mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
68 lines
2.2 KiB
ReStructuredText
68 lines
2.2 KiB
ReStructuredText
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.
|