rigspark-runtime 3.1.1

Hardware detection, backend adapters, lifecycle, memory and harness runtime for rigspark.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
use crate::identity::{Listener, NativeProcessProbe, ProcessIdentity, ProcessProbe};
use std::{
    collections::BTreeMap,
    future::Future,
    path::{Path, PathBuf},
    process::Stdio,
    time::Duration,
};
use tokio_util::sync::CancellationToken;

pub struct SpawnSpec {
    pub binary: PathBuf,
    pub args: Vec<String>,
    pub env: BTreeMap<String, String>,
}
#[async_trait::async_trait]
pub trait ChildProcess: Send {
    fn pid(&self) -> u32;
    fn exited(&mut self) -> Result<bool, String>;
    async fn terminate(&mut self) -> Result<(), String>;
    fn detach(&mut self);
}
#[async_trait::async_trait]
pub trait ProcessControl: Send + Sync {
    async fn occupied(&self, endpoint: &str) -> Result<bool, String>;
    async fn spawn(&self, spec: &SpawnSpec) -> Result<Box<dyn ChildProcess>, String>;
    async fn signal(&self, process: &ProcessIdentity, force: bool) -> Result<(), String>;
    async fn alive(&self, pid: u32) -> Result<bool, String>;
}
struct NativeChild {
    child: tokio::process::Child,
    detached: bool,
    pid: u32,
}
#[async_trait::async_trait]
impl ChildProcess for NativeChild {
    fn pid(&self) -> u32 {
        self.pid
    }
    fn exited(&mut self) -> Result<bool, String> {
        self.child
            .try_wait()
            .map(|value| value.is_some())
            .map_err(|_| "cannot observe child exit".into())
    }
    async fn terminate(&mut self) -> Result<(), String> {
        if self.exited()? {
            return Ok(());
        }
        self.child
            .start_kill()
            .map_err(|_| "child termination failed")?;
        tokio::time::timeout(Duration::from_secs(5), self.child.wait())
            .await
            .map_err(|_| "child termination timed out")?
            .map_err(|_| "child wait failed")?;
        Ok(())
    }
    fn detach(&mut self) {
        self.detached = true;
    }
}
impl Drop for NativeChild {
    fn drop(&mut self) {
        if !self.detached {
            let _ = self.child.start_kill();
        }
    }
}
pub struct NativeProcessControl;
#[async_trait::async_trait]
impl ProcessControl for NativeProcessControl {
    async fn occupied(&self, endpoint: &str) -> Result<bool, String> {
        let url = crate::state::loopback(endpoint).map_err(|error| error.to_string())?;
        let host = url
            .host_str()
            .ok_or("missing host")?
            .trim_matches(['[', ']']);
        let port = url.port_or_known_default().ok_or("missing port")?;
        let addresses = if host == "localhost" {
            vec![format!("127.0.0.1:{port}"), format!("[::1]:{port}")]
        } else {
            vec![format!(
                "{}:{port}",
                if host.contains(':') {
                    format!("[{host}]")
                } else {
                    host.into()
                }
            )]
        };
        for address in addresses {
            match tokio::time::timeout(
                Duration::from_secs(2),
                tokio::net::TcpStream::connect(address),
            )
            .await
            {
                Ok(Ok(_)) => return Ok(true),
                Ok(Err(error)) if error.kind() == std::io::ErrorKind::ConnectionRefused => (),
                _ => return Err("cannot establish port availability".into()),
            }
        }
        Ok(false)
    }
    async fn spawn(&self, spec: &SpawnSpec) -> Result<Box<dyn ChildProcess>, String> {
        if !spec.binary.is_absolute() || spec.args.iter().any(|arg| arg.contains('\0')) {
            return Err("invalid spawn specification".into());
        }
        let mut command = tokio::process::Command::new(&spec.binary);
        command
            .args(&spec.args)
            .env_clear()
            .envs(&spec.env)
            .stdin(Stdio::null())
            .stdout(Stdio::null())
            .stderr(Stdio::null());
        let mut child = command.spawn().map_err(|_| "runtime spawn failed")?;
        let Some(pid) = child.id().filter(|pid| *pid > 0) else {
            let _ = child.kill().await;
            return Err("runtime reported invalid PID".into());
        };
        Ok(Box::new(NativeChild {
            child,
            detached: false,
            pid,
        }))
    }
    async fn signal(&self, expected: &ProcessIdentity, force: bool) -> Result<(), String> {
        let observed = NativeProcessProbe
            .process(expected.pid)
            .await
            .map_err(|_| "cannot verify process before signal")?;
        if !same_process(&observed, expected) {
            return Err("process changed before signal".into());
        }
        #[cfg(unix)]
        {
            let pid = i32::try_from(expected.pid)
                .ok()
                .and_then(rustix::process::Pid::from_raw)
                .ok_or("invalid process PID")?;
            rustix::process::kill_process(
                pid,
                if force {
                    rustix::process::Signal::KILL
                } else {
                    rustix::process::Signal::TERM
                },
            )
            .map_err(|_| "signal failed".to_owned())
        }
        #[cfg(windows)]
        {
            let _ = force;
            let system = sysinfo::System::new_all();
            let process = system
                .process(sysinfo::Pid::from_u32(expected.pid))
                .ok_or("process unavailable")?;
            if process.kill() {
                Ok(())
            } else {
                Err("process termination failed".into())
            }
        }
        #[cfg(not(any(unix, windows)))]
        {
            let _ = force;
            Err("unsupported platform".into())
        }
    }
    async fn alive(&self, pid: u32) -> Result<bool, String> {
        #[cfg(unix)]
        {
            let pid = i32::try_from(pid)
                .ok()
                .and_then(rustix::process::Pid::from_raw)
                .ok_or("invalid process PID")?;
            match rustix::process::test_kill_process(pid) {
                Ok(()) => Ok(true),
                Err(rustix::io::Errno::SRCH) => Ok(false),
                Err(rustix::io::Errno::PERM) => Ok(true),
                Err(_) => Err("process existence unavailable".into()),
            }
        }
        #[cfg(not(unix))]
        {
            let system = sysinfo::System::new_all();
            Ok(system.process(sysinfo::Pid::from_u32(pid)).is_some())
        }
    }
}
pub fn same_process(actual: &ProcessIdentity, expected: &ProcessIdentity) -> bool {
    actual.pid == expected.pid
        && actual.executable == expected.executable
        && actual.started == expected.started
}
/// Package-manager directories searched after `PATH` once
/// [`enable_package_manager_fallback`] is called: apps opened from Finder or a launcher
/// inherit only the system `PATH` and would otherwise miss Homebrew runtimes.
#[cfg(target_os = "macos")]
pub const FALLBACK_BINARY_DIRS: &[&str] = &["/opt/homebrew/bin", "/usr/local/bin"];
#[cfg(target_os = "linux")]
pub const FALLBACK_BINARY_DIRS: &[&str] = &["/usr/local/bin", "/home/linuxbrew/.linuxbrew/bin"];
#[cfg(not(any(target_os = "macos", target_os = "linux")))]
pub const FALLBACK_BINARY_DIRS: &[&str] = &[];

