alktunnels/docs/architecture/producer.md

status, last_updated

status	last_updated
draft	2026-09-07

alktunnels — Producer Half

The producer half: the channels/tunnel/sub open op — its spec, its establisher (dial + listen shapes), its pump handler, and its registration. The producer is whoever can reach the tunnel target; connection direction is irrelevant (OQ-TN-03's hub model). The reverse POC validated the producer running on the connect side of its own connection (from_connection_with_serving).

Design decisions: ADR-001 (params), ADR-002 (ALPN), ADR-003 (codec), ADR-004 (no backend trait). This document is the normative WHAT.

The Open-Op Spec

operation id:   channels/tunnel/sub
op type:        Sub          (reply = one { channel_id } envelope; data plane on the BiStream)
ALPN marker:    alk/tunnel   (ChannelOpenSpec)
visibility:     External
input schema:   { resource: string (required), substrate: enum [tcp, udp, unix] (required) }
output schema:  { channel_id: integer > 0 }
access control: required_scopes: ["tunnel:open"]
description:    SHOULD carry a human-readable hint (round-trips through discovery, OQ-TN-08)

Registration is via ChannelCore::register_openable_with_establisher (alkcall ADR-049 §5): the registry schema-validates input, runs the ACL, allocates the channel (connection-owner rule, ADR-047 §5), runs the establisher as the awaited bounded establishment phase, then spawns the pump handler. The generic channel ops (channel/close, channel/control, channel/resources/subscribe) register separately via ChannelOperations::register_on — the producer (or its assembly layer) MUST register them on the serving registry so peers can manage channels out-of-band (the recipe alkcall review 007 §Part B verified — alkcall/docs/reviews/ 007-establishment-follow-ups-review.md; R-01 = the Establishment plan payload, R-02 = the OpenHandler lifetime contract).

Registration timing: the openable may register AFTER from_connection_with_serving returns (the connect-side serving posture — the reverse POC's W2): the dispatcher reads through the shared Arc<OperationRegistry> per dispatch. Late registration is a supported assembly shape, not a race.

The Establisher

The establisher is the open op's awaited, bounded establishment phase (alkcall ADR-049 §1/§2): validate params semantically, consult ownership if wired, dial/accept the substrate, and return Establishment::new(plan) — the dialed handle rides the typed-opaque plan (ChannelPlan = Arc<dyn Any + Send + Sync>; the + Sync bound constrains plan payloads — socket-backed handles carry it naturally, reverse POC F-1, documented upstream). On failure: EstablishmentError (the typed reason codes) → the wrapper tears the channel down and replies channel:open_failed.

Two shapes (both return the same plan-flow; ADR-004):

1. Dial establisher (the -L/forward shape)

Registry lookup of (resource, substrate) → backing → dial → halves. The dial function is substrate code injected at assembly (ADR-004: the establisher closure closes over it); the protocol crate never sees a socket type. Failure mapping:

Producer condition	Typed reason
resource not in the registry (or wrong substrate)	unknown_resource
dial refused / timed out / unreachable	dial_failed
bind/connect resource exhaustion (fds, ports, slots)	resource_shortage
establisher-internal failure	handler_error
the bound exceeded	timeout (wrapper-level)

2. Listen establisher (the producer-side listener variant)

For a producer whose resource is a LISTENER (SSH -R far-side listener; a hub exposing its own port to a third party): the same open op, the same params; the establisher pops the next accepted connection from an assembly-owned listener queue and returns it as the plan payload. The listener lifecycle (bind, accept loop, cancel) is assembly code — the protocol never binds (OQ-TN-04). Error mapping: an empty queue during establishment is resource_shortage; a closed listener is dial_failed-class. No new wire surface — the listen variant is plan-flow with a different halves source.

Identity: the establisher receives the per-call opener identity (the dispatch-resolved identity overlaid onto the install-time context — alkcall 0.7.0 CF-006). On hub-forwarded opens it sees the end client, not the hub. auth carries the opener's identity plus the transport-truthful fields (alpn, remote_addr, tls_client_fingerprint) — never rewritten. Consult it for ownership-scoped resources if the assembly layer wants OwnershipProvider checks here (OQ-TN-08's optional half).

Concurrency: each open's establisher result flows to ITS pump handler — concurrent opens of the same resource are independent (the R-01 plan flow — alkcall review 007 R-01, the Establishment::new(plan) payload; the forward POC's resource-keyed handoff race is structurally gone, confirmed under concurrency by the reverse POC).

