Merge FEATURE-v3-protocol-limits: typed capacities and effective inspection

Author: etr

Makefile.am

@@ -618,3 +618,5 @@ check-v3-compiled-operations: $(top_builddir)/src/libhttpserver.la
 	python3 $(top_srcdir)/scripts/check-v3-compiled-operations.py $(top_builddir)/src/.libs/libhttpserver.a
 
 .PHONY: check-v3-compiled-operations
+
+EXTRA_DIST += docs/v3-protocol-limits.md scripts/check-v3-protocol-limits.py test/installed/v3_protocol_limits_consumer.cpp

docs/native-tls-build.md

@@ -287,3 +287,7 @@ shared/static consumers in managed/external modes. Supported TLS/H2/UDP-H3
 configurations bind and complete exchanges; missing credentials and invalid
 configurations retain their separate pre-bind rejection checks. Historical
 TASK-179 and TASK-182 records describe their original execution boundaries.
+
+Protocol capacity `resolve_limits()` adds build availability to semantic
+`validate()`; native `effective_limits()` reads the cached startup policy without
+requiring published credentials. See [capacity policy](v3-protocol-limits.md).

docs/v3-api.md

@@ -138,3 +138,15 @@ live application charges return to baseline.
 
 See `examples/v3_http3.cpp` for one route registry serving TCP H1/H2 and UDP H3,
 with an RFC9220 echo route and either loop mode.
+
+## Protocol capacity policy
+
+`server_options::http2()`, `http3()` and `quic()` expose independent optional
+value profiles from `<httpserver/server/protocol_limits.hpp>`.
+`resolve_limits(effective_protocol_limits&) const` is pure and build-aware;
+`validate()` remains semantic-only. `native_server::effective_limits(...) const`
+returns the immutable local startup policy before listen and after stop. Both
+output methods preserve output on failure. Shared budgets remain authoritative.
+See [native protocol capacities](v3-protocol-limits.md) for defaults, bounds,
+compression/retention envelopes and the distinction between enforcement, initial
+advertisement and peer-bounded encoder use.

docs/v3-protocol-limits.md

