From 24b19c4a657cd49d221bf27241112f13f76fe3cb Mon Sep 17 00:00:00 2001
From: Edmond <1571649+EdmondDantes@users.noreply.github.com>
Date: Mon, 4 May 2026 11:22:04 +0300
Subject: [PATCH 01/10] Add true-async-server framework entry

Native PHP HTTP server using TrueAsync coroutine engine with ThreadPool
for SO_REUSEPORT multi-worker scaling. Supports HTTP/1.1 and HTTP/2 over
TLS via ALPN. Covers baseline, pipelined, json, upload, static, async-db,
api-4/16, baseline-h2, static-h2, json-tls test profiles.
---
 frameworks/true-async-server/Dockerfile     |  53 +++++
 frameworks/true-async-server/PostgreSQL.php |  92 +++++++++
 frameworks/true-async-server/entry.php      | 207 ++++++++++++++++++++
 frameworks/true-async-server/meta.json      |  24 +++
 4 files changed, 376 insertions(+)
 create mode 100644 frameworks/true-async-server/Dockerfile
 create mode 100644 frameworks/true-async-server/PostgreSQL.php
 create mode 100644 frameworks/true-async-server/entry.php
 create mode 100644 frameworks/true-async-server/meta.json

diff --git a/frameworks/true-async-server/Dockerfile b/frameworks/true-async-server/Dockerfile
new file mode 100644
index 00000000..93dd066d
--- /dev/null
+++ b/frameworks/true-async-server/Dockerfile
@@ -0,0 +1,53 @@
+FROM ubuntu:24.04
+
+# Minimal runtime deps:
+#   libnghttp2-14  — system nghttp2 (.so linked by true_async_server.so)
+#   libsqlite3-0   — PDO sqlite (built into PHP)
+#   ca-certificates — TLS cert store
+RUN apt-get update -qq && \
+    apt-get install -y --no-install-recommends \
+        libnghttp2-14 \
+        libsqlite3-0 \
+        libpq5 \
+        ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── PHP binary (locally built, ZTS + TrueAsync ABI) ─────────────────
+COPY php /usr/local/bin/php
+
+# ── Custom shared libraries (libuv, OpenSSL 3, ngtcp2, nghttp3) ──────
+COPY libs/ /usr/local/lib/
+RUN ldconfig
+
+# ── PHP extension dir + true_async_server.so ─────────────────────────
+RUN mkdir -p /usr/local/lib/php/extensions/no-debug-zts-20250926
+COPY true_async_server.so /usr/local/lib/php/extensions/no-debug-zts-20250926/true_async_server.so
+COPY pdo_pgsql.so        /usr/local/lib/php/extensions/no-debug-zts-20250926/pdo_pgsql.so
+
+# ── Minimal php.ini ───────────────────────────────────────────────────
+RUN mkdir -p /usr/local/lib && printf '%s\n' \
+      'extension_dir=/usr/local/lib/php/extensions/no-debug-zts-20250926' \
+      'extension=pdo_pgsql' \
+      'extension=true_async_server' \
+      'opcache.enable=1' \
+      'opcache.enable_cli=1' \
+      'opcache.jit=1255' \
+      'opcache.jit_buffer_size=128M' \
+      'opcache.memory_consumption=256' \
+      'opcache.max_accelerated_files=10000' \
+      'opcache.validate_timestamps=0' \
+      'opcache.preload=' \
+      'memory_limit=1024M' \
+      'realpath_cache_size=4M' \
+      'realpath_cache_ttl=600' \
+    > /usr/local/lib/php.ini
+
+# ── Application ───────────────────────────────────────────────────────
+WORKDIR /app
+COPY entry.php /app/entry.php
+COPY PostgreSQL.php /app/PostgreSQL.php
+
+EXPOSE 8080
+EXPOSE 8443
+
+CMD ["php", "/app/entry.php"]
diff --git a/frameworks/true-async-server/PostgreSQL.php b/frameworks/true-async-server/PostgreSQL.php
new file mode 100644
index 00000000..da6fcfef
--- /dev/null
+++ b/frameworks/true-async-server/PostgreSQL.php
@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Postgres access for TrueAsync HTTP handlers.
+ *
+ * Uses the native PDO connection pool shipped with ext-async (PDO::ATTR_POOL_*)
+ * — each PDO method call grabs an idle connection, runs, and returns it to the
+ * pool. Coroutines that find the pool exhausted park on the libuv reactor
+ * instead of blocking the worker thread.
+ */
+final class PostgreSQL
+{
+    private static ?PDO $pdo = null;
+    private static bool $available = false;
+    private const SQL =
+        'SELECT id, name, category, price, quantity, active, tags, rating_score, rating_count '
+        . 'FROM items WHERE price BETWEEN ? AND ? LIMIT ?';
+
+    public static function init(): void
+    {
+        $url = getenv('DATABASE_URL') ?: '';
+        if ($url === '') {
+            return;
+        }
+
+        $parts = parse_url($url);
+        $dsn   = sprintf(
+            'pgsql:host=%s;port=%s;dbname=%s',
+            $parts['host'] ?? 'localhost',
+            $parts['port'] ?? 5432,
+            ltrim($parts['path'] ?? '/benchmark', '/')
+        );
+
+        $maxConn = (int)(getenv('DATABASE_MAX_CONN') ?: 256);
+        $minConn = (int)(getenv('DATABASE_MIN_CONN') ?: max(8, (int)($maxConn / 8)));
+
+        self::$pdo = new PDO(
+            $dsn,
+            $parts['user'] ?? 'bench',
+            $parts['pass'] ?? 'bench',
+            [
+                PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
+                PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
+                PDO::ATTR_EMULATE_PREPARES   => false,
+                PDO::ATTR_POOL_ENABLED       => true,
+                PDO::ATTR_POOL_MIN           => $minConn,
+                PDO::ATTR_POOL_MAX           => $maxConn,
+            ]
+        );
+
+        self::$available = true;
+    }
+
+    public static function query(float $min, float $max, int $limit = 50): string
+    {
+        if (!self::$available) {
+            self::init();
+            if (!self::$available) {
+                return '{"items":[],"count":0}';
+            }
+        }
+
+        try {
+            $stmt = self::$pdo->prepare(self::SQL);
+            $stmt->execute([$min, $max, $limit]);
+            $rows = [];
+            while ($row = $stmt->fetch()) {
+                $rows[] = [
+                    'id'       => $row['id'],
+                    'name'     => $row['name'],
+                    'category' => $row['category'],
+                    'price'    => $row['price'],
+                    'quantity' => $row['quantity'],
+                    'active'   => (bool)$row['active'],
+                    'tags'     => json_decode($row['tags'], true),
+                    'rating'   => [
+                        'score' => $row['rating_score'],
+                        'count' => $row['rating_count'],
+                    ],
+                ];
+            }
+            return json_encode(
+                ['items' => $rows, 'count' => count($rows)],
+                JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
+            );
+        } catch (\Throwable) {
+            return '{"items":[],"count":0}';
+        }
+    }
+}
diff --git a/frameworks/true-async-server/entry.php b/frameworks/true-async-server/entry.php
new file mode 100644
index 00000000..4cbd96f4
--- /dev/null
+++ b/frameworks/true-async-server/entry.php
@@ -0,0 +1,207 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * HttpArena entry point for the TrueAsync HTTP server.
+ *
+ * Architecture:
+ *   - One PHP process. N worker threads (N = available_parallelism()).
+ *   - Server + handler are built once in the main thread, then submitted
+ *     to a ThreadPool. Each worker calls $server->start() on the same
+ *     transferred object; SO_REUSEPORT lets the kernel load-balance
+ *     accept()s across all threads.
+ *   - Each worker has its own PDO connection pool (ext-async PDO::ATTR_POOL_*).
+ *
+ * Override worker count with WORKERS env var.
+ */
+
+use TrueAsync\HttpServer;
+use TrueAsync\HttpServerConfig;
+use TrueAsync\HttpRequest;
+use TrueAsync\HttpResponse;
+use Async\ThreadPool;
+use function Async\spawn;
+use function Async\await_all_or_fail;
+use function Async\available_parallelism;
+
+require __DIR__ . '/PostgreSQL.php';
+
+// --- Preload at process start (read once, transferred to all workers) ---
+
+$datasetRaw   = json_decode(file_get_contents('/data/dataset.json'), true);
+$datasetCount = count($datasetRaw);
+
+$mimeTypes = [
+    'css'   => 'text/css',
+    'js'    => 'application/javascript',
+    'html'  => 'text/html',
+    'woff2' => 'font/woff2',
+    'svg'   => 'image/svg+xml',
+    'webp'  => 'image/webp',
+    'json'  => 'application/json',
+];
+
+$staticFiles = [];
+$staticDir = '/data/static';
+if (is_dir($staticDir)) {
+    foreach (scandir($staticDir) as $name) {
+        if ($name === '.' || $name === '..') continue;
+        if (str_ends_with($name, '.br') || str_ends_with($name, '.gz')) continue;
+        $base = $staticDir . '/' . $name;
+        $ext  = pathinfo($name, PATHINFO_EXTENSION);
+        $staticFiles['/static/' . $name] = [
+            'data' => file_get_contents($base),
+            'mime' => $mimeTypes[$ext] ?? 'application/octet-stream',
+            'br'   => file_exists($base . '.br') ? file_get_contents($base . '.br') : null,
+            'gz'   => file_exists($base . '.gz') ? file_get_contents($base . '.gz') : null,
+        ];
+    }
+}
+
+// --- Runtime knobs ---
+
+$port    = (int)(getenv('PORT') ?: 8080);
+$tlsPort = (int)(getenv('TLS_PORT') ?: 8443);
+$workers = (int)(getenv('WORKERS') ?: 0);
+if ($workers <= 0) {
+    $workers = available_parallelism();
+}
+
+$certPath     = '/certs/server.crt';
+$keyPath      = '/certs/server.key';
+$tlsAvailable = is_readable($certPath) && is_readable($keyPath);
+
+// --- Step 1: build the server (one instance, transferred into each thread) ---
+
+$config = (new HttpServerConfig())
+    ->addListener('0.0.0.0', $port)
+    ->setBacklog(2048)
+    ->setReadTimeout(15)
+    ->setWriteTimeout(15)
+    ->setKeepAliveTimeout(60)
+    ->setShutdownTimeout(5)
+    ->setMaxBodySize(32 * 1024 * 1024);
+
+if ($tlsAvailable) {
+    $config
+        ->addListener('0.0.0.0', $tlsPort, true)
+        ->setCertificate($certPath)
+        ->setPrivateKey($keyPath);
+}
+
+$server = new HttpServer($config);
+
+$server->addHttpHandler(
+    static function (HttpRequest $request, HttpResponse $response)
+        use ($datasetRaw, $datasetCount, $staticFiles): void
+    {
+        $path = $request->getPath();
+
+        if ($path === '/pipeline') {
+            $response->setStatusCode(200)
+                ->setHeader('Content-Type', 'text/plain')
+                ->setBody('ok');
+            return;
+        }
+
+        if ($path === '/baseline2' || $path === '/baseline11') {
+            $method = $request->getMethod();
+            if ($method !== 'GET' && $method !== 'POST') {
+                $response->setStatusCode(405)
+                    ->setHeader('Content-Type', 'text/plain')
+                    ->setBody('Method Not Allowed');
+                return;
+            }
+            $sum = 0;
+            foreach ($request->getQuery() as $v) { $sum += (int)$v; }
+            if ($method === 'POST') {
+                $sum += (int)$request->getBody();
+            }
+            $response->setStatusCode(200)
+                ->setHeader('Content-Type', 'text/plain')
+                ->setBody((string)$sum);
+            return;
+        }
+
+        if (str_starts_with($path, '/json/')) {
+            $tail = substr($path, 6);
+            if ($tail !== '' && ctype_digit($tail)) {
+                $query = $request->getQuery();
+                $count = min((int)$tail, $datasetCount);
+                $mult  = (int)($query['m'] ?? 1);
+                if ($mult === 0) $mult = 1;
+                $items = [];
+                for ($i = 0; $i < $count; $i++) {
+                    $item          = $datasetRaw[$i];
+                    $item['total'] = $item['price'] * $item['quantity'] * $mult;
+                    $items[]       = $item;
+                }
+                $response->setStatusCode(200)
+                    ->setHeader('Content-Type', 'application/json')
+                    ->setBody(json_encode(
+                        ['items' => $items, 'count' => $count],
+                        JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
+                    ));
+                return;
+            }
+        }
+
+        if ($path === '/upload') {
+            $response->setStatusCode(200)
+                ->setHeader('Content-Type', 'text/plain')
+                ->setBody((string)strlen($request->getBody()));
+            return;
+        }
+
+        if ($path === '/async-db') {
+            $query = $request->getQuery();
+            $min   = (float)($query['min'] ?? 10);
+            $max   = (float)($query['max'] ?? 50);
+            $limit = max(1, min(50, (int)($query['limit'] ?? 50)));
+            $response->setStatusCode(200)
+                ->setHeader('Content-Type', 'application/json')
+                ->setBody(PostgreSQL::query($min, $max, $limit));
+            return;
+        }
+
+        if (str_starts_with($path, '/static/') && isset($staticFiles[$path])) {
+            $f  = $staticFiles[$path];
+            $ae = $request->getHeader('Accept-Encoding') ?? '';
+            $response->setStatusCode(200)
+                ->setHeader('Content-Type', $f['mime']);
+            if ($f['br'] !== null && str_contains($ae, 'br')) {
+                $response->setHeader('Content-Encoding', 'br')->setBody($f['br']);
+            } elseif ($f['gz'] !== null && str_contains($ae, 'gzip')) {
+                $response->setHeader('Content-Encoding', 'gzip')->setBody($f['gz']);
+            } else {
+                $response->setBody($f['data']);
+            }
+            return;
+        }
+
+        $response->setStatusCode(404)
+            ->setHeader('Content-Type', 'text/plain')
+            ->setBody('404 Not Found');
+    }
+);
+
+// --- Step 2: launch pool, run $server->start() in every thread ---
+
+fprintf(
+    STDERR,
+    "[true-async-server] %d workers · :%d%s · pid %d\n",
+    $workers,
+    $port,
+    $tlsAvailable ? " · tls :{$tlsPort}" : '',
+    getmypid()
+);
+
+$pool    = new ThreadPool($workers);
+$futures = [];
+for ($i = 0; $i < $workers; $i++) {
+    $futures[] = $pool->submit(static fn() => $server->start());
+}
+
+// Wait until all workers finish (i.e. until the process is stopped).
+spawn(static fn() => await_all_or_fail($futures));
diff --git a/frameworks/true-async-server/meta.json b/frameworks/true-async-server/meta.json
new file mode 100644
index 00000000..6c7cded2
--- /dev/null
+++ b/frameworks/true-async-server/meta.json
@@ -0,0 +1,24 @@
+{
+  "display_name": "true-async-server",
+  "language": "PHP",
+  "type": "tuned",
+  "engine": "true-async-server",
+  "description": "Native PHP HTTP server built on the TrueAsync coroutine engine. Each connection runs as a cooperative coroutine; one OS thread per CPU listens via SO_REUSEPORT inside a single PHP process. PDO connection pool, OPcache JIT, no Caddy / FrankenPHP / FastCGI in front.",
+  "repo": "https://github.com/true-async/server",
+  "enabled": true,
+  "maintainers": ["EdmondDantes"],
+  "tests": [
+    "baseline",
+    "pipelined",
+    "limited-conn",
+    "json",
+    "upload",
+    "static",
+    "async-db",
+    "api-4",
+    "api-16",
+    "baseline-h2",
+    "static-h2",
+    "json-tls"
+  ]
+}

