Skip to main content

@hlf-explorer/monitor

@hlf-explorer/monitor is a reusable library that applications embed when they need to react to what is happening in the ledger. There is a subtlety here that is best grasped right away, so as not to get confused later: the monitor does not talk to Fabric directly. It listens to the explorer's own API, and the explorer backend has already filled the database with raw blocks. In other words, the backend is responsible for the raw material, while the monitor extracts the application meaning from it.

The tracking engine is LedgerMonitor. It connects to the ledger over a socket, on a timer compares the height with the stored one and schedules a parse task for new blocks. At startup it also catches up on the missed blocks, so that not a single block falls out of processing, even if the application was down for a while.

The most interesting part begins in the parse handler — LedgerBlockParseHandler. It holds a registry of parsers keyed by chaincode event names and, within a single database transaction, walks through all the events of a block, handing each one to its parser. And a parser is a LedgerEventParser, which is exactly what application code inherits, describing what to do with a specific business event. Inside, the parser places the result into four buckets, and this division is fundamental:

  1. entities — application entities that are saved right there, inside the same transaction.
  2. events — domain events that are dispatched immediately after commit, locally.
  3. socketEvents — events that go out to clients over the socket.
  4. commands — actions that the parser cannot perform itself inside the transaction, and which are sent to other services of the application after commit.

It is worth dwelling on this division, because it is tied to an honest limitation that we state plainly. Entities are saved atomically together with the very fact that "the block has been parsed", whereas commands are sent after commit and without waiting for the result. This means that if the process crashes between the commit and the dispatch, the command is lost: the database remembers that the block was parsed, but the action that was supposed to follow it did not happen. For an accounting system this means a discrepancy, and we close it with the transactional outbox pattern — more on the status in the roadmap.