Files
marqdo-cli/docs/evidence/2026-11-20-tcp-endpoint.md
cflmy 00bdcad1ff feat(host): add IP-literal blocking TCP resource endpoint (P5)
- 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.
2026-11-20 23:05:06 +08:00

2.6 KiB

RFC-CM P5 evidence: blocking TCP resource endpoint v1

Date: 2026-11-20 (Asia/Shanghai) Repository: marqdo-cli Baseline: 1d87f98 plus this step's changes. Decision record: ADR-0034 Related: provider v1, STATUS §5. Scope: IP-literal blocking TCP only; no DNS/TLS/UDP/server sockets.

Environment and gate

Ubuntu 26.04 development container, Linux x86_64, Rust 1.100.0.

cargo fmt --all -- --check                            PASS
cargo clippy --workspace --all-targets -- -D warnings PASS
cargo test --workspace --locked                       PASS
  426 passed, 0 failed, 2 ignored (existing plugin-sdk doc-tests)

No GitHub CI is available from this checkout; this is local evidence.

Contract

resource.open("tcp", "<ip-literal>:<port>", ["read", "write"])
  • project mode only; pure/strict refuse;
  • exact IP-literal grant (Capabilities.check_net), CLI --allow-net <IP>;
  • DNS names rejected with resource.unsupported (no resolver is called);
  • connect/read/write timeouts 5 seconds; blocking I/O on the interpreter thread;
  • resource.read returns {count, eof}, write a possibly short count, close shuts the socket down; closed/forged handles use existing rules;
  • trace records resource.open/read/write/close effects (IP:port on open, no payload bytes).

No new HostOp, Value, builtin or Markdown syntax.

Tests

Host (crates/marqdo-host/tests/resource_streams.rs, 2 TCP tests):

tcp_resource_round_trips_with_a_network_grant
  loopback echo: write ping -> read ping -> close

tcp_requires_network_grant_and_rejects_dns_names
  no --allow-net -> permission.denied
  "example.test:80" -> resource.unsupported
  pure/strict -> permission.denied

CLI (crates/cli/tests/resource_streams.rs):

tcp_stream_round_trips_through_mqmd_with_a_network_grant
  local TcpListener; .mq.md writes/reads 4 bytes through Memory;
  run --allow-net 127.0.0.1 --json -> [4,4,112,105,110,103,true]

Not done

  • DNS, TLS, HTTP framing, proxies, UDP, raw sockets, socket options.
  • Nonblocking/async/select and server bind/listen.
  • Strict-mode TCP and any claim that std::net in-process is OS isolation.
  • Provider package installation/registry for network endpoints.

Reproduce

export PATH=/root/.cargo/bin:$PATH
export CARGO_HOME=/root/work/marqdo-cli/.cache/cargo
export CARGO_TARGET_DIR=/root/work/marqdo-cli/.cache/target
cargo test -p marqdo-host --test resource_streams tcp
cargo test -p marqdo-cli --test resource_streams tcp
cargo test --workspace --locked