github.com/yacovm/fabric@v2.0.0-alpha.0.20191128145320-c5d4087dc723+incompatible/docs/source/peer_event_services.rst (about)

     1  Peer channel-based event services
     2  =================================
     3  
     4  General overview
     5  ----------------
     6  
     7  In previous versions of Fabric, the peer event service was known as the event
     8  hub. This service sent events any time a new block was added to the peer's
     9  ledger, regardless of the channel to which that block pertained, and it was only
    10  accessible to members of the organization running the eventing peer (i.e., the
    11  one being connected to for events).
    12  
    13  Starting with v1.1, there are two new services which provide events. These services use an
    14  entirely different design to provide events on a per-channel basis. This means
    15  that registration for events occurs at the level of the channel instead of the peer,
    16  allowing for fine-grained control over access to the peer's data. Requests to
    17  receive events are accepted from identities outside of the peer's organization (as
    18  defined by the channel configuration). This also provides greater reliability and a
    19  way to receive events that may have been missed (whether due to a connectivity issue
    20  or because the peer is joining a network that has already been running).
    21  
    22  Available services
    23  ------------------
    24  
    25  * ``Deliver``
    26  
    27  This service sends entire blocks that have been committed to the ledger. If
    28  any events were set by a chaincode, these can be found within the
    29  ``ChaincodeActionPayload`` of the block.
    30  
    31  * ``DeliverFiltered``
    32  
    33  This service sends "filtered" blocks, minimal sets of information about blocks
    34  that have been committed to the ledger. It is intended to be used in a network
    35  where owners of the peers wish for external clients to primarily receive
    36  information about their transactions and the status of those transactions. If
    37  any events were set by a chaincode, these can be found within the
    38  ``FilteredChaincodeAction`` of the filtered block.
    39  
    40  .. note:: The payload of chaincode events will not be included in filtered blocks.
    41  
    42  How to register for events
    43  --------------------------
    44  
    45  Registration for events from either service is done by sending an envelope
    46  containing a deliver seek info message to the peer that contains the desired start
    47  and stop positions, the seek behavior (block until ready or fail if not ready).
    48  There are helper variables ``SeekOldest`` and ``SeekNewest`` that can be used to
    49  indicate the oldest (i.e. first) block or the newest (i.e. last) block on the ledger.
    50  To have the services send events indefinitely, the ``SeekInfo`` message should
    51  include a stop position of ``MAXINT64``.
    52  
    53  .. note:: If mutual TLS is enabled on the peer, the TLS certificate hash must be
    54            set in the envelope's channel header.
    55  
    56  By default, both services use the Channel Readers policy to determine whether
    57  to authorize requesting clients for events.
    58  
    59  Overview of deliver response messages
    60  -------------------------------------
    61  
    62  The event services send back ``DeliverResponse`` messages.
    63  
    64  Each message contains one of the following:
    65  
    66   * status -- HTTP status code. Both services will return the appropriate failure
    67     code if any failure occurs; otherwise, it will return ``200 - SUCCESS`` once
    68     the service has completed sending all information requested by the ``SeekInfo``
    69     message.
    70   * block -- returned only by the ``Deliver`` service.
    71   * filtered block -- returned only by the ``DeliverFiltered`` service.
    72  
    73  A filtered block contains:
    74  
    75   * channel ID.
    76   * number (i.e. the block number).
    77   * array of filtered transactions.
    78   * transaction ID.
    79  
    80     * type (e.g. ``ENDORSER_TRANSACTION``, ``CONFIG``.
    81     * transaction validation code.
    82  
    83   * filtered transaction actions.
    84       * array of filtered chaincode actions.
    85          * chaincode event for the transaction (with the payload nilled out).
    86  
    87  SDK event documentation
    88  -----------------------
    89  
    90  For further details on using the event services, refer to the `SDK documentation. <https://fabric-sdk-node.github.io/tutorial-channel-events.html>`_
    91  
    92  .. Licensed under Creative Commons Attribution 4.0 International License
    93      https://creativecommons.org/licenses/by/4.0/