Skip to main content

runnerd_core/
docker.rs

1//! Runner containers through the Docker Engine API: the connection, container, volume and image requests, and the
2//! `DockerApi` trait the engine and the caches call. It decides nothing about scheduling, and a JIT config only
3//! ever reaches a container as a root-only file, never the create request or a log line.
4
5use std::collections::{BTreeMap, BTreeSet, HashMap};
6use std::fmt;
7use std::time::{Duration, Instant};
8
9use bollard::exec::{CreateExecOptions, StartExecResults};
10use std::pin::Pin;
11
12use bollard::models::{
13    ChangeType, ContainerConfig, ContainerCreateBody, CreateImageInfo, HostConfig, Mount,
14    NetworkCreateRequest, SystemInfo, VolumeCreateRequest,
15};
16use bollard::query_parameters::{
17    AttachContainerOptionsBuilder, CommitContainerOptionsBuilder, CreateContainerOptionsBuilder,
18    CreateImageOptionsBuilder, DataUsageOptionsBuilder, InspectContainerOptionsBuilder,
19    ListContainersOptionsBuilder, ListImagesOptionsBuilder, LogsOptionsBuilder,
20    RemoveContainerOptionsBuilder, RemoveImageOptionsBuilder, RemoveVolumeOptionsBuilder,
21    ResizeContainerTTYOptionsBuilder, UploadToContainerOptionsBuilder, WaitContainerOptionsBuilder,
22};
23use futures_util::stream::BoxStream;
24use futures_util::{StreamExt, TryStreamExt};
25use tracing::info;
26
27use crate::config::ByteSize;
28use crate::isolation::Isolation;
29
30pub use bollard::errors::Error;
31
32/// One runner container: a profile's image stage with the profile's limits.
33#[derive(Debug, Clone)]
34pub struct RunnerSpec {
35    /// The container's name; for a runner, also the runner's.
36    pub name: String,
37    /// The image, such as `runnerd-runner:base`.
38    pub image: String,
39    /// The profile, put on the `runnerd.profile` label.
40    pub profile: String,
41    /// The systemd slice the container is placed in.
42    pub slice: String,
43    /// CPUs the container may use.
44    pub cpus: u32,
45    /// Memory the container may use, swap included.
46    pub memory: ByteSize,
47    /// `NAME=value` environment variables.
48    pub env: Vec<String>,
49    /// Volumes to mount.
50    pub mounts: Vec<Mount>,
51    /// The network the container joins; `None` is Docker's default bridge.
52    pub network: Option<String>,
53    /// Labels on top of `runnerd.profile` and `runnerd.isolation`.
54    pub labels: BTreeMap<String, String>,
55    /// Replaces the image's entrypoint; `None` runs the runner.
56    pub entrypoint: Option<Vec<String>>,
57    /// The runner's just-in-time config, which the entrypoint reads from `JIT_CONFIG_PATH`.
58    pub jit_config: Option<JitConfig>,
59}
60
61/// Where `start` puts the just-in-time config in the container: a root-only file, never the create request,
62/// which Docker stores and clients may log.
63pub const JIT_CONFIG_PATH: &str = "/run/runnerd/jitconfig";
64
65/// A runner's just-in-time config from GitHub: credentials, never printed.
66#[derive(Clone)]
67pub struct JitConfig(pub String);
68
69impl fmt::Debug for JitConfig {
70    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
71        f.write_str("JitConfig(<redacted>)")
72    }
73}
74
75/// What `inspect` reports about a runner container.
76#[derive(Debug, Clone, PartialEq, Eq)]
77pub struct RunnerState {
78    /// Whether the container runs.
79    pub running: bool,
80    /// Its exit code, once it stopped.
81    pub exit_code: Option<i64>,
82    /// Whether the kernel killed a process in it for memory, as Docker saw.
83    pub oom_killed: bool,
84    /// True under `unsafe-dind`: a job in the container can take over the host.
85    pub privileged: bool,
86    /// The runtime Docker runs it with, such as `sysbox-runc`.
87    pub runtime: Option<String>,
88    /// Its main process on the host, while it runs.
89    pub pid: Option<u32>,
90    /// Its address on its first network.
91    pub address: Option<String>,
92    /// When it started, in milliseconds since the epoch.
93    pub started_at: Option<u64>,
94    /// Its memory cap in bytes; `None` when it has none.
95    pub memory: Option<u64>,
96    /// Its CPU limit in millicores; `None` when it has none.
97    pub cpus: Option<u64>,
98}
99
100/// What a command run in a container prints on stdout, as it prints it.
101pub type Output = BoxStream<'static, Result<Vec<u8>, Error>>;
102
103/// An image `images` found.
104#[derive(Debug, Clone, PartialEq, Eq)]
105pub struct Image {
106    /// Its first tag, such as `runnerd-record:42`; its ID when it has none.
107    pub reference: String,
108    /// Its labels.
109    pub labels: HashMap<String, String>,
110    /// The disk it takes beyond its parent image: what removing it frees.
111    pub bytes: u64,
112}
113
114/// An image `tagged_images` found.
115#[derive(Debug, Clone, PartialEq, Eq)]
116pub struct TaggedImage {
117    /// Its ID, such as `sha256:224e…`.
118    pub id: String,
119    /// Its tags, such as `ghcr.io/ayagmar/runnerd-runner:node-0.0.25`.
120    pub tags: Vec<String>,
121    /// The registry digests it was pulled by, such as `ghcr.io/ayagmar/runnerd-runner@sha256:9e79…`.
122    pub digests: Vec<String>,
123}
124
125/// A container's terminal, attached once it was created and before it started, so none of its output is missed.
126pub struct Tty {
127    /// The container's ID.
128    pub container: String,
129    /// What the terminal shows, as it shows it; it ends when the container's process exits.
130    pub output: BoxStream<'static, Result<Vec<u8>, Error>>,
131    /// What is typed into it.
132    pub input: Pin<Box<dyn tokio::io::AsyncWrite + Send>>,
133}
134
135impl fmt::Debug for Tty {
136    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
137        f.debug_struct("Tty")
138            .field("container", &self.container)
139            .finish_non_exhaustive()
140    }
141}
142
143/// A terminal's size.
144#[derive(Debug, Clone, Copy, PartialEq, Eq)]
145pub struct TtySize {
146    /// Columns.
147    pub cols: u16,
148    /// Rows.
149    pub rows: u16,
150}
151
152/// The CPU shares of a runner's container or a record's shell with `cpus` CPUs: 1024 a CPU, within the 2 to 262144
153/// Docker takes, which it writes as the container's `cpu.weight`. They sit in the slice beside each other, so when the
154/// slice's CPUs are all in use they share them in proportion to their `cpus`, not evenly; a container with work still
155/// gets at most its `cpus` (`nano_cpus`). The mirror keeps Docker's default weight, which every job's pulls go
156/// through, and programs outside the slice share the host's CPUs with the slice by its own weight (ADR 0079).
157pub fn cpu_shares(cpus: u32) -> i64 {
158    (i64::from(cpus) * 1024).clamp(2, 262_144)
159}
160
161/// The create-container request for a runner container under an isolation backend.
162pub fn create_body(spec: &RunnerSpec, isolation: &dyn Isolation) -> ContainerCreateBody {
163    // Clamped to 8 EiB, the most Docker takes.
164    let memory = i64::try_from(spec.memory.0).unwrap_or(i64::MAX);
165    let mut host_config = HostConfig {
166        cgroup_parent: Some(spec.slice.clone()),
167        memory: Some(memory),
168        // Swap equal to memory: the container gets no swap on top of its memory.
169        memory_swap: Some(memory),
170        nano_cpus: Some(i64::from(spec.cpus) * 1_000_000_000),
171        cpu_shares: Some(cpu_shares(spec.cpus)),
172        init: Some(true),
173        mounts: Some(spec.mounts.clone()),
174        network_mode: spec.network.clone(),
175        ..Default::default()
176    };
177    isolation.configure(&mut host_config);
178    let mut labels: HashMap<String, String> = spec.labels.clone().into_iter().collect();
179    labels.insert("runnerd.profile".to_owned(), spec.profile.clone());
180    labels.insert("runnerd.isolation".to_owned(), isolation.name().to_owned());
181    ContainerCreateBody {
182        image: Some(spec.image.clone()),
183        env: Some(spec.env.clone()),
184        entrypoint: spec.entrypoint.clone(),
185        labels: Some(labels),
186        host_config: Some(host_config),
187        ..Default::default()
188    }
189}
190
191/// A container `list` found.
192#[derive(Debug, Clone, PartialEq, Eq)]
193pub struct Container {
194    /// The Docker container ID.
195    pub id: String,
196    /// Without Docker's leading `/`.
197    pub name: String,
198    /// Whether it runs.
199    pub running: bool,
200    /// Its labels.
201    pub labels: HashMap<String, String>,
202}
203
204/// A runner start that failed, with the container it may have left: Docker may have made, or even started, it before
205/// the request failed, as when its answer is lost.
206#[derive(Debug)]
207pub struct StartError {
208    /// The container the start left, by ID, or by name when Docker could not say whether one exists; `None` when
209    /// none does. It may run.
210    pub container: Option<String>,
211    /// Why the start failed.
212    pub error: Error,
213}
214
215impl fmt::Display for StartError {
216    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
217        self.error.fmt(f)
218    }
219}
220
221impl std::error::Error for StartError {
222    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
223        Some(&self.error)
224    }
225}
226
227/// For callers that go on whether or not a container was left.
228impl From<StartError> for Error {
229    fn from(failed: StartError) -> Error {
230        failed.error
231    }
232}
233
234/// Whether Docker answered a request with a refusal, so it did nothing: a 4xx answer. Any other error may come after
235/// Docker carried the request out.
236fn refused(error: &Error) -> bool {
237    matches!(
238        error,
239        Error::DockerResponseServerError {
240            status_code: 400..=499,
241            ..
242        }
243    )
244}
245
246/// Whether a Docker error says the container, volume or image does not exist.
247pub fn is_not_found(error: &Error) -> bool {
248    matches!(
249        error,
250        Error::DockerResponseServerError {
251            status_code: 404,
252            ..
253        }
254    )
255}
256
257/// The Docker Engine calls the scheduler and the caches make. `Docker` is the real one; the engine's tests use a
258/// fake.
259pub trait DockerApi: Send + Sync {
260    /// Creates and starts a runner container; returns its ID. A start that fails removes what it made, and says
261    /// which container is left when it cannot.
262    fn start(
263        &self,
264        spec: &RunnerSpec,
265        isolation: &dyn Isolation,
266    ) -> impl Future<Output = Result<String, StartError>> + Send;
267    /// A container's state and isolation.
268    fn inspect(&self, container: &str) -> impl Future<Output = Result<RunnerState, Error>> + Send;
269    /// Removes a runner container, stopping it first if it runs.
270    fn remove(&self, container: &str) -> impl Future<Output = Result<(), Error>> + Send;
271    /// Creates and starts a container that is not a runner, such as the mirror; returns its ID.
272    fn run(
273        &self,
274        name: &str,
275        body: ContainerCreateBody,
276    ) -> impl Future<Output = Result<String, Error>> + Send;
277    /// Every container, running or not, that has the label.
278    fn list(&self, label: &str) -> impl Future<Output = Result<Vec<Container>, Error>> + Send;
279    /// Waits for a container to exit; returns its exit code.
280    fn wait(&self, container: &str) -> impl Future<Output = Result<i64, Error>> + Send;
281    /// A container's output so far, stdout and stderr interleaved.
282    fn logs(&self, container: &str) -> impl Future<Output = Result<String, Error>> + Send;
283    /// A container's output since `since` (seconds since the epoch), each line prefixed with Docker's RFC 3339
284    /// timestamp and a space.
285    fn logs_since(
286        &self,
287        container: &str,
288        since: u64,
289    ) -> impl Future<Output = Result<String, Error>> + Send;
290    /// Runs a command as root in a running container; its stdout streams until it exits or the container stops.
291    /// Its stderr is dropped.
292    fn exec(
293        &self,
294        container: &str,
295        command: Vec<String>,
296    ) -> impl Future<Output = Result<Output, Error>> + Send;
297    /// Whether Docker has an image.
298    fn image_present(&self, image: &str) -> impl Future<Output = Result<bool, Error>> + Send;
299    /// Pulls an image, logging its progress every few seconds.
300    fn pull(&self, image: &str) -> impl Future<Output = Result<(), Error>> + Send;
301    /// Creates a bridge network unless it exists.
302    fn ensure_network(&self, name: &str) -> impl Future<Output = Result<(), Error>> + Send;
303    /// Creates a volume unless it exists.
304    fn ensure_volume(&self, name: &str) -> impl Future<Output = Result<(), Error>> + Send;
305    /// Removes a volume; a volume that does not exist is not an error.
306    fn remove_volume(&self, name: &str) -> impl Future<Output = Result<(), Error>> + Send;
307    /// The disk size of every volume Docker knows, by name. Slow: Docker measures each volume.
308    fn volume_sizes(&self) -> impl Future<Output = Result<BTreeMap<String, u64>, Error>> + Send;
309    /// The paths a container's own layer added or changed, not those it deleted.
310    fn changes(&self, container: &str) -> impl Future<Output = Result<Vec<String>, Error>> + Send;
311    /// The bytes a container's own layer holds.
312    fn written(&self, container: &str) -> impl Future<Output = Result<u64, Error>> + Send;
313    /// Commits a stopped container's own layer as the image `reference` (`repository:tag`) with `labels`; returns
314    /// the disk the image takes beyond its parent.
315    fn commit(
316        &self,
317        container: &str,
318        reference: &str,
319        labels: BTreeMap<String, String>,
320    ) -> impl Future<Output = Result<u64, Error>> + Send;
321    /// Every image with the label.
322    fn images(&self, label: &str) -> impl Future<Output = Result<Vec<Image>, Error>> + Send;
323    /// The ID of the image a reference (tag, digest or ID) names; `None` when Docker does not have it.
324    fn image_id(
325        &self,
326        reference: &str,
327    ) -> impl Future<Output = Result<Option<String>, Error>> + Send;
328    /// Every image Docker has a tag for.
329    fn tagged_images(&self) -> impl Future<Output = Result<Vec<TaggedImage>, Error>> + Send;
330    /// The image ID of every container, running or stopped.
331    fn container_images(&self) -> impl Future<Output = Result<BTreeSet<String>, Error>> + Send;
332    /// Removes an image and the layers only it used; one that does not exist is not an error.
333    fn remove_image(&self, reference: &str) -> impl Future<Output = Result<(), Error>> + Send;
334    /// The free disk where Docker keeps its images and containers.
335    fn free_space(&self) -> impl Future<Output = Result<u64, Error>> + Send;
336    /// Creates a container with a terminal of `size`, attaches to it and starts it. The container's stdin closes
337    /// when `Tty::input` is dropped.
338    fn shell(
339        &self,
340        name: &str,
341        body: ContainerCreateBody,
342        size: TtySize,
343    ) -> impl Future<Output = Result<Tty, Error>> + Send;
344}
345
346/// The local Docker Engine.
347#[derive(Debug)]
348pub struct Docker {
349    api: bollard::Docker,
350}
351
352impl Docker {
353    /// Removes the container a failed start `made`, if any; the start's `error` is the one worth reporting. The
354    /// container stays in the answer unless its removal is confirmed.
355    async fn clean_up(&self, made: Option<String>, error: Error) -> StartError {
356        let container = match made {
357            Some(container) => match self.remove(&container).await {
358                Err(failed) if !is_not_found(&failed) => Some(container),
359                _ => None,
360            },
361            None => None,
362        };
363        StartError { container, error }
364    }
365
366    /// Connects to the Docker Engine at `DOCKER_HOST`, or its local socket. Only `unix://` hosts are supported.
367    pub fn connect() -> Result<Docker, Error> {
368        connect_to(std::env::var("DOCKER_HOST").ok().as_deref())
369    }
370
371    /// The Engine's system information.
372    pub async fn info(&self) -> Result<SystemInfo, Error> {
373        self.api.info().await
374    }
375
376    /// An image's labels; `None` when Docker does not have it.
377    pub async fn image_labels(
378        &self,
379        image: &str,
380    ) -> Result<Option<HashMap<String, String>>, Error> {
381        match self.api.inspect_image(image).await {
382            Ok(inspect) => Ok(Some(
383                inspect
384                    .config
385                    .and_then(|config| config.labels)
386                    .unwrap_or_default(),
387            )),
388            Err(error) if is_not_found(&error) => Ok(None),
389            Err(error) => Err(error),
390        }
391    }
392
393    /// Asks the image's registry for its manifest, without pulling it, and returns the platforms it is built for,
394    /// such as `linux/amd64`. An error means `pull` could not get it.
395    pub async fn registry_platforms(&self, image: &str) -> Result<Vec<String>, Error> {
396        let inspect = self.api.inspect_registry_image(image, None).await?;
397        Ok(inspect
398            .platforms
399            .into_iter()
400            .filter_map(|platform| Some(format!("{}/{}", platform.os?, platform.architecture?)))
401            // Attestation manifests in an index carry the platform unknown/unknown.
402            .filter(|platform| platform != "unknown/unknown")
403            .collect())
404    }
405}
406
407impl DockerApi for Docker {
408    async fn start(
409        &self,
410        spec: &RunnerSpec,
411        isolation: &dyn Isolation,
412    ) -> Result<String, StartError> {
413        let options = CreateContainerOptionsBuilder::new()
414            .name(&spec.name)
415            .build();
416        let id = match self
417            .api
418            .create_container(Some(options), create_body(spec, isolation))
419            .await
420        {
421            Ok(created) => created.id,
422            Err(error) if refused(&error) => {
423                return Err(StartError {
424                    container: None,
425                    error,
426                });
427            }
428            // Docker may have made it and lost the answer: its name, unique to this start, finds it.
429            Err(error) => {
430                let made = match self.api.inspect_container(&spec.name, None).await {
431                    Ok(found) => Some(found.id.unwrap_or_else(|| spec.name.clone())),
432                    Err(missing) if is_not_found(&missing) => None,
433                    Err(_) => Some(spec.name.clone()),
434                };
435                return Err(self.clean_up(made, error).await);
436            }
437        };
438        let started = async {
439            if let Some(jit_config) = &spec.jit_config {
440                let options = UploadToContainerOptionsBuilder::new().path("/").build();
441                let tar = jit_config_tar(jit_config)?;
442                // As a stream: bollard traces a full body's bytes, but a stream only as "(stream)".
443                let tar = futures_util::stream::once(std::future::ready(tar.into()));
444                self.api
445                    .upload_to_container(&id, Some(options), bollard::body_stream(tar))
446                    .await?;
447            }
448            self.api.start_container(&id, None).await
449        };
450        if let Err(error) = started.await {
451            return Err(self.clean_up(Some(id), error).await);
452        }
453        Ok(id)
454    }
455
456    async fn inspect(&self, container: &str) -> Result<RunnerState, Error> {
457        let response = self.api.inspect_container(container, None).await?;
458        let state = response.state.unwrap_or_default();
459        let host_config = response.host_config.unwrap_or_default();
460        let address = response
461            .network_settings
462            .and_then(|settings| settings.networks)
463            .and_then(|networks| {
464                networks
465                    .into_values()
466                    .find_map(|network| network.ip_address.filter(|address| !address.is_empty()))
467            });
468        Ok(RunnerState {
469            running: state.running.unwrap_or(false),
470            exit_code: state.exit_code,
471            oom_killed: state.oom_killed.unwrap_or(false),
472            privileged: host_config.privileged.unwrap_or(false),
473            runtime: host_config.runtime,
474            pid: state
475                .pid
476                .and_then(|pid| u32::try_from(pid).ok())
477                .filter(|pid| *pid > 0),
478            address,
479            started_at: state.started_at.as_deref().and_then(crate::time::parse_ms),
480            memory: host_config
481                .memory
482                .and_then(|memory| u64::try_from(memory).ok())
483                .filter(|memory| *memory > 0),
484            cpus: host_config
485                .nano_cpus
486                .and_then(|nano| u64::try_from(nano / 1_000_000).ok())
487                .filter(|cpus| *cpus > 0),
488        })
489    }
490
491    async fn remove(&self, container: &str) -> Result<(), Error> {
492        // With its anonymous volumes, such as a shell's /state.
493        let options = RemoveContainerOptionsBuilder::new()
494            .force(true)
495            .v(true)
496            .build();
497        self.api.remove_container(container, Some(options)).await
498    }
499
500    async fn run(&self, name: &str, body: ContainerCreateBody) -> Result<String, Error> {
501        let options = CreateContainerOptionsBuilder::new().name(name).build();
502        let id = self.api.create_container(Some(options), body).await?.id;
503        if let Err(error) = self.api.start_container(&id, None).await {
504            let _ = self.remove(&id).await;
505            return Err(error);
506        }
507        Ok(id)
508    }
509
510    async fn list(&self, label: &str) -> Result<Vec<Container>, Error> {
511        let options = ListContainersOptionsBuilder::new()
512            .all(true)
513            .filters(&HashMap::from([("label", vec![label])]))
514            .build();
515        let containers = self.api.list_containers(Some(options)).await?;
516        Ok(containers
517            .into_iter()
518            .map(|container| Container {
519                id: container.id.unwrap_or_default(),
520                name: container
521                    .names
522                    .and_then(|names| names.into_iter().next())
523                    .unwrap_or_default()
524                    .trim_start_matches('/')
525                    .to_owned(),
526                running: container.state
527                    == Some(bollard::models::ContainerSummaryStateEnum::RUNNING),
528                labels: container.labels.unwrap_or_default(),
529            })
530            .collect())
531    }
532
533    async fn wait(&self, container: &str) -> Result<i64, Error> {
534        let options = WaitContainerOptionsBuilder::new()
535            .condition("not-running")
536            .build();
537        let mut responses = self.api.wait_container(container, Some(options));
538        match responses.next().await {
539            Some(Ok(response)) => Ok(response.status_code),
540            // Bollard reports a non-zero exit as an error.
541            Some(Err(Error::DockerContainerWaitError { code, .. })) => Ok(code),
542            Some(Err(error)) => Err(error),
543            None => Ok(0),
544        }
545    }
546
547    async fn logs(&self, container: &str) -> Result<String, Error> {
548        let options = LogsOptionsBuilder::new().stdout(true).stderr(true).build();
549        let chunks: Vec<_> = self
550            .api
551            .logs(container, Some(options))
552            .try_collect()
553            .await?;
554        Ok(chunks.iter().map(ToString::to_string).collect())
555    }
556
557    async fn logs_since(&self, container: &str, since: u64) -> Result<String, Error> {
558        let options = LogsOptionsBuilder::new()
559            .stdout(true)
560            .stderr(true)
561            .timestamps(true)
562            .since(i32::try_from(since).unwrap_or(i32::MAX))
563            .build();
564        let chunks: Vec<_> = self
565            .api
566            .logs(container, Some(options))
567            .try_collect()
568            .await?;
569        Ok(chunks.iter().map(ToString::to_string).collect())
570    }
571
572    async fn exec(&self, container: &str, command: Vec<String>) -> Result<Output, Error> {
573        let options = CreateExecOptions {
574            cmd: Some(command),
575            user: Some("root".to_owned()),
576            attach_stdout: Some(true),
577            attach_stderr: Some(true),
578            ..Default::default()
579        };
580        let exec = self.api.create_exec(container, options).await?;
581        match self.api.start_exec(&exec.id, None).await? {
582            StartExecResults::Attached { output, .. } => Ok(output
583                .try_filter_map(|output| {
584                    std::future::ready(Ok(match output {
585                        bollard::container::LogOutput::StdOut { message } => Some(message.to_vec()),
586                        _ => None,
587                    }))
588                })
589                .boxed()),
590            StartExecResults::Detached => Ok(futures_util::stream::empty().boxed()),
591        }
592    }
593
594    async fn image_present(&self, image: &str) -> Result<bool, Error> {
595        Ok(self.image_labels(image).await?.is_some())
596    }
597
598    async fn pull(&self, image: &str) -> Result<(), Error> {
599        let options = CreateImageOptionsBuilder::new().from_image(image).build();
600        let mut stream = self.api.create_image(Some(options), None, None);
601        let mut progress = PullProgress::default();
602        let mut logged = Instant::now();
603        info!("pulling {image}");
604        while let Some(update) = stream.try_next().await? {
605            progress.update(&update);
606            if logged.elapsed() >= PULL_LOG_INTERVAL {
607                logged = Instant::now();
608                info!("pulling {image}: {progress}");
609            }
610        }
611        info!("pulled {image}");
612        Ok(())
613    }
614
615    async fn ensure_network(&self, name: &str) -> Result<(), Error> {
616        match self.api.inspect_network(name, None).await {
617            Err(error) if is_not_found(&error) => {
618                let request = NetworkCreateRequest {
619                    name: name.to_owned(),
620                    driver: Some("bridge".to_owned()),
621                    ..Default::default()
622                };
623                self.api.create_network(request).await.map(|_| ())
624            }
625            other => other.map(|_| ()),
626        }
627    }
628
629    async fn ensure_volume(&self, name: &str) -> Result<(), Error> {
630        // Creating a volume that exists is a no-op in Docker.
631        let request = VolumeCreateRequest {
632            name: Some(name.to_owned()),
633            ..Default::default()
634        };
635        self.api.create_volume(request).await.map(|_| ())
636    }
637
638    async fn remove_volume(&self, name: &str) -> Result<(), Error> {
639        let options = RemoveVolumeOptionsBuilder::new().build();
640        match self.api.remove_volume(name, Some(options)).await {
641            Err(error) if is_not_found(&error) => Ok(()),
642            other => other,
643        }
644    }
645
646    async fn volume_sizes(&self) -> Result<BTreeMap<String, u64>, Error> {
647        // Without a type filter: bollard cannot encode one in the query.
648        let options = DataUsageOptionsBuilder::new().verbose(true).build();
649        let usage = self.api.df(Some(options)).await?;
650        // API 1.53 leaves the items untyped; they are volumes as `GET /volumes` describes them.
651        Ok(usage
652            .volume_usage
653            .and_then(|volumes| volumes.items)
654            .unwrap_or_default()
655            .into_iter()
656            .filter_map(|volume| {
657                let name = volume.get("Name")?.as_str()?.to_owned();
658                let size = volume.get("UsageData")?.get("Size")?.as_u64()?;
659                Some((name, size))
660            })
661            .collect())
662    }
663
664    async fn changes(&self, container: &str) -> Result<Vec<String>, Error> {
665        Ok(self
666            .api
667            .container_changes(container)
668            .await?
669            .unwrap_or_default()
670            .into_iter()
671            .filter(|change| change.kind != ChangeType::_2)
672            .map(|change| change.path)
673            .collect())
674    }
675
676    async fn written(&self, container: &str) -> Result<u64, Error> {
677        let options = InspectContainerOptionsBuilder::new().size(true).build();
678        let response = self.api.inspect_container(container, Some(options)).await?;
679        Ok(response
680            .size_rw
681            .and_then(|bytes| u64::try_from(bytes).ok())
682            .unwrap_or(0))
683    }
684
685    async fn commit(
686        &self,
687        container: &str,
688        reference: &str,
689        labels: BTreeMap<String, String>,
690    ) -> Result<u64, Error> {
691        let (repository, tag) = reference.rsplit_once(':').unwrap_or((reference, "latest"));
692        let options = CommitContainerOptionsBuilder::new()
693            .container(container)
694            .repo(repository)
695            .tag(tag)
696            .pause(false)
697            .build();
698        let config = ContainerConfig {
699            labels: Some(labels.into_iter().collect()),
700            ..Default::default()
701        };
702        // The image the container runs is the record's parent.
703        let parent = match self.api.inspect_container(container, None).await?.image {
704            Some(parent) => self.api.inspect_image(&parent).await?.size.unwrap_or(0),
705            None => 0,
706        };
707        let id = self.api.commit_container(options, config).await?.id;
708        let size = self.api.inspect_image(&id).await?.size.unwrap_or(0);
709        Ok(u64::try_from(size - parent).unwrap_or(0))
710    }
711
712    async fn images(&self, label: &str) -> Result<Vec<Image>, Error> {
713        let options = ListImagesOptionsBuilder::new()
714            .filters(&HashMap::from([("label", vec![label])]))
715            .build();
716        let images = self.api.list_images(Some(options)).await?;
717        let mut parents: HashMap<String, i64> = HashMap::new();
718        let mut found = Vec::new();
719        for image in images {
720            let parent = if image.parent_id.is_empty() {
721                0
722            } else if let Some(size) = parents.get(&image.parent_id) {
723                *size
724            } else {
725                let size = self
726                    .api
727                    .inspect_image(&image.parent_id)
728                    .await
729                    .ok()
730                    .and_then(|parent| parent.size)
731                    .unwrap_or(0);
732                parents.insert(image.parent_id.clone(), size);
733                size
734            };
735            found.push(Image {
736                reference: image.repo_tags.into_iter().next().unwrap_or(image.id),
737                labels: image.labels,
738                bytes: u64::try_from(image.size - parent).unwrap_or(0),
739            });
740        }
741        Ok(found)
742    }
743
744    async fn image_id(&self, reference: &str) -> Result<Option<String>, Error> {
745        match self.api.inspect_image(reference).await {
746            Ok(inspect) => Ok(inspect.id),
747            Err(error) if is_not_found(&error) => Ok(None),
748            Err(error) => Err(error),
749        }
750    }
751
752    async fn tagged_images(&self) -> Result<Vec<TaggedImage>, Error> {
753        let images = self
754            .api
755            .list_images(Some(ListImagesOptionsBuilder::new().build()))
756            .await?;
757        Ok(images
758            .into_iter()
759            .map(|image| TaggedImage {
760                id: image.id,
761                tags: image
762                    .repo_tags
763                    .into_iter()
764                    .filter(|tag| tag != "<none>:<none>")
765                    .collect(),
766                digests: image
767                    .repo_digests
768                    .into_iter()
769                    .filter(|digest| digest != "<none>@<none>")
770                    .collect(),
771            })
772            .filter(|image| !image.tags.is_empty())
773            .collect())
774    }
775
776    async fn container_images(&self) -> Result<BTreeSet<String>, Error> {
777        let options = ListContainersOptionsBuilder::new().all(true).build();
778        let containers = self.api.list_containers(Some(options)).await?;
779        Ok(containers
780            .into_iter()
781            .filter_map(|container| container.image_id)
782            .collect())
783    }
784
785    async fn remove_image(&self, reference: &str) -> Result<(), Error> {
786        let options = RemoveImageOptionsBuilder::new().build();
787        match self.api.remove_image(reference, Some(options), None).await {
788            Err(error) if is_not_found(&error) => Ok(()),
789            other => other.map(|_| ()),
790        }
791    }
792
793    async fn free_space(&self) -> Result<u64, Error> {
794        let root = self.api.info().await?.docker_root_dir.unwrap_or_default();
795        // Only the directories above Docker's root need to be searchable: the daemon's user cannot read the root.
796        let stat = rustix::fs::statvfs(root.as_str()).map_err(|error| Error::IOError {
797            err: std::io::Error::other(format!("cannot measure the disk of {root}: {error}")),
798        })?;
799        Ok(stat.f_bavail.saturating_mul(stat.f_frsize))
800    }
801
802    async fn shell(
803        &self,
804        name: &str,
805        body: ContainerCreateBody,
806        size: TtySize,
807    ) -> Result<Tty, Error> {
808        let options = CreateContainerOptionsBuilder::new().name(name).build();
809        let id = self.api.create_container(Some(options), body).await?.id;
810        let attached = async {
811            let options = AttachContainerOptionsBuilder::new()
812                .stream(true)
813                .stdin(true)
814                .stdout(true)
815                .stderr(true)
816                .build();
817            let attached = self.api.attach_container(&id, Some(options)).await?;
818            self.api.start_container(&id, None).await?;
819            let resize = ResizeContainerTTYOptionsBuilder::new()
820                .w(i32::from(size.cols))
821                .h(i32::from(size.rows))
822                .build();
823            self.api.resize_container_tty(&id, resize).await?;
824            Ok::<_, Error>(attached)
825        };
826        match attached.await {
827            Ok(attached) => Ok(Tty {
828                container: id,
829                output: attached
830                    .output
831                    .map_ok(|output| output.into_bytes().to_vec())
832                    .boxed(),
833                input: attached.input,
834            }),
835            Err(error) => {
836                let _ = self.remove(&id).await;
837                Err(error)
838            }
839        }
840    }
841}
842
843/// How often `pull` logs its progress.
844const PULL_LOG_INTERVAL: Duration = Duration::from_secs(10);
845
846/// A pull's layers so far, from the statuses Docker streams per layer.
847#[derive(Debug, Default)]
848struct PullProgress {
849    layers: BTreeMap<String, Layer>,
850}
851
852#[derive(Debug, Default)]
853struct Layer {
854    downloaded: u64,
855    size: u64,
856    done: bool,
857}
858
859impl PullProgress {
860    fn update(&mut self, update: &CreateImageInfo) {
861        let (Some(id), Some(status)) = (&update.id, &update.status) else {
862            return;
863        };
864        let bytes = |value: Option<i64>| value.and_then(|value| u64::try_from(value).ok());
865        let detail = update.progress_detail.as_ref();
866        match status.as_str() {
867            "Pulling fs layer" | "Waiting" => {
868                self.layers.entry(id.clone()).or_default();
869            }
870            "Downloading" => {
871                let layer = self.layers.entry(id.clone()).or_default();
872                layer.downloaded =
873                    bytes(detail.and_then(|detail| detail.current)).unwrap_or(layer.downloaded);
874                layer.size = bytes(detail.and_then(|detail| detail.total)).unwrap_or(layer.size);
875            }
876            "Download complete" => {
877                if let Some(layer) = self.layers.get_mut(id) {
878                    layer.downloaded = layer.size;
879                }
880            }
881            "Pull complete" | "Already exists" => {
882                let layer = self.layers.entry(id.clone()).or_default();
883                layer.downloaded = layer.size;
884                layer.done = true;
885            }
886            _ => {}
887        }
888    }
889}
890
891impl fmt::Display for PullProgress {
892    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
893        let done = self.layers.values().filter(|layer| layer.done).count();
894        let downloaded: u64 = self.layers.values().map(|layer| layer.downloaded).sum();
895        let size: u64 = self.layers.values().map(|layer| layer.size).sum();
896        write!(
897            f,
898            "{done} of {} layers done, {} of {} downloaded",
899            self.layers.len(),
900            ByteSize(downloaded),
901            ByteSize(size)
902        )
903    }
904}
905
906fn connect_to(docker_host: Option<&str>) -> Result<Docker, Error> {
907    let api = match docker_host.filter(|host| !host.is_empty()) {
908        None => bollard::Docker::connect_with_socket_defaults()?,
909        Some(host) if host.starts_with("unix://") => {
910            bollard::Docker::connect_with_socket(host, 120, bollard::API_DEFAULT_VERSION)?
911        }
912        // Bollard would quietly fall back to the local socket: a different Engine than the one asked for.
913        Some(host) => {
914            return Err(Error::UnsupportedURISchemeError {
915                uri: host.to_owned(),
916            });
917        }
918    };
919    Ok(Docker { api })
920}
921
922/// A tar archive, to extract at `/`, holding the config as a root-only file at `JIT_CONFIG_PATH`.
923fn jit_config_tar(jit_config: &JitConfig) -> std::io::Result<Vec<u8>> {
924    let mut tar = tar::Builder::new(Vec::new());
925    let path = JIT_CONFIG_PATH.trim_start_matches('/');
926    let mut dir = tar::Header::new_gnu();
927    dir.set_entry_type(tar::EntryType::Directory);
928    dir.set_mode(0o700);
929    dir.set_size(0);
930    tar.append_data(
931        &mut dir,
932        path.rsplit_once('/').map_or("", |(dir, _)| dir),
933        std::io::empty(),
934    )?;
935    let mut file = tar::Header::new_gnu();
936    file.set_mode(0o400);
937    file.set_size(jit_config.0.len() as u64);
938    tar.append_data(&mut file, path, jit_config.0.as_bytes())?;
939    tar.into_inner()
940}
941
942#[cfg(test)]
943mod tests;