bookclerk_storage::b2_api
Backblaze B2 native API replies, read into checked types.
The b2 destination talks to B2 through its native API (version 3):
b2_authorize_account, upload URLs, large-file parts, file-name and
file-version listings, deletes and server-side copies. Every reply comes
from outside Bookclerk, so this module is the boundary that reads them:
pure functions over bytes, with no I/O, fuzzed by the b2_reply target.
The module also holds the request-side rules that must agree with what
it reads back: which file names B2 accepts (check_file_name) and how
a name is percent-encoded into an upload header or a download URL
(encode_file_name).
Replies are capped at MAX_B2_REPLY_BYTES; ids, tokens, URLs, names
and file-info values each have their own cap, so a hostile or broken
service cannot make the guest hold more than a bounded amount.
| Item | Kind | Summary |
|---|---|---|
AuthToken |
struct | An authorization token: for the account, or for one upload URL. |
B2Url |
struct | An https URL B2 handed out (API, download or upload URL), with no user info, query or fragment. |
FileId |
struct | A B2 file id: one version of one file name. |
Bucket |
struct | A bucket an application key may reach. |
Authorization |
struct | What b2_authorize_account granted. |
UploadTarget |
struct | Where one upload (a small file, or one part of a large file) goes. |
FileVersion |
struct | One version of one file, as B2 describes it. |
NamesPage |
struct | One page of b2_list_file_names. |
VersionsPage |
struct | One page of b2_list_file_versions. |
StoredPart |
struct | What b2_upload_part stored. |
DownloadHead |
struct | What a download (GET or HEAD on /file/<bucket>/<name>) says about the file in its response headers. |
ApiError |
struct | An error reply from the API. |
B2ReplyError |
enum | Why a reply could not be read. |
FileNameError |
enum | Why a file name is refused. |
FileAction |
enum | What a file version is. |
check_file_name |
function | Checks a file name against B2's rules: 1 to MAX_FILE_NAME_BYTES bytes of UTF-8, no control characters or backslashes, and no leading, trailing or doubled /. |
encode_file_name |
function | Percent-encodes a file name (or a file-info value) the way B2 reads the X-Bz-File-Name header and the /file/<bucket>/<name> download path: every byte outside the unreserved set and / becomes %XX (uppercase). |
decode_file_name |
function | Decodes percent-encoding (%XX, and + as a space). |
parse_authorization |
function | Reads a b2_authorize_account reply. |
parse_buckets |
function | Reads a b2_list_buckets reply. |
parse_upload_target |
function | Reads a b2_get_upload_url or b2_get_upload_part_url reply. |
parse_file_version |
function | Reads a reply that describes one file version: an upload, a finished large file, a copy, or b2_start_large_file. |
parse_names_page |
function | Reads a b2_list_file_names reply. |
parse_versions_page |
function | Reads a b2_list_file_versions reply. |
parse_part |
function | Reads a b2_upload_part reply. |
parse_download_headers |
function | Reads the headers of a download reply. |
parse_api_error |
function | Reads an error reply. Never fails: a body that is not B2's error JSON reads as code unknown with no message. |
ReplyResult |
type alias | Result alias for this module's parsers. |
MAX_B2_REPLY_BYTES |
constant | Largest reply read, in bytes: a full listing of MAX_LIST_FILES versions, each with its name and file info, fits well inside. |
MAX_LIST_FILES |
constant | Most files one listing reply may hold (B2's own maxFileCount limit). |
MAX_FILE_NAME_BYTES |
constant | Longest file name B2 accepts, in UTF-8 bytes. |
MAX_ID_BYTES |
constant | Longest id (account, bucket, file) accepted, in bytes. |
MAX_TOKEN_BYTES |
constant | Longest authorization token accepted, in bytes. |
MAX_URL_BYTES |
constant | Longest URL accepted, in bytes. |
MAX_FILE_INFO_ENTRIES |
constant | Most file-info entries one file may carry in a reply. |
MAX_FILE_INFO_BYTES |
constant | Longest file-info key or value accepted, in bytes. |
MAX_ERROR_TEXT_BYTES |
constant | Longest error code or message kept from an error reply, in bytes. |
MAX_PARTS |
constant | Most parts a large file may have (B2's limit). |
MAX_DOWNLOAD_HEADERS |
constant | Most response headers read from one download reply. |
pub struct AuthToken(/* private */);
An authorization token: for the account, or for one upload URL.
Its Debug output never shows the token.
pub fn parse(token: &str) -> ReplyResult<Self>
Checks a token: 1 to MAX_TOKEN_BYTES bytes of visible ASCII, so
it is safe in an Authorization header.
Returns B2ReplyError::Malformed for any other text.
pub fn expose(&self) -> &str
The token, for the Authorization header.
Implements: Clone, Debug, Eq, PartialEq
pub struct B2Url(/* private */);
An https URL B2 handed out (API, download or upload URL), with no
user info, query or fragment.
pub fn parse(url: &str) -> ReplyResult<Self>
Checks a URL.
Returns B2ReplyError::Malformed when the URL is not https, is
over MAX_URL_BYTES, has no host, or holds user info, a query, a
fragment, whitespace or control characters.
pub fn as_str(&self) -> &str
The URL, without a trailing /.
pub fn host(&self) -> &str
The URL's host (with its port, when it has one).
Implements: Clone, Debug, Eq, PartialEq
pub struct FileId(/* private */);
A B2 file id: one version of one file name.
pub fn parse(id: &str) -> ReplyResult<Self>
Checks a file id: 1 to MAX_ID_BYTES bytes of visible ASCII.
Returns B2ReplyError::Malformed for any other text.
pub fn as_str(&self) -> &str
The id as text.
Implements: Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd
pub struct Bucket {
pub id: String,
pub name: String,
}
A bucket an application key may reach.
Fields
id: The bucket id, which API calls take.name: The bucket name, which download URLs take.
Implements: Clone, Debug, Eq, PartialEq
pub struct Authorization {
pub account_id: String,
pub token: AuthToken,
pub api_url: B2Url,
pub download_url: B2Url,
pub recommended_part_size: u64,
pub absolute_minimum_part_size: u64,
pub bucket: Option<Bucket>,
pub name_prefix: Option<String>,
pub capabilities: Vec<String>,
}
What b2_authorize_account granted.
Fields
account_id: The account id.token: The token every other API call sends.api_url: Base URL of the API calls.download_url: Base URL of downloads.recommended_part_size: Part size B2 recommends for large files, in bytes.absolute_minimum_part_size: Smallest part (other than the last) B2 accepts, in bytes.bucket: The bucket the key is restricted to, when it is restricted to one.name_prefix: The file-name prefix the key is restricted to, when it is.capabilities: The capabilities the key holds (listFiles,writeFiles, ...).
pub fn can(&self, capability: &str) -> bool
Whether the key holds capability.
Implements: Clone, Debug, Eq, PartialEq
pub struct UploadTarget {
pub url: B2Url,
pub token: AuthToken,
}
Where one upload (a small file, or one part of a large file) goes.
Fields
url: The URL toPOSTthe bytes to.token: The token for that URL only.
Implements: Clone, Debug, Eq, PartialEq
pub struct FileVersion {
pub file_id: Option<FileId>,
pub file_name: String,
pub content_length: u64,
pub content_sha1: Option<String>,
pub content_type: Option<String>,
pub upload_timestamp_ms: u64,
pub action: FileAction,
pub file_info: BTreeMap<String, String>,
}
One version of one file, as B2 describes it.
Fields
file_id: The version's id.file_name: The full file name.content_length: The size in bytes (zero for hide markers and folders).content_sha1: Lowercase hex SHA-1 of the bytes, when B2 knows it (small files, or large files that recordedlarge_file_sha1).content_type: The stored content type.upload_timestamp_ms: When the version was uploaded, in UTC unix milliseconds.action: What the version is.file_info: File info (X-Bz-Info-*values) stored with the version.
Implements: Clone, Debug, Eq, PartialEq
pub struct NamesPage {
pub files: Vec<FileVersion>,
pub next_file_name: Option<String>,
}
One page of b2_list_file_names.
Fields
files: The newest version of each name, in name order.next_file_name: Where the next page starts, when there is one.
Implements: Clone, Debug, Eq, PartialEq
pub struct VersionsPage {
pub files: Vec<FileVersion>,
pub next: Option<(String, FileId)>,
}
One page of b2_list_file_versions.
Fields
files: Versions in name order, newest first within a name.next: Where the next page starts (name and file id), when there is one.
Implements: Clone, Debug, Eq, PartialEq
pub struct StoredPart {
pub part_number: u32,
pub content_sha1: String,
}
What b2_upload_part stored.
Fields
part_number: The part's number (1 toMAX_PARTS).content_sha1: Lowercase hex SHA-1 of the part.
Implements: Clone, Debug, Eq, PartialEq
pub struct DownloadHead {
pub version: FileVersion,
pub body_offset: u64,
pub body_length: u64,
}
What a download (GET or HEAD on /file/<bucket>/<name>) says
about the file in its response headers.
Fields
version: The version served.content_lengthis the whole file's size.body_offset: Offset in the file of this response's first body byte: the range start for a ranged read, 0 otherwise.body_length: Bytes in this response's body: the range length for a ranged read, the whole size otherwise.
Implements: Clone, Debug, Eq, PartialEq
pub struct ApiError {
pub status: u16,
pub code: String,
pub message: String,
}
An error reply from the API.
Fields
status: The HTTP status.code: B2's error code (expired_auth_token,not_found, ...), orunknownwhen the body named none.message: B2's message, when there was one.
pub fn expired_token(&self) -> bool
Whether the account token expired, so a fresh authorization should be tried once.
pub fn retryable(&self) -> bool
Whether B2 asked the caller to try again later (busy, too many requests, or an internal error).
pub fn not_found(&self) -> bool
Whether the object (or file id) does not exist.
Implements: Clone, Debug, Display, Eq, PartialEq
pub enum B2ReplyError {
TooLarge,
Malformed(String),
}
Why a reply could not be read.
Variants
TooLarge: The reply is overMAX_B2_REPLY_BYTES.Malformed: The reply is not the expected JSON shape, or a field breaks a rule.
Implements: Clone, Debug, Display, Eq, Error, PartialEq
pub enum FileNameError {
Empty,
TooLong,
Control,
Slash,
Backslash,
}
Why a file name is refused.
Variants
Empty: The name is empty.TooLong: The name is overMAX_FILE_NAME_BYTESbytes.Control: The name holds a control character (below U+0020, or U+007F).Slash: The name starts or ends with/, or holds//.Backslash: The name holds a backslash, which B2 refuses.
Implements: Clone, Copy, Debug, Display, Eq, Error, PartialEq
pub enum FileAction {
Upload,
Copy,
Hide,
Start,
Folder,
}
What a file version is.
Variants
Upload: A stored file.Copy: A file made by a server-side copy.Hide: A hide marker: the name reads as deleted.Start: A large file started and not yet finished.Folder: A virtual folder (only in listings with a delimiter).
pub fn is_stored(self) -> bool
Whether the version holds the file's bytes (an upload or a copy).
Implements: Clone, Copy, Debug, Eq, PartialEq
pub fn check_file_name(name: &str) -> Result<(), FileNameError>
Checks a file name against B2's rules: 1 to MAX_FILE_NAME_BYTES
bytes of UTF-8, no control characters or backslashes, and no leading,
trailing or doubled /.
name- the full file name, prefix included.
Returns the first rule the name breaks.
pub fn encode_file_name(name: &str) -> String
Percent-encodes a file name (or a file-info value) the way B2 reads the
X-Bz-File-Name header and the /file/<bucket>/<name> download path:
every byte outside the unreserved set and / becomes %XX (uppercase).
name- the text to encode.
The encoded text; decode_file_name gives name back.
pub fn decode_file_name(text: &str) -> Option<String>
Decodes percent-encoding (%XX, and + as a space).
text- encoded text, such as a file-info header value.
The decoded text, or None when an escape is broken or the bytes are
not UTF-8.
pub fn parse_authorization(bytes: &[u8]) -> ReplyResult<Authorization>
Reads a b2_authorize_account reply.
bytes- the reply body.
What the key may do and where to send calls.
Returns B2ReplyError for an oversized or malformed reply, a bad
URL, id or token, a part size of zero or a minimum above the
recommendation, or a restriction to a bucket that no longer exists.
pub fn parse_buckets(bytes: &[u8]) -> ReplyResult<Vec<Bucket>>
Reads a b2_list_buckets reply.
bytes- the reply body.
The buckets it lists (at most 1,000, B2's per-account limit).
Returns B2ReplyError for an oversized or malformed reply, or a bad
bucket id or name.
pub fn parse_upload_target(bytes: &[u8]) -> ReplyResult<UploadTarget>
Reads a b2_get_upload_url or b2_get_upload_part_url reply.
bytes- the reply body.
The upload URL and its token.
Returns B2ReplyError for an oversized or malformed reply, or a bad
URL or token.
pub fn parse_file_version(bytes: &[u8]) -> ReplyResult<FileVersion>
Reads a reply that describes one file version: an upload, a finished
large file, a copy, or b2_start_large_file.
bytes- the reply body.
The version.
Returns B2ReplyError for an oversized or malformed reply, or a field
that breaks its rule.
pub fn parse_names_page(bytes: &[u8]) -> ReplyResult<NamesPage>
Reads a b2_list_file_names reply.
bytes- the reply body.
The page.
Returns B2ReplyError for an oversized or malformed reply, more than
MAX_LIST_FILES files, a bad version, or a continuation name that
does not move past the page.
pub fn parse_versions_page(bytes: &[u8]) -> ReplyResult<VersionsPage>
Reads a b2_list_file_versions reply.
bytes- the reply body.
The page.
Returns B2ReplyError for an oversized or malformed reply, more than
MAX_LIST_FILES files, a bad version, or a continuation with a name
but no id (or the reverse).
pub fn parse_part(bytes: &[u8]) -> ReplyResult<StoredPart>
Reads a b2_upload_part reply.
bytes- the reply body.
The part's number and SHA-1.
Returns B2ReplyError for an oversized or malformed reply, a part
number outside 1 to MAX_PARTS, or a SHA-1 that is not 40 hex
digits.
pub fn parse_download_headers<'a, I>(headers: I) -> ReplyResult<DownloadHead>
where
I: IntoIterator<Item = (&'a str, &'a [u8])>,
Reads the headers of a download reply.
headers- each header's name (any case) and raw value, as received.
The version served and the body's length.
Returns B2ReplyError when there are more than
MAX_DOWNLOAD_HEADERS headers, a required header (Content-Length,
X-Bz-File-Id, X-Bz-File-Name) is missing or repeated, a value is not
text, a number does not parse, Content-Range disagrees with
Content-Length, or file info is over its limits.
pub fn parse_api_error(status: u16, bytes: &[u8]) -> ApiError
Reads an error reply. Never fails: a body that is not B2's error JSON
reads as code unknown with no message.
status- the HTTP status.bytes- the reply body.
The error, with code and message cut to MAX_ERROR_TEXT_BYTES.
pub type ReplyResult<T> = Result<T, B2ReplyError>;
Result alias for this module's parsers.
pub const MAX_B2_REPLY_BYTES: usize = _;
Largest reply read, in bytes: a full listing of MAX_LIST_FILES
versions, each with its name and file info, fits well inside.
pub const MAX_LIST_FILES: usize = 10_000;
Most files one listing reply may hold (B2's own maxFileCount limit).
pub const MAX_FILE_NAME_BYTES: usize = 1024;
Longest file name B2 accepts, in UTF-8 bytes.
pub const MAX_ID_BYTES: usize = 256;
Longest id (account, bucket, file) accepted, in bytes.
pub const MAX_TOKEN_BYTES: usize = 4096;
Longest authorization token accepted, in bytes.
pub const MAX_URL_BYTES: usize = 2048;
Longest URL accepted, in bytes.
pub const MAX_FILE_INFO_ENTRIES: usize = 64;
Most file-info entries one file may carry in a reply.
pub const MAX_FILE_INFO_BYTES: usize = 8192;
Longest file-info key or value accepted, in bytes.
pub const MAX_ERROR_TEXT_BYTES: usize = 1024;
Longest error code or message kept from an error reply, in bytes.
pub const MAX_PARTS: u32 = 10_000;
Most parts a large file may have (B2's limit).
pub const MAX_DOWNLOAD_HEADERS: usize = 128;
Most response headers read from one download reply.
Generated from crates/bookclerk-storage at main · View as Markdown