Skip to content

fix(Middleware): validate allowedQueryParameters entries; #262 review follow-ups - #274

Merged
thomasfosterau merged 2 commits into
trunkfrom
issue-148-reserved-params-followup
Oct 8, 2026
Merged

thomasfosterau merged 2 commits into
trunkfrom
issue-148-reserved-params-followup

Conversation

@thomasfosterau

@thomasfosterau thomasfosterau commented Oct 8, 2026 •

Copy link
Copy Markdown
Owner

Summary

Follow-up to #262. Part of #148.

Review follow-ups to #262 (the reserved query-parameter 400), each checked against trunk at b1d774b, after #264.

  • Allow-list entries are now validated (should-fix). allowedQueryParameters documents its entries as "family base names made only of a-z", the only names the check ever rejects. An entry like lang[region], Lang, lang or "" could never match one, so before this change it admitted nothing, and the parameter it was meant to admit was still rejected. Such an entry now throws the new exported Middleware.InvalidAllowedQueryParameter (Schema.TaggedError, fields parameter and message, @since 0.17.0):

    • schemaErrorsLayer and layerWith throw it when the layer is built, so a typo fails at startup.
    • checkQueryParameters throws it when called.
    • For a bracketed entry whose base is reserved, the message names the base name to list instead (List its base name "lang").
    • For an empty entry "", the message says An empty entry names no parameter; remove it.
    • For any other entry, the message says that a name with a non-a-z character is never rejected, so it needs no entry.
    • The spec's own families (page, …) stay valid entries. They match ^[a-z]+$ and are harmless.
  • Validation runs once per layer. schemaErrorsLayer validates the list when it is built. It then passes the checked list to an internal (non-exported) rejectQueryParameters, so the list isn't re-validated on every request. The public checkQueryParameters is now allowedBaseNames + rejectQueryParameters, and it still validates its own options when called. rejectQueryParameters returns an Option, so the move adds no prefer-option-over-null warn-tier site. The public checkQueryParameters signature is unchanged (Option.getOrUndefined).

  • title: BadRequest.title (nit): already true, skipped. The check already spreads BadRequest.title, as schemaErrorDocument does. Nothing is hard-coded.

  • SchemaAST.isSuspend branch (nit). Added a test, what an endpoint's query schema declares › reads through a suspended schema. Its endpoint's query is Schema.suspend(() => Schema.Struct({ a })). ?a=1 answers 200, and ?a=1&unknown=1 answers the 400.

  • Changeset (nit). .changeset/reject-reserved-query-parameters.md from fix(Middleware): reject reserved all-lowercase query parameters with 400 #262 is still pending: the package is at 0.16.3, and the feature is @since 0.17.0. So I amended it rather than adding a changeset. It now names the lowercase parameters users are likely to hit:

    • q, search, lang, locale
    • limit, offset
    • format, callback
    • token, ref
    • t, v
    • fbclid, gclid

    It also notes that utm_source, _ and x-trace are unaffected, and adds the entry validation.

  • "An allowed name never reaches query" docs: already fixed by fix(Query): drop undeclared query parameters when the query declares nothing (#260) #264, skipped. fix(Query): drop undeclared query parameters when the query declares nothing (#260) #264 (6311818, 30e8530) made the claim true: an endpoint whose query declares nothing now drops undeclared parameters, and a test pins it. The QueryParameterOptions.allowedQueryParameters JSDoc and the README sentence also now say "which keeps only what its query schema declares — also when that schema declares nothing (bug: an endpoint whose query declares nothing passes every parameter to its handler, and ?x=1&x[y]=2 is a 500 #260)". No change needed.

  • Docs. All four entry points that can throw now say so in their JSDoc: QueryParameterOptions.allowedQueryParameters, schemaErrorsLayer, layerWith (added in the second commit) and checkQueryParameters.

README: one paragraph added in the Middleware "Reserved query parameters" section, describing the entry rule. Nothing else in the README is touched.

Mutation checks

  • Entry validation: the new tests were written first. Against unfixed code, 28 of the 29 failed (no throw). The one that passed asserts that valid entries don't throw.
  • Eager validation: with the layer's allowedBaseNames(options) replaced by the raw list (options?.allowedQueryParameters ?? []), 21 tests fail: 9 schemaErrorsLayer, 9 layerWith, the base-name hint, "needs no entry" and the empty-entry message.
  • checkQueryParameters still validates: with its allowedBaseNames(options) replaced by the raw list, 9 tests fail (each refuses … in a checkQueryParameters call).
  • Layer still answers the 400: with the layer's Option.isSome(rejected) short-circuited to false, 12 tests fail.
  • "Needs no entry" message: with the hint condition replaced by true (always "List its base name …"), says a name with any other character needs no entry fails. This test asserts that schemaErrorsLayer({ allowedQueryParameters: ["Lang"] }) throws a message containing "needs no entry" and not "List its base name".
  • Empty-entry message: with the parameter === "" branch disabled, says an empty entry names no parameter fails.
  • Error fields: with the thrown error's parameter mutated to "x", 9 tests fail. This confirms the toThrow(expect.objectContaining(…)) assertions bite.
  • isSuspend branch: with the branch deleted, reads through a suspended schema fails (expected 200 to be 400). The test passes with it restored.

Verification

All run locally on the head commit, in order:

  • pnpm install --frozen-lockfile: pass
  • vp run build: pass
  • vp check: pass (0 errors). The 4353 warnings match the base: no new warn-tier site. The two flagged sites in changed hunks were there before: the title conditional spread moved into rejectQueryParameters, and the allowedQueryParameters?: … | undefined / checkQueryParameters return-type declarations.
  • vp run check (sources, type-level tests, examples, emitted declarations): pass
  • vp run -r test:unit: pass. Root: 2286 tests. Examples: 42 / 39 / 53.
  • vp run docgen: pass. docgen does not run the new InvalidAllowedQueryParameter @example. @effect/docgen 0.5.2's getExampleFiles never collects examples from a class's own doc comment, so a throw in that example still passes docgen. (An earlier version of this body wrongly said docgen ran it.) I checked that example by hand instead, after vp run build:
    • Run with tsx: it prints lang[region] and exits 0.
    • Type-checked with tsc6 (TypeScript 6.0.3) under docgen's examplesCompilerOptions (--ignoreConfig --noEmit --strict --skipLibCheck --module esnext --moduleResolution bundler --target es2022 --lib es2022 --exactOptionalPropertyTypes false --types node): exit 0.
    • Negative control: the same tsc6 invocation on a copy that reads .nope fails with TS2339: Property 'nope' does not exist on type 'InvalidAllowedQueryParameter'.
    • The wider gap, class-level examples that docgen never checks, is filed as chore: docgen skips the @example in a class's own doc comment (10 examples never run) #276 and isn't fixed here.
  • fallow audit --base origin/trunk: pass ("No issues in 4 changed files"; one inherited sourceOf CRAP finding, excluded by the gate). The agent gate (fallow audit --format json --quiet --explain --gate-marker agent) verdict is pass.

Changeset

  • Amended the still-pending .changeset/reject-reserved-query-parameters.md (minor, from fix(Middleware): reject reserved all-lowercase query parameters with 400 #262). It names the common lowercase parameters and the new entry validation. This PR changes only unreleased 0.17.0 behaviour, so no new changeset is needed. The second commit changes only an error message and internal plumbing, and the changeset's text still holds.

Notes

  • Exported surface: one addition, Middleware.InvalidAllowedQueryParameter. Existing signatures are unchanged. schemaErrorsLayer / layerWith / checkQueryParameters can now throw on a misconfigured allow-list. That follows the Registry.layer / Registry.checkFamily precedent of throwing a tagged error for a construction-time misconfiguration. rejectQueryParameters is module-private.
  • Why reject rather than normalise:
  • Owner decision: how strict entry validation should be is the owner's call. This PR proposes the rule above as the default. The second commit doesn't change which entries are accepted or rejected, only the messages and where validation runs. The opt-out question is still the owner's too, as fix(Middleware): reject reserved all-lowercase query parameters with 400 #262 recorded.
  • I didn't touch any of fix(Query): drop undeclared query parameters when the query declares nothing (#260) #264's code beyond the allow-list plumbing in schemaErrorsLayer / checkQueryParameters.

🤖 Generated with Claude Code


Generated by Claude Code

… names (#148)

`allowedQueryParameters` lists family base names made only of a-z, the
only names the reserved-parameter check rejects. An entry such as
`lang[region]`, `Lang`, ` lang` or `""` could never match one, so it
silently admitted nothing and left the parameter it meant to admit
rejected. `schemaErrorsLayer` and `layerWith` now throw the new
`Middleware.InvalidAllowedQueryParameter` when the layer is built, and
`checkQueryParameters` when it is called; a bracketed entry's message
names the base name to list instead.

Also tests the declared-name walk through a suspended query schema, and
names in the pending changeset the common lowercase parameters (`q`,
`lang`, `limit`, `fbclid`, ...) that now answer 400.

Follow-up to #262. Part of #148.

Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc
Co-Authored-By: Claude <noreply@anthropic.com>
…ages (#148)

Review follow-ups to the allow-list entry validation:

- schemaErrorsLayer validates allowedQueryParameters when it is built and
  then hands the checked list to an internal rejectQueryParameters, rather
  than through checkQueryParameters, which re-validated on every request.
  checkQueryParameters still validates its own options.
- An empty entry now says "An empty entry names no parameter; remove it."
  instead of the any-other-character hint.
- layerWith's JSDoc says it throws InvalidAllowedQueryParameter, as the
  other three do.
- Tests pin the "needs no entry" message (not the base-name hint) and the
  empty-entry message.

Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc
Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants