Advanced Topics

This section covers how PURISTA works under the hood. Read this when you need to debug cross-service routing, configure production delivery guarantees, or understand message protocol internals.

Topics

Topic What it covers When you need it
Structure of a Message Fields, headers, addressing, and metadata in every PURISTA message Debugging routing, building custom bridges, or inspecting traces
Queue Internals & Delivery Tuning Leases, heartbeats, retries, dead-letter queues, lifecycle config Running production queue workers with bounded retries
Delivery Semantics & Reliability At-most-once vs at-least-once, idempotency, strict mode Defining production delivery expectations and failure handling

Message flow internals

sequenceDiagram
    autonumber
    participant C as Command Handler
    participant EB as Event Bridge
    participant R as Router
    participant S as Subscription Handler

    C->>EB: send command message
    EB->>EB: validate message envelope
    EB->>R: resolve recipient address
    R->>EB: route to target service
    EB->>S: deliver to subscription handler
    S->>S: validate payload against schema
    S->>EB: ack / nack / extend lease
    EB->>EB: handle retry or dead-letter

Understanding this flow helps when:

  • Messages are not arriving at expected subscriptions
  • Retry behavior differs from expectations
  • You need to build custom event bridge adapters

Production operating patterns

Delivery semantics

Guarantee Behavior When to use
At-most-once Message may be lost on failure Telemetry, metrics, non-critical events
At-least-once Message delivered one or more times Business events, commands, most use cases
Exactly-once Not guaranteed end-to-end; design for idempotency Financial transactions, inventory changes

Idempotency checklist

  • Command handlers produce the same result for the same input
  • Subscription handlers tolerate duplicate events
  • Side effects (DB writes, API calls) use idempotency keys
  • Queue workers check job state before processing

Strict mode

Enable strict: true on commands and subscriptions to fail startup when the active bridge cannot honor requested delivery semantics. This prevents silent degradation in production.

When to read this section

  • You debug cross-service routing and message metadata
  • You define production delivery/retry expectations
  • You need stronger observability and operational safety controls
  • You build custom event bridge or queue bridge adapters

Next: Structure of a Message to understand the message envelope.