Handleiding bij de broncodepreview · 0.1.0
Events, replay en herverbinden
Behandel eventstreams als begrensde aanwijzingen en verzoen de gezaghebbende REST-toestand.
De API-referentie is in het Engels.
De eventstream meldt dat gezaghebbende resources mogelijk zijn veranderd. Hij levert geen volledige bevindingen, beheert geen joblevensduur en vervangt geen revisiecontroles. Het duurzame databaserecord blijft de plek om vast te stellen wat er is gebeurd.
Commit de wijziging vóór de aankondiging
- Verbind met de toegelaten client
De browser gebruikt zijn sessie; de IDE vereist event:read voor de actieve generatie. Credentials en replaycursor horen niet in queryparameters.
- Ontvang een begrensde aanwijzing
project.changed, scan.changed, job.changed en findings.changed verwijzen naar gewijzigde resources. Keepalive-commentaren tonen alleen transportactiviteit.
- Lees de resource
Ververs het bedoelde project, scan, job of bevindingenpagina's en verzoen hun huidige revisies.
- Herverbind met Last-Event-ID
Bewaar het laatst waargenomen event-ID en herverbind na wachttijd. Replay is begrensd.
- Bouw opnieuw op na stream.reset
Als bewaarde events het gat niet kunnen vullen, lees actuele toestand opnieuw in plaats van een leeg ontbrekend interval aan te nemen.
Databasewijzigingen plaatsen binnen de transactie begrensde eventintenties in een outbox. Een dispatcher geeft replayvolgnummers aan gecommitte intenties. PostgreSQL-notificaties wekken de API-listener, die vervolgens duurzame rijen leest. Een notificatie is een weksignaal, niet de volledige eventgeschiedenis.
De API deelt binnen haar proces één blokkerende PostgreSQL-LISTEN-verbinding. Ze maakt het abonnement vóór de eerste databaseleesactie om de listen/query-race te sluiten. Streams lezen uit de outbox en sturen server-sent events naar geautoriseerde clients. Mist een client een weksignaal of heeft hij een oude weergave, dan blijft resourceverzoening nodig.
Zie outboxdispatch en streamlezen.
Open een stream met actuele bevoegdheid
GET /v1/events retourneert text/event-stream. Een browser gebruikt zijn sessie; een IDE vereist event:read voor de exacte actieve generatie. De stream accepteert geen URL-queryparameters. Gebruik voor replay de header Last-Event-ID met een niet-negatief decimaal volgnummer binnen het ondersteunde bereik.
De implementatie begrenst streams tot 32 totaal en vier per subject in elk API-proces. Dit is een proceslokale veiligheidsgrens, geen gedistribueerd quotum over onafhankelijk geschaalde API-instanties. Overschrijding geeft 429; een onbeschikbare listener geeft 503. Extra streams aanmaken is voor geen van beide een herstelstrategie.
IDE-bevoegdheid wordt vóór elk frame, inclusief keepalives, gecontroleerd tegen het duurzame capabilityslot en de generatie. Intrekken sluit de stream zonder credentialdetails in een speciaal event te tonen; herverbinden met ingetrokken bevoegdheid wordt geweigerd.
Lees protocol- en domeinevents
| Event | Betekenis en clientreactie |
|---|---|
stream.ready |
Meldt streamschema en huidige hoogste/vroegste event-ID’s. Verzoen de initiële resourcestatus. |
stream.reset |
De opgegeven cursor kan niet veilig worden afgespeeld. Bouw relevante REST-toestand opnieuw op vóór herverbinden. |
project.changed, scan.changed, job.changed, findings.changed |
Begrensde aanwijzingen voor resourcewijzigingen. Ververs resource of collectie met behoud van revisiecontroles. |
ide.source.open |
Gerichte openstaande bronopenopdracht voor de exacte geautoriseerde IDE-generatie. Geen algemene broadcast of replaybare bevindingpayload. |
Domeinevents hebben volgnummers. Protocolframes en gerichte bronopdrachten worden geen gewone domeinreplayitems. Gerichte aflevering wordt achtergehouden als meerdere actieve streams de ontvanger onduidelijk maken; meer vensters openen mag geen willekeurige ontvanger laten kiezen.
Eventdocumenten zijn maximaal 4 KiB. Tijdens wachten verstuurt de bron elke 15 seconden een keepalive-commentaar. Een keepalive schuift replaytoestand niet op en bewijst geen afgeronde scan. Zie streamuitvoer en autorisatiecontroles.
Herverbind en reset
Een eerste abonnement zonder cursor begint bij het huidige hoogste volgnummer. Het speelt niet alle eerdere events af, dus een initiële REST-weergave blijft nodig. Bewaar bij herverbinden het laatst waargenomen domeinevent-ID en stuur het na wachttijd via de header.
Replay is begrensd tot 256 events. De outbox bewaart maximaal 50.000 verzonden events en 24 uur, zodat geen van beide grenzen beschikbaarheid van een aangevraagde cursor belooft. De stream geeft een reset en sluit bij deze omstandigheden:
| Resetreden | Waarom replay niet kan doorgaan |
|---|---|
cursor_ahead |
Het opgegeven volgnummer ligt voorbij het huidige hoogste nummer. |
cursor_expired |
Vereiste eerdere events zijn niet meer bewaard. |
backlog_too_large |
De openstaande replay overschrijdt de begrensde batch. |
Bouw bij reset geselecteerd project/scan, actieve jobs en relevante bevindingenpagina’s opnieuw op vanuit actuele REST-toestand en stel daarna een nieuwe streambasis in. Verzoen opnieuw na verbindingsverlies of bevoegdheidswijziging. Behandel een gat niet als leeg resultaat, behoud geen verouderde collectiecursor en zet een job niet stilzwijgend op afgerond.
De outbox is een begrensd synchronisatiemechanisme, geen onbeperkt auditlog of garantie op precies één clientactie. De streamreferentie blijft gebonden aan haar gepubliceerde API-momentopname; de hier gekoppelde implementatie verklaart huidig beoordeeld gedrag. Deze documentatiesite opent geen eventverbindingen.