Entrypoints, events and the ABI

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

Last updated View as Markdown

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.

ABI (api_version = 3, object-capability Workers RPC)

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

On the wire this is PluginWorker { describe; open(invocation, bindings) -> Entrypoints; shutdown; databaseMigrations }.

  • The trusted adapter isolate resolves each Entrypoints capability to the matching exported class, through its PLUGIN_<ENTRYPOINT> service binding.
  • Before every call it merges Bindings (config, secrets, events, databases, storage) onto the author's env.
  • Authors never subclass bare WorkerEntrypoint. The adapter-private GRANTED, BRIDGE_TOKEN and PLUGIN_DESCRIBE live 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.
  • JobController capabilities travel as grant-token descriptors the isolate redeems on GRANTED.

Maintainer reference: workerd bridge.

Events and jobs

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. unavailable and deadline_exceeded are retryable, and cancelled cancels it.
  • job.suspend({ checkpoint, wakeAt }) and job.retryLater({ retryAt, reason }) record the other terminal outcomes.
  • job.signal is a locally created AbortSignal, 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.
  • deadlineUnixMs is 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 front door

Workerd is the control-plane front door (invocation, policy, binding, lifecycle, outcome) for every plugin.

  • The host always spawns bookclerk-workerd through bookclerk-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 sees BOOKCLERK_NATIVE_BACKEND and 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 sockets

Native plugins must be rebuilt against this SDK.

  • Production transport is the mux fd: or handle: link, and PluginSocket::into_stream.
  • into_split and into_unix_stream are 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_CLOEXEC and through in-process Command::spawn, because macOS has no SOCK_CLOEXEC. The SDK sets FD_CLOEXEC again when it adopts an inherited descriptor.

Limits and negotiation

  • 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_large if exceeded). List pages are clamped.
  • A SQL request or result over a negotiated DbCapabilities cap fails with limit_exceeded. PluginError.details (a JSON object, empty when an error carries none) holds { "limit", "cap", "used" }, and the message reads limit exceeded: <cap> is <n>; used <m>; the SDKs expose both as err.limit. GuestDatabase.limits returns the caps of the session so a guest can stay under them; on a host that predates the method it fails with unsupported.
  • A result larger than one inline reply is read as a stream. GuestDatabase.executeStreamed (and the adapter-side AdapterDatabaseSession.executeStreamed) answer the same atomic batch as ExecuteStreamFrames under maxStreamedResultBytes / maxStreamedResultRows, which are at least the inline caps; an adapter that advertises 0 for both does not stream and answers unsupported. The SDKs read all() and iterate() through it when the session streams. See streamed results and Working within database limits.
  • Integrity metadata (etag, sha256) rides on PutResult and ReadResult.
  • Optional facilities within the ABI are feature flags (rpc.streams, rpc.scalarLimits, storage.copy, and the storage intent operations), not a substitute for apiVersion.

Spawn negotiates:

  • apiVersion == 3;
  • a matching verified, provenance-qualified identity, declared entrypoints and triggers;
  • the required rpc.streams and rpc.scalarLimits.

It rejects zero or unsafe limits. There is no kind or supportedRoles on the wire, and describe rejects unsupported versions.

Transports

Every transport has the same observable contract.

  • workerd. The isolate keeps RpcTarget stubs. bookclerk-workerd serves 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 one POST /invoke Cap'n $Params body.
  • native, behind workerd. The guest SDK's serve serves schema/plugin.capnp (capnp-rpc), with windowed byte streams on stdin/stdout (the inherited RPC link). bookclerk-workerd owns 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::DirectNativeDiagnostic only (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".

Coming from Cloudflare Workers

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

