Crystal manual retry around Channel or HTTP write can duplicate side effects

A manual retry wrapper cannot detect whether a Crystal write already completed.

When HTTP::Client raises a timeout or a fiber is interrupted during Channel#send, the client cannot distinguish between a request that never reached the destination and one that succeeded server-side but lost its acknowledgment. Retrying in that state can duplicate side effects such as database inserts, charges, or messages.

Confirmed behavior

• HTTP::Client does not retry automatically; every retry is application-defined.
• An unbuffered Channel send blocks until a receiver is available, and an interrupted send leaves the receipt state indeterminate.
• Channel::ClosedError does not indicate whether the receiver consumed the message before closure.
• Crystal's standard library provides no built-in idempotency key, transactional outbox, or exactly-once retry primitive.

Store-side fencing required

Move uniqueness to the storage layer so retries are safe:

1. Generate a client-side UUID for each logical write and send it as an Idempotency-Key header.
2. Have the server store processed keys and return the cached result for duplicate keys instead of re-executing the write.
3. For internal services, record the outbound intent in a local outbox table within the same transaction as the state change, then deliver it separately.

Scoped retry example

def safe_write(payload, idempotency_key)
  attempts = 0
  begin
    response = http_client.post("https://api.example.com/write",
                                headers: {"Idempotency-Key" => idempotency_key},
                                body: payload)
    return response
  rescue HTTP::TimeoutError, IOError => e
    attempts += 1
    retry if attempts < 3
    raise e
  end
end

This pattern assumes the server honors the idempotency key. Without server-side deduplication, retrying a non-idempotent write is unsafe regardless of Crystal version.

Version assumption: this describes recent Crystal standard-library behavior. Confirm your installed compiler version because fiber scheduler and Channel semantics can differ across releases.

Diagnostic detail that changes the recommendation: do you control the receiving service's storage layer, or is the endpoint a third-party API that cannot store idempotency keys?