fepli
deen
EntwicklerSelbst hostenEnterprise

Live-Aktualisierung

Mit der Live-Aktualisierung zeigen offene Seiten eine Änderung in dem Moment, in dem sie geschieht: die freien Plätze in der Angebotsliste der Website, und im Admin-Panel die Plätze, Wartelisten und Anmeldungen. fepli sagt es den Browsern über einen Mercure-Hub, der im Web-Container läuft. Ohne ihn arbeiten die Seiten wie bisher und fragen die Zahlen beim Laden ab.

Was sich ändert

  • Die Angebotsliste der Website. Die freien Plätze und das Etikett „Sofort buchbar“ ändern sich in der offenen Seite, sobald Familien sich anmelden, abmelden oder einen Platz bekommen. Alle sehen sie: Die Liste zeigt sie ohnehin.
  • Das Admin-Panel. Die Plätze im Kopf eines Angebots, in der Angebotsliste und unter seinen Angaben sowie die Anmeldungen im Kopf einer Saison erneuern sich, sobald eine Anmeldung sie ändert. Davon erfährt nur, wer das Angebot sehen darf: Admins von jedem Angebot ihres Mandanten, Veranstalter:innen von den Angeboten ihrer Veranstalter-Profile und von denen, die mit ihnen geteilt wurden.

Der Hub gibt nur IDs und Zahlen weiter, nie Namen, Adressen oder Texte. Ein Browser, der im Admin-Panel von einer Änderung erfährt, fragt fepli nach den neuen Zahlen, und fepli prüft diese Anfrage wie jede Seite.

So funktioniert es

  • Der Hub gehört zum Image. Der Webserver des Images, FrankenPHP, hat einen Mercure-Hub eingebaut. Sie schalten ihn mit einem Block in seiner Konfiguration und zwei Schlüsseln ein. Ein Browser, der seine Verbindung zum Hub offen hält, belegt keinen PHP-Prozess: Der Hub ist ein eigener Teil des Servers.
  • Eine Verbindung pro Browser. Die Tabs eines Browsers teilen sich eine Verbindung zum Hub, wie viele auch offen sind.
  • Nach der Antwort. fepli veröffentlicht erst, wenn es die Anfrage beantwortet hat, die etwas geändert hat, und wenn es den Cache dafür geleert hat. Niemand wartet auf den Hub, und ein Browser, der nach den neuen Zahlen fragt, bekommt sie.
  • Ohne Hub geht nichts kaputt. Ein Hub, der nicht erreichbar ist, kostet eine Warnung im Log, A live update was not published, und sonst nichts: Die Anfrage und der Job, die etwas geändert haben, laufen durch. Die Browser verbinden sich von selbst neu.

Einschalten

1. Zwei Schlüssel erzeugen

openssl rand -base64 48

Führen Sie den Befehl zweimal aus: einen Schlüssel zum Veröffentlichen, einen für die Tokens, mit denen der Browser eines Admins die Änderungen im Admin-Panel empfängt. Tragen Sie beide in fepli.env ein, die der Web-Container, der Worker und der Cron lesen:

fepli.env

MERCURE_PUBLISHER_JWT_KEY=…
MERCURE_SUBSCRIBER_JWT_KEY=…

2. Den Hub im Web-Container einschalten

Die Konfiguration des Hubs hat mehrere Zeilen, die eine Env-Datei nicht aufnehmen kann. Geben Sie sie dem Web-Service in compose.yaml:

compose.yaml

  web:
    <<: *fepli
    environment:
      CADDY_SERVER_EXTRA_DIRECTIVES: |
        mercure {
          transport local
          publisher_jwt {env.MERCURE_PUBLISHER_JWT_KEY}
          subscriber_jwt {env.MERCURE_SUBSCRIBER_JWT_KEY}
          cookie_name fepli_live
          anonymous
          heartbeat 30s
          write_timeout 600s
        }
  • anonymous lässt jeden Browser die freien Plätze der Website empfangen. Die Änderungen im Admin-Panel erreichen nur Browser mit einem Token: Das Admin-Panel setzt es als Cookie mit dem Namen aus cookie_name, für 15 Minuten, und erneuert es.
  • transport local speichert nichts: Ein Browser, der seine Verbindung verloren hat, fragt die Zahlen einmal ab, sobald er wieder verbunden ist.
  • heartbeat hält eine ruhige Verbindung durch Proxys hindurch offen; write_timeout erneuert jede Verbindung nach zehn Minuten.

Der Hub antwortet unter /.well-known/mercure auf jeder Domain der Installation. fepli nennt ihn in <meta name="fepli-live-hub"> der Seiten, sobald MERCURE_PUBLISHER_JWT_KEY gesetzt ist.

3. Dem Worker und dem Cron sagen, wo der Hub ist

