Struct oci_client::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. Typically, 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

source

pub fn new(config: ClientConfig) -> Self

Create a new client with the supplied config

source

pub fn from_source(config_source: &impl ClientConfigSource) -> Self

Create a new client with the supplied config

source

pub async fn store_auth_if_needed(&self, registry: &str, auth: &RegistryAuth)

Store the authentication information for this registry if it’s not already stored in the client.

Most of the time, you don’t need to call this method directly. It’s called by other methods (where you have to provide the authentication information as parameter).

But if you want to pull/push a blob without calling any of the other methods first, which would store the authentication information, you can call this method to store the authentication information manually.

source

pub async fn list_tags( &self, image: &Reference, auth: &RegistryAuth, n: Option<usize>, last: Option<&str>, ) -> Result<TagResponse>

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.

source

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.

source

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

source

pub async fn push_blob( &self, image_ref: &Reference, data: &[u8], digest: &str, ) -> Result<String>

Pushes a blob to the registry

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

pub async fn pull_blob<T: AsyncWrite + Unpin>( &self, image: &Reference, layer: impl AsLayerDescriptor, 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 layer descriptor can be anything that can be referenced as a 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.)

source

pub async fn pull_blob_stream( &self, image: &Reference, layer: impl AsLayerDescriptor, ) -> Result<SizedStream>

Stream a single layer from an OCI registry.

This is a streaming version of Client::pull_blob. Returns SizedStream, which implements Stream or can be used directly to get the content length of the response

§Example
use std::future::Future;
use std::io::Error;

use futures_util::TryStreamExt;
use oci_client::{Client, Reference};
use oci_client::client::ClientConfig;
use oci_client::manifest::OciDescriptor;

async {
  let client = Client::new(Default::default());
  let imgRef: Reference = "busybox:latest".parse().unwrap();
  let desc = OciDescriptor { digest: "sha256:deadbeef".to_owned(), ..Default::default() };
  let mut stream = client.pull_blob_stream(&imgRef, &desc).await.unwrap();
  // Check the optional content length
  let content_length = stream.content_length.unwrap_or_default();
  // Use as a stream
  stream.try_next().await.unwrap().unwrap();
  // Use the underlying stream
  let mut stream = stream.stream;
};
source

pub async fn pull_blob_stream_partial( &self, image: &Reference, layer: impl AsLayerDescriptor, offset: u64, length: Option<u64>, ) -> Result<BlobResponse>

Stream a single layer from an OCI registry starting with a byte offset. This can be used to continue downloading a layer after a network error. Please note that when doing a partial download (meaning it returns the BlobResponse::Partial variant), the layer digest is not verified as all the bytes are not available. The returned blob response will contain the header from the request digest, if it was set, that can be used (in addition to the digest from the layer) to verify the blob once all the bytes have been downloaded. Failure to do this means your content will not be verified.

Returns BlobResponse which indicates if the response was a full or partial response.

source

pub async fn mount_blob( &self, image: &Reference, source: &Reference, digest: &str, ) -> Result<()>

Mounts a blob to the provided reference, from the given source

source

pub async fn push_manifest( &self, image: &Reference, manifest: &OciManifest, ) -> Result<String>

Pushes the manifest for a specified image

Returns pullable manifest URL

source

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

source

pub async fn pull_referrers( &self, image: &Reference, artifact_type: Option<&str>, ) -> Result<OciImageIndex>

Pulls the referrers for the given image filtering by the optionally provided artifact type.

Trait Implementations§

source§

impl Clone for Client

source§

fn clone(&self) -> Client

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Default for Client

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl TryFrom<ClientConfig> for Client

source§

type Error = OciDistributionError

The type returned in the event of a conversion error.
source§

fn try_from(config: ClientConfig) -> Result<Self, Self::Error>

Performs the conversion.

Auto Trait Implementations§

§

impl Freeze for Client

§

impl !RefUnwindSafe for Client

§

impl Send for Client

§

impl Sync for Client

§

impl Unpin for Client

§

impl !UnwindSafe for Client

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

source§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more