Struct RangeFrame 

#[non_exhaustive]
pub struct RangeFrame {
    pub offset: u64,
    pub length: u64,
    pub bytes: Vec<u8>,
    pub complete: bool,
    pub total_length: Option<u64>,
    pub chunk_lens: Option<Vec<u64>>,
    pub chunk_index: Option<u64>,
    pub inclusion_proof: Option<String>,
    pub root: Option<String>,
    pub chunk_count: Option<u64>,
    pub chunk_lens_offset: Option<u64>,
}

One streamed dig.fetchRange frame (L7 spec §8 framing). Frames arrive in ascending offset order and tile the requested range exactly; the caller reassembles by offset and stops on complete.

The metadata splits into two sets, and which frames carry them differs

Read this before implementing either side — the two halves have different rules, and conforming to the wrong half produces a verification miss on a multi-frame read rather than a clean failure.

• Identity — fixed-size, on EVERY frame: root, total_length, chunk_count, plus chunk_index where the window is chunk-aligned. These are what let a reader reject a wrong-generation or wrong-layout holder the moment a frame arrives, which is a property the once-per-stream set can never have. They cost a bounded number of bytes, so carrying them everywhere is cheap. Set them with with_identity + with_chunk_index.
• Prologue — resource-scaling, ONCE per range stream: chunk_lens (paged, located by chunk_lens_offset) and inclusion_proof. Their size is a function of the RESOURCE rather than of the frame, so they ride the first frame or a paged prologue and MUST NOT be repeated on later frames. Set them with with_chunk_lens_page + with_inclusion_proof, or omit them entirely when the request set RangeRequest::skip_layout.

