5.36 URL Conventions

4 min read

Every URL in this chapter maps to a static file. The protocol requires no server-side computation, no dynamic response, and no content negotiation beyond optional HTTP-level compression.

5.36.1 The repository base #

A repository is identified by a base URL, <repo-base>.

The base URL MUST be a syntactically valid HTTP or HTTPS URL per RFC 3986, and MUST NOT have a trailing slash: the well-known relative paths below are appended directly.

HTTPS MUST be used, unless the consumer has been configured with an explicit per-repository insecure-transport allowance. There is no global form of that allowance, and its use MUST generate a per-operation warning.

Enabling the allowance on a repository that has already been added MUST require explicit operator authorisation and MUST emit an audit event. Setting it as part of the initial add is covered by the operator's trust decision at that moment and requires no separate event beyond the add's own.

A consumer MAY additionally support a file:// base URL for local development. A file:// repository MUST be subject to the same per-repository allowance as an HTTP one: it is not HTTPS, and admitting it silently makes removable or network-mounted media a trusted source without the operator ever acknowledging it.

5.36.2 Conventional paths #

A repository SHOULD use these paths unless it has a reason not to; when it does not, the descriptor declares the ones it uses. A consumer that knows only <repo-base> MUST be able to locate repo.json at the conventional path. The descriptor carries the URLs for everything else.

5.36.3 Package URLs #

<repo-base>/p/<name>/<version>/<filename>

where <name> conforms to §5.3, <version> is the full version string of §5.5, and <filename> is <name>_<version>_<architecture>.peipkg.

https://pkgs.peios.org/p/nginx/1.26.2-3/nginx_1.26.2-3_x86_64.peipkg

5.36.4 Sibling artifacts #

The directory containing a package file MAY hold additional siblings for that version. These are reserved for future use and are not normative here:

<repo-base>/p/<name>/<version>/<filename>.debug.peipkg
<repo-base>/p/<name>/<version>/<filename>.sbom.json
<repo-base>/p/<name>/<version>/<filename>.attestation.json

A consumer conforming to this version MUST NOT attempt to fetch a sibling artifact. A producer MAY publish them; their meaning is defined by a future version.

5.36.5 Relative URLs #

A URL field in a descriptor or an index MAY be absolute or relative.

• An absolute URL, carrying a scheme, is used as-is.
• A URL beginning with / is resolved against <repo-base> by prepending the base.
• A URL with neither a scheme nor a leading / is resolved against the URL of the document containing the reference, per RFC 3986 §5.

5.36.6 Hosting #

A conformant repository may be hosted on a plain HTTP server, an object store with an HTTP frontend, a static site host, a CDN in front of any of those, or a combination — descriptor and indexes on a static host, package files on object storage behind redirects.

5.36.7 Network failure #

A consumer that fails to fetch a URL MUST NOT silently fall back to outdated cached data. Using a stale cache without explicit operator consent can mask substituted content or a revoked-key update.

A consumer SHOULD offer a way to configure cache-staleness tolerance per repository.

A consumer whose cached index for a configured repository fails to load or verify MUST treat that as a failure of the operation rather than proceeding without that repository.

Edit this page