oci-client Rust Library

The oci-client crate requires you to enable exactly one of the following three Cargo features for TLS support. Choosing the right one depends on your application's existing crypto requirements and preferred TLS implementation.

• rustls-tls (default): Uses the rustls library with the built-in aws-lc-rs crypto provider.
• rustls-tls-no-provider: Uses rustls but requires you to manually install a crypto provider before building a Client. Use this if your application already manages a crypto provider and you want to avoid aws-lc-rs.
• native-tls: Uses the operating system's native TLS library.

// Example for using rustls-tls-no-provider with the ring provider
// You must install the provider before building a Client
rustls::crypto::ring::default_provider().install_default();

The OCI specification defines a specific JSON error format. The rust-oci-client represents this using OciEnvelope and OciError structs. An OciEnvelope contains a list of OciError objects.

An OciError consists of:

• code: An OciErrorCode (e.g., UNAUTHORIZED, MANIFEST_UNKNOWN).
• message: A human-readable string describing the error.
• detail: An optional, unstructured serde_json::Value containing additional context.

If a registry returns an error code not explicitly defined in the OciErrorCode enum, it is captured in the OciErrorCode::Other(String) variant.

// Example of what an OCI error JSON looks like:
{
  "errors": [{
    "code": "UNAUTHORIZED",
    "message": "authentication required",
    "detail": [{"Type": "repository", "Name": "hello-wasm", "Action": "pull"}]
  }]
}

The OciManifest enum is an untagged wrapper that can represent either an OciImageManifest (a single image) or an OciImageIndex (a list of manifests for different platforms).

You can use the .content_type() method to retrieve the appropriate media type for the specific variant, which is useful when interacting with OCI registries.

• OciManifest::Image(OciImageManifest): Represents a single OCI image.
• OciManifest::ImageIndex(OciImageIndex): Represents an image index (manifest list).

// Example of getting the content type from an OciManifest
let content_type = manifest.content_type();

When pulling an image that is actually an OCI Image Index (a manifest list), the client needs to know which specific variant (OS/Arch) to select. You can provide a custom PlatformResolverFn in your ClientConfig to control this behavior.

Built-in resolvers include:

• current_platform_resolver: Matches the running OS and Architecture.
• linux_amd64_resolver: Specifically selects the first linux/amd64 variant.
• windows_amd64_resolver: Specifically selects the first windows/amd64 variant.

// Example: Using a custom resolver in ClientConfig
let config = ClientConfig {
    platform_resolver: Some(Box::new(|manifests| {
        // Custom logic to pick a digest from the manifests
        manifests.iter().find(|m| m.platform.as_ref().map_or(false, |p| p.os == "linux"))
            .map(|m| m.digest.clone())
    })),
    ..Default::default()
};

The client supports custom TLS configurations via ClientConfig and the Certificate struct.

Certificate Formats

Use the Certificate struct to provide certificates in either Der or Pem encoding:

let cert = Certificate {
    encoding: CertificateEncoding::Pem,
    data: vec![...],
};

Protocol Selection

Control whether the client uses HTTP or HTTPS via ClientProtocol:

• ClientProtocol::Http: Always use HTTP.
• ClientProtocol::Https: Always use HTTPS.
• ClientProtocol::HttpsExcept(Vec<String>): Use HTTPS for all registries except those listed in the provided vector.

When requesting blobs from an OCI registry, the response is encapsulated in the BlobResponse enum. This distinguishes between a full blob download and a partial blob download (used for range requests).

• BlobResponse::Full(SizedStream): The response contains the complete blob.
• BlobResponse::Partial(SizedStream): The response contains only a portion of the blob as requested.

To interact with an OCI registry, create a Client instance. You can create a client using a ClientConfig or by implementing the ClientConfigSource trait on your own configuration type.

If you use Client::new(config), it attempts to build the client from the provided configuration. If the configuration is invalid, it falls back to a default configuration and logs a warning.

// Using ClientConfig directly
let config = ClientConfig { ... };
let client = Client::new(config);

// Using a custom source via ClientConfigSource
struct MyConfig; 
impl ClientConfigSource for MyConfig {
    fn client_config(&self) -> ClientConfig {
        // return your config
    }
}
let client = Client::from_source(&MyConfig);

The History struct describes the history of each layer in the image. The array of history items is ordered from first to last.

Fields:

• created: Timestamp of layer creation (RFC 3339).
• author: The author of the build point.
• created_by: The command which created the layer.
• comment: A custom message set when creating the layer.
• empty_layer: A boolean indicating if this history item created a filesystem diff. If true, this item does not correspond to an actual layer in the rootfs section (e.g., a Dockerfile ENV command).