bookclerk_node_client

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

The host side of the node API (H-4 design, sections 2 to 4; step 7).

A branch node is a separate Bookclerk install that enrolled into an owner library with a single-use link (join_library) or a sign-in at the owner (inspect_library, authorize_branch, redeem_branch_code); it tells the owner when it leaves (announce_leaving). An empty install may instead join as a shared branch, an shared node that shares the library's database and DEK (redeem_shared_branch_code, apply_shared_branch_bootstrap). Its node keys are sealed in its own database (bookclerk_library::control_plane::record_library_link). For every active link, HostClient keeps one socket to the owner's /api/node/v1/connect:

  • TLS everywhere except loopback, verified against the link's SPKI pin or the webpki roots (OwnerEndpoint);

  • the Ed25519 challenge signed with the enrolled key;

  • heartbeats into the owner's node_status;

  • claimed jobs run through a HostJobRunner, their secrets opened with the enrolled X25519 key, renewed and reported under the fence;

  • refreshed store tokens written back sealed to the connection's owner box key (HostJobCtx::write_back);

  • wakes acked after local subscribers have them;

  • reconnect with backoff, resuming the fences still held.

  • claims narrowed to the job kinds this host runs and the plugins its operator consented to (HostClientHandle::set_consented_plugins); a job whose consent is revoked is cancelled and given back unspent;

  • after a wake, the host requests its deployment list and instance configuration from the owner and sends its observations back (HostClientHandle::request for deployments.list, instance.config and observation), and fetches a stored archive with HostClientHandle::fetch_artifact, signed with the node key.

  • a scan's rows returned in fenced batches (HostJobCtx::send_scan_results); an acquire's titles asked for (HostJobCtx::acquire_plan) and its files streamed to the owner under a sealed upload token (HostJobCtx::grant_upload, HostJobCtx::upload_file, HostJobCtx::commit_upload); the job completes with its closing upload's commit.

A branch may also take the copy the library already holds of an edition: HostClientHandle::copy_grant asks for it and HostClientHandle::fetch_copy_file downloads each file, resuming a download that was cut short (fetch_copy_file is the same download for a clerk, which holds a plain token).

An install may instead sign in to a library as a clerk, holding a library card for its person rather than node keys (authorize_clerk, exchange_clerk_code); the daemon reads the person's books over the library's clerk socket (OwnerEndpoint::connect_clerk_socket).

The consent decisions themselves (which plugins, which grant) and how a job runs its guest are the daemon's.

Item Kind Summary
HeartbeatSource trait Measurements for heartbeat frames.
OwnerIo trait A byte stream to the owner, plain (loopback) or TLS.
UploadSource trait Where an uploaded file's bytes come from: readable from any offset, so an interrupted file resends only what the owner lacks.
HostJobRunner trait Runs claimed jobs on this host.
BranchAuthorization struct One sign-in about to start. Debug prints no secret.
BranchRedeem struct What redeem_branch_code needs besides the keys.
InspectedLibrary struct A library as inspect_library found it.
RedeemedBranch struct A branch sign-in the library redeemed and this install recorded.
ClerkAuthorization struct One clerk sign-in about to start. Debug prints no secret.
ClerkRedeem struct What exchange_clerk_code needs: the inspected library and the pending sign-in.
ExchangedCard struct A library card the library handed over for a clerk sign-in, not yet recorded here. Debug prints no secret.
CatalogBatchAccepted struct A recorded catalog batch (HostClientHandle::catalog_sync).
CatalogSession struct An opened catalog session (HostClientHandle::catalog_begin).
ClientTiming struct Timers of the client. The defaults follow the protocol constants.
HostClient struct The host side of the node API for one library link.
HostClientConfig struct What one client connects with.
HostClientHandle struct Watches a running client.
OfferedAccounts struct What the library kept of an HostClientHandle::offer_accounts.
LocalFileSource struct A file on this install's disk as an UploadSource.
OwnerEndpoint struct Where and how to reach one owner.
TlsProbe struct What a first TLS handshake showed of an owner's certificate, before any pin is known (OwnerEndpoint::probe_json).
GrantedCopy struct A copy of an edition the library granted this node (crate::HostClientHandle::copy_grant): what it is, its files, and the bearer token of its downloads. The token is zeroized on drop and never shown by Debug.
HandedSecrets struct The job's secrets, opened with this node's box key. Values are zeroized on drop and Debug shows only which rows they are.
HostJob struct A job the owner handed this host, under its fence.
HostJobCtx struct Everything a runner gets for one job.
HostJobError struct How a job failed: a stable kind and an operator-facing message. Neither may contain a secret.
HostUpload struct An open upload of one title: its id and bearer token. The token is zeroized on drop and never shown by Debug.
AppliedSharedBranch struct What apply_shared_branch_bootstrap wrote.
PendingSharedBranchJoin struct A shared branch join whose files are all in place but whose first start has not opened the library's database yet, or whose undoing was cut short. The daemon confirms it once the database opens, or reverts it when it cannot, so a join to an unreachable database does not leave the server unable to start.
RevertFailed struct Why PendingSharedBranchJoin::revert did not finish.
SharedBranchJoined struct A redeemed shared branch sign-in. Debug prints no secret.
BroughtConnections enum What became of the store connections a library sent with its person (keep_brought_connections).
ClientExit enum Why HostClient::run returned.
CopyFetchError enum Why fetch_copy_file did not bring the file.
CopyStreamError enum Why OwnerEndpoint::get_copy_stream did not bring the bytes.
DialError enum Why the owner could not be reached.
JoinError enum Why joining failed.
OwnerCallError enum Why a call the job makes to the owner (results, plan, upload) failed.
WriteBackError enum Why a token write-back was not stored.
announce_leaving function Tells the library of link that this install is leaving: connects with the link's keys (claiming nothing; sampler answers the connection's first heartbeat), sends node.leaving, and waits for the answer for up to timeout. Answers true when the library accepted it. Call it before the keys are deleted.
authorize_branch function Starts a sign-in at library for this install as branch_name, coming back to redirect_uri (a loopback or https URL).
authorize_join function authorize_branch, optionally offering to join as a shared branch (offer_shared_branch, SHARED_BRANCH_OFFER_PARAM): the consent page then lets an Owner of the library choose a shared branch instead of a branch. Offer it only for an install that holds no library data of its own.
bind_join_person function Binds the link a sign-in join recorded to the person on this install (branch_person): only they may add store connections to the library, or withdraw them from it, through that link. Every join path calls it after redeem_branch_code.
inspect_library function Reads what the library at address says about itself, under the transport policy (plain HTTP only on loopback).
keep_brought_connections function Keeps the store connections a library sent with its person (RedeemedBranch::accounts) for the person on this install (branch_person), recording that they came from the library.
library_origin function Normalizes what an operator typed (owner.example:8443, https://owner.example/) to a canonical origin. A bare host[:port] means https.
redeem_branch_code function Redeems an approved sign-in: the library runs the same redeem as for a link (one node, a receipt, idempotent retries), then this install seals keys and records the link. The code and verifier go once in the request body and are never logged.
authorize_clerk function Starts a clerk sign-in at library for this install as clerk_name, coming back to redirect_uri (a loopback or https URL).
exchange_clerk_code function Sends a clerk sign-in's code and verifier to the library and checks the card it answers is for the library that was inspected, without recording it here (ExchangedCard::record does).
fetch_copy_file function Downloads file index of the copy copy_id to dest.
check_join_ancestry function Reads the library's info over endpoint and refuses a library whose ancestry names this install's own library id (A ← B ← A). Answers its ancestry, to record on the link.
join_library function Enrolls this install into the library named by link.
refuse_cycle function Refuses ancestry when it names this install's own library id, is malformed, or would take this library's ancestry past what one can name (join_overflows_ancestry).
apply_shared_branch_bootstrap function Writes bootstrap as this install's own bootstrap under files_dir:
bootstrap_database_kind function The [database].plugin a shared branch's bootstrap configures.
checked_d1_api_base function Checks the D1 API origin a library's bootstrap names, and returns it normalized. Every D1 query carries the joining server's own API token to that origin, so a shared branch may only be pointed at Cloudflare's API over HTTPS. The library checks its own origin the same way before it offers a shared branch join, so a library on another D1 endpoint cannot take shared branches.
database_guest_installed function True when the database guest for kind is installed for config, so the daemon can open the library's database once the bootstrap is applied. A plugin directory that cannot be read counts as not installed.
install_problem function Why this install may not join as a shared branch now, or None.
interrupted_shared_branch_join function Names the copies an interrupted shared branch join left beside this install's bootstrap files, or None when there are none. The daemon refuses to start while any is there: a process that died while replacing the files leaves some new and some old, and starting on that mix would pair a database with the wrong node identity or key. The message says how to finish or undo the join by hand (see apply_shared_branch_bootstrap).
pending_shared_branch_join function The shared branch join this install applied but has not yet started on (or began undoing), if any. A record that cannot be read, or that names any file other than this install's own bootstrap files and their copies, is not used: copies left beside those files then stop the start (see interrupted_shared_branch_join).
redeem_shared_branch_code function Redeems an approved shared branch sign-in and opens the bootstrap with the node's box secret. The code and verifier go once in the request body, and are registered for redaction (the caller unregisters them).
OwnerSocket type alias The owner socket.
AWAITING_HOST_CONSENT constant Release reason for a job whose plugins this host's operator has not (or no longer) approved.
KIND_NOT_RUN_HERE constant Release reason for a job of a kind this host does not run.
MAX_ARTIFACT_BYTES constant Largest artifact fetched from the owner (the library blob cap).
MAX_LEASE constant Longest lease this host counts on from one work or renewed; a longer grant is renewed as if it were this long.
SECRETS_UNOPENABLE constant Error kind reported when a job's secrets do not open with this node's box key.
CONNECT_PATH constant Path of the node socket.
ENROLL_PATH constant Path of the enroll endpoint.
MAX_UPLOAD_RESUMES constant Most times one file sent in parts resumes before OwnerEndpoint::put_file gives up (a later attempt resumes again).
DATABASE_ENV_OVERRIDES constant Environment variables that would outrank a shared branch's [database] bootstrap; a shared branch join is refused while one is set.
SHARED_BRANCH_POSTGRES_URL_FILE constant File under the files directory that holds a shared branch's Postgres URL, mode 0600. [database.postgres].url_file names it by its absolute path (a relative url_file would be read from the daemon's working directory).

