KNet HTTP/2 Target and Implementation Plan

Status: IMPLEMENTED — LOCAL JVM QUALIFICATION COMPLETE
Current runtime capability: EXPERIMENTAL
Target: production-qualified HTTP/2 proxy interception and API Studio execution without replacing the HTTP/1, traffic, breakpoint, persistence, connectivity, or protocol-inspection architecture.

1. Definition of complete HTTP/2 support

KNet may mark HTTP/2 as SUPPORTED only when all of the following work through real sockets:

Downstream TLS negotiation through ALPN (h2, with HTTP/1.1 fallback).
Clear-text H2C prior knowledge and HTTP/1.1 Upgrade to H2C.
Upstream TLS HTTP/2 negotiation and bounded reusable connection pooling.
Concurrent multiplexed streams with stable connection and stream identities.
HEADERS/CONTINUATION, DATA, SETTINGS, WINDOW_UPDATE, PING, RST_STREAM, GOAWAY, and trailers.
Standards-compliant HPACK handling through Netty's codec.
Per-stream flow control, cancellation, timeout, failure, and body ownership.
HTTP/2-to-HTTP/1 and HTTP/1-to-HTTP/2 translation where either side negotiates a different version.
Request and response breakpoints that pause only the matched stream.
Durable capture, restart-safe paging, filtering, export-ready snapshots, and accurate protocol/source reporting.
API Studio AUTO negotiation and an exact HTTP/2 preference.
Qualification for ordinary HTTP, streaming bodies, SSE, and the HTTP/2 transport required by future gRPC.

Standards-compliant refusal is allowed where the protocol permits it. In particular, KNet will advertise SETTINGS_ENABLE_PUSH = 0 upstream instead of building a server-push product feature. Unknown extension frames must follow RFC handling rules and must never corrupt another stream.

The following are not HTTP/2 implementation failures:

Certificate-pinned clients refusing KNet's interception certificate.
HTTP/3, which uses QUIC and requires its own transport adapter.
Semantic decoding of gRPC or WebSocket messages; HTTP/2 transports their bytes, while protocol inspectors own their meaning.

2. Existing repository foundation

KEEP

:core:traffic canonical request, response, exchange, protocol, origin, body-reference, and StreamId models.
:engine:proxy as the only owner of Netty transport and reference-counted buffers.
The qualified HTTP/1.0/1.1 path (KNetStreamingProxyHandler, KNetOutboundHandler, and HttpOneSemantics).
ProxyCaptureSink and bounded body reservations as the non-blocking capture boundary.
Protocol-neutral application breakpoint contracts and additive semantic extensions.
Room canonical traffic persistence, including its existing streamId, request protocol, response protocol, and origin fields.
Traffic filters, protocol/source presentation, API Studio response inspection, and connectivity mechanisms.
:testingServer as a network-only protocol lab; production modules never depend on it.

MODIFY

Proxy connection setup to negotiate a protocol and select an HTTP/1 or HTTP/2 connection adapter.
TLS contexts to advertise/consume ALPN without moving certificate ownership into the proxy.
Capture exchange admission to accept a nullable StreamId.
Canonical snapshots/events and Room schema to preserve request and response trailers independently.
Breakpoint adaptation so HTTP/2 streams do not enter the ordered HTTP/1 deque.
API Studio HTTP-version preference and JVM transport selection.
Runtime capability maturity and module documentation as qualification gates are passed.

ADD

A small downstream protocol negotiator.
An HTTP/2 connection handler and independently owned per-stream bridge.
HTTP/2 canonical frame/head/trailer mappers.
A bounded upstream HTTP/2 connection pool keyed by authority and TLS policy.
H2C and TLS/ALPN test fixtures, fault injectors, and concurrency/backpressure qualification tests.
Optional Traffic Stream ID presentation and HTTP/2-specific safe diagnostics.

REMOVE

Nothing from the working HTTP/1 path during HTTP/2 development.
Any temporary experimental adapter must be removed before SUPPORTED; two production HTTP/2 paths are not acceptable.

3. Target transport boundaries

TCP connection
    |
    +-- clear text detector ----------------------+-- HTTP/1 connection adapter (existing)
    |                                             |
    |                                             +-- H2C connection adapter (new)
    |
    +-- CONNECT -> KNet TLS -> ALPN --------------+-- HTTP/1 connection adapter (existing)
                                                  |
                                                  +-- HTTP/2 connection adapter (new)

HTTP/2 connection adapter
    |
    +-- connection control owner (SETTINGS/PING/GOAWAY/flow-control budget)
    |
    +-- stream channel N -> HTTP/2 stream bridge
                              |
                              +-- canonical request + StreamId
                              +-- optional per-stream breakpoint gate
                              +-- bounded capture reservations
                              +-- upstream route/stream
                              +-- canonical response/trailers/terminal state

The connection owner handles only connection-scoped frames and budgets. Each stream bridge owns exactly one logical exchange. No connection-wide activeRequest, ordered response queue, or mutable body accumulator is shared by HTTP/2 streams.

4. Runtime flow

TLS interception

The existing HTTP/1 proxy receives CONNECT and resolves KNet's per-host certificate asynchronously.
The downstream server TLS context advertises h2 and http/1.1 through ALPN.
After the handshake, a protocol negotiator installs either the existing HTTP/1 pipeline or the new HTTP/2 frame/multiplex pipeline.
Every HTTP/2 child stream receives its own stream bridge and canonical StreamId.
The upstream route negotiates ALPN independently. Therefore Traffic can truthfully show, for example, Client HTTP/2 and Upstream HTTP/1.1.

Clear-text interception

