Dataflow

Bootup flow when the Barbican API service begins

This is the sequence of calls for booting up the Barbican API server:

1. bin/barbican.sh start: Launches a WSGI service that performs a PasteDeploy process, invoking the middleware components found in barbican/api/middleware as configured in etc/barbican/barbican-api-paste. The middleware components invoke and then execute the Pecan application created via barbican/api/app.py:create_main_app(), which also defines the controllers (defined in barbican/api/controllers/) used to process requested URI routes.

Typical flow when the Barbican API executes

For synchronous calls, the following sequence is generally followed:

1. A client sends an HTTP REST request to the Barbican API server.
2. The WSGI server and routing invokes a method on one of the XxxxController classes in barbican/api/controllers/xxxx.py, keyed to an HTTP verb (so one of POST, GET, DELETE, or PUT).
   1. Example - GET /secrets:
      1. In barbican/api/controllers/secrets.py, the SecretController‘s on_get() is invoked.
      2. A SecretRepo repository class (found in barbican/model/respositories.py) is then used to retrieve the entity of interest, in this case as a Secret entity defined in barbican/model/models.py.
      3. The payload is decrypted as needed, via barbican/plugin/resources.py‘s get_secret() function.
      4. A response JSON is formed and returned to the client.

For asynchronous calls, the following sequence is generally followed:

1. A client sends an HTTP REST request to the Barbican API server.
2. The WSGI server and routing again invokes a method on one of the XxxxcController classes in barbican/api/controllers/.
3. A remote procedure call (RPC) task is enqueue for later processing by a worker node.
   1. Example - POST /orders:
      1. In barbican/api/controllers/orders.py, the OrdersController‘s on_post() is invoked.
      2. The OrderRepo repository class (found in barbican/model/respositories.py) is then used to create the barbican/model/models.py‘s Order entity in a ‘PENDING’ state.
      3. The Queue API’s process_type_order() method on the TaskClient class (found in barbican/queue/client.py) is invoked to send a message to the queue for asynchronous processing.
      4. A response JSON is formed and returned to the client.
4. The Queue service receives the message sent above, invoking a corresponding method on barbican/queue/server.py‘s Tasks class. This method then invokes the process_and_suppress_exceptions() method on one of the barbican/tasks/resources.py‘s BaseTask implementors. This method can then utilize repository classes as needed to retrieve and update entities. It may also interface with third party systems via plugins`. The barbican/queue/client.py‘s TaskClient class above may also be invoked from a worker node for follow on asynchronous processing steps.
   1. Example - POST /orders (continued):
      1. Continuing the example above, the queue would invoke the process_type_order() method on barbican/queue/server.py‘s Tasks class. Note the method is named the same as the TaskClient method above by convention.
      2. This method then invokes process_and_suppress_exceptions() on the barbican/tasks/resources.py‘s BeginTypeOrder class. This class is responsible for processing all newly-POST-ed orders.