HPPR Replication and Streams

Tags: repo, command, streaming

© R.A.Sol

Repository replication and live streams are repository commands with streaming result modes from 031.

• 🖧EXCHANGE uses negotiated raw packet exchange
• 🖧STREAM_PUB uses relay mode after response
• 🖧STREAM_SUB uses relay mode without response

🖧EXCHANGE

🖧EXCHANGE synchronizes packets while preserving repository policy decisions. It has three phases:

1. announce
2. transfer
3. finalize

Phase 1: Announce

Requester sends up to 1024 LF-separated lines:

NEED <versioned-coordinate>
HAVE <versioned-coordinate>

Responder returns FIN or PENDING followed by status lines:

SEND <coord>
DENY <coord>
RECV <coord>
HAVE <coord>

Status meanings:

• SEND: responder will send this packet
• DENY: denied by repository policy
• RECV: responder wants this packet from requester
• HAVE: responder already has this packet

Phase 2: Transfer

Both peers stream raw packets concurrently in both directions.

Implementations MUST perform bidirectional I/O concurrently. Unidirectional blocking can deadlock the exchange.

Packet boundaries are parsed using Data-Length.

Phase 3: Finalize

When Phase 1 returned PENDING, the responder reports final results for the coordinates that entered Phase 2 transfer (SEND and RECV items):

FIN
OK <coord>
FAIL <coord> <type> <msg>

Phase 1 HAVE and DENY items are already terminal negotiation results and do not appear in Phase 3. OK means the Phase 2 action for that coordinate completed: for SEND, the responder wrote the packet bytes; for RECV, the responder received, validated, and stored the matching packet. FAIL is only used for receive/store failures after a RECV, for example invalid received packet, coordinate mismatch, hash mismatch, storage failure, or stream EOF before the expected packet arrived.

A responder MUST NOT skip a packet promised by Phase 1 SEND and report that missing packet as Phase 3 FAIL. Clients count exact raw Phase 2 packets after SEND; a missing raw packet would make the Phase 3 response packet ambiguous. If a responder cannot write a promised SEND packet, it MUST fail the exchange at the connection level, for example with a FATAL error or close.

Repository Authorization in Phase 1

Authorization for NEED and HAVE is repository-service behavior.

The HPPR Repository Service applies the following ACL rules in Phase 1.

For NEED <coord>:

1. check read
2. if readable and exists: SEND
3. else: DENY

For HAVE <coord>:

1. check read
2. if denied: DENY
3. if allowed and exists: HAVE
4. if missing, check write
5. if writable: RECV
6. else: DENY

Blob-Addressed 🖧EXCHANGE

🖧EXCHANGE also accepts blob hash addressing:

NEED ////B.<hash>.H3
HAVE ////B.<hash>.H3

Rules:

• only B. hashes are valid
• P. and S. in blob-addressed mode are FATAL invalid requests
• additional authorization rules are service-specific
• the HPPR Repository Service applies no ACL checks in this mode
• the HPPR Repository Service allows any authenticated session to request blob hash sync

Decision rules:

• NEED: blob exists => SEND, else DENY
• HAVE: blob exists => HAVE, else RECV

Transfer still uses full raw blob packets.

🖧STREAM_PUB

🖧STREAM_PUB ingests live trailer-format Seal segments.

Request:

• API: 🖧STREAM_PUB
• data: <coordinate-prefix>

Response:

• sealed OK

After OK, connection enters relay mode and accepts trailer segments.

Per segment:

1. relay bytes to matching 🖧STREAM_SUB subscribers
2. detect segment close marker
3. verify hash and signature
4. store packet
5. emit 🖧WATCH event

Authorization is repository-service behavior. The HPPR Repository Service checks write per segment at store time.

Disconnect behavior:

• publisher disconnect ends stream
• no explicit end marker required
• partial in-flight segment is discarded
• subscriber sockets are closed

No FATAL is injected into relay stream. Subscribers detect truncation via trailer parsing.

Size rule:

• each segment must respect 32 MiB blob limit

Continuity recommendation:

• include Previous-Segment: <hash> after first segment

🖧STREAM_SUB

🖧STREAM_SUB subscribes to live trailer bytes by prefix.

Request:

• API: 🖧STREAM_SUB
• data: <coordinate-prefix>

Behavior:

• enters dedicated relay mode immediately
• no OK response packet
• when no active publisher exists for the prefix, subscriber waits for one
• wait uses a fixed server timeout
• on wait timeout, repo writes FATAL NOT_FOUND wait timeout and closes
• forwards bytes from matching active publishers

Late joiners receive bytes buffered from current in-flight segment and then continue live.

Authorization is repository-service behavior. The HPPR Repository Service checks read at subscription time.

On publisher disconnect, repo closes subscriber sockets. Mid-segment disconnect yields partial trailer data followed by EOF.

Completed segments remain available via 🖧GET and 🖧EXCHANGE.

Relay Chaining

A downstream repo can relay a live stream by:

1. subscribing upstream with 🖧STREAM_SUB
2. publishing downstream with 🖧STREAM_PUB