master-zapier-plan-draft/packages/dev-overview/01-nats-routes.md
George Lambert 86b421db05
Some checks failed
offline / test (push) Has been cancelled
Add dev-overview: designed vs running NATS routes and Zapier-Verae path.
Independent Forgejo repo maps every verae.* address, endpoint I/O, job
monitor loop, and remaining billing/archive wiring.
2026-09-14 13:25:04 -04:00

5.2 KiB

Designed vs running NATS routes

Designed = named in docs (modules-and-nats.md, MESSAGE-FLOWS.md, per-package NATS.md) or in code (subjects.js, fleet JSON).
Running = a process on NS1 is subscribed or publishing it today, and (for durable work) a JetStream stream exists.

Cluster name verae. Internal URL: three LXC on vmbr1. Public edge is a leaf, not a second cluster.

Legend: JS = JetStream stream; RR = core request-reply; pub = core or JS fire-and-forget; Q = queue group.

JetStream streams (running)

Created by verae-nats-cluster/scripts/ensure-streams.sh (and middleware ensureStreams for the first three).

Stream Subjects Replicas Storage Who consumes
ZAPIER_JOBS verae.zapier.jobs.watch 3 file job-poller (in middleware process)
ZAPIER_EVENTS verae.zapier.jobs.events 3 file middleware wait + webhook router; optional exclusive jobs-events
ZAPIER_WEBHOOKS verae.zapier.webhooks.deliver 3 file webhook-deliver (in middleware process)
ZAPIER_USAGE verae.zapier.usage 3 file no durable consumer running (USAGE_WRITER is named only)
VERAE_ARCHIVE verae.archive.> 3 file worm + tree on LXC 510 (keep); aggregator not fleet-enabled

Address inventory

Address Kind Designed Running Notes
verae.zapier.jobs.watch JS work Q job-poller yes yes middleware publishes; in-process poller consumes
verae.zapier.jobs.events JS events yes yes poller publishes; wait() subscribes; webhook worker routes
verae.zapier.webhooks.deliver JS work Q webhook-deliver yes yes middleware worker in same Node process as HTTP
verae.zapier.usage JS optional yes stream yes, consumer no middleware entitlement is local files, not this subject
verae.internal.jobs.events core republish yes (jobs-events exclusive) partial only if JOBS_EVENTS_EXCLUSIVE=1
verae.billing.statement.get RR yes yes account-balance
verae.billing.balance.get RR yes yes account-balance
verae.billing.balance.adjust RR yes yes CS credits, portal reload
verae.billing.usage.recorded pub yes partial designed from zappier-edge meter; confirm publisher on live edge
verae.billing.payment.recorded pub yes partial portal reload / invoice
verae.billing.credit.applied pub yes partial CS goodwill
verae.billing.customer.put RR/pub yes (account-balance subjects.js) unclear books write
verae.access.authz.check RR Q access-authz yes yes fleet keepFloor
verae.access.authz.deny pub audit yes yes (on deny)
verae.access.web.* ingress yes yes access-web after HTTP
verae.access.api.* ingress yes yes
verae.access.zapier.* ingress yes yes HTTPS plane, not Zapier NATS
verae.access.leaf.in / verae.access.leaf.* ingress yes yes no billing
verae.access.staff.* ingress yes yes CS/sales/accounting
verae.identity.bind RR Q identity yes yes (fleet enabled)
verae.identity.lookup RR Q identity yes yes
verae.archive.put JS (VERAE_ARCHIVE) yes partial splitter is in-process in middleware; worm/tree on 510 consume
verae.archive.query broadcast (no Q) yes partial live aggregator hook TBD in middleware (simulator has it)
verae.archive.reply.<id> replies on bloom hit yes partial worm/tree on 510 can reply; aggregator not fleet-enabled
verae.splitter.in future yes (docs) no splitter stays a library
verae.example.process.in / .out / .reply.* template yes no verae-nats-process is a model, not a live worker
bench.* lab only n/a ephemeral speed studies; not product

Fleet overlay vs in-process

overlays/ns1/fleet.json (2026-09-14):

Service fleet enabled Actual lab
middleware-http true running; also starts job-poller + webhook workers in-process when NATS_ENABLED
job-poller false covered by middleware, not a second fleet spawn
webhook-deliver false same
archive-aggregator false not running as a fleet worker
archive-worm / tree-node false on host fleet running on LXC 510 via verae-keep units.px-worker.json (1 worm + 1 tree)
account-balance, access-*, identity, jobs-events, CS/sales/acct, staff-iam/session true keepFloor
zapier-simulator true, keepFloor false optional
nats managed false 3-node cluster + leftover host loopback

Docs that name routes (do not invent extras)

  • packages/docs-master/modules-and-nats.md, MESSAGE-FLOWS.md
  • packages/overview/03-nats-cluster.md, 06-address-routing.md
  • packages/verae-ops/06-linking-services.md
  • Each package NATS.md
  • verae-nats-cluster/scripts/ensure-streams.sh
  • Public edge: verae-nats-cluster/conf/public-edge.conf.tmpl (leaf, not a new subject family)