Platform

z-oci selects image platforms from OCI indexes and Docker manifest lists. A platform has a required os and architecture, plus optional variant, os_version, and os_features fields.

Select a platform

The CLI accepts os/arch[/variant]:

./zig-out/bin/z-oci resolve --platform linux/amd64 ubuntu:22.04
./zig-out/bin/z-oci inspect --platform linux/amd64 --format json ubuntu:22.04

The library accepts a Platform value:

const platform = z_oci.Platform{
    .os = "linux",
    .architecture = "amd64",
};

Matching follows these rules:

• os and architecture are required and compared case-insensitively.
• An omitted variant accepts any candidate variant. A supplied variant must match case-insensitively.
• A library filter with os_version uses dot-segment prefix matching. 10.0 matches 10.0.17763, but not 10.01.
• os_features is parsed and preserved as metadata; Platform.match does not use it as a selection constraint.
• Nested indexes are followed through at most four child levels. A deeper chain returns depth_limit_exceeded.

For resolve, validate, and getManifest, a multi-arch reference without a platform returns platform_required. inspect can return the top-level index without selecting a leaf. If no descriptor matches, the selecting operation returns platform_not_found. The CLI does not accept --platform for validate because that command requires an exact digest reference.

HTTPS and trust

Registry request builders use HTTPS. The live manifest, token, and /v2/ ping exchangers rewrite URLs to cleartext HTTP only for 127.0.0.1, localhost, and ::1, which supports local registry tests. Other hosts remain HTTPS.

The repository verifies live HTTPS behavior on Linux and macOS. Windows is not a verified supported build target for this repository. The Zig standard library has Windows TLS support, but this project also uses POSIX clock APIs in retry and authentication policy. A custom CA bundle does not establish Windows support.

Config.ca_bundle_path loads a certificate-only PEM trust bundle and replaces the client's OS trust bundle rather than merging with it. The file must not contain private-key PEM blocks, and POSIX files that are writable by other users are rejected. See Credentials for CLI and library trust-bundle setup.

Configuration defaults

These are the defaults in the public Config type:

• max_manifest_bytes: 8 MiB per manifest response.
• max_token_response_bytes: 64 KiB per token response.
• max_token_cache_entries: 128 cached token scopes per AuthEngine; 0 disables the entry limit.
• max_retries: 1 retry after invalidating a cached token that received 401.
• max_network_retries: 1 retry for retryable transport errors and 502, 503, or 504 responses.
• max_rate_limit_retries: 1 retry for 429 responses.
• rate_limit_enabled: false; when enabled, pre-emptive sleeping uses complete trusted RateLimit-* metadata.
• read_timeout_ms: 30,000 ms for Docker credential-helper I/O; 0 disables that helper timeout.
• connect_timeout_ms: 0. The live resolver path does not apply this value to std.http.Client.request; it is available to caller-owned connection recipes through Config.connectIoTimeout().

Public resolve calls create a call-scoped auth engine. Code that creates an AuthEngine directly owns it and must call deinit().

Scope boundaries

z-oci reads registry metadata. It does not pull layers, push images, build images, or act as a container runtime.