TASK-195: Serve native HTTP/2 with independent stream execution

Compose negotiated TLS H2 with bounded wire/stream affinities, hierarchical budgets, exact body credit, common routing and policy, deadlines, RFC8441, and native staged drain. Repair the shared H1 disconnect publication race exposed by parity verification.

Verify 76 TLS-on and 20 TLS-off suites in normal, ASan/UBSan and TSan; all shared/static managed/external public matrices with both pinned clients; installed package parity; 145 required h2spec cases; local headers, docs, linkage, lint and distribution checks. Preserve causal failures and exact evidence in TASK-195-receipt.json and the task-local handoff.

Author: etr

.gitignore

@@ -142,3 +142,5 @@ __pycache__/
 !test/integ/native_websocket_regression.py
 
 !scripts/check-v3-public-tls.py
+!scripts/check-v3-public-http2.py
+!scripts/test-v3-public-http2.py

Makefile.am

@@ -561,3 +561,8 @@ EXTRA_DIST += scripts/audit-v3-native-linkage.sh scripts/test-v3-cutover.py scri
 EXTRA_DIST += scripts/check-v3-public-tls.py test/installed/v3_tls_consumer.cpp
 
 EXTRA_DIST += scripts/lib/v3_public_tls_profiles.py test/installed/v3_tls_profiles.cpp test/installed/v3_tls_client.cpp
+EXTRA_DIST += scripts/check-v3-public-http2.py scripts/test-v3-public-http2.py \
+    scripts/lib/v3_public_http2_inventory.py scripts/lib/v3_public_http2_h2.py scripts/lib/v3_public_http2_policy.py \
+    test/installed/v3_http2_consumer.cpp test/installed/v3_http2_node.mjs test/installed/v3_http2_raw.mjs \
+    examples/v3_http2.cpp specs/architecture/v3/TASK-195-design.md \
+    specs/architecture/v3/TASK-195-implementation-evidence.md specs/architecture/v3/TASK-195-receipt.json

docs/native-tls-build.md

@@ -27,8 +27,9 @@ cross builds must run the smoke on the target in CI.
 `<httpserver/features.hpp>` exposes the same compiled `query_features()` declaration
 in both builds, without backend headers or configuration macros. Availability of
 the provider is distinct from availability of TCP TLS, HTTP/2, and HTTP/3. TCP TLS is available in TLS-on builds for certificate, initial mTLS and eligible
-external-PSK HTTP/1.0 and HTTP/1.1 in both managed and external modes. HTTP/2 and HTTP/3 remain
-unavailable until their owning tasks implement public listeners. `listen()`
+external-PSK HTTP/1.0 and HTTP/1.1 in both managed and external modes. Certificate
+and initial mTLS profiles also serve enabled HTTP/2 through TLS ALPN `h2`.
+HTTP/3 public listeners remain unavailable. `listen()`
 rejects unsupported protocol/profile requests before binding;
 `server_options::validate()` remains semantic.
 
@@ -139,8 +140,10 @@ through retiring I/O completions. No global credential store exists.
 Host names use exact canonical DNS matching, with case folding and a final dot
 removed. Unknown or absent SNI selects `default_host` (zero by default). Each
 listener has its own explicit store; sharing is intentional only when the same
-store is assigned. ALPN may contain `http/1.1` or be empty for ordinary HTTP/1
-fallback. A listener with HTTP/1.1 disabled must initially use empty ALPN. Later
+store is assigned. Certificate and initial mTLS ALPN may contain `h2`,
+`http/1.1`, or both; empty ALPN selects ordinary HTTP/1 fallback. An advertised
+protocol must be enabled in every listener bound to the credential store. PSK
+profiles retain HTTP/1-only ALPN and reject `h2`. Later
 publication cannot negotiate a disabled ALPN; wire requests for a disabled H1
 version are rejected before routing. `exchange::tls()` and request hook contexts
 carry library-owned immutable authenticated peer metadata; plaintext uses null,
@@ -251,3 +254,25 @@ example takes `certificate-directory managed|external port`, opens a real public
 listener and accepts `replace`, `invalid` and `stop` on stdin. Its independent
 installed witness holds a usable connection across rotation and validates the
 new certificate plus rejected-publication preservation.
+
+Public HTTP/2 uses the same native server, route table, hooks, peer policy and
+exchange API as HTTP/1. See [the public example](../examples/v3_http2.cpp) and
+[TASK-195 design](../specs/architecture/v3/TASK-195-design.md). TLS-off
+configuration rejects HTTP/2 before binding. TLS 1.2 HTTP/2 rejects forbidden
+ciphers before publishing request hooks.
+
+Connection wire operations run serially; each stream has its own handler
+affinity on the configured workers. A running handler can occupy one worker,
+so applications should keep handlers cooperative and size the worker pool for
+their concurrent work. Receive credit follows body consumption. Configured
+server limits bound listener, connection and stream descendants, including
+header copies, body rings, output and WebSocket storage. Header, SETTINGS,
+body-idle, suspension, write-idle, WebSocket close and drain timers use native
+readiness deadlines without periodic polling.
+
+RFC8441 Extended CONNECT upgrades one stream and permits ordinary siblings.
+Native drain publishes staged GOAWAY, finishes accepted work, and cancels
+remaining requests and WebSockets at its absolute deadline. A retained ticket
+keeps the original deadline result; its remaining count describes unfinished
+work at expiry, even after actual retirement. A counted handler cannot wait
+on its own drain ticket.

