Vai al contenuto

Un server WebSocket in PHP che resta acceso: notifiche in tempo reale con ReactPHP e Redis

PHP nasce per un modello preciso: arriva una richiesta, il processo la serve, tutto viene buttato via. È un modello robusto, perché ogni errore muore con la richiesta, ma non si presta alle notifiche in tempo reale: per avvisare un utente che il suo ordine è stato spedito serve una connessione aperta per ore, non una risposta in pochi millisecondi. La soluzione più comune è il polling, il browser che chiede “novità?” ogni pochi secondi: semplice, ma costoso e comunque in ritardo.

Con le librerie giuste PHP può anche fare l’altro mestiere: un processo che resta acceso per settimane, gestisce migliaia di connessioni WebSocket e consegna gli eventi appena accadono. In questo articolo ne costruiamo uno con ReactPHP, Ratchet e Redis, e soprattutto vediamo le regole che lo tengono in piedi: un processo di lunga durata perdona molto meno di una richiesta HTTP. Tutto il codice è stato provato con PHP 8.3, Ratchet 0.4.4, ReactPHP 1.x, clue/redis-react 2.8 e Symfony Console 7.4.

L’architettura

Schema: l’applicazione pubblica l’evento su Redis, il server WebSocket con loop, registro e battito lo consegna ai browser del tenant giusto; dopo un’interruzione il browser recupera gli eventi persi via HTTP

I ruoli sono separati in modo netto:

  • l’applicazione (Symfony, Laravel o altro) resta l’unica fonte di verità: quando accade qualcosa salva l’evento nel database e lo pubblica su un canale Redis;
  • il server WebSocket è un processo separato che ascolta quel canale e inoltra ogni evento ai browser interessati. Non salva nulla e non conosce la logica di business;
  • il browser si collega, si autentica, dichiara a quali argomenti è interessato (ad esempio ordine:42) e, se perde qualcosa durante un’interruzione, lo chiede all’applicazione con una normale chiamata HTTP.

Questa divisione è la prima regola di robustezza: un server che non custodisce dati si può riavviare in qualunque momento senza perdere nulla.

Il modello di esecuzione: un loop, nessuna attesa

Il cuore di ReactPHP è il loop degli eventi: un unico thread che aspetta che succeda qualcosa (una connessione, un messaggio, un timer che scade, un evento da Redis) e chiama la funzione registrata per quell’evento. Tutto funziona finché ogni funzione termina in fretta. Una query SQL sincrona da 200 millisecondi, in questo modello, blocca per 200 millisecondi tutte le connessioni del processo. È il vincolo da tenere sempre presente.

Autenticazione con biglietti monouso

Il server WebSocket non dovrebbe avere un secondo sistema di login. L’approccio più semplice è far emettere all’applicazione principale, per l’utente già autenticato, un biglietto firmato con HMAC e valido pochi secondi; il browser lo invia come primo messaggio e il server lo verifica senza toccare il database:

final readonly class Biglietti
{
    public function __construct(private string $segreto, private int $durataSecondi = 30)
    {
    }

    public function emetti(string $utente, string $tenant, ?int $adesso = null): string
    {
        $dati = self::b64(json_encode([
            'u' => $utente,
            't' => $tenant,
            'exp' => ($adesso ?? time()) + $this->durataSecondi,
            'n' => bin2hex(random_bytes(8)), // rende ogni biglietto diverso dagli altri
        ], JSON_THROW_ON_ERROR));

        return $dati . '.' . self::b64(hash_hmac('sha256', $dati, $this->segreto, true));
    }

    /** @return array{utente: string, tenant: string, nonce: string}|null */
    public function verifica(string $biglietto, ?int $adesso = null): ?array
    {
        [$dati, $firma] = array_pad(explode('.', $biglietto, 2), 2, '');
        $attesa = self::b64(hash_hmac('sha256', $dati, $this->segreto, true));

        if (!hash_equals($attesa, $firma)) {
            return null;
        }

        $contenuto = json_decode(base64_decode(strtr($dati, '-_', '+/')), true);
        if (!is_array($contenuto) || ($contenuto['exp'] ?? 0) < ($adesso ?? time())) {
            return null;
        }

        return ['utente' => (string) $contenuto['u'], 'tenant' => (string) $contenuto['t'], 'nonce' => (string) $contenuto['n']];
    }

    private static function b64(string $binario): string
    {
        return rtrim(strtr(base64_encode($binario), '+/', '-_'), '=');
    }
}

