Node SDK Fabric Network Event Handling FABN1100 Liam
Node SDK: Fabric Network Event Handling FABN-1100 Liam Grace @14 gracel (Rocket. Chat) © 2019 IBM Corporation
Abstractions • Adding block event listeners added to Network • Adding chaincode event listeners added to Contract (and renamed chaincode event to contract event) • Adding transaction event listeners added to Transaction and Network • Manage event replay on a contract, block and transaction events without the need for custom persistence logic • Auto recovering Event Hubs – Identify if an Event Hub goes down and automatically find a new one – Pluggable Event Hub selection logic • Event Hub Manager on the Network the responsible for all event hubs across the SDK © 2019 IBM Corporation 2
APIs • Node SDK currently uses Channel. Event. Hub to manage chaincode, block and transaction events • New Classes – Abstract. Event. Listener • Base class for block, transaction and contract (chaincode) event listeners – Event. Hub. Manager • Manages event hub creation, reuse and reconnection – Base. Checkpointer • Records the last block height and transaction ID seen by each listener for event replay – Base. Event. Hub. Selection. Strategy • Pluggable strategy for selecting new event hubs • New Methods – Contract. add. Contract. Listener(listener. Name, event, callback, options) – Network. add. Block. Listener(listener. Name, callback, options) – Network. add. Commit. Listener(tx. Id, callback, options, event. Hub) – Transaction. add. Commit. Listener(callback, options, event. Hub) © 2019 IBM Corporation 3
Example Contract Event Listener • User wants to listen to all sell events to use in its analytics platform. Replay is required – User doesn’t change their callback, SDK controls recording the checkpoint and replaying events Function FILE_SYSTEM_CHECKPOINTER(channel. Name, listener. Name, options) { return new File. System. Checkpointer(channel. Name, listener. Name, options) } await gateway. connect(ccp, { identity: 'admin', wallet: wallet, checkpointer: { factory: FILE_SYSTEM_CHECKPOINTER, options: {} }, event. Hub. Selection. Options: { strategy: Event. Hub. Selection. Strategies. MSPID_SCOPE_ROUND_ROBIN } }); const network = await gateway. get. Network('market 1234'); const contract = network. get. Contract('commercial-paper’); await contract. add. Contract. Listener('sell-listener', 'sell’, (err, event, block. Number, txid) => { if (err) { // Disconnect error handled for the user (new event hub assigned), but they are still notified console. error(err); return; } analytics. save(txid, block. Number, event); © 2019 }, {replay: true}); IBM Corporation 4
Example Block Event Listener • User wants to listen to all block events but doesn’t want event replay – Checkpointing and replay logic are ignored. . . await network. add. Block. Listener(‘block-listener', (err, block) => { if (err) { // Disconnect error handled for the user (new event hub assigned), but they are still notified console. error(err); return; } const last. Tx. Id = block. filtered_transactions[block. filtered_transactions. length - 1]. txid; console. info(`Block height ${block. number}`, Last Transaction ID: ${last. Tx. Id}) }); © 2019 IBM Corporation 5
Example Transaction Event Listener • User wants to listen for a commit event to ensure a commercial paper was issued const transaction = contract. create. Transaction(‘issue’); await transaction. add. Commit. Listener((err, tx. Id, status, block. Height) => { if (err) { console. error(err); return; } if (status === ‘VALID’) { console. info(‘Transaction committed’); } else { console. error(‘Transaction failed. Status: ${status}’); }); await transaction. submit('ibm', '1000000', '2019 -03 -31’) © 2019 IBM Corporation 6
Checkpointing – Checkpointing allows event listeners to track information about blocks they have seen • Useful when replaying missed events – Tracks the last block number and any transaction ID’s seen from that block preventing event duplication – Pluggable checkpointing mechanisms • File System – Default – Developer provided event callbacks are overridden to automatically checkpoint if a checkpoint is given • No extra code for developers © 2019 IBM Corporation 7
Pluggable selection strategies • Selection strategies are pluggable • Select a new or recycle an old event hub if the current one goes down – Use case dependent © 2019 IBM Corporation 8
Pluggable selection strategies - Factory • Provide an event hub selection factory in Gateway. Options • Returns an instance of Base. Event. Hub. Selection. Strategy • Selects a pool of Event Hub’s it wants the strategy to select from // Example factory included in the SDK. User may create their own function MSPID_SCOPE_ROUND_ROBIN(network) { const org. Peers = get. Organization. Peers(network); return new Round. Robin. Event. Hub. Selection. Strategy(org. Peers); } © 2019 IBM Corporation 9
Summary • Added event listener creation to the Contract, Network and Transaction classes – Contract. add. Contract. Listener(listener. Name, event, callback, options) – Network. add. Block. Listener(listener. Name, callback, options) – Network. add. Commit. Listener(tx. Id, callback, options) – Transaction. add. Commit. Listener(callback, options) • Automatic event replay using a pluggable Base. Checkpointer – File System – default • Automatic recovery when an Event Hub goes down – Pluggable Base. Event. Hub. Selection. Strategy to control selection behavior © 2019 IBM Corporation 10
- Slides: 10