docs(review 008 Unit 3 planning): ADR-051 — in-tree ChannelRelay + hub-leg assembly; plan split into 3a/3b/3c
Design session outcome for the relay unit. The hub/spoke family (hub or spoke may relay; the hub re-exposes spoke services by ACL without binding ports) needs the call-half support too, so the unit's scope grew beyond the as-pinned sketch and is now three sub-units. - ADR-051 (new): the relay is the wrapper composition — translate hop = the ADR-049 establisher shape, byte-forward hop = pump_bidi per ADR-050; the relay holds Arc<CallConnection> + ChannelManager per producer leg (not a ChannelClient — take_call_connection's detach is wrong for a hub with three CallConnection claimants); the reason mapping preserves the spoke's code+message (timeout is the one non-1:1 case, mapping to dial_failed); the registration seam is two-phase (discover/stash → per-connection fork-register — the ADR-047 §4 fork mechanism makes a one-call import impossible); the ADR-042 relay map dissolves (implicit per-channel mapping) and channel/close needs no translation surface (EOF cascade propagates with correct ledger accounting on both legs); Pub-typed marked specs are a loud assembly error; establishment bounds compound per hop (noted, no fix); the ACL layering note is pinned (the spoke's AccessControl sees only the hub identity; forwarded_for is never checked). - ADR-042 amended: the §Scope note is revised (implementation is an alkcall export; hub crates compose it) and the two mechanism supersessions are recorded — the contract and auth-model rationale unchanged. - ADR-047 amendment 3's forward reference and the README ADR index updated (001..051). - Review 008 remediation plan: Unit 3 split into 3a (ChannelRelay component + gates), 3b (hub-leg install template — the call-half support), 3c (gate-2 e2e incl. the mid-establishment disconnect window); sequencing note updated; adoption note records the session's decisions. Verified: cargo doc --no-deps (markdown-only change).
This commit is contained in:
1 parent
620180d615
commit
91765446b7
5 files changed
+505
-69
No files matched your search
@@ -2,7 +2,52 @@
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
Accepted (amended 2026-09-17, ADR-051 — the relay implementation is an
|
||||
alkcall export (`ChannelRelay`), not downstream-only code; the §"Scope
|
||||
note" below is revised, and the §`channel_id` mapping / close-translation
|
||||
mechanism is superseded by an implicit-per-channel shape — see
|
||||
"Amendment (ADR-051, in-tree relay export, 2026-09-17)" below;
|
||||
the translate-not-forward contract and the auth-model rationale are
|
||||
unchanged)
|
||||
|
||||
## Amendment (ADR-051, in-tree relay export, 2026-09-17)
|
||||
|
||||
The relay implementation moved into alkcall as a reusable export
|
||||
(`ChannelRelay`, ADR-051) — consumers that exist (alktunnels'
|
||||
graduation, alkhttp's fallback hub, alknodes) all need the same shape,
|
||||
so the §"Scope note" decision ("the relay implementation lives in
|
||||
`alknet-hub`/downstream") is revised: hub crates COMPOSE the export.
|
||||
|
||||
Two implementation findings supersede mechanism text above, both
|
||||
within the two-way door this ADR already marked:
|
||||
|
||||
1. **The `channel_id` mapping dissolves.** §`channel_id` mapping
|
||||
pinned a `HashMap<channel_id, channel_id>` per (browser, spoke)
|
||||
pair. The implementation needs no map: each leg's `ChannelManager`
|
||||
holds its own id → routing state, and the per-channel pump closure
|
||||
binds both legs. The mapping is implicit-per-channel — a
|
||||
`channel_id` never crosses legs, so the translate hop produces
|
||||
per-leg-truthful ids (this also refines alktunnels ADR-008 §Hub
|
||||
re-produce's "re-map the id at their re-produce hop naturally":
|
||||
the re-map is two independent allocations, not a rewrite).
|
||||
2. **`channel/close` needs no translation surface.** The §mapping
|
||||
bullet's "On `channel/close` (translated the same way), the mapping
|
||||
is removed" assumed the map; without it, close propagates through
|
||||
the EOF cascade (consumer-side close → open-op wrapper teardown →
|
||||
pump abort → send-half drop → EOF chunk → spoke handler exits →
|
||||
spoke's own wrapper decrements its ledger) with correct accounting
|
||||
on both legs. The hub never sees a `channel/close` to translate.
|
||||
`channel/control` stays per-leg (OQ-39 — a hub wanting cross-leg
|
||||
control translation composes it downstream), unchanged.
|
||||
|
||||
The byte-forward layer is ADR-050's `pump_bidi` per channel (the
|
||||
hub never parses chunk framing — stronger than §"Data-channel layer"'s
|
||||
rewrite phrasing, which assumed the map-based rewrite shape). The
|
||||
translate layer is the ADR-049 establisher shape
|
||||
(`register_relay_openable`), keeping the consumer leg's full wrapper
|
||||
machinery (registry ACL, per-identity cap/ledger, establishment bound,
|
||||
teardown-on-failure) — the auth-model rationale above is unchanged and
|
||||
now has a concrete in-tree carrier.
|
||||
|
||||
## Context
|
||||
|
||||
|
||||
Reference in new issue
Block a user