Skip to main content

Event Flow

For engineers integrating modules and transports, this page describes the concrete runtime event flow.

Request/response flow (runtime + schema + transport)​

Ordering guarantee​

Runtime executes hook chains in the same order modules are passed to runtime(...).

runtime(moduleA, moduleB, moduleC);

Parameters​

runtime(...modules):

  • modules (RuntimeModule[]): ordered module list; order defines hook execution.

emitReceive(input):

  • input (EmitInput): event input with event, payload or error, and optional envelope metadata/context.

For each chain (onReceive, onSend, onError), execution order is:

  1. moduleA
  2. moduleB
  3. moduleC

Field-by-field forwarding behavior​

Incoming frame -> server runtime​

  1. node-ws-transport decodes wire event.
  2. status becomes receiving.
  3. context is merged with { transport: 'ws', clientId }.
  4. Envelope is forwarded to registry.emitReceive.

Schema execution​

  1. schemaModule reads envelope.event.
  2. envelope.payload is decoded.
  3. Operation/field operation runs with schema-validated input.
  4. Response is emitted with:
    • event: same operation event name
    • payload: encoded output
    • metadata: copied/merged metadata
    • context: copied context
  5. Runtime assigns default status: sending to this new outbound envelope.

Outbound frame -> client runtime​

  1. node-ws-transport encodes envelope.
  2. Client transport decodes envelope.
  3. If metadata.correlationId matches pending request:
    • resolve/reject request promise
  4. Otherwise emit to runtime via emitReceive.

Publish/subscription flow​

Publish metadata behavior:

  • meta from publish call is merged into envelope metadata.
  • key is mapped to metadata as key.
  • ack config is normalized and stored under metadata ack.

Error flow​

Important details:

  • Runtime does not throw across module boundaries for delivery control.
  • schemaModule preserves incoming status in emitted error envelopes.
  • Reliability modules (retry/DLQ) should listen on onError and re-emit envelopes via emitSend/emitReceive.

Module author rules for predictable behavior​

  1. Always pass full envelope data through runtime channels.
  2. Never assume another module exists.
  3. Keep transformations pure and immutable.
  4. If you add context data, merge into context instead of replacing.
  5. If your module serializes, document exactly which fields are encoded and where.