Before 0.13.0 every one of these was “first frame only”, because the whole layout had to fit one frame or the range was unservable (#1640). SPEC.md §5.1.1 is normative.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

offset: u64

This frame’s start offset within the requested range.

length: u64

This frame’s byte length.

bytes: Vec<u8>

The raw ciphertext bytes. On the wire they are base64 (base64_bytes) — the canonical dig.fetchRange frame encoding every producer emits.

complete: bool

Whether this is the final frame of the range.

total_length: Option<u64>

(identity — every frame) the full resource ciphertext length.

chunk_lens: Option<Vec<u64>>

(prologue — once per stream) per-chunk ciphertext lengths of the whole resource, in order, or ONE PAGE of them beginning at chunk_lens_offset.

Resource-scaling, so it MUST NOT be repeated on later frames: on a later frame it was only a redundant equality check on an array the client already held. Omitted entirely when the request set RangeRequest::skip_layout.

chunk_index: Option<u64>

(identity — every frame, where the window is chunk-aligned) index into the resource’s chunk_lens array of the first chunk in THIS frame.

Fixed-size, and about this frame rather than about the resource, so a chunk-aligned continuation frame states it too — see with_chunk_index, which is deliberately separate from the proof setter so stating alignment never costs a repeated proof.

inclusion_proof: Option<String>

(prologue — once per stream) merkle inclusion proof of the whole resource vs the generation root (base64, relayed verbatim); null/absent for capsule: true (self-verifying on install).

Resource-scaling and capped at MAX_INCLUSION_PROOF_B64. At 4,096 B it would consume the entire remaining frame budget if repeated, which is the concrete reason “once per stream” is a MUST NOT rather than a preference.

root: Option<String>

(identity — every frame) the generation root (64-hex) this range is served from, and which the inclusion proof is against.

chunk_count: Option<u64>

(identity — every frame) the resource’s TOTAL chunk count — how many entries the reassembled chunk_lens array has.

Together with root and total_length it is what lets a reader detect a wrong-generation or wrong-layout holder the moment a frame arrives. It is also how a reader sizes the array it is paging in, and how it knows the prologue is complete.

chunk_lens_offset: Option<u64>

(prologue — once per page) the index into the resource’s chunk_lens array at which THIS frame’s chunk_lens page begins — how a paged prologue is located and reassembled.

A resource whose layout exceeds MAX_CHUNK_LENS_PER_FRAME cannot state it on one frame, so the sender pages it: successive frames each carry up to that many entries, stamped with the offset they start at. A reader places each page at its offset and has the whole array once it holds chunk_count entries. Absent means “this frame’s chunk_lens, if any, begins at 0” — the single-frame layout, which is the pre-0.13.0 shape.

Implementations

impl RangeFrame

pub fn data(offset: u64, bytes: Vec<u8>) -> Self

A data frame: bytes at offset, with no metadata — the shape of every continuation frame.

length is derived from bytes, since a frame that misdeclares its own payload length is never what a serve path wants. The metadata a FIRST frame or a prologue page carries is layered on with the with_* setters, so a continuation frame cannot accidentally claim a layout it is not stating — the two shapes are different call chains, not one call with a pile of Nones.

pub fn with_complete(self, complete: bool) -> Self

Mark this as the final frame of the range.

pub fn with_identity( self, root: impl Into<String>, total_length: u64, chunk_count: u64, ) -> Self

The fixed-size identity metadata EVERY frame of a range should carry: the generation root (64-hex) the range is served from, the resource’s ciphertext total_length, and its chunk_count.

These three are what let a reader reject a wrong-generation or wrong-layout holder the moment a frame arrives — which the resource-scaling metadata never could, since it arrives once. They are fixed-size, so carrying them everywhere costs a bounded number of bytes.

pub fn with_chunk_lens_page( self, chunk_lens_offset: u64, chunk_lens: Vec<u64>, ) -> Self

A page of the resource’s chunk_lens array, beginning at entry chunk_lens_offset.

Call it once with offset 0 for a layout that fits one frame (at most MAX_CHUNK_LENS_PER_FRAME entries), or once per page of a paged prologue. chunk_lens is a DECRYPT input — per-chunk AES-GCM-SIV needs the WHOLE array, and a reader rejects an array whose sum differs from total_length — so a page is only ever useful as part of a complete set.

pub fn split_chunk_lens_pages(chunk_lens: &[u64]) -> Vec<(u64, Vec<u64>)>

Split a whole resource’s chunk_lens into the pages of a paged prologue: (offset, page) pairs, in order, each ready for with_chunk_lens_page.

This is the encoder half of the paging rule, and it exists so that no serve path re-derives that rule by hand. #1640 was an encode/decode asymmetry, so the split and its mirror ChunkLensAssembler are published together from one module: the pages this returns are exactly the pages the assembler requires — aligned offsets, MAX_CHUNK_LENS_PER_FRAME entries each except a shorter tail, tiling the array with no gap and no overlap.

A layout at or under the threshold yields a single page at offset 0, which is the single-frame pre-0.13.0 shape; an empty layout yields no pages at all.

pub fn with_chunk_index(self, chunk_index: u64) -> Self

Where this frame starts in the resource’s chunk sequence — the index into chunk_lens of its first chunk, for a chunk-aligned window.

Fixed-size identity, so a chunk-aligned CONTINUATION frame states it too, not only the first frame. It has its own setter for exactly that reason: it used to be a parameter of with_inclusion_proof, which meant the one field every reader wants on every frame could not be stated without repeating a once-per-stream proof — a SPEC.md §5.1.1 MUST NOT, and 4,096 B per frame against a budget with zero slack.

pub fn with_inclusion_proof(self, inclusion_proof: impl Into<String>) -> Self

The merkle inclusion proof of the whole resource against the generation root (base64, relayed verbatim).

Resource-scaling, so it rides the first frame or the prologue — once per range stream, never repeated. Base64 longer than MAX_INCLUSION_PROOF_B64 is refused by encode: such a resource has no conforming range stream at all, and the holder must say so rather than stream frames a reader cannot verify.

pub fn with_declared_length(self, length: u64) -> Self

Override the declared length, which data otherwise derives from bytes.

For budget fixtures that hold every scalar at its widest legal value. A serve path has no reason to call this: a frame whose length disagrees with its payload is a frame the reader distrusts.

pub fn encode(&self) -> Result<Vec<u8>>

Serialize as a u32 big-endian length prefix + JSON body (one framed frame on the stream).

Fails with io::ErrorKind::InvalidData if bytes exceeds MAX_RANGE_FRAME_PAYLOAD, if inclusion_proof exceeds MAX_INCLUSION_PROOF_B64, or if the serialized body exceeds MAX_FRAMED_BODY for any other reason (an unusually large chunk_lens page). A serving peer therefore cannot emit a frame decode is required to reject: it splits its resource on MAX_RANGE_FRAME_PAYLOAD or it learns about it here, at the send site, with the ceiling named in the error.

The payload is checked separately from the body because the body check alone is too weak: a payload well over the ceiling still fits in MAX_FRAMED_BODY once base64’d when the frame carries no metadata, so it would encode here and then overflow the moment the same span rode a FIRST frame with a chunk table attached — a size-dependent, intermittent failure. One explicit ceiling on bytes makes the limit the same for every frame. The proof is checked for the same reason: it is premise 2 of MAX_FIRST_FRAME_CHUNK_LENS, and a premise only a test believes is not a bound (#1655).

pub async fn decode<R: AsyncRead + Unpin>(r: &mut R) -> Result<Option<Self>>

Read + decode one RangeFrame from r. Returns Ok(None) at clean end-of-stream (the reader hit EOF on a frame boundary), so a consumer loops until None or complete.

Trait Implementations

impl Clone for RangeFrame

fn clone(&self) -> RangeFrame

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RangeFrame

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RangeFrame

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for RangeFrame

impl PartialEq for RangeFrame

fn eq(&self, other: &RangeFrame) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for RangeFrame

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for RangeFrame