When gRPC lands: correct the dependency claims in README + ARCHITECTURE §1.4

Cordy commented

2026-08-04 23:22:00 +00:00

Owner

Scheduled documentation debt from the peering decision (#100, IMPLEMENTED-PEERING.md §7). Do not action before #102 merges — until google.golang.org/grpc is actually in go.mod, the current claims are true and editing them would describe software that does not exist.

Trigger: the commit that adds the gRPC dependency (#102, peering control plane).

What becomes false at that moment:

README.md — "Small trust surface. Four Go dependencies total: x/crypto (argon2id), go-oidc + x/oauth2 (OIDC), go-ldap (LDAP), filippo.io/age (at-rest encryption) — plus exactly one vendored browser asset…"
ARCHITECTURE.md §1.4 — the tiny-trust-surface commitment, which peering is a deliberate exception to.

Proposed wording (Nikola to approve, not to be slipped in silently): the core file server keeps its four Go dependencies and one vendored browser asset; peering — opt-in, off unless configured — adds gRPC and protobuf, for control messages only, with the data plane on stdlib HTTP. §1.4 gains a paragraph recording that this was argued (draft recommended against it, option C chosen deliberately) rather than accreted, and noting the mitigations: four RPCs, generated code committed so customers never run protoc, data plane independent and replaceable.

Why this is an issue and not a comment: the "age is not post-quantum" line sat wrong in ARCHITECTURE.md until #28 forced a re-read. Marketing-adjacent claims decay silently; this one gets a tripwire.

Also fold in at the same time: example.config.json + the deployment handbook page gain the peering block, and the handbook gets its peering page (#109 pipeline).

Scheduled documentation debt from the peering decision (#100, `IMPLEMENTED-PEERING.md` §7). **Do not action before #102 merges** — until `google.golang.org/grpc` is actually in `go.mod`, the current claims are true and editing them would describe software that does not exist. **Trigger:** the commit that adds the gRPC dependency (#102, peering control plane). **What becomes false at that moment:** - `README.md` — "**Small trust surface.** Four Go dependencies total: `x/crypto` (argon2id), `go-oidc` + `x/oauth2` (OIDC), `go-ldap` (LDAP), `filippo.io/age` (at-rest encryption) — plus exactly one vendored browser asset…" - `ARCHITECTURE.md` §1.4 — the tiny-trust-surface commitment, which peering is a deliberate exception to. **Proposed wording (Nikola to approve, not to be slipped in silently):** the *core file server* keeps its four Go dependencies and one vendored browser asset; **peering — opt-in, off unless configured — adds gRPC and protobuf**, for control messages only, with the data plane on stdlib HTTP. §1.4 gains a paragraph recording that this was argued (draft recommended against it, option C chosen deliberately) rather than accreted, and noting the mitigations: four RPCs, generated code committed so customers never run `protoc`, data plane independent and replaceable. **Why this is an issue and not a comment:** the "age is not post-quantum" line sat wrong in ARCHITECTURE.md until #28 forced a re-read. Marketing-adjacent claims decay silently; this one gets a tripwire. Also fold in at the same time: `example.config.json` + the deployment handbook page gain the `peering` block, and the handbook gets its peering page (#109 pipeline).

Cordy added this to the v0.5 — Instance peering (federation v1) milestone

2026-08-04 23:22:00 +00:00

Cordy referenced this issue

2026-08-04 23:37:21 +00:00

Peering: trust store + admin API (#101) #119

Cordy referenced this issue

2026-08-04 23:54:30 +00:00

Peering transport: gRPC control plane + HTTP data plane, inbound service #102

Cordy referenced this issue

2026-08-05 00:18:45 +00:00

Peering handshake: Ed25519 challenge-response + capability tokens (#102, part 1) #121

Cordy referenced this issue from a commit

2026-08-05 17:23:44 +00:00

ci: one-shot to locate the #118 dependency claims

Cordy referenced this issue from a commit

2026-08-05 17:26:03 +00:00

ci: one-shot to settle the #118 dependency claims

forgejo-actions referenced this issue from a commit

2026-08-05 17:26:18 +00:00

docs: correct the dependency claims for gRPC (#118, #102)

Cordy referenced this issue

2026-08-05 17:35:50 +00:00

Peering transport: control plane, data plane and single-port routing (#102) #122

Cordy closed this issue

2026-08-05 17:37:14 +00:00

Cordy referenced this issue

2026-08-05 17:37:28 +00:00

Peering: how does the receiver decide a recipient "exists"? (blocks the cmd/cairnd wiring) #123

Cordy referenced this issue

2026-08-05 18:46:16 +00:00

When peering works end to end: describe it in README + ARCHITECTURE #124

Cordy referenced this issue

2026-08-06 02:29:10 +00:00

Peering transport: gRPC control plane + HTTP data plane, inbound service #102

Cordy commented

2026-08-06 02:29:17 +00:00

Author

Owner

Closed — what changed

Actioned in PR #122, the commit that put google.golang.org/grpc and google.golang.org/protobuf into go.mod.

README.md — the claim was already stale before gRPC arrived: it said "Four Go dependencies total" while ARCHITECTURE.md §1.4 said five, and the list itself contained five. Now reads five for the core file server, and names peering's two additions as the one place the discipline was deliberately broken — opt-in, off unless configured, control messages only, data plane on stdlib HTTP.

ARCHITECTURE.md §1.4 — gained a paragraph recording the exception as argued rather than accreted: why option C was chosen (the control surface is multi-method and must stay evolvable across two independently-operated instances, which is where schema discipline earns its cost), what bounds the blast radius (four RPCs, feature off unless configured, generated code committed so no protoc on customer machines, data plane already independent), and — since the point of the exercise was honesty — that a self-hoster enabling peering genuinely does audit a larger surface.

Also corrected Status: v0.3.x → v0.4.x while in there.

What did NOT ship here, and why

The final paragraph of this issue also asked for example.config.json and the handbook deployment page to gain the peering block. That was deliberately left out: at the time, beyond peering.statePath those config fields did not exist. Documenting them would have described software that did not exist — the exact failure mode this issue was created to prevent.

They now do exist (stagingDir, transfersPath, plus the runtime settings peeringEnabled / peeringMaxFileBytes / peeringBaseUrl), and the documentation work is carried on #124, which is trigger-based on #106 so the feature gets described once from fact rather than four times from intent.

## Closed — what changed Actioned in PR #122, the commit that put `google.golang.org/grpc` and `google.golang.org/protobuf` into `go.mod`. **`README.md`** — the claim was already stale *before* gRPC arrived: it said "Four Go dependencies total" while `ARCHITECTURE.md` §1.4 said five, and the list itself contained five. Now reads five for the core file server, and names peering's two additions as the one place the discipline was deliberately broken — opt-in, off unless configured, control messages only, data plane on stdlib HTTP. **`ARCHITECTURE.md` §1.4** — gained a paragraph recording the exception as *argued* rather than accreted: why option C was chosen (the control surface is multi-method and must stay evolvable across two independently-operated instances, which is where schema discipline earns its cost), what bounds the blast radius (four RPCs, feature off unless configured, generated code committed so no `protoc` on customer machines, data plane already independent), and — since the point of the exercise was honesty — that a self-hoster enabling peering genuinely does audit a larger surface. Also corrected `Status: v0.3.x` → `v0.4.x` while in there. ## What did NOT ship here, and why The final paragraph of this issue also asked for `example.config.json` and the handbook deployment page to gain the `peering` block. That was deliberately left out: at the time, beyond `peering.statePath` those config fields **did not exist**. Documenting them would have described software that did not exist — the exact failure mode this issue was created to prevent. They now do exist (`stagingDir`, `transfersPath`, plus the runtime settings `peeringEnabled` / `peeringMaxFileBytes` / `peeringBaseUrl`), and the documentation work is carried on **#124**, which is trigger-based on #106 so the feature gets described once from fact rather than four times from intent.

Rows
Columns

When gRPC lands: correct the dependency claims in README + ARCHITECTURE §1.4 #118

Closed — what changed

What did NOT ship here, and why