Skip to main content

hyprstream_inference/runtime/
resolved_spool.rs

1//! Per-load disk backing for resolved channel-FP8 pointer shards.
2//!
3//! A resolver may still allocate one shard. Spill it before requesting the
4//! next shard, so whole-checkpoint preflight retains only file descriptors,
5//! rather than every resolved heap buffer plus materialized tensors. This is
6//! not a global object cache: anonymous files die with their retained handles.
7
8use anyhow::{Context, Result};
9use sha2::{Digest, Sha256};
10use std::fs::File;
11use std::io::{Read, Seek, Write};
12use std::path::{Path, PathBuf};
13
14#[cfg(target_os = "linux")]
15const RESERVE_BYTES: u64 = 512 << 20;
16const IO_BYTES: usize = 64 << 10;
17
18/// Only trusted process XDG/home convention selects the cache; neither model
19/// paths nor RPC inputs select a spool location. Do not use /tmp (often tmpfs).
20fn cache_parent() -> Result<PathBuf> {
21    let base = std::env::var_os("XDG_CACHE_HOME")
22        .map(PathBuf::from)
23        .filter(|path| path.is_absolute())
24        .or_else(|| {
25            std::env::var_os("HOME")
26                .map(PathBuf::from)
27                .filter(|path| path.is_absolute())
28                .map(|home| home.join(".cache"))
29        })
30        .context("resolved FP8 spool requires absolute XDG cache or HOME")?;
31    // DirBuilder mode applies only to directories newly created here. Never
32    // chmod a shared or pre-existing cache ancestor.
33    #[cfg(unix)]
34    {
35        use std::os::unix::fs::DirBuilderExt as _;
36        std::fs::DirBuilder::new()
37            .recursive(true)
38            .mode(0o700)
39            .create(&base)?;
40    }
41    #[cfg(not(unix))]
42    std::fs::create_dir_all(&base)?;
43    let base = base.canonicalize()?;
44    verify_owned_directory(&base, false)?;
45    let app = base.join("hyprstream");
46    let private = app.join("fp8-resolved-shards");
47    for path in [&app, &private] {
48        #[cfg(unix)]
49        {
50            use std::os::unix::fs::DirBuilderExt as _;
51            match std::fs::DirBuilder::new().mode(0o700).create(path) {
52                Ok(()) => {}
53                Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {}
54                Err(error) => return Err(error.into()),
55            }
56        }
57        #[cfg(not(unix))]
58        std::fs::create_dir_all(path)?;
59        let metadata = std::fs::symlink_metadata(path)?;
60        anyhow::ensure!(
61            metadata.is_dir() && !metadata.file_type().is_symlink(),
62            "resolved FP8 cache child must be a real directory"
63        );
64        verify_owned_directory(path, path == &private)?;
65    }
66    verify_private_parent(&private)?;
67    Ok(private)
68}
69
70#[cfg(unix)]
71fn verify_owned_directory(parent: &Path, private: bool) -> Result<()> {
72    use std::os::unix::fs::MetadataExt as _;
73    let metadata = std::fs::symlink_metadata(parent)?;
74    // SAFETY: geteuid has no pointer arguments or preconditions.
75    let uid = unsafe { libc::geteuid() };
76    anyhow::ensure!(
77        metadata.is_dir()
78            && !metadata.file_type().is_symlink()
79            && metadata.uid() == uid
80            && if private {
81                metadata.mode() & 0o777 == 0o700
82            } else {
83                metadata.mode() & 0o022 == 0
84            },
85        "resolved FP8 spool parent must be owned, real, private0700"
86    );
87    Ok(())
88}
89#[cfg(not(unix))]
90fn verify_owned_directory(_parent: &Path, _private: bool) -> Result<()> {
91    anyhow::bail!("private resolved FP8 disk spooling is unavailable on this platform")
92}
93
94fn verify_private_parent(parent: &Path) -> Result<()> {
95    verify_owned_directory(parent, true)
96}
97
98#[cfg(target_os = "linux")]
99fn required_capacity(bytes: u64) -> Result<u64> {
100    bytes
101        .checked_add(RESERVE_BYTES)
102        .context("resolved FP8 spool capacity overflow")
103}
104
105#[cfg(target_os = "linux")]
106fn admit_file(file: &File, bytes: u64) -> Result<()> {
107    use std::os::fd::AsRawFd as _;
108    use std::os::unix::fs::MetadataExt as _;
109    let metadata = file.metadata()?;
110    anyhow::ensure!(
111        metadata.is_file() && metadata.nlink() == 0 && metadata.mode() & 0o777 == 0o600,
112        "resolved FP8 spool must be an anonymous0600 regular file"
113    );
114    let mut fs = std::mem::MaybeUninit::<libc::statfs>::uninit();
115    // SAFETY: the owned file FD is live and fs is writable statfs storage.
116    anyhow::ensure!(
117        unsafe { libc::fstatfs(file.as_raw_fd(), fs.as_mut_ptr()) } == 0,
118        "resolved FP8 spool filesystem check failed: {}",
119        std::io::Error::last_os_error()
120    );
121    // SAFETY: successful fstatfs initialized fs.
122    let fs = unsafe { fs.assume_init() };
123    anyhow::ensure!(
124        fs.f_type != 0x0102_1994 && fs.f_type != 0x8584_58f6,
125        "resolved FP8 spool refuses memory-backed filesystem"
126    );
127    let mut capacity = std::mem::MaybeUninit::<libc::statvfs>::uninit();
128    // SAFETY: live owned FD and writable statvfs storage.
129    anyhow::ensure!(
130        unsafe { libc::fstatvfs(file.as_raw_fd(), capacity.as_mut_ptr()) } == 0,
131        "resolved FP8 spool capacity check failed: {}",
132        std::io::Error::last_os_error()
133    );
134    // SAFETY: successful fstatvfs initialized capacity.
135    let capacity = unsafe { capacity.assume_init() };
136    let available = u128::from(capacity.f_bavail) * u128::from(capacity.f_frsize);
137    anyhow::ensure!(
138        available >= u128::from(required_capacity(bytes)?),
139        "insufficient disk for resolved FP8 spool plus512MiB reserve"
140    );
141    Ok(())
142}
143#[cfg(not(target_os = "linux"))]
144fn admit_file(_file: &File, _bytes: u64) -> Result<()> {
145    anyhow::bail!("resolved FP8 disk filesystem admission requires Linux")
146}
147
148fn copy_verified(bytes: &[u8], file: &mut File) -> Result<()> {
149    let expected: [u8; 32] = Sha256::digest(bytes).into();
150    for chunk in bytes.chunks(IO_BYTES) {
151        file.write_all(chunk)?;
152    }
153    file.flush()?;
154    anyhow::ensure!(
155        file.metadata()?.len() == bytes.len() as u64,
156        "resolved FP8 spool length differs"
157    );
158    file.rewind()?;
159    let mut hash = Sha256::new();
160    let mut buffer = [0; IO_BYTES];
161    let mut count = 0_u64;
162    loop {
163        let n = file.read(&mut buffer)?;
164        if n == 0 {
165            break;
166        }
167        count = count
168            .checked_add(n as u64)
169            .context("resolved FP8 readback length overflow")?;
170        hash.update(&buffer[..n]);
171    }
172    let actual: [u8; 32] = hash.finalize().into();
173    anyhow::ensure!(
174        count == bytes.len() as u64 && actual == expected,
175        "resolved FP8 spool readback bytes differ"
176    );
177    file.rewind()?;
178    Ok(())
179}
180
181/// Called in spawn_blocking with the ONE current resolver allocation moved
182/// into it. Cancellation cannot abandon a named payload: this function owns
183/// the anonymous FD and Vec until completion, and the caller awaits it before
184/// starting any next resolution. Do not clone the Vec or re-resolve the shard.
185pub(super) fn spool(bytes: Vec<u8>) -> Result<File> {
186    spool_in(bytes, &cache_parent()?)
187}
188
189pub(super) fn spool_in(bytes: Vec<u8>, parent: &Path) -> Result<File> {
190    verify_private_parent(parent)?;
191    let mut file = tempfile::tempfile_in(parent)?;
192    #[cfg(unix)]
193    {
194        use std::os::unix::fs::PermissionsExt as _;
195        // tempfile's Linux O_TMPFILE path inherits OpenOptions' default mode;
196        // constrain this NEW anonymous empty inode before any payload write.
197        file.set_permissions(std::fs::Permissions::from_mode(0o600))?;
198    }
199    // FD-backed filesystem/capacity admission occurs BEFORE any payload write.
200    admit_file(&file, bytes.len() as u64)?;
201    copy_verified(&bytes, &mut file)?;
202    // Explicitly release anonymous heap storage before the next resolver can
203    // run, even while the returned same-byte File remains retained.
204    drop(bytes);
205    Ok(file)
206}
207
208#[cfg(all(test, target_os = "linux"))]
209mod tests {
210    use super::*;
211    use std::os::unix::fs::PermissionsExt as _;
212    fn private_dir(parent: impl AsRef<Path>) -> Result<tempfile::TempDir> {
213        Ok(tempfile::Builder::new()
214            .permissions(std::fs::Permissions::from_mode(0o700))
215            .tempdir_in(parent)?)
216    }
217    #[test]
218    fn resolved_spool_roundtrip_is_anonymous_exact_and_released() -> Result<()> {
219        use std::os::unix::fs::MetadataExt as _;
220        let dir = private_dir(std::env::current_dir()?)?;
221        let bytes: Vec<_> = (0..(3 * IO_BYTES + 7)).map(|i| (i % 251) as u8).collect();
222        let expected = Sha256::digest(&bytes);
223        let mut file = spool_in(bytes, dir.path())?;
224        let fd = {
225            use std::os::fd::AsRawFd as _;
226            file.as_raw_fd()
227        };
228        let inode = file.metadata()?.ino();
229        assert_eq!(file.metadata()?.nlink(), 0);
230        assert_eq!(file.metadata()?.mode() & 0o777, 0o600);
231        let mut actual = Vec::new();
232        file.read_to_end(&mut actual)?;
233        assert_eq!(Sha256::digest(&actual), expected);
234        assert_eq!(std::fs::read_dir(dir.path())?.count(), 0);
235        drop(file);
236        // No named cache payload survives success or FD release.
237        assert_eq!(std::fs::read_dir(dir.path())?.count(), 0);
238        assert!(std::fs::metadata(format!("/proc/self/fd/{fd}"))
239            .map(|m| m.ino() != inode)
240            .unwrap_or(true));
241        Ok(())
242    }
243    #[test]
244    fn resolved_spool_private_parent_and_memory_filesystem_fail_closed() -> Result<()> {
245        use std::os::unix::fs::{symlink, PermissionsExt as _};
246        let dir = private_dir(std::env::current_dir()?)?;
247        std::fs::set_permissions(dir.path(), std::fs::Permissions::from_mode(0o755))?;
248        assert!(spool_in(vec![1, 2, 3], dir.path()).is_err());
249        std::fs::set_permissions(dir.path(), std::fs::Permissions::from_mode(0o700))?;
250        let alias = dir.path().join("alias");
251        symlink(dir.path(), &alias)?;
252        assert!(spool_in(vec![1, 2, 3], &alias).is_err());
253        std::fs::remove_file(alias)?;
254        // /dev/shm is the actual Linux tmpfs; failure must happen beforewrite.
255        let memory = private_dir("/dev/shm")?;
256        let error = spool_in(vec![1, 2, 3], memory.path())
257            .err()
258            .context("accepted tmpfs")?;
259        assert!(error.to_string().contains("memory-backed"));
260        assert_eq!(std::fs::read_dir(memory.path())?.count(), 0);
261        assert!(required_capacity(u64::MAX).is_err());
262        Ok(())
263    }
264    #[test]
265    fn resolved_spool_insufficient_capacity_fails_before_any_write() -> Result<()> {
266        let dir = private_dir(std::env::current_dir()?)?;
267        let file = tempfile::tempfile_in(dir.path())?;
268        file.set_permissions(std::fs::Permissions::from_mode(0o600))?;
269        // A tiny FD with an impossible requested capacity exercises the real
270        // fstatvfs refusal without allocating or writing giant payloads.
271        let error = admit_file(&file, u64::MAX - RESERVE_BYTES)
272            .err()
273            .context("accepted impossible disk request")?;
274        assert!(error.to_string().contains("insufficient disk"));
275        assert_eq!(file.metadata()?.len(), 0);
276        assert_eq!(std::fs::read_dir(dir.path())?.count(), 0);
277        Ok(())
278    }
279
280    #[test]
281    fn resolved_spool_write_failure_leaves_no_named_payload() -> Result<()> {
282        let dir = private_dir(std::env::current_dir()?)?;
283        let mut file = File::options().write(true).open("/dev/full")?;
284        assert!(copy_verified(&[1, 2, 3], &mut file).is_err());
285        assert_eq!(std::fs::read_dir(dir.path())?.count(), 0);
286        Ok(())
287    }
288}