From 64f184078259221b9c30db5d1e91692103f5438f Mon Sep 17 00:00:00 2001
From: Edmond <1571649+EdmondDantes@users.noreply.github.com>
Date: Mon, 4 May 2026 15:03:36 +0300
Subject: [PATCH 02/10] Add true-async-server Docker Compose test suite (34/38
 passing)

- Add docker-compose.yml: postgres + server + validator services on
  a shared bridge network; validator exits with the test result code
- Add test/Dockerfile + test/validate.sh: full HTTP/1.1, HTTP/2,
  TLS, JSON, upload, static, async-db and TCP-fragmentation tests
- Fix entry.php: require PostgreSQL.php inside each per-thread
  closure so every worker thread has the class in its PHP environment
- Fix Dockerfile: switch to slim base image with INI tuning
- Add ISSUES.md: documents 4 remaining alpha.3 failures with root
  causes and suggested server-level fixes
---
 frameworks/true-async-server/Dockerfile       |  46 +--
 frameworks/true-async-server/ISSUES.md        |  91 ++++++
 .../true-async-server/docker-compose.yml      |  54 ++++
 frameworks/true-async-server/entry.php        |   7 +-
 frameworks/true-async-server/test/Dockerfile  |  11 +
 frameworks/true-async-server/test/validate.sh | 263 ++++++++++++++++++
 6 files changed, 430 insertions(+), 42 deletions(-)
 create mode 100644 frameworks/true-async-server/ISSUES.md
 create mode 100644 frameworks/true-async-server/docker-compose.yml
 create mode 100644 frameworks/true-async-server/test/Dockerfile
 create mode 100644 frameworks/true-async-server/test/validate.sh

diff --git a/frameworks/true-async-server/Dockerfile b/frameworks/true-async-server/Dockerfile
index 93dd066d..9b89130c 100644
--- a/frameworks/true-async-server/Dockerfile
+++ b/frameworks/true-async-server/Dockerfile
@@ -1,53 +1,17 @@
-FROM ubuntu:24.04
+FROM trueasync/php-true-async:0.7.0-alpha.3-php8.6
 
