#BinSchema

用一份可组合的 Codec[T] 同时定义安全解码与编码，并让每个字节都可解释。

#特性

• 安全默认值：64 MiB 核心输入/输出限制、集合长度上限、嵌套深度上限和严格 EOF 检查。
• 双向定义：同一 Codec[T] 同时负责解码和编码，便于验证 encode(decode(bytes)) == bytes。
• 可诊断错误：错误包含分类、绝对字节偏移、字段路径和稳定的可读消息。
• 结构追踪：.named() 记录字段的 [start, end)、类型和值预览，可直接驱动可视化界面。
• Schema 与静态检查：每个 Codec[T] 都能导出结构树，并通过 lint() 检查缺失的局部上限、动态分支和区域吞噬等协议风险。
• 规范变长整数：内置安全的 uleb128() 与 sleb128()，拒绝截断、溢出、超长和非最短编码。
• 高级组合：提供 count_prefixed、until_eof 与 tagged，覆盖计数数组、流式尾读和标签联合。
• 零拷贝解码：decode_view、bytes_view_fixed、remaining_view 与 checksum_suffix_view 可直接借用 BytesView，有需要时再显式转成拥有型 Bytes。
• 缓冲式增量帧解析：decode_prefix、probe_decode 与 IncrementalDecoder 支持分块输入、NeedMore 判定和多 frame 尾部保留；它是 buffered/retry framing，而不是 continuation-based parser。
• 跨后端验证：Wasm、Wasm-GC、JavaScript、Native 四后端使用同一套测试。
• 结构化安全回归：从真实格式的 Schema/Trace 派生确定性 mutation，覆盖截断、长度膨胀、CRC 损坏和字段边界翻转。
• 真实格式校验：检查 PNG CRC 与块顺序、WAVE RIFF 结构、PCAP 字节序/长度/时间戳、ISO BMFF box 长度与扩展头，DNS section count、label 长度和压缩指针边界/方向/深度，以及 ELF32/64、端序、header table 范围、扩展 section numbering 与 section-name string table。

#快速开始

moon add prowk/binschema

import {
  "prowk/binschema" @bin,
}

import {
  "prowk/binschema/formats" @formats,
}

///|
test "README quick start" {
  let packet = @binschema.pair(
    @binschema.magic(b"BS").named("magic"),
    @binschema.pair(
      @binschema.u8().named("version"),
      @binschema.uleb128().named("stream_id"),
    ),
  )
  let value = ((), (1U, 624485UL))
  let bytes = match @binschema.encode(packet, value) {
    Err(error) => fail(error.render())
    Ok(bytes) => bytes
  }
  match @binschema.decode(packet, bytes) {
    Err(error) => fail(error.render())
    Ok(decoded) => {
      assert_eq(decoded.value, value)
      assert_eq(decoded.trace.length(), 3)
      assert_true(packet.describe().contains("stream_id"))
      assert_eq(packet.lint().length(), 0)
    }
  }
}

#增量 / 流式输入

///|
test "README incremental decode" {
  let codec = @binschema.pair(@binschema.u16_be(), @binschema.u8())
  let stream = @binschema.IncrementalDecoder::new(codec)
  assert_true(stream.feed(b"\x12") is @binschema.NeedMore)
  match stream.feed(b"\x34\x56\xaa") {
    @binschema.Done(decoded) => assert_eq(decoded.value, (0x1234U, 0x56U))
    _ => fail("expected one complete frame")
  }
  assert_eq(stream.buffered_bytes(), 1)
}

#可复现的自定义协议示例

magic "BS" | version u8 | stream_id uleb128 | sequence u16_le

moon update
moon run --target native examples/custom_packet

encoded: 42 53 01 e5 8e 26 07 00
stream_id: 624485
trace fields: 4

moon run --target native examples/demo_protocol

#CLI

moon run --target native cmd/main -- inspect image.png
moon run --target native cmd/main -- inspect capture.pcap --json
moon run --target native cmd/main -- verify audio.wav
moon run --target native cmd/main -- sample png sample.png
moon run --target native cmd/main -- sample bmff sample.mp4
moon run --target native cmd/main -- sample dns sample.dns
moon run --target native cmd/main -- sample elf sample.elf
moon run --target native cmd/main -- lint png
moon run --target native cmd/main -- lint pcap --json
moon run --target native cmd/main -- inspect sample.mp4 --format bmff
moon run --target native cmd/main -- inspect sample.dns --format dns
moon run --target native cmd/main -- inspect sample.elf
moon run --target native cmd/main -- formats

#真实格式支持边界

• PNG：signature、chunk 结构/顺序、CRC、核心 IHDR 合法性；不宣称实现全部图像语义。
• WAVE：RIFF 长度、chunk/padding、fmt / data 基础一致性；不解码音频 payload。
• PCAP：全局头、端序、packet 长度、时间戳范围和 snapshot 约束。
• ISO BMFF：box header、32/64-bit size、size=0、uuid 与未知 payload 保留；不解析完整媒体语义。
• DNS：header/question/RR framing 与安全 compression pointer；RDATA 目前保持 raw bytes。
• ELF：ELF32/64 header、端序、program/section table 范围、扩展 section numbering 和 section names；不解析 symbols、relocations、DWARF 或动态链接语义。

#Web / Wasm-GC 检查器

moon build --target wasm-gc web/bridge --release
cp _build/wasm-gc/release/build/web/bridge/bridge.wasm web/binschema.wasm
python -m http.server 4173 --directory web

Copy-Item _build/wasm-gc/release/build/web/bridge/bridge.wasm web/binschema.wasm

#仓库结构

├─ codec.mbt / decoder.mbt / encoder.mbt  # 安全组合子核心
├─ schema.mbt / lint.mbt                  # Schema 元数据与静态检查
├─ primitives.mbt / varint.mbt            # 定长与变长基础类型
├─ formats/                               # ELF / PNG / WAVE / PCAP / ISO BMFF / DNS
├─ cmd/main/                              # 原生 CLI
├─ web/                                   # Wasm-GC 桥接与浏览器检查器
├─ examples/custom_packet/                # 最小自定义协议示例
├─ examples/demo_protocol/                # 更完整的真实协议示例
└─ docs/                                  # 架构和安全模型

#开发与验收

moon update
moon info
moon fmt --check
moon check --target all --deny-warn
moon test --target all --deny-warn
moon test README.mbt.md --target native --deny-warn
moon bench --build-only --target native --deny-warn
moon test --target native --enable-coverage --deny-warn
moon coverage analyze
moon build --target native cmd/main --release
moon build --target native examples/custom_packet --release
moon build --target native examples/demo_protocol --release
moon build --target wasm-gc web/bridge --release
cmp README.md README.mbt.md

#License