Entrypoints, events and the ABI
This page is the reference for the Workers RPC surface a plugin implements and the bindings it receives: entrypoint classes, events, KV namespaces, queues, and the methods of each capability.
Public types are classes and streams, not transport verbs. Chunking,
handleId, readChunk, writeChunk, finalize and abort aren't ABI
methods. Abort is a stream cancel, or RpcTarget disposal.
// Default export: triggers declared in plugin.toml.
class BookclerkEntrypoint<Env> extends WorkerEntrypoint<Env> {
describe?(): Promise<PluginDescribe>; // optional refinement
event?(batch: EventBatch): Promise<void>; // [[events.consumers]]
queue?(batch: QueueBatch): Promise<void>; // [[queues.consumers]]
job?(job: JobController): Promise<JobCompletion | void>; // [triggers] jobs
scheduled?(controller: ScheduledController): Promise<void>; // [triggers] crons
databaseMigrations?(binding: string): Promise<PluginMigration[]>; // [[databases]]
shutdown?(): Promise<void>;
}
// Named entrypoints: one exported class per `entrypoints = [...]` item.
export class Storefront extends StorefrontEntrypoint<Env> { /* login, scan, fetchTitle, … */ }
export class Storage extends StorageEntrypoint<Env> { /* head, list, get, put, copy */ }
export class RemoteLibrary extends RemoteLibraryEntrypoint<Env> { /* health, diagnose, start, stop */ }
export class DatabaseAdapter extends DatabaseAdapterEntrypoint<Env> { /* openSession */ }
export class Cli extends CliEntrypoint<Env> { /* describe, invoke */ }
export class Oidc extends OidcEntrypoint<Env> { /* clients, authenticateUser */ }
export class Metadata extends MetadataEntrypoint<Env> { /* health, lookup, search, chapters */ }
export class Covers extends CoverEntrypoint<Env> { /* health, fetchCovers */ }
export default class MyPlugin extends BookclerkEntrypoint<Env> { /* … */ }
On the wire this is
PluginWorker { describe; open(invocation, bindings) -> Entrypoints; shutdown; databaseMigrations }.
- The trusted adapter isolate resolves each
Entrypointscapability to the matching exported class, through itsPLUGIN_<ENTRYPOINT>service binding. - Before every call it merges
Bindings(config,secrets,events,databases,storage) onto the author'senv. - Authors never subclass bare
WorkerEntrypoint. The adapter-privateGRANTED,BRIDGE_TOKENandPLUGIN_DESCRIBElive only on the wrapper (AdapterEnv).
Between the launcher and the adapter isolate, every ABI method call is one
POST /invoke. Its body is the <Interface>.<method>$Params struct as
Cap'n Proto bytes, and its reply is the $Results struct. The launcher
reuses the host's typed Cap'n clients over an HTTP hook, and the isolate
decodes with the generated generated-wire.ts codecs.
- Only the control handshake (
describe,open,shutdown) is JSON. - Object bodies stream over dedicated routes.
JobControllercapabilities travel as grant-token descriptors the isolate redeems onGRANTED.
Maintainer reference: workerd bridge.
event(batch) mirrors Workers queue(batch). Each EventMessage records
one outcome, and the first call wins:
ack();retry({ retryAt | delaySeconds, reason });reject(reason);deadLetter(reason);suspend({ checkpoint, wakeAt, wakeOnEventType, wakeOnFilter }).
Untouched messages ack when the handler returns, and retry when it throws.
job(job) mirrors Workers scheduled(controller):
- Returning completes the job, optionally with
{ message, bytesCopied }. - Throwing rejects it.
unavailableanddeadline_exceededare retryable, andcancelledcancels it. job.suspend({ checkpoint, wakeAt })andjob.retryLater({ retryAt, reason })record the other terminal outcomes.job.signalis a locally createdAbortSignal, projected from the transport cancellation capability, because an AbortSignal doesn't serialize as a Workers RPC value.
JobInvocation is a versioned durable command envelope. The envelope
schema version and the payload schema version are separate.
- Idempotency keys are scoped to
(account, plugin, commandType)until a terminal fenced outcome is committed. They aren't reusable across accounts. deadlineUnixMsis a hint to the guest. The host fence and lease are authoritative, and must not be outlived.- A suspension is durable only after Bookclerk atomically commits the fenced outcome.
JobController grants input, output and progress() for one durable
invocation. Media flows through those streams. Progress, checkpoints,
completion, retry class and cancellation stay job state, not chunk
messages.
Workerd is the control-plane front door (invocation, policy, binding, lifecycle, outcome) for every plugin.
- The host always spawns
bookclerk-workerdthroughbookclerk-jail. - For
runtime = "native"it also spawns the backend as a sibling jail, and hands both children the inherited RPC and proxy links. The launcher never seesBOOKCLERK_NATIVE_BACKENDand never starts the guest itself. - Isolate, native jail and a future container are backends the host
selects from
runtime.
For a native guest, the launcher speaks typed Cap'n Proto over the
inherited RPC link. It forwards every Entrypoints family (event
consumer, job runner, storefront, storage, database adapter, remote
library, CLI, OIDC) without entering JavaScript. The adapter isolate only
decides describe (merged against PLUGIN_DESCRIBE) and the open
policy (POST /open → openInvocation), and receives shutdown.
Important
Direct host-to-native Cap'n Proto isn't a product path. It exists only
as SpawnTransport::DirectNativeDiagnostic, for tests and diagnostics.
A missing bookclerk-workerd or workerd is a hard spawn error in
every isolation mode. The OS jail is still required, and Windows
Isolation::Off still needs bookclerk-jail beside the host.
Native plugins must be rebuilt against this SDK.
- Production transport is the mux
fd:orhandle:link, andPluginSocket::into_stream. into_splitandinto_unix_streamare for Unix pathname sockets only. They return an unsupported-transport error on a mux link, and don't open a TCP socket.- The host gives each guest a fresh challenge
(
BOOKCLERK_SESSION_CHALLENGE) and reads those bytes before it serves the proxy. An unrelated child, or another session's guest, can't complete that challenge. The numeric descriptor isn't the session. - On macOS, socket and pipe creation holds a process-wide lock from
allocation through
FD_CLOEXECand through in-processCommand::spawn, because macOS has noSOCK_CLOEXEC. The SDK setsFD_CLOEXECagain when it adopts an inherited descriptor.
- List pagination is opaque and bounded. A missing or stale cursor
returns
invalid_cursor, never a silent restart at page one. Concurrent mutation is weakly consistent. Local backends don't promise a lexicographic walk over an unsorted folder without an index. - Scalar RPC values are capped at 256 KiB (
payload_too_largeif exceeded). List pages are clamped. - A SQL request or result over a negotiated
DbCapabilitiescap fails withlimit_exceeded.PluginError.details(a JSON object, empty when an error carries none) holds{ "limit", "cap", "used" }, and the message readslimit exceeded: <cap> is <n>; used <m>; the SDKs expose both aserr.limit.GuestDatabase.limitsreturns the caps of the session so a guest can stay under them; on a host that predates the method it fails withunsupported. - A result larger than one inline reply is read as a stream.
GuestDatabase.executeStreamed(and the adapter-sideAdapterDatabaseSession.executeStreamed) answer the same atomic batch asExecuteStreamFrames undermaxStreamedResultBytes/maxStreamedResultRows, which are at least the inline caps; an adapter that advertises0for both does not stream and answersunsupported. The SDKs readall()anditerate()through it when the session streams. See streamed results and Working within database limits. - Integrity metadata (etag, sha256) rides on
PutResultandReadResult. - Optional facilities within the ABI are feature flags (
rpc.streams,rpc.scalarLimits,storage.copy, and the storage intent operations), not a substitute forapiVersion.
Spawn negotiates:
apiVersion == 3;- a matching verified, provenance-qualified identity, declared
entrypointsand triggers; - the required
rpc.streamsandrpc.scalarLimits.
It rejects zero or unsafe limits. There is no kind or supportedRoles
on the wire, and describe rejects unsupported versions.
Every transport has the same observable contract.
- workerd. The isolate keeps
RpcTargetstubs.bookclerk-workerdserves Bookclerk Cap'n Proto on stdio, and talks HTTP/JSRPC to the isolate with streamed bodies (capnpConnectHost = "plugin"on the rpc socket). Author methods travel as onePOST /invokeCap'n$Paramsbody. - native, behind workerd. The guest SDK's
serveservesschema/plugin.capnp(capnp-rpc), with windowed byte streams on stdin/stdout (the inherited RPC link).bookclerk-workerdowns the other end, forwards every entrypoint family typed, and serves the host on its own stdio. CONNECT uses the inherited mux link.ExecutorIdentity.runtime_backend = "native-behind-workerd". - native, direct (diagnostic). The same guest wire, with the host
connected to the guest's stdio and no launcher in between. This is
SpawnTransport::DirectNativeDiagnosticonly (runtime_backend = "native-direct").
FD passing and localPath remain native-only optimizations behind the
stream adapter, never visible to authors.
First-party destinations (local, s3) and the remaining product guests
speak the object-capability ABI. The Echo examples are api_version = 3
guests that export cli (and optional event and job triggers), not a
kind = "integration".
| Workers concept | Bookclerk v3 |
|---|---|
export default class extends WorkerEntrypoint |
export default class extends BookclerkEntrypoint (event / queue / job / scheduled triggers) |
Named export class entrypoints |
entrypoints = ["storefront", …] + matching *Entrypoint subclass |
env.DB |
[[databases]] → granted on env |
env.KV |
[[kv_namespaces]] → get / getWithMetadata / put / delete / list with expiration, expirationTtl, and metadata |
env.SECRETS |
[secrets] → granted on env |
[[queues.producers]] / [[queues.consumers]] |
env.<BINDING>.send / sendBatch and queue(batch) with per-message ack / retry |
[[events.consumers]] |
event(batch) with ack / retry / reject / deadLetter / suspend, and env.EVENTS.read to catch up on past events |
[[events.producers]] |
env.EVENTS.publish (host outbox; forced source) |
[triggers] crons / scheduled(controller) |
[triggers] crons and scheduled(controller), five-field UTC schedules (see Scheduled triggers) |
[triggers] jobs |
job(controller) (durable command envelope) |
wrangler types |
bookclerk-plugin types → generated Env |
| Workers for Platforms / Dynamic Workers | Not used: local embedded workerd + OS jail only |
Plugins that declare [[events.producers]] publish domain events through
the EVENTS binding. It is a Bindings.events capability the host passes
to PluginWorker.open(invocation, bindings).
There is no other guest-to-host notification path. The former
HOST.notify reverse channel and its host_stub.js and NOTIFY bindings
are gone.
const ok = await env.EVENTS.publish({
eventType: "wishlist_synced", // must be a granted [[events.producers]] type
schemaVersion: 1, // defaults to 1
deduplicationKey: `wishlist:${asin}`, // optional; see below
payload: { asin, title }, // JSON, ≤ 64 KiB UTF-8 (MAX_EVENT_PAYLOAD_BYTES)
});
// ok: { eventId: string, duplicate: boolean }
The host EventPublisher writes straight into the library outbox
(domain_events), with these rules:
- Forced provenance.
sourceis always the plugin's PluginKey, andaccount_idis the opening invocation's account, so a guest can't spoof another producer.correlationIdandcausationIddefault to the invocation's values when the guest leaves them empty. - Host-emitted types. Some domain events belong to the host.
book_acquiredis one: a source plugin's acquire handler returns the book, then the host's acquire pipeline records it and publishesbook_acquiredin the same transaction as the edition's acquire state. Its payload names the title by the account holding that acquired it (titleId), its edition (editionId),source,asin,isbn,accountIdand the writtenpathKeys.edition_linked,edition_updatedandholding_addedare written by the library model resolver in the same batch as the store listing they describe,holding_removedin the batch that deletes the holding,edition_acquire_changedwith an acquire state change other than becoming acquired,ingest_batch_finishedwhen an upload or storage intake batch ends,wishlist_changedandlistening_syncedby the library after a wishlist or listening write, andplayback_started,playback_progressandplayback_finishedby the built-in player after a listening write. A plugin can consume them under[[events.consumers]], but can't declare them under[[events.producers]](checkand load fail), and the host publisher refuses them even from an older grant. - Producer grant. Publishing needs the manifest to declare
[[events.producers]]and the operator grant to cover those types (the consent request lists them). Publishing a type outside that intersection fails withforbidden. With no consented producer and no consented consumer (see Reading past events),envhas noEVENTS. - Payload cap.
payloadis UTF-8 JSON of at most 64 KiB (payload_too_largeotherwise). Non-JSON bytes areinvalid_params, and an empty payload is stored as{}. - Deduplication.
(account_id, source, event_type, deduplication_key)is a permanent unique index on the outbox. A repeat publish returns the existingeventIdwithduplicate = true, instead of inserting a second row. An emptydeduplicationKeygets a fresh UUID, so it always publishes. - Availability. Outbox write failures surface as
unavailable(retryable). The event is never half-written.
Transports. Native guests receive Bindings.events as a Cap'n Proto
capability. Under workerd:
- The trusted adapter isolate mints a per-
open, events-only grant token on the launcher'sGRANTEDchannel. - It hands the author a
GrantedEventsRpcTarget. publish()POSTs the event to/events/publish. The launcher checks the grant again (unknown, expired or database-only grants areforbidden) and enforces the payload cap, before forwarding to the host publisher.
Author isolates never see GRANTED or the grant token.
A plugin that sleeps, or that was down, can miss deliveries: they
expire after the consumer's
message_retention_period. Instead of a growing backlog, the plugin pulls
what it missed from the outbox when it next runs, the way a Workers
consumer re-reads its source after a gap.
let after = await env.KV.get("events-cursor") ?? undefined;
for (;;) {
const page = await env.EVENTS.read({ after, types: ["book_acquired"], limit: 100 });
for (const event of page.events) {
// event.deduplicationKey is the event id; dedupe on it.
}
if (page.cursor) await env.KV.put("events-cursor", page.cursor);
if (!page.more) break;
after = page.cursor;
}
The EVENTS binding exists when a consented [[events.producers]] or
[[events.consumers]] row exists. read needs a consumer; publish still
needs a producer.
- What it returns. Events, oldest first, that the plugin's consented
[[events.consumers]]rows match by type, schema version andfilter, exactly as delivery matches them.typesnarrows the read to some of those types; an empty list means all of them, and a type outside the consent isforbidden. Queue messages are never returned. - Account scope. An invocation opened for an account reads only that account's events. An invocation with no account reads every account, as its deliveries do.
- Where it starts. Pass at most one of
after(a cursor from an earlier page) andsince(aDateor Unix milliseconds;sinceUnixMsis accepted as the same field). With neither, the read starts at the oldest event the host keeps. Reads never go back further than[events].retention_days;truncatedis true when the start was older than that, so the plugin knows it may have lost events for good. - Paging.
limitdefaults to, and may not exceed,MAX_LIST_PAGE. Keep thecursorand pass it back asafterwhilemoreis true. The cursor is opaque, at most 512 bytes (MAX_EVENT_CURSOR_BYTES), and a cursor the host did not issue isinvalid_cursor. A page can hold fewer events thanlimitwithmoreset: each read scans a bounded number of outbox rows, and the cursor then marks how far it got. - The last 30 seconds wait. A read returns only events stored at least
30 seconds ago (
EVENT_STREAM_SETTLE_SECS). The host stamps an event's time before its insert commits, so a slow publication can land behind a newer one; holding the newest events back keeps a cursor from moving past an event that has not appeared yet. Newer events still arrive through delivery, and the next read picks them up. - Gap notice.
expiredEventIdslists the events in the page whose delivery to this plugin expired unhandled. - Not a delivery. A read changes no delivery state and is not
acknowledged.
deliveryAttemptis0anddeduplicationKeyis the event id, so a plugin that also receives deliveries dedupes the two on the event id.
Transports. Native guests call EventPublisher.read on the
Bindings.events capability. Under workerd, read() POSTs to
/events/read on the same grant as publish(); the launcher refuses a
body over 64 KiB or one that is not a JSON request object, then the host
checks consent and bounds.
[[kv_namespaces]] gives a plugin Workers KVNamespace-shaped storage,
which the host serves from the library database (plugin_kv). Every row
is scoped to the plugin's PluginKey and to the namespace the manifest row
names. So the values follow the instance: a sync cursor written on one
host is what the same instance reads after it moves to another.
[[kv_namespaces]] # env.KV, namespace "kv"
[[kv_namespaces]]
binding = "CURSORS" # env.CURSORS
namespace = "sync.cursors" # [a-z0-9][a-z0-9._-]*; default: binding lowercased
max_value_bytes = 4096 # default 65536, at most 1 MiB
max_keys = 500 # default 10000, at most 1000000
await env.CURSORS.put(`audible:${accountId}`, nextPageToken, {
expirationTtl: 86_400, // or `expiration` (seconds since epoch)
metadata: { scannedAt: Date.now() },
});
const cursor = await env.CURSORS.get(`audible:${accountId}`); // string | null
const { value, metadata } = await env.CURSORS.getWithMetadata(key, "json");
const listing = await env.KV.list({ prefix: "audible:", limit: 100 }); // { keys, list_complete, cursor? }
await env.KV.delete(key);
The rules:
- Scope. The guest never chooses the plugin key or namespace; both
come from the manifest row and the spawned identity. Two rows are
separate stores unless they name the same
namespace. - Consent. Declaring any row adds the
plugin_kvbinding token to the consent request. Without it, noenv.<BINDING>appears. - Limits. Keys are 1–512 UTF-8 bytes (
MAX_KV_KEY_BYTES), metadata is JSON of at most 1 KiB (MAX_KV_METADATA_BYTES), and a value is at most the row'smax_value_bytes(payload_too_largeotherwise). Aputof a new key into a namespace already holdingmax_keyslive keys fails withforbidden. Rewriting an existing key never counts against the cap. - Expiry. Expiry is lazy. An expired key reads as absent, doesn't
count against
max_keys, and is removed by the next write that needs the slot, or by the host's periodic prune. - Consistency. Reads see the latest committed write (it is a library row, not an edge cache), so there is no Workers-style 60-second propagation window.
- Transports. Native guests receive
Bindings.kv(NamedKv) as Cap'n ProtoKvNamespacecapabilities. Under workerd, the adapter isolate mints one kv-only grant token per binding, and the author'senv.<BINDING>callsPOST /kv/get|put|delete|liston the launcher'sGRANTEDchannel. Python guests get the same surface asKvNamespace(get,get_with_metadata,put,delete,list).
[queues] gives a plugin Workers-shaped queues on the host outbox.
- A
[[queues.producers]]row is anenvbinding that sends to one queue. - A
[[queues.consumers]]row delivers that queue to the default export'squeue(batch)trigger. - Queue names are
[a-z0-9][a-z0-9._-]*. Thecore.andhost.prefixes are the host's (core.eventsis the domain-event bus that[[events.*]]rows bind to). - Two plugins that name the same queue share it: one produces, the other consumes.
[[queues.producers]]
queue = "thumbnails"
binding = "THUMBNAILS" # env.THUMBNAILS
[[queues.consumers]]
queue = "thumbnails"
max_batch_size = 10 # messages per queue(batch) call (≤ 100)
max_retries = 3 # redeliveries before dead-letter
dead_letter_queue = "thumbnails-dlq"
retry_delay = 30 # seconds when retry() names no delay
message_retention_period = 3600 # seconds a due message may wait unleased (default 1 day)
// Producer: Workers `Queue`-shaped.
const { messageIds } = await env.THUMBNAILS.send({ bookId }, { delaySeconds: 5 });
await env.THUMBNAILS.sendBatch(
[{ body: "plain", contentType: "text" }, { body: bytes, contentType: "bytes" }],
{ delaySeconds: 0 },
);
// Consumer: one ordered batch from one queue, one outcome per message.
export default class MyPlugin extends BookclerkEntrypoint<Env> {
async queue(batch: QueueBatch) {
for (const msg of batch.messages) { // msg.id, msg.timestamp, msg.attempts, msg.source
try {
await handle(msg.json()); // or msg.text() / msg.body
msg.ack();
} catch {
msg.retry({ delaySeconds: 60, reason: "downstream busy" });
}
}
}
}
The rules mirror event(batch):
- Outcomes.
ack()marks the message delivered.retry()redelivers afterdelaySeconds, or after the consumer'sretry_delaywhen none is given. Untouched messages ack when the handler returns, and retry when it throws. Delivery is at-least-once, so consume idempotently onmsg.id. - Dead letters. A message still retrying after
max_retriesredeliveries is parked asdead_letter. When the consumer names adead_letter_queue, the host first copies the message there, so a second consumer (or an operator) can pick it up. - Retention. A message that is never handed to the consumer expires
after
message_retention_period(see Retention). - Bodies.
contentTypeisjson(the default; the body is JSON text),text(UTF-8) orbytes(raw). Bodies are capped at 64 KiB (MAX_EVENT_PAYLOAD_BYTES), and a batch sends at mostMAX_LIST_PAGEmessages. Sends never coalesce: everysendis a new message. - Forced provenance.
sourceis the sending plugin's PluginKey, and the account is the opening invocation's. The queue is fixed by the manifest row, never chosen per call. - Consent. Each producer binding and each consumer queue is a grant
token (
queue:<BINDING>,queue_consumer:<queue>) in the consent request. A binding the operator hasn't granted is absent fromenv, and a queue the grant doesn't cover is never delivered.describe()can't widen either list beyondplugin.toml. - Transports. Native guests receive producers on
Bindings.queuesas Cap'n Proto capabilities, and the batch onQueueConsumer.queue. Under workerd, the adapter isolate mints one queue-only grant token per binding and hands the author aGrantedQueueRpcTarget.sendandsendBatchPOST to/queues/sendon the launcher'sGRANTEDchannel, where the grant and the caps are checked again before the host producer writes the outbox.
Operators see queues with bookclerk queues list (counters and live
consumers per queue) and bookclerk queues inspect <name> (recent
messages and deliveries), backed by GET /api/queues and
GET /api/queues/{name}. Delivery rows are the same event_deliveries
that the bookclerk events verbs act on (retry, ack, cancel).
[triggers] crons runs the default export's scheduled(controller) on a
schedule, as Workers Cron Triggers do.
[triggers]
crons = ["*/30 * * * *", "0 3 * * MON-FRI"]
export default class MyPlugin extends BookclerkEntrypoint<Env> {
async scheduled(controller: ScheduledController) {
// controller.cron, controller.scheduledTime (UTC Unix ms),
// controller.fireId, controller.attempt, controller.deadlineUnixMs
await refresh(controller.scheduledTime);
}
}
Python authors define async def scheduled(self, controller) and receive a
frozen ScheduledController (cron, scheduled_time, fire_id,
attempt, deadline_unix_ms). Native guests implement
ScheduledHandler::scheduled and return it from open as
Entrypoints.scheduled_handler.
- Schedules. Each entry has five fields (minute, hour, day of month,
month, day of week) and is read in UTC. Fields take
*, values, ranges, lists and/step; months and weekdays also takeJAN–DECandSUN–SAT, and7is Sunday. When both day fields are restricted, a day matching either one fires, as in Vixie cron.L,W,#,@dailystyle macros and seconds are rejected, and so are schedules that never fire or can go nine years without firing (such as0 0 29 2 */7, February 29 on a Sunday). A manifest declares at most 8 schedules of at most 128 bytes each (MAX_CRON_BYTES). - One fire per instance. Each fire runs once per deployed plugin
instance, library-wide. Every daemon checks its schedules every 15
seconds, and a compare-and-swap on the shared
plugin_cron_cursorsrow lets exactly one node claim a fire. The claim admits a durableplugin_scheduledjob in the same batch, and the job queue routes it to a node that runs the instance (see Job kinds). - Missed fires coalesce. A library that was down through several fire
times runs one late fire for the newest of them, with that time as
scheduledTime. The same goes for an instance that was undeployed and is deployed again. A schedule seen for the first time (a new instance, or a schedule a new version adds) waits for its next fire. - Overlap. A fire that comes due while the previous fire of the same schedule is still queued or running is skipped, and the daemon logs a warning.
- Retries. Returning completes the fire. Throwing retries the same
fire (same
scheduledTimeandfireId) with backoff, up to 3 attempts, so handlers should be idempotent onfireId. - Consent. Each schedule is a grant token (
cron:<schedule>, with the schedule's whitespace normalized). A schedule the grant doesn't cover never fires, anddescribe()can't add schedules beyondplugin.toml.
Note
Fires run only on library nodes. An owned branch node (one that runs work
for a single member) doesn't claim plugin_scheduled jobs.
Some services push changes over a WebSocket instead of being polled (Audiobookshelf's Socket.io channel, for example). Holding that socket open would keep the plugin running forever, so the host holds it instead, as Durable Objects' hibernatable WebSockets do: the plugin opens a socket through its binding, the host keeps the connection while the plugin sleeps, and each real message wakes the plugin's socket handler.
[sockets] # env.SOCKETS; `binding = "PUSH"` renames it
[capabilities.network]
mode = "outbound"
tcp = ["abs.example.com:443"]
Note
The host hands out the Sockets binding to deployed integrations (the
family Audiobookshelf belongs to) whose grant has the sockets token.
Storefront and storage deployments don't get it yet. Until a plugin uses
it, it keeps its polling fallback.
Each SDK shapes the binding like Durable Objects' hibernatable WebSockets:
env.SOCKETS.connect(url, options) and getWebSockets() in TypeScript
(get_web_sockets() in Python), with messages on the default
entrypoint's webSocketMessage(ws, message) and closes on
webSocketClose(ws, code, reason, wasClean) (web_socket_message and
web_socket_close in Python). Rust plugins use the binding directly or
through bookclerk_plugin_sdk::sockets::HostWebSocket. SDK attachments
are UTF-8 JSON, so any SDK reads what another stored. See the
TypeScript,
Python and
Rust guides.
- Binding.
Sockets.connecttakes aws://orwss://URL, the subprotocols to offer, extra request headers, up to 4 heartbeat pairs and an attachment, and returns the socket's id.send,close,setAttachmentandlistact on the plugin's own sockets only. An instance holds at most 8 sockets (maxSocketsPerInstance). - Handler. A plugin that declares
[sockets]may return aSocketHandlerfromopen. The host callsmessagewith each frame and the socket's attachment, andclosedonce when the socket ends, with the close code, the reason and whether the close was clean. A plugin that returns no handler gets no pushed messages. - Poll now.
messagereplies withSocketMessageOk. SettingpollEventsasks the host to callpollEventsright away, while the plugin is awake, instead of at the next scheduled poll. A remote library sets it when a message announces a new user, so the user gets a claim ticket within seconds. The host ignores it for a plugin whose host schedules no poll. - Heartbeats. Each pair names a request frame and its reply. When an
incoming frame equals a request exactly (same kind and bytes), the host
sends the reply and doesn't wake the plugin, so a Socket.io ping
2answered with3costs no start. Frames are 1 to 256 bytes. - Attachment. Up to 2 KiB of plugin bytes stored with the socket and
handed back with every message, as
serializeAttachmentis for Durable Objects. A plugin keeps what it needs to handle a message there (an account id, a library id), since it may have restarted in between. - Checks. The host refuses, and the Rust SDK client checks before
sending, a URL with credentials, a
fragment, a percent-encoded, punycode (
xn--) or non-canonical host (127.1,0x7f.1), or a bad port; header names the broker owns (Host,Upgrade,Connection,Sec-WebSocket-*and other hop-by-hop headers); control bytes in a header value; frames over 256 KiB (maxSocketFrameBytes); and close codes a peer may not send. Header values may be credentials, so errors never repeat them. - Consent. Declaring
[sockets]adds thesocketsbinding token to the grant, and the target of every socket is checked against the network grant as any other connection is. - Broker. One broker per plugin instance holds its sockets: the
front door,
bookclerk-workerd, started in broker mode inside the plugin's jail under its effective network grant. A socket's host must be on the grant'sdomains(a WebSocket starts as an HTTP request) or have atcpentry for its port, and the broker connects only to resolved addresses the grant allows, with no redirects.wss://is checked against Mozilla's root certificates. The broker sends the host'sUser-Agent(see User-Agent) and gives up on a connection after 10 seconds, a handshake after 15, a frame write after 10 and a close after 5. - Lifetime. The host starts the broker on the plugin's first
connectand stops it once the last socket closed, so an instance with no socket runs nothing. The broker belongs to the deployment, not to the plugin process: a plugin that sleeps or restarts keeps its sockets, and a message for a sleeping plugin starts it. A message that arrives while the instance is still starting waits for it rather than being dropped. If the broker dies, each of its sockets is reported closed with 1006 and the attachment the host last saw. A change to the plugin's grant stops the broker the same way, like any other plugin process; the nextconnectstarts a broker under the new grant. Redeploying the instance starts a fresh broker, and the old one's sockets close with it. - Delivery. Messages for one socket reach the plugin in order, one
at a time. Up to 32 may wait while the plugin starts; past that the
broker stops reading the socket (heartbeats included) until the plugin
catches up, but still sends what the plugin sends on it. A socket that
ended still counts against the 8-socket limit until the plugin has
taken its last message and its close.
closedcomes after a socket's last message, with code 1009 when the server sent a message over 256 KiB, 1005 when its close frame had no code, 1006 when the connection dropped without one, and 1001 when the broker itself stopped.
Some services report changes by calling a URL (Backblaze B2's event
notifications, for example). A plugin can't listen for them itself: it
sleeps, has no address, and may run on any node. So the host takes the
request on the library's public address, checks it, stores it, and the
plugin reads it later through env.WEBHOOKS, like a pulled Workers Queue.
The manifest rows are in [[webhooks]].
const url = await env.WEBHOOKS.url("b2-events"); // null without a public address
const { messages, missed } = await env.WEBHOOKS.pull("b2-events", { batchSize: 50 });
// ...handle each message.body...
await env.WEBHOOKS.ack("b2-events", { acks: messages.map((m) => m.leaseId) });
- URL.
url(name)mints the instance's token for that row once and returns<public origin>/hooks/<token>/<name>, where the token is 43 characters of base64url (32 random bytes) and the library keeps only its SHA-256 and a sealed copy. It returns no URL unlessintegrations.public_originis anhttpsorigin on a globally reachable host (a public DNS name or global IP address, notlocalhost, a private or link-local address, or a.local-style name), andplugins.webhooksisauto. A plugin without a URL keeps its fallback, such as a listing. - Route.
POST /hooks/<token>/<name>is outside operator auth; the token is the credential. The route answers 404 for an unknown token or name, 405 for another method, 429 over the row'srate_per_minute(a token bucket per instance and webhook), 413 for a body overmax_body_bytes, 401 for a missing or wrong signature, 400 for a kept header that repeats or holds a control character, and 503 while webhooks are off, the signing secret is unset, this node runs no guest for the instance, or the instance already holds 10,000 waiting requests. A stored request gets 204. The body of a refusal says no more than its status. - Signature. An
hmac-sha256row computes HMAC-SHA256 of the raw body under the secret setting it names and compares it in constant time with the signature header (after its prefix, decoded as hex or base64). The header must appear exactly once. - Stored request. The host keeps the body as sent,
content-typeand the row'sheaders(lowercase), and when it arrived, for the row'sretention_secs. Requests are stored in the library database in chunks that fit every database profile. - Pull.
pull(name, { batchSize, visibilityTimeoutMs })leases up tobatchSize(1 to 100, default 10) waiting requests, oldest first, and hides them from other pulls for the visibility timeout (default one minute, at most 12 hours). A page also stops at 4 MiB of bodies. Each message carriesleaseId,timestamp,attempts,headersandbody(bytes).missedis true once after requests expired unread or were dropped at the cap, so the plugin resynchronizes another way. - Ack.
ack(name, { acks, retries })deletes acknowledged requests and offers retried ones to the next pull at once, up to 100 leases in each list; a lease can't be in both. A lease that ran out is offered again on its own. - Wake. A plugin may also export
webhookHandler; after a request is stored the host calls itsdelivered(name, waiting)on a running guest (webhookDeliveredin TypeScript,webhook_deliveredin Python) so it can pull at once. The host doesn't start a sleeping guest for it. A storage plugin's feed is read on the next destination sync pass, which a stored request brings forward. - Consent. Declaring any row adds the
webhookstoken to the grant. The binding is handed only to a deployed instance whose grant has it, and only for the rows its manifest declares.
Note
The route takes requests on a node that runs the instance. In a library
with several nodes, point integrations.public_origin at one that runs
the plugin; elsewhere the route answers 503 and the sender retries.
Every open carries Bindings.network, the network grant in effect, so a
plugin can tell an unapproved destination from an unreachable one and
say so. It is feedback only: the host enforces the grant whatever the
plugin does with it.
| Field | Meaning |
|---|---|
outbound |
False when the network is denied |
domains |
Fetch entries in effect (host, *.host, host:port, *), including approved setting destinations |
tcp |
Raw TCP destinations as host:port, one per port |
settings |
One row per network setting: key, network (fetch or tcp), destination, state (approved, pending, unset or invalid) and error |
TypeScript and Python read it as env.NETWORK; Rust reads
Bindings::network. No declared binding may be named NETWORK.
A connection the grant does not cover fails with network_not_granted.
details.destination names the host:port, and details.setting names
the network setting whose destination awaits approval, when one does:
- a refused
fetch()answers403with anx-bookclerk-error: network_not_grantedheader and a JSON body{"error": {"code", "message", "details"}}; - a refused
connect()or native socket fails with that code (the native socket proxy answers403with the same body); - a refused pushed socket (
env.SOCKETS.connect) rejects with the typed error.
Tell the operator to approve the destination on the plugin's consent form; don't retry until the grant changes.
The methods each capability entrypoint answers, by capability.
| Method | Purpose |
|---|---|
describe |
Identity, version, capabilities, brand (metadataJson) |
shutdown |
Graceful teardown |
health |
Connectivity and config check |
diagnose |
Human-readable CLI probe lines |
cliDescribe |
Declared CLI command schema (CliSchema) |
cliInvoke |
Run a declared command (CliInvokeParams → CliInvokeResult) |
oidcClients |
Bookclerk-as-IdP relying-party templates (OidcClientTemplate[]; empty when unused) |
Role contexts carry the instance's effective settings (schema defaults
under the document) as JSON: the same object the guest sees as
env.CONFIG.
The optional metadataJson field cli may embed the same schema as
cliDescribe. Prefer advertising capability cli and implementing both
methods.
You may also mirror the schema in plugin.toml under [cli], so
bookclerk plugins <id> --help works without spawning the plugin. At
invoke time, describe and cliDescribe remain authoritative.
Host commands that apply to every plugin stay on Bookclerk verbs
(plugins list|info|diagnose|approve|enable|disable, integrations …,
auth …). Plugin-specific commands are declared and invoked as:
bookclerk plugins <plugin-id> <command> [args…]
An example schema (JSON, metadataJson cli, or cliDescribe):
{
"commands": [
{
"name": "ping",
"about": "Probe echo plugin",
"args": [
{
"name": "message",
"long": "message",
"kind": "string",
"required": false,
"default": "hi"
}
]
}
]
}
cliInvoke params: { "command": "ping", "args": { "message": "hi" } }.
Result: { "exitCode": 0, "stdout": "…", "stderr": "…", "json": … }.
The handler family is derived from the declared entrypoints and triggers.
There is no kind = "integration".
- Remote-library guests export
remoteLibrary(and oftenoidcandcli). - Event-driven guests declare
[[events.consumers]], and implementevent(batch)on the defaultBookclerkEntrypoint.
| Surface | Notes |
|---|---|
event(batch) |
A typed DomainEvent batch (see below) |
remoteLibrary.health / diagnose |
Liveness and human-readable probe lines |
remoteLibrary.start / stop |
Background watchers |
remoteLibrary.scanLibrary |
{ force: bool } |
remoteLibrary.syncListening |
Listening progress snapshots; the host upserts them tagged with the plugin id |
remoteLibrary.pollEvents |
Observed external users. The host polls after start, and kicks off core workflows (such as claim tickets). The plugin stays unaware of the portal and tickets |
oidc.authenticateUser |
{ username, password } → external user (when oidc is exported) |
cli |
Declared under [cli] / entrypoints = ["cli"] |
event(batch) receives a typed
DomainEvent batch: eventId,
eventType, schemaVersion, correlation and causation, source,
deduplicationKey, deliveryAttempt, and a bounded payload.
- Each
EventMessagerecordsack,retry,reject,deadLetterorsuspend. - A
suspendparks a checkpoint. The next delivery copiescheckpointJson,checkpointSchemaVersion,invocationSequenceandresumePending. wakeOnEventTypeandwakeOnFilterJsonask the host to wake on a matching later event (empty means timestamp-only).- Host delivery is at-least-once, so guests must be idempotent on
deduplicationKey.
Declare durable consumers in plugin.toml. Leave them out to receive
no outbox deliveries (fail closed):
[[events.consumers]]
type = "book_acquired"
schema_versions = [1]
supports_suspend = false
# resource_class = "network" # default; the only accepted value today
# filter = { accountId = "acct" }
# max_retries = 5
# message_retention_period = 86400 # seconds; 60..=1209600, default 1 day
- Any
[[events.consumers]]row needs anevent(batch)handler on the default export. - The optional
resource_class(default"network", currently the only accepted value) is copied ontoevent_deliveries. A typo orcpuis rejected when the manifest is checked, and skipped (fail closed) at dispatch. - The optional
filteris a host-owned JSON object. The dispatcher matches payload object key equality only (no plugin-provided code or CEL). - The optional
message_retention_periodis how long, in seconds, a delivery may wait without being handed to the plugin before the host expires it (see Retention). - Echo and Audiobookshelf may leave both out (defaults).
The subscriber catalog.
- Each host heartbeats into
event_subscriber_nodesthe plugin instances its deployments run (presentorplacedon that node) and the integrations currently loaded. An instance's row is keyed by(node_id, plugin instance id), so two instances of one plugin each get their own copy of an event. A plugin without an instance is keyed by its canonical PluginKey, not the display alias. - The deployment decides whether an instance subscribes, not its process.
An instance that is deployed but not running (still starting, or failing
to spawn) keeps its enabled row, so matching events get a delivery for it
at publish time; the delivery waits as
pendinguntil the instance runs. Subscriptions are the consented[[events.consumers]]and[[queues.consumers]]rows of what the deployment would run: the active installed version and its grant, or the discovered manifest for a plugin with no library install. - The catalog key is the node id from
node-identity.json. Nodes don't delete catalog rows they lack.
A delivery does not wait forever. Like a Cloudflare Queues message, it has a retention period, so an instance that is deployed but not running stops piling up work.
- The period is the consumer's
message_retention_period(60 seconds to 14 days), or one day when the consumer names none. It never exceeds[events].retention_days. - A delivery expires when it has been due for longer than that period and
was never handed to the plugin. Its state becomes
expired, notdead_letter. A delivery that was leased, retried, suspended or is resuming does not expire;max_retriesand dead letters govern it. - Expiry is best effort. The hourly
maintenance.eventsduty expires deliveries, scanning about 10 000 rows a run and resuming where it stopped, so a delivery can outlive its period by an hour or more and can still be leased until the sweep reaches it. Retention bounds a backlog; it is not a delivery deadline, and the lease path does not check it. - A subscriber with no live catalog row (for example, while every node
that runs it is down) waits the full
[events].retention_days, since its declared period cannot be read. - Expired rows stay until
[events].retention_dayspasses, as the record of which events an instance missed. A plugin catches up after a gap withenv.EVENTS.read, which names those events inexpiredEventIds. - Deliveries for the host's own consumers (
host:and node queues) never expire. - A plugin is live when any heartbeating node (60 s TTL) has it enabled. Matching subscriptions are the union of those enabled rows.
Dispatch.
- The dispatcher
INSERT OR IGNOREs deliveries for pending events, one D1 atomic operation per(event_id, plugin_id), with receiptdispatch-{event_id}-{plugin_id}. - It also late-joins already-
dispatchedevents through a missing-pair anti-join (receiptreconcile-{event_id}-{plugin_id}). An unchanged live catalog with no missing pairs does a bounded emptySELECTand zero dispatch writes. - This node's catalog heartbeat runs before that reconcile, so a catch-up page can't starve the 60 s TTL.
- Each tick dispatches at most 32 pending outbox rows.
- A dispatch error clears the empty-reconcile skip cache. A bounded reconcile still runs at least every 60 s as a backstop.
Suspend and wake.
- After its dispatch step, each tick always runs a claimed wake slice (a UUID fence token, not the node id), even when undispatched rows remain.
- Accepting a wake clears
wake_event_type,wake_filter_jsonandwake_grants_json, so a retry isn't woken again. - A
suspendedresult is accepted only when a subscription matches that exact(type, schema_version)and setssupports_suspend = true. Otherwise it is stored as a permanent reject. - A non-empty
wakeOnEventTypemust also match a declared subscription type. - The host derives wake grants from those subscriptions:
schemaVersions, plus the intersection ofsub.filterandwakeOnFilterJson. An empty requested filter keeps the subscription filter, and can't broaden it. Waiting on an event doesn't grant a new binding. - Publish commits
wake_pendingand returns. The dispatcher claims bounded wake slices, so producer latency doesn't track the number of sleepers. - The wake page size follows the negotiated
maxBinds(100 on D1), soIN (…)and the fenced sleeper UPDATE stay under the bind cap. The UPDATE includesEXISTS (wake_pending ∧ lease owner).
book_acquired. A successful acquire writes book_acquired into
domain_events in the same transaction as the edition's acquire state
(the account holding as titleId, the edition, storage key, product ids;
never media bytes). The holding is also the event's correlation and
ordering key. It sets the envelope source to the book's storefront
plugin id.
edition_acquire_changed. Any other acquire state change of a title
(queued, downloading, failed, or reset to not acquired) writes
edition_acquire_changed (editionId, titleId, the account holding,
and status, one of not_acquired, queued, downloading or error)
in the same transaction. Its source is the book's storefront plugin id
too.
A write is recorded only while its holding still holds the edition: one read before a revoke or rescan removed the holding changes nothing and publishes no event.
ingest_batch_finished. When an upload or a
storage intake batch reaches a final state, the host writes
ingest_batch_finished (batchId; state, one of done, failed or
cancelled; source, upload or intake; intakeInstance, the storage
instance an intake batch read, else null; detail, why it failed, else
null) in the same transaction. Its source is core.import. Each file's
outcome stays with the batch: read GET /api/uploads/{id}.
Library model events. Recording a store listing publishes, in the same batch as its rows:
edition_linked(editionId,listingId) when a listing is first stored or now sells another edition (an Administrator's pin publishes it too, withedition_updatedfor the edition the listing left; each pin publishes again, even back to an edition the listing sold before);edition_updated(editionId) when the listing filled a missing subtitle, publication date or duration on its edition;edition_updated(editionId,fields: ["chapters"]) when the chapters an edition plays change: a new chapter claim from an acquire, or an Administrator's edit or pin (see Chapters);holding_added(listingId,holder,holdingId) when an account or branch library holds the listing (a title a branch shares, with holdernode:<node id>), or holds it again after it was removed;account_idis the account for an account holder and empty for a branch.
The host publishes holding_removed (listingId, holder, holdingId)
in the batch that deletes a holding: a scan no longer lists the title (see
Paged scans), the account is revoked, its id is remapped
(the holding moves, with holding_removed for the old account and
holding_added for the new one), or a branch no longer shares the title
(its full catalog pass no longer names it, it stopped sharing, or it
left).
Their source is the plugin key of the listing's store.
Each daemon's search index consumes them, with book_acquired, to keep its
node-local index current (see
Search index).
Taste events. The library publishes these after the write they describe, best effort (a failed publish is logged, and the write stands):
wishlist_changed(requestId,identityId,status) when a wishlist entry is added or changes status (openorcancelled), or an open entry is removed with its user (deleted);identityIdis the portal identity that wished, or null;listening_synced(provider,identityIds) when a listening sync changed a stored row's owner, matched book or work, authors, start, quarter or finish; itssourceis the integration that synced, andidentityIdsnames the portal identities whose rows changed. A sync that changes none of these publishes nothing;playback_started,playback_progressandplayback_finished(userId,editionId,workId,sessionId,positionMs,durationMs) from the built-in player: when someone opens a play session, when a session closes or progress is set outright (then with a nullsessionId), and when a listener reaches the end of an edition.workIdanddurationMscan be null. The position reports of a playing session publish nothing.
Discover's host consumer reads them to refresh shelves (see Discovery design).
Leasing.
An event is a fact that fans out: every subscribed instance gets its own delivery, and subscribers never compete for one. A delivery is leased, which only picks the node that runs that subscriber's copy. A job is a command with one handler, and is claimed (see Durable job queue).
- The producer's
ordering_keyis stored on the envelope, and copied verbatim onto each delivery. - Each VPS leases only deliveries for instances loaded on that process, and only events its node-local catalog matches (type, schema version, filter).
- The host evaluates catalog JSON filters, then compare-and-sets a concrete delivery id inside a generic atomic plan.
[events.concurrency](default 1) is the number of local delivery workers and the library-wide maximum ofrunningdeliveries per(plugin_id, resource_class)(networktoday). It is enforced at lease time with a portablebookclerk_slotsrow, so two VPSes can't over-admit underREAD COMMITTED.- FIFO per ordering key stays. Unrelated keys are only blocked by that cap.
Running.
- The delivery worker heartbeats the lease during
event(batch)(lease/3). - A fence loss or an operator
cancel_requestedcancels the in-flight RPC (including workerd and native). - An expired-lease reclaim restores
resume_pendingwhencheckpoint_jsonis set.
See Jobs.
Export storefront (there is no kind = "source"). The typed Cap'n
methods on ContentSource and
StorefrontEntrypoint are:
| Method | Notes |
|---|---|
login |
Password storefronts. Params include pluginDataDir, marketplace, label, email and password. Result: { account, credentials? }. The host seals the credentials (provider = plugin id) and upserts the account row |
loginStart / loginComplete |
OAuth storefronts (Audible). Start returns { sessionId, url }; complete returns the login result |
scan |
Returns one page of one account's library (see Paged scans). Params carry pluginDataDir, accountId, filters, that account's host-injected credential ({ accountId, credentials }, the credentials as opaque JSON bytes; no library database path), cursor and syncToken. The reply is a ScanPage of books[] records (see Book records); the host stores them with source forced to the plugin id |
searchCatalog |
{ query, region, limit, page, sort, field } → CatalogHit[] (see Book records). A limit of 0 means the storefront's default page of 20 hits; an empty query returns [] |
catalogDetail |
{ productId, isbn? } → { found, hit }: the full record for one product (description, narrators, runtime, genres). The host calls it only on a store that declares detailByProductId (for its own product ids) or detailByIsbn (which also answers a bare ISBN, sent in both fields) |
fetchTitle |
The host injects credentials from encrypted_secrets. The plugin writes media under the work folder and returns a PlainFetch of plain files (DRM guests decrypt before returning): mediaKind, the carrier it fetched, which must be in its declared fetches; files, each { path, role, contentType?, title?, durationMs? } with role part (ordered pieces), whole (the edition in one file, such as an M4B) or cover; chapters; chapterKind, what those markers are (chapters for the book's own chapters, tracks for track or file markers, unknown when the store does not say), which decides how the host ranks them against other chapter sources; and an optional pdfUrl. A reply lists parts or one whole file, never both, and at most one cover. The host acquires audio editions only today. When the store throttles the account, fail with rate_limited (and details.retryAfterMs when the store said how long): the host pauses automatic downloads on that account (see [acquire]). A native Rust storefront whose store reports throttling only in words can test the refusal text with bookclerk_storefront::is_throttle_reason |
purchaseHint |
Purchase link and, when withPrice is set, the live price of one title. null when the store does not sell it. lookup says how the host names the title (see Price lookups) |
purchaseHints |
The same for several titles in one call ({ queries }, one answer per query in order). The default in every SDK asks purchaseHint for each query, four at a time, those with a product id first, and stops starting lookups after 4 s, answering null for the rest, so the host's batch gets what the store managed; a store whose catalog prices many products per request (Audible's products?asins= takes fifty, Chirp's GraphQL takes aliased ids) overrides it to make one request, so a page of Discover cards costs one call per store |
qualityOffers |
{ accountId, credentials?, sourceConfig, titleIds, fetch } → { offers, refreshedCredentials? }: which stream the account would download for each title today, without downloading (see Quality offers). The host calls it only on a store that declares catalog.qualityOffers |
Each purchaseHint query carries lookup, which says how to find the
title:
lookup |
The store should |
|---|---|
product |
Answer for its own productId alone |
isbn |
Answer for that exact isbn, or null. Never a title match. Sent only to a store that declares catalog.priceByIsbn |
asin |
Answer for that exact asin, or null, as for isbn. Sent only to a store that declares catalog.priceByAsin |
title |
Search by title and authors and return every priced listing the search matched |
unspecified |
Use any field, strongest first (older hosts) |
A title search answers with records rather than a single pick: return
{ hint, records } (TypeScript PurchaseHintAnswer; a dict of the same
shape in Python; PurchaseHintResult.records in Rust) where each record
is { record, hint }, the listing's full CatalogHit and its prices.
hint stays the store's own pick for hosts that ignore records. The host
places each record in its library model by identifiers, credits and kinds,
and keeps only the recording the card is about, so a store never has to
tell a narration from a dramatisation of the same title. A bare hint is
still accepted and carries no records.
In Rust, a storefront returns records by overriding purchase_hint_result
and purchase_hints_results. A store without a bulk price endpoint calls
purchase_hint_results_one_by_one from purchase_hints_results to get the
same four-at-a-time, 4 s default as purchaseHints. The default
purchase_hint_result wraps purchase_hint and returns no records.
The host asks each store the strongest way it declared: by the store's own product when the card names one, then by exact ISBN, then by exact ASIN, then by title (see Discovery for how it evaluates the answers).
When the store answers 429, return a PluginError with code
rate_limited and, when the store sent Retry-After, details.retryAfterMs
(PluginError::rate_limited(message, retry_after) in Rust; the TS and Python
SDKs take the same shape). The host then leaves that store's price lookups
alone for the time it said, else for a minute that doubles on each repeat
up to fifteen minutes, and shows the cards without a price meanwhile. Any
other failure of a price lookup is soft: the card simply has no price.
Important
Plugins must not open library.db or read master.key. Don't put
encrypted content keys on the wire: decrypt in the guest when needed.
The host scans one account at a time and asks for its library a page at a time, so a large library never has to fit in one reply and a stopped scan picks up where it left off.
- The first call has an empty
cursor. Each later call passes back thenextCursorof the page before. A page with an emptynextCursoris the last one. - An empty
syncTokenasks for a full pass: every title the account holds. A non-empty one is a token the plugin returned at the end of an earlier pass, and asks only for what changed since then (a delta pass). - On the last page, set
syncTokento the token for the next pass (empty when the store has no change feed) andcompleteto true when the pass listed every title the account holds. A delta pass is not complete. - List titles the store reports gone in a delta pass as product ids in
removed.storePagescounts the store requests behind the page, for progress and diagnostics.
A page holds at most MAX_SCAN_PAGE_BOOKS (500) books and as many removed
ids; cursor and syncToken are at most MAX_SCAN_CURSOR_BYTES (4096)
bytes. Both are opaque to the host and never shown to anyone. The host
refuses a page that breaks a limit, returns a cursor it already returned
in the same pass, carries a book for another account or a blank product id,
and fails the scan.
The host keeps where each account stands in the account_scan_state
table:
- It saves
nextCursorafter writing each page. A scan that stops resumes from that cursor, with the token the pass started with, if the cursor is less than 24 hours old. - It stores the last page's
syncTokenand sends it on the next pass, but asks for a full pass again when no complete pass has finished in seven days. - A plugin that no longer accepts a cursor or token rejects the call with
invalid_cursor. The host forgets both and restarts once as a full pass. If the first page of a resumed pass fails for another reason, the host forgets the cursor and restarts that pass once from the beginning. If the first page of a delta pass fails for another reason, the host restarts once as a full pass and keeps the stored token until that pass replaces it. - A pass stops with an error after 10,000 pages.
A store with no change feed returns full passes with an empty syncToken;
a page number makes a fine cursor. A plugin that needs more state than one
token can keep it in its own KV namespace or, for one
row per title, its own database ([[databases]], sized with the helpers in
Database limits). The first-party Libro.fm, Chirp and
GraphicAudio plugins do the latter through the bookclerk-scan-delta
crate: they keep a fingerprint of each title the last pass listed in a
SCAN_STATE database, and a delta pass sends only new or changed titles
plus the product ids that disappeared. Without the database they return
full passes.
The host keeps the account's holdings in step with the pass:
- It removes the account's holding of each
removedproduct id. - Each page marks the account's holdings of the products it listed with the pass's id, kept with the cursor so a resumed pass marks the same id.
- When a full pass (no page was sent a token) ends
complete, the host removes the account's holdings that no page of the pass listed.
Each removal publishes holding_removed. So a plugin must set complete
only when the pass really listed every title: a complete full pass that
lists none removes every holding of the account. The flat library rows
and acquired files stay.
Each SDK has a helper that does the paging for you: scanPage in
TypeScript, scan_page in Python and in the Rust SDK. You give it a
function that fetches one page of the store's own listing, by the store's
own cursor, and it returns the reply for the call:
import { scanPage, type ScanPage, type ScanParams } from "@bookclerk/plugin-sdk/workerd";
scan(params: ScanParams): Promise<ScanPage> {
return scanPage(params, async (storeCursor) => {
const page = Number(storeCursor || "1");
const listing = await this.library(params.accountId, page);
return {
books: listing.items.map(toScanBook),
next: listing.hasMore ? String(page + 1) : "",
complete: true,
};
});
}
- The function gets an empty store cursor for the first store page, then
each
nextit returned. An emptynextmarks the last store page. - A store page may hold any number of titles and removed ids. The helper returns them 500 at a time, fetching that store page again for each slice, so the plugin keeps no state between calls.
- Set
syncTokenandcompleteon the last store page. The helper sends them only with the pass's last reply. - The helper rejects a cursor it did not write, or a slice past the end
of a store page that shrank mid-pass, with
invalid_cursor, so the host restarts the pass. A store cursor longer than about 4 KB fails withinternal.
The three SDKs write the same cursors, so a plugin can move between them without breaking a pass in progress.
The daily upgrade check
asks a store which file an account would download for titles it already
holds. A storefront takes part by setting catalog.qualityOffers in
describe() and answering qualityOffers:
- The host sends up to
maxListPageof the account's product ids intitleIds, with its credentials, the instance'ssourceConfigand thefetchoptions an acquire would use (DRM path, quality, xHE-AAC). - Answer one
TitleQualityOfferper id, in the same order. Setfoundand fillofferwith the stream'scodec,aacProfile(AAC only;unknownotherwise), and, when known,bitrateKbps,sampleRateHzandchannels. Leavefoundfalse for a title you can't answer, and offer only streams afetchTitlewith the same options would deliver. - When the store throttles the account, fail with
rate_limited; the host leaves the account alone until the next day.
The host checks the reply before comparing anything: no more answers than
titles sent, a channel count up to 32, a sample rate up to 768 kHz, a
bitrate up to 800,000 kbps, and an AAC profile only on AAC. A reply that
breaks one is refused whole. refreshedCredentials follows
Refreshed credentials. The default in every SDK
fails with unsupported; Audible is the first-party store that answers it.
A store may renew an account's tokens while the plugin uses them, such as an access token that expired in the middle of a scan. The plugin hands the renewed credentials back so the next call does not have to renew them again:
- Set
refreshedCredentialson theScanPage,PlainFetchorQualityOffersResultreply to the account's whole credentials, in the same JSON form the host sent them. Leave it empty when nothing changed. - The value must be one JSON object of at most
MAX_REFRESHED_CREDENTIAL_BYTES(64 KiB). The host refuses a scan page that breaks either rule and fails the scan. - The host keeps the renewed credentials before it writes the page's
titles, and sends them on the pass's later pages. A
PlainFetchreply that breaks the rules keeps its title; the credentials are logged and dropped.
The host stores them only while the account still has the credentials it sent the plugin. If someone signed the account in again in the meantime, that sign-in wins and the renewed credentials are dropped. On a member's computer that runs a job for a library it joined, the renewed credentials go back to that library under the job's lease instead, and are never stored on the member's computer.
The host registers the renewed values for log redaction as it receives them. A plugin should still never log them.
Discover's catalog search merges every storefront's searchCatalog hits
into one list. It never names a store; a storefront takes part in ranking
and enrichment by declaring it:
-
Rank hints. Set
rankHinton eachsearchCataloghit to the store's own 1-based rank for the requested sort, counted across pages (page 2 of 20-hit pages starts at 21), or to a store-wide popularity rank when the store has one. The relevance and popularity sorts order the merged list by the best rank any store gave a work, then put unranked works after ranked ones. Leave it0when the store's order means nothing. The Rust storefront crate'sCatalogSearchOpts::stamp_rank_hintsfills it from the page and limit. -
ISBN detail lookup. Set
catalog.detailByIsbnindescribe()whencatalogDetailresolves any audiobook ISBN to a full record. After ranking a page, the host asks those stores, insortKeyorder, to fill description, narrators, runtime and genres on lean rows from any store. A row is looked up by its ISBN, or, when the store also declaresdetailByProductIdand listed the work itself, by its own product id. The first record found fills the gaps and adds that store's edition. The lookups share a short time budget, so a slow store can't hold up a search. -
Product detail lookup. Set
catalog.detailByProductIdindescribe()whencatalogDetailresolves the product ids your own search, expand and deals hits carry to a full record. The host then asks your store to fill the lean rows it listed (as above, but by your product id only), and a title dialog asks it for the editions it listed before any ISBN store. A store that leaves it off is never woken for a detail lookup. -
Price lookup by identifier. Set
catalog.priceByIsbnandcatalog.priceByAsinindescribe()whenpurchaseHintprices an exact ISBN or ASIN (see Price lookups). The host never sends an identifier lookup a store has not declared.
All default to off. The first-party storefronts declare them as follows: Audible ranks its hits and prices exact ASINs, Libro.fm answers ISBN and product detail lookups and prices exact ISBNs, GraphicAudio answers product detail lookups, and Chirp declares none. All four answer title searches with records.
Storefronts and metadata providers must declare the media they work with,
in plugin.toml and in describe(). There is no default:
[media]
works = ["book", "podcast"] # work kinds the plugin reports
lists = ["audio"] # carriers it reports in scans, search and records
fetches = ["audio"] # carriers fetchTitle can deliver (storefronts only)
describe() returns the same lists as media: { workKinds, lists, fetches }. The host refuses to spawn a storefront or metadata provider
whose works or lists is empty or names unspecified, whose fetches
names a carrier lists does not, or whose describe() disagrees with
plugin.toml. Every other plugin leaves [media] out. Because the
declaration is in the manifest, the host can tell what a sleeping plugin
sells without starting it.
The SDKs fill media from the manifest. A TypeScript or Python plugin gets
it with the rest of the manifest projection, and a Rust plugin sets
media: manifest_media(include_str!("../plugin.toml"))? beside
manifest_capabilities.
The host then checks each record against it: a scan page with a record whose kinds are unspecified or outside the declaration is refused whole, and such catalog hits and metadata records are dropped. The first-party plugins declare:
| Plugin | works |
lists |
fetches |
|---|---|---|---|
| Audible | book, podcast |
audio |
audio |
| Libro.fm, Chirp, GraphicAudio | book |
audio |
audio |
| OpenLibrary (metadata) | book |
print |
none |
| Audnexus (metadata) | book |
audio |
none |
scan returns ScanBook records, and the catalog methods (searchCatalog,
catalogDetail, expandCandidates, listDeals) return CatalogHit
records. Both describe a title in structured fields, following the
library data model:
| Field | Meaning |
|---|---|
workKind |
book or podcast. A podcast record that sets parentProductId is an episode of that show; one without it is the show |
expressionKind |
text, narration, dramatisation, graphic (comics, graphic novels) or originalAudio (podcast episodes, lectures and other audio that reads no text). A full-cast production is a dramatisation. A translation is not a kind: set language and credit the translator |
mediaKind |
audio, ebook (any downloadable document: EPUB, PDF, CBZ) or print. Whether the host acquires an edition depends on the storefront's fetches and on what the host supports, not on this field alone |
identifiers |
{ scheme, value, marketplace? } entries. scheme is isbn (ISBN-10 or ISBN-13), asin (set marketplace), openLibraryEdition or openLibraryWork. The host trims each value, upper-cases ASINs, and turns a valid ISBN-10 into its ISBN-13 |
credits |
{ name, role, level } entries in billing order, one person or body per entry. role is author (the default), narrator, translator, editor, illustrator, publisher, host, cast or adaptor. Set level to roleDefault unless the credit sits somewhere unusual: by default authors and adaptors credit the work, narrators, translators, hosts and cast the expression, and editors, illustrators and publishers the edition |
seriesEntries |
{ name, position?, storeSeriesId? } entries, one per series the work belongs to. position is the label as the store prints it (1, 2.5, 1-3). The host removes a trailing edition marker and the word "Series" from name (King and Maxwell (abridged) and King & Maxwell Series are stored as King and Maxwell and King & Maxwell), and matches series with & read as and, so send the name as the store prints it |
parentProductId |
The show's product id, on a podcast episode. Only podcasts keep it |
language, abridgement |
Content language, and unknown (the default), unabridged or abridged |
explicitness |
Whether the store marks the edition as explicit (adult) content: unknown (the default), clean or explicit. The host keeps it on the store listing, so a patron scope can hide explicit books |
Every record names all three kinds. Each kind enum starts with
unspecified, which is what a record that forgets the field sends, and
the host refuses such a record rather than guessing. An audiobook is
book + narration + audio, a podcast episode podcast +
originalAudio + audio, and a digital comic book + graphic +
ebook.
ScanBook also carries publishedAt and purchasedAt (RFC 3339) and
categories.
Fill these from the store's own data. When a store returns a list of
names, send one credit per name; split a display string such as
"Jane Doe, John Roe" only when that is all the store gives.
Note
The host resolves each record into a listing of its work, expression and
edition. A record that is not a valid listing is stored from its flat
fields instead: names join by role, the first ISBN and ASIN fill the
identifiers, and the first series entry fills the series. An episode
with no storeSeriesId is filed under the show named by
parentProductId. Ebook and print scan records are not stored yet, and
records with an unspecified kind are never stored.
Export metadata to answer bibliographic lookups from a public catalog
(OpenLibrary, Audnexus and similar). A metadata provider only describes
what the catalog says; the host decides which library title a record
belongs to, and never lets a record name an existing row.
The typed methods on MetadataProvider and MetadataEntrypoint are:
| Method | Notes |
|---|---|
health |
Liveness and readiness |
lookup |
{ identifiers, marketplace?, limit? } → MetadataRecord[]. Look up the editions the identifiers name. Ignore schemes you don't serve, and return [] when nothing matches |
search |
{ title, author?, language?, marketplace?, limit? } → MetadataRecord[], most relevant first |
chapters |
{ identifiers, marketplace? } → MetadataChapters: found, chapters in pre-order with startMs, lengthMs? and depth (0 for top level), brandIntroMs?, brandOutroMs?, runtimeMs?, and accurate when the offsets are exact |
A MetadataRecord carries the same book record fields as
a CatalogHit (kinds, identifiers, credits, series, language,
abridgement; not explicitness, which comes from stores and files), plus description, coverUrl, url, publisher,
lengthMinutes, publishedAt, categories and an optional rating. It has
no store product id or price, because nothing is sold.
A provider that serves only some methods leaves the others to the base
class, which answers typed unsupported. Declare the catalog hosts you
call under [capabilities.network]. The guest has no other network
access, and the host never fetches on its behalf.
export class Metadata extends MetadataEntrypoint<Env> {
async lookup(params: MetadataLookupParams): Promise<MetadataRecord[]> {
const isbn = params.identifiers.find((id) => id.scheme === "isbn");
// Identifier values come from library data: check them before they
// reach a URL.
if (!isbn || !/^[0-9X-]{10,17}$/i.test(isbn.value)) return [];
const res = await fetch(`https://openlibrary.org/isbn/${encodeURIComponent(isbn.value)}.json`);
if (!res.ok) return [];
const edition = (await res.json()) as { title: string };
return [
{
title: edition.title,
abridgement: "unknown",
workKind: "book",
expressionKind: "text",
mediaKind: "print",
identifiers: [isbn],
credits: [],
seriesEntries: [],
},
];
}
}
For a complete provider, see the first-party openlibrary and audnexus
plugins under crates/bookclerk-plugins/optional/ (metadata-openlibrary
and metadata-audnexus).
The host asks every deployed provider in turn: for Audible ASIN matching
during scans, Discover title details, the acquire chapter overlay, and
bookclerk discover enrich-metadata. Lookups and searches collect records
from every provider; chapters stops at the first layout with found
set. A provider that fails is logged and skipped
(integrations).
Export covers to download cover images for the host. The host never
fetches a cover URL itself: it hands the URLs to a cover fetcher, then
checks each body's real type, decodes it with limits and re-encodes it
before it stores or serves anything.
The typed methods on CoverFetcher and CoverEntrypoint are:
| Method | Notes |
|---|---|
health |
Liveness and readiness |
fetchCovers |
({ urls, maxBytes, conditions }, sink) → CoverImage[]. Fetch each URL and put its body into sink under the key String(i), where i is the URL's index. Answer one CoverImage per URL, in request order: { url, stored, notModified, contentType?, error?, etag?, lastModified?, cacheControl?, expires?, date?, age? } |
urlsholds 1 toMAX_COVER_URLS(32) absolutehttpsURLs, andmaxBytesis at mostMAX_COVER_BYTES(10 MiB).conditionsholds the validators the host already has, by index, and may be shorter thanurls. Sendconditions[i].ifNoneMatchasIf-None-Matchandconditions[i].ifModifiedSinceasIf-Modified-Sincewhen they are set. Each value is at mostMAX_COVER_HEADER_BYTES(1024) bytes.- When the server answers
304 Not Modified, put nothing into the sink and answerstored: false, notModified: true: the host's copy is still current. - Copy the server's
ETag,Last-Modified,Cache-Control,Expires,DateandAgeinto the answer verbatim, for a200or a304. Leave out a value longer thanMAX_COVER_HEADER_BYTES; the host refuses an answer that carries one, or one that is bothstoredandnotModified. The values are advisory: the host parses them again with its own limits. sinkis a host-servedDestinationthat accepts onlyput, only for the keys0tourls.length - 1, each once. A body overmaxBytesfails thatputwithpayload_too_large; every other method isunsupported.- Answer a failed URL with
stored: falseand anerrorsuch asHTTP 404. Throw only when the whole request is malformed. - The host checks the answer: one entry per URL, the URLs as asked, and a
body for every
stored: true. Astoredanswer with no body becomes an error.
Bodies go to the sink rather than into the reply, because a reply is capped well below one image (see the workerd bridge).
export class Covers extends CoverEntrypoint<Env> {
async fetchCovers(params: CoverFetchParams, sink: Destination): Promise<CoverImage[]> {
const out: CoverImage[] = [];
for (const [i, url] of params.urls.entries()) {
const res = await fetch(url);
if (!res.ok || res.body === null) {
out.push({ url, stored: false, notModified: false, error: `HTTP ${res.status}` });
continue;
}
await sink.put(String(i), res.body);
out.push({ url, stored: true, notModified: false });
}
return out;
}
}
The first-party covers plugin (crates/bookclerk-plugins/optional/covers)
is the complete fetcher. It holds the *
any public website grant, because cover
art lives on every catalog's own CDN.
Export metadataFiles to read, and optionally write, the metadata files
that sit next to a book's audio: a metadata.json from another library
manager, an OPF, an NFO, a desc.txt. Sidecar parsing lives in plugins,
never in the host: the host finds the files, hands the bytes to the
plugin that declared the dialect, and checks what comes back.
Each dialect is a row under [metadata_files]
in plugin.toml. The row names the files it claims, the fields the
format carries and whether the plugin also writes it.
The typed methods on MetadataFiles and MetadataFilesEntrypoint are:
| Method | Notes |
|---|---|
health |
Liveness and readiness |
parse |
({ dialect, fileName, bytes }) → MetadataFileRecord. Read one file and say what it states about its edition |
render |
({ dialect, record, fields, existing, audioFiles }) → the new file's bytes (Uint8Array, or a string written as UTF-8). Set each field in fields to the record's value and keep the rest of existing as it was |
A MetadataFileRecord lists in present every field the file states,
including a field it states as empty. A field the file does not mention
stays out of present: absent means unknown, not cleared. creditRoles
does the same for credits: it names each role the file states, so a file
that lists only narrators says nothing about authors. explicitness
(unknown, clean or explicit) says whether the file marks the edition
as explicit content, as Audiobookshelf's metadata.json does with
explicit.
The host checks both directions:
dialectis one the plugin declared,fileNameis a plain file name (no path) of at most 255 bytes, andbytesis at mostMAX_METADATA_FILE_BYTES(256 KiB). A larger file is skipped rather than sent. The cap keeps the whole call inside one bridge request (see the workerd bridge).- A parsed record lists each field at most once, carries a value only for
a field in
present, and states only fields and credit roles the dialect declares. Labels are non-blank single lines of at mostMAX_METADATA_FILE_TEXT_BYTES(1024) bytes;descriptionis at mostMAX_METADATA_FILE_DESCRIPTION_BYTES(64 KiB); each list holds at mostMAX_METADATA_FILE_LIST_ENTRIES(256) entries andchaptersat mostMAX_METADATA_FILE_CHAPTERS(2000), in start order with no depth jump of more than one.publishedAtisYYYY,YYYY-MMorYYYY-MM-DD. renderis sent only to a dialect withwrites = true, only for fields the dialect carries, and the answer is at mostMAX_METADATA_FILE_BYTES.existingis empty when the host creates the file.audioFileslists the edition's audio files in playback order, each a plain file name with its running time in milliseconds (0 when unknown, never past 2^53 - 1), at mostMAX_METADATA_AUDIO_FILES(4096) of them; it is empty when the host does not know them. Chapter starts inrecordcount from the start of the first file, so a format that names its audio, such as a CUE sheet, can place each chapter in its file. An empty answer means the dialect has nothing left to write; the host decides whether to remove the file.- Throw
invalid_paramsfromparsefor a file the dialect cannot read. The host records the file as unreadable and moves on. Any reply that breaks a rule above is refused asinternal.
export class MetadataFiles extends MetadataFilesEntrypoint<Env> {
async parse(params: MetadataFileParseParams): Promise<MetadataFileRecord> {
const text = new TextDecoder("utf-8", { fatal: true }).decode(params.bytes).trim();
if (text === "") {
return { present: ["description"] };
}
return { present: ["description"], description: text };
}
async render(params: MetadataFileRenderParams): Promise<string> {
return params.record.description ?? "";
}
}
The first-party metadata_files plugin
(crates/bookclerk-plugins/optional/metadata-files) reads and writes OPF
package documents, Kodi album.nfo files and CUE sheets, and reads Libation's catalog record without writing it. A format that belongs to one tool
lives in that tool's plugin. The plugin's README lists what each record
maps to.
The host does not call the entrypoint yet beyond health probes. Finding the files, matching them to editions and writing changes back come with the metadata file sync work.
Export notifier to deliver notifications to one outside service: a
chat webhook, a mail relay, a paging service. The host decides what to
send and to whom (see the notifications ADR);
a notifier only sends one message, which the host has already rendered,
to one destination. [notifier] in
plugin.toml declares the destination
kinds, formats and personal address fields.
The typed methods on Notifier and NotifierEntrypoint are:
| Method | Notes |
|---|---|
health |
Liveness and readiness: can the service be reached with the current settings |
send |
({ message, destination }) → { providerId? }. Deliver one message; providerId is the service's id for it, when it gives one |
validateDestination |
({ addressJson }) → { addressJson, label? }. Check and normalise a personal address a patron entered; label is a short hint that is never a secret (a***@example.com). The default accepts the address as given |
A NotificationMessage carries notificationId (the same on every
destination's copy; where the service takes an idempotency key, build it
from notificationId and the destination's destinationId, so two
addresses on one service account both receive it and a retry to the same
destination reuses the same key), notificationType, severity, title, a plain text body,
optional markdown and html bodies, an optional link into the
library, labelled fields, an optional groupKey for threading, and an
alert action and key for services that open and close incidents. When
sensitive is set the body carries a secret, such as an account-mail
link: never log it. The destination is channel (its target lives in
the instance's settings, and addressJson is empty) or personal (its
addressJson is a JSON object of the declared address fields, which may
hold secrets and is never logged).
How send fails decides what happens next:
rate_limitedis retried, afterdetails.retryAfterMswhen the service said how long (capped at one hour), otherwise on the job's backoff;unavailable,deadline_exceeded(the call ran out of time) andcancelled(the host stopped it, for example on shutdown) are retried on the job's backoff;- any other error fails this destination for this message.
The host checks both directions:
- A message has a printable
notificationIdof at most 128 bytes, a type id, a non-blank one-line title of at mostMAX_NOTIFICATION_TITLE_BYTES(256),textandmarkdownof at mostMAX_NOTIFICATION_TEXT_BYTES(16 KiB),htmlof at mostMAX_NOTIFICATION_HTML_BYTES(64 KiB), at mostMAX_NOTIFICATION_FIELDS(25) fields with values of at mostMAX_NOTIFICATION_FIELD_BYTES(1 KiB), and an alert key exactly when the alert action is notnone. A link ishttps, orhttponly to a loopback host, with no credentials. - An address document is one JSON object of at most 16 keys, each
[a-z][a-z0-9_]{0,63}and given once, with one-line string values; the whole text is at mostMAX_NOTIFIER_ADDRESS_BYTES(4 KiB). AvalidateDestinationanswer that breaks these rules, or an empty address, is refused asinternal. - A provider id that is empty, longer than 1 KiB or not one line is dropped; the message still counts as delivered. An error's text is cut to one line of 512 bytes for the delivery log.
export class Notifier extends NotifierEntrypoint<Env> {
async send({ message }: NotifySendParams): Promise<NotifySent> {
const res = await fetch(this.env.CONFIG.webhook_url, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ text: `${message.title}\n${message.text}` }),
});
if (res.status === 429) {
const seconds = Number(res.headers.get("retry-after") ?? "0");
throw new PluginError("rate_limited", "service is busy", {
retryAfterMs: seconds * 1000,
});
}
if (res.status >= 500) throw new PluginError("unavailable", `HTTP ${res.status}`);
if (!res.ok) throw new PluginError("invalid_params", `HTTP ${res.status}`);
return {};
}
}
The host gives send 30 seconds and validateDestination 6 seconds;
a call that runs longer is dropped and answers unavailable, so a send
is retried.
The host calls send from one notify_send job per delivery and
records the answer in the delivery log; see
Notifications for retries and pausing.
A plugin that declares [[notifications.types]]
gets an env.NOTIFY binding with one method, raise. The host routes
each raise by the administrators' rules and each patron's preferences;
the plugin never learns where it went.
await env.NOTIFY.raise({
notificationType: "sync_failed",
fields: { Account: account.name },
linkPath: `/accounts/${account.id}`,
alertAction: "trigger",
alertKey: `sync:${account.id}`,
});
notificationTypeis a declared type id, without the plugin prefix the host adds.fieldsare{ name, value }rows or a plain object, with the caps of a message's fields.patronIdis required for apatrontype: the patron's library user id in decimal ("42", with no sign or leading zero), for a patron who holds the store account the invocation runs for.linkPathis a path inside the library (/books/42): it starts with one/and has no space or backslash. The host adds its public origin.groupKey,alertActionandalertKeyfollow the message rules.
raise answers the host's notificationId, or invalid_params for an
undeclared type or a malformed raise, forbidden for a patron outside
the scope, and rate_limited past the per-session raise budget.
Python authors call env.NOTIFY.raise_(...) with snake-case keywords.
Native guests receive the binding as Bindings.notify.
The binding is handed to the instance's entrypoint calls (not to
stream copies). A plugin may raise at most 30 notifications a minute per
session (one per store account the instance works for).
Export ingress to give the library a public https address, so patrons
and branches can reach it from outside the home network. The
[ingress] table says how: a
relay plugin carries requests from a provider such as a tunnel service,
and a direct plugin keeps an address that points at the daemon current.
The host runs at most one ingress instance at a time.
The typed methods on Ingress and IngressEntrypoint are:
| Method | Notes |
|---|---|
start |
() → { origin }. Bring the address up and answer once it serves. origin is https:// and a lowercase host name of at least two labels, with no port, path, query, user info or trailing dot or slash, at most MAX_INGRESS_ORIGIN_BYTES (253) bytes after the scheme. The top label starts with a letter, so nothing a URL parser reads as an IP address passes |
health |
() → { serving, detail }. Whether the address serves now; detail tells the operator why not |
stop |
Take the address down. The host stops relying on it once this returns |
A relay plugin hands each request its provider delivers to the library:
export class Ingress extends IngressEntrypoint<Env> {
async start(): Promise<IngressStarted> {
// Connect to the provider; for each request it delivers:
// const response = await this.env.ORIGIN.fetch(request, {
// clientAddress: providerReportedClientIp,
// });
return { origin: "https://lib.example.net" };
}
}
env.ORIGIN.fetch(request, { clientAddress }) sends the path and query of
request.url, its method, headers and body, and resolves with the
library's Response. Both bodies stream. The host checks each request
before the library sees it and refuses it with invalid_params when:
- the method is not an HTTP token of at most 32 bytes;
- the target is not a path and query (it must start with one
/, hold only visible ASCII and no#) or is longer thanMAX_ORIGIN_TARGET_BYTES(8192); - there are more than
MAX_ORIGIN_HEADERS(128) header fields, their names and values add up to more thanMAX_ORIGIN_HEADER_BYTES(64 KiB), a name is not a token, a value holds a control or non-ASCII byte, or a field describes the connection (connection,keep-alive,te,trailer,transfer-encoding,upgradeand theproxy-*fields); clientAddressis set and is not an IP address.
The TypeScript binding drops connection fields itself. host,
forwarded, x-forwarded-* and x-real-ip are dropped rather than
refused: the library answers on its own public origin, and the client
address comes only from clientAddress. Take it from the provider's own
connection metadata (such as cf-connecting-ip on a Cloudflare relay),
never from a header the client sent. Responses follow the same header
rules, so a library response never carries a connection field.
env.ORIGIN is present only on a relay plugin while it is the active
ingress, and only in the TypeScript SDK; the Python SDK serves direct
plugins.
The host runs an ingress instance only while it is the library's
active ingress (bookclerk ingress activate), an Owner exists and
operator auth is on. It calls start once the guest is healthy, health
every minute, and stop before it retires or replaces the instance.
Every ORIGIN request is the tunnel transport: the operator's own
paths and credentials are refused, and the operator's exposure choice
decides the rest (see Public address). ORIGIN
carries plain HTTP requests, not WebSocket upgrades.
Export ai to serve models: the plugin loads them, the host and other
plugins call them by name (see the model plugins ADR).
[ai].serves in plugin.toml declares the tasks.
Text embeddings (textEmbeddings) is the only task today: a model
turns each text into a vector, and texts with similar meaning get nearby
vectors.
The typed methods on AiModels and AiEntrypoint are:
| Method | Notes |
|---|---|
health |
Liveness and readiness: can the models be loaded with the current settings |
models |
() → { models }. The models served now. Must be cheap: load no model here |
run |
({ model, input }) → { output }. Run one model on one input; model is the plugin's own model id |
A listed model has a modelId ([a-z0-9][a-z0-9._-]*, at most 158
bytes), a task, a revision and, for text embeddings, dimensions
(numbers per vector, 1 to MAX_AI_EMBED_DIMENSIONS, 4096), maxTokens
and the languages it has loaded. Callers name it
@<plugin id>/<model id>.
Important
Vectors are comparable only within one revision. Change revision
whenever the weights, the tokenizer or the loaded language packs change.
The host stores it beside every vector and never compares across
revisions.
The input of a text-embedding run is textEmbeddings.texts: 1 to
MAX_AI_EMBED_TEXTS (64) texts of at most MAX_AI_EMBED_TEXT_BYTES
(16 KiB), each marked document (stored content) or query (a search
query matched against documents). The output is textEmbeddings:
dimensionsandrevision, the same as the listing;vectors: one vector per text in input order, as little-endian 32-bit floats, concatenated (packEmbeddingVectorsbuilds it);fallbacks: ascending indexes of the texts the tokenizer could not cover with the loaded languages, so the host can recompute them later.
The host treats the listing and every reply as untrusted. A listing over
MAX_AI_MODELS (64), with a repeated or malformed id, an unprintable
revision or a missing vector length is refused whole. A reply with the
wrong number of vectors, another length or revision, or a number that is
not finite fails the run as unavailable; the caller never sees a partial
result.
export class Ai extends AiEntrypoint<Env> {
async models(): Promise<AiModelList> {
return {
models: [
{
modelId: "tiny",
task: "textEmbeddings",
revision: "sha256:0123abcd",
dimensions: 384,
maxTokens: 512,
languages: ["en"],
},
],
};
}
async run({ model, input }: AiRunParams): Promise<AiRunOk> {
if (model !== "tiny") throw new PluginError("not_found", `no model ${model}`);
const vectors = input.textEmbeddings.texts.map(({ text }) => embed(text));
return {
output: {
textEmbeddings: {
dimensions: 384,
vectors: packEmbeddingVectors(vectors),
revision: "sha256:0123abcd",
fallbacks: [],
},
},
};
}
}
Note
Bookclerk's own features do not call models yet: Discover still ranks with word-hash vectors. The first-party model plugin and Discover on model vectors come next.
A plugin that lists tasks under [ai].calls gets
an env.AI binding with one method, run, shaped like the AI binding
of Cloudflare Workers. The host routes the run to the deployed plugin
that serves the model.
const out = await env.AI.run("@library/text-embeddings", {
text: ["A detective in Victorian London", "Dragons and a stolen ring"],
});
// out.shape = [2, 384]; out.data[0] is the first vector
- The model is
@<plugin id>/<model id>, or the alias@library/text-embeddingsfor the library's text-embedding model, so a caller need not know which plugin is installed. textis one text or a batch;roleisdocument(the default) orquery.- The answer has
shape,data(onenumber[]per text), the fullmodelname that ran, itsrevision, andfallbacks. Storemodelandrevisionbeside any vector you keep.
run fails with invalid_params for a malformed name or input,
forbidden for a task the plugin was not granted, not_found when no
plugin deployed on the node serves the model, rate_limited past the
budget, deadline_exceeded after 30 seconds, and unavailable when the
model plugin failed or answered wrongly. A plugin cannot call a model it
serves itself.
A plugin instance may send 240 texts a minute through AI. That is
enough to embed a search query or a handful of new items; work over a
whole library belongs to the host's jobs.
Python authors call await env.AI.run(model, text=[...], role="query").
Native guests receive the binding as Bindings.ai and send AiRunParams.
Export storage (there is no kind = "output"). Guests implement
Destination and
StorageEntrypoint: head, list (paginated), streamed get, streamed
put, optional copy, and the optional
intent operations.
- The host never reassembles a large object into
Bytes, and never writes the full object to guest scratch and thenput_file. S3 guests feed the existing multipart sink as bytes arrive. - Oversized scalar
putandgetfail closed. - There is no public
handleId/readChunk/writeChunkprotocol. Destinations transfer media throughByteSourcestreams. Range, multipart and checkpoint work in issue #120 builds on this contract, without another public ABI redesign.
Beyond the required methods, a storage guest can take over operations the
host would otherwise build from head, list, copy, get, put and
delete. The host says what it wants and the guest chooses how. Each
operation is optional: the guest declares it by accepting its feature in
rpcFeatures, and the host runs its own fallback for every operation the
guest did not declare. The fallback gives the same result when nothing else
writes the same keys at the same time, but it may be slower (a copy and a
delete instead of a rename) and it is not atomic: a concurrent writer can
slip in between its steps. Where that matters, the guest declares the
operation, or storage.conditionalWrite, and enforces it natively.
| Feature | Method | What the guest does |
|---|---|---|
storage.move |
move(from, to, options) |
Moves one object. |
storage.moveMany |
moveMany(request) |
Moves explicit pairs, or one page of every object under a prefix. |
storage.deleteMany |
deleteMany(keys) |
Removes up to maxBatchKeys (256) objects. |
storage.headMany |
headMany(keys) |
Probes up to maxBatchKeys objects. |
storage.translateKeys |
translateKeys(keys) |
Turns up to maxBatchKeys host keys into the keys it stores (Translating keys). |
storage.conditionalWrite |
put with ifMatch / ifNoneMatch |
Publishes only while the precondition holds, else fails with conflict. |
storage.changes |
changes(request) |
Returns keys changed since a cursor. |
The rules every operation follows:
- Replies say what was honoured.
MoveResult.atomicandMoveManyPage.atomicsay whether the move was a rename no reader could observe half done. Alistpage setssignaturesIncludedwhen it filled in the signature fieldsListOptions.withSignaturesasked for, andmodifiedSinceAppliedwhen it left out objects older thanListOptions.modifiedSinceMs; a guest that ignores a hint returns the unfiltered page and leaves the flag false. - Long operations are paged and safe to repeat. A prefix
moveManyreturns at mostmaxBatchKeysoutcomes and anextCursor, and repeating a page after a restart moves nothing twice. Amovewhose source is gone and whose target exists succeeds withalreadyMoved. - Batches answer per key.
moveManywith pairs anddeleteManyreturn one outcome per key, in the order sent; an outcome with an error code is that key's failure, and the rest of the batch still counts. Deleting a missing object is a success.headManyreturns one probe per key, empty for a missing object. - Options only grow.
MoveOptions,ListOptionsandWriteOptionsgain fields at new ordinals, and a zero value always means the old behaviour. - Preconditions are never dropped. A request whose
ifMatch,ifSourceMatchor cursor cannot be read is refused rather than run without it, and a granted destination (aputthrough a capability handed to another plugin) refusesifMatch/ifNoneMatchbecause that channel cannot carry them yet. - Prefix moves need disjoint prefixes. The source and target of a
prefix
moveManymay not contain each other, after.and empty path segments are dropped and\is read as/, because a nested object could overwrite one that has not moved yet.
The platform local destination declares every operation: moves are
renames, and on a local disk noOverwrite
and ifNoneMatch publish through a hard link that fails when the target
exists. ifMatch, and every condition on a network or FUSE mount, is
checked just before the rename and reported as not atomic (see
Local filesystem). Its changes
feed comes from a file-system watcher when the instance's watch setting
is on and the root is on a local disk; otherwise every page has complete
false (see Watching the folder).
The optional s3 destination declares the same set. It cannot see its
bucket's settings when it is described, so it declares them for every store.
Its changes feed drains the bucket's Amazon SQS notification queue when
the instance's notification_queue_url setting names one, and otherwise
every page has complete false (see
Following changes in the bucket).
It finds out once, on first use, which request kinds (plain upload,
multipart completion, copy, part copy, delete) enforce their conditions
(see
Moves and conditional writes).
Where every request an operation sends is enforced, conditions go to S3
with the request and the store decides them; a move is a pinned copy and a conditional delete, never
atomic. Otherwise the guest runs the host's own algorithm for that
operation and says atomic: false.
The host checks every reply against the request before acting on it: the
outcomes must name the keys it sent, in order, a prefix page may only name
keys under the prefix and must advance its cursor, and a changes page
stays within maxChangesPage (256) entries and a cursor of at most
maxChangesCursorBytes (4 KiB). A reply that breaks a rule fails the
operation with internal.
Listing entries and probes can carry a change signature: an opaque
backend-defined value (for example a local file's inode, size and times,
or an S3 ETag and version id) that stays the same while the object is
unchanged. The host uses it to skip re-reading files it already knows.
modifiedAtMs and versionId ride alongside it.
The host's own move fallback copies, probes the source again, and deletes
it only when the probe shows it is still the object it copied (same etag,
else same size and modification time); a source rewritten during the copy,
or one the probe cannot vouch for, is kept and the move fails with
conflict. Without etags the check is a heuristic: a rewrite of the same
size within the same millisecond passes it. The ABI has no delete
conditioned on an etag, so a rewrite between that probe and the delete can
still be lost too. A guest that declares storage.move avoids both gaps. With noOverwrite,
the fallback writes the target with ifNoneMatch when the guest declares
storage.conditionalWrite, and otherwise checks for the target just before
the copy (so atomic is false).
changes is a hint, not a ledger. The first call, with an empty cursor,
returns the current position and no changes. A feed drained from a queue
treats a call's cursor as the receipt for the pages up to it: their
messages are deleted then, and pages handed out after it are offered again,
so a retried cursor gets those changes once more. Such a feed has one
reader, so the host calls it from one place: the destination's sync pass,
every five minutes, on the one node holding the destination's sync lease.
It records each page before it sends that page's cursor back, and probes
(head) a changed key whose entry carries no size or signature. A page with complete false
means the guest may have missed changes since the cursor (a watcher
restarted, a queue dropped messages), and the host backs it with a full
listing. A change kind added after an SDK was built reads as changed. A scheduled listing stays the backstop either way.
liveWatch says the running guest produces the feed itself, so stopping
it would lose changes (a watcher, as opposed to a durable queue). While
the latest page has both complete and liveWatch true, the host keeps
the guest awake instead of stopping it when idle. A page without them, a
changes error, or the guest exiting lets it sleep again. The host
honours liveWatch only from the first-party storage plugins it starts on
demand, which today means the local destination with watch on (see
decision 13).
The host names every file with one host key: segments joined by /,
each non-empty, never . or .., with no \ or control characters, at
most 1024 bytes. A destination that declares storage.translateKeys
receives host keys in translateKeys(keys) and returns, in the same order,
the key it will store each one under: a path its file system accepts, or an
object key its store can hold. The host then writes, checks for and records
that key, and never passes a translated key back through translateKeys.
A destination without the feature stores each host key as written, and the
host does not wake a sleeping guest to ask. The host checks every reply: it
has one key per host key, and each key is relative, at most
4 KiB, with no control characters and no empty,
. or .. segment when split on / or \. A reply that breaks a rule
fails with internal, and the host stores host keys for that write.
Translation should be deterministic: the same host key must give the same
key on every call, because the host recomputes it to find files it wrote
earlier. The SDKs' translateKeys default returns the keys unchanged. The
local destination applies the host platform's file-name rules, and s3
the object-store rules and 1024-byte limit including its prefix (see
Keys each destination stores).
The optional r2 destination declares the same set as s3 and shares its
implementation. Its changes feed pulls the bucket's event notifications
from a Cloudflare Queue's HTTP pull consumer when the instance's
notification_queue_id setting names one, and otherwise every page has
complete false (see
Following changes in an R2 bucket).
It is an ordinary storage guest: its settings and secrets reach it in
CONFIG and SECRETS, and its network access is its declared
[capabilities.network] grant.
The optional b2 destination talks to Backblaze B2's native API. It
declares only storage.translateKeys (with the s3 key rules) besides
copies: B2 has no conditional writes, so the host checks before a
conditional write and reports it as not atomic, and moves, batch deletes
and batch probes use the host's fallbacks. It has no changes feed yet.
Its replies are read by bookclerk-storage::b2_api, a fuzzed boundary.
First-party S3 ships as bookclerk-plugin-destination-s3
(api_version = 3). Its bucket, region, endpoint, prefix, naming
overrides and credentials are [[settings]]. The host runs it wherever
its instance has a present deployment, and has no in-process S3 backend.
A second install that reuses id = "s3" is a separate PluginKey with its
own instances.
Export databaseAdapter (there is no kind = "database"). Guests are
BookclerkSQL adapters: they implement the SeaORM proxy boundary over
Workers RPC, plus a generic atomic-plan executor.
- Guests speak only canonical BookclerkSQL. Adapters lower it at execute
(
bookclerk-db-exec). - Engine connect, migrate and proxy code lives in the guest
(
bookclerk-plugin-database-sqlite, and the optional d1 and postgres guests). The host doesn't link SQL engines. - The host owns the schema, domain SQL, proofs and Bookclerk invariants (see ADR: SQL database contract). Guests must not import Bookclerk entities or embed application table names.
- The host opens the library through the external database loader (the
guest is required; there is no in-process fallback). SQLite opens
library.dbat the jail-granted path (BOOKCLERK_SQLITE_PATHorsqlitePath) when the session opens.
Important
A backend that can't advertise atomicBatch, parameterized statements,
and bind and statement limits at or above the host minimum is not
loaded (fail closed). Non-SQL engines aren't supported.
An adapter proves it keeps this contract with the adapter conformance
suite in bookclerk-db-testkit (see
A database adapter's own suite),
which every first-party adapter passes.
| Method | Notes |
|---|---|
Database.openSession |
Opens the adapter session. The guest connects its engine from DatabaseContext.config (verified first-party guests receive host-injected connect params; SQLite: path grant; D1/Postgres: host-injected credentials) |
Database.dropUnit |
Physically deletes one provisioned binding unit (unitRef is adapter-owned: a sqlite path, a postgres database, a D1 name). Missing units are success. Adapters that can't prove deletion fail closed |
AdapterDatabaseSession.capabilities |
A typed control-plane call after openSession. Advertises the SQL contract version, execution semantics, schemaMigrations, backup flags and all limits. Host policy requires schemaMigrations. Diagnostic engine identity isn't a capability. The host must not invent these from the plugin id |
AdapterDatabaseSession.bootstrap |
The diagnostic engine name only (engine). Not part of DbCapabilities, and never used to admit a guest or generate SQL. Any string is valid |
AdapterDatabaseSession.execute |
The one typed atomic operation (AdapterExecuteRequest → ExecuteReply). The request is already-desugared canonical Bookclerk SQL (? placeholders) plus 1:1 hash-bound proofs. Adapters lower at execute. Guests don't interpret Bookclerk operation names. job(job) does not receive the host library on env: plugins that need durable SQL declare [[databases]] bindings, and receive physically separate units on env.<BINDING> |
AdapterDatabaseSession.executeStreamed |
The same atomic batch as execute, answered as ExecuteStreamFrames (ExecuteStreamReply: inline bytes, a ByteSource, or err) so the result may grow to maxStreamedResultBytes / maxStreamedResultRows. The batch commits before the first frame. Adapters that do not stream advertise 0 for both caps and answer unsupported |
AdapterDatabaseSession.close |
Releases the session and its engine connection |
Some methods are host-private: never visible to plugin authors, and only
in first-party guests built with the abi host feature.
HostAdapterDatabaseSession.beginopens a native interactive SeaORM transaction and returns anAdapterTransaction(execute,commit,rollback).- The host records a sticky per-task fault when
beginfails, so later statements can't fall back to autocommit. A failedcommitis surfaced toLibraryStore(SeaORM's proxy hook is infallible). AdapterDatabaseSession.executeandHostAdapterDatabaseSession.executecarry the sameAdapterExecuteRequest(canonical SQL, structured proofs, an optional receipt-persist hint).- D1 keeps
beginunsupported, and routes hostexecutethrough its native batch proxy.
The built-in ids are sqlite, d1 and postgres (matching
[database].plugin).
Plugins may declare Workers-style named database bindings in the manifest:
[[databases]]
binding = "DB"
[[databases]]
binding = "CACHE" # [A-Z][A-Z0-9_]*, unique, max 8
SQL bindings don't replace [[kv_namespaces]]. Named bindings are
plugin-private state, not a place to put host tables. The durable job
queue, library catalog and secrets stay in the host library database, and
job(job) never gets an env binding pointed at library.db.
The active adapter provisions bindings, physically separate from the Bookclerk library and from every other plugin (close to a Cloudflare Workers D1 binding):
- SQLite: one file per binding, under
$BOOKCLERK_FILES_DIR/plugin-databases/<plugin-key-fs-id>/<BINDING>.db(the sqlite adapter jail grants that folder). The leaf isPluginKey::fs_id()(pk-plus 32 hex, 128 bits), not the display alias and not the canonical PluginKey (which isn't a valid Windows path component). Theplugin_databasesregistry still stores the canonical PluginKey. - PostgreSQL: one database per binding (
pb_plus 32 hex of the(plugin, binding)digest; 35 ≤ 63 characters), created on first use (CREATEDBrequired). This is a separate database, not a schema on the library database, so plugin SQL can't see host tables. - Cloudflare D1: one D1 database per binding (
bookclerk-pb-plus the same 32 hex), found or created by name through the REST API. Provisioning fails closed with an operator-facing error when the API token can't create databases. - Third-party adapters: advertise
DbCapabilities.pluginDatabasesand the backup flags they can actually provide (consistentBackupRead,atomicUnitRestore). The host opens plugin bindings through the active adapter session (DatabaseAdapterConfig+provision), and doesn't switch on sqlite, postgres or d1 crates. Adapters that don't advertise support fail the job, rather than sharing a database.
Consent. Each binding appears as a database:<NAME> grant entry, and
needs operator approval before enable, like other capabilities.
Registry. Provisioned units are recorded in the host
plugin_databases registry. An existing row wins, so re-opens never
re-target a binding.
Operators inspect and remove them with
bookclerk plugins db list and
bookclerk plugins db drop <plugin> [binding]. The drop command calls the
adapter's Database.dropUnit, then removes the registry row, and fails
closed if a physical delete can't be proven.
Inside a binding the plugin owns its schema. It registers a complete,
ordered history at startup (databaseMigrations(binding)): opaque IDs the
plugin chooses, plus already-separated BookclerkSQL schema and data
operations. Bookclerk gives those IDs no version meaning; registration
order is the forward sequence.
Registration is a bounded startup scalar:
- at most
maxListPagemigrations; maxPluginMigrationOpsoperations per migration;maxPluginMigrationTotalOpsoperations across the registration;- each SQL at most
maxScalarBytes; - aggregate id and SQL UTF-8 at most
maxPluginMigrationRegistrationBytes.
The host then:
- Proves the sequence with one evolving type environment.
- Checks that the durable
bookclerk_plugin_migrationshistory is an exact prefix of the registration. - Applies only the pending suffix, one atomic receipt per registered migration (slot lock, operations, journal append).
Ordinary binding execute is query and DML only. Durable CREATE and
DROP are admitted only while the host applies that registration.
ALTER and CREATE TABLE AS stay refused.
Mixed guest CREATE plus INSERT isn't a product path: register and
apply, then DML. A same-token DML replay must not insert twice.
Inside a binding, the host reserves exactly one identifier prefix,
bookclerk_. All of its bookkeeping carries it:
bookclerk_schema_migrations, bookclerk_plugin_migrations,
bookclerk_receipts, bookclerk_slots, the bookclerk_sql_* catalog,
and the bookclerk_src wrap alias.
- Engine catalogs (
sqlite_*,pg_*,information_schema) and schema-qualified names are reserved too. REFERENCEStargets use the same reserved-name rules asCREATEandDROP.- Any other name, including a framework's own
schema_migrations, is the plugin's. - The binding's own
bookclerk_receiptsandbookclerk_plugin_migrationstables stay host-owned, so retry tokens replay inside the binding and plugins can't edit the journal.
The guest grammar still applies: a single statement, no ATTACH,
PRAGMA or session verbs, and no schema-qualified names. It is Bookclerk
SQL v1, not a wider SQLite dialect:
- Functions are the portable helpers, and
hexis denied. - Column types are
INTEGER,REAL,TEXT,BLOBandBOOLEAN. INSERT OR IGNOREis for unique or primary-key conflicts only, and is lowered toON CONFLICT DO NOTHINGon every backend, including SQLite and D1.SELECTandWITHsources are wrapped asSELECT * FROM (<source>) AS bookclerk_src WHERE true.- Helper arity and wire types are enforced, so callers needn't
CASTforround,sum,avgorcount. - Canonical
LIKEis case-sensitive (GLOBlowering on SQLite and D1,COLLATE "C"on Postgres).
Schema metadata is durable in the adapter-private
bookclerk_sql_catalog, bookclerk_sql_schema and bookclerk_sql_ddl
tables (Postgres identity is in bookclerk_identity). All are
guest-denied.
- Opening a binding reloads types from that catalog.
- A matching no-op
CREATE TABLE IF NOT EXISTSdoesn't rewrite the catalog or identity. The first admitted CREATE must persist complete canonical DDL, and a binding missing that catalog fails closed (reset or recreate it).
See the SQL contract v1.
PluginWorker.open receives the bindings as the append-only
Bindings.databases :List(NamedDatabase) field.
- Rust guests call
DatabaseBinding::take_named_from_bindings(&mut bindings, "DB"). - For workerd guests, the launcher mints one database-only grant token per
binding at
open, and carries it in the bridge context (databases: { DB: <token> }). The trusted adapter isolate turns each token into a granted-channel transport overPOST /db/execute(withGET /db/limitsforlimits(); the launcher also servesPOST /db/execute-streamed, the streamed read the SDK helpers adopt next, see the SQL contract), and installs the resultingenv.DBon the author'senvfor every call of thatopen(events, storefront, jobs, …). It is a fullDatabaseBinding:prepare,bind,run,all,first,raw,batchandlimits().
Authors never see the token.
- plugin.toml: declare entrypoints, triggers and bindings.
- Capabilities and consent: what each binding needs approved.
- Jobs: the durable queue behind jobs and event deliveries.
Source: docs/plugins/abi.md at main · View as Markdown