dockerhub

Documentation

Overview

Package dockerhub is the Docker Hub RegistrySource implementation. It collects per-repo pull counts and tag metadata via the unauthenticated Docker Hub /v2/ API, handling wildcard owner expansion, per-repo tag pagination, and severe-degradation detection.

Contract boundaries kept intact through extraction:

• URL shapes (https://hub.docker.com/v2/repositories/{owner}/...) are unchanged; httpx.DockerGitHubRedirectPolicy (wired on the shared *http.Client in main.go) still enforces the SSRF allowlist.
• Response JSON parsing (pull_count, last_updated, per-tag images[]) matches the on-disk model.Snapshot.DockerHub shape byte-for-byte.
• Page caps (owner listing: 10 pages; per-repo tags: 50 pages; 100 items per page) and the "hit cap → warn log" signal are preserved so dashboards that alert on truncation still see the same key set.

The package exposes a *Client (for composition-root wiring via api.RegistrySource) plus the exported Degraded predicate (a pure function retained because its input-shape is what the legacy TestDockerHubDegraded matrix asserts against). All collection behavior is reached through *Client methods; there are no free-function shims.

Index

• Constants
• func Degraded(results []model.RepoStats, attempted int) bool
• type Client
  • func NewClient(client *http.Client, retryOpts []httpx.Option, pageCap int, ...) *Client
  • func (c *Client) Collect(ctx context.Context, refs []model.RepoRef) (entries []model.RegistryEntry, attempted int, healthy bool)
  • func (c *Client) CollectTags(ctx context.Context, repo string) []model.TagInfo
  • func (c *Client) ListRepos(ctx context.Context, owner string) ([]model.RepoStats, error)
  • func (c *Client) Name() string
  • func (c *Client) Source() model.RegistrySource

Constants

const (
	MaxOwnerPages = 10
	MaxTagPages   = 50
	PageSize      = 100
)

Pagination caps. Chosen well above realistic usage so normal traffic never hits them; hitting a cap is a signal that behaviour changed and the warn logs below surface it. OwnerPages and TagPages bound the worst case per collection (1000 repos/owner, 5000 tags/repo).

Functions

func Degraded

func Degraded(results []model.RepoStats, attempted int) bool

Degraded reports whether a Docker Hub collection result is severely degraded: zero results with at least one attempt, or more than half of attempts failed. Kept as an exported free function because its pure-input shape is what the legacy TestDockerHubDegraded case matrix asserts against.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client implements api.RegistrySource for Docker Hub. Construct via NewClient; the zero value is not usable.

func NewClient

func NewClient(client *http.Client, retryOpts []httpx.Option, pageCap int, logger *slog.Logger) *Client

NewClient returns a Client that uses the provided *http.Client for all outbound requests, applying retryOpts to each call via httpx.Retry. A nil logger falls back to slog.Default. pageCap of 0 means "use the package-default caps"; any non-zero value applies to both owner listing and per-repo tag listing (used by tests to force the cap).

func (*Client) Collect

func (c *Client) Collect(
	ctx context.Context,
	refs []model.RepoRef,
) (entries []model.RegistryEntry, attempted int, healthy bool)

Collect gathers pull counts and tag metadata for every ref in refs. Returns the per-repo entries plus the attempted count (including failures) and a healthy flag derived from the severe-degradation rule: healthy is true when attempted == 0 or more than half of attempts produced a result. Matches the Degraded + pre-refactor return shape.

entries carry only the Docker Hub-relevant fields (Name, LastUpdated, PullCount, Tags); DownloadCount is left zero so later collect-level code can map entries into model.Snapshot.DockerHub without bleed.

func (*Client) CollectTags

func (c *Client) CollectTags(ctx context.Context, repo string) []model.TagInfo

CollectTags fetches all tags for a Docker Hub repo in owner/name form. Parse failures and transport errors terminate pagination; what got fetched before the failure is returned. Exposed as a method receiver for the same reason as ListRepos.

func (*Client) ListRepos

func (c *Client) ListRepos(ctx context.Context, owner string) ([]model.RepoStats, error)

ListRepos paginates the Docker Hub owner listing endpoint and returns each repo's Name (as owner/name), PullCount, and LastUpdated. Tags is left nil for the caller to fill separately. Exposed as a method receiver so tests that previously used the free-function form flip to c.ListRepos cleanly; collectWildcards still calls the unexported helper to share the paging machinery.

func (*Client) Name

func (c *Client) Name() string

Name identifies this source in logs and in the per-source health ratio. Matches the "dockerhub" const used on the HTTP API surface.

func (*Client) Source

func (c *Client) Source() model.RegistrySource

Source returns the typed model.RegistrySource the orchestrator uses to route entries into snap.DockerHub without a string compare. model.SourceDockerHub.String() must stay equal to Name() — both read as "dockerhub" on the wire.