Anleitung zur Quellcode-Vorschau · 0.1.0
Ereignisse, Replay und Wiederverbindung
Behandle Ereignisstreams als begrenzte Hinweise und gleiche den maßgeblichen REST-Zustand ab.
Die API-Referenz ist auf Englisch.
Der Ereignisstream informiert Clients über mögliche Änderungen maßgeblicher Ressourcen. Er liefert keine vollständigen Befunde, bestimmt keine Joblebensdauer und ersetzt keine Revisionsprüfungen. Der dauerhafte Datenbankdatensatz bleibt die Stelle zur Feststellung des Geschehens.
Committe Änderungen vor ihrer Ankündigung
- Mit zugelassenem Client verbinden
Der Browser nutzt seine Sitzung; die IDE benötigt event:read für ihre aktive Generation. Zugangsdaten und Replaycursor gehören nicht in Abfrageparameter.
- Begrenzten Hinweis empfangen
project.changed, scan.changed, job.changed und findings.changed verweisen auf geänderte Ressourcen. Keepalive-Kommentare zeigen nur Transportaktivität.
- Ressource lesen
Aktualisiere vorgesehenes Projekt, Scan, Job oder Befundseiten und gleiche aktuelle Revisionen ab.
- Mit Last-Event-ID erneut verbinden
Bewahre die zuletzt beobachtete Ereignis-ID und verbinde nach Backoff erneut. Replay ist begrenzt.
- Nach stream.reset neu aufbauen
Können aufbewahrte Ereignisse die Lücke nicht füllen, lies aktuellen Zustand neu, statt einen leeren fehlenden Zeitraum anzunehmen.
Datenbankänderungen hinterlegen begrenzte Ereignisabsichten innerhalb der Transaktion in einer Outbox. Ein Dispatcher weist committeten Absichten Replay-Sequenznummern zu. PostgreSQL-Benachrichtigungen wecken den API-Listener, der anschließend dauerhafte Zeilen liest. Eine Benachrichtigung ist ein Wecksignal, keine vollständige Ereignishistorie.
Die API teilt innerhalb ihres Prozesses eine blockierende PostgreSQL-LISTEN-Verbindung. Sie richtet das Abonnement vor dem ersten Datenbankabruf ein und schließt damit das Listen/Query-Rennen. Streams lesen die Outbox und senden Server-Sent Events an autorisierte Clients. Verpasst ein Client ein Wecksignal oder hat eine alte Ansicht, bleibt Ressourcenabgleich erforderlich.
Siehe Outbox-Versand und Streamabrufe.
Öffne einen Stream mit aktueller Berechtigung
GET /v1/events liefert text/event-stream. Browser verwenden ihre Sitzung; IDEs benötigen event:read für die genaue aktive Generation. Der Stream akzeptiert keine URL-Abfrageparameter. Nutze für Replay den Header Last-Event-ID mit einer nicht negativen dezimalen Sequenznummer im unterstützten Bereich.
Die Implementierung begrenzt Streams je API-Prozess auf insgesamt 32 und vier pro Subjekt. Das ist eine prozesslokale Sicherheitsgrenze, kein verteiltes Kontingent über unabhängig skalierte API-Instanzen. Überschreitung liefert 429, ein nicht verfügbarer Listener 503. Zusätzliche Streams sind für keinen Fall eine Wiederherstellungsstrategie.
Vor Frames einschließlich Keepalives wird IDE-Berechtigung gegen dauerhaften Capability-Slot und Generation geprüft. Widerruf schließt den Stream ohne Zugangsdaten in einem besonderen Ereignis offenzulegen; Wiederverbindung mit widerrufener Berechtigung wird abgelehnt.
Lies Protokoll- und Domänenereignisse
| Ereignis | Bedeutung und Clientreaktion |
|---|---|
stream.ready |
Meldet Streamschema und aktuelle höchste/früheste Ereignis-IDs. Gleiche den anfänglichen Ressourcenzustand ab. |
stream.reset |
Der übergebene Cursor ist nicht sicher abspielbar. Baue relevanten REST-Zustand vor Wiederverbindung neu auf. |
project.changed, scan.changed, job.changed, findings.changed |
Begrenzte Änderungshinweise. Aktualisiere betroffene Ressource oder Sammlung mit Revisionsprüfungen. |
ide.source.open |
Gezielter ausstehender Quellöffnungsbefehl für die genaue autorisierte IDE-Generation. Kein allgemeiner Broadcast und keine abspielbare Befundnutzlast. |
Domänenereignisse haben Sequenz-IDs. Protokollframes und gezielte Quellbefehle werden keine gewöhnlichen Domänen-Replayeinträge. Gezielte Zustellung wird zurückgehalten, wenn mehrere aktive Streams den Empfänger mehrdeutig machen. Weitere Fenster dürfen keinen beliebigen Empfänger für Quellbefehle verursachen.
Ereignisdokumente sind auf 4 KiB begrenzt. Während des Wartens sendet die Quelle alle 15 Sekunden einen Keepalive-Kommentar. Ein Keepalive verschiebt keinen Replayzustand und beweist keinen Scanabschluss. Siehe Streamausgabe und Autorisierungsprüfungen.
Verbinde erneut und setze zurück
Ein erstes Abonnement ohne Cursor beginnt beim aktuellen höchsten Stand. Es spielt frühere Ereignisse nicht vollständig ab; der Client braucht weiterhin eine anfängliche REST-Ansicht. Bewahre beim Wiederverbinden die zuletzt beobachtete Domänenereignis-ID auf und sende sie nach Backoff im Header.
Replay ist auf 256 Ereignisse begrenzt. Die Outbox bewahrt höchstens 50.000 versandte Ereignisse und 24 Stunden auf. Keine Grenze verspricht daher die Verfügbarkeit eines angefragten Cursors. Unter diesen Bedingungen sendet der Stream Reset und schließt:
| Resetgrund | Warum Replay nicht fortfahren kann |
|---|---|
cursor_ahead |
Die Sequenz liegt hinter dem aktuellen höchsten Stand. |
cursor_expired |
Benötigte frühere Ereignisse werden nicht mehr aufbewahrt. |
backlog_too_large |
Das ausstehende Replay überschreitet die begrenzte Menge. |
Baue bei Reset ausgewähltes Projekt/Scan, aktive Jobs und relevante Befundseiten aus aktuellem REST-Zustand neu auf und richte dann eine frische Streambasis ein. Gleiche nach Verbindungsverlust oder Berechtigungsänderung erneut ab. Eine Lücke ist kein leeres Ergebnis; behalte keinen veralteten Sammlungscursor und markiere keinen Job stillschweigend als abgeschlossen.
Die Outbox ist ein begrenzter Synchronisationsmechanismus, kein unbegrenztes Auditlog und keine Garantie genau einmaliger Clientaktionen. Die Streamreferenz bleibt an ihren veröffentlichten API-Snapshot gebunden; die verlinkte Implementierung erklärt aktuell geprüftes Verhalten. Diese Dokumentationswebsite öffnet keine Ereignisverbindungen.