alknet/tasks/architecture/adr-026-transport-interface-separation.md at 835724d08748d50390553c69df04a664043a8397

Files

glm-5.1 19b3d3a078 docs: write Phase 0 architecture foundation — ADRs 026-034, spec docs, and task updates

Phase 0a — ADRs (9 new):
- ADR-026: Transport/interface separation (three-layer model)
- ADR-027: Crate decomposition (core, secret, storage, flowgraph, napi, CLI)
- ADR-028: Auth as irpc service (AuthProtocol behind feature flag)
- ADR-029: Identity as core type (Identity + IdentityProvider in alknet-core)
- ADR-030: Static/dynamic config split (ArcSwap, ConfigReloadHandle)
- ADR-031: Forwarding policy (rule-based allow/deny, TransportKind-aware)
- ADR-032: Event boundary discipline (domain, irpc, call protocol boundaries)
- ADR-033: OperationEnv universal composition (three dispatch paths)
- ADR-034: Head/worker terminology (replace hub/spoke)

Phase 0b — New spec documents (7):
- identity.md, services.md, interface.md, configuration.md,
  storage.md, flowgraph.md, secret-service.md

Updated existing docs:
- auth.md: reference identity.md for canonical definitions, add AuthProtocol
- open-questions.md: resolve OQ-12, OQ-16, OQ-18, OQ-22, OQ-23-25
- README.md: add all new docs, ADRs 026-034

Marked 19 architecture tasks as completed.

2026-06-07 09:32:58 +00:00

3.6 KiB

Raw Blame History

id, name, status, depends_on, scope, risk, impact, level

name

status

depends_on

scope

risk

impact

level

architecture/adr-026-transport-interface-separation

Write ADR-026 — Transport/interface separation (three-layer model)

completed

moderate

high

project

implementation

Description

Write ADR-026 establishing the three-layer model: Transport (Layer 1), Interface (Layer 2), Protocol (Layer 3). This is the most architecturally significant new ADR — it redefines SSH as an interface (not a transport) and enables the DNS control channel, raw framing, and future WebTransport as (Transport, Interface) pairs.

The three layers:

Layer 1: Transport — produces byte streams. TCP, TLS, iroh, DNS (as byte carrier), WebTransport. A Transport still produces AsyncRead + AsyncWrite + Unpin + Send.
Layer 2: Interface — consumes a Transport::Stream and produces call protocol events (sessions). SSH is an interface. Raw framing (4-byte length prefix + JSON EventEnvelope) is an interface. DNS control channel is a (DNS transport, raw framing interface) pair.
Layer 3: Protocol — carries semantics. Call protocol events, operation registry, service calls. Protocol is agnostic to both Transport and Interface below it.

A connection is always a (Transport, Interface) pair. The valid combinations are enumerated:

(TLS, SSH) — standard alknet tunnel
(TCP, SSH) — plain SSH tunnel
(iroh, SSH) — P2P SSH tunnel
(DNS, raw framing) — DNS control channel
(WebTransport, SSH) — browser SSH tunnel (future)
(WebTransport, raw framing) — browser call protocol (future)
(TCP, raw framing) — direct call protocol, local mesh

Key changes from current architecture:

SSH is an interface, not a transport. Currently deeply embedded in ServerHandler.
The TransportKind enum gains Dns and WebTransport variants (initially tags only).
Raw framing (4-byte BE length prefix + JSON) is an interface without SSH wrapping.
DNS control channel carries call protocol frames directly — it does NOT wrap SSH inside DNS.

This ADR requires careful review because it's the foundation for Phase 1.8 (Interface Abstraction), which is the most invasive code change.

Acceptance Criteria

docs/architecture/decisions/026-transport-interface-separation.md exists
ADR follows established format
Context explains why SSH is currently tangled with transport and why separating them matters (enables DNS, raw framing, WebTransport without SSH)
Decision states: three layers; SSH is Layer 2 not Layer 1; Transport trait produces byte streams unchanged; Interface trait consumes Transport::Stream and produces call protocol sessions; connection = (Transport, Interface) pair; valid pairs enumerated
Shows the Interface trait signature (consume stream, produce sessions)
Lists the valid (Transport, Interface) combinations
Consequences: enables DNS control channel without SSH wrapping; enables raw framing for service mesh; SSH becomes pluggable; ServerHandler is refactored into SshInterface
DNS control channel carries call protocol directly (NOT SSH inside DNS) — explicitly stated
References: research/core.md DNS section, integration-plan.md Phase 1.8

References

docs/research/core.md — transport layer, DNS transport section
docs/research/integration-plan.md — Phase 1.8, three-layer model, DNS as (DNS transport, raw framing interface)
docs/architecture/transport.md — current Transport trait (unchanged at Layer 1)
docs/architecture/server.md — current ServerHandler (will become SshInterface)

Notes

To be filled by implementation agent

Summary

To be filled on completion

3.6 KiB Raw Blame History