moby/moby

Distribution

Purpose

daemon/internal/distribution/ is the registry client used by the legacy image store to pull and push images to OCI distribution-spec registries. The modern containerd-backed store does not use this code — it goes through containerd's own resolver instead.

Layout

File	Role
`config.go`	`ImagePullConfig`, `ImagePushConfig`, registry/transport setup.
`registry.go`	Builds a `distribution.Repository` from a registry endpoint.
`repository.go`	Repository wrapper.
`transport.go`	Authenticated HTTP transport.
`pull.go`	Generic pull entry point.
`pull_v2.go`	OCI/registry V2 pull (~26K LOC).
`pull_v2_unix.go`, `pull_v2_windows.go`	Per-OS layer extraction.
`push.go`	Generic push entry point.
`push_v2.go`	OCI/registry V2 push (~24K LOC).
`manifest.go`	Manifest schema handling (schema 1 + 2 + OCI).
`metadata/`	Persistent V2 metadata cache.
`xfer/`	Concurrent layer download/upload pool.
`utils/`	Progress + JSON stream helpers.
`errors.go`	Distribution-specific error types.

Pull / push pipeline

graph LR
  Pull[Pull V2] -->|manifests| Verify[Schema verify]
  Verify -->|descriptors| XferD[xfer.LayerDownloadManager]
  XferD -->|tar| Layer[layer.Store]
  Layer -->|chainIDs| ImageStore[image.Store]
  Push[Push V2] --> XferU[xfer.LayerUploadManager]
  XferU --> Registry
  Push --> Manifest[Build manifest]
  Manifest --> Registry

xfer/ runs configurable parallelism (default 3 concurrent downloads) and tracks progress; the API streams {status, progressDetail, id} JSON lines back to the client. Failures are retried with backoff inside xfer/transfer.go.

V1 manifest support

pull_v2.go and manifest.go still handle schema 1 manifests for compatibility with very old registries, with verification (signed by a trust anchor in the manifest itself).

Authentication

Auth tokens come from the API request — clients send a base64 JSON X-Registry-Auth header, which daemon/server/router/image/ decodes and passes through. The transport.go layer wires it into the HTTP transport. Long-lived registry credentials never live in the daemon itself.

When this code is used

Legacy image store path. With the containerd-backed store, daemon/containerd/image_pull.go / image_push.go use the containerd resolver directly and bypass this package.
Plugin install/upgrade. Managed plugins are distributed via OCI registries, and the plugin manager reuses parts of this client.

Entry points for modification

A new manifest media type: update manifest.go and the schema selectors in pull_v2.go/push_v2.go.
Concurrency tuning: parameters live in xfer/transfer.go and are surfaced via the --max-concurrent-downloads / --max-concurrent-uploads daemon flags.
Auth changes: usually plumb through config.go rather than touching transport.go directly.