docs(comfy-router): document queued delivery across the Router pages - #1648
Merged
Merged
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Team Run ID: 📒 Files selected for processing (213)
📝 WalkthroughWalkthroughQueued delivery is documented for Comfy Router. The generator now emits synchronous and queued examples for supported model pages. Router guides describe submission, polling, collection, response states, preview gating, and workspace rollout behavior. Impish queue, tidy docs. ChangesQueued delivery generation
Router queue documentation
Model page examples
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Comment |
🌐 i18n translation sync reminder@comfyui-wiki English documentation was updated in this PR. Please complete or schedule translation updates for the following files: Japanese (
|
…Banana 2 example Adds development/comfy-router/queue.mdx documenting the queued delivery mode (submit, status, result, cancel) with copy-paste Python, TypeScript and cURL snippets against vertexai/gemini-3.1-flash-image, wires it into the Comfy Router nav, and points the limitations page's 'No queued submission' section at it. The page carries a gated-preview banner: a workspace that is not enabled receives 403 not_enabled.
The preview page was written before the TypeScript SDK had a queue surface, so its TypeScript block was raw fetch and its Python block was the only SDK example. Both SDKs shipped submit, subscribe and handle in 0.3.0, so the page now shows the same request three ways (Python, TypeScript, cURL) and covers each SDK method once: submit and the handle's event loop, subscribe with a progress callback, handle for collecting from another process, status and cancel, and the async Python client. It also moves the example to bfl/flux-2-pro, the quickstart's model, so a reader sees the exact request they already ran being queued, and brings the cancel contract in line with the published reference (409 ALREADY_COMPLETED, not 400).
Every runnable Quick start is now a tab pair: "Wait for the result" is the models.run call the page already had, "Queue and collect later" is the same body through models.submit, polled to completion and collected. Both tabs come from the one example object, so they cannot disagree about the request, and the queued builders mirror the synchronous ones for file inputs and result paths. Derived pages (no code.yaml) get the same pair from their synced example. The queued tab opens with snippets/comfy-router/queue-preview-notice.mdx while that file exists, on the same existence rule as the preview banner: once queued delivery is on for every workspace, rm it and regen. Regenerated all 204 pages; code-pages:check is fresh and the generator tests pass.
…eued delivery A reader who lands on the quickstart or the API guide had no way to learn that Router can hand back a request_id instead of holding the connection. The quickstart gains a short "Queue instead of waiting" section, the API guide links queued delivery from its timeout guidance and its Next list, and the headers page notes what Idempotent-Replayed and Retry-After mean on the queue routes. The quickstart and limitations pages are owned by the cloud repo and overwritten on every spec sync; their text here is for the preview and is upstreamed separately.
mattmillerai
changed the title
mattmillerai
force-pushed
the
matt/router-queue-preview
branch
from
September 15, 2026 22:32
b440d44 to
3a82393
Compare
mattmillerai
marked this pull request as ready for review
September 15, 2026 23:15
This was referenced Sep 15, 2026
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ELI5
Comfy Router used to have one way to get a picture: stay on the phone until it is done. The SDKs' 0.3.0 release added a second way: drop off a ticket, get a ticket number at once, and come back for the picture when it is ready, from the same program or a different one. This PR teaches the docs that second way everywhere a reader would look for it: a dedicated page that walks through it, a "Queue and collect later" tab on every model page right beside the snippet they already copy, and pointers from the quickstart, the API guide and the headers page.
Motivation
comfy-sdk0.3.0 and@comfyorg/sdk0.3.0 shippedmodels.submit,models.subscribeandmodels.handleon 2026-09-14, and the four queue routes are already in the generated API reference on this site. Nothing else on docs.comfy.org mentions them: the quickstart is synchronous only, the limitations page says queued submission does not exist, and the 204 per-model pages show one delivery mode. A reader has to find the SDK README to learn the surface exists. The queue is a gated preview, so the pages say so and the queued tab opens with that note.Provenance
interactive sessionbun run code-pages:gen(204 pages: 27 curated, 177 derived);bun run code-pages:check(204 fresh);bun test ./.github/scripts/snippets/(30 pass, 0 fail);npx mint broken-links(no broken links); localmint devrender of the queued delivery page, the quickstart, a single-model page with file inputs (FLUX.1 Kontext) and a multi-model page (Google Gemini) with the queued tab active, confirming the nested tabs and the notice render.Reviewer context
result.kindshape the queued snippets here already use, so whichever lands second regenerates the pages. Simplify the developer landing page and clarify Router limits #1685 — Simplify the developer landing page and clarify Router delivery adds a delivery-mode section to the API guide; this PR only adds links there, so the two should merge cleanly. The limitations edit in Simplify the developer landing page and clarify Router limits #1685 is on a cloud-owned page that the next sync overwrites.snippets/comfy-router/queue-preview-notice.mdx, regenerate, and drop the banner on the queue page).Summary
development/comfy-router/queue("Queued delivery (preview)" in the Comfy Router nav after "Using the Router API"): the two delivery modes side by side, the four routes, then one request queued in Python, TypeScript and cURL with SDK 0.3.0 (submit, the handle's event loop,get()), followed bysubscribe,handlefor collecting from another process,status()andcancel(), the async Python client, how the SDKs surface a failed completion, the response shapes, idempotency and billing, and the error table.runsnippets) and "Queue and collect later" (the same body throughsubmit, polled and collected). Both tabs are generated from the one example, so they cannot drift. The queued tab opens with a rollout note that lives in a snippet file and disappears from all 204 pages when that file is deleted.Idempotent-ReplayedandRetry-Aftermean on the queue routes; the limitations page says queued delivery exists as a gated preview.Changes
development/comfy-router/queue.mdx: rewritten for SDK 0.3.0 (the earlier draft predated the TypeScript methods and used rawfetch); example moved tobfl/flux-2-proto match the quickstart; cancelling a finished request corrected to409..github/scripts/snippets/gen-code-pages.ts:pythonQueueSnippet,typescriptQueueSnippet,curlQueueSnippet,codeGroup,deliveryTabsand the existence-gatedqueueNotice;quickStartandderivedSnippetsemit the tab pair. The README documents the two tabs.snippets/comfy-router/queue-preview-notice.mdx: the rollout note.development/comfy-router/models/**/code.mdx: regenerated (204 pages).docs.json: the queue page in the Comfy Router group.quickstart.mdx,api.mdx,headers.mdx,limitations.mdx: the pointers above.Test plan
code-pages,snippet-script-tests,validate-links,check-anchorsandmint-checksare green.