23 Commits

Author	SHA1	Message	Date
chenchaonan	7073a93653	sync upstream (#19) ... * [Partner Nodes] feat: add Krea 2 Medium Turbo model (#14280) * [Partner Nodes] feat: add seed input to Flux Erase node (#14283) Signed-off-by: bigcat88 <bigcat88@icloud.com> * chore: update workflow templates to v0.9.98 (#14284) * Bump comfyui-frontend-package to 1.45.15 (#14265) * Fix ideogram if model dtype gets set to fp8. (#14291) * Consolidate audio nodes into SaveAudioAdvanced node (CORE-202) (#13871) * Enable cfg1 optimization for DualModelGuider with CFGGuider (#14290) * Enable cfg1 optimization for DualModelGuider * Fix CFG Override tooltip * Fix interoperation with external source of pinned memory pressure (#14252) * mm: split off registration helper to doer and headroom calc * pinned_memory: implement registration comfy side Move away from Aimdo buffer registrations which seem fraught with danger and do it comfy side. Just start with the basic move. * pinned_memory: do registrations as portable memory * pinned_memory: discard async errors on registration fail Like the good ol days. * pinned_memory: implement abs shortfall retry If pinned registration happens to fail despite the previous budget ensures, consider the allocation shortfall, ensure it again, and try again. This allows comfy pins to interoperate with other software that might be doing substantive pinning. * aimdo 049 (#14300) * [Partner Nodes] feat: add new Gemini text node (#14299) * [Partner Nodes] feat: add temperature and top_p to NanoBanan node (#14305) * feat: add PreviewGaussianSplat + PreviewPointCloud nodes (#14194) * Update AMD portable readme. (#14303) * BE-1172 fix(3d): save Preview3DAdvanced / PreviewGaussianSplat / PreviewPointCloud to temp/, rename viewport input (#14294) * feat(3d): reorder Preview3DAdvanced / PreviewGaussianSplat / PreviewPointCloud inputs and outputs (#14308) * Update line endings check to ignore .ci files. (#14319) * Use windows line endings for windows portable readmes. (#14334) * Add SeedVR2 support (CORE-6) (#14110) * chore: update embedded docs to v0.5.3 (#14350) * Add Color primitive (#14260) * Improve ResolutionSelector (#14309) * feat(assets): extract image dimensions at ingest and emit on asset responses (#13991) * feat(assets): extract image dimensions at ingest and emit on asset responses Image assets now carry width/height under the existing `metadata` field on asset responses, shaped as `{"kind": "image", "width": W, "height": H}`. This lets consumers get original dimensions (e.g. for clients that render server-side thumbnails and can't recover them from naturalWidth/Height) without an extra round-trip. Dimensions are written to AssetReference.system_metadata across three ingest paths: - Direct file ingest (upload, in-place registration): Pillow reads the image header right after hashing, while the file is still in OS page cache. Non-image MIME types are skipped without touching the file. - From-hash registration: this path never reads the file bytes, so dimensions are best-effort copied from any prior sibling reference of the same asset that already carries kind=image metadata. Missing siblings, non-image siblings, or absent dimension keys leave the new reference's metadata unchanged. - Scanner enrichment: extends the existing system_metadata write in enrich_asset so scanner-registered images get the same treatment as uploaded ones. Existing system_metadata keys (e.g. safetensors fields written by the enricher, download provenance) are preserved through merge. Existing assets ingested before this change retain their current metadata — no automatic backfill in this PR. Tests cover image emission, non-image no-op, merge preservation, and the from-hash sibling back-fill (including the no-sibling and non-image-sibling cases). * fix(assets): validate sibling dimensions before backfilling Per CodeRabbit review on #13991: the previous loop accepted any sibling with `kind == "image"` and copied whichever dimension keys happened to be present, then returned. A partial sibling (kind set but missing or invalid width/height) could persist incomplete metadata onto the new reference even when a later sibling had valid dimensions. Now we validate that the sibling has both width and height as positive integers before adopting its dimensions, and continue scanning to the next sibling otherwise. * fix(assets): reject booleans in sibling dimension validation (use type-is) Per CodeRabbit follow-up on #13991: bool is a subclass of int in Python, so isinstance(True, int) is True. The previous strict-int gate would have accepted width=True (truthy + > 0) as a valid dimension. Realistic occurrence is low (extract_image_dimensions returns proper ints, JSON doesn't serialize bools as numbers), but the validation gate exists for defense-in-depth so it should be actually strict. --------- Co-authored-by: guill <jacob.e.segal@gmail.com> * Revert "Add SeedVR2 support (CORE-6) (#14110)" (#14359) This reverts commit 7863cf0e53. * chore(openapi): sync shared API contract from cloud@5273c30 (#14266) * fix: Add back apply_rotary_emb for Qwen Image (#14364) * Allow custom templates with Ideogram4 TE (#14374) * main/server: Add --debug-hang (#14371) Add an option to debug a hang with ctrl-C, dumping the backtraces to see where its stuck or slow. * Add LoRA key mapping for LTXV/LTXAV models (#14349) * feat: Add model support for SCAIL-2 (#14373) * initial SCAIL2 support * Move bg_removal_model input socket to first position for nicer display (#14353) * mm: dont reset cast buffers in cleanup_models_gc() (#14372) cleanup_models_gc can be called once per load_models_gpu via free_memory, which in turn can de-activate an active model via this reset_cast_buffers. cleanup_models_gc() could also come via obscure garbage collector paths so limit reset_cast_buffers to the post-node callsite instead. * Ensure conditions are not trainable to avoid bugs (#14368) * feat: Add Bernini-R model support (Wan video) (CORE-279) (#14216) * Depth anything 3 (Core-135) (#13853) Co-authored-by: Alexis Rolland <alexisrolland@hotmail.com> * Always enable cuda malloc on cu130 and higher. (#14381) * chore(openapi): sync shared API contract from cloud@ca12913 (#14367) * [Trainer/bug] Ensure model is not inference mode (CORE-72) (#13400) * Ensure model is not inference mode * force clone inside training mode to avoid inference tensor * Allow force deepcopy for model patcher * chore(assets): drop vestigial tags.tag_type column (#14248) tag_type was always "user" in practice — no code path ever set it to anything else (no system/seeded classification was wired up) and nothing queried it. The column, its ix_tags_tag_type index, and the TagUsage.type API field were dead weight, so they're removed. Adds alembic migration 0004 to drop the column and index. Verified: asset-seeder tests pass; migration applies cleanly on a fresh SQLite (tags retains only name; tag_type column + index dropped). Co-authored-by: guill <jacob.e.segal@gmail.com> * feat(assets): cursor-based pagination on GET /api/assets (#14014) * spec(assets): add cursor pagination params to GET /api/assets Add 'after' query param and 'next_cursor' response field for keyset pagination. Matches the cloud Go implementation (BE-893) so frontend sees a unified contract across runtimes. Offset/limit remain as a deprecated fallback. * feat(assets): add cursor encode/decode helpers for keyset pagination Port of cloud common/pagination/cursor.go. Wire format is base64url of {"s", "v", "id"} JSON; times are Unix microseconds UTC to match PostgreSQL timestamp precision. Includes a byte-identity fixture pinned against the cloud Go wire format so cross-runtime FE pagination can't silently drift. * feat(assets): thread cursor through schemas, service, and query layer list_assets_page accepts an opaque 'after' cursor and returns next_cursor when more pages are available. The query applies a keyset WHERE clause and a secondary ORDER BY id for deterministic tiebreak. Cursor sort field is validated against the request sort, and a last_access_time sort (OSS-only) falls back to offset/limit. Offset is ignored whenever a cursor is supplied. * feat(assets): wire cursor pagination through GET /api/assets handler Adds integration tests for: full cursor walk, invalid-cursor 400, sort/cursor mismatch 400, cursor-wins-over-offset, absent next_cursor when no more results, and pagination stability across deletes. * fix(assets): address cursor-review verified findings - Mint next_cursor on every cursor-supported sort, not only when 'after' was supplied. A first request (no 'after') previously returned next_cursor=None, leaving cursor mode unreachable from a clean start. - Over-fetch limit+1 so an exactly-full terminal page doesn't mint a spurious cursor pointing at a phantom next page. - Map crafted out-of-range microsecond cursors (OverflowError / OSError in datetime construction) to 400 INVALID_CURSOR instead of leaking 500. - Bump MAX_CURSOR_VALUE_LENGTH 256 -> 512 to match the AssetReference name column max; without this, a long-named asset minted a cursor the same server then refused on the next request. Cross-runtime byte identity with cloud is unaffected because no cloud cursor ever carries a value > 256 (cloud schema doesn't permit it). - Return None from _encode_next_cursor when the boundary row carries a NULL sort value (e.g. an Asset without size_bytes backfilled), instead of silently encoding 0 and mis-positioning the keyset. - Fix schemas_in.py comment so it matches actual handler behavior (last_access_time + 'after' raises 400, does not fall back). - Add AssetsApiError schema + 400 response to GET /api/assets in openapi.yaml so generated clients know the INVALID_CURSOR envelope. - Extend integration coverage: first-page mint, exact-multiple terminal page, cursor walks for created_at/updated_at/size sorts, datetime overflow surfaces as 400 not 500. - Add unit coverage for datetime overflow and 512-char round-trip. * feat(assets): bind cursor to sort order + Go-compat JSON escaping Address three needs-judgment items from the cursor-review judge synthesis: 1. Cursor wire format now includes an "o" key carrying the sort direction ("asc" / "desc") it was minted under. A request that replays the cursor with a flipped `order` parameter is rejected with 400 INVALID_CURSOR instead of silently walking the wrong direction. Legacy cursors without "o" still decode (the binding is best-effort until cloud mirrors the field — follow-up filed separately). 2. JSON serialization now escapes `<`, `>`, `&`, U+2028, U+2029 to mirror Go's default `json.Marshal` behavior. Without this, an asset name containing those characters produced different bytes on Python vs cloud Go. The escaped form is what both runtimes emit. 3. Add direct query-layer tests for the keyset tiebreaker — the secondary ORDER BY id branch was previously unexercised. Two scenarios: all rows share a primary sort value, and mixed ties straddle page boundaries. Both assert no row is dropped or duplicated across the walk. Wire-format note: Python cursors now differ from current cloud cursors by exactly the "o" key. Cloud follow-up will bring the two back into byte alignment. * fix(assets): address bot review comments - Soften offset param prose: it's not deprecated, just not preferred for sequential walks. Random-access UIs (jump-to-page, item count displays) legitimately still want offset, so dropping the 'deprecated' framing rather than promoting it to a machine-readable deprecated:true flag. - Add explicit HTTP status assertions before every json() / next_cursor read in test_list_cursor.py so a failing request surfaces as an HTTP error instead of a confusing KeyError on a 4xx/5xx body. * feat(assets): require cursor o field, drop legacy permissive path Cursor pagination hasn't shipped on either runtime yet — this PR is still draft and cloud's mirror is just behind it — so there are no legacy no-o cursors in the wild. Make o mandatory from day one rather than landing permissive and tightening later. decode_cursor now rejects any payload without o (or with a non-string o) as malformed. CursorPayload.order becomes a required str. Tests that constructed CursorPayload directly now pass order="desc"; test_legacy_cursor_without_order_accepted flips to test_cursor_without_order_rejected. * chore(assets): drop cross-repo prose from cursor comments Strip prose references to sibling Go implementations and external ticket IDs from cursor.py, the cursor tests, the keyset integration tests, asset_management's sort-field comment, and the legacy prompt_id alias comment. Pure docstring/comment scrub — no behavior or wire-format changes. x-runtime: [cloud] field annotations in openapi.yaml are unchanged; those are the spec's structural cross-runtime convention, not internal references. * test(assets): include 'o' in microsecond-boundary cursor payload The boundary test was building a cursor without the required `o` key, so decode failed on the missing-order branch before reaching the µs-overflow path the test is asserting. Both paths return 400 INVALID_CURSOR so the assertion passed for the wrong reason. Add `o` to the payload and matching `order=` to the request so the decode reaches the intended branch. * fix(assets): address ultrareview findings on cursor pagination Six fact-checked findings from the multi-model review pass: - Encoder/decoder length asymmetry: encode_cursor now rejects empty id, oversized id (>128), oversized value (>512), and invalid order tokens symmetrically with decode_cursor. Prevents the same server from minting a cursor it then 400s on the next request (e.g. a filesystem-scanned asset name >512 chars). The bad-order path now raises InvalidCursorError (still subclasses ValueError) so route-layer handling stays uniform. - Raw U+2028/U+2029 in cursor.py source: ripgrep treated those lines as line-terminators, confirming the bytes were the actual separators. Any editor save / autoformat / git tooling that normalizes invisibles would silently break the encoder. Replaced with explicit / Python escape sequences. - set(seen) == set(names) hid ordering regressions: a cursor walk that dropped a row at a page boundary or returned duplicates could pass. Reworked the assertion to (1) reject duplicates, (2) require full coverage, and (3) assert strict positional order for size sort, the only field with a clock-independent ordering. - Flaky time.sleep(0.05) between inserts: Windows CI clock resolution is ~15ms, so back-to-back inserts under load could collide and exercise the tiebreaker instead of the documented path. Removed the sleep and let the strengthened assertion above carry coverage / no-duplicates, with size sort carrying strict order. - Cursor error envelope diverged from the rest of routes.py: cursor 400s emitted {error: {code, message}} while every other 400 in the file emits {error: {code, message, details}} via _build_error_response. Switched to _build_error_response and added the details field to the AssetsApiError schema in openapi.yaml. - "Byte-identity fixtures" only checked substring containment, defeating the test class's stated purpose of pinning the wire format. Switched to exact-bytes equality against an inline expected payload string per fixture, so any whitespace / key-order / escape drift fails loudly. Also dropped Go / json.Marshal references from docstrings — the byte format is the contract, not the runtime that mints it. * fix(assets): cap cursors by encoded wire size, not just char count Char-count guards on value/id can still let multibyte or escape-heavy inputs blow past MAX_ENCODED_CURSOR_LENGTH once UTF-8 + escape expansion + base64url runs. A 512-character name of 'é' (2 bytes UTF-8) or '<' (serializes to the 6-byte '<' escape) passes the char check, mints a ~1500-byte cursor, then 400s when handed back on the next request. Compute the final encoded form and reject it before returning if it exceeds the wire cap. Adds regression tests for both inflation paths. * refactor(assets): extract cursor JSON escaping helper; size wire cap above per-field caps Addresses review feedback on cursor.py: - Extract the inline escape chain into _apply_wire_compatible_json_escapes() with a comment pinning it to the wire format's escape set, so the parity intent is explicit rather than reading as an ad-hoc transform. - Raise MAX_ENCODED_CURSOR_LENGTH to 8192 (comfortably above the ~5.2KB worst-case the per-field caps can produce) and drop the mint-time length guard. Encoder/decoder symmetry now holds by construction: the encoder can't produce a cursor the decode path rejects, so there is no confusing user-visible 'cursor too long' failure at mint time. - Rewrite the two over-wire-cap tests to assert worst-case multibyte and escape-heavy values mint and round-trip, instead of being rejected. * refactor(assets): drop cross-runtime cursor escaping; cursors are opaque The custom JSON escaping of <, >, &, U+2028, and U+2029 existed only to keep the encoded cursor byte-identical with the Cloud implementation of the same payload format. Cursors are opaque tokens, so byte-level compatibility across implementations is not needed — plain json.dumps output is sufficient. Remove the escaping helper and the byte-identity test fixtures that pinned the wire format; keep round-trip coverage for the affected characters. --------- Co-authored-by: guill <jacob.e.segal@gmail.com> * fix(assets): remove unused delete_content param from deleteAsset (#14241) * fix(assets): remove unused delete_content param from deleteAsset The delete_content query param on DELETE /api/assets/{id} was introduced in #12125 and had its default flipped to false in #12621. In practice no client sends it: the frontend issues a bare DELETE /assets/{id}, so every real caller already gets the default soft-delete (the reference is hidden, content preserved). The only thing that set delete_content=true was this repo's own test teardown. Remove the param from the route and the OpenAPI spec so the contract matches what clients actually use (and lines up with the cloud surface). The route now always soft-deletes. The underlying delete_asset_reference helper keeps its delete_content_if_orphan option, so orphan reclamation remains available internally for a future GC path — it's just no longer exposed on the public endpoint. Tests that used delete_content=true for hard cleanup now soft-delete; test_delete_upon_reference_count asserts content preservation instead of orphan removal. * test/docs: address review on deleteAsset delete_content removal - Rename test_delete_upon_reference_count -> test_soft_delete_preserves_asset_identity_across_references; the old name implied last-ref cleanup, but it now verifies the opposite (soft delete preserves identity across references). - Strengthen the re-association assertion: also check asset_hash == src_hash so it proves content reuse rather than relying on the now-tautological created_new is False. - Document delete_asset_reference: the orphan-reclamation branch is intentionally internal-only; the public endpoint always soft-deletes. - Normalize the soft-delete comment phrasing. * test(assets): make seed content unique per test for isolation Removing the delete_content param means delete is always a soft delete, so content created by one test now survives into the next. The suite had been relying on hard-delete teardown for isolation, so shared fixed-content fixtures started colliding: seeded_asset (b"A"*4096) and make_asset_bytes (deterministic on name) produced the same hash every test, so the second seed deduped to the surviving asset and returned 200 instead of 201, cascading into ~14 failures/errors. Salt both fixtures with a per-test uuid so each test creates fresh content (created_new True, 201), while keeping content deterministic within a test (same name/size -> same bytes) and preserving exact byte length so size-based list/sort assertions are unaffected. * main: force cudnn.benchmark to false (#14390) Some custom nodes try to set this true globally. It messes with dynamic VRAM with one-off spikes that can OOM but this is also very high risk for windows where such allocations might get serviced by shared memory fallback. Trump it. * feat(assets): add job_ids filter to GET /api/assets (#13998) * feat(assets): add job_ids filter to GET /api/assets Mirrors the existing cloud `job_ids` query param on the local Python server: clients can pass a comma-separated list (or repeated query params) of UUIDs to filter assets by their associated job. The `AssetReference.job_id` column already exists, so no migration is needed — this just plumbs the filter through schema → service → query. Marks the parameter as available in both runtimes by dropping the `[cloud-only]` description prefix and the `x-runtime: [cloud]` tag from the OpenAPI spec, per the OSS field-drift convention (absent runtime tag = populated by both local and cloud). * fix(assets): tighten job_ids — array schema, max_length, narrow except From cursor-reviews on the parent commit: - OpenAPI: declare job_ids as `type: array, items: string format: uuid` with `style: form, explode: true` so it matches the documented contract (and matches sibling include_tags/exclude_tags shape). Description now states both accepted shapes explicitly. - Schema: cap `job_ids` at 500 entries (max_length on the Pydantic field) so a client can't splice an unbounded list into the IN clauses. - Schema: drop `AttributeError` from the except — `raw` only contains `str` items by construction, so `uuid.UUID(<str>)` raises `ValueError` exclusively; the second clause was dead code. * fix(assets): tighten job_ids validator + add schema-level tests Aligns with the parallel hardening from draft PR #13848 (now closed as a duplicate). The validator now: - Raises ValueError on non-string list items (was: silently dropped). - Raises ValueError on non-string / non-list top-level values like dict or int (was: silently passed through to Pydantic's downstream coercion). Adds tests-unit/assets_test/queries/test_list_assets_query.py covering the validator end-to-end: CSV canonicalization, dedup order, default empty, invalid UUID, non-string list item, non-string non-list value, and the max_length=500 boundary. * feat(prompt): enforce canonical UUID prompt_id at job creation POST /prompt previously accepted any client-supplied prompt_id verbatim, str()-coercing even non-strings, and minting the literal job id "None" for an explicit JSON null. The new GET /api/assets job_ids filter matches stored job ids as canonical UUIDs exactly, so a non-UUID id minted a job whose assets could never be filtered. - validate_job_id (comfy_execution/jobs.py): requires a string in the canonical lowercase hyphenated UUID form; raises ValueError otherwise, including parseable-but-non-canonical spellings (uppercase, braced, URN, bare hex), which would otherwise be silently rewritten and then miss every exact-match lookup downstream (history keys, websocket correlation, /interrupt, the assets job_ids filter). - POST /prompt: absent or null prompt_id means the server mints uuid4; invalid means 400 invalid_prompt_id on the standard error envelope. - openapi.yaml: document the request-side prompt_id (format uuid, nullable) on PromptRequest. - tests: unit matrix for validate_job_id; integration tests against the booted server covering rejection, acceptance, and null handling. --------- Co-authored-by: guill <jacob.e.segal@gmail.com> * feat(assets): include asset id in executed WebSocket message (#13862) * feat(assets): enrich executed WS message with asset metadata When --enable-assets is set, each file-type output entry in the `executed` WebSocket message now includes id, name, asset_hash, size, and mime_type — matching the shape already returned by /upload/image. The enrichment lives in comfy_execution/asset_enrichment.py (no torch dependency) and is called from both send sites in execution.py: freshly executed nodes register the file inline via register_file_in_place; cached node re-sends look up the existing AssetReference by file path to avoid re-hashing. Errors are caught per-entry so a failure never blocks the WS message from sending. * fix(assets): inject only id in executed WS message per Asset Identity RFC Per the Asset Identity RFC, the executed WebSocket payload should carry id alone — hash is already encoded in the filename, and name/preview_url/ size belong behind GET /api/assets/{id} rather than being pushed eagerly. Simplifies the DB lookup path: we only need ref.id, so the asset.hash null-check is no longer required as a fallback trigger. * fix(assets): reject path traversal when resolving output abs_path Subfolder/filename were joined and absolutized without containment check, so '..' segments or an absolute filename could escape the type's base directory and register an unrelated on-disk file as an asset. Add commonpath-based containment check; skip enrichment (warn, leave entry unchanged) when the resolved path escapes base. Catches ValueError from cross-drive paths on Windows. * docs(assets): drop Asset Identity RFC reference from docstring * docs(assets): trim docstring to what enrichment does, not what it doesn't * test(assets): use real platform paths so containment check works on Windows The previous test setup patched os.path.abspath to identity and used a POSIX-style '/output' base, which collided with Windows path separators in os.path.commonpath. Drop the abspath/join patches and use a real tempdir-rooted base so the containment check runs against actual platform paths. * refactor(assets): enrich at output-processing time, not in the WS send path Per review: enrichment lived inside the client_id-guarded send sites, so a headless run (no websocket client) never registered assets at all, and ui_outputs/history stored the un-enriched entries. Now output_ui is enriched once, right after the node produces it and before it is stored in ui_outputs — so registration happens regardless of connected clients, and the asset id flows into history and the execution cache for free. _send_cached_ui re-sends the stored (already-enriched) dict verbatim, which lets the DB-lookup-by-path fallback be deleted: every enrichment is now a fresh output, and register_file_in_place re-hashes on upsert so an overwritten path can never carry a stale id. * revert(assets): drop job_ids filter from GET /api/assets (#14408) The job_ids query filter added in #13998 has no live consumer: the frontend Generated tab kept sourcing from GET /jobs, and the cloud side removed its equivalent filter from the shared asset spec. Carrying it on the local server only re-introduces Core<->Cloud drift on the shared contract, so remove it to match. Removed: the job_ids field + validator on ListAssetsQuery, the IN(...) clauses in list_references_page, the service/route passthrough, and the filter-only tests. Kept: the canonical-UUID prompt_id enforcement at job creation (also landed in #13998). It stands on its own -- job ids are matched verbatim by history keys, websocket correlation, and /interrupt -- and cloud inherits it by running core for execution, so no divergence is created. * chore(openapi): sync shared API contract from cloud@e3c52ad (#14406) * I don't think this actually works anymore. (#14403) * ops: tolerate already force casted dynamic weight (#14410) Some custom nodes .to weights completely out of load context which can wreak havoc if its for a model that is not active. Detect this condition and just let it fall-through to the non-dynamic loader straight up. --------- Signed-off-by: bigcat88 <bigcat88@icloud.com> Co-authored-by: Alexander Piskun <13381981+bigcat88@users.noreply.github.com> Co-authored-by: Daxiong (Lin) <contact@comfyui-wiki.com> Co-authored-by: Comfy Org PR Bot <snomiao+comfy-pr@gmail.com> Co-authored-by: comfyanonymous <121283862+comfyanonymous@users.noreply.github.com> Co-authored-by: Alexis Rolland <alexisrolland@hotmail.com> Co-authored-by: Jukka Seppänen <40791699+kijai@users.noreply.github.com> Co-authored-by: rattus <46076784+rattus128@users.noreply.github.com> Co-authored-by: Terry Jia <terryjia88@gmail.com> Co-authored-by: John Pollock <pollockjj@users.noreply.github.com> Co-authored-by: Silver <65376327+silveroxides@users.noreply.github.com> Co-authored-by: Matt Miller <mattmiller@comfy.org> Co-authored-by: guill <jacob.e.segal@gmail.com> Co-authored-by: kelseyee <971704395@qq.com> Co-authored-by: Kohaku-Blueleaf <59680068+KohakuBlueleaf@users.noreply.github.com> Co-authored-by: Talmaj <Talmaj@users.noreply.github.com>	2026-06-11 12:04:28 +08:00
Comfy Org PR Bot	bb84c75283	chore(openapi): sync shared API contract from cloud@7c470f0 (#14174)	2026-06-03 13:20:30 -07:00
Matt Miller	921775704c	openapi: document QueueManageResponse body on POST /api/queue (#14117) ... * openapi: document QueueManageResponse body on POST /api/queue The Cloud runtime returns a JSON body from POST /api/queue describing which prompts were deleted and whether the queue was cleared. The spec previously declared a bare 200 with no schema, so generated clients had no type for the response. Adds a QueueManageResponse schema ({deleted, cleared}) and references it from the 200 response. Tagged x-runtime: [cloud] with a [cloud-only] description: local ComfyUI returns an empty 200 body, so both fields are nullable. * openapi: fix GET /api/hub/labels response to the label-catalog shape (#14118) * openapi: fix GET /api/hub/labels response to the label-catalog shape GET /api/hub/labels returns the catalog of available labels you can filter by, which the Cloud runtime serves as {labels: HubLabelInfo[]} (slug name, display_name, and a type category: tag/model/custom_node). The spec had this operation returning a bare array of HubLabel ({id, name, color}) — that schema models the label chips attached to a published workflow (HubWorkflow.labels), a different object. The catalog schema (HubLabelInfo) already existed but was unreferenced. Repoints the 200 response to a new HubLabelListResponse wrapper over the existing HubLabelInfo. HubLabel is unchanged and still used by HubWorkflow.labels. Endpoint remains x-runtime: [cloud]. * openapi: add Cloud-runtime fields (workflow_id, execution_error) to JobEntry (#14119) * openapi: add Cloud-runtime fields workflow_id, execution_error to JobEntry The Cloud runtime returns two additional fields on JobEntry that the spec didn't declare: - workflow_id: UUID of the Cloud workflow entity the job is associated with - execution_error: structured ComfyUI execution error for failed jobs (reuses the existing ExecutionError schema) Both tagged x-runtime: [cloud] with [cloud-only] descriptions; local ComfyUI does not populate them. * openapi: document Cloud-runtime request fields on POST /api/assets/export (#14120) The Cloud runtime accepts three request fields on /api/assets/export that the spec didn't declare: - job_ids: include all assets associated with the given jobs - naming_strategy: how to name files in the ZIP (enum, default group_by_job_time) - job_asset_name_filters: optional per-job asset-name allowlist Also drops asset_ids from required: the runtime supports exporting by job_ids alone, so neither field is individually required. /api/assets/export is already x-runtime: [cloud]; these are plain field additions under that endpoint-level tag.	2026-05-26 16:25:20 -07:00
Matt Miller	ea62dc11c9	openapi: fix invalid BillingStatus schema (object + enum hybrid) (#14071)	2026-05-24 10:58:35 +08:00
Matt Miller	187442cca4	openapi: add enum values + FeedbackRequest schema for cloud cutover (PR E) (#14070) ... * openapi: add enum values + FeedbackRequest schema for cloud cutover (PR E) Adds missing cloud-runtime enum values to vendor schemas that the cloud runtime emits but vendor declared as plain strings. Changes: - JobEntry.status: enum [pending, in_progress, completed, failed, cancelled] - JobDetailResponse.status: same enum - BillingStatus: enum [awaiting_payment_method, pending_payment, paid, payment_failed, inactive] - FeedbackRequest schema added (with type enum) - /api/feedback POST: requestBody now $refs FeedbackRequest All cloud-runtime-emitted; no impact on OSS-local semantics. Identified via Comfy-Org/cloud's TestCutoverSafe gate (BE-1106) as the remaining schema-level divergences after PRs A-D landed and got synced. * openapi: add type enum to Workspace schema (cutover follow-up) Cloud's Workspace runtime shape includes a 'type' field with enum [personal, team] that vendor's Workspace was missing. Cloud handlers reference the generated ingest.WorkspaceType Go enum. Same kind of surgical addition as JobEntry.status / BillingStatus / JobDetailResponse.status in this PR — adds cloud-runtime field to existing vendor schema.	2026-05-22 18:23:22 -07:00
Matt Miller	c3c881f37b	openapi: rename cloud-side response schemas to match runtime (PR D) (#14065) ... * openapi: rename cloud-side response schemas to match runtime (PR D) Follow-up to the BE-1106 stack (#14060/61/63). Cloud's Go handlers reference response schemas by name (e.g., ingest.WorkflowResponse, ingest.SubscribeResponse), but vendor's matching operations were declaring those responses against differently-named vendor-side schemas (CloudWorkflow, BillingSubscription, etc.). After the stack landed, schemas like WorkflowResponse exist in vendor but weren't referenced by any path, so codegen pruned the unreferenced types. This PR: 1. Updates 34 operation $refs in cloud-runtime paths to point to the schema names cloud's handlers expect (e.g., CloudWorkflow → WorkflowResponse on /api/workflows/{workflow_id}). 2. Adds 12 cloud-only schemas that weren't in vendor yet but are referenced by these renames (e.g., SubscribeResponse, CancelSubscriptionResponse, BillingOpStatusResponse). Each copied verbatim from Comfy-Org/cloud's hand-written ingest spec and tagged x-runtime: [cloud] with a [cloud-only] description prefix. Schema renames span the same domains as the operationId renames in PR A: billing/subscriptions (7 schemas), workflows (5), userdata (3), jobs (2), hub (2), history (2), auth/workspace (4), and misc cloud endpoints (9). Convergent safety check after this lands (against cloud's TestCutoverSafe gate, BE-1106): Pre-PR D: 205 missing handler refs Post-PR D: 105 missing handler refs (-49%) Cumulative since the original 938-ref baseline: -89% The remaining 105 are a Phase 3 follow-up (response headers, text/plain responses, codegen-derived enum sub-types, and a small set of inline-response-schema operations that vendor declares inline where cloud has named-schema $refs). * openapi: drop PR-label comment from new schemas block PR-internal labels don't belong in committed code — future readers won't know what 'PR D' means and the marker stops being useful the moment this PR merges.	2026-05-22 16:34:52 -07:00
Matt Miller	7984a6a38e	openapi: rename 55 cloud-side operationIds to match runtime (PR A of 3) (#14060) ... * openapi: rename 55 cloud-side operationIds to match runtime handlers For the 55 operations below, vendor's operationId did not match the name cloud's runtime handlers expect. Generated types from vendor therefore had different names (e.g. CreateSubscription200JSONResponse) than what cloud handlers reference (Subscribe200JSONResponse), which blocks the post-cutover combined-spec codegen. All 55 renames target the cloud-runtime-authoritative name. Several of these endpoints are shared concepts (queue, settings, userdata, object_info) that OSS local also serves — the rename aligns vendor with the longstanding cloud handler-side convention to unblock the shared codegen. No request/response *shape* changes in this PR; only operationId labels. Notable categories: - Billing/subscriptions: 7 renames (subscribe, getBillingPlans, ...) - Workspace + workflows: 13 renames (createWorkflow, ...) - Hub: 3 renames - Auth/users: 5 renames - Shared OSS surface (settings, queue, view, userdata): 12 renames - Misc cloud-only: 15 renames Identified via Comfy-Org/cloud's TestCutoverSafe build-safety gate (BE-1106), which compares handler type references against codegen output from the combined spec. * fix(openapi): resolve getHistory operationId collision Spectral flagged: both /api/history (OSS local) and /api/history_v2 (cloud) had operationId 'getHistory' after the rename. Rename vendor's /api/history to 'getPromptHistory' to disambiguate. Cloud's runtime denies /api/history at the overlay level so combined codegen is unaffected by this change. * openapi: add 41 cloud-runtime schemas to components.schemas (PR B of 3) (#14061) * openapi: add 41 cloud-runtime schemas to components.schemas (cutover prep) Adds schemas that exist in Comfy-Org/cloud's hand-written ingest spec but not yet in this vendored OSS spec. All tagged x-runtime: [cloud] per the field-drift convention and prefixed with [cloud-only] in the description. These schemas are referenced by cloud's Go handlers via the generated ingest.<Schema> Go type names. Codegen from the vendored spec didn't produce those types because the schemas weren't declared here. Adding them unblocks the post-cutover combined-spec codegen. Schemas added (alphabetical): AssetDownloadResponse, AssetMetadataResponse, BillingBalanceResponse, BillingPlansResponse, BillingStatusResponse, GetUserDataResponseFull, HistoryDetailEntry, HistoryDetailResponse, HistoryResponse, HubLabelInfo, HubProfileSummary, HubWorkflowListResponse, HubWorkflowStatus, HubWorkflowSummary, HubWorkflowTemplateEntry, JobStatusResponse, JobsListResponse, LabelRef, LogsResponse, Member, OAuthRegisterBadRequestResponse, PendingInvite, Plan, PlanAvailability, PlanAvailabilityReason, PlanSeatSummary, PreviewPlanInfo, PreviewSubscribeResponse, PublishedWorkflowDetail, SecretResponse, SubscriptionDuration, SubscriptionTier, UserDataResponseFull, ValidationError, ValidationResult, WorkflowForkedFrom, WorkflowResponse, WorkflowVersionContentResponse, WorkspaceAPIKeyInfo, WorkspaceSummary, WorkspaceWithRole Identified via Comfy-Org/cloud's TestCutoverSafe build-safety gate (BE-1106). Companion to PR #14060 (operationId renames). * fix(openapi): add BindingErrorResponse schema OAuthRegisterBadRequestResponse references BindingErrorResponse but that schema wasn't in the original add. Adding it now as a cloud-only schema matching the cloud runtime's binding-error shape (single 'message' string field). * openapi: add missing 4xx/5xx response bodies for cloud-emitting endpoints (#14063) Vendor declares shared endpoints (e.g. /api/queue, /api/settings, /api/assets/*, /api/billing/*) with success responses but is missing many of the 4xx/5xx error response bodies that Comfy-Org/cloud's runtime actually emits. Cloud's Go handlers reference the generated ingest.Op<StatusCode>JSONResponse types for these missing statuses, which currently fail to resolve when codegen runs against the vendored spec. This PR adds 237 response entries across 117 operations, restoring the documented error responses that cloud emits. Bodies are copied verbatim from Comfy-Org/cloud's hand-written ingest spec (services/ingest/openapi.yaml) and reference a new ErrorResponse schema also added in this PR (matches cloud's {code, message} runtime shape, tagged x-runtime: [cloud]). ErrorResponse is intentionally separate from the existing CloudError schema. CloudError's shape ({error}) describes one runtime; cloud emits a different shape ({code, message}). Existing CloudError refs in vendor are untouched; new cloud-emitting error references use ErrorResponse. Identified via Comfy-Org/cloud's TestCutoverSafe build-safety gate (BE-1106). Companion to PR #14060 (operationId renames) and PR #14061 (cloud-only schema additions).	2026-05-22 16:15:18 -07:00
Matt Miller	112fcd5f3b	openapi: align response declarations with implementation (5 endpoints) (#14058) ... * openapi: align response declarations with implementation (5 endpoints) - POST /api/assets/download: replace 200 with 202 + tracking-task body (endpoint runs asynchronously and returns task_id/status/message). - POST /api/assets/export: same 200 → 202 + tracking-task body. - POST /api/assets/from-workflow: change 201 → 200 (handler responds 200, not 201; no Location header emitted). - POST /api/feedback: change 200 → 201 (creates a feedback record). - /api/jobs and /api/jobs/{job_id}: change timestamp fields from type: number to type: integer + format: int64. Values are Unix milliseconds — number causes oapi-codegen to emit float64, losing precision and producing the wrong Go type. Affected fields: create_time, update_time, execution_start_time, execution_end_time. Verification: each change reflects what the endpoint observably returns; no handler changes required. Backwards-compatible for existing clients (integer is a subset of number; status code shifts within 2xx). * openapi: align asset download/export 202 status enum with runtime + sibling schemas CodeRabbit caught a vocabulary mismatch: the two new 202 response schemas declared `[pending, running, completed, failed]` while the rest of the same spec uses `[created, running, completed, failed]` for the identical task lifecycle (download/export progress WebSocket events, /api/tasks, TaskEntry, TaskResponse — 4 sites total). Cloud's runtime emits `created` on initial creation (AssetDownloadResponseStatusCreated; task.Status sourced from the DB enum whose initial value is Created). `pending` would have introduced a fifth, contradictory vocabulary for the same lifecycle and pushed the spec further from the implementation it is meant to align with. Followup tracked separately: extract a shared TaskStatus enum so all five sites move in lockstep instead of needing per-site edits.	2026-05-22 14:31:43 -07:00
Matt Miller	1668aaf037	openapi: remove cloud-only job_ids query param from GET /api/assets (#14016) ... The job_ids query parameter on GET /api/assets is tagged x-runtime: [cloud] and only exists for cloud's variant of this endpoint. Cloud removed all consumers and the cloud-side handler/codegen/tests in Comfy-Org/cloud#3778. With cloud no longer accepting this parameter, the [cloud-only] documentation here is wrong — drop it so the daily sync to cloud/services/ingest/vendor/openapi.yaml propagates the removal.	2026-05-20 21:32:08 -07:00
Matt Miller	ea174d3f12	fix(openapi): correct POST /api/assets/import to importPublishedAssets (#14027) ... The operation at POST /api/assets/import was defined as `importAssets` with a URL-list body shape, but no runtime actually serves that operation at this path. The cloud runtime serves a different operation here — `importPublishedAssets` — which imports published-workflow assets into the caller's library by ID, not by URL. Cloud's URL-based asset ingestion lives at separate paths (POST /assets/download + GET /assets/remote-metadata) tracked elsewhere; nothing in this PR affects that work. Changes: - Replace the operation at POST /api/assets/import with `importPublishedAssets`, taking ImportPublishedAssetsRequest (published_asset_ids + optional share_id) and returning ImportPublishedAssetsResponse (list of AssetInfo). - Remove the unused AssetImportRequest component schema (no other references in the spec). - Operation and schemas tagged x-runtime: [cloud] with [cloud-only] description prefix, matching the existing convention for cloud-runtime-only operations elsewhere in the spec. Spectral lint passes (0 errors); the two hint-level findings on the spec are pre-existing and unrelated. No FE consumer references AssetImportRequest today; this is a pure spec correction to match what the cloud runtime actually serves.	2026-05-20 21:28:16 -07:00
Matt Miller	9f9b32ed97	feat: add OAuth 2.1 + RFC 7591 DCR endpoints to openapi.yaml (#14026) ... Add the OAuth 2.1 authorization flow and RFC 7591 Dynamic Client Registration endpoints to the shared spec, alongside the existing auth-tagged operations (/api/auth/session, /api/auth/token, /.well-known/jwks.json). All tagged x-runtime: [cloud] with a [cloud-only] description prefix, following the established convention for cloud-runtime-only operations. Endpoints: - GET /.well-known/oauth-authorization-server (RFC 8414 metadata) - GET /.well-known/oauth-protected-resource (RFC 9728 metadata) - GET /oauth/authorize (consent challenge) - POST /oauth/authorize (consent submission) - POST /oauth/token (RFC 6749 §3.2) - POST /oauth/register (RFC 7591 §3.1 DCR) Component schemas added: - OAuthAuthorizationServerMetadata - OAuthProtectedResourceMetadata - OAuthConsentChallenge, OAuthConsentChallengeWorkspace - OAuthAuthorizeRedirectResponse - OAuthTokenResponse, OAuthTokenError - OAuthRegisterRequest, OAuthRegisterResponse, OAuthRegisterError These endpoints are implemented in the cloud runtime today and are called by browser frontends rendering the consent UI and by MCP-spec-compliant clients (Claude Desktop, Cursor, etc.) doing auto-discovery + self-registration. Documenting them in the shared spec lets the cloud frontend generate types directly from this spec instead of maintaining a parallel definition. Spectral lints clean (0 errors). The hint-level findings on OAuthTokenError / OAuthRegisterError ("standard error schema") match the same hint on CloudError — these are protocol-specific RFC-shaped errors, not generic application errors.	2026-05-20 21:22:12 -07:00
Matt Miller	6887165a9d	docs(openapi): tighten workspace API key description field (BE-1004) (#13996) ... Aligns the OSS spec with the cloud-side BE-1004 contract: - createWorkspaceApiKey request body: add maxLength: 5000 to the description property (matches cloud's hub_profile.description MaxLen(5000) convention; enforced cloud-side via handler check). - WorkspaceApiKey + WorkspaceApiKeyCreated response schemas: mark description as required (cloud's handler always populates the field, defaulting to empty string when not supplied on create), drop nullable: true, add maxLength: 5000 for symmetry, and clarify the doc string ("Always present in responses; empty string when no description was supplied on create"). Both schemas are tagged x-runtime: [cloud] at the schema level so the tightening is correctly scoped — OSS-only implementations are not required to honor the workspace API keys endpoints at all. Related cloud PR: Comfy-Org/cloud#3747	2026-05-19 16:55:04 -07:00
Matt Miller	cc4d711eb1	feat(openapi): add optional description field to workspace API key schemas (#13993) ... * feat(openapi): add optional description field to workspace API key schemas Add an optional `description` property (type: string) to three workspace API key schemas in openapi.yaml: - Inline request body of createWorkspaceApiKey (POST /api/workspace/api-keys) - WorkspaceApiKey (list/info schema) - WorkspaceApiKeyCreated (creation response schema) The field is not added to any `required` array, making it fully backward-compatible with existing clients. Refs: BE-1005, BE-1004 Co-authored-by: Matt Miller <mattmillerai@users.noreply.github.com> * fix(openapi): mark description nullable in workspace API key response schemas Per CodeRabbit review on PR #13993: the underlying DB column is nullable varchar (default ''), so the response schemas should permit null to match stored data reality. Without nullable: true the OpenAPI contract would require coercion on the handler side or risk a contract violation. Request schema unchanged — clients shouldn't be sending null on create.	2026-05-19 14:48:47 -07:00
Matt Miller	d0328b442d	docs(openapi): remove top-level width/height fields on Asset schema (#13973) ... These two fields were added recently to the Asset schema as nullable integers, with the intent of exposing original image dimensions for FE consumers (cloud-side thumbnailing makes naturalWidth/Height return the wrong size for an image card's dimension label). The implementation effort that consumes them subsequently converged on a different shape — dimensions nested under the existing free-form `metadata` JSON field as `{kind: "image", width, height}` — to avoid introducing type-specific flat fields on the canonical Asset shape, and to leave room for forward-compatible additions (video duration, fps, etc.) without further schema churn. This removes the now-unused top-level fields so the spec reflects the agreed direction. No other schema definitions reference these fields directly: AssetCreated, AssetUpdated, etc. inherit Asset via allOf and do not redefine them. The runtime ingest implementation that would have populated these fields was not yet shipped, so no clients are relying on the top-level shape. Co-authored-by: Alexis Rolland <alexisrolland@hotmail.com>	2026-05-19 10:00:26 -07:00
Matt Miller	6b61918a16	docs(openapi): deprecate /api/upload/mask in favor of /api/upload/image (#13968) ... Mark the uploadMask operation as deprecated and point clients at /api/upload/image. The mask-compositing behavior the endpoint provides (alpha-compositing the supplied mask onto an original_ref image) is now expected to happen client-side, with the composited result uploaded through the unified /api/upload/image path. The endpoint continues to function for older clients; no runtime behavior changes ship with this commit. Only the OpenAPI annotation and the human-facing description are updated.	2026-05-19 12:19:51 +08:00
Christian Byrne	b112f68681	Generalize frontend version warning to all comfy* requirements.txt entries (#13875)	2026-05-14 16:13:30 -07:00
Matt Miller	fb097bedc2	Mark deprecated cloud-runtime endpoints in spec (#13789) ... * Mark deprecated cloud-runtime endpoints in openapi.yaml Add five cloud-runtime FE-facing endpoints to the OSS spec with deprecated: true and standardized description prefixes: - GET /api/history_v2 — superseded by GET /api/jobs - GET /api/history_v2/{prompt_id} — superseded by GET /api/jobs/{prompt_id} - GET /api/logs — returns static placeholder; no real log data - GET /api/viewvideo — alias of GET /api/view for legacy video playback - GET /api/job/{job_id}/status — superseded by GET /api/jobs/{job_id} Each endpoint is tagged x-runtime: [cloud] and follows the same deprecation convention established for /api/history endpoints. Co-authored-by: Matt Miller <MillerMedia@users.noreply.github.com> * fix(spec): consolidate duplicate path entries on deprecated cloud-runtime endpoints Previous commit added new path entries with `deprecated: true` for `/api/job/{job_id}/status`, `/api/history_v2`, `/api/history_v2/{prompt_id}`, `/api/logs`, and `/api/viewvideo`, but the canonical entries already existed elsewhere in the file. Result: 5 duplicate path keys (Spectral parser errors), and the deprecation flag did not land on the operations that FE clients consume by operationId. This commit moves `deprecated: true` plus the standardized "Deprecated." description onto the canonical operations (`getCloudJobStatus`, `getHistoryV2`, `getHistoryV2ByPromptId`, `getCloudLogs`, `viewVideo`) and removes the duplicate entries. Operation IDs and response schemas are unchanged. Spectral lint passes with zero new warnings.	2026-05-12 11:06:28 -07:00
Matt Miller	4e823431cc	Add cloud-runtime experiment node-schema endpoints to spec (#13806) ... * Add cloud-runtime experiment node-schema endpoints to spec Replace the GET operations at /api/experiment/nodes and /api/experiment/nodes/{id} with getNodeInfoSchema and getNodeByID — the optimized, ETag-tagged object_info schema endpoints the cloud frontend depends on for the workflow editor. Each operation is tagged x-runtime: [cloud] and uses the runtime-only tag for cloud-side codegen exclusion. Response headers document the ETag and Cache-Control validators; 304 Not Modified is declared for RFC 7232 conditional GETs. Remove the now-unused CloudNodeList schema to keep Spectral clean. Co-authored-by: Matt Miller <MillerMedia@users.noreply.github.com> * spec: document If-None-Match header on conditional GET endpoints Both `getNodeInfoSchema` and `getNodeByID` advertise `ETag` response headers and a `304 Not Modified` response, but the spec didn't declare the `If-None-Match` request header that triggers conditional validation. Adding it as an optional header parameter on both ops so client codegen exposes the conditional-GET pattern.	2026-05-08 19:14:23 -07:00
Matt Miller	87878f354f	Add cloud-runtime FE-facing operations to spec (#13734) ... * Add cloud-runtime FE-facing operations to openapi.yaml Add ~67 cloud-runtime FE-facing path operations to the core OpenAPI spec, each tagged with x-runtime: [cloud] at the operation level. These operations are served by the cloud runtime; the local runtime returns 404 for all of these paths. Domain groups added: - Jobs / prompts: /api/job/*, /api/jobs/*/cancel, /api/prompt/*, etc. - History v2: /api/history_v2, /api/history_v2/{prompt_id} - Cloud logs: /api/logs - Asset extensions: /api/assets/download, export, import, etc. - Custom nodes: /api/experiment/nodes (cloud install/uninstall) - Hub: /api/hub/profiles, /api/hub/workflows, /api/hub/labels, etc. - Workflows: /api/workflows CRUD, versioning, fork, publish - Auth/session: /api/auth/session, /api/auth/token, /.well-known/jwks.json - Billing: /api/billing/balance, plans, subscribe, topup, etc. - Workspace: /api/workspace/*, /api/workspaces/* - User/settings/misc: /api/user, /api/secrets, /api/feedback, etc. Also adds corresponding cloud-only component schemas (CloudJob, CloudWorkflow, BillingPlan, Workspace, HubProfile, AuthSession, etc.), all tagged with x-runtime: [cloud]. Spectral lint passes under the existing ruleset with zero new warnings. * Add job_id field to Asset schema and deprecate prompt_id (#13736) - Add job_id as a nullable UUID field to the Asset schema - Mark prompt_id as deprecated with note pointing to job_id - No x-runtime tag needed as both runtimes populate the field * Add hash field to Asset schemas and deprecate asset_hash (#13738) - Add 'hash' as a nullable string field to Asset and AssetUpdated schemas - Mark 'asset_hash' as deprecated with a note pointing to 'hash' - AssetCreated inherits 'hash' via allOf from Asset - Spectral lint clean (no new warnings) * Fix method drift on cloud-runtime endpoints Three PUT operations were added that should be PATCH (cloud serves PATCH for partial updates): - /api/workflows/{workflow_id} - /api/workspaces/{id} - /api/workspace/members/{userId} Two POST operations were added that should be GET (cloud serves GET with query params): - /api/assets/remote-metadata (url moves to query param) - /api/files/mask-layers (response shape replaced — operation queries related mask layer filenames, not file uploads) * Add missing cloud-runtime operations and schemas PR review surfaced operations the cloud runtime serves that weren't covered by the initial spec push, plus one path family missed entirely. New methods on existing paths: - /api/auth/session: add POST (create session cookie) and DELETE (logout) - /api/secrets/{id}: add GET (read metadata) and PATCH (update) - /api/hub/profiles: add POST (create profile) - /api/hub/workflows: add POST (publish to hub) - /api/hub/workflows/{share_id}: add DELETE (unpublish) - /api/workspaces/{id}: add DELETE (soft-delete workspace) - /api/workspace/members/{user_id}/api-keys: add DELETE (bulk revoke) - /api/workflows/{workflow_id}/versions: add POST (create new version) - /api/userdata/{file}/publish: add GET (read publish info) New path family: - /api/tasks (GET list) and /api/tasks/{task_id} (GET detail) for the background task framework New component schemas (all tagged x-runtime: [cloud]): CreateSessionResponse, DeleteSessionResponse, UpdateSecretRequest, BulkRevokeAPIKeysResponse, CreateHubProfileRequest, PublishHubWorkflowRequest, HubWorkflowDetail, AssetInfo, CreateWorkflowVersionRequest, WorkflowVersionResponse, WorkflowPublishInfo, TaskEntry, TaskResponse, TasksListResponse. Existing SecretMeta extended with provider and last_used_at fields the cloud runtime actually returns. New tag: task. Spectral lint passes with zero errors. * Add job_id and prompt_id to AssetUpdated schema Mirrors the Asset schema's deprecation pattern: prompt_id is marked deprecated with a description pointing to job_id; job_id is the new preferred field. PUT /api/assets/{id} responses can now carry both fields consistent with the other Asset-returning endpoints. * feat: add width and height fields to Asset schema (#13745) Add nullable integer fields 'width' and 'height' to the Asset schema in openapi.yaml. These expose original image dimensions in pixels for clients that need pre-thumbnail size info. Both fields are null for non-image assets or assets ingested before dimension extraction. Co-authored-by: Matt Miller <MillerMedia@users.noreply.github.com> * Remove /api/job/{job_id} and /api/job/{job_id}/outputs These two paths are not actually served by the cloud runtime — they return 404 with a redirect message pointing callers to the canonical `/api/jobs/{job_id}` (plural). Declaring them with `x-runtime: [cloud]` and a 200 response schema is incorrect. `/api/job/{job_id}/status` stays — it is a real cloud-served endpoint. Also drops the now-orphaned `CloudJob` and `CloudJobOutputs` component schemas. `CloudJobStatus` is retained.	2026-05-08 12:39:16 -07:00
Matt Miller	89014792c9	feat: add cloud-specific fields to OSS openapi.yaml as nullable (#13623) ... * feat: add cloud-specific fields to OSS openapi.yaml as nullable Add cross-runtime fields with x-runtime: [cloud] extension and [cloud-only] description prefix per the convention established in BE-613. All new fields are nullable and not in required arrays, so they are purely additive. /api/features response: - max_upload_size (integer, int64) - free_tier_credits (integer, int32) - posthog_api_host (string, uri) - max_concurrent_jobs (integer, int32) - workflow_templates_version (string) - workflow_templates_source (string, enum) PromptRequest schema: - workflow_id (string, uuid) - workflow_version_id (string, uuid) POST /api/assets: - id field (uuid) on multipart/form-data for idempotent creation - application/json alternate content-type for URL-based uploads POST /api/assets/from-hash: - mime_type (string) to preserve type without re-inspection PUT /api/assets/{id}: - mime_type (string) for overriding auto-detection GET /api/assets additional query parameters: - job_ids (string) — filter by associated job UUIDs - include_public (boolean) — include workspace-public assets - asset_hash (string) — filter by exact content hash Resolves: BE-613 Blocks: BE-364, BE-361, BE-363 Co-authored-by: Matt Miller <MillerMedia@users.noreply.github.com> * fix(openapi): address CodeRabbit feedback (BE-613) - max_upload_size is set in both runtimes via SERVER_FEATURE_FLAGS; drop the cloud-only / nullable tagging. - Require `url` on the application/json POST /api/assets body so the contract is enforceable by validators and codegen. --------- Co-authored-by: Matt Miller <MillerMedia@users.noreply.github.com>	2026-05-05 14:20:09 -07:00
Matt Miller	413e250ccd	spec: add workflow_id / workflow_version_id to PromptRequest with x-runtime tag (#13709) ... Adds two optional, nullable UUID fields to PromptRequest for runtimes that wrap workflow execution in a workflow-version entity (the hosted-cloud runtime does this; local ComfyUI does not). Both fields are tagged `x-runtime: [cloud]` to mark them as runtime-specific — local ComfyUI returns `null` (or omits them entirely) and that's correct behavior, not drift. ## Why these fields belong in the OSS spec Hosted-cloud's frontend and backend share `openapi.yaml` as their single source of truth via auto-generated client types. Without the fields declared in the spec, the cloud runtime has to either: 1. Hand-edit a vendored copy of openapi.yaml (drift between vendor and upstream — unsustainable). 2. Maintain a separate cloud-only spec file (forks the contract, defeats the point of a shared OSS spec). Both options have been tried and both produce maintenance pain. The shape that scales is: cloud-only fields live in OSS spec under their intended path, declared nullable, with an explicit `x-runtime` tag so local-only readers can ignore them programmatically and human readers can see what each runtime populates. ## About the `x-runtime` extension This is the first use of `x-runtime` in this spec. Convention: - `x-runtime: [cloud]` — only the hosted-cloud runtime populates the field; local returns null or omits. - `x-runtime: [local]` — only local populates; cloud returns null. - Tag absent — both runtimes populate the field (the default). This is a vendor extension (`x-` prefix) and is ignored by spec validators that don't recognize it, including `kin-openapi`. Local clients reading the spec see two extra optional nullable fields, which is forward-compatible with all existing readers. ## What this does not change - No Python code changes. `PromptRequest` already accepts arbitrary optional fields (`extra_data: additionalProperties: true` on the same schema is a stronger guarantee). The Python server already silently accepts and ignores both fields today. - No required-fields change. Both fields stay outside `required`, so older clients that don't know about them keep validating. - No nullability widening on existing fields. ## Verification - YAML parses (`yaml.safe_load`). - `kin-openapi` `loader.LoadFromFile` accepts the modified spec. - `openapi3filter.ValidateRequest` on a PromptRequest with both fields set to `null`, set to a valid UUID, or omitted — all pass.	2026-05-04 18:59:48 -07:00
Matt Miller	35819e35a8	fix(spec): mark DeviceStats.index and NodeInfo.essentials_category as nullable (#13706) ... * fix(spec): mark DeviceStats.index and NodeInfo.essentials_category as nullable Two fields in openapi.yaml are declared as required/non-nullable but the Python implementation legitimately returns `null` for them, so any client that response-validates against the spec will fail. `DeviceStats.index` (used by GET /api/system_stats): - server.py emits `"index": device.index` unconditionally - For the CPU device (--cpu mode), `torch.device("cpu").index` is `None` - → JSON response includes `"index": null` for CPU devices `NodeInfo.essentials_category` (used by GET /api/object_info): - The V3 schema-based path (comfy_api/latest/_io.py:1654) unconditionally passes `essentials_category=self.essentials_category` into NodeInfoV1 and serializes via dataclasses.asdict(), so the key is always present - Schema's `essentials_category` defaults to `None` for nodes that don't set it in `define_schema` (e.g. the APG node) - → JSON response includes `"essentials_category": null` for those nodes - (The V1 path in server.py uses `hasattr` and so omits the key entirely when not set, but the V3 path is the one that produces nulls) Both fields keep their existing `required` status — they're always present in the response, the value is just nullable. Descriptions expanded to spell out when `null` is expected. * docs(spec): clarify essentials_category presence rules The previous description said "null for nodes that don't set ESSENTIALS_CATEGORY (V1)" — that's wrong. server.py:739-740 uses `hasattr` and OMITS the key when the V1 attribute isn't defined; null only happens if the attribute is explicitly set to None. Spell out all three legal shapes (string / null / absent) and which path produces which.	2026-05-04 18:28:21 -07:00
Matt Miller	443074eee9	Add OpenAPI 3.1 specification for ComfyUI API (#13397) ... * Add OpenAPI 3.1 specification for ComfyUI API Adds a comprehensive OpenAPI 3.1 spec documenting all HTTP endpoints exposed by ComfyUI's server, including prompt execution, queue management, file uploads, userdata, settings, system stats, object info, assets, and internal routes. The spec was validated against the source code with adversarial review from multiple models, and passes Spectral linting with zero errors. Also removes openapi.yaml from .gitignore so the spec is tracked. * Mark /api/history endpoints as deprecated Address Jacob's review feedback on PR #13397 by explicitly marking the three /api/history operations as deprecated in the OpenAPI spec: * GET /api/history -> superseded by GET /api/jobs * POST /api/history -> superseded by /api/jobs management * GET /api/history/{prompt_id} -> superseded by GET /api/jobs/{job_id} Each operation gains deprecated: true plus a description that names the replacement. A formal sunset timeline (RFC 8594 Deprecation and RFC 8553 Sunset headers, minimum-runway policy) is being defined separately and will be applied as a follow-up. * Address Spectral lint findings in openapi.yaml - Add operation descriptions to 52 endpoints (prompt, queue, upload, view, models, userdata, settings, assets, internal, etc.) - Add schema descriptions to 22 component schemas - Add parameter descriptions to 8 path parameters that were missing them - Remove 6 unused component schemas: TaskOutput, EmbeddingsResponse, ExtensionsResponse, LogRawResponse, UserInfo, UserDataFullInfo No wire/shape changes. Reduces Spectral findings from 92 to 4. The remaining 4 are real issues (WebSocket 101 on /ws, loose error schema, and two snake_case warnings on real wire field names) and are worth addressing separately. * fix(openapi): address jtreminio oneOf review on /api/userdata Restructure the UserData response schemas to address the review feedback on the `oneOf` without a discriminator, and fix two accuracy bugs found while doing it. Changes - GET /api/userdata response: extract the inline `oneOf` to a named schema (`ListUserdataResponse`) and add the missing third variant returned when `split=true` and `full_info=false` (array of `[relative_path, ...path_components]`). Previously only two of the three actual server response shapes were described. - UserDataResponse (POST endpoints): correct the description — this schema is a single item, not a list — and point at the canonical `GetUserDataResponseFullFile` schema instead of the duplicate `UserDataResponseFull`. Also removes the malformed blank line in `UserDataResponseShort`. - Delete the now-unused `UserDataResponseFull` and `UserDataResponseShort` schemas (replaced by reuse of `GetUserDataResponseFullFile` and an inline string variant). - Add an `x-variant-selector` vendor extension to both `oneOf` sites documenting which query-parameter combination selects which branch, since a true OpenAPI `discriminator` is not applicable (the variants are type-disjoint and the selector lives in the request, not the response body). This keeps the shapes the server actually emits (no wire-breaking change) while making the selection rule explicit for SDK generators and readers. --------- Co-authored-by: guill <jacob.e.segal@gmail.com>	2026-04-23 21:00:25 -07:00