diff --git a/.github/workflows/contract-dist.yml b/.github/workflows/contract-dist.yml index a85d06c..f5c69b1 100644 --- a/.github/workflows/contract-dist.yml +++ b/.github/workflows/contract-dist.yml @@ -27,7 +27,7 @@ jobs: node -e " const s = require('./contract/dist/envelope.schema.json'); const ec = require('./contract/dist/error-codes.json'); - if (ec.codes.length !== 13) throw new Error('13 码表异常'); + if (ec.codes.length !== 14) throw new Error('14 码表异常'); for (const c of ec.codes) { if (!(c.code > 0) || !c.key || !c.message || !(c.http >= 400)) throw new Error('三元组残缺: ' + JSON.stringify(c)); } diff --git a/.github/workflows/rust-stack.yml b/.github/workflows/rust-stack.yml new file mode 100644 index 0000000..db58a62 --- /dev/null +++ b/.github/workflows/rust-stack.yml @@ -0,0 +1,53 @@ +name: rust-stack + +# rust 栈 CI:四段门禁(fmt / clippy -D warnings / cargo-deny / test,spec 九-1)+ MSRV 双档(R7)。 +# 模板生成后冒烟(spec 九-3)待批次二模板落地后追加 job。 +# conformance 测试读仓内 contract/dist/error-codes.json(提交态在场,contract-dist 门拒漂移)。 + +on: + push: + branches: [main, dev] + paths: ['stacks/rust/**', '.github/workflows/rust-stack.yml'] + pull_request: + paths: ['stacks/rust/**', '.github/workflows/rust-stack.yml'] + +jobs: + check: + name: Rust ${{ matrix.toolchain }} · 四段门禁 + strategy: + fail-fast: false + matrix: + # R7:stable + MSRV 1.80 双档(dtolnay 动作以 RUSTUP_TOOLCHAIN 覆盖 rust-toolchain.toml) + toolchain: [stable, '1.80'] + runs-on: ubuntu-latest + # job 级 env 压过目录级 rust-toolchain.toml(1.95.0 本地档)——否则矩阵 toolchain + # 被覆盖、rustfmt/clippy 组件缺失即红(RUSTUP_TOOLCHAIN 优先级 > toolchain file) + env: + RUSTUP_TOOLCHAIN: ${{ matrix.toolchain }} + defaults: + run: + working-directory: stacks/rust + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@master + with: + toolchain: ${{ matrix.toolchain }} + components: rustfmt, clippy + - uses: Swatinem/rust-cache@v2 + with: + workspaces: stacks/rust/Cargo.toml + - run: cargo fmt --all -- --check + - run: cargo clippy --all-targets -- -D warnings + - run: cargo test --workspace + + deny: + name: cargo-deny · 依赖审计 + runs-on: ubuntu-latest + defaults: + run: + working-directory: stacks/rust + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + - uses: taiki-e/install-action@cargo-deny + - run: cargo deny check diff --git a/AGENTS.md b/AGENTS.md index 99949ff..c9a56ce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,12 +7,13 @@ | 目录 | 职责 | |---|---| -| `contract/` | 全域契约唯一权威:api(REST 四件套 + realtime / telemetry / audit)/ infra(22 份)/ web / clients / domains / agent + `registry.md` 命名登记处 | +| `contract/` | 全域契约唯一权威:api(REST 四件套 + realtime / telemetry / audit / captcha)/ infra(22 份)/ web / clients / domains / agent + `registry.md` 命名登记处 + `dist/` 机器可读派生层(JSON 由 api markdown 生成,漂移门盯防) | | `stacks/` | 云栈实现:java / golang / web / python(rust 规约已立待施工) | -| `clients/` | 端侧:android / ios / miniprogram / game + `create/` 客户端生成器 | +| `clients/` | 端侧:android / ios / miniprogram / game(desktop 预留)+ `create/` 客户端生成器 | | `embedded/esp32/` | 固件轨(esp-idf-hal std,规约已立待施工) | +| `tools/` | 模板定位器 `locate-scaffolds.cjs` 与将来的 `yarch init` CLI | | `docs/` | 架构与发展策划;`docs/references/` = 调研 digest(分析文体的合法归宿) | -| `.github/workflows/` | CI(含 template-smoke 生成器冒烟) | +| `.github/workflows/` | CI(含 template-smoke 生成器冒烟、contract-dist 漂移门) | ## 命令表 @@ -25,6 +26,7 @@ | android | `cd clients/android && ./gradlew test` | | ios | `cd clients/ios && swift test` | | 生成器冒烟 | `npm create @yarch/admin@latest` / `npm create @yarch/app@latest`(CI template-smoke 同款) | +| 契约 dist 重生成 | `node contract/dist/gen-dist.mjs`(改 `contract/api/*.md` 后必跑,否则 contract-dist CI 漂移门红) | ## 红线清单 diff --git a/README.md b/README.md index 9cd1379..d16dbc7 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ ## 从 0 到 1:一条命令生成工程 -四个栈同一套契约,全部**生成即合规**——统一信封 · 13 码错误码 · traceId 贯穿 · 分页(页码 D6 + keyset 游标)· 幂等 · 逻辑删除 · 机检预置,业务代码只写业务。 +四个栈同一套契约,全部**生成即合规**——统一信封 · 14 码错误码 · traceId 贯穿 · 分页(页码 D6 + keyset 游标)· 幂等 · 逻辑删除 · 机检预置,业务代码只写业务。 ### Java · Maven archetype(零 clone,Central 已发版) @@ -171,7 +171,7 @@ yarch/ | 构件 | 能力 | |---|---| | `yarch-parent` + `yarch-bom` | 构建基线 + 版本唯一仲裁(Boot 4.1 / JDK 25 编 21 / Spotless 4 空格) | -| `yarch-common` | 信封 / 13 码错误码表 / PageData / BusinessException / Asserts / Masks / TraceIds | +| `yarch-common` | 信封 / 14 码错误码表 / PageData / BusinessException / Asserts / Masks / TraceIds | | `yarch-web-…` | 异常矩阵 / 分页 / **幂等** / **@RateLimited(1006)** / **@OperationLog** / **@SignedApi** | | `yarch-logging-…` | **ndjson 行协议** / TraceIdFilter(traceparent 优先) | | `yarch-persistence-…` | PG + MyBatis-Plus:**逻辑删除** / 审计填充 / **分页下推** / keyset 游标 | @@ -209,7 +209,7 @@ yarch/ | 层 | Java | Web | Python | |---|---|---|---| -| 契约断言 | 错误码 13 码逐码核对 + 信封形状 + ndjson 字段 | 错误码表逐码核对 + 解包语义 | testx:13 码全表 + 信封/ndjson/PageData(跨栈 conformance 同表) | +| 契约断言 | 错误码 14 码逐码核对 + 信封形状 + ndjson 字段 | 错误码表逐码核对 + 解包语义 | testx:14 码全表 + 信封/ndjson/PageData(跨栈 conformance 同表) | | 架构守卫 | ArchUnit(DDD 依赖倒置 / 五层单向) | depcruise(pages 薄入口 / 禁反向 / contract 零框架) | import-linter(契约内核零框架 + 禁反向依赖) | | 代码风格 | Spotless AOSP 4 空格(check 挂 verify) | biome(规范单点) | ruff check + format + mypy | diff --git a/contract/README.md b/contract/README.md index 26c3d21..9297143 100644 --- a/contract/README.md +++ b/contract/README.md @@ -39,8 +39,8 @@ | 规约 | 前置依赖(硬) | 主要协作参考(软) | |---|---|---| | mysql / postgresql / mongodb / redis / nginx | — | api 四件套(错误码/幂等/traceId 口径) | -| api/realtime | — | error-codes(13 码表复用)、logging-trace(ndjson/traceId)、rest-conventions(命名/大消息引用化)、clients/client-shared(六节客户端纪律)、nginx/higress(入口透传) | -| api/telemetry | — | error-codes(13 码表回执)、logging-trace(埋点矩阵行)、kafka(摄入管道)、clickhouse(攒批写入)、clients/client-shared(七节客户端纪律) | +| api/realtime | — | error-codes(14 码表复用)、logging-trace(ndjson/traceId)、rest-conventions(命名/大消息引用化)、clients/client-shared(六节客户端纪律)、nginx/higress(入口透传) | +| api/telemetry | — | error-codes(14 码表回执)、logging-trace(埋点矩阵行)、kafka(摄入管道)、clickhouse(攒批写入)、clients/client-shared(七节客户端纪律) | | api/audit | — | logging-trace(行协议同源)、clickhouse(append-only 存储)、registry(派生资源登记指引同款) | | infra/prometheus / infra/grafana | — | api/logging-trace(service/env 标签口径)、api/audit + api/telemetry(CH 数据源共用)、agent/extensions(数据源凭证 ${ENV}) | | timescale | postgresql | clickhouse(日志场景分流) | @@ -90,24 +90,26 @@ | 实时通道规约 RT1-RT9(2026-09-16 拍板) | 新立 [api/realtime.md](api/realtime.md) v1.0 与 REST 四件套并列:**WebSocket(wss)五端默认档**(KCP/UDP 重竞技与 MQTT device 域为触发档);**首帧 AUTH**(凭证禁入 URL,30s 限时);**应用层心跳**(30s 发 / 60s 判死,单配置点);**重连三要素**(指数退避+抖动+封顶);补投/离线消息触发式(seq 预留);**独立 PushEnvelope**(type/seq/id/ts/traceId/data)错误口径复用 13 码表、消息级 traceId + 连接级 ndjson;条文覆盖全五端,内核首批 web+miniprogram+cocos。client-shared 同批增六节(长连接客户端纪律)。依据:[realtime-channel-digest.md](../docs/references/realtime-channel-digest.md) | 已生效(2026-09-16) | | 可观测轨 OB1-OB9 + EP2-R/EP3-R(2026-09-16 拍板) | 骨架 = **OTel 三信号 + Collector**(厂商中立);**logging-trace 升 v1.1**(spanId 入上下文与日志、租户上下文 X-Tenant-Id 进传播矩阵——机制归 yarch 隔离模型归业务、埋点上报边界进矩阵);metrics = **Prometheus**(exposition 标准 + RED 基础集装配件收口,新 infra/prometheus.md);logs/traces 后端 = **ClickHouse 统一**(官方 ClickStack 路径,不新立 Loki/Tempo/Mimir,LGTM 触发档;新 infra/grafana.md:Grafana 单面板两件制 + Alerting + dashboards/告警规则 provisioning 进 git);**ndjson 行协议不搬家**(OTel SDK 只管 traces+metrics,采集走 Collector filelog);traces 默认全量+采样单配置点;**审计 EP4 并轨**:api/audit.md v1.0(最小审计事件面 + 固定字段集 → CH append-only + 保留期 ≥180d,落 OperationLogStore SPI CH 实现件);EP3-R:error-codes 标识列即稳定 key,error-codes.json 必含 code/key/message + REST Accept-Language 就绪位(多语言 catalog 不做)。依据:[observability-track-digest.md](../docs/references/observability-track-digest.md) | 已生效(2026-09-16) | | 埋点管道轨 TM1-TM8(2026-09-16 拍板) | 新立 [api/telemetry.md](api/telemetry.md) v1.0:**tracking plan 登记先行**(事件注册表进业务仓 docs + CI/服务端双校验,登记哲学第三用);上报走业务域名 `POST /api/v1/telemetry/events`(微信白名单零新增)批量双阈值 20 条/10s + onHide/pagehide 强 flush + web sendBeacon 兜底 + RestResponse 信封回执、fire-and-forget 失败静默;SDK 可靠性纪律(内存队列有界 500 + storage 双写 + 失败回滚重试带上限);隐私红线(禁 PII/白名单通用属性/采集开关);SDK 落 **@yarch/contract telemetry 模块**(零新包,首批 web+miniprogram+cocos 对齐 RT9);管道 = 装配件收口转 **kafka** → 摄入 worker 攒批写 **CH**(业务禁直写);StarRocks BI 与 CDC(debezium+PG)触发式。client-shared 同批增七节。依据:[telemetry-pipeline-digest.md](../docs/references/telemetry-pipeline-digest.md) | 已生效(2026-09-16) | +| 验证码框架 CP1-CP10(2026-09-18 拍板) | 新立 [api/captcha.md](api/captcha.md) v1.0:**Provider SPI + 框架核心**(进程内组件,非独立服务);**首发三 Provider**(image 默认 / sms-otp / turnstile——OTP 分发通道宿主注入 SmsSender,yarch 不背通知抽象,EP7 届时对齐);LOCAL/REMOTE 两类校验模式;**框架内置场景路由**(默认 Provider + scene→Provider 覆盖映射,租户覆盖归应用层扩展位);**一次性原子消费**(GETDEL,java 存量 get→delete 两步视为缺陷随重构修复);**2005 CAPTCHA_INVALID 三态合一**(error-codes v1.1 纯增量,四栈 conformance 14 码)+ 限流复用 1006;`GET /api/v1/captcha` 存量字段不动 + verify 内联业务流不设独立端点;字符集/长度入契约、渲染样式自由;java 首批 SPI 重构 + golang 对齐(五处漂移清偿)+ python 首批落地,三栈测试向量 V1-V11 同源;web/客户端零动作 | 已生效(2026-09-18) | **租户边界标识**(服务名)登记处:[registry.md](registry.md)。 ## 机器可读出口(dist/ · P1 主引擎,2026-09-17) -`contract/dist/` 是 markdown 契约的**派生机器工件**(权威仍是本目录 markdown):`error-codes.json`(13 码全表 `{code, key, message, http, segment}` + success——key 即 i18n 稳定标识,EP3-R)与 `envelope.schema.json`(RestResponse / PageData 的 JSON Schema draft-07)。生成器 `gen-dist.mjs`(零依赖 Node)从 markdown 表格派生;**markdown 改动而 dist 未重生成 = CI 拒绝**(contract-dist workflow,同 registry-snapshot 漂移门机制)。四栈 conformance 测试读同一份 json 断言(java `GlobalErrorCodeContractTest` / golang `errcode_test` / python `test_errcode` / web `contract.test.ts`),不再各养手抄表。 +`contract/dist/` 是 markdown 契约的**派生机器工件**(权威仍是本目录 markdown):`error-codes.json`(14 码全表 `{code, key, message, http, segment}` + success——key 即 i18n 稳定标识,EP3-R)与 `envelope.schema.json`(RestResponse / PageData 的 JSON Schema draft-07)。生成器 `gen-dist.mjs`(零依赖 Node)从 markdown 表格派生;**markdown 改动而 dist 未重生成 = CI 拒绝**(contract-dist workflow,同 registry-snapshot 漂移门机制)。四栈 conformance 测试读同一份 json 断言(java `GlobalErrorCodeContractTest` / golang `errcode_test` / python `test_errcode` / web `contract.test.ts`),不再各养手抄表。 -## API 契约(REST 四件套 + 实时通道 + 埋点 + 审计) +## API 契约(REST 四件套 + 实时通道 + 埋点 + 审计 + 验证码) | 契约 | 文件 | 一句话 | |---|---|---| | 响应形状 | [rest-response.md](api/rest-response.md) | code/message/data/traceId 四字段,0 即成功 | -| 错误码段位 | [error-codes.md](api/error-codes.md) | 一张跨语言 errno 段位表,yarch 拥有 0/1xxx/2xxx;标识列即 i18n 稳定 key(EP3-R) | +| 错误码段位 | [error-codes.md](api/error-codes.md) | 一张跨语言 errno 段位表,yarch 拥有 0/1xxx/2xxx;标识列即 i18n 稳定 key(EP3-R);v1.1 增 2005 | | 日志与追踪 | [logging-trace.md](api/logging-trace.md) | 统一 JSON 行协议 + traceId 贯穿(W3C traceparent);v1.1 增 spanId / 租户上下文 / 埋点矩阵行 | | REST 约定 | [rest-conventions.md](api/rest-conventions.md) | 命名/分页/状态码/幂等,无方言;Accept-Language i18n 就绪位(EP3-R) | -| 实时通道 | [realtime.md](api/realtime.md) | WebSocket 长连接与推送:首帧鉴权 / 应用层心跳 / 退避重连 / PushEnvelope(复用 13 码表与 traceId 口径,独立于 RestResponse) | +| 实时通道 | [realtime.md](api/realtime.md) | WebSocket 长连接与推送:首帧鉴权 / 应用层心跳 / 退避重连 / PushEnvelope(复用 14 码表与 traceId 口径,独立于 RestResponse) | | 埋点管道 | [telemetry.md](api/telemetry.md) | tracking plan 登记先行 / 业务域名批量上报(双阈值 + onHide·sendBeacon 兜底)/ 收口转 kafka 禁直写 CH / SDK 落契约内核首批三端 | | 审计留存 | [audit.md](api/audit.md) | 合规通道:最小审计事件面 + ndjson 固定字段集 → CH append-only + 保留期 ≥180d,落 OperationLogStore SPI 的 CH 实现件 | +| 验证码框架 | [captcha.md](api/captcha.md) | Provider SPI(image/sms-otp/turnstile 三档)+ 框架核心(一次性原子消费 GETDEL / 场景路由 / 限流 1006 / 2005 三态合一);verify 内联业务流不设独立端点 | ## 数据与中间件规约(infra/) @@ -207,6 +209,7 @@ | 2026-09-16 | **企业级定位修订 + 实时通道定稿**:EP1-EP12 拍板(目标场景补「企业级应用/游戏交付」;三轨排序 realtime > 可观测(含审计)> 埋点;多租户拆两层、i18n 仅就绪位、桌面端/支付协议层触发式登记);[api/realtime.md](api/realtime.md) v1.0 定稿(RT1-RT9:WS 五端默认档 / 首帧 AUTH / 应用层心跳 / 退避三要素 / PushEnvelope 复用 13 码表);client-shared 增六节(长连接与推送);registry 三节增 wss 域名登记行。依据 digest:enterprise-capability-gap / realtime-channel | 已定稿 | | 2026-09-16 | **企业级第二三轨定稿(可观测 + 埋点)**:OB1-OB9 + EP2-R/EP3-R、TM1-TM8 拍板——logging-trace **v1.1**(spanId / X-Tenant-Id 租户传播 / 埋点矩阵行,纯增量);[api/telemetry.md](api/telemetry.md) v1.0(tracking plan 登记先行 / 业务域名批量上报 / 收口转 kafka 禁直写 CH);[api/audit.md](api/audit.md) v1.0(审计最小事件面 → CH append-only ≥180d);infra 增 [prometheus.md](infra/prometheus.md) + [grafana.md](infra/grafana.md)(共 22 份);client-shared 增七节(埋点上报);error-codes 实现规则 4(标识即稳定 key)+ rest-conventions Accept-Language 就绪位(EP3-R)。依据 digest:observability-track / telemetry-pipeline | 已定稿 | | 2026-09-17 | **P1 契约机器可读出口落地**:`contract/dist/` 派生层开张(error-codes.json + envelope.schema.json,gen-dist.mjs 从 markdown 表格生成,contract-dist CI 漂移门);四栈 conformance 改读同一份 json(java/golang/python/web 同源断言,缺文件优雅跳过);N1 收口——java 双 archetype / golang / python 生成器模板补 AGENTS.md 三件套(java archetype 三件套走 unfiltered fileSet:Velocity 会把 markdown 的 ## 当行注释吞掉)+ web 五模板补 CLAUDE/GEMINI 一行派生 | 已生效 | +| 2026-09-18 | **验证码框架 CP1-CP10 拍板成文**:新立 [api/captcha.md](api/captcha.md) v1.0(Provider SPI 三档 + 一次性原子消费 GETDEL + 场景路由 + verify 内联业务流 + 跨栈测试向量附录);error-codes **v1.1** 纯增量 2005 CAPTCHA_INVALID(dist 14 码,四栈 conformance 同步);java `yarch-captcha-spring-boot-starter` 同批 SPI 重构(image/sms-otp/turnstile + GETDEL 缺陷修复),golang/python captcha 触发档对齐,web/客户端消费面零动作 | 已生效 | | — | 遗留项:低频组件强制级占比复审;机检条文标注启动(下一步:随 stacks 重做启动 `yarch lint`/AI 审查清单) | 待办 | ## 术语对照(各栈方言) diff --git a/contract/api/captcha.md b/contract/api/captcha.md new file mode 100644 index 0000000..011fb01 --- /dev/null +++ b/contract/api/captcha.md @@ -0,0 +1,98 @@ +# 契约 · 验证码框架(Captcha · Provider SPI 与消费面)(v1.0 已定稿) + +> **状态:已定稿**(2026-09-18 经 CP1-CP10 决策清单拍板;拍板口径见 [../README.md](../README.md) 关键架构决策登记表 CP 行)。 +> 等级:**【强制】**违反即缺陷;**【推荐】**默认遵守、评审后可豁免;**【参考】**正向引导。 +> 分工:本规约管**人机校验挑战**(challenge 生成/分发/校验/防重放);登录态与凭证错误归 [error-codes.md](error-codes.md) `2xxx`;存储 key 纪律归 [../infra/redis.md](../infra/redis.md);REST 信封归 [rest-response.md](rest-response.md)。 + +## 一、形态与职责(CP2) + +1. 【强制】形态 = **Provider SPI + 框架核心**(进程内组件,非独立服务):渠道差异(图形/OTP/第三方)是框架内多态,不构成服务边界(无独立数据域、无独立伸缩诉求)。 +2. 【强制】职责分界: + +| 归属 | 职责 | +|---|---| +| 框架核心(与 Provider 无关) | challenge 生命周期(key 生成/存储/TTL/一次性原子消费)、场景路由(四)、生成端限流联动(五-1)、错误语义统一(五-2) | +| Provider(SPI 实现) | 生成挑战(答案 + 分发载体,或透出接入配置)、答案比对规则(本地型)/ 远程校验(远程型) | + +3. 【强制】Provider 标识(`id`)kebab-case,系统保留字:`image` / `sms-otp` / `turnstile`;业务自定义 Provider 禁占用保留字(注册表哲学同 [realtime.md](realtime.md) 三-1)。 + +## 二、Provider 行为契约(CP3) + +1. 【强制】Provider 必须声明校验模式,二选一: + - **LOCAL(本地校验型)**:答案由框架核心托管进 Redis,一次性原子消费(三);Provider 只产出答案与分发载体、给出比对规则。 + - **REMOTE(远程校验型)**:无服务端答案存储;Provider 透出接入配置(如 `siteKey`)并执行远程校验调用;一次性语义由上游保证。 +2. 【强制】`image` 档(LOCAL,默认档):答案 = 4 位字符,字符集固定为去混淆 32 字符 `ABCDEFGHJKLMNPQRSTUVWXYZ23456789`(去 `I O 0 1`);比对 = 首尾空白 trim + 大小写不敏感;分发载体 = PNG 裸 base64(**无 `data:` 前缀**,前端自行拼装 dataURL——存量字段形态不动)。渲染样式(噪线/颜色/尺寸)实现自由(CP9:绑各栈图形库能力,不入契约)。 +3. 【强制】`sms-otp` 档(LOCAL):答案 = 6 位数字 OTP(安全随机源);比对 = 精确匹配(禁宽松比对);分发 = **发送通道由宿主注入**(`SmsSender`/Notifier SPI)——yarch 不背通知渠道抽象(通知领域契约排队中,EP7,届时对齐);发送目标(手机号)回显必须脱敏。 +4. 【强制】`turnstile` 档(REMOTE):分发 = `siteKey` 配置透出(前端嵌 widget 自取 token);校验 = 上游 siteverify 接口(token + secret + remoteip);服务端不复存 token、禁将 token 落 Redis。 +5. 【参考】触发档(首个消费者出现时增补条文):滑块/行为验证、邮箱 OTP、其他第三方人工验证(reCAPTCHA/hCaptcha 等)。 + +## 三、challenge 生命周期(CP6/CP7) + +1. 【强制】key 由服务端安全随机生成(≥128 bit 熵,UUIDv4 同级及以上),**禁业务可预测值**(用户名/时间戳派生等)。 +2. 【推荐】TTL 默认 **120s**、应用可配;OTP 档可放宽至 300s。 +3. 【强制】**一次性语义**:对/错/异常均消费该 key(防重放与枚举)——校验失败后同 key 二次提交必须失败。 +4. 【强制】**原子消费**:取答案与删除必须原子(`GETDEL`;实例 < Redis 6.2 时用等价 Lua `GET+DEL`)——两步 get→delete 是缺陷(并发双 verify 竞态双双通过)。 +5. 【强制】存储 key 遵循 [../infra/redis.md](../infra/redis.md):`{服务名}:captcha:{provider}:{key}`(首段 = 服务名,共享实例租户边界);REMOTE 型不产生存储 key。 + +## 四、场景路由(CP4) + +1. 【强制】场景标识(`scene`)为自由 kebab-case 字符串,宿主自定——yarch 不拥有业务场景枚举(同 3xxx-8xxx 治理哲学);【参考】常用:`login` / `register` / `reset-password`。 +2. 【强制】路由配置模型 = **默认 Provider(缺省 `image`)+ scene→Provider 覆盖映射**;未配置的 scene 一律走默认 Provider(不报错)。 +3. 【参考】租户级覆盖是宿主应用层扩展位:框架配置面到应用级为止,租户维度的覆盖映射由宿主实现(如查租户配置表后显式指定 Provider)。 + +## 五、限流与错误(CP5/CP8) + +1. 【强制】生成/分发端点默认挂限流,超限报 `1006 RATE_LIMITED`(复用 [error-codes.md](error-codes.md) 通用段与各栈限流件);【参考】默认阈值 per-IP 固定窗口 60s/10 次。 +2. 【强制】本规约唯一新增错误码 **`2005 CAPTCHA_INVALID`(HTTP 400)**:key 无效 / 已消费 / 答案错误**三态合一**,禁细分(细分即向探测方泄露 key 状态);其余一律复用既有码(限流 1006、参数缺失 1001)。 +3. 【推荐】`sms-otp` 的分发按**发送目标**(手机号)维度追加限流(防短信轰炸),阈值宿主定。 + +## 六、REST 消费面(CP8) + +1. 【强制】`GET /api/v1/captcha`(image 默认档;`scene` 可选 query 参数,见四)→ `RestResponse`;Challenge 形状: + +| 字段 | 类型 | 语义 | +|---|---|---| +| `provider` | string | Provider 标识(增量字段,存量消费者可忽略) | +| `key` | string | challenge key(提交回传) | +| `imageBase64` | string | PNG 裸 base64(无 `data:` 前缀,前端自行拼装;image 档专属) | + + 存量字段 `key` / `imageBase64` 名字与语义不变(存量前端零动作,CP10)。 +2. 【强制】**verify 不设独立端点**:校验内联在受保护业务流(login/register 等)的参数对 `captchaKey` / `captchaAnswer`(camelCase,D3 同源)中,由业务端点调框架核心完成——独立 verify 端点会成为探测面。 +3. 【强制】REMOTE 型内联参数:`captchaAnswer` = 上游 token(`captchaKey` 省略)。 +4. 【参考】`sms-otp` / `turnstile` 的 HTTP 分发端点为**触发档**(编程式调用首发即可用);触发时增补条文(如 `POST /api/v1/captcha/sms-otp`,含目标脱敏与发送限流)。 + +## 七、可机检条文清单 + +> 对齐 [../README.md](../README.md)「机检路线」。落地载体为各栈装配件(实现触发式登记,首批范围见附录)。 + +| 条文 | 机检手段 | 阶段 | +|---|---|---| +| 二-2 字符集与长度 | 装配件单测(生成答案白名单断言) | 单测 | +| 三-3/三-4 一次性与原子消费 | conformance 向量 V2/V3/V6(见附录) | 单测 | +| 三-5 存储 key 形状 | 装配件单测(key 前缀断言 `服务名:captcha:`) | 单测 | +| 五-2 错误码三态合一 | 四栈 conformance(随 [../dist/error-codes.json](../dist/error-codes.json) 同源断言 2005) | 单测 | +| 六-1 端点与 Challenge 字段 | 装配件端点测试(字段恒在) | 单测 | + +## 附:跨栈一致性测试向量(conformance 同源) + +> 各栈实现须以同源向量断言行为一致(EP5 HMAC 跨栈验收同款);java 首批落地,golang/python 触发时同源引用。 + +| # | 向量 | 期望 | +|---|---|---| +| V1 | issue(image) 后以正确答案 verify | `true`,且同 key 立即失效 | +| V2 | V1 后同 key 以同答案再 verify | `false`(一次性) | +| V3 | 以错误答案 verify | `false`,且 key 已消费(防重放枚举) | +| V4 | 以不存在/过期 key verify | `false` | +| V5 | 答案带首尾空白且大小写不同(image) | 命中(trim + 大小写不敏感) | +| V6 | 并发两个 verify 同 key | 恰一个 `true`(原子消费) | +| V7 | issue 后查存储 TTL | `0 < TTL ≤ 120`(默认档) | +| V8 | sms-otp:issue(目标) → SmsSender 收 6 位数字;错一位 verify | 发送可达;`false` 且已消费 | +| V9 | turnstile:注入 stub 校验端点,通过/失败两分支 | 与 stub 一致;全程零 Redis 存储 key | +| V10 | 场景路由:配置 `scenes` 映射 + 未配置 scene | 映射生效 / 走默认 Provider | +| V11 | 生成端点同 IP 超限流阈值 | `1006 RATE_LIMITED` | + +## 附:来源与拍板记录 + +- 拍板记录(唯一登记处:[../README.md](../README.md) 关键架构决策登记表 CP 行,此处为引用):2026-09-18 CP1-CP10——独立成文 `contract/api/captcha.md`;SPI + 框架核心形态;**首发三 Provider(image/sms-otp/turnstile)**,OTP 分发通道宿主注入;**框架内置场景路由**(默认 + 覆盖映射,租户覆盖归应用层扩展位);2005 单码三态合一 + 限流复用 1006;TTL 120s 推荐 + 一次性强制;GETDEL 原子消费(java 存量 get→delete 两步视为缺陷随重构修复);`GET /api/v1/captcha` + verify 内联业务流 + 存量字段不动;字符集/长度入契约、渲染样式自由;java 首批实现、golang/python 触发档。 +- 现状依据:java `yarch-captcha-spring-boot-starter`(图形码 + Redis 一次性 token,2026-09-02 第二批)为存量基准。 +- 实现节奏:java 首批已落地(SPI 重构 + 三 Provider + 向量测试);golang 已对齐(SPI 化 + 场景路由 + 五处漂移清偿:长度/TTL 默认/端点字段/存储 key provider 段/失败码 2005);python 首批已落地(`yarch_python.captcha` 同源 SPI + 纯 stdlib PNG 渲染);web/客户端零动作(消费字段不变)。 diff --git a/contract/api/error-codes.md b/contract/api/error-codes.md index 372dc38..0213e95 100644 --- a/contract/api/error-codes.md +++ b/contract/api/error-codes.md @@ -1,6 +1,6 @@ -# 契约 · 错误码全局段位表(v1.0 已定稿) +# 契约 · 错误码全局段位表(v1.1 已定稿) -> **状态:已定稿**(2026-09-01 评审通过;D1-D6 已拍板,口径为"业界标准优先于阿里手册",结论见 [../../docs/references/alibaba-java-manual-digest.md](../../docs/references/alibaba-java-manual-digest.md) D 表)。 +> **状态:已定稿**(2026-09-01 评审通过;D1-D6 已拍板,口径为"业界标准优先于阿里手册",结论见 [../../docs/references/alibaba-java-manual-digest.md](../../docs/references/alibaba-java-manual-digest.md) D 表。2026-09-18 升 v1.1:纯增量新增 2005 CAPTCHA_INVALID,随 [captcha.md](captcha.md) v1.0)。 > > **D1 已拍板**:采用 `int32 数字段位 + 标识符`(与 HTTP 状态码+reason phrase、gRPC code+name 的业界形态同构);**不采用**阿里 5 位字符串 A/B/C 方案——按"谁的错"分段偏客服排障视角,与按"谁拥有"分段的多仓治理诉求冲突,且 int32 对四栈类型系统与序列化最友好。 @@ -43,6 +43,7 @@ | 2002 | CREDENTIALS_EXPIRED | 凭证已过期 | 401 | | 2003 | FORBIDDEN | 权限不足 | 403 | | 2004 | ACCOUNT_DISABLED | 账号已禁用 | 403 | +| 2005 | CAPTCHA_INVALID | 验证码校验失败 | 400 | ## 实现规则 @@ -67,3 +68,4 @@ | CREDENTIALS_EXPIRED | `CREDENTIALS_EXPIRED` | `CredentialsExpired` | `CREDENTIALS_EXPIRED` | `CREDENTIALS_EXPIRED` | | FORBIDDEN | `FORBIDDEN` | `Forbidden` | `FORBIDDEN` | `FORBIDDEN` | | ACCOUNT_DISABLED | `ACCOUNT_DISABLED` | `AccountDisabled` | `ACCOUNT_DISABLED` | `ACCOUNT_DISABLED` | +| CAPTCHA_INVALID | `CAPTCHA_INVALID` | `CaptchaInvalid` | `CAPTCHA_INVALID` | `CAPTCHA_INVALID` | diff --git a/contract/api/realtime.md b/contract/api/realtime.md index a829d7a..ea96fa8 100644 --- a/contract/api/realtime.md +++ b/contract/api/realtime.md @@ -36,7 +36,7 @@ | `id` | string | 消息标识:上行请求帧由客户端生成,服务端响应帧回带同值(请求-响应关联);服务端推送自生成 | | `ts` | ISO-8601 UTC | D4 同源 | | `traceId` | string | 32 位小写 hex,见四-2 | -| `data` | object | 载荷,字段 camelCase;错误帧为 `code` / `message`(复用 13 码表,见四-1) | +| `data` | object | 载荷,字段 camelCase;错误帧为 `code` / `message`(复用 14 码表,见四-1) | 2. 【强制】请求-响应 over 通道:客户端上行带 `id`,服务端回执帧(业务响应或 `error` 帧)回带同 `id`;`error` 帧形状 `{type:"error", id, code, message, traceId}`。 3. 【强制】单帧载荷 ≤ 64KB:超限内容走 REST 或对象存储引用化传递(对齐 [../infra/kafka.md](../infra/kafka.md) 大消息引用化先例)。 @@ -67,7 +67,7 @@ | 二-4 退避三要素 | 内核重连序列单测(指数 + 抖动 + 封顶断言) | 单测 | | 三-1 信封字段恒在 | 内核序列化单测(缺字段即构造失败) | 单测 | | 三-1 系统保留 type 冲突 | 业务 type 注册表校验(CI 枚举检查) | CI | -| 四-1 错误码复用 | 契约断言(同 13 码表,随支柱 1 error-codes.json 同源) | 单测 | +| 四-1 错误码复用 | 契约断言(同 14 码表,随支柱 1 error-codes.json 同源) | 单测 | --- diff --git a/contract/dist/error-codes.json b/contract/dist/error-codes.json index 3434872..cf7cdc2 100644 --- a/contract/dist/error-codes.json +++ b/contract/dist/error-codes.json @@ -96,6 +96,13 @@ "message": "账号已禁用", "http": 403, "segment": "2xxx" + }, + { + "code": 2005, + "key": "CAPTCHA_INVALID", + "message": "验证码校验失败", + "http": 400, + "segment": "2xxx" } ] } diff --git a/contract/dist/gen-dist.mjs b/contract/dist/gen-dist.mjs index 11f4858..933472b 100644 --- a/contract/dist/gen-dist.mjs +++ b/contract/dist/gen-dist.mjs @@ -62,7 +62,7 @@ function genErrorCodes() { }; parse(seg1, "1xxx", seg2); parse(seg2, "2xxx", impl); - if (codes.length !== 13) throw new Error(`13 码全表解析异常:得到 ${codes.length} 条`); + if (codes.length !== 14) throw new Error(`14 码全表解析异常:得到 ${codes.length} 条`); // 段位分配表的 0 成功行(key 由四栈方言持有:OK / SUCCESS / CODE_SUCCESS) const alloc = tableRows(md.slice(0, seg1)); diff --git a/contract/infra/prometheus.md b/contract/infra/prometheus.md index 116dca3..7e8a61e 100644 --- a/contract/infra/prometheus.md +++ b/contract/infra/prometheus.md @@ -25,7 +25,7 @@ | 条文 | 机检手段 | 阶段 | |---|---|---| | 二-1 标签基线 | 装配件单测(exposition 样本断言) | 单测 | -| 二-2 RED 基础指标集 | 四栈 conformance 同表断言(对齐 13 码表机检先例) | CI | +| 二-2 RED 基础指标集 | 四栈 conformance 同表断言(对齐 14 码表机检先例) | CI | | 二-3 命名风格 | 装配件 lint(业务指标注册时校验 snake_case + 单位后缀) | CI | --- diff --git a/docs/superpowers/plans/2026-09-18-yarch-rust-batch1.md b/docs/superpowers/plans/2026-09-18-yarch-rust-batch1.md new file mode 100644 index 0000000..9c83394 --- /dev/null +++ b/docs/superpowers/plans/2026-09-18-yarch-rust-batch1.md @@ -0,0 +1,1017 @@ +# Rust 栈批次一(契约内核)Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 落地 yarch rust 栈第一批——cargo workspace + `yarch-contract` 契约内核(response/errcode/trace 三模块)+ 同源契约断言 + CI 四段门禁,本地与 CI 全绿。 + +**Architecture:** 依 [设计文档](../specs/2026-09-18-ycomp-component-platform-design.md) SP0 与 `stacks/rust/PLAN.md` 第一批:workspace 两 crate(`yarch-contract` 契约内核零框架 + `yarch-axum` 批次二占位空壳);错误码表同源断言唯一权威 `contract/dist/error-codes.json`(P1 契约机器可读出口口径,对齐 golang/java/python/web 四栈 conformance);CI 走 spec 九-1 四段门禁(fmt / clippy -D warnings / cargo-deny / test)+ R7 MSRV 1.80 双档矩阵。 + +**Tech Stack:** Rust 1.95.0(本地,已核实)、edition 2021、MSRV 1.80;依赖仅 `serde`(derive)+ `rand` 0.9(traceId 生成)+ `serde_json`(dev);CI 用 dtolnay/rust-toolchain + Swatinem/rust-cache + taiki-e/install-action@cargo-deny。 + +**范围边界(不在本计划):** registry 登记 ycomp/ycomp-console(批次 0,验证码批提交后另做);CL1-CL6 组件库契约拍板;yarch-axum 中间件五件与模板(批次二);组件库两包(SP1)。 + +## Global Constraints + +- **pathspec 提交铁律**:本仓 index 有滞留 WIP 史,提交必须 `git commit -m "…" -- `,绝不裸 commit。 +- **工作树污染隔离**:工作树现有另一会话未提交的验证码批改动(`contract/README.md`、`contract/api/error-codes.md`、`contract/dist/*`、`stacks/golang/errcode/*`、`stacks/java/**/GlobalErrorCode*`、`stacks/python/**/test_errcode.py`、`stacks/web/**/contract*`、未跟踪 `contract/api/captcha.md`)。本计划**只创建/修改本任务清单 Files 列出的文件**,不碰上述文件。 +- **CI 依赖前置(Task 0 核实)**:conformance 断言按 14 码(error-codes v1.1,工作树现状)写内建表;**CI 读提交态 dist json**——验证码批未提交则 CI 必红。执行本计划前必须先由用户提交验证码批(见 Task 0)。 +- 契约语义唯一权威 = `contract/api/` 四件套;实现与契约不一致 = bug(四栈同口径)。 +- MSRV 1.80(`rust-version`),edition 2021;rustfmt + clippy `-D warnings` 全绿才可提交。 +- 本地验证命令一律 `cd stacks/rust` 后执行(Bash 工具 cwd 漂移坑:单条命令内显式 cd 并 pwd 确认)。 +- 根 `.gitignore` 已含 `target/`(已核实,无需追加)。 + +--- + +### Task 0: 前置确认(验证码批 + 工具链) + +**Files:** 无(纯检查) + +- [ ] **Step 1: 确认验证码批已提交** + +Run: `git status --porcelain | grep -E "captcha|error-codes|GlobalErrorCode|test_errcode|contract.test|errcode_test|dist"` +Expected: 无输出(验证码批已落库)。**若有输出:停下,请用户提交该批后再继续**(dist json 的 14 码是 conformance 前提;勿代提交——非本计划工作)。 + +- [ ] **Step 2: 确认工具链** + +Run: `rustc --version && cargo --version` +Expected: `rustc 1.95.0 …`、`cargo 1.95.0 …`(已核实存在;若环境变化缺 rust,`rustup toolchain install 1.95.0`)。 + +--- + +### Task 1: workspace 骨架 + 两 crate 空壳 + +**Files:** +- Create: `stacks/rust/Cargo.toml` +- Create: `stacks/rust/rust-toolchain.toml` +- Create: `stacks/rust/deny.toml` +- Create: `stacks/rust/crates/yarch-contract/Cargo.toml` +- Create: `stacks/rust/crates/yarch-contract/src/lib.rs` +- Create: `stacks/rust/crates/yarch-axum/Cargo.toml` +- Create: `stacks/rust/crates/yarch-axum/src/lib.rs` + +**Interfaces:** +- Consumes: 无(首个任务) +- Produces: workspace 结构与包元数据;`yarch-contract` / `yarch-axum` 两个空 lib(后续任务在其中加模块) + +- [ ] **Step 1: 写 workspace 根 `stacks/rust/Cargo.toml`** + +```toml +# yarch rust 栈 workspace:契约内核(零框架)+ axum 装配(批次二施工)。 +# 规约唯一权威:stacks/rust/spec.md(R1-R7)+ contract/api/ 四件套。 +[workspace] +resolver = "2" +members = ["crates/yarch-contract", "crates/yarch-axum"] + +[workspace.package] +version = "0.1.0" +edition = "2021" +license = "Apache-2.0" +repository = "https://github.com/ydonghao/yarch" +rust-version = "1.80" + +[workspace.dependencies] +serde = { version = "1", features = ["derive"] } +serde_json = "1" +rand = "0.9" +``` + +- [ ] **Step 2: 写 `stacks/rust/rust-toolchain.toml`** + +```toml +# 本地开发钉死 1.95.0(spec 一-1);CI 矩阵 stable + MSRV 1.80 双档经 +# dtolnay/rust-toolchain 的 RUSTUP_TOOLCHAIN 环境变量覆盖,互不干扰。 +[toolchain] +channel = "1.95.0" +``` + +- [ ] **Step 3: 写 `stacks/rust/deny.toml`** + +```toml +# cargo-deny(spec 一-3):许可证白名单 + 禁重复大版本 + RUSTSEC 咨询。 +[graph] +all-features = true + +[licenses] +allow = [ + "MIT", + "Apache-2.0", + "Apache-2.0 WITH LLVM-exception", + "BSD-2-Clause", + "BSD-3-Clause", + "ISC", + "Unicode-3.0", + "Zlib", +] +``` + +- [ ] **Step 4: 写 `stacks/rust/crates/yarch-contract/Cargo.toml`** + +```toml +[package] +name = "yarch-contract" +description = "yarch 契约内核(Rust 方言):REST 信封 / 错误码段位表 / traceId——零框架" +keywords = ["yarch", "contract", "rest", "error-code"] +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true + +[dependencies] +serde = { workspace = true } +rand = { workspace = true } + +[dev-dependencies] +serde_json = { workspace = true } +``` + +- [ ] **Step 5: 写 `crates/yarch-contract/src/lib.rs`(占位,模块随 Task 2-4 增)** + +```rust +//! yarch-contract:Rust 契约内核(零框架)。 +//! +//! 语义唯一权威 = contract/api/ 四件套;实现与契约不一致 = bug(四栈同口径)。 +//! 约束对象:yarch 体系全部 Rust 云端业务服务(与 embedded/esp32 固件轨零共享 crate)。 +``` + +- [ ] **Step 6: 写 `crates/yarch-axum/Cargo.toml` 与空壳 lib** + +`crates/yarch-axum/Cargo.toml`: + +```toml +[package] +name = "yarch-axum" +description = "yarch axum 装配层:中间件五件/提取器/分页/幂等(批次二施工,本批为空壳)" +keywords = ["yarch", "axum", "middleware"] +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true +``` + +`crates/yarch-axum/src/lib.rs`: + +```rust +//! yarch-axum:axum 0.8 装配层——中间件五件(Trace/Recovery/AccessLog/Idempotency/Rate)、 +//! sqlx 装配与提取器。批次二施工;本批为占位空壳。 +``` + +- [ ] **Step 7: 验证空壳可构建、可测、机检绿** + +Run: +```bash +cd /Users/yuandonghao/sidejob/sources/yarch/stacks/rust && pwd && \ + cargo build --workspace && cargo test --workspace && \ + cargo fmt --all -- --check && cargo clippy --all-targets -- -D warnings +``` +Expected: 构建成功;`test result: ok. 0 passed`(两 crate 各 0 测试);fmt 无 diff;clippy 零告警。 + +- [ ] **Step 8: Commit** + +```bash +git add stacks/rust/Cargo.toml stacks/rust/rust-toolchain.toml stacks/rust/deny.toml \ + stacks/rust/crates/yarch-contract stacks/rust/crates/yarch-axum +git commit -m "feat(rust): 栈批次一开工——workspace 两 crate 空壳 + toolchain 钉 1.95.0 + deny.toml" -- \ + stacks/rust/Cargo.toml stacks/rust/rust-toolchain.toml stacks/rust/deny.toml \ + stacks/rust/crates/yarch-contract stacks/rust/crates/yarch-axum +``` + +--- + +### Task 2: errcode 模块(错误码段位表) + +**Files:** +- Modify: `stacks/rust/crates/yarch-contract/src/lib.rs`(加 `pub mod errcode;`) +- Create: `stacks/rust/crates/yarch-contract/src/errcode.rs`(实现 + 内联单测) + +**Interfaces:** +- Consumes: 无(内核首个模块) +- Produces(后续任务与业务工程依赖): + - `pub struct ErrCode { pub code: i32, pub key: &'static str, pub message: &'static str, pub http: u16 }` + - 常量:`OK`(0)+ 14 个内建码常量(`INTERNAL_ERROR`…`CAPTCHA_INVALID`,UPPER_SNAKE 命名 = dist key 同形) + - `pub const BUILTIN: &[ErrCode]`(全表,含 OK,供 conformance 对表) + - `pub fn lookup(code: i32) -> ErrCode`(未登记回退 `INTERNAL_ERROR`) + - `pub fn is_registered(code: i32) -> bool` + - `pub fn register(code: i32, key: &'static str, message: &'static str, http: u16) -> Result<(), RegisterError>`(业务段 3xxx-8xxx;幂等重登放行;`RegisterError::{OutOfRange, HttpNotAllowed, Conflict}`) + +- [ ] **Step 1: lib.rs 挂模块声明(先挂再写实现 → 编译红)** + +在 `lib.rs` 文档注释后追加一行: + +```rust +pub mod errcode; +``` + +- [ ] **Step 2: 创建 `errcode.rs` 骨架(类型/常量/测试全集 + 三函数桩)** + +文件内容 = Step 4 完整文件**去掉三个函数体**、其余逐字一致(doc 注释、`ErrCode` + `new`、全部常量、`BUILTIN`、`BUSINESS_MIN/MAX`、`RegisterError`、`BUSINESS` 静态、`http_allowed`、完整 `mod tests`),三个函数先写桩: + +```rust +pub fn lookup(code: i32) -> ErrCode { + todo!() +} + +pub fn is_registered(code: i32) -> bool { + todo!() +} + +pub fn register( + code: i32, + key: &'static str, + message: &'static str, + http: u16, +) -> Result<(), RegisterError> { + todo!() +} +``` + +- [ ] **Step 3: 跑测试确认红** + +Run: `cd /Users/yuandonghao/sidejob/sources/yarch/stacks/rust && cargo test -p yarch-contract` +Expected: 编译通过;`ok_constant`、`builtin_table_is_unique` 2 项 PASS,其余 4 项 panic(`not yet implemented`)。 + +- [ ] **Step 4: `errcode.rs` 完整权威内容(把三个 `todo!()` 桩换成真身)** + +```rust +//! 错误码段位表(契约内核)。 +//! +//! 唯一权威 = contract/api/error-codes.md(机器可读派生层 contract/dist/error-codes.json, +//! 同源断言见 tests/conformance.rs)。yarch 只拥有 0、1xxx、2xxx;3xxx-8xxx 由业务仓 +//! 登记后方可使用([`register`]);9xxx 预留不得使用。 + +use std::collections::HashMap; +use std::sync::RwLock; + +/// 错误码元数据(不可变值对象)。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct ErrCode { + /// 业务码。0 = 成功;非 0 见段位表 + pub code: i32, + /// UPPER_SNAKE 标识(与 dist json 的 key 同形) + pub key: &'static str, + /// 默认中文文案(可直接作为前端降级文案) + pub message: &'static str, + /// 固定 HTTP 状态码映射(服务端不得自行发挥) + pub http: u16, +} + +impl ErrCode { + const fn new(code: i32, key: &'static str, message: &'static str, http: u16) -> Self { + Self { code, key, message, http } + } +} + +/// 成功(code = 0) +pub const OK: ErrCode = ErrCode::new(0, "OK", "成功", 200); + +// 通用段 1xxx +pub const INTERNAL_ERROR: ErrCode = ErrCode::new(1000, "INTERNAL_ERROR", "内部错误", 500); +pub const INVALID_ARGUMENT: ErrCode = ErrCode::new(1001, "INVALID_ARGUMENT", "参数校验失败", 400); +pub const MALFORMED_BODY: ErrCode = ErrCode::new(1002, "MALFORMED_BODY", "请求体格式错误", 400); +pub const NOT_FOUND: ErrCode = ErrCode::new(1004, "NOT_FOUND", "资源不存在", 404); +pub const CONFLICT: ErrCode = ErrCode::new(1005, "CONFLICT", "资源冲突", 409); +pub const RATE_LIMITED: ErrCode = ErrCode::new(1006, "RATE_LIMITED", "触发限流", 429); +pub const IDEMPOTENCY_CONFLICT: ErrCode = + ErrCode::new(1007, "IDEMPOTENCY_CONFLICT", "幂等冲突:重复提交", 409); +pub const UPSTREAM_TIMEOUT: ErrCode = ErrCode::new(1008, "UPSTREAM_TIMEOUT", "上游依赖超时", 504); +pub const UNAVAILABLE: ErrCode = ErrCode::new(1009, "UNAVAILABLE", "服务暂不可用", 503); + +// 认证与权限段 2xxx +pub const UNAUTHORIZED: ErrCode = ErrCode::new(2001, "UNAUTHORIZED", "未认证", 401); +pub const CREDENTIALS_EXPIRED: ErrCode = ErrCode::new(2002, "CREDENTIALS_EXPIRED", "凭证已过期", 401); +pub const FORBIDDEN: ErrCode = ErrCode::new(2003, "FORBIDDEN", "权限不足", 403); +pub const ACCOUNT_DISABLED: ErrCode = ErrCode::new(2004, "ACCOUNT_DISABLED", "账号已禁用", 403); +pub const CAPTCHA_INVALID: ErrCode = ErrCode::new(2005, "CAPTCHA_INVALID", "验证码校验失败", 400); + +/// 内建全表(0 + 1xxx + 2xxx;同源断言对表用) +pub const BUILTIN: &[ErrCode] = &[ + OK, + INTERNAL_ERROR, + INVALID_ARGUMENT, + MALFORMED_BODY, + NOT_FOUND, + CONFLICT, + RATE_LIMITED, + IDEMPOTENCY_CONFLICT, + UPSTREAM_TIMEOUT, + UNAVAILABLE, + UNAUTHORIZED, + CREDENTIALS_EXPIRED, + FORBIDDEN, + ACCOUNT_DISABLED, + CAPTCHA_INVALID, +]; + +/// 业务段边界:3xxx-8xxx(9xxx 预留不得使用) +const BUSINESS_MIN: i32 = 3000; +const BUSINESS_MAX: i32 = 8999; + +/// 业务码登记失败(对齐 golang panic 语义;Rust 以 Result 承载,装配期调用方 `.expect` fail-fast) +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum RegisterError { + /// 段位越界(仅 3xxx-8xxx 可登记) + OutOfRange(i32), + /// HTTP 状态码不在白名单 + HttpNotAllowed(u16), + /// 同 code 已登记且元信息不同 + Conflict { code: i32, existing_key: &'static str }, +} + +static BUSINESS: RwLock>> = RwLock::new(None); + +/// 登记业务码。幂等:同 code 同元信息重复登记放行;元信息冲突返回 [`RegisterError::Conflict`]。 +pub fn register( + code: i32, + key: &'static str, + message: &'static str, + http: u16, +) -> Result<(), RegisterError> { + if !(BUSINESS_MIN..=BUSINESS_MAX).contains(&code) { + return Err(RegisterError::OutOfRange(code)); + } + if !http_allowed(http) { + return Err(RegisterError::HttpNotAllowed(http)); + } + let mut guard = BUSINESS.write().expect("errcode business registry poisoned"); + let map = guard.get_or_insert_with(HashMap::new); + match map.get(&code) { + Some(existing) + if existing.key == key && existing.message == message && existing.http == http => + { + Ok(()) + } + Some(existing) => Err(RegisterError::Conflict { code, existing_key: existing.key }), + None => { + map.insert(code, ErrCode::new(code, key, message, http)); + Ok(()) + } + } +} + +/// 查码:内建表 → 业务表 → 回退 INTERNAL_ERROR(未登记 code 视为实现缺陷,兜底内部错误语义)。 +pub fn lookup(code: i32) -> ErrCode { + if let Some(c) = BUILTIN.iter().find(|c| c.code == code) { + return *c; + } + if let Ok(guard) = BUSINESS.read() { + if let Some(c) = guard.as_ref().and_then(|m| m.get(&code)) { + return *c; + } + } + INTERNAL_ERROR +} + +/// code 是否已登记(内建或业务段) +pub fn is_registered(code: i32) -> bool { + if BUILTIN.iter().any(|c| c.code == code) { + return true; + } + BUSINESS + .read() + .map(|g| g.as_ref().is_some_and(|m| m.contains_key(&code))) + .unwrap_or(false) +} + +/// rest-conventions.md 业务 API 状态码白名单(对齐 golang httpAllowed) +fn http_allowed(status: u16) -> bool { + matches!(status, 200 | 201 | 400 | 401 | 403 | 404 | 409 | 429 | 500 | 503 | 504) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn ok_constant() { + assert_eq!((OK.code, OK.key, OK.message, OK.http), (0, "OK", "成功", 200)); + } + + #[test] + fn builtin_table_is_unique() { + let mut codes: Vec = BUILTIN.iter().map(|c| c.code).collect(); + let total = codes.len(); + codes.sort_unstable(); + codes.dedup(); + assert_eq!(codes.len(), total, "内建码表存在重复 code"); + let mut keys: Vec<&str> = BUILTIN.iter().map(|c| c.key).collect(); + let ktotal = keys.len(); + keys.sort_unstable(); + keys.dedup(); + assert_eq!(keys.len(), ktotal, "内建码表存在重复 key"); + } + + #[test] + fn unregistered_falls_back_to_internal_error() { + assert!(!is_registered(9999)); + let c = lookup(9999); + assert_eq!((c.code, c.message, c.http), (1000, "内部错误", 500)); + } + + #[test] + fn register_business_code() { + // 测试共享全局表:各测试用不同 code 避免相互污染 + assert!(register(3998, "DEMO_BUSY", "示例繁忙", 409).is_ok()); + // 幂等重登放行 + assert!(register(3998, "DEMO_BUSY", "示例繁忙", 409).is_ok()); + // 元信息冲突拒绝 + assert_eq!( + register(3998, "OTHER", "其他", 409), + Err(RegisterError::Conflict { code: 3998, existing_key: "DEMO_BUSY" }) + ); + let c = lookup(3998); + assert_eq!((c.code, c.key, c.message, c.http), (3998, "DEMO_BUSY", "示例繁忙", 409)); + assert!(is_registered(3998)); + } + + #[test] + fn register_rejects_out_of_range() { + assert_eq!(register(2999, "X", "x", 400), Err(RegisterError::OutOfRange(2999))); + assert_eq!(register(9000, "X", "x", 400), Err(RegisterError::OutOfRange(9000))); + } + + #[test] + fn register_rejects_http_outside_whitelist() { + assert_eq!(register(3997, "X", "x", 204), Err(RegisterError::HttpNotAllowed(204))); + } +} +``` + +- [ ] **Step 5: 跑测试** + +Run: `cd /Users/yuandonghao/sidejob/sources/yarch/stacks/rust && cargo test -p yarch-contract` +Expected: `errcode::tests` 6 项全 PASS。 + +- [ ] **Step 6: 机检** + +Run: `cd /Users/yuandonghao/sidejob/sources/yarch/stacks/rust && cargo fmt --all && cargo clippy --all-targets -- -D warnings` +Expected: fmt 整形无输出;clippy 零告警。 + +- [ ] **Step 7: Commit** + +```bash +git add stacks/rust/crates/yarch-contract +git commit -m "feat(rust): 契约内核 errcode——14 码内建表 + 业务段 3xxx-8xxx 登记(对齐 golang 语义:未登记回退/幂等重登/HTTP 白名单)" -- stacks/rust/crates/yarch-contract +``` + +--- + +### Task 3: response 模块(REST 信封) + +**Files:** +- Modify: `stacks/rust/crates/yarch-contract/src/lib.rs`(加 `pub mod response;`) +- Create: `stacks/rust/crates/yarch-contract/src/response.rs` + +**Interfaces:** +- Consumes: `errcode::OK`、`errcode::lookup` +- Produces: + - `pub struct RestResponse { pub code: i32, pub message: String, pub data: Option, pub trace_id: String }`(serde 序列化 camelCase `traceId`;字段顺序 code→message→data→traceId) + - `RestResponse::ok(data: T, trace_id) / ok_empty(trace_id) / error(code: i32, trace_id) / error_with_message(code, message, trace_id)`——错误路径 `data` 恒 `None` + +- [ ] **Step 1: lib.rs 挂模块** + +```rust +pub mod response; +``` + +- [ ] **Step 2: 创建 `response.rs` 骨架并确认红** + +文件内容 = Step 3 完整文件**去掉四个构造函数体**、其余逐字一致(doc 注释、`RestResponse` 结构 + serde 派生、完整 `mod tests`),四个构造函数先写桩: + +```rust +pub fn ok(data: T, trace_id: impl Into) -> Self { + todo!() +} + +pub fn ok_empty(trace_id: impl Into) -> Self { + todo!() +} + +pub fn error(code: i32, trace_id: impl Into) -> Self { + todo!() +} + +pub fn error_with_message(code: i32, message: impl Into, trace_id: impl Into) -> Self { + todo!() +} +``` + +Run: `cd /Users/yuandonghao/sidejob/sources/yarch/stacks/rust && cargo test -p yarch-contract response` +Expected: 编译通过;response 6 项全部 panic(`not yet implemented`)。 + +- [ ] **Step 3: `response.rs` 完整权威内容(把四个 `todo!()` 桩换成真身)** + +```rust +//! REST 信封(契约内核):四字段 camelCase,`code != 0` 时 `data` 必须为 `null`。 +//! +//! 语义唯一权威 = contract/api/rest-response.md。 + +use serde::{Deserialize, Serialize}; + +use crate::errcode; + +/// 响应信封。字段名 camelCase(traceId 经 serde rename),任何栈不得增删改名。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct RestResponse { + /// 业务码。0 = 成功;非 0 见 errcode 段位表 + pub code: i32, + /// 人类可读文案;不得携带堆栈/内部细节 + pub message: String, + /// 业务负载。code != 0 时必须为 null + pub data: Option, + /// 追踪 ID,恒等于响应头 X-Trace-Id;取不到时为空串 + #[serde(rename = "traceId")] + pub trace_id: String, +} + +impl RestResponse { + /// 成功且带负载 + pub fn ok(data: T, trace_id: impl Into) -> Self { + Self { + code: errcode::OK.code, + message: errcode::OK.message.to_string(), + data: Some(data), + trace_id: trace_id.into(), + } + } + + /// 成功且无负载(data = null) + pub fn ok_empty(trace_id: impl Into) -> Self { + Self { code: errcode::OK.code, message: errcode::OK.message.to_string(), data: None, trace_id: trace_id.into() } + } + + /// 业务失败:message 取码表默认文案;data 恒 None。 + /// 未登记 code 回退 INTERNAL_ERROR(整个信封按 1000 语义出,防止未定义码泄漏)。 + pub fn error(code: i32, trace_id: impl Into) -> Self { + let c = errcode::lookup(code); + Self { code: c.code, message: c.message.to_string(), data: None, trace_id: trace_id.into() } + } + + /// 业务失败 + 覆盖文案(按「默认文案:细节」规则由调用方拼装) + pub fn error_with_message(code: i32, message: impl Into, trace_id: impl Into) -> Self { + let c = errcode::lookup(code); + Self { code: c.code, message: message.into(), data: None, trace_id: trace_id.into() } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[derive(Serialize, Deserialize, PartialEq, Debug)] + struct Payload { + value: i32, + } + + #[test] + fn ok_serializes_to_exact_envelope() { + let resp = RestResponse::ok(Payload { value: 1 }, "0af7651916cd43dd8448eb211c80319c"); + let json = serde_json::to_string(&resp).unwrap(); + assert_eq!( + json, + r#"{"code":0,"message":"成功","data":{"value":1},"traceId":"0af7651916cd43dd8448eb211c80319c"}"# + ); + } + + #[test] + fn error_serializes_data_null() { + let resp: RestResponse = RestResponse::error(1001, "t"); + let json = serde_json::to_string(&resp).unwrap(); + assert_eq!(json, r#"{"code":1001,"message":"参数校验失败","data":null,"traceId":"t"}"#); + } + + #[test] + fn ok_empty_keeps_data_null() { + let resp: RestResponse = RestResponse::ok_empty("t"); + assert_eq!(resp.code, 0); + assert!(resp.data.is_none()); + let json = serde_json::to_string(&resp).unwrap(); + assert_eq!(json, r#"{"code":0,"message":"成功","data":null,"traceId":"t"}"#); + } + + #[test] + fn unregistered_code_falls_back_to_internal_error() { + let resp: RestResponse = RestResponse::error(9999, "t"); + assert_eq!(resp.code, 1000); + assert_eq!(resp.message, "内部错误"); + } + + #[test] + fn error_with_message_overrides() { + let resp: RestResponse = RestResponse::error_with_message(1001, "参数校验失败:pageSize 必须 ≤ 100", "t"); + let json = serde_json::to_string(&resp).unwrap(); + assert_eq!( + json, + r#"{"code":1001,"message":"参数校验失败:pageSize 必须 ≤ 100","data":null,"traceId":"t"}"# + ); + } + + #[test] + fn deserialize_round_trip() { + let resp = RestResponse::ok(Payload { value: 7 }, "tid"); + let json = serde_json::to_string(&resp).unwrap(); + let back: RestResponse = serde_json::from_str(&json).unwrap(); + assert_eq!(back, resp); + } +} +``` + +- [ ] **Step 4: 跑测试** + +Run: `cd /Users/yuandonghao/sidejob/sources/yarch/stacks/rust && cargo test -p yarch-contract` +Expected: errcode 6 + response 6 全 PASS。 + +- [ ] **Step 5: 机检 + Commit** + +Run: `cd /Users/yuandonghao/sidejob/sources/yarch/stacks/rust && cargo fmt --all && cargo clippy --all-targets -- -D warnings` + +```bash +git add stacks/rust/crates/yarch-contract +git commit -m "feat(rust): 契约内核 response——RestResponse 四字段信封(camelCase traceId/错误路径 data 恒 null/未登记码回退 1000)" -- stacks/rust/crates/yarch-contract +``` + +--- + +### Task 4: trace 模块(traceId + traceparent) + +**Files:** +- Modify: `stacks/rust/crates/yarch-contract/src/lib.rs`(加 `pub mod trace;`) +- Create: `stacks/rust/crates/yarch-contract/src/trace.rs` + +**Interfaces:** +- Consumes: 无 +- Produces: + - `pub struct TraceId(String)`:`TraceId::generate()`(32 hex 非全零)、`as_str()`、`Display`、`TraceId::is_valid(s: &str) -> bool` + - `pub struct TraceParent { pub trace_id: String, pub parent_span_id: String }` + - `pub fn parse_traceparent(header: &str) -> Option`(版本 00;非法输入 None) + +- [ ] **Step 1: lib.rs 挂模块** + +```rust +pub mod trace; +``` + +- [ ] **Step 2: 创建 `trace.rs` 骨架并确认红** + +文件内容 = Step 3 完整文件**去掉三个函数体**、其余逐字一致(doc 注释、`TraceId` 结构 + `Display`、`TraceParent`、`is_all_zero`、完整 `mod tests`),三个函数先写桩: + +```rust +impl TraceId { + pub fn generate() -> Self { + todo!() + } + + pub fn as_str(&self) -> &str { + &self.0 + } + + pub fn is_valid(s: &str) -> bool { + todo!() + } +} + +pub fn parse_traceparent(header: &str) -> Option { + todo!() +} +``` + +Run: `cd /Users/yuandonghao/sidejob/sources/yarch/stacks/rust && cargo test -p yarch-contract trace` +Expected: 编译通过;trace 5 项全部 panic(`not yet implemented`)。 + +- [ ] **Step 3: `trace.rs` 完整权威内容(把三个 `todo!()` 桩换成真身)** + +完整权威内容: + +```rust +//! traceId 语义(契约内核):32 hex 生成与 W3C traceparent 解析。 +//! +//! 语义唯一权威 = contract/api/logging-trace.md(W3C traceparent 传播)、 +//! contract/api/rest-response.md(traceId 恒等于响应头 X-Trace-Id)。 + +use rand::Rng; + +/// 32 位小写十六进制 traceId(16 字节)。W3C 规定不得全零。 +#[derive(Debug, Clone, PartialEq, Eq, Hash)] +pub struct TraceId(String); + +impl TraceId { + /// 生成随机 traceId(W3C:非全零 32 hex) + pub fn generate() -> Self { + let v: u128 = rand::rng().random(); + Self(format!("{v:032x}")) + } + + pub fn as_str(&self) -> &str { + &self.0 + } + + /// 校验 32 位小写十六进制(W3C 规定小写,大小写敏感) + pub fn is_valid(s: &str) -> bool { + s.len() == 32 && s.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) + } +} + +impl std::fmt::Display for TraceId { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(&self.0) + } +} + +/// W3C traceparent 解析结果:`00-{trace-id}-{parent-id}-{flags}` +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct TraceParent { + pub trace_id: String, + pub parent_span_id: String, +} + +/// 解析 W3C traceparent 头(版本 00;trace-id 32 hex 非全零;parent-id 16 hex 非全零;flags 2 hex)。 +/// 非法输入返回 None,由调用方决定重新生成或透传。 +pub fn parse_traceparent(header: &str) -> Option { + let parts: Vec<&str> = header.trim().split('-').collect(); + if parts.len() != 4 || parts[0] != "00" { + return None; + } + let (trace_id, parent_span_id, flags) = (parts[1], parts[2], parts[3]); + if !TraceId::is_valid(trace_id) || is_all_zero(trace_id) { + return None; + } + if parent_span_id.len() != 16 + || !parent_span_id.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) + || is_all_zero(parent_span_id) + { + return None; + } + if flags.len() != 2 || !flags.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) { + return None; + } + Some(TraceParent { trace_id: trace_id.to_string(), parent_span_id: parent_span_id.to_string() }) +} + +fn is_all_zero(hex: &str) -> bool { + hex.bytes().all(|b| b == b'0') +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn generated_trace_id_is_32_lowercase_hex() { + let tid = TraceId::generate(); + assert!(TraceId::is_valid(tid.as_str()), "traceId 形状非法: {tid}"); + assert_ne!(tid.as_str(), "00000000000000000000000000000000"); + } + + #[test] + fn generated_trace_ids_differ() { + assert_ne!(TraceId::generate(), TraceId::generate()); + } + + #[test] + fn is_valid_rejects_bad_shapes() { + assert!(!TraceId::is_valid("")); + assert!(!TraceId::is_valid("abc")); + assert!(!TraceId::is_valid("0AF7651916CD43DD8448EB211C80319C")); // 大写拒绝 + assert!(!TraceId::is_valid("0af7651916cd43dd8448eb211c80319")); // 31 位 + assert!(TraceId::is_valid("0af7651916cd43dd8448eb211c80319c")); + } + + #[test] + fn parses_valid_traceparent() { + let tp = parse_traceparent("00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01").unwrap(); + assert_eq!(tp.trace_id, "0af7651916cd43dd8448eb211c80319c"); + assert_eq!(tp.parent_span_id, "00f067aa0ba902b7"); + // 首尾空白容忍 + assert!(parse_traceparent(" 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01 ").is_some()); + } + + #[test] + fn rejects_invalid_traceparent() { + let cases = [ + "", // 空 + "0af7651916cd43dd8448eb211c80319c", // 非 traceparent 形态 + "ff-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01", // 非 00 版本 + "00-00000000000000000000000000000000-00f067aa0ba902b7-01", // 全零 trace-id + "00-0af7651916cd43dd8448eb211c80319-00f067aa0ba902b7-01", // 31 位 trace-id + "00-0af7651916cd43dd8448eb211c80319c-0000000000000000-01", // 全零 parent-id + "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-1", // 1 位 flags + "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-xyz", // flags 非法字符 + ]; + for case in cases { + assert!(parse_traceparent(case).is_none(), "应拒绝: {case}"); + } + } +} +``` + +- [ ] **Step 4: 跑测试 + 机检** + +Run: `cd /Users/yuandonghao/sidejob/sources/yarch/stacks/rust && cargo test -p yarch-contract && cargo fmt --all && cargo clippy --all-targets -- -D warnings` +Expected: errcode 6 + response 6 + trace 5 全 PASS;机检绿。 + +- [ ] **Step 5: Commit** + +```bash +git add stacks/rust/crates/yarch-contract +git commit -m "feat(rust): 契约内核 trace——TraceId 32 hex 生成 + W3C traceparent 解析(版本 00/非全零/小写严格)" -- stacks/rust/crates/yarch-contract +``` + +--- + +### Task 5: 同源 conformance 断言(tests/conformance.rs) + +**Files:** +- Create: `stacks/rust/crates/yarch-contract/tests/conformance.rs` + +**Interfaces:** +- Consumes: `errcode::BUILTIN`、`errcode::OK`、`errcode::lookup`、`errcode::is_registered` +- Produces: 无(纯测试;CI 必跑、独立环境缺 dist 优雅跳过) + +- [ ] **Step 1: 写 `tests/conformance.rs`** + +```rust +//! 同源断言:内建码表的唯一机器可读权威 = contract/dist/error-codes.json +//! (由 contract/api/error-codes.md 派生,contract-dist CI 拒双向漂移)。 +//! dist 不在场(消费方独立测试环境)则跳过;仓内 CI 必跑(P1 契约机器可读出口口径, +//! 与 golang/java/python/web 四栈 conformance 同表)。 + +use serde::Deserialize; +use yarch_contract::errcode; + +#[derive(Deserialize)] +struct DistRow { + code: i32, + key: String, + message: String, + http: u16, +} + +#[derive(Deserialize)] +struct DistSuccess { + code: i32, + message: String, +} + +#[derive(Deserialize)] +struct Dist { + success: DistSuccess, + codes: Vec, +} + +fn load_dist() -> Option { + let raw = std::fs::read_to_string("../../../../contract/dist/error-codes.json").ok()?; + Some(serde_json::from_str(&raw).expect("dist json 解析失败")) +} + +#[test] +fn ok_matches_dist_success() { + let Some(dist) = load_dist() else { + println!("contract dist json 不在场,跳过同源断言"); + return; + }; + assert_eq!( + (errcode::OK.code, errcode::OK.message), + (dist.success.code, dist.success.message.as_str()) + ); +} + +#[test] +fn builtin_table_matches_dist_codes() { + let Some(dist) = load_dist() else { + println!("contract dist json 不在场,跳过同源断言"); + return; + }; + // 双向对表(不硬编码码数——加码只改 md + dist + 内建表三处,本测试零改): + // dist 每行都在内建表中且元数据全等;内建表除 OK 外无多余行 + let builtin_rows = errcode::BUILTIN.iter().filter(|c| c.code != 0).count(); + assert_eq!(dist.codes.len(), builtin_rows, "内建码表与 dist 行数不一致(漂移)"); + for row in &dist.codes { + let c = errcode::lookup(row.code); + assert!(errcode::is_registered(row.code), "code {} 在内建表中缺失", row.code); + assert_eq!( + (c.code, c.key, c.message, c.http), + (row.code, row.key.as_str(), row.message.as_str(), row.http), + "code {} 元数据与 dist 不一致", + row.code + ); + } +} +``` + +- [ ] **Step 2: 跑测试(本地 dist 在场,必跑真断言)** + +Run: `cd /Users/yuandonghao/sidejob/sources/yarch/stacks/rust && cargo test -p yarch-contract --test conformance` +Expected: 2 项 PASS(本地工作树 dist = 14 码 + success)。 + +- [ ] **Step 3: 全量 + 机检 + Commit** + +Run: `cd /Users/yuandonghao/sidejob/sources/yarch/stacks/rust && cargo test --workspace && cargo fmt --all && cargo clippy --all-targets -- -D warnings` + +```bash +git add stacks/rust/crates/yarch-contract/tests/conformance.rs +git commit -m "test(rust): 契约内核 conformance 同源断言——14 码对表 contract/dist/error-codes.json(缺场优雅跳过,双向零硬编码行数)" -- stacks/rust/crates/yarch-contract/tests/conformance.rs +``` + +--- + +### Task 6: CI workflow(rust-stack.yml 四段门禁 + MSRV 双档) + +**Files:** +- Create: `.github/workflows/rust-stack.yml` +- Modify: `stacks/rust/PLAN.md`(五、施工批次——第一批标记完成) + +**Interfaces:** +- Consumes: Task 1-5 全部产物 +- Produces: CI 门禁 `rust-stack`(push main/dev + PR,paths 过滤 `stacks/rust/**`) + +- [ ] **Step 1: 写 `.github/workflows/rust-stack.yml`** + +```yaml +name: rust-stack + +# rust 栈 CI:四段门禁(fmt / clippy -D warnings / cargo-deny / test,spec 九-1)+ MSRV 双档(R7)。 +# 模板生成后冒烟(spec 九-3)待批次二模板落地后追加 job。 +# conformance 测试读仓内 contract/dist/error-codes.json(提交态在场,contract-dist 门拒漂移)。 + +on: + push: + branches: [main, dev] + paths: ['stacks/rust/**', '.github/workflows/rust-stack.yml'] + pull_request: + paths: ['stacks/rust/**', '.github/workflows/rust-stack.yml'] + +jobs: + check: + name: Rust ${{ matrix.toolchain }} · 四段门禁 + strategy: + fail-fast: false + matrix: + # R7:stable + MSRV 1.80 双档(dtolnay 动作以 RUSTUP_TOOLCHAIN 覆盖 rust-toolchain.toml) + toolchain: [stable, '1.80'] + runs-on: ubuntu-latest + defaults: + run: + working-directory: stacks/rust + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@master + with: + toolchain: ${{ matrix.toolchain }} + components: rustfmt, clippy + - uses: Swatinem/rust-cache@v2 + with: + workspaces: stacks/rust/Cargo.toml + - run: cargo fmt --all -- --check + - run: cargo clippy --all-targets -- -D warnings + - run: cargo test --workspace + + deny: + name: cargo-deny · 依赖审计 + runs-on: ubuntu-latest + defaults: + run: + working-directory: stacks/rust + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + - uses: taiki-e/install-action@cargo-deny + - run: cargo deny check +``` + +- [ ] **Step 2: 本地 YAML 语法机检(仓有 workflow YAML 暗雷史)** + +Run: `ruby -ryaml -e 'YAML.load_file("/Users/yuandonghao/sidejob/sources/yarch/.github/workflows/rust-stack.yml"); puts "yaml ok"'` +Expected: `yaml ok`。 + +- [ ] **Step 3: PLAN.md 批次一标记完成** + +`stacks/rust/PLAN.md` 五、施工批次第 1 条改为(追加状态): + +```markdown +1. **第一批(已完成 2026-09-18)**:spec.md 成文 + PLAN.md 落位 + workspace 骨架(两 crate + 契约内核 response/errcode/trace 三模块 + 同源 conformance 断言读 contract/dist)——本地 cargo test/fmt/clippy 绿,CI rust-stack.yml 四段门禁 + MSRV 双档。 +``` + +- [ ] **Step 4: Commit** + +```bash +git add .github/workflows/rust-stack.yml stacks/rust/PLAN.md +git commit -m "ci(rust): rust-stack 四段门禁(fmt/clippy/deny/test + stable/1.80 双档矩阵)——批次一收口" -- .github/workflows/rust-stack.yml stacks/rust/PLAN.md +``` + +- [ ] **Step 5: 触发 CI 验证(用户授权 push 后)** + +Run: `git push origin dev`(经用户确认后执行;或用户自行 push) +Expected: GitHub Actions `rust-stack` workflow 两 job 全绿;1.80 档若因依赖 MSRV 红则按红线预案处理(见下)。 + +**已知风险与预案**:1.80 档可能因 `serde_json`/`rand` 新版本 MSRV 高于 1.80 而红。预案:在 `[workspace.dependencies]` 钉下界(如 `serde_json = "~1.0.128"`、`rand = "~0.9.1"`)后重试;仍红则在 Cargo.toml 加 `[workspace.package]` 之外单独说明并上报用户决策(R7 的 MSRV 是拍板项,不擅自降档)。 + +--- + +## 收尾(本计划 DoD) + +1. `cd stacks/rust && cargo test --workspace` 全绿(errcode 6 + response 6 + trace 5 + conformance 2 = 19 项); +2. `cargo fmt --all -- --check` + `cargo clippy --all-targets -- -D warnings` 绿; +3. CI `rust-stack` 两 job 绿(含 MSRV 1.80 档); +4. 全部提交走 pathspec,工作树验证码批文件零触碰。 + +后续计划(依本批真实 crate 形状再写):批次二(yarch-axum 中间件五件 + sqlx 装配 + cargo-generate 模板,需先 `cargo install cargo-generate`);批次 0 registry 登记 ycomp(验证码批提交后);SP1 组件库(CL1-CL6 拍板先行)。 diff --git a/docs/superpowers/specs/2026-09-18-ycomp-component-platform-design.md b/docs/superpowers/specs/2026-09-18-ycomp-component-platform-design.md new file mode 100644 index 0000000..16891c2 --- /dev/null +++ b/docs/superpowers/specs/2026-09-18-ycomp-component-platform-design.md @@ -0,0 +1,167 @@ +# ycomp 组件资产平台设计(2026-09-18) + +> 状态:设计定稿(本对话四节逐节确认),待用户终审。本文是后续 `contract/web/component-library.md` 契约决策清单的底稿与三个子工程的施工总纲。 +> 编号口径:CL* = 组件库契约决策清单项(成文前须正式拍板);SP* = 子工程批次。 + +## 一、背景与目标 + +用户要在 yarch 规约体系之上建一个**前端组件资产平台**(重平台形态:登记 / 版本管理 / 在线预览 / 使用追踪),服务于个人名下各系统(ysaas、ybookreading、microduck 及后续工程)的构建复用。平台本身是 **yarch 首个完整 dogfood 消费工程**,同时充当 **rust 云栈的触发工程**。 + +**边界(明确不做)**:不做分发(npm `@yarch` org 是唯一分发通道)、不做构建流水线(预览零构建)、不做多租户/多贡献者(个人自用)、不做私有 registry、**不自建认证/用户体系(后续接 ysaas 平台 SSO,触发式——届时再立决策清单)**。 + +## 二、拍板记录(2026-09-18 本对话) + +| # | 议题 | 结论 | +|---|---|---| +| D1 | 平台形态 | 组件资产平台(重平台):登记 + 预览 + 同步 + 追踪 | +| D2 | 受众 | 个人自用;**无认证/用户体系(后续接 ysaas SSO,触发式)**、无多租户与权限分级 | +| D3 | 资产范围 | React 业务组件、Vue 业务组件、design token/主题包、页面模板/区块(四类全管) | +| D4 | UI 档关系 | 按框架各选生态:React → antd v5;Vue → ElementPlus。微前端「档唯一」仅约束单体系内部,不约束组件库 | +| D5 | 分发通道 | 公共 npm `@yarch` org;平台只管元数据/预览/检索,不碰分发 | +| D6 | 仓归属 | 组件包进 yarch `stacks/web/packages/`;平台独立仓,与 yarch 同级(`/Users/yuandonghao/sidejob/sources/ycomp/`),结构参考 ysaas(frontend/backend/docs/AGENTS.md) | +| D7 | 平台后端栈 | Rust(用户指定,兼作 rust 栈触发工程);先施工 `stacks/rust` 批次一/二,模板/发版流水线(批次三)后置,平台以 git tag 依赖两 crate | +| D8 | 首批交付范围 | 闭环 + 自动同步 + 使用追踪(登记 → 同步 → 预览 → 追踪 → 总览全链路) | +| D9 | 平台技术核心 | 方案 A 轻运行时:元数据服务 + iframe 沙箱 esm.sh import map 运行时预览 + npm registry 轮询同步 + lockfile 扫描追踪 | + +## 三、工程结构与命名 + +### 三个子工程 + +| 子工程 | 位置 | 内容 | 依赖 | +|---|---|---|---| +| SP0 · rust 栈施工 | yarch `stacks/rust/` | 批次一/二:契约内核 + axum 装配 + 中间件五件 + sqlx 装配 + cargo-generate 模板 | 无(前置) | +| SP1 · 组件库首批包 | yarch `stacks/web/packages/` | `@yarch/tokens` + `@yarch/pro-react` + 预览约定 | SP0 无关(可与 SP0 并行) | +| SP2 · ycomp 平台 | 独立仓 `sources/ycomp/` | rust 后端 + admin 前端 + 沙箱 + 同步/追踪 | SP0(crate 依赖)、SP1(预览货物) | + +### ycomp 仓结构(对齐 ysaas) + +``` +sources/ycomp/ +├── frontend/ # npm create @yarch/admin --ui antd 产出;页面:资产列表/包详情/预览沙箱/登记/同步管理/usage 总览 +├── backend/ # cargo generate 产出的 rust 服务(DDD 七包)+ Dockerfile + .env(.example) +├── docs/ # requirements / architecture / plans / waivers / errno.md(3xxx 错误码段登记) +└── AGENTS.md # yarch agent 规约同款工程守则 +``` + +### 命名与登记(registry 校验通过,实施批次 0 正式登记) + +- 服务名 `ycomp`(格式 `^[a-z][a-z0-9-]{1,31}$`、非裸通用词)→ registry 二节登记;共享 PG 新库 `ycomp`(库名=服务名,一应用一库);**不启用** Redis(元数据服务无需缓存层) +- 前端应用名 `ycomp-console`(首段=已登记服务名)→ registry 四节登记;单应用非微前端(规约一-4「不得为微前端而微前端」) +- 组件包:`@yarch/tokens`、`@yarch/pro-react`(首批);`@yarch/pro-vue`、页面区块包(二批) + +## 四、SP0 · rust 栈最小施工范围 + +严格按 `stacks/rust/PLAN.md` 已拍板批次,平台需要什么先立什么: + +1. **批次一**:cargo workspace 两 crate 空壳 + `yarch-contract`(response/errcode/trace 三模块)+ 13 码全表断言(同源读 `contract/dist/error-codes.json`,对齐四栈 conformance)——`cargo test` 绿。 +2. **批次二**:`yarch-axum` 中间件五件(Trace/Recovery/AccessLog/Idempotency/Rate,对照 python `test_middleware_composition.py` 逐条翻译)+ sqlx 装配(分页/逻辑删除)+ `templates/service/`(DDD 七包 + users 示例)。 +3. **批次三后置**:crates.io 发版流水线、MSRV 双档矩阵不挡平台——平台以 git tag 依赖引用两 crate,发版后切 crates.io。 +4. CI 基本盘(cargo test / clippy -D warnings / rustfmt --check)在 SP0 内即须绿,否则 DoD 不成立。 + +## 五、SP1 · 组件库首批包与预览约定 + +### `@yarch/tokens`(框架无关) + +- 载体:CSS custom properties + 机器可读 `tokens.json`(色板/字体/间距/圆角/阴影 + 暗色模式集,token 心法对齐 HI UI 5.0 经验)+ TS 常量导出。 +- 定位:web/小程序/游戏三端共享 design token 的落点,接 clients 规约「跨形态复用走共享层(design token)」条文。 + +### `@yarch/pro-react`(antd v5 基线)首批 CRUD 三件套 + +- **ProTable**:查询表单 + 表格 + 分页一体,直接消费 `@yarch/contract` 的 `ListData` 分页信封。 +- **ProForm**:查询/编辑表单;错误码 → 校验态映射。 +- **useApiQuery / useApiMutation**:信封解包 / 错误码 / traceId 透传的 React hooks。 +- 每组件携带 **demo manifest**(预览约定载体,候选形态见 CL1)。 +- 发版走既有 tag→npm 管道(web-publish.yml 同款链路)。 +- 模板侧后置一步:`create-admin` antd 档预装 `@yarch/pro-react`(新工程开箱即用)。 + +### 预览约定(新契约 `contract/web/component-library.md` 核心条文候选) + +- demo manifest(CL1 定形态):每个资产包自带可预览元数据(demo 列表:标题/描述/源码/入口),平台沙箱统一解释。 +- tokens.json schema(CL2 定结构):tokens 类资产的机器可读约定,平台通用渲染器直接消费。 +- import map / esm.sh 属平台实现细节,**不入条文**(条文只约束资产包自带什么,不管平台怎么渲染)。 + +## 六、SP2 · ycomp 平台系统设计(方案 A) + +### 形态与部署 + +- rust axum 单体(cargo generate 产出,DDD 七包)+ sqlx + 共享 PG 库 `ycomp`。 +- **单二进制**:rust-embed 内嵌 frontend/dist(tower-http ServeDir + history 路由 fallback),systemd 或 docker 部署 yuandonghao-linux;Dockerfile 多阶段(cargo release 构建 + 静态资源 + slim runtime)。 +- **无认证暴露面**:服务只绑内网地址或反代限内网访问(不公网裸奔);ysaas SSO 接入前保持此口径。 +- 观测 = tracing + ndjson(rust 栈中间件自带 AccessLog/Trace),prometheus 触发式后置。 + +### 数据模型(postgresql.md 口径:snake_case/单数表/`is_` 布尔/timestamptz/逻辑删除) + +| 表 | 要点 | +|---|---| +| `package` | npm_name 唯一;kind(component/token/block);framework(react/vue/none);ecosystem(antd/element-plus/none);title/description/repo_url | +| `package_version` | version、dist_tag、manifest jsonb、readme_md、published_at、synced_at | +| `consumer_repo` | name、git_url、branch、is_active、last_scan_at、last_scan_status | +| `package_usage` | 当前态使用关系(repo × 包 × 锁定版本 + 来源 package.json/lockfile),扫描 upsert | +| `sync_run` / `scan_run` | 两 job 审计流水(起止/增量/错误) | + +### API(REST 四件套口径:信封 + 错误码 + traceId;错误码 3xxx 段登记 ycomp/docs/errno.md) + +- 认证:**无**(见一、边界;后续 ysaas SSO 接入为触发项)。 +- 包:`POST /api/v1/packages`(登记 npm 包名,首次即拉元数据)、`GET /api/v1/packages`(kind/framework/关键词筛选,keyset 分页)、`GET /api/v1/packages/{id}`、`GET /api/v1/packages/{id}/versions`、`GET .../versions/{version}`。 +- 仓:`POST /api/v1/repos`、`GET /api/v1/repos`、`GET /api/v1/repos/{id}`(含 usage)。 +- 触发:`POST /api/v1/syncs/npm`、`POST /api/v1/scans/repo`(手动按钮同 job 逻辑)。 +- 总览:`GET /api/v1/usage/overview`(包 × 系统 × 锁定版本矩阵——升级影响面板)。 +- `GET /healthz`。 + +### 同步 job(tokio 定时小时级 + 手动) + +登记包名集合 → `GET registry.npmjs.org/{name}` → diff versions vs 库 → 落 `package_version` + 拉 README;幂等 upsert;reqwest + tracing。 + +### 追踪 job(日级 + 手动) + +浅 clone 各 active consumer_repo(https + PAT 环境变量;clone 缓存挂卷避免全量重拉)→ 解析 package.json(直接依赖)+ pnpm-lock.yaml(锁定版本)中的 `@yarch/*` → upsert `package_usage` + `scan_run` 流水。 + +### 预览沙箱(平台灵魂) + +- 前端路由 `/preview/:pkg/:version/:demo` → iframe `sandbox="allow-scripts"`(禁同源、无 cookie 访问)。 +- iframe 内动态生成 import map:react/react-dom/antd/dayjs 按**该版本 manifest 的 peerDeps** 解析到 esm.sh 固定版本 → import 包的 demos 入口 → 渲染 demo。 +- tokens 类资产走平台内置通用 token 渲染器(直接读 tokens.json,无需运行时)。 +- 降级:esm.sh 不可达 → 预览页报错 + npmjs 外链,元数据功能不受影响。 +- 预览对象是自家公共 npm 包,攻击面小;sandbox 属性兜底。 + +### 平台前端自举 + +`npm create @yarch/admin --ui antd` 产出(布局/CRUD 范式现成;**模板登录流剔除**——暂无认证,接入路由直进),console 自身消费 `@yarch/pro-react` 管理包元数据——组件库第零号消费者,狗粮闭环。 + +## 七、组件库契约决策清单(成文前须正式拍板) + +| # | 议题 | 倾向 | +|---|---|---| +| CL1 | demo manifest 形态 | 包导出 `demos` 入口(含源码字符串,沙箱运行时读取)vs 根目录 `demos/` 随包发布文件;倾向导出入口(类型安全 + 无文件 IO) | +| CL2 | tokens.json schema | 分组结构(color/typography/spacing/radius/shadow + 暗色模式集)与命名口径 | +| CL3 | 包命名定稿 | `@yarch/pro-react` / `@yarch/tokens` / 二批 `@yarch/pro-vue`;区块包命名后议 | +| CL4 | 预览约定条文边界 | manifest/tokens schema 入条文;import map/esm.sh 留实现细节 | +| CL5 | 模板预装策略 | `create-admin` antd 档预装 `@yarch/pro-react` 的版本锚定方式 | +| CL6 | 基线库锁定条文 | React=antd v5、Vue=ElementPlus 是否入 `component-library.md` 成文(延伸 W1 UI 档口径) | + +## 八、施工顺序与 DoD + +``` +批次 0:本文终审 → registry 登记(ycomp / ycomp-console)+ README 决策表 +批次 1(SP0-一):yarch-contract 内核 + 13 码断言 DoD:cargo test 绿 +批次 2(SP0-二):yarch-axum 五中间件 + sqlx + 模板 DoD:cargo test/clippy/rustfmt 绿 + 模板生成冒烟 + ∥(SP1):CL1-CL6 拍板 → component-library.md 成文 → tokens + pro-react 三件套 + DoD:pnpm test 绿 + 包可发版 +批次 3(SP2-骨架):cargo generate ycomp 仓 + PG 库 + 迁移 DoD:healthz + 包登记 API 闭环 +批次 4(SP2-API/jobs):包/仓/版本 API + 同步 job + 追踪 job DoD:集成测试(真实 PG)绿 +批次 5(SP2-前端/沙箱):console 页面 + 预览沙箱 + usage 总览 DoD:端到端剧本绿 +批次 6(部署):单二进制内嵌前端 → yuandonghao-linux 上线 DoD:curl healthz + 预览可访问 +``` + +端到端验收剧本:登记 `@yarch/pro-react` → 同步出版本 → 预览能渲染 ProTable demo → 登记 ysaas 仓 → 扫描出 usage → 总览面板可见锁定版本。 + +## 九、风险与观察哨 + +| 风险 | 预案 | +|---|---| +| esm.sh 第三方 CDN 可用性 | 降级不致命(预览报错 + 外链);观察哨:连续不可用再评估自举 CDN 或快照方案(方案 B 退路) | +| rust 栈施工超预期(async 上下文/tower 版本矩阵) | PLAN 已列;平台后端如被阻塞可临时以更薄手写 axum 骨架先行、回头对齐(须登记 waiver) | +| 追踪 job clone 凭证管理 | PAT 走环境变量;只读最小权限 token | +| 服务无认证被公网暴露 | 只绑内网/反代限内网;接入 ysaas SSO 前不公网开放 | +| sqlx 离线 CI 校验 | 预置 `.sqlx/` 快照(PLAN 七-1) | +| 组件库与平台互相等待 | SP1 与 SP0 并行;沙箱开发期可用本地 mock manifest 先行 | diff --git a/stacks/golang/PLAN.md b/stacks/golang/PLAN.md index d08ab04..33a860f 100644 --- a/stacks/golang/PLAN.md +++ b/stacks/golang/PLAN.md @@ -94,6 +94,8 @@ stacks/golang/ # module github.com/ydonghao/yarch/stacks/go **触发式增长(一规约一 package,不做配置档)**:mysql 档(`persist/mysql`)、kafka、rocketmq、xxl-job、nacos、minio、es、qdrant、wire 组装校验、`yarch init`。 +**captcha 契约对齐(2026-09-18,contract/api/captcha.md v1.0 CP1-CP10 落地)**:五处漂移清偿——长度 5→4、TTL 默认 5min→120s(Options.TTL 可配)、端点字段 id/image→provider/key/imageBase64(裸 base64 去 data: 前缀)、存储 key 加 provider 段(`{服务名}:captcha:{provider}:{key}`,Service 经 redix.Keys 生成)、校验失败 1001→2005 CAPTCHA_INVALID;**SPI 化**:Provider 接口(ID/Mode/Issue/Matches + RemoteVerifier 小接口)+ 框架核心 Service(GETDEL 原子消费/场景路由 Options.Scenes+DefaultProvider/装配 fail fast)+ 三档 Provider(image/SmsOtpProvider 宿主 SmsSender 注入+目标脱敏/TurnstileProvider SiteVerifyCaller 打桩+fail-closed);Handler.Issue 端点(scene 参数,非 image 档 1001,限流由业务注册时挂 middleware.RateLimit/RateLimitRedis——契约五-1);测试向量 V1-V11 同源落地(含 8 goroutine 并发恰一过)+ TC 真 Redis 行为级(V6/V7/key 形状)。 + ## 七、开放问题与风险 1. Hertz 中间件修改请求 ctx:用 `c.SetCtx` 注入 context value,同时 `c.Set` 双写(handler 两种取法都命中)——已验证 API 存在于 v0.10.x。 diff --git a/stacks/golang/captcha/captcha.go b/stacks/golang/captcha/captcha.go index 345efa9..046c9b6 100644 --- a/stacks/golang/captcha/captcha.go +++ b/stacks/golang/captcha/captcha.go @@ -1,36 +1,39 @@ -// Package captcha 图形验证码(对偶 java yarch-captcha-starter): -// 生成 PNG + Redis 一次性 token(校验即消费,TTL 默认 5 分钟)。 -// 标准 GET /api/v1/captcha 端点由 Handler 提供(契约 java 侧同路径)。 +// Package captcha 验证码框架(contract/api/captcha.md v1.0): +// Provider SPI 三档(image/sms-otp/turnstile)+ 框架核心(challenge 生命周期一次性原子消费、 +// 场景路由、错误语义 2005)。标准 GET /api/v1/captcha 端点由 Handler 提供(六-1), +// 校验内联业务流不设独立端点(六-2)。 package captcha import ( + "bytes" "context" "crypto/rand" + "encoding/base64" "errors" "image" "image/color" "image/png" - "bytes" - "encoding/base64" "math/big" + "strings" "time" + "github.com/redis/go-redis/v9" + "golang.org/x/image/font" "golang.org/x/image/font/basicfont" "golang.org/x/image/math/fixed" - - "github.com/redis/go-redis/v9" ) // Store 验证码存储接口(一次性 token 语义)。 type Store interface { // Issue 签发:id → code,TTL。 Issue(ctx context.Context, id, code string, ttl time.Duration) error - // Consume 原子取出并删除(一次性):id 不存在或已消费返回 false。 + // Consume 原子取出并删除(一次性,三-3/三-4):id 不存在或已消费返回 false。 Consume(ctx context.Context, id string) (string, bool, error) } -// RedisStore Redis 实现(key 由调用方经 redix.Keys 生成,首段=服务名)。 +// RedisStore Redis 实现(full key 由框架核心 Service 经 redix.Keys 生成: +// 服务名:captcha:{provider}:{key},首段=服务名纪律三-5)。 type RedisStore struct{ rdb redis.UniversalClient } func NewRedisStore(rdb redis.UniversalClient) *RedisStore { return &RedisStore{rdb: rdb} } @@ -39,7 +42,7 @@ func (s *RedisStore) Issue(ctx context.Context, id, code string, ttl time.Durati return s.rdb.Set(ctx, id, code, ttl).Err() } -// Consume GETDEL 原子取出删除——一次性保证(校验失败同样消费,防重放爆破)。 +// Consume GETDEL 原子取出删除——一次性保证(校验失败同样消费,防重放爆破三-3)。 func (s *RedisStore) Consume(ctx context.Context, id string) (string, bool, error) { code, err := s.rdb.GetDel(ctx, id).Result() if errors.Is(err, redis.Nil) { @@ -51,19 +54,19 @@ func (s *RedisStore) Consume(ctx context.Context, id string) (string, bool, erro return code, true, nil } -// alphabet 去混淆字符集(剔除 0O1I)。 +// alphabet 去混淆字符集(二-2【强制】:32 字符,去 0/O/1/I——跨栈 conformance 断言对象)。 const alphabet = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ" const ( - // DefaultLen 验证码字符数。 - DefaultLen = 5 - // DefaultTTL 有效期。 - DefaultTTL = 5 * time.Minute - // W/H 图片尺寸。 + // DefaultLen 验证码字符数(二-2【强制】:4 位)。 + DefaultLen = 4 + // DefaultTTL 有效期默认(三-2【推荐】120s,Options.TTL 可配)。 + DefaultTTL = 2 * time.Minute + // W/H 图片尺寸(渲染样式自由,CP9)。 W, H = 160, 48 ) -// NewCode 生成随机码。 +// NewCode 生成随机码(安全随机源,三-1 同源要求)。 func NewCode(n int) string { b := make([]byte, n) for i := range b { @@ -73,7 +76,7 @@ func NewCode(n int) string { return string(b) } -// NewID 生成验证码 ID。 +// NewID 生成验证码 ID(16 字节安全随机 hex = 128 bit 熵,三-1:禁业务可预测值)。 func NewID() string { var b [16]byte _, _ = rand.Read(b[:]) @@ -102,33 +105,46 @@ func RenderPNG(code string) []byte { // 干扰线 for i := 0; i < 3; i++ { c := color.RGBA{R: uint8(randInt(180)), G: uint8(randInt(180)), B: uint8(randInt(180)), A: 120} - x, y := randInt(W), randInt(H) + _, y := randInt(W), randInt(H) for s := 0; s < W; s += 3 { img.Set(s, (y+s/2+randInt(5))%H, c) - _ = x } } // 字符 for i := 0; i < len(code); i++ { - drawChar(img, rune(code[i]), 12+i*28+randInt(6), 26+randInt(8), rgb()) + drawChar(img, rune(code[i]), 24+i*32+randInt(6), 30+randInt(8), rgb()) } var buf bytes.Buffer _ = png.Encode(&buf, img) return buf.Bytes() } -// ImageDataURL PNG → data URL(前端 直用)。 -func ImageDataURL(pngBytes []byte) string { - return "data:image/png;base64," + base64.StdEncoding.EncodeToString(pngBytes) +// ImageBase64 PNG → 裸 base64(二-2/六-1:无 data: 前缀,前端自行拼装 dataURL)。 +func ImageBase64(pngBytes []byte) string { + return base64.StdEncoding.EncodeToString(pngBytes) } -// Verify 校验(大小写不敏感;无论对错 token 均已一次性消费)。 -func Verify(ctx context.Context, s Store, id, input string) bool { - code, ok, err := s.Consume(ctx, id) - if err != nil || !ok { +// trimSpace 去首尾空白(比对口径,二-2)。 +func trimSpace(s string) string { return strings.TrimSpace(s) } + +// equalFold ASCII 大小写不敏感比较(二-2)。 +func equalFold(a, b string) bool { + if len(a) != len(b) { return false } - return equalFold(code, input) + for i := 0; i < len(a); i++ { + ca, cb := a[i], b[i] + if 'A' <= ca && ca <= 'Z' { + ca += 32 + } + if 'A' <= cb && cb <= 'Z' { + cb += 32 + } + if ca != cb { + return false + } + } + return true } // drawChar 用 font.Drawer + basicfont.Face7x13 绘制单字符。 @@ -152,22 +168,3 @@ func gray() color.RGBA { return color.RGBA{R: 170, G: 170, B: 170, A: 255} } func rgb() color.RGBA { return color.RGBA{R: uint8(40 + randInt(120)), G: uint8(40 + randInt(120)), B: uint8(40 + randInt(120)), A: 255} } - -func equalFold(a, b string) bool { - if len(a) != len(b) { - return false - } - for i := 0; i < len(a); i++ { - ca, cb := a[i], b[i] - if 'A' <= ca && ca <= 'Z' { - ca += 32 - } - if 'A' <= cb && cb <= 'Z' { - cb += 32 - } - if ca != cb { - return false - } - } - return true -} diff --git a/stacks/golang/captcha/captcha_test.go b/stacks/golang/captcha/captcha_test.go index 264d5c7..3f374f9 100644 --- a/stacks/golang/captcha/captcha_test.go +++ b/stacks/golang/captcha/captcha_test.go @@ -7,6 +7,8 @@ import ( "encoding/json" "image/png" "log/slog" + "strings" + "sync" "testing" "time" @@ -14,103 +16,373 @@ import ( "github.com/cloudwego/hertz/pkg/common/ut" "github.com/ydonghao/yarch/stacks/golang/captcha" + "github.com/ydonghao/yarch/stacks/golang/errcode" + "github.com/ydonghao/yarch/stacks/golang/middleware" + "github.com/ydonghao/yarch/stacks/golang/redix" ) -// memStore 内存实现(Redis 行为级集成在 testcontainers 子 module)。 -type memStore struct{ m map[string]string } +// atomicMemStore 并发安全内存实现(Redis 行为级在 testcontainers 子 module)。 +// Consume 加锁取出即删——为 V6 提供原子语义底座。 +type atomicMemStore struct { + mu sync.Mutex + m map[string]string + tt map[string]time.Duration +} + +func newMemStore() *atomicMemStore { + return &atomicMemStore{m: map[string]string{}, tt: map[string]time.Duration{}} +} -func (s *memStore) Issue(ctx context.Context, id, code string, ttl time.Duration) error { +func (s *atomicMemStore) Issue(ctx context.Context, id, code string, ttl time.Duration) error { + s.mu.Lock() + defer s.mu.Unlock() s.m[id] = code + s.tt[id] = ttl return nil } -func (s *memStore) Consume(ctx context.Context, id string) (string, bool, error) { + +func (s *atomicMemStore) Consume(ctx context.Context, id string) (string, bool, error) { + s.mu.Lock() + defer s.mu.Unlock() c, ok := s.m[id] delete(s.m, id) return c, ok, nil } -// 端点断言:200 信封 + id/image 字段 + image 是合法 PNG 的 dataURL。 -func TestHandlerIssue(t *testing.T) { - store := &memStore{m: map[string]string{}} - h := server.Default(server.WithHostPorts(":0")) +func (s *atomicMemStore) keys() []string { + s.mu.Lock() + defer s.mu.Unlock() + out := make([]string, 0, len(s.m)) + for k := range s.m { + out = append(out, k) + } + return out +} + +// fakeSmsSender V8:捕获发送(目标, 内容)。 +type fakeSmsSender struct { + mu sync.Mutex + sent [][2]string +} + +func (f *fakeSmsSender) Send(destination, content string) error { + f.mu.Lock() + defer f.mu.Unlock() + f.sent = append(f.sent, [2]string{destination, content}) + return nil +} + +func (f *fakeSmsSender) last() (string, string) { + f.mu.Lock() + defer f.mu.Unlock() + pair := f.sent[len(f.sent)-1] + return pair[0], pair[1] +} + +// stubCaller V9:turnstile siteverify 打桩。 +type stubCaller struct{ ok bool } + +func (s stubCaller) Call(verifyURL, secret, response, remoteIP string) bool { return s.ok } + +// newSvc 构造测试 Service(存储 key 形状断言用 redix.NewKeys 真实服务名纪律)。 +func newSvc(t *testing.T, store captcha.Store, opts captcha.Options) *captcha.Service { + t.Helper() + keys, err := redix.NewKeys("mysvc") + if err != nil { + t.Fatalf("NewKeys: %v", err) + } + svc, err := captcha.NewService(store, keys, opts) + if err != nil { + t.Fatalf("NewService: %v", err) + } + return svc +} + +// V1/V2/V3/V4/V5:image 档生命周期——一次性、失败同消费、trim + 大小写不敏感。 +func TestImageLifecycleVectors(t *testing.T) { + store := newMemStore() + svc := newSvc(t, store, captcha.Options{}) + ctx := context.Background() + + issued, err := svc.Issue(ctx, "", "") + if err != nil { + t.Fatalf("issue: %v", err) + } + if issued.Provider != "image" || issued.Key == "" { + t.Fatalf("issued = %+v", issued) + } + answer := store.m["mysvc:captcha:image:"+issued.Key] + if answer == "" || len(answer) != captcha.DefaultLen { + t.Fatalf("托管答案异常: %q", answer) + } + if !svc.Verify(ctx, "", issued.Key, " "+strings.ToLower(answer)+" ") { + t.Fatal("V5:trim + 大小写不敏感应通过") + } + if svc.Verify(ctx, "", issued.Key, answer) { + t.Fatal("V2:一次性——二次校验必败") + } + + issued2, _ := svc.Issue(ctx, "", "") + if svc.Verify(ctx, "", issued2.Key, "XXXX") { + t.Fatal("V3:错答案必须失败") + } + answer2 := store.m["mysvc:captcha:image:"+issued2.Key] + if svc.Verify(ctx, "", issued2.Key, answer2) { + t.Fatal("V3:错答案后 key 已消费(防重放枚举)") + } + + if svc.Verify(ctx, "", "00000000000000000000000000000000", "ABCD") { + t.Fatal("V4:不存在 key 必败") + } +} + +// V7:TTL 默认 120s(【推荐】档),Options.TTL 可配。 +func TestTtlVector(t *testing.T) { + store := newMemStore() + svc := newSvc(t, store, captcha.Options{}) + issued, _ := svc.Issue(context.Background(), "", "") + if got := store.tt["mysvc:captcha:image:"+issued.Key]; got != 2*time.Minute { + t.Fatalf("V7:默认 TTL = %v, want 120s", got) + } + + store2 := newMemStore() + svc2 := newSvc(t, store2, captcha.Options{TTL: 300 * time.Second}) + issued2, _ := svc2.Issue(context.Background(), "", "") + if got := store2.tt["mysvc:captcha:image:"+issued2.Key]; got != 300*time.Second { + t.Fatalf("V7:自定义 TTL = %v, want 300s", got) + } +} + +// V6:并发校验恰一个成功(原子消费)。 +func TestConcurrentVerifyVector(t *testing.T) { + store := newMemStore() + svc := newSvc(t, store, captcha.Options{}) + ctx := context.Background() + issued, _ := svc.Issue(ctx, "", "") + answer := store.m["mysvc:captcha:image:"+issued.Key] + + const threads = 8 + var wg sync.WaitGroup + results := make([]bool, threads) + start := make(chan struct{}) + for i := 0; i < threads; i++ { + wg.Add(1) + go func(i int) { + defer wg.Done() + <-start + results[i] = svc.Verify(ctx, "", issued.Key, answer) + }(i) + } + close(start) + wg.Wait() + wins := 0 + for _, r := range results { + if r { + wins++ + } + } + if wins != 1 { + t.Fatalf("V6:并发校验应恰一过,实际 %d", wins) + } +} + +// V8/V10:sms-otp 档(scene 路由映射)——6 位数字、宿主通道发送、目标脱敏、精确比对。 +func TestSmsOtpVector(t *testing.T) { + store := newMemStore() + sender := &fakeSmsSender{} + svc := newSvc(t, store, captcha.Options{Scenes: map[string]string{"login": "sms-otp"}, SmsSender: sender}) + ctx := context.Background() + + issued, err := svc.Issue(ctx, "login", "13800138000") + if err != nil { + t.Fatalf("issue: %v", err) + } + if issued.Provider != "sms-otp" { + t.Fatalf("V10:scene 路由应命中 sms-otp,实际 %s", issued.Provider) + } + dest, otp := sender.last() + if dest != "13800138000" { + t.Fatalf("V8:OTP 应经宿主通道发送,目标 %s", dest) + } + if len(otp) != 6 { + t.Fatalf("V8:6 位数字 OTP,实际 %q", otp) + } + for _, r := range otp { + if r < '0' || r > '9' { + t.Fatalf("V8:非数字 OTP %q", otp) + } + } + if got := issued.Payload["destination"]; got != "138****8000" { + t.Fatalf("V8:目标脱敏回显 = %q", got) + } + if !svc.Verify(ctx, "login", issued.Key, otp) { + t.Fatal("V8:正确 OTP 应通过") + } + issued2, _ := svc.Issue(ctx, "login", "13800138000") + _, otp2 := sender.last() + wrong := "000000" + if otp2 == wrong { + wrong = "111111" + } + if svc.Verify(ctx, "login", issued2.Key, wrong) { + t.Fatal("V8:错码必须失败(精确比对)") + } + if svc.Verify(ctx, "login", issued2.Key, otp2) { + t.Fatal("V3:错试后已消费") + } + + // 二-3:缺发送目标 = 1001 上抛 + if _, err := svc.Issue(ctx, "login", ""); err == nil { + t.Fatal("sms-otp 缺目标应报错") + } +} + +// V9:REMOTE 档 stub 两分支 + 空 token + 无服务端答案 + 零存储。 +func TestTurnstileVector(t *testing.T) { + store := newMemStore() + p := captcha.NewTurnstileProviderWithCaller( + captcha.TurnstileConfig{SiteKey: "site-1", SecretKey: "sec-1"}, stubCaller{ok: true}) + + ch, err := p.Issue(captcha.IssueRequest{}) + if err != nil { + t.Fatalf("issue: %v", err) + } + if ch.SecretAnswer != "" { + t.Fatal("V9:REMOTE 档无服务端答案(二-1)") + } + if ch.Payload["siteKey"] != "site-1" { + t.Fatalf("V9:siteKey 透出,实际 %v", ch.Payload) + } + if len(store.keys()) != 0 { + t.Fatal("V9:REMOTE 档全程零存储(三-5)") + } + if !p.VerifyRemote("tok", "10.0.0.1") { + t.Fatal("V9:stub 通过分支") + } + fail := captcha.NewTurnstileProviderWithCaller( + captcha.TurnstileConfig{SiteKey: "s", SecretKey: "x"}, stubCaller{ok: false}) + if fail.VerifyRemote("tok", "") { + t.Fatal("V9:stub 失败分支") + } + if p.VerifyRemote(" ", "") || p.VerifyRemote("", "") { + t.Fatal("V9:空 token 必败") + } +} + +// V10:场景路由——未配置场景走默认;默认档可配;未注册引用构造即败(fail fast)。 +func TestSceneRoutingVector(t *testing.T) { + store := newMemStore() + svc := newSvc(t, store, captcha.Options{Scenes: map[string]string{"login": "sms-otp"}, SmsSender: &fakeSmsSender{}}) + if got := svc.Route("register").ID(); got != "image" { + t.Fatalf("V10:未配置场景应走默认 image,实际 %s", got) + } + if got := svc.Route("").ID(); got != "image" { + t.Fatalf("V10:空场景应走默认,实际 %s", got) + } + + svc2 := newSvc(t, newMemStore(), captcha.Options{DefaultProvider: "sms-otp", SmsSender: &fakeSmsSender{}}) + if got := svc2.Route("anything").ID(); got != "sms-otp" { + t.Fatalf("V10:默认档覆盖应生效,实际 %s", got) + } + + keys, _ := redix.NewKeys("mysvc") + if _, err := captcha.NewService(newMemStore(), keys, captcha.Options{Scenes: map[string]string{"login": "nope"}}); err == nil { + t.Fatal("场景引用未注册 Provider 应构造失败") + } + if _, err := captcha.NewService(newMemStore(), keys, captcha.Options{DefaultProvider: "nope"}); err == nil { + t.Fatal("默认档引用未注册 Provider 应构造失败") + } +} + +// 端点(六-1):非 image 档场景 1001;默认档字段恒在 + 裸 base64 PNG。 +func TestHandlerEndpoint(t *testing.T) { slog.SetLogLoggerLevel(slog.LevelError) - ch := captcha.NewHandler(store, func(id string) string { return "mysvc:captcha:" + id }, 0) - h.GET("/api/v1/captcha", ch.Issue) + svc := newSvc(t, newMemStore(), captcha.Options{Scenes: map[string]string{"login": "sms-otp"}, SmsSender: &fakeSmsSender{}}) + h := server.Default(server.WithHostPorts(":0")) + handler := captcha.NewHandler(svc) + h.GET("/api/v1/captcha", middleware.RateLimit(1000, 1000), handler.Issue) - w := ut.PerformRequest(h.Engine, "GET", "/api/v1/captcha", nil) + // 非 image 档场景经图形端点 = 1001(六-1) + w := ut.PerformRequest(h.Engine, "GET", "/api/v1/captcha?scene=login", nil) var env struct { Code int `json:"code"` Data struct { - ID string `json:"id"` - Image string `json:"image"` + Provider string `json:"provider"` + Key string `json:"key"` + ImageBase64 string `json:"imageBase64"` } `json:"data"` } if err := json.Unmarshal(w.Body.Bytes(), &env); err != nil { t.Fatalf("not envelope: %v", err) } - if w.Code != 200 || env.Code != 0 || env.Data.ID == "" { - t.Fatalf("resp = %d %+v", w.Code, env) + if w.Code != 400 || env.Code != int(errcode.InvalidArgument) { + t.Fatalf("非 image 场景应 400+1001:%d %+v", w.Code, env) } - const prefix = "data:image/png;base64," - if len(env.Data.Image) <= len(prefix) || env.Data.Image[:len(prefix)] != prefix { - t.Fatalf("image not dataURL: %.40s", env.Data.Image) + + // 默认档:字段恒在(provider 增量 + key/imageBase64 存量形态) + w2 := ut.PerformRequest(h.Engine, "GET", "/api/v1/captcha", nil) + if err := json.Unmarshal(w2.Body.Bytes(), &env); err != nil { + t.Fatalf("not envelope: %v", err) } - // 解 base64 → PNG magic - img := decodeB64(t, env.Data.Image[len(prefix):]) - if !bytes.HasPrefix(img, []byte{0x89, 'P', 'N', 'G'}) { + if w2.Code != 200 || env.Code != 0 || env.Data.Provider != "image" || env.Data.Key == "" { + t.Fatalf("resp = %d %+v", w2.Code, env) + } + if strings.HasPrefix(env.Data.ImageBase64, "data:") { + t.Fatal("二-2:裸 base64 禁 data: 前缀") + } + raw, err := base64.StdEncoding.DecodeString(env.Data.ImageBase64) + if err != nil { + t.Fatalf("imageBase64 应为裸 base64: %v", err) + } + if !bytes.HasPrefix(raw, []byte{0x89, 'P', 'N', 'G'}) { t.Fatal("not PNG magic") } - if _, err := png.Decode(bytes.NewReader(img)); err != nil { + if _, err := png.Decode(bytes.NewReader(raw)); err != nil { t.Fatalf("png decode: %v", err) } } -// 一次性 + 大小写不敏感 + 失败同样消费。 -func TestVerifySemantics(t *testing.T) { - store := &memStore{m: map[string]string{}} - h := captcha.NewHandler(store, func(id string) string { return id }, 0) - ctx := context.Background() - - _ = store.Issue(ctx, "k1", "AB3CD", time.Minute) - if !h.Verify(ctx, "k1", "ab3cd") { - t.Fatal("大小写不敏感应通过") - } - if h.Verify(ctx, "k1", "AB3CD") { - t.Fatal("一次性:二次校验必须失败") +// V11:生成端点限流(五-1:注册时挂限流中间件,超限 429+1006)。 +func TestHandlerRateLimited(t *testing.T) { + slog.SetLogLoggerLevel(slog.LevelError) + svc := newSvc(t, newMemStore(), captcha.Options{}) + h := server.Default(server.WithHostPorts(":0")) + h.GET("/api/v1/captcha", middleware.RateLimit(0.0001, 2), captcha.NewHandler(svc).Issue) + for i := 0; i < 2; i++ { + if w := ut.PerformRequest(h.Engine, "GET", "/api/v1/captcha", nil); w.Code != 200 { + t.Fatalf("名额内应 200,第 %d 次 = %d", i+1, w.Code) + } } - - _ = store.Issue(ctx, "k2", "XY9ZK", time.Minute) - if h.Verify(ctx, "k2", "WRONG") { - t.Fatal("错码必须失败") + w := ut.PerformRequest(h.Engine, "GET", "/api/v1/captcha", nil) + var env struct { + Code int `json:"code"` } - if h.Verify(ctx, "k2", "XY9ZK") { - t.Fatal("失败后 token 已消费,防重放爆破") + _ = json.Unmarshal(w.Body.Bytes(), &env) + if w.Code != 429 || env.Code != int(errcode.RateLimited) { + t.Fatalf("V11:超限应 429+1006,实际 %d %+v", w.Code, env) } } +// 字符集与长度(二-2【强制】:4 位、去混淆 32 字符集)。 func TestNewCode(t *testing.T) { c := captcha.NewCode(captcha.DefaultLen) if len(c) != captcha.DefaultLen { t.Fatalf("len = %d", len(c)) } for i := 0; i < len(c); i++ { - for _, bad := range []byte{'0', 'O', '1', 'I'} { - if c[i] == bad { - t.Fatalf("混淆字符 %q 出现: %s", bad, c) - } + if !strings.ContainsRune("23456789ABCDEFGHJKLMNPQRSTUVWXYZ", rune(c[i])) { + t.Fatalf("字符 %q 不在契约字符集: %s", rune(c[i]), c) } } - a, b := captcha.NewCode(5), captcha.NewCode(5) + a, b := captcha.NewCode(8), captcha.NewCode(8) if a == b { t.Fatal("两次生成不应相同(概率级)") } } -func decodeB64(t *testing.T, s string) []byte { - t.Helper() - b, err := base64.StdEncoding.DecodeString(s) - if err != nil { - t.Fatalf("base64: %v", err) +// 2005 码位锚定(五-2 三态合一:业务侧 false → xerror.New(errcode.CaptchaInvalid))。 +func TestCaptchaInvalidCodePinned(t *testing.T) { + if errcode.CaptchaInvalid != 2005 { + t.Fatalf("2005 码位漂移: %d", int(errcode.CaptchaInvalid)) } - return b } diff --git a/stacks/golang/captcha/handler.go b/stacks/golang/captcha/handler.go index eb08641..0140f11 100644 --- a/stacks/golang/captcha/handler.go +++ b/stacks/golang/captcha/handler.go @@ -2,47 +2,33 @@ package captcha import ( "context" - "time" "github.com/cloudwego/hertz/pkg/app" "github.com/ydonghao/yarch/stacks/golang/web" ) -// keyFn 业务侧提供 key 生成器(redix.Keys.K("captcha", id)——首段=服务名纪律)。 -type keyFn func(id string) string +// Handler 验证码端点件(contract/api/captcha.md 六)。 +// 业务注册时挂限流中间件(五-1:middleware.RateLimit 进程内档 / RateLimitRedis 分布式档)。 +type Handler struct{ svc *Service } -// Handler 验证码端点件。 -type Handler struct { - store Store - key keyFn - ttl time.Duration -} - -// NewHandler 构造(ttl ≤ 0 用默认 5 分钟)。 -func NewHandler(store Store, key keyFn, ttl time.Duration) *Handler { - if ttl <= 0 { - ttl = DefaultTTL - } - return &Handler{store: store, key: key, ttl: ttl} -} +// NewHandler 端点件构造。 +func NewHandler(svc *Service) *Handler { return &Handler{svc: svc} } -// Issue GET /api/v1/captcha → 200 + {id, image(dataURL)}。 -// image 为 data:image/png;base64(前端 直用);code 不出网。 +// Issue GET /api/v1/captcha → RestResponse(六-1)。 +// scene 可选路由参数(四);imageBase64 为裸 base64(无 data: 前缀,二-2);code 不出网。 +// 非 image 档场景 = 1001(端点形态与档位不匹配)。 func (h *Handler) Issue(ctx context.Context, c *app.RequestContext) { - id := NewID() - code := NewCode(DefaultLen) - if err := h.store.Issue(ctx, h.key(id), code, h.ttl); err != nil { - web.ErrCode(c, 1009, "") + ch, be := h.svc.Challenge(ctx, string(c.Query("scene"))) + if be != nil { + web.ErrCode(c, be.Code, "") return } - web.OK(c, 200, map[string]string{ - "id": id, - "image": ImageDataURL(RenderPNG(code)), - }) + web.OK(c, 200, ch) } -// Verify 校验并一次性消费(挂在登录等业务 handler 内调用;失败返回 false 由业务给 1001 细节)。 -func (h *Handler) Verify(ctx context.Context, id, input string) bool { - return Verify(ctx, h.store, h.key(id), input) +// Verify 内联校验(六-2):挂在登录等业务 handler 内调用;false → 2005 CAPTCHA_INVALID +// (五-2 三态合一:web.ErrCode(c, errcode.CaptchaInvalid, "")),禁细分 key 状态。 +func (h *Handler) Verify(ctx context.Context, scene, key, input string) bool { + return h.svc.Verify(ctx, scene, key, input) } diff --git a/stacks/golang/captcha/provider.go b/stacks/golang/captcha/provider.go new file mode 100644 index 0000000..59c7f5d --- /dev/null +++ b/stacks/golang/captcha/provider.go @@ -0,0 +1,57 @@ +package captcha + +// Provider SPI(contract/api/captcha.md 一-2/二):渠道差异是框架内多态, +// 实现只管「生成挑战」与「答案比对/远程校验」;生命周期(key/存储/TTL/一次性原子消费)、 +// 场景路由、错误语义归框架核心 Service。 +// +// 保留字 id(一-3):image / sms-otp / turnstile,业务自定义 Provider 禁占用。 +type Provider interface { + // ID Provider 标识(kebab-case,保留字见接口注释) + ID() string + + // Mode 校验模式(二-1):LOCAL=答案由框架核心托管、一次性原子消费;REMOTE=远程校验、无服务端答案存储 + Mode() VerifyMode + + // Issue 生成分发(LOCAL:产出机密答案 + 公开载体;REMOTE:答案恒空、载体为接入配置透出) + Issue(req IssueRequest) (IssuedChallenge, error) + + // Matches LOCAL 档答案比对规则。默认 = 首尾空白 trim + 大小写不敏感(二-2 image 档);精确档(二-3 sms-otp)覆写 + Matches(stored, attempted string) bool +} + +// RemoteVerifier REMOTE 档远程校验(二-1)——REMOTE 型 Provider 额外实现 +// (Go 无默认方法,LOCAL 型无需空实现)。 +type RemoteVerifier interface { + VerifyRemote(token, remoteIP string) bool +} + +// VerifyMode 校验模式二分(二-1)。 +type VerifyMode int + +const ( + // ModeLocal 本地校验型:答案由框架核心托管进存储,一次性原子消费(三) + ModeLocal VerifyMode = iota + // ModeRemote 远程校验型:无服务端答案存储,一次性语义由上游保证 + ModeRemote +) + +// IssueRequest 分发请求:Scene 为路由场景(四-1,可空);Destination 为发送目标(sms-otp 档必填)。 +type IssueRequest struct { + Scene string + Destination string +} + +// IssuedChallenge 分发产物:SecretAnswer 为机密答案(LOCAL 档进存储由框架核心托管,REMOTE 恒空); +// Payload 为公开载体(image 的 imageBase64 / turnstile 的 siteKey / sms-otp 的脱敏目标)。 +type IssuedChallenge struct { + SecretAnswer string + Payload map[string]string +} + +// DefaultMatches 默认比对口径(二-2):attempted 去首尾空白 + 大小写不敏感;stored 为空即败。 +func DefaultMatches(stored, attempted string) bool { + if stored == "" { + return false + } + return equalFold(stored, trimSpace(attempted)) +} diff --git a/stacks/golang/captcha/service.go b/stacks/golang/captcha/service.go new file mode 100644 index 0000000..58fb5a2 --- /dev/null +++ b/stacks/golang/captcha/service.go @@ -0,0 +1,157 @@ +package captcha + +import ( + "context" + "time" + + "github.com/ydonghao/yarch/stacks/golang/errcode" + "github.com/ydonghao/yarch/stacks/golang/redix" + "github.com/ydonghao/yarch/stacks/golang/xerror" +) + +// Options 装配配置(contract/api/captcha.md 三-2/四-2/二-3/二-4)。 +// 租户级覆盖是宿主应用层扩展位(四-3),本配置面到应用级为止。 +type Options struct { + // TTL challenge 有效期(三-2【推荐】120s;OTP 档可放宽至 300s)。零值取 DefaultTTL。 + TTL time.Duration + // DefaultProvider 默认 Provider(四-2,空取 image);未配置场景一律走此档。 + DefaultProvider string + // Scenes scene → Provider 覆盖映射(四-2);scene 为宿主自定 kebab-case,yarch 不拥有场景枚举。 + Scenes map[string]string + // SmsSender 非 nil 时注册 sms-otp 档(二-3:分发通道宿主注入)。 + SmsSender SmsSender + // Turnstile 非 nil 时注册 turnstile 档(二-4:接入凭据在场才装配)。 + Turnstile *TurnstileConfig +} + +// Issued 编程式分发产物(六-4:sms-otp/turnstile 档首发走编程式,HTTP 端点为触发档)。 +type Issued struct { + Provider string + Key string + Payload map[string]string +} + +// Challenge REST 端点形状(六-1):provider/key/imageBase64 恒在(image 档)。 +type Challenge struct { + Provider string `json:"provider"` + Key string `json:"key"` + ImageBase64 string `json:"imageBase64"` +} + +// Service 框架核心(contract/api/captcha.md 一-2):challenge 生命周期(生成/存储/TTL/ +// 一次性原子消费三)、场景路由(四)归此;生成与比对归 Provider。 +type Service struct { + store Store + keys *redix.Keys + providers map[string]Provider + defaultID string + scenes map[string]string + ttl time.Duration +} + +// NewService 构造并校验装配(fail fast):image 恒注册;sms-otp/turnstile 按 Options 条件注册; +// DefaultProvider 与 Scenes 引用的 Provider 必须已注册,否则返回错误(配置即崩,不留运行期悬空)。 +func NewService(store Store, keys *redix.Keys, opts Options) (*Service, error) { + providers := map[string]Provider{"image": &ImageProvider{}} + if opts.SmsSender != nil { + providers["sms-otp"] = &SmsOtpProvider{sender: opts.SmsSender} + } + if opts.Turnstile != nil { + providers["turnstile"] = NewTurnstileProvider(*opts.Turnstile) + } + defaultID := opts.DefaultProvider + if defaultID == "" { + defaultID = "image" + } + if _, ok := providers[defaultID]; !ok { + return nil, xerror.Newf(errcode.InvalidArgument, "默认 Provider 未注册:%s", defaultID) + } + for scene, id := range opts.Scenes { + if _, ok := providers[id]; !ok { + return nil, xerror.Newf(errcode.InvalidArgument, "场景 %s 引用未注册 Provider:%s", scene, id) + } + } + ttl := opts.TTL + if ttl <= 0 { + ttl = DefaultTTL + } + scenes := make(map[string]string, len(opts.Scenes)) + for scene, id := range opts.Scenes { + scenes[scene] = id + } + return &Service{ + store: store, + keys: keys, + providers: providers, + defaultID: defaultID, + scenes: scenes, + ttl: ttl, + }, nil +} + +// Route 场景路由(四-2):未配置场景走默认 Provider(不报错)。 +func (s *Service) Route(scene string) Provider { + if id, ok := s.scenes[scene]; ok { + return s.providers[id] + } + return s.providers[s.defaultID] +} + +// Issue 分发(四-2 路由)。LOCAL 档生成安全随机 key(三-1)并带 TTL 托管答案; +// REMOTE 档零存储(三-5)。分发失败(如 OTP 通道异常)原样上抛由宿主定级。 +func (s *Service) Issue(ctx context.Context, scene, destination string) (Issued, error) { + p := s.Route(scene) + ch, err := p.Issue(IssueRequest{Scene: scene, Destination: destination}) + if err != nil { + return Issued{}, err + } + key := "" + if p.Mode() == ModeLocal { + key = NewID() + if err := s.store.Issue(ctx, s.storeKey(p.ID(), key), ch.SecretAnswer, s.ttl); err != nil { + return Issued{}, err + } + } + return Issued{Provider: p.ID(), Key: key, Payload: ch.Payload}, nil +} + +// Verify 校验(六-2:内联受保护业务流,不设独立端点)。 +// LOCAL = 原子消费后按 Provider 比对(三-3 对/错/异常均消费;三-4 GETDEL); +// REMOTE = 外委校验(二-1)。false 时业务报 2005 CAPTCHA_INVALID(五-2 三态合一)。 +func (s *Service) Verify(ctx context.Context, scene, key, answer string) bool { + p := s.Route(scene) + if p.Mode() == ModeRemote { + rv, ok := p.(RemoteVerifier) + if !ok { + return false + } + return rv.VerifyRemote(answer, "") + } + stored, ok, err := s.store.Consume(ctx, s.storeKey(p.ID(), key)) + if err != nil || !ok { + return false + } + return p.Matches(stored, answer) +} + +// Challenge REST 端点便捷面(六-1):GET /api/v1/captcha 只服务 image 档, +// 路由到他档 = 1001 参数错(先查档位再分发——sms-otp 等档缺端点参数不在此报)。 +func (s *Service) Challenge(ctx context.Context, scene string) (Challenge, *xerror.BizError) { + if id := s.Route(scene).ID(); id != "image" { + return Challenge{}, xerror.Newf(errcode.InvalidArgument, "场景 %s 非 image 档,不经图形分发端点", scene) + } + issued, err := s.Issue(ctx, scene, "") + if err != nil { + return Challenge{}, xerror.FromError(err) + } + return Challenge{ + Provider: issued.Provider, + Key: issued.Key, + ImageBase64: issued.Payload["imageBase64"], + }, nil +} + +// storeKey 存储 key(三-5):{服务名}:captcha:{provider}:{key}——redix.Keys 强制首段服务名。 +func (s *Service) storeKey(providerID, key string) string { + return s.keys.K("captcha", providerID, key) +} diff --git a/stacks/golang/captcha/smsotp.go b/stacks/golang/captcha/smsotp.go new file mode 100644 index 0000000..7f29e67 --- /dev/null +++ b/stacks/golang/captcha/smsotp.go @@ -0,0 +1,64 @@ +package captcha + +import "fmt" + +// ImageProvider image 档(contract/api/captcha.md 二-2,LOCAL 默认档): +// 4 位去混淆字符集【强制】;比对默认口径(trim + 大小写不敏感);渲染样式自由(CP9)。 +type ImageProvider struct{} + +func (p *ImageProvider) ID() string { return "image" } +func (p *ImageProvider) Mode() VerifyMode { return ModeLocal } + +func (p *ImageProvider) Issue(req IssueRequest) (IssuedChallenge, error) { + answer := NewCode(DefaultLen) + return IssuedChallenge{ + SecretAnswer: answer, + Payload: map[string]string{"imageBase64": ImageBase64(RenderPNG(answer))}, + }, nil +} + +// Matches 默认口径:trim + 大小写不敏感(二-2)。 +func (p *ImageProvider) Matches(stored, attempted string) bool { + return DefaultMatches(stored, attempted) +} + +// SmsSender OTP 分发通道 SPI(二-3):发送通道由宿主注入——yarch 不背通知渠道抽象 +// (通知领域契约排队中 EP7,届时对齐)。宿主提供实现后经 Options.SmsSender 注册 sms-otp 档。 +type SmsSender interface { + // Send 发送 OTP 到目标(手机号)。destination 明文仅在此处出现;回显侧已由框架脱敏。 + Send(destination, content string) error +} + +// SmsOtpProvider sms-otp 档(contract/api/captcha.md 二-3,LOCAL): +// 6 位数字 OTP(安全随机源);精确匹配(禁宽松比对);目标回显脱敏。 +type SmsOtpProvider struct{ sender SmsSender } + +func (p *SmsOtpProvider) ID() string { return "sms-otp" } +func (p *SmsOtpProvider) Mode() VerifyMode { return ModeLocal } + +func (p *SmsOtpProvider) Issue(req IssueRequest) (IssuedChallenge, error) { + if req.Destination == "" { + return IssuedChallenge{}, fmt.Errorf("sms-otp 档须提供发送目标(1001)") + } + otp := fmt.Sprintf("%06d", randInt(1_000_000)) + if err := p.sender.Send(req.Destination, otp); err != nil { + return IssuedChallenge{}, err + } + return IssuedChallenge{ + SecretAnswer: otp, + Payload: map[string]string{"destination": MaskDestination(req.Destination)}, + }, nil +} + +// Matches 精确匹配(二-3 禁宽松比对):仅去首尾空白,无大小写折中。 +func (p *SmsOtpProvider) Matches(stored, attempted string) bool { + return stored != "" && stored == trimSpace(attempted) +} + +// MaskDestination 目标脱敏回显(二-3):≥7 位留前 3 后 4,其余全遮。 +func MaskDestination(destination string) string { + if len(destination) < 7 { + return "****" + } + return destination[:3] + "****" + destination[len(destination)-4:] +} diff --git a/stacks/golang/captcha/turnstile.go b/stacks/golang/captcha/turnstile.go new file mode 100644 index 0000000..f5bc1d9 --- /dev/null +++ b/stacks/golang/captcha/turnstile.go @@ -0,0 +1,83 @@ +package captcha + +import ( + "encoding/json" + "net/http" + "net/url" + "strings" +) + +// TurnstileConfig turnstile 档接入配置(二-4):SecretKey 非空时该档才装配。 +type TurnstileConfig struct { + SiteKey string + SecretKey string + // VerifyURL 上游 siteverify 地址(默认 Cloudflare 官方端点) + VerifyURL string +} + +// SiteVerifyCaller siteverify 调用器(测试打桩位)。 +type SiteVerifyCaller interface { + Call(verifyURL, secret, response, remoteIP string) bool +} + +// TurnstileProvider turnstile 档(contract/api/captcha.md 二-4,REMOTE): +// siteKey 透出 + siteverify 外委校验;token 不落存储(三-5:REMOTE 型不产生存储 key)。 +type TurnstileProvider struct { + cfg TurnstileConfig + caller SiteVerifyCaller +} + +func NewTurnstileProvider(cfg TurnstileConfig) *TurnstileProvider { + return &TurnstileProvider{cfg: cfg, caller: siteVerifyCaller{}} +} + +// NewTurnstileProviderWithCaller 构造(caller 注入,测试打桩位)。 +func NewTurnstileProviderWithCaller(cfg TurnstileConfig, caller SiteVerifyCaller) *TurnstileProvider { + return &TurnstileProvider{cfg: cfg, caller: caller} +} + +func (p *TurnstileProvider) ID() string { return "turnstile" } +func (p *TurnstileProvider) Mode() VerifyMode { return ModeRemote } + +func (p *TurnstileProvider) Issue(req IssueRequest) (IssuedChallenge, error) { + // REMOTE 档:无服务端答案(二-1),分发即接入配置透出(二-4:前端嵌 widget 自取 token) + return IssuedChallenge{SecretAnswer: "", Payload: map[string]string{"siteKey": p.cfg.SiteKey}}, nil +} + +func (p *TurnstileProvider) Matches(stored, attempted string) bool { return false } // REMOTE 档不适用 + +// VerifyRemote 外委校验:空 token 即败;上游不可达 fail closed(一律 false)。 +func (p *TurnstileProvider) VerifyRemote(token, remoteIP string) bool { + if strings.TrimSpace(token) == "" { + return false + } + verifyURL := p.cfg.VerifyURL + if verifyURL == "" { + verifyURL = "https://challenges.cloudflare.com/turnstile/v0/siteverify" + } + return p.caller.Call(verifyURL, p.cfg.SecretKey, token, remoteIP) +} + +// siteVerifyCaller 默认调用器:POST siteverify(form 编码),解析 {"success":bool}。 +type siteVerifyCaller struct{} + +func (siteVerifyCaller) Call(verifyURL, secret, response, remoteIP string) bool { + form := url.Values{} + form.Set("secret", secret) + form.Set("response", response) + if remoteIP != "" { + form.Set("remoteip", remoteIP) + } + resp, err := http.PostForm(verifyURL, form) + if err != nil { + return false + } + defer func() { _ = resp.Body.Close() }() + var out struct { + Success bool `json:"success"` + } + if err := json.NewDecoder(resp.Body).Decode(&out); err != nil { + return false + } + return out.Success +} diff --git a/stacks/golang/errcode/errcode.go b/stacks/golang/errcode/errcode.go index 1ff442d..f0aef6b 100644 --- a/stacks/golang/errcode/errcode.go +++ b/stacks/golang/errcode/errcode.go @@ -1,4 +1,4 @@ -// Package errcode 实现契约「错误码全局段位表」(contract/api/error-codes.md v1.0)。 +// Package errcode 实现契约「错误码全局段位表」(contract/api/error-codes.md v1.1)。 // yarch 只拥有 0、1xxx、2xxx;3xxx-8xxx 由业务仓注册后方可使用,9xxx 预留不得使用。 package errcode @@ -31,6 +31,7 @@ const ( CredentialsExpired Code = 2002 // CREDENTIALS_EXPIRED / 凭证已过期 / 401 Forbidden Code = 2003 // FORBIDDEN / 权限不足 / 403 AccountDisabled Code = 2004 // ACCOUNT_DISABLED / 账号已禁用 / 403 + CaptchaInvalid Code = 2005 // CAPTCHA_INVALID / 验证码校验失败 / 400(captcha.md 五-2:三态合一禁细分) ) type meta struct { @@ -53,6 +54,7 @@ var builtin = map[Code]meta{ CredentialsExpired: {"CredentialsExpired", "凭证已过期", 401}, Forbidden: {"Forbidden", "权限不足", 403}, AccountDisabled: {"AccountDisabled", "账号已禁用", 403}, + CaptchaInvalid: {"CaptchaInvalid", "验证码校验失败", 400}, } var ( diff --git a/stacks/golang/errcode/errcode_test.go b/stacks/golang/errcode/errcode_test.go index 7bd309f..abab52a 100644 --- a/stacks/golang/errcode/errcode_test.go +++ b/stacks/golang/errcode/errcode_test.go @@ -9,7 +9,7 @@ import ( "github.com/ydonghao/yarch/stacks/golang/errcode" ) -// 契约断言:13 码全表唯一权威 = contract/dist/error-codes.json(由 contract/api/error-codes.md 派生, +// 契约断言:14 码全表唯一权威 = contract/dist/error-codes.json(由 contract/api/error-codes.md 派生, // CI 拒双向漂移)——四栈读同一份 json 断言,不再各养手抄表(P1 契约机器可读出口)。 // dist 文件不在场(消费方模块独立测试环境)则跳过本表断言,CI 仓内必跑。 func TestBuiltinTable(t *testing.T) { @@ -28,8 +28,8 @@ func TestBuiltinTable(t *testing.T) { if err := json.Unmarshal(raw, &dist); err != nil { t.Fatalf("dist json 解析失败: %v", err) } - if len(dist.Codes) != 13 { - t.Fatalf("dist 13 码表异常: %d 条", len(dist.Codes)) + if len(dist.Codes) != 14 { + t.Fatalf("dist 14 码表异常: %d 条", len(dist.Codes)) } for _, row := range dist.Codes { code := errcode.Code(row.Code) diff --git a/stacks/golang/testcontainers/ratelimit_captcha_test.go b/stacks/golang/testcontainers/ratelimit_captcha_test.go index d3babc8..0ddc000 100644 --- a/stacks/golang/testcontainers/ratelimit_captcha_test.go +++ b/stacks/golang/testcontainers/ratelimit_captcha_test.go @@ -2,6 +2,8 @@ package testcontainers import ( "context" + "strings" + "sync" "testing" "time" @@ -57,3 +59,63 @@ func TestCaptchaRedisStore(t *testing.T) { t.Fatal("一次性:二次消费必须失败") } } + +// V6/V7 行为级:Service 全链路(GETDEL 原子消费并发恰一过 + TTL 生效 + 存储 key 形状)。 +func TestCaptchaServiceWithRedis(t *testing.T) { + addr := StartRedis(t) + rdb := redis.NewClient(&redis.Options{Addr: addr}) + defer rdb.Close() + ctx := context.Background() + + keys, _ := redix.NewKeys("mysvc") + svc, err := captcha.NewService(captcha.NewRedisStore(rdb), keys, captcha.Options{}) + if err != nil { + t.Fatalf("NewService: %v", err) + } + issued, err := svc.Issue(ctx, "", "") + if err != nil { + t.Fatalf("issue: %v", err) + } + if issued.Provider != "image" || issued.Key == "" { + t.Fatalf("issued = %+v", issued) + } + + // 三-5:存储 key 形状 {服务名}:captcha:{provider}:{key} + storeKey := "mysvc:captcha:image:" + issued.Key + ttl, err := rdb.TTL(ctx, storeKey).Result() + if err != nil || ttl <= 0 || ttl > 2*time.Minute { + t.Fatalf("V7:TTL 异常 %v err=%v", ttl, err) + } + + answer, err := rdb.Get(ctx, storeKey).Result() + if err != nil { + t.Fatalf("peek: %v", err) + } + + // V6:8 并发校验恰一过(GETDEL 原子) + const threads = 8 + var wg sync.WaitGroup + wins := 0 + var mu sync.Mutex + start := make(chan struct{}) + for i := 0; i < threads; i++ { + wg.Add(1) + go func() { + defer wg.Done() + <-start + if svc.Verify(ctx, "", issued.Key, strings.ToLower(answer)) { + mu.Lock() + wins++ + mu.Unlock() + } + }() + } + close(start) + wg.Wait() + if wins != 1 { + t.Fatalf("V6:并发校验应恰一过,实际 %d", wins) + } + if _, err := rdb.Get(ctx, storeKey).Result(); err == nil { + t.Fatal("V2:校验后 key 已消费") + } +} diff --git a/stacks/java/core/yarch-common/src/main/java/io/github/ydonghao/yarch/common/code/GlobalErrorCode.java b/stacks/java/core/yarch-common/src/main/java/io/github/ydonghao/yarch/common/code/GlobalErrorCode.java index 8c714bc..30372e6 100644 --- a/stacks/java/core/yarch-common/src/main/java/io/github/ydonghao/yarch/common/code/GlobalErrorCode.java +++ b/stacks/java/core/yarch-common/src/main/java/io/github/ydonghao/yarch/common/code/GlobalErrorCode.java @@ -3,7 +3,7 @@ import java.util.Optional; /** - * yarch 内置错误码全表(契约唯一权威:contract/api/error-codes.md v1.0)。 本枚举与契约表不一致即 bug——由 + * yarch 内置错误码全表(契约唯一权威:contract/api/error-codes.md v1.1)。 本枚举与契约表不一致即 bug——由 * yarch-test-spring-boot-starter 的契约断言测试守护。 */ public enum GlobalErrorCode implements ErrorCode { @@ -25,7 +25,10 @@ public enum GlobalErrorCode implements ErrorCode { UNAUTHORIZED(2001, "未认证", 401), CREDENTIALS_EXPIRED(2002, "凭证已过期", 401), FORBIDDEN(2003, "权限不足", 403), - ACCOUNT_DISABLED(2004, "账号已禁用", 403); + ACCOUNT_DISABLED(2004, "账号已禁用", 403), + + /** 验证码校验失败:key 无效/已消费/答案错误三态合一,禁细分(captcha.md 五-2) */ + CAPTCHA_INVALID(2005, "验证码校验失败", 400); private final int code; private final String defaultMessage; diff --git a/stacks/java/core/yarch-common/src/test/java/io/github/ydonghao/yarch/common/code/GlobalErrorCodeContractTest.java b/stacks/java/core/yarch-common/src/test/java/io/github/ydonghao/yarch/common/code/GlobalErrorCodeContractTest.java index ad20e3b..b7407db 100644 --- a/stacks/java/core/yarch-common/src/test/java/io/github/ydonghao/yarch/common/code/GlobalErrorCodeContractTest.java +++ b/stacks/java/core/yarch-common/src/test/java/io/github/ydonghao/yarch/common/code/GlobalErrorCodeContractTest.java @@ -12,7 +12,7 @@ import org.junit.jupiter.api.Test; /** - * 错误码契约守护:13 码全表唯一权威 = contract/dist/error-codes.json(由 error-codes.md 派生, CI 拒双向漂移)——四栈读同一份 json + * 错误码契约守护:14 码全表唯一权威 = contract/dist/error-codes.json(由 error-codes.md 派生, CI 拒双向漂移)——四栈读同一份 json * 断言,不再各养手抄表(P1 契约机器可读出口)。 dist 文件不在场(消费方独立测试环境)则跳过表断言,CI 仓内必跑。 */ class GlobalErrorCodeContractTest { @@ -39,7 +39,7 @@ private static List loadContractTable() throws Exception { @Test void enumMatchesContractTable() throws Exception { List contractTable = loadContractTable(); - assertEquals(13, contractTable.size(), "dist 码表条数异常"); + assertEquals(14, contractTable.size(), "dist 码表条数异常"); assertEquals(contractTable.size(), GlobalErrorCode.values().length, "码表条数与契约不一致"); for (Object[] row : contractTable) { int code = (int) row[0]; diff --git a/stacks/java/starter/yarch-captcha-spring-boot-starter/pom.xml b/stacks/java/starter/yarch-captcha-spring-boot-starter/pom.xml index 57208f4..0e8a763 100644 --- a/stacks/java/starter/yarch-captcha-spring-boot-starter/pom.xml +++ b/stacks/java/starter/yarch-captcha-spring-boot-starter/pom.xml @@ -31,5 +31,11 @@ spring-boot-starter-test test + + + org.springframework.boot + spring-boot-starter-webmvc-test + test + diff --git a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/CaptchaProperties.java b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/CaptchaProperties.java new file mode 100644 index 0000000..74381c1 --- /dev/null +++ b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/CaptchaProperties.java @@ -0,0 +1,84 @@ +package io.github.ydonghao.yarch.captcha; + +import java.time.Duration; +import java.util.LinkedHashMap; +import java.util.Map; +import org.springframework.boot.context.properties.ConfigurationProperties; + +/** 装配配置(contract/api/captcha.md 三-2/四-2/二-4)。租户级覆盖是宿主应用层扩展位(四-3),本配置面到应用级为止。 */ +@ConfigurationProperties("yarch.captcha") +public class CaptchaProperties { + + /** 默认 Provider(四-2,缺省 image);未配置场景一律走此档 */ + private String defaultProvider = "image"; + + /** scene → Provider 覆盖映射(四-2);scene 为宿主自定 kebab-case,yarch 不拥有场景枚举 */ + private Map scenes = new LinkedHashMap<>(); + + /** challenge TTL(三-2【推荐】120s;OTP 档可放宽至 300s) */ + private Duration ttl = Duration.ofSeconds(120); + + private final Turnstile turnstile = new Turnstile(); + + public String getDefaultProvider() { + return defaultProvider; + } + + public void setDefaultProvider(String defaultProvider) { + this.defaultProvider = defaultProvider; + } + + public Map getScenes() { + return scenes; + } + + public void setScenes(Map scenes) { + this.scenes = scenes; + } + + public Duration getTtl() { + return ttl; + } + + public void setTtl(Duration ttl) { + this.ttl = ttl; + } + + public Turnstile getTurnstile() { + return turnstile; + } + + /** turnstile 档接入配置(二-4):secret-key 配置存在时该档才装配 */ + public static class Turnstile { + + private String siteKey = ""; + + private String secretKey = ""; + + private String verifyUrl = "https://challenges.cloudflare.com/turnstile/v0/siteverify"; + + public String getSiteKey() { + return siteKey; + } + + public void setSiteKey(String siteKey) { + this.siteKey = siteKey; + } + + public String getSecretKey() { + return secretKey; + } + + public void setSecretKey(String secretKey) { + this.secretKey = secretKey; + } + + public String getVerifyUrl() { + return verifyUrl; + } + + public void setVerifyUrl(String verifyUrl) { + this.verifyUrl = verifyUrl; + } + } +} diff --git a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/CaptchaProvider.java b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/CaptchaProvider.java new file mode 100644 index 0000000..e366a37 --- /dev/null +++ b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/CaptchaProvider.java @@ -0,0 +1,50 @@ +package io.github.ydonghao.yarch.captcha; + +import java.util.Map; + +/** + * 验证码 Provider SPI(contract/api/captcha.md 一-2/二):渠道差异是框架内多态,实现只管「生成挑战」与「答案比对/远程校验」; + * 生命周期(key/存储/TTL/一次性原子消费)、场景路由、错误语义归框架核心 {@link CaptchaService}。 + * + *