Publishing events (env.EVENTS)

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. source is always the plugin's PluginKey, and account_id is the opening invocation's account, so a guest can't spoof another producer. correlationId and causationId default to the invocation's values when the guest leaves them empty.
  • Host-emitted types. Some domain events belong to the host. book_acquired is one: a source plugin's acquire handler returns the book, then the host's acquire pipeline records it and publishes book_acquired in 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, accountId and the written pathKeys. edition_linked, edition_updated and holding_added are written by the library model resolver in the same batch as the store listing they describe, holding_removed in the batch that deletes the holding, edition_acquire_changed with an acquire state change other than becoming acquired, ingest_batch_finished when an upload or storage intake batch ends, wishlist_changed and listening_synced by the library after a wishlist or listening write, and playback_started, playback_progress and playback_finished by the built-in player after a listening write. A plugin can consume them under [[events.consumers]], but can't declare them under [[events.producers]] (check and 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 with forbidden. With no consented producer and no consented consumer (see Reading past events), env has no EVENTS.
  • Payload cap. payload is UTF-8 JSON of at most 64 KiB (payload_too_large otherwise). Non-JSON bytes are invalid_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 existing eventId with duplicate = true, instead of inserting a second row. An empty deduplicationKey gets 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:

  1. The trusted adapter isolate mints a per-open, events-only grant token on the launcher's GRANTED channel.
  2. It hands the author a GrantedEvents RpcTarget.
  3. publish() POSTs the event to /events/publish. The launcher checks the grant again (unknown, expired or database-only grants are forbidden) and enforces the payload cap, before forwarding to the host publisher.

Author isolates never see GRANTED or the grant token.