Perché un biglietto e non il cookie di sessione? Perché il server WebSocket spesso gira su un altro host o un’altra porta, e perché leggere le sessioni dell’applicazione significherebbe accedere al loro archivio dentro il loop. Il biglietto viaggia una volta sola, scade in fretta e, come vedremo, il server lo accetta una volta sola. L’applicazione lo emette con un endpoint protetto (ad esempio POST /api/notifiche/biglietto) che chiama emetti() con l’utente e il tenant della sessione.

L’unico stato: chi ascolta cosa

In un processo che vive settimane, ogni array che cresce senza mai essere svuotato è una perdita di memoria. Il server tiene un solo stato: le connessioni autenticate e un indice “tenant + argomento → connessioni”. La chiave contiene il tenant, quindi un cliente non può mai ricevere gli eventi di un altro, anche se si iscrive allo stesso argomento. E ogni chiave vuota viene eliminata:

final class Registro
{
    /** @var \SplObjectStorage<ConnectionInterface, array{utente: string, tenant: string, argomenti: array<string, true>}> */
    private \SplObjectStorage $sessioni;

    /** @var array<string, array<int, ConnectionInterface>> chiave "tenant|argomento" → connessioni */
    private array $iscritti = [];

    public function iscrivi(ConnectionInterface $conn, string $argomento): void
    {
        $sessione = $this->sessioni[$conn];
        $sessione['argomenti'][$argomento] = true;
        $this->sessioni[$conn] = $sessione;
        $this->iscritti[$sessione['tenant'] . '|' . $argomento][spl_object_id($conn)] = $conn;
    }

    public function rimuovi(ConnectionInterface $conn): void
    {
        if (!$this->sessioni->contains($conn)) {
            return;
        }

        $sessione = $this->sessioni[$conn];
        foreach (array_keys($sessione['argomenti']) as $argomento) {
            $this->togliDaIndice($sessione['tenant'] . '|' . $argomento, $conn);
        }
        $this->sessioni->detach($conn);
    }

    /** @return iterable<ConnectionInterface> */
    public function destinatari(string $tenant, string $argomento): iterable
    {
        return $this->iscritti[$tenant . '|' . $argomento] ?? [];
    }

    private function togliDaIndice(string $chiave, ConnectionInterface $conn): void
    {
        unset($this->iscritti[$chiave][spl_object_id($conn)]);
        if (($this->iscritti[$chiave] ?? null) === []) {
            unset($this->iscritti[$chiave]); // senza questa riga l'indice cresce per sempre
        }
    }

    // autentica(), autenticata(), sessione(), disiscrivi(), tutte(), statistiche() seguono lo stesso schema
}

Il componente WebSocket

Ratchet si occupa dell’handshake e dei frame del protocollo; a noi resta da implementare MessageComponentInterface, cioè cosa fare all’apertura, a ogni messaggio, alla chiusura e in caso di errore. Due accorgimenti meritano attenzione. Il primo: una connessione appena aperta non appartiene a nessuno, quindi parte un timer che la chiude se non si autentica entro dieci secondi. Senza questo limite, chiunque potrebbe aprire migliaia di socket e lasciarli lì:

public function onOpen(ConnectionInterface $conn): void
{
    // la connessione non è ancora di nessuno: se non si autentica in tempo la chiudiamo
    $this->inAttesaDiAccesso[$conn] = $this->loop->addTimer($this->secondiPerAutenticarsi, function () use ($conn): void {
        $this->inAttesaDiAccesso->detach($conn);
        $this->invia($conn, ['tipo' => 'errore', 'motivo' => 'autenticazione_scaduta']);
        $conn->close();
    });
}

private function autentica(ConnectionInterface $conn, array $messaggio): void
{
    $dati = $messaggio['tipo'] === 'accesso' ? $this->biglietti->verifica((string) ($messaggio['biglietto'] ?? '')) : null;

    if ($dati === null || isset($this->nonceUsati[$dati['nonce']])) {
        $this->invia($conn, ['tipo' => 'errore', 'motivo' => 'accesso_non_valido']);
        $conn->close();
        return;
    }

    $this->nonceUsati[$dati['nonce']] = time() + 60; // il biglietto non potrà essere riusato
    $this->loop->cancelTimer($this->inAttesaDiAccesso[$conn]);
    $this->inAttesaDiAccesso->detach($conn);
    $this->registro->autentica($conn, $dati['utente'], $dati['tenant']);
    $this->invia($conn, ['tipo' => 'benvenuto', 'ultimoId' => $this->ultimoId[$dati['tenant']] ?? 0]);
}

