Add HTTP QUERY Method Support (RFC 10008)

[thzgajendra]

Objective / Issue

Closes #3756. Add first-class support for the HTTP QUERY method (RFC 10008) to gofr — both inbound route registration and the outbound HTTP service client.

QUERY is a safe, idempotent, cacheable method that carries the query in the request body. It bridges the gap between GET (no body, URL-length limits, query leaks into logs) and POST (has a body but is neither safe nor idempotent). It is well-suited to service-to-service search/query APIs.

What we found

• Inbound: app had no way to register a QUERY route (GET/POST/PUT/PATCH/DELETE only).
• Outbound: the httpClient interface and every decorator (retry, auth, custom-header, file-token, rate-limiter, circuit-breaker) had no QUERY method. The circuit-breaker doRequest switch also had no default case — an unrecognized method silently returned a nil response.
• Go's net/http has no http.MethodQuery constant yet, but it accepts arbitrary method strings on both server and client, so there is no stdlib blocker.

How we fixed it

Inbound

• App.QUERY(pattern, handler) registers the route (method string "QUERY"). The body is read via the existing ctx.Bind (Content-Type driven), identical to POST.

Outbound

• Added Query / QueryWithHeaders(ctx, path, queryParams, body[, headers]) to the httpClient interface and httpService (delegates to the already method-agnostic createAndSendRequest).
• Threaded the two methods through every decorator: retryProvider, authProvider, customHeader, fileTokenDecorator, rateLimiter.
• Circuit breaker: added a QUERY case to doRequest plus the Query/QueryWithHeaders wrappers. Since QUERY is safe + idempotent, it is wrapped by the circuit-breaker and retry options like GET.
• Added a default case to doRequest returning a new ErrUnsupportedMethod instead of silently returning nil.
• Added the Query/QueryWithHeaders methods to the generated MockHTTP.

Design decisions / alternatives not taken

• Content-Type 400 enforcement: RFC 10008 says a server MUST reject a QUERY with a missing/invalid Content-Type. gofr's existing POST handling is lenient (Bind returns nil for unknown types), so to avoid changing shared request handling we kept the same behavior and documented the requirement (validate in the handler). Auto-enforcement was considered but rejected for blast-radius reasons.
• http.MethodQuery constant: not in Go's stdlib yet, so a package-level methodQuery = "QUERY" constant is used.

Docs / Test / Playground

• Docs: updated docs/advanced-guide/http-communication/page.md with Query/QueryWithHeaders and a note on QUERY semantics.
• Example: examples/http-server gains a SearchHandler on a QUERY /search route plus an integration test.

Test plan

• go build ./...
• go test ./pkg/gofr/... ./pkg/gofr/service/... pass
• gofmt clean; lint clean for changed code
• Inbound: end-to-end test registers QUERY /search, sends a QUERY with a JSON body, asserts the handler binds and echoes it.
• Outbound: httpService.Query/QueryWithHeaders (method, path, query params, body, Content-Type default, empty body).
• Decorators: Query covered for retry, auth, custom-header, file-token, rate-limiter.
• Circuit breaker: QUERY success routing + default-case returns ErrUnsupportedMethod.

Risk & Rollback

Low risk — purely additive. New interface methods are implemented across all decorators and the mock; existing verbs are unchanged. The only behavioral change to existing code is the circuit-breaker default case, which converts a previously silent nil-response path into an explicit error. Rollback is a straight revert.

[Umang01-hash]

Nice work — clean and consistent. Ran it locally: QUERY /search returns 200 with the body bound and echoed, and metrics (method="QUERY"), logs (trace/span IDs) and traces all show up correctly. QUERY mirrors POST in every decorator, the circuit-breaker default case is a good catch, and no breaking change (the HTTP interface is sealed by its unexported method, so external code can't implement it anyway).

One thing to fix before merge: docs/advanced-guide/mcp/page.md still says only GET/HEAD/OPTIONS are exposed as agent tools and "an agent cannot mutate state." Since QUERY routes are now exposed too, please update that page to match — it's the one place the docs contradict the new behavior.

Minor (optional): the retry and rate_limiter QUERY tests only assert status 200, so they'd pass even if Query delegated to the wrong verb — the other decorators pin method=="QUERY", so it's covered overall, just noting for parity.

Approving — only the MCP docs update is worth doing before merge.