The Pump Handler

The OpenHandler (alkcall ADR-049/050 shape: Fn(Value, Option<ChannelPlan>, Connection, AuthContext) -> JoinHandle<()>):

1. Downcast the plan to the concrete handle type (Arc::downcast::<TargetHandle> — establisher and handler agree on the type; alkcall never inspects it).
2. conn.accept_bi() — the channel's yield-once BiStream.
3. pump_bidi(bidi, handle.read, handle.write) — awaited inline inside the handler's task. The returned JoinHandle MUST track the data-plane lifetime (R-02): the wrapper awaits it and its completion triggers channel teardown. Early return = teardown-at-birth — both pumps see instant EOF with zero bytes; the "spawn-and-forget" shape is the one bug class the R-02 telemetry (yield-once flag + birth-teardown debug hint) diagnoses at runtime. Hand-rolling the two-pump shape is out (ADR-050).
4. UDP: the plan payload is the FRAMED adapter (ADR-003) — the pump is unchanged; the codec lives at the substrate/pump boundary.

The handler is substrate-agnostic by construction: it cannot know whether the halves came from TCP, UDP, a unix socket, or an in-process pipe, and must not (AGENTS.md convention 7).

Registration API (the spec surface)

pub fn register_tunnel_openable(
    core: &ChannelCore,                 // the manager + policy pair
    registry: &ResourceRegistry,        // assembly-owned: (resource, substrate) -> backing
    on_registry: &Arc<OperationRegistry>,  // the session's dispatch registry
                                        // (the per-session fork per alkcall ADR-047 §4
                                        // amendment, 2026-09-03 — NOT the connection
                                        // overlay; Layer-2-registered open ops resolve
                                        // NOT_FOUND, review 004 F-01)
    auth: AuthContext,                  // the install-time context (per-call overlay is upstream's)
    dial: DialFn,                       // substrate halves function (ADR-004; `local` feature or assembly)
) -> Result<(), String>

• ResourceRegistry (assembly construct, OQ-TN-11): maps (resource, substrate) → backing. The POCs' HashMap shape is the candidate; the collision domain is the producer's registry (ADR-001 — two producers on one connection may expose the same resource name independently).
• The scope constant TUNNEL_OPEN_SCOPE = "tunnel:open"; the open-op spec builder is public so assembly layers can compose variants (e.g. extra ACL fields) without forking the wire shape.
• The pump handler factory is public for the same reason.

Access control posture

Tunnels reach local networks — the open gate is the security boundary (OQ-TN-08):

• The registry runs AccessControl before the establisher (the ACL rides register_openable; free via alkcall).
• TUNNEL_OPEN_SCOPE is the base gate; the assembly layer MAY add resource-scoped checks via the establisher (ownership on the resource name) — the protocol provides the seam, not the policy.
• No target allowlists, no tunnel-specific policy machinery in v1 — the far side owns the resource (OQ-TN-08 resolution); discovery is the ACL-filtered ops listing.

Open Questions

• OQ-TN-11: resource naming collision domain + lifecycle (partially resolved — the per-producer registry is the leading candidate)
• OQ-TN-14: unix/stdio substrate placement (open — backend module task, not a wire question)

References

• wire.md (the open op's wire surface), overview.md (module map)
• Forward POC docs/research/poc-summary.md; reverse POC docs/research/reverse-poc-summary.md (both producer shapes ran)
• alkcall ADR-047/049 (open ops + establishment), ADR-050 (pump_bidi), ledger CF-005/CF-006 (identity precedence + per-call opener)