pub struct DataHeader {
pub endpoint: Option<String>,
pub content_len: Option<u64>,
pub content_type: Option<String>,
pub traceparent: Option<String>,
pub tracestate: Option<String>,
pub topic: Option<String>,
pub sequence: Option<u64>,
pub producer: Option<[u8; 32]>,
pub achieved: Option<Acknowledgement>,
pub report_id: Option<u64>,
pub report: Vec<CursorLevel>,
pub report_mode: ReportMode,
}Expand description
DATA header: one transfer.
Every field is optional at the decoder. Which of them the context
requires is a dispatch question: an initiating stream must name an endpoint
and the reply half of an exchange must not, but the decoder sees bytes, not
streams (docs/PROTOCOL.md §6.2).
Fields§
§endpoint: Option<String>Endpoint path. Required on an initiating stream, ignored on a reply.
content_len: Option<u64>Advisory payload length.
content_type: Option<String>Opaque content type label.
traceparent: Option<String>W3C traceparent.
tracestate: Option<String>W3C tracestate, opaque passthrough.
topic: Option<String>Pub/Sub topic; opaque bytes, selected by the filter grammar of
docs/PROTOCOL.md §6.4. Only meaningful on transfers fanned out by a
publisher.
sequence: Option<u64>Per-producer sequence number, for ordering and gap detection
(docs/PROTOCOL.md §6.2, key 6).
Written by a publisher whose connection negotiated PerProducer
ordering, and by nothing under core: the number is assigned once per
published message, before fan-out, so a copy a subscriber lost shows up
as a hole in its own sequence. It is not a transfer identifier and
correlates nothing — an exchange is correlated by its stream.
producer: Option<[u8; 32]>Producer identity: the raw 32-byte digest (docs/PROTOCOL.md §6.2,
key 7).
Specified ahead of code, and absent in the default case by design:
the receiver already knows the sending peer’s proved fingerprint from
the handshake, so this names a producer only where it is not the
connection peer — a relay, or a name an L2 subscription supplies
(decisions/0008
§4.4). The sha256:<64 hex> spelling is presentation only and never
goes on the wire.
achieved: Option<Acknowledgement>The completion level the sender achieved for the message it is
answering (docs/PROTOCOL.md §6.2, key 8).
This is the L2 confirm, and it is a statement about one hop: a broker
that has taken responsibility for a message in memory writes
Acknowledgement::Accepted on the reply half of the producer’s
exchange, which is what makes the reply a publisher confirm without a
frame kind of its own
(decisions/0018
§4.6). It is achieved, never requested — a level a peer wants is
negotiated in HELLO and refused there if it cannot be reached
(0006 §4.4) — and it
is never relayed: the producer’s confirm says nothing about what a
consumer later does with the message
(GUARANTEES.md §2).
A v0 sender leaves it absent, and an absent key is not
Acknowledgement::None: it says this hop makes no claim beyond the
transport receipt QUIC already gave.
report_id: Option<u64>Identifier the sender assigns to the report it orders (key 9).
Present exactly when DataHeader::report is non-empty. It names the
CURSOR stream that will report on this transfer, and it is scoped to
the connection and to the direction that allocated it: a peer reports
only on transfers it received, so the two directions cannot collide.
report: Vec<CursorLevel>Levels the sender asks to be reported, strictly ascending (key 10).
An order, not a guarantee: a receiver that cannot reach a level
simply does not report it, and the transfer does not fail for it. A
level a peer must reach is the negotiated acknowledgement dimension
of HELLO instead
(decisions/0006
§4.4).
report_mode: ReportModeHow often the reporter should emit a record (key 11).
ReportMode::Progress is the default and is never written.
Implementations§
Source§impl DataHeader
impl DataHeader
Sourcepub fn addressed(endpoint: impl Into<String>) -> DataHeader
pub fn addressed(endpoint: impl Into<String>) -> DataHeader
A header addressing endpoint, for the initiating half of a stream.
Sourcepub fn reply() -> DataHeader
pub fn reply() -> DataHeader
A header for the reply half of an exchange: no endpoint, no topic.
The stream is the correlation, so a reply carries no identifier of the request it answers.
Sourcepub fn encode(&self) -> Vec<u8> ⓘ
pub fn encode(&self) -> Vec<u8> ⓘ
Encodes the header.
Key 10 goes out in the canonical form §6.2 makes normative —
strictly ascending by wire value, no repeats — whatever order
DataHeader::report happens to hold. That rule is enforced here
because encoding cannot fail: a vector in any other order would
otherwise produce bytes that close the connection at every conformant
peer, and there would be no way to tell the caller so.
The report’s other two rules stay the caller’s for exactly that
reason — both need an error, and this function has none to give. At
most limits::MAX_REPORT_LEVELS distinct levels, and key 9
present exactly when key 10 is: weida’s data_header refuses an
oversized order with Error::LimitExceeded and allocates the report
id alongside the order, so no caller reaches this encoder with either
mistake.
Sourcepub fn encode_into(&self, out: &mut Vec<u8>)
pub fn encode_into(&self, out: &mut Vec<u8>)
Appends the encoded header to out, for a send path that reuses a
buffer (B-250). The canonical form has one implementation and this is
it; Self::encode is a wrapper.
Sourcepub fn decode(bytes: &[u8]) -> Result<DataHeader, HeaderError>
pub fn decode(bytes: &[u8]) -> Result<DataHeader, HeaderError>
Decodes the header.