-# Minimal runtime deps:
-#   libnghttp2-14  — system nghttp2 (.so linked by true_async_server.so)
-#   libsqlite3-0   — PDO sqlite (built into PHP)
-#   ca-certificates — TLS cert store
-RUN apt-get update -qq && \
-    apt-get install -y --no-install-recommends \
-        libnghttp2-14 \
-        libsqlite3-0 \
-        libpq5 \
-        ca-certificates \
-    && rm -rf /var/lib/apt/lists/*
-
-# ── PHP binary (locally built, ZTS + TrueAsync ABI) ─────────────────
-COPY php /usr/local/bin/php
-
-# ── Custom shared libraries (libuv, OpenSSL 3, ngtcp2, nghttp3) ──────
-COPY libs/ /usr/local/lib/
-RUN ldconfig
-
-# ── PHP extension dir + true_async_server.so ─────────────────────────
-RUN mkdir -p /usr/local/lib/php/extensions/no-debug-zts-20250926
-COPY true_async_server.so /usr/local/lib/php/extensions/no-debug-zts-20250926/true_async_server.so
-COPY pdo_pgsql.so        /usr/local/lib/php/extensions/no-debug-zts-20250926/pdo_pgsql.so
-
-# ── Minimal php.ini ───────────────────────────────────────────────────
-RUN mkdir -p /usr/local/lib && printf '%s\n' \
-      'extension_dir=/usr/local/lib/php/extensions/no-debug-zts-20250926' \
-      'extension=pdo_pgsql' \
-      'extension=true_async_server' \
-      'opcache.enable=1' \
-      'opcache.enable_cli=1' \
+RUN printf '%s\n' \
       'opcache.jit=1255' \
       'opcache.jit_buffer_size=128M' \
       'opcache.memory_consumption=256' \
       'opcache.max_accelerated_files=10000' \
       'opcache.validate_timestamps=0' \
-      'opcache.preload=' \
       'memory_limit=1024M' \
-      'realpath_cache_size=4M' \
-      'realpath_cache_ttl=600' \
-    > /usr/local/lib/php.ini
+    > /etc/php.d/99-arena.ini
 
-# ── Application ───────────────────────────────────────────────────────
 WORKDIR /app
-COPY entry.php /app/entry.php
-COPY PostgreSQL.php /app/PostgreSQL.php
+COPY entry.php PostgreSQL.php /app/
 
-EXPOSE 8080
-EXPOSE 8443
+EXPOSE 8080 8443
 
 CMD ["php", "/app/entry.php"]
diff --git a/frameworks/true-async-server/ISSUES.md b/frameworks/true-async-server/ISSUES.md
new file mode 100644
index 00000000..abe16351
--- /dev/null
+++ b/frameworks/true-async-server/ISSUES.md
@@ -0,0 +1,91 @@
+# Known Issues — true-async-server (alpha.3)
+
+Tested against `trueasync/php-true-async:0.7.0-alpha.3-php8.6`.  
+Test suite: `frameworks/true-async-server/test/validate.sh`  
+Result: **34 / 38 passed**.
+
+---
+
+## Passing test groups
+
+| Group | Tests |
+|---|---|
+| baseline HTTP/1.1 (GET, POST, chunked POST) | ✅ |
+| baseline TCP fragmentation — GET only | ✅ 2/4 |
+| pipelined | ✅ |
+| json processing | ✅ |
+| upload | ✅ |
+| static files | ✅ |
+| async-db (PostgreSQL) | ✅ |
+| baseline-h2 (HTTPS + HTTP/2) | ✅ |
+| static-h2 | ✅ |
+| json-tls (HTTPS + HTTP/1.1 TLS) | ✅ |
+
+---
+
+## Failing tests (4)
+
+### 1. HTTP/1.1 body not fully buffered on fragmented POST
+
+**Tests:**
+- `POST split headers/body` — headers in one TCP segment, body `"20"` in a second
+- `POST split body bytes` — headers in one TCP segment, body split into `"2"` + `"0"`
+
+**Observed behaviour:**
+```
+FAIL [POST split headers/body]:  expected='75' got='57'
+FAIL [POST split body bytes]:    expected='75' got='55'
+```
+
+`57 = 13 + 42 + 2` — the server read only the first byte `"2"` of the two-byte body `"20"`.  
+`55 = 13 + 42 + 0` — the server read no body bytes at all when they arrived in two separate writes.
+
+**Root cause:**  
+`HttpRequest::getBody()` appears to return whatever bytes are present in the receive buffer at the moment of the call instead of waiting until `Content-Length` bytes have accumulated. When the request body arrives in a separate TCP segment after the headers, the handler coroutine is dispatched before the body bytes land in the buffer, and `getBody()` returns a partial (or empty) string.
+
+**HTTP/2 is not affected** — HTTP/2 frames the body before dispatching, so `getBody()` is always complete.
+
+**Suggested fix (server-level):**  
+`getBody()` must block / yield until `Content-Length` bytes have been fully received from the socket before returning control to the handler.
+
+---
+
+### 2. Spорadic empty responses during server startup (race condition)
+
+**Tests (intermittent):**
+- `GET /baseline11 random a=… b=…`
+- `POST /baseline11 random body=…`
+
+**Observed behaviour:**
+```
+FAIL [GET /baseline11 random a=372 b=922]: expected='1294' got=''
+FAIL [POST /baseline11 random body=346]:   expected='401'  got=''
+```
+The same requests succeed when sent against a server that has been running for several seconds.
+
+**Server log (concurrent with failures):**
+```
+Warning: Attempt to finalize a coroutine that is still in the queue in Unknown on line 0
+```
+
+**Root cause:**  
+When `ThreadPool` starts 16 workers simultaneously, their event-loop initialisation coroutines overlap with early incoming requests. The lifecycle management in `alpha.3` occasionally finalises a request-handler coroutine while it is still enqueued, causing the connection to be closed without a response.
+
+The issue is transient: workers stabilise after a few seconds and subsequent identical requests succeed. A 20-request warm-up + 1 s sleep was added to `validate.sh` to reduce the window, but under low-latency Docker networks the race can still be triggered.
+
+**Suggested fix (server-level):**  
+Ensure that per-worker event-loop initialisation is fully complete (all coroutines flushed) before the first `accept()` call is made, or guard against finalising a coroutine that has not yet been dequeued.
+
+**Workaround (application-level):**  
+Set `WORKERS=1` or `WORKERS=2` via environment variable for integration testing; the race disappears with a single worker.
+
+---
+
+## Fixes applied in this integration
+
+| Issue | Fix |
+|---|---|
+| `async-db` → HTTP 500 "Class PostgreSQL not found" | `PostgreSQL.php` is now `require`-d inside each per-thread closure; every worker thread has its own PHP class table |
+| `check_header` using `curl -I` failing with newer curl | Replaced `-sI` with `-D - -o /dev/null` to dump headers without changing the HTTP method |
+| Validator failures immediately after Docker Compose start | Added 20-request warm-up loop + `sleep 1` in `validate.sh` |
+| `\r\n` literals not decoded to real CRLF in fragmented-TCP tests | Fixed bash→Python escaping: `'\\\\r'` in the `-c "…"` string becomes `'\\r'` in Python source, correctly replacing literal `\r` with CR |
diff --git a/frameworks/true-async-server/docker-compose.yml b/frameworks/true-async-server/docker-compose.yml
new file mode 100644
index 00000000..42b1b8b2
--- /dev/null
+++ b/frameworks/true-async-server/docker-compose.yml
@@ -0,0 +1,54 @@
+services:
+  postgres:
+    image: postgres:18
+    command: ["-c", "max_connections=256"]
+    environment:
+      POSTGRES_USER: bench
+      POSTGRES_PASSWORD: bench
+      POSTGRES_DB: benchmark
+    volumes:
+      - ${DATA_DIR:-../../data}/pgdb-seed.sql:/docker-entrypoint-initdb.d/seed.sql:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U bench -d benchmark && psql -U bench -d benchmark -tAc 'SELECT 1 FROM items LIMIT 1' | grep -q 1"]
+      interval: 2s
+      timeout: 10s
+      retries: 30
+    networks: [arena]
+
+  server:
+    build:
+      context: .
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      DATABASE_URL: postgres://bench:bench@postgres:5432/benchmark
+      DATABASE_MAX_CONN: "256"
+    volumes:
+      - ${DATA_DIR:-../../data}/dataset.json:/data/dataset.json:ro
+      - ${DATA_DIR:-../../data}/static:/data/static:ro
+      - ${CERTS_DIR:-../../certs}:/certs:ro
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://127.0.0.1:8080/pipeline"]
+      interval: 2s
+      timeout: 5s
+      retries: 20
+    networks: [arena]
+
+  validator:
+    build:
+      context: ./test
+    depends_on:
+      server:
+        condition: service_healthy
+    environment:
+      SERVER: server
+      HTTP_PORT: "8080"
+      HTTPS_PORT: "8443"
+    volumes:
+      - ${CERTS_DIR:-../../certs}:/certs:ro
+    networks: [arena]
+
+networks:
+  arena:
+    driver: bridge
diff --git a/frameworks/true-async-server/entry.php b/frameworks/true-async-server/entry.php
index 4cbd96f4..0b8dd2d6 100644
--- a/frameworks/true-async-server/entry.php
+++ b/frameworks/true-async-server/entry.php
@@ -177,6 +177,7 @@ static function (HttpRequest $request, HttpResponse $response)
             } else {
                 $response->setBody($f['data']);
             }
+
             return;
         }
 
@@ -200,7 +201,11 @@ static function (HttpRequest $request, HttpResponse $response)
 $pool    = new ThreadPool($workers);
 $futures = [];
 for ($i = 0; $i < $workers; $i++) {
-    $futures[] = $pool->submit(static fn() => $server->start());
+    // Each worker thread has its own PHP environment — re-require class files.
+    $futures[] = $pool->submit(static function () use ($server): void {
+        require __DIR__ . '/PostgreSQL.php';
+        $server->start();
+    });
 }
 
 // Wait until all workers finish (i.e. until the process is stopped).
diff --git a/frameworks/true-async-server/test/Dockerfile b/frameworks/true-async-server/test/Dockerfile
new file mode 100644
index 00000000..f92336db
--- /dev/null
+++ b/frameworks/true-async-server/test/Dockerfile
@@ -0,0 +1,11 @@
+FROM python:3.12-slim
+
+# curl with HTTP/2 support (Debian bookworm libcurl includes nghttp2)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY validate.sh /validate.sh
+RUN chmod +x /validate.sh
+
+ENTRYPOINT ["/validate.sh"]
diff --git a/frameworks/true-async-server/test/validate.sh b/frameworks/true-async-server/test/validate.sh
new file mode 100644
index 00000000..a78f21fb
--- /dev/null
+++ b/frameworks/true-async-server/test/validate.sh
@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+# Validation suite for true-async-server — runs inside the 'validator' service.
+#
+# Environment (set by docker-compose.yml):
+#   SERVER      hostname of the server service  (default: server)
+#   HTTP_PORT   plain HTTP port                 (default: 8080)
+#   HTTPS_PORT  TLS port for HTTP/2 + TLS       (default: 8443)
+
+set -uo pipefail   # -e intentionally omitted — arithmetic would kill the script
+
+SERVER="${SERVER:-server}"
+HTTP_PORT="${HTTP_PORT:-8080}"
+HTTPS_PORT="${HTTPS_PORT:-8443}"
+
+H1="http://${SERVER}:${HTTP_PORT}"
+TLS="https://${SERVER}:${HTTPS_PORT}"
+
+PASS=0
+FAIL=0
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+ok()   { echo "  PASS [$1]"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL [$1]: $2"; FAIL=$((FAIL + 1)); }
+
+# check <label> <expected-body> [curl-args...]
+check() {
+    local lbl="$1" exp="$2"; shift 2
+    local got
+    got=$(curl -s --max-time 10 "$@" 2>/dev/null || true)
+    [[ "$got" == "$exp" ]] && ok "$lbl" || fail "$lbl" "expected='$exp' got='${got:0:120}'"
+}
+
+# check_status <label> <expected-code> [curl-args...]
+check_status() {
+    local lbl="$1" exp="$2"; shift 2
+    local got
+    got=$(curl -s --max-time 10 -o /dev/null -w "%{http_code}" "$@" 2>/dev/null || true)
+    [[ "$got" == "$exp" ]] && ok "$lbl" || fail "$lbl" "expected HTTP $exp got $got"
+}
+
+# check_header <label> <header-name> <expected-prefix> [curl-args...]
+# Uses -D - to dump headers without changing the HTTP method (avoids curl
+# refusing to combine --head with --data on newer curl versions).
+check_header() {
+    local lbl="$1" hname="$2" exp="$3"; shift 3
+    local got
+    got=$(curl -s --max-time 10 -D - -o /dev/null "$@" 2>/dev/null \
+          | grep -i "^${hname}:" | head -1 | tr -d '\r' | sed 's/^[^:]*: *//')
+    echo "$got" | grep -qi "^${exp}" && ok "$lbl ($got)" || fail "$lbl" "expected $hname~'$exp' got='$got'"
+}
+
+# check_json <label> <url> <expected-count> <mult>
+# Verifies: count matches, every item has 'total', total == price*qty*mult
+check_json() {
+    local lbl="$1" url="$2" expected_count="$3" m="$4"
+    local resp result
+    resp=$(curl -sk --max-time 10 "$url" 2>/dev/null || true)
+    result=$(python3 -c "
+import sys, json
+resp, expected_count, m = sys.argv[1], int(sys.argv[2]), int(sys.argv[3])
+try:
+    d = json.loads(resp)
+except Exception as e:
+    print('FAIL parse:', e); sys.exit(0)
+count  = d.get('count', 0)
+items  = d.get('items', [])
+ht = all('total' in i for i in items) if items else False
+ct = all(abs(i.get('total',0) - i['price'] * i['quantity'] * m) < 0.01 for i in items) if items else False
+if count == expected_count and ht and ct:
+    print('PASS')
+else:
+    print(f'FAIL count={count}/{expected_count} has_total={ht} totals_ok={ct}')
+" "$resp" "$expected_count" "$m" 2>/dev/null || echo "FAIL python3 error")
+    [[ "$result" == "PASS" ]] && ok "$lbl" || fail "$lbl" "$result"
+}
+
+# check_asyncdb <label> <url> <expected-count>
+check_asyncdb() {
+    local lbl="$1" url="$2" expected_count="$3"
+    local resp result
+    resp=$(curl -s --max-time 15 "$url" 2>/dev/null || true)
+    result=$(python3 -c "
+import sys, json
+resp, expected_count = sys.argv[1], int(sys.argv[2])
+try:
+    d = json.loads(resp)
+except Exception as e:
+    print('FAIL parse:', e); sys.exit(0)
+count  = d.get('count', 0)
+items  = d.get('items', [])
+hr = all('rating' in i and 'score' in i['rating'] for i in items) if items else True
+ht = all(isinstance(i.get('tags'), list) for i in items) if items else True
+ha = all(isinstance(i.get('active'), bool) for i in items) if items else True
+if count == expected_count and hr and ht and ha:
+    print('PASS')
+else:
+    print(f'FAIL count={count}/{expected_count} rating={hr} tags={ht} active={ha}')
+" "$resp" "$expected_count" 2>/dev/null || echo "FAIL python3 error")
+    [[ "$result" == "PASS" ]] && ok "$lbl" || fail "$lbl" "$result"
+}
+
+# check_fragmented <label> <expected-body> <frag1> [frag2 ...]
+# Fragments may contain literal \r\n — python decodes them to actual CRLF.
+check_fragmented() {
+    local lbl="$1" exp="$2"; shift 2
+    local result
+    result=$(python3 -c "
+import sys, socket, time
+host, port = sys.argv[1], int(sys.argv[2])
+frags = sys.argv[3:]
+try:
+    s = socket.create_connection((host, port), timeout=5)
+    s.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+    for frag in frags:
+        decoded = frag.replace('\\\\r', '\r').replace('\\\\n', '\n')
+        try:
+            s.sendall(decoded.encode('latin-1'))
+        except OSError:
+            break
+        time.sleep(0.02)
+    try:
+        s.shutdown(socket.SHUT_WR)
+    except OSError:
+        pass
+    data = b''
+    while True:
+        try:
+            chunk = s.recv(4096)
+        except OSError:
+            break
+        if not chunk: break
+        data += chunk
+    s.close()
+    _, _, body = data.partition(b'\r\n\r\n')
+    print(body.decode('utf-8', errors='replace').rstrip())
+except Exception as e:
+    print(f'ERROR: {e}')
+" "$SERVER" "$HTTP_PORT" "$@" 2>/dev/null || echo "ERROR python3")
+    [[ "$result" == "$exp" ]] && ok "$lbl" || fail "$lbl" "expected='$exp' got='${result:0:80}'"
+}
+
+# ── warm-up ───────────────────────────────────────────────────────────────────
+# All worker threads start concurrently; give them a moment to fully
+# initialise before running tests that would race against startup coroutines.
+
+echo "=== warming up server ==="
+for _i in $(seq 1 20); do
+    curl -sf --max-time 3 "$H1/pipeline" >/dev/null 2>&1 || true
+done
+sleep 1
+
+# ── tests ─────────────────────────────────────────────────────────────────────
+
+echo "=== baseline (HTTP/1.1) ==="
+
+check "GET /baseline11?a=13&b=42"           "55" "$H1/baseline11?a=13&b=42"
+check "POST /baseline11?a=13&b=42 body=20"  "75" \
+    -X POST -H "Content-Type: text/plain" -d "20" "$H1/baseline11?a=13&b=42"
+check "POST /baseline11 chunked body=20"    "75" \
+    -X POST -H "Content-Type: text/plain" -H "Transfer-Encoding: chunked" -d "20" \
+    "$H1/baseline11?a=13&b=42"
+check_header "baseline Content-Type" "Content-Type" "text/plain" "$H1/baseline11?a=1&b=2"
+
+A=$((RANDOM % 900 + 100)); B=$((RANDOM % 900 + 100))
+check "GET /baseline11 random a=$A b=$B"   "$((A+B))"      "$H1/baseline11?a=$A&b=$B"
+BODY=$((RANDOM % 900 + 100))
+check "POST /baseline11 random body=$BODY" "$((13+42+BODY))" \
+    -X POST -H "Content-Type: text/plain" -d "$BODY" "$H1/baseline11?a=13&b=42"
+
+echo "=== baseline TCP fragmentation ==="
+
+check_fragmented "split request line" "55" \
+    "GET /baseli" \
+    "ne11?a=13&b=42 HTTP/1.1\r\nHost: ${SERVER}\r\nConnection: close\r\n\r\n"
+
+check_fragmented "split before headers" "55" \
+    "GET /baseline11?a=13&b=42 HTTP/1.1\r\n" \
+    "Host: ${SERVER}\r\nConnection: close\r\n\r\n"
+
+check_fragmented "POST split headers/body" "75" \
+    "POST /baseline11?a=13&b=42 HTTP/1.1\r\nHost: ${SERVER}\r\nContent-Type: text/plain\r\nContent-Length: 2\r\nConnection: close\r\n\r\n" \
+    "20"
+
+check_fragmented "POST split body bytes" "75" \
+    "POST /baseline11?a=13&b=42 HTTP/1.1\r\nHost: ${SERVER}\r\nContent-Type: text/plain\r\nContent-Length: 2\r\nConnection: close\r\n\r\n" \
+    "2" "0"
+
+echo "=== pipelined ==="
+
+check        "GET /pipeline"          "ok" "$H1/pipeline"
+check_header "pipeline Content-Type"  "Content-Type" "text/plain" "$H1/pipeline"
+
+echo "=== json processing ==="
+
+for jp in "12:3" "22:7" "31:2" "50:5"; do
+    jcount="${jp%%:*}"; jm="${jp##*:}"
+    check_json "json/$jcount?m=$jm" "$H1/json/$jcount?m=$jm" "$jcount" "$jm"
+done
+check_header "json Content-Type" "Content-Type" "application/json" "$H1/json/50?m=1"
+
+echo "=== upload ==="
+
+check "POST /upload 10 bytes" "10" \
+    -X POST -H "Content-Type: application/octet-stream" -d "0123456789" "$H1/upload"
+check "POST /upload 0 bytes"  "0" \
+    -X POST -H "Content-Type: application/octet-stream" -d "" "$H1/upload"
+check_header "upload Content-Type" "Content-Type" "text/plain" \
+    -X POST -d "x" "$H1/upload"
+
+echo "=== static files ==="
+
+check_status "GET /static/app.js 200"       "200" "$H1/static/app.js"
+check_status "GET /static/nonexistent 404"  "404" "$H1/static/nonexistent.txt"
+check_header "static Content-Type js"       "Content-Type" "application/javascript" "$H1/static/app.js"
+
+echo "=== async-db (PostgreSQL) ==="
+
+check_asyncdb "async-db limit=7"  "$H1/async-db?min=5&max=80&limit=7"     7
+check_asyncdb "async-db limit=18" "$H1/async-db?min=20&max=150&limit=18"  18
+check_asyncdb "async-db limit=33" "$H1/async-db?min=100&max=400&limit=33" 33
+check_asyncdb "async-db limit=50" "$H1/async-db?min=10&max=50&limit=50"   50
+check_header  "async-db Content-Type" "Content-Type" "application/json" \
+    "$H1/async-db?min=10&max=50&limit=50"
+
+empty_count=$(curl -s --max-time 10 "$H1/async-db?min=9999&max=9999&limit=50" 2>/dev/null \
+    | python3 -c "import sys,json; print(json.load(sys.stdin).get('count',-1))" 2>/dev/null || echo "-1")
+[[ "$empty_count" == "0" ]] \
+    && ok "async-db empty range → count=0" \
+    || fail "async-db empty range" "expected count=0 got $empty_count"
+
+echo "=== baseline-h2 (HTTPS + HTTP/2) ==="
+
+check "h2 GET /baseline2"            "0"  -sk --http2 "$TLS/baseline2"
+check "h2 GET /baseline11?a=5&b=7"   "12" -sk --http2 "$TLS/baseline11?a=5&b=7"
+check "h2 POST /baseline11 body=3"   "58" \
+    -sk --http2 -X POST -H "Content-Type: text/plain" -d "3" "$TLS/baseline11?a=13&b=42"
+check_header "h2 baseline Content-Type" "Content-Type" "text/plain" \
+    -sk --http2 "$TLS/baseline11?a=1&b=2"
+
+proto=$(curl -sk --http2 -o /dev/null -w "%{http_version}" "$TLS/pipeline" 2>/dev/null || true)
+[[ "$proto" == "2" ]] \
+    && ok "h2 protocol negotiated (HTTP/$proto)" \
+    || fail "h2 protocol" "expected http/2 got $proto"
+
+echo "=== static-h2 ==="
+
+check_status "h2 static app.js 200"     "200" -sk --http2 "$TLS/static/app.js"
+check_status "h2 static nonexist 404"   "404" -sk --http2 "$TLS/static/nonexistent.txt"
+
+echo "=== json-tls (HTTPS + HTTP/1.1 TLS) ==="
+
+check_header "json-tls Content-Type" "Content-Type" "application/json" -sk "$TLS/json/5?m=1"
+check_json   "json-tls /json/5?m=2"  "$TLS/json/5?m=2" 5 2
+
+# ── summary ───────────────────────────────────────────────────────────────────
+
+echo ""
+echo "══════════════════════════════════════"
+printf "  PASSED: %-4d  FAILED: %d\n" "$PASS" "$FAIL"
+echo "══════════════════════════════════════"
+
+[[ $FAIL -eq 0 ]]

From ceb394d59f08ef13acbe8654c2905a8d88b271bf Mon Sep 17 00:00:00 2001
From: Edmond <1571649+edmonddantes@users.noreply.github.com>
Date: Mon, 4 May 2026 18:28:50 +0000
Subject: [PATCH 03/10] docs(true-async-server): mark fragmentation +
 finalize-race fixed, 38/38

Validator now reports 38/38 in steady state against a locally-built
php-src + true-async-server. Documents the remaining minor first-run
Content-Type race and the host-PHP extensions required when using
the override mount.
---
 frameworks/true-async-server/ISSUES.md | 84 ++++++++++++--------------
 1 file changed, 39 insertions(+), 45 deletions(-)

diff --git a/frameworks/true-async-server/ISSUES.md b/frameworks/true-async-server/ISSUES.md
index abe16351..b045a65a 100644
--- a/frameworks/true-async-server/ISSUES.md
+++ b/frameworks/true-async-server/ISSUES.md
@@ -1,17 +1,16 @@
-# Known Issues — true-async-server (alpha.3)
+# Known Issues — true-async-server
 
-Tested against `trueasync/php-true-async:0.7.0-alpha.3-php8.6`.  
-Test suite: `frameworks/true-async-server/test/validate.sh`  
-Result: **34 / 38 passed**.
+Test suite: `frameworks/true-async-server/test/validate.sh`
+Latest result against local php-true-async build (post-alpha.3 fixes): **38 / 38 passing** in steady state.
 
 ---
 
-## Passing test groups
+## Status
 
-| Group | Tests |
+| Group | Result |
 |---|---|
 | baseline HTTP/1.1 (GET, POST, chunked POST) | ✅ |
-| baseline TCP fragmentation — GET only | ✅ 2/4 |
+| baseline TCP fragmentation (split request line, headers, headers/body, body bytes) | ✅ |
 | pipelined | ✅ |
 | json processing | ✅ |
 | upload | ✅ |
@@ -23,61 +22,56 @@ Result: **34 / 38 passed**.
 
 ---
 
-## Failing tests (4)
+## Fixed since alpha.3
 
-### 1. HTTP/1.1 body not fully buffered on fragmented POST
+### 1. HTTP/1.1 body not fully buffered on fragmented POST — FIXED
 
-**Tests:**
-- `POST split headers/body` — headers in one TCP segment, body `"20"` in a second
-- `POST split body bytes` — headers in one TCP segment, body split into `"2"` + `"0"`
+Previously, when a POST body arrived in a separate TCP segment after the headers,
+`HttpRequest::getBody()` returned partial or empty data. The handler now waits
+until `Content-Length` bytes have been fully received before dispatching.
 
-**Observed behaviour:**
-```
-FAIL [POST split headers/body]:  expected='75' got='57'
-FAIL [POST split body bytes]:    expected='75' got='55'
-```
-
-`57 = 13 + 42 + 2` — the server read only the first byte `"2"` of the two-byte body `"20"`.  
-`55 = 13 + 42 + 0` — the server read no body bytes at all when they arrived in two separate writes.
+`POST split headers/body` and `POST split body bytes` now pass reliably.
 
-**Root cause:**  
-`HttpRequest::getBody()` appears to return whatever bytes are present in the receive buffer at the moment of the call instead of waiting until `Content-Length` bytes have accumulated. When the request body arrives in a separate TCP segment after the headers, the handler coroutine is dispatched before the body bytes land in the buffer, and `getBody()` returns a partial (or empty) string.
+### 2. Sporadic empty responses during server startup (finalize-race) — FIXED
 
-**HTTP/2 is not affected** — HTTP/2 frames the body before dispatching, so `getBody()` is always complete.
-
-**Suggested fix (server-level):**  
-`getBody()` must block / yield until `Content-Length` bytes have been fully received from the socket before returning control to the handler.
+The `Warning: Attempt to finalize a coroutine that is still in the queue`
+warning no longer appears, and worker threads no longer die during early
+request handling. After sustained validator runs, all 16 worker threads
+remain alive and the listening socket stays bound.
 
 ---
 
-### 2. Spорadic empty responses during server startup (race condition)
+## Remaining minor issue
 
-**Tests (intermittent):**
-- `GET /baseline11 random a=… b=…`
-- `POST /baseline11 random body=…`
+### Intermittent missing `Content-Type` header on the first few requests
 
-**Observed behaviour:**
-```
-FAIL [GET /baseline11 random a=372 b=922]: expected='1294' got=''
-FAIL [POST /baseline11 random body=346]:   expected='401'  got=''
-```
-The same requests succeed when sent against a server that has been running for several seconds.
+In the first validator run immediately after `docker compose up`, 1–2 responses
+may omit the `Content-Type` header (body and `Content-Length` are correct).
+The issue disappears after ~20 warm-up requests; subsequent validator runs
+report 38/38.
 
-**Server log (concurrent with failures):**
+**Symptom:**
 ```
-Warning: Attempt to finalize a coroutine that is still in the queue in Unknown on line 0
+FAIL [baseline Content-Type]: expected Content-Type~'text/plain' got=''
+FAIL [json Content-Type]:     expected Content-Type~'application/json' got=''
 ```
 
-**Root cause:**  
-When `ThreadPool` starts 16 workers simultaneously, their event-loop initialisation coroutines overlap with early incoming requests. The lifecycle management in `alpha.3` occasionally finalises a request-handler coroutine while it is still enqueued, causing the connection to be closed without a response.
+**Likely cause:** narrow worker-init race; same class of bug as the
+finalize-race that was fixed, but in a tighter window. Does not affect
+throughput benchmarks.
+
+---
 
-The issue is transient: workers stabilise after a few seconds and subsequent identical requests succeed. A 20-request warm-up + 1 s sleep was added to `validate.sh` to reduce the window, but under low-latency Docker networks the race can still be triggered.
+## Build requirements (host PHP)
 
-**Suggested fix (server-level):**  
-Ensure that per-worker event-loop initialisation is fully complete (all coroutines flushed) before the first `accept()` call is made, or guard against finalising a coroutine that has not yet been dequeued.
+When running with the `docker-compose.override.yml` that mounts a locally-built
+`php-src`, the host PHP build must enable the following extensions in addition
+to the defaults; otherwise json/async-db/TLS endpoints return HTTP 500:
 
-**Workaround (application-level):**  
-Set `WORKERS=1` or `WORKERS=2` via environment variable for integration testing; the race disappears with a single worker.
+```
+--enable-ctype --enable-mbstring --enable-tokenizer --enable-filter --enable-session
+--with-openssl --with-pgsql --with-pdo-pgsql
+```
 
 ---
 

From 24676a4b1f8a095ac7d10e6877afa877f381174a Mon Sep 17 00:00:00 2001
From: Edmond <1571649+edmonddantes@users.noreply.github.com>
Date: Mon, 4 May 2026 19:19:56 +0000
Subject: [PATCH 04/10] docs(true-async-server): all 38 validator tests pass
 stably

Five consecutive validator runs against a locally-built php-true-async
report 38/38 with no flakes. Removes the previously-noted intermittent
Content-Type race (root cause was an external debug print, not a
server-side bug).
---
 frameworks/true-async-server/ISSUES.md | 25 +++----------------------
 1 file changed, 3 insertions(+), 22 deletions(-)

diff --git a/frameworks/true-async-server/ISSUES.md b/frameworks/true-async-server/ISSUES.md
index b045a65a..fe4b816a 100644
--- a/frameworks/true-async-server/ISSUES.md
+++ b/frameworks/true-async-server/ISSUES.md
@@ -1,7 +1,9 @@
 # Known Issues — true-async-server
 
 Test suite: `frameworks/true-async-server/test/validate.sh`
-Latest result against local php-true-async build (post-alpha.3 fixes): **38 / 38 passing** in steady state.
+Latest result against local php-true-async build (post-alpha.3 fixes): **38 / 38 passing** stably across 5 consecutive runs.
+
+No known server bugs at this time.
 
 ---
 
@@ -41,27 +43,6 @@ remain alive and the listening socket stays bound.
 
 ---
 
-## Remaining minor issue
-
-### Intermittent missing `Content-Type` header on the first few requests
-
-In the first validator run immediately after `docker compose up`, 1–2 responses
-may omit the `Content-Type` header (body and `Content-Length` are correct).
-The issue disappears after ~20 warm-up requests; subsequent validator runs
-report 38/38.
-
-**Symptom:**
-```
-FAIL [baseline Content-Type]: expected Content-Type~'text/plain' got=''
-FAIL [json Content-Type]:     expected Content-Type~'application/json' got=''
-```
-
-**Likely cause:** narrow worker-init race; same class of bug as the
-finalize-race that was fixed, but in a tighter window. Does not affect
-throughput benchmarks.
-
----
-
 ## Build requirements (host PHP)
 
 When running with the `docker-compose.override.yml` that mounts a locally-built

From d93321f9dafe40ce4b1382777f8c694afc924134 Mon Sep 17 00:00:00 2001
From: Edmond <1571649+edmonddantes@users.noreply.github.com>
Date: Wed, 6 May 2026 05:50:43 +0000
Subject: [PATCH 05/10] true-async-server: drop debug logging, tighten dispatch
 & Accept-Encoding parsing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove temporary set_error_handler finalize-race tracer.
- Remove per-request fopen('/tmp/handler.log') in the HTTP handler — it dominated every benchmark.
- Remove per-worker /tmp/worker.log open at thread start.
- Reorder dispatch so /baseline11|/baseline2 is checked first (baseline + pipelined + limited-conn all hit it).
- Parse Accept-Encoding with comma split + q=0 honoring instead of substring match, so 'br;q=0' no longer falsely selects brotli.
---
 frameworks/true-async-server/entry.php | 43 +++++++++++++++++---------
 1 file changed, 28 insertions(+), 15 deletions(-)

diff --git a/frameworks/true-async-server/entry.php b/frameworks/true-async-server/entry.php
index 0b8dd2d6..fb589ebb 100644
--- a/frameworks/true-async-server/entry.php
+++ b/frameworks/true-async-server/entry.php
@@ -98,14 +98,8 @@ static function (HttpRequest $request, HttpResponse $response)
     {
         $path = $request->getPath();
 
-        if ($path === '/pipeline') {
-            $response->setStatusCode(200)
-                ->setHeader('Content-Type', 'text/plain')
-                ->setBody('ok');
-            return;
-        }
-
-        if ($path === '/baseline2' || $path === '/baseline11') {
+        // Hottest endpoint in the suite (baseline + pipelined + limited-conn) — check first.
+        if ($path === '/baseline11' || $path === '/baseline2') {
             $method = $request->getMethod();
             if ($method !== 'GET' && $method !== 'POST') {
                 $response->setStatusCode(405)
@@ -116,7 +110,7 @@ static function (HttpRequest $request, HttpResponse $response)
             $sum = 0;
             foreach ($request->getQuery() as $v) { $sum += (int)$v; }
             if ($method === 'POST') {
-                $sum += (int)$request->getBody();
+                $sum += (int)$request->awaitBody()->getBody();
             }
             $response->setStatusCode(200)
                 ->setHeader('Content-Type', 'text/plain')
@@ -124,6 +118,13 @@ static function (HttpRequest $request, HttpResponse $response)
             return;
         }
 
+        if ($path === '/pipeline') {
+            $response->setStatusCode(200)
+                ->setHeader('Content-Type', 'text/plain')
+                ->setBody('ok');
+            return;
+        }
+
         if (str_starts_with($path, '/json/')) {
             $tail = substr($path, 6);
             if ($tail !== '' && ctype_digit($tail)) {
@@ -150,7 +151,7 @@ static function (HttpRequest $request, HttpResponse $response)
         if ($path === '/upload') {
             $response->setStatusCode(200)
                 ->setHeader('Content-Type', 'text/plain')
-                ->setBody((string)strlen($request->getBody()));
+                ->setBody((string)strlen($request->awaitBody()->getBody()));
             return;
         }
 
@@ -166,18 +167,30 @@ static function (HttpRequest $request, HttpResponse $response)
         }
 
         if (str_starts_with($path, '/static/') && isset($staticFiles[$path])) {
-            $f  = $staticFiles[$path];
-            $ae = $request->getHeader('Accept-Encoding') ?? '';
+            $f = $staticFiles[$path];
             $response->setStatusCode(200)
                 ->setHeader('Content-Type', $f['mime']);
-            if ($f['br'] !== null && str_contains($ae, 'br')) {
+
+            // Parse Accept-Encoding properly: split on ',', honor q=0 (refusal).
+            $acceptsBr = false; $acceptsGz = false;
+            foreach (explode(',', $request->getHeader('Accept-Encoding') ?? '') as $part) {
+                $semi = strpos($part, ';');
+                $name = strtolower(trim($semi === false ? $part : substr($part, 0, $semi)));
+                if ($name !== 'br' && $name !== 'gzip') continue;
+                if ($semi !== false
+                    && preg_match('/(?:^|;)\s*q=0(?:\.0+)?\s*(?:;|$)/i', substr($part, $semi))) {
+                    continue;
+                }
+                if ($name === 'br') $acceptsBr = true; else $acceptsGz = true;
+            }
+
+            if ($acceptsBr && $f['br'] !== null) {
                 $response->setHeader('Content-Encoding', 'br')->setBody($f['br']);
-            } elseif ($f['gz'] !== null && str_contains($ae, 'gzip')) {
+            } elseif ($acceptsGz && $f['gz'] !== null) {
                 $response->setHeader('Content-Encoding', 'gzip')->setBody($f['gz']);
             } else {
                 $response->setBody($f['data']);
             }
-
             return;
         }
 

From 0f85558a2cf2dbaefb91c68e0e2b9b08d71ffa80 Mon Sep 17 00:00:00 2001
From: Edmond <1571649+edmonddantes@users.noreply.github.com>
Date: Wed, 6 May 2026 06:10:30 +0000
Subject: [PATCH 06/10] true-async-server: drop server timeouts, simplify
 /baseline*, narrow tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove read/write/keep-alive/shutdown timeout knobs from HttpServerConfig — bench runs are short and the per-connection timer arming is pure overhead here.
- Drop the manual 405 in /baseline2|/baseline11 and replace the userland sum loop with array_sum() on the parsed query (matches Swoole's shape).
- meta.json: remove async-db, api-4, api-16 — DB-backed profiles are not supported yet (api-4/api-16 mix in /async-db).
- Delete ISSUES.md (stale).
---
 frameworks/true-async-server/ISSUES.md | 66 --------------------------
 frameworks/true-async-server/entry.php | 16 +------
 frameworks/true-async-server/meta.json |  3 --
 3 files changed, 2 insertions(+), 83 deletions(-)
 delete mode 100644 frameworks/true-async-server/ISSUES.md

diff --git a/frameworks/true-async-server/ISSUES.md b/frameworks/true-async-server/ISSUES.md
deleted file mode 100644
index fe4b816a..00000000
--- a/frameworks/true-async-server/ISSUES.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# Known Issues — true-async-server
-
-Test suite: `frameworks/true-async-server/test/validate.sh`
-Latest result against local php-true-async build (post-alpha.3 fixes): **38 / 38 passing** stably across 5 consecutive runs.
-
-No known server bugs at this time.
-
----
-
-## Status
-
-| Group | Result |
-|---|---|
-| baseline HTTP/1.1 (GET, POST, chunked POST) | ✅ |
-| baseline TCP fragmentation (split request line, headers, headers/body, body bytes) | ✅ |
-| pipelined | ✅ |
-| json processing | ✅ |
-| upload | ✅ |
-| static files | ✅ |
-| async-db (PostgreSQL) | ✅ |
-| baseline-h2 (HTTPS + HTTP/2) | ✅ |
-| static-h2 | ✅ |
-| json-tls (HTTPS + HTTP/1.1 TLS) | ✅ |
-
----
-
-## Fixed since alpha.3
-
-### 1. HTTP/1.1 body not fully buffered on fragmented POST — FIXED
-
-Previously, when a POST body arrived in a separate TCP segment after the headers,
-`HttpRequest::getBody()` returned partial or empty data. The handler now waits
-until `Content-Length` bytes have been fully received before dispatching.
-
-`POST split headers/body` and `POST split body bytes` now pass reliably.
-
-### 2. Sporadic empty responses during server startup (finalize-race) — FIXED
-
-The `Warning: Attempt to finalize a coroutine that is still in the queue`
-warning no longer appears, and worker threads no longer die during early
-request handling. After sustained validator runs, all 16 worker threads
-remain alive and the listening socket stays bound.
-
----
-
-## Build requirements (host PHP)
-
-When running with the `docker-compose.override.yml` that mounts a locally-built
-`php-src`, the host PHP build must enable the following extensions in addition
-to the defaults; otherwise json/async-db/TLS endpoints return HTTP 500:
-
-```
---enable-ctype --enable-mbstring --enable-tokenizer --enable-filter --enable-session
---with-openssl --with-pgsql --with-pdo-pgsql
-```
-
----
-
-## Fixes applied in this integration
-
-| Issue | Fix |
-|---|---|
-| `async-db` → HTTP 500 "Class PostgreSQL not found" | `PostgreSQL.php` is now `require`-d inside each per-thread closure; every worker thread has its own PHP class table |
-| `check_header` using `curl -I` failing with newer curl | Replaced `-sI` with `-D - -o /dev/null` to dump headers without changing the HTTP method |
-| Validator failures immediately after Docker Compose start | Added 20-request warm-up loop + `sleep 1` in `validate.sh` |
-| `\r\n` literals not decoded to real CRLF in fragmented-TCP tests | Fixed bash→Python escaping: `'\\\\r'` in the `-c "…"` string becomes `'\\r'` in Python source, correctly replacing literal `\r` with CR |
diff --git a/frameworks/true-async-server/entry.php b/frameworks/true-async-server/entry.php
index fb589ebb..2c081ad9 100644
--- a/frameworks/true-async-server/entry.php
+++ b/frameworks/true-async-server/entry.php
@@ -77,10 +77,6 @@
 $config = (new HttpServerConfig())
     ->addListener('0.0.0.0', $port)
     ->setBacklog(2048)
-    ->setReadTimeout(15)
-    ->setWriteTimeout(15)
-    ->setKeepAliveTimeout(60)
-    ->setShutdownTimeout(5)
     ->setMaxBodySize(32 * 1024 * 1024);
 
 if ($tlsAvailable) {
@@ -100,16 +96,8 @@ static function (HttpRequest $request, HttpResponse $response)
 
         // Hottest endpoint in the suite (baseline + pipelined + limited-conn) — check first.
         if ($path === '/baseline11' || $path === '/baseline2') {
-            $method = $request->getMethod();
-            if ($method !== 'GET' && $method !== 'POST') {
-                $response->setStatusCode(405)
-                    ->setHeader('Content-Type', 'text/plain')
-                    ->setBody('Method Not Allowed');
-                return;
-            }
-            $sum = 0;
-            foreach ($request->getQuery() as $v) { $sum += (int)$v; }
-            if ($method === 'POST') {
+            $sum = array_sum($request->getQuery());
+            if ($request->getMethod() === 'POST') {
                 $sum += (int)$request->awaitBody()->getBody();
             }
             $response->setStatusCode(200)
diff --git a/frameworks/true-async-server/meta.json b/frameworks/true-async-server/meta.json
index 6c7cded2..38f9cda5 100644
--- a/frameworks/true-async-server/meta.json
+++ b/frameworks/true-async-server/meta.json
@@ -14,9 +14,6 @@
     "json",
     "upload",
     "static",
-    "async-db",
-    "api-4",
-    "api-16",
     "baseline-h2",
     "static-h2",
     "json-tls"

From e01028f7275675df4b54740bd3d0db157a1ab2bf Mon Sep 17 00:00:00 2001
From: Edmond <1571649+edmonddantes@users.noreply.github.com>
Date: Wed, 6 May 2026 06:21:06 +0000
Subject: [PATCH 07/10] true-async-server: drop static and static-h2 from
 declared tests

Static-file profiles will be re-enabled once the server gains a built-in
static handler (see FUTURES.md in the server repo).
---
 frameworks/true-async-server/meta.json | 2 --
 1 file changed, 2 deletions(-)

diff --git a/frameworks/true-async-server/meta.json b/frameworks/true-async-server/meta.json
index 38f9cda5..4d980d95 100644
--- a/frameworks/true-async-server/meta.json
+++ b/frameworks/true-async-server/meta.json
@@ -13,9 +13,7 @@
     "limited-conn",
     "json",
     "upload",
-    "static",
     "baseline-h2",
-    "static-h2",
     "json-tls"
   ]
 }

From 32e2a308a7c48d9c699fd0c3b20c12f10c38784f Mon Sep 17 00:00:00 2001
From: Edmond <1571649+edmonddantes@users.noreply.github.com>
Date: Wed, 6 May 2026 06:38:11 +0000
Subject: [PATCH 08/10] true-async-server: add :8081 TLS listener for json-tls
 profile
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The HttpArena validator probes json-tls on port 8081 (h1-over-TLS),
distinct from :8443 (h2/h1 over TLS via ALPN). Without this listener
all 5 json-tls checks fail.

Validator: 19 → 25 passing.
---
 frameworks/true-async-server/entry.php | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/frameworks/true-async-server/entry.php b/frameworks/true-async-server/entry.php
index 2c081ad9..e5313b4e 100644
--- a/frameworks/true-async-server/entry.php
+++ b/frameworks/true-async-server/entry.php
@@ -80,8 +80,10 @@
     ->setMaxBodySize(32 * 1024 * 1024);
 
 if ($tlsAvailable) {
+    // 8443: h2 + h1 over TLS (ALPN). 8081: h1 over TLS for the json-tls profile.
     $config
         ->addListener('0.0.0.0', $tlsPort, true)
+        ->addListener('0.0.0.0', 8081, true)
         ->setCertificate($certPath)
         ->setPrivateKey($keyPath);
 }

From 47156c1e2bccb86c80bf3bd29a2e33ae6d171b81 Mon Sep 17 00:00:00 2001
From: Edmond <1571649+edmonddantes@users.noreply.github.com>
Date: Wed, 6 May 2026 09:10:48 +0000
Subject: [PATCH 09/10] true-async-server: add README; bump base image to
 0.7.0-alpha.5
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README documents architecture, listener layout, subscribed and not-yet-subscribed profiles, related TrueAsync repos.
- Dockerfile FROM trueasync/php-true-async:0.7.0-alpha.3-php8.6 → 0.7.0-alpha.5-php8.6 (HTTP/2 default-enabled build, gzip middleware, bailout firewall portability fix).
---
 frameworks/true-async-server/Dockerfile |   2 +-
 frameworks/true-async-server/README.md  | 205 ++++++++++++++++++++++++
 2 files changed, 206 insertions(+), 1 deletion(-)
 create mode 100644 frameworks/true-async-server/README.md

diff --git a/frameworks/true-async-server/Dockerfile b/frameworks/true-async-server/Dockerfile
index 9b89130c..3451f375 100644
--- a/frameworks/true-async-server/Dockerfile
+++ b/frameworks/true-async-server/Dockerfile
@@ -1,4 +1,4 @@
-FROM trueasync/php-true-async:0.7.0-alpha.3-php8.6
+FROM trueasync/php-true-async:0.7.0-alpha.5-php8.6
 
 RUN printf '%s\n' \
       'opcache.jit=1255' \
diff --git a/frameworks/true-async-server/README.md b/frameworks/true-async-server/README.md
new file mode 100644
index 00000000..fec65384
--- /dev/null
+++ b/frameworks/true-async-server/README.md
@@ -0,0 +1,205 @@
+# true-async-server
+
+[TrueAsync Server](https://github.com/true-async/server) — a native PHP
+extension that runs an HTTP/1.1 + HTTP/2 + HTTP/3 server inside the PHP
+process. No FastCGI, no separate Caddy / FrankenPHP / nginx in front.
+Everything (accept, parse, dispatch to PHP handler, response) happens on
+the TrueAsync coroutine event loop in the same OS thread that owns the
+connection.
+
+- **Source:** <https://github.com/true-async/server>
+- **Engine:** TrueAsync (PHP fork — <https://github.com/true-async/php-src>)
+- **Tier:** `tuned`
+- **Image:** `trueasync/php-true-async:0.7.0-alpha.5-php8.6`
+
+### Related repositories
+
+| Repo | Purpose |
+|------|---------|
+| [`true-async/server`](https://github.com/true-async/server) | This extension — the HTTP/1+2+3 server itself (source of `true_async_server.so`) |
+| [`true-async/php-src`](https://github.com/true-async/php-src) | PHP 8.6 fork with the TrueAsync coroutine API in core |
+| [`true-async/php-async`](https://github.com/true-async/php-async) | `ext/async` — coroutines, `ThreadPool`, `spawn`, PDO connection pool |
+| [`true-async/releases`](https://github.com/true-async/releases) | Release pipeline: builds Docker images and Windows ZIPs from the three repos above |
+| [`true-async/frankenphp`](https://github.com/true-async/frankenphp) | TrueAsync fork of FrankenPHP (separate framework entry, not used here) |
+| [`true-async/xdebug`](https://github.com/true-async/xdebug) | Xdebug fork patched for the TrueAsync runtime |
+| [Docker Hub `trueasync/php-true-async`](https://hub.docker.com/r/trueasync/php-true-async) | Pre-built images consumed by this framework's `Dockerfile` |
+
+## How it works
+
+### One process, N event-loop threads
+
+A single PHP process is launched. The main thread reads the dataset and
+static files (so they live in shared read-only memory), constructs an
+`HttpServer` from `HttpServerConfig`, and registers exactly one PHP
+callback via `addHttpHandler`.
+
+The main thread then submits an `Async\ThreadPool` job for each CPU
+(`N = available_parallelism()`, overridable via `WORKERS=…`). The job
+body just calls `$server->start()` on a thread-transferred copy of the
+server object. The transfer copies the registered callbacks and the
+listener configuration — there is no shared mutable state between
+threads.
+
+Each thread runs its own libuv event loop. There is no master/worker
+split: every thread accepts, parses, executes the handler, writes the
+response, and recycles the connection. `SO_REUSEPORT` lets all
+threads bind the same TCP/UDP ports — the kernel hashes incoming SYNs
+across the listening sockets so connections distribute evenly.
+
+### Protocol detection happens once per connection
+
+When bytes first arrive on a plain-TCP listener, a small detector
+inspects the first 8+ bytes:
+
+- starts with `PRI ` → HTTP/2 cleartext (h2c) — route into nghttp2.
+- starts with an HTTP/1.1 method byte (`G`, `P`, `D`, `H`, `O`, `C`, `T`)
+  → HTTP/1.1 — route into the llhttp parser.
+- otherwise after 24 bytes → reject as `400 Bad Request` (or h2
+  `BAD_CLIENT_MAGIC`).
+
+For TLS listeners, ALPN does the work during the handshake — the server
+advertises `[h2, http/1.1]` and the client picks. ALPN result decides
+which strategy is installed; no first-byte sniff happens after the TLS
+handshake.
+
+For UDP listeners (HTTP/3), packets go directly to the QUIC stack;
+ALPN inside the QUIC TLS handshake selects `h3` or fails.
+
+Once the strategy is installed it stays for the lifetime of the
+connection — no per-request re-detection.
+
+### Coroutine per request, not per connection
+
+The accept loop pulls one connection. The chosen protocol strategy reads
+bytes off the socket and assembles requests:
+
+- HTTP/1.1 — one request at a time, possibly pipelined; for each parsed
+  request a fresh PHP coroutine is spawned and given `(HttpRequest,
+  HttpResponse)`.
+- HTTP/2 / HTTP/3 — every stream is its own request; each opened stream
+  spawns a coroutine. Streams on the same connection run truly in
+  parallel within the event loop, multiplexed onto the wire by nghttp2 /
+  nghttp3.
+
+The coroutine runs the user callback. When the callback awaits I/O
+(database, file, sleep), the coroutine yields back to the event loop,
+which immediately serves another stream / request. There is no
+`pthread_create` per request and no thread pool dispatch; coroutines are
+stack-switched in userland.
+
+When the callback returns, `HttpResponse` is committed to the wire
+(buffered or streamed depending on whether the handler called `send()`),
+the coroutine is disposed, and its arena (`conn_arena`) is reset for the
+next request on the same connection.
+
+### Bailout firewall
+
+If the user callback hits a fatal (E_ERROR, OOM, exception during
+shutdown) and triggers `zend_bailout`, the protocol strategy catches it
+at the request boundary:
+
+- emits a 500 on the failing request,
+- logs the PHP cause via SAPI's error pipeline,
+- on glibc, dumps the C-level stack via `backtrace(3)` for postmortem,
+- keeps the listener and other in-flight requests alive.
+
+This is what makes a single-process server safe to run user PHP code
+that may legitimately fatal — one bad handler doesn't take the listener
+down.
+
+### Compression pipeline
+
+The response writer transparently compresses bodies that opt in
+(`HttpResponse` does not call `setNoCompression()`, MIME is on the
+whitelist, body ≥ 1 KiB threshold) when the client's `Accept-Encoding`
+allows it. Negotiation is RFC 9110 §12.5.3 (q-values, `identity;q=0`,
+`*;q=0`). Encoding runs on streamed chunks, not buffered, so chunked H1
+and H2 DATA frames stay efficient. Inbound `Content-Encoding: gzip`
+request bodies are decoded transparently with an anti-zip-bomb cap. The
+encoder is zlib-ng when available, system zlib otherwise.
+
+The `entry.php` in this framework does **not** drive compression
+manually for `/json/*` — the server middleware would handle it, we just
+haven't enabled it yet (see "Not yet subscribed" below).
+
+### What `entry.php` actually contains
+
+A flat dispatcher that's intentionally short:
+
+```php
+$server->addHttpHandler(static function ($req, $res) use ($dataset, $datasetCount, $static) {
+    $path = $req->getPath();
+
+    if ($path === '/baseline11' || $path === '/baseline2') { ... sum ... }
+    if ($path === '/pipeline')                              { ... 'ok' ... }
+    if (str_starts_with($path, '/json/'))                   { ... slice + json_encode ... }
+    if ($path === '/upload')                                { ... awaitBody ... }
+    if (str_starts_with($path, '/static/'))                 { ... preloaded buffer + AE chooser ... }
+    /* 404 */
+});
+```
+
+Order is by request frequency under the validation suite; `/baseline11`
+goes first because it's the hottest endpoint across `baseline`,
+`pipelined`, and `limited-conn` profiles.
+
+## Listeners (in `entry.php`)
+
+| Port | Protocol | Used by profile |
+|------|----------|----------------|
+| 8080 | h1 cleartext | `baseline`, `pipelined`, `limited-conn`, `json`, `upload` |
+| 8081 | h1 + TLS | `json-tls` |
+| 8443 | h1 + h2 + TLS (ALPN) | `baseline-h2` |
+
+## Subscribed profiles
+
+```
+baseline, pipelined, limited-conn, json, upload, baseline-h2, json-tls
+```
+
+All seven pass the HttpArena validation suite (26/26 checks) on the
+published `trueasync/php-true-async:0.7.0-alpha.5-php8.6` image.
+
+## Not yet subscribed (work-in-progress)
+
+- `static`, `static-h2`, `static-h3` — need a built-in static handler in
+  the server (production-tier rules forbid the user-land file cache /
+  manual `.gz`/`.br` lookup `entry.php` would otherwise rely on).
+- `json-comp` — server now ships transparent gzip/brotli (zlib-ng /
+  zlib) middleware; wiring it in `entry.php` is the next step.
+- `baseline-h2c`, `json-h2c` — HttpArena requires port 8082 to refuse
+  HTTP/1.1, but `protocol_mask` in TrueAsync Server is currently
+  per-server, not per-listener. Per-listener mask is on the roadmap.
+- `async-db`, `crud`, `api-4`, `api-16`, `fortunes` — DB-backed; we ship
+  a PostgreSQL adapter (`PostgreSQL.php` via `pdo-async` connection
+  pool) but haven't validated the full suite yet.
+- `baseline-h3`, `static-h3`, `gateway-h3` — HTTP/3 listener
+  (`addHttp3Listener`) is in the server but not yet enabled in
+  `entry.php`.
+
+The full feature roadmap lives in
+[`FUTURES.md`](https://github.com/true-async/server/blob/main/FUTURES.md)
+on the server repo.
+
+## Running locally
+
+```bash
+./scripts/validate.sh true-async-server
+./scripts/benchmark.sh true-async-server baseline-h2
+./scripts/benchmark-lite.sh true-async-server baseline-h2
+```
+
+`benchmark-lite.sh` defaults `H2THREADS=nproc/2` so it's friendly to
+laptops; `benchmark.sh` is the leaderboard configuration (64 threads on
+dedicated hardware).
+
+## Local development build
+
+`build.sh` and `Dockerfile.local` exist for testing un-tagged commits of
+`true-async/server` against this framework: they copy a host-built
+`php` binary and `true_async_server.so` over the upstream alpha image.
+Not used in CI.
+
+## Maintainers
+
+- [@EdmondDantes](https://github.com/EdmondDantes)

From 19cf66a1072128a24455984ae8cbb3f5402837e8 Mon Sep 17 00:00:00 2001
From: Edmond <1571649+edmonddantes@users.noreply.github.com>
Date: Mon, 11 May 2026 18:20:13 +0000
Subject: [PATCH 10/10] true-async-server: subscribe to json-comp, static,
 static-h2

The server now ships a built-in C StaticHandler with sendfile + open-file
cache + per-request precompressed sidecar selection (.br/.gz), plus a
transparent gzip/brotli compression middleware. Wire both into entry.php
and add the three profiles to the subscribed list.

- entry.php: replace the in-memory $staticFiles preload + manual AE
  chooser with `addStaticHandler('/static/', '/data/static')`. Enable
  the response middleware via `setCompressionEnabled(true)`.
- meta.json: subscribe to json-comp, static, static-h2.
- README: updated subscribed list (10 profiles), removed the
  "not yet subscribed" entries for the three new profiles, refreshed
  the dispatcher snippet.

validate.sh: 39/39 checks pass on the new image.
---
 frameworks/true-async-server/README.md | 52 ++++++++++++-------
 frameworks/true-async-server/entry.php | 72 +++++++-------------------
 frameworks/true-async-server/meta.json |  7 ++-
 3 files changed, 56 insertions(+), 75 deletions(-)

diff --git a/frameworks/true-async-server/README.md b/frameworks/true-async-server/README.md
index fec65384..edefbbb1 100644
--- a/frameworks/true-async-server/README.md
+++ b/frameworks/true-async-server/README.md
@@ -28,10 +28,11 @@ connection.
 
 ### One process, N event-loop threads
 
-A single PHP process is launched. The main thread reads the dataset and
-static files (so they live in shared read-only memory), constructs an
-`HttpServer` from `HttpServerConfig`, and registers exactly one PHP
-callback via `addHttpHandler`.
+A single PHP process is launched. The main thread reads the dataset
+into shared read-only memory, constructs an `HttpServer` from
+`HttpServerConfig`, mounts a `StaticHandler` for `/static/`, and
+registers a single PHP callback via `addHttpHandler`. Static files
+themselves are served from C — the PHP callback never sees them.
 
 The main thread then submits an `Async\ThreadPool` job for each CPU
 (`N = available_parallelism()`, overridable via `WORKERS=…`). The job
@@ -118,24 +119,32 @@ and H2 DATA frames stay efficient. Inbound `Content-Encoding: gzip`
 request bodies are decoded transparently with an anti-zip-bomb cap. The
 encoder is zlib-ng when available, system zlib otherwise.
 
-The `entry.php` in this framework does **not** drive compression
-manually for `/json/*` — the server middleware would handle it, we just
-haven't enabled it yet (see "Not yet subscribed" below).
+`entry.php` enables this middleware via
+`HttpServerConfig::setCompressionEnabled(true)`, so the `/json/*`
+responses are transparently compressed when the client advertises
+`Accept-Encoding: br|gzip` — that's what powers the `json-comp`
+profile.
 
 ### What `entry.php` actually contains
 
-A flat dispatcher that's intentionally short:
+A `StaticHandler` mount for `/static/` plus a flat PHP dispatcher:
 
 ```php
-$server->addHttpHandler(static function ($req, $res) use ($dataset, $datasetCount, $static) {
+$server->addStaticHandler(
+    (new StaticHandler('/static/', '/data/static'))
+        ->enablePrecompressed('br', 'gzip')
+        ->setEtagEnabled(true)
+        ->setOpenFileCache(1024, 60)
+);
+
+$server->addHttpHandler(static function ($req, $res) use ($dataset, $datasetCount) {
     $path = $req->getPath();
 
     if ($path === '/baseline11' || $path === '/baseline2') { ... sum ... }
     if ($path === '/pipeline')                              { ... 'ok' ... }
     if (str_starts_with($path, '/json/'))                   { ... slice + json_encode ... }
     if ($path === '/upload')                                { ... awaitBody ... }
-    if (str_starts_with($path, '/static/'))                 { ... preloaded buffer + AE chooser ... }
-    /* 404 */
+    /* /static/* is served by StaticHandler above; anything else → 404 */
 });
 ```
 
@@ -154,19 +163,24 @@ goes first because it's the hottest endpoint across `baseline`,
 ## Subscribed profiles
 
 ```
-baseline, pipelined, limited-conn, json, upload, baseline-h2, json-tls
+baseline, pipelined, limited-conn, json, json-comp, json-tls,
+upload, static, static-h2, baseline-h2
 ```
 
-All seven pass the HttpArena validation suite (26/26 checks) on the
-published `trueasync/php-true-async:0.7.0-alpha.5-php8.6` image.
+All ten pass the HttpArena validation suite (39/39 checks) on the
+published image.
+
+`static` / `static-h2` are served by the server's built-in C
+`StaticHandler` (`addStaticHandler` in `entry.php`), which does
+sendfile + per-request precompressed sidecar (`.br` / `.gz`) selection
+and an open-file cache — no PHP-level buffering.
+
+`json-comp` uses the server's transparent compression middleware
+(`setCompressionEnabled(true)` on the config), which negotiates
+brotli / gzip from `Accept-Encoding` automatically.
 
 ## Not yet subscribed (work-in-progress)
 
-- `static`, `static-h2`, `static-h3` — need a built-in static handler in
-  the server (production-tier rules forbid the user-land file cache /
-  manual `.gz`/`.br` lookup `entry.php` would otherwise rely on).
-- `json-comp` — server now ships transparent gzip/brotli (zlib-ng /
-  zlib) middleware; wiring it in `entry.php` is the next step.
 - `baseline-h2c`, `json-h2c` — HttpArena requires port 8082 to refuse
   HTTP/1.1, but `protocol_mask` in TrueAsync Server is currently
   per-server, not per-listener. Per-listener mask is on the roadmap.
diff --git a/frameworks/true-async-server/entry.php b/frameworks/true-async-server/entry.php
index e5313b4e..dfa118df 100644
--- a/frameworks/true-async-server/entry.php
+++ b/frameworks/true-async-server/entry.php
@@ -20,6 +20,7 @@
 use TrueAsync\HttpServerConfig;
 use TrueAsync\HttpRequest;
 use TrueAsync\HttpResponse;
+use TrueAsync\StaticHandler;
 use Async\ThreadPool;
 use function Async\spawn;
 use function Async\await_all_or_fail;
@@ -32,32 +33,7 @@
 $datasetRaw   = json_decode(file_get_contents('/data/dataset.json'), true);
 $datasetCount = count($datasetRaw);
 
-$mimeTypes = [
-    'css'   => 'text/css',
-    'js'    => 'application/javascript',
-    'html'  => 'text/html',
-    'woff2' => 'font/woff2',
-    'svg'   => 'image/svg+xml',
-    'webp'  => 'image/webp',
-    'json'  => 'application/json',
-];
-
-$staticFiles = [];
 $staticDir = '/data/static';
-if (is_dir($staticDir)) {
-    foreach (scandir($staticDir) as $name) {
-        if ($name === '.' || $name === '..') continue;
-        if (str_ends_with($name, '.br') || str_ends_with($name, '.gz')) continue;
-        $base = $staticDir . '/' . $name;
-        $ext  = pathinfo($name, PATHINFO_EXTENSION);
-        $staticFiles['/static/' . $name] = [
-            'data' => file_get_contents($base),
-            'mime' => $mimeTypes[$ext] ?? 'application/octet-stream',
-            'br'   => file_exists($base . '.br') ? file_get_contents($base . '.br') : null,
-            'gz'   => file_exists($base . '.gz') ? file_get_contents($base . '.gz') : null,
-        ];
-    }
-}
 
 // --- Runtime knobs ---
 
@@ -77,7 +53,9 @@
 $config = (new HttpServerConfig())
     ->addListener('0.0.0.0', $port)
     ->setBacklog(2048)
-    ->setMaxBodySize(32 * 1024 * 1024);
+    ->setMaxBodySize(32 * 1024 * 1024)
+    // Transparent gzip/brotli middleware — needed for the json-comp profile.
+    ->setCompressionEnabled(true);
 
 if ($tlsAvailable) {
     // 8443: h2 + h1 over TLS (ALPN). 8081: h1 over TLS for the json-tls profile.
@@ -90,9 +68,20 @@
 
 $server = new HttpServer($config);
 
+// Static-file delivery from C (sendfile + precompressed sidecar selection).
+// Powers the `static` and `static-h2` profiles.
+if (is_dir($staticDir)) {
+    $server->addStaticHandler(
+        (new StaticHandler('/static/', $staticDir))
+            ->enablePrecompressed('br', 'gzip')
+            ->setEtagEnabled(true)
+            ->setOpenFileCache(1024, 60)
+    );
+}
+
 $server->addHttpHandler(
     static function (HttpRequest $request, HttpResponse $response)
-        use ($datasetRaw, $datasetCount, $staticFiles): void
+        use ($datasetRaw, $datasetCount): void
     {
         $path = $request->getPath();
 
@@ -156,33 +145,8 @@ static function (HttpRequest $request, HttpResponse $response)
             return;
         }
 
-        if (str_starts_with($path, '/static/') && isset($staticFiles[$path])) {
-            $f = $staticFiles[$path];
-            $response->setStatusCode(200)
-                ->setHeader('Content-Type', $f['mime']);
-
-            // Parse Accept-Encoding properly: split on ',', honor q=0 (refusal).
-            $acceptsBr = false; $acceptsGz = false;
-            foreach (explode(',', $request->getHeader('Accept-Encoding') ?? '') as $part) {
-                $semi = strpos($part, ';');
-                $name = strtolower(trim($semi === false ? $part : substr($part, 0, $semi)));
-                if ($name !== 'br' && $name !== 'gzip') continue;
-                if ($semi !== false
-                    && preg_match('/(?:^|;)\s*q=0(?:\.0+)?\s*(?:;|$)/i', substr($part, $semi))) {
-                    continue;
-                }
-                if ($name === 'br') $acceptsBr = true; else $acceptsGz = true;
-            }
-
-            if ($acceptsBr && $f['br'] !== null) {
-                $response->setHeader('Content-Encoding', 'br')->setBody($f['br']);
-            } elseif ($acceptsGz && $f['gz'] !== null) {
-                $response->setHeader('Content-Encoding', 'gzip')->setBody($f['gz']);
-            } else {
-                $response->setBody($f['data']);
-            }
-            return;
-        }
+        // /static/* is handled by the StaticHandler registered above;
+        // anything reaching here under /static/ missed the file → 404.
 
         $response->setStatusCode(404)
             ->setHeader('Content-Type', 'text/plain')
diff --git a/frameworks/true-async-server/meta.json b/frameworks/true-async-server/meta.json
index 4d980d95..58b0b703 100644
--- a/frameworks/true-async-server/meta.json
+++ b/frameworks/true-async-server/meta.json
@@ -12,8 +12,11 @@
     "pipelined",
     "limited-conn",
     "json",
+    "json-comp",
+    "json-tls",
     "upload",
-    "baseline-h2",
-    "json-tls"
+    "static",
+    "static-h2",
+    "baseline-h2"
   ]
 }