HPPR Command Messages

Tags: wire, command

© R.A.Sol

HPPR endpoints exchange command messages. A command service defines the command names it accepts, the request envelope it requires, and the authorization rules for each command.

A command message is a packet or packet-shaped envelope carrying:

• a command name in API
• command arguments in the Blob data or Null packet data
• service-specific identity and authorization material in the envelope

Command names that belong to HPPR itself start with 🖧, for example 🖧GET and 🖧HELLO.

Null Command Packets

The sentinel hash 0.H3 is never computed or verified.

Use 0.H3 for:

• generic 🖧HELLO request and response packets
• error responses
• trusted local command envelopes where a service explicitly accepts them

Null packets are never stored in repository storage.

🖧: 0.H3
[Header: value]*
Data-Length: <len>

<data>

Header rules follow 010 for format, encoding, control bytes, line endings, and line length. Differences from Plex:

• Any header name is allowed.
• Required Plex header order does not apply.
• Header count max is 512.
• Data-Length is the final header before the blank line.
• Data max is 34 MiB (32 MiB payload + 2 MiB envelope overhead).

Command Services

A command service chooses:

• the command names it accepts
• the command flows it exposes (031)
• the accepted request envelope for each flow
• the success response shape
• which commands enter a streaming result mode
• the authorization rules for each command

The HPPR Repository Service defines the standard repository command set in 041.

HELLO Command

🖧HELLO requests command-flow capabilities and endpoint metadata.

A transport MAY deliver equivalent greeting metadata earlier in connection setup. The 🖧HELLO command remains the generic capability query and refresh operation when the endpoint accepts it.

The generic Null HELLO request is:

🖧: 0.H3
API: 🖧HELLO
Data-Length: 0

HELLO response headers are defined in 032.

Errors

Generic network errors are Null packets. Data starts with one status line:

• ERROR <TYPE> <detail> keeps the connection open
• FATAL <TYPE> <detail> closes the connection

Trusted or local endpoints MAY add Status: ok|error|fatal as an endpoint convention. Clients may use Status when present, but parsing the ERROR or FATAL data prefix is the generic error rule.

Standard generic error types:

• NOT_FOUND
• FORBIDDEN
• TOO_LARGE
• INVALID
• INTERNAL

Services MAY define additional error types and details.

Example:

🖧: 0.H3
Data-Length: 21

ERROR NOT_FOUND missing