FABN-1492: Define a specific BlockEvent type (#160)

Signed-off-by: Mark S. Lewis <mark_lewis@uk.ibm.com>

fabric-network/index.js

@@ -261,8 +261,19 @@
  */
 
 /**
- * @typedef {EventInfo} Network~BlockEvent
+ * @typedef {object} Network~BlockEvent
  * @memberof module:fabric-network
+ * @property {Long} blockNumber The number of the block this event represents.
+ * @property {('filtered'|'full'|'private')} type Type of block event. The type will dictate the actual implementation
+ * sub-type for this event.
+ * @see module:fabric-network.Network~FilteredBlockEvent
+ */
+
+/**
+ * @typedef {module:fabric-network.Network~BlockEvent} Network~FilteredBlockEvent
+ * @memberof module:fabric-network
+ * @property {"filtered"} type Type of block event.
+ * @property {FilteredBlock} blockData The raw filtered block data.
  */
 
 /**
@@ -333,10 +344,17 @@
  * @returns {module:fabric-network.Network~BlockListener} The added listener.
  * @example
  * const listener: BlockListener = async (event) => {
- *     // Handle block event, then (optionally) remove myself as a listener
- *     network.removeBlockListener(listener);
+ *     // Handle block event
+ *
+ *     // Listener may remove itself if desired
+ *     if (event.blockNumber === endBlock) {
+ *         network.removeBlockListener(listener);
+ *     }
  * }
- * await network.addBlockListener(listener);
+ * const options: ListenerOptions = {
+ *     startBlock: 1
+ * };
+ * await network.addBlockListener(listener, options);
  */
 
 /**
@@ -346,6 +364,14 @@
  * @param listener {module:fabric-network.Network~BlockListener} A block listener callback function.
  */
 
+/**
+ * A callback function that will be invoked when either a peer communication error occurs or a transaction commit event
+ * is received. Only one of the two arguments will have a value for any given invocation.
+ * @callback Network~BlockListener
+ * @memberof module:fabric-network
+ * @param {module:fabric-network.Network~BlockEvent} event A block event.
+ */
+
 
 module.exports.Gateway = require('./lib/gateway');
 module.exports.Wallet = require('./lib/impl/wallet/wallet').Wallet;

fabric-network/src/impl/event/blockeventsource.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { BlockEvent, BlockListener } from './blocklistener';
+import { BlockEvent, BlockListener, FilteredBlockEvent } from './blocklistener';
 import { OrderedBlockQueue } from './orderedblockqueue';
 import { AsyncNotifier } from './asyncnotifier';
 import { EventServiceManager } from './eventservicemanager';
@@ -16,6 +16,7 @@ import {
 	EventService
 } from 'fabric-common';
 import Long = require('long');
+import util = require('util');
 
 import * as Logger from '../../logger';
 const logger = Logger.getLogger('BlockEventSource');
@@ -117,13 +118,27 @@ export class BlockEventSource {
 		}
 	}
 
-	private onBlockEvent(event: EventInfo) {
-		this.blockQueue.addBlock(event!);
+	private onBlockEvent(eventInfo: EventInfo) {
+		const blockEvent = this.newBlockEvent(eventInfo);
+		this.blockQueue.addBlock(blockEvent);
 		if (this.blockQueue.size() > 0) {
 			this.asyncNotifier.notify();
 		}
 	}
 
+	private newBlockEvent(eventInfo: EventInfo): BlockEvent {
+		if (eventInfo.filteredBlock) {
+			const blockEvent: FilteredBlockEvent = {
+				type: 'filtered',
+				blockNumber: eventInfo.blockNumber,
+				blockData: eventInfo.filteredBlock
+			};
+			return blockEvent;
+		} else {
+			throw new Error('Unexpected block event info: ' + util.inspect(eventInfo));
+		}
+	}
+
 	private async notifyListeners(event: BlockEvent) {
 		const promises = Array.from(this.listeners).map((listener) => listener(event));
 		const results = await allSettled(promises);

fabric-network/src/impl/event/blocklistener.ts

@@ -4,7 +4,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { EventInfo } from 'fabric-common';
+import { FilteredBlock } from 'fabric-common';
+import Long = require('long');
+
+export interface BlockEvent {
+	type: string;
+	blockNumber: Long;
+}
+
+export interface FilteredBlockEvent extends BlockEvent {
+	type: 'filtered';
+	blockData: FilteredBlock;
+}
 
-export type BlockEvent = EventInfo;
 export type BlockListener = (event: BlockEvent) => Promise<void>;

fabric-network/src/impl/event/contractlistenersession.ts

@@ -6,7 +6,7 @@
 
 import * as Logger from '../../logger';
 import { Network } from '../../network';
-import { BlockEvent, BlockListener } from './blocklistener';
+import { BlockListener, FilteredBlockEvent, BlockEvent } from './blocklistener';
 import { ContractEvent, ContractListener } from './contractlistener';
 import { ListenerSession } from './listenersession';
 // @ts-ignore no implicit any
@@ -23,7 +23,7 @@ export class ContractListenerSession implements ListenerSession {
 		this.listener = listener;
 		this.chaincodeId = chaincodeId;
 		this.network = network;
-		this.blockListener = (blockEvent: BlockEvent) => this.getContractEventsforFilteredBlock(blockEvent);
+		this.blockListener = (blockEvent: BlockEvent) => this.onBlockEvent(blockEvent);
 	}
 
 	public async start() {
@@ -34,13 +34,21 @@ export class ContractListenerSession implements ListenerSession {
 		this.network.removeBlockListener(this.blockListener);
 	}
 
-	private async getContractEventsforFilteredBlock(blockEvent: BlockEvent) {
+	private async onBlockEvent(blockEvent: BlockEvent): Promise<void> {
+		if (blockEvent.type === 'filtered') {
+			await this.getContractEventsforFilteredBlock(blockEvent as FilteredBlockEvent);
+		} else {
+			throw new Error(`Unexpected block event type: ${blockEvent.type}`);
+		}
+	}
+
+	private async getContractEventsforFilteredBlock(blockEvent: FilteredBlockEvent) {
 
 		// For filtered blocks
-		if (blockEvent.filteredBlock && blockEvent.filteredBlock.filtered_transactions) {
+		if (blockEvent.blockData.filtered_transactions) {
 			// const blockNumber: string = blockEvent.filteredBlock.number;
 
-			for (const filteredTransaction of blockEvent.filteredBlock.filtered_transactions) {
+			for (const filteredTransaction of blockEvent.blockData.filtered_transactions) {
 
 				// const transactionId: string = filteredTransaction.txid;
 				// const transactionValidationCode: string = this.getTransactionValidationCode(filteredTransaction);