Spiegazione · Engineering
Cos'è una chiave di idempotenza: e perché la vostra app ne ha bisogno
Ogni app capace di funzionare offline prima o poi risponde alla stessa domanda: cosa succede quando l'utente tocca «invia» due volte, o la rete cade a metà richiesta e il client riprova? La risposta è un piccolo meccanismo chiamato chiave di idempotenza, ecco come funziona e come appare nel nostro codice.
Il problema in una frase
Le reti sono inaffidabili, quindi i client devono riprovare. I retry fanno arrivare la stessa azione logica più di una volta. Senza protezione, «più di una volta» diventa due registrazioni orarie, due fatture, due prenotazioni.
Notate cosa il problema non è: non è «l'utente ha fatto doppio clic». Gli utenti fanno doppio clic, ma il caso comune è molto meno visibile, un'app mobile in un cantiere perde il segnale, mette la timbratura in coda, il server la applica, la risposta muore in transito e l'app (giustamente) la rimanda. Il duplicato è il sistema che funziona come previsto.
Il meccanismo
Una chiave di idempotenza è un identificatore univoco che il client genera per azione logica, non per richiesta HTTP. Il client allega la stessa chiave alla richiesta originale e a ogni retry di quell'azione. Il server tiene traccia delle chiavi viste. Quando una chiave arriva due volte, il server restituisce il primo risultato invece di eseguire la mutazione due volte.
Tre proprietà la fanno funzionare:
- La chiave appartiene al client. Se la emettesse il server, un retry prima di riceverla non sarebbe identificabile. La chiave viene coniata sul dispositivo, nelle nostre app mobile un UUID creato nel momento in cui l'utente timbra, non quando parte la chiamata di rete.
- Il record è un claim, non un risultato. Il server scrive prima il claim («questa chiave è mia, esito in sospeso»), poi muta. Un retry concorrente trova il claim e aspetta o ripete l'esito originale, non può mai infilare una seconda mutazione sotto.
- Il claim lega il payload. Salviamo con la chiave un hash dell'azione e dei suoi input normalizzati. Stessa chiave, payload diverso → un conflitto 409, non una sovrascrittura silenziosa. Un retry dovrebbe significare solo «la stessa cosa di nuovo».
Dove si vede nelle nostre app
La coda di timbratura mobile di ArbeitszeitCheck porta un clientRequestIdcodeclient_event_id attraverso ogni replay. TourCheck lega lo stesso contratto a code sulle conferme dei punti di controllo, dove un replay confronta l'intero claim, nota, foto, timestamp, con la riga salvata. La scadenza conta quanto la deduplica: le nostre righe di claim vivono sette giorni, abbastanza da coprire un lungo weekend senza copertura, poco abbastanza perché la tabella resti una coda e non un registro.
La versione breve per la vostra app
Se la vostra API muta stato e il vostro client può riprovare, e ogni client può riprovare, vi servono esattamente tre cose: una chiave generata dal client per azione, una riga di claim scritta per prima e un hash del payload così che «stessa chiave» significhi anche «stesso intento». Questo è tutto il pattern. Il resto, finestre di replay, job di pulizia, codici di stato di conflitto, è idraulica intorno a quei tre impegni.