bookclerk_node_proto
Wire protocol between a Bookclerk branch node and its library.
A host connects to GET /api/node/v1/connect with the WebSocket
subprotocol SUBPROTOCOL and proves itself with the Ed25519 key it
enrolled (H-4 design, section 3):
- host → owner:
Body::Hello{node_id, incarnation, software_version, resume} - owner → host:
Body::Challenge{nonce, library_id} - host → owner:
Body::Auth{sig}, an Ed25519 signature overauth_transcript - owner → host:
Body::Welcome, or a close withCLOSE_AUTH_FAILED/CLOSE_REVOKED.
Frames are JSON text of at most MAX_FRAME_BYTES; binary frames are a
protocol error because bulk data travels over HTTP.
After the handshake, a hello that listed held fences is answered with
Body::Resumed. Work is pulled: the host sends Body::Claim and
gets Body::Work (the job, its fence, and its secrets sealed to the
node's box key with seal_secrets) or Body::NoWork; it then
sends Body::Renew, Body::Complete or Body::Fail under that
fence, and may write a refreshed store token back with
Body::SecretUpdate. The owner forwards the host's node.<id> queue
as Body::Wake frames, each answered with Body::Ack.
A claim may carry a ClaimFilter (the kinds the host runs, whose work
it takes (ClaimScope), and the
plugins its operator consented to); a job handed back unrun goes with
Body::Release. To act on wakes the host reads
Body::DeploymentsList and Body::InstanceConfigGet (SECRETS
sealed with seal_instance_secrets), reports
Body::Observations, and fetches stored archives over HTTP at
ARTIFACTS_PATH with a request signed by sign_artifact_request.
A scan run on a host returns its rows in fenced Body::ScanResults
batches; the owner validates and writes them. Each account's pass then
reports the ids a delta pass found gone (Body::ScanRemoved) and how
it ended (Body::ScanPassEnd), so the owner keeps the account's sync
token (WorkJob::scan_tokens hands it back) and prunes after a
complete full pass. An acquire asks
Body::AcquirePlan for its titles, then for each title asks
Body::UploadGrant and streams the files over HTTP at
UPLOADS_PATH with the token sealed in Body::UploadGranted (a file
larger than UPLOAD_PART_BYTES as consecutive UploadParts); the
owner streams them on to its output destinations without staging them,
and the job completes when the last title's upload commits.
A branch shares the titles of its own library with the library it
joined (Body::CatalogBegin, Body::CatalogSync,
Body::CatalogUpload; see CatalogTitle): titles carry no account
or user field, and files reuse the upload endpoint.
A library asks its branches whether they can supply works it knows
(LookupWork, by strong identifiers, never titles): it stores the
questions and wakes the branch, which pulls them with
Body::CatalogQuestions and answers with Body::CatalogFound.
A member's request for a book a branch listed is a job on the library
pinned to that branch (BranchRequest): the branch claims it with
Body::RequestsClaim and reports with Body::RequestFinish; the
book itself travels up through the catalog sync.
A window (a branch whose link takes no work) reads the library's books
with Body::WindowBooks, page by page (Body::WindowPage,
WindowWork, each edition a WindowEdition marked when it is the
branch owner's), and merges them by identifier with the other libraries
it joined.
A host that leaves sends Body::NodeLeaving; the owner revokes the
node at once. Joining with a sign-in instead of a link is the OAuth
code + PKCE flow of the built-in client BRANCH_CLIENT_ID (OwnerInfo,
OAuthEnrollRequest). An Owner of the library may instead let the
install join as a shared branch (a shared node, ConnectionType::SharedBranch): its
redeem answer carries a SharedBranchBootstrap sealed to the node's box key.
A branch's redeem answer may carry the signing-in user's own store
accounts as an AccountBundle sealed the same way, when the user
chose to bring them.
An install can also sign in to a library as a person rather than join
it as a node: a clerk (CLERK_CLIENT_ID, ClerkTokenAnswer),
whose session token travels as Authorization: Bookclerk-Clerk
(parse_clerk_authorization). With it the clerk holds the clerk
socket at CLERK_CONNECT_PATH (ClerkFrame, LibraryFrame):
changed topics and pages of the library's books, never work.
This crate is pure: no I/O, no clock, no randomness. The daemon (owner) and the host client share it so both sides sign and check the same bytes.
| Item | Kind | Summary |
|---|---|---|
AccountBundle |
struct | The store accounts a library hands a joining branch, for one person. Debug prints no secret. |
CarriedAccount |
struct | One store account in an AccountBundle. |
CarriedSecret |
struct | One secret of a CarriedAccount: an encrypted_secrets row of the account, by kind and name. |
CatalogFile |
struct | One file of a CatalogTitle. |
CatalogMetadata |
struct | Bibliographic metadata of a CatalogTitle. |
CatalogRef |
struct | A title named by store and product id. |
CatalogTitle |
struct | One title, as a branch shares it. |
ClerkAuthorizeParams |
struct | The authorization request a clerk consent is for (the query /oidc/authorize forwards to the library's /clerk/approve page). |
ClerkTokenAnswer |
struct | POST /api/clerk/v1/token answer. |
ClerkTokenRequest |
struct | POST /api/clerk/v1/token body: exactly these three strings, each once, and nothing else. |
ClerkUser |
struct | The person a clerk session signs in as. |
StoredClerkCode |
struct | What the library stored with an approved code, as the token exchange checks it. |
ClerkCopy |
struct | What a copy.granted frame carries. |
CopyToken |
struct | A copy token as a clerk socket frame carries it: the bearer of the download endpoint (crate::COPY_AUTH_SCHEME). Its Debug prints no token, and the text is zeroized when dropped. |
CopyFile |
struct | One file of a copy (crate::Body::CopyGranted). |
CopyGrantedFrame |
struct | The fields of a crate::Body::CopyGranted, borrowed for copy_granted_problem. |
AcquireTarget |
struct | One title an acquire job should fetch on a host (Body::AcquireTargets). |
CallNumber |
struct | A title's short call number as the owner names it: 1 to MAX_CALL_NUMBER_BYTES ASCII letters and digits, so it is safe in any storage key segment. Deserializing anything else fails, which refuses the whole frame. |
ClaimFilter |
struct | What a host is willing to claim (claim.filter). |
FileCopy |
struct | Where one uploaded file is written: a destination and its key there. |
Frame |
struct | One frame: the envelope and its body. |
HeldFence |
struct | A lease the host still holds when it reconnects (hello.resume). |
JobStatusEntry |
struct | One job's state in Body::JobStatuses. |
PlanDestination |
struct | One output destination of the shared node that answered an acquire plan (Body::AcquireTargets). |
RemoteArtifact |
struct | One downloadable artifact of a RemoteVersion. |
RemoteDeployment |
struct | One deployment that targets a host (deployments.items). |
RemoteVersion |
struct | The active version of a plugin a host is asked to run. |
ScanImport |
struct | The owner's library import settings a host scan runs with. |
ScanToken |
struct | The sync token an owner holds for one account a host scan covers. |
TargetTitle |
struct | A title an AcquireTarget names, as the owner's library holds it: the store listing's identity and the metadata a host names the title's files from and seeds its scratch library with. The store and account are the target's own. |
UploadAnswer |
struct | Answer of the upload endpoint (every status carries one). |
UploadCommitRequest |
struct | Body of POST <UPLOADS_PATH><upload_id>/commit. |
UploadFile |
struct | One file of an upload (Body::UploadGrant). Its content crosses the network once and is written to every copy, each destination under the key that destination's own naming options give it. |
UploadProbe |
struct | What a node's probe found in an audio file it uploads (UploadFile::probe). The media type travels as UploadFile::content_type. |
WorkJob |
struct | A job handed to a host. |
OAuthEnrollAnswer |
struct | POST /api/node/v1/enroll/oauth answer. |
OAuthEnrollRequest |
struct | POST /api/node/v1/enroll/oauth body. Keys are base64url without padding. |
OwnerInfo |
struct | GET /api/node/v1/info answer. |
LookupAnswer |
struct | A branch's answer to one LookupWork. |
LookupEdition |
struct | One edition a branch can supply. |
LookupIdentifier |
struct | One identifier of the work a question is about. |
LookupWork |
struct | One question: "can you supply this work?". |
BranchOrigin |
struct | A branch's public origin: http or https, a host, an optional port and nothing else (no user, path, query or fragment), at most MAX_BRANCH_ORIGIN_BYTES bytes, in the form Url serializes it (lowercase scheme and host, default port dropped). |
BranchRequest |
struct | One request a branch claimed: "send this library that book". |
SecretEntry |
struct | One secret in a bundle. |
SecretRef |
struct | Names one encrypted_secrets row of a store account. It carries no secret material. |
SecretValue |
struct | Secret bytes: zeroized on drop, redacted in Debug, and base64url on the wire. |
SharedBranchBootstrap |
struct | What a shared branch receives at redeem: the [database] bootstrap and the DEK, for the node id the library recorded (kind = shared). Debug prints no secret. |
ArtifactRequest |
struct | What a signed artifact request covers. |
AuthContext |
struct | What a handshake signature covers. |
UploadPart |
struct | A part of a declared file: at least one byte, inside the file. |
WindowCopy |
struct | The copy of an edition's primary audio file a library holds, as its probe of the file found it: enough for a reader to decide whether to take the library's copy or fetch its own, without asking again. |
WindowCursor |
struct | Where a page of the person's books starts: an opaque key the library handed out as the previous page's next, or empty for the first page. |
WindowEdition |
struct | One edition of a WindowWork: the edition as the library holds it, and whether it is the person's own. |
WindowWork |
struct | One work the library holds for the window's person. |
ClerkFrame |
enum | A frame from a clerk to a library. |
ClerkSocketError |
enum | Why the library did not answer a books or copy.grant frame. |
ClerkTopic |
enum | Something a clerk hears about on the socket. Each names the routes to read again; the socket itself carries no row data. |
LibraryFrame |
enum | A frame from a library to a clerk. |
CopyAnswer |
enum | What the head of a download's answer says follows it (parse_copy_answer). |
CopyRange |
enum | What a download's Range header asks for (parse_copy_range). |
CopyRole |
enum | What a file of a copy is, as the library recorded it when it wrote the file. |
Body |
enum | What a frame says, tagged by type. |
ClaimScope |
enum | Whose work a host takes from a library (claim.filter.scope), as the branch operator set it for that link. |
FrameError |
enum | Why a frame was not accepted. |
KeeperOutcome |
enum | What a library did with a keeper's Body::AccountsUpdate. |
KeyError |
enum | Why a public key was refused. |
Availability |
enum | How a branch can supply an edition. |
LookupFormat |
enum | A file format a branch has for an edition. |
LookupScheme |
enum | Which kind of identifier a LookupIdentifier is. Only identifiers that name one edition or one work are asked about; anything else does not parse. |
RequestOutcome |
enum | What a branch did with a claimed request. |
SealError |
enum | Why a sealed box could not be made or opened. |
ConnectionType |
enum | How a joining install connects to a library. |
SharedBranchDatabase |
enum | The library's database, as a shared branch needs it to connect. |
AuthError |
enum | Why a handshake signature was refused. |
TunnelExposure |
enum | What public traffic may reach. |
TunnelRefusal |
enum | Why a tunnel request was refused. |
UploadRange |
enum | What a Content-Range on an upload PUT asks for. |
account_bundle_aad |
function | Associated data of the account bundle for node_id of library_id: the domain tag, then each field as a 4-byte big-endian length and its bytes. |
account_offer_aad |
function | Associated data of an account offer from node_id to its library library_id: ACCOUNT_OFFER_AAD_DOMAIN, then the two ids as in account_bundle_aad. |
check_account_bundle |
function | Checks bundle against every rule parse_account_bundle applies. |
open_account_bundle |
function | Opens a bundle made by seal_account_bundle with the joining node's box secret, for the library and node ids the redeem answered. |
open_account_offer |
function | Opens an offer made by seal_account_offer with the library's owner box secret, for the library id and the node id of the authenticated connection it arrived on. |
parse_account_bundle |
function | Parses the opened bytes of an account bundle for node_id of library_id and checks it (check_account_bundle). Sans-IO: the branch runs it on what open returns, and the fuzz target runs it on arbitrary bytes. |
seal_account_bundle |
function | Seals bundle to the joining node's box key recipient, as base64url text for the redeem answer. |
seal_account_offer |
function | Seals a branch's bundle to its library's owner box key recipient (crate::Body::Welcome), for crate::Body::AccountsAdd. The box is bound with account_offer_aad, so a joining bundle never opens as an offer, nor the other way round. |
is_ancestry |
function | True when every id in ancestry is a plain library id and there are at most MAX_ANCESTRY. |
is_library_id |
function | True for a plain library id in an ancestry. |
is_marketplace |
function | True for a marketplace: empty, or up to MAX_MARKETPLACE_BYTES lowercase ASCII letters and digits. |
is_product_id |
function | True for a product id: 1 to 256 bytes, no whitespace at the ends and no control characters. |
is_store_id |
function | True for a store id: a short lowercase token. |
clerk_exchange_matches |
function | True when request redeems stored: the code belongs to CLERK_CLIENT_ID, the redirect URI is the same, the method is S256 and the trimmed verifier hashes to the challenge (compared in constant time). |
clerk_request_problem |
function | Why a clerk authorization request is malformed, or None when the library may show its consent page. |
is_clerk_name |
function | True for a clerk name: 1 to MAX_CLERK_NAME_BYTES bytes, no control characters. |
is_clerk_token |
function | True for a session token: exactly CLERK_TOKEN_LEN base64url characters. |
is_s256_challenge |
function | True for an S256 code challenge: exactly 43 base64url characters. |
parse_clerk_authorization |
function | The session token in an Authorization header value, when the value is exactly Bookclerk-Clerk <token>. |
parse_clerk_query |
function | Parses an authorize query string (the raw query /oidc/authorize received), sans-IO so the fuzz target drives the same code. |
parse_clerk_token_answer |
function | Reads the library's POST /api/clerk/v1/token answer on the clerk. |
parse_clerk_token_request |
function | Reads a POST /api/clerk/v1/token body. |
is_topic_name |
function | True when name could be a topic name: 1 to MAX_CLERK_TOPIC_BYTES bytes of lowercase ASCII letters, digits, _ and .. |
parse_clerk_frame |
function | Reads a frame a clerk sent: at most MAX_CLERK_FRAME_BYTES, one JSON object with v (1), a known type, and exactly that type's fields, each once (a field written as null counts as absent). |
parse_library_frame |
function | Reads a frame a library sent: at most crate::MAX_FRAME_BYTES, one JSON object with v (1), a known type, and exactly that type's fields, each once. |
copy_answer_head_end |
function | Finds where the head of a download's answer ends in the bytes received so far, however the library's writes were cut into reads. |
copy_grant_problem |
function | Why a crate::Body::CopyGrant is malformed, or None: a store id, a marketplace (empty when the store has none) and a product id. |
copy_granted_problem |
function | Why a crate::Body::CopyGranted is malformed, or None: a copy id (is_copy_id), a non-empty sealed token of base64url text, a life of 1 to MAX_COPY_TOKEN_SECS seconds, a well-formed copy, and 1 to MAX_COPY_FILES well-formed files with distinct names, exactly one of them the primary audio (CopyRole::Audio). |
is_copy_id |
function | True for a copy id: a lowercase hyphenated UUID. |
parse_copy_answer |
function | Reads the head of the answer to a download of a file of size bytes that asked for the bytes from asked_from on (0 for the whole file). |
parse_copy_range |
function | Reads the Range header of a download of a file of size bytes. |
is_destination_id |
function | True when id is a destination id: a short lowercase token. |
is_storage_key |
function | True when key is a relative storage key: no empty, . or .. segment, no backslash or control character, not absolute, at most MAX_UPLOAD_KEY_BYTES, and never a Windows path that leaves the destination's root (colon_is_safe). |
scan_pass_end_problem |
function | Why a Body::ScanPassEnd the owner received is malformed, or None when it is one a host could send: a non-blank account id and a sync token of at most MAX_SCAN_SYNC_TOKEN_BYTES with no control characters. |
scan_removed_problem |
function | Why a Body::ScanRemoved the owner received is malformed, or None when it is one a host could send: a non-blank account id, at most MAX_SCAN_REMOVED_IDS product ids, each non-blank, at most MAX_SCAN_PRODUCT_ID_BYTES and free of control characters. |
target_destinations_problem |
function | Why target's destination list (AcquireTarget::destinations) does not fit the plan it came with, or None: every id it names is one of plan's destinations, named once, in the plan's order. |
is_branch_name |
function | True for a branch name: 1 to MAX_BRANCH_NAME_BYTES bytes, no control characters. |
is_branch_redirect_uri |
function | True for a redirect URI BRANCH_CLIENT_ID may use: an absolute https URL, or an http URL whose host is a loopback IP literal or localhost (RFC 8252 section 7.3), with no user info and no fragment. |
is_library_name |
function | True for a library name: 1 to MAX_LIBRARY_NAME_BYTES bytes, no control characters. |
pkce_challenge |
function | The RFC 7636 S256 challenge of verifier: base64url (no padding) of its SHA-256. |
box_public_key |
function | The X25519 public key of a 32-byte secret (clamped per RFC 7748). |
sign_public_key |
function | The Ed25519 public key of a 32-byte signing seed. |
validate_box_public_key |
function | Validates an X25519 public box key (a Montgomery u-coordinate). |
validate_sign_public_key |
function | Validates an Ed25519 public signing key. |
found_problem |
function | Why a crate::Body::CatalogFound is malformed, or None: at most MAX_LOOKUP_WORKS works named in all, each once, every answer well-formed and every missing work a correlation key. |
is_work_ref |
function | True for a correlation key: 1 to MAX_WORK_REF_BYTES ASCII letters, digits and -. |
questions_problem |
function | Why a list of questions is malformed, or None: at most MAX_LOOKUP_WORKS well-formed questions, each about a different work. |
claimed_problem |
function | Why a list of claimed requests is malformed, or None: at most MAX_CLAIMED_REQUESTS well-formed requests, each for a different job. |
finish_problem |
function | The problem with a requests.finish {job, generation} a library received, or None when both are ones it could have handed out. |
is_request_job |
function | True for a request's job id: 1 to MAX_REQUEST_JOB_BYTES ASCII letters, digits, - and _. |
copy_token_aad |
function | Associated data of the token for copy copy_id, granted to node_id. |
instance_secrets_aad |
function | Associated data of instance_id's SECRETS handed to node_id at document revision. |
open |
function | Opens a box sealed to the public key of recipient_secret. |
open_copy_token |
function | Opens a token made by seal_copy_token with the node's box secret. |
open_instance_secrets |
function | Opens a payload made by seal_instance_secrets with the node's box secret. |
open_secret_update |
function | Opens a write-back made by seal_secret_update with the owner's per-connection box secret. |
open_secrets |
function | Opens a bundle made by seal_secrets with the node's box secret. |
open_upload_token |
function | Opens a token made by seal_upload_token with the node's box secret. |
seal |
function | Seals plaintext to recipient (an X25519 public key) with the ephemeral secret ephemeral_secret, binding aad. |
seal_copy_token |
function | Seals a copy token for node_id's box key recipient, bound to the node and the copy, as base64url text for a copy.granted frame. The token is a bearer credential for the download endpoint, so it never travels as frame text. |
seal_instance_secrets |
function | Seals an instance's SECRETS payload (JSON bytes) for node_id's box key recipient, bound to the instance and document revision, as base64url text for an instance_config frame. |
seal_secret_update |
function | Seals a refreshed token to the owner's per-connection box key owner_box_key (from welcome), bound to the node, job, fence and ref, as base64url text for a secret.update frame. |
seal_secrets |
function | Seals entries for node_id's box key recipient, bound to job_id and fence, as base64url text for a work frame. |
seal_upload_token |
function | Seals an upload token for node_id's box key recipient, bound to the job, fence and upload, as base64url text for an upload.granted frame. The token is a bearer credential for the upload endpoint, so it never travels as frame text. |
secret_update_aad |
function | Associated data of a token write-back from node_id for secret_ref, handed with job_id under fence. |
secrets_aad |
function | Associated data of the secret bundle handed to node_id for job_id under lease generation fence: the domain tag, then each field as a 4-byte big-endian length and its bytes. |
upload_token_aad |
function | Associated data of the token for upload upload_id, granted to node_id for job_id under lease generation fence. |
open_shared_branch_bootstrap |
function | Opens a bootstrap made by seal_shared_branch_bootstrap with the joining node's box secret, for the library and node ids the redeem answered. |
seal_shared_branch_bootstrap |
function | Seals bootstrap to the joining node's box key recipient, as base64url text for the redeem answer. |
shared_branch_bootstrap_aad |
function | Associated data of a shared branch bootstrap for node_id of library_id: the domain tag, then each field as a 4-byte big-endian length and its bytes. |
artifact_transcript |
function | The bytes a host signs for an artifact request: the domain tag, then each field as a 4-byte big-endian length and its bytes. |
auth_transcript |
function | The bytes a host signs: the domain tag, then each field as a 4-byte big-endian length and its bytes. |
canonical_origin |
function | The ASCII origin (scheme://host[:port]) of an http(s) URL, with the default port and any path dropped and the host lowercased. |
decode_nonce |
function | Decodes a challenge nonce. |
encode_nonce |
function | Encodes a nonce as base64url without padding. |
parse_artifact_authorization |
function | Splits an artifact Authorization header into node id, issue time and signature. |
sign_artifact_request |
function | The Authorization header value of a signed artifact request. |
sign_auth |
function | Signs a handshake; the result is base64url without padding. |
verify_artifact_request |
function | Verifies a signed artifact request with the node's enrolled key and checks its time against now (unix seconds). |
verify_auth |
function | Verifies a handshake signature with the node's enrolled public key. Uses strict verification (no malleable or small-order signatures). |
normalize_tunnel_path |
function | The path the router matches for raw: the router trims trailing slashes and keeps exactly one leading slash, so //api/node/ routes as /api/node. |
tunnel_refusal |
function | Whether a tunnel request for path is refused. |
parse_upload_range |
function | Reads a Content-Range header value on an upload PUT of a declared file of size bytes. |
upload_parts |
function | The parts a host sends a file of size bytes in, each at most part_bytes (at least 1) long, in order; empty when the file fits in one request (size <= part_bytes), which is then sent whole. |
window_page_problem |
function | Why a crate::Body::WindowPage is malformed, or None: at most MAX_WINDOW_WORKS well-formed works with distinct grouping keys, and a next cursor, when there is one, past after (the cursor the window asked with), so paging always moves forward. |
ACCOUNT_BUNDLE_AAD_DOMAIN |
constant | Domain tag that starts the associated data of an account bundle. |
ACCOUNT_BUNDLE_VERSION |
constant | Version of an AccountBundle. |
ACCOUNT_OFFER_AAD_DOMAIN |
constant | Domain tag that starts the associated data of an account offer: a branch's AccountBundle sent up to its library (crate::Body::AccountsAdd). A distinct tag keeps a bundle sealed in one direction from opening as the other. |
MAX_ACCOUNT_BUNDLE_BYTES |
constant | Largest opened bundle accepted, in bytes. A bundle at every limit above would be far larger; this keeps the redeem answer small. |
MAX_ACCOUNT_SECRETS |
constant | Most secrets one carried account holds. |
MAX_BUNDLE_ACCOUNTS |
constant | Most accounts one bundle carries. |
MAX_CARRIED_ACCOUNT_ID_BYTES |
constant | Longest store account id carried, in bytes. |
MAX_CARRIED_FIELD_BYTES |
constant | Longest source alias, marketplace, secret kind or label carried, in bytes. |
MAX_CARRIED_PLUGIN_KEY_BYTES |
constant | Longest plugin key carried, in bytes. |
MAX_CARRIED_SECRET_BYTES |
constant | Largest secret value carried, in bytes. |
CATALOG_ITEM |
constant | Item kind of the catalog fence (lost.item), and the job id a catalog upload's token is sealed for. |
MAX_ANCESTRY |
constant | Most library ids an ancestry may list. |
MAX_CATALOG_BATCH_TITLES |
constant | Most titles one crate::Body::CatalogSync batch may carry. |
MAX_CATALOG_CURSOR_BYTES |
constant | Longest cursor. |
MAX_CATALOG_TITLE_BYTES |
constant | Largest serialized title in a batch. |
MAX_CATALOG_WANTED |
constant | Most titles one answer may say are wanted. |
MAX_MARKETPLACE_BYTES |
constant | Longest marketplace. |
CLERK_AUTH_SCHEME |
constant | The Authorization scheme a clerk sends its session token under. |
CLERK_CALLBACK_PATH |
constant | The clerk's own web app page a clerk sign-in's redirect comes back to (<clerk origin>/clerk/callback?code=…&state=…). |
CLERK_CLIENT_ID |
constant | The built-in public OAuth client a clerk signs in through. It is never stored in the library's clients table. |
CLERK_CODE_TTL_SECS |
constant | Seconds an authorization code for CLERK_CLIENT_ID lives. |
CLERK_IDLE_DAYS |
constant | Days a clerk session stays signed in without being used. Each use moves the expiry forward again. |
CLERK_SCOPE |
constant | The only scope CLERK_CLIENT_ID may ask for. |
CLERK_TOKEN_LEN |
constant | Length of a session token: base64url (no padding) of 32 random bytes. |
CLERK_TOKEN_PATH |
constant | POST: redeem an approved clerk sign-in for a session token. |
MAX_CLERK_ANSWER_BYTES |
constant | Largest POST /api/clerk/v1/token answer a clerk reads. |
MAX_CLERK_DISPLAY_NAME_BYTES |
constant | Longest display name a clerk keeps from a token answer. |
MAX_CLERK_NAME_BYTES |
constant | Longest clerk name sent. |
MAX_CLERK_STATE_BYTES |
constant | Longest state an authorize request may carry. |
CLERK_CONNECT_PATH |
constant | Path of the clerk socket. |
CLERK_SOCKET_VERSION |
constant | The v every frame carries. |
CLERK_SUBPROTOCOL |
constant | The WebSocket subprotocol a clerk must offer. |
MAX_CLERK_FRAME_BYTES |
constant | Largest frame a library accepts from a clerk, in bytes; a books frame is under 120. |
MAX_CLERK_TOPICS |
constant | Most topic names one hello or changed frame may carry, known or not. |
MAX_CLERK_TOPIC_BYTES |
constant | Longest topic name, in bytes. |
COPIES_PATH |
constant | Path prefix of the download endpoint: the files of copy <copy_id> are at COPIES_PATH<copy_id>/files/<n>. |
COPY_AUTH_SCHEME |
constant | Authorization scheme of the download endpoint. |
MAX_COPY_ANSWER_HEAD_BYTES |
constant | Longest head of a download's answer a reader takes, in bytes: the status line and headers, before the blank line. |
MAX_COPY_FILES |
constant | Most files one crate::Body::CopyGranted may list. |
MAX_COPY_FILE_BYTES |
constant | Largest CopyFile::size (1 TiB): above any audiobook file. |
MAX_COPY_NAME_BYTES |
constant | Longest CopyFile::name, in bytes. |
MAX_COPY_TOKEN_SECS |
constant | Longest a copy token may be stated to live, in seconds (one day). |
ITEM_JOB |
constant | Work item kind for jobs. |
MAX_CALL_NUMBER_BYTES |
constant | Longest call number (see CallNumber). |
MAX_DESTINATION_ID_BYTES |
constant | Longest destination id. |
MAX_PROBE_BITRATE_KBPS |
constant | Highest bitrate an UploadProbe may state, in kilobits per second: above any audiobook encoding, so a forged value cannot win by size alone. |
MAX_SCAN_BATCH_ROWS |
constant | Most rows one Body::ScanResults batch may carry. |
MAX_SCAN_PRODUCT_ID_BYTES |
constant | Longest product id a Body::ScanRemoved batch may carry. |
MAX_SCAN_REMOVED_IDS |
constant | Most product ids one Body::ScanRemoved batch may carry (a scan page's own cap). |
MAX_SCAN_ROW_BYTES |
constant | Largest serialized row in a Body::ScanResults batch. |
MAX_SCAN_SYNC_TOKEN_BYTES |
constant | Longest sync token a Body::ScanPassEnd or ScanToken may carry (a scan page's own cap). |
MAX_SCAN_TOKENS |
constant | Most ScanTokens one WorkJob may carry. |
MAX_STATUS_JOBS |
constant | Most job ids one Body::JobStatus may ask about. |
MAX_UPLOAD_COPIES |
constant | Most destinations one uploaded file may be written to. |
MAX_UPLOAD_FILES |
constant | Most files one upload may declare. |
MAX_UPLOAD_FILE_BYTES |
constant | Largest file one upload may declare (8 GiB). |
MAX_UPLOAD_KEY_BYTES |
constant | Longest storage key an upload may declare. |
AUTHORIZE_PATH |
constant | The owner's authorization endpoint (path). |
BRANCH_CLIENT_ID |
constant | The built-in public OAuth client a joining branch signs in through. It is never stored in the owner's clients table. |
BRANCH_CODE_TTL_SECS |
constant | Seconds an authorization code for BRANCH_CLIENT_ID lives. |
BRANCH_SCOPE |
constant | The only scope BRANCH_CLIENT_ID may ask for. |
ENROLL_OAUTH_PATH |
constant | POST: redeem an approved branch sign-in. |
INFO_PATH |
constant | GET: what a library tells a joining install before sign-in. |
JOIN_CALLBACK_PATH |
constant | Path of the joining install's own callback (the SPA route the browser returns to, and the CLI's loopback listener). |
MAX_BRANCH_NAME_BYTES |
constant | Longest branch name sent. |
MAX_LIBRARY_NAME_BYTES |
constant | Longest library name accepted: a library is named by its public host, and a DNS name runs to 253 bytes. |
PUBLIC_KEY_LEN |
constant | Length of either public key. |
MAX_LOOKUP_EDITIONS |
constant | Most editions one LookupAnswer may list. |
MAX_LOOKUP_IDENTIFIERS |
constant | Most identifiers one LookupWork may carry. |
MAX_LOOKUP_WORKS |
constant | Most works one crate::Body::CatalogAsk or crate::Body::CatalogFound may name. |
MAX_WORK_REF_BYTES |
constant | Longest correlation key (LookupWork::work). |
MAX_BRANCH_ORIGIN_BYTES |
constant | Longest origin a branch may report, in bytes. |
ITEM_REQUEST |
constant | The work item name of a request in a crate::Body::Lost answer. |
MAX_CLAIMED_REQUESTS |
constant | Most requests one crate::Body::RequestsClaimed may carry. |
MAX_REQUEST_JOB_BYTES |
constant | Longest job id a request may carry. |
COPY_TOKEN_AAD_DOMAIN |
constant | Domain of the associated data of a sealed copy token. |
INSTANCE_SECRETS_AAD_DOMAIN |
constant | Domain tag that starts the associated data of an instance's SECRETS. |
SEALED_BOX_INFO |
constant | HKDF info string of a sealed box. |
SEALED_BOX_OVERHEAD |
constant | Bytes a sealed box adds to its plaintext (ephemeral key and tag). |
SECRETS_AAD_DOMAIN |
constant | Domain tag that starts the associated data of a secret bundle. |
SECRET_UPDATE_AAD_DOMAIN |
constant | Domain tag that starts the associated data of a token write-back. |
UPLOAD_TOKEN_AAD_DOMAIN |
constant | Domain tag that starts the associated data of an upload token. |
DEK_LEN |
constant | Length of the data-encryption key. |
SHARED_BRANCH_BOOTSTRAP_AAD_DOMAIN |
constant | Domain tag that starts the associated data of a shared branch bootstrap. |
SHARED_BRANCH_BOOTSTRAP_VERSION |
constant | Version of SharedBranchBootstrap. |
SHARED_BRANCH_GRANTED_SCOPE |
constant | The scope a shared branch code is granted (stored with the code at consent). |
SHARED_BRANCH_OFFER_PARAM |
constant | Authorize-request parameter by which a joining install offers to join as a shared branch (shared_branch_offer=1): it is empty, so its own data may be replaced. Without it the consent page offers a branch only. |
ARTIFACT_AUTH_SCHEME |
constant | Authorization scheme of a signed artifact request: Bookclerk-Node <node_id> <issued_at> <sig>. |
ARTIFACT_DOMAIN |
constant | Domain tag that starts every signed artifact request. |
ARTIFACT_REQUEST_MAX_SKEW_SECS |
constant | How far a signed artifact request's time may be from the owner's clock. |
AUTH_DOMAIN |
constant | Domain tag that starts every signed transcript. |
NONCE_LEN |
constant | Length of a challenge nonce. |
BRANCH_API_PATHS |
constant | API paths TunnelExposure::Branches serves. Each also covers the paths below it. |
LEGACY_CONTROL_PATHS |
constant | Legacy control routes outside /api/ that TunnelExposure::Branches refuses. Each also covers the paths below it. |
OPERATOR_ONLY_PATHS |
constant | Paths no tunnel request reaches: the operator-token sign-in, the loopback tray handoff, operator elevation and the operator's first-Owner bootstrap. Each also covers the paths below it. |
UPLOAD_PART_BYTES |
constant | Largest part a host sends (64 MiB): under the request-body caps of the relays an install can sit behind (100 MB on Cloudflare's Free plan). |
MAX_COPY_CONTENT_TYPE_BYTES |
constant | Longest WindowCopy::content_type, in bytes. |
MAX_COPY_VERSION_BYTES |
constant | Longest WindowCopy::version, in bytes. |
MAX_WINDOW_WORKS |
constant | Most works one crate::Body::WindowPage may carry. |
ARTIFACTS_PATH |
constant | Path prefix of the owner's artifact endpoint: GET /api/node/v1/artifacts/<archive_sha256> with a signed Authorization (sign_artifact_request) streams one stored archive to a host that runs it. |
UPLOADS_PATH |
constant | Path prefix of the owner's upload endpoint (H-4 design, section 6): PUT|HEAD <prefix><upload_id>/files/<n> streams one declared file and POST <prefix><upload_id>/commit commits the title, each with Authorization: Bookclerk-Upload <token> (UPLOAD_AUTH_SCHEME). |
UPLOAD_AUTH_SCHEME |
constant | Authorization scheme of the upload endpoint. |
SUBPROTOCOL |
constant | WebSocket subprotocol a host must offer. |
FRAME_VERSION |
constant | Frame envelope version (v). |
MAX_FRAME_BYTES |
constant | Largest frame either side accepts (1 MiB). |
PING_INTERVAL_SECS |
constant | Seconds between pings from each side. |
IDLE_TIMEOUT_SECS |
constant | Seconds without any inbound frame before a side closes the connection. |
SEND_QUEUE_FRAMES |
constant | Frames a side queues for sending before it stops forwarding wakes and waits for the peer to read. |
HANDSHAKE_TIMEOUT_SECS |
constant | Seconds the owner waits for each handshake frame. |
CLOSE_AUTH_FAILED |
constant | Close code: the handshake failed (unknown node, bad signature, or a malformed or late handshake frame). |
CLOSE_REVOKED |
constant | Close code: the node's credential is revoked. |
CLOSE_SUPERSEDED |
constant | Close code: a newer authenticated connection for the same node replaced this one. |
CLOSE_PROTOCOL |
constant | Close code: a frame broke the protocol after the handshake (binary, oversized, malformed, or the wrong version). |
pub struct AccountBundle {
pub v: u32,
pub library_id: String,
pub node_id: String,
pub accounts: Vec<CarriedAccount>,
}
The store accounts a library hands a joining branch, for one person.
Debug prints no secret.
Fields
v:ACCOUNT_BUNDLE_VERSION.library_id: The library id.node_id: The node id the library minted for the branch.accounts: The person's accounts, each with its secrets.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct CarriedAccount {
pub plugin_key: String,
pub account_id: String,
pub source: String,
pub marketplace: String,
pub label: Option<String>,
pub secrets: Vec<CarriedSecret>,
}
One store account in an AccountBundle.
Fields
plugin_key: Provenance-qualified plugin key of the storefront that owns the account.account_id: Store account id, unique within its plugin key.source: Display alias of the storefront (libro,chirp, ...).marketplace: Store marketplace or locale code (us,uk, ...).label: The account's display label, when it has one.secrets: The account's sealed secrets, unsealed for the box.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct CarriedSecret {
pub kind: String,
pub name: String,
pub value: SecretValue,
}
One secret of a [CarriedAccount]: an encrypted_secrets row of the
account, by kind and name.
Fields
kind: Secret kind (source_auth, ...).name: Logical secret name within the account.value: The secret bytes.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct CatalogFile {
pub key: String,
pub size: u64,
pub content_type: Option<String>,
}
One file of a CatalogTitle.
Fields
key: Relative storage key (the same on every destination of the receiving library).size: Size in bytes.content_type: MIME type.
Implements: Clone, Debug, Deserialize<'de>, Eq, Ord, PartialEq, PartialOrd, Serialize
pub struct CatalogMetadata {
pub title: String,
pub subtitle: Option<String>,
pub authors: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_index: Option<String>,
pub asin: Option<String>,
pub isbn: Option<String>,
pub publisher: Option<String>,
pub length_minutes: Option<i64>,
pub content_kind: Option<String>,
pub language: Option<String>,
pub published_at: Option<String>,
}
Bibliographic metadata of a CatalogTitle.
Fields
title: Display title.subtitle: Subtitle.authors: Authors as the store lists them.narrators: Narrators.series: Series name.series_index: Position in the series.asin: Amazon ASIN.isbn: ISBN.publisher: Publisher.length_minutes: Runtime in minutes.content_kind:book,episode, ...language: Language code.published_at: Publication date text.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct CatalogRef {
pub store: String,
pub product_id: String,
}
A title named by store and product id.
Fields
store: Store id.product_id: Product id.
Implements: Clone, Debug, Deserialize<'de>, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize
pub struct CatalogTitle {
pub store: String,
pub product_id: String,
pub marketplace: String,
pub metadata: CatalogMetadata,
pub primary_key: String,
pub pdf_key: Option<String>,
pub files: Vec<CatalogFile>,
}
One title, as a branch shares it.
Fields
store: The store that sells it, as the store's plain id (audible,libro, ...).product_id: The store's product id (ASIN, ISBN, ...).marketplace: Lower-cased marketplace of the store listing (us,uk); empty when the store has none. The receiving library scopes the ASIN to it, so the title meets the same edition there.metadata: Bibliographic metadata.primary_key: Storage key of the primary audio file (one offiles).pdf_key: Storage key of the companion PDF (one offiles), when shared.files: Every file of the title.
pub fn reference(&self) -> CatalogRef
The title's CatalogRef.
pub fn problem(&self) -> Option<&'static str>
Why the title is malformed, or None: the store, product id and
marketplace, a non-empty bounded title and bounded metadata, between one and
MAX_UPLOAD_FILES files with distinct storage keys within
MAX_UPLOAD_FILE_BYTES, and the primary key (and PDF key) among
them.
pub fn manifest_digest(&self) -> String
Lowercase hex SHA-256 of the title's manifest (primary key, PDF key and files, sorted by key): equal digests mean the same files.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct ClerkAuthorizeParams {
pub client_id: String,
pub redirect_uri: String,
pub response_type: String,
pub scope: Option<String>,
pub state: Option<String>,
pub code_challenge: String,
pub code_challenge_method: Option<String>,
pub clerk_name: Option<String>,
}
The authorization request a clerk consent is for (the query
/oidc/authorize forwards to the library's /clerk/approve page).
Fields
client_id: Must beCLERK_CLIENT_ID.redirect_uri: Where the code goes: loopback or https.response_type: Must becode.scope: Must beCLERK_SCOPE.state: Echoed on the redirect.code_challenge: PKCE S256 challenge.code_challenge_method: Must beS256.clerk_name: The name the clerk gives itself, shown on the consent page and in the user's session list.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, IntoParams, PartialEq, ToSchema
pub struct ClerkTokenAnswer {
pub token: String,
pub library_id: String,
pub user: ClerkUser,
pub idle_secs: i64,
}
POST /api/clerk/v1/token answer.
Fields
token: The session token, sent asAuthorization: Bookclerk-Clerk <token>. Shown once; the library keeps only its hash.library_id: The library id.user: The signed-in person on that library.idle_secs: Seconds the session stays signed in unused; each use resets it.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct ClerkTokenRequest {
pub code: String,
pub code_verifier: String,
pub redirect_uri: String,
}
POST /api/clerk/v1/token body: exactly these three strings, each
once, and nothing else.
Fields
code: The single-use code from the redirect.code_verifier: The PKCE verifier whose S256 challenge the authorize request sent.redirect_uri: The redirect URI the authorize request named.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct ClerkUser {
pub id: i64,
pub display_name: Option<String>,
}
The person a clerk session signs in as.
Fields
id: The user's id on the library.display_name: The user's display name on the library, when set.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct StoredClerkCode<'a> {
pub client_id: &'a str,
pub redirect_uri: &'a str,
pub method: &'a str,
pub challenge: &'a str,
}
What the library stored with an approved code, as the token exchange checks it.
Fields
client_id: The OAuth client the code was approved for.redirect_uri: The redirect URI the authorize request named.method: The PKCE method the authorize request named.challenge: The PKCE challenge the authorize request sent.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct ClerkCopy {
pub store: String,
pub marketplace: String,
pub product_id: String,
pub copy_id: String,
pub token: CopyToken,
pub expires_in_secs: u64,
pub copy: WindowCopy,
pub files: Vec<CopyFile>,
}
What a copy.granted frame carries.
Fields
store: Store id of the listing the clerk asked with.marketplace: That listing's marketplace; empty for a store without marketplaces.product_id: That listing's product id.copy_id: Copy id; the files are atCOPIES_PATH<copy_id>/files/<n>.token: The bearer token for the download endpoint.expires_in_secs: Seconds the token stays valid.copy: What the copy is, as the library's page states it.files: The copy's files; a file's index here is its<n>.
pub fn problem(&self) -> Option<&'static str>
Why the grant is malformed, or None: a listing that passes
copy_grant_problem and the rest passing
copy_granted_problem, the token held to the same rule as a
node's sealed one (1 to 1024 base64url characters).
Implements: Clone, Debug, Eq, PartialEq
pub struct CopyToken(/* private */);
A copy token as a clerk socket frame carries it: the bearer of the
download endpoint (crate::COPY_AUTH_SCHEME). Its Debug prints no
token, and the text is zeroized when dropped.
pub fn new(token: &str) -> Self
Wraps token.
pub fn expose(&self) -> &str
The token text, for the Authorization header.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct CopyFile {
pub name: String,
pub role: CopyRole,
pub size: u64,
pub content_type: Option<String>,
pub probe: Option<UploadProbe>,
}
One file of a copy (crate::Body::CopyGranted).
Fields
name: The file's path below the title's folder on the library,/separated (crate::is_storage_key, at mostMAX_COPY_NAME_BYTES). The reader places it under its own naming, so this is a hint to what the file is, never a path to write to as given.role: What the file is.size: Exact size in bytes, at mostMAX_COPY_FILE_BYTES.content_type: The media type the library's probe found, for a probed audio file.probe: What the library's probe found in an audio file; absent for other files and for audio it has not probed.
pub fn is_well_formed(&self) -> bool
True when the name is a relative path within its length limit, the
size is within MAX_COPY_FILE_BYTES, the media type (if stated)
is a media type token and the probe (if stated) is well formed.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct CopyGrantedFrame<'a> {
pub copy_id: &'a str,
pub sealed_token: &'a str,
pub expires_in_secs: u64,
pub copy: &'a WindowCopy,
pub files: &'a [CopyFile],
}
The fields of a crate::Body::CopyGranted, borrowed for
copy_granted_problem.
Fields
copy_id: The copy id.sealed_token: The sealed token text.expires_in_secs: Seconds the token stays valid.copy: What the copy is.files: The copy's files.
Implements: Clone, Copy, Debug
pub struct AcquireTarget {
pub holding_id: String,
pub plugin_key: String,
pub account_id: String,
pub title: TargetTitle,
pub parent: Option<TargetTitle>,
pub call_number: Option<CallNumber>,
pub parent_call_number: Option<CallNumber>,
pub destinations: Option<Vec<String>>,
}
One title an acquire job should fetch on a host
(Body::AcquireTargets).
Fields
holding_id: The owner's account holding of the title (holdings.id): the id the host's upload of it names.plugin_key: Plugin key of the store that sells it.account_id: Store account that owns it.title: The title as the owner's library holds it, for naming and metadata.parent: The title's podcast parent as the owner's library holds it, when the title is an episode whose show an account of the same store holds there: a destination that saves episodes to the parent's folder names them from it, as an acquire on the owner would.call_number: The title's call number on the owner (the short id of its edition there), which the<call number>naming tag writes. A host acquires into a scratch library whose edition ids differ, so it names with this one to plan the same keys the owner grants.parent_call_number: The podcast parent's call number on the owner, for a destination that saves episodes to the parent's folder.destinations: The ids of the plan's destinations whose filter takes this title, in the plan's order: the title's target set, which the host writes and uploads to and nowhere else. An empty list means no destination takes it, so the host fails the title without fetching it.Nonecomes from an owner that predates destination filters and means every destination of the plan.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct CallNumber(/* private */);
A title's short call number as the owner names it: 1 to
MAX_CALL_NUMBER_BYTES ASCII letters and digits, so it is safe in any
storage key segment. Deserializing anything else fails, which refuses
the whole frame.
pub fn as_str(&self) -> &str
The id as text.
Implements: Clone, Debug, Deserialize<'de>, Eq, From<CallNumber>, PartialEq, Serialize, TryFrom<String>
pub struct ClaimFilter {
pub kinds: Vec<String>,
pub plugins: Vec<String>,
pub scope: ClaimScope,
}
What a host is willing to claim (claim.filter).
Fields
kinds: Job kinds the host runs.plugins: Plugin keys the host's operator consented to.scope: Whose work the host takes. Absent meansClaimScope::Own.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct FileCopy {
pub destination: String,
pub key: String,
}
Where one uploaded file is written: a destination and its key there.
Fields
destination: APlanDestination::id.key: Storage key on that destination.
Implements: Clone, Debug, Deserialize<'de>, Eq, Ord, PartialEq, PartialOrd, Serialize
pub struct Frame {
pub v: u32,
pub id: String,
pub body: Body,
}
One frame: the envelope and its body.
Fields
v: Envelope version; alwaysFRAME_VERSION.id: Request id, echoed by the answer.body: The body, tagged bytype.
pub fn new(id: impl Into<String>, body: Body) -> Self
A version-1 frame.
pub fn parse(text: &str) -> Result<Self, FrameError>
Parses a text frame, checking size and version.
Returns FrameError for an oversized, malformed, or wrong-version
frame.
pub fn to_text(&self) -> String
Serializes the frame as JSON text.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct HeldFence {
pub kind: String,
pub id: String,
pub fence: i64,
}
A lease the host still holds when it reconnects (hello.resume).
Fields
kind:jobordelivery.id: Job id or delivery id.fence: Lease generation the host holds.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct JobStatusEntry {
pub id: String,
pub kind: String,
pub state: String,
pub progress: Option<String>,
pub error_kind: Option<String>,
pub error_message: Option<String>,
}
One job's state in Body::JobStatuses.
Fields
id: Job id.kind: Job kind (scan,acquire, ...).state:pending,running,succeeded,failed, orcancelled.progress: Progress or result text.error_kind: Structured error kind when it failed or was cancelled.error_message: Error text when it failed or was cancelled.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct PlanDestination {
pub id: String,
pub options: Value,
}
One output destination of the shared node that answered an acquire plan
(Body::AcquireTargets).
Fields
id: Destination id on that shared node: its storage plugin's id, such aslocal,s3orr2(one destination per plugin).options: That destination'sDownloadOptions(JSON): its naming templates, replacement characters and path limits.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct RemoteArtifact {
pub target: String,
pub url: String,
pub format: String,
pub archive_root: String,
pub archive_sha256: String,
pub payload_root_sha256: String,
pub executable: String,
}
One downloadable artifact of a RemoteVersion.
Fields
target: Bookclerk target (linux-x64-gnu,any, ...).url:https:URL, orblob:sha256:<hex>for an archive the owner stores (fetched from the owner's artifact endpoint,crate::ARTIFACTS_PATH).format: Archive format.archive_root: Path inside the archive to the plugin root.archive_sha256: SHA-256 of the archive.payload_root_sha256: Payload-root digest of the extracted tree.executable: Executable inside the plugin root.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct RemoteDeployment {
pub deployment_id: String,
pub instance_id: String,
pub plugin_key: String,
pub desired: String,
pub revision: i64,
pub default_instance: bool,
pub version: Option<RemoteVersion>,
}
One deployment that targets a host (deployments.items).
Fields
deployment_id: Deployment id.instance_id: Plugin instance the deployment runs.plugin_key: The instance's plugin key.desired: Desired state (present,placed).revision: Desired-row revision.default_instance: True for the plugin's default instance (unpinned jobs use it).version: The plugin's active version; absent when none is installed.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct RemoteVersion {
pub version: String,
pub manifest_id: String,
pub manifest_toml: String,
pub settings: Value,
pub artifacts: Vec<RemoteArtifact>,
pub grant_json: String,
pub publisher_verified: bool,
}
The active version of a plugin a host is asked to run.
Fields
version: Semver version.manifest_id: Manifest id (display alias).manifest_toml:plugin.tomltext.settings: Settings schema the version declares (JSON).artifacts: Per-target artifacts.grant_json: The grant the library's operator approved (JSON); empty while the version is unapproved, in which case nothing runs.publisher_verified: True when the publisher was verified at install.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct ScanImport {
pub import_episodes: bool,
pub import_plus_titles: bool,
}
The owner's library import settings a host scan runs with.
Fields
import_episodes: Import podcast episodes.import_plus_titles: Import subscription (Plus) titles.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct ScanToken {
pub account_id: String,
pub sync_token: String,
}
The sync token an owner holds for one account a host scan covers.
Fields
account_id: The store account.sync_token: The token, at mostMAX_SCAN_SYNC_TOKEN_BYTES.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct TargetTitle {
pub product_id: String,
pub source: String,
pub marketplace: String,
pub asin: Option<String>,
pub isbn: Option<String>,
pub title: String,
pub subtitle: Option<String>,
pub authors: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_index: Option<String>,
pub series_product_id: Option<String>,
pub publisher: Option<String>,
pub categories: Option<String>,
pub length_minutes: Option<i64>,
pub is_abridged: bool,
pub content_kind: String,
pub purchased_at: Option<String>,
pub published_at: Option<String>,
}
A title an AcquireTarget names, as the owner's library holds it:
the store listing's identity and the metadata a host names the title's
files from and seeds its scratch library with. The store and account
are the target's own.
Fields
product_id: The store's product id of the listing (what the store fetches).source: The store's source name (audible,librofm, ...), as the listing's plugin reports it.marketplace: The store marketplace the listing is sold in (us,uk, ...).asin: The edition's ASIN, when it has one.isbn: The edition's ISBN, when it has one.title: The listing's title.subtitle: The listing's subtitle.authors: Authors, comma-separated, as the listing gives them.narrators: Narrators, comma-separated, as the listing gives them.series: The series name, when the title is in one.series_index: The title's position in its series, as text (1,2.5).series_product_id: The store's product id of the series, or of an episode's show.publisher: The publisher.categories: Categories, comma-separated, as the listing gives them.length_minutes: Running time in whole minutes.is_abridged: Whether the listing is abridged.content_kind:book,podcastorepisode.purchased_at: When the account bought it, RFC 3339.published_at: When it was published, RFC 3339.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct UploadAnswer {
pub status: String,
pub reason: Option<String>,
pub offset: Option<u64>,
pub job_completed: bool,
}
Answer of the upload endpoint (every status carries one).
Fields
status: Stable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reason: Why, forrefused, andresumefor anunavailablepart that does not continue the open file atSelf::offset.offset: Forpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs.job_completed: Forcommitted: the job is finished.
Implements: Clone, ComposeSchema, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct UploadCommitRequest {
pub finish: bool,
pub detail: Option<String>,
}
Body of POST <UPLOADS_PATH><upload_id>/commit.
Fields
finish: Complete the job with this commit (the job's closing upload).detail: Outcome text recorded as the job's progress whenfinishis set.
Implements: Clone, ComposeSchema, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct UploadFile {
pub copies: Vec<FileCopy>,
pub size: u64,
pub sha256: String,
pub content_type: Option<String>,
pub probe: Option<UploadProbe>,
}
One file of an upload (Body::UploadGrant). Its content crosses the
network once and is written to every copy, each destination under the
key that destination's own naming options give it.
Fields
copies: Where the file is written; at most one copy per destination.size: Exact size in bytes.sha256: Lowercase hex SHA-256 of the content.content_type: MIME type to store with it.probe: What the sender's probe found in an audio file, so the library keeps it on the file's row without reading the file back; absent for other files and for audio the sender could not probe.
pub fn is_well_formed(&self) -> bool
True when the file has between one and MAX_UPLOAD_COPIES
copies, each naming a different destination id
(is_destination_id) and a storage key (is_storage_key); the
size is within MAX_UPLOAD_FILE_BYTES; the digest is lowercase
hex SHA-256; and the probe, if there is one, is well formed
(UploadProbe::is_well_formed).
pub fn key_on(&self, destination: &str) -> Option<&str>
This file's key on destination, if it is written there.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct UploadProbe {
pub bitrate_kbps: Option<u32>,
pub lossless: bool,
pub source_store: Option<String>,
}
What a node's probe found in an audio file it uploads
(UploadFile::probe). The media type travels as
UploadFile::content_type.
The library stores these values as the sender states them: the sender is a node it trusts with the title, and they decide only which of two copies of one edition is kept.
Fields
bitrate_kbps: Average audio bitrate in kilobits per second, 1 toMAX_PROBE_BITRATE_KBPS; absent when the file states no running time.lossless: True for a lossless encoding (FLAC, ALAC).source_store: Plain id of the storefront the copy was downloaded from (crate::is_store_id), when the sender knows it.
pub fn is_well_formed(&self) -> bool
True when the bitrate, if stated, is 1 to
MAX_PROBE_BITRATE_KBPS and the storefront, if named, is a store
id (crate::is_store_id).
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct WorkJob {
pub id: String,
pub kind: String,
pub payload: Value,
pub attempt: i64,
pub scan_import: Option<ScanImport>,
pub for_node_owner: bool,
pub scan_tokens: Vec<ScanToken>,
}
A job handed to a host.
Fields
id: Job id.kind: Job kind (scan,acquire, ...).payload: Kind-specific payload, as the owner stores it.attempt: Claims of this job so far, this one included.scan_import: For a scan: which titles the owner's library imports. The owner writes every row a host returns, so the host scans with the owner's settings, never its own. Absent for other kinds.for_node_owner: True when every store account the job touches belongs to the user who owns the node: the branch's own books. A branch keeps its own copy of another member's book only when its operator asked for that. Absent means false.scan_tokens: For a scan: the sync token the owner holds for each handed account whose last complete pass is recent enough to build on. The host's guest runs a delta pass from it; an account without one runs a full pass. At mostMAX_SCAN_TOKENSentries. Absent means none.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct OAuthEnrollAnswer {
pub library_id: String,
pub node_id: String,
pub connection: ConnectionType,
pub bootstrap: Option<String>,
pub accounts: Option<String>,
}
POST /api/node/v1/enroll/oauth answer.
Fields
library_id: The library id.node_id: The node id recorded for the joining install.connection: The connection type recorded (branchwhen left out).bootstrap: For a shared branch: thecrate::SharedBranchBootstrapsealed to the node's box key (crate::seal_shared_branch_bootstrap), as base64url without padding.accounts: For a branch whose user chose "Bring my store connections to this branch": the user's own store accounts as acrate::AccountBundlesealed to the node's box key (crate::seal_account_bundle), as base64url without padding. Left out when the user did not choose it or had none to bring.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct OAuthEnrollRequest {
pub code: String,
pub code_verifier: String,
pub redirect_uri: String,
pub sign_pk: String,
pub box_pk: String,
pub branch_name: String,
pub software_version: String,
pub connection: ConnectionType,
}
POST /api/node/v1/enroll/oauth body. Keys are base64url without
padding.
Fields
code: The authorization code from the callback.code_verifier: The PKCE verifier.redirect_uri: The redirect URI the authorization was requested with.sign_pk: Ed25519 public signing key.box_pk: X25519 public box key.branch_name: The name this branch joins as (the node's label).software_version: The joining install's Bookclerk version.connection: The connection type the code was approved for. It must match the one bound to the code at consent; left out for a branch.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct OwnerInfo {
pub library_id: String,
pub library_name: String,
pub origin: String,
pub transport: String,
pub enrollment: bool,
pub spki_fingerprint: Option<String>,
pub software_version: String,
pub ancestry: Vec<String>,
}
GET /api/node/v1/info answer.
Fields
library_id: The library id.library_name: A name to show for the library.origin: The library's canonical origin: the one the node handshake signs and the authorize endpoint lives under.transport: The node API transport mode (acme,proxy,self_signed,loopback).enrollment: Whether the library lets new branches join (core.branch_enrollment).spki_fingerprint: Inself_signedmode: base64url SHA-256 of the certificate's SubjectPublicKeyInfo, which the joining operator confirms against the owner's Settings → Branches page.software_version: The library's Bookclerk version.ancestry: The library's ancestry: its own library id first, then the library id of every library above it up to the root. A joining library refuses a parent whose ancestry names its own library id, so a tree of libraries never becomes a cycle.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct LookupAnswer {
pub work: String,
pub editions: Vec<LookupEdition>,
}
A branch's answer to one LookupWork.
Fields
work: The question'sLookupWork::work.editions: What the branch can supply; 1 toMAX_LOOKUP_EDITIONSeditions.
pub fn problem(&self) -> Option<&'static str>
Why the answer is malformed, or None: a correlation key, and 1 to
MAX_LOOKUP_EDITIONS well-formed editions with distinct
(store, marketplace, product id).
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct LookupEdition {
pub store: String,
pub marketplace: String,
pub product_id: String,
pub availability: Availability,
pub formats: Vec<LookupFormat>,
pub metadata: CatalogMetadata,
}
One edition a branch can supply.
Fields
store: The store that sells it, as the store's plain id (audible,libro, ...).marketplace: Lower-cased marketplace of the store listing (us); empty when the store has none.product_id: The store's product id (ASIN, ISBN, ...).availability: Whether the branch holds it or can borrow it.formats: Formats the branch has; empty when unknown.metadata: Bibliographic metadata, as the branch's library has it.
pub fn problem(&self) -> Option<&'static str>
Why the edition is malformed, or None: a store id, product id and
marketplace within their rules, distinct formats, a non-empty
bounded title and bounded metadata.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct LookupIdentifier {
pub scheme: LookupScheme,
pub value: String,
pub marketplace: String,
}
One identifier of the work a question is about.
Fields
scheme: The scheme.value: The normalised value (an ASIN, an ISBN-13, an OpenLibrary id).marketplace: Lower-cased marketplace for an ASIN; empty for every other scheme.
pub fn is_well_formed(&self) -> bool
True when the value is 1 to 64 ASCII letters, digits and -, and
the marketplace is set exactly for an ASIN, as up to 16 lowercase
ASCII letters and digits.
Implements: Clone, Debug, Deserialize<'de>, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize
pub struct LookupWork {
pub work: String,
pub identifiers: Vec<LookupIdentifier>,
}
One question: "can you supply this work?".
Fields
work: The asking library's work id, echoed in the answer; opaque to the branch.identifiers: The work's identifiers; at least one, at mostMAX_LOOKUP_IDENTIFIERS.
pub fn problem(&self) -> Option<&'static str>
Why the question is malformed, or None: a correlation key
(is_work_ref) and 1 to MAX_LOOKUP_IDENTIFIERS distinct
well-formed identifiers.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct BranchOrigin(/* private */);
A branch's public origin: http or https, a host, an optional port and
nothing else (no user, path, query or fragment), at most
MAX_BRANCH_ORIGIN_BYTES bytes, in the form Url serializes it
(lowercase scheme and host, default port dropped).
pub fn parse(raw: &str) -> Option<Self>
Parses the origin a branch reported.
Surrounding whitespace and one trailing / are ignored, as in the
branch's own integrations.public_origin setting.
raw- Thepublic_origintext from a heartbeat frame.
The normalized origin, or None when the text is not a plain
http(s) origin within the size limit.
pub fn as_str(&self) -> &str
The origin as text, such as https://branch.example:8443.
pub fn into_string(self) -> String
The origin as owned text.
Implements: Clone, Debug, Eq, PartialEq
pub struct BranchRequest {
pub job: String,
pub generation: i64,
pub work: LookupWork,
pub store: String,
pub marketplace: String,
pub product_id: String,
}
One request a branch claimed: "send this library that book".
Fields
job: The library's job id; the branch echoes it when it finishes.generation: The job's lease generation; together with the job id and the branch's node id it is the fence the finish is checked against.work: The work, by identifier, as a catalog question names it.store: The store of the listing the branch answered with, as its plain id (audible).marketplace: Lower-cased marketplace of that listing; empty when the store has none.product_id: The store's product id of that listing.
pub fn problem(&self) -> Option<&'static str>
Why the request is malformed, or None: a job id
(is_request_job), a positive generation, a well-formed work, and
a store id, marketplace and product id within the catalog rules.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct SecretEntry {
pub secret_ref: SecretRef,
pub value: SecretValue,
}
One secret in a bundle.
Fields
secret_ref: Which row the value belongs to.value: The unsealed value.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct SecretRef {
pub kind: String,
pub provider: String,
pub account_id: String,
pub name: String,
}
Names one encrypted_secrets row of a store account. It carries no
secret material.
Fields
kind: Secret kind (source_auth,widevine, ...).provider: Plugin key that owns the secret.account_id: Store account id.name: Logical secret name within that account.
Implements: Clone, Debug, Deserialize<'de>, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize
pub struct SecretValue(/* private */);
Secret bytes: zeroized on drop, redacted in Debug, and base64url on
the wire.
pub fn new(bytes: Vec<u8>) -> Self
Wraps secret bytes.
pub fn expose(&self) -> &[u8]
The secret bytes.
pub fn len(&self) -> usize
Length in bytes.
pub fn is_empty(&self) -> bool
True when empty.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct SharedBranchBootstrap {
pub v: u32,
pub library_id: String,
pub node_id: String,
pub database: SharedBranchDatabase,
pub dek: SecretValue,
}
What a shared branch receives at redeem: the [database] bootstrap and the DEK,
for the node id the library recorded (kind = shared). Debug prints no
secret.
Fields
v:SHARED_BRANCH_BOOTSTRAP_VERSION.library_id: The library id.node_id: The node id recorded for this shared branch.database: How to reach the library's database.dek: The library's 32-byte data-encryption key.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct ArtifactRequest<'a> {
pub library_id: &'a str,
pub node_id: &'a str,
pub owner_origin: &'a str,
pub archive_sha256: &'a str,
pub issued_at: i64,
}
What a signed artifact request covers.
Fields
library_id: Library id.node_id: Requesting node id.owner_origin: Owner origin ascanonical_originspells it.archive_sha256: Lowercase hex SHA-256 of the archive asked for.issued_at: Unix seconds when the host signed the request.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct AuthContext<'a> {
pub library_id: &'a str,
pub node_id: &'a str,
pub incarnation: &'a str,
pub nonce: &'a [u8; 32],
pub owner_origin: &'a str,
}
What a handshake signature covers.
Fields
library_id: Library id from the challenge.node_id: Node id from the hello.incarnation: Incarnation from the hello.nonce: Nonce from the challenge.owner_origin: Owner origin ascanonical_originspells it. The host uses the origin it dialed; the owner uses its own configured origin, so a signature relayed through another server does not verify.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct UploadPart {
pub offset: u64,
pub length: u64,
}
A part of a declared file: at least one byte, inside the file.
Fields
offset: Offset of the part's first byte in the file.length: Bytes in the part; at least 1.
pub fn end(&self) -> u64
Offset just past the part's last byte.
pub fn is_last(&self, size: u64) -> bool
Whether the part ends the file of size bytes.
pub fn content_range(&self, size: u64) -> String
The Content-Range value naming this part of a file of size
bytes, as parse_upload_range reads it.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct WindowCopy {
pub source_store: Option<String>,
pub content_type: String,
pub bitrate_kbps: Option<u32>,
pub lossless: bool,
pub version: String,
}
The copy of an edition's primary audio file a library holds, as its probe of the file found it: enough for a reader to decide whether to take the library's copy or fetch its own, without asking again.
A hint, like [WindowEdition::yours]: the library checks what it hands
out when a copy is asked for.
Fields
source_store: The storefront the library's copy was downloaded from (a store id); absent when the library does not know. It can differ from the edition's own store when the same edition is sold by several.content_type: The file's media type, such asaudio/mp4; 1 toMAX_COPY_CONTENT_TYPE_BYTESbytes of atype/subtypetoken.bitrate_kbps: Average bitrate in kbps, 1 tocrate::MAX_PROBE_BITRATE_KBPS; absent when the file was not probed or states no running time.lossless: True when the audio encoding is lossless; false also for a file that was not probed.version: An opaque token that changes whenever the library's file is replaced: 1 toMAX_COPY_VERSION_BYTESASCII letters, digits and-. A reader keeps it to notice a newer copy.
pub fn is_well_formed(&self) -> bool
True when every field is within its documented shape.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct WindowCursor(/* private */);
Where a page of the person's books starts: an opaque key the library
handed out as the previous page's next, or empty for the first page.
A cursor is empty or, like a grouping key (is_work_ref), at most
crate::lookup::MAX_WORK_REF_BYTES bytes of ASCII letters, digits and -. Cursors
order as strings, and each page's next sorts after the cursor it
answers, so paging always moves forward. On the wire it is a JSON
string; anything else is refused.
pub fn start() -> Self
The cursor of the first page.
pub fn parse(text: &str) -> Option<Self>
Reads a cursor: None unless text is empty or a well-formed key.
pub fn is_start(&self) -> bool
True for the first page's cursor.
pub fn as_str(&self) -> &str
The cursor's text.
Implements: Clone, Debug, Default, Deserialize<'de>, Display, Eq, From<WindowCursor>, Hash, Ord, PartialEq, PartialOrd, Serialize, TryFrom<String>
pub struct WindowEdition {
pub edition: LookupEdition,
pub yours: bool,
pub copy: Option<WindowCopy>,
}
One edition of a [WindowWork]: the edition as the library holds it,
and whether it is the person's own.
Fields
edition: The edition, with every format any of the library's copies has.yours: True when the person holds it through a store account of their own on the library; false for a book only other people there hold. A hint for the reader: anything the library hands out on the strength of it is checked again there.copy: The copy of the edition's audio the library holds, when it has acquired one and knows its media type; absent otherwise.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct WindowWork {
pub work: String,
pub identifiers: Vec<LookupIdentifier>,
pub editions: Vec<WindowEdition>,
}
One work the library holds for the window's person.
Fields
work: The library's own work id (or another key unique within the page) that groups these editions; opaque to the window and never compared across libraries.identifiers: The work's identifiers in the library, strong ones first; at mostMAX_LOOKUP_IDENTIFIERS, and empty when the library has none.editions: The library's editions of the work; 1 toMAX_LOOKUP_EDITIONS, eachAvailability::Owned(the library holds it on a store account) or, on a clerk's page,Availability::Reachable(only a branch of the library lists it; never the person's and with no copy).
pub fn problem(&self) -> Option<&'static str>
Why the work is malformed, or None: a grouping key
(is_work_ref), at most MAX_LOOKUP_IDENTIFIERS distinct
well-formed identifiers, and 1 to MAX_LOOKUP_EDITIONS well-formed
editions, with distinct (store, marketplace, product id) and, where
one is stated, a well-formed copy (WindowCopy::is_well_formed).
An edition is Availability::Owned, or Availability::Reachable
with neither a copy nor WindowEdition::yours.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum ClerkFrame {
Books { after: WindowCursor },
CopyGrant { store: String, marketplace: String, product_id: String },
}
A frame from a clerk to a library.
Variants
Books:books: the page of the library's books afterafter(empty for the first page).after: The cursor of the previous page.
CopyGrant:copy.grant: ask for the library's copy of one edition, named by its store listing; the person is the card's.store: Store id of the edition's listing.marketplace: The listing's marketplace; empty for a store without marketplaces.product_id: The listing's product id.
pub fn encode(&self) -> String
The frame's JSON text, as a clerk sends it.
Implements: Clone, Debug, Eq, PartialEq
pub enum ClerkSocketError {
Invalid,
Unavailable,
NotFound,
}
Why the library did not answer a books or copy.grant frame.
Variants
Invalid: The clerk sent a frame the library could not read.Unavailable: The library could not read the books just now; ask again later.NotFound:copy.grantonly: the person may not take that edition, or the library holds no copy of it. One code for both.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum ClerkTopic {
Library,
Discover,
}
Something a clerk hears about on the socket. Each names the routes to read again; the socket itself carries no row data.
Variants
Library: The library's books changed: read them again.Discover: The person's stored Discover shelves may have changed.
pub const ALL: [Self; 2] = _
Every topic.
pub fn as_str(self) -> &'static str
The topic's wire name.
pub fn from_name(name: &str) -> Option<Self>
The topic named name, or None for a name this version does not
know.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize
pub enum LibraryFrame {
Hello { topics: BTreeSet<ClerkTopic> },
Changed { topics: BTreeSet<ClerkTopic> },
BooksPage { after: WindowCursor, works: Vec<WindowWork>, next: Option<WindowCursor> },
CopyGranted(Box<ClerkCopy>),
Error { code: ClerkSocketError },
}
A frame from a library to a clerk.
Variants
Hello:hello: the topics this card hears about, sent once.topics: The topics, without names this version does not know.
Changed:changed: these topics changed.topics: The topics, without names this version does not know.
BooksPage:books.page: one page of the library's books, the card's person's own marked (crate::WindowEdition::yours).after: The cursor the clerk asked with.works: At mostcrate::MAX_WINDOW_WORKSworks.next: The cursor of the next page;Noneon the last page.
CopyGranted:copy.granted: the copy may be downloaded.Error:error: abooksorcopy.grantframe was not answered.code: Why.
pub fn encode(&self) -> String
The frame's JSON text, as a library sends it.
Implements: Clone, Debug, Eq, PartialEq
pub enum CopyAnswer {
Body { offset: u64, length: u64 },
Status(u16),
}
What the head of a download's answer says follows it
(parse_copy_answer).
Variants
Body:lengthbytes of the file follow, from byteoffsetto its end:offset + lengthis the file's size, andoffsetis 0 or the byte the reader asked to resume from.offset: First byte of the file the body holds.length: Number of bytes that follow.
Status: The library answered with this status and no file bytes: a refusal (401, 404), an unsatisfiable range (416) or a fault.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum CopyRange {
Whole,
Part { offset: u64, length: u64 },
Unsatisfiable,
}
What a download's Range header asks for (parse_copy_range).
Variants
Whole: The whole file (answer 200): no usable range was named.Part:lengthbytes fromoffset(answer 206);lengthis at least 1 and the range lies within the file.offset: First byte.length: Number of bytes.
Unsatisfiable: A well-formed range that starts at or past the end of the file (answer 416).
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum CopyRole {
Audio,
Part,
Chapter,
Pdf,
Cover,
Sidecar,
Transcript,
Epub,
}
What a file of a copy is, as the library recorded it when it wrote the file.
Variants
Audio: The edition's primary audio file.Part: One part of a multi-part audio edition.Chapter: One chapter file.Pdf: The companion PDF.Cover: The cover image.Sidecar: A metadata sidecar.Transcript: A transcript.Epub: The ebook.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Ord, PartialEq, PartialOrd, Serialize
pub enum Body {
Hello { node_id: String, incarnation: String, software_version: String, resume: Vec<HeldFence> },
Challenge { nonce: String, library_id: String },
Auth { sig: String },
Welcome { node_id: String, library_id: String, box_key: String },
Resumed { renewed: Vec<HeldFence>, lost: Vec<HeldFence>, unchecked: Vec<HeldFence>, lease_secs: Option<u64> },
Error { code: String, message: String },
Heartbeat { started_at: String, interval_secs: u64, cpu_millicores: i64, memory_bytes: Option<i64>, cpu_used_millicores: Option<i64>, memory_available_bytes: Option<i64>, files_dir_free_bytes: Option<i64>, public_origin: Option<String> },
Claim { item: String, class: Option<String>, filter: Option<ClaimFilter> },
Work { item: String, job: WorkJob, fence: i64, lease_secs: u64, sealed_secrets: Option<String>, plugin_keys: Vec<String>, source_plugin_key: Option<String>, resumed: bool },
NoWork { retry_after_secs: u64 },
Renew { item: String, job_id: String, fence: i64, progress: Option<String> },
Renewed { lease_secs: u64, cancel: bool },
Lost { item: String, job_id: String, fence: i64 },
Complete { job_id: String, fence: i64, detail: Option<String> },
Fail { job_id: String, fence: i64, error_kind: String, message: String },
Release { job_id: String, fence: i64, reason: String, resumed: bool },
DeploymentsList { },
Deployments { items: Vec<RemoteDeployment> },
InstanceConfigGet { instance_id: String },
InstanceConfig { instance_id: String, revision: i64, config: Value, sealed_secrets: Option<String>, secrets_withheld: bool },
Observation { deployment_id: String, status: String, detail: String, applied_config_revision: Option<i64> },
SecretUpdate { job_id: String, fence: i64, secret_ref: SecretRef, sealed_value: String },
ScanResults { job_id: String, fence: i64, plugin_key: String, batch: u64, books: Vec<Value> },
ScanAccepted { batch: u64, upserted: u64 },
ScanRemoved { job_id: String, fence: i64, plugin_key: String, account_id: String, batch: u64, product_ids: Vec<String> },
ScanPassEnd { job_id: String, fence: i64, plugin_key: String, account_id: String, sync_token: String, complete: bool, full: bool },
AcquirePlan { job_id: String, fence: i64 },
AcquireTargets { targets: Vec<AcquireTarget>, destinations: Vec<PlanDestination> },
UploadGrant { job_id: String, fence: i64, holding_id: String, primary_key: String, pdf_key: Option<String>, files: Vec<UploadFile> },
UploadGranted { upload_id: String, sealed_token: String, expires_in_secs: u64 },
ScanRequest { account: Option<String>, plugin_instance_id: Option<String> },
ScanPlanned { created: Vec<String>, duplicates: Vec<String>, queue_full: u64 },
JobStatus { job_ids: Vec<String> },
JobStatuses { jobs: Vec<JobStatusEntry> },
Wake { message: Value },
Ack { },
NodeLeaving { },
CatalogBegin { share_books: bool, include_branches: bool },
CatalogSession { fence: i64, cursor: String, ancestry: Vec<String>, destinations: Vec<String>, wanted: Vec<CatalogRef>, members_books: bool },
CatalogSync { fence: i64, batch: u64, cursor: String, done: bool, titles: Vec<CatalogTitle> },
CatalogAccepted { batch: u64, upserted: u64, skipped: u64, wanted: Vec<CatalogRef> },
CatalogUpload { fence: i64, store: String, product_id: String, files: Vec<UploadFile> },
AccountsAdd { sealed: String },
AccountsAdded { added: u64, already_here: u64, taken: u64, failed: u64, not_allowed: bool },
AccountsRemove { plugin_key: String, account_id: String },
AccountsUpdate { sealed: String, revision: i64 },
AccountsUpdated { outcome: KeeperOutcome },
CatalogQuestions { },
CatalogAsk { works: Vec<LookupWork> },
CatalogFound { answers: Vec<LookupAnswer>, missing: Vec<String> },
RequestsClaim { },
RequestsClaimed { requests: Vec<BranchRequest> },
RequestFinish { job: String, generation: i64, outcome: RequestOutcome },
WindowBooks { after: WindowCursor },
WindowPage { works: Vec<WindowWork>, next: Option<WindowCursor> },
CopyGrant { store: String, marketplace: String, product_id: String },
CopyGranted { copy_id: String, sealed_token: String, expires_in_secs: u64, copy: WindowCopy, files: Vec<CopyFile> },
Accepted { },
Unknown,
}
What a frame says, tagged by type.
Variants
Hello: Host → owner: first frame.node_id: Node id the owner minted at enrollment.incarnation: Host process incarnation (new on each start).software_version: Host's Bookclerk version.resume: Leases the host still holds from an earlier connection.
Challenge: Owner → host: the nonce to sign.nonce: 32 random bytes, base64url without padding.library_id: Library id (also signed).
Auth: Host → owner: proof of key possession.sig: Ed25519 signature overcrate::auth_transcript, base64url without padding.
Welcome: Owner → host: the handshake succeeded.node_id: Authenticated node id.library_id: Library id.box_key: The owner's X25519 box key for this connection, base64url without padding. The host seals token write-backs to it (crate::seal_secret_update), so no secret travels as frame text either way.
Resumed: Owner → host, right afterBody::Welcomewhen the hello listed fences: which leases the owner renewed, which are lost, and which it could not check now. The host aborts lost work; every later frame under a lost fence is refused.renewed: Leases renewed for this connection.lost: Leases that expired, were taken over, or are no longer trusted.unchecked: Leases the owner could not check (a transient read or write failure). They are neither renewed nor lost: the host keeps the work and renews them as usual, and thatrenewdecides.lease_secs: The lease, in seconds, therenewedfences now run for, counted from the host'shello. The owner's lease length may have changed while the host was away, so the host counts this rather than its original grant; absent when nothing was renewed.
Error: Either side: a request was not served. The connection stays open.code: Stable code (unsupported,invalid, ...).message: Human-readable detail.
Heartbeat: Host → owner: the host's own measurements, recorded innode_statuslike any node's heartbeat. Answered withBody::Accepted.started_at: RFC 3339 time the host daemon started.interval_secs: Promised heartbeat interval in seconds.cpu_millicores: Detected CPU capacity in millicores.memory_bytes: Detected memory in bytes.cpu_used_millicores: Measured CPU in use, in millicores.memory_available_bytes: Measured memory available to new work.files_dir_free_bytes: Free bytes on the host's files directory.public_origin: The branch'sintegrations.public_origin, the address other installs reach it at; absent for a branch that has none (a local branch). The library keeps it only whencrate::BranchOrigin::parseaccepts it.
Claim: Host → owner: pull one work item. Answered withBody::WorkorBody::NoWork.item:ITEM_JOB(deliveries are not served yet).class: Job resource class;networkwhen absent.filter: The host's own narrowing: only jobs of these kinds whose every plugin its operator consented to, and whose work (ClaimScope). Absent claims everything the node is trusted with.
Work: Owner → host: a claimed job, its lease, and its sealed secrets.item:ITEM_JOB.job: The job.fence: Lease generation; every later frame for the job names it.lease_secs: Lease length; renew well within it.sealed_secrets: The job's secrets sealed to the node's box key, bound to the node, job and fence (crate::seal_secrets). Absent when the job needs none.plugin_keys: Plugin keys the job runs; the host runs it only when it still consents to every one.source_plugin_key: The one plugin ofplugin_keyswhose source guest runs the job (the others are destinations it writes); the owner hands a host only jobs that name one.resumed: The claim resumed a suspended job: no attempt was spent, and the job's checkpoint applies.
NoWork: Owner → host: nothing to claim now.retry_after_secs: Seconds to wait before claiming again.
Renew: Host → owner: extend a lease. Answered withBody::RenewedorBody::Lost.item:ITEM_JOB.job_id: Job id.fence: Lease generation the host holds.progress: Progress text to record.
Renewed: Owner → host: the lease was extended.lease_secs: Lease length from now.cancel: The operator asked to cancel; stop and reportfail.
Lost: Owner → host: the fence no longer owns the item; abort it and drop its secrets.item:ITEM_JOB.job_id: Job id.fence: The fence that was refused.
Complete: Host → owner: the job finished. Answered withBody::AcceptedorBody::Lost.job_id: Job id.fence: Lease generation the host holds.detail: Outcome text recorded as the job's progress.
Fail: Host → owner: the job failed. Answered withBody::AcceptedorBody::Lost.job_id: Job id.fence: Lease generation the host holds.error_kind: Stable error kind.message: Operator-facing message (never a secret).
Release: Host → owner: give a job back unrun (its operator no longer consents to the job's plugin). The job returns to pending without spending the attempt. Answered withBody::AcceptedorBody::Lost.job_id: Job id.fence: Lease generation the host holds.reason: Stable reason (awaiting_host_consent, ...), for the log.resumed: Theresumedflag of the job'sworkframe, so a resumed claim is given back resumable.
DeploymentsList: Host → owner: the deployments that target this host and should run. Answered withBody::Deployments.Deployments: Owner → host: the answer toBody::DeploymentsList.items: One entry per deployment, in deployment-id order.
InstanceConfigGet: Host → owner:CONFIGandSECRETSof an instance deployed to this host. Answered withBody::InstanceConfig, orerror {code: "not_found"}for an instance not deployed here.instance_id: Plugin instance id.
InstanceConfig: Owner → host: the answer toBody::InstanceConfigGet.instance_id: Plugin instance id.revision: Instance document revision these values apply.config:CONFIG: schema defaults overlaid with the document.sealed_secrets:SECRETSas a JSON object, sealed to the node's box key and bound to the node, instance and revision (crate::seal_instance_secrets). Absent when the instance has none or they were withheld.secrets_withheld: True when the instance has secrets this node is not trusted with (it receives them only when its owner may see every job's secrets).
Observation: Host → owner: the host's observation of one of its deployments (materialized, orerrorwith a detail such asawaiting_host_consent). Answered withBody::Accepted.deployment_id: Deployment id.status:materializedorerror.detail: Bounded detail.applied_config_revision: Instance document revision the host applied.
SecretUpdate: Host → owner: write back a refreshed store token. Accepted only for a secret handed out with the job under this still-live fence.job_id: Job the secret was handed with.fence: Lease generation it was handed under.secret_ref: The secret row.sealed_value: The new value sealed to the connection's owner box key (Body::Welcome), bound to the node, job, fence and ref (crate::seal_secret_update).
ScanResults: Host → owner: one batch of a scan's book rows (decision 6). The owner checks the fence, the node's trust with the job, and every row's account before it writes any row to its library, on every batch. Answered withBody::ScanAccepted,Body::Lost, orerror {code: "refused"}.job_id: Job the rows belong to.fence: Lease generation the host holds.plugin_key: Plugin key whose guest produced the rows (one of the job's).batch: Batch number, from 1, for the logs.books: Book rows as the guest'sScanBook(camelCase JSON objects); at mostMAX_SCAN_BATCH_ROWS.
ScanAccepted: Owner → host: a results batch was written, or aBody::ScanRemovedorBody::ScanPassEndwas applied.batch: The batch number (0for a pass end).upserted: Rows written, or for a removals batch or a pass end the holdings removed.
ScanRemoved: Host → owner: product ids a delta pass reported gone from one account, sent after the job's rows and before that account'sBody::ScanPassEnd. The owner checks the fence, the node's trust and the account as for a row naming it, then removes those holdings. Answered withBody::ScanAccepted,Body::Lost, orerror {code: "refused"}.job_id: Job the pass belongs to.fence: Lease generation the host holds.plugin_key: The job's source plugin key.account_id: The account the titles left.batch: Batch number, from 1, for the logs.product_ids: At mostMAX_SCAN_REMOVED_IDSproduct ids.
ScanPassEnd: Host → owner: how one account's pass ended, after all its rows and removals. The owner stores the sync token for the account's next pass and, after a complete full pass, removes the account's holdings this job's rows did not list. Answered withBody::ScanAccepted,Body::Lost, orerror {code: "refused"}.job_id: Job the pass belongs to.fence: Lease generation the host holds.plugin_key: The job's source plugin key.account_id: The account the pass scanned.sync_token: The plugin's token for the account's next pass, at mostMAX_SCAN_SYNC_TOKEN_BYTES; empty when it keeps none.complete: The pass listed every title the account holds.full: The pass was full: it was sent no sync token, or restarted as a full pass after its token was refused.
AcquirePlan: Host → owner: what an acquire job should fetch here. Answered withBody::AcquireTargets,Body::Lost, orerror.job_id: The acquire job.fence: Lease generation the host holds.
AcquireTargets: Owner → host: the titles to acquire and how to package them.targets: Titles still to acquire, each one of the job's accounts.destinations: Every output destination deployed on the answering shared node, the primary first, each with its own packaging and naming options, so the host names each destination's files as a local acquire would.
UploadGrant: Host → owner: ask to upload one title's files. Answered withBody::UploadGranted,Body::Lost, orerror.job_id: The acquire job.fence: Lease generation the host holds.holding_id: The account holding of the title the files are for (holdings.idon the owner; one of the job's targets).primary_key: Storage key of the title's primary audio file on the primary destination (one offiles' copies there).pdf_key: Storage key of the title's companion PDF on the primary destination (one offiles' copies there), when one is uploaded.files: Every file, in upload order. Empty, with an emptyholding_id, for the job's closing upload, whose commit only completes the job.
UploadGranted: Owner → host: the upload is open.upload_id: Upload id; the files go toUPLOADS_PATH<upload_id>/files/<n>.sealed_token: The bearer token for the upload endpoint, sealed to the node's box key and bound to the node, job, fence and upload (crate::seal_upload_token).expires_in_secs: Seconds the token stays valid unless extended: the owner extends it while the job's fence is live (each renewal and each accepted file).
ScanRequest: Host → owner: queue a library scan on the library for the node's owner (H-5). The owner's scan planner runs as that user: an Owner or Administrator scanning every account gets one job per scan-enabled account, routed across the library's nodes and hosts; anyone else scans only the accounts they own. Answered withBody::ScanPlannedorerror {code: "forbidden" | "invalid" | "unavailable"}.account: Scan only this store account (even when not scan-enabled).plugin_instance_id: Pin every planned job to this plugin instance.
ScanPlanned: Owner → host: what aBody::ScanRequestqueued.created: New jobs.duplicates: Jobs that were already pending or running.queue_full: Planned jobs the queue had no room for.
JobStatus: Host → owner: the state of jobs this node may see (H-5). A job the node's owner could not have queued, or an unknown id, is left out. Answered withBody::JobStatuses.job_ids: Job ids, at mostMAX_STATUS_JOBS.
JobStatuses: Owner → host: the jobs of aBody::JobStatus.jobs: One entry per visible job, in request order.
Wake: Owner → host: a message from the host'snode.<id>queue. The host answersBody::Ackwith the same frame id once it has acted.message: The queue message ({"type": "deployment.changed", ...}).
Ack: Host → owner: the wake with this frame id was handled.NodeLeaving: Host → owner: this host is leaving the library (its operator chose Leave library). The owner revokes the node's credential and stops counting it as live at once, instead of waiting for missed heartbeats, answersBody::Accepted, and closes the connection.CatalogBegin: Branch → library: open (or reopen) this branch's catalog sync with the link's two settings. The library records them on the branch's node row and bumps its catalog fence, so frames under an older fence are lost. Answered withBody::CatalogSessionorerror.share_books: "Share this branch's books with library".include_branches: "Include books from my own branches".
CatalogSession: Library → branch: the answer toBody::CatalogBegin.fence: The catalog fence every latercatalog.*frame names.cursor: Resume after this cursor (empty: from the start).ancestry: The library's ancestry: its own library id, then each library above it, up to the root.destinations: The library node's output destination ids, the primary first; a catalog upload copies each file to every one under its key.wanted: Titles recorded earlier whose files have not arrived yet.members_books: The library's "Acquire all of this branch's members' books": when true, the branch also sends the books its members acquired that it lists to this library, not only its owner's. Absent (older libraries) reads as false.
CatalogSync: Branch → library: one batch of shared titles (no account or user fields; seecrate::CatalogTitle). Answered withBody::CatalogAccepted,Body::Lost(item = "catalog"), orerror {code: "refused"}.fence: The catalog fence.batch: Batch number, from 1, for the logs.cursor: The cursor after this batch's last title; the library resumes after it.done: True for the last batch of a pass. When the library's pass from an empty cursor is under way (a resumed pass included), titles it did not name are withdrawn; otherwise it changes nothing more.titles: The titles; at mostcrate::MAX_CATALOG_BATCH_TITLES.
CatalogAccepted: Library → branch: a catalog batch was recorded.batch: The batch number.upserted: Titles recorded.skipped: Titles not recorded because this library already holds them (no echo back).wanted: Titles whose files the library wants.
CatalogUpload: Branch → library: open an upload of one recorded title's files. Answered withBody::UploadGranted(the token sealed for jobcrate::CATALOG_ITEMunder the catalog fence),Body::Lost, orerror.fence: The catalog fence.store: Store id of the title.product_id: Product id of the title.files: The title's files, in upload order, each copied to every destination of the session under its manifest key.
AccountsAdd: Branch → library: add the branch person's store connections to this library ("Add my connections to library").sealedis ancrate::AccountBundlesealed to the connection's owner box key (Body::Welcome) and bound to the library and node ids (crate::seal_account_offer). The library keeps them for the user its node row names as the branch's owner, under that user's account rule. Answered withBody::AccountsAddedorerror.sealed: The sealed bundle, base64url without padding.
AccountsAdded: Library → branch: what became of anBody::AccountsAdd.added: Accounts now connected here for the person.already_here: Accounts the person had already connected here.taken: Accounts connected to someone else here; left as they are.failed: Accounts that could not be kept.not_allowed: The library's operator does not let the person connect store accounts there; nothing was kept.
AccountsRemove: Branch → library: the person disconnected this store account everywhere. The library unlinks it from the branch owner's identities when it came from this branch's person, and takes it back once no link holds it. Answered withBody::Acceptedorerror.plugin_key: Provenance-qualified plugin key of the storefront.account_id: Store account id.
AccountsUpdate: Branch → library: the newest sign-in of one single-keeper store account this branch keeps ("one refresh keeper" in the library catalog network ADR).sealedis ancrate::AccountBundleof exactly that account, sealed and bound likeBody::AccountsAdd;revisionis the keeper's revision of the sign-in (milliseconds since the Unix epoch of its newest secret write there, above 0). The library replaces its copy only when the account is its branch owner's, shared with this branch, andrevisionis above the last one it applied from it. Answered withBody::AccountsUpdatedorerror.sealed: The sealed one-account bundle, base64url without padding.revision: The keeper's revision of the sign-in.
AccountsUpdated: Library → branch: what became of anBody::AccountsUpdate.outcome: What the library did with the sign-in.
CatalogQuestions: Branch → library: send the catalog questions waiting for this branch (seecrate::LookupWork). Answered withBody::CatalogAsk, orerror {code: "refused"}when the node is not a branch this library trusts.CatalogAsk: Library → branch: the questions waiting for it, at mostcrate::MAX_LOOKUP_WORKS; empty when none is.works: The questions.
CatalogFound: Branch → library: answers to questions it was asked; a question with no answer means the branch cannot supply that work. Answered withBody::Acceptedorerror.answers: The answers, at mostcrate::MAX_LOOKUP_WORKS.missing: Works of the batch the branch looked up and cannot supply, so the library stops asking until the answer expires.
RequestsClaim: Branch → library: claim the interlibrary requests waiting for this branch (seecrate::BranchRequest). Answered withBody::RequestsClaimed, orerror {code: "refused"}when the node is not a branch this library trusts.RequestsClaimed: Library → branch: the requests now leased to it, at mostcrate::MAX_CLAIMED_REQUESTS; empty when none waits.requests: The requests now leased to the asking branch, at mostcrate::MAX_CLAIMED_REQUESTS.
RequestFinish: Branch → library: what it did with one claimed request. Answered withBody::Accepted,Body::Lost(itemcrate::ITEM_REQUEST) when the lease is no longer the branch's, orerror.job: The request's job id.generation: The lease generation it was claimed under.outcome: What the branch did.
WindowBooks: Window → library: send the next page of the books this library holds for the window's person (the node's owner). Answered withBody::WindowPage, orerror {code: "refused"}when the node is not a branch this library trusts.after: Thenextcursor of the previous page; empty (or absent) for the first page.
WindowPage: Library → window: one page of the person's books.works: The works, at mostcrate::MAX_WINDOW_WORKS.next: The cursor to ask with for the next page; absent on the last.
CopyGrant: Reader → library: ask for the copy this library holds of one edition, named by its store listing, for the node's owner (copy_grant_problem). Answered withBody::CopyGranted, orerrorwithrefused(not a branch this library trusts),not_found(the person cannot take the edition, or the library holds no copy of it),invalid, orunavailable(the library cannot read its storage right now).store: Store id of the edition's listing.marketplace: The listing's marketplace; empty (or absent) for a store without marketplaces.product_id: The listing's product id.
CopyGranted: Library → reader: the copy may be downloaded.copy_id: Copy id; the files are atCOPIES_PATH<copy_id>/files/<n>.sealed_token: The bearer token for the download endpoint, sealed to the node's box key and bound to the node and the copy (crate::seal_copy_token).expires_in_secs: Seconds the token stays valid.copy: What the copy is, as the library's page states it.files: The copy's files; a file's index here is its<n>.
Accepted: Owner → host: the request with this frame id was applied.Unknown: A frame type this side does not know.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum ClaimScope {
Own,
AllMembers,
}
Whose work a host takes from a library (claim.filter.scope), as the
branch operator set it for that link.
The library still hands only work the node is trusted with: a scope can narrow that trust, never widen it.
Variants
Own: Only work for the store accounts of the user who owns the node.AllMembers: Work for any member of the library the node is trusted with ("Download for other members of library").
pub fn is_own(&self) -> bool
True for ClaimScope::Own, the default left off the wire.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum FrameError {
TooLarge,
Malformed,
Version(u32),
}
Why a frame was not accepted.
Variants
TooLarge: More thanMAX_FRAME_BYTES.Malformed: Not a JSON frame of the expected shape.Version:vis notFRAME_VERSION.
Implements: Debug, Display, Eq, Error, PartialEq
pub enum KeeperOutcome {
Applied,
Stale,
NotShared,
}
What a library did with a keeper's Body::AccountsUpdate.
Variants
Applied: The library's copy now holds the pushed sign-in.Stale: The library already applied this revision or a newer one from the branch; nothing changed.NotShared: The account is not the branch owner's here, or not shared with this branch; nothing changed. The keeper stops pushing it here.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum KeyError {
Length,
NotOnCurve,
NonCanonical,
WeakPoint,
}
Why a public key was refused.
Variants
Length: Not 32 bytes.NotOnCurve: Not a point on the curve.NonCanonical: A non-canonical encoding of a point.WeakPoint: A small-order or mixed-order point.
Implements: Debug, Display, Eq, Error, PartialEq
pub enum Availability {
Owned,
Reachable,
}
How a branch can supply an edition.
Variants
Owned: The branch's own library holds it (its owner's or a member's book).Reachable: The branch can borrow it from another library it joined, which allows onward lending.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum LookupFormat {
Audio,
Pdf,
}
A file format a branch has for an edition.
Variants
Audio: The audiobook itself.Pdf: The companion PDF.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Ord, PartialEq, PartialOrd, Serialize
pub enum LookupScheme {
Asin,
Isbn,
OpenlibraryEdition,
OpenlibraryWork,
}
Which kind of identifier a LookupIdentifier is. Only identifiers
that name one edition or one work are asked about; anything else does
not parse.
Variants
Asin: Amazon ASIN of an edition in one marketplace (strong).Isbn: ISBN-13 of an edition (weak: one ISBN can sit on several editions).OpenlibraryEdition: OpenLibrary edition id (strong).OpenlibraryWork: OpenLibrary work id (names the work).
pub fn as_str(self) -> &'static str
The scheme as the library model stores it (edition_identifiers.scheme).
pub fn parse(text: &str) -> Option<Self>
Parses stored scheme text; None for any other.
pub fn is_scoped(self) -> bool
True for the one scheme scoped to a marketplace (ASIN).
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize
pub enum RequestOutcome {
Accepted,
NotListed,
Failed,
}
What a branch did with a claimed request.
Variants
Accepted: The branch took it: the book is queued or already on the branch, and reaches the library through the branch's catalog sync.NotListed: The branch no longer lists the book to this library (nobody here holds it, the holder opted out, or sharing is off). Final: the library does not ask again.Failed: The branch could not take it now (a local read or write failed). The library retries it while the job has attempts left.
pub fn as_str(self) -> &'static str
The outcome as the library records it on the job.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum SealError {
Key,
Degenerate,
Open,
Bundle,
}
Why a sealed box could not be made or opened.
Variants
Key: The recipient key is not a valid box key.Degenerate: Key agreement produced the all-zero point.Open: The box is too short, not base64url, or does not authenticate.Bundle: The opened bundle is not a JSON list of secrets.
Implements: Debug, Display, Eq, Error, PartialEq
pub enum ConnectionType {
Branch,
SharedBranch,
}
How a joining install connects to a library.
Variants
Branch: A branch node: its own database, work over the node socket (default).SharedBranch: A shared node: shares the library's database and DEK.
pub fn as_str(self) -> &'static str
Stable text (branch, shared_branch).
pub fn parse(raw: &str) -> Option<Self>
Parses branch or shared_branch (case-insensitive); anything else is
None.
pub fn is_branch(&self) -> bool
True for Self::Branch (serde: the field is left out).
pub fn granted_scope(self) -> &'static str
The scope a code for this connection type is granted.
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum SharedBranchDatabase {
Postgres { url: SecretValue },
D1 { account_id: String, database_id: String, api_base: String },
}
The library's database, as a shared branch needs it to connect.
Variants
Postgres: PostgreSQL: the connection URL (it carries credentials).url:postgres://user:password@host/db.
D1: Cloudflare D1: the database's ids. The API token stays environment-only bootstrap on each node and is never sent.account_id: Cloudflare account id.database_id: D1 database UUID.api_base: Cloudflare API base.
pub fn plugin(&self) -> &'static str
The [database].plugin id (postgres, d1).
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum AuthError {
Key,
Malformed,
Mismatch,
}
Why a handshake signature was refused.
Variants
Key: The stored public key is invalid.Malformed: The signature is not base64url of 64 bytes.Mismatch: The signature does not verify.
Implements: Debug, Display, Eq, Error, PartialEq
pub enum TunnelExposure {
Branches,
Library,
}
What public traffic may reach.
Variants
Branches: Only what branches and clerks need.Library: The whole library, web app included.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum TunnelRefusal {
OperatorOnly,
NotExposed,
}
Why a tunnel request was refused.
Variants
OperatorOnly: The path is for the operator on this machine only.NotExposed: The exposure the operator chose does not include the path.
pub fn as_str(self) -> &'static str
Stable code for the response body and logs.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum UploadRange {
Part(UploadPart),
Status,
}
What a Content-Range on an upload PUT asks for.
Variants
Part: The body is this part of the file.Status: No body: answer with the offset the owner needs next (bytes */<size>).
pub fn status_header(size: u64) -> String
The status query's Content-Range value for a file of size
bytes.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub fn account_bundle_aad(library_id: &str, node_id: &str) -> Vec<u8>
Associated data of the account bundle for node_id of library_id:
the domain tag, then each field as a 4-byte big-endian length and its
bytes.
pub fn account_offer_aad(library_id: &str, node_id: &str) -> Vec<u8>
Associated data of an account offer from node_id to its library
library_id: ACCOUNT_OFFER_AAD_DOMAIN, then the two ids as in
account_bundle_aad.
pub fn check_account_bundle(
bundle: &AccountBundle,
library_id: &str,
node_id: &str,
) -> Result<(), SealError>
Checks bundle against every rule parse_account_bundle applies.
Returns SealError::Bundle for a wrong version or ids, too many
accounts or secrets, an empty or oversized field or value, a repeated
account, or a repeated secret within an account.
pub fn open_account_bundle(
recipient_secret: &[u8; 32],
library_id: &str,
node_id: &str,
sealed: &str,
) -> Result<AccountBundle, SealError>
Opens a bundle made by seal_account_bundle with the joining node's
box secret, for the library and node ids the redeem answered.
Returns SealError::Open when the box was sealed to another key, for
another library or node, or was altered, and SealError::Bundle when
its content is refused by parse_account_bundle.
pub fn open_account_offer(
recipient_secret: &[u8; 32],
library_id: &str,
node_id: &str,
sealed: &str,
) -> Result<AccountBundle, SealError>
Opens an offer made by seal_account_offer with the library's owner
box secret, for the library id and the node id of the authenticated
connection it arrived on.
pub fn parse_account_bundle(
plaintext: &[u8],
library_id: &str,
node_id: &str,
) -> Result<AccountBundle, SealError>
Parses the opened bytes of an account bundle for node_id of
library_id and checks it (check_account_bundle). Sans-IO: the
branch runs it on what open returns, and the fuzz target runs it on
arbitrary bytes.
Returns SealError::Bundle for bytes over
MAX_ACCOUNT_BUNDLE_BYTES, bytes that are not a bundle, and a bundle
the check refuses.
pub fn seal_account_bundle(
recipient: &[u8],
ephemeral_secret: &[u8; 32],
bundle: &AccountBundle,
) -> Result<String, SealError>
Seals bundle to the joining node's box key recipient, as base64url
text for the redeem answer.
Returns SealError::Key for an invalid recipient key and
SealError::Bundle for a bundle check_account_bundle refuses for
its own ids, or whose JSON is over MAX_ACCOUNT_BUNDLE_BYTES.
pub fn seal_account_offer(
recipient: &[u8],
ephemeral_secret: &[u8; 32],
bundle: &AccountBundle,
) -> Result<String, SealError>
Seals a branch's bundle to its library's owner box key recipient
(crate::Body::Welcome), for crate::Body::AccountsAdd. The box is
bound with account_offer_aad, so a joining bundle never opens as an
offer, nor the other way round.
pub fn is_ancestry(ancestry: &[String]) -> bool
True when every id in ancestry is a plain library id and there are at
most MAX_ANCESTRY.
pub fn is_library_id(id: &str) -> bool
True for a plain library id in an ancestry.
pub fn is_marketplace(marketplace: &str) -> bool
True for a marketplace: empty, or up to MAX_MARKETPLACE_BYTES
lowercase ASCII letters and digits.
pub fn is_product_id(product_id: &str) -> bool
True for a product id: 1 to 256 bytes, no whitespace at the ends and no control characters.
pub fn is_store_id(store: &str) -> bool
True for a store id: a short lowercase token.
pub fn clerk_exchange_matches(
stored: &StoredClerkCode<'_>,
request: &ClerkTokenRequest,
) -> bool
True when request redeems stored: the code belongs to
CLERK_CLIENT_ID, the redirect URI is the same, the method is S256
and the trimmed verifier hashes to the challenge (compared in constant
time).
stored- The approved code's record.request- The token request.
Whether the exchange may mint a library card.
pub fn clerk_request_problem(params: &ClerkAuthorizeParams) -> Option<&'static str>
Why a clerk authorization request is malformed, or None when the
library may show its consent page.
params- The parsed request (parse_clerk_query).
A short reason, or None.
pub fn is_clerk_name(name: &str) -> bool
True for a clerk name: 1 to MAX_CLERK_NAME_BYTES bytes, no control
characters.
pub fn is_clerk_token(token: &str) -> bool
True for a session token: exactly CLERK_TOKEN_LEN base64url
characters.
pub fn is_s256_challenge(raw: &str) -> bool
True for an S256 code challenge: exactly 43 base64url characters.
pub fn parse_clerk_authorization(value: &[u8]) -> Option<&str>
The session token in an Authorization header value, when the value is
exactly Bookclerk-Clerk <token>.
The scheme is matched case-insensitively (RFC 9110 section 11.1); one
space separates it from the token; the token must pass
is_clerk_token. Anything else, including an operator Bearer
token, is None.
value- The raw header value bytes.
The token, borrowed from value, or None.
pub fn parse_clerk_query(raw: &str) -> Option<ClerkAuthorizeParams>
Parses an authorize query string (the raw query /oidc/authorize
received), sans-IO so the fuzz target drives the same code.
raw- The query string, without the?.
The parameters, or None when a parameter repeats, a required one is
missing, or the shape is wrong. Unknown parameters are ignored.
pub fn parse_clerk_token_answer(body: &[u8]) -> Option<ClerkTokenAnswer>
Reads the library's POST /api/clerk/v1/token answer on the clerk.
The answer comes from another machine, so it is checked before any of
it is kept: at most MAX_CLERK_ANSWER_BYTES of UTF-8 (all of it,
unknown keys included), one JSON object with no known key written twice, token a session token (is_clerk_token),
library_id a library id (crate::is_library_id), user.id a
positive integer, user.display_name (optional) at most
MAX_CLERK_DISPLAY_NAME_BYTES bytes with no control characters, and
idle_secs from 1 second to a year. Keys it does not know are ignored,
so a newer library can add to the answer.
body- The answer body bytes.
The answer, or None when it breaks any rule.
pub fn parse_clerk_token_request(body: &[u8]) -> Option<ClerkTokenRequest>
Reads a POST /api/clerk/v1/token body.
body- The request body bytes, from another machine.
The request when the body is one JSON object with exactly code,
code_verifier and redirect_uri, each a string written once, or
None.
pub fn is_topic_name(name: &str) -> bool
True when name could be a topic name: 1 to MAX_CLERK_TOPIC_BYTES
bytes of lowercase ASCII letters, digits, _ and ..
pub fn parse_clerk_frame(text: &[u8]) -> Option<ClerkFrame>
Reads a frame a clerk sent: at most MAX_CLERK_FRAME_BYTES, one JSON
object with v (1), a known type, and exactly that type's fields,
each once (a field written as null counts as absent).
books:after, a stringWindowCursor.copy.grant:store,product_idand, for a store with marketplaces,marketplace, passingcopy_grant_problem.
text- The frame's bytes.
The frame, or None when it breaks any rule.
pub fn parse_library_frame(text: &[u8]) -> Option<LibraryFrame>
Reads a frame a library sent: at most crate::MAX_FRAME_BYTES, one
JSON object with v (1), a known type, and exactly that type's fields,
each once.
helloandchanged:topics, at mostMAX_CLERK_TOPICSnames, eachis_topic_name; names this version does not know are dropped.books.page:after(aWindowCursor),works, andnextunless it is the last page, passingcrate::window_page_problem.copy.granted:store,product_id,copy_id,token,expires_in_secs,copy,filesand, for a store with marketplaces,marketplace, passingClerkCopy::problem.error: aClerkSocketErrorcode.
text- The frame's bytes.
The frame, or None when it breaks any rule.
pub fn copy_answer_head_end(received: &[u8]) -> Result<Option<usize>, &'static str>
Finds where the head of a download's answer ends in the bytes received so far, however the library's writes were cut into reads.
The head ends before the first blank line (CRLF CRLF). A reader calls
this on everything it has received after each read: the head is the
first n bytes, parse_copy_answer reads it, and the body starts
four bytes after it. The answer depends only on the bytes, never on
where the reads fell: once it is Some(n) or an error it stays that
for every longer run of the same bytes.
Ok(Some(n)) when the head is the first n bytes, Ok(None) when
the blank line has not arrived yet and still may.
Returns a short reason when the head would be longer than
MAX_COPY_ANSWER_HEAD_BYTES.
pub fn copy_grant_problem(
store: &str,
marketplace: &str,
product_id: &str,
) -> Option<&'static str>
Why a crate::Body::CopyGrant is malformed, or None: a store id, a
marketplace (empty when the store has none) and a product id.
pub fn copy_granted_problem(frame: &CopyGrantedFrame<'_>) -> Option<&'static str>
Why a crate::Body::CopyGranted is malformed, or None: a copy id
(is_copy_id), a non-empty sealed token of base64url text, a life of
1 to MAX_COPY_TOKEN_SECS seconds, a well-formed copy, and 1 to
MAX_COPY_FILES well-formed files with distinct names, exactly one
of them the primary audio (CopyRole::Audio).
pub fn is_copy_id(id: &str) -> bool
True for a copy id: a lowercase hyphenated UUID.
pub fn parse_copy_answer(
head: &[u8],
asked_from: u64,
size: u64,
) -> Result<CopyAnswer, &'static str>
Reads the head of the answer to a download of a file of size bytes
that asked for the bytes from asked_from on (0 for the whole file).
head is the status line and the headers, each line ended by CRLF or
the end of the head, without the blank line that ends it. A reader
writes the body where this says, so the head must state exactly the
bytes that were asked for:
200withContent-Lengthequal tosize: the whole file, also when a range was asked for (a server may ignore one);206withContent-Range: bytes <asked_from>-<size - 1>/<size>and the matchingContent-Length, only whenasked_fromis above 0 and inside the file;- any other status from 100 to 599: no file bytes. A
416that states aContent-Rangemust state the unsatisfied form,bytes */<size>.
A header's name is an HTTP token (letters, digits and
!#$%&'*+-.^_`|~).
Returns a short reason when the head is longer than
MAX_COPY_ANSWER_HEAD_BYTES, is not printable ASCII lines, has no
HTTP/1.x status line, states a transfer encoding, repeats or
misstates Content-Length or Content-Range, or answers 200 or
206 with other bytes than the ones asked for.
pub fn parse_copy_range(header: &str, size: u64) -> CopyRange
Reads the Range header of a download of a file of size bytes.
One byte range is honoured: bytes=A-B (clamped to the file's end),
bytes=A- and the suffix form bytes=-N (the last N bytes). Each
number is 1 to 19 decimal digits. Anything else (another unit, several
ranges, spaces, signs, A past B) is ignored and reads the whole
file, as HTTP allows a server to do.
pub fn is_destination_id(id: &str) -> bool
True when id is a destination id: a short lowercase token.
pub fn is_storage_key(key: &str) -> bool
True when key is a relative storage key: no empty, . or ..
segment, no backslash or control character, not absolute, at most
MAX_UPLOAD_KEY_BYTES, and never a Windows path that leaves the
destination's root (colon_is_safe).
pub fn scan_pass_end_problem(account_id: &str, sync_token: &str) -> Option<&'static str>
Why a Body::ScanPassEnd the owner received is malformed, or None
when it is one a host could send: a non-blank account id and a sync
token of at most MAX_SCAN_SYNC_TOKEN_BYTES with no control
characters.
pub fn scan_removed_problem(
account_id: &str,
product_ids: &[String],
) -> Option<&'static str>
Why a Body::ScanRemoved the owner received is malformed, or None
when it is one a host could send: a non-blank account id, at most
MAX_SCAN_REMOVED_IDS product ids, each non-blank, at most
MAX_SCAN_PRODUCT_ID_BYTES and free of control characters.
pub fn target_destinations_problem(
target: &AcquireTarget,
plan: &[PlanDestination],
) -> Option<&'static str>
Why target's destination list (AcquireTarget::destinations) does
not fit the plan it came with, or None: every id it names is one of
plan's destinations, named once, in the plan's order.
target- One target of anacquire.targetsanswer.plan- That answer's destinations, the primary first.
None when the list fits (or is absent), otherwise a short reason.
pub fn is_branch_name(name: &str) -> bool
True for a branch name: 1 to MAX_BRANCH_NAME_BYTES bytes, no control
characters.
pub fn is_branch_redirect_uri(raw: &str) -> bool
True for a redirect URI BRANCH_CLIENT_ID may use: an absolute
https URL, or an http URL whose host is a loopback IP literal or
localhost (RFC 8252 section 7.3), with no user info and no fragment.
pub fn is_library_name(name: &str) -> bool
True for a library name: 1 to MAX_LIBRARY_NAME_BYTES bytes, no
control characters.
pub fn pkce_challenge(verifier: &str) -> String
The RFC 7636 S256 challenge of verifier: base64url (no padding) of its
SHA-256.
pub fn box_public_key(secret: &[u8; 32]) -> [u8; 32]
The X25519 public key of a 32-byte secret (clamped per RFC 7748).
pub fn sign_public_key(seed: &[u8; 32]) -> [u8; 32]
The Ed25519 public key of a 32-byte signing seed.
pub fn validate_box_public_key(raw: &[u8]) -> Result<(), KeyError>
Validates an X25519 public box key (a Montgomery u-coordinate).
Returns KeyError when the key is the wrong length, on the twist,
not canonical, or not in the prime-order subgroup.
pub fn validate_sign_public_key(raw: &[u8]) -> Result<VerifyingKey, KeyError>
Validates an Ed25519 public signing key.
Returns KeyError when the key is the wrong length, not a canonical
curve point, or not in the prime-order subgroup.
pub fn found_problem(answers: &[LookupAnswer], missing: &[String]) -> Option<&'static str>
Why a crate::Body::CatalogFound is malformed, or None: at most
MAX_LOOKUP_WORKS works named in all, each once, every answer
well-formed and every missing work a correlation key.
pub fn is_work_ref(work: &str) -> bool
True for a correlation key: 1 to MAX_WORK_REF_BYTES ASCII letters,
digits and -.
pub fn questions_problem(works: &[LookupWork]) -> Option<&'static str>
Why a list of questions is malformed, or None: at most
MAX_LOOKUP_WORKS well-formed questions, each about a different work.
pub fn claimed_problem(requests: &[BranchRequest]) -> Option<&'static str>
Why a list of claimed requests is malformed, or None: at most
MAX_CLAIMED_REQUESTS well-formed requests, each for a different job.
pub fn finish_problem(job: &str, generation: i64) -> Option<&'static str>
The problem with a requests.finish {job, generation} a library
received, or None when both are ones it could have handed out.
pub fn is_request_job(job: &str) -> bool
True for a request's job id: 1 to MAX_REQUEST_JOB_BYTES ASCII
letters, digits, - and _.
pub fn copy_token_aad(node_id: &str, copy_id: &str) -> Vec<u8>
Associated data of the token for copy copy_id, granted to node_id.
pub fn instance_secrets_aad(node_id: &str, instance_id: &str, revision: i64) -> Vec<u8>
Associated data of instance_id's SECRETS handed to node_id at
document revision.
pub fn open(
recipient_secret: &[u8; 32],
aad: &[u8],
sealed: &[u8],
) -> Result<Zeroizing<Vec<u8>>, SealError>
Opens a box sealed to the public key of recipient_secret.
Returns SealError::Open when the box is short, was sealed to another
key or other associated data, or was altered.
pub fn open_copy_token(
recipient_secret: &[u8; 32],
node_id: &str,
copy_id: &str,
sealed: &str,
) -> Result<SecretValue, SealError>
Opens a token made by seal_copy_token with the node's box secret.
Returns SealError::Open when it was not sealed to this node for
this copy.
pub fn open_instance_secrets(
recipient_secret: &[u8; 32],
node_id: &str,
instance_id: &str,
revision: i64,
sealed: &str,
) -> Result<SecretValue, SealError>
Opens a payload made by seal_instance_secrets with the node's box
secret.
Returns SealError::Open when it was not sealed to this node for this
instance and revision.
pub fn open_secret_update(
owner_box_secret: &[u8; 32],
node_id: &str,
job_id: &str,
fence: i64,
secret_ref: &SecretRef,
sealed: &str,
) -> Result<SecretValue, SealError>
Opens a write-back made by seal_secret_update with the owner's
per-connection box secret.
Returns SealError::Open when it was not sealed to this key for this
node, job, fence and ref.
pub fn open_secrets(
recipient_secret: &[u8; 32],
node_id: &str,
job_id: &str,
fence: i64,
sealed: &str,
) -> Result<Vec<SecretEntry>, SealError>
Opens a bundle made by seal_secrets with the node's box secret.
Returns SealError::Open when the box does not open for this node,
job and fence, and SealError::Bundle when its content is malformed.
pub fn open_upload_token(
recipient_secret: &[u8; 32],
node_id: &str,
job_id: &str,
fence: i64,
upload_id: &str,
sealed: &str,
) -> Result<SecretValue, SealError>
Opens a token made by seal_upload_token with the node's box secret.
Returns SealError::Open when it was not sealed to this node for this
job, fence and upload.
pub fn seal(
recipient: &[u8],
ephemeral_secret: &[u8; 32],
aad: &[u8],
plaintext: &[u8],
) -> Result<Vec<u8>, SealError>
Seals plaintext to recipient (an X25519 public key) with the
ephemeral secret ephemeral_secret, binding aad.
ephemeral_secret must be fresh random bytes for every box; reusing it
for two plaintexts to one recipient reuses the key and nonce.
Returns SealError::Key for an invalid recipient key and
SealError::Degenerate when key agreement fails.
pub fn seal_copy_token(
recipient: &[u8],
ephemeral_secret: &[u8; 32],
node_id: &str,
copy_id: &str,
token: &[u8],
) -> Result<String, SealError>
Seals a copy token for node_id's box key recipient, bound to the
node and the copy, as base64url text for a copy.granted frame. The
token is a bearer credential for the download endpoint, so it never
travels as frame text.
Returns SealError when the recipient key is invalid.
pub fn seal_instance_secrets(
recipient: &[u8],
ephemeral_secret: &[u8; 32],
node_id: &str,
instance_id: &str,
revision: i64,
secrets_json: &[u8],
) -> Result<String, SealError>
Seals an instance's SECRETS payload (JSON bytes) for node_id's box
key recipient, bound to the instance and document revision, as
base64url text for an instance_config frame.
Returns SealError when the recipient key is invalid.
pub fn seal_secret_update(
owner_box_key: &[u8],
ephemeral_secret: &[u8; 32],
node_id: &str,
job_id: &str,
fence: i64,
secret_ref: &SecretRef,
value: &[u8],
) -> Result<String, SealError>
Seals a refreshed token to the owner's per-connection box key
owner_box_key (from welcome), bound to the node, job, fence and
ref, as base64url text for a secret.update frame.
Returns SealError when the owner key is invalid.
pub fn seal_secrets(
recipient: &[u8],
ephemeral_secret: &[u8; 32],
node_id: &str,
job_id: &str,
fence: i64,
entries: &[SecretEntry],
) -> Result<String, SealError>
Seals entries for node_id's box key recipient, bound to job_id
and fence, as base64url text for a work frame.
Returns SealError when the recipient key is invalid.
pub fn seal_upload_token(
recipient: &[u8],
ephemeral_secret: &[u8; 32],
node_id: &str,
job_id: &str,
fence: i64,
upload_id: &str,
token: &[u8],
) -> Result<String, SealError>
Seals an upload token for node_id's box key recipient, bound to the
job, fence and upload, as base64url text for an upload.granted frame.
The token is a bearer credential for the upload endpoint, so it never
travels as frame text.
Returns SealError when the recipient key is invalid.
pub fn secret_update_aad(
node_id: &str,
job_id: &str,
fence: i64,
secret_ref: &SecretRef,
) -> Vec<u8>
Associated data of a token write-back from node_id for secret_ref,
handed with job_id under fence.
pub fn secrets_aad(node_id: &str, job_id: &str, fence: i64) -> Vec<u8>
Associated data of the secret bundle handed to node_id for job_id
under lease generation fence: the domain tag, then each field as a
4-byte big-endian length and its bytes.
pub fn upload_token_aad(
node_id: &str,
job_id: &str,
fence: i64,
upload_id: &str,
) -> Vec<u8>
Associated data of the token for upload upload_id, granted to
node_id for job_id under lease generation fence.
pub fn open_shared_branch_bootstrap(
recipient_secret: &[u8; 32],
library_id: &str,
node_id: &str,
sealed: &str,
) -> Result<SharedBranchBootstrap, SealError>
Opens a bootstrap made by seal_shared_branch_bootstrap with the joining
node's box secret, for the library and node ids the redeem answered.
Returns SealError::Open when the box was sealed to another key, for
another library or node, or was altered, and SealError::Bundle when
its content is malformed or names other ids.
pub fn seal_shared_branch_bootstrap(
recipient: &[u8],
ephemeral_secret: &[u8; 32],
bootstrap: &SharedBranchBootstrap,
) -> Result<String, SealError>
Seals bootstrap to the joining node's box key recipient, as
base64url text for the redeem answer.
Returns SealError::Key for an invalid recipient key and
SealError::Bundle for a bootstrap that is not version 1 or whose DEK
is not 32 bytes.
pub fn shared_branch_bootstrap_aad(library_id: &str, node_id: &str) -> Vec<u8>
Associated data of a shared branch bootstrap for node_id of library_id: the
domain tag, then each field as a 4-byte big-endian length and its bytes.
pub fn artifact_transcript(request: &ArtifactRequest<'_>) -> Vec<u8>
The bytes a host signs for an artifact request: the domain tag, then each field as a 4-byte big-endian length and its bytes.
pub fn auth_transcript(ctx: &AuthContext<'_>) -> Vec<u8>
The bytes a host signs: the domain tag, then each field as a 4-byte big-endian length and its bytes.
pub fn canonical_origin(raw: &str) -> Option<String>
The ASCII origin (scheme://host[:port]) of an http(s) URL, with the
default port and any path dropped and the host lowercased.
pub fn decode_nonce(raw: &str) -> Option<[u8; 32]>
Decodes a challenge nonce.
pub fn encode_nonce(nonce: &[u8; 32]) -> String
Encodes a nonce as base64url without padding.
pub fn parse_artifact_authorization(header: &str) -> Option<(&str, i64, &str)>
Splits an artifact Authorization header into node id, issue time and
signature.
pub fn sign_artifact_request(key: &SigningKey, request: &ArtifactRequest<'_>) -> String
The Authorization header value of a signed artifact request.
pub fn sign_auth(key: &SigningKey, ctx: &AuthContext<'_>) -> String
Signs a handshake; the result is base64url without padding.
pub fn verify_artifact_request(
public_key: &[u8],
request: &ArtifactRequest<'_>,
sig: &str,
now: i64,
) -> Result<(), AuthError>
Verifies a signed artifact request with the node's enrolled key and
checks its time against now (unix seconds).
Returns AuthError when the key is invalid, the signature is
malformed or does not verify, or the time is out of range
(AuthError::Mismatch).
pub fn verify_auth(
public_key: &[u8],
ctx: &AuthContext<'_>,
sig: &str,
) -> Result<(), AuthError>
Verifies a handshake signature with the node's enrolled public key. Uses strict verification (no malleable or small-order signatures).
Returns AuthError when the key is invalid, the signature is
malformed, or it does not verify.
pub fn normalize_tunnel_path(raw: &str) -> String
The path the router matches for raw: the router trims trailing slashes
and keeps exactly one leading slash, so //api/node/ routes as
/api/node.
raw- The request target's path, without the query.
raw without leading or trailing slashes, behind one leading slash.
pub fn tunnel_refusal(path: &str, exposure: TunnelExposure) -> Option<TunnelRefusal>
Whether a tunnel request for path is refused.
path- The path fromnormalize_tunnel_path.exposure- What the operator chose to expose.
None to serve the request, or why it is refused.
pub fn parse_upload_range(header: &[u8], size: u64) -> Option<UploadRange>
Reads a Content-Range header value on an upload PUT of a declared
file of size bytes.
header- the header value as sent.size- the file's declared size from the upload's manifest.
UploadRange::Part for exactly bytes <first>-<last>/<size>, with
canonical decimal numbers, first <= last < size and the declared size;
UploadRange::Status for exactly bytes */<size> with the declared
size; None for anything else, including a part of an empty file
(which is always sent whole).
pub fn upload_parts(size: u64, part_bytes: u64) -> Vec<UploadPart>
The parts a host sends a file of size bytes in, each at most
part_bytes (at least 1) long, in order; empty when the file fits in
one request (size <= part_bytes), which is then sent whole.
pub fn window_page_problem(
after: &WindowCursor,
works: &[WindowWork],
next: Option<&WindowCursor>,
) -> Option<&'static str>
Why a crate::Body::WindowPage is malformed, or None: at most
MAX_WINDOW_WORKS well-formed works with distinct grouping keys, and a
next cursor, when there is one, past after (the cursor the window
asked with), so paging always moves forward.
pub const ACCOUNT_BUNDLE_AAD_DOMAIN: &[u8] = b"bookclerk-node.v1 account-bundle";
Domain tag that starts the associated data of an account bundle.
pub const ACCOUNT_BUNDLE_VERSION: u32 = 1;
Version of an AccountBundle.
pub const ACCOUNT_OFFER_AAD_DOMAIN: &[u8] = b"bookclerk-node.v1 account-offer";
Domain tag that starts the associated data of an account offer: a
branch's AccountBundle sent up to its library
(crate::Body::AccountsAdd). A distinct tag keeps a bundle sealed in
one direction from opening as the other.
pub const MAX_ACCOUNT_BUNDLE_BYTES: usize = _;
Largest opened bundle accepted, in bytes. A bundle at every limit above would be far larger; this keeps the redeem answer small.
pub const MAX_ACCOUNT_SECRETS: usize = 16;
Most secrets one carried account holds.
pub const MAX_BUNDLE_ACCOUNTS: usize = 64;
Most accounts one bundle carries.
pub const MAX_CARRIED_ACCOUNT_ID_BYTES: usize = 256;
Longest store account id carried, in bytes.
pub const MAX_CARRIED_FIELD_BYTES: usize = 128;
Longest source alias, marketplace, secret kind or label carried, in bytes.
pub const MAX_CARRIED_PLUGIN_KEY_BYTES: usize = 256;
Longest plugin key carried, in bytes.
pub const MAX_CARRIED_SECRET_BYTES: usize = _;
Largest secret value carried, in bytes.
pub const CATALOG_ITEM: &str = "catalog";
Item kind of the catalog fence (lost.item), and the job id a catalog
upload's token is sealed for.
pub const MAX_ANCESTRY: usize = 64;
Most library ids an ancestry may list.
pub const MAX_CATALOG_BATCH_TITLES: usize = 100;
Most titles one crate::Body::CatalogSync batch may carry.
pub const MAX_CATALOG_CURSOR_BYTES: usize = 512;
Longest cursor.
pub const MAX_CATALOG_TITLE_BYTES: usize = _;
Largest serialized title in a batch.
pub const MAX_CATALOG_WANTED: usize = 200;
Most titles one answer may say are wanted.
pub const MAX_MARKETPLACE_BYTES: usize = 16;
Longest marketplace.
pub const CLERK_AUTH_SCHEME: &str = "Bookclerk-Clerk";
The Authorization scheme a clerk sends its session token under.
pub const CLERK_CALLBACK_PATH: &str = "/clerk/callback";
The clerk's own web app page a clerk sign-in's redirect comes back to
(<clerk origin>/clerk/callback?code=…&state=…).
pub const CLERK_CLIENT_ID: &str = "bookclerk-clerk";
The built-in public OAuth client a clerk signs in through. It is never stored in the library's clients table.
pub const CLERK_CODE_TTL_SECS: i64 = 60;
Seconds an authorization code for CLERK_CLIENT_ID lives.
pub const CLERK_IDLE_DAYS: i64 = 90;
Days a clerk session stays signed in without being used. Each use moves the expiry forward again.
pub const CLERK_SCOPE: &str = "library:member";
The only scope CLERK_CLIENT_ID may ask for.
pub const CLERK_TOKEN_LEN: usize = 43;
Length of a session token: base64url (no padding) of 32 random bytes.
pub const CLERK_TOKEN_PATH: &str = "/api/clerk/v1/token";
POST: redeem an approved clerk sign-in for a session token.
pub const MAX_CLERK_ANSWER_BYTES: usize = _;
Largest POST /api/clerk/v1/token answer a clerk reads.
pub const MAX_CLERK_DISPLAY_NAME_BYTES: usize = 128;
Longest display name a clerk keeps from a token answer.
pub const MAX_CLERK_NAME_BYTES: usize = 64;
Longest clerk name sent.
pub const MAX_CLERK_STATE_BYTES: usize = 512;
Longest state an authorize request may carry.
pub const CLERK_CONNECT_PATH: &str = "/api/clerk/v1/connect";
Path of the clerk socket.
pub const CLERK_SOCKET_VERSION: u8 = 1;
The v every frame carries.
pub const CLERK_SUBPROTOCOL: &str = "bookclerk-clerk.v1";
The WebSocket subprotocol a clerk must offer.
pub const MAX_CLERK_FRAME_BYTES: usize = _;
Largest frame a library accepts from a clerk, in bytes; a books frame
is under 120.
pub const MAX_CLERK_TOPICS: usize = 16;
Most topic names one hello or changed frame may carry, known or not.
pub const MAX_CLERK_TOPIC_BYTES: usize = 32;
Longest topic name, in bytes.
pub const COPIES_PATH: &str = "/api/copies/v1/";
Path prefix of the download endpoint: the files of copy <copy_id>
are at COPIES_PATH<copy_id>/files/<n>.
pub const COPY_AUTH_SCHEME: &str = "Bookclerk-Copy";
Authorization scheme of the download endpoint.
pub const MAX_COPY_ANSWER_HEAD_BYTES: usize = _;
Longest head of a download's answer a reader takes, in bytes: the status line and headers, before the blank line.
pub const MAX_COPY_FILES: usize = 1000;
Most files one crate::Body::CopyGranted may list.
pub const MAX_COPY_FILE_BYTES: u64 = _;
Largest CopyFile::size (1 TiB): above any audiobook file.
pub const MAX_COPY_NAME_BYTES: usize = 512;
Longest CopyFile::name, in bytes.
pub const MAX_COPY_TOKEN_SECS: u64 = _;
Longest a copy token may be stated to live, in seconds (one day).
pub const ITEM_JOB: &str = "job";
Work item kind for jobs.
pub const MAX_CALL_NUMBER_BYTES: usize = 16;
Longest call number (see CallNumber).
pub const MAX_DESTINATION_ID_BYTES: usize = 64;
Longest destination id.
pub const MAX_PROBE_BITRATE_KBPS: u32 = 20_000;
Highest bitrate an UploadProbe may state, in kilobits per second:
above any audiobook encoding, so a forged value cannot win by size alone.
pub const MAX_SCAN_BATCH_ROWS: usize = 200;
Most rows one Body::ScanResults batch may carry.
pub const MAX_SCAN_PRODUCT_ID_BYTES: usize = 512;
Longest product id a Body::ScanRemoved batch may carry.
pub const MAX_SCAN_REMOVED_IDS: usize = 500;
Most product ids one Body::ScanRemoved batch may carry (a scan
page's own cap).
pub const MAX_SCAN_ROW_BYTES: usize = _;
Largest serialized row in a Body::ScanResults batch.
pub const MAX_SCAN_SYNC_TOKEN_BYTES: usize = 4096;
Longest sync token a Body::ScanPassEnd or ScanToken may carry
(a scan page's own cap).
pub const MAX_SCAN_TOKENS: usize = 256;
Most ScanTokens one WorkJob may carry.
pub const MAX_STATUS_JOBS: usize = 64;
Most job ids one Body::JobStatus may ask about.
pub const MAX_UPLOAD_COPIES: usize = 16;
Most destinations one uploaded file may be written to.
pub const MAX_UPLOAD_FILES: usize = 512;
Most files one upload may declare.
pub const MAX_UPLOAD_FILE_BYTES: u64 = _;
Largest file one upload may declare (8 GiB).
pub const MAX_UPLOAD_KEY_BYTES: usize = 1024;
Longest storage key an upload may declare.
pub const AUTHORIZE_PATH: &str = "/oidc/authorize";
The owner's authorization endpoint (path).
pub const BRANCH_CLIENT_ID: &str = "bookclerk-branch";
The built-in public OAuth client a joining branch signs in through. It is never stored in the owner's clients table.
pub const BRANCH_CODE_TTL_SECS: i64 = 60;
Seconds an authorization code for BRANCH_CLIENT_ID lives.
pub const BRANCH_SCOPE: &str = "node:enroll";
The only scope BRANCH_CLIENT_ID may ask for.
pub const ENROLL_OAUTH_PATH: &str = "/api/node/v1/enroll/oauth";
POST: redeem an approved branch sign-in.
pub const INFO_PATH: &str = "/api/node/v1/info";
GET: what a library tells a joining install before sign-in.
pub const JOIN_CALLBACK_PATH: &str = "/join/callback";
Path of the joining install's own callback (the SPA route the browser returns to, and the CLI's loopback listener).
pub const MAX_BRANCH_NAME_BYTES: usize = 64;
Longest branch name sent.
pub const MAX_LIBRARY_NAME_BYTES: usize = 253;
Longest library name accepted: a library is named by its public host, and a DNS name runs to 253 bytes.
pub const PUBLIC_KEY_LEN: usize = 32;
Length of either public key.
pub const MAX_LOOKUP_EDITIONS: usize = 8;
Most editions one LookupAnswer may list.
pub const MAX_LOOKUP_IDENTIFIERS: usize = 16;
Most identifiers one LookupWork may carry.
pub const MAX_LOOKUP_WORKS: usize = 100;
Most works one crate::Body::CatalogAsk or
crate::Body::CatalogFound may name.
pub const MAX_WORK_REF_BYTES: usize = 64;
Longest correlation key (LookupWork::work).
pub const MAX_BRANCH_ORIGIN_BYTES: usize = 255;
Longest origin a branch may report, in bytes.
pub const ITEM_REQUEST: &str = "request";
The work item name of a request in a crate::Body::Lost answer.
pub const MAX_CLAIMED_REQUESTS: usize = 16;
Most requests one crate::Body::RequestsClaimed may carry.
pub const MAX_REQUEST_JOB_BYTES: usize = 96;
Longest job id a request may carry.
pub const COPY_TOKEN_AAD_DOMAIN: &[u8] = b"bookclerk-node.v1 copy-token";
Domain of the associated data of a sealed copy token.
pub const INSTANCE_SECRETS_AAD_DOMAIN: &[u8] = b"bookclerk-node.v1 instance-secrets";
Domain tag that starts the associated data of an instance's SECRETS.
pub const SEALED_BOX_INFO: &[u8] = b"bookclerk-node.v1 sealed-box";
HKDF info string of a sealed box.
pub const SEALED_BOX_OVERHEAD: usize = _;
Bytes a sealed box adds to its plaintext (ephemeral key and tag).
pub const SECRETS_AAD_DOMAIN: &[u8] = b"bookclerk-node.v1 job-secrets";
Domain tag that starts the associated data of a secret bundle.
pub const SECRET_UPDATE_AAD_DOMAIN: &[u8] = b"bookclerk-node.v1 secret-update";
Domain tag that starts the associated data of a token write-back.
pub const UPLOAD_TOKEN_AAD_DOMAIN: &[u8] = b"bookclerk-node.v1 upload-token";
Domain tag that starts the associated data of an upload token.
pub const DEK_LEN: usize = 32;
Length of the data-encryption key.
pub const SHARED_BRANCH_BOOTSTRAP_AAD_DOMAIN: &[u8] = b"bookclerk-node.v1 shared-branch-bootstrap";
Domain tag that starts the associated data of a shared branch bootstrap.
pub const SHARED_BRANCH_BOOTSTRAP_VERSION: u32 = 1;
Version of SharedBranchBootstrap.
pub const SHARED_BRANCH_GRANTED_SCOPE: &str = "node:enroll node:shared_branch";
The scope a shared branch code is granted (stored with the code at consent).
pub const SHARED_BRANCH_OFFER_PARAM: &str = "shared_branch_offer";
Authorize-request parameter by which a joining install offers to join as
a shared branch (shared_branch_offer=1): it is empty, so its own data may be replaced.
Without it the consent page offers a branch only.
pub const ARTIFACT_AUTH_SCHEME: &str = "Bookclerk-Node";
Authorization scheme of a signed artifact request:
Bookclerk-Node <node_id> <issued_at> <sig>.
pub const ARTIFACT_DOMAIN: &[u8] = b"bookclerk-node-artifact-v1";
Domain tag that starts every signed artifact request.
pub const ARTIFACT_REQUEST_MAX_SKEW_SECS: i64 = 300;
How far a signed artifact request's time may be from the owner's clock.
pub const AUTH_DOMAIN: &[u8] = b"bookclerk-node-auth-v1";
Domain tag that starts every signed transcript.
pub const NONCE_LEN: usize = 32;
Length of a challenge nonce.
pub const BRANCH_API_PATHS: [&str; 13] = _;
API paths TunnelExposure::Branches serves. Each also covers the paths
below it.
pub const LEGACY_CONTROL_PATHS: [&str; 5] = _;
Legacy control routes outside /api/ that
TunnelExposure::Branches refuses. Each also covers the paths below
it.
pub const OPERATOR_ONLY_PATHS: [&str; 6] = _;
Paths no tunnel request reaches: the operator-token sign-in, the loopback tray handoff, operator elevation and the operator's first-Owner bootstrap. Each also covers the paths below it.
pub const UPLOAD_PART_BYTES: u64 = _;
Largest part a host sends (64 MiB): under the request-body caps of the relays an install can sit behind (100 MB on Cloudflare's Free plan).
pub const MAX_COPY_CONTENT_TYPE_BYTES: usize = 64;
Longest WindowCopy::content_type, in bytes.
pub const MAX_COPY_VERSION_BYTES: usize = 64;
Longest WindowCopy::version, in bytes.
pub const MAX_WINDOW_WORKS: usize = 100;
Most works one crate::Body::WindowPage may carry.
pub const ARTIFACTS_PATH: &str = "/api/node/v1/artifacts/";
Path prefix of the owner's artifact endpoint: GET /api/node/v1/artifacts/<archive_sha256> with a signed Authorization
(sign_artifact_request) streams one stored archive to a host that
runs it.
pub const UPLOADS_PATH: &str = "/api/node/v1/uploads/";
Path prefix of the owner's upload endpoint (H-4 design, section 6):
PUT|HEAD <prefix><upload_id>/files/<n> streams one declared file and
POST <prefix><upload_id>/commit commits the title, each with
Authorization: Bookclerk-Upload <token> (UPLOAD_AUTH_SCHEME).
pub const UPLOAD_AUTH_SCHEME: &str = "Bookclerk-Upload";
Authorization scheme of the upload endpoint.
pub const SUBPROTOCOL: &str = "bookclerk-node.v1";
WebSocket subprotocol a host must offer.
pub const FRAME_VERSION: u32 = 1;
Frame envelope version (v).
pub const MAX_FRAME_BYTES: usize = _;
Largest frame either side accepts (1 MiB).
pub const PING_INTERVAL_SECS: u64 = 20;
Seconds between pings from each side.
pub const IDLE_TIMEOUT_SECS: u64 = 60;
Seconds without any inbound frame before a side closes the connection.
pub const SEND_QUEUE_FRAMES: usize = 64;
Frames a side queues for sending before it stops forwarding wakes and waits for the peer to read.
pub const HANDSHAKE_TIMEOUT_SECS: u64 = 10;
Seconds the owner waits for each handshake frame.
pub const CLOSE_AUTH_FAILED: u16 = 4401;
Close code: the handshake failed (unknown node, bad signature, or a malformed or late handshake frame).
pub const CLOSE_REVOKED: u16 = 4403;
Close code: the node's credential is revoked.
pub const CLOSE_SUPERSEDED: u16 = 4409;
Close code: a newer authenticated connection for the same node replaced this one.
pub const CLOSE_PROTOCOL: u16 = 4400;
Close code: a frame broke the protocol after the handshake (binary, oversized, malformed, or the wrong version).
Generated from crates/bookclerk-node-proto at main · View as Markdown