Files

glm-5.1 d3633b7839 docs: complete Phase 0 architecture — spec updates, review fixes, and link portability

Update four existing specs (overview, server, napi-and-pubsub, call-protocol) to
reflect Phase 0 decisions: three-layer model, IdentityProvider, ForwardingPolicy,
OperationEnv, static/dynamic config split. Review all 9 Phase 0a ADRs (026-034)
for consistency. Fix 4 critical issues from architecture review: missing OQ-SVC-05
in open-questions.md, deprecated hub terminology, undefined AuthService and noq
terms. Replace inline OQ text with cross-references per format rules. Add
ConfigServiceImpl definition to configuration.md. Port absolute workspace paths
to project-relative links by copying referenced docs (feasibility, certbot,
fail2ban, event_source_types) into docs/research/.

2026-06-07 11:27:52 +00:00

1.9 KiB

Raw Blame History

ADR-003: iroh Stream via tokio::io::join

Status

Accepted

Context

iroh's QUIC implementation provides separate RecvStream (implements AsyncRead) and SendStream (implements AsyncWrite) for each bidirectional channel opened via open_bi() / accept_bi(). russh's connect_stream() and run_stream() require a single type implementing both AsyncRead and AsyncWrite.

Options considered:

tokio::io::join(recv, send) — Combines the two halves into Join<RecvStream, SendStream> which implements both traits.
Custom IrohStream wrapper — A struct with recv and send fields that delegates AsyncRead to recv and AsyncWrite to send.
Using iroh's Connection directly — Opening a new open_bi() for each SSH channel instead of running SSH over a single stream.

Decision

Use tokio::io::join(recv_stream, send_stream) (Option 1).

One line of code, correct trait implementations, no custom types needed. The Join<A, B> type implements AsyncRead using A and AsyncWrite using B, which maps directly to iroh's split stream model.

If profiling later shows overhead (unlikely — it's just method dispatch), we can switch to a custom wrapper. But YAGNI until demonstrated.

Option 3 was rejected because it would require modifying russh to understand iroh connections. The whole point of the transport trait is that SSH doesn't know about iroh.

Consequences

Positive: Minimal code. One line to bridge iroh and russh.
Positive: No custom types to maintain.
Positive: Correct AsyncRead + AsyncWrite behavior — Poll::Pending on one half doesn't affect the other.
Negative: None identified. The Join type is a standard tokio combinator with well-tested semantics.

1.9 KiB Raw Blame History