_common.py 33 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835
  1. """
  2. _common.py — Shared logic for ComfyUI skill scripts.
  3. Single source of truth for:
  4. - HTTP transport (with retry/backoff, streaming, timeout handling)
  5. - Cloud detection and endpoint mapping (local ComfyUI vs Comfy Cloud)
  6. - Workflow node-type catalogs (param patterns, model loaders, output nodes)
  7. - API-format validation
  8. - Path-traversal-safe file writes
  9. - API-key loading from env / CLI
  10. Stdlib-only by design (with optional `requests` upgrade if installed). Python 3.10+.
  11. """
  12. from __future__ import annotations
  13. import json
  14. import os
  15. import random
  16. import re
  17. import sys
  18. import time
  19. import uuid
  20. from dataclasses import dataclass
  21. from pathlib import Path
  22. from typing import Any, Iterator
  23. from urllib.parse import urlparse
  24. # Optional: prefer `requests` if installed (better redirects, streaming, header handling)
  25. try:
  26. import requests # type: ignore[import-not-found]
  27. HAS_REQUESTS = True
  28. except ImportError: # pragma: no cover - exercised via stdlib fallback
  29. HAS_REQUESTS = False
  30. import urllib.error
  31. import urllib.request
  32. # =============================================================================
  33. # Constants & catalogs
  34. # =============================================================================
  35. DEFAULT_LOCAL_HOST = "http://127.0.0.1:8188"
  36. DEFAULT_CLOUD_HOST = "https://cloud.comfy.org"
  37. ENV_API_KEY = "COMFY_CLOUD_API_KEY" # env var NAME (placeholder, not a secret value)
  38. # Connection / retry defaults
  39. DEFAULT_HTTP_TIMEOUT = 60 # seconds — single-attempt request timeout
  40. DEFAULT_RETRIES = 3 # total attempts including the first
  41. RETRY_BASE_DELAY = 1.0 # seconds — exponential backoff base
  42. RETRY_MAX_DELAY = 30.0 # seconds — cap on backoff
  43. RETRY_STATUS_CODES = {408, 429, 500, 502, 503, 504, 522, 524}
  44. # Streaming download chunk size (bytes)
  45. DOWNLOAD_CHUNK_SIZE = 1 << 16 # 64 KiB
  46. # Heuristic: workflows with these node types tend to be slow → larger default timeout
  47. SLOW_OUTPUT_NODES = {
  48. "VHS_VideoCombine", "SaveAnimatedWEBP", "SaveAnimatedPNG",
  49. "SaveVideo", "SaveAudio", "SaveAnimateDiffVideo",
  50. "SVD_img2vid_Conditioning",
  51. "WanVideoSampler", "HunyuanVideoSampler",
  52. "CogVideoSampler", "LTXVideoSampler",
  53. }
  54. # ---------------------------------------------------------------------------
  55. # Output node catalog (extensible — community packs add their own)
  56. # ---------------------------------------------------------------------------
  57. OUTPUT_NODES: set[str] = {
  58. # Built-in
  59. "SaveImage", "PreviewImage",
  60. "SaveAudio", "SaveVideo", "PreviewAudio", "PreviewVideo",
  61. "SaveAnimatedWEBP", "SaveAnimatedPNG",
  62. # Common community packs
  63. "VHS_VideoCombine", # Video Helper Suite
  64. "ImageSave", # Was Node Suite
  65. "Image Save", # Was Node Suite (alt name)
  66. "easy imageSave", # easy-use
  67. "Image Save With Metadata",
  68. "PreviewImage|pysssss", # pysssss preview
  69. "ShowText|pysssss",
  70. "SaveLatent",
  71. "SaveGLB", # 3D
  72. "Save3D",
  73. }
  74. # ---------------------------------------------------------------------------
  75. # Folder aliases — handle ComfyUI's gradual folder renames
  76. # ---------------------------------------------------------------------------
  77. # When `check_deps.py` queries `/models/<folder>` and gets 404 / empty,
  78. # it tries each alias in turn. Critical for Comfy Cloud which has fully
  79. # migrated to the new naming (unet → diffusion_models, clip → text_encoders).
  80. FOLDER_ALIASES: dict[str, list[str]] = {
  81. "unet": ["unet", "diffusion_models"],
  82. "diffusion_models": ["diffusion_models", "unet"],
  83. "clip": ["clip", "text_encoders"],
  84. "text_encoders": ["text_encoders", "clip"],
  85. "controlnet": ["controlnet", "control_net"],
  86. }
  87. def folder_aliases_for(folder: str) -> list[str]:
  88. """Return the search order of folder names (primary first)."""
  89. return FOLDER_ALIASES.get(folder, [folder])
  90. # ---------------------------------------------------------------------------
  91. # Model-loader catalog: class_type -> (input field, model folder)
  92. # ---------------------------------------------------------------------------
  93. # A loader can have multiple fields (e.g., DualCLIPLoader has clip_name1 and
  94. # clip_name2). We list them with explicit entries. The folder name is the
  95. # *canonical* one; FOLDER_ALIASES is consulted when querying.
  96. MODEL_LOADERS: dict[str, list[tuple[str, str]]] = {
  97. # Checkpoints
  98. "CheckpointLoaderSimple": [("ckpt_name", "checkpoints")],
  99. "CheckpointLoader": [("ckpt_name", "checkpoints")],
  100. "CheckpointLoader (Simple)": [("ckpt_name", "checkpoints")],
  101. "ImageOnlyCheckpointLoader": [("ckpt_name", "checkpoints")],
  102. "unCLIPCheckpointLoader": [("ckpt_name", "checkpoints")],
  103. # LoRA
  104. "LoraLoader": [("lora_name", "loras")],
  105. "LoraLoaderModelOnly": [("lora_name", "loras")],
  106. "LoraLoaderTagsQuery": [("lora_name", "loras")],
  107. # VAE
  108. "VAELoader": [("vae_name", "vae")],
  109. # ControlNet
  110. "ControlNetLoader": [("control_net_name", "controlnet")],
  111. "DiffControlNetLoader": [("control_net_name", "controlnet")],
  112. "ControlNetLoaderAdvanced": [("control_net_name", "controlnet")],
  113. # CLIP / text encoders (primary "clip" folder; check_deps tries text_encoders too)
  114. "CLIPLoader": [("clip_name", "clip")],
  115. "DualCLIPLoader": [("clip_name1", "clip"), ("clip_name2", "clip")],
  116. "TripleCLIPLoader": [("clip_name1", "clip"), ("clip_name2", "clip"), ("clip_name3", "clip")],
  117. "CLIPVisionLoader": [("clip_name", "clip_vision")],
  118. # UNET / Diffusion model (primary "unet"; check_deps tries diffusion_models too)
  119. "UNETLoader": [("unet_name", "unet")],
  120. "DiffusionModelLoader": [("model_name", "diffusion_models")],
  121. "UNETLoaderGGUF": [("unet_name", "unet")],
  122. # Upscaler
  123. "UpscaleModelLoader": [("model_name", "upscale_models")],
  124. # Style / GLIGEN / Hypernetwork
  125. "StyleModelLoader": [("style_model_name", "style_models")],
  126. "GLIGENLoader": [("gligen_name", "gligen")],
  127. "HypernetworkLoader": [("hypernetwork_name", "hypernetworks")],
  128. # IPAdapter family (community).
  129. # Note: IPAdapterUnifiedLoader's `preset` and IPAdapterInsightFaceLoader's
  130. # `provider` are enums (not file paths), so they're intentionally omitted —
  131. # check_deps would otherwise treat enum values as missing model files.
  132. "IPAdapterModelLoader": [("ipadapter_file", "ipadapter")],
  133. "InstantIDModelLoader": [("instantid_file", "instantid")],
  134. # AnimateDiff / video
  135. "ADE_LoadAnimateDiffModel": [("model_name", "animatediff_models")],
  136. "ADE_AnimateDiffLoaderWithContext": [("model_name", "animatediff_models")],
  137. "ADE_AnimateDiffLoaderGen1": [("model_name", "animatediff_models")],
  138. # Photomaker
  139. "PhotoMakerLoader": [("photomaker_model_name", "photomaker")],
  140. # Sampler / scheduler models
  141. "ModelSamplingFlux": [], # parametric only
  142. }
  143. # ---------------------------------------------------------------------------
  144. # Param patterns: (class_type, field_name) -> friendly_name
  145. # Order matters — first match wins for naming. Use _meta.title for disambiguation.
  146. # ---------------------------------------------------------------------------
  147. PARAM_PATTERNS: list[tuple[str, str, str]] = [
  148. # ---- Prompts ----
  149. ("CLIPTextEncode", "text", "prompt"),
  150. ("CLIPTextEncodeSDXL", "text_g", "prompt"),
  151. ("CLIPTextEncodeSDXL", "text_l", "prompt_l"),
  152. ("CLIPTextEncodeSDXLRefiner", "text", "refiner_prompt"),
  153. ("CLIPTextEncodeFlux", "clip_l", "prompt_l"),
  154. ("CLIPTextEncodeFlux", "t5xxl", "prompt"),
  155. ("CLIPTextEncodeFlux", "guidance", "guidance"),
  156. ("smZ CLIPTextEncode", "text", "prompt"),
  157. ("BNK_CLIPTextEncodeAdvanced", "text", "prompt"),
  158. # ---- Standard sampling ----
  159. ("KSampler", "seed", "seed"),
  160. ("KSampler", "steps", "steps"),
  161. ("KSampler", "cfg", "cfg"),
  162. ("KSampler", "sampler_name", "sampler_name"),
  163. ("KSampler", "scheduler", "scheduler"),
  164. ("KSampler", "denoise", "denoise"),
  165. ("KSamplerAdvanced", "noise_seed", "seed"),
  166. ("KSamplerAdvanced", "steps", "steps"),
  167. ("KSamplerAdvanced", "cfg", "cfg"),
  168. ("KSamplerAdvanced", "sampler_name", "sampler_name"),
  169. ("KSamplerAdvanced", "scheduler", "scheduler"),
  170. ("KSamplerAdvanced", "start_at_step", "start_at_step"),
  171. ("KSamplerAdvanced", "end_at_step", "end_at_step"),
  172. # ---- Modern sampler chain (Flux / SD3 / SDXL refiner via SamplerCustom) ----
  173. ("RandomNoise", "noise_seed", "seed"),
  174. ("BasicScheduler", "steps", "steps"),
  175. ("BasicScheduler", "scheduler", "scheduler"),
  176. ("BasicScheduler", "denoise", "denoise"),
  177. ("KSamplerSelect", "sampler_name", "sampler_name"),
  178. # NB: BasicGuider has no cfg input (it just bundles model+conditioning).
  179. ("CFGGuider", "cfg", "cfg"),
  180. ("DualCFGGuider", "cfg_conds", "cfg"),
  181. ("DualCFGGuider", "cfg_cond2_negative", "cfg_negative"),
  182. ("ModelSamplingFlux", "max_shift", "max_shift"),
  183. ("ModelSamplingFlux", "base_shift", "base_shift"),
  184. ("ModelSamplingFlux", "width", "model_width"),
  185. ("ModelSamplingFlux", "height", "model_height"),
  186. ("ModelSamplingSD3", "shift", "shift"),
  187. ("ModelSamplingDiscrete", "sampling", "sampling"),
  188. ("SDTurboScheduler", "steps", "steps"),
  189. ("SDTurboScheduler", "denoise", "denoise"),
  190. ("SamplerCustom", "noise_seed", "seed"),
  191. ("SamplerCustom", "cfg", "cfg"),
  192. # NB: SamplerCustomAdvanced takes a NOISE input (from RandomNoise) — no seed field directly.
  193. # ---- Dimensions / latent ----
  194. ("EmptyLatentImage", "width", "width"),
  195. ("EmptyLatentImage", "height", "height"),
  196. ("EmptyLatentImage", "batch_size", "batch_size"),
  197. ("EmptySD3LatentImage", "width", "width"),
  198. ("EmptySD3LatentImage", "height", "height"),
  199. ("EmptySD3LatentImage", "batch_size", "batch_size"),
  200. ("EmptyHunyuanLatentVideo", "width", "width"),
  201. ("EmptyHunyuanLatentVideo", "height", "height"),
  202. ("EmptyHunyuanLatentVideo", "length", "length"),
  203. ("EmptyHunyuanLatentVideo", "batch_size", "batch_size"),
  204. ("EmptyMochiLatentVideo", "width", "width"),
  205. ("EmptyMochiLatentVideo", "height", "height"),
  206. ("EmptyMochiLatentVideo", "length", "length"),
  207. ("EmptyLTXVLatentVideo", "width", "width"),
  208. ("EmptyLTXVLatentVideo", "height", "height"),
  209. ("EmptyLTXVLatentVideo", "length", "length"),
  210. ("LatentUpscale", "width", "upscale_width"),
  211. ("LatentUpscale", "height", "upscale_height"),
  212. ("LatentUpscaleBy", "scale_by", "scale_by"),
  213. ("ImageScale", "width", "width"),
  214. ("ImageScale", "height", "height"),
  215. # ---- Image input ----
  216. ("LoadImage", "image", "image"),
  217. ("LoadImageMask", "image", "mask_image"),
  218. ("LoadImageOutput", "image", "image"),
  219. ("VHS_LoadVideo", "video", "video"),
  220. ("VHS_LoadAudio", "audio", "audio"),
  221. # ---- Model selection (sometimes useful to swap per run) ----
  222. ("CheckpointLoaderSimple", "ckpt_name", "ckpt_name"),
  223. ("CheckpointLoader", "ckpt_name", "ckpt_name"),
  224. ("ImageOnlyCheckpointLoader", "ckpt_name", "ckpt_name"),
  225. ("VAELoader", "vae_name", "vae_name"),
  226. ("UNETLoader", "unet_name", "unet_name"),
  227. ("DiffusionModelLoader", "model_name", "diffusion_model_name"),
  228. ("UpscaleModelLoader", "model_name", "upscale_model_name"),
  229. ("CLIPLoader", "clip_name", "clip_name"),
  230. ("DualCLIPLoader", "clip_name1", "clip_name1"),
  231. ("DualCLIPLoader", "clip_name2", "clip_name2"),
  232. ("ControlNetLoader", "control_net_name", "controlnet_name"),
  233. # ---- LoRA ----
  234. ("LoraLoader", "lora_name", "lora_name"),
  235. ("LoraLoader", "strength_model", "lora_strength"),
  236. ("LoraLoader", "strength_clip", "lora_strength_clip"),
  237. ("LoraLoaderModelOnly", "lora_name", "lora_name"),
  238. ("LoraLoaderModelOnly", "strength_model", "lora_strength"),
  239. # ---- ControlNet ----
  240. ("ControlNetApply", "strength", "controlnet_strength"),
  241. ("ControlNetApplyAdvanced", "strength", "controlnet_strength"),
  242. ("ControlNetApplyAdvanced", "start_percent", "controlnet_start"),
  243. ("ControlNetApplyAdvanced", "end_percent", "controlnet_end"),
  244. # ---- IPAdapter ----
  245. ("IPAdapterAdvanced", "weight", "ipadapter_weight"),
  246. ("IPAdapterAdvanced", "start_at", "ipadapter_start"),
  247. ("IPAdapterAdvanced", "end_at", "ipadapter_end"),
  248. ("IPAdapter", "weight", "ipadapter_weight"),
  249. # ---- Upscale ----
  250. ("ImageUpscaleWithModel", "upscale_method", "upscale_method"),
  251. # ---- AnimateDiff ----
  252. ("ADE_AnimateDiffLoaderWithContext", "motion_scale", "motion_scale"),
  253. ("ADE_AnimateDiffLoaderGen1", "motion_scale", "motion_scale"),
  254. # ---- Video / Save ----
  255. ("VHS_VideoCombine", "frame_rate", "frame_rate"),
  256. ("VHS_VideoCombine", "format", "video_format"),
  257. ("VHS_VideoCombine", "filename_prefix", "filename_prefix"),
  258. ("SaveImage", "filename_prefix", "filename_prefix"),
  259. # ---- Hunyuan / Wan / LTX video ----
  260. ("HunyuanVideoSampler", "seed", "seed"),
  261. ("HunyuanVideoSampler", "steps", "steps"),
  262. ("HunyuanVideoSampler", "cfg", "cfg"),
  263. ("WanVideoSampler", "seed", "seed"),
  264. ("WanVideoSampler", "steps", "steps"),
  265. ("WanVideoSampler", "cfg", "cfg"),
  266. ("LTXVScheduler", "max_shift", "max_shift"),
  267. ("LTXVScheduler", "base_shift", "base_shift"),
  268. # ---- rgthree primitives (often used as user-facing inputs) ----
  269. ("Seed (rgthree)", "seed", "seed"),
  270. ("Image Comparer (rgthree)", "image_a", "image"),
  271. ("Power Lora Loader (rgthree)", "PowerLoraLoaderHeaderWidget", "_lora_header"),
  272. # ---- Easy-use / utility primitives ----
  273. ("PrimitiveNode", "value", "primitive_value"),
  274. ("easy seed", "seed", "seed"),
  275. ("easy positive", "positive", "prompt"),
  276. ("easy negative", "negative", "negative_prompt"),
  277. ("easy fullLoader", "ckpt_name", "ckpt_name"),
  278. ("easy fullLoader", "vae_name", "vae_name"),
  279. ("easy fullLoader", "lora_name", "lora_name"),
  280. ("easy fullLoader", "positive", "prompt"),
  281. ("easy fullLoader", "negative", "negative_prompt"),
  282. ]
  283. # Prompt-like fields whose value should be scanned for embedding references
  284. PROMPT_FIELDS = {"text", "text_g", "text_l", "t5xxl", "clip_l", "positive", "negative"}
  285. # Pattern matches: embedding:name, embedding:name.pt, embedding:name:1.2, (embedding:name:1.2)
  286. # Word-boundary at start avoids matching things like "no_embedding:foo".
  287. EMBEDDING_REGEX = re.compile(
  288. r"(?:^|[\s,(\[])embedding\s*:\s*([A-Za-z0-9_\-\./\\]+?)(?:\.(?:pt|safetensors|bin))?(?=[\s:,)\(\]]|$)",
  289. re.IGNORECASE,
  290. )
  291. # =============================================================================
  292. # Cloud detection & endpoint routing
  293. # =============================================================================
  294. CLOUD_DOMAIN_SUFFIXES = (".comfy.org",)
  295. CLOUD_DOMAIN_EXACT = {"cloud.comfy.org"}
  296. def is_cloud_host(host: str) -> bool:
  297. """True if the host points at Comfy Cloud (or staging/preview subdomain)."""
  298. parsed = urlparse(host if "://" in host else f"http://{host}")
  299. hostname = (parsed.hostname or "").lower()
  300. if hostname in CLOUD_DOMAIN_EXACT:
  301. return True
  302. return any(hostname.endswith(s) for s in CLOUD_DOMAIN_SUFFIXES)
  303. def build_cloud_aware_url(base: str, path: str, *, force_cloud: bool | None = None) -> str:
  304. """Build a URL that adds /api prefix when targeting Comfy Cloud.
  305. Local ComfyUI accepts both `/foo` and `/api/foo` for many endpoints.
  306. Cloud requires `/api/foo`.
  307. `path` should be a path component (e.g. "/prompt") or full path with query
  308. (e.g. "/view?filename=x").
  309. """
  310. base = base.rstrip("/")
  311. cloud = is_cloud_host(base) if force_cloud is None else force_cloud
  312. if not path.startswith("/"):
  313. path = "/" + path
  314. if cloud and not path.startswith("/api/"):
  315. path = "/api" + path
  316. return base + path
  317. def cloud_endpoint(path: str) -> str:
  318. """Map a cloud endpoint path to its current canonical form.
  319. Handles known renames documented in the Comfy Cloud API:
  320. /history -> /history_v2
  321. /models/<f> -> /experiment/models/<f>
  322. /models -> /experiment/models
  323. """
  324. if path.startswith("/history") and not path.startswith("/history_v2"):
  325. return "/history_v2" + path[len("/history"):]
  326. if path.startswith("/models/"):
  327. return "/experiment/models/" + path[len("/models/"):]
  328. if path == "/models":
  329. return "/experiment/models"
  330. return path
  331. def resolve_url(base: str, path: str, *, is_cloud: bool | None = None) -> str:
  332. """Top-level URL resolver. Applies cloud rename + /api prefix as needed."""
  333. cloud = is_cloud_host(base) if is_cloud is None else is_cloud
  334. if cloud:
  335. path = cloud_endpoint(path)
  336. return build_cloud_aware_url(base, path, force_cloud=cloud)
  337. # =============================================================================
  338. # API key resolution
  339. # =============================================================================
  340. def resolve_api_key(explicit: str | None) -> str | None:
  341. """Look up API key from CLI flag → env var. Strips whitespace and quotes."""
  342. val = explicit if explicit else os.environ.get(ENV_API_KEY)
  343. if val is None:
  344. return None
  345. val = val.strip().strip("'\"")
  346. return val or None
  347. # =============================================================================
  348. # HTTP transport
  349. # =============================================================================
  350. @dataclass
  351. class HTTPResponse:
  352. status: int
  353. headers: dict[str, str]
  354. body: bytes
  355. url: str # final URL after redirects
  356. def text(self, encoding: str = "utf-8") -> str:
  357. return self.body.decode(encoding, errors="replace")
  358. def json(self) -> Any:
  359. return json.loads(self.body.decode("utf-8", errors="replace"))
  360. def _sleep_backoff(attempt: int, base: float = RETRY_BASE_DELAY, cap: float = RETRY_MAX_DELAY) -> None:
  361. """Sleep with full-jitter exponential backoff."""
  362. delay = min(cap, base * (2 ** attempt))
  363. delay = random.uniform(0, delay)
  364. time.sleep(delay)
  365. def http_request(
  366. method: str,
  367. url: str,
  368. *,
  369. headers: dict[str, str] | None = None,
  370. json_body: Any = None,
  371. data: bytes | None = None,
  372. files: dict | None = None,
  373. form: dict | None = None,
  374. timeout: float = DEFAULT_HTTP_TIMEOUT,
  375. follow_redirects: bool = True,
  376. retries: int = DEFAULT_RETRIES,
  377. stream: bool = False,
  378. sink: Path | None = None,
  379. ) -> HTTPResponse:
  380. """Single entry point for all HTTP traffic.
  381. Behavior:
  382. - Retries on connection errors and on HTTP statuses in RETRY_STATUS_CODES,
  383. with exponential backoff + jitter.
  384. - For cross-host redirects, drops Authorization-style headers (so signed
  385. URLs don't leak the API key to S3/CloudFront).
  386. - When `stream=True` and `sink` is a Path, streams the response body to
  387. disk in 64 KiB chunks instead of buffering.
  388. Either `json_body`, `data`, or `files`+`form` may be supplied (mutually exclusive).
  389. """
  390. if headers is None:
  391. headers = {}
  392. headers = dict(headers) # copy
  393. headers.setdefault("User-Agent", "hermes-comfyui-skill/5.0")
  394. if files or form is not None:
  395. # Multipart upload — needs `requests`. The stdlib fallback lacks
  396. # multipart encoding helpers; raise a clear error.
  397. if not HAS_REQUESTS:
  398. raise RuntimeError(
  399. "Multipart upload requires the `requests` package. "
  400. "Install with: pip install requests"
  401. )
  402. last_exc: Exception | None = None
  403. for attempt in range(retries):
  404. try:
  405. resp = _http_once(
  406. method=method, url=url, headers=headers,
  407. json_body=json_body, data=data, files=files, form=form,
  408. timeout=timeout, follow_redirects=follow_redirects,
  409. stream=stream, sink=sink,
  410. )
  411. if resp.status in RETRY_STATUS_CODES and attempt + 1 < retries:
  412. _sleep_backoff(attempt)
  413. continue
  414. return resp
  415. except (TimeoutError, ConnectionError, OSError) as e:
  416. last_exc = e
  417. if attempt + 1 < retries:
  418. _sleep_backoff(attempt)
  419. continue
  420. raise
  421. # Should not reach here unless retries was 0
  422. if last_exc:
  423. raise last_exc
  424. raise RuntimeError("http_request: retries exhausted with no response")
  425. _SENSITIVE_HEADERS = ("x-api-key", "authorization", "cookie")
  426. if HAS_REQUESTS:
  427. class _StripSensitiveOnRedirectSession(requests.Session):
  428. """Session that drops sensitive headers on cross-host redirects.
  429. `requests` already strips `Authorization` cross-host (rebuild_auth),
  430. but it does NOT strip custom headers like `X-API-Key`. We override
  431. `rebuild_auth` to additionally strip every header in
  432. `_SENSITIVE_HEADERS` when the destination is a different host —
  433. critical when ComfyUI Cloud's `/api/view` redirects to a signed S3 URL.
  434. """
  435. def rebuild_auth(self, prepared_request, response): # type: ignore[override]
  436. super().rebuild_auth(prepared_request, response)
  437. try:
  438. old_url = response.request.url
  439. new_url = prepared_request.url
  440. old_host = (urlparse(old_url).hostname or "").lower()
  441. new_host = (urlparse(new_url).hostname or "").lower()
  442. if old_host and new_host and old_host != new_host:
  443. headers = prepared_request.headers
  444. for key in list(headers.keys()):
  445. if key.lower() in _SENSITIVE_HEADERS:
  446. del headers[key]
  447. except Exception:
  448. # Defensive: never let header stripping break a redirect.
  449. pass
  450. def _http_once(
  451. *, method: str, url: str, headers: dict[str, str],
  452. json_body: Any, data: bytes | None, files: dict | None, form: dict | None,
  453. timeout: float, follow_redirects: bool,
  454. stream: bool, sink: Path | None,
  455. ) -> HTTPResponse:
  456. """One HTTP attempt. No retry."""
  457. if HAS_REQUESTS:
  458. kwargs: dict[str, Any] = {
  459. "method": method, "url": url, "headers": headers,
  460. "timeout": timeout, "allow_redirects": follow_redirects,
  461. }
  462. if json_body is not None:
  463. kwargs["json"] = json_body
  464. elif data is not None:
  465. kwargs["data"] = data
  466. elif files is not None or form is not None:
  467. kwargs["files"] = files
  468. kwargs["data"] = form
  469. if stream:
  470. kwargs["stream"] = True
  471. # Use the subclass that strips sensitive headers cross-host
  472. with _StripSensitiveOnRedirectSession() as s:
  473. try:
  474. r = s.request(**kwargs)
  475. if stream and sink is not None:
  476. sink.parent.mkdir(parents=True, exist_ok=True)
  477. with sink.open("wb") as f:
  478. for chunk in r.iter_content(DOWNLOAD_CHUNK_SIZE):
  479. if chunk:
  480. f.write(chunk)
  481. body = b"" # already drained
  482. else:
  483. body = r.content
  484. return HTTPResponse(
  485. status=r.status_code,
  486. headers={k: v for k, v in r.headers.items()},
  487. body=body,
  488. url=r.url,
  489. )
  490. except requests.exceptions.RequestException as e:
  491. # Convert to TimeoutError / ConnectionError so the retry loop
  492. # picks them up uniformly with the stdlib path.
  493. if isinstance(e, requests.exceptions.Timeout):
  494. raise TimeoutError(str(e)) from e
  495. raise ConnectionError(str(e)) from e
  496. # ---------- stdlib fallback ----------
  497. if json_body is not None:
  498. body_bytes = json.dumps(json_body).encode("utf-8")
  499. headers.setdefault("Content-Type", "application/json")
  500. else:
  501. body_bytes = data
  502. req = urllib.request.Request(url, data=body_bytes, headers=headers, method=method)
  503. # urllib follows redirects by default. We need to:
  504. # 1) intercept cross-host redirects and drop X-API-Key
  505. # 2) optionally NOT follow redirects when follow_redirects=False
  506. class _RedirectHandler(urllib.request.HTTPRedirectHandler):
  507. def __init__(self, original_host: str, follow: bool):
  508. self.original_host = original_host
  509. self.follow = follow
  510. def redirect_request(self, req2, fp, code, msg, hdrs, newurl):
  511. if not self.follow:
  512. return None
  513. new_host = (urlparse(newurl).hostname or "").lower()
  514. if new_host != self.original_host:
  515. # Build a new request with cleaned headers
  516. clean_headers = {
  517. k: v for k, v in req2.header_items()
  518. if k.lower() not in {"x-api-key", "authorization", "cookie"}
  519. }
  520. new_req = urllib.request.Request(newurl, headers=clean_headers, method="GET")
  521. return new_req
  522. return super().redirect_request(req2, fp, code, msg, hdrs, newurl)
  523. original_host = (urlparse(url).hostname or "").lower()
  524. opener = urllib.request.build_opener(_RedirectHandler(original_host, follow_redirects))
  525. try:
  526. resp = opener.open(req, timeout=timeout)
  527. except urllib.error.HTTPError as e:
  528. return HTTPResponse(
  529. status=e.code,
  530. headers=dict(e.headers) if e.headers else {},
  531. body=e.read() or b"",
  532. url=getattr(e, "url", url),
  533. )
  534. final_url = resp.geturl()
  535. final_status = resp.status
  536. final_headers = dict(resp.headers)
  537. if stream and sink is not None:
  538. sink.parent.mkdir(parents=True, exist_ok=True)
  539. with sink.open("wb") as f:
  540. while True:
  541. chunk = resp.read(DOWNLOAD_CHUNK_SIZE)
  542. if not chunk:
  543. break
  544. f.write(chunk)
  545. return HTTPResponse(status=final_status, headers=final_headers, body=b"", url=final_url)
  546. return HTTPResponse(status=final_status, headers=final_headers, body=resp.read(), url=final_url)
  547. def http_get(url: str, **kwargs: Any) -> HTTPResponse:
  548. return http_request("GET", url, **kwargs)
  549. def http_post(url: str, **kwargs: Any) -> HTTPResponse:
  550. return http_request("POST", url, **kwargs)
  551. # =============================================================================
  552. # Workflow validation & helpers
  553. # =============================================================================
  554. def is_api_format(workflow: Any) -> bool:
  555. """API format = top-level dict where each value has `class_type`."""
  556. if not isinstance(workflow, dict):
  557. return False
  558. if "nodes" in workflow and "links" in workflow:
  559. return False
  560. for v in workflow.values():
  561. if isinstance(v, dict) and "class_type" in v:
  562. return True
  563. return False
  564. def unwrap_workflow(payload: Any) -> dict:
  565. """Unwrap common wrapper variants. Returns API-format workflow or raises ValueError."""
  566. if isinstance(payload, dict) and is_api_format(payload):
  567. return payload
  568. # Some files wrap workflow under "prompt" key (e.g. saved /prompt payloads)
  569. if isinstance(payload, dict) and "prompt" in payload and is_api_format(payload["prompt"]):
  570. return payload["prompt"]
  571. # Editor format
  572. if isinstance(payload, dict) and "nodes" in payload and "links" in payload:
  573. raise ValueError(
  574. "Workflow is in editor format (has top-level 'nodes' and 'links' arrays). "
  575. "Re-export from ComfyUI using 'Workflow → Export (API)' (newer UI) "
  576. "or 'Save (API Format)' (older UI)."
  577. )
  578. raise ValueError(
  579. "Workflow is not in API format. Each top-level entry must have a 'class_type' field."
  580. )
  581. def is_link(value: Any) -> bool:
  582. """True if `value` is a [node_id, output_index] connection (length-2 list)."""
  583. return (
  584. isinstance(value, list)
  585. and len(value) == 2
  586. and isinstance(value[0], str)
  587. and isinstance(value[1], int)
  588. )
  589. def iter_nodes(workflow: dict) -> Iterator[tuple[str, dict]]:
  590. """Yield (node_id, node) for each valid API-format node."""
  591. for node_id, node in workflow.items():
  592. if isinstance(node, dict) and "class_type" in node:
  593. yield node_id, node
  594. def iter_model_deps(workflow: dict) -> Iterator[dict]:
  595. """Yield {node_id, class_type, field, value, folder} for each model dependency."""
  596. for node_id, node in iter_nodes(workflow):
  597. cls = node["class_type"]
  598. if cls not in MODEL_LOADERS:
  599. continue
  600. inputs = node.get("inputs", {}) or {}
  601. for field_name, folder in MODEL_LOADERS[cls]:
  602. val = inputs.get(field_name)
  603. if val and isinstance(val, str) and not is_link(val):
  604. yield {
  605. "node_id": node_id,
  606. "class_type": cls,
  607. "field": field_name,
  608. "value": val,
  609. "folder": folder,
  610. }
  611. def iter_embedding_refs(workflow: dict) -> Iterator[tuple[str, str]]:
  612. """Yield (node_id, embedding_name) for every embedding mention in prompts."""
  613. for node_id, node in iter_nodes(workflow):
  614. inputs = node.get("inputs", {}) or {}
  615. for field_name, val in inputs.items():
  616. if field_name not in PROMPT_FIELDS:
  617. continue
  618. if not isinstance(val, str):
  619. continue
  620. for m in EMBEDDING_REGEX.finditer(val):
  621. yield node_id, m.group(1)
  622. # =============================================================================
  623. # Path safety
  624. # =============================================================================
  625. def safe_path_join(base: Path, *parts: str) -> Path:
  626. """Join paths, raising if the result escapes `base`.
  627. Server-supplied filenames may contain `../` etc. This guards against
  628. path-traversal attacks when downloading outputs.
  629. """
  630. base_resolved = base.resolve()
  631. candidate = base.joinpath(*parts).resolve()
  632. try:
  633. candidate.relative_to(base_resolved)
  634. except ValueError as e:
  635. raise ValueError(
  636. f"Refusing path traversal: {candidate} is outside {base_resolved}"
  637. ) from e
  638. return candidate
  639. def media_type_from_filename(filename: str) -> str:
  640. ext = Path(filename).suffix.lower()
  641. if ext in {".mp4", ".webm", ".avi", ".mov", ".mkv", ".gif", ".webp"}:
  642. return "video"
  643. if ext in {".wav", ".mp3", ".flac", ".ogg", ".m4a"}:
  644. return "audio"
  645. if ext in {".glb", ".obj", ".ply", ".gltf"}:
  646. return "3d"
  647. if ext in {".json", ".txt", ".md"}:
  648. return "text"
  649. return "image"
  650. def looks_like_video_workflow(workflow: dict) -> bool:
  651. """Used to bump default timeout for video workflows."""
  652. for _, node in iter_nodes(workflow):
  653. if node["class_type"] in SLOW_OUTPUT_NODES:
  654. return True
  655. if node["class_type"].lower().startswith(("animatediff", "ade_", "wanvideo", "hunyuanvideo", "ltxvideo", "cogvideo")):
  656. return True
  657. return False
  658. # =============================================================================
  659. # Seed handling
  660. # =============================================================================
  661. # ComfyUI's max seed range. Many UIs treat `-1` as "randomize on submit".
  662. SEED_MAX = 2**63 - 1
  663. SEED_MIN = 0
  664. def coerce_seed(value: Any) -> int:
  665. """Convert -1 or None to a fresh random seed; otherwise return int(value).
  666. Accepts numeric -1 OR string "-1" (both treated as "randomize"). Other
  667. parse failures raise TypeError/ValueError for the caller to surface.
  668. """
  669. if value is None:
  670. return random.randint(SEED_MIN, SEED_MAX)
  671. # Stringly-typed -1 from CLI / JSON should also randomize
  672. if isinstance(value, str) and value.strip() == "-1":
  673. return random.randint(SEED_MIN, SEED_MAX)
  674. if value == -1:
  675. return random.randint(SEED_MIN, SEED_MAX)
  676. return int(value)
  677. # =============================================================================
  678. # Cloud model-list normalization
  679. # =============================================================================
  680. def parse_model_list(payload: Any) -> set[str]:
  681. """Normalize model-list responses from local ComfyUI vs Comfy Cloud.
  682. Local: `["a.safetensors", "b.safetensors"]`
  683. Cloud: `[{"name": "a.safetensors", "pathIndex": 0}, ...]`
  684. """
  685. if not isinstance(payload, list):
  686. return set()
  687. out: set[str] = set()
  688. for item in payload:
  689. if isinstance(item, str):
  690. out.add(item)
  691. elif isinstance(item, dict):
  692. name = item.get("name") or item.get("filename") or item.get("path")
  693. if isinstance(name, str):
  694. out.add(name)
  695. return out
  696. # =============================================================================
  697. # Misc utilities
  698. # =============================================================================
  699. def new_client_id() -> str:
  700. return str(uuid.uuid4())
  701. def fmt_kv(d: dict) -> str:
  702. """Pretty key=value for log lines."""
  703. return " ".join(f"{k}={v!r}" for k, v in d.items())
  704. def emit_json(obj: Any, *, indent: int = 2) -> None:
  705. """Print JSON to stdout. Centralised so behavior can be tweaked (e.g., --raw)."""
  706. print(json.dumps(obj, indent=indent, default=str))
  707. def log(msg: str) -> None:
  708. """stderr log with consistent prefix (so JSON stdout stays clean)."""
  709. print(f"[comfyui-skill] {msg}", file=sys.stderr)