Source specifiers

Grammar and resolution of the strings rig use, rig inspect, and rig hub update accept.

A source specifier is the argument to rig use and rig inspect.

Grammar

<source> := <hub-source>
          | <github-source>
          | <registry-source>
          | <local-source>

<hub-source>      := "hub:"  <author> "/" <name> [ "@" <version> ]
<github-source>   := "github:" <user> "/" <repo> [ "@" <tag> ]
<registry-source> := "registry:" <author> "/" <name> [ "@" <version> ]
<local-source>    := ( "./" | "/" ) <path-to-rig-tgz>

Resolution table

Source	Resolves to	Verification
`hub:a/n`	latest version of `a/n` on the Hub	SHA-256 from `X-Rig-SHA256` response header
`hub:a/n@v`	specific version	SHA-256
`github:u/r`	latest release; first `.rig.tgz` asset	none
`github:u/r@t`	release tagged `t`	none
`registry:a/n`	latest version per `index.json`	SHA-256 from `index.json`
`registry:a/n@v`	specific version per `index.json`	SHA-256
`./path.rig.tgz`	local file	none
`/abs/path.rig.tgz`	local file	none

Hub HTTP endpoints used

For hub:a/n[@v]:

GET  {RIG_HUB_URL}/api/v1/packages/{a}/{n}                       # metadata
GET  {RIG_HUB_URL}/api/v1/packages/{a}/{n}/{v}/artifact          # download

{RIG_HUB_URL} defaults to https://userig.xyz. Override via the RIG_HUB_URL env var.

Local registry layout

For registry:a/n[@v]:

{RIG_REGISTRY_DIR}/index.json
{RIG_REGISTRY_DIR}/blobs/{a}__{n}__{v}.rig.tgz

{RIG_REGISTRY_DIR} is set by the RIG_REGISTRY_DIR env var or via a CLI flag.

Version omitted

If @<version> is omitted, the resolver picks the latest stable:

hub: — latest from the Hub's metadata.
github: — latest release per GitHub's API.
registry: — highest semver in index.json excluding pre-releases.

Pre-releases (e.g. 1.0.0-alpha.1) are only chosen when explicitly named with @.

Errors

Error	Cause
`Unknown source scheme`	None of the supported prefixes matched.
`Package not found`	Hub or registry has no `a/n`.
`Version not found`	The requested `@v` isn't in the index.
`SHA256 mismatch`	The downloaded blob's hash doesn't match the expected.
`Artifact missing from release`	`github:` source's release has no `.rig.tgz` asset.