-
Notifications
You must be signed in to change notification settings - Fork 163
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.
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
Add spec for brew package URLs
#281
Open
woodruffw
wants to merge
12
commits into
package-url:master
Choose a base branch
from
trail-of-forks:ww/brew-purl
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+134
−1
Open
Changes from 9 commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
5e94a65
Add spec for `brew` package URLs
woodruffw d1ebec9
Apply suggestions from code review
woodruffw 9ae6363
Apply suggestions from code review
woodruffw ca87bdd
reflow
woodruffw 9f288b0
Update PURL-TYPES.rst
woodruffw ba01dcb
more disambiguation
woodruffw 2d0348d
Adds two Homebrew purl test cases from @matt-phylum
colindean 0ecae1b
Adds Homebrew test cases
colindean 7cd6265
Merge pull request #1 from colindean/colindean/brew-purl-testcases
woodruffw ac6e582
Update test-suite-data.json
woodruffw f8fd63e
PURL-TYPES: remove brew from TODO list
woodruffw 584a4e4
Merge branch 'master' into ww/brew-purl
woodruffw File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -87,6 +87,32 @@ bitnami | |
| pkg:bitnami/[email protected] | ||
| pkg:bitnami/[email protected]?arch=arm64 | ||
|
|
||
| brew | ||
| ---- | ||
| ``brew`` for Homebrew-based packages: | ||
|
|
||
| - There is no default package repository; this should be implied either from | ||
| the ``namespace`` or using a tap URL via the ``tap_url`` qualifier. | ||
| - The ``namespace``, which is called a "Tap" in Homebrew terminology, defaults to ``homebrew/core``. | ||
|
|
||
| - When the ``tap_url`` qualifier is not specified, the Tap identifier corresponds to the URL | ||
| ``https://github.com/{org}/homebrew-{tap}``, such as | ||
| ``https://github.com/homebrew/homebrew-core`` for ``homebrew/core``. | ||
| - When the ``tap_url`` qualifier is specified, the Tap identifier is the local name of the Tap. | ||
|
|
||
| - The ``name`` is the formula name. Formula names that contain ``@`` must be percent-encoded, | ||
| such as ``postgresql%4012`` for ``postgres@12``. | ||
| - The ``version`` is the formula version. | ||
| - Qualifier ``tap_url``: for taps that are not on GitHub or otherwise require an explicit URL, | ||
| this is the full ``git`` URL to the tap. | ||
| - Examples:: | ||
|
|
||
| pkg:brew/[email protected] | ||
woodruffw marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| pkg:brew/postgresql%[email protected] | ||
| pkg:brew/homebrew/core/[email protected] | ||
| pkg:brew/some-org/some-tap/[email protected] | ||
| pkg:brew/some-org/some-tap/[email protected]?tap_url=https://git.example.com/some-org/some-tap.git | ||
|
|
||
| cocoapods | ||
| --------- | ||
| ``cocoapods`` for CocoaPods: | ||
|
|
||
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -550,5 +550,113 @@ | |
| "qualifiers": null, | ||
| "subpath": null, | ||
| "is_invalid": false | ||
| }, | ||
| { | ||
| "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@[email protected]", | ||
| "canonical_purl": "pkg:brew/postgres%[email protected]", | ||
| "type": "brew", | ||
| "namespace": null, | ||
| "name": "postgres@16", | ||
| "version": "16.1", | ||
| "qualifiers": null, | ||
| "subpath": null, | ||
| "is_invalid": false | ||
| }, | ||
| { | ||
| "description": "brew may specify a namespace that uses the Homebrew default tap lookup mechanism", | ||
| "purl": "pkg:brew/some-org/some-tap/[email protected]?tap_url=https://git.example.com/some-org/some-tap.git", | ||
| "canonical_purl": "pkg:brew/some-org/some-tap/[email protected]?tap_url=https://git.example.com/some-org/some-tap.git", | ||
| "type": "brew", | ||
| "namespace": "https://git.example.com/some-org/some-tap.git", | ||
woodruffw marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "name": "sqlite", | ||
| "version": "3.43.2", | ||
| "qualifiers": { "tap_url": "https://git.example.com/some-org/some-tap.git"}, | ||
| "subpath": null, | ||
| "is_invalid": false | ||
| }, | ||
| { | ||
| "description": "brew may specify a namespace that uses the Homebrew default tap lookup mechanism", | ||
| "purl": "pkg:brew/some-org/some-tap/[email protected]", | ||
| "canonical_purl": "pkg:brew/some-org/some-tap/[email protected]", | ||
| "type": "brew", | ||
| "namespace": "some-org/some-tap", | ||
| "name": "sqlite", | ||
| "version": "3.43.2", | ||
| "qualifiers": null, | ||
| "subpath": null, | ||
| "is_invalid": false | ||
| }, | ||
| { | ||
| "description": "brew may specify a namespace that is its default repository", | ||
| "purl": "pkg:brew/homebrew/core/[email protected]", | ||
| "canonical_purl": "pkg:brew/homebrew/core/[email protected]", | ||
| "type": "brew", | ||
| "namespace": "homebrew/core", | ||
| "name": "sqlite", | ||
| "version": "3.43.2", | ||
| "qualifiers": null, | ||
| "subpath": null, | ||
| "is_invalid": false | ||
| }, | ||
| { | ||
| "description": "brew typical formula", | ||
| "purl": "pkg:brew/[email protected]", | ||
| "canonical_purl": "pkg:brew/[email protected]", | ||
| "type": "brew", | ||
| "namespace": null, | ||
| "name": "sqlite", | ||
| "version": "3.43.2", | ||
| "qualifiers": null, | ||
| "subpath": null, | ||
| "is_invalid": false | ||
| }, | ||
| { | ||
| "description": "invalid brew purl without name", | ||
| "purl": "pkg:brew/@0.9.1", | ||
| "canonical_purl": "pkg:brew/@0.9.1", | ||
| "type": "brew", | ||
| "namespace": null, | ||
| "name": null, | ||
| "version": "0.9.1", | ||
| "qualifiers": null, | ||
| "subpath": null, | ||
| "is_invalid": true | ||
| }, | ||
| { | ||
| "description": "invalid brew purl without version", | ||
| "purl": "pkg:brew/A3", | ||
| "canonical_purl": "pkg:brew/A3", | ||
| "type": "brew", | ||
| "namespace": null, | ||
| "name": "A3", | ||
| "version": null, | ||
| "qualifiers": null, | ||
| "subpath": null, | ||
| "is_invalid": true | ||
| }, | ||
| { | ||
| "description": "brew requires name and version at minimum", | ||
| "purl": "pkg:brew", | ||
| "canonical_purl": "pkg:brew", | ||
| "type": "brew", | ||
| "namespace": null, | ||
| "name": null, | ||
| "version": null, | ||
| "qualifiers": null, | ||
| "subpath": null, | ||
| "is_invalid": true | ||
| } | ||
| ] | ||
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.
There was a problem hiding this comment.
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
or
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.There was a problem hiding this comment.
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@[email protected]would actually be encoded aspkg:brew/postgresql%[email protected]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.
There was a problem hiding this comment.
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…
There was a problem hiding this comment.
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 🙂
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
pkg:brew/postgresql@[email protected]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 "[email protected]"
package-url/packageurl-js throws an error (I thought I saw a fix for this, but maybe the PR hasn't merged)
There was a problem hiding this comment.
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.