Add spec for brew package URLs

[woodruffw]

This adds the brew purl type.

Closes #254.

[woodruffw]

CC @p-linnane @SMillerDev @colindean for thoughts as well 🙂

[colindean]

One major nit and a few non-blocking questions and suggestions

[colindean]

question (non-blocking): Should there be another parameter to name the tap? We use the named tap at work, e.g.

brew tap myco/brewhouse git@git.myco.com:brew/house.git

and the formula, uh, myco-ctl could have a purl

pkg:brew/myco/brewhouse/myco-ctl?tap_url=git@git.myco.com:brew/house.git

and brew would know how to name the tap if it needed to be tapped, or perhaps

pkg:brew/myco/brewhouse/myco-ctl?tap_url=git@git.myco.com:brew/house.git&tap_name=myco/brewhouse

or more simply

pkg:brew/myco-ctl?tap_url=git@git.myco.com:brew/house.git&tap_name=myco/brewhouse

[woodruffw]

My 0.02c would be for your first form:

pkg:brew/myco/brewhouse/myco-ctl?tap_url=git@git.myco.com:brew/house.git

I think that's unambiguous: the github.com/{org}/homebrew-{tap} logic only applies when a tap_url isn't present, so I think this is the shortest form that conveys all needed information. But maybe I've overlooked something?

[pombredanne]

@MikeMcQuaid 👋 A quick review or ack from you would awesome!

[pombredanne]

Thanks!
LGTM overall, though the double @ in postgres@16@16.1 name seems a bit weird. Is it possible to run brew install postgres@16@16.1 or instead brew install postgres@16.1 or instead brew install postgres%4016@16.1

[matt-phylum]

According to Stack Overflow, you cannot install a specific version. pkg:brew/postgresql%4016@16.1 means version 16.1 of Postgres from the postgresql@16 package, which is useful for answering "what's installed?", but apparently not useful for trying to install the same package. The repository apparently doesn't keep old versions: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/p/postgresql@16.rb

[woodruffw]

LGTM overall, though the double @ in postgres@16@16.1 name seems a bit weird. Is it possible to run brew install postgres@16@16.1 or instead brew install postgres@16.1 or instead brew install postgres%4016@16.1

Both brew install postgres and brew install postgres@16 are supported, but the others aren't. Homebrew doesn't really support multiple versions of the same package (per what @matt-phylum said) -- the @X syntax is a hack that Homebrew does to allow multiple versions of the same package to exist in a tap when the ecosystem can't all exist on a single version (e.g. OpenSSL, Python, etc.).

TL;DR yes, there is no way to install a specific minor version, e.g. postgres 16.1. postgres@16 is the full name of a formula, referring specifically to whatever latest version of postgres 16 is packaged by Homebrew.

Link for reference: https://github.com/Homebrew/homebrew-core/blob/master/Formula/p/postgresql%4016.rb

[MikeMcQuaid]

Looks good to me!

[woodruffw]

Gentle ping for review+approval here: this is no longer a blocker in Homebrew's attestation work, but I'd like to get it in so that we can consider it for any future attestation changes, if necessary 🙂

[woodruffw]

Another gentle ping for review here!

[captn3m0]

+1 for merging this.

[matt-phylum]

I think it's important for this PR to add entries to the test suite. Package names can contain the @ character and this is not handled correctly by maennchen/purl (maennchen/purl#10) or anchore/packageurl-go (does not accept bug reports). Both fail to handle pkg:brew/postgres%4016.

There's also a common misimplementation of the parsing spec which can cause problems here. The spec says "Split the remainder once from the right on '@'. The left side is the remainder. Percent-decode the right side. This is the version." However, some implementations split once from the left on '@'. If somebody writes pkg:brew/postgres@16@16.1 (non-canonical. the test should ensure the correct canonicalization):

• anchore/packageurl-go, maennchen/purl, sonatype/package-url-java parse it as postgres version 16@16.1 (split from the left instead of the right)
• giterlizzi/perl-URI-PackageURL parse it as version 16 (somehow discarding the 16.1)
• package-url/packageurl-js throws an exception (Incorrect validation of version encoding packageurl-js#57)

{
  "description": "brew names may contain at signs",
  "purl": "pkg:brew/postgres%4016",
  "canonical_purl": "pkg:brew/postgres%4016",
  "type": "brew",
  "namespace": null,
  "name": "postgres@16",
  "version": null,
  "qualifiers": null,
  "subpath": null,
  "is_invalid": false
},
{
  "description": "brew may contain multiple at signs",
  "purl": "pkg:brew/postgres@16@16.1",
  "canonical_purl": "pkg:brew/postgres%4016@16.1",
  "type": "brew",
  "namespace": null,
  "name": "postgres@16",
  "version": "16.1",
  "qualifiers": null,
  "subpath": null,
  "is_invalid": false
}

[woodruffw]

Makes sense, although the ship has since sailed on the main backing feature that I needed this for (Homebrew's build provenance feature, which instead uses Homebrew's own wheel filename format for its subject).

As such, I don't have any time allocated for this in the immediate future. I'll try and get back to it when I do have some slack time, but if it's a pressing feature for anyone in the next 1-3 months I have no objection to someone else taking ownership here.

Edit: @colindean has graciously done this 🙂

[colindean]

💪 I like this test case setup.

[colindean]

@woodruffw I got one wrong upon reviewing the unresolved comments. Please merge this suggestion.

@matt-phylum I think the rest of the comments can be resolved.

[tonylturner]

Is there an update on this issue? I came here to submit a similar issue and was glad to see this but it's been open for 9 months now. Any ETA on review?

[woodruffw]

From the perspective of the Homebrew upstream, this has been done and is ready for final review/merge since June. It'd be nice to have a repository owner to shepherd this, although I'm not exactly sure who that'd be (@pombredanne perhaps? 🙂)

[jkowalleck]

please also remove brew from the list "Other candidate types to define"

[woodruffw]

please also remove bre from the list "Other candidate types to define"

Done with f8fd63e; PTAL.

[johnmhoran]

Thank you for your PR @woodruffw. When you have the chance, could you please resolve the conflicts referred to below?

[woodruffw]

This should be good to go again thanks to @colindean -- @johnmhoran @jkowalleck PTAL

[colindean]

@johnmhoran @jkowalleck Is there any chance this can be merged in the next few days?

[jkowalleck]

Is there any chance this can be merged in the next few days?

need to do some detailed research, before i can actually approve the PR.
Sorry, will not have time for that before mid January.

[colindean]

Thanks for that timeline clarity and for the depth of review. The next great window for this would be in time for Homebrew's annual meeting on February 3.