feat: add RFC 10008 QUERY method and Accept-Query header support#1077
Open
He-Pin wants to merge 5 commits into
Open
feat: add RFC 10008 QUERY method and Accept-Query header support#1077He-Pin wants to merge 5 commits into
He-Pin wants to merge 5 commits into
Conversation
Motivation: RFC 10008 defines the HTTP QUERY method as a safe, idempotent method that expects a request body, along with the Accept-Query response header for signaling supported query media types. pekko-http should provide first-class support for this standard HTTP method. Modification: - Add QUERY method constant to HttpMethods (Scala and Java API) - Add Accept-Query modeled response header with MediaRange list - Add Accept-Query parser supporting RFC 9651 Structured Fields syntax (quoted strings like "application/jsonpath") with q-value stripping - Add query routing directive (Scala DSL and Java DSL) - Add HttpRequest.QUERY factory method (Java API) - Add AcceptQuery Java API abstract class - Register accept-query in HeaderParser dispatch - Add documentation page for query directive with Scala/Java examples - Add directional tests: method lookup, header parsing (token, quoted string, wildcard, q-value stripping), directive routing Result: Downstream consumers can implement RFC 10008 QUERY method support using built-in constants, headers, parsing, and routing directives. Tests: - sbt "http-core / Test / testOnly org.apache.pekko.http.scaladsl.model.HttpMethodsSpec" → 6 passed - sbt "http-core / Test / testOnly org.apache.pekko.http.impl.model.parser.HttpHeaderSpec" → 75 passed - sbt "http-core / Test / testOnly org.apache.pekko.http.scaladsl.model.headers.HeaderSpec" → 18 passed - sbt "http-tests / Test / testOnly org.apache.pekko.http.scaladsl.server.directives.MethodDirectivesSpec" → 14 passed - sbt "docs / Test / testOnly docs.http.scaladsl.server.directives.MethodDirectivesExamplesSpec docs.http.javadsl.server.directives.MethodDirectivesExamplesTest" → 11 passed - sbt "http-core / mimaReportBinaryIssues" → success - sbt "http / mimaReportBinaryIssues" → success References: Refs netty/netty#16978, https://www.rfc-editor.org/rfc/rfc10008
Motivation: Review feedback identified missing directional tests for QUERY method semantics (safe, idempotent, expected entity) and an unused import. Modification: - Add property tests verifying QUERY is safe, idempotent, and expects a request entity per RFC 10008 (goes beyond Netty's test coverage) - Remove unused HttpMethod import from MethodDirectivesSpec Result: Stronger test coverage ensuring RFC 10008 semantics are preserved. Tests: - sbt "http-core / Test / testOnly org.apache.pekko.http.scaladsl.model.HttpMethodsSpec" → 9 passed - sbt "http-tests / Test / testOnly org.apache.pekko.http.scaladsl.server.directives.MethodDirectivesSpec" → 14 passed References: Refs https://www.rfc-editor.org/rfc/rfc10008
Motivation: Accept-Query is a Structured Field in RFC 10008, but the PR reused Accept media-range parsing and rendering in places that could emit invalid field values or treat parameters as Accept weights. Modification: Parse Accept-Query media ranges and parameters with Structured Field token/string rules. Render Accept-Query values with token-or-string selection, preserve valid SF parameters, reject invalid wildcard and decimal-parameter forms, and add focused parser/rendering tests. Add the query directive to the alphabetical docs index and fix Accept-Query RFC section links. Result: Accept-Query parsing and rendering now matches RFC 10008 Section 3 while keeping the parser path lightweight. Tests: - scalafmt --mode diff-ref=origin/main - scalafmt --list --mode diff-ref=origin/main - git diff --check - sbt 'project http-core' 'Test / testOnly org.apache.pekko.http.impl.model.parser.HttpHeaderSpec' - sbt 'project http-core' 'Test / testOnly org.apache.pekko.http.scaladsl.model.headers.HeaderSpec' - sbt 'project http-core' 'Test / testOnly org.apache.pekko.http.scaladsl.model.HttpMethodsSpec' - sbt 'http-tests / Test / testOnly org.apache.pekko.http.scaladsl.server.directives.MethodDirectivesSpec' - sbt docs/paradox References: Refs #1077
pjfanning
reviewed
Jun 19, 2026
Motivation: AcceptQuery.java is a new file with original code, not derived from Akka. It should use the standard ASF license header, not the "derived from Akka" header. Modification: Replace apacheFromAkkaSourceHeader with the standard apacheHeader as defined in CopyrightHeader.scala. Result: AcceptQuery.java carries the correct license header for new contributions. References: Refs #1077
He-Pin
commented
Jun 19, 2026
He-Pin
left a comment
He-Pin
left a comment
Member
Author
There was a problem hiding this comment.
Fixed: AcceptQuery.java now uses the standard ASF license header (apacheHeader) instead of the Akka-derived header (apacheFromAkkaSourceHeader), as this is a new file with original code.
Motivation: `private[this]` is being phased out in Scala 3 and provides no measurable benefit for vals in objects/traits. Modification: Replace `private[this]` with `private` in AcceptHeader.scala (3 vals) and headers.scala (1 val). Result: Cleaner code compatible with Scala 3 conventions. scalafmt applied. Tests: Not run - visibility-only change References: Refs #1077
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
2 participants
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
QUERYHTTP method constant (safe, idempotent, expects request body per RFC 10008) to both Scala and Java APIAccept-Querymodeled response header with enhanced parser supporting RFC 9651 Structured Fields syntax (quoted strings, q-value stripping)queryrouting directive for both Scala DSL and Java DSLHttpRequest.QUERY()factory method for Java APIMotivation
RFC 10008 defines the HTTP
QUERYmethod as a safe and idempotent method that expects a request body, along with theAccept-Queryresponse header. pekko-http should provide first-class support for this standard HTTP method, similar to what Netty did in PR #16978.Modification
Core (http-core)
HttpMethod.scala: AddQUERYtoHttpMethods(safe=true, idempotent=true, requestEntityAcceptance=Expected)HttpMethods.java: AddQUERYconstant to Java APIHttpRequest.java: AddQUERY(String uri)factory methodheaders.scala: AddAccept-Querymodeled response header (Seq[MediaRange])AcceptQuery.java: New Java API abstract classHeaderParser.scala: Registeraccept-queryin dispatchAcceptHeader.scala: Addaccept-queryparser with RFC 9651 Structured Fields support:application/json) and quoted-string ("application/jsonpath") formsRouting (http)
MethodDirectives.scala(scaladsl): AddquerydirectiveMethodDirectives.scala(javadsl): AddquerydirectiveDocumentation (docs)
query.mdpage for the query method directiveTests
HttpMethodsSpec: QUERY method lookupHttpHeaderSpec: Accept-Query parsing (token, quoted string, wildcard, q-value stripping, RFC example)HeaderSpec: Accept-Query renderingMethodDirectivesSpec: query directive routingMethodDirectivesExamplesSpec/MethodDirectivesExamplesTest: doc examplesResult
Downstream consumers can implement RFC 10008 QUERY method support using built-in constants, headers, parsing, and routing directives.
Test plan
sbt "http-core / Test / testOnly org.apache.pekko.http.scaladsl.model.HttpMethodsSpec"→ 6 passedsbt "http-core / Test / testOnly org.apache.pekko.http.impl.model.parser.HttpHeaderSpec"→ 75 passedsbt "http-core / Test / testOnly org.apache.pekko.http.scaladsl.model.headers.HeaderSpec"→ 18 passedsbt "http-tests / Test / testOnly org.apache.pekko.http.scaladsl.server.directives.MethodDirectivesSpec"→ 14 passedsbt "docs / Test / testOnly docs.http.scaladsl.server.directives.MethodDirectivesExamplesSpec docs.http.javadsl.server.directives.MethodDirectivesExamplesTest"→ 11 passedsbt "http-core / mimaReportBinaryIssues"→ successsbt "http / mimaReportBinaryIssues"→ successgit diff --check→ cleanReferences
Refs netty/netty#16978, https://www.rfc-editor.org/rfc/rfc10008
Tests