HPPR HELLO and Endpoint Metadata

Tags: wire, command-flow, metadata

© R.A.Sol

🖧HELLO returns endpoint metadata. It tells the client which command flow this endpoint uses, which commands are accepted on that flow, and which other transport endpoints are reachable.

The generic HELLO request packet is defined in 030.

HELLO Response Shape

A HELLO response is a Null packet:

🖧: 0.H3
Command-Flow: session|message
[Session-Commands: <command-entry> *( " | " <command-entry> )]*
[Message-Commands: <command-entry> *( " | " <command-entry> )]*
[Allow-Null-Command: 0|1]
[Transport: <via> [hints...]]*
[Header: value]*
Data-Length: 0

Other HELLO headers are endpoint-specific or service-specific. The HPPR Repository Service adds repository fields such as Session-ID, Repo-Name, Seal-By, and PHC in 043 and 044.

Command-Flow

Command-Flow names the command execution flow advertised by this HELLO response.

Known values:

Rules:

• Command-Flow appears at most once.
• value is exactly session or message.
• session means connection-local session state exists and non-HELLO commands use a session-bound request envelope.
• message means one complete request message returns one complete response message and no connection-local session binding is used.

Command Capability Headers

Command capability uses flow-specific command-list headers:

Session-Commands: 🖧GET 1 | 🖧STORE 1 | 🖧WATCH 1
Message-Commands: 🖧HELLO 1 | 🖧GET 1 | 🖧INGEST 1

Rules:

• A session-flow HELLO emits Session-Commands and does not need Message-Commands.
• A message-flow HELLO emits Message-Commands and does not need Session-Commands.
• A HELLO response does not use command-list headers to describe commands on another transport endpoint. Clients query that endpoint’s own HELLO if they need exact command support there.
• Each command-list header appears zero or more times only if line splitting is needed; normal output uses one header.
• Header value is a | separated list of command entries.
• A command entry format is <command> <version> [options...].
• Future per-command options append inside that command entry.
• Duplicate command names within the selected command list are invalid.
• Option tokens in command-list headers MUST NOT contain the exact separator string |.
• Unknown option tokens are ignored by clients that do not understand them.
• Malformed command entries make the HELLO capability advertisement invalid.

Formal grammar:

Session-Commands = command-entry *( " | " command-entry )
Message-Commands = command-entry *( " | " command-entry )
command-entry = command-name SP version *(SP option)
version = non-empty base-10 integer
option = non-empty token without SP or the literal separator " | "

Allow-Null-Command

Allow-Null-Command is a boolean capability for trusted local command envelopes.

Rules:

• absent means 0.
• Allow-Null-Command controls non-HELLO Null command request packets.
• Generic Null 🖧HELLO remains the discovery request for endpoints that support HELLO, even when Allow-Null-Command is absent or 0.
• 1 means the endpoint accepts trusted local Null command request packets for non-HELLO commands.
• This capability is for local object-capability endpoints, not public network repository listeners.
• Allow-Null-Command is independent of Command-Flow; a local object endpoint can still run message flow.

Transport

Transport advertises reachable transport endpoints:

Transport: tcp:4777 flow=session
Transport: quib:4776 flow=session
Transport: ws:4778 flow=session
Transport: http:4778 flow=message path=/hppr
Transport: udp:4777 flow=message

Rules:

• first token is always the via string or transport endpoint.
• following tokens are transport hints.
• known flow hints are flow=session and flow=message.
• HTTP path is written as path=<absolute-path>.
• path= applies only to HTTP unless another transport spec defines it.
• unknown hints are ignored.
• flow hints describe the command flow reachable at that transport endpoint, not the current endpoint.
• hostless transport forms are resolved against the already-known host as in 033.

Common Endpoint Headers

The following headers are common conventions. Services define whether they are required for that service.