rust-oci-client

rust-oci-client (published on crates.io as oci-client, and formerly known as oci-distribution) is a Rust implementation of the OCI Distribution specification — the HTTP protocol that Docker Hub and other container registries use to store and serve images and artifacts. It gives Rust applications an async client for pulling and pushing image manifests, configs, and blobs to any OCI-compliant registry.

Maintained under the CNCF ORAS project, the library handles registry authentication (including token caching), manifest and blob transfer, digest computation and validation, and pluggable TLS backends. It is a foundational building block for Rust tooling that needs to interact with container and artifact registries, such as WebAssembly runtimes and OCI-based package tools.

What You Get

• An async Client for pulling and pushing OCI image manifests, configs, and blobs
• Registry authentication with a built-in token cache keyed by registry operation
• SHA-256 digest computation and validation for content-addressable integrity
• Selectable TLS backends (rustls or native-tls) and optional Hickory DNS via Cargo features
• Typed manifest, config, and annotation models built on the oci-spec crate

Common Use Cases

• Pulling container image layers and configs from Docker Hub or a private registry
• Pushing OCI artifacts (such as Wasm modules or policy bundles) to a registry
• Building Rust CLI tools and runtimes that distribute content via OCI registries
• Verifying image integrity through content-addressable digests

Under The Hood

Architecture — The crate root (src/lib.rs) re-exports client::Client as the primary entry point alongside Reference from oci-spec. The module layout maps cleanly onto the OCI Distribution protocol: client.rs drives the registry HTTP conversation, manifest.rs and config.rs model image manifests and configs, blob.rs streams layer content, digest.rs computes and validates SHA-256 digests, secrets.rs holds auth credentials, and token_cache.rs caches bearer tokens keyed by RegistryOperation. errors.rs defines a thiserror-based error enum surfaced across the API.

Tech Stack — Async Rust on Tokio, with reqwest as the HTTP client (default-features off, json/query/stream enabled) and oci-spec for the canonical manifest/reference types. Supporting crates include jsonwebtoken and http-auth for registry auth, sha2/hex for digests, chrono, regex, and olpc-cjson for canonical JSON. Cargo features select the TLS backend (rustls-tls by default, or native-tls) and optionally hickory-dns.

Code Quality — The crate enforces #![deny(missing_docs)], so the entire public surface is documented, and it publishes docs on docs.rs. It carries a tests/ directory (digest validation plus fixtures) and inline test helpers, uses cargo-deny (deny.toml) for dependency and license auditing, and is actively maintained under the CNCF ORAS project with named Microsoft/SUSE authors.

API Design — The public API is compact and idiomatic: a single Client type with async pull/push methods and a small set of typed models. The examples/ directory (get-manifest and a wasm example) and thorough rustdoc make common flows easy to follow, though understanding the OCI Distribution protocol and content-addressable digests is a prerequisite for advanced use.