Welcome to SEAL NATS¶

This documentation describes the installation and customization of SEAL NATS.

Several SEAL Systems products use NATS as message broker. Therefore SEAL Systems provides a preconfigured version, named SEAL NATS.

Products Using NATS¶

PLOSSYS Output Engine (formerly PLOSSYS 5)

Uses NATS for status and SAP notifications.
DPF, as of version 4.0.0

Uses NATS to start working units, report job status, and broadcast administrative actions such as configuration updates and job cleanup.

Architecture¶

SEAL NATS runs as one shared message broker for all products on a server or in a cluster. Each product keeps its own microservices and its own MongoDB database. Only the messaging between these microservices goes through NATS.

Products using SEAL NATS

NATS is fast, small, and easy to use in cluster architectures. Each product handles a broker outage on its own, see the product-specific sections below.

PLOSSYS Output Engine¶

Prior to using NATS, PLOSSYS Output Engine stored print job changes in capped MongoDB collections. This strained the database. A brief subscriber outage could also lose status messages.

PLOSSYS Output Engine now uses a transactional outbox pattern. A microservice writes the job data and the notification into the same MongoDB transaction. seal-out-ngn-message-relay reads the notification from the outbox and sends it via NATS. Only after the receiving service confirms delivery, seal-out-ngn-message-relay deletes the notification from the outbox.

PLOSSYS Output Engine message flow

Transactional outbox: a message only leaves the outbox once seal-co-notifier confirms delivery.

DPF¶

As of version 4.0.0, DPF uses NATS for two kinds of messaging: processing jobs through working units, and broadcasting administrative actions triggered from the DPF CLI.

For job processing, seal-dpf-jobclient-api publishes the job status after accepting a new job. The DPF Process Manager, seal-dpf-process-manager, starts the next working unit by publishing on a subject named after that working unit. The DPF Working Unit Manager hosting that working unit subscribes to its subject once, so NATS also works as a registry of the working units available in the system. When a working unit finishes, it publishes the job status back, and the DPF Process Manager continues the workflow.

DPF job processing message flow

WU_NAME stands for the working unit name, JOB_ID for the job's _id in MongoDB.

Once the whole workflow ends, whether it succeeds, fails, or is canceled, the DPF Process Manager publishes a final job status, dpf.job.status.FINISHED.JOB_ID.

If the DPF Process Manager finds a job whose processing lock expired, for example after a DPF Working Unit Manager crashed, it resends the same working unit or job status message shown above to resume processing. There is no separate service or subject for this recovery step.

Administrative actions run through seal-dpf-management-api instead of directly through the DPF CLI. The DPF CLI calls this REST service, which then publishes the NATS message.

DPF administrative message flow

The DPF CLI never publishes to NATS directly. seal-dpf-management-api does, after the CLI calls it over REST.

Literature

For details on NATS in general, refer to the original documentation of the software producer:

NATS documentation