Skip to content

Add Homebrew JSON API and bottle proxy support #247

Description

@andrew

Add first-class proxy support for Homebrew's JSON API and prebuilt homebrew/core bottles. The proxy currently has Homebrew package metadata support through registries, but Homebrew clients cannot use it as a download mirror.

With #198 and #199 merged, the required OCI support is available. #198 provides shared OCI bearer-challenge authentication, including the flow used by GHCR. #199 adds OCI manifest caching, digest aliases, cached blob lookup, HEAD support, and offline serving. The Homebrew handler should generalize and reuse that code.

The initial scope should include:

  • Proxy the Homebrew JSON API, defaulting to https://formulae.brew.sh/api. Allow the upstream base URL to be configured, including another proxy's /homebrew endpoint. This includes the signed formula and cask files, per-package endpoints, and the current internal/packages.<platform>.jws.json endpoint. Preserve signed JWS responses byte-for-byte.
  • Proxy manifests and bottle blobs for homebrew/core, using https://ghcr.io as the default artifact registry. Allow the registry base URL to be configured, including another proxy.
  • Cache API responses with the existing metadata cache and bottles with the existing artifact store. No additional database schema changes should be needed.
  • Preserve conditional request, content type, content length, ETag, last modified, OCI digest, GET, and HEAD behaviour used by Homebrew.
  • Do not forward client credentials to the configured Homebrew upstreams or their redirects.
  • Verify digest-addressed OCI responses before recording them as cached. The broader artifact-integrity work remains tracked in Verify artifact integrity and support sigstore attestations #42.
  • Document client configuration using HOMEBREW_API_DOMAIN and HOMEBREW_ARTIFACT_DOMAIN, plus proxy upstream configuration through YAML and environment variables. Restrict the artifact route to /v2/homebrew/core/**; other rewritten artifact paths should return 404 and allow Homebrew's normal fallback.
  • Test the handler with an actual brew fetch jq against an empty cache, a warm cache, and an unavailable upstream.

Arbitrary source archives, cask application downloads, custom tap artifact hosts, legacy flat-file mirrors configured through HOMEBREW_BOTTLE_DOMAIN, and generic HOMEBREW_ARTIFACT_DOMAIN URL-proxy behaviour are out of scope for the first version. HOMEBREW_ARTIFACT_DOMAIN is only used here to preserve Homebrew's OCI bottle paths while pointing them at the proxy.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions