Long-Running Operations

# Do NOT do the work in the request
@router.post("/reports")
async def create_report(body: ReportIn, user = Depends(current_user)):
    job = await db.create_job(kind="report", user_id=user.id,
                              params=body.dict(), status="queued")
    await queue.enqueue("generate_report", job.id)      # Celery, RQ, Arq…
    return JSONResponse(202, {"job_id": job.id,
                              "status_url": f"/jobs/{job.id}"})

@router.get("/jobs/{job_id}")
async def job_status(job_id: str, user = Depends(current_user)):
    job = await db.get_job(job_id, user_id=job_id and user.id)  # ownership
    if not job: raise HTTPException(404)
    return {"status": job.status,          # queued | running | done | failed
            "progress": job.progress,       # 0-100, if you can compute it
            "result_url": job.result_url,   # when done
            "error": job.error}             # when failed

# The worker updates progress as it goes, so the UI can show
# something honest rather than an indeterminate spinner for a minute.

# Jobs must be idempotent and retryable: a worker can die mid-task
# and the queue will redeliver. Design for the task running twice.

// POLLING — simplest, works everywhere, survives a refresh
useQuery({
  queryKey: ['job', jobId],
  queryFn: () => api(`/jobs/${jobId}`),
  refetchInterval: (q) =>
    ['done', 'failed'].includes(q.state.data?.status) ? false : 2000,
})
// Back off as it goes: 1s, 2s, 5s, 10s. A fixed 500ms interval on a
// ten-minute job is 1,200 pointless requests per user.

// SSE — push, one direction, reconnects itself. Best for progress.
const es = new EventSource(`/jobs/${jobId}/stream`)
es.onmessage = e => setProgress(JSON.parse(e.data))
es.addEventListener('done', () => es.close())
// Watch out for platform buffering: some proxies hold SSE output
// until the response closes, which defeats the point.

// WEBHOOKS — for server-to-server, when the caller is not a browser
// (a payment gateway telling you a charge succeeded). Verify the
// signature, respond 200 fast, process asynchronously, and expect
// duplicates — so handling must be idempotent.

// Choosing: polling for most job UIs, SSE when live progress is the
// point, webhooks between servers. WebSockets only if the client
// also needs to send continuously.

// The job id belongs in the URL or in storage, so a refresh or a
// closed laptop does not lose the work:
navigate(`/reports/${jobId}`)

// A user must be able to leave. The job continues on the server; the
// page just stops watching. Tell them how they will find out:
"We are generating your report. You can close this page — we will
 email you when it is ready."

// Show real progress where you can, and a phase where you cannot:
//   "Processing 340 of 1,200 rows"        > a spinner
//   "Analysing submissions…"              > "Loading…"

// Failure needs to be actionable and specific:
{job.status === 'failed' && (
  <ErrorState message={job.error} onRetry={() => retry(job.id)} />
)}

// And bound it: a job stuck in "running" for an hour is a dead
// worker, not slow work. Time jobs out server-side and mark them
// failed, or the UI polls forever.

// Cancellation: let the user stop a long job, and have the worker
// check a cancellation flag between steps.