bookclerk_node_client
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::requestfordeployments.list,instance.configandobservation), and fetches a stored archive withHostClientHandle::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). |
pub trait HeartbeatSource: Send + 'static {
fn sample(&mut self) -> NodeHeartbeat;
}
Measurements for heartbeat frames.
fn sample(&mut self) -> NodeHeartbeat
Samples this host now. May block briefly (it runs on a blocking thread).
Implemented by: NodeSampler
pub trait OwnerIo: AsyncRead + AsyncWrite + Unpin + Send {}
A byte stream to the owner, plain (loopback) or TLS.
Implemented by: T
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.
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.
An I/O error when the file cannot be opened at offset.
Implemented by: LocalFileSource
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.
fn run(
&self,
ctx: HostJobCtx,
) -> impl Future<Output = Result<String, HostJobError>> + Send
Runs one job; Ok carries the outcome text recorded as progress.
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 OAuthstate(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
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 answersJoinError::Unsavednaming that node, for its owner to revoke.
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),Nonewhen the certificate chains to the public roots or the library is on loopback.
Implements: Clone, Debug, Eq, PartialEq
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;Nonewhen the user did not choose it, had none to bring, or the box did not open (logged).
Implements: Debug
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 OAuthstate(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
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.
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.
pub fn library_id(&self) -> &str
The library the card is for.
pub async fn record(self, store: &LibraryStore) -> Result<ClerkLink, JoinError>
Seals the card into a clerk link
(bookclerk_library::control_plane::record_clerk_link).
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
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
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
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
pub struct HostClient<R: HostJobRunner> {
/* private fields */
}
The host side of the node API for one library link.
pub fn new(
config: HostClientConfig,
runner: R,
sampler: Box<dyn HeartbeatSource>,
) -> Result<(Self, HostClientHandle), DialError>
A client for config, running jobs through runner.
Returns DialError when the link's origin or pin fails the
transport policy.
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.
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 untilHostClientHandle::deployments_refreshednames 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 andSelf::max_jobs; a share that shrinks below the jobs held cancels none of them, it only stops claims until enough finish.Noneholds up toSelf::max_jobs.
pub struct HostClientHandle {
/* private fields */
}
Watches a running client.
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.
pub fn connections(&self) -> Receiver<u64>
Count of welcomed connections so far.
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.
pub fn is_connected(&self) -> bool
True while a welcomed connection is live.
pub fn held_fences(&self) -> Vec<HeldFence>
Fences this host holds and has not lost.
pub fn node_id(&self) -> &str
The node id this host has in the library.
pub fn library_id(&self) -> &str
The parent library id.
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.
pub fn consented_plugins(&self) -> BTreeSet<String>
The plugin keys consented to now.
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.
pub fn claim_scope(&self) -> ClaimScope
Whose work claims take now.
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.
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.
Returns OwnerCallError::Refused with the library's reason, or
OwnerCallError::Unavailable when no connection answered or the
bundle could not be sealed.
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.
Returns OwnerCallError::Refused when the library refuses it, or
OwnerCallError::Unavailable when no connection answers.
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.
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.
Returns SealError when it was not sealed to this node for this
instance and revision.
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.
Returns DialError when the request fails or the owner does not
answer 200 with at most MAX_ARTIFACT_BYTES.
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).
Returns OwnerCallError.
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.
Returns OwnerCallError; Lost when the fence moved on.
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.
Returns OwnerCallError; Refused when the library does not
count this node as a branch.
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.
Returns OwnerCallError.
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.
Returns OwnerCallError; Refused when the library does not
count this node as a branch.
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.
Returns OwnerCallError; Lost when the lease is no longer this
branch's.
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).
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.
Returns OwnerCallError; Refused when the library does not
count this node as a branch.
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).
None when the library answers not_found: the person cannot take
that edition, or the library holds no copy of it.
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.
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).
Returns [crate::CopyFetchError]: OtherLibrary when another
library granted copy (its token is not sent), NoSuchFile when
the grant lists no file at index.
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).
Returns OwnerCallError.
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.
Returns OwnerCallError.
pub async fn commit_catalog_upload(
&self,
upload: &HostUpload,
) -> Result<(), OwnerCallError>
Commits a catalog upload.
Returns OwnerCallError.
Implements: Clone
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
pub struct LocalFileSource(pub PathBuf);
A file on this install's disk as an UploadSource.
Implements: Clone, Debug, UploadSource
pub struct OwnerEndpoint {
/* private fields */
}
Where and how to reach one owner.
pub fn new(origin: &str, spki_pin: Option<&str>) -> Result<Self, DialError>
Checks origin (and the link's spki_pin) against the transport
policy.
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.
pub fn origin(&self) -> &str
The canonical origin the handshake signs.
pub fn is_pinned(&self) -> bool
True when the link pins the owner's certificate.
pub async fn connect(&self) -> Result<Box<dyn OwnerIo>, DialError>
Opens a byte stream to the owner under the policy.
Returns DialError when the owner is unreachable or TLS fails.
pub async fn connect_socket(&self) -> Result<OwnerSocket, DialError>
Dials the node socket, offering SUBPROTOCOL and requiring the
owner to select it.
Returns DialError when the connection or the upgrade fails.
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.
card- The library card (the token alone, without the scheme).
Returns DialError when the connection or the upgrade fails;
DialError::Refused carries the library's status (401 when the
card was ended).
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.
Returns DialError when the request cannot be made or the answer
is malformed.
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).
Returns DialError when the request cannot be made or the answer
is malformed or over the limit.
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.
Returns DialError when the request cannot be made, the answer is
malformed, or it is larger than max_body.
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.
Returns DialError when the request cannot be made, the answer is
malformed, or it is larger than max_body.
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.
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.
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).
As Self::put_stream, once the resumes run out; and
DialError::Io when source cannot be read from an offset.
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.
Returns DialError when the request cannot be made or the answer
is malformed.
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.
resume_from- Bytes of the filefilealready holds; 0 asks for the whole file.size- The file's exact size, as the grant stated it.
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).
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.
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.
Returns DialError when the request cannot be made or the answer
is malformed.
Implements: Clone, Debug
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
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; filenis atCOPIES_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.
pub fn authorization(&self) -> Result<Zeroizing<String>, OwnerCallError>
The Authorization header value of this copy's downloads.
Returns OwnerCallError::Unavailable when the token is not text.
Implements: Debug, Drop
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.
pub fn refs(&self) -> impl Iterator<Item = &SecretRef>
The rows handed with the job.
pub fn get(&self, secret_ref: &SecretRef) -> Option<&SecretValue>
The value of one handed row.
pub fn len(&self) -> usize
Number of handed rows.
pub fn is_empty(&self) -> bool
True when the job needs no secrets.
Implements: Debug
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 ishost:<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 ofplugin_keyswhose 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 atcrate::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
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.
pub fn is_cancelled(&self) -> bool
True when the runner should stop: the fence was lost or the operator cancelled the job.
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.
pub fn cancel_flag(&self) -> Arc<AtomicBool>
The cancel flag, for runners that poll it elsewhere.
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.
Returns WriteBackError when the ref was not handed, the owner
refuses, the fence is lost, or no owner connection answers.
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.
Returns OwnerCallError; Lost also cancels the job.
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.
Returns OwnerCallError; Lost also cancels the job.
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.
Returns OwnerCallError; Lost also cancels the job.
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).
Returns OwnerCallError; Lost also cancels the job.
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).
Returns OwnerCallError; Lost also cancels the job.
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.
Returns OwnerCallError; Lost (the owner aborted the upload)
also cancels the job.
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.
Returns OwnerCallError; Lost also cancels the job.
Implements: Debug
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.
pub fn new(kind: impl Into<String>, message: impl Into<String>) -> Self
A failure of kind.
Implements: Clone, Debug, Eq, PartialEq
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
pub struct AppliedSharedBranch {
pub database: DatabasePluginKind,
pub wrapped: bool,
pub config_file: PathBuf,
}
What apply_shared_branch_bootstrap wrote.
Fields
database: The[database].pluginnow configured.wrapped: True whenmaster.keyis wrapped with this install's password.config_file: The config file written.
Implements: Clone, Debug, Eq, PartialEq
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.
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.
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.
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.
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
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
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
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 (seeCarriedImport).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
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
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:401when the token ended, the branch is no longer trusted or the card is signed out (ask for a new grant),404when 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>
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>
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>
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 wholehttps://<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'serrorcode.
Record: The enroll request could not be built, or the library'sinfo(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.
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>
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
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
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.
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).
Returns JoinError::Link for a redirect URI the library would refuse
or a malformed branch name.
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.
As authorize_branch.
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.
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.
The user the link is bound to, when one was.
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_signedlibrary 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.
Returns JoinError when the address is malformed, the library is
unreachable or untrusted, or its answer is malformed or names another
origin.
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.
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.
Returns a read or write error (import_carried_accounts).
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.
Returns JoinError::Link when it is not an http(s) origin.
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.
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).
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).
Returns JoinError::Link for a redirect URI the library would refuse
or a malformed clerk name.
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.
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.
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.
authorization- TheAuthorizationheader value of the copy's downloads (crate::GrantedCopy::authorizationon 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.
Returns CopyFetchError; after Transfer, calling again resumes.
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.
Returns JoinError::Cycle for a cycle, and JoinError when the
library cannot be read (fail closed: no join without the check).
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.
Returns JoinError when the link is malformed, the owner is
unreachable or refuses, or the local write fails.
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).
Returns JoinError::Cycle, JoinError::AncestryTooDeep or
JoinError::Record.
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, mode0600;node-identity.json: the node id the library recorded, bound to its library;master.key: the library's DEK, wrapped withpassword(this install'sBOOKCLERK_AUTH_PASSWORDor[auth].password) when set;[database]inconfig_file(other settings kept):postgreswithurl_filenaming the URL file (never the URL itself in the TOML), ord1with 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.
Returns JoinError::Record when a file cannot be written or the
existing config.toml does not parse.
pub fn bootstrap_database_kind(database: &SharedBranchDatabase) -> DatabasePluginKind
The [database].plugin a shared branch's bootstrap configures.
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.
Returns JoinError::Record when api_base is not an https URL on
api.cloudflare.com (no other port, user name or password).
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.
pub async fn install_problem(store: &LibraryStore) -> Result<Option<String>, JoinError>
Why this install may not join as a shared branch now, or None.
Returns the read error.
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).
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).
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).
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).
pub type OwnerSocket = WebSocketStream<Box<dyn OwnerIo>>;
The owner socket.
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.
pub const KIND_NOT_RUN_HERE: &str = "kind_not_run_here";
Release reason for a job of a kind this host does not run.
pub const MAX_ARTIFACT_BYTES: usize = bookclerk_library::control_plane::MAX_ARTIFACT_BLOB_BYTES;
Largest artifact fetched from the owner (the library blob cap).
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.
pub const SECRETS_UNOPENABLE: &str = "secrets_unopenable";
Error kind reported when a job's secrets do not open with this node's box key.
pub const CONNECT_PATH: &str = "/api/node/v1/connect";
Path of the node socket.
pub const ENROLL_PATH: &str = "/api/node/v1/enroll";
Path of the enroll endpoint.
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).
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.
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