Auch der Worker und der Cron veröffentlichen, für die Änderungen ihrer Jobs: ein Losverfahren, eine Warteliste, die nachrückt. Sie haben keinen eigenen Hub und schicken ihre Updates deshalb an den Web-Container. Tragen Sie seine Adresse in fepli.env ein; der Web-Container veröffentlicht in seinen eigenen Hub und beachtet sie nicht:

fepli.env

MERCURE_URL=http://web/.well-known/mercure

4. Den Stream durch den Proxy lassen

Die Verbindung zum Hub bleibt offen und empfängt ab und zu ein Ereignis. Nichts zwischen dem Browser und dem Web-Container darf sie puffern oder schließen, während sie ruhig ist.

  • Varnish. Das Varnish-Image reicht /.well-known/mercure direkt an den Web-Container durch, ohne es zu cachen und ohne seine Cookies anzufassen. Verwenden Sie das aktuelle Image.
  • Caddy wie im Compose-Setup reicht den Stream unverändert weiter.
  • Andere Proxys brauchen für /.well-known/mercure abgeschaltetes Puffern und eine Leerlaufzeit, die länger ist als der Heartbeat von 30 Sekunden. Bei nginx: proxy_buffering off; und proxy_read_timeout 1h; für diese Location.

Starten Sie die Container neu: docker compose up -d.

Variablen

  • Name
    MERCURE_PUBLISHER_JWT_KEY
    Typ
    string
    Beschreibung

    Der Schlüssel, mit dem fepli seine Updates signiert und der Hub sie prüft. Leer schaltet die Live-Aktualisierung aus.

  • Name
    MERCURE_SUBSCRIBER_JWT_KEY
    Typ
    string
    Beschreibung

    Der Schlüssel der Tokens, die der Browser eines Admins dem Hub zeigt. Leer schaltet die Live-Aktualisierung im Admin-Panel aus; die der Website bleibt an.

  • Name
    MERCURE_URL
    Typ
    URL
    Beschreibung

    Wohin der Worker und der Cron ihre Updates im Netzwerk schicken: http://web/.well-known/mercure. Der Web-Container beachtet sie nicht.

  • Name
    MERCURE_PUBLIC_URL
    Typ
    URL
    Beschreibung

    Wo sich Browser mit dem Hub verbinden. Standard: /.well-known/mercure auf der Domain der Seite.

  • Name
    MERCURE_COOKIE_NAME
    Typ
    string
    Beschreibung

    Das Cookie des Tokens im Admin-Panel. Standard: fepli_live, das cookie_name des Hubs oben. Ändern Sie beide gemeinsam oder keines.

Prüfen

  • Die Seite nennt den Hub. Der Quelltext einer Seite der Website enthält <meta name="fepli-live-hub" …>. Eine Seite des Admin-Panels enthält es zusätzlich mit data-subscribe.

  • Der Hub antwortet. Diese Anfrage bleibt offen und gibt alle 30 Sekunden : aus:

    curl -N 'https://example.fepli.eu/.well-known/mercure?topic=/fepli/editions/<edition>/places'

    <edition> ist die UUID der Saison in ihrer kurzen base58-Form, wie in der Adresse von live.json der Angebotsliste (im Netzwerk-Tab des Browsers). Bei mehreren Mandanten steht statt fepli der Slug des Mandanten. Ändern Sie im Admin-Panel die maximale Teilnehmerzahl eines Angebots, und die Anfrage gibt ein event: places aus.

  • Eine Verbindung pro Browser. Im Netzwerk-Tab des Browsers: eine Anfrage an /.well-known/mercure, wie viele Tabs der Installation auch offen sind. Im Admin-Panel geht ihr eine Anfrage an /admin/_live/token voraus.

Grenzen

  • Ein Web-Container. Der Hub hält seine Verbindungen in dem Web-Container, in dem er läuft. Mit mehr als einem Web-Container erreicht ein Update nur die Browser, die mit dem Container verbunden sind, der es veröffentlicht hat. Schalten Sie die Live-Aktualisierung für eine solche Installation noch nicht ein.
  • Updates. Ein Neustart des Web-Containers beendet jede Verbindung. Die Browser verbinden sich innerhalb von Sekunden neu und fragen die Zahlen einmal ab.
  • Rechte, die sich ändern. Ein Token gilt 15 Minuten, und der Hub prüft es, wenn sich ein Browser verbindet. Ein Konto, dem der Zugriff auf ein Angebot entzogen wird, erfährt von dessen Änderungen, bis sein Browser sich neu verbindet, höchstens eine Viertelstunde. Was es erreicht, ist die ID des Angebots.

Ausschalten

Leeren Sie MERCURE_PUBLISHER_JWT_KEY, entfernen Sie CADDY_SERVER_EXTRA_DIRECTIVES und starten Sie die Container neu. Seiten, die Varnish noch hält, nennen den Hub, bis sie neu gerendert werden; ihre Browser finden keinen Hub und fragen die Zahlen ab wie bisher.

War diese Seite hilfreich?