qualia_core_db/sensing/acquisition/storage/
custody.rs1use super::*;
6use crate::{
7 q42::{field_envelope as env, field_semantics as sem},
8 sensing::acquisition as a,
9};
10use std::{
11 fs::{self, File, OpenOptions},
12 io::{self, Read, Write},
13 path::{Component, Path, PathBuf},
14 sync::atomic::{AtomicU64, Ordering},
15};
16
17const MAX_CUSTODY_ENTRIES: usize = 65;
18static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0);
19
20#[derive(Clone, Copy, Debug)]
21pub struct PublishOptions {
22 pub max_bytes: usize,
23 pub envelope: env::Limits,
24 pub shared: sem::Limits,
25 pub limits: Limits,
26}
27
28impl Default for PublishOptions {
29 fn default() -> Self {
30 Self {
31 max_bytes: 256 * 1024 * 1024,
32 envelope: env::Limits::default(),
33 shared: sem::Limits::default(),
34 limits: Limits::default(),
35 }
36 }
37}
38
39#[derive(Clone, Debug, PartialEq, Eq)]
40pub struct PublishedArtifact {
41 pub blake3: [u8; 32],
42 pub byte_length: u64,
43 pub family: Family,
44 pub path: PathBuf,
45}
46
47#[derive(Debug)]
48pub enum PublishError {
49 Io(io::Error),
50 Budget,
51 InvalidPath,
52 Conflict,
53 Admission(Error),
54}
55
56impl From<io::Error> for PublishError {
57 fn from(error: io::Error) -> Self {
58 Self::Io(error)
59 }
60}
61
62impl From<Error> for PublishError {
63 fn from(error: Error) -> Self {
64 Self::Admission(error)
65 }
66}
67
68impl std::fmt::Display for PublishError {
69 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
70 match self {
71 Self::Io(e) => write!(f, "acquisition custody IO: {e}"),
72 Self::Budget => f.write_str("acquisition custody byte budget exceeded"),
73 Self::InvalidPath => f.write_str("acquisition custody path redirects or is unsafe"),
74 Self::Conflict => f.write_str("acquisition custody destination bytes mismatch"),
75 Self::Admission(e) => write!(f, "acquisition custody admission failed: {e:?}"),
76 }
77 }
78}
79
80impl std::error::Error for PublishError {}
81
82struct StagingGuard(Option<PathBuf>);
83impl StagingGuard {
84 fn path(&self) -> Result<&Path, PublishError> {
85 self.0.as_deref().ok_or(PublishError::InvalidPath)
86 }
87}
88impl Drop for StagingGuard {
89 fn drop(&mut self) {
90 if let Some(path) = self.0.take() {
91 let _ = fs::remove_file(path);
92 }
93 }
94}
95
96fn validate_root(root: &Path) -> Result<(), PublishError> {
97 if !root.is_absolute() || root.as_os_str().len() > 4096 {
98 return Err(PublishError::InvalidPath);
99 }
100 if root.components().any(|part| matches!(part, Component::ParentDir)) {
101 return Err(PublishError::InvalidPath);
102 }
103 #[cfg(windows)]
104 {
105 use std::path::Prefix;
106 if !matches!(
107 root.components().next(),
108 Some(Component::Prefix(prefix))
109 if matches!(prefix.kind(), Prefix::Disk(_) | Prefix::VerbatimDisk(_))
110 ) {
111 return Err(PublishError::InvalidPath);
112 }
113 }
114 Ok(())
115}
116
117fn check_no_reparse(meta: &fs::Metadata) -> Result<(), PublishError> {
118 if meta.file_type().is_symlink() {
119 return Err(PublishError::InvalidPath);
120 }
121 #[cfg(windows)]
122 {
123 use std::os::windows::fs::MetadataExt;
124 const ATTRIBUTE_REPARSE_POINT: u32 = 0x0000_0400;
125 if meta.file_attributes() & ATTRIBUTE_REPARSE_POINT != 0 {
126 return Err(PublishError::InvalidPath);
127 }
128 }
129 Ok(())
130}
131
132fn child_dir(parent: &Path, name: &str) -> Result<PathBuf, PublishError> {
133 let path = parent.join(name);
134 match fs::create_dir(&path) {
135 Ok(()) => {}
136 Err(e) if e.kind() == io::ErrorKind::AlreadyExists => {}
137 Err(e) => return Err(e.into()),
138 }
139 let meta = fs::symlink_metadata(&path)?;
140 check_no_reparse(&meta)?;
141 if !meta.is_dir() {
142 return Err(PublishError::InvalidPath);
143 }
144 let canonical = path.canonicalize()?;
145 if canonical.parent() != Some(parent) {
146 return Err(PublishError::InvalidPath);
147 }
148 Ok(canonical)
149}
150
151fn storage_dir(root: &Path, create: bool) -> Result<PathBuf, PublishError> {
152 validate_root(root)?;
153 if create {
154 fs::create_dir_all(root)?;
155 }
156 let canonical_root = root.canonicalize()?;
157 if create {
158 return child_dir(&child_dir(&canonical_root, "sensing")?, "acquisition");
159 }
160 let sensing = canonical_root.join("sensing");
161 let sm = fs::symlink_metadata(&sensing)?;
162 check_no_reparse(&sm)?;
163 if !sm.is_dir() {
164 return Err(PublishError::InvalidPath);
165 }
166 let acq = sensing.canonicalize()?.join("acquisition");
167 let am = fs::symlink_metadata(&acq)?;
168 check_no_reparse(&am)?;
169 if !am.is_dir() {
170 return Err(PublishError::InvalidPath);
171 }
172 let canonical = acq.canonicalize()?;
173 if canonical.parent() != sensing.canonicalize().ok().as_deref() {
174 return Err(PublishError::InvalidPath);
175 }
176 Ok(canonical)
177}
178
179fn open_regular(path: &Path) -> Result<File, PublishError> {
180 let pre = fs::symlink_metadata(path)?;
181 check_no_reparse(&pre)?;
182 if !pre.is_file() {
183 return Err(PublishError::InvalidPath);
184 }
185 let mut options = OpenOptions::new();
186 options.read(true);
187 #[cfg(windows)]
188 {
189 use std::os::windows::fs::OpenOptionsExt;
190 const OPEN_REPARSE_POINT: u32 = 0x0020_0000;
191 options.custom_flags(OPEN_REPARSE_POINT);
192 }
193 let file = options.open(path)?;
194 let meta = file.metadata()?;
195 check_no_reparse(&meta)?;
196 if !meta.is_file() {
197 return Err(PublishError::InvalidPath);
198 }
199 Ok(file)
200}
201
202fn verify_exact(path: &Path, bytes: &[u8]) -> Result<(), PublishError> {
203 let mut file = open_regular(path)?;
204 if file.metadata()?.len() != bytes.len() as u64 {
205 return Err(PublishError::Conflict);
206 }
207 let mut scratch = [0u8; 8192];
208 for expected in bytes.chunks(scratch.len()) {
209 file.read_exact(&mut scratch[..expected.len()])?;
210 if &scratch[..expected.len()] != expected {
211 return Err(PublishError::Conflict);
212 }
213 }
214 if file.read(&mut scratch[..1])? != 0 {
215 return Err(PublishError::Conflict);
216 }
217 Ok(())
218}
219
220fn create_staging(dir: &Path, bytes: &[u8]) -> Result<StagingGuard, PublishError> {
221 let pid = std::process::id();
222 for _ in 0..64 {
223 let seq = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
224 let candidate = dir.join(format!(".tmp-acq-{pid}-{seq}.part"));
225 let mut options = OpenOptions::new();
226 options.write(true).create_new(true);
227 #[cfg(unix)]
228 {
229 use std::os::unix::fs::OpenOptionsExt;
230 options.mode(0o600);
231 }
232 match options.open(&candidate) {
233 Ok(mut file) => {
234 let guard = StagingGuard(Some(candidate));
235 file.write_all(bytes)?;
236 file.sync_all()?;
237 return Ok(guard);
238 }
239 Err(e) if e.kind() == io::ErrorKind::AlreadyExists => continue,
240 Err(e) => return Err(e.into()),
241 }
242 }
243 Err(PublishError::Io(io::Error::new(
244 io::ErrorKind::AlreadyExists,
245 "exhausted staging filenames",
246 )))
247}
248
249fn extension(family: Family) -> &'static str {
250 match family {
251 Family::QacV1Candidate => "qac",
252 Family::EmfV4Candidate => "emf",
253 }
254}
255
256pub fn publish_container(
259 root: &Path,
260 family: Family,
261 selected: u32,
262 bytes: &[u8],
263 scratch: &mut sem::Scratch<'_>,
264 options: PublishOptions,
265) -> Result<PublishedArtifact, PublishError> {
266 validate_root(root)?;
267 if bytes.len() > options.max_bytes {
268 return Err(PublishError::Budget);
269 }
270 let structural = env::StructuralView::open(bytes, family, options.envelope)
271 .map_err(Error::from)?;
272 if structural.entry_count() as usize > MAX_CUSTODY_ENTRIES {
273 return Err(Error::Scratch.into());
274 }
275 let mut originals = [None; MAX_CUSTODY_ENTRIES];
276 let _doc = admit(
277 &structural,
278 selected,
279 &mut originals,
280 scratch,
281 options.shared,
282 options.limits,
283 )?;
284 let digest = *blake3::hash(bytes).as_bytes();
285 let dir = storage_dir(root, true)?;
286 let mut hex = String::with_capacity(64);
287 for byte in digest {
288 use std::fmt::Write as _;
289 let _ = write!(&mut hex, "{byte:02x}");
290 }
291 let dest = dir.join(format!("{hex}.{}", extension(family)));
292 let guard = create_staging(&dir, bytes)?;
293 match fs::hard_link(guard.path()?, &dest) {
294 Ok(()) => {}
295 Err(e) if e.kind() == io::ErrorKind::AlreadyExists => verify_exact(&dest, bytes)?,
296 Err(e) => return Err(e.into()),
297 }
298 Ok(PublishedArtifact {
299 blake3: digest,
300 byte_length: bytes.len() as u64,
301 family,
302 path: dest,
303 })
304}
305
306pub fn read_container<'a, 's>(
308 root: &Path,
309 family: Family,
310 digest: &[u8; 32],
311 selected: u32,
312 buffer: &'a mut [u8],
313 originals: &'s mut [Option<a::Original<'a>>],
314 scratch: &mut sem::Scratch<'_>,
315 options: PublishOptions,
316) -> Result<(usize, PublishedArtifact, Document<'a, 's>), PublishError> {
317 let dir = storage_dir(root, false)?;
318 let mut hex = String::with_capacity(64);
319 for byte in *digest {
320 use std::fmt::Write as _;
321 let _ = write!(&mut hex, "{byte:02x}");
322 }
323 let path = dir.join(format!("{hex}.{}", extension(family)));
324 let mut file = open_regular(&path)?;
325 let file_len = file.metadata()?.len();
326 let len = usize::try_from(file_len).map_err(|_| PublishError::Budget)?;
327 if len > options.max_bytes || len > buffer.len() {
328 return Err(PublishError::Budget);
329 }
330 file.read_exact(&mut buffer[..len])?;
331 let mut extra = [0u8; 1];
332 if file.read(&mut extra)? != 0 {
333 return Err(PublishError::Conflict);
334 }
335 let bytes = &buffer[..len];
336 let actual_digest = *blake3::hash(bytes).as_bytes();
337 if actual_digest != *digest {
338 return Err(PublishError::Conflict);
339 }
340 let structural = env::StructuralView::open(bytes, family, options.envelope)
341 .map_err(Error::from)?;
342 let doc = admit(
343 &structural,
344 selected,
345 originals,
346 scratch,
347 options.shared,
348 options.limits,
349 )?;
350 let artifact = PublishedArtifact {
351 blake3: actual_digest,
352 byte_length: len as u64,
353 family,
354 path,
355 };
356 Ok((len, artifact, doc))
357}
358
359#[cfg(test)]
360#[path = "custody_tests.rs"]
361mod tests;