Reading past events (env.EVENTS.read)

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 and filter, exactly as delivery matches them. types narrows the read to some of those types; an empty list means all of them, and a type outside the consent is forbidden. 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) and since (a Date or Unix milliseconds; sinceUnixMs is 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; truncated is true when the start was older than that, so the plugin knows it may have lost events for good.
  • Paging. limit defaults to, and may not exceed, MAX_LIST_PAGE. Keep the cursor and pass it back as after while more is true. The cursor is opaque, at most 512 bytes (MAX_EVENT_CURSOR_BYTES), and a cursor the host did not issue is invalid_cursor. A page can hold fewer events than limit with more set: 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. expiredEventIds lists 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. deliveryAttempt is 0 and deduplicationKey is 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

[[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_kv binding token to the consent request. Without it, no env.<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's max_value_bytes (payload_too_large otherwise). A put of a new key into a namespace already holding max_keys live keys fails with forbidden. 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 Proto KvNamespace capabilities. Under workerd, the adapter isolate mints one kv-only grant token per binding, and the author's env.<BINDING> calls POST /kv/get|put|delete|list on the launcher's GRANTED channel. Python guests get the same surface as KvNamespace (get, get_with_metadata, put, delete, list).

Queues

[queues] gives a plugin Workers-shaped queues on the host outbox.

  • A [[queues.producers]] row is an env binding that sends to one queue.
  • A [[queues.consumers]] row delivers that queue to the default export's queue(batch) trigger.
  • Queue names are [a-z0-9][a-z0-9._-]*. The core. and host. prefixes are the host's (core.events is 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 after delaySeconds, or after the consumer's retry_delay when none is given. Untouched messages ack when the handler returns, and retry when it throws. Delivery is at-least-once, so consume idempotently on msg.id.
  • Dead letters. A message still retrying after max_retries redeliveries is parked as dead_letter. When the consumer names a dead_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. contentType is json (the default; the body is JSON text), text (UTF-8) or bytes (raw). Bodies are capped at 64 KiB (MAX_EVENT_PAYLOAD_BYTES), and a batch sends at most MAX_LIST_PAGE messages. Sends never coalesce: every send is a new message.
  • Forced provenance. source is 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 from env, and a queue the grant doesn't cover is never delivered. describe() can't widen either list beyond plugin.toml.
  • Transports. Native guests receive producers on Bindings.queues as Cap'n Proto capabilities, and the batch on QueueConsumer.queue. Under workerd, the adapter isolate mints one queue-only grant token per binding and hands the author a GrantedQueue RpcTarget. send and sendBatch POST to /queues/send on the launcher's GRANTED channel, 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).

Scheduled triggers

[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 take JAN–DEC and SUN–SAT, and 7 is Sunday. When both day fields are restricted, a day matching either one fires, as in Vixie cron. L, W, #, @daily style macros and seconds are rejected, and so are schedules that never fire or can go nine years without firing (such as 0 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_cursors row lets exactly one node claim a fire. The claim admits a durable plugin_scheduled job 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 scheduledTime and fireId) with backoff, up to 3 attempts, so handlers should be idempotent on fireId.
  • Consent. Each schedule is a grant token (cron:<schedule>, with the schedule's whitespace normalized). A schedule the grant doesn't cover never fires, and describe() can't add schedules beyond plugin.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.

Pushed sockets ([sockets])

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.connect takes a ws:// or wss:// URL, the subprotocols to offer, extra request headers, up to 4 heartbeat pairs and an attachment, and returns the socket's id. send, close, setAttachment and list act on the plugin's own sockets only. An instance holds at most 8 sockets (maxSocketsPerInstance).
  • Handler. A plugin that declares [sockets] may return a SocketHandler from open. The host calls message with each frame and the socket's attachment, and closed once 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. message replies with SocketMessageOk. Setting pollEvents asks the host to call pollEvents right 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 2 answered with 3 costs 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 serializeAttachment is 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 the sockets binding 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's domains (a WebSocket starts as an HTTP request) or have a tcp entry 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's User-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 connect and 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 next connect starts 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. closed comes 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.

Inbound webhooks ([[webhooks]])

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 unless integrations.public_origin is an https origin on a globally reachable host (a public DNS name or global IP address, not localhost, a private or link-local address, or a .local-style name), and plugins.webhooks is auto. 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's rate_per_minute (a token bucket per instance and webhook), 413 for a body over max_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-sha256 row 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-type and the row's headers (lowercase), and when it arrived, for the row's retention_secs. Requests are stored in the library database in chunks that fit every database profile.
  • Pull. pull(name, { batchSize, visibilityTimeoutMs }) leases up to batchSize (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 carries leaseId, timestamp, attempts, headers and body (bytes). missed is 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 its delivered(name, waiting) on a running guest (webhookDelivered in TypeScript, webhook_delivered in 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 webhooks token 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.

Network grant (env.NETWORK)

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() answers 403 with an x-bookclerk-error: network_not_granted header and a JSON body {"error": {"code", "message", "details"}};
  • a refused connect() or native socket fails with that code (the native socket proxy answers 403 with 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.

Entrypoint methods

The methods each capability entrypoint answers, by capability.

Common

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.

Plugin CLI

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": … }.

Integration and remote-library capabilities

The handler family is derived from the declared entrypoints and triggers. There is no kind = "integration".

  • Remote-library guests export remoteLibrary (and often oidc and cli).
  • Event-driven guests declare [[events.consumers]], and implement event(batch) on the default BookclerkEntrypoint.
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 EventMessage records ack, retry, reject, deadLetter or suspend.
  • A suspend parks a checkpoint. The next delivery copies checkpointJson, checkpointSchemaVersion, invocationSequence and resumePending.
  • wakeOnEventType and wakeOnFilterJson ask 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.

Event consumers

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 an event(batch) handler on the default export.
  • The optional resource_class (default "network", currently the only accepted value) is copied onto event_deliveries. A typo or cpu is rejected when the manifest is checked, and skipped (fail closed) at dispatch.
  • The optional filter is a host-owned JSON object. The dispatcher matches payload object key equality only (no plugin-provided code or CEL).
  • The optional message_retention_period is 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).

How events are delivered

The subscriber catalog.

  • Each host heartbeats into event_subscriber_nodes the plugin instances its deployments run (present or placed on 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 pending until 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.

Retention of undelivered events

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, not dead_letter. A delivery that was leased, retried, suspended or is resuming does not expire; max_retries and dead letters govern it.
  • Expiry is best effort. The hourly maintenance.events duty 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_days passes, as the record of which events an instance missed. A plugin catches up after a gap with env.EVENTS.read, which names those events in expiredEventIds.
  • 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 receipt dispatch-{event_id}-{plugin_id}.
  • It also late-joins already-dispatched events through a missing-pair anti-join (receipt reconcile-{event_id}-{plugin_id}). An unchanged live catalog with no missing pairs does a bounded empty SELECT and 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_json and wake_grants_json, so a retry isn't woken again.
  • A suspended result is accepted only when a subscription matches that exact (type, schema_version) and sets supports_suspend = true. Otherwise it is stored as a permanent reject.
  • A non-empty wakeOnEventType must also match a declared subscription type.
  • The host derives wake grants from those subscriptions: schemaVersions, plus the intersection of sub.filter and wakeOnFilterJson. 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_pending and 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), so IN (…) and the fenced sleeper UPDATE stay under the bind cap. The UPDATE includes EXISTS (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, with edition_updated for 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 holder node:<node id>), or holds it again after it was removed; account_id is 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 (open or cancelled), or an open entry is removed with its user (deleted); identityId is 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; its source is the integration that synced, and identityIds names the portal identities whose rows changed. A sync that changes none of these publishes nothing;
  • playback_started, playback_progress and playback_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 null sessionId), and when a listener reaches the end of an edition. workId and durationMs can 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_key is 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 of running deliveries per (plugin_id, resource_class) (network today). It is enforced at lease time with a portable bookclerk_slots row, so two VPSes can't over-admit under READ 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_requested cancels the in-flight RPC (including workerd and native).
  • An expired-lease reclaim restores resume_pending when checkpoint_json is set.

See Jobs.

Storefront capabilities

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

Price lookups

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.

Paged scans

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.

  1. The first call has an empty cursor. Each later call passes back the nextCursor of the page before. A page with an empty nextCursor is the last one.
  2. An empty syncToken asks 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).
  3. On the last page, set syncToken to the token for the next pass (empty when the store has no change feed) and complete to true when the pass listed every title the account holds. A delta pass is not complete.
  4. List titles the store reports gone in a delta pass as product ids in removed. storePages counts 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 nextCursor after 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 syncToken and 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 removed product 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,
    };
  });
}
  1. The function gets an empty store cursor for the first store page, then each next it returned. An empty next marks the last store page.
  2. 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.
  3. Set syncToken and complete on the last store page. The helper sends them only with the pass's last reply.
  4. 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 with internal.

