#MoonVCR

• 无 IO 核心：数据模型、确定性匹配、Record/Replay/StrictOffline 会话、脱敏、诊断和响应契约，可在 wasm 环境运行；
• native 适配层：基于官方 moonbitlang/async 的真实 HTTP 客户端和 cassette 文件读写，当前由 Ubuntu GitHub CI 验证。

#当前状态

• 当前源码修复版本：0.3.2；发布状态与对应 SHA/CI 证据见 FINAL_ACCEPTANCE.md；
• 0.3.1 及更早版本存在已确认的脱敏绕过或错误匹配，不能依据旧 CI 全绿认定安全；请升级并审阅重录旧档案；
• 0.3.2 对独立审核发现的七类问题补充修复，包括精确 JSON 路径、重复参数顺序、native 头信息、有界文件读取和诊断一致性；逐项说明见 AUDIT_REMEDIATION_0.3.2.md，兼容行为见 MIGRATION.md。

#已实现能力

• 版本化 Request、Response、Interaction 和 Cassette 模型；
• 确定性 JSON 编解码，拒绝损坏 JSON、错误结构和未知格式版本；
• 方法、URL/query、选定 header 和 body 的确定性匹配；
• 无分隔符歧义的长度编码匹配键，以及重复交互按顺序消费；
• Record、Replay、StrictOffline 会话，剩余交互计数和完整消费断言；
• URL 用户信息、fragment、百分号编码敏感参数、常见敏感 header/query 脱敏；
• 请求与响应独立的必填/可选 JSON 路径脱敏，失败时不写入 cassette；
• 不直接回显请求/响应值的 replay miss 与 mismatch；契约报告包含配置的规则和字段路径，不应在这些名称中配置凭据；
• 状态码、header 存在性/精确值、body 类型、必填/可选 JSON 字段和数组元素契约；
• native 真实 HTTP GET/POST、header、JSON、二进制 body、连接失败和超时转换；
• native cassette 大小限制、默认禁止覆盖、显式替换、同目录临时文件和同步写入；
• 分页 SDK、订单兼容性、受限网络 CI 三组成功与故障场景；
• 100、1,000、10,000 条交互的确定性容量验收。

#安装

moon add chenqi-arch/moonbit-project@0.3.2

#核心快速开始

import {
  "chenqi-arch/moonbit-project" @moonvcr,
}

pkgtype(kind: "executable")

fn main {
  let cassette_text = @moonvcr.Cassette::encode(@moonvcr.example_cassette())
  let cassette = @moonvcr.Cassette::decode(cassette_text) catch {
    _ => abort("cassette decode failed")
  }
  let request : @moonvcr.Request = {
    method: "GET",
    url: "https://api.example.test/v1/items?page=1",
    headers: [{ name: "accept", value: "application/json", }],
    body: @moonvcr.Empty,
  }
  let session = @moonvcr.Session::with_defaults(
    cassette,
    @moonvcr.StrictOffline,
  )
  let response = match session.replay(request) {
    Ok(response) => response
    Err(error) => abort(error.summary())
  }
  guard response.status == 200 else { abort("unexpected status") }
  match session.assert_complete() {
    Ok(_) => ()
    Err(error) => abort(error.summary())
  }
  println("offline consumer passed status=200")
}

#显式录制与脱敏

let request_rules = RedactionConfig::default()
request_rules.json_paths.push("/credentials/token")
let response_rules = RedactionConfig::default()
response_rules.optional_json_paths.push("/session/token")

let session = Session::new_with_redaction_policy(
  Cassette::empty(),
  Record,
  MatchConfig::default(),
  { request: request_rules, response: response_rules, },
)
let result = session.record_response(request, response)
let text = session.cassette().encode()

#响应契约

let contract : ResponseContract = {
  allowed_statuses: [200, 201],
  required_headers: ["content-type"],
  required_header_values: [
    { name: "content-type", expected_value: "application/json", },
  ],
  body_kind: Some(ExpectTextBody),
  json_fields: [{ path: "/id", expected_kind: JsonNumber, }],
  optional_json_fields: [{ path: "/note", expected_kind: JsonString, }],
  json_array_elements: [{ path: "/items", expected_kind: JsonObject, }],
}
let report = response.validate_contract(contract)
guard report.is_valid() else { abort(report.summary()) }

