MerlijnW70/jsonfort

# jsonfort

**一个经过强化的、零依赖、支持 `no_std` 的 JSON 拉式解析器，可以安全地用于处理您不信任的字节。** 它绝不会发生 panic、越界读取、过度分配内存，或在处理恶意输入时卡死 —— 每个格式错误的文档都会返回一个类型化的错误，而绝不会崩溃。 ## 为什么需要 代理和服务会接收到并非由它们自己编写的 JSON —— 工具调用参数、模型输出、RPC 负载。一个可能会 panic、无限制分配内存，或者在处理深度嵌套文档时导致栈溢出的解析器，无疑是一个随时可能触发的可用性 Bug。`jsonfort` 的设计初衷就是直接处理这种不受信任的数据流： - ✅ **绝不会 panic / 越界读取 / 过度分配内存 / 卡死** —— 无论输入什么内容，这一点已通过数百万输入的确定性模糊测试工具得到证明，且每次访问都是失败即关闭的（fail-closed）`slice::get`。 - ✅ **非递归** —— 嵌套深度通过 `u128` 深度位集进行跟踪，因此对于深度嵌套的输入，会以 `DepthExceeded` 错误安全关闭，而不是导致调用栈溢出（这是一种反 DoS 特性，而非偶然）。 - ✅ **零分配、零拷贝** —— 字符串和数字值都是直接从输入缓冲区中*借用*（borrowed）的 `&str` 切片。解析器仅持有几个字长的状态，不包含任何其他内存分配。 - ✅ **零依赖** · `#![no_std]` · `#![forbid(unsafe_code)]`。 ## 快速开始 ``` use jsonfort::{Parser, Event}; let mut p = Parser::new(br#"{"tool":"web_search","n":2}"#); assert_eq!(p.next_event().unwrap(), Some(Event::BeginObject)); assert_eq!(p.next_event().unwrap(), Some(Event::Key("tool"))); assert_eq!(p.next_event().unwrap(), Some(Event::Str("web_search"))); assert_eq!(p.next_event().unwrap(), Some(Event::Key("n"))); assert_eq!(p.next_event().unwrap(), Some(Event::Number("2"))); assert_eq!(p.next_event().unwrap(), Some(Event::EndObject)); assert_eq!(p.next_event().unwrap(), None); // clean end ``` 或者仅仅检查不受信任的字节是否为格式良好的 JSON，且不进行内存分配： ``` if jsonfort::validate(untrusted).is_ok() { // it parses; now walk it with Parser to extract what you need } ``` `Parser` 还实现了 `Iterator`，并且它是**可融合的**（fuses）：在发生第一次错误后，它会先产生相应的事件，接着返回那一个 `Err`，然后就会停止 —— 对格式错误的文档进行迭代绝不会陷入死循环。 ## 安装 ``` [dependencies] jsonfort = "0.1" ``` ## 借用的字符串包含什么内容 `Event::Str` / `Event::Key` 借用的是引号之间的**原始**字节 —— 这些字节已通过 UTF-8 验证，且每个转义符都经过了格式良好性检查，但**并未被反转义**。`"a\nb"` 会作为 `a \ n b` 这四个字节返回；解码转义符需要一个由调用者拥有的缓冲区，这超出了零内存分配核心的设计范围。因为字符串永远不会被解码，所以 `\u` 转义符**仅会验证是否包含四个十六进制数字 —— 而不会验证代理项对**（单独的 `\uD800` 会被接受）。数字以原始且语法有效的切片形式返回；如果您想要 `i64`/`f64`，请对它们使用 `str::parse`。 ## 关于测试声明 `jsonfort` 遵守 **100% 的行为变异覆盖率**（0 个存活突变）—— 每个比较/布尔/算术运算符和分支都会发生变异，并且测试套件会重新运行，因此不会有未经测试的分支存活。因为变异测试无法触及*字面量或精确的边界*，所以控制字符阈值、转义集、空白符集和数字语法都由显式的边界测试来锁定，并且一个确定性的模糊测试/属性测试工具断言了在数百万输入中绝不会发生 panic 以及往返（round-trip）属性。绿色的构建意味着被测试的行为得到了真正的锁定 —— 但这并不意味着“已被证明没有 Bug”。 ## 许可证 MIT。

标签：JSON解析器, no_std, Rust, 可视化界面, 底层开发, 网络流量审计, 通知系统, 防拒绝服务, 零拷贝, 高可用性