Skip to main content

rigspark_runtime/
engines.rs

1//! Managed engines: ComfyUI (image and video) and mlx-audio (voice on Apple Silicon).
2//!
3//! After one consent click RigSpark installs them into its own folder (`<home>/engines`) from
4//! pinned sources, then starts, health-checks, reuses and stops them itself. Installs the user
5//! already has win: a ComfyUI listening on 127.0.0.1:8188, an existing ComfyUI folder with its
6//! own Python, or an `mlx_audio.server` on PATH. See docs/specs/managed-engines.md.
7use async_trait::async_trait;
8use futures_util::StreamExt;
9use serde::Serialize;
10use sha2::{Digest, Sha256};
11use std::{
12    collections::BTreeMap,
13    path::{Path, PathBuf},
14    sync::{Arc, Mutex},
15    time::Duration,
16};
17use tokio::io::AsyncWriteExt;
18use tokio_util::sync::CancellationToken;
19
20/// The installer that fetches Python and packages.
21pub const UV_VERSION: &str = "0.13.7";
22pub const PYTHON_VERSION: &str = "3.12";
23/// Packages resolve as they were on this date, so every install gets the same versions.
24pub const PACKAGES_AS_OF: &str = "2026-11-01T00:00:00Z";
25pub const COMFYUI_VERSION: &str = "0.38.2";
26pub const MLX_AUDIO_REQUIREMENT: &str = "mlx-audio==0.6.4";
27/// Port a ComfyUI started by hand listens on.
28pub const COMFYUI_DEFAULT_PORT: u16 = 8188;
29/// The first start imports PyTorch, which can take minutes on a cold disk.
30const COMFYUI_READY_TIMEOUT: Duration = Duration::from_secs(300);
31const REDIRECT_LIMIT: usize = 5;
32
33/// A file fetched over HTTPS and checked against a pinned SHA-256 before use.
34#[derive(Debug, Clone, Copy, PartialEq, Eq)]
35pub struct Pinned {
36    pub url: &'static str,
37    pub sha256: &'static str,
38    /// Larger downloads are refused.
39    pub max_bytes: u64,
40}
41
42/// `uv`'s official release tarball for this platform and the folder inside it.
43pub fn uv_pin(os: &str, arch: &str) -> Option<(Pinned, &'static str)> {
44    const MAX: u64 = 64 * 1024 * 1024;
45    let (folder, sha256) = match (os, arch) {
46        ("macos", "aarch64") => (
47            "uv-aarch64-apple-darwin",
48            "81b811b57e4624df7ed3aac148e0359100d9962f3d9dce00aec533dc2e086731",
49        ),
50        ("macos", "x86_64") => (
51            "uv-x86_64-apple-darwin",
52            "20c47e4c1f630b8abaff8c291fa9b9aa300fef92c4fbff95adf198b55287cda7",
53        ),
54        ("linux", "x86_64") => (
55            "uv-x86_64-unknown-linux-gnu",
56            "c5221ff41b7892bfc223543883600125f6a47fe845093e0f5bdff4f359196d83",
57        ),
58        ("linux", "aarch64") => (
59            "uv-aarch64-unknown-linux-gnu",
60            "71279f8d3c67241e807b9d8db872d1bf541579fb9f08b7d1eb1682196d1e57dc",
61        ),
62        _ => return None,
63    };
64    let url = match folder {
65        "uv-aarch64-apple-darwin" => {
66            "https://github.com/astral-sh/uv/releases/download/0.13.7/uv-aarch64-apple-darwin.tar.gz"
67        }
68        "uv-x86_64-apple-darwin" => {
69            "https://github.com/astral-sh/uv/releases/download/0.13.7/uv-x86_64-apple-darwin.tar.gz"
70        }
71        "uv-x86_64-unknown-linux-gnu" => {
72            "https://github.com/astral-sh/uv/releases/download/0.13.7/uv-x86_64-unknown-linux-gnu.tar.gz"
73        }
74        _ => {
75            "https://github.com/astral-sh/uv/releases/download/0.13.7/uv-aarch64-unknown-linux-gnu.tar.gz"
76        }
77    };
78    Some((
79        Pinned {
80            url,
81            sha256,
82            max_bytes: MAX,
83        },
84        folder,
85    ))
86}
87
88/// ComfyUI's upstream release source (GPL-3.0, unmodified) and the folder it unpacks to.
89pub const COMFYUI_SOURCE: Pinned = Pinned {
90    url: "https://codeload.github.com/comfyanonymous/ComfyUI/tar.gz/refs/tags/v0.38.2",
91    sha256: "124fe87ed469ae582a08ee0bbc05761f0b1239c38e4a095bb564479e66ed671e",
92    max_bytes: 64 * 1024 * 1024,
93};
94pub const COMFYUI_FOLDER: &str = "ComfyUI-0.38.2";
95
96/// Hosts RigSpark itself downloads engine files from; every redirect is checked again.
97const ALLOWED_HOSTS: &[&str] = &[
98    "github.com",
99    "codeload.github.com",
100    "objects.githubusercontent.com",
101    "release-assets.githubusercontent.com",
102];
103
104pub fn allowed_url(raw: &str) -> Result<url::Url, String> {
105    let url = url::Url::parse(raw).map_err(|_| "invalid download URL".to_owned())?;
106    let host = url.host_str().unwrap_or_default();
107    if url.scheme() != "https"
108        || !url.username().is_empty()
109        || url.password().is_some()
110        || url.port().is_some()
111        || !ALLOWED_HOSTS.contains(&host)
112    {
113        return Err(format!("download host is not allowed: {host}"));
114    }
115    Ok(url)
116}
117
118#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize)]
119#[serde(rename_all = "kebab-case")]
120pub enum Engine {
121    Comfyui,
122    MlxAudio,
123}
124
125impl Engine {
126    pub const ALL: [Engine; 2] = [Engine::Comfyui, Engine::MlxAudio];
127    pub fn name(self) -> &'static str {
128        match self {
129            Engine::Comfyui => "comfyui",
130            Engine::MlxAudio => "mlx-audio",
131        }
132    }
133    pub fn parse(value: &str) -> Option<Self> {
134        Self::ALL.into_iter().find(|engine| engine.name() == value)
135    }
136    pub fn label(self) -> &'static str {
137        match self {
138            Engine::Comfyui => "Image and video (ComfyUI)",
139            Engine::MlxAudio => "Voice (mlx-audio)",
140        }
141    }
142    /// What the consent card says will be installed.
143    pub fn installs(self) -> &'static str {
144        match self {
145            Engine::Comfyui => {
146                "Python 3.12, PyTorch and ComfyUI 0.38.2, into RigSpark's own folder. Downloads several GB."
147            }
148            Engine::MlxAudio => {
149                "Python 3.12 and mlx-audio 0.6.4, into RigSpark's own folder. Downloads about a GB."
150            }
151        }
152    }
153    fn steps(self) -> u32 {
154        match self {
155            Engine::Comfyui => 5,
156            Engine::MlxAudio => 3,
157        }
158    }
159}
160
161#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
162#[serde(rename_all = "lowercase")]
163pub enum EngineState {
164    Missing,
165    Installing,
166    Ready,
167    Failed,
168    Unsupported,
169}
170
171/// Where a ready engine comes from.
172#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
173#[serde(rename_all = "lowercase")]
174pub enum Source {
175    /// Installed by RigSpark under `<home>/engines`.
176    Managed,
177    /// The user's own install.
178    Existing,
179}
180
181#[derive(Debug, Clone, Serialize)]
182#[serde(rename_all = "camelCase")]
183pub struct EngineView {
184    pub engine: Engine,
185    pub label: &'static str,
186    pub installs: &'static str,
187    pub state: EngineState,
188    pub source: Option<Source>,
189    pub detail: String,
190    /// `(step, of)` while installing.
191    pub step: Option<(u32, u32)>,
192    /// Where a running ComfyUI answers.
193    pub endpoint: Option<String>,
194}
195
196/// Network boundary: fetch `pinned` to `dest` only if its SHA-256 matches.
197#[async_trait]
198pub trait Fetch: Send + Sync {
199    async fn fetch(
200        &self,
201        pinned: &Pinned,
202        dest: &Path,
203        cancel: &CancellationToken,
204    ) -> Result<(), String>;
205}
206
207/// Process boundary for install steps (`tar`, `uv`): run to completion.
208#[async_trait]
209pub trait Run: Send + Sync {
210    async fn run(
211        &self,
212        program: &Path,
213        args: &[String],
214        env: &BTreeMap<String, String>,
215        cancel: &CancellationToken,
216    ) -> Result<(), String>;
217}
218
219pub struct HttpsFetch {
220    client: reqwest::Client,
221}
222
223impl HttpsFetch {
224    pub fn new() -> Result<Self, String> {
225        Ok(Self {
226            client: reqwest::Client::builder()
227                .redirect(reqwest::redirect::Policy::none())
228                .connect_timeout(Duration::from_secs(15))
229                .user_agent(concat!("rigspark/", env!("CARGO_PKG_VERSION")))
230                .build()
231                .map_err(|error| error.to_string())?,
232        })
233    }
234}
235
236#[async_trait]
237impl Fetch for HttpsFetch {
238    async fn fetch(
239        &self,
240        pinned: &Pinned,
241        dest: &Path,
242        cancel: &CancellationToken,
243    ) -> Result<(), String> {
244        let mut url = allowed_url(pinned.url)?;
245        let mut response = None;
246        for _ in 0..=REDIRECT_LIMIT {
247            let reply = tokio::select! {
248                biased;
249                _ = cancel.cancelled() => return Err("cancelled".into()),
250                reply = self.client.get(url.clone()).send() => reply.map_err(|error| format!("download failed: {error}"))?,
251            };
252            if reply.status().is_redirection() {
253                let location = reply
254                    .headers()
255                    .get("location")
256                    .and_then(|value| value.to_str().ok())
257                    .ok_or("redirect without a location")?;
258                url = allowed_url(
259                    url.join(location)
260                        .map_err(|_| "invalid redirect".to_owned())?
261                        .as_str(),
262                )?;
263                continue;
264            }
265            response = Some(reply);
266            break;
267        }
268        let response = response.ok_or("too many download redirects")?;
269        if !response.status().is_success() {
270            return Err(format!("download failed: HTTP {}", response.status()));
271        }
272        if response
273            .content_length()
274            .is_some_and(|length| length > pinned.max_bytes)
275        {
276            return Err("download is larger than allowed".into());
277        }
278        let parent = dest.parent().ok_or("invalid download destination")?;
279        tokio::fs::create_dir_all(parent)
280            .await
281            .map_err(|error| error.to_string())?;
282        let partial = dest.with_extension("part");
283        let mut file = tokio::fs::File::create(&partial)
284            .await
285            .map_err(|error| error.to_string())?;
286        let mut hash = Sha256::new();
287        let mut total = 0u64;
288        let mut stream = response.bytes_stream();
289        loop {
290            let chunk = tokio::select! {
291                biased;
292                _ = cancel.cancelled() => None,
293                chunk = stream.next() => Some(chunk),
294            };
295            let Some(chunk) = chunk else {
296                let _ = tokio::fs::remove_file(&partial).await;
297                return Err("cancelled".into());
298            };
299            let Some(chunk) = chunk else { break };
300            let chunk = chunk.map_err(|error| format!("download interrupted: {error}"))?;
301            total += chunk.len() as u64;
302            if total > pinned.max_bytes {
303                let _ = tokio::fs::remove_file(&partial).await;
304                return Err("download is larger than allowed".into());
305            }
306            hash.update(&chunk);
307            file.write_all(&chunk)
308                .await
309                .map_err(|error| error.to_string())?;
310        }
311        file.sync_all().await.map_err(|error| error.to_string())?;
312        drop(file);
313        verify_digest(&format!("{:x}", hash.finalize()), pinned.sha256).inspect_err(|_| {
314            let _ = std::fs::remove_file(&partial);
315        })?;
316        tokio::fs::rename(&partial, dest)
317            .await
318            .map_err(|error| error.to_string())
319    }
320}
321
322/// Fail closed: anything but the pinned digest is refused.
323pub fn verify_digest(actual: &str, pinned: &str) -> Result<(), String> {
324    if pinned.len() == 64 && actual.eq_ignore_ascii_case(pinned) {
325        Ok(())
326    } else {
327        Err("download integrity mismatch; refusing to install".into())
328    }
329}
330
331pub struct SystemRun;
332
333#[async_trait]
334impl Run for SystemRun {
335    async fn run(
336        &self,
337        program: &Path,
338        args: &[String],
339        env: &BTreeMap<String, String>,
340        cancel: &CancellationToken,
341    ) -> Result<(), String> {
342        let mut command = tokio::process::Command::new(program);
343        command
344            .args(args)
345            .envs(env)
346            .stdin(std::process::Stdio::null())
347            .stdout(std::process::Stdio::null())
348            .stderr(std::process::Stdio::piped())
349            .kill_on_drop(true);
350        let child = command
351            .spawn()
352            .map_err(|_| format!("could not run {}", display_name(program)))?;
353        let output = tokio::select! {
354            biased;
355            _ = cancel.cancelled() => return Err("cancelled".into()),
356            output = child.wait_with_output() => output.map_err(|error| error.to_string())?,
357        };
358        if output.status.success() {
359            return Ok(());
360        }
361        // The last line of stderr is usually the reason (a resolver or network error).
362        let reason = String::from_utf8_lossy(&output.stderr)
363            .lines()
364            .rev()
365            .find(|line| !line.trim().is_empty())
366            .map(|line| rigspark_core::reports::strip_control(line.trim()))
367            .unwrap_or_default();
368        let reason: String = reason.chars().take(300).collect();
369        Err(format!(
370            "{} failed{}",
371            display_name(program),
372            if reason.is_empty() {
373                String::new()
374            } else {
375                format!(": {reason}")
376            }
377        ))
378    }
379}
380
381fn display_name(program: &Path) -> String {
382    program
383        .file_name()
384        .map(|name| name.to_string_lossy().into_owned())
385        .unwrap_or_else(|| "installer".into())
386}
387
388/// A ComfyUI install RigSpark can start: its folder and its own Python.
389#[derive(Debug, Clone, PartialEq, Eq)]
390pub struct ComfyInstall {
391    pub dir: PathBuf,
392    pub python: PathBuf,
393    pub source: Source,
394}
395
396/// Where ComfyUI answers for a generation.
397#[derive(Debug, Clone, PartialEq, Eq)]
398pub struct ComfyEndpoint {
399    pub dir: PathBuf,
400    pub port: u16,
401    /// RigSpark started it and stops it on shutdown.
402    pub owned: bool,
403}
404
405/// The Python inside an existing ComfyUI folder, if it has its own environment.
406pub fn comfy_python(dir: &Path) -> Option<PathBuf> {
407    [
408        ".venv/bin/python",
409        "venv/bin/python",
410        ".venv/Scripts/python.exe",
411        "venv/Scripts/python.exe",
412    ]
413    .iter()
414    .map(|candidate| dir.join(candidate))
415    .find(|candidate| candidate.is_file())
416}
417
418#[derive(Debug, Clone, Default)]
419struct Progress {
420    installing: bool,
421    failed: Option<String>,
422    step: Option<(u32, u32)>,
423    detail: String,
424}
425
426struct Owned {
427    child: tokio::process::Child,
428    endpoint: ComfyEndpoint,
429}
430
431pub struct Engines {
432    root: PathBuf,
433    fetch: Arc<dyn Fetch>,
434    run: Arc<dyn Run>,
435    platform: (&'static str, &'static str),
436    /// The user's own ComfyUI folder (`RIGSPARK_COMFYUI_DIR` or `~/ComfyUI`).
437    existing_comfyui: Option<PathBuf>,
438    progress: Mutex<BTreeMap<Engine, Progress>>,
439    comfy: tokio::sync::Mutex<Option<Owned>>,
440    client: reqwest::Client,
441    default_port: u16,
442}
443
444impl Engines {
445    /// The real network, `tar` and `uv`, for `home`'s `engines` folder.
446    pub fn new(home: &Path) -> Result<Arc<Self>, String> {
447        Ok(Arc::new(Self::with(
448            home.join("engines"),
449            Arc::new(HttpsFetch::new()?),
450            Arc::new(SystemRun),
451            (std::env::consts::OS, std::env::consts::ARCH),
452            crate::generation::default_comfyui_dir(),
453            COMFYUI_DEFAULT_PORT,
454        )))
455    }
456
457    /// Everything injected; for tests.
458    pub fn with(
459        root: PathBuf,
460        fetch: Arc<dyn Fetch>,
461        run: Arc<dyn Run>,
462        platform: (&'static str, &'static str),
463        existing_comfyui: Option<PathBuf>,
464        default_port: u16,
465    ) -> Self {
466        Self {
467            root,
468            fetch,
469            run,
470            platform,
471            existing_comfyui,
472            progress: Mutex::new(BTreeMap::new()),
473            comfy: tokio::sync::Mutex::new(None),
474            client: reqwest::Client::builder()
475                .no_proxy()
476                .build()
477                .unwrap_or_default(),
478            default_port,
479        }
480    }
481
482    pub fn root(&self) -> &Path {
483        &self.root
484    }
485
486    fn engine_dir(&self, engine: Engine) -> PathBuf {
487        self.root.join(engine.name())
488    }
489
490    fn marker(&self, engine: Engine) -> PathBuf {
491        self.engine_dir(engine).join("installed.json")
492    }
493
494    fn uv_binary(&self) -> PathBuf {
495        let folder = uv_pin(self.platform.0, self.platform.1)
496            .map(|(_, folder)| folder)
497            .unwrap_or("uv");
498        self.root
499            .join("tools")
500            .join(format!("uv-{UV_VERSION}"))
501            .join(folder)
502            .join(if self.platform.0 == "windows" {
503                "uv.exe"
504            } else {
505                "uv"
506            })
507    }
508
509    fn managed_comfyui_dir(&self) -> PathBuf {
510        self.engine_dir(Engine::Comfyui).join(COMFYUI_FOLDER)
511    }
512
513    fn venv_python(venv: &Path) -> PathBuf {
514        venv.join("bin").join("python")
515    }
516
517    /// Whether this machine can run `engine` from a managed install.
518    pub fn supported(&self, engine: Engine) -> bool {
519        match engine {
520            Engine::Comfyui => uv_pin(self.platform.0, self.platform.1).is_some(),
521            Engine::MlxAudio => self.platform == ("macos", "aarch64"),
522        }
523    }
524
525    fn installed(&self, engine: Engine) -> bool {
526        self.marker(engine).is_file()
527            && match engine {
528                Engine::Comfyui => comfy_python(&self.managed_comfyui_dir()).is_some(),
529                Engine::MlxAudio => self.managed_mlx_audio_server().is_some(),
530            }
531    }
532
533    /// RigSpark's own `mlx_audio.server`, once installed.
534    pub fn managed_mlx_audio_server(&self) -> Option<PathBuf> {
535        managed_mlx_audio_server_in(&self.root)
536    }
537
538    /// The ComfyUI to use: RigSpark's own first, then the user's folder if it has a Python.
539    pub fn comfyui_install(&self) -> Option<ComfyInstall> {
540        if self.installed(Engine::Comfyui) {
541            let dir = self.managed_comfyui_dir();
542            return comfy_python(&dir).map(|python| ComfyInstall {
543                dir,
544                python,
545                source: Source::Managed,
546            });
547        }
548        let dir = self.existing_comfyui.clone()?;
549        comfy_python(&dir).map(|python| ComfyInstall {
550            dir,
551            python,
552            source: Source::Existing,
553        })
554    }
555
556    /// A ComfyUI folder for weights even when it can't be started by RigSpark (a user who
557    /// runs ComfyUI themselves, perhaps with conda).
558    pub fn comfyui_dir(&self) -> Option<PathBuf> {
559        self.comfyui_install()
560            .map(|install| install.dir)
561            .or_else(|| self.existing_comfyui.clone())
562    }
563
564    pub fn status(&self, engine: Engine, external_mlx_audio: bool) -> EngineView {
565        let progress = self
566            .progress
567            .lock()
568            .ok()
569            .and_then(|progress| progress.get(&engine).cloned())
570            .unwrap_or_default();
571        let (state, source) = if progress.installing {
572            (EngineState::Installing, None)
573        } else {
574            match engine {
575                Engine::Comfyui => match self.comfyui_install() {
576                    Some(install) => (EngineState::Ready, Some(install.source)),
577                    None if progress.failed.is_some() => (EngineState::Failed, None),
578                    None if !self.supported(engine) => (EngineState::Unsupported, None),
579                    None => (EngineState::Missing, None),
580                },
581                Engine::MlxAudio => {
582                    if self.managed_mlx_audio_server().is_some() {
583                        (EngineState::Ready, Some(Source::Managed))
584                    } else if external_mlx_audio {
585                        (EngineState::Ready, Some(Source::Existing))
586                    } else if progress.failed.is_some() {
587                        (EngineState::Failed, None)
588                    } else if !self.supported(engine) {
589                        (EngineState::Unsupported, None)
590                    } else {
591                        (EngineState::Missing, None)
592                    }
593                }
594            }
595        };
596        let endpoint = match engine {
597            Engine::Comfyui => self.comfy.try_lock().ok().and_then(|owned| {
598                owned
599                    .as_ref()
600                    .map(|owned| format!("http://127.0.0.1:{}", owned.endpoint.port))
601            }),
602            Engine::MlxAudio => None,
603        };
604        let detail = match state {
605            EngineState::Installing => progress.detail,
606            EngineState::Failed => progress.failed.unwrap_or_default(),
607            EngineState::Unsupported if engine == Engine::MlxAudio => {
608                "mlx-audio runs on Apple Silicon only; attach a local speech server instead".into()
609            }
610            EngineState::Unsupported => {
611                "Managed install isn't available on this platform yet; start ComfyUI yourself"
612                    .into()
613            }
614            _ => String::new(),
615        };
616        EngineView {
617            engine,
618            label: engine.label(),
619            installs: engine.installs(),
620            state,
621            source,
622            detail,
623            step: (state == EngineState::Installing)
624                .then_some(progress.step)
625                .flatten(),
626            endpoint,
627        }
628    }
629
630    fn report(&self, engine: Engine, step: u32, detail: &str) {
631        if let Ok(mut progress) = self.progress.lock() {
632            let entry = progress.entry(engine).or_default();
633            entry.step = Some((step, engine.steps()));
634            entry.detail = detail.to_owned();
635        }
636    }
637
638    /// Starts installing `engine` in the background. Refuses a second install of the same
639    /// engine while one runs.
640    pub fn install(
641        self: &Arc<Self>,
642        engine: Engine,
643        cancel: CancellationToken,
644    ) -> Result<(), String> {
645        if !self.supported(engine) {
646            return Err(format!(
647                "{} can't be installed on this machine",
648                engine.label()
649            ));
650        }
651        {
652            let mut progress = self
653                .progress
654                .lock()
655                .map_err(|_| "engine state unavailable")?;
656            let entry = progress.entry(engine).or_default();
657            if entry.installing {
658                return Err(format!("{} is already being installed", engine.label()));
659            }
660            *entry = Progress {
661                installing: true,
662                detail: "Starting".into(),
663                ..Progress::default()
664            };
665        }
666        let engines = self.clone();
667        tokio::spawn(async move {
668            let outcome = engines.install_now(engine, &cancel).await;
669            if let Ok(mut progress) = engines.progress.lock() {
670                let entry = progress.entry(engine).or_default();
671                entry.installing = false;
672                entry.step = None;
673                entry.failed = outcome.err();
674            }
675        });
676        Ok(())
677    }
678
679    /// Runs every step; the installed marker is written only after all of them succeed.
680    pub async fn install_now(
681        &self,
682        engine: Engine,
683        cancel: &CancellationToken,
684    ) -> Result<(), String> {
685        let _ = tokio::fs::remove_file(self.marker(engine)).await;
686        let uv = self.ensure_uv(engine, cancel).await?;
687        let env = self.uv_env();
688        let dir = self.engine_dir(engine);
689        match engine {
690            Engine::Comfyui => {
691                self.report(engine, 2, "Downloading ComfyUI 0.38.2");
692                let archive = self
693                    .root
694                    .join("downloads")
695                    .join(format!("comfyui-{COMFYUI_VERSION}.tar.gz"));
696                self.fetch.fetch(&COMFYUI_SOURCE, &archive, cancel).await?;
697                self.report(engine, 3, "Unpacking ComfyUI");
698                tokio::fs::create_dir_all(&dir)
699                    .await
700                    .map_err(|error| error.to_string())?;
701                let target = self.managed_comfyui_dir();
702                if tokio::fs::try_exists(&target).await.unwrap_or(false) {
703                    tokio::fs::remove_dir_all(&target)
704                        .await
705                        .map_err(|error| error.to_string())?;
706                }
707                self.run
708                    .run(
709                        Path::new("tar"),
710                        &untar(&archive, &dir),
711                        &BTreeMap::new(),
712                        cancel,
713                    )
714                    .await?;
715                if !target.join("main.py").is_file() {
716                    return Err("ComfyUI archive did not unpack as expected".into());
717                }
718                self.report(engine, 4, "Installing Python 3.12");
719                let venv = target.join(".venv");
720                self.run.run(&uv, &venv_args(&venv), &env, cancel).await?;
721                self.report(engine, 5, "Installing PyTorch and ComfyUI's packages");
722                let mut args = pip_args(&venv);
723                args.extend([
724                    "-r".into(),
725                    target.join("requirements.txt").display().to_string(),
726                ]);
727                self.run.run(&uv, &args, &env, cancel).await?;
728                if !Self::venv_python(&venv).is_file() {
729                    return Err("ComfyUI's Python environment is missing".into());
730                }
731            }
732            Engine::MlxAudio => {
733                self.report(engine, 2, "Installing Python 3.12");
734                let venv = dir.join(".venv");
735                self.run.run(&uv, &venv_args(&venv), &env, cancel).await?;
736                self.report(engine, 3, "Installing mlx-audio 0.6.4");
737                let mut args = pip_args(&venv);
738                args.push(MLX_AUDIO_REQUIREMENT.into());
739                self.run.run(&uv, &args, &env, cancel).await?;
740                if !venv.join("bin/mlx_audio.server").is_file() {
741                    return Err("mlx-audio installed without its server".into());
742                }
743            }
744        }
745        let marker = serde_json::json!({
746            "engine": engine.name(),
747            "uv": UV_VERSION,
748            "python": PYTHON_VERSION,
749            "packagesAsOf": PACKAGES_AS_OF,
750            "version": match engine { Engine::Comfyui => COMFYUI_VERSION, Engine::MlxAudio => MLX_AUDIO_REQUIREMENT },
751        });
752        tokio::fs::write(self.marker(engine), marker.to_string())
753            .await
754            .map_err(|error| error.to_string())
755    }
756
757    async fn ensure_uv(
758        &self,
759        engine: Engine,
760        cancel: &CancellationToken,
761    ) -> Result<PathBuf, String> {
762        self.report(engine, 1, "Getting the installer (uv 0.13.7)");
763        let binary = self.uv_binary();
764        if binary.is_file() {
765            return Ok(binary);
766        }
767        let (pin, _) =
768            uv_pin(self.platform.0, self.platform.1).ok_or("no installer for this platform")?;
769        let archive = self
770            .root
771            .join("downloads")
772            .join(format!("uv-{UV_VERSION}.tar.gz"));
773        self.fetch.fetch(&pin, &archive, cancel).await?;
774        let tools = self.root.join("tools").join(format!("uv-{UV_VERSION}"));
775        tokio::fs::create_dir_all(&tools)
776            .await
777            .map_err(|error| error.to_string())?;
778        self.run
779            .run(
780                Path::new("tar"),
781                &untar(&archive, &tools),
782                &BTreeMap::new(),
783                cancel,
784            )
785            .await?;
786        if !binary.is_file() {
787            return Err("installer archive did not unpack as expected".into());
788        }
789        Ok(binary)
790    }
791
792    /// Keeps `uv`'s cache and Python builds inside RigSpark's folder and ignores any user
793    /// configuration that could point it elsewhere.
794    fn uv_env(&self) -> BTreeMap<String, String> {
795        [
796            ("UV_NO_CONFIG", "1".to_owned()),
797            (
798                "UV_CACHE_DIR",
799                self.root.join("cache").display().to_string(),
800            ),
801            (
802                "UV_PYTHON_INSTALL_DIR",
803                self.root.join("python").display().to_string(),
804            ),
805            ("UV_PYTHON_PREFERENCE", "only-managed".to_owned()),
806        ]
807        .into_iter()
808        .map(|(key, value)| (key.to_owned(), value))
809        .collect()
810    }
811
812    /// A ComfyUI to generate with, starting one if none answers. Reuses the one RigSpark
813    /// started earlier while it is alive.
814    pub async fn ensure_comfyui(
815        &self,
816        cancel: &CancellationToken,
817    ) -> Result<ComfyEndpoint, String> {
818        let mut owned = self.comfy.lock().await;
819        if let Some(current) = owned.as_mut() {
820            if matches!(current.child.try_wait(), Ok(None))
821                && self.answers(current.endpoint.port).await
822            {
823                return Ok(current.endpoint.clone());
824            }
825            *owned = None;
826        }
827        if self.answers(self.default_port).await {
828            let dir = self.comfyui_dir().ok_or(
829                "ComfyUI is running, but its folder wasn't found; set RIGSPARK_COMFYUI_DIR",
830            )?;
831            return Ok(ComfyEndpoint {
832                dir,
833                port: self.default_port,
834                owned: false,
835            });
836        }
837        let install = self
838            .comfyui_install()
839            .ok_or("ComfyUI isn't set up yet: choose Set up in the composer to install it")?;
840        let port = free_port()?;
841        let mut command = tokio::process::Command::new(&install.python);
842        command
843            .arg(install.dir.join("main.py"))
844            .args([
845                "--listen",
846                "127.0.0.1",
847                "--port",
848                &port.to_string(),
849                "--disable-auto-launch",
850            ])
851            .current_dir(&install.dir)
852            .stdin(std::process::Stdio::null())
853            .stdout(std::process::Stdio::null())
854            .stderr(std::process::Stdio::null())
855            .kill_on_drop(true);
856        let mut child = command
857            .spawn()
858            .map_err(|_| "ComfyUI failed to start".to_owned())?;
859        let deadline = tokio::time::Instant::now() + COMFYUI_READY_TIMEOUT;
860        loop {
861            if cancel.is_cancelled() {
862                let _ = child.start_kill();
863                return Err("cancelled".into());
864            }
865            if !matches!(child.try_wait(), Ok(None)) {
866                return Err(
867                    "ComfyUI stopped while starting; open it once from Terminal to see why".into(),
868                );
869            }
870            if self.answers(port).await {
871                break;
872            }
873            if tokio::time::Instant::now() >= deadline {
874                let _ = child.start_kill();
875                return Err("ComfyUI didn't become ready within 5 minutes".into());
876            }
877            tokio::time::sleep(Duration::from_millis(500)).await;
878        }
879        let endpoint = ComfyEndpoint {
880            dir: install.dir,
881            port,
882            owned: true,
883        };
884        *owned = Some(Owned {
885            child,
886            endpoint: endpoint.clone(),
887        });
888        Ok(endpoint)
889    }
890
891    async fn answers(&self, port: u16) -> bool {
892        self.client
893            .get(format!("http://127.0.0.1:{port}/system_stats"))
894            .timeout(Duration::from_secs(2))
895            .send()
896            .await
897            .is_ok_and(|response| response.status().is_success())
898    }
899
900    /// Stops the ComfyUI RigSpark started, if any.
901    pub async fn shutdown(&self) {
902        if let Some(mut owned) = self.comfy.lock().await.take() {
903            let _ = owned.child.start_kill();
904            let _ = tokio::time::timeout(Duration::from_secs(5), owned.child.wait()).await;
905        }
906    }
907}
908
909/// RigSpark's own `mlx_audio.server` under an `engines` folder, once fully installed.
910pub fn managed_mlx_audio_server_in(engines_root: &Path) -> Option<PathBuf> {
911    let dir = engines_root.join(Engine::MlxAudio.name());
912    let path = dir.join(".venv/bin/mlx_audio.server");
913    (dir.join("installed.json").is_file() && path.is_file()).then_some(path)
914}
915
916fn untar(archive: &Path, into: &Path) -> Vec<String> {
917    vec![
918        "-xzf".into(),
919        archive.display().to_string(),
920        "-C".into(),
921        into.display().to_string(),
922    ]
923}
924
925fn venv_args(venv: &Path) -> Vec<String> {
926    vec![
927        "venv".into(),
928        "--python".into(),
929        PYTHON_VERSION.into(),
930        "--clear".into(),
931        venv.display().to_string(),
932    ]
933}
934
935fn pip_args(venv: &Path) -> Vec<String> {
936    vec![
937        "pip".into(),
938        "install".into(),
939        "--python".into(),
940        Engines::venv_python(venv).display().to_string(),
941        "--exclude-newer".into(),
942        PACKAGES_AS_OF.into(),
943    ]
944}
945
946fn free_port() -> Result<u16, String> {
947    std::net::TcpListener::bind((std::net::Ipv4Addr::LOCALHOST, 0))
948        .and_then(|listener| listener.local_addr())
949        .map(|address| address.port())
950        .map_err(|_| "no free local port".into())
951}
952
953#[cfg(test)]
954mod tests {
955    use super::*;
956
957    #[test]
958    fn every_supported_platform_has_a_pinned_installer() {
959        for (os, arch) in [
960            ("macos", "aarch64"),
961            ("macos", "x86_64"),
962            ("linux", "x86_64"),
963            ("linux", "aarch64"),
964        ] {
965            let (pin, folder) = uv_pin(os, arch).unwrap();
966            assert_eq!(pin.sha256.len(), 64);
967            assert!(pin.sha256.bytes().all(|byte| byte.is_ascii_hexdigit()));
968            assert!(pin.url.ends_with(&format!("{folder}.tar.gz")));
969            assert!(pin.url.contains(&format!("/download/{UV_VERSION}/")));
970            allowed_url(pin.url).unwrap();
971        }
972        assert!(uv_pin("windows", "x86_64").is_none());
973        assert!(uv_pin("freebsd", "x86_64").is_none());
974        allowed_url(COMFYUI_SOURCE.url).unwrap();
975        assert!(COMFYUI_SOURCE.url.ends_with(&format!("v{COMFYUI_VERSION}")));
976        assert!(COMFYUI_FOLDER.ends_with(COMFYUI_VERSION));
977    }
978
979    #[test]
980    fn only_https_from_github_hosts_is_downloaded() {
981        assert!(allowed_url("https://github.com/astral-sh/uv/releases/download/x").is_ok());
982        assert!(allowed_url("https://objects.githubusercontent.com/a").is_ok());
983        for refused in [
984            "http://github.com/a",
985            "https://github.com:8443/a",
986            "https://user@github.com/a",
987            "https://evil.example/a",
988            "https://github.com.evil.example/a",
989            "file:///etc/passwd",
990        ] {
991            assert!(allowed_url(refused).is_err(), "{refused}");
992        }
993    }
994
995    #[test]
996    fn digests_fail_closed() {
997        let pinned = "a".repeat(64);
998        assert!(verify_digest(&pinned.to_uppercase(), &pinned).is_ok());
999        assert!(verify_digest(&"b".repeat(64), &pinned).is_err());
1000        assert!(verify_digest("", "").is_err());
1001    }
1002
1003    #[test]
1004    fn packages_resolve_as_of_a_fixed_date_inside_rigsparks_folder() {
1005        let args = pip_args(Path::new("/r/engines/mlx-audio/.venv"));
1006        assert_eq!(args[..2], ["pip".to_owned(), "install".to_owned()]);
1007        let at = args
1008            .iter()
1009            .position(|arg| arg == "--exclude-newer")
1010            .unwrap();
1011        assert_eq!(args[at + 1], PACKAGES_AS_OF);
1012        assert!(args.contains(&"/r/engines/mlx-audio/.venv/bin/python".to_owned()));
1013        assert!(venv_args(Path::new("/v")).contains(&PYTHON_VERSION.to_owned()));
1014    }
1015}