bookclerk_plugin_sdk::resume
Sans-IO decisions for resuming an interrupted HTTP download.
Audience: guests that download large files (store audio, archives).
crate::download (feature http) drives these functions over the
SDK's HTTP client; they are separate and IO-free so the fuzz target
download_resume and the unit tests exercise exactly the code a guest
runs.
A download keeps the bytes it already has and asks the server for the
rest with Range: bytes=<offset>-. The server's answer is untrusted:
parse_content_range reads its Content-Range header and
next_step decides whether the body continues the partial file,
replaces it, finishes it, or ends the download. A body is only ever
appended where it provably starts at the partial's end, so a server
that answers a different range, changes the file's size, or ignores
the range never splices unrelated bytes into the file.
| Item | Kind | Summary |
|---|---|---|
Partial |
struct | What a download already has when it reads a response. |
ResponseHead |
struct | The parts of a response's head next_step reads. |
ContentRange |
enum | A Content-Range header the server sent, as parse_content_range reads it. |
Step |
enum | What to do with a response, as next_step decides it. |
Validator |
enum | A validator that identifies one version of the remote file, sent as If-Range so a server whose file changed answers the whole new file instead of a range of it. |
parse_content_range |
function | Parses a Content-Range value (RFC 9110 §14.4) for the bytes unit. |
next_step |
function | Decides what a response means for a partial download. |
MAX_CONTENT_RANGE_BYTES |
constant | Longest Content-Range value read, in bytes. A valid one for a file under 2^64 bytes is at most bytes plus three 20-digit numbers. |
MAX_VALIDATOR_BYTES |
constant | Longest validator (ETag or Last-Modified value) kept for If-Range, in bytes. Real ones are well under this; a longer value is not used. |
pub struct Partial {
pub offset: u64,
pub total: Option<u64>,
}
What a download already has when it reads a response.
Fields
offset: Bytes already written, from the start of the file; the request asked forRange: bytes=<offset>-when this is above zero.total: The file's length as an earlier response stated it, if any; a response stating another length means the file changed.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct ResponseHead<'a> {
pub status: u16,
pub content_range: Option<&'a [u8]>,
pub content_length: Option<u64>,
}
The parts of a response's head next_step reads.
Fields
status: HTTP status code.content_range: The rawContent-Rangevalue, when the header was sent.content_length:Content-Length, when the header was sent and is a number.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum ContentRange {
Bytes { first: u64, last: u64, total: Option<u64> },
Unsatisfied { total: u64 },
}
A Content-Range header the server sent, as parse_content_range
reads it.
Variants
Bytes:bytes <first>-<last>/<total>: the body holds bytesfirsttolast(inclusive) of a filetotalbytes long, or of a file whose length the server did not state (/*).first: Offset of the body's first byte in the file.last: Offset of the body's last byte in the file; at leastfirst.total: The whole file's length in bytes, greater thanlast;Nonefor/*.
Unsatisfied:bytes */<total>: the range asked for is past the end of a filetotalbytes long (the form a416carries).total: The whole file's length in bytes.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum Step {
Append { total: Option<u64>, end: Option<u64> },
Replace { total: Option<u64>, end: Option<u64> },
Complete,
StartOver,
Retry,
Fail,
}
What to do with a response, as next_step decides it.
Variants
Append: The body continues the partial at its current end (206starting exactly at the offset): append it.total: The file's length, when the server stated it.end: Offset just past the body's last byte, for a206(its range's last byte plus one): a body that runs past it does not match its own range, and one that stops there leaves the rest of the file to ask for.Nonefor a200, whose body runs to the end of the file.
Replace: The body is the whole file from byte 0 (200, or a206from 0 asked without a range): drop what the partial holds and write the body in its place.total: The file's length, when the server stated it.end: Offset just past the body's last byte, for a206(its range's last byte plus one): a body that runs past it does not match its own range, and one that stops there leaves the rest of the file to ask for.Nonefor a200, whose body runs to the end of the file.
Complete: The partial already holds the whole file (416stating a length equal to the offset): nothing more to read.StartOver: The answer does not fit the partial (another range, a changed length, an unsatisfiable range at another length): drop the partial and ask again for the whole file.Retry: A transient refusal (408,429,5xx): wait and ask again for the same range.Fail: Any other status: the download fails with it.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum Validator {
ETag(String),
LastModified(String),
}
A validator that identifies one version of the remote file, sent as
If-Range so a server whose file changed answers the whole new file
instead of a range of it.
Variants
ETag: A strongETag(never one starting withW/, whichIf-Rangemay not carry).LastModified: ALast-Modifieddate, as sent.
pub fn from_headers(etag: Option<&[u8]>, last_modified: Option<&[u8]>) -> Option<Self>
Picks the validator to resume with from a response's headers.
A strong ETag wins over Last-Modified. A value is used only
when it is visible ASCII (and spaces, for a date) of at most
MAX_VALIDATOR_BYTES bytes, so it can be sent back unchanged.
etag- The rawETagvalue, when sent.last_modified- The rawLast-Modifiedvalue, when sent.
The validator, or None when neither header is usable.
pub fn as_str(&self) -> &str
The value to send as If-Range.
Implements: Clone, Debug, Eq, PartialEq
pub fn parse_content_range(value: &[u8]) -> Option<ContentRange>
Parses a Content-Range value (RFC 9110 §14.4) for the bytes unit.
Accepts exactly bytes <first>-<last>/<total|*> or bytes */<total>,
with one space after the unit and decimal numbers only. Optional
whitespace around the value is ignored; anything else (another unit,
signs, a range whose last byte is before its first or at or past the
stated length, numbers that overflow 64 bits, a value longer than
MAX_CONTENT_RANGE_BYTES) is refused.
value- The header value as received, not necessarily UTF-8.
The parsed range, or None when the value is not a valid bytes
content range.
pub fn next_step(partial: Partial, head: ResponseHead<'_>) -> Step
Decides what a response means for a partial download.
Only a 206 whose Content-Range starts exactly at partial.offset
and states the same length as partial.total (when both are known),
with a Content-Length (when sent) matching the range, is appended. A
200 replaces the partial. A 416 finishes the download only when it
states bytes */<offset> for a non-empty partial and agrees with the
known length. Everything else that names a range the partial cannot
use starts over; 408, 429 and 5xx are retried; any other status
fails.
partial- What the download held when it sent the request.head- The response's status and range headers.
The Step to take.
pub const MAX_CONTENT_RANGE_BYTES: usize = 80;
Longest Content-Range value read, in bytes. A valid one for a file
under 2^64 bytes is at most bytes plus three 20-digit numbers.
pub const MAX_VALIDATOR_BYTES: usize = 256;
Longest validator (ETag or Last-Modified value) kept for If-Range,
in bytes. Real ones are well under this; a longer value is not used.
Generated from crates/bookclerk-plugin-sdk at main · View as Markdown