apache / apache/pekko-http

Support WebSockets over HTTP/2 via RFC 8441 Extended CONNECT

Open
#1,112 1 comment 1 reaction 0 assignees View on GitHub
Dominant language
Scala
Stars
196
Forks
55
Avg merge
4d 52m
Merged PRs (30d)
74

Description

## Problem

Pekko HTTP supports HTTP/2 and WebSockets, but WebSocket support currently appears to be limited to the classic HTTP/1.1 upgrade handshake.

RFC 8441 defines how to bootstrap WebSockets over HTTP/2 using Extended CONNECT:

- server advertises `SETTINGS_ENABLE_CONNECT_PROTOCOL = 1`
- client sends `:method = CONNECT`
- client sends `:protocol = websocket`
- request also includes `:scheme`, `:path`, and `:authority`
- server accepts with `:status = 200`
- WebSocket frames are then carried over the HTTP/2 stream

This would allow applications to serve HTTP/2 requests and WebSockets on the same HTTP/2 connection instead of falling back to a separate HTTP/1.1 WebSocket upgrade connection.

RFC: https://www.rfc-editor.org/rfc/rfc8441.html

## Current Behavior

Pekko HTTP WebSocket handling is based on the HTTP/1.1 upgrade model:

- request validation expects `Upgrade: websocket`, `Connection: Upgrade`, `Sec-WebSocket-Key`, and `Sec-WebSocket-Version`
- accepted WebSockets return `101 Switching Protocols`
- the existing `WebSocketUpgrade` API represents upgrading the connection to WebSocket

That matches RFC 6455 over HTTP/1.1, but not RFC 8441 over HTTP/2.

## Expected Behavior

When HTTP/2 is enabled, Pekko HTTP should optionally support RFC 8441 WebSockets over HTTP/2.

At a high level this likely means:

- advertise `SETTINGS_ENABLE_CONNECT_PROTOCOL = 1` when server-side support is enabled
- accept HTTP/2 Extended CONNECT requests with `:protocol = websocket`
- expose those requests to routing / low-level APIs similarly to existing WebSocket upgrade requests
- allow existing `handleWebSocketMessages` / `WebSocketUpgrade` style APIs to work where practical
- respond with HTTP/2 `:status = 200` when the WebSocket is accepted
- connect the existing WebSocket frame/message stack to the HTTP/2 stream DATA flow
- map HTTP/2 stream end/reset/failure semantics sensibly to WebSocket close behavior

## Motivation

Modern browsers support WebSockets over HTTP/2 via RFC 8441. Supporting this in Pekko HTTP would allow one server port and one HTTP/2 connection to handle both normal HTTP traffic and WebSockets.

This is useful for frameworks built on Pekko HTTP as well. For example, Play Framework can enable HTTP/2 on its Pekko HTTP backend, but WebSocket support still depends on the HTTP/1.1 upgrade path because Pekko HTTP does not currently expose RFC 8441 WebSocket support.

## Notes

Netty has already added several low-level RFC 8441 building blocks, but still tracks high-level WebSocket-over-HTTP/2 support as an open feature request:

- https://github.com/netty/netty/issues/8011
- https://github.com/netty/netty/issues/12352
- https://github.com/netty/netty/pull/11192
- https://github.com/netty/netty/pull/14995
- https://github.com/netty/netty/pull/15312
- https://github.com/netty/netty/pull/16932

A third-party Netty implementation also exists:

- https://github.com/jauntsdn/netty-websocket-http2

## Questions

- Would the Pekko HTTP project be open to RFC 8441 server-side support?
- Should this be implemented behind an explicit config flag, for example under `pekko.http.server.websocket` or `pekko.http.server.http2`?
- Should the existing `WebSocketUpgrade` API be reused for HTTP/2 Extended CONNECT, or should there be a separate API to distinguish HTTP/1.1 upgrade from HTTP/2 stream-based WebSocket bootstrap?

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the existing WebSocketUpgrade and handleWebSocketMessages APIs, then trace the HTTP/2 handling against RFC 8441. Define how SETTINGS_ENABLE_CONNECT_PROTOCOL, Extended CONNECT, HTTP/2 status 200, frame flow, and stream termination should integrate with the existing WebSocket message stack. Done means an agreed API and server-side behavior, with coverage for accepted and terminated HTTP/2 WebSocket streams.

Written by the indexing model from the issue text.

Assessment

Tech stack
scala
Domain
api, backend, networking
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.