A fork-per-message child inherits the server's listening socket. A child
that outlived the server (a long-running handler such as an engine loop)
kept the port bound, so the restarted server failed with EADDRINUSE until
that child died.
- Track every forked child (Server\ChildProcesses). On hard and soft
shutdown, send SIGTERM to the ones still running, SIGKILL them after
websockets.shutdown.child_grace_seconds (default 2) and reap them. A PID is
signalled only while waitpid() confirms it is still an unreaped child, with
SIGCHLD blocked, so a recycled PID is never hit. Opt out with
websockets.shutdown.terminate_children = false.
- Right after fork the child closes its copy of the listening socket, so even
a stray child cannot hold the port. Only the fd is closed: the React server
is not closed, because removing it from an ext-ev/ext-event loop would edit
the epoll set the child shares with the parent.
- The child restores default SIGTERM/SIGINT/SIGCHLD handling. Under ext-ev
the inherited libev handlers swallowed SIGTERM in the child.
- A child that dies of a fatal error (out of memory, E_ERROR) now sends
<event>:error from a shutdown function (Server\ChildFatalErrorGuard,
#1462). A child that dies without any reply (killed by a signal, or the
shutdown function never ran) gets <event>:error from the parent, decided
once both its stream and its exit status are in
(Websocket\ChildMessageOutcome).
- Tests: real forks, signals and sockets for the shutdown, the port release
and the fatal reply; end to end through Handler::forkWithSocketPair(). The
test TestCase now stops a leftover broadcast socket, which made
ws_available() true for later tests.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- Introduced `helpers-and-testing.md` to document global helpers and WebsocketService class usage.
- Created `HandlerLifecycleTest.php` to test the full WebSocket handler lifecycle, including connection management, channel subscriptions, and message routing.
- Added `WebsocketServiceTest.php` to validate state tracking methods in WebsocketService, covering user authentication, channel tracking, and broadcast functionality.
Fabian @ Blax Software