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:

.. code-block:: bash

    $ 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
:ref:`setup` message.

All messages sent from control to kernel (and vice versa) must be
valid BSON objects (according to the `BSON Spec
<https://bsonspec.org/spec.html>`_). 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``.


.. contents::  BSON API
    :depth: 3


BSON API Reference
==================

This is a bare-bones reference; for more explanation of the calls,
cross-reference the `Python API <reference.html>`_, and see also the
`Conceptual Overview <conceptual.html>`_.

Initialization
----------------------------------------------


.. _setup:

``setup``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    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.



.. _shutdown:

``shutdown``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "shutdown",
      "requestId" : /* requestId */
    }



The ``shutdown`` object is used to shutdown the kernel API and exit the kernel process.


Networks
----------------------------------------------


.. _addNetwork:

``addNetwork``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    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:

``networks``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "networks",
      "requestId" : /* requestId */
    }

    RESPONSE:
    {
      "requestId" : /* requestId */,
      "networks" : /* array of Network objects */
    }



Obtains the list of Networks accessible by the API.



.. _network:

``network``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    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:

``setNetworkSecret``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    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:

``addGateway``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    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.



.. _gateways:

``gateways``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "gateways",
      "requestId" : /* requestId */,
      "networkId" : /* the ID of the network */
    }

    RESPONSE:
    {
      "requestId" : /* requestId */,
      "gateways" : /* array of configured Gateways */
    }



Returns the list of Gateways currently configured for this Network.


Identities
----------------------------------------------


.. _addIdentity:

``addIdentity``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "addIdentity",
      "requestId" : /* requestId */
    }







.. _identities:

``identities``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "identities",
      "requestId" : /* requestId */
    }







.. _identity:

``identity``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "identity",
      "requestId" : /* requestId */
    }






Node Management
----------------------------------------------


.. _addNode:

``addNode``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "addNode",
      "requestId" : /* requestId */
    }







.. _nodes:

``nodes``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "nodes",
      "requestId" : /* requestId */
    }







.. _node:

``node``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "node",
      "requestId" : /* requestId */
    }






Node
----------------------------------------------


.. _nodeStart:

``nodeStart``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "nodeStart",
      "requestId" : /* requestId */
    }







.. _nodeStatus:

``nodeStatus``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "nodeStatus",
      "requestId" : /* requestId */
    }







.. _nodeShutdown:

``nodeShutdown``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "nodeShutdown",
      "requestId" : /* requestId */
    }







.. _startServer:

``startServer``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "startServer",
      "requestId" : /* requestId */
    }







.. _connect:

``connect``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "connect",
      "requestId" : /* requestId */
    }







.. _knownNodes:

``knownNodes``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "knownNodes",
      "requestId" : /* requestId */
    }







.. _knownNodeInfo:

``knownNodeInfo``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "knownNodeInfo",
      "requestId" : /* requestId */
    }







.. _networkStats:

``networkStats``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "networkStats",
      "requestId" : /* requestId */
    }







.. _createPipeline:

``createPipeline``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "createPipeline",
      "requestId" : /* requestId */
    }







.. _pipelines:

``pipelines``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "pipelines",
      "requestId" : /* requestId */
    }







.. _pipeline:

``pipeline``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "pipeline",
      "requestId" : /* requestId */
    }






Pipeline
----------------------------------------------


.. _packetRequest:

``packetRequest``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "packetRequest",
      "requestId" : /* requestId */
    }







.. _packet:

``packet``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "packet",
      "requestId" : /* requestId */
    }







.. _shutdownPipeline:

``shutdownPipeline``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "shutdownPipeline",
      "requestId" : /* requestId */
    }







.. _setupUDPPortMap:

``setupUDPPortMap``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

    REQUEST:
    {
      "api" : "setupUDPPortMap",
      "requestId" : /* requestId */
    }