zlayer_types/
lib.rs

1//! Shared wire types for the `ZLayer` platform.
2//!
3//! This crate is the SDK-facing types crate: API DTOs, OCI image
4//! references, and other serde-friendly wire shapes consumed by both
5//! the daemon and clients. It is intentionally lightweight — no axum,
6//! no tokio, no reqwest. Heavier server-side abstractions live in
7//! `zlayer-api`, `zlayer-core`, and friends.
8
9/// Canonical OCI image reference.
10///
11/// Re-export of [`oci_client::Reference`] (which itself re-exports
12/// `oci_spec::distribution::Reference`). Use this as the wire type for
13/// any image reference — the OCI spec grammar
14/// `[host[:port]/]name[:tag][@digest]`, with built-in normalization
15/// for Docker Hub defaults.
16pub use oci_client::Reference as ImageReference;
17
18/// Serde helpers to (de)serialize an [`ImageReference`] as its OCI-spec
19/// canonical string form (`[host[:port]/]name[:tag][@digest]`) instead of
20/// the default struct shape `{registry, repository, tag, digest}`.
21///
22/// Use with `#[serde(with = "zlayer_types::image_ref_serde")]` on a field
23/// of type `ImageReference`. For optional fields use `image_ref_serde::option`.
24pub mod image_ref_serde {
25    use super::ImageReference;
26    use serde::{Deserialize, Deserializer, Serializer};
27    use std::str::FromStr;
28
29    /// # Errors
30    ///
31    /// Returns the serializer's error if writing the string form fails.
32    pub fn serialize<S: Serializer>(r: &ImageReference, s: S) -> Result<S::Ok, S::Error> {
33        s.serialize_str(&r.to_string())
34    }
35
36    /// # Errors
37    ///
38    /// Returns a deserialization error if the input is not a valid OCI image reference string.
39    pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<ImageReference, D::Error> {
40        let s = String::deserialize(d)?;
41        ImageReference::from_str(&s).map_err(serde::de::Error::custom)
42    }
43
44    pub mod option {
45        use super::ImageReference;
46        use serde::{Deserialize, Deserializer, Serializer};
47        use std::str::FromStr;
48
49        /// # Errors
50        ///
51        /// Returns the serializer's error if writing the string form fails.
52        pub fn serialize<S: Serializer>(
53            r: &Option<ImageReference>,
54            s: S,
55        ) -> Result<S::Ok, S::Error> {
56            match r {
57                Some(r) => s.serialize_str(&r.to_string()),
58                None => s.serialize_none(),
59            }
60        }
61
62        /// # Errors
63        ///
64        /// Returns a deserialization error if the input is not a valid OCI image reference string.
65        pub fn deserialize<'de, D: Deserializer<'de>>(
66            d: D,
67        ) -> Result<Option<ImageReference>, D::Error> {
68            let s: Option<String> = Option::deserialize(d)?;
69            match s {
70                Some(s) => ImageReference::from_str(&s)
71                    .map(Some)
72                    .map_err(serde::de::Error::custom),
73                None => Ok(None),
74            }
75        }
76    }
77}
78
79/// Wire-type modules. Each maps to one logical area; downstream crates
80/// import via `pub use zlayer_types::<area>::...`.
81pub mod api;
82pub mod auth;
83pub mod client;
84pub mod spec;
85pub mod storage;
zlayer_types/lib.rs

zlayer_types/
lib.rs