保留字 id(一-3):{@code image} / {@code sms-otp} / {@code turnstile}。 + */ +public interface CaptchaProvider { + + /** Provider 标识(kebab-case,保留字见类注释) */ + String id(); + + /** 校验模式(二-1):LOCAL=答案由框架核心托管、一次性原子消费;REMOTE=远程校验、无服务端答案存储 */ + VerifyMode mode(); + + /** + * 生成分发(LOCAL:产出机密答案 + 公开载体;REMOTE:答案恒 null、载体为接入配置透出)。 + * + * @param request 分发请求(场景 + 可选发送目标,sms-otp 档必填目标) + */ + IssuedChallenge issue(IssueRequest request); + + /** LOCAL 档答案比对规则。默认 = 首尾空白 trim + 大小写不敏感(二-2 image 档口径); 精确档(二-3 sms-otp)覆写。 */ + default boolean matches(String storedAnswer, String attempted) { + return storedAnswer != null + && storedAnswer.equalsIgnoreCase(attempted == null ? "" : attempted.trim()); + } + + /** REMOTE 档远程校验(二-1);LOCAL 档实现可不覆写 */ + default boolean verifyRemote(String token, String remoteIp) { + throw new UnsupportedOperationException("REMOTE 型 Provider 必须实现 verifyRemote"); + } + + enum VerifyMode { + LOCAL, + REMOTE + } + + /** 分发请求:scene 为路由场景(四-1,可 null);destination 为发送目标(sms-otp 档必填) */ + record IssueRequest(String scene, String destination) {} + + /** + * 分发产物:secretAnswer 为机密答案(LOCAL 档进 Redis,由框架核心托管;REMOTE 档恒 null); payload 为公开载体(image 的 + * imageBase64 / turnstile 的 siteKey / sms-otp 的脱敏目标)。 + */ + record IssuedChallenge(String secretAnswer, Map payload) {} +} diff --git a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/CaptchaService.java b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/CaptchaService.java index 4f244fe..35fb40c 100644 --- a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/CaptchaService.java +++ b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/CaptchaService.java @@ -1,96 +1,153 @@ package io.github.ydonghao.yarch.captcha; +import io.github.ydonghao.yarch.common.code.BusinessException; +import io.github.ydonghao.yarch.common.code.GlobalErrorCode; import io.github.ydonghao.yarch.redis.RedisKeys; -import java.awt.BasicStroke; -import java.awt.Color; -import java.awt.Font; -import java.awt.Graphics2D; -import java.awt.image.BufferedImage; -import java.io.ByteArrayOutputStream; -import java.security.SecureRandom; import java.time.Duration; -import java.util.Base64; +import java.util.List; +import java.util.Map; import java.util.UUID; -import javax.imageio.ImageIO; +import java.util.function.Function; +import java.util.stream.Collectors; import org.springframework.data.redis.core.StringRedisTemplate; +import org.springframework.data.redis.core.script.RedisScript; -/** 图形验证码(E2):生成 4 位去混淆字符 + 噪线;答案进 Redis(key 首段=服务名, TTL 120s、一次性——verify 即删)。 */ +/** + * 框架核心(contract/api/captcha.md 一-2):challenge 生命周期(生成/存储/TTL/一次性原子消费)、 场景路由(四)、错误语义(五)归此;生成与比对归 + * {@link CaptchaProvider}。 + * + *

存储 key(三-5):{@code 服务名:captcha:{provider}:{key}}(首段=服务名,共享实例租户边界)。 + */ public class CaptchaService { - private static final String ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"; - private static final SecureRandom RANDOM = new SecureRandom(); + /** + * GETDEL 等价 Lua(三-4【强制】原子消费):取答案与删除一次提交,兼容 < Redis 6.2 实例; 两步 get→delete 是缺陷(并发双 verify + * 竞态双双通过)。 + */ + private static final RedisScript GET_AND_DELETE = + RedisScript.of( + "local v = redis.call('GET', KEYS[1]); redis.call('DEL', KEYS[1]); return v", + String.class); private final StringRedisTemplate redis; private final String serviceName; + private final Map providers; + private final CaptchaProperties properties; - public CaptchaService(StringRedisTemplate redis, String serviceName) { + public CaptchaService( + StringRedisTemplate redis, + String serviceName, + List providers, + CaptchaProperties properties) { this.redis = redis; this.serviceName = serviceName; + this.providers = + providers.stream() + .collect( + Collectors.toUnmodifiableMap( + CaptchaProvider::id, Function.identity())); + this.properties = properties; } + /** REST 端点形状(六-1):provider/key/imageBase64 恒在,存量字段形态不动(CP10) */ + public record Challenge(String provider, String key, String imageBase64) {} + + /** 编程式分发产物(六-4:sms-otp/turnstile 档首发走编程式,HTTP 端点为触发档) */ + public record Issued(String provider, String key, Map payload) {} + + /** + * 分发(按场景路由,四-2:未配置场景走默认 Provider)。 + * + * @param scene 场景标识(可 null = 默认档) + * @param destination 发送目标(sms-otp 档必填,image 档忽略) + */ + public Issued issue(String scene, String destination) { + CaptchaProvider provider = route(scene); + CaptchaProvider.IssuedChallenge challenge = + provider.issue(new CaptchaProvider.IssueRequest(scene, destination)); + String key = null; + if (provider.mode() == CaptchaProvider.VerifyMode.LOCAL) { + // 三-1:key 服务端安全随机(≥128 bit),禁业务可预测值 + key = UUID.randomUUID().toString(); + redis.opsForValue().set(storeKey(provider.id(), key), challenge.secretAnswer(), ttl()); + } + return new Issued(provider.id(), key, challenge.payload()); + } + + /** + * 校验(六-2:内联受保护业务流,不设独立端点)。LOCAL = GETDEL 原子消费后按 Provider 比对 (三-3 对/错/异常均消费);REMOTE = + * 外委校验(二-1,token 一次性由上游保证)。 + */ + public boolean verify(String scene, String key, String answer) { + CaptchaProvider provider = route(scene); + if (provider.mode() == CaptchaProvider.VerifyMode.REMOTE) { + return provider.verifyRemote(answer, null); + } + String stored = redis.execute(GET_AND_DELETE, List.of(storeKey(provider.id(), key))); + return provider.matches(stored, answer); + } + + /** REST 端点便捷面(六-1):GET /api/v1/captcha 只服务 image 档,路由到他档即参数错(1001) */ + public Challenge challenge(String scene) { + Issued issued = issue(scene, null); + if (!"image".equals(issued.provider())) { + throw BusinessException.of( + GlobalErrorCode.INVALID_ARGUMENT, "场景 " + scene + " 非 image 档,不经图形分发端点"); + } + return new Challenge(issued.provider(), issued.key(), issued.payload().get("imageBase64")); + } + + // ---------- 存量便捷面(E2 形态,存量调用方零改动;语义锁死 image 档,不随默认路由漂移) ---------- + + /** 存量图形验证码响应(key + 裸 base64) */ public record Captcha(String key, String imageBase64) {} public Captcha generate() { - StringBuilder answer = new StringBuilder(4); - for (int i = 0; i < 4; i++) { - answer.append(ALPHABET.charAt(RANDOM.nextInt(ALPHABET.length()))); - } + CaptchaProvider image = provider("image"); + CaptchaProvider.IssuedChallenge challenge = + image.issue(new CaptchaProvider.IssueRequest(null, null)); String key = UUID.randomUUID().toString(); - redis.opsForValue().set(storeKey(key), answer.toString(), Duration.ofSeconds(120)); - return new Captcha(key, renderPng(answer.toString())); + redis.opsForValue().set(storeKey("image", key), challenge.secretAnswer(), ttl()); + return new Captcha(key, challenge.payload().get("imageBase64")); } - /** 一次性校验:对/错都消费该 key(防重放枚举) */ public boolean verify(String key, String answer) { - String stored = redis.opsForValue().get(storeKey(key)); - redis.delete(storeKey(key)); - return stored != null && stored.equalsIgnoreCase(answer == null ? "" : answer.trim()); + CaptchaProvider image = provider("image"); + String stored = redis.execute(GET_AND_DELETE, List.of(storeKey("image", key))); + return image.matches(stored, answer); } - String peek(String key) { - return redis.opsForValue().get(storeKey(key)); + // ---------- 内部 ---------- + + private CaptchaProvider route(String scene) { + String providerId = + properties.getScenes().getOrDefault(scene, properties.getDefaultProvider()); + return provider(providerId); } - long ttlSeconds(String key) { - Long ttl = redis.getExpire(storeKey(key)); - return ttl == null ? -1 : ttl; + private CaptchaProvider provider(String providerId) { + CaptchaProvider provider = providers.get(providerId); + if (provider == null) { + throw new IllegalStateException("未注册的验证码 Provider:" + providerId); + } + return provider; } - private String storeKey(String key) { - return RedisKeys.of(serviceName).parts("captcha", key); + private Duration ttl() { + Duration ttl = properties.getTtl(); + return ttl == null || ttl.isNegative() || ttl.isZero() ? Duration.ofSeconds(120) : ttl; } - private String renderPng(String text) { - try { - BufferedImage image = new BufferedImage(150, 50, BufferedImage.TYPE_INT_RGB); - Graphics2D g = image.createGraphics(); - g.setColor(Color.WHITE); - g.fillRect(0, 0, 150, 50); - for (int i = 0; i < 6; i++) { - g.setColor( - new Color(RANDOM.nextInt(200), RANDOM.nextInt(200), RANDOM.nextInt(200))); - g.setStroke(new BasicStroke(1.4f)); - g.drawLine( - RANDOM.nextInt(150), - RANDOM.nextInt(50), - RANDOM.nextInt(150), - RANDOM.nextInt(50)); - } - g.setFont(new Font("SansSerif", Font.BOLD, 30)); - for (int i = 0; i < text.length(); i++) { - g.setColor( - new Color( - 20 + RANDOM.nextInt(100), - 20 + RANDOM.nextInt(100), - 20 + RANDOM.nextInt(100))); - g.drawString(String.valueOf(text.charAt(i)), 15 + i * 32, 36); - } - g.dispose(); - ByteArrayOutputStream out = new ByteArrayOutputStream(); - ImageIO.write(image, "png", out); - return Base64.getEncoder().encodeToString(out.toByteArray()); - } catch (Exception e) { - throw new IllegalStateException("captcha render failed", e); - } + String storeKey(String providerId, String key) { + return RedisKeys.of(serviceName).parts("captcha", providerId, key); + } + + String peek(String providerId, String key) { + return redis.opsForValue().get(storeKey(providerId, key)); + } + + long ttlSeconds(String providerId, String key) { + Long ttl = redis.getExpire(storeKey(providerId, key)); + return ttl == null ? -1 : ttl; } } diff --git a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/ImageCaptchaProvider.java b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/ImageCaptchaProvider.java new file mode 100644 index 0000000..44532b8 --- /dev/null +++ b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/ImageCaptchaProvider.java @@ -0,0 +1,77 @@ +package io.github.ydonghao.yarch.captcha; + +import java.awt.BasicStroke; +import java.awt.Color; +import java.awt.Font; +import java.awt.Graphics2D; +import java.awt.image.BufferedImage; +import java.io.ByteArrayOutputStream; +import java.security.SecureRandom; +import java.util.Base64; +import java.util.Map; +import javax.imageio.ImageIO; + +/** image 档(contract/api/captcha.md 二-2,LOCAL 默认档):4 位去混淆字符集【强制】;渲染样式自由(CP9)。 */ +public class ImageCaptchaProvider implements CaptchaProvider { + + /** 去混淆 32 字符集(二-2:去 I/O/0/1,跨栈 conformance 向量 V 系断言对象) */ + static final String ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"; + + private static final SecureRandom RANDOM = new SecureRandom(); + + @Override + public String id() { + return "image"; + } + + @Override + public VerifyMode mode() { + return VerifyMode.LOCAL; + } + + @Override + public IssuedChallenge issue(IssueRequest request) { + StringBuilder answer = new StringBuilder(4); + for (int i = 0; i < 4; i++) { + answer.append(ALPHABET.charAt(RANDOM.nextInt(ALPHABET.length()))); + } + return new IssuedChallenge( + answer.toString(), Map.of("imageBase64", renderPng(answer.toString()))); + } + + // matches 用默认口径:trim + 大小写不敏感(二-2) + + private String renderPng(String text) { + try { + BufferedImage image = new BufferedImage(150, 50, BufferedImage.TYPE_INT_RGB); + Graphics2D g = image.createGraphics(); + g.setColor(Color.WHITE); + g.fillRect(0, 0, 150, 50); + for (int i = 0; i < 6; i++) { + g.setColor( + new Color(RANDOM.nextInt(200), RANDOM.nextInt(200), RANDOM.nextInt(200))); + g.setStroke(new BasicStroke(1.4f)); + g.drawLine( + RANDOM.nextInt(150), + RANDOM.nextInt(50), + RANDOM.nextInt(150), + RANDOM.nextInt(50)); + } + g.setFont(new Font("SansSerif", Font.BOLD, 30)); + for (int i = 0; i < text.length(); i++) { + g.setColor( + new Color( + 20 + RANDOM.nextInt(100), + 20 + RANDOM.nextInt(100), + 20 + RANDOM.nextInt(100))); + g.drawString(String.valueOf(text.charAt(i)), 15 + i * 32, 36); + } + g.dispose(); + ByteArrayOutputStream out = new ByteArrayOutputStream(); + ImageIO.write(image, "png", out); + return Base64.getEncoder().encodeToString(out.toByteArray()); + } catch (Exception e) { + throw new IllegalStateException("captcha render failed", e); + } + } +} diff --git a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/SmsOtpProvider.java b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/SmsOtpProvider.java new file mode 100644 index 0000000..934feab --- /dev/null +++ b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/SmsOtpProvider.java @@ -0,0 +1,55 @@ +package io.github.ydonghao.yarch.captcha; + +import io.github.ydonghao.yarch.common.code.BusinessException; +import io.github.ydonghao.yarch.common.code.GlobalErrorCode; +import java.security.SecureRandom; +import java.util.Map; + +/** sms-otp 档(contract/api/captcha.md 二-3,LOCAL):6 位数字 OTP;分发通道宿主注入 {@link SmsSender};目标回显脱敏。 */ +public class SmsOtpProvider implements CaptchaProvider { + + private static final SecureRandom RANDOM = new SecureRandom(); + + private final SmsSender sender; + + public SmsOtpProvider(SmsSender sender) { + this.sender = sender; + } + + @Override + public String id() { + return "sms-otp"; + } + + @Override + public VerifyMode mode() { + return VerifyMode.LOCAL; + } + + @Override + public IssuedChallenge issue(IssueRequest request) { + String destination = request.destination(); + if (destination == null || destination.isBlank()) { + throw BusinessException.of(GlobalErrorCode.INVALID_ARGUMENT, "sms-otp 档须提供发送目标"); + } + String otp = String.format("%06d", RANDOM.nextInt(1_000_000)); + sender.send(destination, otp); + return new IssuedChallenge(otp, Map.of("destination", mask(destination))); + } + + /** 精确匹配(二-3 禁宽松比对):仅去首尾空白,无大小写折中 */ + @Override + public boolean matches(String storedAnswer, String attempted) { + return storedAnswer != null && attempted != null && storedAnswer.equals(attempted.trim()); + } + + /** 目标脱敏回显(二-3):≥7 位留前 3 后 4,其余全遮 */ + static String mask(String destination) { + if (destination.length() < 7) { + return "****"; + } + return destination.substring(0, 3) + + "****" + + destination.substring(destination.length() - 4); + } +} diff --git a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/SmsSender.java b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/SmsSender.java new file mode 100644 index 0000000..270800d --- /dev/null +++ b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/SmsSender.java @@ -0,0 +1,16 @@ +package io.github.ydonghao.yarch.captcha; + +/** + * OTP 分发通道 SPI(contract/api/captcha.md 二-3):发送通道由宿主注入——yarch 不背通知渠道抽象 (通知领域契约排队中 EP7,届时对齐)。宿主提供本接口 + * Bean 后 sms-otp 档自动装配。 + */ +public interface SmsSender { + + /** + * 发送 OTP 到目标(手机号)。 + * + * @param destination 发送目标(明文,仅在此处出现;回显侧已由框架脱敏) + * @param content 6 位数字 OTP + */ + void send(String destination, String content); +} diff --git a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/TurnstileProvider.java b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/TurnstileProvider.java new file mode 100644 index 0000000..f6d08a4 --- /dev/null +++ b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/TurnstileProvider.java @@ -0,0 +1,85 @@ +package io.github.ydonghao.yarch.captcha; + +import com.fasterxml.jackson.databind.ObjectMapper; +import java.net.URI; +import java.net.URLEncoder; +import java.net.http.HttpClient; +import java.net.http.HttpRequest; +import java.net.http.HttpResponse; +import java.nio.charset.StandardCharsets; +import java.util.Map; + +/** turnstile 档(contract/api/captcha.md 二-4,REMOTE):siteKey 透出 + siteverify 外委校验;token 不落 Redis。 */ +public class TurnstileProvider implements CaptchaProvider { + + /** siteverify 调用器(构造注入,测试可打桩) */ + @FunctionalInterface + public interface SiteVerifyCaller { + boolean call(String verifyUrl, String secret, String response, String remoteIp); + } + + private static final ObjectMapper MAPPER = new ObjectMapper(); + + private final CaptchaProperties.Turnstile props; + private final SiteVerifyCaller caller; + + public TurnstileProvider(CaptchaProperties.Turnstile props) { + this(props, TurnstileProvider::siteVerify); + } + + TurnstileProvider(CaptchaProperties.Turnstile props, SiteVerifyCaller caller) { + this.props = props; + this.caller = caller; + } + + @Override + public String id() { + return "turnstile"; + } + + @Override + public VerifyMode mode() { + return VerifyMode.REMOTE; + } + + @Override + public IssuedChallenge issue(IssueRequest request) { + // REMOTE 档:无服务端答案(二-1),分发即接入配置透出(二-4:前端嵌 widget 自取 token) + return new IssuedChallenge(null, Map.of("siteKey", props.getSiteKey())); + } + + @Override + public boolean verifyRemote(String token, String remoteIp) { + if (token == null || token.isBlank()) { + return false; + } + return caller.call(props.getVerifyUrl(), props.getSecretKey(), token, remoteIp); + } + + /** 默认调用器:POST siteverify(form 编码),解析 {@code {"success":bool}};上游不可达一律 false(fail closed) */ + static boolean siteVerify(String verifyUrl, String secret, String response, String remoteIp) { + try { + StringBuilder form = + new StringBuilder("secret=") + .append(URLEncoder.encode(secret, StandardCharsets.UTF_8)) + .append("&response=") + .append(URLEncoder.encode(response, StandardCharsets.UTF_8)); + if (remoteIp != null && !remoteIp.isBlank()) { + form.append("&remoteip=") + .append(URLEncoder.encode(remoteIp, StandardCharsets.UTF_8)); + } + HttpRequest request = + HttpRequest.newBuilder(URI.create(verifyUrl)) + .header("Content-Type", "application/x-www-form-urlencoded") + .POST(HttpRequest.BodyPublishers.ofString(form.toString())) + .build(); + String body = + HttpClient.newHttpClient() + .send(request, HttpResponse.BodyHandlers.ofString()) + .body(); + return MAPPER.readTree(body).path("success").asBoolean(false); + } catch (Exception e) { + return false; + } + } +} diff --git a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/YarchCaptchaAutoConfiguration.java b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/YarchCaptchaAutoConfiguration.java index 1ab7cb0..95478b2 100644 --- a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/YarchCaptchaAutoConfiguration.java +++ b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/captcha/YarchCaptchaAutoConfiguration.java @@ -1,23 +1,54 @@ package io.github.ydonghao.yarch.captcha; import io.github.ydonghao.yarch.common.web.RestResponse; +import io.github.ydonghao.yarch.web.ratelimit.RateLimited; +import org.springframework.beans.factory.ObjectProvider; import org.springframework.beans.factory.annotation.Value; import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; +import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.data.redis.core.StringRedisTemplate; import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; -/** 验证码装配:服务 + 可选标准入口(yarch.captcha.endpoint-enabled=false 关闭) */ +/** + * 验证码装配(contract/api/captcha.md):三档 Provider + 框架核心 + 可选标准入口(yarch.captcha.endpoint-enabled=false + * 关闭) + */ @AutoConfiguration +@EnableConfigurationProperties(CaptchaProperties.class) public class YarchCaptchaAutoConfiguration { + @Bean + public ImageCaptchaProvider imageCaptchaProvider() { + return new ImageCaptchaProvider(); + } + + /** sms-otp 档:宿主提供 {@link SmsSender} 分发通道 Bean 才装配(二-3) */ + @Bean + @ConditionalOnBean(SmsSender.class) + public SmsOtpProvider smsOtpProvider(SmsSender sender) { + return new SmsOtpProvider(sender); + } + + /** turnstile 档:接入凭据配置存在才装配(二-4) */ + @Bean + @ConditionalOnProperty("yarch.captcha.turnstile.secret-key") + public TurnstileProvider turnstileProvider(CaptchaProperties properties) { + return new TurnstileProvider(properties.getTurnstile()); + } + @Bean public CaptchaService captchaService( StringRedisTemplate redis, - @Value("${spring.application.name:unknown-service}") String serviceName) { - return new CaptchaService(redis, serviceName); + @Value("${spring.application.name:unknown-service}") String serviceName, + ObjectProvider providers, + CaptchaProperties properties) { + return new CaptchaService( + redis, serviceName, providers.orderedStream().toList(), properties); } @Bean @@ -38,9 +69,12 @@ static class CaptchaController { this.captchaService = captchaService; } + /** 六-1:image 默认档端点;scene 可选路由参数(四)。五-1:默认挂限流(1006,60s/10 次【参考】档) */ @GetMapping("/api/v1/captcha") - public RestResponse captcha() { - return RestResponse.ok(captchaService.generate()); + @RateLimited(key = "captcha", permits = 10, windowSeconds = 60) + public RestResponse captcha( + @RequestParam(name = "scene", required = false) String scene) { + return RestResponse.ok(captchaService.challenge(scene)); } } } diff --git a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/captcha/CaptchaEndpointTest.java b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/captcha/CaptchaEndpointTest.java new file mode 100644 index 0000000..811bb9f --- /dev/null +++ b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/captcha/CaptchaEndpointTest.java @@ -0,0 +1,88 @@ +package io.github.ydonghao.yarch.captcha; + +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assumptions.assumeTrue; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; + +import io.github.ydonghao.yarch.test.containers.RedisTestDb; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.SpringBootConfiguration; +import org.springframework.boot.autoconfigure.EnableAutoConfiguration; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.test.context.TestConfiguration; +import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc; +import org.springframework.context.annotation.Bean; +import org.springframework.test.context.DynamicPropertyRegistry; +import org.springframework.test.context.DynamicPropertySource; +import org.springframework.test.web.servlet.MockMvc; +import org.springframework.test.web.servlet.MvcResult; + +/** + * 六-1 端点与 V11 限流:GET /api/v1/captcha 字段恒在(provider 增量 + key/imageBase64 存量形态); 限流 1006(@RateLimited + * 60s/10 次【参考】档)。单方法串行自控计数顺序(窗口内共享)。 + */ +@SpringBootTest( + classes = {CaptchaEndpointTest.App.class, CaptchaEndpointTest.Fakes.class}, + properties = "yarch.captcha.scenes.login=sms-otp") +@AutoConfigureMockMvc +class CaptchaEndpointTest { + + @SpringBootConfiguration + @EnableAutoConfiguration + static class App {} + + @TestConfiguration + static class Fakes { + @Bean + SmsSender noopSmsSender() { + return (destination, content) -> {}; + } + } + + static final RedisTestDb redis = RedisTestDb.dockerAvailable() ? RedisTestDb.start() : null; + + @DynamicPropertySource + static void props(DynamicPropertyRegistry registry) { + if (redis != null) { + redis.register(registry); + } + } + + @BeforeAll + static void requireDocker() { + assumeTrue(redis != null, "本机无 Docker,跳过验证码端点测试"); + } + + @Autowired MockMvc mockMvc; + + @Test + void endpointFieldsAndRateLimit() throws Exception { + // 1) 非 image 档场景经图形端点 = 1001(六-1),消耗 1 个限流名额 + mockMvc.perform(get("/api/v1/captcha").param("scene", "login")) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(1001)); + + // 2) 默认档:字段恒在(provider 增量;key/imageBase64 存量形态不动) + mockMvc.perform(get("/api/v1/captcha")) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.code").value(0)) + .andExpect(jsonPath("$.data.provider").value("image")) + .andExpect(jsonPath("$.data.key").isNotEmpty()) + .andExpect(jsonPath("$.data.imageBase64").isNotEmpty()); + + // 3) V11:60s 窗口 10 次名额耗尽后报 1006(五-1)——已消耗 2 次,再打 8 次满额 + for (int i = 0; i < 8; i++) { + mockMvc.perform(get("/api/v1/captcha")).andExpect(status().isOk()); + } + MvcResult limited = mockMvc.perform(get("/api/v1/captcha")).andReturn(); + int status = limited.getResponse().getStatus(); + String body = limited.getResponse().getContentAsString(); + assertTrue( + status == 429 || body.contains("\"code\":1006"), + "V11:超限应报 1006(429),实际 " + status + " " + body); + } +} diff --git a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/captcha/CaptchaServiceTest.java b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/captcha/CaptchaServiceTest.java index eeb4ed7..a1d45b0 100644 --- a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/captcha/CaptchaServiceTest.java +++ b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/captcha/CaptchaServiceTest.java @@ -1,30 +1,53 @@ package io.github.ydonghao.yarch.captcha; +import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; import static org.junit.jupiter.api.Assumptions.assumeTrue; +import io.github.ydonghao.yarch.common.code.BusinessException; import io.github.ydonghao.yarch.test.containers.RedisTestDb; +import java.util.List; +import java.util.concurrent.CopyOnWriteArrayList; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.TimeUnit; import org.junit.jupiter.api.BeforeAll; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.SpringBootConfiguration; import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.test.context.TestConfiguration; +import org.springframework.context.annotation.Bean; import org.springframework.test.context.DynamicPropertyRegistry; import org.springframework.test.context.DynamicPropertySource; -/** E2 验收:生成(base64+TTL)、一次性校验(对/错均消费)、大小写不敏感 */ +/** + * captcha.md v1.0 跨栈一致性向量(附录 V 系)——java 首批落地;golang/python 触发时同源引用。 覆盖:V1-V5(image + * 生命周期)、V6(原子消费)、V7(TTL)、V8(sms-otp)、V10(场景路由)+ 存量便捷面。 + */ @SpringBootTest( - classes = CaptchaServiceTest.App.class, - properties = "yarch.captcha.endpoint-enabled=false") + classes = {CaptchaServiceTest.App.class, CaptchaServiceTest.Fakes.class}, + properties = {"yarch.captcha.endpoint-enabled=false", "yarch.captcha.scenes.login=sms-otp"}) class CaptchaServiceTest { @SpringBootConfiguration @EnableAutoConfiguration static class App {} + /** V8:sms-otp 档装配条件——宿主 SmsSender(静态捕获,测试方法间共享,断言用差量) */ + @TestConfiguration + static class Fakes { + @Bean + SmsSender capturingSmsSender() { + return (destination, content) -> SENT.add(content); + } + } + static final RedisTestDb redis = RedisTestDb.dockerAvailable() ? RedisTestDb.start() : null; @DynamicPropertySource @@ -41,19 +64,124 @@ static void requireDocker() { @Autowired CaptchaService captchaService; + static final List SENT = new CopyOnWriteArrayList<>(); + + // ---------- V1-V5:image 档生命周期 ---------- + + @Test + void v1_correctAnswerVerifiesOnce() { + CaptchaService.Issued issued = captchaService.issue(null, null); + assertEquals("image", issued.provider()); + String answer = captchaService.peek("image", issued.key()); + + assertTrue(captchaService.verify(null, issued.key(), answer.toLowerCase()), "V5:大小写不敏感"); + assertFalse(captchaService.verify(null, issued.key(), answer), "V2:一次性——第二次必败"); + } + @Test - void generatesImageWithTtlAndOneShotVerify() { - CaptchaService.Captcha captcha = captchaService.generate(); - assertNotNull(captcha.key()); - assertTrue(captcha.imageBase64().length() > 100, "PNG base64 应非空"); - assertTrue(captchaService.ttlSeconds(captcha.key()) > 0, "答案须带 TTL"); + void v5_answerWithSurroundingWhitespaceMatches() { + CaptchaService.Issued issued = captchaService.issue(null, null); + String answer = captchaService.peek("image", issued.key()); + assertTrue( + captchaService.verify(null, issued.key(), " " + answer.toLowerCase() + " "), + "V5:trim + 大小写不敏感"); + } - String answer = captchaService.peek(captcha.key()); - assertTrue(captchaService.verify(captcha.key(), answer.toLowerCase()), "大小写不敏感"); - assertFalse(captchaService.verify(captcha.key(), answer), "一次性:第二次必败"); + @Test + void v3_wrongAnswerConsumesKey() { + CaptchaService.Issued issued = captchaService.issue(null, null); + String answer = captchaService.peek("image", issued.key()); + assertFalse(captchaService.verify(null, issued.key(), "XXXX"), "错答案验证失败"); + assertFalse(captchaService.verify(null, issued.key(), answer), "V3:错答案后 key 已消费(防重放枚举)"); + } + + @Test + void v4_unknownKeyFails() { + assertFalse(captchaService.verify(null, "00000000-0000-0000-0000-000000000000", "ABCD")); + } + + @Test + void v7_ttlWithinDefaultWindow() { + CaptchaService.Issued issued = captchaService.issue(null, null); + long ttl = captchaService.ttlSeconds("image", issued.key()); + assertTrue(ttl > 0 && ttl <= 120, "V7:0 < TTL ≤ 120,实际 " + ttl); + } - CaptchaService.Captcha other = captchaService.generate(); - assertNotNull(captchaService.peek(other.key())); - assertFalse(captchaService.verify(other.key(), "XXXX"), "错答案验证失败(且已消费)"); + @Test + void v6_concurrentVerifyExactlyOneWins() throws Exception { + CaptchaService.Issued issued = captchaService.issue(null, null); + String answer = captchaService.peek("image", issued.key()); + int threads = 8; + CountDownLatch start = new CountDownLatch(1); + CountDownLatch done = new CountDownLatch(threads); + List results = new CopyOnWriteArrayList<>(); + ExecutorService pool = Executors.newFixedThreadPool(threads); + for (int i = 0; i < threads; i++) { + pool.submit( + () -> { + try { + start.await(); + results.add(captchaService.verify(null, issued.key(), answer)); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } finally { + done.countDown(); + } + }); + } + start.countDown(); + assertTrue(done.await(5, TimeUnit.SECONDS)); + pool.shutdownNow(); + assertEquals( + 1, + results.stream().filter(Boolean::booleanValue).count(), + "V6:并发校验恰一个成功(GETDEL 原子)"); + } + + // ---------- V8:sms-otp 档 ---------- + + @Test + void v8_smsOtpSendsSixDigitsAndVerifiesExactly() { + int before = SENT.size(); + CaptchaService.Issued issued = captchaService.issue("login", "13800138000"); + assertEquals("sms-otp", issued.provider(), "V10:scenes.login 映射生效"); + assertEquals(before + 1, SENT.size(), "OTP 已通过宿主 SmsSender 发送"); + String otp = SENT.get(SENT.size() - 1); + assertTrue(otp.matches("\\d{6}"), "6 位数字 OTP"); + assertEquals("138****8000", issued.payload().get("destination"), "目标脱敏回显"); + + assertTrue(captchaService.verify("login", issued.key(), otp), "正确 OTP 通过"); + CaptchaService.Issued second = captchaService.issue("login", "13800138000"); + String secondOtp = SENT.get(SENT.size() - 1); + String wrong = secondOtp.equals("000000") ? "111111" : "000000"; + assertFalse(captchaService.verify("login", second.key(), wrong), "V8:错码失败(精确比对)"); + assertFalse(captchaService.verify("login", second.key(), secondOtp), "V3:错试后已消费"); + } + + // ---------- V10:场景路由 ---------- + + @Test + void v10_unconfiguredSceneFallsBackToDefault() { + assertEquals( + "image", captchaService.issue("register", null).provider(), "未配置场景走默认 Provider"); + assertEquals("image", captchaService.issue(null, null).provider(), "null 场景走默认"); + } + + @Test + void legacyFacadeStaysOnImage() { + // 存量便捷面(E2 形态):语义锁死 image 档,不随路由配置漂移 + CaptchaService.Captcha legacy = captchaService.generate(); + assertNotNull(legacy.key()); + assertTrue(legacy.imageBase64().length() > 100); + assertTrue( + captchaService.verify( + legacy.key(), captchaService.peek("image", legacy.key()).toLowerCase())); + } + + @Test + void challengeRejectsNonImageScene() { + BusinessException e = + assertThrows(BusinessException.class, () -> captchaService.challenge("login")); + assertEquals(1001, e.getErrorCode().code(), "六-1:非 image 档场景经图形端点 = 1001"); } } diff --git a/stacks/java/starter/yarch-captcha-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/captcha/TurnstileProviderTest.java b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/captcha/TurnstileProviderTest.java new file mode 100644 index 0000000..21ef2b2 --- /dev/null +++ b/stacks/java/starter/yarch-captcha-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/captcha/TurnstileProviderTest.java @@ -0,0 +1,49 @@ +package io.github.ydonghao.yarch.captcha; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Map; +import org.junit.jupiter.api.Test; + +/** V9:turnstile 档(REMOTE)——stub siteverify 通过/失败两分支;全程零服务端答案存储(二-4)。 */ +class TurnstileProviderTest { + + private final CaptchaProperties.Turnstile props = new CaptchaProperties.Turnstile(); + + @Test + void v9_issueExposesSiteKeyWithoutServerSideAnswer() { + props.setSiteKey("site-key-1"); + TurnstileProvider provider = new TurnstileProvider(props, (u, s, r, ip) -> true); + + CaptchaProvider.IssuedChallenge issued = + provider.issue(new CaptchaProvider.IssueRequest(null, null)); + assertNull(issued.secretAnswer(), "REMOTE 档无服务端答案(二-1)"); + assertEquals(Map.of("siteKey", "site-key-1"), issued.payload()); + assertEquals(CaptchaProvider.VerifyMode.REMOTE, provider.mode()); + } + + @Test + void v9_verifyDelegatesToCaller() { + TurnstileProvider pass = new TurnstileProvider(props, (u, s, r, ip) -> true); + TurnstileProvider fail = new TurnstileProvider(props, (u, s, r, ip) -> false); + assertTrue(pass.verifyRemote("tok", "10.0.0.1")); + assertFalse(fail.verifyRemote("tok", "10.0.0.1")); + } + + @Test + void v9_blankTokenFails() { + TurnstileProvider provider = new TurnstileProvider(props, (u, s, r, ip) -> true); + assertFalse(provider.verifyRemote(null, null)); + assertFalse(provider.verifyRemote(" ", null)); + } + + @Test + void v9_upstreamUnreachableFailsClosed() { + props.setVerifyUrl("http://127.0.0.1:1/siteverify"); // 不可达端点 + TurnstileProvider provider = new TurnstileProvider(props); + assertFalse(provider.verifyRemote("tok", null), "上游不可达一律 false(fail closed)"); + } +} diff --git a/stacks/java/starter/yarch-test-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/test/ContractAsserts.java b/stacks/java/starter/yarch-test-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/test/ContractAsserts.java index 1e8b300..a25479c 100644 --- a/stacks/java/starter/yarch-test-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/test/ContractAsserts.java +++ b/stacks/java/starter/yarch-test-spring-boot-starter/src/main/java/io/github/ydonghao/yarch/test/ContractAsserts.java @@ -17,7 +17,7 @@ public final class ContractAsserts { private ContractAsserts() {} - /** contract/api/error-codes.md v1.0 全表:code → identifier|message|http */ + /** contract/api/error-codes.md v1.1 全表:code → identifier|message|http */ private static final Map CONTRACT_TABLE = Map.ofEntries( Map.entry(1000, "INTERNAL_ERROR|内部错误|500"), @@ -32,9 +32,10 @@ private ContractAsserts() {} Map.entry(2001, "UNAUTHORIZED|未认证|401"), Map.entry(2002, "CREDENTIALS_EXPIRED|凭证已过期|401"), Map.entry(2003, "FORBIDDEN|权限不足|403"), - Map.entry(2004, "ACCOUNT_DISABLED|账号已禁用|403")); + Map.entry(2004, "ACCOUNT_DISABLED|账号已禁用|403"), + Map.entry(2005, "CAPTCHA_INVALID|验证码校验失败|400")); - /** 全表核对 GlobalErrorCode 与契约字面量(13 码 + HTTP 映射 + 默认文案) */ + /** 全表核对 GlobalErrorCode 与契约字面量(14 码 + HTTP 映射 + 默认文案) */ public static void assertErrorCodeTable() { assertEquals( CONTRACT_TABLE.size(), diff --git a/stacks/java/starter/yarch-test-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/test/ContractAssertsSelfTest.java b/stacks/java/starter/yarch-test-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/test/ContractAssertsSelfTest.java index 8445d88..cd400db 100644 --- a/stacks/java/starter/yarch-test-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/test/ContractAssertsSelfTest.java +++ b/stacks/java/starter/yarch-test-spring-boot-starter/src/test/java/io/github/ydonghao/yarch/test/ContractAssertsSelfTest.java @@ -16,7 +16,7 @@ class ContractAssertsSelfTest { @Test void errorCodeTableAssertsPass() { - // 全表核对(13 码 + HTTP 映射 + 默认文案),任何漂移在此失败 + // 全表核对(14 码 + HTTP 映射 + 默认文案),任何漂移在此失败 ContractAsserts.assertErrorCodeTable(); } diff --git a/stacks/python/PLAN.md b/stacks/python/PLAN.md index e885cd6..3d948a8 100644 --- a/stacks/python/PLAN.md +++ b/stacks/python/PLAN.md @@ -179,7 +179,9 @@ uvx yarch-init@latest --service ysaas-scan --out ysaas-scan 12. `python-stack.yml`(全量机检 + 生成后冒烟 + 双矩阵 3.12/3.13); 13. README + 架构图 + **随批登记**:stacks/README 状态行、docs/architecture.md 第三节与三·五、contract/README 术语对照表加 python 列、tools/locate-scaffolds.cjs 的 STACKS 表。 -**触发式增长(一规约一 module,不做配置档)**:auth(JWT 2xxx,golang 第二批对偶件)、captcha、kafka、minio、async 档(AsyncSession + asyncpg)、simple 档模板、qdrant/es 等数据件。 +**触发式增长(一规约一 module,不做配置档)**:auth(JWT 2xxx,golang 第二批对偶件)、kafka、minio、async 档(AsyncSession + asyncpg)、simple 档模板、qdrant/es 等数据件。 + +**captcha module 首批落地(2026-09-18,contract/api/captcha.md v1.0 CP1-CP10)**:`yarch_python.captcha`——Provider SPI 三档(image/SmsOtpProvider 宿主 SmsSender 注入+目标脱敏/TurnstileProvider SiteVerifyCaller 打桩+fail-closed)+ 框架核心 CaptchaService(GETDEL 原子消费/场景路由 Options.scenes+default_provider/装配 fail fast/非 image 场景经端点 1001)+ CaptchaStore(redis getdel)+ create_router(GET /api/v1/captcha + 默认 per-IP 限流 LocalLimiter,redis 档传 FixedWindowLimiter,超限 1006);PNG 渲染纯 stdlib(位图字模 + zlib/struct 编码,零 Pillow——CP9 渲染自由);校验失败 2005 CAPTCHA_INVALID 三态合一;测试向量 V1-V11 同源落地(单测 12 + TC 真 Redis 3 + 端点限流)。 ## 八、开放问题与风险 diff --git a/stacks/python/packages/yarch-python/src/yarch_python/captcha/__init__.py b/stacks/python/packages/yarch-python/src/yarch_python/captcha/__init__.py new file mode 100644 index 0000000..3342a7f --- /dev/null +++ b/stacks/python/packages/yarch-python/src/yarch_python/captcha/__init__.py @@ -0,0 +1,349 @@ +"""契约内核:验证码框架(captcha.md v1.0)——Provider SPI 三档 + 框架核心。 + +形态 = 进程内组件(CP2):渠道差异(图形/OTP/第三方)是框架内多态,不构成服务边界。 +框架核心管 challenge 生命周期(生成/存储/TTL/一次性原子消费三)、场景路由(四)、 +错误语义(2005 三态合一五-2);Provider 只管生成挑战与答案比对/远程校验(二)。 +""" + +import secrets +import threading +import time +import uuid +from dataclasses import dataclass, field +from enum import Enum +from typing import Any, Protocol + +from fastapi import APIRouter, Request + +from yarch_python import errcode +from yarch_python.captcha._png import render_png_base64 +from yarch_python.redix import Keys +from yarch_python.web import ok +from yarch_python.xerror import BizError + +# 二-2【强制】:去混淆 32 字符集(跨栈 conformance 断言对象) +ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789" +DEFAULT_LEN = 4 # 二-2【强制】:4 位 +DEFAULT_TTL_S = 120 # 三-2【推荐】:120s,Options.ttl_s 可配;OTP 档可放宽至 300s + + +class VerifyMode(Enum): + """校验模式二分(二-1)。""" + + LOCAL = "LOCAL" # 本地校验型:答案由框架核心托管,一次性原子消费(三) + REMOTE = "REMOTE" # 远程校验型:无服务端答案存储,一次性语义由上游保证 + + +@dataclass +class IssueRequest: + """分发请求(scene=路由场景可空;destination=发送目标,sms-otp 档必填)。""" + + scene: str | None = None + destination: str | None = None + + +@dataclass +class IssuedChallenge: + """分发产物:secret_answer 机密答案(LOCAL 进存储,REMOTE 恒 None);payload 公开载体。""" + + secret_answer: str | None + payload: dict[str, str] + + +class CaptchaProvider: + """Provider SPI 基类(一-2/二):保留字 id = image / sms-otp / turnstile(一-3)。""" + + id: str = "" + mode: VerifyMode = VerifyMode.LOCAL + + def issue(self, request: IssueRequest) -> IssuedChallenge: + raise NotImplementedError + + def matches(self, stored: str | None, attempted: str | None) -> bool: + """默认比对口径(二-2):attempted 去首尾空白 + 大小写不敏感;精确档(二-3)覆写。""" + if not stored or attempted is None: + return False + return stored.lower() == attempted.strip().lower() + + +class ImageCaptchaProvider(CaptchaProvider): + """image 档(二-2,LOCAL 默认档):4 位去混淆字符集【强制】;渲染样式自由(CP9)。""" + + id = "image" + mode = VerifyMode.LOCAL + + def issue(self, request: IssueRequest) -> IssuedChallenge: + answer = "".join(secrets.choice(ALPHABET) for _ in range(DEFAULT_LEN)) + return IssuedChallenge( + secret_answer=answer, + payload={"imageBase64": render_png_base64(answer)}, + ) + + # matches 用默认口径:trim + 大小写不敏感 + + +class SmsSender(Protocol): + """OTP 分发通道 SPI(二-3):由宿主注入——yarch 不背通知渠道抽象(EP7 届时对齐)。""" + + def send(self, destination: str, content: str) -> None: ... + + +def mask_destination(destination: str) -> str: + """目标脱敏回显(二-3):≥7 位留前 3 后 4,其余全遮。""" + if len(destination) < 7: + return "****" + return destination[:3] + "****" + destination[-4:] + + +class SmsOtpProvider(CaptchaProvider): + """sms-otp 档(二-3,LOCAL):6 位数字 OTP(安全随机源);精确匹配(禁宽松比对)。""" + + id = "sms-otp" + mode = VerifyMode.LOCAL + + def __init__(self, sender: SmsSender): + self._sender = sender + + def issue(self, request: IssueRequest) -> IssuedChallenge: + if not request.destination: + raise BizError(errcode.Code.INVALID_ARGUMENT, detail="sms-otp 档须提供发送目标") + otp = f"{secrets.randbelow(10**6):06d}" + self._sender.send(request.destination, otp) + return IssuedChallenge( + secret_answer=otp, + payload={"destination": mask_destination(request.destination)}, + ) + + def matches(self, stored: str | None, attempted: str | None) -> bool: + """精确匹配(二-3):仅去首尾空白,无大小写折中。""" + return bool(stored) and attempted is not None and stored == attempted.strip() + + +@dataclass +class TurnstileConfig: + """turnstile 档接入配置(二-4):secret_key 非空时该档才装配。""" + + site_key: str = "" + secret_key: str = "" + verify_url: str = "https://challenges.cloudflare.com/turnstile/v0/siteverify" + + +class SiteVerifyCaller(Protocol): + """siteverify 调用器(测试打桩位)。""" + + def __call__( + self, verify_url: str, secret: str, response: str, remote_ip: str | None + ) -> bool: ... + + +def _siteverify(verify_url: str, secret: str, response: str, remote_ip: str | None) -> bool: + """默认调用器:POST siteverify(form 编码),解析 success;上游不可达 fail closed。""" + import httpx + + data = {"secret": secret, "response": response} + if remote_ip: + data["remoteip"] = remote_ip + try: + r = httpx.post(verify_url, data=data, timeout=5.0) + return bool(r.json().get("success", False)) + except Exception: + return False + + +class TurnstileProvider(CaptchaProvider): + """turnstile 档(二-4,REMOTE):siteKey 透出 + siteverify 外委;token 不落存储(三-5)。""" + + id = "turnstile" + mode = VerifyMode.REMOTE + + def __init__(self, config: TurnstileConfig, caller: SiteVerifyCaller | None = None): + self._config = config + self._caller = caller or _siteverify + + def issue(self, request: IssueRequest) -> IssuedChallenge: + # REMOTE 档:无服务端答案(二-1),分发即接入配置透出(前端嵌 widget 自取 token) + return IssuedChallenge(secret_answer=None, payload={"siteKey": self._config.site_key}) + + def verify_remote(self, token: str | None, remote_ip: str | None = None) -> bool: + if not token or not token.strip(): + return False + return bool( + self._caller(self._config.verify_url, self._config.secret_key, token, remote_ip) + ) + + +@dataclass +class Options: + """装配配置(三-2/四-2/二-3/二-4)。租户级覆盖是宿主应用层扩展位(四-3)。""" + + default_provider: str = "image" # 四-2:未配置场景一律走此档 + scenes: dict[str, str] = field(default_factory=dict) # scene → provider 覆盖映射 + ttl_s: int = DEFAULT_TTL_S # 三-2【推荐】 + sms_sender: SmsSender | None = None # 非 None 注册 sms-otp 档 + turnstile: TurnstileConfig | None = None # 非 None 注册 turnstile 档 + + +@dataclass +class Issued: + """编程式分发产物(六-4:sms-otp/turnstile 档首发走编程式,HTTP 端点为触发档)。""" + + provider: str + key: str | None + payload: dict[str, str] + + +@dataclass +class Challenge: + """REST 端点形状(六-1):provider/key/imageBase64 恒在(image 档,存量字段形态不动 CP10)。""" + + provider: str + key: str + image_base64: str + + +class ChallengeStore(Protocol): + """challenge 存储端口(一次性 token 语义)——CaptchaStore 为 Redis 实现,测试可注入内存 fake。""" + + def issue(self, key: str, code: str, ttl_s: int) -> None: ... + + def consume(self, key: str) -> str | None: ... + + +class CaptchaStore: + """Redis 行为件;full key 由 Service 经 Keys 生成(三-5)。""" + + def __init__(self, redis: Any): + self._redis = redis + + def issue(self, key: str, code: str, ttl_s: int) -> None: + self._redis.set(key, code, ex=ttl_s) + + def consume(self, key: str) -> str | None: + """GETDEL 原子取出删除(三-4【强制】)——两步 get→delete 是并发重放缺陷。""" + return self._redis.getdel(key) + + +class CaptchaService: + """框架核心(一-2):生命周期/场景路由/错误语义归此;生成与比对归 Provider。 + + 装配 fail fast:image 恒注册;sms-otp/turnstile 按 Options 条件注册; + default_provider 与 scenes 引用未注册 Provider 即构造失败。 + """ + + def __init__(self, store: ChallengeStore, keys: Keys, options: Options | None = None): + self._store = store + self._keys = keys + opts = options or Options() + self._providers: dict[str, CaptchaProvider] = {"image": ImageCaptchaProvider()} + if opts.sms_sender is not None: + self._providers["sms-otp"] = SmsOtpProvider(opts.sms_sender) + if opts.turnstile is not None: + self._providers["turnstile"] = TurnstileProvider(opts.turnstile) + if opts.default_provider not in self._providers: + raise ValueError(f"默认 Provider 未注册:{opts.default_provider}") + for scene, provider_id in opts.scenes.items(): + if provider_id not in self._providers: + raise ValueError(f"场景 {scene} 引用未注册 Provider:{provider_id}") + self._default = opts.default_provider + self._scenes = dict(opts.scenes) + self._ttl_s = opts.ttl_s if opts.ttl_s and opts.ttl_s > 0 else DEFAULT_TTL_S + + def route(self, scene: str | None) -> CaptchaProvider: + """场景路由(四-2):未配置场景走默认 Provider(不报错)。""" + provider_id = self._scenes.get(scene or "", self._default) + return self._providers[provider_id] + + def issue(self, scene: str | None = None, destination: str | None = None) -> Issued: + """分发。LOCAL 档生成安全随机 key(三-1 UUID4=128bit)带 TTL 托管答案;REMOTE 零存储。""" + provider = self.route(scene) + challenge = provider.issue(IssueRequest(scene=scene, destination=destination)) + key: str | None = None + if provider.mode is VerifyMode.LOCAL: + key = str(uuid.uuid4()) + self._store.issue( + self._store_key(provider.id, key), challenge.secret_answer or "", self._ttl_s + ) + return Issued(provider=provider.id, key=key, payload=challenge.payload) + + def verify(self, scene: str | None, key: str | None, answer: str | None) -> bool: + """校验(六-2:内联受保护业务流)。LOCAL = 原子消费后比对(三-3 对/错均消费); + REMOTE = 外委校验。key 不存在/None/已消费一律 False;false 时业务报 + 2005 CAPTCHA_INVALID(五-2 三态合一禁细分)。""" + provider = self.route(scene) + if provider.mode is VerifyMode.REMOTE: + remote = getattr(provider, "verify_remote", None) + return bool(remote(answer)) if remote else False + if not key: + return False + stored = self._store.consume(self._store_key(provider.id, key)) + return provider.matches(stored, answer) + + def challenge(self, scene: str | None = None) -> Challenge: + """REST 端点便捷面(六-1):只服务 image 档,路由到他档 = 1001(先查档位再分发)。""" + if self.route(scene).id != "image": + raise BizError( + errcode.Code.INVALID_ARGUMENT, detail=f"场景 {scene} 非 image 档,不经图形分发端点" + ) + issued = self.issue(scene, None) + return Challenge( + provider=issued.provider, + key=issued.key or "", + image_base64=issued.payload["imageBase64"], + ) + + def _store_key(self, provider_id: str, key: str) -> str: + """存储 key(三-5):{服务名}:captcha:{provider}:{key}——首段=服务名租户边界。""" + return self._keys.of("captcha", provider_id, key) + + +class LocalLimiter: + """进程内固定窗口限流(五-1 默认档,对偶 java @RateLimited 进程内档); + 跨实例档传 redix.FixedWindowLimiter(同 hit(key, window_s, limit) 鸭子接口)。""" + + def __init__(self) -> None: + self._hits: dict[str, tuple[int, float]] = {} + self._lock = threading.Lock() + + def hit(self, key: str, window_s: int, limit: int) -> bool: + now = time.monotonic() + with self._lock: + count, window_start = self._hits.get(key, (0, now)) + if now - window_start >= window_s: + count, window_start = 0, now + if count >= limit: + self._hits[key] = (count, window_start) + return False + self._hits[key] = (count + 1, window_start) + return True + + +def create_router( + service: CaptchaService, + *, + limiter: Any | None = None, + limit: tuple[int, int] = (10, 60), +) -> APIRouter: + """GET /api/v1/captcha 端点件(六-1)+ 默认限流(五-1:per-IP 固定窗口 60s/10 次【参考】档)。 + + limiter 缺省用进程内 LocalLimiter;传 redix.FixedWindowLimiter 即跨实例档。 + 非 image 档场景 = 1001 信封(BizError 由 web.setup 异常处理器渲染)。 + """ + window_limiter = limiter if limiter is not None else LocalLimiter() + max_hits, window_s = limit + router = APIRouter() + + @router.get("/api/v1/captcha") + def captcha_endpoint(request: Request, scene: str | None = None): + ip = request.client.host if request.client else "unknown" + if not window_limiter.hit(f"captcha:{ip}", window_s, max_hits): + raise BizError(errcode.Code.RATE_LIMITED) + challenge = service.challenge(scene) + return ok( + { + "provider": challenge.provider, + "key": challenge.key, + "imageBase64": challenge.image_base64, + } + ) + + return router diff --git a/stacks/python/packages/yarch-python/src/yarch_python/captcha/_png.py b/stacks/python/packages/yarch-python/src/yarch_python/captcha/_png.py new file mode 100644 index 0000000..80e887a --- /dev/null +++ b/stacks/python/packages/yarch-python/src/yarch_python/captcha/_png.py @@ -0,0 +1,131 @@ +"""captcha 内部件:纯 stdlib PNG 渲染(captcha.md 二-2 渲染样式自由 CP9——绑各栈图形库能力, +python 栈以零 Pillow 依赖的位图字模 + zlib/struct 编码实现,答案字符集/长度才是契约强制)。""" + +import base64 +import random +import struct +import zlib + +# 5x7 位图字模('#'/`.`),仅覆盖契约去混淆 32 字符集(二-2:A-Z 去 I/O + 2-9) +_FONT: dict[str, str] = { + "A": ".###./#...#/#...#/#####/#...#/#...#/#...#", + "B": "####./#...#/#...#/####./#...#/#...#/####.", + "C": ".###./#...#/#..../#..../#..../#...#/.###.", + "D": "####./#...#/#...#/#...#/#...#/#...#/####.", + "E": "#####/#..../#..../####./#..../#..../#####", + "F": "#####/#..../#..../####./#..../#..../#....", + "G": ".###./#...#/#..../#.###/#...#/#...#/.###.", + "H": "#...#/#...#/#...#/#####/#...#/#...#/#...#", + "J": "....#/....#/....#/....#/#...#/#...#/.###.", + "K": "#...#/#..#./#.#../##.../#.#../#..#./#...#", + "L": "#..../#..../#..../#..../#..../#..../#####", + "M": "#...#/##.##/#.#.#/#...#/#...#/#...#/#...#", + "N": "#...#/##..#/#.#.#/#..##/#...#/#...#/#...#", + "P": "####./#...#/#...#/####./#..../#..../#....", + "Q": ".###./#...#/#...#/#...#/#.#.#/#..#./.##.#", + "R": "####./#...#/#...#/####./#.#../#..#./#...#", + "S": ".####/#..../#..../.###./....#/....#/####.", + "T": "#####/..#../..#../..#../..#../..#../..#..", + "U": "#...#/#...#/#...#/#...#/#...#/#...#/.###.", + "V": "#...#/#...#/#...#/#...#/#...#/.#.#./..#..", + "W": "#...#/#...#/#...#/#.#.#/#.#.#/##.##/#...#", + "X": "#...#/#...#/.#.#./..#../.#.#./#...#/#...#", + "Y": "#...#/#...#/.#.#./..#../..#../..#../..#..", + "Z": "#####/....#/...#./..#../.#.../#..../#####", + "2": ".###./#...#/....#/...#./..#../.#.../#####", + "3": "####./....#/....#/.###./....#/....#/####.", + "4": "...#./..##./.#.#./#..#./#####/...#./...#.", + "5": "#####/#..../#..../####./....#/....#/####.", + "6": ".###./#..../#..../####./#...#/#...#/.###.", + "7": "#####/....#/...#./..#../.#.../.#.../.#...", + "8": ".###./#...#/#...#/.###./#...#/#...#/.###.", + "9": ".###./#...#/#...#/.####/....#/....#/.###.", +} + + +def _chunk(tag: bytes, data: bytes) -> bytes: + return ( + struct.pack(">I", len(data)) + + tag + + data + + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF) + ) + + +Pixel = tuple[int, int, int] +Canvas = list[list[Pixel]] + + +def _line(px: Canvas, w: int, h: int, x0: int, y0: int, x1: int, y1: int, color: Pixel) -> None: + dx, dy = abs(x1 - x0), -abs(y1 - y0) + sx, sy = (1 if x0 < x1 else -1), (1 if y0 < y1 else -1) + err = dx + dy + while True: + if 0 <= x0 < w and 0 <= y0 < h: + px[y0][x0] = color + if x0 == x1 and y0 == y1: + return + e2 = 2 * err + if e2 >= dy: + err += dy + x0 += sx + if e2 <= dx: + err += dx + y0 += sy + + +def render_png_base64(text: str, *, width: int = 150, height: int = 50, scale: int = 4) -> str: + """渲染答案文本为 PNG 裸 base64(无 data: 前缀,二-2/六-1 口径)。 + + 样式:白底 + 噪点 + 干扰线 + 随机深色位图字符——渲染样式各栈自由(CP9)。 + """ + rnd = random.Random() + px: Canvas = [[(255, 255, 255)] * width for _ in range(height)] + + for _ in range(160): # 噪点 + px[rnd.randrange(height)][rnd.randrange(width)] = (170, 170, 170) + for _ in range(3): # 干扰线 + noise = (rnd.randrange(180), rnd.randrange(180), rnd.randrange(180)) + _line( + px, + width, + height, + rnd.randrange(width), + rnd.randrange(height), + rnd.randrange(width), + rnd.randrange(height), + noise, + ) + + cw = 5 * scale # 单字符像素宽 + gap = 8 + origin_x = max(4, (width - len(text) * cw - (len(text) - 1) * gap) // 2) + origin_y = max(2, (height - 7 * scale) // 2) + for i, ch in enumerate(text): + glyph = _FONT.get(ch) + if glyph is None: + raise ValueError(f"字符 {ch!r} 不在契约字符集") + glyph_rows = glyph.split("/") + ink = (40 + rnd.randrange(120), 40 + rnd.randrange(120), 40 + rnd.randrange(120)) + for row_idx, glyph_row in enumerate(glyph_rows): + for col_idx, bit in enumerate(glyph_row): + if bit == "#": + for sy in range(scale): + for sx in range(scale): + px[origin_y + row_idx * scale + sy][ + origin_x + i * (cw + gap) + col_idx * scale + sx + ] = ink + + raw = bytearray() + for pixel_row in px: + raw.append(0) + for r, g, b in pixel_row: + raw += bytes((r, g, b)) + ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0) + png = ( + b"\x89PNG\r\n\x1a\n" + + _chunk(b"IHDR", ihdr) + + _chunk(b"IDAT", zlib.compress(bytes(raw))) + + _chunk(b"IEND", b"") + ) + return base64.b64encode(png).decode("ascii") diff --git a/stacks/python/packages/yarch-python/src/yarch_python/errcode/__init__.py b/stacks/python/packages/yarch-python/src/yarch_python/errcode/__init__.py index 63f5328..3254ed2 100644 --- a/stacks/python/packages/yarch-python/src/yarch_python/errcode/__init__.py +++ b/stacks/python/packages/yarch-python/src/yarch_python/errcode/__init__.py @@ -1,5 +1,5 @@ # stacks/python/packages/yarch-python/src/yarch_python/errcode/__init__.py -"""契约内核②:错误码全局段位表(error-codes.md v1.0,13 码全表 + HTTP 映射 + 业务码注册)。""" +"""契约内核②:错误码全局段位表(error-codes.md v1.1,14 码全表 + HTTP 映射 + 业务码注册)。""" import re from enum import IntEnum @@ -20,6 +20,7 @@ class Code(IntEnum): CREDENTIALS_EXPIRED = 2002 FORBIDDEN = 2003 ACCOUNT_DISABLED = 2004 + CAPTCHA_INVALID = 2005 # captcha.md 五-2:key 无效/已消费/答案错误三态合一,禁细分 _MESSAGES = { @@ -37,6 +38,7 @@ class Code(IntEnum): 2002: "凭证已过期", 2003: "权限不足", 2004: "账号已禁用", + 2005: "验证码校验失败", } _HTTP = { 0: 200, @@ -53,6 +55,7 @@ class Code(IntEnum): 2002: 401, 2003: 403, 2004: 403, + 2005: 400, } _IDENTIFIERS = {c.value: c.name for c in Code} # 业务码登记表(3xxx-8xxx,业务仓 docs 登记后 register) diff --git a/stacks/python/packages/yarch-python/src/yarch_python/testx/__init__.py b/stacks/python/packages/yarch-python/src/yarch_python/testx/__init__.py index 72c5e28..cd057fc 100644 --- a/stacks/python/packages/yarch-python/src/yarch_python/testx/__init__.py +++ b/stacks/python/packages/yarch-python/src/yarch_python/testx/__init__.py @@ -3,8 +3,8 @@ import json import re -# error-codes.md v1.0 逐行誊写(0 成功 + 13 码);与 tests/test_errcode.py 的 CONTRACT_TABLE -# 同源同值(14 行),业务工程直接 import 本表做跨栈 conformance +# error-codes.md v1.1 逐行誊写(0 成功 + 14 码);与 tests/test_errcode.py 的 CONTRACT_TABLE +# 同源同值(15 行),业务工程直接 import 本表做跨栈 conformance CODE_TABLE: list[tuple[int, str, str, int]] = [ (0, "OK", "成功", 200), (1000, "INTERNAL_ERROR", "内部错误", 500), @@ -20,6 +20,7 @@ (2002, "CREDENTIALS_EXPIRED", "凭证已过期", 401), (2003, "FORBIDDEN", "权限不足", 403), (2004, "ACCOUNT_DISABLED", "账号已禁用", 403), + (2005, "CAPTCHA_INVALID", "验证码校验失败", 400), ] # 与 logx 行协议同口径:毫秒精度 UTC ts + 大写 level(protocol_fields 全集) diff --git a/stacks/python/packages/yarch-python/tests/test_captcha.py b/stacks/python/packages/yarch-python/tests/test_captcha.py new file mode 100644 index 0000000..c5d5c19 --- /dev/null +++ b/stacks/python/packages/yarch-python/tests/test_captcha.py @@ -0,0 +1,234 @@ +# stacks/python/packages/yarch-python/tests/test_captcha.py +"""验证码框架契约断言:captcha.md v1.0 跨栈一致性向量(附录 V 系)python 落地 + 端点/限流。 + +golang/java 同源向量对照:V1-V5(image 生命周期)、V6(原子消费)、V7(TTL)、 +V8(sms-otp)、V9(turnstile REMOTE)、V10(场景路由)、V11(端点限流 1006)。 +""" + +import base64 +import io +import threading + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient +from yarch_python import errcode, logx +from yarch_python.captcha import ( + ALPHABET, + DEFAULT_LEN, + DEFAULT_TTL_S, + CaptchaService, + IssueRequest, + LocalLimiter, + Options, + TurnstileConfig, + TurnstileProvider, + create_router, + mask_destination, +) +from yarch_python.redix import Keys +from yarch_python.web import setup +from yarch_python.xerror import BizError + + +class FakeStore: + """并发安全内存存储(Consume 取出即删——V6 原子语义底座;Redis 行为级在 test_captcha_tc)。""" + + def __init__(self): + self._lock = threading.Lock() + self.data: dict[str, str] = {} + self.ttls: dict[str, int] = {} + + def issue(self, key: str, code: str, ttl_s: int) -> None: + with self._lock: + self.data[key] = code + self.ttls[key] = ttl_s + + def consume(self, key: str) -> str | None: + with self._lock: + return self.data.pop(key, None) + + +class FakeSender: + def __init__(self): + self.sent: list[tuple[str, str]] = [] + + def send(self, destination: str, content: str) -> None: + self.sent.append((destination, content)) + + +def make_svc(store=None, options=None) -> CaptchaService: + return CaptchaService(store if store is not None else FakeStore(), Keys("svc"), options) + + +def test_v1_v5_image_lifecycle(): + store = FakeStore() + svc = make_svc(store) + issued = svc.issue() + assert issued.provider == "image" and issued.key + key = f"svc:captcha:image:{issued.key}" + answer = store.data[key] + assert len(answer) == DEFAULT_LEN and all(c in ALPHABET for c in answer) # 二-2【强制】 + + assert svc.verify(None, issued.key, f" {answer.lower()} ") # V5:trim + 大小写不敏感 + assert not svc.verify(None, issued.key, answer) # V2:一次性——二次必败 + + issued2 = svc.issue() + answer2 = store.data[f"svc:captcha:image:{issued2.key}"] + assert not svc.verify(None, issued2.key, "XXXX") # V3:错答案失败 + assert not svc.verify(None, issued2.key, answer2) # V3:错试后已消费(防重放枚举) + + assert not svc.verify(None, "00000000-0000-0000-0000-000000000000", "ABCD") # V4 + + +def test_v7_ttl_default_and_custom(): + store = FakeStore() + svc = make_svc(store) + issued = svc.issue() + assert store.ttls[f"svc:captcha:image:{issued.key}"] == DEFAULT_TTL_S == 120 # 三-2【推荐】 + + store2 = FakeStore() + make_svc(store2, Options(ttl_s=300)).issue() + assert next(iter(store2.ttls.values())) == 300 + + +def test_v6_concurrent_exactly_one_wins(): + store = FakeStore() + svc = make_svc(store) + issued = svc.issue() + answer = store.data[f"svc:captcha:image:{issued.key}"] + + results: list[bool] = [] + lock = threading.Lock() + start = threading.Event() + + def worker(): + start.wait() + r = svc.verify(None, issued.key, answer) + with lock: + results.append(r) + + threads = [threading.Thread(target=worker) for _ in range(8)] + for t in threads: + t.start() + start.set() + for t in threads: + t.join() + assert sum(results) == 1 # V6:并发校验恰一过(原子消费) + + +def test_v8_sms_otp_with_scene_routing(): + store = FakeStore() + sender = FakeSender() + svc = make_svc(store, Options(scenes={"login": "sms-otp"}, sms_sender=sender)) + + issued = svc.issue("login", "13800138000") + assert issued.provider == "sms-otp" # V10:scene 路由生效 + dest, otp = sender.sent[-1] + assert dest == "13800138000" # OTP 经宿主通道发送 + assert len(otp) == 6 and otp.isdigit() # 二-3:6 位数字 + assert issued.payload["destination"] == "138****8000" # 目标脱敏回显 + assert mask_destination("12345") == "****" + + assert svc.verify("login", issued.key, otp) + issued2 = svc.issue("login", "13800138000") + otp2 = sender.sent[-1][1] + wrong = "000000" if otp2 != "000000" else "111111" + assert not svc.verify("login", issued2.key, wrong) # 精确比对 + assert not svc.verify("login", issued2.key, otp2) # V3:错试后已消费 + + with pytest.raises(BizError) as ei: # 二-3:缺发送目标 + svc.issue("login", None) + assert ei.value.code == errcode.Code.INVALID_ARGUMENT + + +def test_v9_turnstile_remote(): + store = FakeStore() + + def stub(verify_url, secret, response, remote_ip): + return response == "good-token" + + provider = TurnstileProvider( + TurnstileConfig(site_key="site-1", secret_key="sec-1"), caller=stub + ) + challenge = provider.issue(IssueRequest()) + assert challenge.secret_answer is None # REMOTE 档无服务端答案(二-1) + assert challenge.payload == {"siteKey": "site-1"} + assert not store.data # V9:全程零存储(三-5) + + assert provider.verify_remote("good-token", "10.0.0.1") + assert not provider.verify_remote("bad-token", None) + assert not provider.verify_remote("", None) and not provider.verify_remote(" ", None) + + +def test_v10_scene_routing(): + svc = make_svc(options=Options(scenes={"login": "sms-otp"}, sms_sender=FakeSender())) + assert svc.route("register").id == "image" # 未配置场景走默认 + assert svc.route(None).id == "image" + + svc2 = make_svc(options=Options(default_provider="sms-otp", sms_sender=FakeSender())) + assert svc2.route("anything").id == "sms-otp" # 默认档覆盖 + + with pytest.raises(ValueError): # fail fast:引用未注册 Provider + make_svc(options=Options(scenes={"login": "nope"})) + with pytest.raises(ValueError): + make_svc(options=Options(default_provider="nope")) + + +def test_challenge_non_image_scene_is_1001(): + svc = make_svc(options=Options(scenes={"login": "sms-otp"}, sms_sender=FakeSender())) + with pytest.raises(BizError) as ei: # 六-1:端点只服务 image 档 + svc.challenge("login") + assert ei.value.code == errcode.Code.INVALID_ARGUMENT + + +def test_captcha_invalid_code_pinned(): + assert errcode.Code.CAPTCHA_INVALID == 2005 # 五-2 三态合一 + assert errcode.http_of(2005) == 400 + + +def make_app(limit=(10, 60), limiter=None) -> FastAPI: + logx.setup("ysaas-scan", "local", sink=io.StringIO()) + store = FakeStore() + sender = FakeSender() + svc = make_svc(store, Options(scenes={"login": "sms-otp"}, sms_sender=sender, turnstile=None)) + app = FastAPI() + setup(app, service="ysaas-scan", env="local") + app.include_router(create_router(svc, limiter=limiter, limit=limit)) + return app + + +def test_endpoint_fields_and_png_bare_base64(): + client = TestClient(make_app()) + r = client.get("/api/v1/captcha") + assert r.status_code == 200 + body = r.json() + assert body["code"] == 0 + assert body["data"]["provider"] == "image" # 六-1:provider 增量字段 + assert body["data"]["key"] + raw = base64.b64decode(body["data"]["imageBase64"]) # 裸 base64(二-2:无 data: 前缀) + assert raw.startswith(b"\x89PNG") + assert not body["data"]["imageBase64"].startswith("data:") + + +def test_endpoint_non_image_scene_400_1001(): + client = TestClient(make_app()) + r = client.get("/api/v1/captcha", params={"scene": "login"}) + assert r.status_code == 400 + assert r.json()["code"] == errcode.Code.INVALID_ARGUMENT + + +def test_v11_endpoint_rate_limited(): + client = TestClient(make_app(limit=(3, 60))) + for _ in range(3): + assert client.get("/api/v1/captcha").status_code == 200 + r = client.get("/api/v1/captcha") + assert r.status_code == 429 # 五-1:超限 429 + 1006 + assert r.json()["code"] == errcode.Code.RATE_LIMITED + + +def test_local_limiter_window_semantics(): + lim = LocalLimiter() + assert all(lim.hit("k", 60, 3) for _ in range(3)) + assert not lim.hit("k", 60, 3) + assert lim.hit("other", 60, 3) # 独立 key 互不影响 diff --git a/stacks/python/packages/yarch-python/tests/test_captcha_tc.py b/stacks/python/packages/yarch-python/tests/test_captcha_tc.py new file mode 100644 index 0000000..a434bf6 --- /dev/null +++ b/stacks/python/packages/yarch-python/tests/test_captcha_tc.py @@ -0,0 +1,51 @@ +# stacks/python/packages/yarch-python/tests/test_captcha_tc.py +"""验证码 Redis 行为级(captcha.md 三):GETDEL 原子一次性 + TTL + key 形状 + V6 并发恰一过。""" + +import concurrent.futures + +import pytest +from yarch_python.captcha import CaptchaService, CaptchaStore, Options +from yarch_python.redix import Keys + +pytestmark = pytest.mark.integration + + +@pytest.fixture(scope="module") +def redis(): + # testcontainers 4.15:community.redis 的 get_client() 直取客户端(module 级共享容器) + from testcontainers.community.redis import RedisContainer + + with RedisContainer() as c: + yield c.get_client() + + +@pytest.fixture() +def svc(redis): + return CaptchaService(CaptchaStore(redis), Keys("svc"), Options()) + + +def test_v7_ttl_and_key_shape(redis, svc): + issued = svc.issue() + key = f"svc:captcha:image:{issued.key}" # 三-5:{服务名}:captcha:{provider}:{key} + assert redis.exists(key) == 1 + ttl = redis.ttl(key) + assert 0 < ttl <= 120 # V7:默认档 TTL 窗口 + + +def test_v6_concurrent_verify_exactly_one_wins(redis, svc): + issued = svc.issue() + key = f"svc:captcha:image:{issued.key}" + answer = redis.get(key) + + with concurrent.futures.ThreadPoolExecutor(max_workers=8) as pool: + results = list(pool.map(lambda _: svc.verify(None, issued.key, answer.lower()), range(8))) + assert sum(results) == 1 # V6:GETDEL 原子——并发校验恰一过 + assert redis.get(key) is None # V2:校验后 key 已消费 + + +def test_v3_wrong_answer_consumes_key(redis, svc): + issued = svc.issue() + key = f"svc:captcha:image:{issued.key}" + answer = redis.get(key) + assert not svc.verify(None, issued.key, "XXXX" if answer != "XXXX" else "YYYY") + assert redis.get(key) is None # V3:错答案同样消费(防重放枚举) diff --git a/stacks/python/packages/yarch-python/tests/test_errcode.py b/stacks/python/packages/yarch-python/tests/test_errcode.py index 9e23e53..fd24e4f 100644 --- a/stacks/python/packages/yarch-python/tests/test_errcode.py +++ b/stacks/python/packages/yarch-python/tests/test_errcode.py @@ -1,5 +1,5 @@ # stacks/python/packages/yarch-python/tests/test_errcode.py -"""错误码契约断言:13 码全表唯一权威 = contract/dist/error-codes.json(由 error-codes.md +"""错误码契约断言:14 码全表唯一权威 = contract/dist/error-codes.json(由 error-codes.md 派生,CI 拒双向漂移)——四栈读同一份 json 断言,不再各养手抄表(P1 契约机器可读出口)。 dist 文件不在场(消费方独立环境)则整表跳过,CI 仓内必跑。""" @@ -42,7 +42,7 @@ def test_ok_success_constant(): def test_dist_table_complete_when_present(): if not _DIST.exists(): pytest.skip("contract dist json 不在场") - assert len(DIST_TABLE) == 13 + assert len(DIST_TABLE) == 14 def test_1003_reserved_absent(): diff --git a/stacks/python/packages/yarch-python/tests/test_testx.py b/stacks/python/packages/yarch-python/tests/test_testx.py index 03f4499..1c504a2 100644 --- a/stacks/python/packages/yarch-python/tests/test_testx.py +++ b/stacks/python/packages/yarch-python/tests/test_testx.py @@ -7,8 +7,8 @@ pytest_plugins = ("yarch_python.testx.fixtures",) -def test_code_table_has_14_rows(): - assert len(CODE_TABLE) == 14 and CODE_TABLE[0] == (0, "OK", "成功", 200) +def test_code_table_has_15_rows(): + assert len(CODE_TABLE) == 15 and CODE_TABLE[0] == (0, "OK", "成功", 200) @pytest.mark.parametrize("code,identifier,message,http", CODE_TABLE) diff --git a/stacks/rust/Cargo.lock b/stacks/rust/Cargo.lock new file mode 100644 index 0000000..37e441d --- /dev/null +++ b/stacks/rust/Cargo.lock @@ -0,0 +1,226 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 3 + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "getrandom" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd" +dependencies = [ + "cfg-if", + "libc", + "r-efi", + "wasip2", +] + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "libc" +version = "0.2.189" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2" + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "ppv-lite86" +version = "0.2.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9" +dependencies = [ + "zerocopy", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "5.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f" + +[[package]] +name = "rand" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41" +dependencies = [ + "rand_chacha", + "rand_core", +] + +[[package]] +name = "rand_chacha" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb" +dependencies = [ + "ppv-lite86", + "rand_core", +] + +[[package]] +name = "rand_core" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c" +dependencies = [ + "getrandom", +] + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.6", +] + +[[package]] +name = "serde_json" +version = "1.0.151" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "3.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "unicode-ident" +version = "1.0.26" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954" + +[[package]] +name = "wasip2" +version = "1.0.4+wasi-0.2.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487" +dependencies = [ + "wit-bindgen", +] + +[[package]] +name = "wit-bindgen" +version = "0.57.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e" + +[[package]] +name = "yarch-axum" +version = "0.1.0" + +[[package]] +name = "yarch-contract" +version = "0.1.0" +dependencies = [ + "rand", + "serde", + "serde_json", +] + +[[package]] +name = "zerocopy" +version = "0.8.57" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d35102a9f36d089ccae9e4c6802bc118be4487b80aaffc0ab4e0cf5ce92d2873" +dependencies = [ + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.8.57" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "146c01f5ab44258da43cf276c74a2763db2ff3969c9c652c3f2de07041d0b2bc" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/stacks/rust/Cargo.toml b/stacks/rust/Cargo.toml new file mode 100644 index 0000000..9dee497 --- /dev/null +++ b/stacks/rust/Cargo.toml @@ -0,0 +1,17 @@ +# yarch rust 栈 workspace:契约内核(零框架)+ axum 装配(批次二施工)。 +# 规约唯一权威:stacks/rust/spec.md(R1-R7)+ contract/api/ 四件套。 +[workspace] +resolver = "2" +members = ["crates/yarch-contract", "crates/yarch-axum"] + +[workspace.package] +version = "0.1.0" +edition = "2021" +license = "Apache-2.0" +repository = "https://github.com/ydonghao/yarch" +rust-version = "1.80" + +[workspace.dependencies] +serde = { version = "1", features = ["derive"] } +serde_json = "1" +rand = "0.9" diff --git a/stacks/rust/PLAN.md b/stacks/rust/PLAN.md index 26f5138..6c666d7 100644 --- a/stacks/rust/PLAN.md +++ b/stacks/rust/PLAN.md @@ -53,7 +53,7 @@ stacks/rust/ ## 五、施工批次 -1. **第一批(本批)**:spec.md 成文 + PLAN.md 落位 + workspace 骨架(两 crate 空壳 + 契约内核 response/errcode/trace 三模块 + 13 码全表断言测试)——本地 `cargo test` 绿。 +1. **第一批(已完成 2026-09-18)**:spec.md 成文 + PLAN.md 落位 + workspace 骨架(两 crate + 契约内核 response/errcode/trace 三模块 + 同源 conformance 断言读 contract/dist)——本地 cargo test/fmt/clippy 绿,CI rust-stack.yml 四段门禁 + MSRV 双档。 2. **第二批**:yarch-axum 中间件五件(Trace/Recovery/AccessLog/Idempotency/Rate,对齐 python 中间件组合语义)+ sqlx 装配(逻辑删除/审计/分页 D6)+ 模板 users 示例。 3. **第三批**:生成后冒烟(cargo generate → cargo test)+ crates.io 发版流水线(tag 触发)+ conformance 读契约 dist(待 N2 落地后接)。 diff --git a/stacks/rust/crates/yarch-axum/Cargo.toml b/stacks/rust/crates/yarch-axum/Cargo.toml new file mode 100644 index 0000000..abf1001 --- /dev/null +++ b/stacks/rust/crates/yarch-axum/Cargo.toml @@ -0,0 +1,9 @@ +[package] +name = "yarch-axum" +description = "yarch axum 装配层:中间件五件/提取器/分页/幂等(批次二施工,本批为空壳)" +keywords = ["yarch", "axum", "middleware"] +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true diff --git a/stacks/rust/crates/yarch-axum/src/lib.rs b/stacks/rust/crates/yarch-axum/src/lib.rs new file mode 100644 index 0000000..62d7b71 --- /dev/null +++ b/stacks/rust/crates/yarch-axum/src/lib.rs @@ -0,0 +1,2 @@ +//! yarch-axum:axum 0.8 装配层——中间件五件(Trace/Recovery/AccessLog/Idempotency/Rate)、 +//! sqlx 装配与提取器。批次二施工;本批为占位空壳。 diff --git a/stacks/rust/crates/yarch-contract/Cargo.toml b/stacks/rust/crates/yarch-contract/Cargo.toml new file mode 100644 index 0000000..18b8712 --- /dev/null +++ b/stacks/rust/crates/yarch-contract/Cargo.toml @@ -0,0 +1,16 @@ +[package] +name = "yarch-contract" +description = "yarch 契约内核(Rust 方言):REST 信封 / 错误码段位表 / traceId——零框架" +keywords = ["yarch", "contract", "rest", "error-code"] +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true + +[dependencies] +serde = { workspace = true } +rand = { workspace = true } + +[dev-dependencies] +serde_json = { workspace = true } diff --git a/stacks/rust/crates/yarch-contract/src/errcode.rs b/stacks/rust/crates/yarch-contract/src/errcode.rs new file mode 100644 index 0000000..d9d52f3 --- /dev/null +++ b/stacks/rust/crates/yarch-contract/src/errcode.rs @@ -0,0 +1,236 @@ +//! 错误码段位表(契约内核)。 +//! +//! 唯一权威 = contract/api/error-codes.md(机器可读派生层 contract/dist/error-codes.json, +//! 同源断言见 tests/conformance.rs)。yarch 只拥有 0、1xxx、2xxx;3xxx-8xxx 由业务仓 +//! 登记后方可使用([`register`]);9xxx 预留不得使用。 + +use std::collections::HashMap; +use std::sync::RwLock; + +/// 错误码元数据(不可变值对象)。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct ErrCode { + /// 业务码。0 = 成功;非 0 见段位表 + pub code: i32, + /// UPPER_SNAKE 标识(与 dist json 的 key 同形) + pub key: &'static str, + /// 默认中文文案(可直接作为前端降级文案) + pub message: &'static str, + /// 固定 HTTP 状态码映射(服务端不得自行发挥) + pub http: u16, +} + +impl ErrCode { + const fn new(code: i32, key: &'static str, message: &'static str, http: u16) -> Self { + Self { + code, + key, + message, + http, + } + } +} + +/// 成功(code = 0) +pub const OK: ErrCode = ErrCode::new(0, "OK", "成功", 200); + +// 通用段 1xxx +pub const INTERNAL_ERROR: ErrCode = ErrCode::new(1000, "INTERNAL_ERROR", "内部错误", 500); +pub const INVALID_ARGUMENT: ErrCode = ErrCode::new(1001, "INVALID_ARGUMENT", "参数校验失败", 400); +pub const MALFORMED_BODY: ErrCode = ErrCode::new(1002, "MALFORMED_BODY", "请求体格式错误", 400); +pub const NOT_FOUND: ErrCode = ErrCode::new(1004, "NOT_FOUND", "资源不存在", 404); +pub const CONFLICT: ErrCode = ErrCode::new(1005, "CONFLICT", "资源冲突", 409); +pub const RATE_LIMITED: ErrCode = ErrCode::new(1006, "RATE_LIMITED", "触发限流", 429); +pub const IDEMPOTENCY_CONFLICT: ErrCode = + ErrCode::new(1007, "IDEMPOTENCY_CONFLICT", "幂等冲突:重复提交", 409); +pub const UPSTREAM_TIMEOUT: ErrCode = ErrCode::new(1008, "UPSTREAM_TIMEOUT", "上游依赖超时", 504); +pub const UNAVAILABLE: ErrCode = ErrCode::new(1009, "UNAVAILABLE", "服务暂不可用", 503); + +// 认证与权限段 2xxx +pub const UNAUTHORIZED: ErrCode = ErrCode::new(2001, "UNAUTHORIZED", "未认证", 401); +pub const CREDENTIALS_EXPIRED: ErrCode = + ErrCode::new(2002, "CREDENTIALS_EXPIRED", "凭证已过期", 401); +pub const FORBIDDEN: ErrCode = ErrCode::new(2003, "FORBIDDEN", "权限不足", 403); +pub const ACCOUNT_DISABLED: ErrCode = ErrCode::new(2004, "ACCOUNT_DISABLED", "账号已禁用", 403); +pub const CAPTCHA_INVALID: ErrCode = ErrCode::new(2005, "CAPTCHA_INVALID", "验证码校验失败", 400); + +/// 内建全表(0 + 1xxx + 2xxx;同源断言对表用) +pub const BUILTIN: &[ErrCode] = &[ + OK, + INTERNAL_ERROR, + INVALID_ARGUMENT, + MALFORMED_BODY, + NOT_FOUND, + CONFLICT, + RATE_LIMITED, + IDEMPOTENCY_CONFLICT, + UPSTREAM_TIMEOUT, + UNAVAILABLE, + UNAUTHORIZED, + CREDENTIALS_EXPIRED, + FORBIDDEN, + ACCOUNT_DISABLED, + CAPTCHA_INVALID, +]; + +/// 业务段边界:3xxx-8xxx(9xxx 预留不得使用) +const BUSINESS_MIN: i32 = 3000; +const BUSINESS_MAX: i32 = 8999; + +/// 业务码登记失败(对齐 golang panic 语义;Rust 以 Result 承载,装配期调用方 `.expect` fail-fast) +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum RegisterError { + /// 段位越界(仅 3xxx-8xxx 可登记) + OutOfRange(i32), + /// HTTP 状态码不在白名单 + HttpNotAllowed(u16), + /// 同 code 已登记且元信息不同 + Conflict { + code: i32, + existing_key: &'static str, + }, +} + +static BUSINESS: RwLock>> = RwLock::new(None); + +/// 查码:内建表 → 业务表 → 回退 INTERNAL_ERROR(未登记 code 视为实现缺陷,兜底内部错误语义)。 +pub fn lookup(code: i32) -> ErrCode { + if let Some(c) = BUILTIN.iter().find(|c| c.code == code) { + return *c; + } + if let Ok(guard) = BUSINESS.read() { + if let Some(c) = guard.as_ref().and_then(|m| m.get(&code)) { + return *c; + } + } + INTERNAL_ERROR +} + +/// code 是否已登记(内建或业务段) +pub fn is_registered(code: i32) -> bool { + if BUILTIN.iter().any(|c| c.code == code) { + return true; + } + BUSINESS + .read() + .map(|g| g.as_ref().is_some_and(|m| m.contains_key(&code))) + .unwrap_or(false) +} + +/// 登记业务码。幂等:同 code 同元信息重复登记放行;元信息冲突返回 [`RegisterError::Conflict`]。 +pub fn register( + code: i32, + key: &'static str, + message: &'static str, + http: u16, +) -> Result<(), RegisterError> { + if !(BUSINESS_MIN..=BUSINESS_MAX).contains(&code) { + return Err(RegisterError::OutOfRange(code)); + } + if !http_allowed(http) { + return Err(RegisterError::HttpNotAllowed(http)); + } + let mut guard = BUSINESS + .write() + .expect("errcode business registry poisoned"); + let map = guard.get_or_insert_with(HashMap::new); + match map.get(&code) { + Some(existing) + if existing.key == key && existing.message == message && existing.http == http => + { + Ok(()) + } + Some(existing) => Err(RegisterError::Conflict { + code, + existing_key: existing.key, + }), + None => { + map.insert(code, ErrCode::new(code, key, message, http)); + Ok(()) + } + } +} + +/// rest-conventions.md 业务 API 状态码白名单(对齐 golang httpAllowed) +fn http_allowed(status: u16) -> bool { + matches!( + status, + 200 | 201 | 400 | 401 | 403 | 404 | 409 | 429 | 500 | 503 | 504 + ) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn ok_constant() { + assert_eq!( + (OK.code, OK.key, OK.message, OK.http), + (0, "OK", "成功", 200) + ); + } + + #[test] + fn builtin_table_is_unique() { + let mut codes: Vec = BUILTIN.iter().map(|c| c.code).collect(); + let total = codes.len(); + codes.sort_unstable(); + codes.dedup(); + assert_eq!(codes.len(), total, "内建码表存在重复 code"); + let mut keys: Vec<&str> = BUILTIN.iter().map(|c| c.key).collect(); + let ktotal = keys.len(); + keys.sort_unstable(); + keys.dedup(); + assert_eq!(keys.len(), ktotal, "内建码表存在重复 key"); + } + + #[test] + fn unregistered_falls_back_to_internal_error() { + assert!(!is_registered(9999)); + let c = lookup(9999); + assert_eq!((c.code, c.message, c.http), (1000, "内部错误", 500)); + } + + #[test] + fn register_business_code() { + // 测试共享全局表:各测试用不同 code 避免相互污染 + assert!(register(3998, "DEMO_BUSY", "示例繁忙", 409).is_ok()); + // 幂等重登放行 + assert!(register(3998, "DEMO_BUSY", "示例繁忙", 409).is_ok()); + // 元信息冲突拒绝 + assert_eq!( + register(3998, "OTHER", "其他", 409), + Err(RegisterError::Conflict { + code: 3998, + existing_key: "DEMO_BUSY" + }) + ); + let c = lookup(3998); + assert_eq!( + (c.code, c.key, c.message, c.http), + (3998, "DEMO_BUSY", "示例繁忙", 409) + ); + assert!(is_registered(3998)); + } + + #[test] + fn register_rejects_out_of_range() { + assert_eq!( + register(2999, "X", "x", 400), + Err(RegisterError::OutOfRange(2999)) + ); + assert_eq!( + register(9000, "X", "x", 400), + Err(RegisterError::OutOfRange(9000)) + ); + } + + #[test] + fn register_rejects_http_outside_whitelist() { + assert_eq!( + register(3997, "X", "x", 204), + Err(RegisterError::HttpNotAllowed(204)) + ); + } +} diff --git a/stacks/rust/crates/yarch-contract/src/lib.rs b/stacks/rust/crates/yarch-contract/src/lib.rs new file mode 100644 index 0000000..af7e7af --- /dev/null +++ b/stacks/rust/crates/yarch-contract/src/lib.rs @@ -0,0 +1,8 @@ +//! yarch-contract:Rust 契约内核(零框架)。 +//! +//! 语义唯一权威 = contract/api/ 四件套;实现与契约不一致 = bug(四栈同口径)。 +//! 约束对象:yarch 体系全部 Rust 云端业务服务(与 embedded/esp32 固件轨零共享 crate)。 + +pub mod errcode; +pub mod response; +pub mod trace; diff --git a/stacks/rust/crates/yarch-contract/src/response.rs b/stacks/rust/crates/yarch-contract/src/response.rs new file mode 100644 index 0000000..417ae0a --- /dev/null +++ b/stacks/rust/crates/yarch-contract/src/response.rs @@ -0,0 +1,138 @@ +//! REST 信封(契约内核):四字段 camelCase,`code != 0` 时 `data` 必须为 `null`。 +//! +//! 语义唯一权威 = contract/api/rest-response.md。 + +use serde::{Deserialize, Serialize}; + +use crate::errcode; + +/// 响应信封。字段名 camelCase(traceId 经 serde rename),任何栈不得增删改名。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct RestResponse { + /// 业务码。0 = 成功;非 0 见 errcode 段位表 + pub code: i32, + /// 人类可读文案;不得携带堆栈/内部细节 + pub message: String, + /// 业务负载。code != 0 时必须为 null + pub data: Option, + /// 追踪 ID,恒等于响应头 X-Trace-Id;取不到时为空串 + #[serde(rename = "traceId")] + pub trace_id: String, +} + +impl RestResponse { + /// 成功且带负载 + pub fn ok(data: T, trace_id: impl Into) -> Self { + Self { + code: errcode::OK.code, + message: errcode::OK.message.to_string(), + data: Some(data), + trace_id: trace_id.into(), + } + } + + /// 成功且无负载(data = null) + pub fn ok_empty(trace_id: impl Into) -> Self { + Self { + code: errcode::OK.code, + message: errcode::OK.message.to_string(), + data: None, + trace_id: trace_id.into(), + } + } + + /// 业务失败:message 取码表默认文案;data 恒 None。 + /// 未登记 code 回退 INTERNAL_ERROR(整个信封按 1000 语义出,防止未定义码泄漏)。 + pub fn error(code: i32, trace_id: impl Into) -> Self { + let c = errcode::lookup(code); + Self { + code: c.code, + message: c.message.to_string(), + data: None, + trace_id: trace_id.into(), + } + } + + /// 业务失败 + 覆盖文案(按「默认文案:细节」规则由调用方拼装) + pub fn error_with_message( + code: i32, + message: impl Into, + trace_id: impl Into, + ) -> Self { + let c = errcode::lookup(code); + Self { + code: c.code, + message: message.into(), + data: None, + trace_id: trace_id.into(), + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[derive(Serialize, Deserialize, PartialEq, Debug)] + struct Payload { + value: i32, + } + + #[test] + fn ok_serializes_to_exact_envelope() { + let resp = RestResponse::ok(Payload { value: 1 }, "0af7651916cd43dd8448eb211c80319c"); + let json = serde_json::to_string(&resp).unwrap(); + assert_eq!( + json, + r#"{"code":0,"message":"成功","data":{"value":1},"traceId":"0af7651916cd43dd8448eb211c80319c"}"# + ); + } + + #[test] + fn error_serializes_data_null() { + let resp: RestResponse = RestResponse::error(1001, "t"); + let json = serde_json::to_string(&resp).unwrap(); + assert_eq!( + json, + r#"{"code":1001,"message":"参数校验失败","data":null,"traceId":"t"}"# + ); + } + + #[test] + fn ok_empty_keeps_data_null() { + let resp: RestResponse = RestResponse::ok_empty("t"); + assert_eq!(resp.code, 0); + assert!(resp.data.is_none()); + let json = serde_json::to_string(&resp).unwrap(); + assert_eq!( + json, + r#"{"code":0,"message":"成功","data":null,"traceId":"t"}"# + ); + } + + #[test] + fn unregistered_code_falls_back_to_internal_error() { + let resp: RestResponse = RestResponse::error(9999, "t"); + assert_eq!(resp.code, 1000); + assert_eq!(resp.message, "内部错误"); + } + + #[test] + fn error_with_message_overrides() { + let resp: RestResponse = + RestResponse::error_with_message(1001, "参数校验失败:pageSize 必须 ≤ 100", "t"); + let json = serde_json::to_string(&resp).unwrap(); + assert_eq!( + json, + r#"{"code":1001,"message":"参数校验失败:pageSize 必须 ≤ 100","data":null,"traceId":"t"}"# + ); + } + + #[test] + fn deserialize_round_trip() { + let resp = RestResponse::ok(Payload { value: 7 }, "tid"); + let json = serde_json::to_string(&resp).unwrap(); + let back: RestResponse = serde_json::from_str(&json).unwrap(); + assert_eq!(back, resp); + } +} diff --git a/stacks/rust/crates/yarch-contract/src/trace.rs b/stacks/rust/crates/yarch-contract/src/trace.rs new file mode 100644 index 0000000..3cf7ba9 --- /dev/null +++ b/stacks/rust/crates/yarch-contract/src/trace.rs @@ -0,0 +1,132 @@ +//! traceId 语义(契约内核):32 hex 生成与 W3C traceparent 解析。 +//! +//! 语义唯一权威 = contract/api/logging-trace.md(W3C traceparent 传播)、 +//! contract/api/rest-response.md(traceId 恒等于响应头 X-Trace-Id)。 + +use rand::Rng; + +/// 32 位小写十六进制 traceId(16 字节)。W3C 规定不得全零。 +#[derive(Debug, Clone, PartialEq, Eq, Hash)] +pub struct TraceId(String); + +impl TraceId { + /// 生成随机 traceId(W3C:非全零 32 hex) + pub fn generate() -> Self { + let v: u128 = rand::rng().random(); + Self(format!("{v:032x}")) + } + + pub fn as_str(&self) -> &str { + &self.0 + } + + /// 校验 32 位小写十六进制(W3C 规定小写,大小写敏感) + pub fn is_valid(s: &str) -> bool { + s.len() == 32 && s.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) + } +} + +impl std::fmt::Display for TraceId { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(&self.0) + } +} + +/// W3C traceparent 解析结果:`00-{trace-id}-{parent-id}-{flags}` +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct TraceParent { + pub trace_id: String, + pub parent_span_id: String, +} + +/// 解析 W3C traceparent 头(版本 00;trace-id 32 hex 非全零;parent-id 16 hex 非全零;flags 2 hex)。 +/// 非法输入返回 None,由调用方决定重新生成或透传。 +pub fn parse_traceparent(header: &str) -> Option { + let parts: Vec<&str> = header.trim().split('-').collect(); + if parts.len() != 4 || parts[0] != "00" { + return None; + } + let (trace_id, parent_span_id, flags) = (parts[1], parts[2], parts[3]); + if !TraceId::is_valid(trace_id) || is_all_zero(trace_id) { + return None; + } + if parent_span_id.len() != 16 + || !parent_span_id + .bytes() + .all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) + || is_all_zero(parent_span_id) + { + return None; + } + if flags.len() != 2 + || !flags + .bytes() + .all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) + { + return None; + } + Some(TraceParent { + trace_id: trace_id.to_string(), + parent_span_id: parent_span_id.to_string(), + }) +} + +fn is_all_zero(hex: &str) -> bool { + hex.bytes().all(|b| b == b'0') +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn generated_trace_id_is_32_lowercase_hex() { + let tid = TraceId::generate(); + assert!(TraceId::is_valid(tid.as_str()), "traceId 形状非法: {tid}"); + assert_ne!(tid.as_str(), "00000000000000000000000000000000"); + } + + #[test] + fn generated_trace_ids_differ() { + assert_ne!(TraceId::generate(), TraceId::generate()); + } + + #[test] + fn is_valid_rejects_bad_shapes() { + assert!(!TraceId::is_valid("")); + assert!(!TraceId::is_valid("abc")); + assert!(!TraceId::is_valid("0AF7651916CD43DD8448EB211C80319C")); // 大写拒绝 + assert!(!TraceId::is_valid("0af7651916cd43dd8448eb211c80319")); // 31 位 + assert!(TraceId::is_valid("0af7651916cd43dd8448eb211c80319c")); + } + + #[test] + fn parses_valid_traceparent() { + let tp = + parse_traceparent("00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01").unwrap(); + assert_eq!(tp.trace_id, "0af7651916cd43dd8448eb211c80319c"); + assert_eq!(tp.parent_span_id, "00f067aa0ba902b7"); + // 首尾空白容忍 + assert!( + parse_traceparent(" 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01 ") + .is_some() + ); + } + + #[test] + fn rejects_invalid_traceparent() { + let cases = [ + "", // 空 + "0af7651916cd43dd8448eb211c80319c", // 非 traceparent 形态 + "ff-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01", // 非 00 版本 + "00-00000000000000000000000000000000-00f067aa0ba902b7-01", // 全零 trace-id + "00-0af7651916cd43dd8448eb211c80319-00f067aa0ba902b7-01", // 31 位 trace-id + "00-0af7651916cd43dd8448eb211c80319c-0000000000000000-01", // 全零 parent-id + "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-1", // 1 位 flags + "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-xyz", // flags 非法字符 + ]; + for case in cases { + assert!(parse_traceparent(case).is_none(), "应拒绝: {case}"); + } + } +} diff --git a/stacks/rust/crates/yarch-contract/tests/conformance.rs b/stacks/rust/crates/yarch-contract/tests/conformance.rs new file mode 100644 index 0000000..e873f72 --- /dev/null +++ b/stacks/rust/crates/yarch-contract/tests/conformance.rs @@ -0,0 +1,74 @@ +//! 同源断言:内建码表的唯一机器可读权威 = contract/dist/error-codes.json +//! (由 contract/api/error-codes.md 派生,contract-dist CI 拒双向漂移)。 +//! dist 不在场(消费方独立测试环境)则跳过;仓内 CI 必跑(P1 契约机器可读出口口径, +//! 与 golang/java/python/web 四栈 conformance 同表)。 + +use serde::Deserialize; +use yarch_contract::errcode; + +#[derive(Deserialize)] +struct DistRow { + code: i32, + key: String, + message: String, + http: u16, +} + +#[derive(Deserialize)] +struct DistSuccess { + code: i32, + message: String, +} + +#[derive(Deserialize)] +struct Dist { + success: DistSuccess, + codes: Vec, +} + +fn load_dist() -> Option { + let raw = std::fs::read_to_string("../../../../contract/dist/error-codes.json").ok()?; + Some(serde_json::from_str(&raw).expect("dist json 解析失败")) +} + +#[test] +fn ok_matches_dist_success() { + let Some(dist) = load_dist() else { + println!("contract dist json 不在场,跳过同源断言"); + return; + }; + assert_eq!( + (errcode::OK.code, errcode::OK.message), + (dist.success.code, dist.success.message.as_str()) + ); +} + +#[test] +fn builtin_table_matches_dist_codes() { + let Some(dist) = load_dist() else { + println!("contract dist json 不在场,跳过同源断言"); + return; + }; + // 双向对表(不硬编码码数——加码只改 md + dist + 内建表三处,本测试零改): + // dist 每行都在内建表中且元数据全等;内建表除 OK 外无多余行 + let builtin_rows = errcode::BUILTIN.iter().filter(|c| c.code != 0).count(); + assert_eq!( + dist.codes.len(), + builtin_rows, + "内建码表与 dist 行数不一致(漂移)" + ); + for row in &dist.codes { + let c = errcode::lookup(row.code); + assert!( + errcode::is_registered(row.code), + "code {} 在内建表中缺失", + row.code + ); + assert_eq!( + (c.code, c.key, c.message, c.http), + (row.code, row.key.as_str(), row.message.as_str(), row.http), + "code {} 元数据与 dist 不一致", + row.code + ); + } +} diff --git a/stacks/rust/deny.toml b/stacks/rust/deny.toml new file mode 100644 index 0000000..db88cfe --- /dev/null +++ b/stacks/rust/deny.toml @@ -0,0 +1,15 @@ +# cargo-deny(spec 一-3):许可证白名单 + 禁重复大版本 + RUSTSEC 咨询。 +[graph] +all-features = true + +[licenses] +allow = [ + "MIT", + "Apache-2.0", + "Apache-2.0 WITH LLVM-exception", + "BSD-2-Clause", + "BSD-3-Clause", + "ISC", + "Unicode-3.0", + "Zlib", +] diff --git a/stacks/rust/rust-toolchain.toml b/stacks/rust/rust-toolchain.toml new file mode 100644 index 0000000..56f498d --- /dev/null +++ b/stacks/rust/rust-toolchain.toml @@ -0,0 +1,4 @@ +# 本地开发钉死 1.95.0(spec 一-1);CI 矩阵 stable + MSRV 1.80 双档经 +# dtolnay/rust-toolchain 的 RUSTUP_TOOLCHAIN 环境变量覆盖,互不干扰。 +[toolchain] +channel = "1.95.0" diff --git a/stacks/web/packages/contract/src/error-codes.ts b/stacks/web/packages/contract/src/error-codes.ts index 59fdcd5..25fdc20 100644 --- a/stacks/web/packages/contract/src/error-codes.ts +++ b/stacks/web/packages/contract/src/error-codes.ts @@ -1,4 +1,4 @@ -/** 错误码常量表 —— 与 contract/api/error-codes.md v1.0 同源(0/1xxx/2xxx 归 yarch;3xxx+ 业务侧扩展) */ +/** 错误码常量表 —— 与 contract/api/error-codes.md v1.1 同源(0/1xxx/2xxx 归 yarch;3xxx+ 业务侧扩展) */ export const CODE_SUCCESS = 0; export const errorCodes = { @@ -15,6 +15,7 @@ export const errorCodes = { CREDENTIALS_EXPIRED: 2002, FORBIDDEN: 2003, ACCOUNT_DISABLED: 2004, + CAPTCHA_INVALID: 2005, } as const; export type YarchErrorCode = (typeof errorCodes)[keyof typeof errorCodes]; diff --git a/stacks/web/packages/contract/test/contract.test.ts b/stacks/web/packages/contract/test/contract.test.ts index 39165df..ba3a265 100644 --- a/stacks/web/packages/contract/test/contract.test.ts +++ b/stacks/web/packages/contract/test/contract.test.ts @@ -1,5 +1,5 @@ /** - * 契约断言前端版:13 码全表唯一权威 = contract/dist/error-codes.json(由 error-codes.md + * 契约断言前端版:14 码全表唯一权威 = contract/dist/error-codes.json(由 error-codes.md * 派生,CI 拒双向漂移)——四栈读同一份 json 断言,不再各养手抄表(P1 契约机器可读出口)。 * dist 文件不在场(消费方独立环境)则跳过表断言,CI 仓内必跑。 */ @@ -26,8 +26,8 @@ const CONTRACT_TABLE: Record = distTable(); const DIST_PRESENT = Object.keys(CONTRACT_TABLE).length > 0; describe.skipIf(!DIST_PRESENT)("dist 同源断言(contract/dist/error-codes.json)", () => { - it("错误码表与 dist 契约逐码一致(13 码)", () => { - expect(Object.keys(CONTRACT_TABLE)).toHaveLength(13); + it("错误码表与 dist 契约逐码一致(14 码)", () => { + expect(Object.keys(CONTRACT_TABLE)).toHaveLength(14); expect(Object.keys(errorCodes).sort()).toEqual(Object.keys(CONTRACT_TABLE).sort()); for (const [name, code] of Object.entries(CONTRACT_TABLE)) { expect(errorCodes[name as keyof typeof errorCodes]).toBe(code);