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.

This should be implemented after #198 and #199 are merged. #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 formula and cask JSON API from https://formulae.brew.sh/api, preserving signed JWS responses byte-for-byte.
  • Proxy manifests and bottle blobs from https://ghcr.io/v2/homebrew/core through a configurable OCI handler.
  • Cache API responses with the existing metadata cache and bottles with the existing artifact store. No additional database schema changes should be needed after fix(container): serve cached images when upstream is unavailable #199.
  • Preserve conditional request, content type, content length, ETag, last modified, OCI digest, GET, and HEAD behaviour used by Homebrew.
  • Restrict requests to the fixed Homebrew API and GHCR upstreams. Do not forward client credentials to GHCR or its CDN 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_BOTTLE_DOMAIN.
  • 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, and the generic HOMEBREW_ARTIFACT_DOMAIN URL-proxy behaviour are out of scope for the first version. Those require a separate design because they can turn the service into an open URL 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