urn: add URN parser and helpers

.github/codecov.yaml

@@ -1,6 +1,7 @@
 ignore:
 - "test"  # Our test helpers largely do not have tests themselves.
 - "**/*_string.go"  # Ignore generated string implementations.
+- "toolkit/urn/parser.go"  # Generated file
 
 coverage:
   status:

toolkit/urn/.gitignore

@@ -0,0 +1 @@
+*.ri

toolkit/urn/compliance_test.go

@@ -0,0 +1,119 @@
+package urn
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestCompliance(t *testing.T) {
+	t.Run("Valid", func(t *testing.T) {
+		t.Run("Basic", parseOK(`urn:test:test`))
+		t.Run("NID", parseOK(`urn:test-T-0123456789:test`))
+		t.Run("NSS", parseOK(`urn:test:Test-0123456789()+,-.:=@;$_!*'`))
+	})
+	t.Run("Invalid", func(t *testing.T) {
+		t.Run("NID", func(t *testing.T) {
+			t.Run("TooLong", parseErr(`urn:`+strings.Repeat("a", 33)+`:test`))
+			t.Run("BadChars", parseErr(`urn:test//notOK:test`))
+			t.Run("None", parseErr(`urn::test`))
+			t.Run("HyphenStart", parseErr(`urn:-nid:test`))
+			t.Run("HyphenEnd", parseErr(`urn:nid-:test`))
+		})
+		t.Run("NSS", func(t *testing.T) {
+			t.Run("BadChar", parseErr("urn:test:null\x00null"))
+		})
+	})
+	t.Run("Equivalence", func(t *testing.T) {
+		// These test cases are ported out of the RFC.
+		t.Run("CaseInsensitive", allEqual(`urn:example:a123,z456`, `URN:example:a123,z456`, `urn:EXAMPLE:a123,z456`))
+		t.Run("Component", allEqual(`urn:example:a123,z456`, `urn:example:a123,z456?+abc`, `urn:example:a123,z456?=xyz`, `urn:example:a123,z456#789`))
+		t.Run("NSS", allNotEqual(`urn:example:a123,z456`, `urn:example:a123,z456/foo`, `urn:example:a123,z456/bar`, `urn:example:a123,z456/baz`))
+		t.Run("PercentDecoding", func(t *testing.T) {
+			p := []string{`urn:example:a123%2Cz456`, `URN:EXAMPLE:a123%2cz456`}
+			allEqual(p...)(t)
+			for _, p := range p {
+				allNotEqual(`urn:example:a123,z456`, p)(t)
+			}
+		})
+		t.Run("CaseSensitive", allNotEqual(`urn:example:a123,z456`, `urn:example:A123,z456`, `urn:example:a123,Z456`))
+		t.Run("PercentEncoding", func(t *testing.T) {
+			allNotEqual(`urn:example:a123,z456`, `urn:example:%D0%B0123,z456`)(t)
+			allEqual(`urn:example:а123,z456`, `urn:example:%D0%B0123,z456`)(t) // NB that's \u0430 CYRILLIC SMALL LETTER A
+		})
+	})
+}
+
+func parseOK(s string) func(*testing.T) {
+	u, err := Parse(s)
+	return func(t *testing.T) {
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, err := u.R(); err != nil {
+			t.Error(err)
+		}
+		if _, err := u.Q(); err != nil {
+			t.Error(err)
+		}
+	}
+}
+func parseErr(s string) func(*testing.T) {
+	u, err := Parse(s)
+	return func(t *testing.T) {
+		t.Log(err)
+		if err != nil {
+			// OK
+			return
+		}
+		if _, err := u.R(); err == nil {
+			t.Fail()
+		}
+		if _, err := u.Q(); err == nil {
+			t.Fail()
+		}
+	}
+}
+func allEqual(s ...string) func(*testing.T) {
+	var err error
+	u := make([]URN, len(s))
+	for i, s := range s {
+		u[i], err = Parse(s)
+		if err != nil {
+			break
+		}
+	}
+	return func(t *testing.T) {
+		if err != nil {
+			t.Fatal(err)
+		}
+		for i := range u {
+			for j := range u {
+				if !(&u[i]).Equal(&u[j]) {
+					t.Errorf("%v != %v", &u[i], &u[j])
+				}
+			}
+		}
+	}
+}
+func allNotEqual(s ...string) func(*testing.T) {
+	var err error
+	u := make([]URN, len(s))
+	for i, s := range s {
+		u[i], err = Parse(s)
+		if err != nil {
+			break
+		}
+	}
+	return func(t *testing.T) {
+		if err != nil {
+			t.Fatal(err)
+		}
+		for i := range u {
+			for j := range u {
+				if i != j && (&u[i]).Equal(&u[j]) {
+					t.Errorf("%v == %v", &u[i], &u[j])
+				}
+			}
+		}
+	}
+}

toolkit/urn/escape.go

