zlayer_types/api/
images.rs

1//! Image management API DTOs.
2//!
3//! Wire-format types shared between the daemon's `/api/v1/images` and
4//! `/api/v1/system/prune` endpoints and SDK clients. Moved out of
5//! `zlayer-api` so SDK crates can depend on them without pulling in the
6//! full server stack.
7
8use serde::{Deserialize, Serialize};
9use utoipa::{IntoParams, ToSchema};
10
11/// Serializable wrapper for `zlayer_agent::runtime::ImageInfo` so we can
12/// attach `ToSchema` here (the underlying type in `zlayer-agent` can't
13/// depend on `utoipa`).
14#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
15pub struct ImageInfoDto {
16    /// Canonical image reference (e.g. `zachhandley/zlayer-manager:latest`).
17    #[schema(value_type = String)]
18    #[serde(with = "crate::image_ref_serde")]
19    pub reference: crate::ImageReference,
20    /// Content-addressed digest (`sha256:...`) if known.
21    pub digest: Option<String>,
22    /// Size in bytes if known.
23    pub size_bytes: Option<u64>,
24}
25
26/// Serializable wrapper for `zlayer_agent::runtime::PruneResult`.
27#[derive(Debug, Clone, Serialize, Deserialize, Default, ToSchema)]
28pub struct PruneResultDto {
29    /// Image references or digests that were removed.
30    pub deleted: Vec<String>,
31    /// Bytes reclaimed from the cache.
32    pub space_reclaimed: u64,
33}
34
35/// Request body for the pull-image handler. Blocking pull of an OCI image.
36#[derive(Debug, Clone, Deserialize, ToSchema)]
37pub struct PullImageRequest {
38    /// OCI image reference to pull, e.g. `docker.io/library/nginx:latest`.
39    #[schema(value_type = String)]
40    #[serde(with = "crate::image_ref_serde")]
41    pub reference: crate::ImageReference,
42    /// Pull policy override. Accepts `"always"`, `"if_not_present"`, or
43    /// `"never"`. Defaults to `"always"` when omitted.
44    #[serde(default)]
45    pub pull_policy: Option<String>,
46    // -- §3.10: registry auth -----------------------------------------------
47    /// Id of a persisted registry credential (from
48    /// `POST /api/v1/credentials/registry`) to use for this pull. Ignored
49    /// when [`Self::registry_auth`] is also supplied (inline auth wins).
50    /// Requires the daemon to be configured with a credential store.
51    #[serde(default, skip_serializing_if = "Option::is_none")]
52    pub registry_credential_id: Option<String>,
53    /// Inline Docker/OCI registry credentials used for this pull only. Not
54    /// persisted, never logged, never echoed back on a response. Takes
55    /// precedence over `registry_credential_id`.
56    #[serde(default, skip_serializing_if = "Option::is_none")]
57    pub registry_auth: Option<crate::spec::RegistryAuth>,
58}
59
60/// Response body for the pull-image handler. Reports the pulled reference
61/// and, when the backend exposes it via `list_images`, the resolved digest
62/// and on-disk size.
63#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
64pub struct PullImageResponse {
65    /// Canonical reference that was pulled.
66    #[schema(value_type = String)]
67    #[serde(with = "crate::image_ref_serde")]
68    pub reference: crate::ImageReference,
69    /// Content-addressed digest (`sha256:...`) if the runtime reports one.
70    #[serde(default, skip_serializing_if = "Option::is_none")]
71    pub digest: Option<String>,
72    /// On-disk size in bytes if the runtime reports one.
73    #[serde(default, skip_serializing_if = "Option::is_none")]
74    pub size_bytes: Option<u64>,
75}
76
77/// Query parameters for the remove-image handler.
78#[derive(Debug, Deserialize, IntoParams)]
79pub struct RemoveImageQuery {
80    /// Force removal even if the image is referenced by containers.
81    #[serde(default)]
82    pub force: bool,
83}
84
85/// Request body for the tag-image handler. Matches Docker-compat
86/// `docker tag` semantics: create a new reference (`target`) pointing at an
87/// already-cached image (`source`).
88#[derive(Debug, Clone, Deserialize, ToSchema)]
89pub struct TagImageRequest {
90    /// Existing image reference to tag (e.g. `myapp:latest`).
91    #[schema(value_type = String)]
92    #[serde(with = "crate::image_ref_serde")]
93    pub source: crate::ImageReference,
94    /// New reference to create (e.g. `registry.example.com/myapp:v1`).
95    #[schema(value_type = String)]
96    #[serde(with = "crate::image_ref_serde")]
97    pub target: crate::ImageReference,
98}
zlayer_types/api/images.rs

zlayer_types/api/
images.rs
