fix(client,runtime): reconcile the four dispatcher↔client shape mismatches (#3584) - #3592
Merged
Merged
Conversation
…tches (#3584) The #3563 audit ledgered four routes as 'mismatch'. Re-verification showed the two analytics shapes the client spoke (GET /analytics/meta/:cube, POST /analytics/explain) were served by NOTHING — not the dispatcher, not @objectstack/rest, not service-analytics — so both methods 404ed against every deployment and had zero call sites. Split resolution: - analytics ×2 — client aligns to the dispatcher (not breaking in practice: a universally-404ing method has no working callers). analytics.meta(cube?) now calls GET /analytics/meta with an optional ?cube= filter, threaded through the dispatcher into AnalyticsService.getMeta(cubeName?) which always supported it; analytics.explain keeps its name and calls POST /analytics/sql. Ledger rows reclassified mismatch → sdk. - storage ×2 — deliberate disposition, no code moves. The presigned/chunked protocol the SDK speaks is registered autonomously by service-storage on any http-server (not REST-only as the audit assumed); reshaping the client to the bare dispatcher route would regress direct-to-cloud, resumable uploads, upload auth (#2755) and download authorization (#2970/ADR-0104). Ledger rows reclassified mismatch → server-only with the rationale; decision recorded in the audit doc §4 Resolution. Guards stay green: URL-shape tests pin the reconciled client routes, a dispatcher test pins the ?cube= threading, and the ledger hygiene tests (notes on every non-sdk row) pass unchanged. Closes #3584 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Uij3WXdY7d4882DxMeaAAJ
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 26 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Uij3WXdY7d4882DxMeaAAJ
github-actions
Bot
added
documentation
os-zhuang
marked this pull request as ready for review
July 27, 2026 08:55
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #3584. This PR is the decision record the issue's acceptance criteria ask for.
决议：四行不拆成同一个选项
复核修正了审计的一个前提：client 端 analytics 使用的两个形状(
GET /analytics/meta/:cube、POST /analytics/explain)没有任何服务端实现——dispatcher 不提供,@objectstack/rest只挂载/analytics/dataset/query,service-analytics不注册任何 HTTP 路由。所以这两个方法在一切部署形态下都 404("REST 才懂"不成立),且在 objectstack/objectui 两仓库中调用点为零。Analytics ×2 → Option B(client 对齐 dispatcher)
实际上并非破坏性变更:一个必然 404 的方法不可能有正常工作的调用方。
analytics.meta(cube?)→GET /analytics/meta[?cube=]。cube 参数改为可选;dispatcher 现在把?cube=传入AnalyticsService.getMeta(cubeName?)(该过滤能力本来就存在,只是没接线)。analytics.explain(payload)→ 保留方法名,改调POST /analytics/sql(dispatcher 的 SQL dry-run 路由,后端为generateSql)。mismatch→sdk。Storage ×2 → documented deliberate disposition(不动代码)
presigned/chunked 协议不是 REST 独有:
service-storage在任何http-server服务上自主注册它(storage-service-plugin.ts:283)。把 client 改回裸POST /storage/upload会回退直传云端、分块/断点续传、上传鉴权(#2755)与下载授权(#2970/ADR-0104)。协议为规范路径;dispatcher 的两条裸路由在 ledger 中改记为server-only(低层 redirect/stream 兼容面),理由写入行内 note,决议记录于审计文档 §4 Resolution。变更清单
packages/client/src/index.ts— 两个 analytics 方法对齐 dispatcher 形状packages/runtime/src/domains/analytics.ts+http-dispatcher.ts—?cube=过滤接线(约 5 行)packages/runtime/src/route-ledger.ts— 四行重新分类,mismatch归零docs/audits/2026-07-dispatcher-client-route-coverage.md— §4 增加 Resolution,follow-up [WIP] Fix error in step four of the action run #5 标记完成?cube=全链路测试;ledger hygiene guard 机械通过content/docs/api/client-sdk.mdx— 注释修正验证
pnpm turbo test --filter=@objectstack/runtime— 25/25 通过pnpm turbo test --filter=@objectstack/client— 27/27 通过🤖 Generated with Claude Code
https://claude.ai/code/session_01Uij3WXdY7d4882DxMeaAAJ
Generated by Claude Code