The three SDKs write the same cursors, so a plugin can move between them without breaking a pass in progress.

Quality offers

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:

  1. The host sends up to maxListPage of the account's product ids in titleIds, with its credentials, the instance's sourceConfig and the fetch options an acquire would use (DRM path, quality, xHE-AAC).
  2. Answer one TitleQualityOffer per id, in the same order. Set found and fill offer with the stream's codec, aacProfile (AAC only; unknown otherwise), and, when known, bitrateKbps, sampleRateHz and channels. Leave found false for a title you can't answer, and offer only streams a fetchTitle with the same options would deliver.
  3. 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.

Refreshed credentials

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:

  1. Set refreshedCredentials on the ScanPage, PlainFetch or QualityOffersResult reply to the account's whole credentials, in the same JSON form the host sent them. Leave it empty when nothing changed.
  2. 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.
  3. The host keeps the renewed credentials before it writes the page's titles, and sends them on the pass's later pages. A PlainFetch reply 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.

Catalog search capabilities

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 rankHint on each searchCatalog hit 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 it 0 when the store's order means nothing. The Rust storefront crate's CatalogSearchOpts::stamp_rank_hints fills it from the page and limit.

  • ISBN detail lookup. Set catalog.detailByIsbn in describe() when catalogDetail resolves any audiobook ISBN to a full record. After ranking a page, the host asks those stores, in sortKey order, 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 declares detailByProductId and 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.detailByProductId in describe() when catalogDetail resolves 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.priceByIsbn and catalog.priceByAsin in describe() when purchaseHint prices 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.

Declaring media

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

Book records

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.

Metadata providers

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).

