Documentation menu

Multi-node Broker

By default php-via keeps all state in a single worker process. That's correct for most deployments: OpenSwoole handles thousands of concurrent SSE connections comfortably in one worker. When you need multiple workers on the same machine (CPU parallelism) or multiple servers, a broker fans out broadcast() calls so every worker can react to changes that happened on any other worker.

The broker carries broadcasts only. Passing an action or a download to the worker that holds the tab goes through OpenSwoole's worker pipe, whichever broker is set, and it stays within one server.

When do you need a broker?

ScenarioBrokerExternal dep?
Single worker (default)InMemoryBroker, without a withBroker() callNone
Multiple workers, same machineSwooleBroker, without a withBroker() callNone
Multiple servers / containersRedisBroker or NatsBrokerRedis / NATS

TAB scope is always fully isolated per-connection: no broker ever carries TAB broadcasts.

A worker publishes a scope at most once per broadcast flush, however often it was broadcast in between, and the messages a worker receives between two of its flushes share one re-render. See Broadcasting → When the update is sent.

InMemoryBroker (default with one worker)

No configuration needed. It is the broker of a single worker: it publishes nothing and costs nothing. Passing it to withBroker() together with withWorkerNum() above 1 makes start() throw a \RuntimeException, since the other workers would never hear a broadcast.

// These are equivalent with one worker
$config = new Config();
$config = (new Config())->withBroker(new InMemoryBroker());

SwooleBroker (default with several workers)

Uses OpenSwoole's built-in inter-worker pipe (Server::sendMessage / onPipeMessage) to fan out scope invalidations across all worker processes on the same machine. No external infrastructure required. With withWorkerNum() above 1 and no withBroker() call, php-via uses it by itself. GlobalState is backed by OpenSwoole\Table, shared memory that is allocated in the master process and mmap'd into every worker on fork.

use Mbolli\PhpVia\Broker\SwooleBroker;

$config = (new Config())
    ->withWorkerNum(\OpenSwoole\Util::getCPUNum());  // SwooleBroker by default

// The same, spelled out:
$config = (new Config())
    ->withWorkerNum(\OpenSwoole\Util::getCPUNum())
    ->withBroker(new SwooleBroker());

No sticky routing needed. Every worker sits behind the same port, so a load balancer cannot pick one anyway. A tab lives on the worker that holds its stream, and an action or a download that lands on another worker is passed there. Scoped signal values, GlobalState, session data and the client list are shared; PHP statics stay per worker, and server-owned TAB signals start over when a tab's stream reconnects after the worker that held it stopped. See Deployment → Same machine for the details and for the atomic update methods.

Limits (configurable). GlobalState is backed by an OpenSwoole\Table with a fixed capacity allocated at startup: 1 024 keys × 32 KB per value by default, keys up to 63 characters. Increase with Config::withGlobalStateTableSize(int $maxRows, int $maxValueBytes). The row count is a floor, not a ceiling. An \OverflowException is thrown when a value exceeds the configured size or the table is full.

RedisBroker

Uses Redis pub/sub to relay scope invalidations across nodes. Requires the ext-redis PHP extension and the coroutine hook for its connection: SWOOLE_HOOK_TCP, SWOOLE_HOOK_TLS with tls: true, or SWOOLE_HOOK_UNIX for a socket path. php-via's default hook_flags include all three, and start() throws if flags set with withSwooleSettings() leave out the one the broker needs, since every Redis call would then block the worker. See Coroutine hooks. The broker opens two coroutine connections per worker: one for publish, one for the subscribe loop.

Basic setup

use Mbolli\PhpVia\Broker\RedisBroker;

$config->withBroker(new RedisBroker('127.0.0.1', 6379));

Authentication

Pass $password for requirepass setups, or both $password and $username for Redis 6+ ACL users. Keep credentials out of source code: use environment variables or a secrets manager.

// requirepass (Redis default auth)
$config->withBroker(new RedisBroker(
    host: 'redis.internal',
    password: $_ENV['REDIS_PASSWORD'],
));

// ACL user (Redis 6+)
$config->withBroker(new RedisBroker(
    host: 'redis.internal',
    password: $_ENV['REDIS_PASSWORD'],
    username: 'php-via',
));

The minimal ACL permissions required are +subscribe +publish +ping &via:broadcast (or whichever channel name you configure).

TLS