static PACKAGE_MANAGER_FALLBACK: std::sync::atomic::AtomicBool =
    std::sync::atomic::AtomicBool::new(false);

/// Lets a GUI-launched app, whose `PATH` is the system default, also find runtimes in
/// [`FALLBACK_BINARY_DIRS`]. Command-line use keeps the caller's `PATH` exactly.
pub fn enable_package_manager_fallback() {
    PACKAGE_MANAGER_FALLBACK.store(true, std::sync::atomic::Ordering::Relaxed);
}

/// Runtimes an app may ship inside its own bundle; nothing else resolves from there.
pub const BUNDLED_RUNTIMES: &[&str] = &["llama-server"];

static BUNDLED_RUNTIME_DIR: std::sync::OnceLock<PathBuf> = std::sync::OnceLock::new();

/// Registers the directory holding an app's bundled [`BUNDLED_RUNTIMES`]. They are
/// searched last, so a runtime the user installed still wins.
pub fn register_bundled_runtime_dir(dir: PathBuf) -> Result<(), String> {
    if !dir.is_absolute() {
        return Err("bundled runtime directory must be absolute".into());
    }
    BUNDLED_RUNTIME_DIR
        .set(dir)
        .map_err(|_| "bundled runtime directory is already registered".into())
}

/// Whether `binary` resolves to the copy shipped in the registered app bundle.
pub fn resolves_to_bundled(binary: &str) -> bool {
    let (Some(dir), Ok(path)) = (BUNDLED_RUNTIME_DIR.get(), resolve_binary(binary)) else {
        return false;
    };
    dir.canonicalize().is_ok_and(|dir| path.starts_with(dir))
}

/// Directories searched after `PATH` for `binary`, in order.
pub fn fallback_directories<'a>(
    binary: &str,
    package_manager: &[&'a Path],
    bundled: Option<&'a Path>,
) -> Vec<&'a Path> {
    let mut dirs = package_manager.to_vec();
    if BUNDLED_RUNTIMES.contains(&binary)
        && let Some(dir) = bundled.filter(|dir| dir.is_absolute())
    {
        dirs.push(dir);
    }
    dirs
}

