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