Il secondo: i messaggi del client vanno trattati come input ostile. Il server scarta i messaggi più lunghi di 4 KB, accetta solo JSON con un campo tipo e, per l’iscrizione a un argomento, chiede il permesso a una PoliticaAccesso. La politica è un’interfaccia con un vincolo esplicito: deve rispondere senza I/O bloccante. Se servono permessi per singolo record, conviene tenerli in memoria e aggiornarli con un timer, invece di interrogare il database a ogni iscrizione.

La consegna di un evento è poi banale, e proprio per questo veloce:

public function distribuisci(array $evento): int
{
    $tenant = (string) $evento['tenant'];
    $this->ultimoId[$tenant] = max($this->ultimoId[$tenant] ?? 0, (int) $evento['id']);
    $consegne = 0;
    foreach ($this->registro->destinatari($tenant, (string) $evento['argomento']) as $conn) {
        $this->invia($conn, ['tipo' => 'evento'] + $evento);
        $consegne++;
    }

    return $consegne;
}

/** Battito periodico: tiene viva la connessione e comunica l'ultimo evento, per recuperare quelli persi. */
public function battito(): void
{
    foreach ($this->registro->tutte() as $conn) {
        $tenant = $this->registro->sessione($conn)['tenant'];
        $this->invia($conn, ['tipo' => 'battito', 'ultimoId' => $this->ultimoId[$tenant] ?? 0]);
    }

    $adesso = time();
    $this->nonceUsati = array_filter($this->nonceUsati, static fn (int $scadenza) => $scadenza >= $adesso);
}

Il battito fa tre lavori in uno. Tiene viva la connessione: molti bilanciatori e proxy chiudono i collegamenti inattivi dopo un minuto o poco più, quindi l’intervallo va scelto sotto quella soglia. Comunica al client l’ultimo evento noto, così il client capisce se ha perso qualcosa. E ripulisce l’elenco dei biglietti già usati, che altrimenti crescerebbe senza fine. Una nota: l’ultimo id è tenuto per tenant, perché un contatore globale rivelerebbe a ogni cliente il volume di attività degli altri.

Il processo: un comando della console

Il server è un comando Symfony Console. Riusa il container dell’applicazione (configurazione, logger, servizi) e non richiede un gestore di processi scritto a mano: a tenerlo acceso ci pensano systemd, Supervisor o Kubernetes. Il metodo execute() registra tutto e poi cede il controllo al loop:

protected function execute(InputInterface $input, OutputInterface $output): int
{
    $loop = Loop::get();
    $codiceUscita = Command::SUCCESS;
    $notifiche = new ServerNotifiche($loop, new Registro(), $this->biglietti, $this->politica, $this->logger, (float) $input->getOption('attesa-accesso'));

    // 1. il server WebSocket
    $socket = new SocketServer($input->getOption('ascolta'), [], $loop);
    new IoServer(new HttpServer(new WsServer($notifiche)), $socket, $loop);

    // 2. gli eventi dal backend, via Redis pub/sub
    $ferma = function (int $codice, string $motivo) use ($loop, $notifiche, $socket, &$codiceUscita): void {
        $this->logger->notice('Arresto del server', ['motivo' => $motivo]);
        $codiceUscita = $codice;
        $notifiche->chiudiTutto($motivo);
        $socket->close();
        $loop->futureTick(static fn () => $loop->stop()); // lascia partire i frame di chiusura
    };

    (new RedisFactory($loop))->createClient($input->getOption('redis'))->then(
        function (Redis $redis) use ($input, $notifiche, $ferma): void {
            $redis->on('message', function (string $canale, string $carico) use ($notifiche): void {
                $evento = json_decode($carico, true);
                if (is_array($evento) && isset($evento['id'], $evento['tenant'], $evento['argomento'])) {
                    $notifiche->distribuisci($evento);
                }
            });
            // senza Redis il server non riceve più nulla: meglio uscire e farsi riavviare
            $redis->on('close', static fn () => $ferma(Command::FAILURE, 'redis_disconnesso'));
            $redis->subscribe($input->getOption('canale'));
        },
        static fn (\Throwable $e) => $ferma(Command::FAILURE, 'redis_non_raggiungibile: ' . $e->getMessage()),
    );

    // 3. i timer di manutenzione
    $loop->addPeriodicTimer((float) $input->getOption('battito'), $notifiche->battito(...));
    $loop->addPeriodicTimer(300, $this->logger->reset(...)); // svuota i buffer del logger
    $loop->addPeriodicTimer(60, function () use ($notifiche): void {
        $this->logger->info('Stato', $notifiche->statistiche() + ['memoria_mb' => round(memory_get_usage() / 1048576, 1)]);
    });

    // 4. arresto ordinato
    foreach ([SIGINT, SIGTERM] as $segnale) {
        $loop->addSignal($segnale, static fn () => $ferma(Command::SUCCESS, 'riavvio'));
    }

    $output->writeln('In ascolto su ' . $input->getOption('ascolta'));
    $loop->run(); // da qui in poi tutto avviene per eventi

    return $codiceUscita;
}

