- resource.open("tcp", ip:port, ["read","write"]) with exact IP grants,
project mode only, 5s connect/read/write timeouts; no DNS/TLS/UDP/server
sockets (ADR-0034).
- Add TCP stream storage/dispatch in the resource table; CLI --allow-net IP;
pure/strict preflight rejects the grant and the language endpoint.
- Host loopback echo/grant/DNS/strict tests and a .mq.md CLI echo test.
- Update specs, status, architecture, README, changelog and evidence.
Gate: fmt, clippy -D warnings, 426 tests passed.
3.6 KiB
ADR-0034: Blocking TCP resource endpoint v1 (CM-A09/P5 first slice)
Status: Accepted
Date: 2026-11-20
Relates to: docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md
(CM-A09, CM-A11, P5), ADR-0025, ADR-0033
Specs: spec/evaluation.md, spec/security.md
Evidence: docs/evidence/2026-11-20-tcp-endpoint.md
Context
CM-A09/P5 require a real external endpoint reached through the stable resource
ABI, not a new HostOp or Rust builtin per application. The in-process
provider slice (ADR-0033) covers trusted adapters; it does not exercise a real
OS byte stream. This ADR adds the first OS endpoint: a blocking TCP stream.
The scope is deliberately narrow: HTTP/1.1, TLS, DNS, UDP, sockets as a broad API and nonblocking/async I/O remain standard-library or later work.
Decision
1. Resource kind and descriptor
resource.open("tcp", "<ip-literal>:<port>", ["read", "write"]) -> Resource
- descriptor must parse as a
SocketAddrcontaining an IP literal. DNS names are rejected withresource.unsupported; no resolver is called. - rights must be exactly
["read","write"]in this build. A read-only or write-only TCP handle is future work. resource.read/write/closebehave like other streams:- read returns
{count, eof};count=0is transport EOF; - write returns a possibly short count;
- close calls
shutdown(Both)and marks the handle closed; - closed/forged/stale handles use the existing
resource.closed/runtime.resourcerules.
- read returns
- connect, read and write have 5-second timeouts. This is blocking I/O on the interpreter thread; no async runtime is introduced.
2. Authorization
projectmode only.pureandstrictrefuse TCP (permission.denied); strict remains fail-closed (CM-A11), and the G-C lane verifies the refusal.Capabilities.check_net(ip)requires an exact IP-literal grant. The CLI adds--allow-net <IP>(repeatable);--allow-netis refused alongside other external grants in pure/strict preflight.- Granting a hostname or a network range does not authorize a different IP; there is no DNS-based allowlist bypass because DNS is not used.
- No TLS, no proxy, no HTTP parsing in the host.
.mq.mdcode composes protocols over the byte stream.
3. Trace
resource.open/read/write/close effect events are recorded. The trace records
the IP:port for open but never payload bytes or credentials. A TCP endpoint is
an external effect and is not replayed as pure computation.
4. Explicit non-goals
- DNS, TLS, HTTP/1.1 or HTTP/2 host implementations, proxies, redirects.
- UDP, ICMP, raw sockets, socket options, nonblocking/async/select.
- File descriptors exposed to the language,
setsockopt,bind/listenserver sockets. - Strict-mode TCP and any claim that in-process
std::netis OS isolation. - Network provider package installation or a generic socket registry.
Consequences
.mq.mdcan implement a line protocol/HTTP client parser on top of the TCP byte stream using the existing Memory/Text/Result primitives.- The runtime still has no
net.requestbuiltin or newHostOp; a CLI test opens a local echo server, writes/readspingthroughresource.*, and closes. - Blocking timeouts bound a hung peer but do not preempt a blocking syscall deeper than the OS timeout; this is documented.
- Network tests use loopback only; external network access is not required for the gate.
Verification
docs/evidence/2026-11-20-tcp-endpoint.md records host tests (loopback echo,
grant/pure/strict/DNS refusal) and a CLI .mq.md echo test with
--allow-net 127.0.0.1, plus the full workspace gate.