Developer Experience and API Product Thinking Questions

import time, random, logging, requests

MAX_RETRIES = 5
BASE_DELAY = 1.0  # seconds

def deliver(webhook_url, payload, headers, trace_id, store):
    # Log receipt
    logging.info("deliver.start", extra={"trace_id": trace_id, "url": webhook_url})
    idem = headers.get("X-Idempotency-Key")
    if not idem:
        idem = f"auto:{trace_id}"
    # Idempotency check
    status = store.get(f"idempotency:{idem}")
    if status == "delivered":
        logging.info("deliver.skipped_already_delivered", extra={"trace_id": trace_id, "idempotency": idem})
        return True

    attempt = store.get(f"attempts:{idem}") or 0
    while attempt < MAX_RETRIES:
        attempt += 1
        store.put(f"attempts:{idem}", attempt)
        try:
            resp = requests.post(webhook_url, json=payload, headers=headers, timeout=10)
            logging.info("deliver.attempt", extra={"trace_id": trace_id, "attempt": attempt, "status": resp.status_code})
            if 200 <= resp.status_code < 300:
                store.put(f"idempotency:{idem}", "delivered")
                return True
            if 400 <= resp.status_code < 500:
                # client error — don't retry; mark permanently failed
                store.put(f"idempotency:{idem}", "permanent_failed")
                logging.error("deliver.permanent_failure", extra={"trace_id": trace_id, "status": resp.status_code})
                return False
        except Exception as e:
            logging.warning("deliver.error", extra={"trace_id": trace_id, "attempt": attempt, "error": str(e)})

        # backoff with jitter
        delay = BASE_DELAY * (2 ** (attempt - 1))
        jitter = random.uniform(0, delay * 0.5)
        time.sleep(delay + jitter)

    # exhausted retries -> mark permanent failure
    store.put(f"idempotency:{idem}", "permanent_failed")
    logging.error("deliver.exhausted_retries", extra={"trace_id": trace_id, "attempts": attempt})
    return False