Skip to content

feat: add query-gateway plugin for safe caching of read-only body queries - #13810

Open
fatihbm wants to merge 34 commits into
apache:masterfrom
fatihbm:query-gateway-main
Open

feat: add query-gateway plugin for safe caching of read-only body queries#13810
fatihbm wants to merge 34 commits into
apache:masterfrom
fatihbm:query-gateway-main

Conversation

@fatihbm

@fatihbm fatihbm commented Aug 12, 2026

Copy link
Copy Markdown

Description

Adds the query-gateway plugin, an opt-in cache boundary for read-only HTTP requests that carry query content in the request body.

The plugin supports both client POST and RFC 10008 QUERY requests:

  • Client POST requests are preserved when sent upstream.
  • Client QUERY requests are forwarded as POST by default for upstream compatibility.
  • Routes with upstream QUERY support can preserve the QUERY method.
  • Equivalent POST and QUERY query payloads produce the same canonical cache key.
  • Cache admission is conservative and explicit; arbitrary POST traffic is never cached.
  • Local-memory caching is supported by default, with optional Redis and Redis Cluster backends.
  • Redis failures use a bounded local-memory fallback.
  • Cache safety rules exclude unsafe responses and requests with relevant cache-control, authorization, cookie, or set-cookie conditions.

This is useful for search, analytics, reporting, Elasticsearch, and ClickHouse-style read-only requests. These workloads often use POST because they require a request body, even when their semantics are safe and idempotent. The plugin enables safe caching today without requiring immediate native QUERY support from every upstream.

Which issue(s) this PR fixes:

Fixes #13807

Validation

  • Added unit and integration coverage for request method handling, canonical cache keys, cache admission, cache hit/miss behavior, bypass behavior, and fallback behavior.
  • Added an Elasticsearch integration profile that verifies correlated client, APISIX, and upstream logs.
  • Verified client POST and QUERY scenarios, upstream POST and native QUERY forwarding modes, and cache bypass cases.

Checklist

  • I have explained the need for this PR and the problem it solves
  • I have explained the changes or the new features added to this PR
  • I have added tests corresponding to this change
  • I have updated the documentation to reflect this change
  • I have verified that this change is backward compatible

fatihbm added 30 commits August 11, 2026 13:23
@fatihbm
fatihbm marked this pull request as ready for review August 12, 2026 15:03
@dosubot dosubot Bot added size:XXL This PR changes 1000+ lines, ignoring generated files. doc Documentation things enhancement New feature or request github_actions Pull requests that update GitHub Actions code labels Aug 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Documentation things enhancement New feature or request github_actions Pull requests that update GitHub Actions code size:XXL This PR changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: add query-gateway plugin for safe caching of read-only body queries

1 participant