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.
This commit is contained in:
cflmy committed 2026-11-20 23:05:06 +08:00
1 parent 1d87f98539
commit 00bdcad1ff
15 files changed
+435 -4

No files matched your search

+4
View File
@@ -125,6 +125,10 @@ currently `0.1.0`; no release tag has been cut. Dates use ISO 8601.
before module loading, a `std:marqdo-stdlib@<version>#<digest>` package
instance id, `project.stdlib` in Analysis v2, and test coverage for
`std:` resolution, tamper rejection and frozen-binary hash equality.
- P5 blocking TCP endpoint v1 (ADR-0034): `resource.open("tcp", ip:port,
["read","write"])` with exact IP-literal grants, project mode only, 5s
connect/read/write timeouts; no DNS/TLS/UDP/server sockets. CLI `--allow-net
<IP>`; loopback host and `.mq.md` echo tests. Strict/pure refuse.
- CM-A09 in-process ResourceProvider v1 (ADR-0033): `ResourceProvider` trait,
`StdHost::register_resource_provider`, per-kind registration with protocol
version/conflict checks and `Capabilities.allow_resource_provider`; provider
+3
View File
@@ -105,6 +105,9 @@ executes anything.
`.mq.md` print chain is the only execution path for `打印`/`print` on an official install (ADR-0031),
covering all 15 value types; `HostOp::Print` and the legacy formatter are
removed (ADR-0027/0028/0029/0030/0031).
* **Blocking TCP endpoint (RFC-CM P5 first slice)** — `resource.open("tcp",
"<ip>:<port>", ["read","write"])` with exact IP grants, project mode and
5-second timeouts; DNS/TLS/UDP/server sockets excluded (ADR-0034).
* **In-process ResourceProvider v1 (RFC-CM CM-A09 first slice)** — trusted
providers register extra resource kinds, project-mode + name-grant gated,
using the existing `resource.*`/`Result` ABI; no parser/runtime/`HostOp`
+7
View File
@@ -22,6 +22,8 @@ pub struct SandboxSettings {
pub allow_read: Vec<String>,
/// Write grants.
pub allow_write: Vec<String>,
/// Network grants (IP literals, ADR-0034).
pub allow_net: Vec<String>,
/// Foreign execution grant.
pub allow_foreign: bool,
/// Plugin grants.
@@ -70,6 +72,7 @@ impl SandboxSettings {
pub fn strict_preflight(&self) -> Result<(), String> {
let requested = self.allow_foreign
|| !self.allow_read.is_empty()
|| !self.allow_net.is_empty()
|| !self.allow_write.is_empty()
|| !self.allow_plugin.is_empty()
|| !self.plugins.is_empty()
@@ -94,6 +97,7 @@ impl SandboxSettings {
match mode {
SandboxMode::Pure => {
if !self.allow_read.is_empty()
|| !self.allow_net.is_empty()
|| !self.allow_write.is_empty()
|| self.allow_foreign
|| !self.allow_plugin.is_empty()
@@ -112,6 +116,9 @@ impl SandboxSettings {
for pattern in &self.allow_write {
capabilities = capabilities.allow_write(pattern.clone());
}
for host in &self.allow_net {
capabilities = capabilities.allow_net(host.clone());
}
if self.allow_foreign {
capabilities = capabilities.allow_foreign();
}
+4
View File
@@ -86,6 +86,9 @@ struct SandboxArgs {
/// Grant read access to a project-relative glob (repeatable).
#[arg(long = "allow-read", value_name = "GLOB")]
allow_read: Vec<String>,
/// Grant network access to an IP literal host (repeatable, ADR-0034).
#[arg(long = "allow-net", value_name = "IP")]
allow_net: Vec<String>,
/// Grant write access to a project-relative glob (repeatable).
#[arg(long = "allow-write", value_name = "GLOB")]
allow_write: Vec<String>,
@@ -138,6 +141,7 @@ impl SandboxArgs {
commands::SandboxSettings {
mode: self.mode.clone(),
allow_read: self.allow_read.clone(),
allow_net: self.allow_net.clone(),
allow_write: self.allow_write.clone(),
allow_foreign: self.allow_foreign,
allow_plugin: self.allow_plugin.clone(),
+62
View File
@@ -222,6 +222,68 @@ fn file_copy_is_written_in_mqmd_through_chunked_streams() {
);
}
#[test]
fn tcp_stream_round_trips_through_mqmd_with_a_network_grant() {
use std::io::{Read, Write};
use std::net::TcpListener;
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let server = std::thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
let mut buffer = [0u8; 4];
stream.read_exact(&mut buffer).unwrap();
stream.write_all(&buffer).unwrap();
});
let dir = TempDir::new("tcp");
let program = format!(
r#"## main
**内存 = memory.new(1, 1)**
**`内存[0] = 112`**
**`内存[1] = 105`**
**`内存[2] = 110`**
**`内存[3] = 103`**
**流 = resource.open("tcp", "{address}", ["read", "write"])**
**写入 = resource.write(流, 内存, 0, 4)**
**读出 = resource.read(流, 内存, 0, 4)**
**关闭 = resource.close(流)**
*[写入.value.count, 读出.value.count, 内存[0], 内存[1], 内存[2], 内存[3], 关闭.ok]*
"#
);
write_file(&dir.path().join("index.mq.md"), &program);
let output = cli(
dir.path(),
&["run", "index.mq.md", "--allow-net", "127.0.0.1", "--json"],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
let report: serde_json::Value = serde_json::from_slice(&output.stdout).expect("json output");
assert_eq!(report["success"], true);
let values = report["value"]["items"].as_array().expect("list");
assert_eq!(values[0]["decimal"], "4");
assert_eq!(values[1]["decimal"], "4");
for (index, expected) in ["112", "105", "110", "103"].into_iter().enumerate() {
assert_eq!(values[2 + index]["decimal"], expected);
}
assert_eq!(values[6]["value"], true);
server.join().unwrap();
}
#[test]
fn file_stream_requires_a_read_grant() {
let dir = TempDir::new("file-denied");
+6
View File
@@ -374,6 +374,12 @@ impl Capabilities {
self
}
/// Grant network access to one IP literal host (ADR-0034).
pub fn allow_net(mut self, host: impl Into<String>) -> Self {
self.net_hosts.push(host.into());
self
}
/// Grant a registered resource provider by its stable name (ADR-0033).
pub fn allow_resource_provider(mut self, name: impl Into<String>) -> Self {
self.resource_providers.push(name.into());
+49
View File
@@ -5,6 +5,7 @@
//! execution, not at parse/compile time.
use std::collections::{BTreeMap, BTreeSet};
use std::net::{SocketAddr, TcpStream};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
@@ -755,6 +756,54 @@ impl StdHost {
"project file streams support exactly [read] or [write] in this build",
))
}
"tcp" => {
if self.mode != SandboxMode::Project {
return Err(RuntimeError::new(
ErrorCategory::PermissionDenied,
ctx.span,
"tcp resources are available only in project mode",
));
}
if requested != BTreeSet::from(["read", "write"]) {
return Err(RuntimeError::new(
ErrorCategory::ResourceUnsupported,
ctx.span,
"tcp resources require exactly [read, write] in this build",
));
}
let address: SocketAddr = descriptor.parse().map_err(|_| {
RuntimeError::new(
ErrorCategory::ResourceUnsupported,
ctx.span,
format!(
"tcp descriptor `{descriptor}` must be an IP literal address:port (DNS names are not resolved in this build)"
),
)
})?;
self.capabilities
.check_net(&address.ip().to_string(), ctx.span)?;
let stream = TcpStream::connect_timeout(&address, Duration::from_secs(5)).map_err(
|error| {
RuntimeError::new(
ErrorCategory::HostError,
ctx.span,
format!("cannot connect to {address}: {error}"),
)
},
)?;
let _ = stream.set_read_timeout(Some(Duration::from_secs(5)));
let _ = stream.set_write_timeout(Some(Duration::from_secs(5)));
let handle = self.resources.open_tcp(stream);
self.record_semantic(
"resource.open",
None,
Some(&ctx.module_id),
ctx.span,
Some(&format!("kind=tcp address={address}")),
);
self.record_resource_effect("resource.open", ctx, started, "ok");
Ok(Value::Resource(handle))
}
other => {
if self.mode != SandboxMode::Project {
return Err(RuntimeError::new(
+42
View File
@@ -5,6 +5,8 @@
//! table validates run identity, slot identity and generation on every call.
use std::collections::BTreeMap;
use std::io::{Read, Write};
use std::net::TcpStream;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex};
@@ -85,6 +87,10 @@ enum Stream {
token: u64,
closed: bool,
},
Tcp {
stream: TcpStream,
closed: bool,
},
}
struct Slot {
@@ -99,6 +105,7 @@ impl Slot {
Stream::File { closed, .. } => *closed,
Stream::FileWriter { closed, .. } => *closed,
Stream::Provider { closed, .. } => *closed,
Stream::Tcp { closed, .. } => *closed,
}
}
}
@@ -155,6 +162,14 @@ impl ResourceTable {
})
}
/// Register a connected TCP stream.
pub fn open_tcp(&mut self, stream: TcpStream) -> ResourceHandle {
self.insert(Stream::Tcp {
stream,
closed: false,
})
}
/// Open a provider token and wrap it in a host-issued handle.
pub fn open_provider(
&mut self,
@@ -272,6 +287,21 @@ impl ResourceTable {
let mut provider = provider.lock().map_err(|_| provider_lock_error(span))?;
provider.read(*token, max_bytes, span)
}
Stream::Tcp { stream, .. } => {
let mut buffer = vec![0u8; max_bytes];
let count = stream.read(&mut buffer).map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("tcp read failed: {error}"),
)
})?;
buffer.truncate(count);
Ok(ResourceRead {
bytes: buffer,
eof: count == 0,
})
}
}
}
@@ -332,6 +362,13 @@ impl ResourceTable {
let mut provider = provider.lock().map_err(|_| provider_lock_error(span))?;
provider.write(*token, bytes, span)
}
Stream::Tcp { stream, .. } => stream.write(bytes).map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("tcp write failed: {error}"),
)
}),
}
}
@@ -363,6 +400,10 @@ impl ResourceTable {
provider.close(*token, span)?;
*closed = true;
}
Stream::Tcp { stream, closed } => {
let _ = stream.shutdown(std::net::Shutdown::Both);
*closed = true;
}
}
Ok(())
}
@@ -400,6 +441,7 @@ impl ResourceTable {
Stream::Stdout { .. } => "stdio".to_string(),
Stream::File { .. } | Stream::FileWriter { .. } => "file".to_string(),
Stream::Provider { kind, .. } => kind.clone(),
Stream::Tcp { .. } => "tcp".to_string(),
})
}
}
@@ -375,3 +375,82 @@ fn provider_registration_rejects_versions_reserved_names_and_conflicts() {
.unwrap_err();
assert_eq!(conflict.category, ErrorCategory::ResourceUnsupported);
}
#[test]
fn tcp_resource_round_trips_with_a_network_grant() {
use std::io::{Read, Write};
use std::net::TcpListener;
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let server = std::thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
let mut buffer = [0u8; 4];
stream.read_exact(&mut buffer).unwrap();
stream.write_all(&buffer).unwrap();
});
let dir = tempfile::tempdir().unwrap();
let mut host = StdHost::new(
SandboxMode::Project,
Capabilities::project().allow_net("127.0.0.1"),
dir.path(),
);
let ctx = context();
let handle = handle(
host.resource_open(
"tcp",
&address.to_string(),
&["read".to_string(), "write".to_string()],
&ctx,
)
.unwrap(),
);
assert_eq!(host.resource_write(handle, b"ping", &ctx).unwrap(), 4);
let read = host.resource_read(handle, 4, &ctx).unwrap();
assert_eq!(read.bytes, b"ping");
host.resource_close(handle, &ctx).unwrap();
server.join().unwrap();
}
#[test]
fn tcp_requires_network_grant_and_rejects_dns_names() {
let dir = tempfile::tempdir().unwrap();
let mut host = StdHost::new(SandboxMode::Project, Capabilities::project(), dir.path());
let ctx = context();
let denied = host
.resource_open(
"tcp",
"127.0.0.1:9",
&["read".to_string(), "write".to_string()],
&ctx,
)
.unwrap_err();
assert_eq!(denied.category, ErrorCategory::PermissionDenied);
let dns = host
.resource_open(
"tcp",
"example.test:80",
&["read".to_string(), "write".to_string()],
&ctx,
)
.unwrap_err();
assert_eq!(dns.category, ErrorCategory::ResourceUnsupported);
for mode in [SandboxMode::Pure, SandboxMode::Strict] {
let mut host = StdHost::new(
mode,
Capabilities::project().allow_net("127.0.0.1"),
dir.path(),
);
let error = host
.resource_open(
"tcp",
"127.0.0.1:9",
&["read".to_string(), "write".to_string()],
&ctx,
)
.unwrap_err();
assert_eq!(error.category, ErrorCategory::PermissionDenied);
}
}
+7 -1
View File
@@ -135,6 +135,9 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
PluginHandle `plugin/export` are read-only observation members (host id
private); `stdlib/format.mq.md` reproduces builtin `打印`/`repr` for all 15
value types, including Formula/Code/FunctionRef and Code UTF-8 byte length.
- Blocking TCP endpoint (P5 first slice, ADR-0034): project-mode
`resource.open("tcp", ip:port, ["read","write"])` with exact IP grant and
timeouts; no DNS/TLS/UDP/server sockets; strict/pure refuse. CLI `--allow-net`.
- In-process ResourceProvider v1 (CM-A09 first slice, ADR-0033): trusted
providers register additional resource kinds without parser/runtime/HostOp
changes; project-mode + name grant required; pure/strict refuse provider
@@ -195,7 +198,7 @@ behavior. This table records only what is in this tree now.
| P2 Marqdo-written allocator/data structures + minimal structure observation | **PARTIAL, gate NOT passed** | `.mq.md`-only evidence: bump allocator with u32 codec, linked list, failed-allocation atomicity (48–50); CM-A04 structure primitives and a table filter (51–54, ADR-0023); a first-fit free-list allocator with block reuse, splitting, address-adjacent coalescing and `Result` maps (55, ADR-0024), a `Memory`-backed binary tree with recursive insert/in-order traversal (56), a `.mq.md` CSV row splitter (57), an open-addressing hash table with linear probing, update and `hash.full` (58), a `.mq.md` UTF-8 encoder over `Memory` (59), a validating UTF-8 decoder rejecting truncated, bad-continuation and surrogate/overlong input (60), a `Memory`-backed graph adjacency list (61), a recursive JSON parser for nested arrays/objects, strings with escapes, integers, booleans, null and error Results (62), a `Memory`-backed stack bytecode VM with PUSH/ADD/MUL/JMP/JZ/HALT (63), big-endian 16/32/64-bit plus LEB128 integer codecs (64), a `.mq.md` table sort rebuilding a new table from `table.row/columns/cell` (65), a table join (67), a quoted/escaped CSV row parser (68), table group (69), and an Int matrix multiply (70); the first-fit allocator also detects double free (`alloc.double_free`). Evidence: [`memory-p2-closure`](evidence/2026-11-20-memory-p2-closure.md), [`structure-api-p2`](evidence/2026-11-20-structure-api-p2.md), [`result-and-free-list-p2`](evidence/2026-11-20-result-and-free-list-p2.md). P2 remaining: publication as a separate external stdlib repository. The bundled `stdlib/` tree, `std:` imports, digest verification, Analysis identity and frozen-CLI closure test are implemented (ADR-0028). C01–C06/C11/C12 each have `.mq.md` evidence, including JSON floats and a JSON formatter. |
| P3 Resource/Stream ABI | **PARTIAL** | ADR-0025/0026 CM-A06 slices: opaque `Resource`, `resource.open/read/write/close`, stdout write in pure/project, granted project-file read and buffered project-file write in project, EOF/closed/handle errors, wire/host rejection; strict permits only stdio/stdout and refuses file/network resources. Fixture 66 + CLI/host tests. CM-A07 **Compat-C** is implemented: when a program calls `打印/print`, the loader injects the bundled `stdlib/io.mq.md` and the runtime routes to `io.写值` (all 15 value types, UTF-8 via `Memory`, `resource.write(stdout)`); `HostOp::Print` and the legacy `Value::display()` print path are removed, and a missing bundle fails with `kernel.unavailable`. Strict permits only the existing stdio console channel. Still missing: directories, network, generic provider registry, Table storage, strict file/network resources. |
| P4 Table logical/physical migration | **PARTIAL** | ADR-0032/CM-A08: `Value::Table` logical semantics unchanged (T0 `Vec<Vec<Value>>`); `stdlib/data/table.mq.md` provides select/filter/sort/append/set/join/group as value-returning `.mq.md` functions with input immutability. No T1/T2/T3 physical storage, column store or Memory-backed table. |
| P5 third-party Provider / TCP / HTTP | **PARTIAL** | ADR-0033 in-process `ResourceProvider` v1: explicitly trusted providers register by kind, project-mode only, gated by `Capabilities.allow_resource_provider`, using the existing `resource.*`/`Result` ABI; a mock read/write provider is tested. No C/Worker provider transport, network/socket/TCP/HTTP, clock/random/process/device providers, or provider package installation. |
| P5 third-party Provider / TCP / HTTP | **PARTIAL** | ADR-0034 blocking TCP resource endpoint (`resource.open("tcp", "<ip>:<port>", ["read","write"])`, exact IP grant, project-only, 5s timeouts; loopback host+CLI tests). ADR-0033 in-process `ResourceProvider` v1: explicitly trusted providers register by kind, project-mode only, gated by `Capabilities.allow_resource_provider`, using the existing `resource.*`/`Result` ABI; a mock read/write provider is tested. No C/Worker provider transport, DNS/TLS/HTTP framing, UDP, clock/random/process/device providers, or provider package installation. |
| P6 performance / native backends | **NOT IMPLEMENTED** | no bytecode/JIT/GPU/QPU work |
The P1 memory domain is pure computation: it needs no grant and is available in
@@ -236,6 +239,9 @@ user-written allocator is explicitly **not** claimed.
- [`evidence/2026-11-20-provider-abi-cm-a09.md`](evidence/2026-11-20-provider-abi-cm-a09.md)
— ADR-0033 in-process ResourceProvider v1, grants/mode checks, mock provider
read/write and registration rejection cases.
- [`evidence/2026-11-20-tcp-endpoint.md`](evidence/2026-11-20-tcp-endpoint.md)
— ADR-0034 blocking TCP endpoint, IP grants, DNS refusal, loopback host/CLI
echo tests.
- [`evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md`](evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md)
— G0..G12 matrix and RC decision.
- [`security-gate.md`](security-gate.md) — mechanism, attack matrix and strict
+84
View File
@@ -0,0 +1,84 @@
# 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
```text
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 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.
+1
View File
@@ -30,6 +30,7 @@ implementation status lives in `docs/STATUS.md`; frozen behavior is in
| CM-A07 Compat-C remove legacy print formatting | [0031](../adr/0031-print-compat-c-remove-host-formatting.md) | Accepted |
| CM-A08 table logical value / stdlib algorithms / T0 storage | [0032](../adr/0032-table-logical-value-and-stdlib-algorithms.md) | Accepted |
| CM-A09 in-process ResourceProvider v1 | [0033](../adr/0033-in-process-resource-provider-v1.md) | Accepted (trusted in-process slice) |
| P5 blocking TCP resource endpoint v1 | [0034](../adr/0034-tcp-resource-endpoint.md) | Accepted (IP-literal, no DNS/TLS) |
| Table physical storage (T1/T2/T3), C/Worker provider transport, strict file/network resources | — | Not decided; do not implement by implication |
## What a future phase must not do
+78
View File
@@ -0,0 +1,78 @@
# 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](../adr/0034-tcp-resource-endpoint.md)
Related: [provider v1](2026-11-20-provider-abi-cm-a09.md), [STATUS §5](../STATUS.md).
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.
```text
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
```text
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):
```text
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`):
```text
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
```bash
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
```
+3 -3
View File
@@ -27,8 +27,8 @@ Normative implementation:
| Mode | Intended guarantee | Actual status in this build |
|---|---|---|
| `pure` | No external I/O; memory computation and budgets only. | **Enforced.** `Capabilities::pure()` = `console`, `math` only; every FS/foreign/plugin grant flag makes the CLI exit 2 with "pure mode prohibits external I/O grants". |
| `project` | Operator-approved project resources under `CapabilityHost` + bounded resources. | **Enforced for the implemented operations.** Defaults equal `pure`; `--allow-read`, `--allow-write`, `--allow-foreign`, `--allow-plugin` add grants. `resource.open` supports stdout write, granted project-file read/write (ADR-0025/0026) and granted in-process provider kinds (ADR-0033); network/process remain unsupported. Sandboxing is cooperative (in-process checks), not OS isolation; in-process providers are trusted, not sandboxed. |
| `strict` | Untrusted documents under real OS isolation. | **Linux: enforced when the runtime probe passes (ADR-0021).** `resource.open` is **refused** in strict except for the existing `stdio/stdout` console channel (console grant); file/network/process resources remain refused until a provider passes the isolation lane (CM-A11, ADR-0030). `PlatformCapabilities::detect()` runs a real Bubblewrap smoke test; success reports `Available { mechanism }`, failure reports `Unavailable { reason }`. Strict L1 supports the interpreter, console, native Math and the read-only bundled stdlib (published at `/run/marqdo-stdlib` for the Compat-C print chain); `--allow-read/--allow-write/--allow-foreign/--allow-plugin/--plugin/--trust-native-plugin/--kernel/--trace-file` are rejected with exit 2. macOS/Windows and Linux hosts without the mechanisms remain `Unavailable`; there is **no fallback** to an unrestricted process. |
| `project` | Operator-approved project resources under `CapabilityHost` + bounded resources. | **Enforced for the implemented operations.** Defaults equal `pure`; `--allow-read`, `--allow-write`, `--allow-foreign`, `--allow-plugin` add grants. `resource.open` supports stdout write, granted project-file read/write (ADR-0025/0026), granted in-process provider kinds (ADR-0033) and granted IP-literal TCP streams (ADR-0034); process/device remain unsupported. Sandboxing is cooperative (in-process checks), not OS isolation; in-process providers are trusted, not sandboxed. |
| `strict` | Untrusted documents under real OS isolation. | **Linux: enforced when the runtime probe passes (ADR-0021).** `resource.open` is **refused** in strict except for the existing `stdio/stdout` console channel (console grant); file/TCP/provider/process resources remain refused until a provider passes the isolation lane (CM-A11, ADR-0030/0034). `PlatformCapabilities::detect()` runs a real Bubblewrap smoke test; success reports `Available { mechanism }`, failure reports `Unavailable { reason }`. Strict L1 supports the interpreter, console, native Math and the read-only bundled stdlib (published at `/run/marqdo-stdlib` for the Compat-C print chain); `--allow-read/--allow-write/--allow-foreign/--allow-plugin/--plugin/--trust-native-plugin/--kernel/--trace-file` are rejected with exit 2. macOS/Windows and Linux hosts without the mechanisms remain `Unavailable`; there is **no fallback** to an unrestricted process. |
`marqdo inspect <file> --platform` prints the detection report, for example:
@@ -59,7 +59,7 @@ set for one run:
| `math: bool` | `true` | `math.*` host ops |
| `fs_read: Vec<String>` | empty | `fs.read` and project `resource.open("file", path, ["read"])` |
| `fs_write: Vec<String>` | empty | `fs.write` and project `resource.open("file", path, ["write"])` |
| `net_hosts: Vec<String>` | empty | `Capabilities::check_net` exists, but no host op or builtin performs network access in this build |
| `net_hosts: Vec<String>` | empty | exact IP-literal grants for `resource.open("tcp", "<ip>:<port>", ["read","write"])`; DNS is not resolved; `--allow-net <IP>` adds a grant (ADR-0034) |
| `process: bool` | `false` | required together with `foreign` for `foreign.run`/`foreign.call` |
| `foreign: bool` | `false` | foreign kernels |
| `plugins: Vec<String>` | empty | `plugin.invoke` and `StdHost::load_plugin` |
+6
View File
@@ -171,6 +171,12 @@ by:
* fixture 55 additionally has a second-free detection path: freeing an
already-free block returns `{ok:false, code:"alloc.double_free"}`.
P5 TCP endpoint v1 (ADR-0034) is pinned by two host tests in
`crates/marqdo-host/tests/resource_streams.rs` (loopback echo with a grant;
grant/pure/strict/DNS refusal) and
`crates/cli/tests/resource_streams.rs::tcp_stream_round_trips_through_mqmd_with_a_network_grant`
(`--allow-net 127.0.0.1`).
RFC-CM CM-A09 in-process provider v1 (ADR-0033) is pinned by the three
`registered_provider_streams_*` / `provider_*` tests in
`crates/marqdo-host/tests/resource_streams.rs`: a mock provider is registered