# blax-software/reactphp-kernel

A small, protocol-agnostic **ReactPHP backbone**: one long-lived process, one
event loop, one IPC primitive, and one signal/graceful-shutdown story that many
protocol servers attach to.

It is the shared foundation extracted from
[`blax-software/laravel-websockets`](https://git.blax.at/blax-software/laravel-websockets)
so that WebSockets, **WebRTC signaling/media**
([`blax-software/laravel-webrtc`](https://git.blax.at/blax-software/laravel-webrtc)),
and future protocols (SIP, ...) do not each re-implement the plumbing.

```
blax-software/reactphp-kernel        <- this package (the backbone)
   ├─ laravel-websockets             <- WS on the kernel
   └─ laravel-webrtc                 <- WebRTC signaling on the kernel
         └─ Rust/str0m media core    <- via ext-php-rs
```

## What's in the box

| Piece | Responsibility |
|---|---|
| `Kernel` | Owns the loop; registers `Server`s; installs signals; `run()` / graceful `stop()`. |
| `Contracts\Server` | An attachable protocol server: `boot(LoopInterface)` (non-blocking) + `shutdown()`. |
| `Server\SocketServerFactory` | Plain-TCP or TLS listening socket (no framework coupling). |
| `Ipc\SocketPairIpc` | Event-driven parent/child IPC over a Unix socket pair (no polling). |
| `Process\SignalHandler` | SIGINT/SIGTERM → graceful shutdown (no-op without ext-pcntl). |
| `Process\ChildReaper` | Reaps exited forked children (SIGCHLD + periodic backstop) — the reusable form of laravel-websockets #982. |

## Usage

```php
use BlaxSoftware\ReactPhpKernel\Kernel;

(new Kernel())
    ->reapChildren()                 // optional: auto-reap forked children
    ->register($webSocketServer)     // any Contracts\Server
    ->register($webRtcSignaling)
    ->onBoot(fn (Kernel $k) => /* warm caches, announce ready, ... */ null)
    ->run();                         // boots servers, installs signals, runs the loop (blocks)
```

Implement `Contracts\Server` to plug in a protocol:

```php
use BlaxSoftware\ReactPhpKernel\Contracts\Server;
use BlaxSoftware\ReactPhpKernel\Server\SocketServerFactory;
use React\EventLoop\LoopInterface;

final class MyServer implements Server
{
    private $socket = null;

    public function name(): string { return 'my-server'; }

    public function boot(LoopInterface $loop): void
    {
        $this->socket = SocketServerFactory::create('0.0.0.0:9000', $loop);
        $this->socket->on('connection', function ($conn) { /* ... */ });
    }

    public function shutdown(): void
    {
        $this->socket?->close();
    }
}
```

## Requirements

- PHP >= 8.1
- `react/event-loop`, `react/socket`, `react/stream`
- `ext-pcntl` (suggested) for signal handling + child reaping
- `ext-sockets` (suggested) for `SocketPairIpc`

## License

MIT © Blax Software