Realtime communicatie voor digitale schermen

Uitvoering

Snel bezorgen, bij de juiste mediaplayer

Met technische en productverantwoordelijken besprak ik snelheid, groei en uitval. Ik vertaalde hun behoeften naar eisen met een herkomst, prioriteit en voorwaarden voor goedkeuring. MoSCoW (Must, Should, Could en Won’t) hielp onderscheid te maken tussen noodzakelijk werk en aanvullingen.

Voor berichtontvangst gold bijvoorbeeld een tijdsgrens. Bij klantscheiding moest ik kunnen aantonen dat een bericht niet bij een andere klant terechtkwam. Ook de grens van de opdracht stond vast: mediaplayers bleven zelf hun mediabestanden downloaden. Deze afspraken bepaalden zowel het ontwerp als de latere tests.

De bestaande omgeving gaf de doorslag

Met een multicriteria-analyse vergeleek ik oplossingen op twaalf gewogen criteria, waaronder berichtbezorging, herstel na uitval, integratie en kennis binnen de organisatie. Ik onderscheidde de verbinding met de mediaplayer van de berichtenuitwisseling tussen systemen. Socket.IO en Centrifugo waren kandidaten voor de eerste taak; Redis Pub/Sub (publish-subscribe), Redis Streams en RabbitMQ onderzocht ik voor de tweede.

Socket.IO en Centrifugo eindigden gelijk. De bestaande Redis- en containerinfrastructuur en de aanwezige kennis gaven de doorslag voor een eigen service met Socket.IO en Redis Pub/Sub. Ik bouwde die in TypeScript op Node.js. Daarmee kreeg de realtime communicatie een eigen plek naast het CMS. Daar stond extra beheer tegenover: een afzonderlijke service en berichtafspraken die tussen CMS, service en mediaplayers moesten blijven aansluiten.

Een wijziging aankondigen, de contentroute behouden

Het CMS bleef bepalen welke content voor welke doelgroep beschikbaar was. Mijn socketserver kondigde een wijziging aan; de mediaplayer haalde de inhoud op en speelde die af. Zo kon ik de communicatie uitbreiden terwijl contentbeheer en afspeellogica bij de bestaande onderdelen bleven.

Het CMS publiceert daarvoor een bericht op een Redis-kanaal. De socketserver is op die kanalen geabonneerd, controleert het bericht en stuurt de melding naar de juiste verbonden mediaplayers. Dit publish-subscribe-model voorkomt dat het CMS elk draaiend exemplaar van de service afzonderlijk moet aanspreken.

Voor de ontvangerselectie koppelde ik Socket.IO-rooms, groepen verbindingen, aan klanten, mediaplayers en afspeellijsten. In het voorbeeld hieronder gebruiken A, B en C dezelfde afspeellijst. D hoort bij dezelfde klant, maar gebruikt een andere lijst en ontvangt deze melding daarom niet.

Met ioredis ontvangt elk exemplaar van de service de CMS-publicatie via Redis en bezorgt die bij zijn eigen verbonden mediaplayers. De Socket.IO Redis-adapter heeft daarnaast een afzonderlijke taak: Socket.IO-berichten tussen service-exemplaren uitwisselen. Hij verspreidt deze CMS-publicatie niet nogmaals.

De verbinding was de basis voor mijn eigen controles

Socket.IO bood benoemde berichten, groepen ontvangers en ontvangstbevestigingen. Engine.IO verzorgde daaronder het opzetten en bewaken van de verbinding. Het transport kan beginnen met long-polling via HTTP (Hypertext Transfer Protocol) en overgaan naar een blijvende WebSocketverbinding. Deze transportkeuze staat los van de periodieke contentcontrole bij het CMS.

Op die basis bouwde ik de regels voor identiteit, berichtinhoud en ontvangers. Een ontvangstbevestiging zegt daarbij alleen dat het bericht is aangekomen. Het downloaden en tonen van nieuwe content gebeurt daarna op de mediaplayer.

Ontwerpen terwijl de berichtafspraken veranderden

Het prototype maakte duidelijker welke gegevens de berichten moesten bevatten en hoe de service daarop moest reageren. Ik werkte de berichtafspraken en het ontwerp daarom tijdens de bouw bij.

Met UML (Unified Modeling Language) beschreef ik de gegevens en interacties. Een sessie, verbinding en bericht hebben bijvoorbeeld elk een eigen levensduur. Bij de identiteitscontrole gaf ik de CMS-koppeling, sessieopslag en telemetrie van buitenaf mee. Deze dependency injection maakte het mogelijk om in een test een CMS-antwoord of tijdelijke fout na te bootsen.

