BSON API Overview¶
The Pipes Kernel is a standalone process that is controlled by messages sent over a local TCP connection. The controlling process must establish a TCP server at a port on the local machine, which will be used to communicate with the kernel. The kernel process is initiated by:
$ pipes_kernel [port]
Where port is the TCP port of local TCP server socket of the
controlling process. The kernel will then initiate a TCP connection to
the local server process, which must then accept() the
connection. At this point, the TCP connection to the kernel is
established, and all other control is done via this connection. The
first message that must be sent from the control process is the
setup message.
All messages sent from control to kernel (and vice versa) must be valid BSON objects (according to the BSON Spec). The first four bytes of a valid BSON object are the size of the object/message, so this is also used to dilineate the messages over the TCP connection.
The kernel API is a combination request-response and asynchronous
API. All messages sent from the control process to the kernel are
request objects. Each such object must include a requestId, which
is an integer identifier. Request IDs must be unique and increasing
for the duration of the kernel session.
Response objects are sent from the kernel back to the control
process. Many requests (but not all) will result in a single response
object being sent back from the kernel. The client cannot assume that
the next object received will be the response, as it is possible that
an asynchronous notification object (see below) may be sent
in-between. The client must wait for a response object that has the
matching requestId from the request.
In the case of an API error (typically caused by invalid parameters in
a request object), the response object will have the error field
set with a description of the cause of the error. No other fields
should be considered valid if the error field is set.
Notification objects are sent from the kernel to the control process,
independent of requests. Such objects do not have an associated
requestId.
BSON API
BSON API Reference¶
This is a bare-bones reference; for more explanation of the calls, cross-reference the Python API, and see also the Conceptual Overview.
Initialization¶
setup¶
REQUEST:
{
"api" : "setup",
"requestId" : /* requestId */,
"path" : /* filesystem path */
}
RESPONSE:
{
"requestId" : /* requestId */,
"path" : /* build version string */
}
The setup object is used to initialize the kernel API. It must be the first call made to the API. It must include the path attribute, which is an existing filesystem path which the kernel can use for persistent state.
Networks¶
addNetwork¶
REQUEST:
{
"api" : "addNetwork",
"requestId" : /* requestId */,
"data" : /* network file data */
}
RESPONSE:
{
"requestId" : /* requestId */,
"networkId" : /* the ID of the new network */,
"name" : /* the name of the new network */
}
Adds a new Network with the data (bytes) object of a netfile. The must be the contents of a valid netfile created with the Network administration tools.
networks¶
REQUEST:
{
"api" : "networks",
"requestId" : /* requestId */
}
RESPONSE:
{
"requestId" : /* requestId */,
"networks" : /* array of Network objects */
}
Obtains the list of Networks accessible by the API.
network¶
REQUEST:
{
"api" : "network",
"requestId" : /* requestId */,
"networkId" : /* the ID of the network to query */
}
RESPONSE:
{
"requestId" : /* requestId */,
"name" : /* the name of the network */,
"bootstrap" : /* `true` if this is a bootstrap network */,
"hasSecret" : /* `true` if we have the secret for this network */
}
Obtains a Network object by its networkId.
setNetworkSecret¶
REQUEST:
{
"api" : "setNetworkSecret",
"requestId" : /* requestId */,
"networkId" : /* the ID of the network */,
"secret" : /* the secret data (bytes) */
}
RESPONSE:
{
"requestId" : /* requestId */,
"hasSecret" : /* `true` if we have the secret for this network */
}
Use this to set the secret for this Network, which is required before connection.
addGateway¶
REQUEST:
{
"api" : "addGateway",
"requestId" : /* requestId */,
"networkId" : /* the ID of the network */,
"host" : /* IP address of the gateway */,
"port" : /* TCP port of the gateway */
}
RESPONSE:
{
"requestId" : /* requestId */,
"networkId" : /* the ID of the network */,
"host" : /* IP address of the added gateway */,
"port" : /* TCP port of the added gateway */
}
Adds a Gateway Peer to this Network, given by the indicated host and port. A Node will attempt to connect to the Network via all known Gateways.
Identities¶
addIdentity¶
REQUEST:
{
"api" : "addIdentity",
"requestId" : /* requestId */
}
identities¶
REQUEST:
{
"api" : "identities",
"requestId" : /* requestId */
}
Node¶
nodeStatus¶
REQUEST:
{
"api" : "nodeStatus",
"requestId" : /* requestId */
}
nodeShutdown¶
REQUEST:
{
"api" : "nodeShutdown",
"requestId" : /* requestId */
}
startServer¶
REQUEST:
{
"api" : "startServer",
"requestId" : /* requestId */
}
knownNodes¶
REQUEST:
{
"api" : "knownNodes",
"requestId" : /* requestId */
}
knownNodeInfo¶
REQUEST:
{
"api" : "knownNodeInfo",
"requestId" : /* requestId */
}
networkStats¶
REQUEST:
{
"api" : "networkStats",
"requestId" : /* requestId */
}
createPipeline¶
REQUEST:
{
"api" : "createPipeline",
"requestId" : /* requestId */
}
Pipeline¶
packetRequest¶
REQUEST:
{
"api" : "packetRequest",
"requestId" : /* requestId */
}
shutdownPipeline¶
REQUEST:
{
"api" : "shutdownPipeline",
"requestId" : /* requestId */
}
setupUDPPortMap¶
REQUEST:
{
"api" : "setupUDPPortMap",
"requestId" : /* requestId */
}