Add dev-overview: designed vs running NATS routes and Zapier-Verae path.
Some checks failed
offline / test (push) Has been cancelled
Some checks failed
offline / test (push) Has been cancelled
Independent Forgejo repo maps every verae.* address, endpoint I/O, job monitor loop, and remaining billing/archive wiring.
This commit is contained in:
parent
c83f1c6717
commit
86b421db05
1 changed files with 436 additions and 1 deletions
76
packages/dev-overview/01-nats-routes.md
Normal file
76
packages/dev-overview/01-nats-routes.md
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
# 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)
|
||||
Loading…
Reference in a new issue