Seneca Microservices Framework

The Seneca protocol uses a request/response model that is transport-independent, assuming JSON documents can be delivered as discrete units. It supports synchronous requests, asynchronous actor/pub/sub flows, and chained synchronous flows.

Key concepts:

• Message: A single outbound request JSON document. A response is considered part of the message concept.
• meta$: A reserved property for Seneca metadata. If missing, Seneca constructs it with default values to allow manual interactions (e.g., via curl).
• Correlation ID (cid): Retained across service instances to trace the entire causal chain of a message flow.
• Message ID (mid): A unique identifier for a specific message instance.

To run a Seneca script normally:

node microservice.js

To run in test mode with human-readable, full debug logs:

node microservice.js --seneca.test

Note: Logs are output in JSON format by default, making them suitable for logging services.

$ node microservice.js --seneca.test

To run the sales tax example, first ensure all dependencies are installed via npm install. Then, execute the scripts in the following specific sequence:

1. node sales-tax.js
2. node sales-tax-config.js

Note: This specific example uses the original callback-based API. If you prefer using async/await, refer to the seneca-promisify package.

The trk (tracking) array provides a history of the message flow through various services.

• Each entry in trk represents one outbound request and at most one response.
• When an inbound message triggers new outbound messages, the originating Seneca instance is added to the tracking array.
• The tms array within each tracking entry records UTC milliseconds for send/receive events, allowing for local processing time measurement.

To use Seneca in your Node.js project, install it using npm:

npm install seneca

Use seneca.add(pattern, handler) to define a new command. The pattern is a JSON object that Seneca uses for pattern matching. The handler is a function that receives a message (msg) and a callback (done).

Example of a simple pattern:

var seneca = require('seneca')()

seneca.add({cmd: 'salestax'}, function (msg, done) {
  var rate  = 0.23
  var total = msg.net * (1 + rate)
  done(null, {total: total})
})

Use seneca.act(pattern, callback) to run a command. You can pass the pattern as a JSON object or as a string using an abbreviated JSON format (Jsonic).

Using a JSON object:

seneca.act({cmd: 'salestax', net: 100}, function (err, result) {
  console.log(result.total)
})

Using an abbreviated string:

seneca.act('cmd:salestax,net:100', function (err, result) {
  console.log(result.total)
})

Combining pattern and data:

seneca.act('cmd:salestax', {net: 100}, function (err, result) {
  console.log(result.total)
})

The listen() method starts a service that listens for JSON messages. When messages arrive, they are submitted to the local Seneca instance and executed. By default, in process and http transports are included.

Example of listening on a specific port with a pin:

Seneca()
  .use(approver)
  .listen({type: 'http', port: '8260', pin: 'cmd:*'})

Calling seneca.client() enables the Seneca instance to send actions it cannot match locally out over the network to configured clients. You can chain multiple .client() calls to specify different ports and pins.

seneca.client({port: 8260, pin: 'cmd:run'})
  .client({port: 8270, pin: 'cmd:run'})
  .act('cmd:run', handler)

seneca.client({port: 8260, pin: 'cmd:run'})
  .client({port: 8270, pin: 'cmd:run'})
  .use(local)
  .act('cmd:run', handler)