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