alktunnels/docs/architecture/decisions/002-alpn-strategy.md

ADR-002: Single alk/tunnel ALPN (Option A)

Status

Accepted (2026-09-07); amended 2026-09-16 (flavor-form op ids on the one ALPN, see Amendment 1)

Context

alkcall ADR-004: one ALPN per protocol, alk/ prefix. This crate owns the alk/tunnel-family ALPN(s). The open question (OQ-TN-07) was whether stream (TCP/unix) and datagram (UDP) tunnels get distinct ALPNs:

• Option A: single alk/tunnel ALPN; the substrate is a params field, and per-substrate data framing (if any) is self-describing inside the channel.
• Option B: alk/tunnel (stream) + alk/tunnel-dgram (datagram), so the wire framing differs per ALPN cleanly.

Mechanically both are cheap: channels' params is ALPN-specific, and the open-handler registry dispatches per ALPN. The cost difference is consumer-side API shape (two session types vs one with a substrate enum) and the ALPN namespace (a published string is wire-stable).

Prior art surveyed in Phase 0 (ssh-socks5-survey.md):

• SSH uses ONE channel mechanism for all forwarding flavors; the channel type string (direct-tcpip, forwarded-tcpip, direct-streamlocal) is per-open metadata on one transport, not a separate transport per flavor.
• SOCKS5 runs CONNECT and UDP ASSOCIATE over one control connection with a CMD discriminator.
• tun2proxy's udpgw proves datagram framing self-describes over a stream (length-framed datagrams inside a TCP tunnel).
• With OQ-TN-02 resolved as endpoint-at-open for base UDP resources, the substrate discriminator in params tells the establisher and pumps which framing to expect, exactly option A's shape. The discriminator is load-bearing (it selects the framing, ADR-003), so it must ride the open op; the ALPN carries no substrate information at all.

Decision

One ALPN: alk/tunnel. The substrate discriminator in params (ADR-001) selects the data-plane framing; the open op, establisher, pump handler, and consumer session type are shared across substrates (one TunnelSession with a substrate-shaped data plane, not two session types).

• The open op id is channels/tunnel/sub (the channels/<alpn>/sub convention of alkcall ADR-047 (the open op is a Sub-typed operation: the reply carries channel_id once, the data plane flows on the channel's BiStream).
• The channel's ALPN marker on the open-op spec is alk/tunnel (ChannelOpenSpec::new("alk/tunnel"), which is the value the per-ALPN dispatch and the adopted-side manager record for observability.
• If a future tunnel flavor needs structurally different framing from byte zero with no params-dependent dispatch, that is a NEW ALPN decided by a new ADR before its first consumer, and never a change to alk/tunnel's meaning. ALPN strings are wire-stable once published.

Consequences

• One session type for consumers (TunnelSession with a substrate-shaped data plane, ADR-005); no API bifurcation.
• One registration per producer regardless of how many substrates it serves; the resource registry (OQ-TN-11) keys on (resource, substrate).
• Framing is params-dependent, not ALPN-dependent. The establisher validates substrate semantically (the registry lookup); the pump handler is framing-agnostic (raw pass-through halves; the codec lives on the consumer/producer edge for UDP, ADR-003). A mismatched substrate value fails at schema/establisher time, loudly.
• ALPN namespace hygiene: alk/tunnel is published here. The alknet/tunnel spelling in the alknet ADR-071 table predates the alknet/ → alk/ prefix swap (alkcall v0.1.1), so docs and code must not perpetuate the old prefix.

References

• OQ-TN-07 (promoted, resolved by this ADR)
• docs/research/ssh-socks5-survey.md §ALPN-relevant prior art
• alkcall ADR-004 (ALPN convention), ADR-047 (open ops per ALPN)
• AGENTS.md convention 17 (ALPN naming)

Amendment 1 (flavor-form op ids, 2026-09-16)

The decision stands: one ALPN, no ALPN split per flavor. What changes: the one-ALPN rule is realized as one ALPN, several Sub-typed open ops, because ADR-007 (the direct op) and ADR-008 (the forwarded op) are different capabilities sharing the tunnel transport, ssh's one-transport-many-channel-types shape.

• The op-id convention extends to flavor form: channels/<alpn>/sub (the original resource op, reserved and unchanged), channels/<alpn>/direct (dial an arbitrary target), and channels/<alpn>/forwarded (accept-as-open toward the listen opener). New flavors are new op ids, which is additive; the …/sub op is never reused for a different meaning.
• The alternative, sibling ALPNs (alk/tunnel-direct, alk/tunnel-forwarded) with standard …/sub op ids, was rejected: it fragments the tunnel namespace per flavor, forces hub relay to track three ALPNs, and amends this ADR's own new-ALPN justification clause (the flavors share framing; none needs structurally different framing from byte zero).
• Upstream coordination: alkcall ADR-047 pins discovery's ALPN derivation to exactly the …/sub/…/pub suffix shapes (derive_alpn_from_op_name); flavor-form op ids need that derivation (and the hub-relay reconstruction riding it) extended; it was filed upstream (alkcall/docs/reviews/008-tunnels-graduation-upstream-review.md, ask #1) before the first consumer. Runtime was never blocked: registration sets the ALPN marker explicitly and open_channel(op_id, params, alpn) takes the ALPN as an argument.