<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see
* <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\tests;
use seekquarry\atto\Connection;
use seekquarry\atto\WebSite;
use seekquarry\atto\WindowUpdateFrame;
use seekquarry\yioop\library\UnitTest;
/**
* A WebSite that opens up the few protected HTTP/2 send-path pieces a
* test needs to drive a response by hand: setting up the per-stream
* flow-control windows, starting a paced response body, feeding one
* received frame in, draining whatever is queued to the client, and
* registering a fake connection so the drain can find it.
*/
class H2PacedResumeProbeWebSite extends WebSite
{
/**
* Sets up the connection's HTTP/2 send windows the way the server
* does right after the client's opening SETTINGS frame is read.
*
* @param object $conn connection holding the protocol state
* @param array $client_settings client settings, keyed by the
* HTTP/2 settings ids, used here to seed the per-stream
* initial window
* @return void
*/
public function initStreamWindows($conn, $client_settings)
{
$this->initH2SendWindows($conn, $client_settings);
}
/**
* Starts sending a response body on a stream, pacing it across the
* event loop when it is larger than the stream's send window.
*
* @param int $key connection identifier
* @param resource $socket socket the frames go out on
* @param object $conn connection holding the protocol state
* @param int $stream_id stream the body belongs to
* @param string $body the complete response body
* @return void
*/
public function startPacedBody($key, $socket, $conn, $stream_id,
$body)
{
$this->sendH2BodyPaced($key, $socket, $conn, $stream_id, $body);
}
/**
* Hands one received HTTP/2 frame to the server's frame handler,
* standing in for the event loop reading it off the wire.
*
* @param int $key connection identifier
* @param resource $socket socket the connection is on
* @param object $conn connection holding the protocol state
* @param object $frame the frame object to process
* @param string $payload the frame's raw body bytes
* @param int $length the frame body length in bytes
* @return mixed whatever the frame handler returns
*/
public function handleFrame($key, $socket, $conn, $frame, $payload,
$length)
{
return $this->processH2Frame($key, $socket, $conn, $frame,
$payload, $length);
}
/**
* Drains the connections that currently have unsent response bytes,
* writing as much as each socket will take, the way the event loop
* does once per pass.
*
* @return void
*/
public function drainResponses()
{
$this->processResponseStreams(
$this->out_streams[self::CONNECTION] ?? []);
}
/**
* Registers a connection and its socket so the drain step can find
* it, the way accepting a connection would.
*
* @param int $key connection identifier
* @param object $conn the connection object
* @param resource $socket the connection's socket
* @return void
*/
public function registerConnection($key, $conn, $socket)
{
$this->connections[$key] = $conn;
$this->in_streams[self::CONNECTION][$key] = $socket;
}
/**
* Reports whether the connection still has response bytes queued
* and not yet written to the client.
*
* @param int $key connection identifier
* @return bool true when bytes are still waiting to go out
*/
public function hasQueuedResponse($key)
{
return isset($this->out_streams[self::CONNECTION][$key])
&& isset($this->out_streams[self::DATA][$key]);
}
/**
* Reads and processes whatever has arrived on the connection's
* socket, the way the event loop does for a readable connection.
* This drives the real read path, including its handling of an
* end-of-file seen on the socket, rather than handing a frame
* straight to the frame handler.
*
* @param int $key connection identifier
* @param resource $socket the connection's socket to read from
* @return mixed whatever the read path returns
*/
public function readOnce($key, $socket)
{
return $this->parseH2Request($key, $socket);
}
}
/**
* A WebSite that records every frame the HTTP/2 read loop hands to the
* frame handler and reports the first one as a dispatched request, so a
* test can confirm the read loop keeps draining the buffer past that
* first dispatch instead of stopping there.
*/
class H2FrameDrainProbeWebSite extends WebSite
{
/**
* The stream ids of the frames the read loop handed off, in order,
* one entry per call.
* @var array
*/
public $seen = [];
/**
* Reads and processes whatever has arrived on the connection's
* socket, the way the event loop does for a readable connection.
*
* @param int $key connection identifier
* @param resource $socket the connection's socket to read from
* @return mixed whatever the read path returns
*/
public function readOnce($key, $socket)
{
return $this->parseH2Request($key, $socket);
}
/**
* Stands in for the real frame handler: records the frame's stream
* id and reports the very first frame as a dispatched request (a
* non-false return) and the rest as routine. The read loop must
* keep going after that first non-false return, so every frame in a
* single read shows up here.
*
* @param int $key connection identifier
* @param resource $connection the connection's socket
* @param object $conn connection holding the protocol state
* @param object $frame the parsed frame
* @param string $payload the frame's raw body bytes
* @param int $length the frame body length in bytes
* @return mixed true for the first frame, false afterward
*/
protected function processH2Frame($key, $connection, $conn, $frame,
$payload, $length)
{
$this->seen[] = $frame->stream_id;
return count($this->seen) === 1;
}
/**
* Registers a connection and its socket so the read path can find
* it, the way accepting a connection would.
*
* @param int $key connection identifier
* @param object $conn the connection object
* @param resource $socket the connection's socket
* @return void
*/
public function registerConnection($key, $conn, $socket)
{
$this->connections[$key] = $conn;
$this->in_streams[self::CONNECTION][$key] = $socket;
}
}
/**
* A WebSite that exposes the protected memory-sample timing check so a
* test can drive it with chosen clock values instead of the real time.
*/
class MemorySampleProbeWebSite extends WebSite
{
/**
* Sets the sample period the timing check reads, standing in for
* the value the running server takes from its config.
*
* @param int $seconds whole seconds between samples, zero for off
*/
public function setPeriod($seconds)
{
$this->memory_sample_period = $seconds;
}
/**
* Calls the protected timing check with a supplied current time.
*
* @param int $now pretend wall-clock time in whole seconds
* @return bool whether a memory sample is due at that time
*/
public function dueAt($now)
{
return $this->memorySampleDue($now);
}
}
/**
* Gathers the tests for the atto WebSite server in one place. Some cover
* the HTTP/2 send path: a large response must be delivered in full even
* when it does not fit the client's opening per-stream window, the body
* is sent up to the window then parks at a zero send window, and the
* rest must go out once the client returns credit with a WINDOW_UPDATE
* frame, guarding against the partial-transfer failure where the tail
* was never sent; another checks every request coalesced into one read
* is dispatched, not just the first. The HTTP/2 cases run over an
* in-memory socket pair, so they are deterministic and touch no network.
* The rest cover the switchable memory-usage sampling: how often a
* sample is due based on the period the server is configured with.
*
* @author Chris Pollett
*/
class WebSiteTest extends UnitTest
{
/**
* How many streams the closed-stream case opens, completes, and
* then sends a late WINDOW_UPDATE for. Chosen larger than the
* HTTP/2 max-concurrent-streams guard so that, before the fix,
* the run would have stashed enough stranded credit entries to
* trip the guard and close the connection.
*/
const CLOSED_STREAM_RUN = 120;
/**
* The socket pair used by a case, closed in tearDown so a case that
* throws part way through still releases its sockets.
* @var array
*/
public $sockets;
/**
* Forces the atto WebSite file to load before a case builds the
* server and frame objects, since that file is self-contained and
* defines WebSite, Connection, and the frame classes together.
*/
public function setUp()
{
class_exists('seekquarry\\atto\\WebSite');
$this->sockets = [];
}
/**
* Closes the socket pair a case opened.
*/
public function tearDown()
{
foreach ($this->sockets as $socket) {
if (is_resource($socket)) {
fclose($socket);
}
}
$this->sockets = [];
}
/**
* Builds a connection on one end of an in-memory socket pair with
* its HTTP/2 send windows set up like a real client handshake: a
* per-stream initial window the body will not fit in, and a large
* connection-level window so the connection window is never the
* limit.
*
* @param object $site the probe WebSite driving the exchange
* @param int $stream_window the client's per-stream initial window
* @return array [connection key, connection object, server socket]
*/
private function setUpConnection($site, $stream_window)
{
$pair = stream_socket_pair(STREAM_PF_UNIX, STREAM_SOCK_STREAM,
0);
$server = $pair[0];
$client = $pair[1];
stream_set_blocking($server, false);
stream_set_blocking($client, false);
$this->sockets = [$server, $client];
$key = (int)$server;
$connection = new Connection($server, false);
$connection->protocol = 'h2';
$connection->is_websocket = false;
$site->initStreamWindows($connection,
[WebSite::H2_SETTING_INITIAL_WINDOW => $stream_window]);
$connection->protocol_state['send_window'] = 12436774;
$site->registerConnection($key, $connection, $server);
return [$key, $connection, $server];
}
/**
* Drains queued response bytes to the socket while reading the
* client end, so a full socket buffer never blocks further writes,
* and returns all bytes read from the client end so far appended to
* what was already collected.
*
* @param object $site the probe WebSite to drain
* @param int $key connection identifier to drain
* @param resource $client the client end to read from
* @param string $collected bytes read on earlier drains
* @return string $collected plus the newly read bytes
*/
private function drainAndRead($site, $key, $client, $collected)
{
for ($pass = 0; $pass < 2000
&& $site->hasQueuedResponse($key); $pass++) {
$site->drainResponses();
while (($chunk = fread($client, 65536)) !== false
&& $chunk !== "") {
$collected .= $chunk;
}
}
while (($chunk = fread($client, 65536)) !== false
&& $chunk !== "") {
$collected .= $chunk;
}
return $collected;
}
/**
* Sums the payload bytes of the DATA frames addressed to one stream
* inside a buffer of serialized HTTP/2 frames, and reports whether
* any of them carried the END_STREAM flag. Each frame is a nine
* byte header (three byte length, one byte type, one byte flags,
* four byte stream id) followed by its payload.
*
* @param string $buffer serialized frame bytes read from the client
* @param int $stream the stream id whose DATA payload to total
* @return array [total DATA payload bytes, whether END_STREAM seen]
*/
private function countDataPayload($buffer, $stream)
{
$position = 0;
$total = 0;
$length = strlen($buffer);
$end_seen = false;
while ($position + 9 <= $length) {
$frame_length = (ord($buffer[$position]) << 16)
| (ord($buffer[$position + 1]) << 8)
| ord($buffer[$position + 2]);
$type = ord($buffer[$position + 3]);
$flags = ord($buffer[$position + 4]);
$frame_stream = ((ord($buffer[$position + 5]) & 0x7f) << 24)
| (ord($buffer[$position + 6]) << 16)
| (ord($buffer[$position + 7]) << 8)
| ord($buffer[$position + 8]);
$position += 9;
if ($position + $frame_length > $length) {
break;
}
if ($type === 0x00 && $frame_stream === $stream) {
$total += $frame_length;
if ($flags & 0x01) {
$end_seen = true;
}
}
$position += $frame_length;
}
return [$total, $end_seen];
}
/**
* A response larger than the client's per-stream window is sent up
* to the window, parks, and then the rest goes out after a
* WINDOW_UPDATE returns credit, so the client receives the whole
* body with the final DATA frame marked END_STREAM.
*/
public function pacedResumeDeliversWholeBodyTestCase()
{
$site = new H2PacedResumeProbeWebSite("/");
list($key, $connection, $server) =
$this->setUpConnection($site, 131072);
$client = $this->sockets[1];
$stream = 15;
$body = str_repeat("A", 185349);
$site->startPacedBody($key, $server, $connection, $stream,
$body);
$received = $this->drainAndRead($site, $key, $client, "");
list($first_total, ) =
$this->countDataPayload($received, $stream);
$this->assertEqual(131072, $first_total,
'only the first window goes out before any credit returns');
$frame = new WindowUpdateFrame($stream);
$payload = pack("N", 12451840);
$site->handleFrame($key, $server, $connection, $frame,
$payload, 4);
$received = $this->drainAndRead($site, $key, $client, $received);
list($total, $end_seen) =
$this->countDataPayload($received, $stream);
$this->assertEqual(strlen($body), $total,
'the whole body reaches the client after the window update');
$this->assertTrue($end_seen,
'the final data frame carries the end of stream flag');
}
/**
* A response that fits the client's per-stream window is sent in one
* burst, reaching the client whole with the final DATA frame marked
* END_STREAM and needing no WINDOW_UPDATE.
*/
public function oneBurstDeliversWholeBodyTestCase()
{
$site = new H2PacedResumeProbeWebSite("/");
list($key, $connection, $server) =
$this->setUpConnection($site, 131072);
$client = $this->sockets[1];
$stream = 7;
$body = str_repeat("B", 40000);
$site->startPacedBody($key, $server, $connection, $stream,
$body);
$received = $this->drainAndRead($site, $key, $client, "");
list($total, $end_seen) =
$this->countDataPayload($received, $stream);
$this->assertEqual(strlen($body), $total,
'a body within the window is delivered in one burst');
$this->assertTrue($end_seen,
'the final data frame carries the end of stream flag');
}
/**
* The window-update credit is read off the socket through the real
* read path, and the client then closes its send side. Reading the
* credit must resume the parked body, and the end-of-file the close
* raises must not tear the stream down while the rest of the body is
* still queued, so the client receives the whole body with the final
* DATA frame marked END_STREAM. This guards the partial-transfer
* failure where a stalled response, woken only when the socket next
* went readable, was dropped at that wake because end-of-file was
* treated as a reason to close even though bytes were still pending.
*/
public function readCreditThenKeepsFlushingPastEofTestCase()
{
$site = new H2PacedResumeProbeWebSite("/");
list($key, $connection, $server) =
$this->setUpConnection($site, 131072);
$client = $this->sockets[1];
$stream = 15;
$body = str_repeat("A", 185349);
$site->startPacedBody($key, $server, $connection, $stream,
$body);
$received = $this->drainAndRead($site, $key, $client, "");
list($first_total, ) =
$this->countDataPayload($received, $stream);
$this->assertEqual(131072, $first_total,
'only the first window goes out before any credit returns');
$increment = 12451840;
$update = chr(0) . chr(0) . chr(4) . chr(0x08) . chr(0)
. pack("N", $stream & 0x7fffffff) . pack("N", $increment);
fwrite($client, $update);
stream_socket_shutdown($client, STREAM_SHUT_WR);
$site->readOnce($key, $server);
$site->readOnce($key, $server);
$received = $this->drainAndRead($site, $key, $client, $received);
list($total, $end_seen) =
$this->countDataPayload($received, $stream);
$this->assertEqual(strlen($body), $total,
'the whole body still reaches the client after the close');
$this->assertTrue($end_seen,
'the final data frame carries the end of stream flag');
}
/**
* Builds the wire bytes of one HTTP/2 frame: a nine byte header
* (three byte length, one byte type, one byte flags, four byte
* stream id) followed by the payload. The type here is DATA, which
* is enough for a test that only checks the read loop hands each
* framed-off chunk to the frame handler.
*
* @param int $stream the stream id to put in the frame header
* @param string $payload the frame body bytes
* @return string the serialized frame
*/
private function dataFrameBytes($stream, $payload)
{
$length = strlen($payload);
$header = chr(($length >> 16) & 0xff)
. chr(($length >> 8) & 0xff)
. chr($length & 0xff)
. chr(0x00)
. chr(0x00)
. pack("N", $stream & 0x7fffffff);
return $header . $payload;
}
/**
* Two requests that arrive together in a single read must both be
* handed off to the frame handler, not just the first. This guards
* the failure where, after one read carried several streams'
* frames, only the first stream got a response and the rest hung
* because nothing was left to wake the loop and read them.
*/
public function readDispatchesEveryRequestInOneReadTestCase()
{
$site = new H2FrameDrainProbeWebSite("/");
$pair = stream_socket_pair(STREAM_PF_UNIX, STREAM_SOCK_STREAM,
0);
$server = $pair[0];
$client = $pair[1];
stream_set_blocking($server, false);
stream_set_blocking($client, false);
$this->sockets = [$server, $client];
$key = (int)$server;
$connection = new Connection($server, false);
$connection->protocol = 'h2';
$connection->is_websocket = false;
$connection->protocol_state = [];
$site->registerConnection($key, $connection, $server);
$first = $this->dataFrameBytes(1, "abc");
$second = $this->dataFrameBytes(3, "def");
fwrite($client, $first . $second);
$site->readOnce($key, $server);
$this->assertEqual([1, 3], $site->seen,
'both requests arriving in one read are handed off, not '
. 'only the first');
}
/**
* With no period configured, memory sampling stays off and the
* check never reports a sample as due, however much time passes.
*/
public function memorySampleOffWhenUnsetTestCase()
{
$site = new MemorySampleProbeWebSite("/");
$this->assertTrue(!$site->dueAt(1000),
"sampling is off when no period is configured");
$this->assertTrue(!$site->dueAt(500000),
"still off no matter how much time passes");
}
/**
* With a period of zero, which is how an operator turns the feature
* back off, the check still never reports a sample as due.
*/
public function memorySampleOffWhenZeroTestCase()
{
$site = new MemorySampleProbeWebSite("/");
$site->setPeriod(0);
$this->assertTrue(!$site->dueAt(1000),
"a period of zero turns sampling off");
}
/**
* With a positive period the first check is due, further checks are
* not due until the period has passed, and then become due again.
*/
public function memorySampleFiresEveryPeriodTestCase()
{
$site = new MemorySampleProbeWebSite("/");
$site->setPeriod(10);
$this->assertTrue($site->dueAt(1000),
"the first sample is due");
$this->assertTrue(!$site->dueAt(1005),
"a sample is not due before the period elapses");
$this->assertTrue($site->dueAt(1010),
"a sample is due once the period has elapsed");
$this->assertTrue(!$site->dueAt(1011),
"a sample is not due again right away");
}
/**
* Late WINDOW_UPDATE frames for streams the server has already
* finished and closed - which a browser sends as it drains each
* completed response - are ignored rather than stashed as
* pending credit, so a connection that serves a long run of
* responses (a video fetched range by range) never accumulates
* one stranded credit entry per closed stream and never trips
* the pending-credit guard that would close the connection.
*/
public function closedStreamWindowUpdateForClosedStreamIgnoredTestCase()
{
$site = new H2PacedResumeProbeWebSite("/");
list($key, $connection, $server) =
$this->setUpConnection($site, 131072);
$client = $this->sockets[1];
$closed_count = self::CLOSED_STREAM_RUN;
for ($index = 0; $index < $closed_count; $index++) {
$stream = 1 + 2 * $index;
$site->startPacedBody($key, $server, $connection, $stream,
"a small whole body that completes at once");
$this->drainAndRead($site, $key, $client, "");
$frame = new WindowUpdateFrame($stream);
$site->handleFrame($key, $server, $connection, $frame,
pack("N", 65536), 4);
}
$credit = $connection->protocol_state[
'pending_stream_window_credit'] ?? [];
$this->assertEqual(0, count($credit),
'no credit is stashed for streams that already closed');
$this->assertTrue($site->connection($key) !== null,
'the connection is not torn down by a guard tripping');
}
/**
* A WINDOW_UPDATE that arrives for a stream the server has opened
* but not yet begun responding on is still held as pending credit
* and still applied when the response starts, so a browser that
* enlarges a stream's window the instant it opens (the grant that
* lets a larger-than-window page go out in full) is unaffected by
* the closed-stream check.
*/
public function preGrantForOpenStreamStillAppliedTestCase()
{
$site = new H2PacedResumeProbeWebSite("/");
list($key, $connection, $server) =
$this->setUpConnection($site, 65536);
$client = $this->sockets[1];
$stream = 7;
$frame = new WindowUpdateFrame($stream);
$site->handleFrame($key, $server, $connection, $frame,
pack("N", 65536), 4);
$credit = $connection->protocol_state[
'pending_stream_window_credit'] ?? [];
$this->assertEqual(65536, $credit[$stream] ?? 0,
'a pre-grant for an open stream is held, not ignored');
$body = str_repeat("B", 200000);
$site->startPacedBody($key, $server, $connection, $stream,
$body);
$received = $this->drainAndRead($site, $key, $client, "");
list($first_total, ) =
$this->countDataPayload($received, $stream);
$this->assertEqual(131072, $first_total,
'the held pre-grant is added to the initial window so two '
. 'windows worth go out before any further credit');
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software