Tre scelte vanno spiegate:

  • Fallire in modo rumoroso. Se Redis cade, il server non tenta di sopravvivere in uno stato a metà: chiude le connessioni ed esce con codice 1. Il supervisore lo riavvia, il client si riconnette e recupera ciò che ha perso. È più semplice e più affidabile di qualunque logica di riconnessione interna.
  • Arresto ordinato. Alla ricezione di SIGTERM, il segnale che systemd e Kubernetes inviano durante un rilascio, il server avvisa i client con un messaggio di chiusura prima di chiudere. Il client sa subito di doversi ricollegare, invece di scoprirlo al primo invio fallito.
  • Il logger va svuotato. Un handler come il FingersCrossedHandler di Monolog accumula i messaggi in un buffer, in attesa di un errore che ne giustifichi la scrittura: in una richiesta HTTP il buffer muore con il processo, in un demone cresce per sempre. Logger::reset() svuota i buffer di tutti gli handler che lo supportano, e un timer lo chiama ogni cinque minuti.

Avvio e prova manuale:

php bin/console app:notifiche:server --ascolta=0.0.0.0:8080 --redis=redis://127.0.0.1:6379

# da un altro terminale, simulando l'applicazione
redis-cli publish eventi '{"id":101,"tenant":"t1","argomento":"ordine:42","dati":{"stato":"spedito"}}'

Il client: riconnettersi e non perdere nulla

Metà della robustezza sta nel browser. Il client chiede un biglietto nuovo a ogni connessione, si iscrive ai suoi argomenti, si ricollega con un’attesa esponenziale (con un po’ di casualità, così dopo un riavvio i client non si ripresentano tutti nello stesso istante) e, dopo ogni riconnessione, chiede all’applicazione gli eventi successivi all’ultimo che ha ricevuto:

export class CanaleNotifiche {
  constructor({url, urlBiglietto, urlEventiPersi, argomenti = [], suEvento}) {
    Object.assign(this, {url, urlBiglietto, urlEventiPersi, suEvento});
    this.argomenti = new Set(argomenti);
    this.ultimoId = null;   // null finché non sappiamo da dove partire
    this.visti = new Set(); // id già consegnati: lo stesso evento può arrivare sia dal socket sia via HTTP
    this.tentativi = 0;
    this.chiuso = false;
  }

  async apri() {
    // il biglietto si chiede con la sessione dell'applicazione (cookie), un biglietto nuovo a ogni connessione
    const risposta = await fetch(this.urlBiglietto, {method: 'POST', credentials: 'include'});
    if (!risposta.ok) return this.riprova();
    const {biglietto} = await risposta.json();

    this.ws = new WebSocket(this.url);
    this.ws.onopen = () => this.ws.send(JSON.stringify({tipo: 'accesso', biglietto}));
    this.ws.onmessage = (m) => this.gestisci(JSON.parse(m.data));
    this.ws.onclose = () => this.riprova();
  }

  async gestisci(msg) {
    switch (msg.tipo) {
      case 'benvenuto':
        this.tentativi = 0;
        for (const a of this.argomenti) this.ws.send(JSON.stringify({tipo: 'iscrivi', argomento: a}));
        if (this.ultimoId === null) this.ultimoId = msg.ultimoId; // prima connessione: si parte da qui
        else await this.recupera();                              // riconnessione: chiediamo cosa ci siamo persi
        break;
      case 'battito':
        if (msg.ultimoId > (this.ultimoId ?? 0)) await this.recupera();
        break;
      case 'evento':
        if (this.visti.has(msg.id)) return;
        this.visti.add(msg.id);
        if (this.visti.size > 1000) this.visti.delete(this.visti.values().next().value);
        this.ultimoId = Math.max(this.ultimoId ?? 0, msg.id);
        this.suEvento(msg);
        break;
    }
  }

  // chiede via HTTP gli eventi successivi all'ultimo ricevuto: l'archivio dell'applicazione è la fonte di verità
  async recupera() {
    const argomenti = [...this.argomenti].join(',');
    const risposta = await fetch(`${this.urlEventiPersi}?dopo=${this.ultimoId ?? 0}&argomenti=${encodeURIComponent(argomenti)}`, {credentials: 'include'});
    if (!risposta.ok) return;
    for (const evento of await risposta.json()) await this.gestisci({tipo: 'evento', ...evento});
  }

