Verifica formato chiave di idempotenza

Verifica che la chiave non sia vuota, che sia abbastanza lunga da essere unica in pratica, che resti entro una lunghezza massima ragionevole e che ogni carattere sia sicuro in una URL, così che la chiave attraversi intestazioni, log e query string senza sorprese di codifica. Lei invia una stringa e riceve un indicatore valid chiaro, la lunghezza misurata e un elenco di problemi concreti quando qualcosa non va.

Perché le chiavi di idempotenza hanno bisogno di un controllo di formato

Le chiavi di idempotenza esistono affinché una richiesta ripetuta — un pagamento inviato due volte, un ordine creato dopo un timeout — venga elaborata una sola volta. Ma la sicurezza che promettono dipende dal fatto che la chiave stessa sia ben formata. Una chiave troppo corta collide con quella di un altro cliente e deduplica silenziosamente due operazioni diverse in una sola. Una chiave con caratteri fuori dall'alfabeto sicuro per le URL viene deformata da qualche parte tra il Suo client, un proxy, la pipeline dei log e il server, così che il nuovo tentativo arriva con una stringa diversa dall'originale e viene addebitato due volte. Una chiave vuota viene rifiutata immediatamente dalla maggior parte delle API, spesso con un errore generico che richiede un pomeriggio per essere rintracciato. Far passare la chiave attraverso questo controllo del formato della chiave di idempotenza al bordo del Suo sistema intercetta tutti e tre i modi di fallimento in fase di sviluppo, in una suite di test o in una convalida preliminare all'interno del Suo stesso servizio, invece che in un report di riconciliazione settimane dopo.

Cosa viene convalidato esattamente

Il controllo applica le regole di formato che i gestori di pagamenti e i middleware di deduplicazione documentano più spesso. Primo, la chiave deve essere una stringa non vuota; una chiave vuota è un errore, non un avviso, perché nessun server la accetterà. Secondo, la lunghezza: per impostazione predefinita la chiave deve avere almeno 16 caratteri, la soglia sotto la quale l'unicità smette di essere plausibile, e al massimo 255 caratteri, il limite che la maggior parte degli archivi accetta — entrambi i limiti sono configurabili a ogni chiamata. Terzo, l'alfabeto: ogni carattere deve appartenere all'insieme non riservato della RFC 3986 — lettere, cifre, trattino, punto, trattino basso e tilde. Questi caratteri attraversano le intestazioni HTTP, i segmenti di URL e i trasportatori di log senza codifica, che è esattamente il percorso delle chiavi di idempotenza. Quando un carattere non supera il controllo, la risposta elenca ogni carattere incriminato distinto, così Lei può vedere se qualcuno ha inserito uno spazio, una barra o un emoji, e l'array issues nomina il problema in forma leggibile dalla macchina: too_short, too_long o unsafe_characters.

Dove il controllo si inserisce nel Suo stack

La maggior parte dei team lo integra in due punti. Il primo è il client che genera le chiavi: subito dopo aver costruito una chiave da un UUID, un timestamp e un id utente, la convalidi una volta e registri un avviso se fallisce, così un bug del generatore emerge in staging invece che in produzione. Il secondo è il contract testing: invii un lotto di chiavi da ogni integrazione che gestisce all'endpoint in CI, così un aggiornamento di libreria che cambia il comportamento di codifica fa fallire la build. L'endpoint è deterministico e senza stato — niente viene memorizzato, nessun elenco di chiavi già viste viene consultato e lo stesso input produce sempre lo stesso output —, il che significa che è sicuro chiamarlo con chiavi reali e abbastanza economico, a $0.002 a richiesta, da eseguirlo a ogni deploy. Lo stesso controllo gira gratis anche nel Suo browser su questa pagina, così uno sviluppatore può incollare una chiave sospetta durante un incidente e ottenere la stessa risposta che darebbe l'API.