#Native HTTP 与文件档案

let response = @native.send_http_with_timeout(request, 2_000)
let recorded = @native.record_http(session, request, timeout_millis=2_000)
@native.save_cassette_new("fixtures/orders.json", session.cassette())
let cassette = @native.load_cassette_default("fixtures/orders.json")

• 超时、连接/协议失败、非法方法和非法 body 被转换为不含 URL/凭据的安全错误；
• 非 2xx 和 3xx 原样返回给业务契约判断；
• TLS 证书验证使用官方客户端默认值，没有“关闭证书验证”选项；
• 不承诺自动跟随重定向，验收固定检查 302 保持为 302；
• native 底层头部 Map 无法无损发送重复请求头，因此同名请求头（大小写不敏感）会在发网前返回 UnsupportedDuplicateHeaders，不能静默覆盖；
• 原始业务响应保留各个 Set-Cookie 及公开解析属性；按依赖解析结果规范化重建，不保证 HTTP 字节拼写。录制副本才按规则逐条脱敏；
• save_cassette_new 默认拒绝覆盖，save_cassette_replace 才允许显式替换；
• 默认加载上限为 10 MB，同一打开句柄最多读取上限加一字节，在 UTF-8/JSON 解码前拒绝超限；文件增长/路径替换不绕过读取预算。TooLarge(n) 的 n 是观察到的字节数下界，不是完整文件大小。

#可运行场景

moon run cmd/moonvcr-pagination
moon run cmd/moonvcr-order-contract
moon run cmd/moonvcr-restricted-ci

pagination SDK offline regression passed pages=2
order compatibility contract passed status headers JSON array optional-field
restricted-network CI passed network_calls=0

moon run cmd/moonvcr-pagination-failure
moon run cmd/moonvcr-order-contract-failure
moon run cmd/moonvcr-restricted-ci-failure

#验收命令

moon fmt --check
moon check
moon build
moon test
moon run cmd/moonvcr-demo
moon run cmd/moonvcr-pagination
moon run cmd/moonvcr-order-contract
moon run cmd/moonvcr-restricted-ci
moon run cmd/moonvcr-security-acceptance
moon package --list

#支持矩阵

#主要 API

• Cassette::empty/decode/encode
• MatchConfig::default
• RedactionConfig::default、RedactionPolicy::default/symmetric
• Session::with_defaults/new/new_with_redaction/new_with_redaction_policy
• Session::send/record_response/replay/diagnose/cassette
• Session::remaining_interactions/assert_complete
• Response::validate_contract、ContractReport::is_valid/summary
• ScriptedTransport::new/send/remaining
• native：send_http/send_http_with_timeout/record_http
• native：load_cassette/load_cassette_default/save_cassette_new/save_cassette_replace

#故障排查

• ReplayMiss：调用 session.diagnose(request)；检查 URL/query、选定 header、body 策略和重复调用次数；
• IncompleteReplay：有录制交互未被业务流程消费；
• RedactionFailed：必填 JSON 路径缺失、路径无效或 body 不是 JSON；
• HTTP request timed out：增大明确期限或排查服务延迟；
• cassette JSON decode failed：检查文件是否截断、结构和格式版本；
• native 构建提示无 C 编译器：安装受支持的 C 工具链，或使用 Ubuntu CI 验收。

#边界与限制

• 不做 TLS MITM、系统代理、浏览器录制或任意进程流量拦截；
• 不自动发现所有业务敏感字段；
• native HTTP 当前使用依赖的完整响应 API，没有响应字节数硬上限；只应对可信、大小受控的服务录制，cassette 文件上限不约束网络响应大小；
• Cassette::encode、文件保存和手工构造的 Request/Response 不是自动脱敏入口；应通过 Record 会话录制、审阅副本后保存，不能直接序列化原始数据；
• 不实现完整 OpenAPI/JSON Schema；
• cassette 默认加载上限 10 MB，容量验收覆盖到 10,000 条，不承诺无限规模；
• matcher 为确定性线性候选扫描，大 cassette 应按服务或测试套件拆分；
• 并发共享同一个可变 Session 不在当前保证范围内；
• moonbitlang/async API 仍可能变化，依赖版本被固定并由 CI 验证。

#开源与安全