Protos¶
Protocol Buffer definitions, served over Connect.
| Package | Source | Served by | Consumers |
|---|---|---|---|
portal.v1 |
platform/nexus/proto/portal/v1/ |
nexus | portal; edge/gateway CI (ReleasePublisherService) |
gateway.v1 |
platform/nexus/proto/gateway/v1/ |
nexus; realtime Worker (RealtimePushService) |
edge agent, realtime Worker, nexus |
relay.v1 |
platform/nexus/proto/relay/v1/ |
nexus | edge/relay |
authz.v1 |
platform/authz/proto/authz/v1/ |
authz | nexus (pkg/authzclient), Monsieur Wifi |
mrwifi.v1 |
platform/mr-wifi/services/go/proto/mrwifi/v1/ |
mr-wifi-go | mr-wifi-svelte (keeps an identical copy in proto/) |
- portal.v1 — every portal RPC and the permission check it applies.
- gateway.v1 — device and internal RPCs, and the WebSocket frame schema.
- relay.v1 — relay enrolment, heartbeat, attach/detach.
Generated code¶
Generated code is committed; CI builds from it and does not regenerate.
| Repo | Output | Generators |
|---|---|---|
| nexus | gen/ (Go) |
local protoc-gen-go (v1.36.11), connectrpc/go v1.18.1 |
| portal | src/lib/api/gen/ (TypeScript) |
bufbuild/es v1.10.0, connectrpc/es v1.6.1 (target=ts) |
| realtime | gen/ (TypeScript), from a vendored proto/ copy |
bufbuild/es v1.10.0, connectrpc/es v1.6.1 |
The portal generates portal/v1 and gateway/v1. src/lib/api/transport.ts
instantiates clients for the Session, Org, Gateway, Admin and Users services
only.
Regenerating¶
# nexus (Go) — the protos live here
cd platform/nexus && buf generate proto
# portal (TypeScript)
cd platform/portal && npm run generate
Do not run buf generate directly in the portal
The portal reaches the protos through a committed symlink,
proto -> ../nexus/proto, and its buf.gen.yaml has clean: true, so buf
empties src/lib/api/gen/ before writing.
- In a git worktree the symlink dangles: the run deletes the committed clients and writes nothing.
- In the main checkout it resolves to whatever branch nexus is on, and generating from the wrong branch silently drops fields.
npm run generate (scripts/generate-proto.mjs) resolves the source
explicitly ($PROTO_DIR, then ./proto, then the main worktree via
git rev-parse --git-common-dir), prints the ref it generated from, and
requires it to be origin/main unless $PROTO_REF names the ref you
intend.
protoc-gen-go version
Use v1.36.11. Any other version produces a large spurious diff across the generated files.
Wire format¶
- Connect-JSON by default everywhere.
int64is a JSON string,bytesis base64, field names are camelCase. - The agent ↔ DO WebSocket frames are plain JSON defined in
platform/realtime/src/messages.ts, not protobuf.