Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add spec for brew package URLs #281

Open
wants to merge 12 commits into
base: master
Choose a base branch
from
+134 −1
Open

Add spec for brew package URLs #281

Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
5e94a65
Add spec for `brew` package URLs
woodruffw Dec 4, 2023
d1ebec9
Apply suggestions from code review
woodruffw Dec 8, 2023
9ae6363
Apply suggestions from code review
woodruffw Dec 8, 2023
ca87bdd
reflow
woodruffw Dec 8, 2023
9f288b0
Update PURL-TYPES.rst
woodruffw Dec 8, 2023
ba01dcb
more disambiguation
woodruffw Dec 8, 2023
2d0348d
Adds two Homebrew purl test cases from @matt-phylum
colindean Jun 17, 2024
0ecae1b
Adds Homebrew test cases
colindean Jun 17, 2024
7cd6265
Merge pull request #1 from colindean/colindean/brew-purl-testcases
woodruffw Jun 17, 2024
ac6e582
Update test-suite-data.json
woodruffw Jun 18, 2024
f8fd63e
PURL-TYPES: remove brew from TODO list
woodruffw Oct 17, 2024
584a4e4
Merge branch 'master' into ww/brew-purl
woodruffw Oct 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions PURL-TYPES.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,25 @@ bitnami
pkg:bitnami/wordpress@6.2.0
pkg:bitnami/wordpress@6.2.0?arch=arm64

brew
----
``brew`` for Homebrew-based packages:

- The default repository (tap) is ``homebrew/core``.
woodruffw marked this conversation as resolved.
Show resolved Hide resolved
woodruffw marked this conversation as resolved.
Show resolved Hide resolved

- The tap syntax is ``https://github.com/{org}/Homebrew-{tap}``, so
``homebrew/core`` corresponds to the URL ``https://github.com/homebrew/homebrew-core``.
woodruffw marked this conversation as resolved.
Show resolved Hide resolved
- The ``name`` is the formula name.
woodruffw marked this conversation as resolved.
Show resolved Hide resolved
- The ``version`` is the formula version.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question (non-blocking): When thinking about the examples below, I think you should clarify how purl spec should handle version-in-formula formulae.

As in, if I want PostgreSQL 12.17 (current release as of this posting), should the purl be

pkg:brew/postgresql@12@12.17

or

pkg:brew/postgresql@12.17

and let whatever's reading the purl — Homebrew, ostensibly — figure out how that version maps to our major-version formulae?

I speculate only the latter is a valid purl, a safe assumption because I don't think it's a good idea to allow two @ in the purl.

Copy link
Author

@woodruffw woodruffw Dec 8, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for calling this out -- my read of the purl spec is that the name and other components are always URL-escaped, e.g. pkg:brew/postgresql@12@12.17 would actually be encoded as pkg:brew/postgresql%4012@12.17 in a "wire format" context. So the purl should always unambiguously map to a package, without the end client having to do additional disambiguation work.

This is a readability sacrifice, but my (potentially wrong) understanding is that purls are mostly meant to show up only in machine-readable contexts anyways.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sigh, it's not pretty, but if that's the way it needs to be, so be it. If that's the case, I'd recommend adding an example with that…

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done! Looks like the other examples for other ecosystem purls also contain URL-escaping examples, so we're in-line here 🙂

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pkg:brew/postgresql@12@12.17 is incorrect. The instructions for parsing a PURL (which not all implementations follow) say to split on @ from the right, so it should parse as you expect for Homebrew, but the spec says that @ must always be escaped when it's not being used as the delimiter before the version number. It'd definitely be good to have an example and maybe even call this out since it's common for people to install packages with names like this.

giterlizzi/perl-URI-PackageURL has name "postgresql" version "12" (and discards the "12.17")

maenchen/purl, sonatype/package-url-java have name "postgresql" version "12@12.17"

package-url/packageurl-js throws an error (I thought I saw a fix for this, but maybe the PR hasn't merged)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, I added @colindean's example below. Adding an explicit callout also makes sense to me; I'll add some language for that.

- Qualifier ``tap_url``: for taps that are not on GitHub or otherwise require an explicit URL,
this is the full URL to the tap.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

- Examples::

pkg:brew/sqlite@3.43.2
woodruffw marked this conversation as resolved.
Show resolved Hide resolved
pkg:brew/homebrew/core/sqlite@3.43.2
pkg:brew/some-org/some-tap/some-app@1.2.3
pkg:brew/some-org/some-tap/some-app@1.2.3&tap_url=https://git.example.com/some-org/some-tap.git
woodruffw marked this conversation as resolved.
Show resolved Hide resolved

cocoapods
---------
``cocoapods`` for CocoaPods:
Expand Down