Detect the HTTP/2 connection preface without consuming bytes irreversibly.
Install the H2C pipeline for prior knowledge.
Preserve the existing HTTP/1 path and support a valid H2C Upgrade transition.
Invalid prefaces/upgrades fail the connection safely without affecting the listener.

Per-stream forwarding

Validate pseudo-headers, forbidden connection headers, limits, and stream state.
Convert the initial header block to canonical RequestHead with ApplicationProtocol.HTTP_2.
Admit capture with connection ID, stream ID, source, and start time.
Evaluate request breakpoint policy for that stream only.
Forward DATA only as downstream/upstream flow-control credit and writability allow.
Map response headers, DATA, and trailers to the same exchange.
Publish exactly one terminal exchange state for normal completion, reset, timeout, GOAWAY, or connection loss.

5. Memory, concurrency, and backpressure rules

Netty owns inbound frame buffers until a stream bridge explicitly retains or copies them.
Capture may copy only bytes admitted by ProxyBodyReservation; capture rejection never blocks forwarding.
Each stream has a small bounded pending-write queue and the connection has a stricter aggregate byte budget.
A slow stream must not stop reads for unrelated streams while connection-level flow-control credit remains.
WINDOW_UPDATE is released only after the next owner has accepted the bytes, not immediately upon decoding.
Breakpoint aggregation is bounded per selected stream. Unmatched streams remain fully streaming.
Pausing a matched stream must not pause its event-loop connection or another stream.
RST_STREAM releases that stream's queued frames, reservations, breakpoint ownership, and upstream mapping.
GOAWAY stops new stream admission, lets eligible existing streams drain, and deterministically fails streams that the peer has declared unprocessed.
Connection-pool count, streams per connection, header-list size, frame size, idle time, and pending bytes are explicit runtime-policy values with safe defaults.

6. Canonical traffic and persistence changes

:core:traffic remains the source of truth.

Keep request and response protocols independent.
Normalize equivalent observed tokens such as HTTP/2.0 to canonical HTTP/2.
Pass StreamId? through ProxyConnectionCapture.startExchange into CaptureEvent.ExchangeStarted.
Add explicit request/response trailer values and trailer capture events; do not merge trailers into initial headers.
Keep HTTP/2 pseudo-headers out of ordinary header lists after mapping them to method, scheme, authority, path, and status.
Preserve ordered duplicate ordinary headers after HPACK decoding.

Room schema v22 will add dedicated encoded request/response trailer columns. Existing rows default to no trailers; the existing stream ID and two protocol columns require no redesign. :data:desktop remains the only mapper and writer.

7. Breakpoint behavior

Reuse BreakpointGate, BreakpointCandidate, typed edits, and protocol extensions.
Add an HTTP/2 adapter that converts one stream's canonical data into the existing candidate contract.
Keep raw HTTP/2 frames inside Netty's connection/stream codecs. Each isolated stream child converts its frames to the existing HTTP-object breakpoint adapter; the adapter therefore remains protocol-neutral at the application boundary while stream ownership stays independent.
A request breakpoint pauses that stream before its end-of-stream is forwarded.
A response breakpoint pauses only the selected response stream after bounded aggregation.
Forwarded edits rebuild valid HTTP/2 header/trailer blocks and recalculate body metadata where necessary.
Dropping an interception sends the appropriate RST_STREAM; it does not close the entire connection.
Disabling/editing rules continues to affect the next eligible stream without pipeline mutation or reconnect.

GraphQL matching remains unchanged because it consumes canonical requests. Future gRPC matching will be another protocol extension, not a branch in the HTTP/2 transport.

8. API Studio behavior

Add HTTP_2 to HttpVersionPreference, persistence, editor selection, and request handoff.
Keep CIO for exact HTTP/1.1 and custom test engines.
Use one JVM HTTP/2-capable client adapter behind DomainHttpExecutor; the adapter supports ALPN, local proxy trust, cancellation, streaming, and observed-version reporting.
AUTO may negotiate/fallback according to server capability.
Exact HTTP_2 must fail clearly when HTTP/2 cannot be negotiated; silently reporting HTTP/1.1 is incorrect.
API Studio attribution remains local to the KNet proxy hop.
The response summary reports the actually negotiated protocol, while a captured Traffic exchange reports both client-facing and upstream protocol legs.

9. UI behavior

Existing HTTP/2 count/filter becomes active from canonical data; no UI-side inference.
Protocol and Source optional Traffic columns continue to use the common column system.
Add an optional Stream column rather than embedding stream IDs into serial numbers or paths.
Overview shows connection ID, stream ID, client protocol, upstream protocol, and source.
Live Intercept shows client/upstream protocol and source using the canonical candidate already supplied.
RST_STREAM/GOAWAY/timeouts use stable safe diagnostics; raw exceptions and frame dumps are not presentation models.
No HTTP/2-specific branch is added to GraphQL/SSE inspectors or the code editor.

10. Implementation phases and gates

Phase H2-0 — Baseline and fixtures

Status: COMPLETE — 2026-08-21

Freeze passing HTTP/1 regression, capacity, breakpoint, capture, and TLS suites.
Extend :testingServer with deterministic TLS/ALPN HTTP/2 in addition to its verified H2C listener.
Add raw/fault fixtures for resets, GOAWAY, trailers, large header blocks, slow streams, and interleaved data.

Exit gate: the lab proves H2C and TLS h2 negotiation independently of KNet.

Verified by the complete :testingServer:test contract and the existing certificate, interceptor, proxy, HTTP-client, and desktop persistence regression suites. No production proxy pipeline changed in this phase.