Repository navigation
Catalog: generic error details, contract check - #1224
Merged
Merged
Conversation
GET /datasets, GET /datasets/search, and GET /datasets/resolve/:id returned the raw Error#message as `details` to anonymous callers on their failure paths, leaking table/column names and query shape. The raw message is still logged server-side via console.error (including a previously-unlogged fallback catch); the response now carries a generic, stable details string instead. Tested with backend/test/catalog-anonymous-error-details.test.ts, which drives the real routes through a fault-injecting D1 wrapper and asserts the raw message never appears in the response body while still being logged. Each of the four fixed call sites was verified to make its corresponding test fail when reverted. Closes #1152
GET /datasets and GET /datasets/:id now safeParse their response against the shared zod contract (catalogItemSchema/datasetDetailSchema envelopes) and log a bounded console.error with the dataset id(s) and first few issues on a mismatch. Log-not-throw: a malformed response still reaches the caller unchanged. Runs on every response in development/test; production samples at ~2% (uniform across both routes) to keep the added safeParse cost negligible at catalog traffic volume. Tested with backend/test/catalog-contract-validation.test.ts, which seeds a real D1 row with an out-of-enum zarr_verify_status (via the sweep_stamps JSON column, since the stored zarr_status column has its own CHECK constraint) through the real routes and asserts the log fires while the response still serves the invalid value unmodified. A statistical test bounds the production sampling rate between 1 and 200 violations over 1000 requests. Each assertion was verified to fail against a reverted/mutated version of the code it covers. Closes #1207
📦 Package PreviewYour package is ready to test! bun install -g nemar-cli@PR1224Version: 🤖 Updated on each push. |
GET /datasets/:id served id as a raw D1 number (SELECT d.*) while catalogItemSchema declares id: string, and file_size_formatted was null for unmeasured file_size while datasetDetailSchema left it non-nullable -- both meant the #1207 validation hook flagged every well-formed detail response from day one. Fixed at the source: id is stringified where the detail object is built, and file_size_formatted is marked nullable on datasetDetailSchema specifically, since the detail route's null vs the list route's '' coalesce is a pre-existing, deliberate split (the list route's file_size_formatted stays non-nullable, matching its actual behavior). Added the missing clean-pass positive control for GET /datasets/:id (a well-formed row logs nothing) and removed the now-unnecessary hand stringification workaround in catalog-has-zarr.test.ts. Tested with backend/test/catalog-contract-validation.test.ts and backend/test/catalog-has-zarr.test.ts (zero [contract] log lines). Both fixes were verified independently: reverting either the id stringification or the nullable schema change makes the new positive-control test fail.
The safeParse/logContractViolation sequence ran synchronously before return c.json(...), contradicting its own doc comment that it must never observably add latency. deferContractCheck now schedules that work on executionCtx.waitUntil, mirroring afterResponse() in routes/auth-orcid.ts: the response returns first, the check runs after, with the same try/catch fallback afterResponse uses (Hono's Context#executionCtx throws when no ExecutionContext was provided, so optional chaining alone is not enough) so a fire-and-forget microtask still runs the check when there is none. Updated the doc comment to describe what is actually guaranteed: latency isolation, not zero cost -- the sampling rate is still what bounds production CPU cost. Test-side, added requestFlushed to catalog-contract-validation.test.ts, mirroring zarr-data-cache.test.ts's requestWith: an explicit test ExecutionContext whose waitUntil is collected and flushed via Promise.allSettled before assertions run, replacing the implicit (and now unverifiable-by-inspection) assumption that Hono's own internal await chain would let the deferred microtask complete before app.request() resolves. Tested with backend/test/catalog-contract-validation.test.ts, backend/test/catalog-has-zarr.test.ts, backend/test/facet-filters-route.test.ts, backend/test/dataset-detail-contract.test.ts, and backend/test/zarr-data-cache.test.ts.
The GET /datasets contract-violation log passed the whole page's dataset_id array (up to 200) regardless of how many rows actually failed. failedListRowIds derives the failing row ids from the zod issue paths (datasets.<index>.<field>), dedups, and caps at 5, so the log names only the rows that need attention. Tested with backend/test/catalog-contract-validation.test.ts's new mixed-page test (one well-formed row, one deliberately invalid), which asserts the log names only the invalid row. Verified the test fails when failedListRowIds is reverted to logging every row's id.
ANONYMOUS_ERROR_DETAILS gave no guidance. Appended retry/support wording: "Please try again; if it persists, contact support." Exported the constant and imported it in catalog-anonymous-error-details.test.ts instead of hand-copying the string, so the test can't silently drift from the real wording.
This was referenced Sep 3, 2026
This branch was previously deployed
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
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.
Summary
Two independently reviewed fixes to the public catalog routes in backend/src/routes/datasets/catalog.ts, each landed as its own commit.
The first fixes issue #1152: GET /datasets, GET /datasets/search, and GET /datasets/resolve/:id are anonymous endpoints that returned the raw Error#message as
detailson their failure paths, leaking table/column names and query shape to unauthenticated callers. The raw message is still logged server-side via console.error on every path, including a fallback catch that previously had no logging at all; the response now carries a generic, stable details string instead. The response shape and status codes are unchanged.The second fixes issue #1207: nothing parsed a live catalog or detail response against the shared zod contract in shared/contract/dataset.ts, so a production regression in a derive path could ship data the contract calls invalid with no signal until a consumer's own parse threw. GET /datasets and GET /datasets/:id now safeParse their response against catalogItemSchema/datasetDetailSchema (via their envelope schemas) and log a bounded console.error naming the dataset id(s) and the first few zod issues on a mismatch. This is log-not-throw: a malformed response still reaches the caller unchanged, per ADR 0005. The check runs on every response in development/test; production samples at roughly 2%, applied uniformly to both routes, to keep the added cost negligible at catalog traffic volume.
Both fixes are scoped to backend/src/routes/datasets/catalog.ts per the issues; the audit of other route files with the same details:msg idiom is the issue's own stated follow-up, not in scope here.
Test plan
bun run lint-- clean.bun x biome check backend/src backend/test shared-- 6 pre-existing errors and 1 warning in backend/src/services/zenodo.ts, backend/src/services/doi-orcid-discovery.ts, and backend/test/bucket-policy.test.ts, none touched by this PR (verified viagit diff origin/devshowing zero diff on those files).bun run typecheck-- clean.bun test backend/test/catalog-anonymous-error-details.test.ts backend/test/catalog-contract-validation.test.ts backend/test/catalog-has-zarr.test.ts backend/test/dataset-detail-contract.test.ts backend/test/facet-filters-route.test.ts backend/test/facet-table-correspondence.unit.test.ts test/contract-live.test.ts test/contract-schemas.test.ts test/search-retrieval.test.ts test/search-min-score.unit.test.ts-- 315 pass, 6 skip, 0 fail.bun test backend/test/(full backend suite) -- 1645 pass, 0 fail.bun test(full repo, includes test/api.test.ts, test/cli.test.ts, test/e2e-upload.test.ts): 52 pre-existing failures, all in the live-integration tier that requires a deployed backend plus TEST_ADMIN_API_KEY/TEST_USER_API_KEY, neither of which is available in this sandbox. None of the 52 failing tests are in catalog.ts, backend/test/, or shared/contract/; confirmed unrelated to this change.Closes #1152
Closes #1207