Exactly-Once Illusions: Design At-Least-Once Plus Truly Idempotent Handlers

1. Handler commits DB work, crashes before ACK → broker redelivers
2. ACK lost on the wire → redelivery of already-processed message
3. DLQ replay after a bugfix → intentional duplicates
4. Two consumers in a "exclusive" group during rebalance overlap
5. Upstream producer retries after 503 with a new broker message id

// consume/idempotent.ts
export async function handleOnce(eventId: string, fn: () => Promise<void>) {
 try {
 await ddb.put({
 Item: { pk: `idemp#${eventId}`, sk: "v1", status: "in_progress", at: Date.now() },
 ConditionExpression: "attribute_not_exists(pk)",
 });
 } catch (e: any) {
 if (e.name === "ConditionalCheckFailedException") {
 const row = await ddb.get({ Key: { pk: `idemp#${eventId}`, sk: "v1" } });
 if (row.Item?.status === "done") return; // ✅ safe replay
 throw new Error("in_progress_elsewhere");
 }
 throw e;
 }
 try {
 await fn();
 await ddb.update({
 Key: { pk: `idemp#${eventId}`, sk: "v1" },
 UpdateExpression: "SET #s = :d",
 ExpressionAttributeNames: { "#s": "status" },
 ExpressionAttributeValues: { ":d": "done" },
 });
 } catch (err) {
 await ddb.delete({ Key: { pk: `idemp#${eventId}`, sk: "v1" } }); // allow retry
 throw err;
 }
}

# effects/email.py
def send_receipt(event_id: str, to: str, body: str):
 try:
 table.put_item(
 Item={"pk": f"email#{event_id}", "to": to},
 ConditionExpression="attribute_not_exists(pk)",
 )
 except ClientError as e:
 if e.response["Error"]["Code"] == "ConditionalCheckFailedException":
 return # ✅ already sent
 raise
 ses.send_email(to=to, body=body)

test("handler survives duplicate delivery", async () => {
 const evt = samplePaymentEvent();
 await handleOnce(evt.id, () => applyPayment(evt));
 await handleOnce(evt.id, () => applyPayment(evt)); // second time no-op
 expect(await ledger.count(evt.id)).toBe(1);
});