docs: modernize HTTP/2 ALPN and h2c guidance - #1253
Open
samueleresca wants to merge 1 commit into
Open
Conversation
Motivation: The HTTP/2 server-side doc still described ALPN as requiring separate negotiation setup and documented a JDK <= 9 fallback where curl could not determine h2 support, plus it presented the HTTP/1.1 h2c Upgrade mechanism without noting it is now obsolete per RFC 9113. Apache Pekko HTTP's minimum supported JDK has since moved to 17, where ALPN is natively part of JSSE and the RFC 7540 Upgrade path has been superseded. Modification: Reword the ALPN section to state it needs no extra provider or boot classpath configuration on supported JDKs, and link to RFC 7301/RFC 9113 instead of RFC 7540. Add a warning that h2c Upgrade is obsolete in RFC 9113 and should only be used for older-client compatibility, rename the "h2c with prior knowledge" section to "Cleartext HTTP/2 with prior knowledge", and drop the outdated JDK <= 9 curl fallback example that no longer applies on the project's supported JDKs. Result: The doc reflects the project's current JDK baseline and RFC 9113 guidance without the stale JDK <= 9 ALPN caveat or unlabeled deprecated h2c Upgrade mechanism. Tests: Not run - docs only References: None - documentation accuracy update
pjfanning
reviewed
Aug 30, 2026
| have [Prior Knowledge](https://httpwg.org/specs/rfc7540.html#known-http) of | ||
| HTTP/2 support. | ||
| Apache Pekko HTTP supports starting a cleartext HTTP/2 connection with | ||
| [prior knowledge](https://www.rfc-editor.org/rfc/rfc9113.html#section-3.3). For compatibility with older clients, it |
Member
There was a problem hiding this comment.
can you keep this as Prior Knowledge - commonly referred to in this form - https://www.google.com/search?q=prior+knowledge+http
pjfanning
reviewed
Aug 30, 2026
|
|
||
| The HTTP/1.1 Upgrade mechanism and the `h2c` upgrade token are obsolete in | ||
| [RFC 9113](https://www.rfc-editor.org/rfc/rfc9113.html#section-11.2). Use this mode only when compatibility with an | ||
| older client requires it. New cleartext HTTP/2 clients should use prior knowledge. |
Member
There was a problem hiding this comment.
same point about Prior Knowledge
pjfanning
reviewed
Aug 30, 2026
| to HTTP/2 before sending your first 'real' request, at the cost of a roundtrip. | ||
|
|
||
| #### h2c with prior knowledge | ||
| #### Cleartext HTTP/2 with prior knowledge |
Member
There was a problem hiding this comment.
Again, I'd prefer Prior Knowledge especially as this is a header and most words in a header are typically started with Caps - 'with' would usually be left as lowercase
pjfanning
reviewed
Aug 30, 2026
| [Prior Knowledge](https://httpwg.org/specs/rfc7540.html#known-http) of HTTP/2 | ||
| support. | ||
| For this reason the approach is known as HTTP/2 with | ||
| [prior knowledge](https://www.rfc-editor.org/rfc/rfc9113.html#section-3.3). |
Member
There was a problem hiding this comment.
same issue with Prior Knowledge
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.
Motivation:
The HTTP/2 server-side doc still described ALPN as requiring separate negotiation setup and documented a JDK <= 9 fallback where curl could not determine h2 support, plus it presented the HTTP/1.1 h2c Upgrade mechanism without noting it is now obsolete per RFC 9113. Apache Pekko HTTP's minimum supported JDK has since moved to 17, where ALPN is natively part of JSSE and the RFC 7540 Upgrade path has been superseded.
Modification:
Reword the ALPN section to state it needs no extra provider or boot classpath configuration on supported JDKs, and link to RFC 7301/RFC 9113 instead of RFC 7540. Add a warning that h2c Upgrade is obsolete in RFC 9113 and should only be used for older-client compatibility, rename the "h2c with prior knowledge" section to "Cleartext HTTP/2 with prior knowledge", and drop the outdated JDK <= 9 curl fallback example that no longer applies on the project's supported JDKs.
Result:
The doc reflects the project's current JDK baseline and RFC 9113 guidance without the stale JDK <= 9 ALPN caveat or unlabeled deprecated h2c Upgrade mechanism.
Tests:
Not run - docs only
References:
None - documentation accuracy update