feat(config): optional per-request async scope; release 0.7.2

HttpServerConfig::setRequestScope(bool) / isRequestScope() — opt out of the
per-request child async scope (default on, behaviour unchanged). When off, the
H1/H2/H3 handler coroutine reuses the connection scope directly, saving two
emalloc/efree per request; Async\request_context() then returns null (use ?->).

Wired through the per-worker view AND the cross-thread shared-config snapshot
(freeze + populate_from_shared), so the knob is honoured under setWorkers(N>1)
— not just single-worker. Setter is chainable and locks after start().

Tests: core/049 (default/toggle/chainable/locked/scope-off null context),
core/050 (multi-worker propagation). Bumps the stale version #define to 0.7.2;
CHANGELOG gains 0.7.2 + the previously-undocumented 0.7.1 (H3 stream credit).

Author: EdmondDantes

CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.2] - 2026-06-02
+
+### Added
+
+- `HttpServerConfig::setRequestScope(bool)` / `isRequestScope()` — opt out of the
+  per-request child async scope (default on). Off reuses the connection scope,
+  saving two allocations per request; `Async\request_context()` then returns null
+  (use `?->`). Propagates across `setWorkers(N>1)`.
+
+## [0.7.1] - 2026-06-01
+
+### Fixed
+
+- HTTP/3: replenish the connection's bidi stream credit on stream close
+  (`extend_max_streams_bidi`), so long-lived connections no longer stall at the
+  `initial_max_streams_bidi` cap (#79).
+
 ## [0.7.0] - 2026-06-01
 
 Headline release: **HTTP/3 over QUIC**. Folds in everything tagged but not yet

include/php_http_server.h

@@ -40,7 +40,7 @@
 extern zend_module_entry http_server_module_entry;
 #define phpext_http_server_ptr &http_server_module_entry
 
-#define PHP_HTTP_SERVER_VERSION "0.6.7"
+#define PHP_HTTP_SERVER_VERSION "0.7.2"
 
 /*
  * ==========================================================================
@@ -240,6 +240,7 @@ struct _http_server_config_t {
     uint32_t tls_buffer_bytes;        /* CT-out BIO ring size, record-aligned (#29) */
     bool     http3_alt_svc_enabled;
     bool     http3_pacing;            /* QUIC send pacing — opt-in (#59 Phase 2) */
+    bool     request_scope;           /* Per-request child scope (default on) */
 
     /* HTTP body compression (issues #8, #9). Phase 1 ships gzip via zlib-ng;
      * phase 2 adds Brotli + zstd through the same vtable.
@@ -780,6 +781,7 @@ typedef struct {
     uint32_t tls_buffer_bytes;           /* CT-out BIO ring size (#29) */
     bool     http3_alt_svc_enabled;
     bool     http3_pacing;               /* QUIC send pacing — opt-in (#59) */
+    bool     request_scope;              /* Per-request child scope (default on) */
     bool     telemetry_enabled;          /* W3C trace context ingestion */
     bool     body_streaming_enabled;     /* Issue #26 */
     /* Hot-path gate: true iff per-request hrtime stamps (enqueue_ns /

src/core/http_connection.c

@@ -1982,7 +1982,8 @@ static void h1_static_on_passthrough_to_php(void *user)
      * http_request_handler_coroutine_new). */
     zend_coroutine_t *coroutine = http_request_handler_coroutine_new(
         conn->scope, http_handler_coroutine_entry, ctx,
-        http_handler_coroutine_dispose);
+        http_handler_coroutine_dispose,
+        conn->view != NULL ? conn->view->request_scope : true);
 
     if (UNEXPECTED(coroutine == NULL)) {
         zval_ptr_dtor(&ctx->request_zv);
@@ -2200,7 +2201,8 @@ static void http_connection_dispatch_request(http_connection_t *conn, http_reque
      * (and its spawns) finish, or on spawn failure inside the helper. */
     zend_coroutine_t *coroutine = http_request_handler_coroutine_new(
         conn->scope, http_handler_coroutine_entry, ctx,
-        http_handler_coroutine_dispose);
+        http_handler_coroutine_dispose,
+        conn->view != NULL ? conn->view->request_scope : true);
 
     if (coroutine == NULL) {
         /* Spawn failed. The usual cause is a stale EG(exception) — a

src/core/http_connection.h

@@ -449,20 +449,28 @@ zend_async_scope_t *http_request_scope_new(zend_async_scope_t *server_scope);
  * (not yet enqueued) on success; on failure disposes the scope and
  * returns NULL, leaving protocol-specific zval/conn cleanup to the
  * caller. Shared by the H1/H2/H3 dispatch paths — static inline as it
- * sits on the per-request hot path. */
+ * sits on the per-request hot path.
+ *
+ * own_scope (HttpServerConfig::setRequestScope): true mints a per-request
+ * child scope (isolated request_context()); false reuses server_scope —
+ * two fewer allocations, but request_context() is then null. */
 static zend_always_inline zend_coroutine_t *http_request_handler_coroutine_new(
         zend_async_scope_t *server_scope,
         zend_coroutine_entry_t entry, void *extended_data,
-        zend_async_coroutine_dispose dispose)
+        zend_async_coroutine_dispose dispose,
+        const bool own_scope)
 {
-    zend_async_scope_t *req_scope = http_request_scope_new(server_scope);
+    zend_async_scope_t *req_scope = own_scope ? http_request_scope_new(server_scope) : server_scope;
     if (req_scope == NULL) {
         return NULL;
     }
 
     zend_coroutine_t *coroutine = ZEND_ASYNC_NEW_COROUTINE(req_scope);
     if (coroutine == NULL) {
-        req_scope->try_to_dispose(req_scope);
+        if (own_scope) {
+            req_scope->try_to_dispose(req_scope);
+        }
+
         return NULL;
     }
 

src/http2/http2_strategy.c

@@ -300,7 +300,8 @@ static void http2_strategy_dispatch(struct http_request_t *request,
      * its own request_context() subtree, isolated from sibling streams. */
     zend_coroutine_t *co = http_request_handler_coroutine_new(
         self->conn->scope, http2_handler_coroutine_entry, stream,
-        http2_handler_coroutine_dispose);
+        http2_handler_coroutine_dispose,
+        self->conn->view != NULL ? self->conn->view->request_scope : true);
 
     if (co == NULL) {
         zval_ptr_dtor(&stream->request_zv);

src/http3/http3_dispatch.c

@@ -251,7 +251,8 @@ void http3_stream_dispatch(http3_connection_t *c, http3_stream_t *s)
      * http_request_handler_coroutine_new — each multiplexed stream gets
      * its own request_context() subtree, isolated from sibling streams. */
     zend_coroutine_t *co = http_request_handler_coroutine_new(
-        scope, h3_handler_coroutine_entry, s, h3_handler_coroutine_dispose);
+        scope, h3_handler_coroutine_entry, s, h3_handler_coroutine_dispose,
+        s->conn->view != NULL ? s->conn->view->request_scope : true);
 
     if (co == NULL) {
         zval_ptr_dtor(&s->request_zv);  ZVAL_UNDEF(&s->request_zv);

src/http_server_class.c

@@ -956,6 +956,7 @@ const http_server_view_t http_server_view_default = {
     .tls_buffer_bytes = 0,
     .http3_alt_svc_enabled = true,
     .http3_pacing = false,
+    .request_scope = true,
 };
 
 /* Counters / view accessors. Always return a non-NULL pointer; callers
@@ -2346,6 +2347,9 @@ ZEND_METHOD(TrueAsync_HttpServer, start)
     zend_call_method_with_0_params(Z_OBJ(server->config), NULL, NULL, "isHttp3Pacing", &retval);
     server->view.http3_pacing = (Z_TYPE(retval) == IS_TRUE);
 
+    zend_call_method_with_0_params(Z_OBJ(server->config), NULL, NULL, "isRequestScope", &retval);
+    server->view.request_scope = (Z_TYPE(retval) == IS_TRUE);
+
     zend_call_method_with_0_params(Z_OBJ(server->config), NULL, NULL, "isTelemetryEnabled", &retval);
     server->view.telemetry_enabled = (Z_TYPE(retval) == IS_TRUE);
 

src/http_server_config.c

@@ -112,6 +112,7 @@ struct _http_server_shared_config_t {
      * honoured at start() time as an escape hatch. */
     bool                    http3_alt_svc_enabled;
     bool                    http3_pacing;
+    bool                    request_scope;
 };
 
 /* Forward declarations for shared-config lifecycle helpers */
@@ -402,6 +403,7 @@ ZEND_METHOD(TrueAsync_HttpServerConfig, __construct)
     config->tls_buffer_bytes = DEFAULT_TLS_BUFFER_BYTES;
     config->http3_alt_svc_enabled = true;  /* RFC 7838 advertise on by default */
     config->http3_pacing = false;          /* QUIC send pacing — opt-in (#59) */
+    config->request_scope = true;          /* Per-request child scope on by default */
     config->write_buffer_size = DEFAULT_WRITE_BUFFER_SIZE;
     config->auto_await_body = true;  /* Default: wait for body on non-multipart */
     ZVAL_UNDEF(&config->bootloader);
@@ -1617,6 +1619,40 @@ ZEND_METHOD(TrueAsync_HttpServerConfig, isHttp3Pacing)
     RETURN_BOOL(config->http3_pacing);
 }
 
+/* {{{ proto HttpServerConfig::setRequestScope(bool $enable): static
+ *
+ * Per-request child scope (on by default). When on, every request (and
+ * every multiplexed H2/H3 stream) runs in its own async scope, giving it
+ * an isolated request_context() subtree and a clean drain boundary.
+ *
+ * Turning it off reuses the connection scope directly, saving two
+ * allocations per request — but Async\request_context() then returns
+ * null (use the ?-> operator), so only disable it for handlers that
+ * never rely on per-request context. */
+ZEND_METHOD(TrueAsync_HttpServerConfig, setRequestScope)
+{
+    bool enable;
+    ZEND_PARSE_PARAMETERS_START(1, 1)
+        Z_PARAM_BOOL(enable)
+    ZEND_PARSE_PARAMETERS_END();
+
+    http_server_config_t *config = Z_HTTP_SERVER_CONFIG_P(ZEND_THIS);
+
+    if (config_check_locked(config)) {
+        return;
+    }
+
+    config->request_scope = enable;
+    RETURN_OBJ_COPY(Z_OBJ_P(ZEND_THIS));
+}
+
+ZEND_METHOD(TrueAsync_HttpServerConfig, isRequestScope)
+{
+    ZEND_PARSE_PARAMETERS_NONE();
+    http_server_config_t *config = Z_HTTP_SERVER_CONFIG_P(ZEND_THIS);
+    RETURN_BOOL(config->request_scope);
+}
+
 /* ==========================================================================
  * HTTP body compression knobs (issue #8). Editable until the config is
  * locked — see HttpServer::__construct. The MIME whitelist setter
@@ -2500,6 +2536,7 @@ static zend_object *http_server_config_create(zend_class_entry *ce)
     config->tls_buffer_bytes = 0;
     config->http3_alt_svc_enabled = true;
     config->http3_pacing = false;
+    config->request_scope = true;
     config->write_buffer_size = 0;
     config->http2_enabled = false;
     config->websocket_enabled = false;
@@ -2637,6 +2674,7 @@ static http_server_shared_config_t *http_server_shared_config_freeze(
     shared->tls_buffer_bytes = src->tls_buffer_bytes;
     shared->http3_alt_svc_enabled        = src->http3_alt_svc_enabled;
     shared->http3_pacing                 = src->http3_pacing;
+    shared->request_scope                = src->request_scope;
     shared->write_buffer_size  = src->write_buffer_size;
 
     shared->http2_enabled              = src->http2_enabled;
@@ -2789,6 +2827,7 @@ static void http_server_config_populate_from_shared(
     dst->tls_buffer_bytes = src->tls_buffer_bytes;
     dst->http3_alt_svc_enabled        = src->http3_alt_svc_enabled;
     dst->http3_pacing                 = src->http3_pacing;
+    dst->request_scope                = src->request_scope;
     dst->write_buffer_size  = src->write_buffer_size;
 
     dst->http2_enabled              = src->http2_enabled;

stubs/HttpServerConfig.php

@@ -529,6 +529,19 @@ public function setHttp3Pacing(bool $enable): static {}
     /** @return bool */
     public function isHttp3Pacing(): bool {}
 
+    /**
+     * Per-request child scope (on by default). Off reuses the connection
+     * scope directly — saves two allocations per request, but
+     * Async\request_context() then returns null (use ?->).
+     *
+     * @param bool $enable
+     * @return static
+     */
+    public function setRequestScope(bool $enable): static {}
+
+    /** @return bool */
+    public function isRequestScope(): bool {}
+
     // === HTTP body compression (issue #8) ===
 
     /**

stubs/HttpServerConfig.php_arginfo.h

@@ -153,6 +153,10 @@ ZEND_END_ARG_INFO()
 
 #define arginfo_class_TrueAsync_HttpServerConfig_isHttp3Pacing arginfo_class_TrueAsync_HttpServerConfig_isHttp3AltSvcEnabled
 
+#define arginfo_class_TrueAsync_HttpServerConfig_setRequestScope arginfo_class_TrueAsync_HttpServerConfig_setHttp3AltSvcEnabled
+
+#define arginfo_class_TrueAsync_HttpServerConfig_isRequestScope arginfo_class_TrueAsync_HttpServerConfig_isHttp3AltSvcEnabled
+
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_class_TrueAsync_HttpServerConfig_setCompressionLevel, 0, 1, IS_STATIC, 0)
 	ZEND_ARG_TYPE_INFO(0, level, IS_LONG, 0)
 ZEND_END_ARG_INFO()
@@ -307,6 +311,8 @@ ZEND_METHOD(TrueAsync_HttpServerConfig, setHttp3AltSvcEnabled);
 ZEND_METHOD(TrueAsync_HttpServerConfig, isHttp3AltSvcEnabled);
 ZEND_METHOD(TrueAsync_HttpServerConfig, setHttp3Pacing);
 ZEND_METHOD(TrueAsync_HttpServerConfig, isHttp3Pacing);
+ZEND_METHOD(TrueAsync_HttpServerConfig, setRequestScope);
+ZEND_METHOD(TrueAsync_HttpServerConfig, isRequestScope);
 ZEND_METHOD(TrueAsync_HttpServerConfig, setCompressionEnabled);
 ZEND_METHOD(TrueAsync_HttpServerConfig, isCompressionEnabled);
 ZEND_METHOD(TrueAsync_HttpServerConfig, setCompressionLevel);
@@ -408,6 +414,8 @@ static const zend_function_entry class_TrueAsync_HttpServerConfig_methods[] = {
 	ZEND_ME(TrueAsync_HttpServerConfig, isHttp3AltSvcEnabled, arginfo_class_TrueAsync_HttpServerConfig_isHttp3AltSvcEnabled, ZEND_ACC_PUBLIC)
 	ZEND_ME(TrueAsync_HttpServerConfig, setHttp3Pacing, arginfo_class_TrueAsync_HttpServerConfig_setHttp3Pacing, ZEND_ACC_PUBLIC)
 	ZEND_ME(TrueAsync_HttpServerConfig, isHttp3Pacing, arginfo_class_TrueAsync_HttpServerConfig_isHttp3Pacing, ZEND_ACC_PUBLIC)
+	ZEND_ME(TrueAsync_HttpServerConfig, setRequestScope, arginfo_class_TrueAsync_HttpServerConfig_setRequestScope, ZEND_ACC_PUBLIC)
+	ZEND_ME(TrueAsync_HttpServerConfig, isRequestScope, arginfo_class_TrueAsync_HttpServerConfig_isRequestScope, ZEND_ACC_PUBLIC)
 	ZEND_ME(TrueAsync_HttpServerConfig, setCompressionEnabled, arginfo_class_TrueAsync_HttpServerConfig_setCompressionEnabled, ZEND_ACC_PUBLIC)
 	ZEND_ME(TrueAsync_HttpServerConfig, isCompressionEnabled, arginfo_class_TrueAsync_HttpServerConfig_isCompressionEnabled, ZEND_ACC_PUBLIC)
 	ZEND_ME(TrueAsync_HttpServerConfig, setCompressionLevel, arginfo_class_TrueAsync_HttpServerConfig_setCompressionLevel, ZEND_ACC_PUBLIC)