Forklaring · Teknikk

Hva er en idempotensnøkkel: og hvorfor appen deres trenger en

4. november 2026 · Software by Design

Enhver app som fungerer offline svarer før eller siden på det samme spørsmålet: hva skjer når brukeren trykker «send» to ganger, eller når nettverket dør midt i en request og klienten prøver på nytt? Det svaret er en liten mekanisme kalt en idempotensnøkkel, her er hvordan den fungerer, og hvordan den ser ut i vår egen kode.

Problemet i én setning

Nettverk er upålitelige, så klienter må gjøre nye forsøk. Nye forsøk betyr at den samme logiske handlingen ankommer mer enn én gang. Uten beskyttelse blir «mer enn én gang» to timeregistreringer, to fakturaer, to bookinger.

Legg merke til hva problemet ikke er: det er ikke «brukeren dobbeltklikket». Brukere dobbeltklikker, men det vanlige tilfellet er langt mindre synlig, en mobilapp på en byggeplass mister dekningen, legger innstemplingen i kø, serveren bruker den, svaret dør underveis, og appen (helt korrekt) sender den igjen. Duplikatet er systemet som fungerer som tiltenkt.

Mekanismen

En idempotensnøkkel er en unik identifikator som klienten genererer per logisk handling, ikke per HTTP-forespørsel. Klienten fester samme nøkkel til den opprinnelige forespørselen og hvert nytt forsøk på den handlingen. Serveren holder oversikt over nøklene den har sett. Når en nøkkel dukker opp to ganger, returnerer serveren det første resultatet i stedet for å utføre mutasjonen to ganger.

Tre egenskaper får det til å virke:

  • Klienten eier nøkkelen. Hvis serveren utstedte den, kunne et nytt forsøk før mottak ikke identifiseres. Nøkkelen preges på enheten, i mobilappene våre en UUID opprettet i det øyeblikket brukeren stempler, ikke når nettverkskallet fyres.
  • Oppføringen er en forespørsel, ikke et resultat. Serveren skriver forespørselen først («denne nøkkelen er nå min, resultat underveis») og muterer deretter. En konkurrerende ny forespørsel finner forespørselen og venter på eller henter det opprinnelige utfallet, den kan aldri sne en ny mutasjon inn under den.
  • Forespørselen binder nyttelasten. Vi lagrer en hash av handlingen og dens normaliserte input sammen med nøkkelen. Samme nøkkel, annen nyttelast → en 409-konflikt, ikke en taus overskriving. Et nytt forsøk skal bare noen gang bety «det samme igjen».

Hvor den dukker opp i appene våre

ArbeitszeitChecks mobile stempelkø bærer en clientRequestIdcodeclient_event_id gjennom hver gjensending. TourCheck binder samme kontrakt til code på kontrollpunktsbekreftelser, der en gjensending sammenligner hele forespørselen, notat, foto, tidsstempel, mot den lagrede raden. Utløpet betyr like mye som dedupliseringen: forespørselsradene våre lever i sju dager, lenge nok til å dekke en langhelg uten dekning, kort nok til at tabellen forblir en kø og ikke en logg.

Kortversjonen for deres egen app

Hvis API-et deres muterer tilstand og klienten deres kan sende forespørsler på nytt, og det kan enhver klient, trenger dere nøyaktig tre ting: en klientgenerert nøkkel per handling, en forespørselsrad ved første skriving, og en payload-hash slik at «samme nøkkel» også betyr «samme intensjon». Det er hele mønsteret. Alt annet, gjensendingsvinduer, oppryddingsjobber, statuskoder for konflikt, er rørleggerarbeid rundt de tre forpliktelsene.