@@ -0,0 +1,50 @@
+package urn
+
+// These functions are adapted out of the net/url package.
+//
+// URNs have slightly different rules.
+
+// Copyright 2009 The Go Authors.
+
+const upperhex = "0123456789ABCDEF"
+
+// Escape only handles non-ASCII characters and leaves other validation to the
+// parsers.
+func escape(s string) string {
+	ct := 0
+	for i := 0; i < len(s); i++ {
+		c := s[i]
+		if c > 0x7F {
+			ct++
+		}
+	}
+
+	if ct == 0 {
+		return s
+	}
+
+	var buf [64]byte
+	var t []byte
+
+	required := len(s) + 2*ct
+	if required <= len(buf) {
+		t = buf[:required]
+	} else {
+		t = make([]byte, required)
+	}
+
+	j := 0
+	for i := 0; i < len(s); i++ {
+		switch c := s[i]; {
+		case c > 0x7F:
+			t[j] = '%'
+			t[j+1] = upperhex[c>>4]
+			t[j+2] = upperhex[c&15]
+			j += 3
+		default:
+			t[j] = s[i]
+			j++
+		}
+	}
+	return string(t)
+}

toolkit/urn/generate.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+set -e
+
+for cmd in ragel-go gofmt sed; do
+	if ! command -v "$cmd" >/dev/null 2>&1; then
+		printf 'missing needed command: %s\n' "$cmd" >&2
+		exit 99
+	fi
+done
+
+ragel-go -s -p -F1 -o _parser.go parser.rl
+trap 'rm _parser.go' EXIT
+{
+	printf '// Code generated by ragel-go DO NOT EDIT.\n\n'
+	gofmt -s _parser.go
+} > parser.go

toolkit/urn/name.go

@@ -0,0 +1,46 @@
+package urn
+
+import (
+	"net/url"
+	"strings"
+)
+
+// Name is a claircore name.
+//
+// Names are expected to be unique within a claircore system and comparable
+// across instances. Names are hierarchical, moving from least specific to most
+// specific.
+//
+// Any pointer fields are optional metadata that may not exist depending on the
+// (System, Kind) pair.
+type Name struct {
+	// System scopes to a claircore system or "mode", such as "indexer" or
+	// "updater".
+	System string
+	// Kind scopes to a specific type of object used within the System.
+	Kind string
+	// Name scopes to a specific object within the system.
+	Name string
+	// Version is the named object's version.
+	//
+	// Versions can be ordered with a lexical sort.
+	Version *string
+}
+
+// String implements fmt.Stringer.
+func (n *Name) String() string {
+	v := url.Values{}
+	if n.Version != nil {
+		v.Set("version", *n.Version)
+	}
+	u := URN{
+		NID: `claircore`,
+		NSS: strings.Join(
+			[]string{n.System, n.Kind, n.Name},
+			":",
+		),
+		q: v.Encode(),
+	}
+
+	return u.String()
+}

toolkit/urn/name_test.go

@@ -0,0 +1,107 @@
+package urn
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+)
+
+func TestName(t *testing.T) {
+	version := "1"
+	tt := []struct {
+		In   string
+		Want Name
+	}{
+		// Weird cases first:
+		{
+			In: "urn:claircore:indexer:package:test?=version=1&version=999",
+			Want: Name{
+				System:  "indexer",
+				Kind:    "package",
+				Name:    "test",
+				Version: &version,
+			},
+		},
+		{
+			In: "urn:claircore:indexer:package:test",
+			Want: Name{
+				System: "indexer",
+				Kind:   "package",
+				Name:   "test",
+			},
+		},
+		{
+			In: "urn:claircore:indexer:package:test?+resolve=something",
+			Want: Name{
+				System: "indexer",
+				Kind:   "package",
+				Name:   "test",
+			},
+		},
+		{
+			In: "urn:claircore:indexer:package:test#some_anchor",
+			Want: Name{
+				System: "indexer",
+				Kind:   "package",
+				Name:   "test",
+			},
+		},
+
+		// Some other exhaustive cases:
+		{
+			In: "urn:claircore:indexer:repository:test?=version=1",
+			Want: Name{
+				System:  "indexer",
+				Kind:    "repository",
+				Name:    "test",
+				Version: &version,
+			},
+		},
+		{
+			In: "urn:claircore:indexer:distribution:test?=version=1",
+			Want: Name{
+				System:  "indexer",
+				Kind:    "distribution",
+				Name:    "test",
+				Version: &version,
+			},
+		},
+		{
+			In: "urn:claircore:matcher:vulnerability:test?=version=1",
+			Want: Name{
+				System:  "matcher",
+				Kind:    "vulnerability",
+				Name:    "test",
+				Version: &version,
+			},
+		},
+		{
+			In: "urn:claircore:matcher:enrichment:test?=version=1",
+			Want: Name{
+				System:  "matcher",
+				Kind:    "enrichment",
+				Name:    "test",
+				Version: &version,
+			},
+		},
+	}
+
+	for _, tc := range tt {
+		t.Logf("parse: %q", tc.In)
+		u, err := Parse(tc.In)
+		if err != nil {
+			t.Error(err)
+			continue
+		}
+		got, err := u.Name()
+		if err != nil {
+			t.Error(err)
+			continue
+		}
+		want := tc.Want
+		t.Logf("name:  %q", got.String())
+		if !cmp.Equal(&got, &want) {
+			t.Error(cmp.Diff(&got, &want))
+		}
+	}
+}