Add Homebrew JSON API and bottle proxy support - #254
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Adds first-class proxying for Homebrew’s JSON API and homebrew/core OCI bottles, building on the existing metadata cache + OCI artifact store to support offline use while preserving signed API payload bytes and validating digest-addressed OCI content before caching.
Changes:
- Adds
/homebrew/*handler to proxy Homebrew JSON API responses (including signed JWS) with optional metadata caching. - Extends OCI
/v2/*routing to support per-repository upstream registries (used to sendhomebrew/coreto GHCR by default). - Adds digest verification for cached OCI blobs/manifests and expands validator handling (ETag/Last-Modified, HEAD behavior) across metadata + OCI manifest responses.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Documents Homebrew client configuration and upstream chaining. |
| internal/server/server.go | Wires /homebrew routing and registers homebrew/core registry override for /v2. |
| internal/handler/homebrew.go | New Homebrew JSON API handler and homebrew/core OCI registry registration helper. |
| internal/handler/homebrew_test.go | Tests byte-for-byte signed response preservation, validators, offline stale serving, and path/method rejection. |
| internal/handler/handler.go | Improves validator usage, HEAD behavior, and adds artifact digest verification before caching. |
| internal/handler/handler_test.go | Updates mock storage hashing to SHA-256 to support new digest verification behavior. |
| internal/handler/container.go | Adds per-repository registry routing and digest verification for blob fetches; improves HEAD response header handling. |
| internal/handler/container_test.go | Adds tests for longest-prefix registry routing, credential non-forwarding, and digest mismatch non-caching. |
| internal/handler/container_manifest.go | Adds registry-scoped manifest cache keys, Last-Modified handling, conditional 304 support, and manifest digest verification. |
| internal/config/config.go | Adds configurable Homebrew API + artifact upstreams with defaults and env var support. |
| internal/config/config_test.go | Verifies defaults + YAML/env loading for new Homebrew upstream config. |
| docs/configuration.md | Documents new upstream config keys. |
| config.example.yaml | Adds example Homebrew upstream configuration entries. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
andrew
force-pushed
the
homebrew-proxy-247
branch
from
August 17, 2026 08:40
ad13676 to
2e672fc
Compare
andrew
force-pushed
the
homebrew-proxy-247
branch
from
September 2, 2026 20:24
7693321 to
5daabf3
Compare
Route Homebrew API HEAD requests through ProxyCached so a warm cache answers without an upstream call and stale entries are served when the upstream is unreachable. HEAD still reaches upstream as HEAD when metadata caching is disabled. Limit OCI manifest digest verification to sha256 references and Docker-Content-Digest headers so other digest algorithms are proxied instead of rejected, and log the failing expected value.
Compute real manifest digests in #280's fixture upstreams so the new verification accepts them, and add headerETag / headerLastModified to
The Homebrew API cache key does not include Accept, so replaying the client header could serve one representation under another; the API does not negotiate anyway. Compare If-None-Match with weak comparison, list splitting and "*" per RFC 7232 instead of string equality, and apply the same helper to the metadata and swift responders.
Move the configureScanning doc comment back to its function after the auto-merge stacked it on mountProtocolHandlers, and drop the second ETag/Last-Modified set in writeMetadataCachedResponse now that the pre-304 set covers both response paths.
andrew
force-pushed
the
homebrew-proxy-247
branch
from
September 3, 2026 09:23
54106fe to
211fc3e
Compare
pinguinfuss
added a commit
to pinguinfuss/proxy
that referenced
this pull request
Sep 6, 2026
Homebrew (git-pkgs#254) routes every API path through ProxyCached and so, since git-pkgs#304, fetches formula.jws.json (~33 MB plain, ~5 MB gzip) uncompressed on every refresh -- the case that motivated git-pkgs#305. Request gzip for the JSON API via proxyCachedWithEncoding: brew fetches every API download with curl --compressed and decodes Content-Encoding itself, so the compressed bytes and header are cached and served as-is and both hops stay compressed. The analytics endpoints are the one brew consumer fetched without --compressed; they stay on identity.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds first-class Homebrew JSON API and bottle proxy support for #247.
Signed API responses are cached without rewriting.
homebrew/coremanifests and blobs are served offline from cache and checked against their content digests before cache records are written.The API and artifact upstreams default to
https://formulae.brew.sh/apiandhttps://ghcr.io. Both can be configured through YAML or environment variables, so one proxy can use another proxy as its upstream.Client setup and upstream configuration are documented in the README.
Closes #247