  riprova() {
    if (this.chiuso) return;
    // attesa esponenziale con un po' di casualità, per non far riconnettere tutti nello stesso istante
    const attesa = Math.min(30000, 1000 * 2 ** this.tentativi++) * (0.5 + Math.random() / 2);
    setTimeout(() => this.apri(), attesa);
  }

  chiudi() { this.chiuso = true; this.ws?.close(); }
}

Un dettaglio emerso proprio durante le prove. La prima versione del client si fidava del numero di evento comunicato dal server al momento della riconnessione; ma un server appena riavviato riparte da zero, e gli eventi pubblicati durante il riavvio andavano persi senza che nessuno se ne accorgesse. Da qui la regola: dopo una riconnessione il client chiede comunque all’applicazione ciò che è successo dopo l’ultimo evento ricevuto, ed elimina i doppioni per id.

Le prove

Il server è stato provato con Redis reale e client WebSocket indipendenti. In sintesi:

Scenario Risultato
Evento del tenant t1 su ordine:42 consegnato solo ai client di t1 iscritti all’argomento; un client di t2 iscritto allo stesso argomento non lo riceve
Avviso a tutto il tenant (argomento *) ricevuto da tutte le connessioni del tenant, e solo da quelle
Connessione che non si autentica chiusa allo scadere del tempo, con il motivo
Biglietto riusato rifiutato e connessione chiusa
Iscrizione a un argomento non permesso rifiutata con accesso_negato
SIGTERM i client ricevono chiusura; il processo esce con codice 0
Caduta della connessione a Redis i client ricevono chiusura; il processo esce con codice 1
Riavvio del server con un evento pubblicato nel frattempo il client riceve tutti e tre gli eventi (prima, durante e dopo il riavvio)

Per la memoria, un test ha eseguito 50.000 cicli completi (apertura, autenticazione, iscrizione, consegna di un evento, chiusura). A fine prova il registro era vuoto e la memoria tornava al valore iniziale. L’unica struttura che cresce è l’elenco dei biglietti già usati, che il battito ripulisce dopo un minuto: è una crescita limitata e voluta, non una perdita.

Le trappole di un processo che non muore

  • Chiamate bloccanti. Ogni query sincrona, chiamata HTTP con cURL o lettura di file grandi ferma il loop. Se servono, usate client asincroni (ReactPHP ne ha per HTTP, MySQL e Redis) o spostate il lavoro nell’applicazione principale.
  • Strutture che crescono. Cache locali, elenchi di connessioni, contatori: ogni struttura ha bisogno di una regola di pulizia. Misurate la memoria con un timer e osservatela nel tempo.
  • Connessioni al database scadute. Se il processo usa una connessione al database, il server MySQL la chiude dopo un periodo di inattività. Riconnettersi su errore, o non tenere connessioni nel processo, evita errori misteriosi dopo una notte tranquilla.
  • Eccezioni non gestite. Un’eccezione dentro una callback può fermare il loop. Gestitele dove possono nascere, e lasciate che gli errori irrecuperabili terminino il processo: il supervisore lo riavvierà.
  • Più istanze. Con più server dietro un bilanciatore, Redis pub/sub consegna ogni evento a tutte le istanze, e ciascuna lo inoltra ai propri client: non serve instradamento particolare. Pub/sub non conserva i messaggi: se un’istanza è giù, perde gli eventi. È accettabile solo perché il client sa recuperarli dall’applicazione.
  • Il bilanciatore. Deve supportare l’upgrade a WebSocket e avere un timeout di inattività superiore all’intervallo del battito.

E le alternative?

Ratchet è maturo ma poco sviluppato negli ultimi anni; la stessa architettura si può realizzare con altri strumenti. Swoole/OpenSwoole offre un server WebSocket integrato con coroutine. Amp, dalla versione 3, usa le fiber di PHP 8.1 e permette di scrivere codice asincrono senza catene di promesse. RoadRunner, l’application server scritto in Go, delega i WebSocket a un server dedicato come Centrifugo. E se la comunicazione va solo dal server al browser, i Server-Sent Events sono più semplici dei WebSocket: un’unica risposta HTTP che resta aperta, con riconnessione automatica gestita dal browser. In ogni caso le regole restano le stesse: loop veloce, stato minimo, uscita pulita e un client che sa recuperare.

Conclusione

Un server PHP di lunga durata funziona se lo si progetta per morire bene. Niente stato importante in memoria, niente attese dentro il loop, ogni struttura con la sua pulizia, un supervisore che lo riavvia e un client che non dà per scontata nessuna consegna. Con questi vincoli, poche centinaia di righe sostituiscono il polling e consegnano le notifiche nel momento in cui accadono.