Struct oci_distribution::Client
source · pub struct Client { /* private fields */ }Expand description
The OCI client connects to an OCI registry and fetches OCI images.
An OCI registry is a container registry that adheres to the OCI Distribution specification. DockerHub is one example, as are ACR and GCR. This client provides a native Rust implementation for pulling OCI images.
Some OCI registries support completely anonymous access. But most require
at least an Oauth2 handshake. Typlically, you will want to create a new
client, and then run the auth() method, which will attempt to get
a read-only bearer token. From there, pulling images can be done with
the pull_* functions.
For true anonymous access, you can skip auth(). This is not recommended
unless you are sure that the remote registry does not require Oauth2.
Implementations§
source§impl Client
impl Client
sourcepub fn new(config: ClientConfig) -> Self
pub fn new(config: ClientConfig) -> Self
Create a new client with the supplied config
sourcepub fn from_source(config_source: &impl ClientConfigSource) -> Self
pub fn from_source(config_source: &impl ClientConfigSource) -> Self
Create a new client with the supplied config
Fetches the available Tags for the given Reference
The client will check if it’s already been authenticated and if not will attempt to do.
sourcepub async fn pull(
&self,
image: &Reference,
auth: &RegistryAuth,
accepted_media_types: Vec<&str>
) -> Result<ImageData>
pub async fn pull( &self, image: &Reference, auth: &RegistryAuth, accepted_media_types: Vec<&str> ) -> Result<ImageData>
Pull an image and return the bytes
The client will check if it’s already been authenticated and if not will attempt to do.
sourcepub async fn push(
&self,
image_ref: &Reference,
layers: &[ImageLayer],
config: Config,
auth: &RegistryAuth,
manifest: Option<OciImageManifest>
) -> Result<PushResponse>
pub async fn push( &self, image_ref: &Reference, layers: &[ImageLayer], config: Config, auth: &RegistryAuth, manifest: Option<OciImageManifest> ) -> Result<PushResponse>
Push an image and return the uploaded URL of the image
The client will check if it’s already been authenticated and if not will attempt to do.
If a manifest is not provided, the client will attempt to generate it from the provided image and config data.
Returns pullable URL for the image
sourcepub async fn push_blob(
&self,
image_ref: &Reference,
data: &[u8],
digest: &str
) -> Result<String>
pub async fn push_blob( &self, image_ref: &Reference, data: &[u8], digest: &str ) -> Result<String>
Pushes a blob to the registry
sourcepub async fn auth(
&self,
image: &Reference,
authentication: &RegistryAuth,
operation: RegistryOperation
) -> Result<Option<String>>
pub async fn auth( &self, image: &Reference, authentication: &RegistryAuth, operation: RegistryOperation ) -> Result<Option<String>>
Perform an OAuth v2 auth request if necessary.
This performs authorization and then stores the token internally to be used on other requests.
sourcepub async fn fetch_manifest_digest(
&self,
image: &Reference,
auth: &RegistryAuth
) -> Result<String>
pub async fn fetch_manifest_digest( &self, image: &Reference, auth: &RegistryAuth ) -> Result<String>
Fetch a manifest’s digest from the remote OCI Distribution service.
If the connection has already gone through authentication, this will use the bearer token. Otherwise, this will attempt an anonymous pull.
Will first attempt to read the Docker-Content-Digest header using a
HEAD request. If this header is not present, will make a second GET
request and return the SHA256 of the response body.
sourcepub async fn pull_image_manifest(
&self,
image: &Reference,
auth: &RegistryAuth
) -> Result<(OciImageManifest, String)>
pub async fn pull_image_manifest( &self, image: &Reference, auth: &RegistryAuth ) -> Result<(OciImageManifest, String)>
Pull a manifest from the remote OCI Distribution service.
The client will check if it’s already been authenticated and if not will attempt to do.
A Tuple is returned containing the OciImageManifest and the manifest content digest hash.
If a multi-platform Image Index manifest is encountered, a platform-specific Image manifest will be selected using the client’s default platform resolution.
sourcepub async fn pull_manifest_raw(
&self,
image: &Reference,
auth: &RegistryAuth,
accepted_media_types: &[&str]
) -> Result<(Vec<u8>, String)>
pub async fn pull_manifest_raw( &self, image: &Reference, auth: &RegistryAuth, accepted_media_types: &[&str] ) -> Result<(Vec<u8>, String)>
Pull a manifest from the remote OCI Distribution service without parsing it.
The client will check if it’s already been authenticated and if not will attempt to do.
A Tuple is returned containing raw byte representation of the manifest and the manifest content digest.
sourcepub async fn pull_manifest(
&self,
image: &Reference,
auth: &RegistryAuth
) -> Result<(OciManifest, String)>
pub async fn pull_manifest( &self, image: &Reference, auth: &RegistryAuth ) -> Result<(OciManifest, String)>
Pull a manifest from the remote OCI Distribution service.
The client will check if it’s already been authenticated and if not will attempt to do.
A Tuple is returned containing the Manifest and the manifest content digest hash.
sourcepub async fn pull_manifest_and_config(
&self,
image: &Reference,
auth: &RegistryAuth
) -> Result<(OciImageManifest, String, String)>
pub async fn pull_manifest_and_config( &self, image: &Reference, auth: &RegistryAuth ) -> Result<(OciImageManifest, String, String)>
Pull a manifest and its config from the remote OCI Distribution service.
The client will check if it’s already been authenticated and if not will attempt to do.
A Tuple is returned containing the OciImageManifest, the manifest content digest hash and the contents of the manifests config layer as a String.
sourcepub async fn push_manifest_list(
&self,
reference: &Reference,
auth: &RegistryAuth,
manifest: OciImageIndex
) -> Result<String>
pub async fn push_manifest_list( &self, reference: &Reference, auth: &RegistryAuth, manifest: OciImageIndex ) -> Result<String>
Push a manifest list to an OCI registry.
This pushes a manifest list to an OCI registry.
sourcepub async fn pull_blob<T: AsyncWrite + Unpin>(
&self,
image: &Reference,
layer: &OciDescriptor,
out: T
) -> Result<()>
pub async fn pull_blob<T: AsyncWrite + Unpin>( &self, image: &Reference, layer: &OciDescriptor, out: T ) -> Result<()>
Pull a single layer from an OCI registry.
This pulls the layer for a particular image that is identified by the given layer descriptor. The image reference is used to find the repository and the registry, but it is not used to verify that the digest is a layer inside of the image. (The manifest is used for that.)
sourcepub async fn pull_blob_stream(
&self,
image: &Reference,
layer: &OciDescriptor
) -> Result<impl Stream<Item = Result<Bytes, Error>>>
pub async fn pull_blob_stream( &self, image: &Reference, layer: &OciDescriptor ) -> Result<impl Stream<Item = Result<Bytes, Error>>>
Stream a single layer from an OCI registry.
This is a streaming version of Client::pull_blob.
Returns Stream.
sourcepub async fn mount_blob(
&self,
image: &Reference,
source: &Reference,
digest: &str
) -> Result<()>
pub async fn mount_blob( &self, image: &Reference, source: &Reference, digest: &str ) -> Result<()>
Mounts a blob to the provided reference, from the given source
sourcepub async fn push_manifest(
&self,
image: &Reference,
manifest: &OciManifest
) -> Result<String>
pub async fn push_manifest( &self, image: &Reference, manifest: &OciManifest ) -> Result<String>
Pushes the manifest for a specified image
Returns pullable manifest URL
sourcepub async fn push_manifest_raw(
&self,
image: &Reference,
body: Vec<u8>,
content_type: HeaderValue
) -> Result<String>
pub async fn push_manifest_raw( &self, image: &Reference, body: Vec<u8>, content_type: HeaderValue ) -> Result<String>
Pushes the manifest, provided as raw bytes, for a specified image
Returns pullable manifest url