Skip to main content

rigspark_runtime/
generation.rs

1//! Local image/video generation through an attached, loopback-only ComfyUI server.
2//!
3//! Only built-in workflows composed of allowlisted core nodes are ever submitted, so paid
4//! ComfyUI Partner (API) nodes and cloud services can never be reached through rigspark.
5use crate::{
6    acquire::{Acquisition, Artifact, DownloadTransport},
7    http::{HttpError, Request, Transport, read_json},
8};
9use rigspark_core::generation::{
10    FileRole, FitVerdict, GenerationCatalog, GenerationFit, GenerationKind, GenerationModel,
11    Workflow, fit,
12};
13use serde::Serialize;
14use serde_json::{Value, json};
15use std::{
16    collections::HashMap,
17    path::{Path, PathBuf},
18    sync::Arc,
19    time::Duration,
20};
21use tokio::io::{AsyncReadExt, AsyncWriteExt};
22use tokio_util::sync::CancellationToken;
23
24pub const DEFAULT_PORT: u16 = 8188;
25pub const MAX_PROMPT_BYTES: usize = 16 * 1024;
26mod preflight;
27pub const MAX_SEED: u64 = 9_007_199_254_740_991;
28
29/// Picture shape. `Square` keeps each workflow's published size; the others keep its pixel
30/// count and change the ratio, in multiples of 16 as the latent space needs.
31#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize)]
32#[serde(rename_all = "lowercase")]
33pub enum Aspect {
34    #[default]
35    Square,
36    /// 16:9, for thumbnails.
37    Landscape,
38    /// 9:16, for phone wallpapers.
39    Portrait,
40}
41impl Aspect {
42    pub fn parse(value: &str) -> Option<Self> {
43        match value {
44            "square" => Some(Self::Square),
45            "landscape" => Some(Self::Landscape),
46            "portrait" => Some(Self::Portrait),
47            _ => None,
48        }
49    }
50    pub fn name(self) -> &'static str {
51        match self {
52            Self::Square => "square",
53            Self::Landscape => "landscape",
54            Self::Portrait => "portrait",
55        }
56    }
57    /// Width and height with the same pixel count as `width`×`height` at this ratio.
58    pub fn dimensions(self, width: u64, height: u64) -> (u64, u64) {
59        let (across, down) = match self {
60            Self::Square => return (width, height),
61            Self::Landscape => (16.0, 9.0),
62            Self::Portrait => (9.0, 16.0),
63        };
64        let area = (width * height) as f64;
65        let round = |value: f64| ((value / 16.0).round() as u64).max(1) * 16;
66        (
67            round((area * across / down).sqrt()),
68            round((area * down / across).sqrt()),
69        )
70    }
71}
72
73/// Reshapes every latent and sampling node of an image graph to `aspect`.
74pub fn shaped(
75    mut graph: Value,
76    kind: GenerationKind,
77    aspect: Aspect,
78) -> Result<Value, GenerationError> {
79    if aspect == Aspect::Square {
80        return Ok(graph);
81    }
82    if kind != GenerationKind::Image {
83        return Err(GenerationError::Invalid("only images take an aspect ratio"));
84    }
85    let mut changed = false;
86    for node in graph
87        .as_object_mut()
88        .into_iter()
89        .flat_map(|nodes| nodes.values_mut())
90    {
91        let Some(inputs) = node.get_mut("inputs").and_then(Value::as_object_mut) else {
92            continue;
93        };
94        if let (Some(width), Some(height)) = (
95            inputs.get("width").and_then(Value::as_u64),
96            inputs.get("height").and_then(Value::as_u64),
97        ) {
98            let (width, height) = aspect.dimensions(width, height);
99            inputs.insert("width".into(), width.into());
100            inputs.insert("height".into(), height.into());
101            changed = true;
102        }
103    }
104    if !changed {
105        return Err(GenerationError::Invalid(
106            "this workflow has no image size to change",
107        ));
108    }
109    Ok(graph)
110}
111const MAX_OUTPUT_BYTES: u64 = 1024 * 1024 * 1024;
112const WEIGHT_TIMEOUT: Duration = Duration::from_secs(6 * 60 * 60);
113/// Core ComfyUI nodes used by the built-in workflows; anything else is refused.
114pub const LOCAL_NODES: [&str; 22] = [
115    "BasicGuider",
116    "BasicScheduler",
117    "CheckpointLoaderSimple",
118    "CLIPLoader",
119    "CLIPTextEncode",
120    "DualCLIPLoader",
121    "EmptyHunyuanLatentVideo",
122    "EmptyLatentImage",
123    "EmptySD3LatentImage",
124    "KSampler",
125    "KSamplerSelect",
126    "ModelSamplingAuraFlow",
127    "ModelSamplingFlux",
128    "ModelSamplingSD3",
129    "RandomNoise",
130    "SamplerCustomAdvanced",
131    "SaveAnimatedWEBP",
132    "SaveImage",
133    "UNETLoader",
134    "VAEDecode",
135    "VAELoader",
136    "Wan22ImageToVideoLatent",
137];
138/// Wan 2.1's published default negative prompt (Apache-2.0), as used by the official
139/// ComfyUI example: https://comfyanonymous.github.io/ComfyUI_examples/wan/
140const WAN_NEGATIVE_PROMPT: &str = "色调艳丽,过曝,静态,细节模糊不清,字幕,风格,作品,画作,画面,静止,整体发灰,最差质量,低质量,JPEG压缩残留,丑陋的,残缺的,多余的手指,画得不好的手部,画得不好的脸部,畸形的,毁容的,形态畸形的肢体,手指融合,静止不动的画面,杂乱的背景,三条腿,背景人很多,倒着走";
141
142#[derive(Debug, thiserror::Error)]
143pub enum GenerationError {
144    #[error("invalid generation request: {0}")]
145    Invalid(&'static str),
146    #[error("{0}")]
147    Catalog(String),
148    #[error("{0}")]
149    NoFit(String),
150    #[error("hardware detection failed: {0}")]
151    Hardware(String),
152    #[error(
153        "ComfyUI is not reachable at {0}; start ComfyUI on loopback (default port 8188) and retry"
154    )]
155    Unreachable(String),
156    #[error("weight installation failed: {0}")]
157    Install(String),
158    #[error(
159        "ComfyUI does not list {0}; make sure --comfyui-dir points at the running ComfyUI installation"
160    )]
161    NotVisible(String),
162    #[error("workflow node `{0}` is not an allowlisted local node; refusing to submit")]
163    NonLocalNode(String),
164    #[error("{0}")]
165    Incompatible(String),
166    #[error("ComfyUI rejected the workflow: {0}")]
167    Rejected(String),
168    #[error("ComfyUI generation failed: {0}")]
169    Failed(String),
170    #[error("invalid ComfyUI response: {0}")]
171    Response(&'static str),
172    #[error("output already exists: {0}")]
173    Exists(PathBuf),
174    #[error("could not write output: {0}")]
175    Output(String),
176    #[error("generation timed out")]
177    Timeout,
178    #[error("operation cancelled")]
179    Cancelled,
180    #[error(transparent)]
181    Http(HttpError),
182}
183impl From<HttpError> for GenerationError {
184    fn from(error: HttpError) -> Self {
185        match error {
186            HttpError::Cancelled => Self::Cancelled,
187            other => Self::Http(other),
188        }
189    }
190}
191
192pub fn output_extension(kind: GenerationKind) -> &'static str {
193    match kind {
194        GenerationKind::Image => "png",
195        GenerationKind::Video => "webp",
196    }
197}
198fn save_node(workflow: Workflow) -> &'static str {
199    match workflow {
200        Workflow::FluxCheckpoint | Workflow::FluxSplit | Workflow::MingDesign => "9",
201        Workflow::WanT2v | Workflow::Wan22Ti2v => "28",
202        Workflow::QwenImage => "60",
203    }
204}
205
206/// Random seed in the JSON-safe integer range, reported back so runs are reproducible.
207pub fn random_seed() -> u64 {
208    uuid::Uuid::new_v4().as_u64_pair().0 & MAX_SEED
209}
210
211pub fn validate_prompt(prompt: &str) -> Result<(), GenerationError> {
212    if prompt.trim().is_empty()
213        || prompt.len() > MAX_PROMPT_BYTES
214        || prompt
215            .chars()
216            .any(|ch| ch.is_control() && ch != '\n' && ch != '\t')
217    {
218        return Err(GenerationError::Invalid(
219            "prompt must be 1..=16384 bytes of text without control characters",
220        ));
221    }
222    Ok(())
223}
224
225/// ComfyUI reports its compute device per `/system_stats`; Apple GPUs report `mps`.
226pub fn apple_mps(devices: &[String]) -> bool {
227    devices.iter().any(|device| device == "mps")
228}
229
230/// Wan's official `uni_pc` sampler diverged into noise on Apple MPS in live testing (ComfyUI
231/// 0.38, 30 steps), while `euler` at the official size and length stayed coherent.
232fn wan_sampler(devices: &[String]) -> &'static str {
233    if apple_mps(devices) {
234        "euler"
235    } else {
236        "uni_pc"
237    }
238}
239
240/// Builds the API-format graph published in the official ComfyUI examples.
241pub fn workflow(
242    model: &GenerationModel,
243    names: &HashMap<FileRole, String>,
244    prompt: &str,
245    seed: u64,
246    devices: &[String],
247) -> Result<Value, GenerationError> {
248    let name = |role| {
249        names
250            .get(&role)
251            .cloned()
252            .ok_or(GenerationError::Invalid("missing installed weight name"))
253    };
254    let workflow = model
255        .runnable()
256        .map_err(|error| GenerationError::Catalog(error.to_string()))?;
257    Ok(match workflow {
258        // https://comfyanonymous.github.io/ComfyUI_examples/flux/ (schnell fp8 checkpoint)
259        Workflow::FluxCheckpoint => json!({
260            "6": {"class_type": "CLIPTextEncode", "inputs": {"text": prompt, "clip": ["30", 1]}},
261            "8": {"class_type": "VAEDecode", "inputs": {"samples": ["31", 0], "vae": ["30", 2]}},
262            "9": {"class_type": "SaveImage", "inputs": {"filename_prefix": "rigspark", "images": ["8", 0]}},
263            "27": {"class_type": "EmptySD3LatentImage", "inputs": {"width": 1024, "height": 1024, "batch_size": 1}},
264            "30": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": name(FileRole::Checkpoint)?}},
265            "31": {"class_type": "KSampler", "inputs": {
266                "seed": seed, "steps": 4, "cfg": 1.0, "sampler_name": "euler", "scheduler": "simple",
267                "denoise": 1.0, "model": ["30", 0], "positive": ["6", 0], "negative": ["33", 0],
268                "latent_image": ["27", 0]}},
269            "33": {"class_type": "CLIPTextEncode", "inputs": {"text": "", "clip": ["30", 1]}},
270        }),
271        // https://comfyanonymous.github.io/ComfyUI_examples/flux/ (regular full version)
272        Workflow::FluxSplit => json!({
273            "5": {"class_type": "EmptyLatentImage", "inputs": {"width": 1024, "height": 1024, "batch_size": 1}},
274            "6": {"class_type": "CLIPTextEncode", "inputs": {"text": prompt, "clip": ["11", 0]}},
275            "8": {"class_type": "VAEDecode", "inputs": {"samples": ["13", 0], "vae": ["10", 0]}},
276            "9": {"class_type": "SaveImage", "inputs": {"filename_prefix": "rigspark", "images": ["8", 0]}},
277            "10": {"class_type": "VAELoader", "inputs": {"vae_name": name(FileRole::Vae)?}},
278            "11": {"class_type": "DualCLIPLoader", "inputs": {
279                "clip_name1": name(FileRole::TextEncoder)?,
280                "clip_name2": name(FileRole::Clip)?,
281                "type": "flux"}},
282            "12": {"class_type": "UNETLoader", "inputs": {
283                "unet_name": name(FileRole::Diffusion)?, "weight_dtype": "default"}},
284            "13": {"class_type": "SamplerCustomAdvanced", "inputs": {
285                "noise": ["25", 0], "guider": ["22", 0], "sampler": ["16", 0],
286                "sigmas": ["17", 0], "latent_image": ["5", 0]}},
287            "16": {"class_type": "KSamplerSelect", "inputs": {"sampler_name": "euler"}},
288            "17": {"class_type": "BasicScheduler", "inputs": {
289                "scheduler": "simple", "steps": 4, "denoise": 1.0, "model": ["12", 0]}},
290            "22": {"class_type": "BasicGuider", "inputs": {
291                "model": ["12", 0], "conditioning": ["6", 0]}},
292            "25": {"class_type": "RandomNoise", "inputs": {"noise_seed": seed}},
293        }),
294        // https://comfyanonymous.github.io/ComfyUI_examples/wan/ (text to video, 1.3B)
295        Workflow::WanT2v => json!({
296            "3": {"class_type": "KSampler", "inputs": {
297                "seed": seed, "steps": 30, "cfg": 6.0, "sampler_name": wan_sampler(devices), "scheduler": "simple",
298                "denoise": 1.0, "model": ["48", 0], "positive": ["6", 0], "negative": ["7", 0],
299                "latent_image": ["40", 0]}},
300            "6": {"class_type": "CLIPTextEncode", "inputs": {"text": prompt, "clip": ["38", 0]}},
301            "7": {"class_type": "CLIPTextEncode", "inputs": {"text": WAN_NEGATIVE_PROMPT, "clip": ["38", 0]}},
302            "8": {"class_type": "VAEDecode", "inputs": {"samples": ["3", 0], "vae": ["39", 0]}},
303            "28": {"class_type": "SaveAnimatedWEBP", "inputs": {
304                "filename_prefix": "rigspark", "fps": 16.0, "lossless": false, "quality": 90,
305                "method": "default", "images": ["8", 0]}},
306            "37": {"class_type": "UNETLoader", "inputs": {"unet_name": name(FileRole::Diffusion)?, "weight_dtype": "default"}},
307            "38": {"class_type": "CLIPLoader", "inputs": {"clip_name": name(FileRole::TextEncoder)?, "type": "wan", "device": "default"}},
308            "39": {"class_type": "VAELoader", "inputs": {"vae_name": name(FileRole::Vae)?}},
309            "40": {"class_type": "EmptyHunyuanLatentVideo", "inputs": {"width": 832, "height": 480, "length": 49, "batch_size": 1}},
310            "48": {"class_type": "ModelSamplingSD3", "inputs": {"shift": 8.0, "model": ["37", 0]}},
311        }),
312        // https://comfyanonymous.github.io/ComfyUI_examples/wan22/ (5B text to video)
313        Workflow::Wan22Ti2v => json!({
314            "3": {"class_type": "KSampler", "inputs": {
315                "seed": seed, "steps": 30, "cfg": 5.0, "sampler_name": wan_sampler(devices), "scheduler": "simple",
316                "denoise": 1.0, "model": ["48", 0], "positive": ["6", 0], "negative": ["7", 0],
317                "latent_image": ["55", 0]}},
318            "6": {"class_type": "CLIPTextEncode", "inputs": {"text": prompt, "clip": ["38", 0]}},
319            "7": {"class_type": "CLIPTextEncode", "inputs": {"text": WAN_NEGATIVE_PROMPT, "clip": ["38", 0]}},
320            "8": {"class_type": "VAEDecode", "inputs": {"samples": ["3", 0], "vae": ["39", 0]}},
321            "28": {"class_type": "SaveAnimatedWEBP", "inputs": {
322                "filename_prefix": "rigspark", "fps": 24.0, "lossless": false, "quality": 90,
323                "method": "default", "images": ["8", 0]}},
324            "37": {"class_type": "UNETLoader", "inputs": {"unet_name": name(FileRole::Diffusion)?, "weight_dtype": "default"}},
325            "38": {"class_type": "CLIPLoader", "inputs": {"clip_name": name(FileRole::TextEncoder)?, "type": "wan", "device": "default"}},
326            "39": {"class_type": "VAELoader", "inputs": {"vae_name": name(FileRole::Vae)?}},
327            "48": {"class_type": "ModelSamplingSD3", "inputs": {"shift": 8.0, "model": ["37", 0]}},
328            "55": {"class_type": "Wan22ImageToVideoLatent", "inputs": {
329                "width": 1280, "height": 704, "length": 41, "batch_size": 1, "vae": ["39", 0]}},
330        }),
331        // Pinned Ming contract and deliberate template reductions: docs/references/ming-design-workflow.md.
332        Workflow::MingDesign => json!({
333            "5": {"class_type": "EmptyLatentImage", "inputs": {"width": 1024, "height": 1024, "batch_size": 1}},
334            "6": {"class_type": "CLIPTextEncode", "inputs": {"text": prompt, "clip": ["11", 0]}},
335            "8": {"class_type": "VAEDecode", "inputs": {"samples": ["13", 0], "vae": ["10", 0]}},
336            "9": {"class_type": "SaveImage", "inputs": {"filename_prefix": "rigspark", "images": ["8", 0]}},
337            "10": {"class_type": "VAELoader", "inputs": {"vae_name": name(FileRole::Vae)?}},
338            "11": {"class_type": "CLIPLoader", "inputs": {
339                "clip_name": name(FileRole::TextEncoder)?, "type": "qwen_image", "device": "default"}},
340            "12": {"class_type": "UNETLoader", "inputs": {
341                "unet_name": name(FileRole::Diffusion)?, "weight_dtype": "default"}},
342            "13": {"class_type": "SamplerCustomAdvanced", "inputs": {
343                "noise": ["25", 0], "guider": ["22", 0], "sampler": ["16", 0],
344                "sigmas": ["17", 0], "latent_image": ["5", 0]}},
345            "16": {"class_type": "KSamplerSelect", "inputs": {"sampler_name": "euler"}},
346            "17": {"class_type": "BasicScheduler", "inputs": {
347                "scheduler": "simple", "steps": 12, "denoise": 1.0, "model": ["26", 0]}},
348            "22": {"class_type": "BasicGuider", "inputs": {
349                "model": ["26", 0], "conditioning": ["6", 0]}},
350            "25": {"class_type": "RandomNoise", "inputs": {"noise_seed": seed}},
351            "26": {"class_type": "ModelSamplingFlux", "inputs": {
352                "model": ["12", 0], "max_shift": 1.15, "base_shift": 0.5, "width": 1024, "height": 1024}},
353        }),
354        // https://comfyanonymous.github.io/ComfyUI_examples/qwen_image/ (basic workflow)
355        Workflow::QwenImage => json!({
356            "3": {"class_type": "KSampler", "inputs": {
357                "seed": seed, "steps": 20, "cfg": 2.5, "sampler_name": "euler", "scheduler": "simple",
358                "denoise": 1.0, "model": ["66", 0], "positive": ["6", 0], "negative": ["7", 0],
359                "latent_image": ["58", 0]}},
360            "6": {"class_type": "CLIPTextEncode", "inputs": {"text": prompt, "clip": ["38", 0]}},
361            "7": {"class_type": "CLIPTextEncode", "inputs": {"text": " ", "clip": ["38", 0]}},
362            "8": {"class_type": "VAEDecode", "inputs": {"samples": ["3", 0], "vae": ["39", 0]}},
363            "37": {"class_type": "UNETLoader", "inputs": {"unet_name": name(FileRole::Diffusion)?, "weight_dtype": "default"}},
364            "38": {"class_type": "CLIPLoader", "inputs": {"clip_name": name(FileRole::TextEncoder)?, "type": "qwen_image", "device": "default"}},
365            "39": {"class_type": "VAELoader", "inputs": {"vae_name": name(FileRole::Vae)?}},
366            "58": {"class_type": "EmptySD3LatentImage", "inputs": {"width": 1328, "height": 1328, "batch_size": 1}},
367            "60": {"class_type": "SaveImage", "inputs": {"filename_prefix": "rigspark", "images": ["8", 0]}},
368            "66": {"class_type": "ModelSamplingAuraFlow", "inputs": {"shift": 3.1, "model": ["37", 0]}},
369        }),
370    })
371}
372
373/// Fails closed unless every node is an allowlisted core local node.
374pub fn ensure_local_only(workflow: &Value) -> Result<(), GenerationError> {
375    let nodes = workflow
376        .as_object()
377        .filter(|nodes| !nodes.is_empty() && nodes.len() <= 64)
378        .ok_or(GenerationError::Invalid(
379            "workflow must be a non-empty node map",
380        ))?;
381    for node in nodes.values() {
382        let class = node
383            .get("class_type")
384            .and_then(Value::as_str)
385            .ok_or(GenerationError::Invalid("workflow node has no class_type"))?;
386        if !LOCAL_NODES.contains(&class) || !node.get("inputs").is_some_and(Value::is_object) {
387            return Err(GenerationError::NonLocalNode(
388                class.chars().take(128).collect(),
389            ));
390        }
391    }
392    Ok(())
393}
394
395pub struct GenerationRequest<'request> {
396    pub model: &'request GenerationModel,
397    pub prompt: &'request str,
398    pub seed: u64,
399    pub aspect: Aspect,
400    pub endpoint: &'request str,
401    pub comfyui_dir: &'request Path,
402    /// Exact output file; when absent a name is derived inside `output_dir`.
403    pub output: Option<&'request Path>,
404    pub output_dir: &'request Path,
405}
406
407#[derive(Debug, Clone, Serialize)]
408#[serde(rename_all = "camelCase")]
409pub struct InstalledWeight {
410    pub role: FileRole,
411    pub name: String,
412    pub bytes: u64,
413    pub cached: bool,
414}
415
416#[derive(Debug, Clone, Serialize)]
417#[serde(rename_all = "camelCase")]
418pub struct GenerationOutcome {
419    pub model: String,
420    pub kind: GenerationKind,
421    pub path: PathBuf,
422    pub bytes: u64,
423    pub prompt_id: String,
424    pub seed: u64,
425    pub weights: Vec<InstalledWeight>,
426}
427
428pub type Events = Arc<dyn Fn(String) + Send + Sync>;
429
430/// What ComfyUI reports about itself before a run.
431#[derive(Debug, Clone, Default)]
432pub struct ComfyStatus {
433    pub devices: Vec<String>,
434    /// Smallest free device memory, falling back to free system RAM; `None` when unreported.
435    pub free_bytes: Option<u64>,
436}
437
438/// Weight file names a workflow graph loads, with `\` normalised to `/`.
439fn model_files(graph: &Value) -> std::collections::BTreeSet<String> {
440    graph
441        .as_object()
442        .into_iter()
443        .flat_map(|nodes| nodes.values())
444        .filter_map(|node| node.get("inputs").and_then(Value::as_object))
445        .flat_map(|inputs| inputs.values())
446        .filter_map(Value::as_str)
447        .filter(|value| value.ends_with(".safetensors"))
448        .map(|value| value.replace('\\', "/"))
449        .collect()
450}
451
452pub struct ComfyUi<'runtime> {
453    pub http: &'runtime dyn Transport,
454    pub download: &'runtime dyn DownloadTransport,
455    pub poll_interval: Duration,
456    pub deadline: Duration,
457    pub events: Option<Events>,
458}
459
460fn prompt_id(value: &Value) -> Result<String, GenerationError> {
461    value
462        .get("prompt_id")
463        .and_then(Value::as_str)
464        .filter(|id| {
465            !id.is_empty()
466                && id.len() <= 128
467                && id
468                    .bytes()
469                    .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-')
470        })
471        .map(str::to_owned)
472        .ok_or(GenerationError::Response("missing or invalid prompt_id"))
473}
474fn summary(value: &Value) -> String {
475    let mut parts = Vec::new();
476    if let Some(message) = value.pointer("/error/message").and_then(Value::as_str) {
477        parts.push(message.to_owned());
478    }
479    if let Some(nodes) = value.get("node_errors").and_then(Value::as_object) {
480        for (node, detail) in nodes.iter().take(8) {
481            let class = detail
482                .get("class_type")
483                .and_then(Value::as_str)
484                .unwrap_or("?");
485            for error in detail
486                .get("errors")
487                .and_then(Value::as_array)
488                .into_iter()
489                .flatten()
490                .take(4)
491            {
492                let text = error
493                    .get("details")
494                    .or_else(|| error.get("message"))
495                    .and_then(Value::as_str)
496                    .unwrap_or("error");
497                parts.push(format!("node {node} ({class}): {text}"));
498            }
499        }
500    }
501    if let Some(message) = value.get("exception_message").and_then(Value::as_str) {
502        let node = value
503            .get("node_type")
504            .and_then(Value::as_str)
505            .unwrap_or("?");
506        parts.push(format!("{node}: {message}"));
507    }
508    let text = if parts.is_empty() {
509        "no details reported".to_owned()
510    } else {
511        parts.join("; ")
512    };
513    text.chars()
514        .filter(|ch| !ch.is_control())
515        .take(1000)
516        .collect()
517}
518fn safe_output_name(value: &str, extension: &str) -> bool {
519    !value.is_empty()
520        && value.len() <= 255
521        && !value.starts_with('.')
522        && !value.contains(['/', '\\', ':'])
523        && !value.chars().any(char::is_control)
524        && value
525            .rsplit_once('.')
526            .is_some_and(|(_, ext)| ext.eq_ignore_ascii_case(extension))
527}
528fn safe_subfolder(value: &str) -> bool {
529    value.is_empty()
530        || (value.len() <= 255
531            && !value.starts_with('/')
532            && !value.contains(['\\', ':'])
533            && !value.chars().any(char::is_control)
534            && value
535                .split('/')
536                .all(|part| !part.is_empty() && part != "." && part != ".."))
537}
538fn has_magic(kind: GenerationKind, head: &[u8]) -> bool {
539    match kind {
540        GenerationKind::Image => head.starts_with(b"\x89PNG\r\n\x1a\n"),
541        GenerationKind::Video => {
542            head.len() >= 12 && &head[..4] == b"RIFF" && &head[8..12] == b"WEBP"
543        }
544    }
545}
546
547impl ComfyUi<'_> {
548    fn emit(&self, message: String) {
549        if let Some(events) = &self.events {
550            events(message);
551        }
552    }
553
554    async fn get_json(
555        &self,
556        endpoint: &str,
557        path: &str,
558        cancel: &CancellationToken,
559        limit: usize,
560    ) -> Result<Value, GenerationError> {
561        let request = Request::new(endpoint, path, None, None)?;
562        Ok(read_json(self.http, request, cancel, limit).await?)
563    }
564
565    /// Reads a JSON body regardless of status so ComfyUI validation errors can be shown.
566    async fn post_json(
567        &self,
568        endpoint: &str,
569        path: &str,
570        body: Value,
571        cancel: &CancellationToken,
572    ) -> Result<(u16, Value), GenerationError> {
573        let request = Request::new(endpoint, path, Some(body), None)?;
574        let operation = async {
575            let response = self.http.send(request).await?;
576            let mut bytes = Vec::new();
577            response
578                .body
579                .take(4 * 1024 * 1024 + 1)
580                .read_to_end(&mut bytes)
581                .await
582                .map_err(|_| HttpError::Transport)?;
583            if bytes.len() > 4 * 1024 * 1024 {
584                return Err(HttpError::Limit);
585            }
586            let value = if bytes.is_empty() {
587                Value::Null
588            } else {
589                serde_json::from_slice(&bytes).map_err(|_| HttpError::Response)?
590            };
591            Ok((response.status, value))
592        };
593        tokio::select! {
594            biased;
595            _ = cancel.cancelled() => Err(GenerationError::Cancelled),
596            result = tokio::time::timeout(Duration::from_secs(120), operation) =>
597                Ok(result.map_err(|_| HttpError::Timeout)??),
598        }
599    }
600
601    /// Confirms the listener is ComfyUI and returns its reported devices and free memory.
602    pub async fn ready(
603        &self,
604        endpoint: &str,
605        cancel: &CancellationToken,
606    ) -> Result<ComfyStatus, GenerationError> {
607        match self
608            .get_json(endpoint, "/system_stats", cancel, 1024 * 1024)
609            .await
610        {
611            Ok(stats) if stats.get("system").is_some_and(Value::is_object) => {
612                let devices: Vec<&Value> = stats
613                    .get("devices")
614                    .and_then(Value::as_array)
615                    .into_iter()
616                    .flatten()
617                    .take(16)
618                    .collect();
619                let free_bytes = devices
620                    .iter()
621                    .filter_map(|device| device.get("vram_free").and_then(Value::as_u64))
622                    .min()
623                    .or_else(|| stats.pointer("/system/ram_free").and_then(Value::as_u64));
624                Ok(ComfyStatus {
625                    devices: devices
626                        .iter()
627                        .filter_map(|device| device.get("type").and_then(Value::as_str))
628                        .filter(|kind| {
629                            kind.len() <= 32
630                                && kind.bytes().all(|byte| byte.is_ascii_alphanumeric())
631                        })
632                        .map(str::to_owned)
633                        .collect(),
634                    free_bytes,
635                })
636            }
637            Ok(_) => Err(GenerationError::Response("listener is not ComfyUI")),
638            Err(GenerationError::Cancelled) => Err(GenerationError::Cancelled),
639            Err(GenerationError::Http(HttpError::Invalid)) => Err(GenerationError::Invalid(
640                "ComfyUI endpoint must be loopback HTTP",
641            )),
642            Err(_) => Err(GenerationError::Unreachable(endpoint.to_owned())),
643        }
644    }
645
646    /// Installs (or re-verifies) every pinned weight under `<comfyui>/models/<folder>/rigspark`.
647    pub async fn install(
648        &self,
649        model: &GenerationModel,
650        comfyui_dir: &Path,
651        cancel: &CancellationToken,
652    ) -> Result<Vec<InstalledWeight>, GenerationError> {
653        let models = comfyui_dir.join("models");
654        if !std::fs::metadata(&models).is_ok_and(|metadata| metadata.is_dir()) {
655            return Err(GenerationError::Invalid(
656                "ComfyUI directory must contain a models/ folder",
657            ));
658        }
659        let workflow = model
660            .runnable()
661            .map_err(|error| GenerationError::Catalog(error.to_string()))?;
662        let mut installed = Vec::new();
663        for role in workflow.roles() {
664            let file = model
665                .file(*role)
666                .ok_or(GenerationError::Invalid("model is missing a workflow file"))?;
667            let artifact = Artifact {
668                backend: "comfyui".into(),
669                repo: file.repo.clone(),
670                revision: file.revision.clone(),
671                file: file.file.clone(),
672                sha256: file.sha256.clone(),
673                bytes: file.bytes,
674            };
675            let (owner, repository) = file
676                .repo
677                .split_once('/')
678                .ok_or(GenerationError::Invalid("invalid weight repository"))?;
679            let name = format!(
680                "rigspark/comfyui/{owner}/{repository}@{}/{}",
681                file.revision, file.file
682            );
683            let mut acquisition = Acquisition::new(models.join(role.folder()).join("rigspark"))
684                .map_err(GenerationError::Install)?
685                .with_timeout(WEIGHT_TIMEOUT);
686            if let Some(events) = self.events.clone() {
687                let last = Arc::new(std::sync::atomic::AtomicU64::new(u64::MAX));
688                acquisition = acquisition.with_progress(move |done, total, file| {
689                    let percent = done.saturating_mul(100).checked_div(total).unwrap_or(100);
690                    if last.swap(percent / 5, std::sync::atomic::Ordering::Relaxed) != percent / 5 {
691                        events(format!(
692                            "Weights {file}: {percent}% of {:.1} GiB",
693                            total as f64 / 1073741824.0
694                        ));
695                    }
696                });
697            }
698            let acquired = acquisition
699                .acquire(&artifact, self.download, cancel)
700                .await
701                .map_err(|error| {
702                    if cancel.is_cancelled() {
703                        GenerationError::Cancelled
704                    } else {
705                        GenerationError::Install(error)
706                    }
707                })?;
708            if !acquired
709                .path
710                .ends_with(name.trim_start_matches("rigspark/"))
711            {
712                return Err(GenerationError::Install(
713                    "unexpected weight location".into(),
714                ));
715            }
716            installed.push(InstalledWeight {
717                role: *role,
718                name,
719                bytes: acquired.bytes,
720                cached: acquired.cached,
721            });
722        }
723        Ok(installed)
724    }
725
726    /// Replaces each expected name with ComfyUI's own spelling (e.g. `\` on Windows).
727    async fn resolve_names(
728        &self,
729        endpoint: &str,
730        weights: &mut [InstalledWeight],
731        cancel: &CancellationToken,
732    ) -> Result<(), GenerationError> {
733        for weight in weights {
734            let listing = self
735                .get_json(
736                    endpoint,
737                    &format!("/models/{}", weight.role.folder()),
738                    cancel,
739                    4 * 1024 * 1024,
740                )
741                .await?;
742            let listed = listing
743                .as_array()
744                .ok_or(GenerationError::Response("model listing is not an array"))?
745                .iter()
746                .filter_map(Value::as_str)
747                .find(|entry| entry.replace('\\', "/") == weight.name)
748                .ok_or_else(|| GenerationError::NotVisible(weight.name.clone()))?;
749            weight.name = listed.to_owned();
750        }
751        Ok(())
752    }
753
754    /// Weight files of the most recent ComfyUI prompt, best effort.
755    async fn previous_files(
756        &self,
757        endpoint: &str,
758        cancel: &CancellationToken,
759    ) -> Option<std::collections::BTreeSet<String>> {
760        let request = Request::new(endpoint, "/history", None, None)
761            .ok()?
762            .with_query(&[("max_items", "1")])
763            .ok()?;
764        let history = read_json(self.http, request, cancel, 16 * 1024 * 1024)
765            .await
766            .ok()?;
767        let graph = history
768            .as_object()?
769            .values()
770            .next_back()?
771            .get("prompt")?
772            .get(2)?;
773        Some(model_files(graph)).filter(|files| !files.is_empty())
774    }
775
776    /// Unloads another workflow's weights before switching models when memory is shared (Apple
777    /// MPS) or free device memory is below this model's weights. Live testing on a 36 GB M4 Max:
778    /// Wan swapped and sampled ~4x slower beside a resident FLUX even with more free memory than
779    /// Wan's weights, because activations and upcast encoders need far more than the files.
780    async fn make_room(
781        &self,
782        endpoint: &str,
783        status: &ComfyStatus,
784        needed: u64,
785        graph: &Value,
786        cancel: &CancellationToken,
787    ) -> Result<(), GenerationError> {
788        let shared = apple_mps(&status.devices);
789        let short = status.free_bytes.is_some_and(|free| free < needed);
790        if !shared && !short {
791            return Ok(());
792        }
793        let Some(previous) = self.previous_files(endpoint, cancel).await else {
794            return Ok(());
795        };
796        if previous == model_files(graph) {
797            return Ok(());
798        }
799        let free = status.free_bytes.map_or_else(
800            || "unknown".to_owned(),
801            |free| format!("{:.1} GiB", free as f64 / 1073741824.0),
802        );
803        self.emit(format!(
804            "Freeing ComfyUI memory before switching models ({free} free, {:.1} GiB of weights needed{})",
805            needed as f64 / 1073741824.0,
806            if shared { ", shared Apple memory" } else { "" }
807        ));
808        let (code, _) = self
809            .post_json(
810                endpoint,
811                "/free",
812                json!({"unload_models": true, "free_memory": true}),
813                cancel,
814            )
815            .await?;
816        if !(200..300).contains(&code) {
817            self.emit(format!(
818                "ComfyUI declined to free memory (HTTP {code}); continuing"
819            ));
820        }
821        Ok(())
822    }
823
824    async fn cancel_remote(&self, endpoint: &str, id: &str) {
825        let fresh = CancellationToken::new();
826        for (path, body) in [
827            ("/queue", json!({"delete": [id]})),
828            ("/interrupt", json!({"prompt_id": id})),
829        ] {
830            let _ = tokio::time::timeout(
831                Duration::from_secs(5),
832                self.post_json(endpoint, path, body, &fresh),
833            )
834            .await;
835        }
836    }
837
838    async fn wait(
839        &self,
840        endpoint: &str,
841        id: &str,
842        cancel: &CancellationToken,
843    ) -> Result<Value, GenerationError> {
844        let started = tokio::time::Instant::now();
845        loop {
846            if started.elapsed() > self.deadline {
847                return Err(GenerationError::Timeout);
848            }
849            tokio::select! {
850                biased;
851                _ = cancel.cancelled() => return Err(GenerationError::Cancelled),
852                _ = tokio::time::sleep(self.poll_interval) => {}
853            }
854            let history = self
855                .get_json(
856                    endpoint,
857                    &format!("/history/{id}"),
858                    cancel,
859                    16 * 1024 * 1024,
860                )
861                .await?;
862            let Some(entry) = history.get(id) else {
863                continue;
864            };
865            let status = entry.get("status");
866            if status
867                .and_then(|status| status.get("status_str"))
868                .and_then(Value::as_str)
869                == Some("error")
870            {
871                let detail = status
872                    .and_then(|status| status.get("messages"))
873                    .and_then(Value::as_array)
874                    .into_iter()
875                    .flatten()
876                    .find(|message| {
877                        message.get(0).and_then(Value::as_str) == Some("execution_error")
878                    })
879                    .and_then(|message| message.get(1))
880                    .map(summary)
881                    .unwrap_or_else(|| "execution error".into());
882                return Err(GenerationError::Failed(detail));
883            }
884            if status
885                .and_then(|status| status.get("completed"))
886                .and_then(Value::as_bool)
887                == Some(true)
888            {
889                return entry
890                    .get("outputs")
891                    .cloned()
892                    .ok_or(GenerationError::Response("completed prompt has no outputs"));
893            }
894        }
895    }
896
897    async fn fetch(
898        &self,
899        endpoint: &str,
900        kind: GenerationKind,
901        descriptor: &Value,
902        target: &Path,
903        cancel: &CancellationToken,
904    ) -> Result<u64, GenerationError> {
905        let extension = output_extension(kind);
906        let field = |key| descriptor.get(key).and_then(Value::as_str);
907        let filename = field("filename")
908            .filter(|name| safe_output_name(name, extension))
909            .ok_or(GenerationError::Response("unsafe output filename"))?;
910        let subfolder = field("subfolder")
911            .filter(|folder| safe_subfolder(folder))
912            .ok_or(GenerationError::Response("unsafe output subfolder"))?;
913        if field("type") != Some("output") {
914            return Err(GenerationError::Response("output is not a saved file"));
915        }
916        let request = Request::new(endpoint, "/view", None, None)?.with_query(&[
917            ("filename", filename),
918            ("subfolder", subfolder),
919            ("type", "output"),
920        ])?;
921        let parent = target
922            .parent()
923            .filter(|parent| !parent.as_os_str().is_empty())
924            .unwrap_or(Path::new("."));
925        let operation = async {
926            let response = self.http.send(request).await?;
927            if !(200..300).contains(&response.status) {
928                return Err(GenerationError::Http(HttpError::Status(response.status)));
929            }
930            let temporary = tempfile::Builder::new()
931                .prefix(".rigspark-output.")
932                .suffix(".part")
933                .tempfile_in(parent)
934                .map_err(|error| GenerationError::Output(error.to_string()))?;
935            let mut output = tokio::fs::File::from_std(
936                temporary
937                    .reopen()
938                    .map_err(|error| GenerationError::Output(error.to_string()))?,
939            );
940            let mut body = response.body.take(MAX_OUTPUT_BYTES + 1);
941            let mut buffer = vec![0u8; 65536];
942            let mut head = Vec::with_capacity(16);
943            let mut total = 0u64;
944            loop {
945                let count = body
946                    .read(&mut buffer)
947                    .await
948                    .map_err(|_| HttpError::Transport)?;
949                if count == 0 {
950                    break;
951                }
952                total += count as u64;
953                if total > MAX_OUTPUT_BYTES {
954                    return Err(GenerationError::Response("output exceeds 1 GiB"));
955                }
956                if head.len() < 16 {
957                    let needed = (16 - head.len()).min(count);
958                    head.extend_from_slice(&buffer[..needed]);
959                }
960                output
961                    .write_all(&buffer[..count])
962                    .await
963                    .map_err(|error| GenerationError::Output(error.to_string()))?;
964            }
965            if !has_magic(kind, &head) {
966                return Err(GenerationError::Response(
967                    "output is not the expected media type",
968                ));
969            }
970            output
971                .sync_all()
972                .await
973                .map_err(|error| GenerationError::Output(error.to_string()))?;
974            drop(output);
975            temporary.persist_noclobber(target).map_err(|error| {
976                if error.error.kind() == std::io::ErrorKind::AlreadyExists {
977                    GenerationError::Exists(target.to_path_buf())
978                } else {
979                    GenerationError::Output(error.error.to_string())
980                }
981            })?;
982            Ok(total)
983        };
984        tokio::select! {
985            biased;
986            _ = cancel.cancelled() => Err(GenerationError::Cancelled),
987            result = tokio::time::timeout(Duration::from_secs(600), operation) =>
988                result.map_err(|_| GenerationError::Timeout)?,
989        }
990    }
991
992    pub async fn generate(
993        &self,
994        request: &GenerationRequest<'_>,
995        cancel: &CancellationToken,
996    ) -> Result<GenerationOutcome, GenerationError> {
997        let model = request.model;
998        validate_prompt(request.prompt)?;
999        if request.seed > MAX_SEED {
1000            return Err(GenerationError::Invalid(
1001                "seed must be in 0..=9007199254740991",
1002            ));
1003        }
1004        crate::state::loopback(request.endpoint)
1005            .map_err(|_| GenerationError::Invalid("ComfyUI endpoint must be loopback HTTP"))?;
1006        let extension = output_extension(model.kind);
1007        if let Some(output) = request.output {
1008            if !output
1009                .extension()
1010                .and_then(|ext| ext.to_str())
1011                .is_some_and(|ext| ext.eq_ignore_ascii_case(extension))
1012            {
1013                return Err(GenerationError::Invalid(match model.kind {
1014                    GenerationKind::Image => "image output must use the .png extension",
1015                    GenerationKind::Video => "video output must use the .webp extension",
1016                }));
1017            }
1018            if std::fs::symlink_metadata(output).is_ok() {
1019                return Err(GenerationError::Exists(output.to_path_buf()));
1020            }
1021        }
1022        let built_in = model
1023            .runnable()
1024            .map_err(|error| GenerationError::Catalog(error.to_string()))?;
1025        let status = self.ready(request.endpoint, cancel).await?;
1026        let devices = &status.devices;
1027        if matches!(built_in, Workflow::WanT2v | Workflow::Wan22Ti2v) && apple_mps(devices) {
1028            self.emit(
1029                "ComfyUI reports Apple MPS: using the euler sampler (uni_pc diverges on MPS)"
1030                    .into(),
1031            );
1032        }
1033        if built_in == Workflow::MingDesign {
1034            let names = model
1035                .files
1036                .iter()
1037                .map(|file| (file.role, file.file.clone()))
1038                .collect();
1039            let graph = shaped(
1040                workflow(model, &names, request.prompt, request.seed, devices)?,
1041                model.kind,
1042                request.aspect,
1043            )?;
1044            self.emit("Checking native Ming Design capabilities before downloading weights".into());
1045            preflight::ming(self, request.endpoint, &graph, cancel).await?;
1046        }
1047        self.emit(format!("Verifying weights for {}", model.id));
1048        let mut weights = self.install(model, request.comfyui_dir, cancel).await?;
1049        self.resolve_names(request.endpoint, &mut weights, cancel)
1050            .await?;
1051        let names = weights
1052            .iter()
1053            .map(|weight| (weight.role, weight.name.clone()))
1054            .collect();
1055        let graph = shaped(
1056            workflow(model, &names, request.prompt, request.seed, devices)?,
1057            model.kind,
1058            request.aspect,
1059        )?;
1060        ensure_local_only(&graph)?;
1061        self.make_room(
1062            request.endpoint,
1063            &status,
1064            model.total_bytes(),
1065            &graph,
1066            cancel,
1067        )
1068        .await?;
1069        let (status, response) = self
1070            .post_json(
1071                request.endpoint,
1072                "/prompt",
1073                json!({"prompt": graph}),
1074                cancel,
1075            )
1076            .await?;
1077        if !(200..300).contains(&status) {
1078            return Err(GenerationError::Rejected(summary(&response)));
1079        }
1080        if response
1081            .get("node_errors")
1082            .and_then(Value::as_object)
1083            .is_some_and(|errors| !errors.is_empty())
1084        {
1085            return Err(GenerationError::Rejected(summary(&response)));
1086        }
1087        let id = prompt_id(&response)?;
1088        self.emit(format!(
1089            "Queued ComfyUI prompt {id}; generating {}",
1090            model.kind.name()
1091        ));
1092        let outputs = match self.wait(request.endpoint, &id, cancel).await {
1093            Ok(outputs) => outputs,
1094            Err(error) => {
1095                if matches!(error, GenerationError::Cancelled | GenerationError::Timeout) {
1096                    self.cancel_remote(request.endpoint, &id).await;
1097                }
1098                return Err(error);
1099            }
1100        };
1101        let descriptor = outputs
1102            .get(save_node(built_in))
1103            .and_then(|node| node.get("images"))
1104            .and_then(Value::as_array)
1105            .and_then(|images| images.first())
1106            .ok_or(GenerationError::Response("save node produced no output"))?;
1107        let target = match request.output {
1108            Some(path) => path.to_path_buf(),
1109            None => request.output_dir.join(format!(
1110                "rigspark-{}-{}.{extension}",
1111                model.kind.name(),
1112                &id[..id.len().min(8)]
1113            )),
1114        };
1115        let bytes = self
1116            .fetch(request.endpoint, model.kind, descriptor, &target, cancel)
1117            .await?;
1118        Ok(GenerationOutcome {
1119            model: model.id.clone(),
1120            kind: model.kind,
1121            path: target,
1122            bytes,
1123            prompt_id: id,
1124            seed: request.seed,
1125            weights,
1126        })
1127    }
1128}
1129
1130/// Inputs shared by the CLI, terminal UI, and browser GUI.
1131#[derive(Debug, Clone)]
1132pub struct NativeOptions {
1133    pub model: String,
1134    pub prompt: String,
1135    pub seed: Option<u64>,
1136    pub aspect: Aspect,
1137    pub comfyui_dir: PathBuf,
1138    pub port: u16,
1139    pub bypass: bool,
1140    pub output: Option<PathBuf>,
1141    pub output_dir: PathBuf,
1142}
1143
1144#[derive(Debug, Clone, Serialize)]
1145pub struct NativeOutcome {
1146    pub result: GenerationOutcome,
1147    pub fit: GenerationFit,
1148}
1149
1150/// `RIGSPARK_COMFYUI_DIR`, else `~/ComfyUI` when it looks like a ComfyUI install.
1151pub fn default_comfyui_dir() -> Option<PathBuf> {
1152    if let Some(dir) = std::env::var_os("RIGSPARK_COMFYUI_DIR").filter(|dir| !dir.is_empty()) {
1153        return Some(PathBuf::from(dir));
1154    }
1155    let home = std::env::var_os("HOME")
1156        .or_else(|| std::env::var_os("USERPROFILE"))
1157        .filter(|home| !home.is_empty())?;
1158    let candidate = PathBuf::from(home).join("ComfyUI");
1159    candidate.join("models").is_dir().then_some(candidate)
1160}
1161
1162/// Validates everything that needs no hardware, network, or ComfyUI access.
1163pub fn prepare(
1164    options: &NativeOptions,
1165) -> Result<(GenerationModel, u64, PathBuf), GenerationError> {
1166    validate_prompt(&options.prompt)?;
1167    let seed = match options.seed {
1168        Some(seed) if seed <= MAX_SEED => seed,
1169        Some(_) => {
1170            return Err(GenerationError::Invalid(
1171                "seed must be in 0..=9007199254740991",
1172            ));
1173        }
1174        None => random_seed(),
1175    };
1176    if options.port == 0 {
1177        return Err(GenerationError::Invalid(
1178            "ComfyUI port must be in 1..=65535",
1179        ));
1180    }
1181    let catalog = GenerationCatalog::bundled()
1182        .map_err(|error| GenerationError::Catalog(error.to_string()))?;
1183    let model = catalog
1184        .resolve(&options.model)
1185        .map_err(|error| GenerationError::Catalog(error.to_string()))?
1186        .clone();
1187    model
1188        .runnable()
1189        .map_err(|error| GenerationError::Catalog(error.to_string()))?;
1190    if options.aspect != Aspect::Square && model.kind != GenerationKind::Image {
1191        return Err(GenerationError::Invalid("only images take an aspect ratio"));
1192    }
1193    if options.comfyui_dir.as_os_str().is_empty() {
1194        return Err(GenerationError::Invalid(
1195            "a ComfyUI directory is required (--comfyui-dir or RIGSPARK_COMFYUI_DIR)",
1196        ));
1197    }
1198    let dir = std::path::absolute(&options.comfyui_dir)
1199        .map_err(|_| GenerationError::Invalid("invalid ComfyUI directory"))?;
1200    if !dir.join("models").is_dir() {
1201        return Err(GenerationError::Invalid(
1202            "ComfyUI directory must contain a models/ folder",
1203        ));
1204    }
1205    Ok((model, seed, dir))
1206}
1207
1208/// Full local run: validate, check memory fit, then drive the loopback ComfyUI server.
1209pub async fn run_native(
1210    options: &NativeOptions,
1211    events: Option<Events>,
1212    cancel: &CancellationToken,
1213) -> Result<NativeOutcome, GenerationError> {
1214    let (model, seed, comfyui_dir) = prepare(options)?;
1215    let emit = |message: String| {
1216        if let Some(events) = &events {
1217            events(message);
1218        }
1219    };
1220    let (hardware, warnings) = crate::hardware::detect()
1221        .await
1222        .map_err(|error| GenerationError::Hardware(error.to_string()))?;
1223    for warning in warnings {
1224        emit(warning);
1225    }
1226    let memory = fit(&model, &hardware);
1227    if memory.verdict == FitVerdict::No && !options.bypass {
1228        return Err(GenerationError::NoFit(format!(
1229            "{} will not fit this machine ({}); bypass to try anyway (integrity checks still apply)",
1230            model.id, memory.reason
1231        )));
1232    }
1233    emit(format!(
1234        "Model {} ({}): fit {} - {}; speed unknown",
1235        model.id,
1236        model.kind.name(),
1237        memory.verdict.name(),
1238        memory.reason
1239    ));
1240    let http = crate::http::NativeTransport::new()?;
1241    let download = crate::acquire::HfTransport::new().map_err(GenerationError::Install)?;
1242    let client = ComfyUi {
1243        http: &http,
1244        download: &download,
1245        poll_interval: Duration::from_secs(1),
1246        deadline: Duration::from_secs(2 * 60 * 60),
1247        events: events.clone(),
1248    };
1249    let endpoint = format!("http://127.0.0.1:{}", options.port);
1250    let result = client
1251        .generate(
1252            &GenerationRequest {
1253                model: &model,
1254                prompt: &options.prompt,
1255                seed,
1256                aspect: options.aspect,
1257                endpoint: &endpoint,
1258                comfyui_dir: &comfyui_dir,
1259                output: options.output.as_deref(),
1260                output_dir: &options.output_dir,
1261            },
1262            cancel,
1263        )
1264        .await?;
1265    Ok(NativeOutcome {
1266        result,
1267        fit: memory,
1268    })
1269}
1270
1271pub type GenerationFuture<'call> = std::pin::Pin<
1272    Box<dyn std::future::Future<Output = Result<NativeOutcome, GenerationError>> + Send + 'call>,
1273>;
1274
1275/// Injectable generation boundary so the TUI and GUI can be tested without ComfyUI.
1276pub trait Generator: Send + Sync {
1277    fn generate(
1278        &self,
1279        options: NativeOptions,
1280        events: Events,
1281        cancel: CancellationToken,
1282    ) -> GenerationFuture<'_>;
1283}
1284
1285pub struct NativeGenerator;
1286impl Generator for NativeGenerator {
1287    fn generate(
1288        &self,
1289        options: NativeOptions,
1290        events: Events,
1291        cancel: CancellationToken,
1292    ) -> GenerationFuture<'_> {
1293        Box::pin(async move { run_native(&options, Some(events), &cancel).await })
1294    }
1295}
1296
1297#[cfg(test)]
1298mod tests {
1299    use super::*;
1300
1301    #[test]
1302    fn prompt_ids_are_short_ascii_alphanumeric_or_dash() {
1303        let id = |value: &str| prompt_id(&json!({ "prompt_id": value }));
1304        assert_eq!(id("abc-123").unwrap(), "abc-123");
1305        assert!(id(&"a".repeat(128)).is_ok());
1306        for bad in ["", "abc def", "../x", "abc/def", "é"] {
1307            assert!(id(bad).is_err(), "{bad:?}");
1308        }
1309        assert!(id(&"a".repeat(129)).is_err());
1310        assert!(prompt_id(&json!({"prompt_id": 7})).is_err());
1311    }
1312
1313    #[test]
1314    fn output_subfolders_stay_relative_and_inside_the_output_tree() {
1315        for good in ["", "a", "a/b", "videos/2026-11"] {
1316            assert!(safe_subfolder(good), "{good:?}");
1317        }
1318        assert!(safe_subfolder(&"a".repeat(255)));
1319        assert!(!safe_subfolder(&"a".repeat(256)));
1320        for bad in [
1321            "/etc", "a\\b", "c:x", "a\u{1}b", "a//b", "a/", ".", "..", "./a", "a/..", "../a",
1322        ] {
1323            assert!(!safe_subfolder(bad), "{bad:?}");
1324        }
1325    }
1326
1327    #[test]
1328    fn media_is_recognised_by_its_signature() {
1329        assert!(has_magic(GenerationKind::Image, b"\x89PNG\r\n\x1a\nrest"));
1330        assert!(!has_magic(GenerationKind::Image, b"\x89PNG\r\n"));
1331        assert!(has_magic(GenerationKind::Video, b"RIFF\0\0\0\0WEBP"));
1332        for bad in [
1333            b"RIFF\0\0\0\0WEBX".as_slice(),
1334            b"RIFX\0\0\0\0WEBP",
1335            b"RIFF\0\0\0\0WEB",
1336            b"RIFF",
1337            b"",
1338        ] {
1339            assert!(!has_magic(GenerationKind::Video, bad), "{bad:?}");
1340        }
1341    }
1342}