Files
marqdo-cli/docs/adr/0034-tcp-resource-endpoint.md
cflmy e981168d92 feat(stdlib): add HTTP framing over TCP and close P5 C10 locally
- Add stdlib/net/http.mq.md: status/header/chunked response parsing and request
  construction in .mq.md; no host HTTP/TLS implementation.
- Add stdlib/tests/http.mq.md and an end-to-end loopback test that sends a GET
  over resource.open("tcp"), reads bytes, parses the response and returns
  status/content-type/body.
- Update ADR-0034, status/spec/README/changelog and evidence; refresh the
  bundle digest.

Gate: fmt, clippy -D warnings, 430 tests passed.
2026-11-20 23:13:06 +08:00

3.8 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 SocketAddr containing an IP literal. DNS names are rejected with resource.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/close behave like other streams:
    • read returns {count, eof}; count=0 is 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.resource rules.
  • connect, read and write have 5-second timeouts. This is blocking I/O on the interpreter thread; no async runtime is introduced.

2. Authorization

  • project mode only. pure and strict refuse 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-net is 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.md code 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/listen server sockets.
  • Strict-mode TCP and any claim that in-process std::net is OS isolation.
  • Network provider package installation or a generic socket registry.

Consequences

  • .mq.md can implement a line protocol/HTTP client parser on top of the TCP byte stream using the existing Memory/Text/Result primitives. The bundled stdlib/net/http.mq.md provides HTTP/1.1 response parsing (status, headers, chunked transfer) and request construction; http_over_tcp.rs runs a local HTTP exchange through resource.open("tcp", ...) and the module.
  • The runtime still has no net.request builtin or new HostOp; a CLI test opens a local echo server, writes/reads ping through resource.*, 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.