Re-exports

Traits

HeartbeatSource

pub trait HeartbeatSource: Send + 'static {
    fn sample(&mut self) -> NodeHeartbeat;
}

Measurements for heartbeat frames.

HeartbeatSource::sample

fn sample(&mut self) -> NodeHeartbeat

Samples this host now. May block briefly (it runs on a blocking thread).

Implemented by: NodeSampler

OwnerIo

pub trait OwnerIo: AsyncRead + AsyncWrite + Unpin + Send {}

A byte stream to the owner, plain (loopback) or TLS.

Implemented by: T

UploadSource

pub trait UploadSource: Sync {
    fn open_at(
        &self,
        offset: u64,
    ) -> impl Future<Output = Result<Pin<Box<dyn AsyncRead + Send>>>> + Send;
}

Where an uploaded file's bytes come from: readable from any offset, so an interrupted file resends only what the owner lacks.

UploadSource::open_at

fn open_at(
    &self,
    offset: u64,
) -> impl Future<Output = Result<Pin<Box<dyn AsyncRead + Send>>>> + Send

A reader of the file from offset to its end.

Errors

An I/O error when the file cannot be opened at offset.

Implemented by: LocalFileSource

HostJobRunner

pub trait HostJobRunner: Send + Sync + 'static {
    fn run(
        &self,
        ctx: HostJobCtx,
    ) -> impl Future<Output = Result<String, HostJobError>> + Send;
}

Runs claimed jobs on this host.

The runner must stop soon after HostJobCtx::is_cancelled turns true; its result is then discarded. Error kinds and messages are recorded on the owner and must never contain secret material.

HostJobRunner::run

fn run(
    &self,
    ctx: HostJobCtx,
) -> impl Future<Output = Result<String, HostJobError>> + Send

Runs one job; Ok carries the outcome text recorded as progress.

Structs

BranchAuthorization

pub struct BranchAuthorization {
    pub authorize_url: String,
    pub state: Zeroizing<String>,
    pub verifier: Zeroizing<String>,
    pub keys: LibraryLinkKeys,
    pub redirect_uri: String,
}

One sign-in about to start. Debug prints no secret.

Fields

  • authorize_url: Where to send the browser.
  • state: The OAuth state (also in the URL).
  • verifier: The PKCE verifier; never leaves this install.
  • keys: The node keys the branch will enroll.
  • redirect_uri: The redirect URI in the URL.

Implements: Debug

BranchRedeem

pub struct BranchRedeem<'a> {
    pub origin: &'a str,
    pub spki_pin: Option<&'a str>,
    pub library_id: &'a str,
    pub code: &'a str,
    pub verifier: &'a str,
    pub redirect_uri: &'a str,
    pub branch_name: &'a str,
    pub software_version: &'a str,
    pub enrolled_node_id: Option<&'a str>,
}

What redeem_branch_code needs besides the keys.

Fields

  • origin: The library's canonical origin.
  • spki_pin: The pin confirmed for a self-signed library.
  • library_id: The library id the library reported before sign-in.
  • code: The code from the callback.
  • verifier: The PKCE verifier.
  • redirect_uri: The redirect URI of the authorization.
  • branch_name: The branch name.
  • software_version: This install's version.
  • enrolled_node_id: The node the library enrolled on an earlier attempt of this same exchange that could not be saved here (JoinError::SaveFailed), when this is a retry of it. The code is already spent then, so an ancestry check that now fails for good answers JoinError::Unsaved naming that node, for its owner to revoke.

InspectedLibrary

pub struct InspectedLibrary {
    pub info: OwnerInfo,
    pub origin: String,
    pub spki_pin: Option<String>,
}

A library as inspect_library found it.

Fields

  • info: What the library said about itself.
  • origin: Its canonical origin.
  • spki_pin: The SPKI pin to trust from now on: set for a self-signed library (the operator must confirm it), None when the certificate chains to the public roots or the library is on loopback.

Implements: Clone, Debug, Eq, PartialEq

RedeemedBranch

pub struct RedeemedBranch {
    pub link: LibraryLink,
    pub node_id: String,
    pub accounts: Option<AccountBundle>,
}

A branch sign-in the library redeemed and this install recorded.

Fields

  • link: The recorded link, as stored after this enrollment (another join may have replaced it since).
  • node_id: The node id this enrollment was minted: what the join binds its person to, whatever the stored link names by then.
  • accounts: The store accounts the library's user chose to bring to this branch, opened with the link's box key; None when the user did not choose it, had none to bring, or the box did not open (logged).

Implements: Debug

ClerkAuthorization

pub struct ClerkAuthorization {
    pub authorize_url: String,
    pub state: Zeroizing<String>,
    pub verifier: Zeroizing<String>,
    pub redirect_uri: String,
    pub clerk_name: String,
}

One clerk sign-in about to start. Debug prints no secret.

Fields

  • authorize_url: Where to send the browser.
  • state: The OAuth state (also in the URL).
  • verifier: The PKCE verifier; never leaves this install.
  • redirect_uri: The redirect URI in the URL.
  • clerk_name: The name this install signs in as, trimmed.

Implements: Debug

ClerkRedeem

pub struct ClerkRedeem<'a> {
    pub origin: &'a str,
    pub spki_pin: Option<&'a str>,
    pub library_id: &'a str,
    pub library_name: &'a str,
    pub code: &'a str,
    pub verifier: &'a str,
    pub redirect_uri: &'a str,
    pub clerk_name: &'a str,
}

What exchange_clerk_code needs: the inspected library and the pending sign-in.

Fields

  • origin: The library's canonical origin.
  • spki_pin: The pin confirmed for a self-signed library.
  • library_id: The library id the library's info reported; the answer must match.
  • library_name: The library's name from its info.
  • code: The code from the redirect.
  • verifier: The sign-in's PKCE verifier.
  • redirect_uri: The redirect URI the authorize request named.
  • clerk_name: The name this install signed in as.

ExchangedCard

pub struct ExchangedCard {
    /* private fields */
}

A library card the library handed over for a clerk sign-in, not yet recorded here. Debug prints no secret.

ExchangedCard::library_id

pub fn library_id(&self) -> &str

The library the card is for.

ExchangedCard::record

pub async fn record(self, store: &LibraryStore) -> Result<ClerkLink, JoinError>

Seals the card into a clerk link (bookclerk_library::control_plane::record_clerk_link).

Errors

