Skip to content

Commit fa5e863

Browse files
fix(rest)!: refuse unknown keys on the dataset query body (#29156) (#29251)
domain:server#2 · os-steve · session_01ADHkmQxwoGb5fSnrFkpxmt <!-- claude-projects-attribution: {"github_login":"os-steve"} --> _Requested by **Steve** · [project thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9V3vR51WpJqhGrbpzMAviUT)_ Fixes #29156 Clause-②: no (narrowing) Metadata-protocol: none ## 维护者速读 - 改了什么:数据集查询接口 `POST /analytics/dataset/query` 现在拒收请求体里它不认识的键(400 VALIDATION_FAILED,点名该键);把 `runtimeFilter` 放错在 `selection` 外面时,提示「did you mean `selection.runtimeFilter`」。同时给了 `dataset` 又给 `datasetName` 也拒收。 - 为什么改:以前放错位置的筛选条件被静默丢掉,接口照样 200,返回的是未筛选的总数,看板数字偏大且无人察觉。 - 风险与回滚:只影响发送了多余键的调用方;客户端 SDK、控制台看板/报表/数据集预览、verify 都只发这四个键,实测不受影响。回滚即还原 `analytics-routes.ts` 的一处调用。 - 先看:`packages/rest/src/analytics-dataset-body-door.ts`(判定逻辑与提示);`packages/rest/src/analytics-routes.ts`(接入点,在 selection 判定之前);`packages/rest/src/analytics-dataset-body-door.test.ts`。 - 两分钟验证:`pnpm --filter @objectstack/rest exec vitest run src/analytics-dataset-body-door.test.ts`,预期 19 条全过(其中 10 条在 main 上为红)。 - 需要你做的:无,席位落地。 ## What changes `POST {basePath}/analytics/dataset/query` judged `body.selection` (through `datasetSelectionRefusal`), `body.dataset` and `body.datasetName`, and ignored every other top-level key. A `runtimeFilter` written beside `selection` instead of inside it answered **200 with the unfiltered aggregate**; `"bogus": 1` beside `selection` answered 200 too. The sibling door `POST /analytics/query` refuses an unknown key, and this door's own `selection` refuses one with a "did you mean" hint. - New `packages/rest/src/analytics-dataset-body-door.ts`: `datasetQueryBodyRefusal(body)` over the closed set `DATASET_QUERY_BODY_KEYS` = `dataset`, `datasetName`, `previewDrafts`, `selection`, measured from the handler's read points (the handler reads exactly these four off `req.body`). - An unknown key answers `400 VALIDATION_FAILED`, message `Unrecognized key(s) on this dataset query: ...` (the sibling door's opening), one `details.fields[]` entry per key with `code: unknown_field`. The query never runs. - Remedy: `runtimeFilter`, `filter`, `filters`, `where` say `did you mean selection.runtimeFilter?`; any other selection member says `did you mean selection.KEY?`. The member list is read off `DatasetSelectionSchema.shape`, not transcribed. - A truthy `dataset` beside a truthy `datasetName` (the handler's own truthiness) answers `400 VALIDATION_FAILED` naming both (`invalid_shape`). A falsy `datasetName` beside `dataset` still runs inline, and a falsy `dataset` beside a name still runs the saved dataset, as before. - `analytics-routes.ts`: one call, right after the body is read and before the `selection.measures` check, so a misplaced member is named before "selection.measures must be a non-empty array". - Envelope: this door's own body-refusal frame (flat `{ code, message, details.fields }`, the one an unknown `selection` key already answers here), not the nested `{ error: {...} }` the sibling dispatcher door writes. One door, one dialect. - Changeset `.changeset/29156-dataset-query-body-unknown-keys.md` (`@objectstack/rest` patch, BREAKING banner, Before / Now / Unchanged bullets and the remedy, `adr-0087: not-required (no-migration-prescription)`). - `content/docs/data-modeling/analytics.mdx` states the body shape, so it now says which keys the body takes and what is refused. No `packages/spec` or `ui/` edit. ## Why A dropped filter is a wider number with nothing to tell it apart from a filter that matched everything: the REST ingress policy's silent-widening case (`query-allowlist.ts`), on the body instead of the query string. ### Producer census (before narrowing) | Producer | Keys it sends | |:--|:--| | `@objectstack/client` `analytics.queryDataset` | the caller's payload, typed `dataset?`, `datasetName?`, `selection`, `previewDrafts?` | | Console `ui/packages/data-objectstack` `queryDataset` (dashboards, reports, charts, filter bar, dataset preview) | `datasetName` OR `dataset` (a ternary), `selection`, `previewDrafts` only when true | | `@objectstack/verify` `dashboard-window.ts` | `datasetName`, `selection` | | docs `analytics.mdx`, platform-checklist `dashboards.json` / `studio-authoring.json` | `datasetName`, `selection` | | dogfood suites (10 files) | `dataset` or `datasetName`, `selection` | | MCP / AI tools (`packages/mcp`, `service-ai`) | none: no caller of this door | No producer sends a key outside the four, and none sends both `dataset` and `datasetName`, so the pair is refused in this PR (delta acceptance 3). ## Tests - `packages/rest/src/analytics-dataset-body-door.test.ts` (new, 19 cases, through the real route): §1 refusals (top-level `runtimeFilter` on a saved and an inline dataset, `filter` / `filters` / `where`, a misplaced `dimensions`, `bogus`, several keys sorted, the accepted keys listed), each asserting status, `code`, the named keys, the remedy, and that `queryDataset` was never called; §2 the `dataset` + `datasetName` refusal (no lookup, no query) and its three controls (a `''` and a `null` `datasetName` beside `dataset` run inline; a `null` `dataset` beside a name runs the saved dataset); §3 controls asserting the arguments the service received (`datasetName`, inline `dataset`, `selection.runtimeFilter`, `previewDrafts`, the unchanged selection-level refusal, the unchanged "Provide body.dataset" message). - `packages/qa/dogfood/test/analytics-dataset-body-door.dogfood.test.ts` (new, 4 cases, showcase stack over HTTP): plain body 200 with a count above 0; `selection.runtimeFilter` 200 and narrows to 0; top-level `runtimeFilter` 400 with the remedy; `bogus` 400. - No existing test needed an edit. ## Verification Head `9b9d5b7b` (a fast-forward on `dbf091e2`, the merge of `origin/main` 14208f2 into the fix), objectstack-ai/objectstack. The `9b9d5b7b` round aligned the `dataset` + `datasetName` check to the handler's truthiness and added two pins (a `''` and a `null` `datasetName` beside `dataset` run inline). At `9b9d5b7b`: the rest pin file 19 of 19; ablation of the old condition reds the `''` pin (1 failed, 18 passed) and restores to HEAD; rest suite 368 files, 6982 tests passed; typecheck exit 0; the same 90 derived gates all exit 0. The readings below are from `dbf091e2` unless stated; the dogfood battery was not re-run, since no dogfood test sends both keys. <details><summary>Red first on main, green with the fix</summary> - Base `692e0dc8`, the test committed alone (`e7b0ead3`): `pnpm --filter @objectstack/rest exec vitest run src/analytics-dataset-body-door.test.ts` → **Tests 10 failed | 7 passed (17)**; every refusal case read `expected 200 to be 400` with the body `{"rows":[],"fields":[]}` (the query ran), every control green. - With the fix (`1d599e3e`): **Tests 17 passed (17)**; dogfood pin **Tests 4 passed (4)**. </details> <details><summary>Ablation of the refusal (scripts/ablation-replace.mjs, rebuilt, dist proven)</summary> - Mutation: `if (bodyRefusal) {` → `if (bodyRefusal && false) {` in `analytics-routes.ts` (anchor 1 → 0, blob 372cafb → 3142e06b6c1b); `@objectstack/rest` rebuilt with `--force`; `ablation-dist-preflight` marker present in `dist/index.cjs` and `dist/index.js`. - Rest pin: **Tests 10 failed | 7 passed (17)**, the same 10 refusals red. - Dogfood pin (showcase over HTTP): **Tests 2 failed | 2 passed (4)**. The top-level `runtimeFilter` case read `{"rows":[{"project_count":5}], …, "sql":"SELECT COUNT(*) AS \"project_count\" FROM \"showcase_project\""}: expected 200 to be 400`: the unfiltered count, while the `selection.runtimeFilter` control on the same stack answers 0. - Restore: blob == HEAD 372cafb, `git diff HEAD` empty; rebuilt, `--absent` marker absent from all 6 built files, tree clean; rest pin 17/17, dogfood pin 4/4. </details> <details><summary>Package suites and lint</summary> - `pnpm --filter @objectstack/rest test` → **Test Files 368 passed (368) · Tests 6980 passed | 332 skipped**, exit 0 (at `6b02dae7`; the merge brought no `packages/rest` or analytics path). - `pnpm --filter @objectstack/rest typecheck` → exit 0 (test layer 0 errors). - `eslint packages/rest packages/qa/dogfood --no-inline-config` (root config) → exit 0. </details> <details><summary>Full dogfood battery (narrowing), final head dbf091e</summary> - `pnpm --filter @objectstack/dogfood test` under os-verify-lock → `VERDICT command-exit 0` · **Test Files 389 passed | 3 skipped (392) · Tests 3212 passed | 28 skipped (3240)**. No failure. </details> <details><summary>Derived gates at dbf091e</summary> - `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` → 90 commands; all run, all exit 0. `check-plugin-teardown-shape.mjs --self-test` first answered exit 3 (pinned commit 621a487 missing from the shallow clone); after `git fetch --depth=1 origin 621a487…` it passed (48 cases). - `--ran` reconciliation: **90 derived, 90 run, 0 NOT-MEASURED, 0 UNRUN** (a DERIVED zero). - `check-changeset-no-major.mjs --base origin/main --event` (this body) → exit 0: `no (narrowing)` + `none` at `patch`. `check-adr-0087-registration.mjs` → `not-required (no-migration-prescription)` notice. </details> ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (no spec edit) - [x] 2. Every name I added uses the casing for its kind. - [x] 3. No formatter ran; `pnpm lint` passes. (eslint over the touched packages, see Verification) - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [ ] 6. `packages/spec` touched: n/a, not touched. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English (the 维护者速读 section is the required Chinese summary). - [x] The *Before Submitting* list in CONTRIBUTING.md is done. ## Acceptance notes - The claim wrote `Clause-②: no`; this refuses bodies that answered 200 before, so the PR and changeset carry `Clause-②: no (narrowing)` (the delta's narrowing rules: `!` title, BREAKING banner, `adr-0087:` marker, full dogfood battery, ablation). - Out of scope, noted: the same route's query string is not a closed set (it reads `preview` through `refuseRepeatedQueryParams` only); the ingress policy converts routes per lane. --- _Generated by [Claude Code](https://claude.ai/code/session_01ADHkmQ6M1P18JzkN4aDNPb)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 5a2bdf9 commit fa5e863

6 files changed

Lines changed: 529 additions & 0 deletions

File tree

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
'@objectstack/rest': patch
3+
---
4+
5+
fix(rest)!: `POST /analytics/dataset/query` refuses an unknown key on its request body, and a body naming both `dataset` and `datasetName`, instead of answering 200 (#29156)
6+
7+
Clause-②: no (narrowing) — the dataset query door refuses two request bodies it served before: one carrying a key beside `selection` that the door does not read, and one naming both `dataset` and `datasetName`. Nothing is widened, and no published spec schema moves.
8+
Metadata-protocol: none
9+
10+
<!-- adr-0087: not-required (no-migration-prescription) No metadata key, spec schema, export or type changes: this is the REST door's own request body, which reads the same four keys as before. The refusal names each key it did not understand and where it belongs, so the caller's fix is in the answer and there is nothing for a migration to rewrite. -->
11+
12+
**BREAKING** accept-set narrowing at `POST /analytics/dataset/query` (`@objectstack/rest`).
13+
14+
- **Before.** The door read `selection`, `previewDrafts`, `dataset` and `datasetName` off the body and ignored every other key. A `runtimeFilter` written beside `selection` instead of inside it answered 200 with the UNFILTERED aggregate, and `bogus: 1` beside `selection` answered 200 too. A body naming both `dataset` and `datasetName` ran the inline definition and dropped the name without a word.
15+
- **Now.** Any other top-level key answers `400 VALIDATION_FAILED` naming it ("Unrecognized key(s) on this dataset query: …"), with one `details.fields[]` entry per key (`code: unknown_field`), and the query is not run. A misplaced selection member names its place: `runtimeFilter`, `filter`, `filters` and `where` say "did you mean `selection.runtimeFilter`?", and any other selection member (`dimensions`, `measures`, `order`, …) says "did you mean `selection.KEY`?". `dataset` beside `datasetName` answers `400 VALIDATION_FAILED` naming both.
16+
- **Unchanged.** `{ datasetName, selection }`, `{ dataset, selection }` and `previewDrafts` are served as before, and the analytics service receives the same arguments. A `null` `dataset` beside a `datasetName` still runs the saved dataset. The refusals inside `selection` are unchanged.
17+
- **Who sees it.** A caller that sends a key the door never read. `@objectstack/client`'s `analytics.queryDataset`, the Console's dashboards, reports and dataset preview, and `@objectstack/verify` send only the four keys above, and never both `dataset` and `datasetName`.
18+
19+
**The remedy.** Move a selection member inside `selection` (`{ datasetName, selection: { measures, runtimeFilter } }`), drop any other key, and send exactly one of `dataset` (an inline definition) or `datasetName` (a saved one).

‎content/docs/data-modeling/analytics.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -262,6 +262,13 @@ POST {basePath}/analytics/dataset/query
262262
selection: { dimensions: ['stage'], measures: ['revenue'], runtimeFilter: {...} } }
263263
```
264264

265+
The body takes `selection`, `previewDrafts`, and exactly one of `dataset` (an
266+
inline definition) or `datasetName` (a saved one). Every selection member, the
267+
filter included, goes inside `selection`: any other top-level key is refused
268+
with `400 VALIDATION_FAILED` naming it (a `runtimeFilter` beside `selection`
269+
answers "did you mean `selection.runtimeFilter`?"), and so is a body naming
270+
both `dataset` and `datasetName`.
271+
265272
The same governed path backs the Studio dataset preview, dashboard widgets, and
266273
dataset-bound reports — so the numbers match everywhere.
267274

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
//
3+
// END-TO-END gate for #29156: `POST /analytics/dataset/query` refuses an
4+
// unknown key on its OUTER body, proven on the stock showcase through the real
5+
// stack (HTTP → REST → the dataset query door).
6+
//
7+
// Before the fix a `runtimeFilter` written beside `selection` instead of
8+
// inside it answered 200 with the UNFILTERED aggregate, and `bogus: 1` beside
9+
// `selection` answered 200 too. Both now answer 400 VALIDATION_FAILED naming
10+
// the key; the misplaced filter names `selection.runtimeFilter`.
11+
//
12+
// Controls: the same filter inside `selection` is served (200) and actually
13+
// narrows the answer, and the plain body is served.
14+
15+
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
16+
import { type VerifyStack } from '@objectstack/verify';
17+
import { bootShowcase } from './showcase-boot.js';
18+
19+
const DATASET = 'showcase_project_metrics';
20+
const MEASURE = 'project_count';
21+
// Matches no showcase project, so a filter that is honoured answers 0 and a
22+
// dropped one answers the full count.
23+
const NO_MATCH = { name: { $icontains: 'zz-no-such-project-29156' } };
24+
25+
describe('dogfood: the dataset query door refuses unknown body keys (#29156)', () => {
26+
let stack: VerifyStack;
27+
let token: string;
28+
29+
beforeAll(async () => {
30+
stack = await bootShowcase();
31+
token = await stack.signIn();
32+
}, 180_000);
33+
34+
afterAll(async () => {
35+
await stack?.stop?.();
36+
});
37+
38+
async function datasetQuery(body: Record<string, unknown>): Promise<{ status: number; body: Record<string, any> }> {
39+
const res = await stack.apiAs(token, 'POST', '/analytics/dataset/query', body);
40+
return { status: res.status, body: (await res.json()) as Record<string, any> };
41+
}
42+
43+
const count = (body: Record<string, any>): number => Number(body.rows?.[0]?.[MEASURE] ?? 0);
44+
45+
it('CONTROL: the plain body is served and counts projects', async () => {
46+
const res = await datasetQuery({ datasetName: DATASET, selection: { measures: [MEASURE] } });
47+
expect(res.status, JSON.stringify(res.body)).toBe(200);
48+
expect(count(res.body)).toBeGreaterThan(0);
49+
});
50+
51+
it('CONTROL: `selection.runtimeFilter` is served and narrows the answer', async () => {
52+
const res = await datasetQuery({ datasetName: DATASET, selection: { measures: [MEASURE], runtimeFilter: NO_MATCH } });
53+
expect(res.status, JSON.stringify(res.body)).toBe(200);
54+
expect(count(res.body)).toBe(0);
55+
});
56+
57+
it('a top-level `runtimeFilter` → 400 VALIDATION_FAILED naming it, remedy `selection.runtimeFilter`', async () => {
58+
const res = await datasetQuery({ datasetName: DATASET, selection: { measures: [MEASURE] }, runtimeFilter: NO_MATCH });
59+
expect(res.status, JSON.stringify(res.body)).toBe(400);
60+
expect(res.body.code).toBe('VALIDATION_FAILED');
61+
expect(String(res.body.message)).toContain('Unrecognized key(s) on this dataset query: `runtimeFilter`');
62+
expect(String(res.body.message)).toContain('did you mean `selection.runtimeFilter`?');
63+
expect(res.body.details?.fields?.map((f: { field: string }) => f.field)).toEqual(['runtimeFilter']);
64+
});
65+
66+
it('`bogus: 1` beside `selection` → 400 VALIDATION_FAILED naming `bogus`', async () => {
67+
const res = await datasetQuery({ datasetName: DATASET, selection: { measures: [MEASURE] }, bogus: 1 });
68+
expect(res.status, JSON.stringify(res.body)).toBe(400);
69+
expect(res.body.code).toBe('VALIDATION_FAILED');
70+
expect(String(res.body.message)).toContain('Unrecognized key(s) on this dataset query: `bogus`');
71+
});
72+
});

0 commit comments

Comments
 (0)