HPPR Command Flows

Tags: wire, command-flow

© R.A.Sol

A command flow defines how an endpoint accepts HPPR command messages.

The command name says what operation is requested. The command flow says how the request is framed, what state the endpoint may rely on, and what result modes are available.

Envelope and Principal

Each command flow has an accepted request envelope. The envelope is the packet shape that carries the command and its arguments.

A service interprets the envelope to produce a command principal. The principal is the identity or capability used for authorization. The flow defines the state available to validate the envelope; the service defines what the resulting principal means.

Session Command Flow

The session command flow has connection-local state.

It uses 🖧HELLO or transport handshake metadata to create connection-local binding state, then requires a session-bound request envelope for every non-HELLO command.

A session flow is the right fit when:

• replay resistance depends on connection state
• a command needs an authenticated principal
• a stream command continues after its initial request packet

Message Command Flow

The message command flow accepts one complete HPPR request message and returns one complete HPPR response message. It has no connection-local session state.

A message-flow request does not rely on prior per-connection 🖧HELLO state. Message requests are replayable unless the service’s accepted envelope adds its own replay rule.

A message flow is the right fit when:

• a public read can stand alone
• an object-capability endpoint treats possession of the endpoint as authority
• a transport such as HTTP or UDP carries one independent exchange

Result Modes

A command’s result mode describes what happens after the request envelope is accepted. The five modes below are the generic vocabulary used by command specs, including streaming commands.

Single-response packet

The endpoint reads one request packet and returns one response packet.

Most commands use this mode.

Acknowledged stream

The endpoint returns an initial success response, then keeps the connection open and writes a command-defined stream.

Repository 🖧WATCH uses this mode.

Negotiated raw packet exchange

The endpoint returns a negotiation response. Both peers then transfer raw packet bytes according to the command’s negotiated plan.

Repository 🖧EXCHANGE uses this mode.

Relay mode after response

The endpoint returns an initial success response, then treats the rest of the connection as command-defined relay bytes.

Repository 🖧STREAM_PUB uses this mode.

Relay mode without response

The endpoint accepts the request and immediately treats the connection as command-defined relay output, with no success response packet.

Repository 🖧STREAM_SUB uses this mode.

Generic Rules

• the flow’s accepted envelope defines the request shape and response mapping
• the service defines command availability
• stream commands are available only when the service and flow explicitly accept the command’s result mode
• transports such as HTTP and UDP MAY expose message flow

The HPPR Repository Service defines concrete repository envelopes and flow behavior in 042, 043, and 044.