De keuzes legde ik vast in ADR’s (Architecture Decision Records), met aanleiding, alternatieven en gevolgen. Het Strangler Fig-principe diende als ontwerpkader om de communicatielaag naast het bestaande systeem te plaatsen. Polling bleef bestaan, waardoor beide routes onderhouden moesten worden.

Bij een korte onderbreking bewaarde de service sessiegegevens tijdelijk in het geheugen. Voor hervatting controleerde hij opnieuw de identiteit en klant. Een procesherstart wist die sessies, en Redis Pub/Sub bewaart geen berichten voor latere bezorging. Polling kon de actuele content alsnog ophalen; een gemiste eenmalige opdracht werd daarmee niet opnieuw uitgevoerd.

Eerst vaststellen of de afspeellijst is veranderd

Omdat polling beschikbaar bleef, keek ik ook naar de contentcontrole in CakePHP. Een mediaplayer had bij ongewijzigde inhoud geen nieuwe lijst nodig, terwijl het CMS die vrijwel iedere keer volledig opbouwde. Ik scheidde daarom het vaststellen van een wijziging van het samenstellen van de lijst.

De lichte controle berekent per mediaplayer een revisiekenmerk uit bestaande gegevens. De mediaplayer vergelijkt dat met de vorige waarde en haalt alleen bij een wijziging de volledige afspeellijst op. Voor het kenmerk hoeft het CMS de volledige lijst niet op te bouwen.

Een teller bij iedere opslaghandeling was onvoldoende. Sommige schrijfroutes in de legacycode omzeilden de gebruikelijke opslaghooks. Bovendien kan een afspeelrooster veranderen doordat een tijdvenster ingaat, zonder dat iemand gegevens opslaat. Daarom liet ik de controle aansluiten op de bestaande gegevens en de tijd- en regelselectie van de afspeellijstgenerator.

De mediaplayer bleef bij de lichte controle zijn status doorgeven. Mislukte de controle, dan gebruikte hij de bestaande volledige ophaalroute. Ik voegde regressietests toe voor onder meer verwijderde content, gewijzigde instellingen en roostergrenzen. De database-uitvoering blokkeerde lokaal door ontbrekende configuratie. Hoeveel belasting deze aanpassing in de praktijk bespaart, is niet met een gecontroleerde meting vastgesteld.

Een geldige verbinding geeft niet overal toegang

Omdat klanten infrastructuur delen, controleert de service eerst wie een mediaplayer is en daarna welke ontvangersgroepen hij mag gebruiken. Het bestaande CMS blijft de bron voor de identiteitscontrole. Al vóór die controle begrenst de service het aantal verbindingspogingen, zodat niet iedere poging onbeperkt verdere verwerking kan veroorzaken.

Ook berichten worden gecontroleerd. Ajv toetst hun structuur, verplichte velden en gegevenstypen. Daarna vergelijkt de service de klantidentiteit in het bericht met die in het Redis-kanaal en controleert hij de bestemming. Een bericht met geldige velden maar een verkeerde klant of ontvangersgroep wordt afgewezen.

Het diagram zet deze maatregelen naast de WebSocket-richtlijn van OWASP (Open Worldwide Application Security Project). Twee grenzen blijven relevant: ingetrokken toegangsgegevens beëindigen een bestaande verbinding niet automatisch, en de omringende infrastructuur moet de verbinding versleutelen.

Bij verbindings- en bezorgproblemen legt de service logs en meetgegevens vast. Daarmee kan worden onderzocht waar het misging. De registratie van mislukte bezorging start zelf geen contentcontrole; die blijft de verantwoordelijkheid van de mediaplayer.

Foutscenario’s testen vóór het bouwen

Met Jest toetste ik onder meer verkeerde ontvangers, mislukte authenticatie en ontbrekende ontvangstbevestigingen. In unit-tests verving ik afhankelijkheden door testimplementaties om fouten gericht op te roepen. De testsuite bevat daarnaast integratietests die met Testcontainers een echte Redis-container starten en een Socket.IO-testclient verbinden.

Regeldekking hielp mij zien welke code de tests bereikten. Of de uitkomst klopte, moest blijken uit de controles op het verwachte gedrag.

Ik nam de controles op in een geautomatiseerde bouwroute: code- en opmaakcontrole, TypeScript-controle, tests en controle van afhankelijkheden. Pas daarna volgden het bouwen van een Docker-image en een kwetsbaarheidsscan met Snyk. De lockfile legde pakketversies vast voor volgende installaties.

