Document type: nats_pattern

Table of Contents

This page defines the nats_pattern document type. It is one entry in the document types taxonomy. The taxonomy page holds the general contract every document follows: frontmatter, state, linking and tags. This page holds only what is specific to nats_pattern. The rest of the page calls a page of this type a pattern page.

1. Scope

A NATS pattern governs how a service speaks on the bus: how it addresses a subject, how it subscribes and who owns the subscription, how it publishes, how it makes a request and answers one, how it handles an error, and what it leaves behind for diagnostics. It is the NATS counterpart of a Document type: service_architecture_pattern, scoped to the ores.nats wrapper and the subjects of the platform. Three kinds of pattern are out of scope, because they have other sources and other readers:

  • Code-level design patterns, such as the Gang of Four's or a C++ idiom, which live inside one component.
  • User interface patterns, which belong to the journeys and the screens.
  • Local conventions, such as the SQL, HTTP and shell entity patterns of the codegen. They have no outside source, so they are conventions, and their pages keep their own type.

2. Contract

Implements
loading, citation. A pattern page loads what is known about one established pattern, and a design cites it by name: "use Durable Subscription". See NATS service patterns.
Folder
doc/knowledge/nats_patterns/, one page per pattern, as pattern_<slug>.org. The hub, NATS service patterns, lives in the same folder and orders the pages.
Scope
the page owns one pattern: its mechanism, its failure handling, its pitfalls and its sources. A use of the pattern is not this page's subject. The architecture page that uses the pattern owns the choices that are its own: the role, the subjects, the limits, the moments it acts. The pattern page names each use in * In ORE Studio and links it. It does not restate it.
Name
the title is the pattern's name in its authoritative source, for example Durable Subscription or Idempotent Message Identity. A name ORE Studio used before the page existed is an alias under * Also known as, never the title.
Group
#+pattern_group: places the pattern in one group of the language: addressing, subscription, publication, request, error-handling, diagnostics or ownership. The scaffold refuses a pattern with no group, an unknown one, or a group from the service-architecture vocabulary.
Sources
at least one authoritative source: the book, catalogue or standard that defines the pattern, with the section. A page with no source is a local convention, not a pattern, and it belongs in an architecture page.
Level
cross.
(no term)
Not stateful. A pattern page has no TODO and no * Status table.
How to create
compass add nats_pattern --pattern-group <group>. --parent-dir is optional and defaults to doc/knowledge/nats_patterns/. See How do I create a new doc? for the flags.
Required sections (in this order)
  • Blurb: two to four sentences before the first heading. It names the pattern, states its intent and says where ORE Studio uses it. A pattern page has no * Summary heading; the blurb is the summary.
  • * Also known as: the other names, each with its source, and any local name.
  • * Context: the situation in which the problem arises.
  • * Problem: one question.
  • * Forces: what pulls in opposite directions.
  • * Solution: the pattern, stated in the ores.nats call it governs. The language is stated in library calls, not diagrams, so the section shows a #+begin_src cpp :results verbatim block with the call, in the order the participants make it. Add a second block when one call does not show the point: the reply, the error path, or the lifetime a subscription must have.
  • * Failure handling: a table with one row each for errors, timeouts, retries, idempotency and observability. A row that does not apply says so and gives the reason.
  • * Pitfalls: the known ways the pattern goes wrong, with the symptom and the cause, including the ones ORE Studio has met.
  • * Security: the trust boundaries, and what a leak or a forgery costs.
  • * Resulting context: the benefits and the liabilities.
  • * In ORE Studio: each use, with a link to the page that owns it.
  • * Related patterns: the other patterns of the language, each with how it relates.
  • * Sources: the authoritative references.
  • * See also: the hub, and any other internal page.

3. A pattern page and an architecture page

The two pages answer different questions, and a fact belongs to one of them.

Question Page
How does the mechanism work, and how does it fail? the pattern page
What do the sources call it, and where do they define it? the pattern page
Which role, subject, limit or lifetime does this use choose? the architecture page
When does this component act, and why? the architecture page

A rule that both pages state drifts, and a reader finds the stale copy first. So an architecture page links the pattern for the mechanism, and the pattern page links the architecture page for the use.

4. A composite pattern

Some problems need several patterns together, for example a request that must survive a restart. A composite is a pattern page of its own. Its * Solution names the patterns it combines and links them, and it states only what the combination adds: the order, the boundaries between them, and the failures that arise between them. It cites the sources of its parts, and it may cite a source of its own when one names the combination.

Emacs 29.3 (Org mode 9.6.15)