bv_runtime/
runtime.rs

1use std::collections::HashMap;
2use std::fmt;
3use std::path::PathBuf;
4use std::str::FromStr;
5use std::time::Duration;
6
7use bv_core::error::Result;
8use bv_core::manifest::GpuSpec;
9
10// OciRef
11
12#[derive(Debug, Clone)]
13pub struct OciRef {
14    pub registry: String,
15    pub repository: String,
16    pub tag: Option<String>,
17    pub digest: Option<String>,
18}
19
20impl OciRef {
21    pub fn parse(s: &str) -> std::result::Result<Self, String> {
22        s.parse()
23    }
24
25    /// Return the string Docker expects for `docker pull` / `docker run`.
26    /// For docker.io images the registry prefix is stripped so that Docker Hub
27    /// resolves references correctly across all Docker versions.
28    pub fn docker_arg(&self) -> String {
29        if self.registry == "docker.io" {
30            let mut s = self.repository.clone();
31            if let Some(tag) = &self.tag {
32                s.push(':');
33                s.push_str(tag);
34            }
35            if let Some(digest) = &self.digest {
36                s.push('@');
37                s.push_str(digest);
38            }
39            s
40        } else {
41            self.to_string()
42        }
43    }
44}
45
46impl fmt::Display for OciRef {
47    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
48        write!(f, "{}/{}", self.registry, self.repository)?;
49        if let Some(tag) = &self.tag {
50            write!(f, ":{tag}")?;
51        }
52        if let Some(digest) = &self.digest {
53            write!(f, "@{digest}")?;
54        }
55        Ok(())
56    }
57}
58
59impl FromStr for OciRef {
60    type Err = String;
61
62    fn from_str(raw: &str) -> std::result::Result<Self, Self::Err> {
63        let s = raw
64            .strip_prefix("docker://")
65            .or_else(|| raw.strip_prefix("oci://"))
66            .unwrap_or(raw);
67
68        let (image_part, digest) = if let Some((img, d)) = s.split_once('@') {
69            (img, Some(d.to_string()))
70        } else {
71            (s, None)
72        };
73
74        // Tag detection rules:
75        // - If there is no '/', the input is a single image name with an
76        //   optional tag (e.g. `foo:1.0`).
77        // - Otherwise, only the segment after the last '/' may carry a tag.
78        //   This avoids treating a registry port (`localhost:5000/foo`) as a tag.
79        let (name_part, tag) = if !image_part.contains('/') {
80            if let Some(pos) = image_part.rfind(':') {
81                (&image_part[..pos], Some(image_part[pos + 1..].to_string()))
82            } else {
83                (image_part, None)
84            }
85        } else {
86            let last_slash = image_part.rfind('/').unwrap();
87            let last_segment = &image_part[last_slash + 1..];
88            if let Some(rel_colon) = last_segment.find(':') {
89                let split = last_slash + 1 + rel_colon;
90                (
91                    &image_part[..split],
92                    Some(image_part[split + 1..].to_string()),
93                )
94            } else {
95                (image_part, None)
96            }
97        };
98
99        let (registry, repository) = split_registry(name_part);
100
101        Ok(OciRef {
102            registry,
103            repository,
104            tag,
105            digest,
106        })
107    }
108}
109
110fn split_registry(name: &str) -> (String, String) {
111    if let Some(slash_pos) = name.find('/') {
112        let potential_registry = &name[..slash_pos];
113        if potential_registry.contains('.')
114            || potential_registry.contains(':')
115            || potential_registry == "localhost"
116        {
117            return (
118                potential_registry.to_string(),
119                name[slash_pos + 1..].to_string(),
120            );
121        }
122    }
123    ("docker.io".to_string(), name.to_string())
124}
125
126// Supporting types
127
128#[derive(Debug, Clone)]
129pub struct ImageDigest(pub String);
130
131impl fmt::Display for ImageDigest {
132    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
133        f.write_str(&self.0)
134    }
135}
136
137#[derive(Debug, Clone)]
138pub struct ImageMetadata {
139    pub digest: ImageDigest,
140    pub size_bytes: Option<u64>,
141    pub labels: HashMap<String, String>,
142}
143
144#[derive(Debug, Clone)]
145pub struct RuntimeInfo {
146    pub name: String,
147    pub version: String,
148    pub extra: HashMap<String, String>,
149}
150
151#[derive(Debug, Clone)]
152pub struct Mount {
153    pub host_path: PathBuf,
154    pub container_path: PathBuf,
155    pub read_only: bool,
156}
157
158#[derive(Debug, Clone, Default)]
159pub struct GpuProfile {
160    pub spec: Option<GpuSpec>,
161}
162
163#[derive(Debug, Clone)]
164pub struct RunSpec {
165    /// OCI reference of the image to run (may carry a pinned digest).
166    pub image: OciRef,
167    pub command: Vec<String>,
168    pub env: HashMap<String, String>,
169    pub mounts: Vec<Mount>,
170    pub gpu: GpuProfile,
171    pub working_dir: Option<PathBuf>,
172    /// When true, capture stdout+stderr into `RunOutcome` instead of inheriting
173    /// to the host. Used by `bv conformance` to inspect probe output without
174    /// flooding the user's terminal.
175    #[doc(hidden)]
176    pub capture_output: bool,
177}
178
179#[derive(Debug, Default)]
180pub struct RunOutcome {
181    pub exit_code: i32,
182    pub duration: Duration,
183    /// Captured stdout when `RunSpec.capture_output` is true; empty otherwise.
184    pub stdout: Vec<u8>,
185    /// Captured stderr when `RunSpec.capture_output` is true; empty otherwise.
186    pub stderr: Vec<u8>,
187}
188
189// ProgressReporter
190
191pub trait ProgressReporter: Send + Sync {
192    fn update(&self, message: &str, current: Option<u64>, total: Option<u64>);
193    fn finish(&self, message: &str);
194
195    /// Hide our own spinner/bars while a child process draws to the terminal.
196    /// Implementations should clear their lines until the returned guard is dropped.
197    /// The default is a no-op for reporters that don't draw to a TTY.
198    fn pause(&self) -> Box<dyn PauseGuard + '_> {
199        Box::new(NoopPauseGuard)
200    }
201}
202
203pub trait PauseGuard {}
204
205pub struct NoopPauseGuard;
206impl PauseGuard for NoopPauseGuard {}
207
208pub struct NoopProgress;
209
210impl ProgressReporter for NoopProgress {
211    fn update(&self, _: &str, _: Option<u64>, _: Option<u64>) {}
212    fn finish(&self, _: &str) {}
213}
214
215// ContainerRuntime trait
216
217pub trait ContainerRuntime {
218    fn name(&self) -> &str;
219    fn health_check(&self) -> Result<RuntimeInfo>;
220    fn pull(&self, image: &OciRef, progress: &dyn ProgressReporter) -> Result<ImageDigest>;
221    fn run(&self, spec: &RunSpec) -> Result<RunOutcome>;
222    fn inspect(&self, digest: &ImageDigest) -> Result<ImageMetadata>;
223    /// Check whether `image_ref@digest` is already in the local Docker cache.
224    fn is_locally_available(&self, _image_ref: &str, digest: &str) -> bool {
225        self.inspect(&ImageDigest(digest.to_string())).is_ok()
226    }
227    fn gpu_args(&self, profile: &GpuProfile) -> Vec<String>;
228    fn mount_args(&self, mounts: &[Mount]) -> Vec<String>;
229}
230
231// Tests
232
233#[cfg(test)]
234mod tests {
235    use super::*;
236
237    #[test]
238    fn parse_simple_image() {
239        let r: OciRef = "ubuntu:22.04".parse().unwrap();
240        assert_eq!(r.registry, "docker.io");
241        assert_eq!(r.repository, "ubuntu");
242        assert_eq!(r.tag.as_deref(), Some("22.04"));
243        assert!(r.digest.is_none());
244    }
245
246    #[test]
247    fn parse_with_registry() {
248        let r: OciRef = "ghcr.io/biocontainers/bwa:0.7.17".parse().unwrap();
249        assert_eq!(r.registry, "ghcr.io");
250        assert_eq!(r.repository, "biocontainers/bwa");
251        assert_eq!(r.tag.as_deref(), Some("0.7.17"));
252    }
253
254    #[test]
255    fn parse_with_digest() {
256        let r: OciRef = "ubuntu@sha256:abc123".parse().unwrap();
257        assert_eq!(r.digest.as_deref(), Some("sha256:abc123"));
258        assert!(r.tag.is_none());
259    }
260
261    #[test]
262    fn parse_docker_scheme() {
263        let r: OciRef = "docker://biocontainers/bwa:0.7.17".parse().unwrap();
264        assert_eq!(r.registry, "docker.io");
265        assert_eq!(r.repository, "biocontainers/bwa");
266    }
267
268    #[test]
269    fn docker_arg_strips_docker_io() {
270        let r: OciRef = "ncbi/blast:2.14.0".parse().unwrap();
271        assert_eq!(r.docker_arg(), "ncbi/blast:2.14.0");
272
273        let mut r2: OciRef = "ncbi/blast:2.14.0".parse().unwrap();
274        r2.tag = None;
275        r2.digest = Some("sha256:abc123".into());
276        assert_eq!(r2.docker_arg(), "ncbi/blast@sha256:abc123");
277    }
278
279    #[test]
280    fn docker_arg_keeps_external_registry() {
281        let r: OciRef = "quay.io/biocontainers/blast:2.15.0".parse().unwrap();
282        assert_eq!(r.docker_arg(), "quay.io/biocontainers/blast:2.15.0");
283    }
284
285    #[test]
286    fn parse_localhost_port_registry_with_repo() {
287        let r: OciRef = "localhost:5000/foo/bar".parse().unwrap();
288        assert_eq!(r.registry, "localhost:5000");
289        assert_eq!(r.repository, "foo/bar");
290        assert!(r.tag.is_none());
291        assert!(r.digest.is_none());
292    }
293
294    #[test]
295    fn parse_localhost_port_registry_with_repo_and_tag() {
296        let r: OciRef = "localhost:5000/foo/bar:1.0".parse().unwrap();
297        assert_eq!(r.registry, "localhost:5000");
298        assert_eq!(r.repository, "foo/bar");
299        assert_eq!(r.tag.as_deref(), Some("1.0"));
300    }
301
302    #[test]
303    fn parse_single_name() {
304        let r: OciRef = "foo".parse().unwrap();
305        assert_eq!(r.registry, "docker.io");
306        assert_eq!(r.repository, "foo");
307        assert!(r.tag.is_none());
308    }
309
310    #[test]
311    fn parse_single_name_with_tag() {
312        let r: OciRef = "foo:1.0".parse().unwrap();
313        assert_eq!(r.registry, "docker.io");
314        assert_eq!(r.repository, "foo");
315        assert_eq!(r.tag.as_deref(), Some("1.0"));
316    }
317
318    #[test]
319    fn parse_two_segments_no_registry() {
320        let r: OciRef = "foo/bar".parse().unwrap();
321        assert_eq!(r.registry, "docker.io");
322        assert_eq!(r.repository, "foo/bar");
323        assert!(r.tag.is_none());
324    }
325
326    #[test]
327    fn parse_quay_with_tag() {
328        let r: OciRef = "quay.io/biocontainers/blast:2.14.0".parse().unwrap();
329        assert_eq!(r.registry, "quay.io");
330        assert_eq!(r.repository, "biocontainers/blast");
331        assert_eq!(r.tag.as_deref(), Some("2.14.0"));
332    }
333
334    #[test]
335    fn parse_ghcr_with_digest() {
336        let r: OciRef = "ghcr.io/owner/repo@sha256:abc".parse().unwrap();
337        assert_eq!(r.registry, "ghcr.io");
338        assert_eq!(r.repository, "owner/repo");
339        assert!(r.tag.is_none());
340        assert_eq!(r.digest.as_deref(), Some("sha256:abc"));
341    }
342}
bv_runtime/runtime.rs

bv_runtime/
runtime.rs