@@ -0,0 +1,147 @@
+# Native protocol capacities
+
+Include `<httpserver/server/protocol_limits.hpp>` directly, or use
+`<httpserver/server/configuration.hpp>`. `server_options::http2()`, `http3()`
+and `quic()` each return mutable/const references to an optional value profile.
+A missing profile keeps the existing native derivation. A present profile,
+including an empty one, requests explicit capacity validation. Individual unset
+members retain their defaults.
+
+```cpp
+httpserver::server::server_options options;
+// Configure TLS, credentials, enabled protocols and matching listeners first.
+options.budgets().set(httpserver::server::resource::header_fields, 4096);
+options.budgets().set(httpserver::server::resource::quic_reassembly_bytes,
+                      16 * 1024 * 1024);
+options.http2().emplace().max_concurrent_requests = 192;
+options.http2()->decoder_table_bytes = 8192;
+options.http2()->encoder_table_bytes = 16384;
+options.http3().emplace().max_concurrent_requests = 24;
+options.http3()->max_blocked_headers = 32;
+options.quic().emplace().max_stream_records = 96;
+httpserver::server::effective_protocol_limits limits;
+auto result = options.resolve_limits(limits);
+if (result.ok()) {
+    httpserver::server::native_server server(options);
+    result = server.effective_limits(limits);
+}
+```
+
+`header_capacity_options` holds `max_compressed_bytes`, `max_expanded_bytes`
+and `max_fields`, all optional `std::size_t` values. H2/H3 profiles contain
+`headers`, `max_concurrent_requests`, `decoder_table_bytes` and
+`encoder_table_bytes`. H3 additionally contains `max_blocked_headers` and
+`max_retained_header_bytes`. QUIC contains `max_stream_records`.
+
+`resolve_limits(effective_protocol_limits&) const` performs semantic and storage
+planning, then checks compiled protocol/provider availability. It performs no I/O,
+credential acquisition, reservations, environment reads, binds or worker startup.
+`validate()` runs the same semantic/storage planner without the build availability
+gate; a valid TLS configuration can therefore validate in a TLS-off build while
+resolution returns `not_supported`. Startup completes those checks before binding
+any endpoint, then checks credentials/backend readiness.
+
+`native_server::effective_limits(effective_protocol_limits&) const` reads the
+immutable plan resolved from the server's copied options. It works before listen,
+while serving or draining, after a failed listen, and after stop. Credential
+publication/replacement and mutations of the original options cannot change that
+report. Both methods leave the entire output unchanged on failure. Inspection is
+local startup policy; it does not inspect live connections or imply a successful
+handshake. Managed and external loops use the same plan.
+
+H2 applies to enabled H2 with a TLS TCP listener. H3 and QUIC apply to enabled H3
+with an explicit TLS UDP listener. Inapplicable effective sections are absent.
+A present profile for an inapplicable/disabled protocol fails `invalid_argument`.
+Unsupported compiled transports fail build-aware resolution/startup with
+`not_supported`. An unused TLS provider selection leaves plaintext HTTP/1 available. Existing TLS profile/transport rules still apply.
+
+## Defaults and bounds
+
+| Capacity | Unset native policy |
+| --- | --- |
+| H2 concurrent requests | `min(128, streams budget)` |
+| H2 compressed header bytes | `min(65536, body_buffer_bytes / 16)` |
+| H2 expanded header bytes | `min(65536, header_bytes / 3)` |
+| H2 fields | `min(256, header_fields budget)` |
+| H2 decoder/encoder table bytes | 4096 each |
+| H3 concurrent requests | `min(16, streams budget)` |
+| H3 compressed/expanded bytes/fields | 8192 / 16384 / 128 |
+| H3 decoder/encoder table bytes | `min(4096, qpack_table_bytes budget)` each |
+| H3 blocked headers | `min(8, blocked_headers budget)` |
+| H3 retained compressed HEADERS bytes | 65536 |
+| QUIC retained stream records | 64 |
+| Initial QUIC bidi/uni stream credit | H3 request ceiling / 8 |
+| Advertised/native send datagram bytes | 1200 / 1200 |
+
+Positive explicit request ceilings must fit the aggregate stream budget. H2's
+ceiling is 1,048,576; the historical128 is a default. H3 requests must also fit the
+retained ledger alongside three local and three peer control/QPACK roles. The
+ledger range is7..65,536; its actual prepaid storage can impose a smaller limit.
+Explicit H3 policy needs at least four aggregate stream seats for three peer
+critical roles and one request. Uni credit8 also permits unknown stream types;
+those records compete with requests and terminal records for the same ledger.
+
+Header bytes and fields must be positive. H2 expanded bytes fit three copies in
+`header_bytes`; H3 needs five aggregate header-byte charges and an additional
+semantic field seat (`max_fields + 1`). Field resource maxima are65,536 for H2
+and65,535 for H3, subject to the configured budget. H2 compressed bytes fit the
+body-buffer budget after native owner, frame and one stream descriptor workspace. H3 compressed/decoded metadata, retained HEADERS, semantic
+copies, body/response buffers and descriptor arrays must fit its private prepaid
+workspace. At least one maximum compressed section must fit retained HEADERS.
+All arithmetic and wire conversions are checked; errors identify the field or
+storage/budget relationship. Explicit values are rejected instead of clamped.
+
+Compression tables permit zero, with a resource maximum16,777,216 bytes. Both
+local directions must fit the same aggregate compression budget for an explicit
+policy. H2 includes `max(4096, decoder_table_bytes) + encoder_table_bytes`, because
+a reduced advertised decoder maximum becomes enforceable after SETTINGS ACK.
+The initial4096 allowance is reported separately as
+`effective_http2_limits::pre_ack_decoder_table_bytes`. Zero H2 encoder capacity
+emits the required table-size update. See [RFC9113 §4.3.1](https://www.rfc-editor.org/rfc/rfc9113.html#section-4.3.1).
+
+H3 uses `decoder_table_bytes + encoder_table_bytes`. Decoder zero with a positive
+encoder reserves its output workspace; both zero still support static/literal
+sections without dynamic inserts. Blocked-header ceilings permit zero and are
+bounded by the aggregate blocked-header budget (maximum65,536). They are
+independent of request/record ceilings. Encoder ceilings in both protocols are
+local limits: actual use is additionally bounded by the peer's SETTINGS. See
+[RFC9204 §§3.2.3,5,7.3](https://www.rfc-editor.org/rfc/rfc9204.html).
+
+Private H3 data/critical subdivisions grow for explicit policy when the root
+reassembly budget permits. Planning includes the retained flow ledger, native
+transport/framing descriptors, bridge records and scratch/receipt/information
+arrays, decoded fields, semantic copies, compression instruction/output work,
+recovery metadata/payload, queued datagrams, TLS/CRYPTO and critical roles. The
+UDP listener's131072-byte charge remains outside that prepaid envelope. Runtime
+subdivision reservations stop at the prepaid boundary; semantic resources still
+reach the shared ancestors. Completely unset policy preserves its old subdivision
+`min(393216, floor(quic_reassembly_bytes * 3 / 8))` for each pool and retains its
+existing runtime pressure behavior.
+
+A successful resolution proves a bounded structural envelope and space for one
+maximum request alongside persistent records and critical state. It does not
+reserve all concurrent requests at their largest allowed sizes. Connections and
+streams still compete for shared budgets and can encounter ordinary resource
+refusal without changing the report.
+
+## Enforcement, advertisement and retention
+
+The report includes aggregate `budgets`, optional `http2`, `http3` and `quic`
+sections, and nested `initial_advertisement` values. H2 advertises the resolved
+request/decoder ceilings; H3 advertises its decoder/blocked ceilings and QUIC
+advertises initial request credit. Neither protocol advertises a header-list or
+field-section byte maximum. `max_header_list_bytes` and
+`max_field_section_bytes` remain absent even with explicit local header limits.
+Expanded size includes name/value bytes and32 bytes per field, as described in
+[RFC9114 §4.2.2](https://www.rfc-editor.org/rfc/rfc9114.html#section-4.2.2).
+
+Normal request retirement replenishes QUIC MAX_STREAMS credit. Initial credit is
+not a lifetime request count. Terminal descriptors remain retained to prevent
+stream recreation; eventually the total record ledger is authoritative. Larger
+ledgers support more retirements while keeping this bound. See
+[RFC9000 §§4.6,18.2](https://www.rfc-editor.org/rfc/rfc9000.html).
+
+The inspected QUIC datagram values are fixed read-only implementation policy.
+There is no datagram-size setter, PMTU growth or new key-update behavior here.
+Existing per-key usage guards remain in force; this API makes no promise about
+graceful connection-local key exhaustion.

docs/v3-source-layout.md

@@ -354,6 +354,11 @@ Windows execution belongs to CI/the v3 PR.
 |---|---|---|
 | `src/detail/connection_engine_config.cpp` | `src/httpserver/detail/connection_engine.hpp` | Compiled operations extracted without algorithm changes |
 | `src/detail/io_poll_backend_timers.cpp` | `src/httpserver/detail/io_poll_backend.hpp`, `src/httpserver/detail/io_timer_sweep.hpp` | Compiled operations extracted without algorithm changes |
+| `src/httpserver/server/protocol_limits.hpp` | `src/httpserver/server/protocol_limits.hpp` | Installed capacity option/report value types; implementation in public options/server units |
+| `src/httpserver/detail/protocol_limits.hpp` | `src/httpserver/detail/protocol_limits.hpp` | Private immutable plan and planning declarations |
+| `src/detail/protocol_limits.cpp` | `src/httpserver/detail/protocol_limits.hpp` | Common semantic capacity resolution and compiled availability |
+| `src/detail/http3_capacity.cpp` | `src/httpserver/detail/protocol_limits.hpp` | Pure prepaid H3/QUIC envelope using owner accounting helpers |
+| `src/httpserver/detail/capacity_math.hpp` | `src/httpserver/detail/capacity_math.hpp` | Private checked arithmetic primitives |
 
 ## Retained inline definitions
 
@@ -1033,3 +1038,8 @@ operation, including true templates and constant evaluation operations.
 | `src/httpserver/detail/websocket_session_state.hpp` | `httpserver::websocket::detail::session_wait::bind_frame(httpserver::detail::task_frame_base *)` | trivial accessor/value operation |
 | `src/httpserver/detail/websocket_session_state.hpp` | `httpserver::websocket::detail::session_wait::await_ready()` | trivial accessor/value operation |
 | `src/httpserver/detail/websocket_session_state.hpp` | `httpserver::websocket::detail::session_wait::await_resume()` | trivial accessor/value operation |
+| `src/httpserver/server/options.hpp` | `httpserver::server::server_options::http2()` (mutable/const) | trivial accessor/value operation |
+| `src/httpserver/server/options.hpp` | `httpserver::server::server_options::http3()` (mutable/const) | trivial accessor/value operation |
+| `src/httpserver/server/options.hpp` | `httpserver::server::server_options::quic()` (mutable/const) | trivial accessor/value operation |
+| `src/httpserver/detail/capacity_math.hpp` | `httpserver::detail::capacity_add()` | small checked byte/arithmetic primitive |
+| `src/httpserver/detail/capacity_math.hpp` | `httpserver::detail::capacity_multiply()` | small checked byte/arithmetic primitive |

examples/README.md

@@ -386,3 +386,7 @@ v3 development; no automatic v2 port is implied.
 - [turbo_mode.cpp](turbo_mode.cpp)
 - [url_registration.cpp](url_registration.cpp)
 - [websocket_echo.cpp](websocket_echo.cpp)
+
+`v3_protocol_options` also demonstrates typed H2/H3/QUIC capacity profiles, pure
+`resolve_limits()` and immutable `effective_limits()` inspection with adequate
+shared budgets. See [protocol capacity policy](../docs/v3-protocol-limits.md).

examples/v3_protocol_options.cpp

@@ -5,6 +5,7 @@
 #include <iostream>
 #include <fstream>
 #include <memory>
+#include <string>
 #include <httpserver/features.hpp>
 #include <httpserver/server/server.hpp>
 #include <httpserver/server/tls_credentials.hpp>
@@ -41,13 +42,30 @@ bool demonstrate(const char* label, httpserver::http::protocol protocol, bool tl
     }
     options.add_listener({"127.0.0.1", 0, tls, credentials,
         protocol == http::protocol::http_3 ? srv::listener_transport::udp : srv::listener_transport::tcp});
+    options.budgets().set(srv::resource::header_fields, 4096);
+    options.budgets().set(srv::resource::quic_reassembly_bytes, 16 * 1024 * 1024);
+    if (protocol == http::protocol::http_2) {
+        options.http2().emplace().max_concurrent_requests = 192;
+        options.http2()->decoder_table_bytes = 8192;
+        options.http2()->encoder_table_bytes = 16384;
+    }
+    if (protocol == http::protocol::http_3) {
+        options.http3().emplace().max_concurrent_requests = 24;
+        options.http3()->max_blocked_headers = 32;
+        options.quic().emplace().max_stream_records = 96;
+    }
+    srv::effective_protocol_limits limits;
+    const auto resolved = options.resolve_limits(limits);
     const auto validated = options.validate();
     srv::native_server server(options);
+    const auto inspected = server.effective_limits(limits);
+    if (inspected.code() != resolved.code()) return false;
     const auto listened = server.listen();
     const auto port = server.get_bound_port(0);
     std::cout << label << " validate=" << outcome_name(validated)
               << " listen=" << outcome_name(listened) << " port=" << port << '\n';
     server.stop();
+    if (server.effective_limits(limits).code() != inspected.code()) return false;
     if (!tls || available) return validated.ok() && listened.ok() && port != 0;
     return listened.code() == http::outcome_code::not_supported && port == 0;
 }