docs: show how to poll an async job with http.request

Merged
SC
4d ago
+52-0

Summary

A common need is to POST a job, then poll its status URL until the job is done. This works today with http.request, format: json and repeat_policy: until on the step's own output, but no page shows it. This PR adds a short recipe to the HTTP page and links it from the repeat_policy section.

Changes

  • step-types/http.md: new "Poll an Asynchronous Job" section after JSON Output Mode. A submit step reads status_url from the JSON response, a status step repeats until state matches re:^(done|failed)$ (with a retry_policy for short outages and a limit on the number of polls), and a last step fails the run unless the state is done.
  • writing-workflows/control-flow.md: link to the recipe after the until note.

Checks

  • node scripts/validate-examples.mjs with Dagu built from main (0689a90): 913 examples validated
  • pnpm build
  • pnpm test:worker
  • git diff --check
  • Ran the recipe with Dagu main against a local test server that answers running twice and then a final state:
    • final state done: 3 polls, run succeeded
    • final state failed: 3 polls, check_result failed, run failed
    • one 503 from the status endpoint: the retry ran, polling continued, run succeeded
    • limit: 1: 1 poll, check_result failed on running

Summary by cubic

Adds documentation showing how to poll an asynchronous job's status URL with http.request.

  • New "Poll an Asynchronous Job" recipe on the HTTP step page, covering submit, poll until a final state, and a final result check.
  • Links the recipe from the repeat_policy until note in the control-flow docs.