hyprstream_inference/runtime/
resolved_spool.rs1use 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
18fn 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 #[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 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 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 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 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 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
181pub(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 file.set_permissions(std::fs::Permissions::from_mode(0o600))?;
198 }
199 admit_file(&file, bytes.len() as u64)?;
201 copy_verified(&bytes, &mut file)?;
202 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 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 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 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}