Merge TASK-195: Serve public HTTP2 streams through native listeners

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