ic_build/artifacts/staging/mod.rs
1//! Invocation-owned artifact staging without cache publication or reuse.
2//!
3//! Callers own the parent directory, recipes and publication boundary. This
4//! module allocates only its own child and removes it after the last owner is
5//! dropped. Explicit retention transfers cleanup to the caller.
6//! It never prunes existing artifacts or publishes a product release.
7
8use std::{
9 fmt, fs, io,
10 path::{Path, PathBuf},
11 sync::atomic::{AtomicU64, Ordering},
12};
13
14use ic_host_artifacts::artifact::{ArtifactError, CopyError, copy_reader};
15use ic_host_fs::{
16 durable::{NamedWriteError, PublicationMode, WriteOptions, write_with},
17 owned_directory::OwnedDirectory,
18 read::open_regular_file,
19};
20
21mod produce;
22pub use produce::produce_and_retain_artifact;
23
24const STAGE_ATTEMPTS: usize = 64;
25static STAGE_SEQUENCE: AtomicU64 = AtomicU64::new(0);
26
27/// Temporary artifact directory retained until its owner is closed or dropped.
28///
29/// The caller keeps custody of the parent and allocated child against unrelated
30/// writers. Drop performs best-effort cleanup of this invocation-owned child;
31/// use [`Self::close`] when cleanup failures must reach the caller. No shared
32/// cache entry is created, reused or removed.
33#[derive(Debug)]
34pub struct ArtifactStagingDirectory {
35 directory: OwnedDirectory,
36}
37
38impl ArtifactStagingDirectory {
39 /// Allocate a distinct staging child beneath an existing caller-owned directory.
40 ///
41 /// The parent is not created. Existing children are never reused or removed.
42 ///
43 /// # Errors
44 /// Returns the filesystem error for a missing or unwritable parent, or
45 /// `AlreadyExists` when every allocation attempt collides.
46 pub fn new(parent: &Path) -> io::Result<Self> {
47 for _ in 0..STAGE_ATTEMPTS {
48 let sequence = STAGE_SEQUENCE.fetch_add(1, Ordering::Relaxed);
49 let root = parent.join(format!(
50 ".ic-build-artifact-stage-{}-{sequence}",
51 std::process::id()
52 ));
53 match fs::create_dir(&root) {
54 Ok(()) => {
55 return Ok(Self {
56 directory: OwnedDirectory::new(root),
57 });
58 }
59 Err(source) if source.kind() == io::ErrorKind::AlreadyExists => {}
60 Err(source) => return Err(source),
61 }
62 }
63 Err(io::Error::new(
64 io::ErrorKind::AlreadyExists,
65 format!(
66 "failed to allocate artifact staging beneath {}",
67 parent.display()
68 ),
69 ))
70 }
71
72 /// Borrow the owned staging directory through artifact production and consumption.
73 #[must_use]
74 pub fn path(&self) -> &Path {
75 self.directory.path()
76 }
77
78 /// Remove this owned staging child, reporting cleanup failure without a hidden retry.
79 ///
80 /// On failure, the caller owns recovery of the remaining staging child.
81 /// It does not remove the parent or any other artifact directory.
82 ///
83 /// # Errors
84 /// Returns the filesystem error if removing the owned child fails.
85 pub fn close(self) -> io::Result<()> {
86 self.directory.cleanup()
87 }
88}
89
90/// Owned copy of one completed producer output, independent of later source replacement.
91///
92/// Keep this record alive through every use of [`Self::path`]. The copy is
93/// temporary rather than a reusable cache entry; ordinary Drop removes it.
94/// [`Self::retain`] explicitly transfers cleanup to the caller.
95#[derive(Debug)]
96pub struct CapturedArtifact {
97 staging: ArtifactStagingDirectory,
98 path: PathBuf,
99}
100
101/// Finalization failed after capture custody was transferred to the caller.
102///
103/// The exact bytes remain at [`Self::retained_path`]. If rename succeeded but
104/// cleanup failed, that path is the destination; otherwise it is the staging file.
105#[derive(Debug)]
106pub struct CaptureRetentionError {
107 /// Filesystem operation that failed.
108 pub source: io::Error,
109 /// Actual retained file path after the failed operation.
110 pub retained_path: PathBuf,
111 /// Owned staging child still requiring caller disposition.
112 pub staging_directory: PathBuf,
113}
114
115impl fmt::Display for CaptureRetentionError {
116 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
117 write!(
118 formatter,
119 "capture retained at {} (staging {}): {}",
120 self.retained_path.display(),
121 self.staging_directory.display(),
122 self.source
123 )
124 }
125}
126
127impl std::error::Error for CaptureRetentionError {
128 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
129 Some(&self.source)
130 }
131}
132
133impl CapturedArtifact {
134 /// Capture an output synchronously before another producer can overwrite it.
135 ///
136 /// The caller keeps the source stable during capture and selects the maximum
137 /// readable byte count. Read/publication failures retain their typed causes
138 /// inside the returned I/O error. Existing public destinations are untouched.
139 /// Bytes stream through bounded scratch rather than a complete in-memory copy.
140 ///
141 /// # Errors
142 /// Returns the source read/byte-limit, staging allocation or durable-write
143 /// error. An unsuccessful capture performs best-effort staging cleanup.
144 pub fn capture(source: &Path, parent: &Path, maximum_bytes: usize) -> io::Result<Self> {
145 let source = open_regular_file(source).map_err(io::Error::from)?;
146 let limit = maximum_bytes as u64;
147 if source.metadata()?.len() > limit {
148 return Err(ArtifactError::LimitExceeded { limit }.into());
149 }
150 let staging = ArtifactStagingDirectory::new(parent)?;
151 let path = staging.path().join("input.artifact");
152 write_with(
153 &path,
154 WriteOptions {
155 mode: PublicationMode::Replace,
156 permissions: 0o666,
157 },
158 |file| copy_reader(source, file, limit).map(|_| ()),
159 )
160 .map_err(|error| match error {
161 NamedWriteError::Producer {
162 source: CopyError::Input(source),
163 cleanup_error: None,
164 } => io::Error::from(source),
165 other => io::Error::other(other),
166 })?;
167 Ok(Self { staging, path })
168 }
169
170 /// Borrow the exact captured bytes while this record owns their lifetime.
171 #[must_use]
172 pub fn path(&self) -> &Path {
173 &self.path
174 }
175
176 /// Transfer the captured file and its staging child to caller-owned retention.
177 ///
178 /// Unlike close or Drop, this keeps the exact captured bytes after this owner
179 /// is consumed. The caller owns later cleanup of the returned path's parent.
180 /// Keep custody of those paths; this grants no cache or release admission.
181 #[must_use]
182 pub fn retain(mut self) -> PathBuf {
183 self.staging.directory.disarm();
184 self.path
185 }
186
187 /// Retain the exact capture at a caller-selected destination.
188 ///
189 /// Uses [`fs::rename`] semantics, including replacement of an existing
190 /// destination when supported. The caller owns destination admission and
191 /// later custody. Only the empty owned staging child is removed on success.
192 ///
193 /// # Errors
194 /// Rename or cleanup failure reports the actual retained bytes and staging
195 /// child. Neither failure deletes evidence or silently retries publication.
196 pub fn retain_to(self, destination: &Path) -> Result<PathBuf, CaptureRetentionError> {
197 let staging = self.staging.path().to_owned();
198 let retained = self.retain();
199 fs::rename(&retained, destination).map_err(|source| CaptureRetentionError {
200 source,
201 retained_path: retained.clone(),
202 staging_directory: staging.clone(),
203 })?;
204 fs::remove_dir(&staging).map_err(|source| CaptureRetentionError {
205 source,
206 retained_path: destination.to_owned(),
207 staging_directory: staging,
208 })?;
209 Ok(destination.to_owned())
210 }
211
212 /// Remove the captured output and its owned staging child, reporting cleanup failure.
213 ///
214 /// # Errors
215 /// Returns the filesystem error if removing the owned child fails.
216 pub fn close(self) -> io::Result<()> {
217 self.staging.close()
218 }
219}
220
221#[cfg(test)]
222mod tests;