// TLS: verify against system CA bundle
$config->withBroker(new RedisBroker(
    host: 'redis.internal',
    port: 6380,
    password: $_ENV['REDIS_PASSWORD'],
    tls: true,
));

// TLS with a custom CA (self-signed or internal PKI)
$config->withBroker(new RedisBroker(
    host: 'redis.internal',
    port: 6380,
    password: $_ENV['REDIS_PASSWORD'],
    tls: true,
    tlsCaFile: '/etc/ssl/my-ca.pem',
));

Custom channel

If multiple apps share the same Redis instance, give each app a distinct channel so their broadcast traffic doesn't cross-contaminate:

$config->withBroker(new RedisBroker(channel: 'myapp:broadcast'));

Full constructor signature

new RedisBroker(
    string  $host     = '127.0.0.1',
    int     $port     = 6379,
    ?string $password = null,   // #[SensitiveParameter]
    ?string $username = null,
    string  $channel  = 'via:broadcast',
    bool    $tls      = false,
    ?string $tlsCaFile = null,
)

NatsBroker

Uses a raw OpenSwoole coroutine TCP socket with the minimal NATS protocol: no extra PHP extension required beyond OpenSwoole itself. Good choice for containerised deployments where NATS already runs for other services.

Basic setup

use Mbolli\PhpVia\Broker\NatsBroker;

$config->withBroker(new NatsBroker('127.0.0.1', 4222));

Token authentication

$config->withBroker(new NatsBroker(
    host: 'nats.internal',
    authToken: $_ENV['NATS_TOKEN'],
));

TLS

// TLS: verify against system CA bundle (port 4243 is the TLS convention)
$config->withBroker(new NatsBroker(host: 'nats.internal', port: 4243, tls: true));

// TLS + custom CA + token
$config->withBroker(new NatsBroker(
    host: 'nats.internal',
    port: 4243,
    authToken: $_ENV['NATS_TOKEN'],
    tls: true,
    tlsCaFile: '/etc/ssl/my-ca.pem',
));

Custom subject

$config->withBroker(new NatsBroker(subject: 'myapp.broadcast'));

Full constructor signature

new NatsBroker(
    string  $host      = '127.0.0.1',
    int     $port      = 4222,
    ?string $authToken = null,          // #[SensitiveParameter]
    string  $subject   = 'via.broadcast',
    bool    $tls       = false,
    ?string $tlsCaFile = null,
)

Error observability

Both Redis and NATS brokers reconnect automatically with exponential backoff (1 s → 30 s cap). Register an error handler to receive a \Throwable on every connection drop:

$config->onBrokerError(function (\Throwable $e): void {
    // Safe summary only: do NOT log $e->getMessage() verbatim if it may
    // contain connection strings or credentials (OWASP: sensitive data exposure).
    error_log('[broker] connection lost: ' . get_class($e));
    $metrics->increment('broker.error');
});

The handler fires for every reconnect attempt. When the broker is in the backoff window, isConnected() returns false and the /_health endpoint reports "status":"degraded".

Health endpoint

Every php-via server exposes GET /_health, no configuration needed, no devMode gate. Use it with your load balancer, Kubernetes liveness probes, or uptime monitors:

curl https://myapp.example.com/_health
{
  "status": "ok",
  "version": "0.14.2",
  "broker": {
    "driver": "RedisBroker",
    "connected": true
  },
  "connections": {
    "contexts": 42,
    "sse": 38
  }
}

HTTP 200 when the broker is connected. HTTP 503 when the broker is in the reconnect window ("status":"degraded"). The response contains no IP addresses, credentials, or per-user data. connections counts the contexts and open streams of the worker that answered, not of the whole server. version is Via::VERSION.

Example Caddy health check to remove a degraded node from rotation:

reverse_proxy node1:3000 node2:3000 {
    health_uri      /_health
    health_interval 5s
    health_timeout  2s
    health_status   200
}

Upgrading nodes that share a broker

A broker message names a scope, and the form of some scopes can change between releases: in 0.14 a session's scope became a hash of its id. Upgrade every node that shares a broker together, so all of them name a scope the same way.

Connection count

Each php-via worker process opens its own connection(s) to the broker backend.

BrokerConnections per worker
InMemoryBroker0
SwooleBroker0 (in-process pipes)
RedisBroker2 (publish + subscribe)
NatsBroker1

Plan your Redis/NATS maxclients / connection limits accordingly. With withWorkerNum(N), multiply the per-worker count by N.

Next steps