`net`

net 让 guest 通过平台代理发起受 manifest 限制的请求—响应。guest 不获得浏览器 fetch、socket、DNS、真实连接、代理凭据或任意重定向权。

基本示例

const response = await host.net.fetch({
  url: 'https://api.example.com/v1/catalog',
  method: 'GET',
  headers: { accept: 'application/json' },
});

if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
const catalog = JSON.parse(new TextDecoder().decode(response.body));

和浏览器 Fetch 一样，HTTP 404/500 是正常响应状态，不自动变成 HostError；代理失败、策略拒绝和预算失败才抛 HostError。

适用场景

调用应用在 manifest 中公开声明的 HTTPS API。
获取有明确大小上限的 JSON 或二进制响应。
由平台代理持有服务凭据、执行目的地校验和审计。

WebSocket、WebTransport、WebRTC、P2P、局域网发现、任意 TCP/UDP 和无限流不在 v0.1。

manifest 与能力声明

{
  "capabilities": ["host:net.fetch"],
  "network": {
    "hosts": ["api.example.com"],
    "methods": ["GET", "POST"]
  }
}

宿主在发布时验证声明，在每次调用和每次重定向时重新执行；不能只检查字符串前缀。

Reference

net.fetch()

net.fetch(request, cancellation?) -> NetResponse

NetRequest {
  url: bounded-https-url
  method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE"
  headers?: HeaderMap
  body?: ByteSource
  timeoutMs?: u32
}

NetResponse {
  status: u16
  headers: HeaderMap
  body: Bytes
  finalUrl?: bounded-https-url
}

方法、请求头和响应头均为 v0.1 白名单。Cookie、Authorization、代理头、连接控制头和会泄露底层网络的信息不允许由 guest 自由设置或读取。

POST 与取消示例

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 5_000);

try {
  const response = await host.net.fetch({
    url: 'https://api.example.com/v1/items',
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: new TextEncoder().encode(JSON.stringify({ name: 'demo' })),
    timeoutMs: 5_000,
  }, controller.signal);
  handleResponse(response);
} finally {
  clearTimeout(timeout);
}

取消表示 guest 不再需要结果；宿主应尽快停止上游请求，但不能承诺远端服务器没有处理已发送的数据。

原生 WASM 示例

NetRequest request = {
  .url = "https://api.example.com/v1/catalog",
  .method = NET_GET,
  .headers = accept_json_headers(),
};
NetResponse response = host_net_fetch(request, byte_sink(body, sizeof(body)), cancel_token);
if (response.status == 200) decode_catalog(body, response.written);

原生绑定的大响应必须显式返回 required 或未来的流句柄；绝不能截断正文却保留 200 状态。

重定向与身份

默认不跟随重定向；启用时只允许有限次数，并逐跳验证 HTTPS、host 和方法变化。
平台凭据由宿主按固定服务配置附加，不返回 guest。
Set-Cookie 不建立 guest 可观察的浏览器 cookie jar。
URL 用户名/密码、IP 字面量、非标准端口和 DNS 重绑定风险按平台策略拒绝。

安全与预算

信任档位：lime；peer 为 manifest 声明的 third-party，mediation 为 brokered。
预算覆盖 URL/头长度、请求体、响应体、超时、重定向数、并发数和时间窗字节。
响应头只返回白名单；移除网络拓扑、代理实现和身份凭据。
日志只记录受限目的地和统计信息，不记录正文或秘密请求头。
宿主必须防止 SSRF，包括解析后的地址类别检查和重定向再校验。

错误与测试

特有错误包括 destination-denied、invalid-request、timeout、cancelled、response-too-large、redirect-denied 和 upstream-unavailable。一致性测试至少覆盖 host 混淆、Unicode 域名、重定向绕过、DNS 重绑定、头过滤、404 正常返回、取消竞态和响应上限。