Cover fetchers

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? }
  • urls holds 1 to MAX_COVER_URLS (32) absolute https URLs, and maxBytes is at most MAX_COVER_BYTES (10 MiB).
  • conditions holds the validators the host already has, by index, and may be shorter than urls. Send conditions[i].ifNoneMatch as If-None-Match and conditions[i].ifModifiedSince as If-Modified-Since when they are set. Each value is at most MAX_COVER_HEADER_BYTES (1024) bytes.
  • When the server answers 304 Not Modified, put nothing into the sink and answer stored: false, notModified: true: the host's copy is still current.
  • Copy the server's ETag, Last-Modified, Cache-Control, Expires, Date and Age into the answer verbatim, for a 200 or a 304. Leave out a value longer than MAX_COVER_HEADER_BYTES; the host refuses an answer that carries one, or one that is both stored and notModified. The values are advisory: the host parses them again with its own limits.
  • sink is a host-served Destination that accepts only put, only for the keys 0 to urls.length - 1, each once. A body over maxBytes fails that put with payload_too_large; every other method is unsupported.
  • Answer a failed URL with stored: false and an error such as HTTP 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. A stored answer 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.

Metadata file dialects

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:

  • dialect is one the plugin declared, fileName is a plain file name (no path) of at most 255 bytes, and bytes is at most MAX_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 most MAX_METADATA_FILE_TEXT_BYTES (1024) bytes; description is at most MAX_METADATA_FILE_DESCRIPTION_BYTES (64 KiB); each list holds at most MAX_METADATA_FILE_LIST_ENTRIES (256) entries and chapters at most MAX_METADATA_FILE_CHAPTERS (2000), in start order with no depth jump of more than one. publishedAt is YYYY, YYYY-MM or YYYY-MM-DD.
  • render is sent only to a dialect with writes = true, only for fields the dialect carries, and the answer is at most MAX_METADATA_FILE_BYTES. existing is empty when the host creates the file. audioFiles lists 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 most MAX_METADATA_AUDIO_FILES (4096) of them; it is empty when the host does not know them. Chapter starts in record count 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_params from parse for 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 as internal.
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.

