Engineering · ArbeitszeitCheck
Anatomia di una timbratura offline
12:07, cancello di un cantiere, niente campo. L'operaio timbra comunque. Ecco tutto quello che quella timbratura attraversa prima di arrivare nel foglio presenze, e dove sarebbe potuto andare storta.
Minuto zero: il telefono non raggiunge il server
L'app mobile non riprova alla cieca e non finge un successo. La timbratura entra in una coda FIFO cifrata sul dispositivo, testo cifrato AES-GCM in AsyncStorage, con la chiave dati custodita in SecureStore. Quest'ultimo dettaglio ha una ragione vera: SecureStore limita i valori a circa due kilobyte su Android, quindi il design ovvio (coda in SecureStore, fatto) non è mai stato disponibile. La coda stessa è limitata a 32 voci, un buffer delimitato, non una promessa infinita. Lo stato ottimistico mostra subito il lavoratore come «timbrato in ingresso». La coda si svuota quando torna la copertura.
Lo svuotamento è volutamente pignolo: l'app fa lo snapshot della coda sotto un mutex, esegue il lavoro di rete fuori dal lock, poi fonde il risultato dentro, così una timbratura accodata durante uno svuotamento non viene sovrascritta dalla fusione. È la classe di bug che si trova solo essendo paranoici sulle scritture concorrenti.
Il replay: prima il claim, poi la mutazione
Quando la timbratura finalmente raggiunge il server porta due cose che una timbratura normale non ha: un clientRequestIdcodeoccurredAt e un timestamp payload_hashcodeoccurredAt. Il server non la applica direttamente. Prima scrive una riga di claim«questo request id ora è mio, esito in sospeso». Solo dopo muta il foglio presenze. Se due retry fanno a gara, il secondo trova il claim già preso e riceve l'esito del primo tentativo invece di una doppia timbratura.
La riga di claim porta un failedcode, sha256 sull'azione e i suoi input normalizzati. Stesso request id con un payload diverso risponde 409, non una sovrascrittura silenziosa: un client che riprova «timbra ingresso» e rimanda per errore «timbra uscita» riceve un errore visibile, non dati corrotti. I claim lasciati in sospeso per più di 300 secondi vengono recuperati. L'intera finestra di replay è di sette giorni, dopo i quali un job di pulizia elimina le righe.
Di chi è l'orologio che conta
Gli orologi dei telefoni derivano e si possono portare indietro di proposito, quindi la conformità è valutata su code, il momento in cui il lavoratore ha timbrato davvero, non sull'ora di arrivo. Quanto il server si fida di quel timestamp è un'impostazione admin delimitata: skew configurabile tra 24 e 72 ore indietro, cinque minuti nel futuro. Il tetto è voluto. Una timbratura «di giovedì scorso» ha bisogno di una persona che la guardi, non di un algoritmo che le creda.
Il percorso chiosco ha lo stesso contratto con le sue complicazioni: una cache badge NFC cifrata (TTL di sette giorni, massimo 500 voci) così un terminale di corridoio in un seminterrato apre comunque la schermata d'azione giusta durante un'interruzione, e uno svuotamento riuscito riscrive il nuovo stato in quella cache, altrimenti l'interruzione successiva offrirebbe al lavoratore azioni già sbagliate.
Cosa manca ancora, per iscritto
Due lacune. Una timbratura che fallisce definitivamente resta in coda marcata code, l'utente vede un toast, ma non c'è ancora una UI di retry per riga. E le vecchie versioni dell'app che non conoscono i nuovi campi semplicemente timbrano solo online. Non si rompe niente, perdono solo la funzione. Entrambe sono scritte nel decision doc perché il peggior tipo di limite è quello che nessuno ha documentato.
Il decision record completo, inclusi l'ordine dei lock e il job di pulizia, vive nel repository che l'AGPL garantisce possiate leggere. È l'altra metà della risposta di questo post: la coda non è solo progettata per sopravvivere a una zona morta, è documentata perché possiate verificare che lo è.