docs/v3-api.md

@@ -12,7 +12,9 @@ selection, budgets, timeouts, worker concurrency and loop ownership.
 \ref httpserver::server::native_server validates before binding and owns shutdown.
 Plaintext HTTP/1.0 and HTTP/1.1 listeners are available. TLS-on builds also serve
 public HTTP/1 certificate, initial mTLS and eligible external-PSK listeners.
-Public H2/H3 listeners still return not_supported before binding.
+Certificate and initial mTLS listeners also serve HTTP/2 when enabled and negotiated
+with TLS ALPN `h2`. HTTP/3 listeners still return not_supported before binding.
+HTTP/2 has no cleartext upgrade or prior-knowledge listener.
 Provider availability from \ref httpserver::query_features is a separate fact.
 
 \include v3_protocol_options.cpp

examples/README.md

@@ -207,3 +207,16 @@ empty.
 
 Thanks to https://devcenter.heroku.com/articles/ssl-certificate-self
 for these instructions.
+
+`v3_http2.cpp` serves `/hello` through one certificate listener and one route
+table for HTTP/1.1 and HTTP/2. Build against the installed package:
+
+```sh
+c++ -std=c++20 v3_http2.cpp $(pkg-config --cflags --libs libhttpserver) -pthread -o v3_http2
+./v3_http2 a-chain.pem a-key.pem
+```
+
+The example prints its loopback port and stops when stdin receives a line.
+The certificate chain must identify `a.example`; clients should verify its CA
+and SNI. HTTP/2 requires a TLS-on build. The installed H2 matrix compiles and
+runs this example with both shared and static linkage.

examples/v3_http2.cpp

@@ -0,0 +1,38 @@
+/* Copyright (C) 2026 Sebastiano Merlino; SPDX-License-Identifier: LGPL-2.1-or-later */
+#include <fstream>
+#include <iostream>
+#include <memory>
+#include <string>
+#include <httpserver.hpp>
+#include <httpserver/server/tls_credentials.hpp>
+
+namespace srv = httpserver::server;
+namespace http = httpserver::http;
+
+std::string read_pem(const char* path) {
+    std::ifstream input(path);
+    return {std::istreambuf_iterator<char>(input), {}};
+}
+
+int main(int argc, char** argv) {
+    if (argc != 3) return 2;
+    auto credentials = std::make_shared<srv::tls_credentials>();
+    srv::tls_host_credentials host{"a.example", read_pem(argv[1]), read_pem(argv[2]), {"h2", "http/1.1"}};
+    if (!credentials->replace({{host}, 0}).ok()) return 1;
+    srv::server_options options;
+    options.protocols().enable(http::protocol::http_2);
+    options.tls().provider = srv::tls_provider::system_default;
+    options.tls().profile = srv::tls_profile::certificates;
+    options.add_listener({"127.0.0.1", 0, true, credentials});
+    srv::native_server server(options);
+    if (!server.route(http::method::known(http::method_id::get), "/hello", [](httpserver::exchange& x) -> httpserver::task<void> {
+        x.start_response(http::status::from_code(200), {});
+        const std::string text = "hello h2\n";
+        co_await x.writer().write(std::as_bytes(std::span(text)));
+        co_await x.writer().finish();
+    }).ok() || !server.listen().ok()) return 1;
+    std::cout << server.get_bound_port(0) << std::endl;
+    std::string command;
+    std::getline(std::cin, command);
+    server.stop();
+}

scripts/check-v3-installed-consumer.py

@@ -102,6 +102,9 @@ def package_lane(args, source, output, mode, inventory):
     command([sys.executable, str(source / 'scripts/check-v3-public-tls.py'), '--prefix', str(prefix),
              '--provider-prefix', str(args.provider_prefix), '--build', str(build), '--tls', mode,
              '--compiler', args.compiler, '--output', str(lane / 'public-tls')], source, runtime_env)
+    command([args.client_python, str(source / 'scripts/check-v3-public-http2.py'), '--prefix', str(prefix),
+             '--provider-prefix', str(args.provider_prefix), '--build', str(build), '--tls', mode,
+             '--compiler', args.compiler, '--node', args.node, '--output', str(lane / 'public-http2')], source, runtime_env)
     receipt = audit.audit(prefix, build, consumer_dir / ('v3_package_consumer' + suffix), mode,
                           'strict', args.provider_prefix, args.compiler)
     receipt.update(consumer_metadata=metadata, public=public, integrations=integrations)
@@ -122,6 +125,8 @@ def main():
     parser.add_argument('--jobs', type=int, default=2)
     parser.add_argument('--compiler', default='c++')
     parser.add_argument('--cc', default='cc')
+    parser.add_argument('--client-python', default=sys.executable)
+    parser.add_argument('--node', default='node')
     parser.add_argument('--make', default='make')
     args = parser.parse_args()
     source = Path(__file__).resolve().parent.parent