Notifiers

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_limited is retried, after details.retryAfterMs when the service said how long (capped at one hour), otherwise on the job's backoff;
  • unavailable, deadline_exceeded (the call ran out of time) and cancelled (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 notificationId of at most 128 bytes, a type id, a non-blank one-line title of at most MAX_NOTIFICATION_TITLE_BYTES (256), text and markdown of at most MAX_NOTIFICATION_TEXT_BYTES (16 KiB), html of at most MAX_NOTIFICATION_HTML_BYTES (64 KiB), at most MAX_NOTIFICATION_FIELDS (25) fields with values of at most MAX_NOTIFICATION_FIELD_BYTES (1 KiB), and an alert key exactly when the alert action is not none. A link is https, or http only 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 most MAX_NOTIFIER_ADDRESS_BYTES (4 KiB). A validateDestination answer that breaks these rules, or an empty address, is refused as internal.
  • 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.

Raising notifications

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}`,
});
  • notificationType is a declared type id, without the plugin prefix the host adds.
  • fields are { name, value } rows or a plain object, with the caps of a message's fields.
  • patronId is required for a patron type: 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.
  • linkPath is a path inside the library (/books/42): it starts with one / and has no space or backslash. The host adds its public origin.
  • groupKey, alertAction and alertKey follow 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).

Public addresses (ingress)

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 than MAX_ORIGIN_TARGET_BYTES (8192);
  • there are more than MAX_ORIGIN_HEADERS (128) header fields, their names and values add up to more than MAX_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, upgrade and the proxy-* fields);
  • clientAddress is 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.

Model plugins

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:

  • dimensions and revision, the same as the listing;
  • vectors: one vector per text in input order, as little-endian 32-bit floats, concatenated (packEmbeddingVectors builds 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.

Calling models

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-embeddings for the library's text-embedding model, so a caller need not know which plugin is installed.
  • text is one text or a batch; role is document (the default) or query.
  • The answer has shape, data (one number[] per text), the full model name that ran, its revision, and fallbacks. Store model and revision beside 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.

Storage entrypoints

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 then put_file. S3 guests feed the existing multipart sink as bytes arrive.
  • Oversized scalar put and get fail closed.
  • There is no public handleId / readChunk / writeChunk protocol. Destinations transfer media through ByteSource streams. Range, multipart and checkpoint work in issue #120 builds on this contract, without another public ABI redesign.

Intent operations

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.atomic and MoveManyPage.atomic say whether the move was a rename no reader could observe half done. A list page sets signaturesIncluded when it filled in the signature fields ListOptions.withSignatures asked for, and modifiedSinceApplied when it left out objects older than ListOptions.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 moveMany returns at most maxBatchKeys outcomes and a nextCursor, and repeating a page after a restart moves nothing twice. A move whose source is gone and whose target exists succeeds with alreadyMoved.
  • Batches answer per key. moveMany with pairs and deleteMany return 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. headMany returns one probe per key, empty for a missing object.
  • Options only grow. MoveOptions, ListOptions and WriteOptions gain fields at new ordinals, and a zero value always means the old behaviour.
  • Preconditions are never dropped. A request whose ifMatch, ifSourceMatch or cursor cannot be read is refused rather than run without it, and a granted destination (a put through a capability handed to another plugin) refuses ifMatch / ifNoneMatch because that channel cannot carry them yet.
  • Prefix moves need disjoint prefixes. The source and target of a prefix moveMany may 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).

Translating keys

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.

Database adapter entrypoints

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.db at the jail-granted path (BOOKCLERK_SQLITE_PATH or sqlitePath) 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.begin opens a native interactive SeaORM transaction and returns an AdapterTransaction (execute, commit, rollback).
  • The host records a sticky per-task fault when begin fails, so later statements can't fall back to autocommit. A failed commit is surfaced to LibraryStore (SeaORM's proxy hook is infallible).
  • AdapterDatabaseSession.execute and HostAdapterDatabaseSession.execute carry the same AdapterExecuteRequest (canonical SQL, structured proofs, an optional receipt-persist hint).
  • D1 keeps begin unsupported, and routes host execute through its native batch proxy.

The built-in ids are sqlite, d1 and postgres (matching [database].plugin).

Isolated plugin database bindings

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 is PluginKey::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). The plugin_databases registry 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 (CREATEDB required). 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.pluginDatabases and 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.

Schema migrations inside a binding

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 maxListPage migrations;
  • maxPluginMigrationOps operations per migration;
  • maxPluginMigrationTotalOps operations across the registration;
  • each SQL at most maxScalarBytes;
  • aggregate id and SQL UTF-8 at most maxPluginMigrationRegistrationBytes.

The host then:

  1. Proves the sequence with one evolving type environment.
  2. Checks that the durable bookclerk_plugin_migrations history is an exact prefix of the registration.
  3. 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.

Reserved names

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.
  • REFERENCES targets use the same reserved-name rules as CREATE and DROP.
  • Any other name, including a framework's own schema_migrations, is the plugin's.
  • The binding's own bookclerk_receipts and bookclerk_plugin_migrations tables stay host-owned, so retry tokens replay inside the binding and plugins can't edit the journal.

The SQL a plugin may use

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 hex is denied.
  • Column types are INTEGER, REAL, TEXT, BLOB and BOOLEAN.
  • INSERT OR IGNORE is for unique or primary-key conflicts only, and is lowered to ON CONFLICT DO NOTHING on every backend, including SQLite and D1. SELECT and WITH sources are wrapped as SELECT * FROM (<source>) AS bookclerk_src WHERE true.
  • Helper arity and wire types are enforced, so callers needn't CAST for round, sum, avg or count.
  • Canonical LIKE is case-sensitive (GLOB lowering 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 EXISTS doesn'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.

How bindings reach the guest

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 over POST /db/execute (with GET /db/limits for limits(); the launcher also serves POST /db/execute-streamed, the streamed read the SDK helpers adopt next, see the SQL contract), and installs the resulting env.DB on the author's env for every call of that open (events, storefront, jobs, …). It is a full DatabaseBinding: prepare, bind, run, all, first, raw, batch and limits().

Authors never see the token.

Next steps

Source: docs/plugins/abi.md at main · View as Markdown