macula_topic (macula v3.13.0)
View SourceMesh topic construction and validation.
Every mesh topic follows a strict 5-segment structure:
{realm}/{publisher}/{publisher}/{domain}/{name}_v{N}
The two publisher slots carry different values depending on the topic's ownership tier. Three tiers exist:
realm: {realm}/_realm/_realm/{domain}/{name}_v{N} org: {realm}/{org}/_org/{domain}/{name}_v{N} app: {realm}/{org}/{app}/{domain}/{name}_v{N}
Tier answers: who owns the topic's schema and authority?
realm — realm authority (membership, identity, ban) org — org-spanning concept (licensing, billing) app — app-internal (game state, RPCs, app events)
Use realm_fact / org_fact / app_fact for pub/sub topics (past tense names — something happened).
Use realm_hope / org_hope / app_hope for RPC procedure names (present tense names — we want something to happen).
System topics (with leading underscore — _mesh.*, _dist.*, _dht.*) are infrastructure-owned, dot-separated, and exempt from this 5-segment structure.
Full guide: docs/guides/TOPIC_NAMING_GUIDE.md
Summary
Functions
Build an app-tier fact topic. A specific app owns the schema. All slots carry real values.
Build an app-tier hope procedure name.
Build a topic from explicit segments. Validates each segment and the publisher-slot tier combination. Prefer the tier-specific builders (realm_fact, org_fact, app_fact).
Check if a topic is a system topic. System topics use the leading-underscore convention (e.g. _mesh.node.up, _dist.tunnel.X, _dht.list_gateways). They are infrastructure-owned, dot-separated, and exempt from the canonical 5-segment structure. Out of scope for this validator — passed through as-is.
Build an org-tier fact topic. An org owns the schema across multiple of its apps. The app slot carries the _org sentinel.
Build an org-tier hope procedure name.
Parse a topic into its constituent parts and tier. Returns an error tuple for any non-canonical topic. System topics (leading underscore prefix) are not canonical and will return an error from parse/1; use validate/1 to accept system topics as well.
Build a realm-tier fact (pub/sub) topic. Realm authority owns the schema. Publisher and subscriber slots carry the _realm sentinel.
Build a realm-tier hope (RPC) procedure name.
Validate a topic string. Accepts canonical 5-segment topics AND system topics (leading underscore prefix infrastructure events).
Types
Functions
Build an app-tier fact topic. A specific app owns the schema. All slots carry real values.
Build an app-tier hope procedure name.
Build a topic from explicit segments. Validates each segment and the publisher-slot tier combination. Prefer the tier-specific builders (realm_fact, org_fact, app_fact).
Check if a topic is a system topic. System topics use the leading-underscore convention (e.g. _mesh.node.up, _dist.tunnel.X, _dht.list_gateways). They are infrastructure-owned, dot-separated, and exempt from the canonical 5-segment structure. Out of scope for this validator — passed through as-is.
Build an org-tier fact topic. An org owns the schema across multiple of its apps. The app slot carries the _org sentinel.
Build an org-tier hope procedure name.
Parse a topic into its constituent parts and tier. Returns an error tuple for any non-canonical topic. System topics (leading underscore prefix) are not canonical and will return an error from parse/1; use validate/1 to accept system topics as well.
Build a realm-tier fact (pub/sub) topic. Realm authority owns the schema. Publisher and subscriber slots carry the _realm sentinel.
Build a realm-tier hope (RPC) procedure name.
Validate a topic string. Accepts canonical 5-segment topics AND system topics (leading underscore prefix infrastructure events).