harness

Cratefield Harness 是 Cratefield 背后的开源 MIT 许可核心，是一个可用于编译自定义后端的 Rust 后端框架。其核心前提是：每个产品都需要后端，且几乎没有必要从零开始构建，因此该框架旨在提供一次性的通用后端方案。用户只需选择模块 crate、连接适配器，即可交付一个带有独立数据库的无状态 Worker。 组合模型：一个项目（venture）通过 Harness 构建器声明项目身份、公共 URL 和 CORS 来源，添加模块，并选择包含数据库绑定、邮件发送器和验证码提供商的运行时。构建过程会拒绝以下情况：模块所需的端口运行时无法提供、两个模块声明相同的表或路由，或模块基于不同的合约版本构建。项目模板在 cargo test 下运行组合过程，确保配置错误在部署前被拦截。 模块与端口：模块是实现了 Module trait 的 crate，根据模块名称挂载在版本化路径下。它声明名称、所需端口、迁移脚本（通过 include_str! 嵌入 SQL，且仅使用 SQLite 和 Postgres 共同支持的子集）以及 axum 路由器。模块绝不直接接触供应商绑定、环境变量或供应商客户端，而是请求 Database、Mailer、Captcha、RateLimiter、Signer 和 KeyValue 等端口，由适配器提供响应。根据 README，这一规则使得迁移出 Cloudflare 仅需更改一个运行时 crate。 包含的 crates：cratefield 门面；cratefield-core（包含 Module trait、Harness 构建器、端口 trait、problem+json 错误、请求作用域、事件总线和模板）；cratefield-runtime-cloudflare；Resend 邮件、Turnstile 验证码和通过 rusqlite 实现的 SQLite 适配器；email-signup 模块（支持双重确认、取消订阅和管理员导出）和 waitlist 模块（支持确认、排队位置和推荐码）；cratefield-secrets（通过 Database 端口实现信封加密密钥）；cratefield-kms（用于封装和解封数据密钥，包含一个拒绝在生产环境使用的本地文件提供程序）；cratefield-ui（在 /ui 将模块界面渲染为 HTML）；cratefield-cli（提供包含 migrations collect、doctor 和 modules 命令的 fz 二进制文件）；以及每个模块必须通过的一致性测试套件 cratefield-testing。计划中的 crates 包括基于 sqlx 的 cratefield-adapter-postgres 和基于 tokio 的 cratefield-runtime-native。 迁移与请求：查询通过 sea-query 处理，因此可适配两种数据库。确认和取消订阅链接采用带密钥轮转的 HMAC 签名令牌，无需会话存储。请求作用域通过 axum 扩展而非共享状态传递，一致性测试套件包含对此的并发请求测试。 挂载：模块默认编译进 Worker 中，或作为 sidecar 运行（单独构建并部署 Worker，通过服务绑定在相同路径下挂载，共享数据库和密钥）。README 指出 sidecar 选项已设计但尚未构建。 可观测性：每个请求包含一个结构化 span，携带 request_id、method、route、module、status、duration_ms、ip_hash 和 ua_family，绝不包含电子邮件地址。模板 wrangler.toml 中启用了 Workers Logs，且响应中会回显 x-request-id。错误分类由核心注册表生成，并在 CI 中进行漂移检查。 仓库所述路线图：M0 基础（工作区工具、核心、Cloudflare 运行时、Resend 和 Turnstile 适配器、SQLite 适配器、fz、测试套件）；M1 首批模块；M2 首个项目上线，包括 crates.io 发布、文档和合约版本控制（标记为进行中）；M3 自托管可移植性，包括 Postgres 适配器、原生运行时、对等套件和数据迁移。另有三个史诗级任务已指定但尚未排期。 工具链与状态：rust-toolchain.toml 固定了 Stable Rust，目标平台为 wasm32-unknown-unknown，使用 worker-build 和 wrangler；CI 运行 fmt、clippy（禁止警告）、测试、cargo deny，并将示例项目构建为 wasm，以防止原生依赖潜入模块。这些 crates 尚未发布到 crates.io，因此 README 建议通过 git 依赖仓库。私有 crate 标记为 publish = false 而非存放在独立仓库。许可证：MIT。