utils.docker package

Subpackages

Submodules

utils.docker.mirror module

Address the GHCR mirror copy of an upstream image.

Owns the mirror path formula for both the provider that writes the copies and the registry probes that read them.

utils.docker.mirror.mirror_image(image: str) → str | None

Return the mirror repository for image, or None when unresolvable.

None means the caller has to address the upstream registry: the image name is malformed, the mirror prefix is not configured, or neither the GitHub environment nor the git remote names the GHCR namespace.

utils.docker.mirror.mirror_image_base(registry: str, name: str, *, namespace: str, repository: str, prefix: str) → str

Return the mirror repository for an upstream image, without a tag.

Parameters:

  • registry – normalised upstream registry host, e.g. docker.io.

  • name – upstream repository without the registry, e.g. postgis/postgis.

  • namespace – GHCR owner.

  • repository – GHCR repository the mirror lives under.

  • prefix – path segment separating mirrored images from own images.

utils.docker.paths_utils module

utils.docker.paths_utils.get_docker_paths(application_id: str, path_docker_compose_instances: str) → dict

Build the compose dict based on path_docker_compose_instances and application_id. Uses get_entity_name to extract the entity name from application_id.

utils.docker.registry module

Generic Docker Registry HTTP API v2 client.

Lists tags and checks tag reachability for ANY registry that speaks the standard v2 API (Docker Hub, GHCR, MCR, Quay, GitLab/opencode, …) via the RFC-standard WWW-Authenticate: Bearer token-challenge flow, so no per-registry special case is needed. docker.io resolves to registry-1.docker.io and bare official names are prefixed with library/.

Reachability (manifest_exists()) distinguishes three outcomes: True (tag present), False (registry answered 404 — tag absent), and None (indeterminate: network error, auth wall, rate limit) so callers can fail on a genuinely broken pin without flaking on a slow or private registry.

utils.docker.registry.config_blob(image: str, reference: str, os_name: str, architecture: str) → dict | None

Return the OCI config blob of image:reference from its registry.

Parameters:

  • image – image name, with or without registry host.

  • reference – tag or digest.

  • os_name – platform to resolve a multi-arch index to.

  • architecture – platform to resolve a multi-arch index to.

Returns:

The parsed blob with config and history, or None on any indeterminate outcome (see fetch_manifest()) and on an index without a matching platform.

utils.docker.registry.fetch_manifest(image: str, reference: str) → dict | None

Return the parsed manifest (or index) for image:reference.

None on any indeterminate outcome: unresolvable name, network error, auth wall, rate limit, non-200 status, or unparsable body.

utils.docker.registry.fetch_registry_tags(image: str, max_pages: int = 10, last: str | None = None) → list[str]

Return all tags for image from its registry (empty on any failure).

last seeds the OCI pagination cursor: only tags sorting lexically after it are returned. Repos like GitLab CNG carry tens of thousands of commit-sha tags before the v* release tags, so an unseeded scan exhausts max_pages without ever reaching them.

utils.docker.registry.image_healthcheck(image: str, reference: str, *, os_name: str = 'linux', architecture: str = 'amd64') → dict | None

Return the HEALTHCHECK baked into image:reference.

Parameters:

  • image – image name, with or without registry host.

  • reference – tag or digest.

  • os_name – platform to resolve a multi-arch index to.

  • architecture – platform to resolve a multi-arch index to.

Returns:

The image’s healthcheck config, {} when the image definitively declares none, and None when the answer is indeterminate - an unresolvable name, a network error, an auth wall, a rate limit, or an index without a matching platform. A caller must not read {} and None as the same thing: only the former is evidence.

Reads from the mirror first and falls back to the upstream registry only for images the mirror does not carry, so a full sweep does not spend the upstream’s rate limit. Determinate answers are cached on disk.

utils.docker.registry.image_healthcheck_probed(image: str, reference: str, *, os_name: str = 'linux', architecture: str = 'amd64') → tuple[dict | None, str]

image_healthcheck() plus which address answered.

Returns:

(healthcheck, source) where source is cache, mirror, upstream or none. Reading upstream is the documented fallback for images the mirror does not carry; a caller that sweeps many images can use the counts to tell a fallback from a mirror that stopped working.

utils.docker.registry.manifest_exists(image: str, reference: str) → bool | None

Whether image:reference resolves to a manifest.

True present, False registry said 404, None indeterminate (network error, 401/403 auth wall, 429 rate limit, 5xx).

A confirmed hit is cached on disk. The probe stays on the upstream registry: it exists to prove the declared pin is still pullable from where the deploy pulls it, which a mirrored copy cannot answer for.

utils.docker.registry.manifest_transfer_size(image: str, reference: str, *, os_name: str = 'linux', architecture: str = 'amd64') → int | None

Return the compressed transfer size of image:reference in bytes.

The size is the config blob plus every layer blob, i.e. what a pull moves over the wire. A multi-platform index is resolved to the os_name/architecture manifest first.

None on any indeterminate outcome (see fetch_manifest()), on an index without a matching platform, and on a manifest that carries no layers.

Read from the GHCR mirror when one is configured, falling back to the upstream registry only for images the mirror does not carry. Measured sizes are cached on disk (see _cache_dir()).

Module contents