Returns JoinError::Unsaved when the card could not be recorded here, among others while this install is still an active branch of the library (the library then holds a session this install cannot use; the person ends it from the library's session list).

Implements: Debug

CatalogBatchAccepted

pub struct CatalogBatchAccepted {
    pub upserted: u64,
    pub skipped: u64,
    pub wanted: Vec<CatalogRef>,
}

A recorded catalog batch (HostClientHandle::catalog_sync).

Fields

  • upserted: Titles recorded.
  • skipped: Titles the library already holds (not echoed back).
  • wanted: Titles whose files the library wants.

Implements: Clone, Debug, Eq, PartialEq

CatalogSession

pub struct CatalogSession {
    pub fence: i64,
    pub cursor: String,
    pub ancestry: Vec<String>,
    pub destinations: Vec<String>,
    pub wanted: Vec<CatalogRef>,
    pub members_books: bool,
}

An opened catalog session (HostClientHandle::catalog_begin).

Fields

  • fence: The catalog fence every later call names.
  • cursor: Resume after this cursor (empty: from the start).
  • ancestry: The library's ancestry, its own library id first.
  • destinations: The library node's destination ids, the primary first.
  • wanted: Titles whose files the library still wants.
  • members_books: The library's "Acquire all of this branch's members' books": send the members' books this branch lists to it as well.

Implements: Clone, Debug, Eq, PartialEq

ClientTiming

pub struct ClientTiming {
    pub heartbeat_interval: Duration,
    pub ping_interval: Duration,
    pub idle_timeout: Duration,
    pub backoff_min: Duration,
    pub backoff_max: Duration,
    pub request_timeout: Duration,
}

Timers of the client. The defaults follow the protocol constants.

Fields

  • heartbeat_interval: Between heartbeats.
  • ping_interval: Between pings.
  • idle_timeout: Without any inbound frame before the client closes.
  • backoff_min: First reconnect delay.
  • backoff_max: Largest reconnect delay.
  • request_timeout: How long a request waits for room in the send queue and then for its answer.

Implements: Clone, Copy, Debug, Default

HostClient

pub struct HostClient<R: HostJobRunner> {
    /* private fields */
}

The host side of the node API for one library link.

HostClient::new

pub fn new(
    config: HostClientConfig,
    runner: R,
    sampler: Box<dyn HeartbeatSource>,
) -> Result<(Self, HostClientHandle), DialError>

A client for config, running jobs through runner.

Errors

Returns DialError when the link's origin or pin fails the transport policy.

HostClient::run

pub async fn run(self, shutdown: Receiver<bool>) -> ClientExit

Connects, serves, and reconnects until shutdown turns true (or its sender is dropped) or the owner revokes this node.

Every held job is cancelled as lost when this returns, whatever the reason, and also when the future is dropped or its task aborted first, so no job task keeps running for a client that is gone.

HostClientConfig

pub struct HostClientConfig {
    pub link: LibraryLink,
    pub keys: LibraryLinkKeys,
    pub software_version: String,
    pub incarnation: String,
    pub max_jobs: usize,
    pub claim_kinds: Vec<String>,
    pub claims_after_refresh: bool,
    pub timing: ClientTiming,
    pub share: Option<Receiver<usize>>,
}

What one client connects with.

Fields

  • link: The active library link.
  • keys: Its node keys.
  • software_version: This host's Bookclerk version.
  • incarnation: This process's incarnation (a plain id).
  • max_jobs: Jobs run at once. Zero claims nothing.
  • claim_kinds: Job kinds this host runs (scan, ...). Empty claims nothing.
  • claims_after_refresh: When set, a connection claims nothing until HostClientHandle::deployments_refreshed names it, so the caller can re-read what the owner deployed (which may have changed while this host was away) before work runs against it.
  • timing: Timers.
  • share: This link's share of the machine, in jobs, when the host shares its capacity between several libraries and its own work. The claim loop holds at most the smaller of this and Self::max_jobs; a share that shrinks below the jobs held cancels none of them, it only stops claims until enough finish. None holds up to Self::max_jobs.

HostClientHandle

pub struct HostClientHandle {
    /* private fields */
}

Watches a running client.

HostClientHandle::subscribe_wakes

pub fn subscribe_wakes(&self) -> Receiver<Value>

Wakes the owner forwarded ({"type": "deployment.changed", ...}).

A wake is acked once it is handed to at least one subscriber; while there is none it stays unacked and the owner redelivers it later. A subscriber that falls more than 64 wakes behind sees broadcast::error::RecvError::Lagged for wakes already acked, and must then resync the state they announce from the owner.

HostClientHandle::connections

pub fn connections(&self) -> Receiver<u64>

Count of welcomed connections so far.

HostClientHandle::deployments_refreshed

pub fn deployments_refreshed(&self, connection: u64)

Records that the deployments were re-read on the connection counted connection (a Self::connections value read before the request), which opens its claims under HostClientConfig::claims_after_refresh. A read made on an earlier connection opens nothing on a later one.

HostClientHandle::is_connected

pub fn is_connected(&self) -> bool

True while a welcomed connection is live.

HostClientHandle::held_fences

pub fn held_fences(&self) -> Vec<HeldFence>

Fences this host holds and has not lost.

HostClientHandle::node_id

pub fn node_id(&self) -> &str

The node id this host has in the library.

HostClientHandle::library_id

pub fn library_id(&self) -> &str

The parent library id.

HostClientHandle::set_consented_plugins

pub fn set_consented_plugins(&self, plugins: BTreeSet<String>)

Sets the plugin keys this host's operator consents to. Claims carry them as their filter from the next claim on; a held job that runs a plugin outside them is cancelled and given back unrun.

The new set is published before the held jobs are scanned: a job that is being started concurrently is either already held (and caught by the scan) or checks consent after it is held and so reads the new set. Scanning first would leave a gap where a job inserted after the scan still read the old set and ran.

HostClientHandle::consented_plugins

pub fn consented_plugins(&self) -> BTreeSet<String>

The plugin keys consented to now.

HostClientHandle::set_claim_scope

pub fn set_claim_scope(&self, scope: ClaimScope)

Sets whose work later claims take. Jobs already held keep running: the setting decides what this host asks for, and the library hands only work the node is trusted with either way.

HostClientHandle::claim_scope

pub fn claim_scope(&self) -> ClaimScope

Whose work claims take now.

HostClientHandle::request

pub async fn request(&self, body: Body) -> Option<Frame>

Sends body on the live connection (waiting up to the request timeout for one) and answers the owner's frame, or None when no connection answered.

HostClientHandle::offer_accounts

pub async fn offer_accounts(
    &self,
    accounts: Vec<CarriedAccount>,
) -> Result<OfferedAccounts, OwnerCallError>

Offers the branch person's store accounts to the library ("Add my connections to library"): seals them to the live connection's owner box key, bound to the library and this node, and answers the library's report.

Errors

Returns OwnerCallError::Refused with the library's reason, or OwnerCallError::Unavailable when no connection answered or the bundle could not be sealed.

HostClientHandle::push_sign_in

pub async fn push_sign_in(
    &self,
    account: CarriedAccount,
    revision: i64,
) -> Result<KeeperOutcome, OwnerCallError>

Pushes the newest sign-in of one single-keeper store account this branch keeps up to the library (accounts.update), sealed like Self::offer_accounts, at the keeper's revision.

Errors

Returns OwnerCallError::Refused when the library refuses it, or OwnerCallError::Unavailable when no connection answers.

HostClientHandle::withdraw_account

pub async fn withdraw_account(
    &self,
    plugin_key: &str,
    account_id: &str,
) -> Result<(), OwnerCallError>

Tells the library the person disconnected this store account everywhere; it removes their links to it there.

Errors

As Self::offer_accounts.

HostClientHandle::open_instance_secrets

pub fn open_instance_secrets(
    &self,
    instance_id: &str,
    revision: i64,
    sealed: &str,
) -> Result<SecretValue, SealError>

Opens an instance's SECRETS sealed to this node's box key (instance_config.sealed_secrets), registering the values with the log and diagnostics scrubber.

Errors

Returns SealError when it was not sealed to this node for this instance and revision.

HostClientHandle::fetch_artifact

pub async fn fetch_artifact(&self, archive_sha256: &str) -> Result<Vec<u8>, DialError>

Downloads one archive the owner stores (blob:sha256:<hex>) from its artifact endpoint, signing the request with this node's key. The caller checks the digest.

Errors

Returns DialError when the request fails or the owner does not answer 200 with at most MAX_ARTIFACT_BYTES.

HostClientHandle::catalog_begin

pub async fn catalog_begin(
    &self,
    share_books: bool,
    include_branches: bool,
) -> Result<CatalogSession, OwnerCallError>

catalog.begin: opens this branch's catalog sync with the link's two settings and answers the session (a new fence each time).

Errors

Returns OwnerCallError.

HostClientHandle::catalog_sync

pub async fn catalog_sync(
    &self,
    fence: i64,
    batch: u64,
    cursor: &str,
    done: bool,
    titles: Vec<CatalogTitle>,
) -> Result<CatalogBatchAccepted, OwnerCallError>

catalog.sync: one batch of shared titles under fence, naming the cursor after it.

Errors

Returns OwnerCallError; Lost when the fence moved on.

HostClientHandle::catalog_questions

pub async fn catalog_questions(&self) -> Result<Vec<LookupWork>, OwnerCallError>

catalog.questions: the catalog questions the library has for this branch, at most bookclerk_node_proto::MAX_LOOKUP_WORKS (empty when none waits). A list that breaks the frame rules is refused as OwnerCallError::Unavailable.

Errors

Returns OwnerCallError; Refused when the library does not count this node as a branch.

HostClientHandle::catalog_found

pub async fn catalog_found(
    &self,
    answers: Vec<LookupAnswer>,
    missing: Vec<String>,
) -> Result<(), OwnerCallError>

catalog.found: this branch's answers to questions it was sent, and the works it cannot supply.

Errors

Returns OwnerCallError.

HostClientHandle::requests_claim

pub async fn requests_claim(&self) -> Result<Vec<BranchRequest>, OwnerCallError>

requests.claim: claims the interlibrary requests the library has for this branch, at most bookclerk_node_proto::MAX_CLAIMED_REQUESTS (empty when none waits). A list that breaks the frame rules is refused as OwnerCallError::Unavailable; its leases then expire and the requests go back to pending.

Errors

Returns OwnerCallError; Refused when the library does not count this node as a branch.

HostClientHandle::request_finish

pub async fn request_finish(
    &self,
    job: &str,
    generation: i64,
    outcome: RequestOutcome,
) -> Result<(), OwnerCallError>

requests.finish: reports what this branch did with one claimed request.

Errors

Returns OwnerCallError; Lost when the lease is no longer this branch's.

HostClientHandle::window_books

pub async fn window_books(
    &self,
    after: &WindowCursor,
) -> Result<(Vec<WindowWork>, Option<WindowCursor>), OwnerCallError>

window.books: one page of the books the library holds for this window's person, from cursor after (empty for the first page).

Returns

The page's works and the cursor of the next page (None on the last). A page that breaks the frame rules, or whose cursor does not move past after, is refused as OwnerCallError::Unavailable.

Errors

Returns OwnerCallError; Refused when the library does not count this node as a branch.

HostClientHandle::copy_grant

pub async fn copy_grant(
    &self,
    store: &str,
    marketplace: &str,
    product_id: &str,
) -> Result<Option<GrantedCopy>, OwnerCallError>

copy.grant: asks the library for the copy it holds of the edition named by its store listing, for this node's owner, and opens the sealed token (bound to this node and the copy).

Returns

None when the library answers not_found: the person cannot take that edition, or the library holds no copy of it.

Errors

Returns OwnerCallError; Refused when the library does not count this node as a branch, Unavailable for an answer that breaks the frame rules or a token that does not open.

HostClientHandle::fetch_copy_file

pub async fn fetch_copy_file(
    &self,
    copy: &GrantedCopy,
    index: usize,
    dest: &Path,
) -> Result<(), CopyFetchError>

Downloads file index of copy to dest from the library that granted it, resuming what dest already holds (crate::fetch_copy_file).

Errors

Returns [crate::CopyFetchError]: OtherLibrary when another library granted copy (its token is not sent), NoSuchFile when the grant lists no file at index.

HostClientHandle::catalog_upload

pub async fn catalog_upload(
    &self,
    fence: i64,
    title: &CatalogRef,
    files: Vec<UploadFile>,
) -> Result<HostUpload, OwnerCallError>

catalog.upload: opens an upload of one shared title's files and opens its sealed token (bound to this node, CATALOG_ITEM, the fence and the upload).

Errors

Returns OwnerCallError.

HostClientHandle::upload_catalog_file

pub async fn upload_catalog_file<S: UploadSource + ?Sized>(
    &self,
    upload: &HostUpload,
    index: usize,
    length: u64,
    source: &S,
) -> Result<(), OwnerCallError>

Streams declared file index of a catalog upload (length bytes read from source) to the library's upload endpoint, resuming an interrupted file where the library stands.

Errors

Returns OwnerCallError.

HostClientHandle::commit_catalog_upload

pub async fn commit_catalog_upload(
    &self,
    upload: &HostUpload,
) -> Result<(), OwnerCallError>

Commits a catalog upload.

Errors

Returns OwnerCallError.

Implements: Clone

OfferedAccounts

pub struct OfferedAccounts {
    pub added: u64,
    pub already_here: u64,
    pub taken: u64,
    pub failed: u64,
    pub not_allowed: bool,
}

What the library kept of an HostClientHandle::offer_accounts.

Fields

  • added: Accounts now connected there for the person.
  • already_here: Accounts the person had already connected there.
  • taken: Accounts connected to someone else there; left as they are.
  • failed: Accounts that could not be kept.
  • not_allowed: The library's operator does not let the person connect accounts.

Implements: Clone, Copy, Debug, Eq, PartialEq

LocalFileSource

pub struct LocalFileSource(pub PathBuf);

A file on this install's disk as an UploadSource.

Implements: Clone, Debug, UploadSource

OwnerEndpoint

pub struct OwnerEndpoint {
    /* private fields */
}

Where and how to reach one owner.

OwnerEndpoint::new

pub fn new(origin: &str, spki_pin: Option<&str>) -> Result<Self, DialError>

Checks origin (and the link's spki_pin) against the transport policy.

Errors

Returns DialError::Invalid for a malformed origin or pin and DialError::Insecure for plain HTTP to a non-loopback host or a pinned plain-HTTP origin.

OwnerEndpoint::origin

pub fn origin(&self) -> &str

The canonical origin the handshake signs.

OwnerEndpoint::is_pinned

pub fn is_pinned(&self) -> bool

True when the link pins the owner's certificate.

OwnerEndpoint::connect

pub async fn connect(&self) -> Result<Box<dyn OwnerIo>, DialError>

Opens a byte stream to the owner under the policy.

Errors

Returns DialError when the owner is unreachable or TLS fails.

OwnerEndpoint::connect_socket

pub async fn connect_socket(&self) -> Result<OwnerSocket, DialError>

Dials the node socket, offering SUBPROTOCOL and requiring the owner to select it.

Errors

Returns DialError when the connection or the upgrade fails.

OwnerEndpoint::connect_clerk_socket

pub async fn connect_clerk_socket(&self, card: &str) -> Result<OwnerSocket, DialError>

Dials a library's clerk socket (CLERK_CONNECT_PATH) with a library card, offering CLERK_SUBPROTOCOL and requiring the library to select it. The card is written straight to the stream and never logged.

Arguments
  • card - The library card (the token alone, without the scheme).
Errors

Returns DialError when the connection or the upgrade fails; DialError::Refused carries the library's status (401 when the card was ended).

OwnerEndpoint::post_json

pub async fn post_json(
    &self,
    path: &str,
    body: &[u8],
) -> Result<(u16, Vec<u8>), DialError>

POST path with a JSON body; answers the status and body. The body is written straight to the stream and never logged.

Errors

Returns DialError when the request cannot be made or the answer is malformed.

OwnerEndpoint::post_json_within

pub async fn post_json_within(
    &self,
    path: &str,
    body: &[u8],
    extra_body: usize,
) -> Result<(u16, Vec<u8>), DialError>

post_json for an answer that may carry up to extra_body more bytes than the usual response limit (a redeem answer with sealed store connections).

Errors

Returns DialError when the request cannot be made or the answer is malformed or over the limit.

OwnerEndpoint::get_json

pub async fn get_json(
    &self,
    path: &str,
    max_body: usize,
) -> Result<(u16, Vec<u8>), DialError>

GET path of a small JSON answer (at most max_body bytes), over the verified transport (the link's pin or the webpki roots). Nothing secret is sent.

Errors

Returns DialError when the request cannot be made, the answer is malformed, or it is larger than max_body.

OwnerEndpoint::get_authorized

pub async fn get_authorized(
    &self,
    path: &str,
    authorization: &str,
    max_body: usize,
) -> Result<(u16, Vec<u8>), DialError>

GET path with an Authorization header; answers the status and a body of at most max_body bytes. The header is written straight to the stream and never logged.

Errors

Returns DialError when the request cannot be made, the answer is malformed, or it is larger than max_body.

OwnerEndpoint::put_stream

pub async fn put_stream<R: AsyncRead + Unpin + Send>(
    &self,
    path: &str,
    authorization: &str,
    length: u64,
    body: R,
) -> Result<(u16, Vec<u8>), DialError>

PUT path streaming exactly length bytes from body, with an Authorization header; answers the status and the (small) body. The header and the bytes are written straight to the stream and never logged. Nothing is buffered beyond one copy chunk.

An owner may answer before it has read the whole body (a lost fence); the answer is still read after a failed write, for at most the idle timeout. Every read of body and every write to the owner must make progress within UPLOAD_IDLE_TIMEOUT_SECS.

Errors

Returns DialError when the request cannot be made, body ends early, a read or write stalls (DialError::Timeout), or the answer is malformed or does not come within UPLOAD_ANSWER_TIMEOUT_SECS of the last byte.

OwnerEndpoint::put_file

pub async fn put_file<S: UploadSource + ?Sized>(
    &self,
    path: &str,
    authorization: &str,
    size: u64,
    part_bytes: u64,
    source: &S,
) -> Result<(u16, Vec<u8>), DialError>

PUT path of a declared upload file of size bytes read from source: in one request when it fits in part_bytes, otherwise as consecutive parts of at most part_bytes, each its own request with Content-Range (UploadPart), so a relay that caps request bodies passes it.

A file sent in parts resumes: it first asks where the owner is (bytes */<size>, UploadRange::Status) and sends from that offset, and after a broken part or a resume answer it asks again and sends only the rest, at most MAX_UPLOAD_RESUMES times. Answers the status and body of the request that settled the file: the last part's, the first that was neither 200 partial nor a resume, or the first that says the owner already holds the whole file (received).

Errors

As Self::put_stream, once the resumes run out; and DialError::Io when source cannot be read from an offset.

OwnerEndpoint::post_json_authorized

pub async fn post_json_authorized(
    &self,
    path: &str,
    authorization: &str,
    body: &[u8],
) -> Result<(u16, Vec<u8>), DialError>

POST path with a JSON body and an Authorization header; answers the status and body. Neither is logged.

Errors

Returns DialError when the request cannot be made or the answer is malformed.

OwnerEndpoint::get_copy_stream

pub async fn get_copy_stream(
    &self,
    path: &str,
    authorization: &str,
    resume_from: u64,
    size: u64,
    file: &mut File,
) -> Result<u16, CopyStreamError>

GET path of one file of a copy the library granted, streamed into file: the bytes from resume_from on when the library honours the range, else the whole file. Nothing is buffered beyond one copy chunk, and the header is written straight to the stream and never logged.

The answer's head is read by bookclerk_node_proto::parse_copy_answer, so a body is taken only when it is exactly the bytes asked for: file is cut to empty before a whole file is written and is written from resume_from otherwise, and no more than the stated length is taken. Every read from the library must make progress within the idle timeout.

Arguments
  • resume_from - Bytes of the file file already holds; 0 asks for the whole file.
  • size - The file's exact size, as the grant stated it.
Returns

The status: 200 or 206 once file holds all size bytes, any other status when the library sent no file bytes (file is then untouched).

Errors

Returns CopyStreamError::Transfer when the request cannot be made, the answer does not state exactly the bytes asked for or ends early (DialError::Http), or a read stalls (DialError::Timeout); CopyStreamError::Local when file cannot be written.

OwnerEndpoint::probe_json

pub async fn probe_json(
    &self,
    path: &str,
) -> Result<(u16, Vec<u8>, Option<TlsProbe>), DialError>

GET path on an owner whose certificate is not known yet: the TLS handshake accepts any certificate whose key signs the handshake, records its SPKI pin and whether it would pass the webpki roots, and answers both with the status and body. Plain-HTTP (loopback) origins answer no probe.

Only for reading what a library says about itself before its operator confirms the pin (trust on first use); nothing secret is sent. A pinned endpoint is refused.

Errors

Returns DialError when the request cannot be made or the answer is malformed.

Implements: Clone, Debug

TlsProbe

pub struct TlsProbe {
    pub spki_pin: String,
    pub webpki_trusted: bool,
}

What a first TLS handshake showed of an owner's certificate, before any pin is known (OwnerEndpoint::probe_json).

Fields

  • spki_pin: base64url SHA-256 of the presented certificate's SubjectPublicKeyInfo.
  • webpki_trusted: True when the certificate chains to the webpki roots and names the host (what an unpinned connection requires).

Implements: Clone, Debug, Eq, PartialEq

GrantedCopy

pub struct GrantedCopy {
    pub copy_id: String,
    pub expires_in_secs: u64,
    pub copy: WindowCopy,
    pub files: Vec<CopyFile>,
    /* private fields */
}

A copy of an edition the library granted this node (crate::HostClientHandle::copy_grant): what it is, its files, and the bearer token of its downloads. The token is zeroized on drop and never shown by Debug.

Fields

  • copy_id: Copy id; file n is at COPIES_PATH<copy_id>/files/<n>.
  • expires_in_secs: Seconds the token stays valid from the grant.
  • copy: What the copy is.
  • files: The copy's files, in download order.

GrantedCopy::authorization

pub fn authorization(&self) -> Result<Zeroizing<String>, OwnerCallError>

The Authorization header value of this copy's downloads.

Errors

Returns OwnerCallError::Unavailable when the token is not text.

Implements: Debug, Drop

HandedSecrets

pub struct HandedSecrets(/* private */);

The job's secrets, opened with this node's box key. Values are zeroized on drop and Debug shows only which rows they are.

HandedSecrets::refs

pub fn refs(&self) -> impl Iterator<Item = &SecretRef>

The rows handed with the job.

HandedSecrets::get

pub fn get(&self, secret_ref: &SecretRef) -> Option<&SecretValue>

The value of one handed row.

HandedSecrets::len

pub fn len(&self) -> usize

Number of handed rows.

HandedSecrets::is_empty

pub fn is_empty(&self) -> bool

True when the job needs no secrets.

Implements: Debug

HostJob

pub struct HostJob {
    pub node_id: String,
    pub job: WorkJob,
    pub fence: i64,
    pub lease_secs: u64,
    pub plugin_keys: Vec<String>,
    pub source_plugin_key: Option<String>,
    pub lease_deadline: SystemTime,
    pub resumed: bool,
}

A job the owner handed this host, under its fence.

Fields

  • node_id: This host's node id in the library (the lease owner is host:<node_id>).
  • job: The job as the owner stores it.
  • fence: Lease generation; every frame for the job names it.
  • lease_secs: Lease length the owner granted.
  • plugin_keys: Plugin keys the job runs (each consented when it was claimed).
  • source_plugin_key: The one plugin of plugin_keys whose source guest runs the job, when the owner named it.
  • lease_deadline: When the granted lease runs out, counted as the client counts it: from before the claim was sent, capped at crate::MAX_LEASE. Work handed a deadline should stop by then, since the fence may be lost once it passes without a renewal.
  • resumed: The claim resumed a suspended job: no attempt was spent, and the job's checkpoint applies.

Implements: Clone, Debug

HostJobCtx

pub struct HostJobCtx {
    pub job: HostJob,
    pub secrets: Arc<HandedSecrets>,
    /* private fields */
}

Everything a runner gets for one job.

Fields

  • job: The job and its fence.
  • secrets: Its opened secrets.

HostJobCtx::is_cancelled

pub fn is_cancelled(&self) -> bool

True when the runner should stop: the fence was lost or the operator cancelled the job.

HostJobCtx::is_lost

pub fn is_lost(&self) -> bool

True once the job's fence is lost: the owner reported it, or the lease ran out without a confirmed renewal. The owner may already have handed the job to another run, which then owns the job's titles, so this run must not undo anything it wrote under them.

HostJobCtx::cancel_flag

pub fn cancel_flag(&self) -> Arc<AtomicBool>

The cancel flag, for runners that poll it elsewhere.

HostJobCtx::write_back

pub async fn write_back(
    &self,
    secret_ref: &SecretRef,
    value: &[u8],
) -> Result<(), WriteBackError>

Writes a refreshed store token back to the owner (decision 3).

Only a row handed with this job may be written, and only under its live fence. The value is sealed to the current connection's owner box key, bound to this node, job, fence and ref; it never travels or is logged as text.

Errors

Returns WriteBackError when the ref was not handed, the owner refuses, the fence is lost, or no owner connection answers.

HostJobCtx::send_scan_results

pub async fn send_scan_results(
    &self,
    plugin_key: &str,
    books: Vec<Value>,
) -> Result<u64, OwnerCallError>

Sends one batch of a scan's rows (the guest's ScanBook objects) to the owner, which validates and writes them (decision 6); answers the rows written. At most bookclerk_node_proto::MAX_SCAN_BATCH_ROWS rows, each at most bookclerk_node_proto::MAX_SCAN_ROW_BYTES serialized.

Errors

Returns OwnerCallError; Lost also cancels the job.

HostJobCtx::send_scan_removed

pub async fn send_scan_removed(
    &self,
    plugin_key: &str,
    account_id: &str,
    product_ids: Vec<String>,
) -> Result<u64, OwnerCallError>

Sends product ids a delta pass of account_id found gone to the owner, which removes those holdings; answers how many it removed. Sent after the job's rows, at most bookclerk_node_proto::MAX_SCAN_REMOVED_IDS ids per call.

Errors

Returns OwnerCallError; Lost also cancels the job.

HostJobCtx::send_scan_pass_end

pub async fn send_scan_pass_end(
    &self,
    plugin_key: &str,
    account_id: &str,
    sync_token: &str,
    complete: bool,
    full: bool,
) -> Result<u64, OwnerCallError>

Tells the owner how the pass of account_id ended, after its rows and removals: the owner keeps 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. Answers how many it removed.

Errors

Returns OwnerCallError; Lost also cancels the job.

HostJobCtx::acquire_plan

pub async fn acquire_plan(
    &self,
) -> Result<(Vec<AcquireTarget>, Vec<PlanDestination>), OwnerCallError>

Asks the owner which titles this acquire should fetch, and with which destinations (the shared node's, the primary first, each with its own DownloadOptions).

Errors

Returns OwnerCallError; Lost also cancels the job.

HostJobCtx::grant_upload

pub async fn grant_upload(
    &self,
    holding_id: &str,
    primary_key: &str,
    pdf_key: Option<&str>,
    files: Vec<UploadFile>,
) -> Result<HostUpload, OwnerCallError>

Opens an upload of one title's files (an empty holding_id and no files for the job's closing upload).

Errors

Returns OwnerCallError; Lost also cancels the job.

HostJobCtx::upload_file

pub async fn upload_file<S: UploadSource + ?Sized>(
    &self,
    upload: &HostUpload,
    index: usize,
    length: u64,
    source: &S,
) -> Result<(), OwnerCallError>

Streams declared file index of upload (length bytes read from source) to the owner, which writes it to its destinations as it arrives; an interrupted file resumes where the owner stands.

Errors

Returns OwnerCallError; Lost (the owner aborted the upload) also cancels the job.

HostJobCtx::commit_upload

pub async fn commit_upload(
    &self,
    upload: &HostUpload,
    finish: Option<&str>,
) -> Result<bool, OwnerCallError>

Commits upload. With finish, the owner also completes the job (recording the text as its progress) and the client sends no complete afterwards. Answers whether the job is finished.

Errors

Returns OwnerCallError; Lost also cancels the job.

Implements: Debug

HostJobError

pub struct HostJobError {
    pub kind: String,
    pub message: String,
}

How a job failed: a stable kind and an operator-facing message. Neither may contain a secret.

Fields

  • kind: Stable error kind recorded on the owner's job row.
  • message: Operator-facing message.

HostJobError::new

pub fn new(kind: impl Into<String>, message: impl Into<String>) -> Self

A failure of kind.

Implements: Clone, Debug, Eq, PartialEq

HostUpload

pub struct HostUpload {
    pub upload_id: String,
    /* private fields */
}

An open upload of one title: its id and bearer token. The token is zeroized on drop and never shown by Debug.

Fields

  • upload_id: Upload id.

Implements: Debug, Drop

AppliedSharedBranch

pub struct AppliedSharedBranch {
    pub database: DatabasePluginKind,
    pub wrapped: bool,
    pub config_file: PathBuf,
}

What apply_shared_branch_bootstrap wrote.

Fields

  • database: The [database].plugin now configured.
  • wrapped: True when master.key is wrapped with this install's password.
  • config_file: The config file written.

Implements: Clone, Debug, Eq, PartialEq

PendingSharedBranchJoin

pub struct PendingSharedBranchJoin {
    /* private fields */
}

A shared branch join whose files are all in place but whose first start has not opened the library's database yet, or whose undoing was cut short. The daemon confirms it once the database opens, or reverts it when it cannot, so a join to an unreachable database does not leave the server unable to start.

PendingSharedBranchJoin::reverting

pub fn reverting(&self) -> bool

Whether an earlier start began putting the originals back and did not finish: the daemon then finishes the revert before anything else, and does not try the library's database again.

PendingSharedBranchJoin::confirm

pub fn confirm(self)

The library's database opened: drops the record, then the copies of the originals. The record goes first, so a crash part way leaves copies with no record, which the next start refuses on with interrupted_shared_branch_join's instructions (its config.toml is the library's, so the copies are to be deleted). A copy that cannot be removed is logged, since it stops the next start.

PendingSharedBranchJoin::revert

pub fn revert(self) -> Result<(), RevertFailed>

The library's database did not open: puts every original back, removes the files the join created, and drops the record, so the next start runs on this install's own bootstrap again. The record is first marked reverting, and every step can run again (a copy already moved back is gone, a created file already removed is absent), so a revert cut short by a crash or a failed rename is finished by the next start instead of leaving a mix.

Before the revert starts, every recorded copy must still exist: a copy missing at that point was removed by hand, not moved back, so undoing the rest would leave a mix of this install's files and the library's.

Errors

Returns RevertFailed with started false when nothing was changed (a copy is missing, or the record could not be marked), so the record still says the join is applied. With started true it names the files that could not be put back; the record stays marked reverting, so the next start finishes the undo before anything else.

Implements: Debug

RevertFailed

pub struct RevertFailed {
    pub started: bool,
    pub detail: String,
}

Why PendingSharedBranchJoin::revert did not finish.

Fields

  • started: Whether the undo had begun: when true the record is marked reverting and the next start finishes it; when false nothing was changed and the record still says the join is applied.
  • detail: What went wrong, naming the files involved.

Implements: Debug, Display

SharedBranchJoined

pub struct SharedBranchJoined {
    pub library_id: String,
    pub node_id: String,
    pub bootstrap: SharedBranchBootstrap,
}

A redeemed shared branch sign-in. Debug prints no secret.

Fields

  • library_id: The library id.
  • node_id: The node id the library recorded (kind = shared).
  • bootstrap: The opened bootstrap.

Implements: Debug

Enums

BroughtConnections

pub enum BroughtConnections {
    Kept(CarriedImport),
    NoPerson(usize),
}

What became of the store connections a library sent with its person (keep_brought_connections).

Variants

  • Kept: They were imported for the person (see CarriedImport).
  • NoPerson: No one on this install could be named as their person (no Owner yet, or several); nothing was stored. Holds how many came.

Implements: Clone, Debug, Eq, PartialEq

ClientExit

pub enum ClientExit {
    Shutdown,
    Revoked,
}

Why HostClient::run returned.

Variants

  • Shutdown: The shutdown signal fired.
  • Revoked: The owner closed with [CLOSE_REVOKED]: this node's credential is revoked. The caller should mark the link revoked.

Implements: Clone, Debug, Eq, PartialEq

CopyFetchError

pub enum CopyFetchError {
    InvalidCopy,
    OtherLibrary,
    NoSuchFile,
    Status(u16),
    Transfer(DialError),
    Local(Error),
}

Why fetch_copy_file did not bring the file.

Variants

  • InvalidCopy: The copy id is not one a library gives out; nothing was asked.
  • OtherLibrary: Another library granted the copy than the one asked for its file; nothing was asked, so the token was sent to no one.
  • NoSuchFile: The grant lists no file at that index; nothing was asked.
  • Status: The library answered with this status instead of the file: 401 when the token ended, the branch is no longer trusted or the card is signed out (ask for a new grant), 404 when the copy has no such file.
  • Transfer: The request failed, stalled, or the answer was not the bytes asked for. What arrived so far is kept, so the next call resumes.
  • Local: The local file could not be opened, read or written (a full disk, say). Calling again does not help until that is fixed.

Implements: Debug, Display, Error, From<CopyStreamError>, From<DialError>, From<Error>

CopyStreamError

pub enum CopyStreamError {
    Transfer(DialError),
    Local(Error),
}

Why OwnerEndpoint::get_copy_stream did not bring the bytes.

Variants

  • Transfer: The request or the library's answer failed; asking again may work.
  • Local: The destination file could not be cut, positioned or written (a full disk, say); asking again does not help until that is fixed.

Implements: Debug, Display, Error, From<CopyStreamError>, From<DialError>

DialError

pub enum DialError {
    Insecure(&'static str),
    Invalid(String),
    Io(Error),
    Tls(String),
    Refused(u16),
    Handshake(String),
    Http,
    Timeout,
}

Why the owner could not be reached.

Variants

  • Insecure: The transport policy refuses this origin (plain HTTP to a non-loopback host, or a pin on a plain-HTTP origin).
  • Invalid: The origin or pin is malformed.
  • Io: TCP connect or I/O failed.
  • Tls: The TLS handshake failed: a wrong pin, an untrusted certificate, or a protocol error.
  • Refused: The owner answered the upgrade with an HTTP status.
  • Handshake: The WebSocket handshake failed otherwise.
  • Http: The owner's HTTP answer was malformed or too large.
  • Timeout: A step did not finish in time.

Implements: Debug, Display, Error, From<DialError>, From<Error>

JoinError

pub enum JoinError {
    Link(String),
    Dial(DialError),
    Refused,
    OriginMismatch { origin: String },
    Http { status: u16, error: String },
    Record(String),
    Cycle,
    AncestryTooDeep,
    Unsaved { node_id: Option<String>, reason: String },
    SaveFailed { node_id: String, reason: String },
}

Why joining failed.

Variants

  • Link: The text is not a whole https://<owner>/enroll#bcn1... link.
  • Dial: The owner could not be reached under the transport policy.
  • Refused: The owner refused the link (spent, expired, revoked, or unknown), or the sign-in's code.
  • OriginMismatch: The library names another origin as its own; join at that one.
    • origin: The origin the library names.
  • Http: The owner answered with another status.
    • status: HTTP status.
    • error: The answer's error code.
  • Record: The enroll request could not be built, or the library's info (its ancestry) could not be read.
  • Cycle: The library is this one, or one of its own branches (its ancestry names this library): joining it would make a cycle.
  • AncestryTooDeep: Joining the library would give this one more ancestors than an ancestry can name, so a later join under it could not be checked for a loop.
  • Unsaved: The library accepted the join (an invite link or a sign-in code), but its answer did not parse or the local write failed. The one-use credential is spent and the node keys are gone, so this install cannot use the node the library minted: its owner removes that node (named when the answer said which) and this install joins again.
    • node_id: The node id the owner minted, when its answer named one.
    • reason: What failed.
  • SaveFailed: A sign-in's code was redeemed and the library enrolled this host, but the local write failed. The library answers a repeat of the same exchange (code, verifier, keys) with the same node, so a retry with the sign-in still pending can finish the join.
    • node_id: The node id the library minted.
    • reason: What failed.

JoinError::is_retryable

pub fn is_retryable(&self) -> bool

True for a sign-in redeem failure that a repeat of the same exchange (code, verifier, keys) can fix: the library unreachable (its answer may have been lost after it enrolled the node, which a repeat gets again), busy, or the local write failed.

Implements: Debug, Display, Error, From<DialError>

OwnerCallError

pub enum OwnerCallError {
    Lost,
    Refused(String),
    Unavailable,
}

Why a call the job makes to the owner (results, plan, upload) failed.

Variants

  • Lost: The fence is lost; the job must stop (it is already cancelled).
  • Refused: The owner refused it; the reason is stable.
  • Unavailable: No connection to the owner, or no usable answer.

Implements: Clone, Debug, Display, Eq, Error, PartialEq

WriteBackError

pub enum WriteBackError {
    NotHanded,
    Size,
    Lost,
    Refused(String),
    Unavailable,
}

Why a token write-back was not stored.

Variants

  • NotHanded: The ref was not handed with this job; nothing was sent.
  • Size: The value is empty or larger than the owner accepts; nothing was sent.
  • Lost: The fence is lost; the job must stop.
  • Refused: The owner refused it (fence_not_live, not_trusted, ...).
  • Unavailable: No connection to the owner, or it did not answer in time.

Implements: Debug, Display, Eq, Error, PartialEq

Functions

announce_leaving

pub async fn announce_leaving(
    link: LibraryLink,
    keys: LibraryLinkKeys,
    software_version: &str,
    sampler: Box<dyn HeartbeatSource>,
    timeout: Duration,
) -> bool

Tells the library of link that this install is leaving: connects with the link's keys (claiming nothing; sampler answers the connection's first heartbeat), sends node.leaving, and waits for the answer for up to timeout. Answers true when the library accepted it. Call it before the keys are deleted.

A running client for the same link is superseded by this connection; the library then revokes the node, so that client stops too.

authorize_branch

pub fn authorize_branch(
    library: &InspectedLibrary,
    redirect_uri: &str,
    branch_name: &str,
) -> Result<BranchAuthorization, JoinError>

Starts a sign-in at library for this install as branch_name, coming back to redirect_uri (a loopback or https URL).

Errors

Returns JoinError::Link for a redirect URI the library would refuse or a malformed branch name.

authorize_join

pub fn authorize_join(
    library: &InspectedLibrary,
    redirect_uri: &str,
    branch_name: &str,
    offer_shared_branch: bool,
) -> Result<BranchAuthorization, JoinError>

authorize_branch, optionally offering to join as a shared branch (offer_shared_branch, SHARED_BRANCH_OFFER_PARAM): the consent page then lets an Owner of the library choose a shared branch instead of a branch. Offer it only for an install that holds no library data of its own.

Errors

As authorize_branch.

bind_join_person

pub async fn bind_join_person(
    store: &LibraryStore,
    preferred: Option<i64>,
    redeemed: &RedeemedBranch,
) -> Option<i64>

Binds the link a sign-in join recorded to the person on this install (branch_person): only they may add store connections to the library, or withdraw them from it, through that link. Every join path calls it after redeem_branch_code.

The binding names the node this join's own enrollment minted (RedeemedBranch::node_id), so a join another one replaced meanwhile binds nothing. A failure, or no person to name, leaves the link unbound (as record_library_link stored it): nobody can use it until the branch joins again.

Arguments

  • store - This install's library.
  • preferred - The Owner who elevated into the operator session that ran the join, when one did.
  • redeemed - What the join recorded.

Returns

The user the link is bound to, when one was.

inspect_library

pub async fn inspect_library(address: &str) -> Result<InspectedLibrary, JoinError>

Reads what the library at address says about itself, under the transport policy (plain HTTP only on loopback).

  • A self_signed library must present the certificate whose pin it reports; the pin is answered for the operator to confirm.
  • Any other TLS library must present a certificate that chains to the public roots.
  • The library must name the origin it was reached at as its own (the origin its node handshake signs), so the link is recorded with an origin that works.

Errors

Returns JoinError when the address is malformed, the library is unreachable or untrusted, or its answer is malformed or names another origin.

keep_brought_connections

pub async fn keep_brought_connections(
    store: &LibraryStore,
    preferred: Option<i64>,
    bundle: &AccountBundle,
) -> Result<BroughtConnections>

Keeps the store connections a library sent with its person (RedeemedBranch::accounts) for the person on this install (branch_person), recording that they came from the library.

Arguments

  • store - This install's library.
  • preferred - The Owner who elevated into the operator session that ran the join, when one did.
  • bundle - The opened bundle.

Errors

Returns a read or write error (import_carried_accounts).

library_origin

pub fn library_origin(address: &str) -> Result<String, JoinError>

Normalizes what an operator typed (owner.example:8443, https://owner.example/) to a canonical origin. A bare host[:port] means https.

Errors

Returns JoinError::Link when it is not an http(s) origin.

redeem_branch_code

pub async fn redeem_branch_code(
    store: &LibraryStore,
    redeem: &BranchRedeem<'_>,
    keys: &LibraryLinkKeys,
) -> Result<RedeemedBranch, JoinError>

Redeems an approved sign-in: the library runs the same redeem as for a link (one node, a receipt, idempotent retries), then this install seals keys and records the link. The code and verifier go once in the request body and are never logged.

Errors

Returns JoinError when the library is unreachable or refuses; once the library has enrolled a node, a malformed answer or one for another library gives JoinError::Unsaved, which names that node so it can be revoked there, as does a link this install refuses to record. A failed database or disk write gives JoinError::SaveFailed (redeeming the same code again with the same verifier and keys gets the same node, so that one can be retried, naming that node in BranchRedeem::enrolled_node_id).

authorize_clerk

pub fn authorize_clerk(
    library: &InspectedLibrary,
    redirect_uri: &str,
    clerk_name: &str,
) -> Result<ClerkAuthorization, JoinError>

Starts a clerk sign-in at library for this install as clerk_name, coming back to redirect_uri (a loopback or https URL).

Errors

Returns JoinError::Link for a redirect URI the library would refuse or a malformed clerk name.

exchange_clerk_code

pub async fn exchange_clerk_code(
    redeem: &ClerkRedeem<'_>,
) -> Result<ExchangedCard, JoinError>

Sends a clerk sign-in's code and verifier to the library and checks the card it answers is for the library that was inspected, without recording it here (ExchangedCard::record does).

The code, the verifier and the card are registered for redaction before they could reach a log; the code and verifier go once in the request body.

Errors

Returns JoinError::Refused when the library refuses the code (spent, expired, or not this sign-in's), JoinError when it is unreachable or answers another status, and JoinError::Record when its answer is malformed or names another library.

fetch_copy_file

pub async fn fetch_copy_file(
    endpoint: &OwnerEndpoint,
    authorization: &str,
    copy_id: &str,
    index: usize,
    size: u64,
    dest: &Path,
) -> Result<(), CopyFetchError>

Downloads file index of the copy copy_id to dest.

dest must be a path only this file of this copy is written to: what it already holds is taken as the start of the file. A file already size bytes long is complete and nothing is asked; a shorter one is resumed with a Range request; a longer one is replaced. A library that ignores the range sends the whole file, which replaces what was there.

Arguments

  • authorization - The Authorization header value of the copy's downloads (crate::GrantedCopy::authorization on a branch, the copy scheme and the plain token on a clerk). Never logged.
  • size - The file's exact size, as the grant's file list states it.

Errors

Returns CopyFetchError; after Transfer, calling again resumes.

check_join_ancestry

pub async fn check_join_ancestry(
    store: &LibraryStore,
    endpoint: &OwnerEndpoint,
) -> Result<Vec<String>, JoinError>

Reads the library's info over endpoint and refuses a library whose ancestry names this install's own library id (A ← B ← A). Answers its ancestry, to record on the link.

Errors

Returns JoinError::Cycle for a cycle, and JoinError when the library cannot be read (fail closed: no join without the check).

join_library

pub async fn join_library(
    store: &LibraryStore,
    link: &str,
    software_version: &str,
) -> Result<LibraryLink, JoinError>

Enrolls this install into the library named by link.

Generates fresh node keys, redeems the link at the owner (under the transport policy and the link's SPKI pin), then seals the keys into this install's encrypted_secrets and records the library_links row. The link secret is sent once in the request body and never logged.

link is the whole link as minted (https://owner/enroll#bcn1...): the origin it names is the one this host dials and signs from then on.

Errors

Returns JoinError when the link is malformed, the owner is unreachable or refuses, or the local write fails.

refuse_cycle

pub async fn refuse_cycle(
    store: &LibraryStore,
    ancestry: &[String],
) -> Result<(), JoinError>

Refuses ancestry when it names this install's own library id, is malformed, or would take this library's ancestry past what one can name (join_overflows_ancestry).

Errors

Returns JoinError::Cycle, JoinError::AncestryTooDeep or JoinError::Record.

apply_shared_branch_bootstrap

pub fn apply_shared_branch_bootstrap(
    files_dir: &Path,
    config_file: &Path,
    bootstrap: &SharedBranchBootstrap,
    password: Option<&str>,
) -> Result<AppliedSharedBranch, JoinError>

Writes bootstrap as this install's own bootstrap under files_dir:

  • database-postgres.url (Postgres only): the URL, mode 0600;
  • node-identity.json: the node id the library recorded, bound to its library;
  • master.key: the library's DEK, wrapped with password (this install's BOOKCLERK_AUTH_PASSWORD or [auth].password) when set;
  • [database] in config_file (other settings kept): postgres with url_file naming the URL file (never the URL itself in the TOML), or d1 with its ids (the D1 API token stays this node's environment-only bootstrap).

The files go in as one recoverable step. All the new contents are first written and synced beside their targets (hidden .<name>.shared-branch-<hex> files), and each existing target is copied to <name>.pre-shared-branch; a failure up to here changes no target. The targets are then replaced atomically one by one, in the order above. If one fails, the ones already replaced are put back from their copies (a target that did not exist before is removed), so the install keeps its own bootstrap; the error names any file that could not be put back. On success the copies stay, and shared-branch-join.json in files_dir records the join: the next start drops them once the library's database opens (PendingSharedBranchJoin::confirm) and puts the originals back if it does not (PendingSharedBranchJoin::revert). The caller restarts the daemon afterwards.

A process that dies while replacing leaves the files before that point in the list new and the rest old, with every original still beside its file as <name>.pre-shared-branch and no record; a later apply refuses while a copy is there, and so does the daemon (interrupted_shared_branch_join), with instructions to finish the join by hand (when config_file is already new) or undo it. Staged .<name>.shared-branch-<hex> files left by such a crash are unused and can be deleted.

Errors

Returns JoinError::Record when a file cannot be written or the existing config.toml does not parse.

bootstrap_database_kind

pub fn bootstrap_database_kind(database: &SharedBranchDatabase) -> DatabasePluginKind

The [database].plugin a shared branch's bootstrap configures.

checked_d1_api_base

pub fn checked_d1_api_base(api_base: &str) -> Result<String, JoinError>

Checks the D1 API origin a library's bootstrap names, and returns it normalized. Every D1 query carries the joining server's own API token to that origin, so a shared branch may only be pointed at Cloudflare's API over HTTPS. The library checks its own origin the same way before it offers a shared branch join, so a library on another D1 endpoint cannot take shared branches.

Errors

Returns JoinError::Record when api_base is not an https URL on api.cloudflare.com (no other port, user name or password).

database_guest_installed

pub fn database_guest_installed(config: &Config, kind: DatabasePluginKind) -> bool

True when the database guest for kind is installed for config, so the daemon can open the library's database once the bootstrap is applied. A plugin directory that cannot be read counts as not installed.

install_problem

pub async fn install_problem(store: &LibraryStore) -> Result<Option<String>, JoinError>

Why this install may not join as a shared branch now, or None.

Errors

Returns the read error.

interrupted_shared_branch_join

pub fn interrupted_shared_branch_join(
    files_dir: &Path,
    config_file: &Path,
) -> Option<String>

Names the copies an interrupted shared branch join left beside this install's bootstrap files, or None when there are none. The daemon refuses to start while any is there: a process that died while replacing the files leaves some new and some old, and starting on that mix would pair a database with the wrong node identity or key. The message says how to finish or undo the join by hand (see apply_shared_branch_bootstrap).

pending_shared_branch_join

pub fn pending_shared_branch_join(
    files_dir: &Path,
    config_file: &Path,
) -> Option<PendingSharedBranchJoin>

The shared branch join this install applied but has not yet started on (or began undoing), if any. A record that cannot be read, or that names any file other than this install's own bootstrap files and their copies, is not used: copies left beside those files then stop the start (see interrupted_shared_branch_join).

redeem_shared_branch_code

pub async fn redeem_shared_branch_code(
    redeem: &BranchRedeem<'_>,
    keys: &LibraryLinkKeys,
) -> Result<SharedBranchJoined, JoinError>

Redeems an approved shared branch sign-in and opens the bootstrap with the node's box secret. The code and verifier go once in the request body, and are registered for redaction (the caller unregisters them).

Errors

Returns JoinError when the library is unreachable or refuses (the code was approved for a branch, the user is no longer an Owner, or its database cannot be shared). Once the library has enrolled the node, an answer for another library or type, without a bootstrap, or with one that does not open for this node gives JoinError::Unsaved naming it. JoinError::is_retryable tells which failures a repeat of the same exchange can fix (the library answers it with the same node and a freshly sealed bootstrap).

Type aliases

OwnerSocket

pub type OwnerSocket = WebSocketStream<Box<dyn OwnerIo>>;

The owner socket.

Constants

pub const AWAITING_HOST_CONSENT: &str = "awaiting_host_consent";

Release reason for a job whose plugins this host's operator has not (or no longer) approved.

KIND_NOT_RUN_HERE

pub const KIND_NOT_RUN_HERE: &str = "kind_not_run_here";

Release reason for a job of a kind this host does not run.

MAX_ARTIFACT_BYTES

pub const MAX_ARTIFACT_BYTES: usize = bookclerk_library::control_plane::MAX_ARTIFACT_BLOB_BYTES;

Largest artifact fetched from the owner (the library blob cap).

MAX_LEASE

pub const MAX_LEASE: Duration = _;

Longest lease this host counts on from one work or renewed; a longer grant is renewed as if it were this long.

SECRETS_UNOPENABLE

pub const SECRETS_UNOPENABLE: &str = "secrets_unopenable";

Error kind reported when a job's secrets do not open with this node's box key.

CONNECT_PATH

pub const CONNECT_PATH: &str = "/api/node/v1/connect";

Path of the node socket.

ENROLL_PATH

pub const ENROLL_PATH: &str = "/api/node/v1/enroll";

Path of the enroll endpoint.

MAX_UPLOAD_RESUMES

pub const MAX_UPLOAD_RESUMES: u32 = 8;

Most times one file sent in parts resumes before OwnerEndpoint::put_file gives up (a later attempt resumes again).

DATABASE_ENV_OVERRIDES

pub const DATABASE_ENV_OVERRIDES: &[&str] = _;

Environment variables that would outrank a shared branch's [database] bootstrap; a shared branch join is refused while one is set.

SHARED_BRANCH_POSTGRES_URL_FILE

pub const SHARED_BRANCH_POSTGRES_URL_FILE: &str = "database-postgres.url";

File under the files directory that holds a shared branch's Postgres URL, mode 0600. [database.postgres].url_file names it by its absolute path (a relative url_file would be read from the daemon's working directory).

Generated from crates/bookclerk-node-client at main · View as Markdown