Problem: there are no events for invalid blocks (#2163)
Solution: update the documentation to reflect this. I've also removed the documentation about the event plugin API. That part needs to be refactored to work properly with BigchainDB 2.0. We can reintroduce it later.
This commit is contained in:
parent
25043bc993
commit
8086f75ec8
|
@ -1,67 +0,0 @@
|
|||
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.
|
|
@ -5,4 +5,3 @@ The Events API
|
|||
:maxdepth: 1
|
||||
|
||||
websocket-event-stream-api
|
||||
event-plugin-api
|
||||
|
|
|
@ -11,7 +11,7 @@ The WebSocket Event Stream API
|
|||
BigchainDB provides real-time event streams over the WebSocket protocol with
|
||||
the Event Stream API.
|
||||
Connecting to an event stream from your application enables a BigchainDB node
|
||||
to notify you as events occur, such as new `validated transactions <#valid-transactions>`_.
|
||||
to notify you as events occur, such as new `valid transactions <#valid-transactions>`_.
|
||||
|
||||
|
||||
Demoing the API
|
||||
|
@ -26,7 +26,7 @@ Determining Support for the Event Stream API
|
|||
|
||||
It's a good idea to make sure that the node you're connecting with
|
||||
has advertised support for the Event Stream API. To do so, send a HTTP GET
|
||||
request to the node's :ref:`api-root-endpoint`
|
||||
request to the node's :ref:`api-root-endpoint`
|
||||
(e.g. ``http://localhost:9984/api/v1/``) and check that the
|
||||
response contains a ``streams`` property:
|
||||
|
||||
|
@ -60,7 +60,7 @@ BigchainDB node will be ignored.
|
|||
|
||||
Streams will always be under the WebSocket protocol (so ``ws://`` or
|
||||
``wss://``) and accessible as extensions to the ``/api/v<version>/streams/``
|
||||
API root URL (for example, `validated transactions <#valid-transactions>`_
|
||||
API root URL (for example, `valid transactions <#valid-transactions>`_
|
||||
would be accessible under ``/api/v1/streams/valid_transactions``). If you're
|
||||
running your own BigchainDB instance and need help determining its root URL,
|
||||
then see the page titled :ref:`determining-the-api-root-url`.
|
||||
|
@ -70,22 +70,22 @@ All messages sent in a stream are in the JSON format.
|
|||
.. note::
|
||||
|
||||
For simplicity, BigchainDB initially only provides a stream for all
|
||||
validated transactions. In the future, we may provide streams for other
|
||||
committed transactions. In the future, we may provide streams for other
|
||||
information. We may
|
||||
also provide the ability to filter the stream for specific qualities, such
|
||||
as a specific ``output``'s ``public_key``.
|
||||
|
||||
If you have specific use cases that you think would fit as part of this
|
||||
API, feel free to reach out via `Gitter <https://gitter.im/bigchaindb/bigchaindb>`_
|
||||
or `email <mailto:product@bigchaindb.com>`_.
|
||||
API, consider creating a new `BEP <https://github.com/bigchaindb/BEPs>`_.
|
||||
|
||||
Valid Transactions
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``/valid_transactions``
|
||||
|
||||
Streams an event for any newly validated transactions. Message bodies contain
|
||||
the transaction's ID, associated asset ID, and containing block's ID.
|
||||
Streams an event for any newly valid transactions committed to a block. Message
|
||||
bodies contain the transaction's ID, associated asset ID, and containing
|
||||
block's ID.
|
||||
|
||||
Example message:
|
||||
|
||||
|
@ -94,11 +94,11 @@ Example message:
|
|||
{
|
||||
"transaction_id": "<sha3-256 hash>",
|
||||
"asset_id": "<sha3-256 hash>",
|
||||
"block_id": "<sha3-256 hash>"
|
||||
"block_id": "<int>"
|
||||
}
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
Transactions in BigchainDB are validated in batches ("blocks") and will,
|
||||
Transactions in BigchainDB are committed in batches ("blocks") and will,
|
||||
therefore, be streamed in batches.
|
||||
|
|
Loading…
Reference in New Issue