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:
1 parent
1d87f98539
commit
00bdcad1ff
15 files changed
+435
-4
No files matched your search
@@ -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
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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();
|
||||
}
|
||||
|
||||
@@ -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(),
|
||||
|
||||
@@ -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");
|
||||
|
||||
@@ -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());
|
||||
|
||||
@@ -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(
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
@@ -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` |
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user