Skip to content

Bound binlog socket reads with an optional read timeout - #158

Open
cyppe wants to merge 2 commits into
krowinski:masterfrom
cyppe:fix/bounded-socket-reads
Open

cyppe wants to merge 2 commits into
krowinski:masterfrom
cyppe:fix/bounded-socket-reads

Conversation

@cyppe

@cyppe cyppe commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Socket gets an optional timeout: new Socket(30.0), passed to MySQLReplicationFactory through its existing ?SocketInterface $socket argument. The default is 0, which keeps today's unlimited waits, so nothing changes unless you opt in. With a timeout, connect, each read and each write fail with a SocketException after that many seconds without progress. A packet that keeps arriving, however slowly, is still read whole, and a handled signal (EINTR) doesn't restart the timeout.

Why: on a busy MySQL 8.4 binlog stream, a connection died once without the reader noticing and our consumer hung for about two hours. When no FIN or RST arrives, socket_recv(..., MSG_WAITALL) blocks with no deadline, and the consumer stops with no error, so nothing reconnects. TCP keepalive helps only where the kernel settings are short, and it isn't an application deadline. The source sends an event or a heartbeat at least once per heartbeatPeriod, so a timeout of a few periods turns that silence into a SocketException, which the caller can treat like any other disconnect and reconnect from its last position. We have run this in production since October.

Two smaller fixes in the same class, because the timeout depends on them:

  • Every socket call is silenced and reports its failure as a SocketException (new codes 1001 to 1004 for read, write and connect timeouts and a refused timeout option, chosen above 1000 so they can't collide with an errno). Before, a failing socket_recv()/socket_write() also raised a PHP warning, which a framework error handler (Laravel's, for example) turns into an ErrorException before the SocketException is thrown, so the reconnect path never ran.
  • A payload of exactly 16,777,215 bytes (or a multiple) ends with an empty packet. readFromSocket(0) called socket_recv() with length 0, which returns false without an error code, so it failed with SocketException("Success", 0) and the same event was replayed on every reconnect. It now returns ''.

Writes resume after a short count instead of treating it as success, and the error code comes from socket_last_error($this->socket) instead of the global last error.

Tests: 19 new unit tests in tests/Unit/Socket/SocketTest.php, against local socket pairs, no MySQL needed: a silent peer fails within the timeout, a slow but live packet is read whole, a partly read packet that stops fails, clean and reset disconnects, recurring signals during a read or a write, the empty last packet, a large write to a slow reader, invalid timeouts, and a subclass that doesn't call the parent constructor keeps no timeout. Rebased onto master at ac88d1a (with #156). Unit suite: OK (270 tests, 603 assertions) on PHP 8.4. PHPStan: no errors. ECS: no findings in the changed files (ecs check on master already reports 10 in other files, which I left alone).

🤖 Generated with Claude Code

Socket takes an optional timeout (default 0, which keeps today's unlimited
waits). With a timeout, connect, every read and every write fail with a
SocketException after that long without progress, so a connection that
dies silently (no FIN or RST) no longer blocks the binlog reader forever.
A packet that keeps arriving, however slowly, is still read whole, and a
handled signal does not restart the timeout.

Every socket failure is now reported as a SocketException without a PHP
warning, so a framework error handler cannot turn it into an
ErrorException that bypasses the caller's reconnect logic. A payload whose
last packet is empty (a length of exactly 16,777,215 bytes or a multiple)
is read instead of failing with SocketException("Success", 0).
The big-endian job runs the unit suite in a stock php:8.4-cli image without
pcntl or sockets. The skip in setUp still ran tearDown, whose pcntl_alarm(0)
then failed every test. Class-level RequiresPhpExtension skips before setUp
and tearDown. The two stalled-write tests now send 32 MiB instead of 64 MiB,
which still exceeds loopback socket buffers and fits the default 128M
memory_limit.
@cyppe

cyppe commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

Pushed 91287d7: the socket tests now skip through #[RequiresPhpExtension] where pcntl, posix or sockets is missing (the s390x job's stock php:8.4-cli has neither pcntl nor sockets; the old skip in setUp still ran tearDown, which called pcntl_alarm()). The big-endian job is green, and the socket tests still run in the PHP 8.3–8.5 jobs.

The five PHP 8.2 / * jobs fail in composer install, independently of this PR: require-dev has phpunit/phpunit: ^12.0, and PHPUnit 12 requires PHP >= 8.3. Master's last 8.2 runs passed only because a cached vendor/ skipped the install step; any new run without that cache fails the same way. Since the README still lists PHP 8.2, one option is "phpunit/phpunit": "^11.5 || ^12.0"; the other is dropping 8.2 from the matrix and raising php to >=8.3. Happy to open a small separate PR for whichever you prefer.

@cyppe

cyppe commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

Opened #159 for the PHP 8.2 install failure (allows PHPUnit 11.5 alongside 12, so 8.2 support stays).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant