Merge branch 'block-publisher-plugin-arch'

docs/server/source/events/event-plugin-api.rst

@@ -0,0 +1,67 @@
+The Event Plugin API [experimental]
+===================================
+
+.. danger::
+   The Event Plugin API is **experimental** and might change in the future.
+
+BigchainDB implements an internal event system that allows different software
+components to receive updates on specific topics. The WebSocket API, for example,
+is a subscriber to a stream of events called ``BLOCK_VALID``. Every time a block is
+voted valid, the WebSocket API is notified, and it sends updates to all the
+clients connected.
+
+We decided to make this internal event system public, to allow developers to
+integrate BigchainDB with other applications, such as AMQP systems.
+
+
+Available Events
+----------------
+
+The event types are listed in the source file ``bigchaindb/events.py``.
+
+.. list-table:: Event Types
+   :widths: 15 10 30
+   :header-rows: 1
+
+   * - event name
+     - event id
+     - description
+   * - BLOCK_VALID
+     - 1
+     - a block has been voted valid by the network.
+   * - BLOCK_INVALID
+     - 2
+     - a block has been voted invalid by the network.
+
+
+Plugin Example
+----------------
+
+We developed a minimal plugin that listens to new valid blocks and prints them
+to the console:
+https://github.com/bigchaindb/events-plugin-example
+
+
+Architecture of an Event Plugin
+-------------------------------
+
+Creating your own plugin is really easy, and can be summarized in few steps:
+
+1. Create a new Python package that defines the entry point ``bigchaindb.events`` in its ``setup.py``.
+2. In your entry point, define two properties:
+
+   - ``event_types``: a variable to tell BigchainDB which events your plugin is interested in.
+     A plugin can subscribe to more than one events by combining them using the
+     **binary or** operator, e.g. in case you want to subscribe to both valid and
+     invalid blocks your ``event_types`` can be ``1 | 2``.
+   - ``run``: a function that will process the events coming from BigchainDB.
+3. Install the newly created Python package in the current environment.
+4. Add the plugin name to your BigchainDB configuration.
+5. (Re)start BigchainDB.
+
+If the installation was successful, the plugin will be run in a different
+process. Your plugin will receive events through a ``multiprocessing.Queue``
+object.
+
+.. note::
+   It's your plugin's responsibility to consume it's queue.

docs/server/source/events/index.rst

@@ -0,0 +1,8 @@
+The Events API
+==============
+
+.. toctree::
+    :maxdepth: 1
+
+    websocket-event-stream-api
+    event-plugin-api

docs/server/source/index.rst

@@ -13,7 +13,7 @@ BigchainDB Server Documentation
    dev-and-test/index
    server-reference/index
    http-client-server-api
-   websocket-event-stream-api
+   events/index
    drivers-clients/index
    data-models/index
    schema/transaction