alktunnels/tasks/tunnels/local-socket-halves.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
tunnels/local-socket-halves	local feature — real socket halves functions (TCP dial, UDP connect, unix)	pending	tunnels/producer-open-op tunnels/wire-codec	moderate	medium	component	implementation	local backend sockets feature-gate

Description

Add the local feature module (src/local/) per overview.md §Feature Gates + ADR-004: the real-socket halves functions the assembly layer injects as DialFn/AcceptFn closures. The POCs' substrate adapters are the reference (they ran all of this); the task is packaging them into the feature-gated module with the crate's conventions.

Surface

// src/local/mod.rs (feature = "local"; non-wasm by design)
pub async fn dial_tcp(target: &str) -> Result<TargetHandle, TunnelEstablishError>;
// TcpStream::connect (5s timeout per the POCs) → into_split → boxed halves

pub async fn connect_udp(target: &str) -> Result<TargetHandle, TunnelEstablishError>;
// UdpSocket::bind(("0.0.0.0", 0)) → connect(target) → the FRAMED adapter
// (UdpHalf + codec — ADR-003; truncation fail-loud per OQ-TN-13)

pub async fn dial_unix(path: &str) -> Result<TargetHandle, TunnelEstablishError>;
// UnixStream::connect → into_split (OQ-TN-14: ships with local v1 — cheap,
// same halves shape as TCP)

pub struct TcpListenerHalves { listener: tokio::net::TcpListener }
impl TcpListenerHalves {
    pub async fn bind(addr: &str) -> Result<Self, ...>;
    pub fn accept_fn(&self, queue: &AcceptQueue) -> impl Future;  // the accept loop feeding the queue
}

pub struct UdpAssociateHalves { sock: Arc<UdpSocket> }  // the POC's associate shape

• UDP adapter (UdpHalf): port from the forward POC (params.rs's UdpHalfRead/UdpHalfWrite) with the truncation fix: poll_recv into a too-small caller buffer must fail loud (OQ-TN-13's resolved posture — ADR-003). The codec wraps at this boundary; the pump never sees UDP specifics.
• Error mapping to TunnelEstablishError variants (the POC's Into<EstablishmentError> path).
• TargetHandle re-used from producer.rs (the halves type lives in producer.rs; local/ depends on it, never vice versa).

Feature wiring

[features]
default = []
local = ["tokio/net"]

• tokio/net is the only dep addition (no new external crates; the POCs proved rt+sync+io-util+macros+time+net covers everything).
• The default crate stays wasm-clean: local-gated code must not be importable from producer.rs/consumer.rs (convention 16 — backend modules are never imported from the shared/producer/consumer modules).
• Unix is IN v1 (OQ-TN-14's lean-yes posture; same halves shape as TCP); stdio bridging is NOT (different lifecycle — deferred).

Tests

Behind the feature: TCP dial round-trip through the real establisher path, UDP associate + datagram round-trip with the framed adapter, unix dial round-trip, truncation fail-loud (a short recv surfaces as an error), the 1400-byte MTU datagram through bounded buffers (the POC's sizing test).

Acceptance Criteria

• cargo test --features local green; cargo test (default) unaffected
• cargo test --all-features green (AGENTS.md convention 14)
• wasm32 check on the DEFAULT crate passes; local is non-wasm by design (documented)
• Truncation fails loud (the OQ-TN-13 test)
• No socket type appears outside src/local/
• Clippy/fmt clean

References

• docs/architecture/overview.md §Feature Gates, §Dependencies
• docs/architecture/decisions/004-no-backend-trait.md (the injection point), 003 (the framed adapter)
• POC reference: /workspace/alktunnels-udp-poc/src/producer.rs (UdpHalf, the dial paths), params.rs (the UDP adapter)

Notes

Agent fills during implementation.

Summary

Agent fills this on completion.