Voor de doelomgeving was uitrol via AWS (Amazon Web Services) voorzien, met Elastic Beanstalk voor de service, ElastiCache voor Redis en een ALB (Application Load Balancer) vóór de service. Daar zou ook TLS (Transport Layer Security) worden afgehandeld. Deze uitrolroute was geconfigureerd; de volledige omgeving was bij de overdracht nog niet getoetst.

AI-uitkomsten terugleggen naast de code

Tijdens het onderzoek gebruikte ik een semantische zoekindex om relevante code op betekenis te vinden. Daarin kwamen eerst de broncode van het CMS en de mediaplayer, en later de code en documentatie van mijn socketserver. De zoekresultaten verwezen terug naar hun bronlocatie, zodat ik de omliggende code kon controleren.

De agent kreeg daarnaast context uit codedocumentatie, een kennisbank en taakspecifieke instructies. Ik toetste voorgestelde wijzigingen aan de code, eisen en tests en verantwoordde deze werkwijze in mijn scriptie. Het diagram laat zien hoe de bronnen samenkwamen; via Codeonderzoek kun je de zoekroute verder openen.

Afronding

De berichtbezorging naast de eisen leggen

Om snelheid en herverbinden te toetsen, bouwde ik een eigen meetopstelling met gesimuleerde clients, de socketserver en een echte lokale Redis-server. Ik mat van publicatie in Redis tot ontvangst bij de testclient. Voor de herstelproef liet de testcode verbindingen verbreken en opnieuw openen.

Bij 1.000 virtuele clients kwam 95% van de berichten binnen 79,28 ms (milliseconden) aan. Dat is de p95, het 95e percentiel. Voor herverbinden was de p95 ongeveer 1,35 seconde. Beide waarden lagen binnen de gestelde grenzen van één seconde voor berichtontvangst en vijf seconden voor herverbinden.

De proeven draaiden lokaal op Node 20, met testauthenticatie en verhoogde limieten. De tijden omvatten geen downloads of schermweergave. De beoogde Node 24-omgeving met het echte CMS, echte mediaplayers en de cloudinfrastructuur was hiermee nog niet getoetst. De scenario’s waren eenmalig gemeten.

De oplossing overdraagbaar maken

Ik leverde de socketserver op met tests, mijn scriptie en onderzoeks- en ontwerpdocumentatie. De berichtafspraken en foutafhandeling had ik tijdens het bouwen bijgehouden. Voor de overdracht bracht ik installatie-instructies, beheerhandleidingen en architectuuruitleg samen in een documentatiesite met VitePress.

Daarin bouwde ik een interactieve C4-kaart (Context, Containers, Components en Code). Een ontwikkelaar kon vanuit het systeemoverzicht naar de socketserver, de authenticatiecomponent en de bijbehorende methode navigeren. Daar stond welke gegevens de methode verwachtte en of de controle kon leiden tot accepteren, afwijzen of opnieuw proberen.

De bovenste architectuurlagen beschreef ik zelf; geselecteerde codedetails werden uit TypeScript gegenereerd. Hiervoor gebruikte ik TSDoc-commentaren en TypeDoc om API-documentatie (Application Programming Interface) uit mijn code te maken. Cytoscape.js tekende de kaart, ELK (Eclipse Layout Kernel) bepaalde de plaatsing en een uitbreiding verzorgde het in- en uitklappen.

Met de Skillit-plugin voor TypeDoc genereerde ik ook documentatie voor AI-agents, waaronder llms.txt en llms-full.txt. De kaart en deze navigatiebestanden gebruikten dezelfde gegevens over onderdelen en relaties. Daardoor waren die verbanden zowel voor ontwikkelaars als voor agents beschikbaar.

De demo hieronder toont deze manier van navigeren met twee generieke voorbeeldcomponenten. De namen en relaties zijn illustratief en geven niet de oorspronkelijke projectarchitectuur weer.

class ExampleHandler {
  handle(request: ExampleRequest): ExampleResult;
}

const handler = new ExampleHandler();
const result = handler.handle({ value: 'voorbeeld' });

interface ExampleRequest {
  value: string;
}

interface ExampleResult {
  value: string;
}

const request: ExampleRequest = { value: 'voorbeeld' };
const result: ExampleResult = processRequest(request);

function processRequest(request: ExampleRequest): ExampleResult

const result = processRequest({ value: 'voorbeeld' });
// result: { value: 'voorbeeld' }