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
.
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:
- Create a new Python package that defines the entry point
bigchaindb.events
in itssetup.py
. - 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 yourevent_types
can be1 | 2
.run
: a function that will process the events coming from BigchainDB.
- Install the newly created Python package in the current environment.
- Add the plugin name to your BigchainDB configuration.
- (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.