NPSS Client‑Server Idempotency Key Generation: Choosing Between Client‑Side and Server‑Side Approaches

NPSS should treat idempotency key generation as a compatibility layer rather than a strict requirement: clients may supply keys, but the server must be able to derive or assign them safely so that legacy clients are not dropped. The choice between client-side and server-side key generation hinges on whether the deployment can tolerate coordination overhead and whether the payload hash function is stable across all client environments.

Likely explanation

• Client-generated keys need a coordination registry or monotonic counter to prevent reuse across distinct writes; without it, a duplicate key can silently overwrite an earlier intended update.
• Server-derived keys from a deterministic payload hash (e.g., SHA-256 of canonical JSON) eliminate per-write coordination but add compute overhead for large payloads and depend on the hash function’s stability across client platforms.
• Legacy clients that omit a key must fall back to the configurable deduplication window; the window size directly controls the false-positive rate under high load or clock skew between nodes.

Confirmed facts

Key reuse without coordination may cause unintended idempotency, where a later write silently overwrites an earlier intended update. Deterministic hash collisions, though rare with strong algorithms, can theoretically merge distinct payloads under the same idempotency key. Deduplication window misconfiguration under clock skew across distributed nodes can produce false positives or negatives, decoupling from actual write timing.

Enforcing uniqueness for client-generated keys

1. Server-side key allocation service that hands out reservation tokens tied to a client identifier.
2. Monotonically increasing prefix per client, generated client-side but validated server-side for gaps.
3. Reservation tokens with a time-to-live, after which the key returns to the pool.

These mechanisms preserve support for legacy clients that do not supply a key, because the server can detect the absence and apply the deduplication window as fallback.

Impact on the deduplication window

If NPSS derives idempotency keys server-side from the payload hash, the deduplication window still applies to clients that do not supply a key. A larger window reduces false positives under load or clock skew but extends the exposure window for accidental duplicate processing. A smaller window improves performance at the cost of higher false-positive risk, especially when payload variations produce different hashes that fall outside the window’s coverage.

Diagnostic needed: What is the current deduplication window size (in seconds or operations) and has the system observed any collision events under expected load? This detail would determine whether tightening the window or adding a key-allocation service is the higher-priority change.