PureScript Aff and External API Idempotency Integration

Answer

Generate the idempotency key exactly once at the logical-request boundary, then thread the same opaque key through every attempt of the recursive Aff loop. Do not create the key inside the retry function, and do not let a generic retry combinator regenerate it.

Confirmed pattern

PureScript’s Aff sequences effects, but it does not enforce key stability across retries. Stability must come from scope: the key lives outside the recursive closure.

newtype IdempotencyKey a = IdempotencyKey String

withIdempotencyKey
  :: forall a e b
   . (IdempotencyKey a -> Aff e b)
  -> Aff e b
withIdempotencyKey k = do
  key <- IdempotencyKey <$> randomUUID
  k key

Recursive loop

go
  :: forall a e
   . IdempotencyKey a
  -> Int
  -> Request
  -> Aff e Response
go key attempt request = do
  response <- send request { headers = insert "Idempotency-Key" (unIdempotencyKey key) request.headers }
  case classify response of
    Retryable | attempt < maxAttempts -> do
      delay (backoff attempt + jitter attempt)
      go key (attempt + 1) request
    _ -> pure response

The phantom type variable a tags the key to a logical request type, so the type system prevents passing a key created for one request kind into another. Jitter is computed per attempt from a pure function of the attempt number plus randomness; it never influences the key.

Steps

1. Define IdempotencyKey a as an opaque newtype with a phantom tag.
2. Wrap the request entry point in withIdempotencyKey so the key is generated once.
3. Pass that key into go and reuse it on every recursive call.
4. Classify errors outside the loop; retry only on statuses the remote API documents as retryable.
5. Compute backoff and jitter as a pure function of attempt count, then delay and recurse with the same key.

Assumptions and uncertainty

• Exact delay, error-classification, and HTTP header functions depend on your purescript-aff and HTTP client versions; verify inferred types rather than assuming specific names.
• The header name Idempotency-Key is a placeholder. Confirm the API’s actual header name and which statuses or error codes are retryable before production use.
• Idempotency keys are a client-side convention; the remote service must recognize and deduplicate them, or retries after a server-side success can still duplicate writes.

Missing diagnostic: what is the API’s idempotency header name, and which HTTP statuses should trigger a retry? This changes the header insertion and retry-classification code above.

Verification

• Run spago build and confirm the key type is constructed once outside go, and that phantom-tagged keys cannot be mixed across logical request types.
• Test against a fake HTTP server: record the idempotency header for every attempt of one logical request and assert all attempts use one key, while separate logical requests use different keys.
• Have the fake server return a retryable error once, then success for the same key, and assert the application side effect is recorded only once.
• Log backoff delays to confirm jitter changes per attempt while the key remains constant.