Unified Resource Coordinate

Tags: packet, addressing

HPPR supports two address forms:

by hash: ////<hash>
by coordinate: //<group>/<api>//<key>

Hash addresses are immutable. Coordinate addresses are time-dependent and may resolve to different packets as new packets are stored.

A versioned coordinate pins one exact packet.

Terms

API: the application-facing protocol surface in Plex or Seal packets.
Key: the durable record, document, object, stream, or path inside an API.
Coordinate: a string prefixed with //: //<group>/<api>//<key>.

Coordinate Syntax

Coordinate form:

//<group>/<api>//<key>

Rules:

<group> is one path segment.
<api> is one or more slash-separated non-empty segments.
<key> is one or more slash-separated non-empty segments.
The first // starts the coordinate.
The second // separates API from Key.
The delimiter is coordinate syntax. It is not stored in the API or Key header values.

Examples:

Coordinate	Group	API	Key
`//u/docs//index.html`	`u`	`docs`	`index.html`
`//lab.eu/chat/message//room-7/1`	`lab.eu`	`chat/message`	`room-7/1`
`//lab.eu/chat//message/room-7/1`	`lab.eu`	`chat`	`message/room-7/1`

The API/Key boundary is a design choice. API names should be finite, developer-defined protocol surfaces. Key names may be unbounded, data-defined, or instance-specific.

Version Selectors

Multiple packets can share one coordinate. Add /|/... to select a version.

Top-coordinate: no |, resolves to the latest packet. Example: //g/a//k
Versioned-coordinate: includes type path, TAI, and hash. Example: //g/a//k/|/plex/<tai>/<hash>

Example

Packet:

🖧: P.EXAMPLE~HASH~EXAMPLE~HASH~EXAMPLE~HASH~EX.H3
Group: a-group
API: some-api
Key: our-collection/item
TAI: 1640995200:123000000
...

Addresses:

Direct hash: ////P.EXAMPLE~HASH~EXAMPLE~HASH~EXAMPLE~HASH~EX.H3
Top-coordinate: //a-group/some-api//our-collection/item
Versioned-coordinate: //a-group/some-api//our-collection/item/|/plex/ 1640995200:123000000/ P.EXAMPLE~HASH~EXAMPLE~HASH~EXAMPLE~HASH~EX.H3

Get resolution

In the tables below, <key> is the Key header value and does not end with /. The <api> value does not end with /.

The tip is the latest packet at a coordinate. Tie-break order is highest TAI, then highest hash.

Path	Gets
`//<group>/<api>//<key>`	tip
`//<group>/<api>//<key>/`	tip
`//<group>/<api>//<key>/\|`	tip
`//<group>/<api>//<key>/\|/plex`	Plex tip
`//<group>/<api>//<key>/\|/plex/<tai>`	Plex tip at `tai`
`//<group>/<api>//<key>/\|/plex/<tai>/<hash>`	exact Plex
`//<group>/<api>//<key>/\|/seal`	Seal tip
`//<group>/<api>//<key>/\|/seal/<verifier>`	Seal tip for signer
`//<group>/<api>//<key>/\|/seal/<verifier>/<tai>`	signer Seal tip at `tai`
`//<group>/<api>//<key>/\|/seal/<verifier>/<tai>/<hash>`	exact Seal

List resolution

LIST operates over two trees: the API tree and the Key tree for one exact API.

Path	Lists
`//<group>/`	top-level API segments
`//<group>/<api>/`	API child segments, plus `//` when Key tree exists for exact API
`//<group>/<api>//`	Key roots for exact API
`//<group>/<api>//<key>/`	Key children, plus `\|/` when present
`//<group>/<api>//<key>/\|/`	`plex/` and or `seal/`
`//<group>/<api>//<key>/\|/plex/`	TAIs
`//<group>/<api>//<key>/\|/plex/<tai>/`	hashes
`//<group>/<api>//<key>/\|/seal/`	signer verification values
`//<group>/<api>//<key>/\|/seal/<verifier>/`	TAIs
`//<group>/<api>//<key>/\|/seal/<verifier>/<tai>/`	hashes

The // child in API listings is a boundary marker. It means packets exist under the exact API and their Key roots can be listed with //<group>/<api>//.

Parsing

Parsers MUST treat hash addressing as a separate branch before coordinate parsing.

hash-address = "////" hash-text
coordinate = "//" group "/" api "//" key [version-selector]

////<hash> is a hash address.
//<group>/<api>//<key> is a coordinate.

Reject malformed coordinates including:

missing API/Key delimiter: //g/api/key
empty API: //g//key
empty Key: //g/api//
extra API/Key delimiter inside Key: //g/api//key//extra

| is forbidden in API and Key segments, so /|/ unambiguously starts version selection.