| Versie | Auteur | Datum | Opmerkingen |
|---|---|---|---|
| 1 | Dries Droesbeke | 04/04/2018 | Initial draft. |
De eventhandler is een ACPAAS component die gebruikt wordt om berichten te publiceren waarop verschillende afnemers kunnen subscriben.
De eventhandler is een abstractielaag voor pub/sub die volledig werkt op basis van http voor het afleveren van de berichten.
Het verschil met "traditionele pub/sub" systemen is dat de eventhandler de berichten pusht over http.
In de EventHandler UI of via de admin API kan je voor de berichten die je wil publishen een namespace(project) en topics(type berichten) aanmaken.
NodeJS
dotnet core
- https://github.com/digipolisantwerp/dataaccess-eventhandler_aspnetcore
- https://github.com/digipolisantwerp/eventhandler_aspnetcore https://www.hangfire.io
Hoewel de EventHandler high available is opgezet kan je ervan uitgaan dat deze (net zoals iedere andere dependency) op een gegeven moment niet beschikbaar zal zijn voor uw applicatie.
Daarom raden we aan om ook met een interne queue/tabel te werken binnen de applicatie zodat er geen inconsistenties ontstaan tussen de data uit de verschillende systemen.
Voor iedere subscription kan je onderstaande parameters instellen:
- naam
- endpoint
- authenticatie
- none
- basic auth
- apikey
- OAuth2 client_credentials
- aantal berichten dat gelijktijdig verzonden mogen worden
- retry strategie
- first level
- second level
Met een topic subscription krijg je alle berichten binnen voor deze specifieke topic.
Met een wildcard subscription kan je subscriben op meerdere topics.
Volgende wildcard karakters zijn beschikbaar:
- "*": kan exact 1 woord vervangen
- "#": kan 0 of meerdere woorden vervangen
Bijvoorbeeld voor topic "{bedrijf}.{entiteit}.{event}"
- digipolis.medewerker.created
- digipolis.medewerker.updated
- digipolis.applicatie.created
- digipolis.applicatie.updated
| subscription | matches |
|---|---|
| digipolis.*.created | digipolis.medewerker.created digipolis.applicatie.created |
| #.updated | digipolis.medewerker.updated digipolis.applicatie.updated |
Alle matches komen sequentieel op 1 queue terecht voor de subscriber en zullen volgens de configuratie van de subscription verwerkt worden.
Als het belangrijk is om de volgorde te respecteren bij het afleveren van de berichten kan je gebruik maken van EventHandler functionaleit of dit in de subscriber zelf verwerken.
Via de EventHandler kan je dit bekomen door de subscription te configureren om maximum 1 bericht parallel door te sturen en de subscription te stoppen als er 1 bericht faalt. Afhankelijk van de throughput van de subscriber kan dit al snel een bottleneck worden. De EventHandler past het principe van "best effort" naar volgorde toe. Dit wil zeggen dat er onder uitzonderlijke omstandigheden (failover) 2 berichten tegelijk gestuurd kunnen worden en de volgorde dus verloren gaat.
Een andere optie is om in het bericht zelf een "sequenceId" of "timeStamp" te voorzien en alle berichten in een queue/tabel van de subscriber te persisteren. Daarna kan er dan een ander proces de berichten sorteren en verwerken.
{
"config": {
"retries": {
"firstLevelRetries": {
"enabled": true,
"retries": 3,
"onFailure": "delete"
}
}
}
}
{
"config": {
"retries": {
"firstLevelRetries": {
"enabled": true,
"retries": 3,
"onFailure": "error"
}
}
}
}
{
"config": {
"retries": {
"firstLevelRetries": {
"enabled": true,
"retries": 3,
"onFailure": "stop"
},
"restartAfterStop": {
"delayInMinutes": 30,
"enabled": true
}
}
}
}
{
"config": {
"retries": {
"firstLevelRetries": {
"enabled": true,
"retries": 3,
"onFailure": "second"
},
"secondLevelRetries": {
"enabled": true,
"retries": 5,
"ttl": 600,
"onFailure": "error"
}
}
}
}In dit uitgewerkt voorbeeld beschrijven we de flow van een event vanaf de publisher tot aan de subscriber.
De publisher publiceert een event “dummy.test” op de namespace “dummy.testeventhandler”. Dit kan gebeuren via volgende REST call:
curl -X POST \
https://api-gw-o.antwerpen.be/acpaas/eventhandler/v2/namespaces/dummy.testeventhandler/topics/dummy.test/publish \
-H 'apikey: my-api-key' \
-H 'owner-key: my-owner-key' \
-d '{
"id": "123-456-789",
"object": {
"firstname": "John",
"lastname": "Doe"
}
}'
Op dit event is er een subscriber geabonneerd die dan volgende bericht doorgestuurd krijgt van de eventhandler via een POST method.
De eventhandler zal het bericht van de publisher verrijken met volgende extra headers:
Evha-Correlation-Id: 9e99664e-efef-427f-a7e2-3d449b8cb7c1
Evha-Topic: dummy.test
Evha-Namespace: dummy.testeventhandler
De payload blijft ongewijzigd:
{
"id": "123-456-789",
"object": {
"firstname": "John",
"lastname": "Doe"
}
}