docs(workflows): verify a run through a route the guide actually creates - #3911
Conversation
The "Verify it worked" section polled `GET /api/workflows/runs/$RUN`, but the guide never showed that route and the framework serves no `/api/workflows/**` handler, so the page's own verification step returned 404 for anyone who followed it top to bottom. Verify from the request that started the run instead, which is what the default client can actually support: `createWorkflowClient()` keeps runs in a private in-memory backend, so a second client never sees them. Say that outright, and point readers at a shared persistent backend for the cross-request case the `useWorkflow` hook needs. The new test pins the invariant behind the defect: every localhost API path the guide tells a reader to call must correspond to a route file the same guide shows them how to create.
|
Warning Review limit reached
Next review available in: 24 minutes Limit details: You’ve used the included review currently available. You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?Wait for the limit to reset, then comment An organization admin can change what happens after included review limits in Billing. How do review limits work?CodeRabbit enforces per-developer PR review limits within each organization. For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
📦 Client bundle boundary
A server module in a client graph aborts hydration in the browser. New leaks fail CI; known leaks are tracked in |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3133617130
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The verify route should return the durable run after any terminal outcome, not throw before readers can inspect failed or cancelled node state. Using the settled handle path matches the guide text and the executor contract. Confidence: high Scope-risk: narrow Tested: git diff --check -- docs/guides/workflows.md Tested: deno check docs/guides/workflows.md
The verification example now waits for settlement so failed and cancelled runs remain inspectable. A content contract prevents the guide from returning to the throwing result path. Constraint: Public workflow guidance must cover terminal failures without hiding run state. Rejected: Catch result() errors in the route | settled() expresses the documented intent directly. Confidence: high Scope-risk: narrow Directive: Keep the verification route non-throwing for all terminal workflow states. Tested: Deno 2.7.7 formatter, linter, and guide content contract, 45 steps passed. Not-tested: Full documentation validation task.
What
The workflows guide's "Verify it worked" section told readers to poll:
STATE=$(curl -s "http://localhost:3000/api/workflows/runs/$RUN")The guide never shows that route, and the framework serves no
/api/workflows/**handler (the only built-in workflow endpoint is/_dev/api/workflows, the dev dashboard). A reader who followed the page top to bottom got:The page's own verification step could not be run. Observed on
0.1.1246-rc.13479.Why the obvious fix isn't enough
Adding the missing route does not make the documented flow work.
createWorkflowClient()defaults to a per-instanceMemoryBackend, so a run started by one client is invisible to any other — including one in a different route file. Extracting a single shared client module does not help either.The runtime itself is fine. Starting a run and reading it back inside one request reaches exactly what the guide promises:
{ "status": "completed", "nodeStates": [{ "start": "completed" }] }So the defect is reachability, not execution.
Fix
Verify from the request that started the run, which is what the default client can actually support — and state the in-memory constraint outright rather than leaving readers to infer it. For the cross-request case the
useWorkflowhook needs, point at a shared persistent backend.Regression test
tests/docs/guide-content.test.tspins the invariant behind the defect: every localhost API path the guide tells a reader to call must correspond to a route file the same guide shows them how to create.Against the old text it fails with:
Verification
deno test --no-check -A tests/docs/→ 57 passed, 0 failed.scripts/docs/validate-public-docs.tsclean across 126 files.status: "completed"with acompletednode.Not addressed here
The workflow React hooks (
useWorkflow,useWorkflowStart,useApproval,useWorkflowList) all default toapiBase = "/api/workflows"and depend on server routes that ship no handler factory and are documented nowhere. That is a framework gap rather than a doc fix, and wants its own issue.Found while dogfooding the documented developer journey.