Skip to content

Add first-class HTTP QUERY registration support - #488

Open
Ken Dale (kendaleiv) wants to merge 1 commit into
Azure:v4.xfrom
kendaleiv:add-http-query
Open

Ken Dale (kendaleiv) wants to merge 1 commit into
Azure:v4.xfrom
kendaleiv:add-http-query

Conversation

@kendaleiv

Copy link
Copy Markdown
Member

Summary

Add QUERY to the public HttpMethod type so TypeScript applications can register QUERY-specific HTTP triggers without type assertions.

Introduce app.query overloads following the existing HTTP registration helpers, document usage, and add coverage for registration metadata, public declarations, and request-body preservation.

This change addresses library registration support; it does not change host or proxy handling of QUERY requests. Receiving these requests also requires support in the deployed Functions host and any intervening proxies.

@kendaleiv
Ken Dale (kendaleiv) requested a review from a team as a code owner November 10, 2026 16:01
@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 3ca87db4-e33d-49ca-b76d-db9ccb384dbd
@swapnil-nagar

Copy link
Copy Markdown
Contributor

Thank you for your contribution. Let me validate these change and have few testing done.

Changes looks simple though.

@TsuyoshiUshio

Copy link
Copy Markdown
Contributor

Thanks for this contribution, Ken Dale (@kendaleiv)! I reviewed the change and also traced how a QUERY registration flows through the Node.js worker and the Functions host.

Overall

The PR itself looks good to me. app.query reuses the existing HTTP registration path, and the worker and host pass the method list through as strings, so no runtime changes are needed there. I verified it locally with Core Tools 4.15.2 (Host 4.1053.200.26403, Node worker 3.16.0, Node 22.23.4), in both the normal gRPC mode and HTTP streaming mode:

  • app.query(name, handler), app.query(name, options), and app.http({ methods: ['GET', 'QUERY'] }) register and route correctly.
  • The request body (JSON, including a >64 KiB Unicode payload) is preserved, including after clone().
  • A QUERY-only route rejects GET and POST (404 without invoking the handler).
  • Existing GET/POST registrations and the default ['GET', 'POST'] methods are unchanged (the default does not accept QUERY).
  • The full unit suite (500 tests) passes, and the public types check against TypeScript 5.0 and 4.0.

RFC 10008 alignment: suggest documenting the handler's responsibilities

QUERY is now standardized as RFC 10008. This PR adds registration support, which fits the RFC's intended use (a safe, idempotent request that carries its query in the request body). However, registering with app.query does not by itself make an endpoint RFC-compliant, and users may assume otherwise. I'd suggest adding a short note to the app.query JSDoc (and the docs, if applicable) covering:

  • The function must enforce the Content-Type itself. RFC 10008 §2 requires servers to fail the request if Content-Type is missing or inconsistent with the content. Neither the library nor the host enforces this; in my local test, a handler without validation returned 200 for a QUERY request with no Content-Type.
  • The handler is responsible for keeping QUERY safe and idempotent (no state changes).
  • Caching, conditional requests, and Accept-Query are not provided automatically. Per RFC 10008 §2.7, a cache key for QUERY must include the request content, not just the URL.
  • QUERY is unrelated to the URL query string (request.query).

Potential TypeScript source-compatibility break

Adding 'QUERY' to the public HttpMethod union can break customer code that handles HttpMethod exhaustively. For example:

const labels: Record<HttpMethod, string> = {
  GET: 'GET', POST: 'POST', DELETE: 'DELETE', HEAD: 'HEAD', PATCH: 'PATCH',
  PUT: 'PUT', OPTIONS: 'OPTIONS', TRACE: 'TRACE', CONNECT: 'CONNECT',
};
// After this PR: TS2741: Property 'QUERY' is missing in type ... but required in type 'Record<HttpMethod, string>'.

An exhaustive switch that uses a never check fails similarly (TS2345). I confirmed both snippets compile against the current types and fail against this PR.

This doesn't affect apps that are already running; it surfaces only when a customer upgrades the package and recompiles their TypeScript. Because of that, I don't think this necessarily requires a major version bump. Either way, we should state it clearly in the release notes (and in a tracking issue, if we have one), including the fix: add a QUERY entry, or use Partial<Record<HttpMethod, T>> if only some methods are handled intentionally.

Swapnil Nagar (@swapnil-nagar), what do you think? Should we treat this as a minor release with a clear release-note callout, or do you consider widening HttpMethod a breaking change that needs a major version bump?

@swapnil-nagar

Swapnil Nagar (swapnil-nagar) commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Tsuyoshi Ushio (@TsuyoshiUshio) This should be part of 4.17.2. And I do not expect breaking changes. We just need the integration test running daily to ensure there is no regressions.

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.

3 participants