diff --git a/bigchaindb/events.py b/bigchaindb/events.py index d5172082..709543c6 100644 --- a/bigchaindb/events.py +++ b/bigchaindb/events.py @@ -9,6 +9,8 @@ class EventTypes: """Container class that holds all the possible events BigchainDB manages.""" + # If you add a new Event Type, make sure to add it + # to the docs in docs/server/source/event-plugin-api.rst ALL = ~0 BLOCK_VALID = 1 BLOCK_INVALID = 2 diff --git a/bigchaindb/processes.py b/bigchaindb/processes.py index 682a9210..550342e5 100644 --- a/bigchaindb/processes.py +++ b/bigchaindb/processes.py @@ -4,7 +4,7 @@ import multiprocessing as mp import bigchaindb from bigchaindb import config_utils from bigchaindb.pipelines import vote, block, election, stale -from bigchaindb.events import Exchange +from bigchaindb.events import Exchange, EventTypes from bigchaindb.web import server, websocket_server @@ -70,7 +70,7 @@ def start(): logger.info('WebSocket server started') p_websocket_server = mp.Process(name='ws', target=websocket_server.start, - args=(exchange.get_subscriber_queue(),)) + args=(exchange.get_subscriber_queue(EventTypes.BLOCK_VALID),)) p_websocket_server.start() # start message diff --git a/docs/server/source/events/event-plugin-api.rst b/docs/server/source/events/event-plugin-api.rst new file mode 100644 index 00000000..ee989b02 --- /dev/null +++ b/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 AMPQ 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/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: + + - ``events_types``: a variable to tell BigchainDB to which events your plugin is interested. + - ``run``: a function that will process the events coming from BigchainDB. +3. Install the newly created Python 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. Remember: it's your plugin responsibility to consume that queue. + +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 ``events_types`` can be ``1 | 2``. diff --git a/docs/server/source/events/index.rst b/docs/server/source/events/index.rst new file mode 100644 index 00000000..de1648f7 --- /dev/null +++ b/docs/server/source/events/index.rst @@ -0,0 +1,8 @@ +The Events API +============== + +.. toctree:: + :maxdepth: 1 + + websocket-event-stream-api + event-plugin-api diff --git a/docs/server/source/websocket-event-stream-api.rst b/docs/server/source/events/websocket-event-stream-api.rst similarity index 100% rename from docs/server/source/websocket-event-stream-api.rst rename to docs/server/source/events/websocket-event-stream-api.rst diff --git a/docs/server/source/index.rst b/docs/server/source/index.rst index f2f86a61..ec6efef0 100644 --- a/docs/server/source/index.rst +++ b/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