pub fn resolve_binary(binary: &str) -> Result<PathBuf, String> {
    let package_manager: Vec<&Path> =
        if PACKAGE_MANAGER_FALLBACK.load(std::sync::atomic::Ordering::Relaxed) {
            FALLBACK_BINARY_DIRS.iter().map(Path::new).collect()
        } else {
            Vec::new()
        };
    let fallbacks = fallback_directories(
        binary,
        &package_manager,
        BUNDLED_RUNTIME_DIR.get().map(PathBuf::as_path),
    );
    resolve_binary_in(
        binary,
        &std::env::var_os("PATH").unwrap_or_default(),
        &fallbacks,
    )
}

pub fn resolve_binary_in(
    binary: &str,
    path_var: &std::ffi::OsStr,
    fallbacks: &[&Path],
) -> Result<PathBuf, String> {
    let path = Path::new(binary);
    if path.is_absolute() {
        return path
            .canonicalize()
            .map_err(|_| "runtime executable unavailable".into());
    }

    let fixed = fallbacks.iter().map(|dir| dir.to_path_buf());
    for directory in std::env::split_paths(path_var).chain(fixed) {
        if directory.as_os_str().is_empty() || !directory.is_absolute() {
            continue;
        }
        for name in [binary.to_owned(), format!("{binary}.exe")] {
            let candidate = directory.join(name);
            if candidate.is_file() {
                return candidate
                    .canonicalize()
                    .map_err(|_| "runtime executable cannot be resolved".into());
            }
        }
    }
    Err("runtime executable not found on PATH".into())
}
pub fn bitnet_server_path(value: Option<&std::ffi::OsStr>) -> Result<PathBuf, String> {
    let invalid = || {
        "Set RIGSPARK_BITNET_SERVER to the absolute path of a compiled BitNet llama-server executable (not stock llama.cpp)".to_owned()
    };
    let path = Path::new(value.ok_or_else(invalid)?);
    if !path.is_absolute()
        || path
            .to_str()
            .is_none_or(|text| text.chars().any(char::is_control))
        || !path.is_file()
    {
        return Err(invalid());
    }
    let path = path.canonicalize().map_err(|_| invalid())?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        if path.metadata().map_err(|_| invalid())?.permissions().mode() & 0o111 == 0 {
            return Err(invalid());
        }
    }
    Ok(path)
}

pub fn resolve_bitnet_server() -> Result<PathBuf, String> {
    bitnet_server_path(std::env::var_os("RIGSPARK_BITNET_SERVER").as_deref())
}

