Forklaring · Udvikling
Hvad er en idempotency key: og hvorfor jeres app har brug for en
Enhver offline-funktionel app skal før eller siden svare på det samme spørgsmål: hvad sker der når brugeren trykker »send« to gange, eller netværket dør midt i et request og klienten prøver igen? Det svar er en lille mekanisme der hedder en idempotency key, her er hvordan den virker, og hvordan den ser ud i vores egen kode.
Problemet i én sætning
Netværk er upålidelige, så klienter må prøve igen. Retries betyder at den samme logiske handling ankommer mere end én gang. Uden beskyttelse bliver »mere end én gang« til to tidsregistreringer, to fakturaer, to bookinger.
Bemærk hvad problemet ikke er: det er ikke »brugeren dobbeltklikkede«. Brugere dobbeltklikker, men det almindelige tilfælde er langt mindre synligt, en mobilapp på en byggeplads mister signalet, lægger indstemplingen i kø, serveren anvender den, svaret dør undervejs og appen sender den (med rette) igen. Dubletten er systemet der fungerer som tiltænkt.
Mekanismen
En idempotency key er et unikt id som klienten genererer pr. logisk handling, ikke pr. HTTP-request. Klienten vedhæfter samme key til det oprindelige request og til hver retry af handlingen. Serveren holder styr på sete keys. Når en key ankommer to gange returnerer serveren det første resultat i stedet for at udføre mutationen to gange.
Tre egenskaber får det til at virke:
- Klienten ejer nøglen. Hvis serveren udstedte den, kunne en retry før modtagelsen ikke identificeres. Nøglen præges på enheden, i vores mobilapps et UUID dannet i det øjeblik brugeren stempler, ikke når netværkskaldet affyres.
- Posten er et claim, ikke et resultat. Serveren skriver claimen først (»denne key er nu min, udfald afventer«) og muterer først derefter. En samtidig retry finder claimen og venter på eller afspiller det oprindelige udfald, den kan aldrig snige en anden mutation ind under den.
- Claimen binder payloaden. Vi gemmer en hash af handlingen og dens normaliserede input sammen med nøglen. Samme key, anden payload → et 409-konflikt, ikke en tavs overskrivning. En retry bør kun betyde »det samme igen«.
Hvor det dukker op i vores apps
ArbeitszeitChecks mobile stempelkø bærer et clientRequestIdcodeclient_event_id gennem hver genspilning. TourCheck binder samme kontrakt til code på checkpoint-bekræftelser, hvor en genspilning sammenligner hele claimen, notat, foto, tidsstempel, med den gemte række. Udløbet betyder lige så meget som dedupe-funktionen: vores claim-rækker lever syv dage, længe nok til at dække en lang weekend uden dækning, kort nok til at tabellen forbliver en kø og ikke en log.
Den korte version til jeres egen app
Hvis jeres API muterer tilstand og jeres klient kan prøve igen, og enhver klient kan prøve igen, har I brug for præcis tre ting: en klientgenereret key pr. handling, en claim-række som første skrivning og en payload-hash så »samme key« også betyder »samme hensigt«. Det er hele mønsteret. Alt andet, genspilningsvinduer, oprydningsjobs, konfliktstatuskoder, er rørføring omkring de tre forpligtelser.