CSE Roadmap

Core tier · about 3 hours · 12 parts

Part 5 of 12 · 2 min read

Telling the client when to check back, and webhooks as the alternative

Polling with a hint, or letting the server call you, and why either way needs a safety net.

Think of being told "come back in about 20 minutes" rather than being left to guess and knock on the door every ten seconds.

In plain words: a status endpoint should tell the client how long to wait before asking again, not just whether the job is done.

# from code/mini-jobapi/jobapi.py
h = {} if j.state in TERMINAL else {"Retry-After": max(1, round(expected_s - (now - j.created)))}

Read it as: while the job is not finished, attach a Retry-After header with a rough estimate of the remaining time. Once it is finished, drop the header. Without this hint, a client that polls every 2 seconds for 100 ten-minute jobs sends 30,000 requests. With backoff, it sends 1,400. A webhook that calls the client once sends 100.

The alternative is a webhook. The server calls a URL the client registered when the job finishes. But a webhook can be delivered more than once. The sender retries whenever it does not see a clean success, even if the receiver actually processed it. The fix is the same shape as section 3: a token the receiver can recognise.

# from code/mini-jobapi/jobapi.py
if event["id"] in self.seen: return 200            # duplicate: ack without re-applying

Read it as: before acting on a webhook, check whether this exact event id has already been applied. If so, say "done" without doing it again. In the example, 30 percent of acknowledgements were lost. The sender still ended up delivering every event at least once. The receiver applied each one exactly once. It deduped by event id rather than trusting the sender's retry count.

At-least-once delivery

A guarantee that every event arrives one or more times, never zero, as long as retries continue. It does not promise exactly one delivery.

Example: 999 of 1,000 webhook events in the module's test were acknowledged on the first or a later attempt. The 1,000th was applied by the receiver, but its acknowledgement never reached the sender. The sender kept retrying a job that was, in fact, already done.