pub fn minimal_env() -> BTreeMap<String, String> {
    [
        "PATH",
        "HOME",
        "USER",
        "LOGNAME",
        "LANG",
        "LC_ALL",
        "LC_CTYPE",
        "TMPDIR",
        "TMP",
        "TEMP",
        "SYSTEMROOT",
        "WINDIR",
        "COMSPEC",
        "PATHEXT",
    ]
    .into_iter()
    .filter_map(|key| std::env::var(key).ok().map(|value| (key.into(), value)))
    .collect()
}
pub async fn listener(
    probe: &dyn ProcessProbe,
    endpoint: &str,
    cancel: &CancellationToken,
) -> Result<Listener, String> {
    let url = crate::state::loopback(endpoint).map_err(|error| error.to_string())?;
    let host = url.host_str().ok_or("missing host")?;
    let port = url.port_or_known_default().ok_or("missing port")?;
    tokio::select! {biased;_=cancel.cancelled()=>Err("cancelled".into()),result=tokio::time::timeout(Duration::from_secs(5),probe.listener(port,host))=>{
        let observed=result.map_err(|_|"listener probe timed out")?.map_err(|_|"listener identity unavailable")?;
        crate::identity::choose_listener(std::slice::from_ref(&observed),port,host).map_err(|_|"listener address mismatch".into())
    }}
}
pub async fn wait_owned<F, Fut>(
    child: Box<dyn ChildProcess>,
    endpoint: &str,
    executable: &str,
    probe: &dyn ProcessProbe,
    cancel: &CancellationToken,
    ready: F,
) -> Result<Listener, String>
where
    F: FnOnce() -> Fut,
    Fut: Future<Output = Result<(), String>>,
{
    wait_owned_with_timeout(
        child,
        endpoint,
        executable,
        probe,
        cancel,
        Duration::from_secs(30),
        ready,
    )
    .await
}
pub async fn wait_owned_with_timeout<F, Fut>(
    mut child: Box<dyn ChildProcess>,
    endpoint: &str,
    executable: &str,
    probe: &dyn ProcessProbe,
    cancel: &CancellationToken,
    timeout: Duration,
    ready: F,
) -> Result<Listener, String>
where
    F: FnOnce() -> Fut,
    Fut: Future<Output = Result<(), String>>,
{
    if timeout.is_zero() || timeout > Duration::from_secs(300) {
        child.terminate().await?;
        return Err("invalid readiness deadline".into());
    }
    let operation = async {
        if child.pid() == 0 {
            return Err("invalid child PID".into());
        }
        let readiness = ready();
        tokio::pin!(readiness);
        loop {
            if child.exited()? {
                return Err("runtime exited before readiness".into());
            }
            tokio::select! {result=&mut readiness=>{result?;break;},_=tokio::time::sleep(Duration::from_millis(50))=>()}
        }
        let observed = listener(probe, endpoint, cancel).await?;
        if observed.identity.pid != child.pid() || observed.identity.executable != executable {
            return Err("readiness belongs to another process".into());
        }
        Ok(observed)
    };
    let result = tokio::select! {biased;_=cancel.cancelled()=>Err("cancelled".into()),result=tokio::time::timeout(timeout,operation)=>result.map_err(|_|"runtime readiness timed out".to_owned()).and_then(|result|result)};
    match result {
        Ok(observed) => {
            child.detach();
            Ok(observed)
        }
        Err(error) => {
            child
                .terminate()
                .await
                .map_err(|cleanup| format!("{error}; {cleanup}"))?;
            Err(error)
        }
    }
}
/// Polls after a graceful signal before escalating: model servers can take a few
/// seconds to unload weights (50 ms each, so 3 s).
const GRACEFUL_POLLS: usize = 60;
/// Polls after a forced signal (50 ms each, so 0.5 s).
const FORCED_POLLS: usize = 10;

/// Stop a runtime RigSpark started, identified by `expected`.
///
/// Fails closed: a process is only signalled once its identity matches
/// `expected`. A stale handle is not an error: if nothing listens on the
/// endpoint and the recorded process is gone (or its PID now belongs to another
/// program), the runtime is already stopped.
pub async fn stop_owned(
    endpoint: &str,
    expected: &ProcessIdentity,
    probe: &dyn ProcessProbe,
    control: &dyn ProcessControl,
    cancel: &CancellationToken,
) -> Result<(), String> {
    match listener(probe, endpoint, cancel).await {
        Ok(observed) => {
            if !same_process(&observed.identity, expected) {
                return Err("listener changed; refusing to stop".into());
            }
        }
        Err(error) if cancel.is_cancelled() => return Err(error),
        Err(error) => {
            // Nothing (identifiable) listens. Decide from the recorded process alone.
            if !control.alive(expected.pid).await? {
                return Ok(());
            }
            match probe.process(expected.pid).await {
                Ok(current) if !same_process(&current, expected) => return Ok(()),
                Ok(_) => {} // still our process, just not listening: stop it below
                Err(_) => return Err(error),
            }
        }
    }
    for (force, polls) in [(false, GRACEFUL_POLLS), (true, FORCED_POLLS)] {
        let probed = tokio::select! {biased;_=cancel.cancelled()=>return Err("cancelled".into()),result=tokio::time::timeout(Duration::from_secs(5),probe.process(expected.pid))=>result.map_err(|_|"process probe timed out")?};
        let current = match probed {
            Ok(current) => current,
            Err(_) if !control.alive(expected.pid).await? => return Ok(()),
            Err(_) => {
                return Err(if force {
                    "process identity unavailable after signal".into()
                } else {
                    "process identity unavailable".into()
                });
            }
        };
        if !same_process(&current, expected) {
            if force {
                return Ok(());
            }
            return Err("process changed; refusing to stop".into());
        }
        control.signal(expected, force).await?;
        for _ in 0..polls {
            if !control.alive(expected.pid).await? {
                return Ok(());
            }
            // An exiting process can briefly fail identity probes (zombie, or
            // mid-teardown). That's not a failure: keep waiting. The next pass
            // re-checks identity before any forced signal.
            if let Ok(current) = probe.process(expected.pid).await
                && !same_process(&current, expected)
            {
                return Ok(());
            }
            tokio::select! {biased;_=cancel.cancelled()=>return Err("cancelled".into()),_=tokio::time::sleep(Duration::from_millis(50))=>()}
        }
    }
    Err("runtime remains alive after termination".into())
}