bookclerk_plugin_abi

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

Last updated View as Markdown

Authoritative Bookclerk plugin ABI (api_version 3).

Version 3 is the capability-driven object-capability ABI (Cap'n Proto RPC, transferred byte streams). The guest root is [PluginWorker]: describe() advertises typed PluginCapabilities, then open(invocation, bindings) returns the exported Entrypoints (storefront, storage, databaseAdapter, remoteLibrary, cli, oidc, metadata, covers, metadataFiles, notifier, ai, plus the eventConsumer / jobRunner triggers). Host-granted Bindings carry CONFIG / SECRETS, the EVENTS publisher, and named [[databases]] sessions — the Workers env idiom.

Audience

  • Guest authors — implement PluginWorker and the entrypoint traits against these DTOs (via bookclerk-plugin-sdk, @bookclerk/plugin-sdk, or a language binding generated from the same schema).
  • Host / SDK maintainers — drive entrypoint capabilities, seal credentials, and upsert library rows without depending on store-specific crates.

Product narrative (jail, consent, install layout) lives in docs/plugins/README.md. This crate is the typed wire contract only.

Schema

The Cap'n Proto schema at schema/plugin.capnp is the single source of truth: RPC interfaces, product constants, database enums, and the "Typed method payloads" section. Types here are the Rust projection; the TypeScript and Python SDK projections are generated from the same schema by scripts/gen-plugin-abi.py, which also drift-checks this crate. Wire DTO fields serialize as camelCase.

Install manifests validate against PLUGIN_TOML_SCHEMA_JSON (schema/plugin-toml.json).

Versioning

PRODUCT_API_VERSION is 3 (capability-driven Cap'n Proto / Workers RPC). Product spawn requires plugin.toml api_version = 3. There is no protocol key.

Modules

Module Contents
ai Checks on model listings, model runs and their replies
metadata_files Checks on metadataFiles requests and the records dialects return
methods Capability / consent method name constants (login, event, …)
notifications Checks on notification messages, addresses, raises and notifier replies
Crate-root DTOs PluginDescribe, health, CLI, destination objects
kind Kind-specific DTOs (source / integration / output)
settings_schema [[settings]] operator settings schema shared by manifest and host
package_version plugin.toml version parsing and ordering for schema pinning
db Host-private database connect params (feature host)
error PluginError / PluginErrorCode
guest_sql SQL-v1 grammar / guest admission
sql_desugar Host-only semantic desugars (NULLS, NULLIF)
plugin_capnp Generated Cap'n Proto RPC interfaces
Item Kind Summary
AdapterTransaction trait Host-only interactive transaction on an adapter connection (SeaORM proxy).
HostAdapterDatabaseSession trait Host-only view of an open adapter session (begin for interactive txn).
AdapterDatabaseSession trait Host ↔ database adapter session (capabilities + typed execute).
AiModels trait ai entrypoint: serves models to the host and, through the AI binding, to every plugin with the grant.
AiRunner trait AI binding: runs a model served by a deployed model plugin (Bindings::ai).
Cancellation trait Transport cancellation. SDKs project this into a locally created AbortSignal (AbortSignal is not a serializable Workers RPC value).
ContentSource trait Storefront content source (not byte Source).
CoverFetcher trait covers entrypoint: downloads cover images on the host's behalf.
Database trait Database factory. Sessions cannot survive suspension.
Destination trait Destination capability (storage).
EventConsumer trait [[events.consumers]] handler (Entrypoints::event_consumer).
EventPublisher trait EVENTS binding: host-served outbox publisher (Bindings::events).
GuestDatabase trait Host-granted SQL transport for job plugin authors (no capabilities).
Ingress trait ingress entrypoint: a public address provider (a relay, or a dynamic DNS name). The library runs at most one at a time.
JobRunner trait [triggers] jobs handler (Entrypoints::job_runner).
KvNamespace trait Durable key/value namespace: Workers KVNamespace-shaped binding the host serves from the library database, scoped to the plugin and the namespace a [[kv_namespaces]] row names. Values live in the library, so an instance moved to another host reads its own keys.
MetadataFiles trait metadataFiles entrypoint: converts metadata files (sidecars) next to an edition's media to and from crate::MetadataFileRecords.
MetadataProvider trait metadata entrypoint: bibliographic lookups against a public catalog.
NotificationRaiser trait NOTIFY binding: raises the notification types the plugin declares in [[notifications.types]] (Bindings::notify).
Notifier trait notifier entrypoint: delivers one host-rendered notification to one destination.
Oidc trait oidc entrypoint: relying-party client templates and credential verification on behalf of the host authorization server.
Origin trait The library as a relay ingress plugin reaches it, granted on Bindings::origin (ORIGIN in the Workers idiom).
PluginCli trait cli entrypoint: guest commands under bookclerk plugins <id> <command>.
PluginWorker trait Root PluginWorker capability (describe / open / shutdown).
ProgressSink trait Progress reports for a job invocation (never carries media).
QueueConsumer trait [[queues.consumers]] handler (Entrypoints::queue_consumer).
QueueProducer trait Queue producer binding: host-served send into the queue a [[queues.producers]] row names (Bindings::queues).
RemoteLibrary trait remoteLibrary entrypoint: long-running remote-library lifecycle.
ScheduledHandler trait [triggers] crons handler (Entrypoints::scheduled_handler), the Workers scheduled(controller) trigger.
SocketHandler trait [sockets] handler: what arrives on host-brokered sockets.
Sockets trait Host-brokered outbound WebSockets granted on Bindings::sockets.
Source trait Source capability that can open a named object as a stream.
WebhookHandler trait [[webhooks]] handler: told when the host stored deliveries.
Webhooks trait Host-served inbound webhooks granted on Bindings::webhooks.
GuestReceiptPersist struct Host-stamped hint for adapters to persist guest replay payload before COMMIT.
AdapterExecuteRequest struct Adapter execute payload: canonical SQL, structured proofs, optional receipt.
CanonicalExecuteRequest struct Host-desugared canonical SQL. Proofs are not yet bound.
UnresolvedExecuteRequest struct Source SQL that has not been host-canonicalized.
PluginMigration struct One plugin-owned migration application in registration order.
IntegerArithSite struct One INTEGER arithmetic expression that must not wrap or error on overflow.
PhysicalAccess struct Physical table/column access used for authorization.
ResolvedAssignment struct Destination assignment lhs = rhs (INSERT, UPDATE, …).
ResolvedStatement struct One resolved typed proof bound to an exact canonical statement.
SqlSpan struct Byte span in the exact canonical SQL string a proof is bound to.
TextCollateSite struct One TEXT expression that PostgreSQL must collate as "C".
SqlFnCall struct One helper call found in canonical SQL (code spans only).
HostAdapterDatabaseSessionClient struct Host-side client for begin on an open adapter session capability.
RpcFeature struct Known RPC feature names.
StreamCopyHandler struct Default JobRunner for the stream-copy vertical slice.
StreamCopySpec struct JSON body for a stream_copy JobInvocation.
ScalarLimits struct Negotiated numeric limits advertised at super::PluginDescribe.
BindingValues struct Plain-data portion of Bindings: every granted value that is not a capability. Hosts build this off the vat thread and attach capabilities when they call open.
Bindings struct Host-granted bindings for one PluginWorker::open (env in the Workers idiom). Capability fields are None when the manifest does not declare (or the operator did not grant) the binding.
ByteRange struct Inclusive byte range for a streamed read.
Entrypoints struct Exported entrypoints returned by PluginWorker::open: one capability per plugin.toml entrypoints entry / trigger, None when not exported.
JobController struct Everything one JobRunner::job invocation may touch.
NamedKvBinding struct One granted [[kv_namespaces]] binding on Bindings::kv.
NamedQueueBinding struct One granted [[queues.producers]] binding on Bindings::queues.
NeverCancel struct Cancellation that never fires (tests / hosts without a fence).
OriginReply struct The library's answer to one Origin::fetch: its response head and streamed body.
ReadResult struct Streamed read result. body ownership is transferred to the caller.
AdapterSessionHandle struct Public adapter session plus host-private interactive transaction client.
AiModelsClient struct Cap'n Proto client for AiModels.
AiRunnerClient struct Guest-side client for the host AI binding (AiRunner). Runs are checked before they leave, so a plugin learns of a malformed run without a round trip; the host checks again.
ContentSourceClient struct Cap'n Proto client for ContentSource.
CoverFetcherClient struct Cap'n Proto client for CoverFetcher.
DatabaseClient struct Cap'n Proto client for Database.
DestinationClient struct Host-side Destination over a capnp destination stub.
DestinationServer struct Cap'n Proto server wrapping a Destination trait object.
EventConsumerClient struct Cap'n Proto client for EventConsumer (host → guest delivery).
EventPublisherClient struct Guest-side client for the host EVENTS binding (EventPublisher).
HostBindings struct Host-side Bindings: plain values plus host-served capabilities the guest receives on open.
IngressClient struct Host-side client for a plugin's ingress entrypoint.
JobRunnerClient struct Cap'n Proto client for JobRunner (host → guest job dispatch).
KvNamespaceClient struct Guest-side client for a host KV namespace binding (KvNamespace).
MetadataFilesClient struct Cap'n Proto client for MetadataFiles.
MetadataProviderClient struct Cap'n Proto client for MetadataProvider.
NoOrigin struct Fails closed: an Origin that refuses everything, for hosts that grant no relay ingress. Kept for tests and in-process hosts.
NotificationRaiserClient struct Guest-side client for the host NOTIFY binding (NotificationRaiser). Raises are checked before they leave, so a plugin learns of a malformed raise without a round trip; the host checks again.
NotifierClient struct Cap'n Proto client for Notifier.
OidcClient struct Cap'n Proto client for Oidc.
OpenedEntrypoints struct Typed clients for the entrypoints a guest exported from open. None means the guest did not export that entrypoint.
OriginClient struct Guest-side client for the Origin binding (what a native relay plugin calls).
PluginCliClient struct Cap'n Proto client for PluginCli.
PluginClient struct Host bootstrap client for a plugin vat.
PluginServer struct Cap'n Proto server wrapping PluginWorker.
QueueConsumerClient struct Cap'n Proto client for QueueConsumer (host → guest delivery).
QueueProducerClient struct Guest-side client for a host queue producer binding (QueueProducer).
RemoteLibraryClient struct Cap'n Proto client for RemoteLibrary.
ScheduledHandlerClient struct Cap'n Proto client for ScheduledHandler (host → guest cron fire).
SocketHandlerClient struct Host-side client for a guest's SocketHandler.
SocketsClient struct Guest-side client for the host Sockets binding.
SourceClient struct Host-side Source over a capnp source stub.
SourceServer struct Cap'n Proto server wrapping a Source.
WebhookHandlerClient struct Host-side client for a guest's WebhookHandler.
WebhooksClient struct Guest-side client for the host Webhooks binding.
CopyResult struct Result of a server-side copy.
DomainEvent struct Domain event (not a job). Outbox-produced, at-least-once, idempotent consume.
ExtensibleConfig struct Versioned plugin-specific config (not a substitute for typed ABI fields).
HealthOk struct Health payload.
JobCheckpoint struct Bounded, versioned checkpoint attached to an invocation or suspension.
JobInvocation struct Versioned durable command envelope (not a domain event).
JobInvocationLease struct Claimed-lease fields used to populate a JobInvocation.
ListOptions struct Paginated list request.
ListPage struct One page of keys.
ObjectInfo struct Object listing entry.
ObjectMetadata struct Metadata without a body.
OidcClientTemplate struct Plugin-declared Bookclerk-as-IdP relying-party template.
PluginDescribe struct Guest identity returned by PluginWorker.describe (the adapter merges the manifest projection over the author describe()).
PutResult struct Result of a streamed put.
QueryPage struct Bounded query page for host-internal SeaORM session helpers (not Cap'n ABI).
ScalarLimitsDto struct Wire form of ScalarLimits.
WriteOptions struct Write options for Destination.put.
ChangesPage struct One page of crate::Destination::changes.
ChangesRequest struct Argument of crate::Destination::changes.
KeyOutcome struct Outcome for one key of a batch call.
KeyPair struct One source and target key (or prefix).
MoveManyPage struct One page of crate::Destination::move_many progress.
MoveManyRequest struct Argument of crate::Destination::move_many.
MoveOptions struct Options for crate::Destination::move_object and crate::Destination::move_many. Fields are only ever appended.
MoveResult struct How a single move was done.
ObjectChange struct One entry of a change feed.
PluginMigrationOp enum One already-separated BookclerkSQL operation in a registered migration.
OverflowDialect enum Engine family for overflow derived-table syntax and i64::MIN CAST.
IntegerArithKind enum INTEGER + - * abs site lowered to overflow → NULL.
SchemaAction enum CREATE/DROP action recorded on a proof.
LikePatternSrc enum Proven LIKE pattern sources in one canonical statement.
EventReadCodec enum Which EVENTS.read Cap'n Proto struct roundtrip_event_read_message decodes.
EventReadMessage enum A value roundtrip_event_read_message decoded.
SocketCodec enum Which socket Cap'n Proto struct roundtrip_socket_message decodes.
SocketWireMessage enum A value roundtrip_socket_message decoded.
WebhookCodec enum Which webhook Cap'n Proto struct roundtrip_webhook_message decodes.
WebhookWireMessage enum A value roundtrip_webhook_message decoded.
EventResult enum Per-event result of crate::EventConsumer::event.
JobOutcome enum Outcome of crate::JobRunner::job.
MoveManyTarget enum What a MoveManyRequest moves.
ObjectChangeKind enum What happened to an object in a change feed.
StorageReply enum A guest reply the storage_reply fuzz target decodes.
StorageReplyKind enum Which reply decode_storage_reply_bytes reads.
capnp_u32_len function Converts a Rust list length into a Cap'n Proto UInt32 list size.
plugin_migration_registration_bytes function Aggregate UTF-8 bytes of ids plus SQL across a complete registration.
require_plugin_migration_json_lists function Rejects JSON databaseMigrations list sizes before deserializing operations.
require_plugin_migration_registration function Rejects a plugin migration registration that exceeds RPC resource limits.
apply_integer_overflow function Wrap each INTEGER +/-/*/abs site in a portable overflow CASE.
assert_proof_matches_sql function Require proof to be bound to sql.
admitted_bookclerk_sql_samples function Grammar-aware BookclerkSQL samples for fuzz corpora and differential tests.
canonical_statements_checksum function Length-prefixed SHA-256 of an ordered canonical statement list.
glob_expanded_like_pattern_bytes function UTF-8 byte length of a sqlite-family GLOB pattern after Bookclerk LIKE→GLOB metacharacter escaping ([ * ? become three bytes).
like_pattern_sources function Collects LIKE / NOT LIKE pattern sources with proven lengths when possible.
require_function_args_within function Enforces crate::DbCapabilities::max_function_args on non-chunkable helpers.
require_like_patterns_within function Enforces crate::DbCapabilities::max_pattern_bytes on LIKE patterns.
require_portable_text function Rejects BookclerkSQL TEXT that contains U+0000.
require_portable_text_binds function Rejects U+0000 in every BookclerkSQL TEXT bind.
sql_v1_function_calls function Collects helper calls in code spans (strings/comments are skipped).
sql_v1_helper_is_chunkable function Helpers adapters may nest so each physical call stays inside crate::DbCapabilities::max_function_args.
sql_v1_pack_statements function Splits a BookclerkSQL pack into statements using the SQL-v1 lexer.
sqlite_family_like_divmod_insert_upper_bound function Upper bound on sqlite-family mechanical lowering length for a canonical statement of canonical_len bytes (div/mod NULLIF, INSERT OR IGNORE, LIKE→GLOB). Does not include proof-directed INTEGER overflow wraps.
sqlite_family_mechanical_len_upper_bound function Mechanical sqlite-family length bound for one canonical statement, counting actual LIKE occurrences, / % operators in code spans, and at most one INSERT OR IGNORE rewrite.
text_contains_nul function True when text contains U+0000.
canonical_execute_request_hash function SHA-256 hex of the Cap'n-encoded request with transport metadata cleared.
decode_db_capabilities_reply_bytes function Decodes a standalone Cap'n DbCapabilitiesReply message.
decode_db_value_bytes function Decodes a standalone Cap'n DbValue message.
decode_execute_request_bytes function Decodes a standalone Cap'n ExecuteRequest message.
decode_execute_result_reply_bytes function Decodes a standalone Cap'n ExecuteAtomicReply message.
decode_execute_stream_frame_bytes function Decodes one standalone ExecuteStreamFrame message whose traversal is capped at max_bytes (at least the scalar ceiling).
encoded_db_capabilities_reply_bytes function Encodes a standalone Cap'n DbCapabilitiesReply (ok or err).
encoded_db_value_bytes function Encodes a standalone Cap'n DbValue message (unpacked stream).
encoded_db_value_len function Length in bytes of encoded_db_value_bytes's output, worked out from the value instead of encoding it.
encoded_execute_reply_bytes function Encodes a standalone Cap'n ExecuteReply message (unpacked stream).
encoded_execute_request_bytes function Encodes a standalone Cap'n ExecuteRequest message (unpacked stream).
encoded_execute_result_reply_bytes function Encodes a standalone Cap'n ExecuteAtomicReply (ok or err).
encoded_execute_stream_frame_bytes function Encodes one standalone ExecuteStreamFrame message (unpacked stream, one segment).
encoded_statement_result_bytes function Encodes a standalone Cap'n StatementResult message (unpacked stream).
negotiate_rpc_features function Intersects host-offered and guest-accepted feature lists.
read_all function Reads a small transferred body, stopping at crate::MAX_SCALAR_BYTES.
stream_copy_keys function Copies from → to through granted source/destination streams.
cover_sink_slot function Parses a CoverFetcher.fetchCovers sink key into the URL index it names.
hint_result function A bare hint as a PurchaseHintResult with no records.
purchase_hint_results_one_by_one function ContentSource::purchase_hints_results for a store without a bulk endpoint: asks ContentSource::purchase_hint_result for each query, with the same order, concurrency and PURCHASE_HINTS_BUDGET as the default ContentSource::purchase_hints. A query not started within the budget answers an empty result (found = false, no records).
byte_source_from_async_read function Returns a ByteSource client that pulls from reader.
connect_plugin function Connects as the client side of a two-party vat.
connect_socket_broker function Connects the host's side of the host-to-broker link (see serve_socket_broker).
decode_empty_reply_bytes function Decodes a standalone EmptyReply message the way the host decodes a guest's payload-free reply, for the abi_decode fuzz target and its corpus replay.
decode_plugin_error_bytes function Decodes a standalone PluginError message the way the host decodes a guest's error, for the abi_decode fuzz target and its corpus replay.
pull_byte_source_to_writer function Pulls source into writer using bounded windows.
roundtrip_event_read_message function Decodes one unpacked single-segment EventReadRequest or EventReadPage message with the codec the RPC server and client use, then checks read(write(v)) == v. The fuzz target and its replay test drive this, so they reach the same bounds checks a peer's bytes do.
roundtrip_socket_message function Decodes one unpacked single-segment SocketConnectRequest or SocketMessage with the codec the RPC server and client use, then checks read(write(v)) == v. The socket_request fuzz target and its replay test drive this, so they reach the same decoder a peer's bytes do; the caller then applies crate::sockets checks to the value.
roundtrip_webhook_message function Decodes one unpacked single-segment webhook message with the codec the RPC server and client use, then checks read(write(v)) == v. The webhook_rpc fuzz target and its replay test drive this, so they reach the same decoder a peer's bytes do; the caller then applies the crate::webhooks checks to the value.
serve_plugin function Serves plugin as the bootstrap object on a two-party vat over reader/writer.
serve_plugin_stdio function Serves plugin on stdin/stdout. Must run on a current-thread runtime + LocalSet.
serve_socket_broker function Serves the socket broker's side of the host-to-broker link.
decode_storage_reply_bytes function Decodes one guest storage reply from an unpacked Cap'n Proto message, under the same caps the host applies to a live reply.
encode_storage_reply_bytes function Encodes one storage reply as an unpacked single-segment message, the inverse of decode_storage_reply_bytes.
require_batch_len function Rejects a batch request the guest is not obliged to serve.
validate_changes_page function Checks a guest's change feed page against the cursor the host sent.
validate_head_many function Checks a guest's headMany probes against the keys the host sent.
validate_key_outcomes function Checks a guest's per-key outcomes against the keys the host sent.
validate_move_many_page function Checks a guest's moveMany page against the request it answers.
validate_translated_keys function Checks a guest's translateKeys answer against the host keys it was sent.
MAX_PLUGIN_MIGRATION_ID_BYTES constant Maximum UTF-8 bytes of one plugin-chosen migration id.
PLUGIN_MIGRATIONS_TABLE constant Host-private plugin-binding migration journal (not a plugin-owned table).
PHYSICAL_STAR_COLUMN constant Column name recorded for SELECT * / alias.* / RETURNING * on a physical table.
D1_PHYSICAL_LIKE_GLOB_PATTERN_BYTES constant Physical D1 LIKE/GLOB pattern cap in bytes.
D1_PORTABLE_LIKE_PATTERN_BYTES constant Conservative portable LIKE pattern cap for D1 while LIKE lowers to GLOB.
LIKE_GLOB_PATTERN_WRAP_BYTES constant Bytes added around a LIKE pattern by LIKE_GLOB_WRAP_PREFIX / LIKE_GLOB_WRAP_SUFFIX (the pattern itself is unchanged).
LIKE_GLOB_REWRITE_OVERHEAD constant Worst-case extra bytes per LIKE / NOT LIKE after sqlite-family GLOB wrapping.
LIKE_GLOB_WRAP_PREFIX constant Prefix of the sqlite-family LIKE→GLOB replace(...) wrap (before the pattern).
LIKE_GLOB_WRAP_SUFFIX constant Suffix of the sqlite-family LIKE→GLOB replace(...) wrap (after the pattern).
LIKE_TO_GLOB_KEYWORD_EXTRA constant Extra byte when LIKE is immediately followed by its pattern (no trivia): the rewrite emits GLOB (5) in place of LIKE (4).
SQLITE_FAMILY_DIV_MOD_NULLIF_EXTRA constant Extra bytes for one / or % rewritten to NULLIF(operand, 0).
SQLITE_FAMILY_INSERT_OR_IGNORE_MAX_EXTRA constant Conservative extra bytes for one INSERT OR IGNORE unique-conflict rewrite (conflict clause plus optional SELECT source wrap).
FEATURE_SCALAR_LIMITS constant Guest honors scalar / stream-window / list-page caps.
FEATURE_STORAGE_CHANGES constant Guest implements super::Destination::changes.
FEATURE_STORAGE_CONDITIONAL_WRITE constant Guest enforces super::WriteOptions::if_match and super::WriteOptions::if_none_match.
FEATURE_STORAGE_COPY constant Guest implements server-side super::Destination::copy.
FEATURE_STORAGE_DELETE_MANY constant Guest implements super::Destination::delete_many.
FEATURE_STORAGE_HEAD_MANY constant Guest implements super::Destination::head_many.
FEATURE_STORAGE_MOVE constant Guest implements super::Destination::move_object.
FEATURE_STORAGE_MOVE_MANY constant Guest implements super::Destination::move_many.
FEATURE_STORAGE_TRANSLATE_KEYS constant Guest implements super::Destination::translate_keys.
FEATURE_STREAMS constant Media moves through transferred crate::roles::ByteRange / ByteSource streams.
STORAGE_OPERATION_FEATURES constant Every optional storage operation a host offers a storage guest, beside FEATURE_STORAGE_COPY. Each one the guest accepts replaces the host's fallback for that operation.
MAX_AI_EMBED_DIMENSIONS constant Most numbers in one embedding vector.
MAX_AI_EMBED_TEXTS constant Most texts in one text-embedding run.
MAX_AI_EMBED_TEXT_BYTES constant Longest text in a text-embedding run, in UTF-8 bytes.
MAX_AI_LANGUAGES constant Most language tags on one listed model.
MAX_AI_MODELS constant Most models one plugin lists on its ai entrypoint.
MAX_AI_MODEL_NAME_BYTES constant Longest model name on the AI binding (@<plugin id>/<model id>), in UTF-8 bytes.
MAX_COVER_BYTES constant Largest image body one CoverFetcher.fetchCovers URL may return.
MAX_COVER_HEADER_BYTES constant Longest cache header value one CoverFetcher.fetchCovers call carries in either direction, in bytes.
MAX_COVER_URLS constant Most URLs in one CoverFetcher.fetchCovers call.
MAX_CRON_BYTES constant Longest [triggers] crons source in bytes (ScheduledController.cron).
MAX_EVENT_CURSOR_BYTES constant Longest EventPublisher.read cursor in bytes.
MAX_EVENT_PAYLOAD_BYTES constant Maximum decoded size of a domain-event scalar payload (not a stream).
MAX_INGRESS_ORIGIN_BYTES constant Longest host name in IngressStarted.origin, in bytes.
MAX_KV_KEY_BYTES constant Longest KvNamespace key in UTF-8 bytes.
MAX_KV_METADATA_BYTES constant Largest KvNamespace metadata JSON text in bytes.
MAX_KV_VALUE_BYTES constant Largest KvNamespace value in bytes (a [[kv_namespaces]] row may lower its own cap but never raise it past this).
MAX_LIST_PAGE constant Maximum objects in one Destination.list page.
MAX_METADATA_AUDIO_FILES constant Most audio files a MetadataFiles.render request names.
MAX_METADATA_FILE_BYTES constant Largest metadata file MetadataFiles.parse reads and MetadataFiles.render returns, in bytes.
MAX_METADATA_FILE_CHAPTERS constant Most chapters in a MetadataFileRecord.
MAX_METADATA_FILE_DESCRIPTION_BYTES constant Longest description a MetadataFileRecord carries, in UTF-8 bytes.
MAX_METADATA_FILE_LIST_ENTRIES constant Most entries in each non-chapter list of a MetadataFileRecord.
MAX_METADATA_FILE_TEXT_BYTES constant Longest other text value in a MetadataFileRecord, in UTF-8 bytes.
MAX_NOTIFICATION_FIELDS constant Most labelled fields on one notification message or raise.
MAX_NOTIFICATION_FIELD_BYTES constant Longest notification field value, link, group key or alert key, in UTF-8 bytes.
MAX_NOTIFICATION_HTML_BYTES constant Longest notification HTML body, in UTF-8 bytes.
MAX_NOTIFICATION_TEXT_BYTES constant Longest notification plain-text or markdown body, in UTF-8 bytes.
MAX_NOTIFICATION_TITLE_BYTES constant Longest notification title or field name, in UTF-8 bytes.
MAX_NOTIFIER_ADDRESS_BYTES constant Longest notifier destination address document, in UTF-8 bytes.
MAX_ORIGIN_HEADERS constant Most header fields on one Origin.fetch request, and separately on its response.
MAX_ORIGIN_HEADER_BYTES constant Largest total UTF-8 bytes of header names and values on one Origin.fetch request, and separately on its response.
MAX_ORIGIN_TARGET_BYTES constant Longest OriginRequest.target (path and query), in bytes.
MAX_PLUGIN_MIGRATION_OPS constant Maximum already-separated operations in one plugin-owned migration.
MAX_PLUGIN_MIGRATION_REGISTRATION_BYTES constant Maximum aggregate UTF-8 bytes of plugin migration ids plus SQL in one databaseMigrations registration (Cap'n Proto framing is not counted).
MAX_PLUGIN_MIGRATION_TOTAL_OPS constant Maximum already-separated operations across one databaseMigrations registration (independent of the per-migration cap and of id+SQL UTF-8 bytes).
MAX_REFRESHED_CREDENTIAL_BYTES constant Longest refreshed credential blob a storefront may hand back in bytes (ScanPage.refreshedCredentials, PlainFetch.refreshedCredentials).
MAX_SCALAR_BYTES constant Maximum decoded size of an ordinary RPC scalar value (not a stream window).
MAX_SCAN_CURSOR_BYTES constant Longest scan cursor or sync token in bytes.
MAX_SCAN_PAGE_BOOKS constant Most titles, and separately most removed product ids, in one ContentSource.scan page.
MAX_SOCKETS_PER_INSTANCE constant Most host-brokered sockets one plugin instance may hold open at once.
MAX_SOCKET_ATTACHMENT_BYTES constant Largest per-socket attachment the host keeps, in bytes.
MAX_SOCKET_AUTO_RESPONSES constant Most heartbeat pairs one Sockets.connect may declare.
MAX_SOCKET_AUTO_RESPONSE_BYTES constant Largest heartbeat request or response frame, in bytes.
MAX_SOCKET_FRAME_BYTES constant Largest WebSocket message Sockets.send accepts or SocketHandler.message delivers, in bytes.
MAX_SOCKET_HEADERS constant Most request headers, and separately subprotocols, on one Sockets.connect.
MAX_SOCKET_URL_BYTES constant Longest Sockets.connect URL, in bytes.
MAX_STREAM_WINDOW_BYTES constant Maximum bytes returned by one ByteSource.pull (flow-control window).
MAX_WEBHOOK_BODY_BYTES constant Largest stored webhook request body, in bytes (1 MiB).
MAX_WEBHOOK_HEADERS constant Most request headers a [[webhooks]] row keeps.
MAX_WEBHOOK_HEADER_VALUE_BYTES constant Longest kept request header value, in bytes.
MAX_WEBHOOK_LEASE_ID_BYTES constant Longest WebhookDelivery.leaseId, in bytes.
MAX_WEBHOOK_NAME_BYTES constant Longest [[webhooks]] name, in bytes.
MAX_WEBHOOK_PULL_BATCH constant Most deliveries one Webhooks.pull returns.
MAX_WEBHOOK_VISIBILITY_MS constant Longest Webhooks.pull visibility timeout, in milliseconds (12 hours).
PRODUCT_API_VERSION constant Product ABI version (apiVersion / plugin.toml api_version).
PURCHASE_HINTS_BUDGET constant How long the default ContentSource::purchase_hints keeps starting one-title lookups before answering with what it has. Well under the host's 10 s batch deadline, so even a slow last lookup lands before it and a store without a bulk endpoint still returns the titles it priced.
PURCHASE_HINTS_CONCURRENCY constant How many one-title lookups the default ContentSource::purchase_hints keeps in flight at once. A store without a bulk endpoint answers a page of cards in about a quarter of the time one lookup after another takes, while staying a polite handful of requests rather than a burst.
JSON_MEDIA_TYPE constant Media type of a JSON ExtensibleConfig payload.
MAX_CHECKPOINT_BYTES constant Maximum checkpoint payload size (bytes).
MAX_BATCH_KEYS constant Maximum keys or key pairs in one moveMany, deleteMany or headMany call, and maximum outcomes in one reply.
MAX_CHANGES_CURSOR_BYTES constant Maximum bytes of a Destination.changes cursor.
MAX_CHANGES_PAGE constant Maximum changes in one Destination.changes page.
MAX_TRANSLATED_KEY_BYTES constant Longest key a guest may translate a host key into, in UTF-8 bytes. Generous next to any store's own limit (S3 keys stop at 1024 bytes, file-system paths usually at 4096).
PLUGIN_TOML_SCHEMA_JSON constant Embedded JSON Schema for install plugin.toml files (shared with language SDK author tools and bookclerk plugins validation).

Re-exports

Modules

  • ai: The checks the host runs on model listings, model runs and their replies.
  • backup_ops: Host-facing backup/restore primitives (Send + Sync).
  • db: Database-adapter binding payloads (host connect params + public adapter config).
  • db_execute: Typed Cap'n database data-plane (ExecuteRequest / ExecuteReply) and control-plane (DbCapabilities) mirrors of plugin.capnp.
  • db_stream: Streamed execute replies (executeStreamed).
  • db_value: Universal Cap'n database value domain (DbValue).
  • error: Plugin error model shared by host and guests.
  • event_read: Validation of one EventPublisher.read request and its opaque cursor.
  • generated: GENERATED FILE - do not edit. Run python3 scripts/gen-plugin-abi.py --write after changing crates/bookclerk-plugin-abi/schema/plugin.capnp.
  • guest_sql: Host-side grammar and scope checks for guest-authored typed SQL.
  • json_bytes: Serde helpers projecting Cap'n Proto Data fields as base64 text in JSON.
  • kind: Output-plugin configuration DTOs carried as application/json inside crate::ExtensibleConfig (Bindings.config for the storage entrypoint).
  • media: The media a plugin declares it works with, and the checks the host runs against that declaration.
  • metadata_files: The checks the host runs on what a metadataFiles plugin returns and on what it sends one.
  • methods: Role capability method names (camelCase on the wire).
  • network_grant: The network grant a guest sees at open (Bindings.network).
  • notifications: The checks the host runs on notification requests and replies.
  • origin: Sans-IO checks for the ORIGIN binding and the ingress entrypoint.
  • package_version: plugin.toml version as a semantic version.
  • quality_offers: Validation of one ContentSource.qualityOffers reply before the host compares it with the files it holds.
  • scan_page: Validation of one ContentSource.scan page before the host writes it.
  • settings_schema: Operator-facing plugin settings schema ([[settings]] in plugin.toml).
  • sockets: Sans-IO checks for host-brokered sockets (Bindings.sockets).
  • sql_desugar: Host semantic desugars for canonical Bookclerk SQL.
  • sql_types: Bookclerk SQL v1 types, CAST matrix, and fail-closed expression checking.
  • webhooks: Sans-IO checks for host-served inbound webhooks (Bindings.webhooks).
  • plugin_capnp: Generated Cap'n Proto RPC interfaces (schema/plugin.capnp).
  • plugin_host_capnp: Host-private Cap'n Proto RPC interfaces (schema/plugin_host.capnp).

Traits

AdapterTransaction

pub trait AdapterTransaction {
    fn execute<'life0, 'async_trait>(
        &'life0 self,
        request: AdapterExecuteRequest,
    ) -> Pin<Box<dyn Future<Output = Result<ExecuteReply>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn commit<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn rollback<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn export_identity<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<DbIdentityHighWater>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn import_identity<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _rows: &'life1 [DbIdentityHighWater],
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn list_user_relations<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn prepare_unit_restore<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn drop_user_relations<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _names: &'life1 [String],
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn assert_restore_constraints<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Host-only interactive transaction on an adapter connection (SeaORM proxy).

AdapterTransaction::execute

fn execute<'life0, 'async_trait>(
    &'life0 self,
    request: AdapterExecuteRequest,
) -> Pin<Box<dyn Future<Output = Result<ExecuteReply>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Typed statements on this open transaction (no second BEGIN).

Proofs are required (crate::AdapterExecuteRequest::require_proofs).

AdapterTransaction::commit

fn commit<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Commit.

AdapterTransaction::rollback

fn rollback<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Rollback.

AdapterTransaction::export_identity

fn export_identity<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Vec<DbIdentityHighWater>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Identity high-water from adapter catalogs on this transaction.

AdapterTransaction::import_identity

fn import_identity<'life0, 'life1, 'async_trait>(
    &'life0 self,
    _rows: &'life1 [DbIdentityHighWater],
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Restore identity high-water into adapter catalogs on this transaction.

AdapterTransaction::list_user_relations

fn list_user_relations<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

User-visible relation names visible to this transaction.

AdapterTransaction::prepare_unit_restore

fn prepare_unit_restore<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Prepare this restore transaction (deferred FK checks).

AdapterTransaction::drop_user_relations

fn drop_user_relations<'life0, 'life1, 'async_trait>(
    &'life0 self,
    _names: &'life1 [String],
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Drop named user relations on this transaction.

AdapterTransaction::assert_restore_constraints

fn assert_restore_constraints<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Fail closed when this restore transaction still has FK violations.

HostAdapterDatabaseSession

pub trait HostAdapterDatabaseSession {
    fn begin<'life0, 'async_trait>(
        &'life0 self,
        isolation: IsolationReq,
    ) -> Pin<Box<dyn Future<Output = Result<Box<dyn AdapterTransaction>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn execute<'life0, 'async_trait>(
        &'life0 self,
        request: AdapterExecuteRequest,
    ) -> Pin<Box<dyn Future<Output = Result<ExecuteReply>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Host-only view of an open adapter session (begin for interactive txn).

HostAdapterDatabaseSession::begin

fn begin<'life0, 'async_trait>(
    &'life0 self,
    isolation: IsolationReq,
) -> Pin<Box<dyn Future<Output = Result<Box<dyn AdapterTransaction>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Opens a host-internal interactive transaction (SeaORM proxy).

HostAdapterDatabaseSession::execute

fn execute<'life0, 'async_trait>(
    &'life0 self,
    request: AdapterExecuteRequest,
) -> Pin<Box<dyn Future<Output = Result<ExecuteReply>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Typed atomic execute on this host-private session.

Implemented by: HostAdapterDatabaseSessionClient

AdapterDatabaseSession

pub trait AdapterDatabaseSession {
    fn capabilities<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<DbCapabilities>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn bootstrap<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<DbBootstrap>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn execute<'life0, 'async_trait>(
        &'life0 self,
        request: AdapterExecuteRequest,
    ) -> Pin<Box<dyn Future<Output = Result<ExecuteReply>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn execute_streamed<'life0, 'async_trait>(
        &'life0 self,
        request: AdapterExecuteRequest,
    ) -> Pin<Box<dyn Future<Output = Result<ExecuteStream>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn close<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn export_identity<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<DbIdentityHighWater>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn import_identity<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _rows: &'life1 [DbIdentityHighWater],
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn list_user_relations<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn prepare_unit_restore<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn drop_user_relations<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _names: &'life1 [String],
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn assert_restore_constraints<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Host ↔ database adapter session (capabilities + typed execute).

AdapterDatabaseSession::capabilities

fn capabilities<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<DbCapabilities>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Typed SQL-contract advertisement.

AdapterDatabaseSession::bootstrap

fn bootstrap<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<DbBootstrap>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Bootstrap-only SeaORM proxy metadata for the open session.

AdapterDatabaseSession::execute

fn execute<'life0, 'async_trait>(
    &'life0 self,
    request: AdapterExecuteRequest,
) -> Pin<Box<dyn Future<Output = Result<ExecuteReply>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Typed atomic batch (execute). Canonical SQL plus required 1:1 proofs.

AdapterDatabaseSession::execute_streamed

fn execute_streamed<'life0, 'async_trait>(
    &'life0 self,
    request: AdapterExecuteRequest,
) -> Pin<Box<dyn Future<Output = Result<ExecuteStream>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

execute whose reply is framed and counted against the streamed budget (maxStreamedResultBytes / maxStreamedResultRows) instead of the inline caps. One transaction, one snapshot.

Errors

The default fails with unsupported; adapters that advertise a streamed budget answer with the framed reply.

AdapterDatabaseSession::close

fn close<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Close the session.

AdapterDatabaseSession::export_identity

fn export_identity<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Vec<DbIdentityHighWater>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Identity high-water from adapter catalogs.

AdapterDatabaseSession::import_identity

fn import_identity<'life0, 'life1, 'async_trait>(
    &'life0 self,
    _rows: &'life1 [DbIdentityHighWater],
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Restore identity high-water into adapter catalogs.

AdapterDatabaseSession::list_user_relations

fn list_user_relations<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

User-visible relation names (excludes engine catalogs).

AdapterDatabaseSession::prepare_unit_restore

fn prepare_unit_restore<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Prepare an open restore transaction (deferred FK checks).

AdapterDatabaseSession::drop_user_relations

fn drop_user_relations<'life0, 'life1, 'async_trait>(
    &'life0 self,
    _names: &'life1 [String],
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Drop named user relations (adapter-owned CASCADE / identity companions).

AdapterDatabaseSession::assert_restore_constraints

fn assert_restore_constraints<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Fail closed when the restore transaction still has FK violations.

AiModels

pub trait AiModels {
    fn health<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn models<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<AiModelList>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn run<'life0, 'async_trait>(
        &'life0 self,
        _params: AiRunParams,
    ) -> Pin<Box<dyn Future<Output = Result<AiRunOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

ai entrypoint: serves models to the host and, through the AI binding, to every plugin with the grant.

The host checks the listing (crate::ai::check_models), each run before it reaches the plugin (crate::ai::check_entrypoint_run_params) and each reply (crate::ai::check_run_output). Outputs are comparable only while the model's revision stays the same, so a plugin changes the revision whenever weights, tokenizer or loaded language packs change.

AiModels::health

fn health<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Liveness / readiness probe: model files present and loadable.

AiModels::models

fn models<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<AiModelList>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Lists the models this plugin serves now. Cheap: it must not load a model.

AiModels::run

fn run<'life0, 'async_trait>(
    &'life0 self,
    _params: AiRunParams,
) -> Pin<Box<dyn Future<Output = Result<AiRunOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Runs the plugin's model params.model on params.input. not_found for a model it does not serve, invalid_params for an input of another task.

Implemented by: AiModelsClient

AiRunner

pub trait AiRunner {
    fn run<'life0, 'async_trait>(
        &'life0 self,
        params: AiRunParams,
    ) -> Pin<Box<dyn Future<Output = Result<AiRunOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

AI binding: runs a model served by a deployed model plugin (Bindings::ai).

The host routes the run to the plugin that serves the named model, or to the model the library chose when the name is a task alias (@library/text-embeddings). The caller must hold a grant for the model's task. Each run has a deadline and counts against the calling plugin's budget; work over many items belongs in a job.

AiRunner::run

fn run<'life0, 'async_trait>(
    &'life0 self,
    params: AiRunParams,
) -> Pin<Box<dyn Future<Output = Result<AiRunOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Runs params.model on params.input. not_found when nothing deployed serves the model, forbidden without the grant for its task, rate_limited over budget, unavailable when the model plugin cannot answer in time.

Implemented by: AiRunnerClient

Cancellation

pub trait Cancellation {
    fn poll<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Transport cancellation. SDKs project this into a locally created AbortSignal (AbortSignal is not a serializable Workers RPC value).

Cancellation::poll

fn poll<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<bool>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Returns true when the host has cancelled this invocation.

Transport or capability failures must surface as Err. Callers must fail closed (abort the invocation) rather than treating a failed poll as "not cancelled".

Implemented by: NeverCancel

ContentSource

pub trait ContentSource {
    fn login<'life0, 'async_trait>(
        &'life0 self,
        _params: LoginParams,
    ) -> Pin<Box<dyn Future<Output = Result<LoginResult>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn scan<'life0, 'async_trait>(
        &'life0 self,
        _params: ScanParams,
    ) -> Pin<Box<dyn Future<Output = Result<ScanPage>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn fetch_title<'life0, 'async_trait>(
        &'life0 self,
        _params: FetchTitleParams,
    ) -> Pin<Box<dyn Future<Output = Result<PlainFetch>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn list_accounts<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<SourceAccount>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn login_start<'life0, 'async_trait>(
        &'life0 self,
        _params: LoginParams,
    ) -> Pin<Box<dyn Future<Output = Result<LoginStartResult>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn login_complete<'life0, 'async_trait>(
        &'life0 self,
        _params: LoginCompleteParams,
    ) -> Pin<Box<dyn Future<Output = Result<LoginResult>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn search_catalog<'life0, 'async_trait>(
        &'life0 self,
        _params: SearchCatalogParams,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn expand_candidates<'life0, 'async_trait>(
        &'life0 self,
        _params: ExpandCandidatesParams,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn purchase_hint<'life0, 'async_trait>(
        &'life0 self,
        _params: PurchaseHintParams,
    ) -> Pin<Box<dyn Future<Output = Result<Option<PurchaseHint>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn purchase_hints<'life0, 'async_trait>(
        &'life0 self,
        params: PurchaseHintsParams,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Option<PurchaseHint>>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn purchase_hint_result<'life0, 'async_trait>(
        &'life0 self,
        params: PurchaseHintParams,
    ) -> Pin<Box<dyn Future<Output = Result<PurchaseHintResult>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn purchase_hints_results<'life0, 'async_trait>(
        &'life0 self,
        params: PurchaseHintsParams,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<PurchaseHintResult>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn list_deals<'life0, 'async_trait>(
        &'life0 self,
        _params: ListDealsParams,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn catalog_detail<'life0, 'async_trait>(
        &'life0 self,
        _params: CatalogDetailParams,
    ) -> Pin<Box<dyn Future<Output = Result<Option<CatalogHit>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn quality_offers<'life0, 'async_trait>(
        &'life0 self,
        _params: QualityOffersParams,
    ) -> Pin<Box<dyn Future<Output = Result<QualityOffersResult>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn revoke_account<'life0, 'async_trait>(
        &'life0 self,
        _params: RevokeAccountParams,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn health<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn diagnose<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Storefront content source (not byte Source).

Every method takes and returns the typed Cap'n Proto payload structs from crate::generated; absent methods return PluginError::unsupported.

ContentSource::login

fn login<'life0, 'async_trait>(
    &'life0 self,
    _params: LoginParams,
) -> Pin<Box<dyn Future<Output = Result<LoginResult>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Password or one-shot OAuth login. The host seals LoginResult::credentials into encrypted_secrets.

ContentSource::scan

fn scan<'life0, 'async_trait>(
    &'life0 self,
    _params: ScanParams,
) -> Pin<Box<dyn Future<Output = Result<ScanPage>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

One page of one account's library scan pass; the host upserts ScanPage::books and drives the pass by next_cursor.

ContentSource::fetch_title

fn fetch_title<'life0, 'async_trait>(
    &'life0 self,
    _params: FetchTitleParams,
) -> Pin<Box<dyn Future<Output = Result<PlainFetch>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Fetch one title into params.cache_dir and return plain media paths.

ContentSource::list_accounts

fn list_accounts<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Vec<SourceAccount>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Accounts the guest knows about.

ContentSource::login_start

fn login_start<'life0, 'async_trait>(
    &'life0 self,
    _params: LoginParams,
) -> Pin<Box<dyn Future<Output = Result<LoginStartResult>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Begin an interactive OAuth login.

ContentSource::login_complete

fn login_complete<'life0, 'async_trait>(
    &'life0 self,
    _params: LoginCompleteParams,
) -> Pin<Box<dyn Future<Output = Result<LoginResult>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Finish an interactive OAuth login started by Self::login_start.

ContentSource::search_catalog

fn search_catalog<'life0, 'async_trait>(
    &'life0 self,
    _params: SearchCatalogParams,
) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Free-text storefront catalog search.

ContentSource::expand_candidates

fn expand_candidates<'life0, 'async_trait>(
    &'life0 self,
    _params: ExpandCandidatesParams,
) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Related-title expansion from a seed title.

ContentSource::purchase_hint

fn purchase_hint<'life0, 'async_trait>(
    &'life0 self,
    _params: PurchaseHintParams,
) -> Pin<Box<dyn Future<Output = Result<Option<PurchaseHint>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Purchase link / price hint; Ok(None) when the title is unknown.

ContentSource::purchase_hints

fn purchase_hints<'life0, 'async_trait>(
    &'life0 self,
    params: PurchaseHintsParams,
) -> Pin<Box<dyn Future<Output = Result<Vec<Option<PurchaseHint>>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Purchase links / price hints for several titles in one call, one answer per query in order.

The default asks Self::purchase_hint for each query, PURCHASE_HINTS_CONCURRENCY at a time, queries that already name a product id first (one lookup each) and title searches after, and stops at the first error. It starts no lookup once PURCHASE_HINTS_BUDGET has passed and answers None for the rest, so the host's batch gets what the store managed instead of nothing. A guest whose backend prices many products per request overrides this to make one request. A rate_limited error applies to the whole batch.

ContentSource::purchase_hint_result

fn purchase_hint_result<'life0, 'async_trait>(
    &'life0 self,
    params: PurchaseHintParams,
) -> Pin<Box<dyn Future<Output = Result<PurchaseHintResult>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Self::purchase_hint with the priced records a title search matched (PurchaseHintResult.records), for a host that asked with lookup = title.

The default wraps Self::purchase_hint and returns no records, so the host falls back to the bare hint. A guest that can tell its search results apart (identifiers, credits, kinds) overrides this and Self::purchase_hints_results.

ContentSource::purchase_hints_results

fn purchase_hints_results<'life0, 'async_trait>(
    &'life0 self,
    params: PurchaseHintsParams,
) -> Pin<Box<dyn Future<Output = Result<Vec<PurchaseHintResult>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Self::purchase_hints with each query's priced records, as Self::purchase_hint_result gives them for one query.

The default wraps Self::purchase_hints and returns no records.

ContentSource::list_deals

fn list_deals<'life0, 'async_trait>(
    &'life0 self,
    _params: ListDealsParams,
) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Current storefront deals.

ContentSource::catalog_detail

fn catalog_detail<'life0, 'async_trait>(
    &'life0 self,
    _params: CatalogDetailParams,
) -> Pin<Box<dyn Future<Output = Result<Option<CatalogHit>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Full catalog record for one product; Ok(None) when unknown.

ContentSource::quality_offers

fn quality_offers<'life0, 'async_trait>(
    &'life0 self,
    _params: QualityOffersParams,
) -> Pin<Box<dyn Future<Output = Result<QualityOffersResult>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

The audio quality params.account_id would download for each title today, one answer per title id in order. It must not license or download anything; the host asks only when the guest declares CatalogCapabilities.quality_offers.

Errors

The default answers unsupported; a store's own error fails the whole batch.

ContentSource::revoke_account

fn revoke_account<'life0, 'async_trait>(
    &'life0 self,
    _params: RevokeAccountParams,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Undo store-side state for one account before the host deletes its stored credentials, such as deregistering the device registered at login.

The default does nothing, which is right for stores that keep no per-login state.

Errors

Returns an error when the store rejects the sign-out. The host logs it and revokes the account anyway.

ContentSource::health

fn health<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Storefront health.

ContentSource::diagnose

fn diagnose<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Operator-facing diagnostic lines.

Implemented by: ContentSourceClient

CoverFetcher

pub trait CoverFetcher {
    fn health<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn fetch_covers<'life0, 'async_trait>(
        &'life0 self,
        _params: CoverFetchParams,
        _sink: Box<dyn Destination>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<CoverImage>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

covers entrypoint: downloads cover images on the host's behalf.

The fetcher only transports bytes. Each body goes into sink under its index in params.urls ("0", "1", ...), and the host sniffs, decodes and re-encodes it before anything stores or serves it.

CoverFetcher::health

fn health<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Liveness / readiness probe.

CoverFetcher::fetch_covers

fn fetch_covers<'life0, 'async_trait>(
    &'life0 self,
    _params: CoverFetchParams,
    _sink: Box<dyn Destination>,
) -> Pin<Box<dyn Future<Output = Result<Vec<CoverImage>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Fetches every URL in params.urls and puts each body into sink under its index. Returns one CoverImage per URL, in request order; a URL that failed carries error and stored = false rather than failing the whole call.

Implemented by: CoverFetcherClient

Database

pub trait Database {
    fn open_session<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Box<dyn AdapterDatabaseSession>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn drop_unit<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _unit_ref: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn host_session(&self) -> Option<Box<dyn HostAdapterDatabaseSession>>;
}

Database factory. Sessions cannot survive suspension.

Database::open_session

fn open_session<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Box<dyn AdapterDatabaseSession>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Opens an invocation-scoped adapter session.

Database::drop_unit

fn drop_unit<'life0, 'life1, 'async_trait>(
    &'life0 self,
    _unit_ref: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Physically deletes one provisioned binding unit.

unit_ref is the adapter-native identity recorded in plugin_databases (SQLite file path, PostgreSQL database name, D1 database name, or a third-party instance id). Missing units are success so the host can remove the registry row. The default is unsupported: adapters that cannot prove deletion must fail closed.

Database::host_session

fn host_session(&self) -> Option<Box<dyn HostAdapterDatabaseSession>>

Host-private interactive-transaction view of the adapter connection.

First-party adapters override this. The default advertises no host machinery; hosts then fall back to the public typed execute plane.

Implemented by: DatabaseClient

Destination

pub trait Destination {
    fn head<'life0, 'life1, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Option<ObjectMetadata>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn list<'life0, 'async_trait>(
        &'life0 self,
        options: ListOptions,
    ) -> Pin<Box<dyn Future<Output = Result<ListPage>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn get<'life0, 'life1, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
        range: Option<ByteRange>,
    ) -> Pin<Box<dyn Future<Output = Result<ReadResult>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn put<'life0, 'life1, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
        body: Pin<Box<dyn AsyncRead + Send>>,
        options: WriteOptions,
    ) -> Pin<Box<dyn Future<Output = Result<PutResult>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn copy<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        from: &'life1 str,
        to: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<CopyResult>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,;
    fn delete<'life0, 'life1, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn commit<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _key: &'life1 str,
        _commit_token: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<PutResult>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,;
    fn abort_stage<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _key: &'life1 str,
        _commit_token: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,;
    fn move_object<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _from: &'life1 str,
        _to: &'life2 str,
        _options: MoveOptions,
    ) -> Pin<Box<dyn Future<Output = Result<MoveResult>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,;
    fn move_many<'life0, 'async_trait>(
        &'life0 self,
        _request: MoveManyRequest,
    ) -> Pin<Box<dyn Future<Output = Result<MoveManyPage>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn delete_many<'life0, 'async_trait>(
        &'life0 self,
        _keys: Vec<String>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<KeyOutcome>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn head_many<'life0, 'async_trait>(
        &'life0 self,
        _keys: Vec<String>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Option<ObjectMetadata>>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn changes<'life0, 'async_trait>(
        &'life0 self,
        _request: ChangesRequest,
    ) -> Pin<Box<dyn Future<Output = Result<ChangesPage>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn translate_keys<'life0, 'async_trait>(
        &'life0 self,
        _keys: Vec<String>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Destination capability (storage).

Cap'n Proto stubs are !Send; call these traits from a LocalSet.

Destination::head

fn head<'life0, 'life1, 'async_trait>(
    &'life0 self,
    key: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Option<ObjectMetadata>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Metadata without a body; Ok(None) when the key is missing.

Destination::list

fn list<'life0, 'async_trait>(
    &'life0 self,
    options: ListOptions,
) -> Pin<Box<dyn Future<Output = Result<ListPage>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

One page of keys under options.prefix.

Destination::get

fn get<'life0, 'life1, 'async_trait>(
    &'life0 self,
    key: &'life1 str,
    range: Option<ByteRange>,
) -> Pin<Box<dyn Future<Output = Result<ReadResult>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Streamed read. The body is a transferred stream, not a scalar.

Destination::put

fn put<'life0, 'life1, 'async_trait>(
    &'life0 self,
    key: &'life1 str,
    body: Pin<Box<dyn AsyncRead + Send>>,
    options: WriteOptions,
) -> Pin<Box<dyn Future<Output = Result<PutResult>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Streamed write. body ownership is transferred to the destination.

When WriteOptions::stage_only is true, bytes stream into destination-managed temporary/multipart storage and are not published until Self::commit. Hosts, adapters, brokers, and guests must not spool the complete object locally.

Destination::copy

fn copy<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    from: &'life1 str,
    to: &'life2 str,
) -> Pin<Box<dyn Future<Output = Result<CopyResult>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,

Server-side copy when the backend supports it.

Destination::delete

fn delete<'life0, 'life1, 'async_trait>(
    &'life0 self,
    key: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Delete a key (no-op if missing).

Destination::commit

fn commit<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    _key: &'life1 str,
    _commit_token: &'life2 str,
) -> Pin<Box<dyn Future<Output = Result<PutResult>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,

Finalize a destination-side staged object using commit_token.

Destination::abort_stage

fn abort_stage<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    _key: &'life1 str,
    _commit_token: &'life2 str,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,

Abort a destination-side staged object.

Destination::move_object

fn move_object<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    _from: &'life1 str,
    _to: &'life2 str,
    _options: MoveOptions,
) -> Pin<Box<dyn Future<Output = Result<MoveResult>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,

Move one object (storage.move). Repeating a finished move succeeds with crate::MoveResult::already_moved.

Destination::move_many

fn move_many<'life0, 'async_trait>(
    &'life0 self,
    _request: MoveManyRequest,
) -> Pin<Box<dyn Future<Output = Result<MoveManyPage>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Move a set of objects or a whole prefix (storage.moveMany), one page per call. Safe to repeat.

Destination::delete_many

fn delete_many<'life0, 'async_trait>(
    &'life0 self,
    _keys: Vec<String>,
) -> Pin<Box<dyn Future<Output = Result<Vec<KeyOutcome>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Remove up to crate::MAX_BATCH_KEYS objects (storage.deleteMany), one outcome per key in order. A missing key succeeds.

Destination::head_many

fn head_many<'life0, 'async_trait>(
    &'life0 self,
    _keys: Vec<String>,
) -> Pin<Box<dyn Future<Output = Result<Vec<Option<ObjectMetadata>>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Probe up to crate::MAX_BATCH_KEYS objects (storage.headMany), one entry per key in order; None when the key is missing.

Destination::changes

fn changes<'life0, 'async_trait>(
    &'life0 self,
    _request: ChangesRequest,
) -> Pin<Box<dyn Future<Output = Result<ChangesPage>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Keys changed since a cursor (storage.changes).

Destination::translate_keys

fn translate_keys<'life0, 'async_trait>(
    &'life0 self,
    _keys: Vec<String>,
) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Translate up to crate::MAX_BATCH_KEYS host keys into the keys this destination stores them under (storage.translateKeys), one per host key in order. The same host key must always translate to the same key.

Implemented by: DestinationClient

EventConsumer

pub trait EventConsumer {
    fn event<'life0, 'async_trait>(
        &'life0 self,
        batch: Vec<DomainEvent>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<EventResult>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

[[events.consumers]] handler (Entrypoints::event_consumer).

Delivery is at-least-once; consume idempotently on DomainEvent::deduplication_key.

EventConsumer::event

fn event<'life0, 'async_trait>(
    &'life0 self,
    batch: Vec<DomainEvent>,
) -> Pin<Box<dyn Future<Output = Result<Vec<EventResult>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Handles one ordered batch and returns exactly one EventResult per input event, in order. A short reply is a host-side error: the missing tail is redelivered.

Implemented by: EventConsumerClient

EventPublisher

pub trait EventPublisher {
    fn publish<'life0, 'async_trait>(
        &'life0 self,
        event: PluginEvent,
    ) -> Pin<Box<dyn Future<Output = Result<PublishOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn read<'life0, 'async_trait>(
        &'life0 self,
        request: EventReadRequest,
    ) -> Pin<Box<dyn Future<Output = Result<EventReadPage>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

EVENTS binding: host-served outbox publisher (Bindings::events).

EventPublisher::publish

fn publish<'life0, 'async_trait>(
    &'life0 self,
    event: PluginEvent,
) -> Pin<Box<dyn Future<Output = Result<PublishOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Appends event to the host outbox. The host stamps source (this plugin id) and the invocation account; event_type must be listed in [[events.producers]].

EventPublisher::read

fn read<'life0, 'async_trait>(
    &'life0 self,
    request: EventReadRequest,
) -> Pin<Box<dyn Future<Output = Result<EventReadPage>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Reads one page of past outbox events the instance subscribes to, oldest first, so a plugin can catch up after a gap.

Only types the instance's consented [[events.consumers]] rows subscribe to come back, through the same schema-version and filter match as delivery, and only back to [events].retention_days.

Errors

The default refuses with unsupported; the host publisher validates the request with crate::validate_event_read_request.

Implemented by: EventPublisherClient

GuestDatabase

pub trait GuestDatabase {
    fn execute<'life0, 'async_trait>(
        &'life0 self,
        request: ExecuteRequest,
    ) -> Pin<Box<dyn Future<Output = Result<ExecuteReply>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn close<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn limits<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<DbCapabilities>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn execute_streamed<'life0, 'async_trait>(
        &'life0 self,
        request: ExecuteRequest,
    ) -> Pin<Box<dyn Future<Output = Result<ExecuteStream>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Host-granted SQL transport for job plugin authors (no capabilities).

GuestDatabase::execute

fn execute<'life0, 'async_trait>(
    &'life0 self,
    request: ExecuteRequest,
) -> Pin<Box<dyn Future<Output = Result<ExecuteReply>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Host-mediated typed batch (execute).

GuestDatabase::close

fn close<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Close the grant.

GuestDatabase::limits

fn limits<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<DbCapabilities>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Negotiated limits of this session (DbCapabilities), so a guest can size requests and reads before sending.

Errors

Hosts answer with the adapter's advertisement; the default fails with unsupported for sessions that predate the method.

GuestDatabase::execute_streamed

fn execute_streamed<'life0, 'async_trait>(
    &'life0 self,
    request: ExecuteRequest,
) -> Pin<Box<dyn Future<Output = Result<ExecuteStream>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

execute whose reply is framed and counted against the session's streamed budget, so a result past the inline caps still arrives whole.

Errors

The default fails with unsupported for sessions that predate the method or advertise no streamed budget.

Ingress

pub trait Ingress {
    fn start<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<IngressStarted>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn health<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<IngressHealth>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn stop<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

ingress entrypoint: a public address provider (a relay, or a dynamic DNS name). The library runs at most one at a time.

Ingress::start

fn start<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<IngressStarted>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Brings the public address up and answers the origin it serves.

Ingress::health

fn health<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<IngressHealth>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Whether the public address is serving now.

Ingress::stop

fn stop<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Takes the public address down; stopping a stopped one is not an error.

Implemented by: IngressClient

JobRunner

pub trait JobRunner {
    fn job<'life0, 'async_trait>(
        &'life0 self,
        controller: JobController,
    ) -> Pin<Box<dyn Future<Output = Result<JobOutcome>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

[triggers] jobs handler (Entrypoints::job_runner).

JobRunner::job

fn job<'life0, 'async_trait>(
    &'life0 self,
    controller: JobController,
) -> Pin<Box<dyn Future<Output = Result<JobOutcome>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Runs controller.invocation using the granted capabilities until completion, suspension, or cancellation.

Implemented by: JobRunnerClient, StreamCopyHandler

KvNamespace

pub trait KvNamespace {
    fn get<'life0, 'async_trait>(
        &'life0 self,
        key: String,
    ) -> Pin<Box<dyn Future<Output = Result<KvGetOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn put<'life0, 'async_trait>(
        &'life0 self,
        key: String,
        value: Vec<u8>,
        options: KvPutOptions,
    ) -> Pin<Box<dyn Future<Output = Result<KvPutOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn delete<'life0, 'async_trait>(
        &'life0 self,
        key: String,
    ) -> Pin<Box<dyn Future<Output = Result<KvDeleteOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn list<'life0, 'async_trait>(
        &'life0 self,
        options: KvListOptions,
    ) -> Pin<Box<dyn Future<Output = Result<KvListOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Durable key/value namespace: Workers KVNamespace-shaped binding the host serves from the library database, scoped to the plugin and the namespace a [[kv_namespaces]] row names. Values live in the library, so an instance moved to another host reads its own keys.

KvNamespace::get

fn get<'life0, 'async_trait>(
    &'life0 self,
    key: String,
) -> Pin<Box<dyn Future<Output = Result<KvGetOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Reads one key; found = false when absent or expired.

KvNamespace::put

fn put<'life0, 'async_trait>(
    &'life0 self,
    key: String,
    value: Vec<u8>,
    options: KvPutOptions,
) -> Pin<Box<dyn Future<Output = Result<KvPutOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Writes one key, replacing any previous value and metadata.

KvNamespace::delete

fn delete<'life0, 'async_trait>(
    &'life0 self,
    key: String,
) -> Pin<Box<dyn Future<Output = Result<KvDeleteOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Deletes one key; a missing key is not an error.

KvNamespace::list

fn list<'life0, 'async_trait>(
    &'life0 self,
    options: KvListOptions,
) -> Pin<Box<dyn Future<Output = Result<KvListOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Lists keys in lexical order, one page at a time.

Implemented by: KvNamespaceClient

MetadataFiles

pub trait MetadataFiles {
    fn health<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn parse<'life0, 'async_trait>(
        &'life0 self,
        _params: MetadataFileParseParams,
    ) -> Pin<Box<dyn Future<Output = Result<MetadataFileParsed>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn render<'life0, 'async_trait>(
        &'life0 self,
        _params: MetadataFileRenderParams,
    ) -> Pin<Box<dyn Future<Output = Result<MetadataFileRendered>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

metadataFiles entrypoint: converts metadata files (sidecars) next to an edition's media to and from crate::MetadataFileRecords.

The plugin only converts bytes; the host reads and writes every file and checks every record it returns (see crate::metadata_files). Methods a plugin does not serve keep the default, which returns typed unsupported.

MetadataFiles::health

fn health<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Liveness / readiness probe.

MetadataFiles::parse

fn parse<'life0, 'async_trait>(
    &'life0 self,
    _params: MetadataFileParseParams,
) -> Pin<Box<dyn Future<Output = Result<MetadataFileParsed>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

What the file in params.bytes says, read as params.dialect. A file the dialect cannot read is an invalid_params error.

MetadataFiles::render

fn render<'life0, 'async_trait>(
    &'life0 self,
    _params: MetadataFileRenderParams,
) -> Pin<Box<dyn Future<Output = Result<MetadataFileRendered>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

params.existing with the fields in params.fields set to the record's values, everything else kept.

Implemented by: MetadataFilesClient

MetadataProvider

pub trait MetadataProvider {
    fn health<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn lookup<'life0, 'async_trait>(
        &'life0 self,
        _params: MetadataLookupParams,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<MetadataRecord>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn search<'life0, 'async_trait>(
        &'life0 self,
        _params: MetadataSearchParams,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<MetadataRecord>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn chapters<'life0, 'async_trait>(
        &'life0 self,
        _params: MetadataChaptersParams,
    ) -> Pin<Box<dyn Future<Output = Result<MetadataChapters>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

metadata entrypoint: bibliographic lookups against a public catalog.

A provider describes the editions it finds as MetadataRecords; the host decides identity. Methods a provider does not serve keep the default, which returns typed unsupported.

MetadataProvider::health

fn health<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Liveness / readiness probe.

MetadataProvider::lookup

fn lookup<'life0, 'async_trait>(
    &'life0 self,
    _params: MetadataLookupParams,
) -> Pin<Box<dyn Future<Output = Result<Vec<MetadataRecord>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Records for the editions params.identifiers name, in relevance order.

MetadataProvider::search

fn search<'life0, 'async_trait>(
    &'life0 self,
    _params: MetadataSearchParams,
) -> Pin<Box<dyn Future<Output = Result<Vec<MetadataRecord>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Records matching params.title (and params.author when set), in relevance order.

MetadataProvider::chapters

fn chapters<'life0, 'async_trait>(
    &'life0 self,
    _params: MetadataChaptersParams,
) -> Pin<Box<dyn Future<Output = Result<MetadataChapters>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Chapter layout of the edition params.identifiers name; found is false when the provider has none.

Implemented by: MetadataProviderClient

NotificationRaiser

pub trait NotificationRaiser {
    fn raise<'life0, 'async_trait>(
        &'life0 self,
        params: NotifyRaiseParams,
    ) -> Pin<Box<dyn Future<Output = Result<NotifyRaised>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

NOTIFY binding: raises the notification types the plugin declares in [[notifications.types]] (Bindings::notify).

The host router applies the administrators' routing rules and each patron's preferences; the raising plugin never learns where the notification went.

NotificationRaiser::raise

fn raise<'life0, 'async_trait>(
    &'life0 self,
    params: NotifyRaiseParams,
) -> Pin<Box<dyn Future<Output = Result<NotifyRaised>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Raises one notification. The type must be one the plugin declared (without the plugin prefix the host adds); a patron-audience type names a patron inside the invocation's account scope. Raises are rate-limited per instance (rate_limited).

Implemented by: NotificationRaiserClient

Notifier

pub trait Notifier {
    fn health<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn send<'life0, 'async_trait>(
        &'life0 self,
        _params: NotifySendParams,
    ) -> Pin<Box<dyn Future<Output = Result<NotifySent>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn validate_destination<'life0, 'async_trait>(
        &'life0 self,
        params: NotifyValidateParams,
    ) -> Pin<Box<dyn Future<Output = Result<NotifyValidated>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

notifier entrypoint: delivers one host-rendered notification to one destination.

The host decides what is worth a notification, who gets it and which instance carries it, renders the message, and checks it (crate::notifications::check_send_params) before it reaches the plugin. Each send is one claimed notify.send job, so the host owns retries: answer rate_limited (with the service's Retry-After) or unavailable to be retried; any other error fails that destination.

Notifier::health

fn health<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Liveness / readiness probe: credentials and reachability.

Notifier::send

fn send<'life0, 'async_trait>(
    &'life0 self,
    _params: NotifySendParams,
) -> Pin<Box<dyn Future<Output = Result<NotifySent>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Delivers params.message to params.destination.

Notifier::validate_destination

fn validate_destination<'life0, 'async_trait>(
    &'life0 self,
    params: NotifyValidateParams,
) -> Pin<Box<dyn Future<Output = Result<NotifyValidated>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Normalises and checks a patron's address document before the host saves it; an address the plugin refuses is invalid_params. The default accepts the document unchanged.

Implemented by: NotifierClient

Oidc

pub trait Oidc {
    fn clients<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<OidcClientTemplate>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn authenticate_user<'life0, 'async_trait>(
        &'life0 self,
        _params: AuthenticateUserParams,
    ) -> Pin<Box<dyn Future<Output = Result<ExternalUser>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

oidc entrypoint: relying-party client templates and credential verification on behalf of the host authorization server.

Oidc::clients

fn clients<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Vec<OidcClientTemplate>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Plugin-provided OIDC authorization-server client templates. Empty when the guest only verifies credentials.

Oidc::authenticate_user

fn authenticate_user<'life0, 'async_trait>(
    &'life0 self,
    _params: AuthenticateUserParams,
) -> Pin<Box<dyn Future<Output = Result<ExternalUser>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Verify remote credentials on behalf of the host.

Implemented by: OidcClient

Origin

pub trait Origin {
    fn fetch<'life0, 'async_trait>(
        &'life0 self,
        request: CheckedOriginRequest,
        body: Option<Pin<Box<dyn AsyncRead + Send>>>,
    ) -> Pin<Box<dyn Future<Output = Result<OriginReply>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

The library as a relay ingress plugin reaches it, granted on Bindings::origin (ORIGIN in the Workers idiom).

The host serves it and treats every request as the tunnel transport: public https, never loopback, with the client address the plugin reports. The guest calls it for each request its provider delivers.

Origin::fetch

fn fetch<'life0, 'async_trait>(
    &'life0 self,
    request: CheckedOriginRequest,
    body: Option<Pin<Box<dyn AsyncRead + Send>>>,
) -> Pin<Box<dyn Future<Output = Result<OriginReply>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Serves one request and answers once the response head is ready; the body streams after.

Arguments
Errors

invalid_params for a request refused before the library saw it; unavailable when the library cannot serve now. Any HTTP status, errors included, is an Ok answer.

Implemented by: NoOrigin, OriginClient

PluginCli

pub trait PluginCli {
    fn describe<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<CliSchema>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn invoke<'life0, 'async_trait>(
        &'life0 self,
        _params: CliInvokeParams,
    ) -> Pin<Box<dyn Future<Output = Result<CliInvokeResult>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

cli entrypoint: guest commands under bookclerk plugins <id> <command>.

PluginCli::describe

fn describe<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<CliSchema>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Declared CLI surface. Empty when the guest exposes no commands.

PluginCli::invoke

fn invoke<'life0, 'async_trait>(
    &'life0 self,
    _params: CliInvokeParams,
) -> Pin<Box<dyn Future<Output = Result<CliInvokeResult>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Runs one plugin CLI command.

Implemented by: PluginCliClient

PluginWorker

pub trait PluginWorker: 'static {
    fn describe<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<PluginDescribe>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn open<'life0, 'async_trait>(
        &'life0 self,
        invocation: Invocation,
        bindings: Bindings,
    ) -> Pin<Box<dyn Future<Output = Result<Entrypoints>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn database_migrations<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _binding: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<PluginMigration>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn shutdown<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Root PluginWorker capability (describe / open / shutdown).

describe() advertises typed capabilities; the verified install receipt plus the operator grant is the host allowlist. open() returns the exported Entrypoints for one invocation.

PluginWorker::describe

fn describe<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<PluginDescribe>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Advertises identity, features, and scalar limits.

PluginWorker::open

fn open<'life0, 'async_trait>(
    &'life0 self,
    invocation: Invocation,
    bindings: Bindings,
) -> Pin<Box<dyn Future<Output = Result<Entrypoints>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Opens the exported entrypoints for invocation with the granted bindings.

PluginWorker::database_migrations

fn database_migrations<'life0, 'life1, 'async_trait>(
    &'life0 self,
    _binding: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Vec<PluginMigration>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Complete ordered plugin-owned migration sequence for one named binding.

Called while the host provisions [[databases]], before the binding session is handed out on Bindings::databases. Empty means the binding has no plugin-owned migrations. id values are opaque plugin-chosen identities; registration order is the forward sequence.

PluginWorker::shutdown

fn shutdown<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Releases guest resources.

ProgressSink

pub trait ProgressSink {
    fn report<'life0, 'life1, 'async_trait>(
        &'life0 self,
        percent: f32,
        message: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
}

Progress reports for a job invocation (never carries media).

ProgressSink::report

fn report<'life0, 'life1, 'async_trait>(
    &'life0 self,
    percent: f32,
    message: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Reports percent in 0..=100 and an operator-facing message.

QueueConsumer

pub trait QueueConsumer {
    fn queue<'life0, 'async_trait>(
        &'life0 self,
        batch: QueueBatch,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<QueueResult>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

[[queues.consumers]] handler (Entrypoints::queue_consumer).

Delivery is at-least-once; consume idempotently on QueueMessage::id.

QueueConsumer::queue

fn queue<'life0, 'async_trait>(
    &'life0 self,
    batch: QueueBatch,
) -> Pin<Box<dyn Future<Output = Result<Vec<QueueResult>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Handles one ordered batch from one queue and returns exactly one QueueResult per message, in order. A short reply is a host-side error: the missing tail is redelivered.

Implemented by: QueueConsumerClient

QueueProducer

pub trait QueueProducer {
    fn send<'life0, 'async_trait>(
        &'life0 self,
        message: QueueSendMessage,
    ) -> Pin<Box<dyn Future<Output = Result<QueueSendOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn send_batch<'life0, 'async_trait>(
        &'life0 self,
        messages: Vec<QueueSendMessage>,
        delay_seconds: u32,
    ) -> Pin<Box<dyn Future<Output = Result<QueueSendOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Queue producer binding: host-served send into the queue a [[queues.producers]] row names (Bindings::queues).

QueueProducer::send

fn send<'life0, 'async_trait>(
    &'life0 self,
    message: QueueSendMessage,
) -> Pin<Box<dyn Future<Output = Result<QueueSendOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Sends one message; the host stamps source and assigns the id.

QueueProducer::send_batch

fn send_batch<'life0, 'async_trait>(
    &'life0 self,
    messages: Vec<QueueSendMessage>,
    delay_seconds: u32,
) -> Pin<Box<dyn Future<Output = Result<QueueSendOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Sends up to MAX_LIST_PAGE messages in order. delay_seconds applies to every message whose own delay is zero.

Implemented by: QueueProducerClient

RemoteLibrary

pub trait RemoteLibrary {
    fn health<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn start<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn stop<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn diagnose<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn scan_library<'life0, 'async_trait>(
        &'life0 self,
        _params: ScanLibraryParams,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn sync_listening<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<ListeningProgress>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn poll_events<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<ExternalUser>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

remoteLibrary entrypoint: long-running remote-library lifecycle.

Event delivery is EventConsumer; credential verification is Oidc.

RemoteLibrary::health

fn health<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Liveness.

RemoteLibrary::start

fn start<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Start long-running work after the host has granted bindings.

RemoteLibrary::stop

fn stop<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Stop long-running work.

RemoteLibrary::diagnose

fn diagnose<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Operator-facing diagnostic lines.

RemoteLibrary::scan_library

fn scan_library<'life0, 'async_trait>(
    &'life0 self,
    _params: ScanLibraryParams,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Re-sync the remote library.

RemoteLibrary::sync_listening

fn sync_listening<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Vec<ListeningProgress>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Push / pull listening progress; the host upserts the rows.

RemoteLibrary::poll_events

fn poll_events<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Vec<ExternalUser>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Drain external users observed since the last poll.

Implemented by: RemoteLibraryClient

ScheduledHandler

pub trait ScheduledHandler {
    fn scheduled<'life0, 'async_trait>(
        &'life0 self,
        controller: ScheduledController,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

[triggers] crons handler (Entrypoints::scheduled_handler), the Workers scheduled(controller) trigger.

Each fire is delivered at least once: an error is retried with backoff, keeping ScheduledController::fire_id and scheduled_time, so dedupe on the fire id.

ScheduledHandler::scheduled

fn scheduled<'life0, 'async_trait>(
    &'life0 self,
    controller: ScheduledController,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Runs one cron fire to completion.

Implemented by: ScheduledHandlerClient

SocketHandler

pub trait SocketHandler {
    fn message<'life0, 'async_trait>(
        &'life0 self,
        _event: SocketMessage,
    ) -> Pin<Box<dyn Future<Output = Result<SocketMessageOk>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn closed<'life0, 'async_trait>(
        &'life0 self,
        _event: SocketClosed,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

[sockets] handler: what arrives on host-brokered sockets.

SocketHandler::message

fn message<'life0, 'async_trait>(
    &'life0 self,
    _event: SocketMessage,
) -> Pin<Box<dyn Future<Output = Result<SocketMessageOk>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

One message arrived on an open socket.

The reply may ask the host to poll the plugin's events now (SocketMessageOk::poll_events), when the message announced something the poll hands over.

SocketHandler::closed

fn closed<'life0, 'async_trait>(
    &'life0 self,
    _event: SocketClosed,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

A socket closed. The default ignores it.

Implemented by: SocketHandlerClient

Sockets

pub trait Sockets {
    fn connect<'life0, 'async_trait>(
        &'life0 self,
        request: SocketConnectRequest,
    ) -> Pin<Box<dyn Future<Output = Result<SocketInfo>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn send<'life0, 'async_trait>(
        &'life0 self,
        socket: String,
        frame: SocketFrame,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn close<'life0, 'async_trait>(
        &'life0 self,
        socket: String,
        code: u16,
        reason: String,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn set_attachment<'life0, 'async_trait>(
        &'life0 self,
        socket: String,
        attachment: Vec<u8>,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn list<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<SocketInfo>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Host-brokered outbound WebSockets granted on Bindings::sockets.

A broker the host runs for the plugin instance holds each socket, so a socket outlives the invocation that opened it and stays open while the guest sleeps. Messages arrive on Entrypoints::socket_handler.

Sockets::connect

fn connect<'life0, 'async_trait>(
    &'life0 self,
    request: SocketConnectRequest,
) -> Pin<Box<dyn Future<Output = Result<SocketInfo>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Opens a socket to request.url, which must be on the plugin's network grant, and returns it once the handshake finished.

Sockets::send

fn send<'life0, 'async_trait>(
    &'life0 self,
    socket: String,
    frame: SocketFrame,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Sends one message on an open socket.

Sockets::close

fn close<'life0, 'async_trait>(
    &'life0 self,
    socket: String,
    code: u16,
    reason: String,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Closes a socket; closing an unknown or closed socket is not an error. A zero code sends 1000.

Sockets::set_attachment

fn set_attachment<'life0, 'async_trait>(
    &'life0 self,
    socket: String,
    attachment: Vec<u8>,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Replaces the attachment the host keeps for a socket.

Sockets::list

fn list<'life0, 'async_trait>(
    &'life0 self,
) -> Pin<Box<dyn Future<Output = Result<Vec<SocketInfo>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

The instance's open sockets, oldest first.

Implemented by: SocketsClient

Source

pub trait Source {
    fn open<'life0, 'life1, 'async_trait>(
        &'life0 self,
        key: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<ReadResult>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
}

Source capability that can open a named object as a stream.

Source::open

fn open<'life0, 'life1, 'async_trait>(
    &'life0 self,
    key: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<ReadResult>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Opens key for streamed reading.

Implemented by: SourceClient

WebhookHandler

pub trait WebhookHandler {
    fn delivered<'life0, 'async_trait>(
        &'life0 self,
        _event: WebhookDelivered,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

[[webhooks]] handler: told when the host stored deliveries.

WebhookHandler::delivered

fn delivered<'life0, 'async_trait>(
    &'life0 self,
    _event: WebhookDelivered,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

The host stored deliveries for one webhook; the guest pulls them through Bindings::webhooks. The default ignores the call, and the plugin reads deliveries on its own schedule.

Implemented by: WebhookHandlerClient

Webhooks

pub trait Webhooks {
    fn url<'life0, 'async_trait>(
        &'life0 self,
        name: String,
    ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn pull<'life0, 'async_trait>(
        &'life0 self,
        request: WebhookPullRequest,
    ) -> Pin<Box<dyn Future<Output = Result<WebhookPullPage>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
    fn ack<'life0, 'async_trait>(
        &'life0 self,
        request: WebhookAckRequest,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Host-served inbound webhooks granted on Bindings::webhooks.

The host serves each [[webhooks]] row at a secret URL under the library's public origin, checks and stores each request, and keeps it until the guest acknowledges it or it expires. The methods are shaped like a pulled queue so a feed can treat webhook deliveries and queue messages alike.

Webhooks::url

fn url<'life0, 'async_trait>(
    &'life0 self,
    name: String,
) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

The URL an outside service should call for webhook name; None when the library cannot be reached from the Internet or webhooks are turned off.

Webhooks::pull

fn pull<'life0, 'async_trait>(
    &'life0 self,
    request: WebhookPullRequest,
) -> Pin<Box<dyn Future<Output = Result<WebhookPullPage>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Leases up to request.batch_size waiting deliveries, oldest first.

Webhooks::ack

fn ack<'life0, 'async_trait>(
    &'life0 self,
    request: WebhookAckRequest,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Deletes acknowledged deliveries and offers retried ones again.

Implemented by: WebhooksClient

Structs

GuestReceiptPersist

pub struct GuestReceiptPersist {
    pub guest_statement_len: u32,
    pub guest_request_hash: String,
}

Host-stamped hint for adapters to persist guest replay payload before COMMIT.

Fields

  • guest_statement_len: Guest statement count inside the receipt wrap (excluding prune/select).
  • guest_request_hash: Guest requestHash compared on replay.

GuestReceiptPersist::is_absent

pub fn is_absent(&self) -> bool

True when the host did not stamp a guest-receipt finalize hint.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

AdapterExecuteRequest

pub struct AdapterExecuteRequest {
    pub request: ExecuteRequest,
    pub guest_receipt: GuestReceiptPersist,
    pub proofs: Vec<ResolvedStatement>,
    pub isolation: IsolationReq,
}

Adapter execute payload: canonical SQL, structured proofs, optional receipt.

This is the trust boundary. Transport and adapter execution must call Self::require_proofs and must not regenerate, repair, or substitute proofs.

Fields

  • request: Canonical execute payload (no proofs).
  • guest_receipt: Host-stamped finalize hint for guest replay.
  • proofs: One resolved proof per statement, bound to that statement's SQL.
  • isolation: Isolation the adapter must realize.

AdapterExecuteRequest::new

pub fn new(request: ExecuteRequest, guest_receipt: GuestReceiptPersist) -> Self

Builds an adapter execute request without proofs.

Prefer UnresolvedExecuteRequest::canonicalize plus CanonicalExecuteRequest::bind_proofs. This constructor exists for staged host assembly; Self::require_proofs must still succeed before the request crosses the adapter boundary.

AdapterExecuteRequest::with_proofs

pub fn with_proofs(self, proofs: Vec<ResolvedStatement>) -> Self

Stamps 1:1 proofs (including receipt wrappers).

AdapterExecuteRequest::with_isolation

pub fn with_isolation(self, isolation: IsolationReq) -> Self

Sets isolation (default IsolationReq::AtomicBatch).

AdapterExecuteRequest::require_proofs

pub fn require_proofs(&self) -> Result<()>

Fail closed unless proofs are 1:1 and hash-bound to each statement.

Errors

Returns when the proof count differs or a proof is not bound to its SQL.

Implements: Clone, Debug

CanonicalExecuteRequest

pub struct CanonicalExecuteRequest {
    pub request: ExecuteRequest,
    pub guest_receipt: GuestReceiptPersist,
    pub isolation: IsolationReq,
}

Host-desugared canonical SQL. Proofs are not yet bound.

The SQL strings here are the exact text that must cross the adapter boundary and that proofs must hash.

Fields

  • request: Already-desugared canonical statements (? placeholders).
  • guest_receipt: Host-stamped finalize hint for guest replay.
  • isolation: Isolation the adapter must realize.

CanonicalExecuteRequest::from_desugared

pub fn from_desugared(request: ExecuteRequest) -> Self

Wraps already-desugared SQL (for example after crate::desugar_execute_request).

CanonicalExecuteRequest::with_guest_receipt

pub fn with_guest_receipt(self, guest_receipt: GuestReceiptPersist) -> Self

Host-stamped finalize hint for guest replay.

CanonicalExecuteRequest::with_isolation

pub fn with_isolation(self, isolation: IsolationReq) -> Self

Isolation the adapter must realize.

CanonicalExecuteRequest::bind_proofs

pub fn bind_proofs(self, proofs: Vec<ResolvedStatement>) -> Result<AdapterExecuteRequest>

Binds 1:1 proofs to the canonical SQL. Fail closed on mismatch.

Errors

Returns when the proof count differs or a proof is not bound to its SQL.

Implements: Clone, Debug

UnresolvedExecuteRequest

pub struct UnresolvedExecuteRequest {
    pub request: ExecuteRequest,
    pub guest_receipt: GuestReceiptPersist,
    pub isolation: IsolationReq,
}

Source SQL that has not been host-canonicalized.

Construct this from planner output or SeaORM SQL, then Self::canonicalize exactly once before proof generation.

Fields

  • request: Source statements (may still need NULLS / NULLIF desugar).
  • guest_receipt: Host-stamped finalize hint for guest replay.
  • isolation: Isolation the adapter must realize.

UnresolvedExecuteRequest::new

pub fn new(request: ExecuteRequest) -> Self

Wraps source SQL with default isolation and no receipt hint.

UnresolvedExecuteRequest::with_guest_receipt

pub fn with_guest_receipt(self, guest_receipt: GuestReceiptPersist) -> Self

Host-stamped finalize hint for guest replay.

UnresolvedExecuteRequest::with_isolation

pub fn with_isolation(self, isolation: IsolationReq) -> Self

Isolation the adapter must realize.

UnresolvedExecuteRequest::canonicalize

pub fn canonicalize(self) -> CanonicalExecuteRequest

Applies Bookclerk semantic desugars exactly once.

Implements: Clone, Debug

PluginMigration

pub struct PluginMigration {
    pub id: String,
    pub operations: Vec<PluginMigrationOp>,
}

One plugin-owned migration application in registration order.

Fields

  • id: Opaque plugin-chosen stable identity.
  • operations: Ordered already-separated BookclerkSQL operations.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

IntegerArithSite

pub struct IntegerArithSite {
    pub full: SqlSpan,
    pub lhs: SqlSpan,
    pub rhs: SqlSpan,
    pub kind: IntegerArithKind,
}

One INTEGER arithmetic expression that must not wrap or error on overflow.

Fields

  • full: Full expression span (a + b or abs(n)).
  • lhs: Left operand (or abs argument).
  • rhs: Right operand (abs repeats lhs).
  • kind: Operator.

Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

PhysicalAccess

pub struct PhysicalAccess {
    pub table: String,
    pub column: Option<String>,
}

Physical table/column access used for authorization.

Fields

  • table: Folded physical table name.

  • column: Folded column name when the access is column-specific.

    PHYSICAL_STAR_COLUMN ("*") means a projection wildcard on this table (SELECT *, alias.*, RETURNING *). None is table presence only (FROM / INSERT / UPDATE / DELETE / DROP), not a wildcard.

Implements: Clone, Debug, Deserialize<'de>, Eq, Ord, PartialEq, PartialOrd, Serialize

ResolvedAssignment

pub struct ResolvedAssignment {
    pub table: String,
    pub column: String,
    pub dest: SqlType,
    pub source: SqlType,
}

Destination assignment lhs = rhs (INSERT, UPDATE, …).

Fields

  • table: Physical table of the destination column.
  • column: Destination column.
  • dest: Destination type.
  • source: Unified source type.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

ResolvedStatement

pub struct ResolvedStatement {
    pub statement_hash: String,
    pub output_columns: Vec<(String, SqlType)>,
    pub physical_accesses: Vec<PhysicalAccess>,
    pub assignments: Vec<ResolvedAssignment>,
    pub text_collate_sites: Vec<TextCollateSite>,
    pub integer_arith_sites: Vec<IntegerArithSite>,
    pub functions: Vec<String>,
    pub schema_action: SchemaAction,
}

One resolved typed proof bound to an exact canonical statement.

Fields

  • statement_hash: SHA-256 hex of the exact canonical SQL this proof claims.
  • output_columns: SELECT / RETURNING / VALUES output columns in order.
  • physical_accesses: Physical tables/columns referenced (authorization).
  • assignments: Mutation destination assignments.
  • text_collate_sites: TEXT expression spans for COLLATE "C" (already excluding dest/FROM/AS).
  • integer_arith_sites: INTEGER overflow sites (+ - * abs).
  • functions: Function names invoked in code spans (folded), for authorization.
  • schema_action: DDL action + fingerprint.

ResolvedStatement::bound_empty

pub fn bound_empty(sql: &str) -> Self

Proof for sql with empty semantic payloads (wrapper DDL/DML still hash-bound).

ResolvedStatement::proves

pub fn proves(&self, sql: &str) -> bool

True when sql is the exact statement this proof was built from.

ResolvedStatement::validate_for

pub fn validate_for(&self, sql: &str) -> Result<()>

Rejects a hash-correct proof whose TEXT/arithmetic sidecar cannot be applied.

Errors

Returns when a span is empty, out of range, not on a UTF-8 boundary, operands are not contained in full, sites partially overlap, or an arithmetic kind does not match the operator in sql.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

SqlSpan

pub struct SqlSpan {
    pub start: usize,
    pub end: usize,
}

Byte span in the exact canonical SQL string a proof is bound to.

Fields

  • start: Inclusive start byte offset.
  • end: Exclusive end byte offset.

Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

TextCollateSite

pub struct TextCollateSite {
    pub span: SqlSpan,
}

One TEXT expression that PostgreSQL must collate as "C".

Fields

  • span: Identifier or string-literal span in canonical SQL.

Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

SqlFnCall

pub struct SqlFnCall {
    pub name: String,
    pub arg_count: usize,
}

One helper call found in canonical SQL (code spans only).

Fields

  • name: Folded helper name (json_object, replace, …).
  • arg_count: Top-level argument count (json_object('k', 1) is 2).

Implements: Clone, Debug, Eq, PartialEq

HostAdapterDatabaseSessionClient

pub struct HostAdapterDatabaseSessionClient {
    /* private fields */
}

Host-side client for begin on an open adapter session capability.

HostAdapterDatabaseSessionClient::from_session_client

pub fn from_session_client(client: Client) -> Self

Casts a public adapter session capability to the host-private interface.

Implements: HostAdapterDatabaseSession

RpcFeature

pub struct RpcFeature {
    pub name: &'static str,
}

Known RPC feature names.

Fields

  • name: Wire name (rpc.streams, …).

Implements: Clone, Copy, Debug, Eq, PartialEq

StreamCopyHandler

pub struct StreamCopyHandler;

Default JobRunner for the stream-copy vertical slice.

Implements: JobRunner

StreamCopySpec

pub struct StreamCopySpec {
    pub from: String,
    pub to: String,
}

JSON body for a stream_copy JobInvocation.

Fields

  • from: Source object key.
  • to: Destination object key.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

ScalarLimits

pub struct ScalarLimits {
    pub max_scalar_bytes: u32,
    pub max_stream_window_bytes: u32,
    pub max_list_page: u32,
}

Negotiated numeric limits advertised at super::PluginDescribe.

Fields

ScalarLimits::validate

pub fn validate(self) -> Result<Self>

Rejects zero or above-product-maxima limits.

Errors

Returns crate::PluginError::invalid_params when any component is zero or larger than the product constant.

ScalarLimits::intersect

pub fn intersect(self, other: Self) -> Self

Intersection of host-offered and guest-accepted limits (component-wise min).

ScalarLimits::clamp_list_limit

pub fn clamp_list_limit(self, limit: u32) -> u32

Clamps a list page limit into (0, max_list_page].

Implements: Clone, Copy, Debug, Default, Eq, From<ScalarLimits>, From<ScalarLimitsDto>, PartialEq

BindingValues

pub struct BindingValues {
    pub config: ExtensibleConfig,
    pub secrets: ExtensibleConfig,
    pub adapter: DatabaseAdapterConfig,
    pub network: NetworkGrant,
}

Plain-data portion of [Bindings]: every granted value that is not a capability. Hosts build this off the vat thread and attach capabilities when they call open.

Fields

  • config: CONFIG: granted plugin settings as application/json.
  • secrets: SECRETS: granted secret values as application/json; empty payload when the manifest declares no [secrets].
  • adapter: Database-adapter bootstrap for the databaseAdapter entrypoint. First-party host-managed adapters receive host-private connect params in Self::config; third-party adapters receive this typed bootstrap (and an empty config). plugin_data_dir is empty when config carries host-private params instead.
  • network: NETWORK: the network grant in effect, with each network setting's destination and approval state. Read-only feedback for the guest.

BindingValues::config

pub fn config(config: ExtensibleConfig) -> Self

Bindings carrying only CONFIG.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

Bindings

pub struct Bindings {
    pub config: ExtensibleConfig,
    pub secrets: ExtensibleConfig,
    pub adapter: DatabaseAdapterConfig,
    pub events: Option<Box<dyn EventPublisher>>,
    pub databases: Vec<(String, Box<dyn GuestDatabase>)>,
    pub cancel: Box<dyn Cancellation>,
    pub storage: Option<Box<dyn Destination>>,
    pub queues: Vec<NamedQueueBinding>,
    pub kv: Vec<NamedKvBinding>,
    pub sockets: Option<Box<dyn Sockets>>,
    pub webhooks: Option<Box<dyn Webhooks>>,
    pub network: NetworkGrant,
    pub notify: Option<Box<dyn NotificationRaiser>>,
    pub origin: Option<Box<dyn Origin>>,
    pub ai: Option<Box<dyn AiRunner>>,
}

Host-granted bindings for one PluginWorker::open (env in the Workers idiom). Capability fields are None when the manifest does not declare (or the operator did not grant) the binding.

Fields

  • config: CONFIG: granted plugin settings as application/json.
  • secrets: SECRETS: granted secret values; empty payload when none.
  • adapter: Database-adapter bootstrap (see BindingValues::adapter).
  • events: EVENTS: outbox publisher; None unless [[events.producers]] is granted.
  • databases: Named plugin-owned [[databases]] bindings: isolated databases separate from the Bookclerk library and from every other plugin.
  • cancel: Host cancellation for the whole invocation (fence / lease loss).
  • storage: WORK_FS: host-granted object storage for durable plugin files; None unless [work_fs] is granted. Job input/output travel on JobController, never here.
  • queues: Named [[queues.producers]] bindings; empty when none is granted.
  • kv: Named [[kv_namespaces]] bindings; empty when none is granted.
  • sockets: SOCKETS: host-brokered WebSockets; None unless [sockets] is granted.
  • webhooks: WEBHOOKS: the instance's inbound webhooks; None unless the manifest declares [[webhooks]].
  • network: NETWORK: the network grant in effect (see BindingValues::network).
  • notify: NOTIFY: raises declared notification types; None unless the manifest declares [[notifications.types]].
  • origin: ORIGIN: the library, for the active relay ingress plugin; None for every other plugin.
  • ai: AI: runs models served by model plugins; None unless the manifest declares [ai] calls and the operator approved it.

Bindings::from_values

pub fn from_values(values: BindingValues) -> Self

Bindings with only plain values (no capabilities); tests and in-process hosts.

Bindings::take_named_queue

pub fn take_named_queue(&mut self, name: &str) -> Option<NamedQueueBinding>

Takes the named queue producer binding name, if granted.

Bindings::take_named_kv

pub fn take_named_kv(&mut self, name: &str) -> Option<NamedKvBinding>

Takes the named KV namespace binding name, if granted.

Bindings::values

pub fn values(&self) -> BindingValues

Plain-data view (config / secrets / adapter).

Bindings::take_named_database

pub fn take_named_database(&mut self, name: &str) -> Option<Box<dyn GuestDatabase>>

Takes the named plugin database binding name, if granted.

ByteRange

pub struct ByteRange {
    pub offset: u64,
    pub length: Option<u64>,
}

Inclusive byte range for a streamed read.

Fields

  • offset: Starting offset.
  • length: Number of bytes; None means to end of object.

Implements: Clone, Copy, Debug, Eq, PartialEq

Entrypoints

pub struct Entrypoints {
    pub event_consumer: Option<Box<dyn EventConsumer>>,
    pub job_runner: Option<Box<dyn JobRunner>>,
    pub storefront: Option<Box<dyn ContentSource>>,
    pub storage: Option<Box<dyn Destination>>,
    pub database_adapter: Option<Box<dyn Database>>,
    pub remote_library: Option<Box<dyn RemoteLibrary>>,
    pub cli: Option<Box<dyn PluginCli>>,
    pub oidc: Option<Box<dyn Oidc>>,
    pub queue_consumer: Option<Box<dyn QueueConsumer>>,
    pub scheduled_handler: Option<Box<dyn ScheduledHandler>>,
    pub metadata: Option<Box<dyn MetadataProvider>>,
    pub covers: Option<Box<dyn CoverFetcher>>,
    pub socket_handler: Option<Box<dyn SocketHandler>>,
    pub webhook_handler: Option<Box<dyn WebhookHandler>>,
    pub metadata_files: Option<Box<dyn MetadataFiles>>,
    pub notifier: Option<Box<dyn Notifier>>,
    pub ingress: Option<Box<dyn Ingress>>,
    pub ai: Option<Box<dyn AiModels>>,
}

Exported entrypoints returned by [PluginWorker::open]: one capability per plugin.toml entrypoints entry / trigger, None when not exported.

The host refuses an entrypoint the manifest or operator grant did not allow, so a guest cannot widen its surface here.

Fields

  • event_consumer: [[events.consumers]] trigger.
  • job_runner: [triggers] jobs trigger.
  • storefront: storefront entrypoint.
  • storage: storage entrypoint.
  • database_adapter: databaseAdapter entrypoint.
  • remote_library: remoteLibrary entrypoint.
  • cli: cli entrypoint.
  • oidc: oidc entrypoint.
  • queue_consumer: [[queues.consumers]] trigger.
  • scheduled_handler: [triggers] crons trigger.
  • metadata: metadata entrypoint.
  • covers: covers entrypoint.
  • socket_handler: [sockets] handler.
  • webhook_handler: [[webhooks]] handler.
  • metadata_files: metadataFiles entrypoint.
  • notifier: notifier entrypoint.
  • ingress: ingress entrypoint.
  • ai: ai entrypoint.

Implements: Default

JobController

pub struct JobController {
    pub invocation: JobInvocation,
    pub input: Box<dyn Source>,
    pub output: Box<dyn Destination>,
    pub progress: Box<dyn ProgressSink>,
    pub cancel: Box<dyn Cancellation>,
}

Everything one JobRunner::job invocation may touch.

Named database bindings are not per job: they arrive on Bindings::databases at PluginWorker::open.

Fields

  • invocation: Durable command envelope.
  • input: Input source capability.
  • output: Output destination capability.
  • progress: Progress sink (durable job row).
  • cancel: Cancellation capability (host fence / lease).

NamedKvBinding

pub struct NamedKvBinding {
    pub name: String,
    pub namespace: String,
    pub kv: Box<dyn KvNamespace>,
}

One granted [[kv_namespaces]] binding on Bindings::kv.

Fields

  • name: Binding name on env ([[kv_namespaces]] binding).
  • namespace: Namespace the binding is scoped to.
  • kv: Host-served namespace.

NamedQueueBinding

pub struct NamedQueueBinding {
    pub name: String,
    pub queue: String,
    pub producer: Box<dyn QueueProducer>,
}

One granted [[queues.producers]] binding on Bindings::queues.

Fields

  • name: Binding name on env ([[queues.producers]] binding).
  • queue: Queue the binding sends to.
  • producer: Host-served producer.

NeverCancel

pub struct NeverCancel;

Cancellation that never fires (tests / hosts without a fence).

Implements: Cancellation

OriginReply

pub struct OriginReply {
    pub status: u16,
    pub headers: Vec<OriginHeader>,
    pub body: Option<Pin<Box<dyn AsyncRead + Send>>>,
}

The library's answer to one [Origin::fetch]: its response head and streamed body.

Fields

  • status: HTTP status code, 100 to 599.
  • headers: Response header fields in order; repeated names stay separate.
  • body: Response body; None when the response has none. Dropping it abandons the rest of the body.

ReadResult

pub struct ReadResult {
    pub meta: ObjectMetadata,
    pub body: Pin<Box<dyn AsyncRead + Send>>,
}

Streamed read result. body ownership is transferred to the caller.

Fields

  • meta: Object metadata (size, type, checksums).
  • body: Byte stream; drop/cancel aborts the read.

AdapterSessionHandle

pub struct AdapterSessionHandle {
    pub session: Box<dyn AdapterDatabaseSession>,
    pub host: HostAdapterDatabaseSessionClient,
}

Public adapter session plus host-private interactive transaction client.

Fields

  • session: Typed capabilities / execute / close.
  • host: Host-only begin (capability cast on the same session object).

AiModelsClient

pub struct AiModelsClient {
    /* private fields */
}

Cap'n Proto client for AiModels.

The client checks each listing before the caller sees it (crate::ai::check_models) and each run before it leaves (crate::ai::check_entrypoint_run_params): a malformed listing is an internal error. A run's reply comes back as the plugin said it; the caller, which knows the model's listing, checks it with crate::ai::check_run_output.

AiModelsClient::new

pub fn new(client: Client) -> Self

Wraps an AiModels capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

Arguments
  • client - The guest's AiModels capability.
Returns

The typed client.

Implements: AiModels, Clone

AiRunnerClient

pub struct AiRunnerClient {
    /* private fields */
}

Guest-side client for the host AI binding (AiRunner). Runs are checked before they leave, so a plugin learns of a malformed run without a round trip; the host checks again.

AiRunnerClient::new

pub fn new(client: Client) -> Self

Wraps an AiRunner capability client.

Arguments
  • client - The host's AiRunner capability.
Returns

The typed client.

Implements: AiRunner, Clone

ContentSourceClient

pub struct ContentSourceClient {
    /* private fields */
}

Cap'n Proto client for ContentSource.

ContentSourceClient::new

pub fn new(client: Client) -> Self

Wraps a ContentSource capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

Implements: Clone, ContentSource

CoverFetcherClient

pub struct CoverFetcherClient {
    /* private fields */
}

Cap'n Proto client for CoverFetcher.

The client checks the guest's reply against the request: exactly one CoverImage per requested URL, in order, each naming its URL. Anything else is an internal error, so callers can index the reply by request position.

CoverFetcherClient::new

pub fn new(client: Client, window: u32) -> Self

Wraps a CoverFetcher capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

Arguments
  • client - The guest's CoverFetcher capability.
  • window - Stream window for the host sink, clamped to 1..=MAX_STREAM_WINDOW_BYTES.

CoverFetcherClient::fetch_covers_with_sink

pub async fn fetch_covers_with_sink(
    &self,
    params: CoverFetchParams,
    sink: Client,
) -> Result<Vec<CoverImage>>

fetchCovers with a ready-made sink capability, for transports that pass the sink by reference rather than serving it here (the bookclerk-workerd launcher hands the isolate a grant capability).

Arguments
  • params - URLs and the per-image byte cap.
  • sink - The Destination capability the guest puts bodies into.
Returns

One answer per URL, in request order.

Errors

invalid_params when params breaks the ABI bounds, the guest's own error, or internal when the reply does not answer the request one for one.

Implements: Clone, CoverFetcher

DatabaseClient

pub struct DatabaseClient {
    /* private fields */
}

Cap'n Proto client for Database.

DatabaseClient::new

pub fn new(client: Client) -> Self

Wraps a Database capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

DatabaseClient::open_session_handle

pub async fn open_session_handle(&self) -> Result<AdapterSessionHandle>

Opens a session and host-private transaction client on one capability.

Errors

Returns when openSession fails on the guest.

Implements: Clone, Database

DestinationClient

pub struct DestinationClient {
    /* private fields */
}

Host-side Destination over a capnp destination stub.

DestinationClient::new

pub fn new(client: Client, window: u32) -> Self

Wraps a capnp destination client.

DestinationClient::with_max_list_page

pub fn with_max_list_page(self, max_list_page: u32) -> Self

Applies negotiated list-page cardinality.

Implements: Clone, Destination

DestinationServer

pub struct DestinationServer {
    /* private fields */
}

Cap'n Proto server wrapping a Destination trait object.

DestinationServer::new

pub fn new(inner: Arc<dyn Destination>, window: u32) -> Self

Serves inner with the given stream window.

Implements: Server

EventConsumerClient

pub struct EventConsumerClient {
    /* private fields */
}

Cap'n Proto client for EventConsumer (host → guest delivery).

EventConsumerClient::new

pub fn new(client: Client) -> Self

Wraps a EventConsumer capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

Implements: Clone, EventConsumer

EventPublisherClient

pub struct EventPublisherClient {
    /* private fields */
}

Guest-side client for the host EVENTS binding (EventPublisher).

Implements: Clone, EventPublisher

HostBindings

pub struct HostBindings {
    pub values: BindingValues,
    pub events: Option<Arc<dyn EventPublisher>>,
    pub databases: Vec<(String, Arc<dyn GuestDatabase>)>,
    pub cancel: Arc<dyn Cancellation>,
    pub storage: Option<Arc<dyn Destination>>,
    pub queues: Vec<(String, String, Arc<dyn QueueProducer>)>,
    pub kv: Vec<(String, String, Arc<dyn KvNamespace>)>,
    pub sockets: Option<Arc<dyn Sockets>>,
    pub webhooks: Option<Arc<dyn Webhooks>>,
    pub notify: Option<Arc<dyn NotificationRaiser>>,
    pub origin: Option<Arc<dyn Origin>>,
    pub ai: Option<Arc<dyn AiRunner>>,
}

Host-side [Bindings]: plain values plus host-served capabilities the guest receives on open.

Fields

  • values: CONFIG / SECRETS / adapter bootstrap.
  • events: EVENTS publisher; None unless [[events.producers]] is granted.
  • databases: Named plugin-owned [[databases]] sessions.
  • cancel: Invocation-wide cancellation (fence / lease loss).
  • storage: WORK_FS object storage; None unless [work_fs] is granted.
  • queues: Named [[queues.producers]] producers as (binding, queue, producer).
  • kv: Named [[kv_namespaces]] namespaces as (binding, namespace, kv).
  • sockets: SOCKETS broker link; None unless [sockets] is granted.
  • webhooks: WEBHOOKS store; None unless the manifest declares [[webhooks]].
  • notify: NOTIFY raiser; None unless the manifest declares [[notifications.types]].
  • origin: ORIGIN: the library; None unless the plugin is the active relay ingress.
  • ai: AI model runner; None unless the manifest declares [ai] calls and the operator approved it.

HostBindings::from_values

pub fn from_values(values: BindingValues) -> Self

Bindings with only plain values and no cancellation source.

Implements: Default

IngressClient

pub struct IngressClient {
    /* private fields */
}

Host-side client for a plugin's ingress entrypoint.

IngressClient::new

pub fn new(client: Client) -> Self

Wraps the Entrypoints.ingress capability.

IngressClient::start_checked

pub async fn start_checked(&self) -> Result<IngressOrigin>

Asks the plugin to bring its public address up and checks the origin it reports.

Returns

The origin it serves (parse_ingress_origin).

Errors

The plugin's error, the RPC error, or invalid_params when the reported origin is not an https:// host name.

Implements: Clone, Ingress

JobRunnerClient

pub struct JobRunnerClient {
    /* private fields */
}

Cap'n Proto client for JobRunner (host → guest job dispatch).

JobRunnerClient::new

pub fn new(client: Client, window: u32) -> Self

Wraps a JobRunner capability client with the negotiated stream window.

JobRunnerClient::job

pub async fn job(
    &self,
    invocation: &JobInvocation,
    input: Arc<dyn Source>,
    output: Arc<dyn Destination>,
    progress: Arc<dyn ProgressSink>,
    cancel: Arc<dyn Cancellation>,
) -> Result<JobOutcome>

Runs one job with host-served input / output / progress / cancel capabilities.

Errors

Returns a plugin error when the runner fails.

JobRunnerClient::job_with_capabilities

pub async fn job_with_capabilities(
    &self,
    invocation: &JobInvocation,
    input: Client,
    output: Client,
    progress: Client,
    cancel: Client,
) -> Result<JobOutcome>

Runs one job with caller-built JobController capability clients.

Transports that do not host a local vat (the bookclerk-workerd /invoke hook, where each capability is a grant-token descriptor) build the four clients themselves and reuse the typed envelope here.

Errors

Returns a plugin error when the runner fails.

Implements: Clone, JobRunner

KvNamespaceClient

pub struct KvNamespaceClient {
    /* private fields */
}

Guest-side client for a host KV namespace binding (KvNamespace).

KvNamespaceClient::new

pub fn new(client: Client) -> Self

Wraps a KvNamespace capability client.

Implements: Clone, KvNamespace

MetadataFilesClient

pub struct MetadataFilesClient {
    /* private fields */
}

Cap'n Proto client for MetadataFiles.

The client checks each request before it leaves (crate::check_parse_params, crate::check_render_params) and each reply before the caller sees it: a parsed record must pass crate::validate_metadata_file_record and rendered bytes crate::check_rendered. A reply that fails is an internal error, so a misbehaving dialect never hands the host a record outside the caps. Checks against the dialect's manifest declaration are the caller's (crate::check_record_against_dialect), since only it knows the manifest.

MetadataFilesClient::new

pub fn new(client: Client) -> Self

Wraps a MetadataFiles capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

Arguments
  • client - The guest's MetadataFiles capability.
Returns

The typed client.

Implements: Clone, MetadataFiles

MetadataProviderClient

pub struct MetadataProviderClient {
    /* private fields */
}

Cap'n Proto client for MetadataProvider.

MetadataProviderClient::new

pub fn new(client: Client) -> Self

Wraps a MetadataProvider capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

Implements: Clone, MetadataProvider

NoOrigin

pub struct NoOrigin;

Fails closed: an Origin that refuses everything, for hosts that grant no relay ingress. Kept for tests and in-process hosts.

Implements: Origin

NotificationRaiserClient

pub struct NotificationRaiserClient {
    /* private fields */
}

Guest-side client for the host NOTIFY binding (NotificationRaiser). Raises are checked before they leave, so a plugin learns of a malformed raise without a round trip; the host checks again.

NotificationRaiserClient::new

pub fn new(client: Client) -> Self

Wraps a NotificationRaiser capability client.

Arguments
  • client - The host's NotificationRaiser capability.
Returns

The typed client.

Implements: Clone, NotificationRaiser

NotifierClient

pub struct NotifierClient {
    /* private fields */
}

Cap'n Proto client for Notifier.

The client checks each request before it leaves (crate::notifications::check_send_params) and each validateDestination answer before the caller sees it (crate::notifications::check_validated): a malformed address is an internal error. A send reply comes back as the notifier said it; the caller turns it into an outcome with crate::notifications::classify_send_reply.

NotifierClient::new

pub fn new(client: Client) -> Self

Wraps a Notifier capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

Arguments
  • client - The guest's Notifier capability.
Returns

The typed client.

Implements: Clone, Notifier

OidcClient

pub struct OidcClient {
    /* private fields */
}

Cap'n Proto client for Oidc.

OidcClient::new

pub fn new(client: Client) -> Self

Wraps a Oidc capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

Implements: Clone, Oidc

OpenedEntrypoints

pub struct OpenedEntrypoints {
    pub event_consumer: Option<EventConsumerClient>,
    pub job_runner: Option<JobRunnerClient>,
    pub storefront: Option<ContentSourceClient>,
    pub storage: Option<DestinationClient>,
    pub database_adapter: Option<DatabaseClient>,
    pub remote_library: Option<RemoteLibraryClient>,
    pub cli: Option<PluginCliClient>,
    pub oidc: Option<OidcClient>,
    pub queue_consumer: Option<QueueConsumerClient>,
    pub scheduled_handler: Option<ScheduledHandlerClient>,
    pub metadata: Option<MetadataProviderClient>,
    pub covers: Option<CoverFetcherClient>,
    pub socket_handler: Option<SocketHandlerClient>,
    pub webhook_handler: Option<WebhookHandlerClient>,
    pub metadata_files: Option<MetadataFilesClient>,
    pub notifier: Option<NotifierClient>,
    pub ingress: Option<IngressClient>,
    pub ai: Option<AiModelsClient>,
}

Typed clients for the entrypoints a guest exported from open. None means the guest did not export that entrypoint.

Fields

  • event_consumer: [[events.consumers]] trigger.
  • job_runner: [triggers] jobs trigger.
  • storefront: storefront entrypoint.
  • storage: storage entrypoint.
  • database_adapter: databaseAdapter entrypoint.
  • remote_library: remoteLibrary entrypoint.
  • cli: cli entrypoint.
  • oidc: oidc entrypoint.
  • queue_consumer: [[queues.consumers]] trigger.
  • scheduled_handler: [triggers] crons trigger.
  • metadata: metadata entrypoint.
  • covers: covers entrypoint.
  • socket_handler: [sockets] handler.
  • webhook_handler: [[webhooks]] handler.
  • metadata_files: metadataFiles entrypoint.
  • notifier: notifier entrypoint.
  • ingress: ingress entrypoint.
  • ai: ai entrypoint.

Implements: Default

OriginClient

pub struct OriginClient {
    /* private fields */
}

Guest-side client for the Origin binding (what a native relay plugin calls).

OriginClient::new

pub fn new(client: Client, window: u32) -> Self

Wraps the Bindings.origin capability.

Implements: Origin

PluginCliClient

pub struct PluginCliClient {
    /* private fields */
}

Cap'n Proto client for PluginCli.

PluginCliClient::new

pub fn new(client: Client) -> Self

Wraps a PluginCli capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

Implements: Clone, PluginCli

PluginClient

pub struct PluginClient {
    pub window: u32,
    pub limits: ScalarLimits,
    /* private fields */
}

Host bootstrap client for a plugin vat.

Fields

  • window: Negotiated stream window.
  • limits: Negotiated scalar / list limits.

PluginClient::new

pub fn new(client: Client, window: u32) -> Self

Wraps a bootstrap client.

PluginClient::with_limits

pub fn with_limits(self, limits: ScalarLimits) -> Self

Applies negotiated limits (stream window + list page).

PluginClient::describe

pub async fn describe(&self) -> Result<PluginDescribe>

Calls describe.

Errors

Returns a plugin error when the RPC fails or apiVersion is not crate::limits::PRODUCT_API_VERSION.

PluginClient::open

pub async fn open(
    &self,
    invocation: &Invocation,
    bindings: HostBindings,
) -> Result<OpenedEntrypoints>

Opens the exported entrypoints for invocation with host-granted bindings.

Errors

Returns a plugin error when the RPC fails or the guest refuses the open.

PluginClient::database_migrations

pub async fn database_migrations(&self, binding: &str) -> Result<Vec<PluginMigration>>

Complete ordered plugin-owned migration sequence for one named binding.

Errors

Returns a plugin error when the RPC fails.

PluginClient::shutdown

pub async fn shutdown(&self) -> Result<()>

Asks the guest to release its resources (PluginWorker.shutdown).

Errors

Returns a plugin error when the RPC fails or the guest reports one.

Implements: Clone

PluginServer

pub struct PluginServer {
    /* private fields */
}

Cap'n Proto server wrapping PluginWorker.

PluginServer::new

pub fn new(inner: Arc<dyn PluginWorker>, window: u32) -> Self

Serves inner.

Implements: Server

QueueConsumerClient

pub struct QueueConsumerClient {
    /* private fields */
}

Cap'n Proto client for QueueConsumer (host → guest delivery).

QueueConsumerClient::new

pub fn new(client: Client) -> Self

Wraps a QueueConsumer capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

Implements: Clone, QueueConsumer

QueueProducerClient

pub struct QueueProducerClient {
    /* private fields */
}

Guest-side client for a host queue producer binding (QueueProducer).

QueueProducerClient::new

pub fn new(client: Client) -> Self

Wraps a QueueProducer capability client.

Implements: Clone, QueueProducer

RemoteLibraryClient

pub struct RemoteLibraryClient {
    /* private fields */
}

Cap'n Proto client for RemoteLibrary.

RemoteLibraryClient::new

pub fn new(client: Client) -> Self

Wraps a RemoteLibrary capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

Implements: Clone, RemoteLibrary

ScheduledHandlerClient

pub struct ScheduledHandlerClient {
    /* private fields */
}

Cap'n Proto client for ScheduledHandler (host → guest cron fire).

ScheduledHandlerClient::new

pub fn new(client: Client) -> Self

Wraps a ScheduledHandler capability client (any transport that yields one, including the bookclerk-workerd /invoke hook).

Implements: Clone, ScheduledHandler

SocketHandlerClient

pub struct SocketHandlerClient {
    /* private fields */
}

Host-side client for a guest's SocketHandler.

SocketHandlerClient::new

pub fn new(client: Client) -> Self

Wraps a SocketHandler capability client.

Implements: Clone, SocketHandler

SocketsClient

pub struct SocketsClient {
    /* private fields */
}

Guest-side client for the host Sockets binding.

SocketsClient::new

pub fn new(client: Client) -> Self

Wraps a Sockets capability client.

Implements: Clone, Sockets

SourceClient

pub struct SourceClient {
    /* private fields */
}

Host-side Source over a capnp source stub.

SourceClient::new

pub fn new(client: Client, window: u32) -> Self

Wraps a capnp source client.

Implements: Clone, Source

SourceServer

pub struct SourceServer {
    /* private fields */
}

Cap'n Proto server wrapping a Source.

SourceServer::new

pub fn new(inner: Arc<dyn Source>, window: u32) -> Self

Serves inner.

Implements: Server

WebhookHandlerClient

pub struct WebhookHandlerClient {
    /* private fields */
}

Host-side client for a guest's WebhookHandler.

WebhookHandlerClient::new

pub fn new(client: Client) -> Self

Wraps a WebhookHandler capability client.

Implements: Clone, WebhookHandler

WebhooksClient

pub struct WebhooksClient {
    /* private fields */
}

Guest-side client for the host Webhooks binding.

WebhooksClient::new

pub fn new(client: Client) -> Self

Wraps a Webhooks capability client.

Implements: Clone, Webhooks

CopyResult

pub struct CopyResult {
    pub bytes_copied: u64,
}

Result of a server-side copy.

Fields

  • bytes_copied: Bytes copied when known.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

DomainEvent

pub struct DomainEvent {
    pub event_id: String,
    pub event_type: String,
    pub schema_version: u32,
    pub occurred_at_unix_ms: u64,
    pub account_id: String,
    pub source: String,
    pub correlation_id: String,
    pub causation_id: String,
    pub deduplication_key: String,
    pub delivery_attempt: u32,
    pub payload: Vec<u8>,
    pub checkpoint_json: String,
    pub checkpoint_schema_version: u32,
    pub invocation_sequence: u32,
    pub resume_pending: bool,
}

Domain event (not a job). Outbox-produced, at-least-once, idempotent consume.

Fields

  • event_id: Unique event id.
  • event_type: Event type name.
  • schema_version: Payload schema version.
  • occurred_at_unix_ms: UTC unix milliseconds.
  • account_id: Tenant / account id.
  • source: Producer plugin id; empty when unknown.
  • correlation_id: Trace correlation id.
  • causation_id: Prior event or invocation that caused this one.
  • deduplication_key: Idempotent consume key.
  • delivery_attempt: 1-based delivery attempt.
  • payload: Bounded payload.
  • checkpoint_json: Checkpoint JSON from a prior EventResult::Suspended (≤ MAX_CHECKPOINT_BYTES).
  • checkpoint_schema_version: Schema version of Self::checkpoint_json.
  • invocation_sequence: Resume ordinal copied from the delivery row.
  • resume_pending: True when this invocation continues a prior suspended result.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

ExtensibleConfig

pub struct ExtensibleConfig {
    pub schema_version: u32,
    pub media_type: String,
    pub payload: Vec<u8>,
}

Versioned plugin-specific config (not a substitute for typed ABI fields).

Fields

  • schema_version: Payload schema version.
  • media_type: IANA media type or application/json.
  • payload: Bounded payload bytes.

ExtensibleConfig::json

pub fn json(value: &Value) -> Self

Wraps a JSON document as an application/json payload (schema version 1).

ExtensibleConfig::json_from

pub fn json_from<T: Serialize>(value: &T) -> Result<Self>

Serializes value as an application/json payload (schema version 1).

Errors

Returns crate::PluginErrorCode::Internal when value cannot be serialized.

ExtensibleConfig::is_empty

pub fn is_empty(&self) -> bool

True when no payload was supplied.

ExtensibleConfig::json_value

pub fn json_value(&self) -> Result<Value>

Decodes the payload as a JSON document; an empty payload is {}.

Errors

Returns crate::PluginErrorCode::InvalidParams when the media type is not JSON or the bytes are not valid JSON.

ExtensibleConfig::json_into

pub fn json_into<T: DeserializeOwned>(&self) -> Result<T>

Decodes the JSON payload into T; an empty payload decodes {}.

Errors

Same as Self::json_value, plus a deserialization failure into T.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

HealthOk

pub struct HealthOk {
    pub ok: bool,
    pub detail: String,
}

Health payload.

Fields

  • ok: True when the role is ready.
  • detail: Operator-facing detail.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

JobCheckpoint

pub struct JobCheckpoint {
    pub schema_version: u32,
    pub json: String,
}

Bounded, versioned checkpoint attached to an invocation or suspension.

Fields

  • schema_version: Checkpoint payload schema version. Unknown versions fail closed.
  • json: JSON checkpoint bytes (must be ≤ MAX_CHECKPOINT_BYTES).

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

JobInvocation

pub struct JobInvocation {
    pub payload_schema_version: u32,
    pub invocation_id: String,
    pub command_type: String,
    pub payload_json: String,
    pub idempotency_key: String,
    pub attempt: u32,
    pub correlation_id: String,
    pub causation_id: Option<String>,
    pub deadline_unix_ms: u64,
    pub checkpoint: Option<JobCheckpoint>,
    pub invocation_sequence: u32,
    pub step_id: Option<String>,
}

Versioned durable command envelope (not a domain event).

Idempotency keys are scoped to (account, plugin, commandType) until a terminal fenced outcome is committed. They are not reusable across accounts. deadline_unix_ms is a guest hint; the host fence/lease is authoritative and must not be outlived (clock skew across VPS nodes). The envelope is not independently persisted as opaque bytes across ABI majors; command payload_schema_version and checkpoint schema versions version the stored pieces.

Fields

  • payload_schema_version: Command payload schema version for Self::command_type.
  • invocation_id: Unique id for this attempt envelope.
  • command_type: Command type (stream_copy, …).
  • payload_json: JSON payload for that command type.
  • idempotency_key: Idempotency key (see struct docs for scope).
  • attempt: 1-based attempt counter.
  • correlation_id: Correlation id for traces.
  • causation_id: Optional causation id (prior invocation that produced this one).
  • deadline_unix_ms: Guest-visible UTC deadline as unix milliseconds.
  • checkpoint: Bounded, versioned checkpoint from a prior suspension.
  • invocation_sequence: Resume ordinal; distinct from failure Self::attempt.
  • step_id: Deterministic step identifier within this invocation.

JobInvocation::stream_copy

pub fn stream_copy(job_id: impl Into<String>, payload_json: impl Into<String>) -> Self

Builds a v1 stream_copy invocation with a far-future deadline.

Tests and accountless helpers use this. Production copy jobs should call Self::stream_copy_from_lease so attempt, deadline, and idempotency come from the claimed fence.

JobInvocation::stream_copy_from_lease

pub fn stream_copy_from_lease(
    lease: JobInvocationLease,
    payload_json: impl Into<String>,
) -> Self

Builds a stream_copy envelope from a claimed job lease.

invocation_id is unique per attempt (job_id:attempt:generation). idempotency_key is the durable dedup key and stays stable across reclaim. invocation_sequence is the resume ordinal from the lease (distinct from failure attempt). deadline_unix_ms is the lease expiry as unix milliseconds.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

JobInvocationLease

pub struct JobInvocationLease {
    pub job_id: String,
    pub attempt: u32,
    pub generation: i64,
    pub dedup_key: String,
    pub deadline_unix_ms: u64,
    pub checkpoint: Option<JobCheckpoint>,
    pub invocation_sequence: u32,
}

Claimed-lease fields used to populate a JobInvocation.

Fields

  • job_id: Durable job id (jobs.id).
  • attempt: 1-based attempt counter from the claim.
  • generation: Lease generation from the successful claim.
  • dedup_key: Queue dedup key; stable across reclaim of the same command.
  • deadline_unix_ms: Lease expiry as UTC unix milliseconds (guest deadline hint).
  • checkpoint: Checkpoint restored from a prior JobOutcome::Suspended.
  • invocation_sequence: Resume ordinal from the durable payload; distinct from Self::attempt.

Implements: Clone, Debug, Eq, PartialEq

ListOptions

pub struct ListOptions {
    pub prefix: String,
    pub cursor: Option<String>,
    pub limit: u32,
    pub with_signatures: bool,
    pub modified_since_ms: Option<u64>,
}

Paginated list request.

Fields

  • prefix: Key prefix filter.
  • cursor: Opaque continuation token.
  • limit: Requested page size (0 = default).
  • with_signatures: Hint: fill the signature fields of each ObjectInfo. The reply's ListPage::signatures_included says whether the guest did.
  • modified_since_ms: Hint: only objects modified at or after this UTC unix millisecond. The reply's ListPage::modified_since_applied says whether the guest filtered; when it did not, the page is unfiltered.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

ListPage

pub struct ListPage {
    pub objects: Vec<ObjectInfo>,
    pub next_cursor: Option<String>,
    pub signatures_included: bool,
    pub modified_since_applied: bool,
}

One page of keys.

Cursors are opaque. Missing/stale cursors must return invalid_cursor, never silently restart at page one. Concurrent mutation is weakly consistent unless a backend snapshot is documented.

Fields

  • objects: Objects in this page.
  • next_cursor: Continuation token; None when this is the last page.
  • signatures_included: True when every entry carries the signature fields the backend has (ListOptions::with_signatures honoured).
  • modified_since_applied: True when the guest left out objects modified before ListOptions::modified_since_ms; false means the page is unfiltered.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

ObjectInfo

pub struct ObjectInfo {
    pub key: String,
    pub size: u64,
    pub etag: Option<String>,
    pub modified_at_ms: Option<u64>,
    pub version_id: Option<String>,
    pub signature: Option<String>,
}

Object listing entry.

The signature fields are filled only when the listing was asked for them (ListOptions::with_signatures) and the backend has them (ListPage::signatures_included).

Fields

  • key: Object key.
  • size: Size in bytes.
  • etag: Opaque backend entity tag, when the backend has one.
  • modified_at_ms: Last modification time in UTC unix milliseconds, when known.
  • version_id: Backend object version id (versioned buckets), when there is one.
  • signature: Opaque change signature: an unchanged value means the object did not change. Backend-defined; compare only values from the same backend.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

ObjectMetadata

pub struct ObjectMetadata {
    pub key: String,
    pub size: u64,
    pub content_type: Option<String>,
    pub etag: Option<String>,
    pub sha256: Option<Vec<u8>>,
    pub modified_at_ms: Option<u64>,
    pub version_id: Option<String>,
    pub signature: Option<String>,
}

Metadata without a body.

Fields

  • key: Object key.
  • size: Size in bytes.
  • content_type: MIME type when known.
  • etag: Opaque etag when the backend provides one.
  • sha256: SHA-256 digest when computed.
  • modified_at_ms: Last modification time in UTC unix milliseconds, when known.
  • version_id: Backend object version id (versioned buckets), when there is one.
  • signature: Opaque change signature, as ObjectInfo::signature.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

OidcClientTemplate

pub struct OidcClientTemplate {
    pub client_id: String,
    pub display_name: String,
    pub callback_path: String,
    pub public_client: bool,
    pub default_scopes: Vec<String>,
    pub issue_refresh_token: bool,
    pub origin_config_key: String,
}

Plugin-declared Bookclerk-as-IdP relying-party template.

The host materializes oidc_clients rows. Plugins never mint tokens. origin_config_key is a dotted config path such as integrations.audiobookshelf.base_url.

Fields

  • client_id: Stable OAuth client_id registered with Bookclerk's authorization server.
  • display_name: Operator-facing card title.
  • callback_path: Path appended to the plugin origin (e.g. /auth/openid/callback).
  • public_client: When true, the client is public PKCE (no secret).
  • default_scopes: Scopes offered on first materialization (openid / profile typical).
  • issue_refresh_token: When true, /oidc/token may issue refresh tokens for new rows.
  • origin_config_key: Dotted config key that supplies the player origin.

OidcClientTemplate::scopes_or_default

pub fn scopes_or_default(&self) -> Vec<String>

Scopes used when the guest omitted defaultScopes.

OidcClientTemplate::display_name_or_id

pub fn display_name_or_id(&self) -> &str

Card title, falling back to client_id.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

PluginDescribe

pub struct PluginDescribe {
    pub api_version: u32,
    pub id: String,
    pub display_name: Option<String>,
    pub rpc_features: Vec<String>,
    pub scalar_limits: ScalarLimitsDto,
    pub capabilities: PluginCapabilities,
    pub portal_auth_mode: PortalAuthMode,
    pub password_env_var: Option<String>,
    pub aliases: Vec<String>,
    pub sort_key: u32,
    pub brand: Option<Brand>,
    pub config_options: Vec<ConfigOption>,
    pub cli: CliSchema,
    pub catalog: CatalogCapabilities,
    pub media: MediaSupport,
}

Guest identity returned by PluginWorker.describe (the adapter merges the manifest projection over the author describe()).

Every field is a typed Cap'n Proto field of PluginDescribe; there is no side-channel JSON. Storefront UI extras (brand, config_options, portal_auth_mode, ...) are empty / default for kinds that do not use them.

Fields

  • api_version: Must equal crate::limits::PRODUCT_API_VERSION.
  • id: Plugin id matching plugin.toml.
  • display_name: Optional UI name.
  • rpc_features: Accepted RPC features (intersection with the host offer).
  • scalar_limits: Effective numeric limits.
  • capabilities: Typed capability declaration (entrypoints, event consumers/producers, jobs, database and named bindings). The host compares it with the verified plugin.toml and the operator grant; widening is rejected.
  • portal_auth_mode: Portal Accounts connect mode for storefronts.
  • password_env_var: Reserved wire field: hosts ignore it. Passwords reach a guest only as sealed secrets from Accounts, never from the environment.
  • aliases: Alternate ids accepted for config / CLI targeting.
  • sort_key: UI sort weight among peers of the same kind; lower sorts first.
  • brand: Portal brand; None when the guest has no brand (wire brand.id is empty) and the host renders a neutral fallback.
  • config_options: Discoverable config option groups for source UIs.
  • cli: Embedded CLI schema (same shape as cliDescribe); empty when unused.
  • catalog: Catalog behaviours a storefront declares (ISBN detail lookup, ...); all false for other kinds and for storefronts that declare none.
  • media: The work kinds and carriers the plugin lists and fetches. Required (non-empty) for storefronts and metadata providers and equal to the manifest's [media] table; empty for every other plugin.

PluginDescribe::has_entrypoint

pub fn has_entrypoint(&self, entrypoint: Entrypoint) -> bool

True when the guest exports the named Entrypoint.

PluginDescribe::consumes_event

pub fn consumes_event(&self, event_type: &str) -> bool

True when the guest's default entrypoint consumes event_type.

PluginDescribe::runs_job

pub fn runs_job(&self, job_type: &str) -> bool

True when the guest's default entrypoint runs jobs of job_type.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

PutResult

pub struct PutResult {
    pub key: String,
    pub bytes_written: u64,
    pub etag: Option<String>,
    pub sha256: Option<Vec<u8>>,
    pub modified_at_ms: Option<u64>,
    pub version_id: Option<String>,
    pub signature: Option<String>,
}

Result of a streamed put.

Fields

  • key: Object key written.
  • bytes_written: Bytes accepted.
  • etag: Backend etag when available.
  • sha256: Digest of the written body when computed.
  • modified_at_ms: Modification time of the stored object in UTC unix milliseconds, when known.
  • version_id: Version id of the stored object, when there is one.
  • signature: Change signature of the stored object, so the host can recognise its own write in a later listing.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

QueryPage

pub struct QueryPage {
    pub rows_json: String,
    pub next_cursor: Option<String>,
}

Bounded query page for host-internal SeaORM session helpers (not Cap'n ABI).

Fields

  • rows_json: JSON-encoded rows.
  • next_cursor: Continuation token.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

ScalarLimitsDto

pub struct ScalarLimitsDto {
    pub max_scalar_bytes: u32,
    pub max_stream_window_bytes: u32,
    pub max_list_page: u32,
}

Wire form of ScalarLimits.

Fields

  • max_scalar_bytes: Max ordinary RPC value size in bytes.
  • max_stream_window_bytes: Max ByteSource.pull window in bytes.
  • max_list_page: Max objects per list page.

Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, From<ScalarLimits>, From<ScalarLimitsDto>, PartialEq, Serialize

WriteOptions

pub struct WriteOptions {
    pub content_type: Option<String>,
    pub content_length: Option<u64>,
    pub sha256: Option<Vec<u8>>,
    pub commit_token: Option<String>,
    pub stage_only: bool,
    pub if_match: Option<String>,
    pub if_none_match: bool,
}

Write options for Destination.put.

Fields

  • content_type: MIME type.
  • content_length: Known length; omit when unknown.
  • sha256: Expected SHA-256 of the body.
  • commit_token: Destination-side stage-and-publish token. Empty means a one-shot put.
  • stage_only: When true, put stages remotely and does not publish until commit.
  • if_match: Conditional write: publish only while the stored object's etag equals this value, else fail with conflict. Sent only to a guest that declares storage.conditionalWrite.
  • if_none_match: Conditional write: publish only when no object exists at the key, else fail with conflict. Sent only to a guest that declares storage.conditionalWrite.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

ChangesPage

pub struct ChangesPage {
    pub changes: Vec<ObjectChange>,
    pub cursor: String,
    pub more: bool,
    pub complete: bool,
    pub live_watch: bool,
}

One page of crate::Destination::changes.

Fields

  • changes: Changes since the request's cursor, oldest first. A key may repeat.
  • cursor: Cursor for the next call; never empty.
  • more: True when more changes are ready now.
  • complete: False when the feed may have missed changes since the request's cursor; the host then backs it with a full listing.
  • live_watch: True when the running guest produces the feed itself (a filesystem watcher), so stopping it would lose changes. The host keeps such a guest awake while complete stays true, and honours this only from the first-party storage plugins it starts on demand. Durable feeds leave it false.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

ChangesRequest

pub struct ChangesRequest {
    pub cursor: Option<String>,
    pub limit: u32,
}

Argument of crate::Destination::changes.

Fields

  • cursor: ChangesPage::cursor from the previous call; None asks for the current position (a page with a cursor and no changes).
  • limit: Requested changes per page, clamped to MAX_CHANGES_PAGE; zero means guest default.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

KeyOutcome

pub struct KeyOutcome {
    pub key: String,
    pub error: Option<PluginError>,
}

Outcome for one key of a batch call.

Fields

  • key: The key this outcome is for (the source key for moves).
  • error: The failure for this key; None when it succeeded.

KeyOutcome::ok

pub fn ok(key: impl Into<String>) -> Self

A successful outcome for key.

KeyOutcome::failed

pub fn failed(key: impl Into<String>, error: PluginError) -> Self

A failed outcome for key.

Implements: Clone, Debug, Eq, PartialEq

KeyPair

pub struct KeyPair {
    pub from: String,
    pub to: String,
}

One source and target key (or prefix).

Fields

  • from: Source key or prefix.
  • to: Target key or prefix.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

MoveManyPage

pub struct MoveManyPage {
    pub results: Vec<KeyOutcome>,
    pub next_cursor: Option<String>,
    pub atomic: bool,
    pub objects_moved: u64,
}

One page of crate::Destination::move_many progress.

Fields

  • results: Outcomes in request order. A prefix move done in one step may report a single outcome keyed by the source prefix.
  • next_cursor: Prefix form: cursor for the next call; None when every object moved.
  • atomic: True when every move in this page was atomic.
  • objects_moved: Objects moved in this page.

Implements: Clone, Debug, Default, Eq, PartialEq

MoveManyRequest

pub struct MoveManyRequest {
    pub target: MoveManyTarget,
    pub cursor: Option<String>,
    pub limit: u32,
    pub options: MoveOptions,
}

Argument of crate::Destination::move_many.

Fields

  • target: Explicit pairs or a prefix.
  • cursor: Prefix form: MoveManyPage::next_cursor from the previous call; None starts. Ignored for pairs.
  • limit: Prefix form: objects to move in this call, clamped to MAX_BATCH_KEYS; zero means guest default.
  • options: Overwrite rule applied to every move (if_source_match is ignored).

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

MoveOptions

pub struct MoveOptions {
    pub no_overwrite: bool,
    pub if_source_match: Option<String>,
}

Options for crate::Destination::move_object and crate::Destination::move_many. Fields are only ever appended.

Fields

  • no_overwrite: Fail with conflict instead of replacing an object at the target.
  • if_source_match: Single moves only: move only while the source's etag equals this value, else fail with conflict.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

MoveResult

pub struct MoveResult {
    pub atomic: bool,
    pub already_moved: bool,
}

How a single move was done.

Fields

  • atomic: True when the backend moved atomically (a rename): no reader saw the object at both keys or at neither.
  • already_moved: True when the source was already gone and the target present, as when a move is repeated after a restart. The move counts as done.

Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

ObjectChange

pub struct ObjectChange {
    pub key: String,
    pub kind: ObjectChangeKind,
    pub info: Option<ObjectInfo>,
}

One entry of a change feed.

Fields

  • key: Object key, relative to the destination root.
  • kind: What happened to it.
  • info: Listing fields after the change when the feed carries them.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

Enums

PluginMigrationOp

pub enum PluginMigrationOp {
    Schema(String),
    Data(String),
}

One already-separated BookclerkSQL operation in a registered migration.

Variants

  • Schema: Admitted schema DDL (CREATE / DROP / index).
  • Data: Admitted data DML (INSERT / UPDATE / DELETE).

PluginMigrationOp::sql

pub fn sql(&self) -> &str

Canonical BookclerkSQL for this operation.

PluginMigrationOp::is_schema

pub fn is_schema(&self) -> bool

True when this operation is classified as schema DDL.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

OverflowDialect

pub enum OverflowDialect {
    SqliteFamily,
    Postgres,
}

Engine family for overflow derived-table syntax and i64::MIN CAST.

Variants

  • SqliteFamily: SQLite / D1: correlated FROM (SELECT …) _bc_ov, INTEGER min CAST.
  • Postgres: PostgreSQL: LATERAL + BIGINT min CAST.

Implements: Clone, Copy, Debug, Eq, PartialEq

IntegerArithKind

pub enum IntegerArithKind {
    Add,
    Sub,
    Mul,
    Abs,
}

INTEGER + - * abs site lowered to overflow → NULL.

Variants

  • Add: lhs + rhs
  • Sub: lhs - rhs
  • Mul: lhs * rhs
  • Abs: abs(arg) (lhs is the argument span)

Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

SchemaAction

pub enum SchemaAction {
    None,
    Create { schema: Box<CreateTableSchema>, fingerprint: String, noop: bool },
    Drop { table: String },
}

CREATE/DROP action recorded on a proof.

Variants

  • None: Not DDL.
  • Create: CREATE TABLE — noop when the durable fingerprint already matches.
    • schema: Parsed SQL-v1 table schema (columns, nullability, identity, constraints).
    • fingerprint: Structured schema fingerprint (hex SHA-256).
    • noop: True when catalog already has this exact fingerprint.
  • Drop: DROP TABLE.
    • table: Folded table name.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

LikePatternSrc

pub enum LikePatternSrc {
    Literal(String),
    Bind(usize),
    Unproven,
    Null,
}

Proven LIKE pattern sources in one canonical statement.

Variants

  • Literal: 'literal' (possibly concatenated with ||).
  • Bind: Positional ? bind (0-based bind index in this statement).
  • Unproven: Pattern expression whose length cannot be proven.
  • Null: SQL NULL (no pattern bytes).

Implements: Clone, Debug, Eq, PartialEq

EventReadCodec

pub enum EventReadCodec {
    Request,
    Page,
}

Which EVENTS.read Cap'n Proto struct roundtrip_event_read_message decodes.

Variants

  • Request: EventReadRequest, which the host decodes from a guest.
  • Page: EventReadPage, which a guest decodes from the host.

Implements: Clone, Copy, Debug, Eq, PartialEq

EventReadMessage

pub enum EventReadMessage {
    Request(EventReadRequest),
    Page(EventReadPage),
}

A value roundtrip_event_read_message decoded.

Variants

  • Request: A decoded EventReadRequest.
  • Page: A decoded EventReadPage.

Implements: Clone, Debug, Eq, PartialEq

SocketCodec

pub enum SocketCodec {
    ConnectRequest,
    Message,
}

Which socket Cap'n Proto struct roundtrip_socket_message decodes.

Variants

  • ConnectRequest: SocketConnectRequest, which the host decodes from a guest.
  • Message: SocketMessage, which a guest decodes from the host (and the host decodes from the broker before delivery).

Implements: Clone, Copy, Debug, Eq, PartialEq

SocketWireMessage

pub enum SocketWireMessage {
    ConnectRequest(SocketConnectRequest),
    Message(SocketMessage),
}

A value roundtrip_socket_message decoded.

Variants

  • ConnectRequest: A decoded SocketConnectRequest.
  • Message: A decoded SocketMessage.

Implements: Clone, Debug, Eq, PartialEq

WebhookCodec

pub enum WebhookCodec {
    PullRequest,
    AckRequest,
    Delivery,
}

Which webhook Cap'n Proto struct roundtrip_webhook_message decodes.

Variants

  • PullRequest: WebhookPullRequest, which the host decodes from a guest.
  • AckRequest: WebhookAckRequest, which the host decodes from a guest.
  • Delivery: WebhookDelivery, which a guest decodes from the host.

Implements: Clone, Copy, Debug, Eq, PartialEq

WebhookWireMessage

pub enum WebhookWireMessage {
    PullRequest(WebhookPullRequest),
    AckRequest(WebhookAckRequest),
    Delivery(WebhookDelivery),
}

A value roundtrip_webhook_message decoded.

Variants

  • PullRequest: A decoded WebhookPullRequest.
  • AckRequest: A decoded WebhookAckRequest.
  • Delivery: A decoded WebhookDelivery.

Implements: Clone, Debug, Eq, PartialEq

EventResult

pub enum EventResult {
    Ack,
    Retry { retry_at_unix_ms: u64, reason: String },
    Reject { reason: String },
    DeadLetter { reason: String },
    Suspended { checkpoint_json: String, checkpoint_schema_version: u32, wake_at_unix_ms: u64, wake_on_event_type: String, wake_on_filter_json: String },
}

Per-event result of crate::EventConsumer::event.

Variants

  • Ack: Event processed.
  • Retry: Transient failure; retry after retry_at_unix_ms.
    • retry_at_unix_ms: UTC unix-ms hint.
    • reason: Operator-facing reason.
  • Reject: Permanent rejection.
    • reason: Operator-facing reason.
  • DeadLetter: Poison; do not redeliver.
    • reason: Operator-facing reason.
  • Suspended: Durable sleep: persist checkpoint, release the process, resume later.
    • checkpoint_json: Bounded checkpoint JSON (must be ≤ MAX_CHECKPOINT_BYTES).
    • checkpoint_schema_version: Checkpoint schema version.
    • wake_at_unix_ms: UTC unix-ms wake hint.
    • wake_on_event_type: Event type that can wake this sleep; empty = timestamp-only.
    • wake_on_filter_json: Host-owned payload object filter JSON; empty = type only.

EventResult::from_json_value

pub fn from_json_value(value: &Value) -> Result<Self>

Decode JSON {"kind":"ack"|…}. Missing or unknown kind is an error.

Errors

Returns crate::PluginErrorCode::InvalidParams when the payload is not a tagged EventResult, or crate::PluginErrorCode::PayloadTooLarge when a suspended checkpoint exceeds MAX_CHECKPOINT_BYTES.

EventResult::from_json_str

pub fn from_json_str(raw: &str) -> Result<Self>

Decode a JSON object string as EventResult.

Errors

Same as Self::from_json_value.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

JobOutcome

pub enum JobOutcome {
    Completed { message: String, bytes_copied: u64 },
    Retryable { message: String, retry_after_unix_ms: Option<u64> },
    Rejected { message: String },
    Cancelled { message: String },
    Suspended { checkpoint: JobCheckpoint, wake_at_unix_ms: u64 },
}

Outcome of crate::JobRunner::job.

Suspension is durable only after Bookclerk atomically commits the fenced outcome. Open streams and process memory do not survive.

Variants

  • Completed: Handler finished successfully.
    • message: Operator-facing summary.
    • bytes_copied: Bytes copied when this was a stream copy.
  • Retryable: Transient failure; host may retry after retry_after_unix_ms.
    • message: Operator-facing summary.
    • retry_after_unix_ms: Optional UTC unix-ms hint for the next attempt.
  • Rejected: Permanent rejection (do not retry the same payload).
    • message: Operator-facing summary.
  • Cancelled: Cancelled by host fence / guest abort.
    • message: Operator-facing summary.
  • Suspended: Durable pause; resume with checkpoint after wake_at_unix_ms.
    • checkpoint: Checkpoint to restore on wake.
    • wake_at_unix_ms: UTC unix-ms wake hint.

JobOutcome::is_terminal

pub fn is_terminal(&self) -> bool

True when the host should treat the invocation as finished.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

MoveManyTarget

pub enum MoveManyTarget {
    Pairs(Vec<KeyPair>),
    Prefix(KeyPair),
}

What a MoveManyRequest moves.

Variants

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

ObjectChangeKind

pub enum ObjectChangeKind {
    Changed,
    Upserted,
    Removed,
}

What happened to an object in a change feed.

Variants

  • Changed: Something changed; probe the key to learn what. Unknown wire codes read as this.
  • Upserted: The object was created or rewritten.
  • Removed: The object was removed.

Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

StorageReply

pub enum StorageReply {
    MoveMany(MoveManyPage),
    DeleteMany(Vec<KeyOutcome>),
    HeadMany(Vec<Option<ObjectMetadata>>),
    Changes(ChangesPage),
    List(ListPage),
    TranslateKeys(Vec<String>),
}

A guest reply the storage_reply fuzz target decodes.

Variants

  • MoveMany: A moveMany page.
  • DeleteMany: deleteMany outcomes.
  • HeadMany: headMany probes.
  • Changes: A changes page.
  • List: A list page.
  • TranslateKeys: translateKeys keys.

Implements: Clone, Debug, Eq, PartialEq

StorageReplyKind

pub enum StorageReplyKind {
    MoveMany,
    DeleteMany,
    HeadMany,
    Changes,
    List,
    TranslateKeys,
}

Which reply decode_storage_reply_bytes reads.

Variants

  • MoveMany: MoveManyPage.
  • DeleteMany: DeleteManyResult.
  • HeadMany: HeadManyResult.
  • Changes: ChangesPage.
  • List: ListPage.
  • TranslateKeys: TranslateKeysResult.

Implements: Clone, Copy, Debug, Eq, PartialEq

Functions

capnp_u32_len

pub fn capnp_u32_len(len: usize, what: &str) -> Result<u32>

Converts a Rust list length into a Cap'n Proto UInt32 list size.

Errors

Returns PluginError::payload_too_large when len cannot fit in u32.

plugin_migration_registration_bytes

pub fn plugin_migration_registration_bytes(migrations: &[PluginMigration]) -> usize

Aggregate UTF-8 bytes of ids plus SQL across a complete registration.

require_plugin_migration_json_lists

pub fn require_plugin_migration_json_lists(value: &Value) -> Result<()>

Rejects JSON databaseMigrations list sizes before deserializing operations.

Walks nested operations array lengths only; does not construct PluginMigration values. Call this before serde_json::from_value.

Errors

Returns PluginError::payload_too_large when migration count, operations per migration, or total operations exceed ABI limits.

require_plugin_migration_registration

pub fn require_plugin_migration_registration(migrations: &[PluginMigration]) -> Result<()>

Rejects a plugin migration registration that exceeds RPC resource limits.

Call this before encoding a Cap'n Proto / JSON reply and while decoding, before semantic BookclerkSQL proof. Limits:

Total operations are checked before walking SQL text so a registration of many tiny operations is rejected without treating the 256 KiB text budget as a heap bound.

Errors

Returns PluginError::payload_too_large when any limit is exceeded.

apply_integer_overflow

pub fn apply_integer_overflow(
    dialect: OverflowDialect,
    sql: &str,
    sites: &[IntegerArithSite],
) -> Result<String>

Wrap each INTEGER +/-/*/abs site in a portable overflow CASE.

Sites are applied innermost-first (full.end, then reverse full.start) so right-nested 1 + abs(n) rewrites the abs call before the outer add. After each wrap, remaining (outer) sites shift by the byte count the wrap added or removed; a wrap drops comments between operands, so it can be shorter than its site.

Errors

Returns when a site is empty, past sql, not on a UTF-8 boundary, cannot be wrapped as the recorded operator, or has a boundary strictly inside an inner site it does not enclose.

assert_proof_matches_sql

pub fn assert_proof_matches_sql(proof: &ResolvedStatement, sql: &str) -> Result<()>

Require proof to be bound to sql.

Errors

Returns when the hashes differ (transformed or reindexed SQL).

admitted_bookclerk_sql_samples

pub fn admitted_bookclerk_sql_samples(seed: u64, count: usize) -> Vec<String>

Grammar-aware BookclerkSQL samples for fuzz corpora and differential tests.

Statements stay inside the SQL-v1 grammar (canonical ?, LIKE, INSERT OR IGNORE). TEXT literals are portable UTF-8 without U+0000. LIKE patterns stay within D1_PORTABLE_LIKE_PATTERN_BYTES.

canonical_statements_checksum

pub fn canonical_statements_checksum(statements: &[&str]) -> String

Length-prefixed SHA-256 of an ordered canonical statement list.

Statement boundaries are part of the digest: joining with ; then hashing would collide with literals such as DEFAULT 'a;b'.

glob_expanded_like_pattern_bytes

pub fn glob_expanded_like_pattern_bytes(like_pattern: &str) -> usize

UTF-8 byte length of a sqlite-family GLOB pattern after Bookclerk LIKE→GLOB metacharacter escaping ([ * ? become three bytes).

D1's physical GLOB/LIKE pattern cap is 50 bytes. Adapters that perform this expansion must advertise super::DbCapabilities::max_pattern_bytes small enough that the expanded pattern still fits.

like_pattern_sources

pub fn like_pattern_sources(sql: &str) -> Result<Vec<LikePatternSrc>>

Collects LIKE / NOT LIKE pattern sources with proven lengths when possible.

Errors

Returns PluginError::invalid_params when a string, quoted identifier, or block comment is unterminated.

require_function_args_within

pub fn require_function_args_within(sql: &str, max_function_args: u32) -> Result<()>

Enforces crate::DbCapabilities::max_function_args on non-chunkable helpers.

min / max / coalesce are omitted: adapters nest them so each physical call stays inside the advertised cap. json_object is enforced here: the portable maximum is already crate::SQL_V1_JSON_OBJECT_MAX_ARGS.

Errors

Returns a typed limit_exceeded error (see crate::LimitExceeded) when a non-chunkable call exceeds the cap, and PluginError::invalid_params when the cap is unspecified.

require_like_patterns_within

pub fn require_like_patterns_within(
    sql: &str,
    parameters: &[DbValue],
    max_pattern_bytes: u32,
) -> Result<()>

Enforces crate::DbCapabilities::max_pattern_bytes on LIKE patterns.

Errors

Returns a typed limit_exceeded error (see crate::LimitExceeded) when a literal or TEXT-bound pattern exceeds the cap, and PluginError::invalid_params when the cap is unspecified, a LIKE bind is not TEXT or missing, or a pattern length cannot be proven.

require_portable_text

pub fn require_portable_text(text: &str) -> Result<()>

Rejects BookclerkSQL TEXT that contains U+0000.

Errors

Returns PluginError::invalid_params when text contains NUL.

require_portable_text_binds

pub fn require_portable_text_binds(parameters: &[DbValue]) -> Result<()>

Rejects U+0000 in every BookclerkSQL TEXT bind.

Errors

Returns PluginError::invalid_params when a crate::DbValue::Text bind contains NUL.

sql_v1_function_calls

pub fn sql_v1_function_calls(sql: &str) -> Result<Vec<SqlFnCall>>

Collects helper calls in code spans (strings/comments are skipped).

Errors

Returns PluginError::invalid_params when a string, quoted identifier, or block comment is unterminated.

sql_v1_helper_is_chunkable

pub fn sql_v1_helper_is_chunkable(name: &str) -> bool

Helpers adapters may nest so each physical call stays inside crate::DbCapabilities::max_function_args.

json_object is not chunkable: portable SQL-v1 already caps it at crate::SQL_V1_JSON_OBJECT_MAX_ARGS (D1's physical limit). Nesting via json_patch is not equivalent (JSON Merge Patch deletes nulls).

sql_v1_pack_statements

pub fn sql_v1_pack_statements(sql: &str) -> Result<Vec<String>>

Splits a BookclerkSQL pack into statements using the SQL-v1 lexer.

Semicolons inside string literals, quoted identifiers, line comments, and block comments do not end a statement. Empty fragments are dropped.

Errors

Returns PluginError::invalid_params when quotes or comments are unterminated, or when a fragment is not a single SQL-v1 statement.

sqlite_family_like_divmod_insert_upper_bound

pub const fn sqlite_family_like_divmod_insert_upper_bound(canonical_len: usize) -> usize

Upper bound on sqlite-family mechanical lowering length for a canonical statement of canonical_len bytes (div/mod NULLIF, INSERT OR IGNORE, LIKE→GLOB). Does not include proof-directed INTEGER overflow wraps.

LIKE→GLOB is the densest per-byte expansion among mechanical rewrites (LIKE is 4 bytes; overhead is LIKE_GLOB_REWRITE_OVERHEAD). The count canonical_len / 4 is the maximum number of LIKE keywords that can appear in canonical_len bytes — not an expansion-factor guess. Remaining bytes after packing as many LIKE keywords as possible are charged as / % NULLIF wraps (1-byte operators).

Proof-directed INTEGER overflow CASE wraps are applied from typed proofs before this mechanical bound; they are not a function of payload length alone.

sqlite_family_mechanical_len_upper_bound

pub fn sqlite_family_mechanical_len_upper_bound(sql: &str) -> Result<usize>

Mechanical sqlite-family length bound for one canonical statement, counting actual LIKE occurrences, / % operators in code spans, and at most one INSERT OR IGNORE rewrite.

Always <= sqlite_family_like_divmod_insert_upper_bound(sql.len()) for well-formed packs: the length formula packs the densest rewrite into every 4-byte window, while this preflight charges only constructs that lowering actually rewrites. INTEGER overflow wraps are applied from typed proofs before this mechanical bound.

Errors

Returns PluginError::invalid_params when quotes or block comments are unterminated.

text_contains_nul

pub fn text_contains_nul(text: &str) -> bool

True when text contains U+0000.

canonical_execute_request_hash

pub fn canonical_execute_request_hash(req: &ExecuteRequest) -> Result<String>

SHA-256 hex of the Cap'n-encoded request with transport metadata cleared.

operationId, requestHash, and deadlineUnixMs are not part of the digest: a retry of the same mutation may mint a remaining deadline without hash-conflicting. The trusted host stamps requestHash after validation so guests cannot collide unrelated mutations on one idempotency key.

Errors

Returns PluginError::internal when the message cannot be serialized.

decode_db_capabilities_reply_bytes

pub fn decode_db_capabilities_reply_bytes(bytes: &[u8]) -> Result<DbCapabilities>

Decodes a standalone Cap'n DbCapabilitiesReply message.

Errors

Returns the guest PluginError on err, or a decode failure on ok.

decode_db_value_bytes

pub fn decode_db_value_bytes(bytes: &[u8]) -> Result<DbValue>

Decodes a standalone Cap'n DbValue message.

Errors

Returns when the buffer is not a valid unpacked DbValue.

decode_execute_request_bytes

pub fn decode_execute_request_bytes(bytes: &[u8]) -> Result<ExecuteRequest>

Decodes a standalone Cap'n ExecuteRequest message.

Errors

Returns when the buffer is not a valid unpacked ExecuteRequest.

decode_execute_result_reply_bytes

pub fn decode_execute_result_reply_bytes(bytes: &[u8]) -> Result<ExecuteReply>

Decodes a standalone Cap'n ExecuteAtomicReply message.

Errors

Returns the guest PluginError on err, or a decode failure on ok.

decode_execute_stream_frame_bytes

pub fn decode_execute_stream_frame_bytes(
    bytes: &[u8],
    max_bytes: u32,
) -> Result<ExecuteStreamFrame>

Decodes one standalone ExecuteStreamFrame message whose traversal is capped at max_bytes (at least the scalar ceiling).

Errors

Returns when the buffer is not one valid unpacked frame.

encoded_db_capabilities_reply_bytes

pub fn encoded_db_capabilities_reply_bytes(
    outcome: Result<DbCapabilities>,
) -> Result<Vec<u8>>

Encodes a standalone Cap'n DbCapabilitiesReply (ok or err).

Carries a GuestDatabase.limits answer over the workerd granted HTTP channel (GET /db/limits).

Errors

Returns PluginError::internal when the message cannot be serialized.

encoded_db_value_bytes

pub fn encoded_db_value_bytes(v: &DbValue) -> Result<Vec<u8>>

Encodes a standalone Cap'n DbValue message (unpacked stream).

Errors

Returns PluginError::invalid_params when a DbValue::Text contains U+0000, or PluginError::internal when the message cannot be serialized.

encoded_db_value_len

pub fn encoded_db_value_len(v: &DbValue) -> Result<usize>

Length in bytes of encoded_db_value_bytes's output, worked out from the value instead of encoding it.

A bind's payload size is checked against maxPayloadBytes for every statement, so this runs once per bind. Encoding each value allocated and zeroed a fresh 8 KiB first segment; the layout is fixed, so the size follows from the value alone: the one-segment table (8 bytes), the root pointer (one word), the DbValue struct (its data and pointer words), and for TEXT the bytes plus their NUL terminator, or for BLOB the bytes, each rounded up to whole words.

Errors

Returns PluginError::invalid_params when a DbValue::Text contains U+0000, as encoded_db_value_bytes does.

encoded_execute_reply_bytes

pub fn encoded_execute_reply_bytes(reply: &ExecuteReply) -> Result<Vec<u8>>

Encodes a standalone Cap'n ExecuteReply message (unpacked stream).

Errors

Returns PluginError::invalid_params when a TEXT cell contains U+0000, or PluginError::internal when the message cannot be serialized.

encoded_execute_request_bytes

pub fn encoded_execute_request_bytes(req: &ExecuteRequest) -> Result<Vec<u8>>

Encodes a standalone Cap'n ExecuteRequest message (unpacked stream).

Errors

Returns PluginError::invalid_params when SQL or TEXT binds contain U+0000, or PluginError::internal when the message cannot be serialized.

encoded_execute_result_reply_bytes

pub fn encoded_execute_result_reply_bytes(
    outcome: Result<ExecuteReply>,
) -> Result<Vec<u8>>

Encodes a standalone Cap'n ExecuteAtomicReply (ok or err).

Errors

Returns PluginError::internal when the message cannot be serialized.

encoded_execute_stream_frame_bytes

pub fn encoded_execute_stream_frame_bytes(frame: &ExecuteStreamFrame) -> Result<Vec<u8>>

Encodes one standalone ExecuteStreamFrame message (unpacked stream, one segment).

Errors

Returns PluginError::invalid_params when a TEXT cell contains U+0000, or PluginError::internal when the message cannot be serialized.

encoded_statement_result_bytes

pub fn encoded_statement_result_bytes(stmt: &StatementResult) -> Result<Vec<u8>>

Encodes a standalone Cap'n StatementResult message (unpacked stream).

Used to enforce negotiated maxResultBytes against the actual wire size of one statement before COMMIT.

Errors

Returns PluginError::invalid_params when a TEXT cell contains U+0000, or PluginError::internal when the message cannot be serialized.

negotiate_rpc_features

pub fn negotiate_rpc_features(
    host_offers: &[&str],
    guest_accepts: &[String],
) -> Result<Vec<String>>

Intersects host-offered and guest-accepted feature lists.

Errors

Returns a message when a required feature is missing or the guest offers an unsafe combination (streams without scalar limits).

read_all

pub async fn read_all(body: Pin<Box<dyn AsyncRead + Send>>) -> Result<Vec<u8>>

Reads a small transferred body, stopping at crate::MAX_SCALAR_BYTES.

This is not a media reader. A longer body is PluginError::payload_too_large and the extra bytes are not retained.

Errors

Returns PluginError::payload_too_large or an I/O error mapped as PluginError::internal.

stream_copy_keys

pub async fn stream_copy_keys(
    input: &dyn Source,
    output: &dyn Destination,
    spec: &StreamCopySpec,
    invocation: &JobInvocation,
    progress: &dyn ProgressSink,
    cancel: &dyn Cancellation,
) -> Result<JobOutcome>

Copies from → to through granted source/destination streams.

Bytes are staged under a retry-stable commit_token then committed after a best-effort fence check. Publication is at-least-once and idempotent on that token. Cancellation, a failed cancellation poll, or put/commit failure aborts the stage. A poll error is not treated as "still running".

Errors

Returns a plugin error when open, put, commit, progress reporting, or cancellation polling fails.

cover_sink_slot

pub fn cover_sink_slot(key: &str, slots: usize) -> Option<usize>

Parses a CoverFetcher.fetchCovers sink key into the URL index it names.

The guest puts the body for urls[i] under the key i. Only the canonical decimal spelling is accepted (0, 7, 31; never 07, +7, 7 or 7.0), so each index has exactly one key.

Arguments

  • key - The key the guest wrote under (untrusted).
  • slots - Number of URLs in the request; valid indexes are 0..slots.

Returns

The index, or None when key is not a canonical index below slots.

hint_result

pub fn hint_result(hint: Option<PurchaseHint>) -> PurchaseHintResult

A bare hint as a PurchaseHintResult with no records.

Arguments

  • hint - The store's answer; None when it did not find the title.

purchase_hint_results_one_by_one

pub async fn purchase_hint_results_one_by_one<S: ContentSource + ?Sized>(
    source: &S,
    params: PurchaseHintsParams,
) -> Result<Vec<PurchaseHintResult>>

ContentSource::purchase_hints_results for a store without a bulk endpoint: asks ContentSource::purchase_hint_result for each query, with the same order, concurrency and PURCHASE_HINTS_BUDGET as the default ContentSource::purchase_hints. A query not started within the budget answers an empty result (found = false, no records).

A guest that overrides ContentSource::purchase_hint_result to return title-search records, but has no bulk endpoint, calls this from its purchase_hints_results so batches carry the records too.

Arguments

  • source - The store answering.
  • params - The batch's queries.

Returns

One result per query, in order.

Errors

The first lookup error, which fails the whole batch.

byte_source_from_async_read

pub fn byte_source_from_async_read(
    reader: Pin<Box<dyn AsyncRead + Send>>,
    window: u32,
) -> Client

Returns a ByteSource client that pulls from reader.

connect_plugin

pub fn connect_plugin<R, W>(
    reader: R,
    writer: W,
    window: u32,
) -> (PluginClient, RpcSystem<Side>)
where
    R: AsyncRead + Unpin + 'static,
    W: AsyncWrite + Unpin + 'static,

Connects as the client side of a two-party vat.

Must run inside a tokio::task::LocalSet. The returned RpcSystem must be spawned with tokio::task::spawn_local.

connect_socket_broker

pub fn connect_socket_broker<R, W>(
    reader: R,
    writer: W,
    handler: Arc<dyn SocketHandler>,
) -> (SocketsClient, RpcSystem<Side>)
where
    R: AsyncRead + Unpin + 'static,
    W: AsyncWrite + Unpin + 'static,

Connects the host's side of the host-to-broker link (see serve_socket_broker).

Must run inside a tokio::task::LocalSet. The returned capnp_rpc::RpcSystem must be spawned with tokio::task::spawn_local; the link lasts as long as it runs.

Arguments

  • reader / writer - The link to the broker.
  • handler - Where the broker delivers messages and closes.

Returns

The broker's Sockets and the link's RPC system.

decode_empty_reply_bytes

pub fn decode_empty_reply_bytes(bytes: &[u8]) -> Result<()>

Decodes a standalone EmptyReply message the way the host decodes a guest's payload-free reply, for the abi_decode fuzz target and its corpus replay.

Errors

Returns the guest's PluginError for an err reply, or a decode failure when the buffer is not a valid unpacked single-segment message.

decode_plugin_error_bytes

pub fn decode_plugin_error_bytes(bytes: &[u8]) -> Result<PluginError>

Decodes a standalone PluginError message the way the host decodes a guest's error, for the abi_decode fuzz target and its corpus replay.

Errors

Returns a decode failure when the buffer is not a valid unpacked single-segment message; the error itself is the Ok value.

pull_byte_source_to_writer

pub async fn pull_byte_source_to_writer<W: AsyncWrite + Unpin>(
    source: Client,
    writer: &mut W,
    window: u32,
) -> Result<u64>

Pulls source into writer using bounded windows.

A failed ByteSource.pull is returned as PluginError — never as a clean EOF. Destinations must abort rather than commit.

Errors

Returns a plugin error when the stream or writer fails.

roundtrip_event_read_message

pub fn roundtrip_event_read_message(
    codec: EventReadCodec,
    bytes: &[u8],
) -> Result<EventReadMessage, RoundTripFailure>

Decodes one unpacked single-segment EventReadRequest or EventReadPage message with the codec the RPC server and client use, then checks read(write(v)) == v. The fuzz target and its replay test drive this, so they reach the same bounds checks a peer's bytes do.

Arguments

  • codec - Which struct the message holds.
  • bytes - The message, as capnp::serialize writes it.

Returns

The decoded value, for the caller to check against its own bounds.

Errors

RoundTripFailure::Rejected when the bytes do not decode or break a bound; RoundTripFailure::Codec when a decoded value does not survive write then read intact.

roundtrip_socket_message

pub fn roundtrip_socket_message(
    codec: SocketCodec,
    bytes: &[u8],
) -> Result<SocketWireMessage, RoundTripFailure>

Decodes one unpacked single-segment SocketConnectRequest or SocketMessage with the codec the RPC server and client use, then checks read(write(v)) == v. The socket_request fuzz target and its replay test drive this, so they reach the same decoder a peer's bytes do; the caller then applies crate::sockets checks to the value.

Arguments

  • codec - Which struct the message holds.
  • bytes - The message, as capnp::serialize writes it.

Returns

The decoded value.

Errors

RoundTripFailure::Rejected when the bytes do not decode; RoundTripFailure::Codec when a decoded value does not survive write then read intact.

roundtrip_webhook_message

pub fn roundtrip_webhook_message(
    codec: WebhookCodec,
    bytes: &[u8],
) -> Result<WebhookWireMessage, RoundTripFailure>

Decodes one unpacked single-segment webhook message with the codec the RPC server and client use, then checks read(write(v)) == v. The webhook_rpc fuzz target and its replay test drive this, so they reach the same decoder a peer's bytes do; the caller then applies the crate::webhooks checks to the value.

Arguments

  • codec - Which struct the message holds.
  • bytes - The message, as capnp::serialize writes it.

Returns

The decoded value.

Errors

RoundTripFailure::Rejected when the bytes do not decode; RoundTripFailure::Codec when a decoded value does not survive write then read intact.

serve_plugin

pub async fn serve_plugin<R, W>(
    plugin: Arc<dyn PluginWorker>,
    reader: R,
    writer: W,
    window: u32,
) -> Result<()>
where
    R: AsyncRead + Unpin + 'static,
    W: AsyncWrite + Unpin + 'static,

Serves plugin as the bootstrap object on a two-party vat over reader/writer.

Must run inside a tokio::task::LocalSet.

Errors

Returns a plugin error when the vat fails.

serve_plugin_stdio

pub async fn serve_plugin_stdio(plugin: Arc<dyn PluginWorker>, window: u32) -> Result<()>

Serves plugin on stdin/stdout. Must run on a current-thread runtime + LocalSet.

Errors

Returns a plugin error when the vat fails.

serve_socket_broker

pub async fn serve_socket_broker<R, W>(
    reader: R,
    writer: W,
    make: impl FnOnce(SocketHandlerClient) -> Arc<dyn Sockets>,
) -> Result<()>
where
    R: AsyncRead + Unpin + 'static,
    W: AsyncWrite + Unpin + 'static,

Serves the socket broker's side of the host-to-broker link.

The broker is a separate jailed process that holds a plugin instance's sockets while its guest sleeps. On this one connection each side serves the other: the broker's bootstrap capability is Sockets (the host forwards a guest's calls to it), and the host's is SocketHandler (the broker delivers messages and closes through it). The broker is the two-party server side; connect_socket_broker is the host's half.

Must run inside a tokio::task::LocalSet. Returns when the host hangs up.

Arguments

  • reader / writer - The link to the host.
  • make - Builds the broker's Sockets from the host's handler.

Errors

Returns an internal error when the link fails.

decode_storage_reply_bytes

pub fn decode_storage_reply_bytes(
    kind: StorageReplyKind,
    bytes: &[u8],
) -> Result<StorageReply>

Decodes one guest storage reply from an unpacked Cap'n Proto message, under the same caps the host applies to a live reply.

Arguments

  • kind - Which reply struct the message holds.
  • bytes - The message.

Returns

The decoded reply.

Errors

Returns PluginError when the framing, the codec or a cap rejects it.

encode_storage_reply_bytes

pub fn encode_storage_reply_bytes(reply: &StorageReply) -> Result<Vec<u8>>

Encodes one storage reply as an unpacked single-segment message, the inverse of decode_storage_reply_bytes.

Errors

Returns PluginError when a list cannot be encoded.

require_batch_len

pub fn require_batch_len(what: &str, len: usize) -> Result<()>

Rejects a batch request the guest is not obliged to serve.

Arguments

  • what - The operation name, for the error.
  • len - Keys or pairs in the request.

Errors

Returns invalid_params for an empty batch and payload_too_large for one above MAX_BATCH_KEYS.

validate_changes_page

pub fn validate_changes_page(sent: Option<&str>, page: &ChangesPage) -> Result<()>

Checks a guest's change feed page against the cursor the host sent.

Errors

Returns internal when the page holds more than MAX_CHANGES_PAGE changes, a change names an implausible key, the cursor is empty or longer than MAX_CHANGES_CURSOR_BYTES, or the page says more changes are ready without advancing the cursor.

validate_head_many

pub fn validate_head_many(
    sent: &[String],
    objects: &[Option<ObjectMetadata>],
) -> Result<()>

Checks a guest's headMany probes against the keys the host sent.

Errors

Returns internal unless there is one probe per key, in order, and every found object names the key it was asked for.

validate_key_outcomes

pub fn validate_key_outcomes(
    what: &str,
    sent: &[String],
    results: &[KeyOutcome],
) -> Result<()>

Checks a guest's per-key outcomes against the keys the host sent.

Arguments

  • what - The operation name, for the error.
  • sent - Keys the host sent, in order.
  • results - Outcomes the guest returned.

Errors

Returns internal unless there is exactly one outcome per key, in the same order and naming the same key.

validate_move_many_page

pub fn validate_move_many_page(
    request: &MoveManyRequest,
    page: &MoveManyPage,
) -> Result<()>

Checks a guest's moveMany page against the request it answers.

Pairs get one outcome per pair, keyed by its source, and no cursor. A prefix page carries at most MAX_BATCH_KEYS outcomes, each keyed by a source under the prefix (or the prefix itself), and a cursor that is at most MAX_CHANGES_CURSOR_BYTES and not the one the host sent.

Errors

Returns internal describing the first broken rule.

validate_translated_keys

pub fn validate_translated_keys(sent: &[String], translated: &[String]) -> Result<()>

Checks a guest's translateKeys answer against the host keys it was sent.

Errors

Returns internal unless there is one key per host key and every key is relative (no leading /), at most MAX_TRANSLATED_KEY_BYTES long, free of control characters, and has no empty, . or .. segment between / or \ separators: a key the host can store and read back without leaving the destination.

Constants

MAX_PLUGIN_MIGRATION_ID_BYTES

pub const MAX_PLUGIN_MIGRATION_ID_BYTES: usize = 128;

Maximum UTF-8 bytes of one plugin-chosen migration id.

PLUGIN_MIGRATIONS_TABLE

pub const PLUGIN_MIGRATIONS_TABLE: &str = "bookclerk_plugin_migrations";

Host-private plugin-binding migration journal (not a plugin-owned table).

PHYSICAL_STAR_COLUMN

pub const PHYSICAL_STAR_COLUMN: &str = "*";

Column name recorded for SELECT * / alias.* / RETURNING * on a physical table.

D1_PHYSICAL_LIKE_GLOB_PATTERN_BYTES

pub const D1_PHYSICAL_LIKE_GLOB_PATTERN_BYTES: u32 = 50;

Physical D1 LIKE/GLOB pattern cap in bytes.

D1_PORTABLE_LIKE_PATTERN_BYTES

pub const D1_PORTABLE_LIKE_PATTERN_BYTES: u32 = 16;

Conservative portable LIKE pattern cap for D1 while LIKE lowers to GLOB.

Cloudflare D1 allows 50 bytes in a LIKE/GLOB pattern. Worst-case expansion of [ / * / ? is 3×, so floor(50/3) = 16.

LIKE_GLOB_PATTERN_WRAP_BYTES

pub const LIKE_GLOB_PATTERN_WRAP_BYTES: usize = _;

Bytes added around a LIKE pattern by LIKE_GLOB_WRAP_PREFIX / LIKE_GLOB_WRAP_SUFFIX (the pattern itself is unchanged).

LIKE_GLOB_REWRITE_OVERHEAD

pub const LIKE_GLOB_REWRITE_OVERHEAD: usize = _;

Worst-case extra bytes per LIKE / NOT LIKE after sqlite-family GLOB wrapping.

LIKE_GLOB_WRAP_PREFIX

pub const LIKE_GLOB_WRAP_PREFIX: &str = "replace(replace(replace(replace(replace((";

Prefix of the sqlite-family LIKE→GLOB replace(...) wrap (before the pattern).

Must stay identical to the GLOB wrap in bookclerk-db-exec.

LIKE_GLOB_WRAP_SUFFIX

pub const LIKE_GLOB_WRAP_SUFFIX: &str = "), '[', '[[]'), '*', '[*]'), '?', '[?]'), '%', '*'), '_', '?')";

Suffix of the sqlite-family LIKE→GLOB replace(...) wrap (after the pattern).

LIKE_TO_GLOB_KEYWORD_EXTRA

pub const LIKE_TO_GLOB_KEYWORD_EXTRA: usize = 1;

Extra byte when LIKE is immediately followed by its pattern (no trivia): the rewrite emits GLOB (5) in place of LIKE (4).

SQLITE_FAMILY_DIV_MOD_NULLIF_EXTRA

pub const SQLITE_FAMILY_DIV_MOD_NULLIF_EXTRA: usize = 11;

Extra bytes for one / or % rewritten to NULLIF(operand, 0).

SQLITE_FAMILY_INSERT_OR_IGNORE_MAX_EXTRA

pub const SQLITE_FAMILY_INSERT_OR_IGNORE_MAX_EXTRA: usize = 256;

Conservative extra bytes for one INSERT OR IGNORE unique-conflict rewrite (conflict clause plus optional SELECT source wrap).

FEATURE_SCALAR_LIMITS

pub const FEATURE_SCALAR_LIMITS: &str = crate::plugin_capnp::FEATURE_SCALAR_LIMITS;

Guest honors scalar / stream-window / list-page caps.

FEATURE_STORAGE_CHANGES

pub const FEATURE_STORAGE_CHANGES: &str = crate::plugin_capnp::FEATURE_STORAGE_CHANGES;

Guest implements super::Destination::changes.

FEATURE_STORAGE_CONDITIONAL_WRITE

pub const FEATURE_STORAGE_CONDITIONAL_WRITE: &str = crate::plugin_capnp::FEATURE_STORAGE_CONDITIONAL_WRITE;

Guest enforces super::WriteOptions::if_match and super::WriteOptions::if_none_match.

FEATURE_STORAGE_COPY

pub const FEATURE_STORAGE_COPY: &str = crate::plugin_capnp::FEATURE_STORAGE_COPY;

Guest implements server-side super::Destination::copy.

FEATURE_STORAGE_DELETE_MANY

pub const FEATURE_STORAGE_DELETE_MANY: &str = crate::plugin_capnp::FEATURE_STORAGE_DELETE_MANY;

Guest implements super::Destination::delete_many.

FEATURE_STORAGE_HEAD_MANY

pub const FEATURE_STORAGE_HEAD_MANY: &str = crate::plugin_capnp::FEATURE_STORAGE_HEAD_MANY;

Guest implements super::Destination::head_many.

FEATURE_STORAGE_MOVE

pub const FEATURE_STORAGE_MOVE: &str = crate::plugin_capnp::FEATURE_STORAGE_MOVE;

Guest implements super::Destination::move_object.

FEATURE_STORAGE_MOVE_MANY

pub const FEATURE_STORAGE_MOVE_MANY: &str = crate::plugin_capnp::FEATURE_STORAGE_MOVE_MANY;

Guest implements super::Destination::move_many.

FEATURE_STORAGE_TRANSLATE_KEYS

pub const FEATURE_STORAGE_TRANSLATE_KEYS: &str = crate::plugin_capnp::FEATURE_STORAGE_TRANSLATE_KEYS;

Guest implements super::Destination::translate_keys.

FEATURE_STREAMS

pub const FEATURE_STREAMS: &str = crate::plugin_capnp::FEATURE_STREAMS;

Media moves through transferred crate::roles::ByteRange / ByteSource streams.

STORAGE_OPERATION_FEATURES

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

Every optional storage operation a host offers a storage guest, beside FEATURE_STORAGE_COPY. Each one the guest accepts replaces the host's fallback for that operation.

MAX_AI_EMBED_DIMENSIONS

pub const MAX_AI_EMBED_DIMENSIONS: u32 = crate::plugin_capnp::MAX_AI_EMBED_DIMENSIONS;

Most numbers in one embedding vector.

MAX_AI_EMBED_TEXTS

pub const MAX_AI_EMBED_TEXTS: u32 = crate::plugin_capnp::MAX_AI_EMBED_TEXTS;

Most texts in one text-embedding run.

MAX_AI_EMBED_TEXT_BYTES

pub const MAX_AI_EMBED_TEXT_BYTES: u32 = crate::plugin_capnp::MAX_AI_EMBED_TEXT_BYTES;

Longest text in a text-embedding run, in UTF-8 bytes.

MAX_AI_LANGUAGES

pub const MAX_AI_LANGUAGES: u32 = crate::plugin_capnp::MAX_AI_LANGUAGES;

Most language tags on one listed model.

MAX_AI_MODELS

pub const MAX_AI_MODELS: u32 = crate::plugin_capnp::MAX_AI_MODELS;

Most models one plugin lists on its ai entrypoint.

MAX_AI_MODEL_NAME_BYTES

pub const MAX_AI_MODEL_NAME_BYTES: u32 = crate::plugin_capnp::MAX_AI_MODEL_NAME_BYTES;

Longest model name on the AI binding (@<plugin id>/<model id>), in UTF-8 bytes.

MAX_COVER_BYTES

pub const MAX_COVER_BYTES: u32 = crate::plugin_capnp::MAX_COVER_BYTES;

Largest image body one CoverFetcher.fetchCovers URL may return.

MAX_COVER_HEADER_BYTES

pub const MAX_COVER_HEADER_BYTES: u32 = crate::plugin_capnp::MAX_COVER_HEADER_BYTES;

Longest cache header value one CoverFetcher.fetchCovers call carries in either direction, in bytes.

MAX_COVER_URLS

pub const MAX_COVER_URLS: u32 = crate::plugin_capnp::MAX_COVER_URLS;

Most URLs in one CoverFetcher.fetchCovers call.

MAX_CRON_BYTES

pub const MAX_CRON_BYTES: u32 = crate::plugin_capnp::MAX_CRON_BYTES;

Longest [triggers] crons source in bytes (ScheduledController.cron).

MAX_EVENT_CURSOR_BYTES

pub const MAX_EVENT_CURSOR_BYTES: u32 = crate::plugin_capnp::MAX_EVENT_CURSOR_BYTES;

Longest EventPublisher.read cursor in bytes.

MAX_EVENT_PAYLOAD_BYTES

pub const MAX_EVENT_PAYLOAD_BYTES: u32 = crate::plugin_capnp::MAX_EVENT_PAYLOAD_BYTES;

Maximum decoded size of a domain-event scalar payload (not a stream).

MAX_INGRESS_ORIGIN_BYTES

pub const MAX_INGRESS_ORIGIN_BYTES: u32 = crate::plugin_capnp::MAX_INGRESS_ORIGIN_BYTES;

Longest host name in IngressStarted.origin, in bytes.

MAX_KV_KEY_BYTES

pub const MAX_KV_KEY_BYTES: u32 = crate::plugin_capnp::MAX_KV_KEY_BYTES;

Longest KvNamespace key in UTF-8 bytes.

MAX_KV_METADATA_BYTES

pub const MAX_KV_METADATA_BYTES: u32 = crate::plugin_capnp::MAX_KV_METADATA_BYTES;

Largest KvNamespace metadata JSON text in bytes.

MAX_KV_VALUE_BYTES

pub const MAX_KV_VALUE_BYTES: u32 = crate::plugin_capnp::MAX_KV_VALUE_BYTES;

Largest KvNamespace value in bytes (a [[kv_namespaces]] row may lower its own cap but never raise it past this).

MAX_LIST_PAGE

pub const MAX_LIST_PAGE: u32 = crate::plugin_capnp::MAX_LIST_PAGE;

Maximum objects in one Destination.list page.

MAX_METADATA_AUDIO_FILES

pub const MAX_METADATA_AUDIO_FILES: u32 = crate::plugin_capnp::MAX_METADATA_AUDIO_FILES;

Most audio files a MetadataFiles.render request names.

MAX_METADATA_FILE_BYTES

pub const MAX_METADATA_FILE_BYTES: u32 = crate::plugin_capnp::MAX_METADATA_FILE_BYTES;

Largest metadata file MetadataFiles.parse reads and MetadataFiles.render returns, in bytes.

MAX_METADATA_FILE_CHAPTERS

pub const MAX_METADATA_FILE_CHAPTERS: u32 = crate::plugin_capnp::MAX_METADATA_FILE_CHAPTERS;

Most chapters in a MetadataFileRecord.

MAX_METADATA_FILE_DESCRIPTION_BYTES

pub const MAX_METADATA_FILE_DESCRIPTION_BYTES: u32 = crate::plugin_capnp::MAX_METADATA_FILE_DESCRIPTION_BYTES;

Longest description a MetadataFileRecord carries, in UTF-8 bytes.

MAX_METADATA_FILE_LIST_ENTRIES

pub const MAX_METADATA_FILE_LIST_ENTRIES: u32 = crate::plugin_capnp::MAX_METADATA_FILE_LIST_ENTRIES;

Most entries in each non-chapter list of a MetadataFileRecord.

MAX_METADATA_FILE_TEXT_BYTES

pub const MAX_METADATA_FILE_TEXT_BYTES: u32 = crate::plugin_capnp::MAX_METADATA_FILE_TEXT_BYTES;

Longest other text value in a MetadataFileRecord, in UTF-8 bytes.

MAX_NOTIFICATION_FIELDS

pub const MAX_NOTIFICATION_FIELDS: u32 = crate::plugin_capnp::MAX_NOTIFICATION_FIELDS;

Most labelled fields on one notification message or raise.

MAX_NOTIFICATION_FIELD_BYTES

pub const MAX_NOTIFICATION_FIELD_BYTES: u32 = crate::plugin_capnp::MAX_NOTIFICATION_FIELD_BYTES;

Longest notification field value, link, group key or alert key, in UTF-8 bytes.

MAX_NOTIFICATION_HTML_BYTES

pub const MAX_NOTIFICATION_HTML_BYTES: u32 = crate::plugin_capnp::MAX_NOTIFICATION_HTML_BYTES;

Longest notification HTML body, in UTF-8 bytes.

MAX_NOTIFICATION_TEXT_BYTES

pub const MAX_NOTIFICATION_TEXT_BYTES: u32 = crate::plugin_capnp::MAX_NOTIFICATION_TEXT_BYTES;

Longest notification plain-text or markdown body, in UTF-8 bytes.

MAX_NOTIFICATION_TITLE_BYTES

pub const MAX_NOTIFICATION_TITLE_BYTES: u32 = crate::plugin_capnp::MAX_NOTIFICATION_TITLE_BYTES;

Longest notification title or field name, in UTF-8 bytes.

MAX_NOTIFIER_ADDRESS_BYTES

pub const MAX_NOTIFIER_ADDRESS_BYTES: u32 = crate::plugin_capnp::MAX_NOTIFIER_ADDRESS_BYTES;

Longest notifier destination address document, in UTF-8 bytes.

MAX_ORIGIN_HEADERS

pub const MAX_ORIGIN_HEADERS: u32 = crate::plugin_capnp::MAX_ORIGIN_HEADERS;

Most header fields on one Origin.fetch request, and separately on its response.

MAX_ORIGIN_HEADER_BYTES

pub const MAX_ORIGIN_HEADER_BYTES: u32 = crate::plugin_capnp::MAX_ORIGIN_HEADER_BYTES;

Largest total UTF-8 bytes of header names and values on one Origin.fetch request, and separately on its response.

MAX_ORIGIN_TARGET_BYTES

pub const MAX_ORIGIN_TARGET_BYTES: u32 = crate::plugin_capnp::MAX_ORIGIN_TARGET_BYTES;

Longest OriginRequest.target (path and query), in bytes.

MAX_PLUGIN_MIGRATION_OPS

pub const MAX_PLUGIN_MIGRATION_OPS: u32 = crate::plugin_capnp::MAX_PLUGIN_MIGRATION_OPS;

Maximum already-separated operations in one plugin-owned migration.

MAX_PLUGIN_MIGRATION_REGISTRATION_BYTES

pub const MAX_PLUGIN_MIGRATION_REGISTRATION_BYTES: u32 = crate::plugin_capnp::MAX_PLUGIN_MIGRATION_REGISTRATION_BYTES;

Maximum aggregate UTF-8 bytes of plugin migration ids plus SQL in one databaseMigrations registration (Cap'n Proto framing is not counted).

MAX_PLUGIN_MIGRATION_TOTAL_OPS

pub const MAX_PLUGIN_MIGRATION_TOTAL_OPS: u32 = crate::plugin_capnp::MAX_PLUGIN_MIGRATION_TOTAL_OPS;

Maximum already-separated operations across one databaseMigrations registration (independent of the per-migration cap and of id+SQL UTF-8 bytes).

MAX_REFRESHED_CREDENTIAL_BYTES

pub const MAX_REFRESHED_CREDENTIAL_BYTES: u32 = crate::plugin_capnp::MAX_REFRESHED_CREDENTIAL_BYTES;

Longest refreshed credential blob a storefront may hand back in bytes (ScanPage.refreshedCredentials, PlainFetch.refreshedCredentials).

MAX_SCALAR_BYTES

pub const MAX_SCALAR_BYTES: u32 = crate::plugin_capnp::MAX_SCALAR_BYTES;

Maximum decoded size of an ordinary RPC scalar value (not a stream window).

MAX_SCAN_CURSOR_BYTES

pub const MAX_SCAN_CURSOR_BYTES: u32 = crate::plugin_capnp::MAX_SCAN_CURSOR_BYTES;

Longest scan cursor or sync token in bytes.

MAX_SCAN_PAGE_BOOKS

pub const MAX_SCAN_PAGE_BOOKS: u32 = crate::plugin_capnp::MAX_SCAN_PAGE_BOOKS;

Most titles, and separately most removed product ids, in one ContentSource.scan page.

MAX_SOCKETS_PER_INSTANCE

pub const MAX_SOCKETS_PER_INSTANCE: u32 = crate::plugin_capnp::MAX_SOCKETS_PER_INSTANCE;

Most host-brokered sockets one plugin instance may hold open at once.

MAX_SOCKET_ATTACHMENT_BYTES

pub const MAX_SOCKET_ATTACHMENT_BYTES: u32 = crate::plugin_capnp::MAX_SOCKET_ATTACHMENT_BYTES;

Largest per-socket attachment the host keeps, in bytes.

MAX_SOCKET_AUTO_RESPONSES

pub const MAX_SOCKET_AUTO_RESPONSES: u32 = crate::plugin_capnp::MAX_SOCKET_AUTO_RESPONSES;

Most heartbeat pairs one Sockets.connect may declare.

MAX_SOCKET_AUTO_RESPONSE_BYTES

pub const MAX_SOCKET_AUTO_RESPONSE_BYTES: u32 = crate::plugin_capnp::MAX_SOCKET_AUTO_RESPONSE_BYTES;

Largest heartbeat request or response frame, in bytes.

MAX_SOCKET_FRAME_BYTES

pub const MAX_SOCKET_FRAME_BYTES: u32 = crate::plugin_capnp::MAX_SOCKET_FRAME_BYTES;

Largest WebSocket message Sockets.send accepts or SocketHandler.message delivers, in bytes.

MAX_SOCKET_HEADERS

pub const MAX_SOCKET_HEADERS: u32 = crate::plugin_capnp::MAX_SOCKET_HEADERS;

Most request headers, and separately subprotocols, on one Sockets.connect.

MAX_SOCKET_URL_BYTES

pub const MAX_SOCKET_URL_BYTES: u32 = crate::plugin_capnp::MAX_SOCKET_URL_BYTES;

Longest Sockets.connect URL, in bytes.

MAX_STREAM_WINDOW_BYTES

pub const MAX_STREAM_WINDOW_BYTES: u32 = crate::plugin_capnp::MAX_STREAM_WINDOW_BYTES;

Maximum bytes returned by one ByteSource.pull (flow-control window).

MAX_WEBHOOK_BODY_BYTES

pub const MAX_WEBHOOK_BODY_BYTES: u32 = crate::plugin_capnp::MAX_WEBHOOK_BODY_BYTES;

Largest stored webhook request body, in bytes (1 MiB).

MAX_WEBHOOK_HEADERS

pub const MAX_WEBHOOK_HEADERS: u32 = crate::plugin_capnp::MAX_WEBHOOK_HEADERS;

Most request headers a [[webhooks]] row keeps.

MAX_WEBHOOK_HEADER_VALUE_BYTES

pub const MAX_WEBHOOK_HEADER_VALUE_BYTES: u32 = crate::plugin_capnp::MAX_WEBHOOK_HEADER_VALUE_BYTES;

Longest kept request header value, in bytes.

MAX_WEBHOOK_LEASE_ID_BYTES

pub const MAX_WEBHOOK_LEASE_ID_BYTES: u32 = crate::plugin_capnp::MAX_WEBHOOK_LEASE_ID_BYTES;

Longest WebhookDelivery.leaseId, in bytes.

MAX_WEBHOOK_NAME_BYTES

pub const MAX_WEBHOOK_NAME_BYTES: u32 = crate::plugin_capnp::MAX_WEBHOOK_NAME_BYTES;

Longest [[webhooks]] name, in bytes.

MAX_WEBHOOK_PULL_BATCH

pub const MAX_WEBHOOK_PULL_BATCH: u32 = crate::plugin_capnp::MAX_WEBHOOK_PULL_BATCH;

Most deliveries one Webhooks.pull returns.

MAX_WEBHOOK_VISIBILITY_MS

pub const MAX_WEBHOOK_VISIBILITY_MS: u32 = crate::plugin_capnp::MAX_WEBHOOK_VISIBILITY_MS;

Longest Webhooks.pull visibility timeout, in milliseconds (12 hours).

PRODUCT_API_VERSION

pub const PRODUCT_API_VERSION: u32 = crate::plugin_capnp::API_VERSION;

Product ABI version (apiVersion / plugin.toml api_version).

PURCHASE_HINTS_BUDGET

pub const PURCHASE_HINTS_BUDGET: Duration = _;

How long the default ContentSource::purchase_hints keeps starting one-title lookups before answering with what it has. Well under the host's 10 s batch deadline, so even a slow last lookup lands before it and a store without a bulk endpoint still returns the titles it priced.

PURCHASE_HINTS_CONCURRENCY

pub const PURCHASE_HINTS_CONCURRENCY: usize = 4;

How many one-title lookups the default ContentSource::purchase_hints keeps in flight at once. A store without a bulk endpoint answers a page of cards in about a quarter of the time one lookup after another takes, while staying a polite handful of requests rather than a burst.

JSON_MEDIA_TYPE

pub const JSON_MEDIA_TYPE: &str = "application/json";

Media type of a JSON ExtensibleConfig payload.

MAX_CHECKPOINT_BYTES

pub const MAX_CHECKPOINT_BYTES: u32 = crate::plugin_capnp::MAX_CHECKPOINT_BYTES;

Maximum checkpoint payload size (bytes).

MAX_BATCH_KEYS

pub const MAX_BATCH_KEYS: u32 = crate::plugin_capnp::MAX_BATCH_KEYS;

Maximum keys or key pairs in one moveMany, deleteMany or headMany call, and maximum outcomes in one reply.

MAX_CHANGES_CURSOR_BYTES

pub const MAX_CHANGES_CURSOR_BYTES: u32 = crate::plugin_capnp::MAX_CHANGES_CURSOR_BYTES;

Maximum bytes of a Destination.changes cursor.

MAX_CHANGES_PAGE

pub const MAX_CHANGES_PAGE: u32 = crate::plugin_capnp::MAX_CHANGES_PAGE;

Maximum changes in one Destination.changes page.

MAX_TRANSLATED_KEY_BYTES

pub const MAX_TRANSLATED_KEY_BYTES: usize = 4096;

Longest key a guest may translate a host key into, in UTF-8 bytes. Generous next to any store's own limit (S3 keys stop at 1024 bytes, file-system paths usually at 4096).

PLUGIN_TOML_SCHEMA_JSON

pub const PLUGIN_TOML_SCHEMA_JSON: &str = "{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"https://bookclerk.dev/schemas/plugin-toml.json\",\n  \"title\": \"BookclerkPluginToml\",\n  \"description\": \"Install descriptor for a Bookclerk plugin (plugin.toml), api_version = 3. Keys use TOML/snake_case. There is no plugin `kind`; handler family is derived from entrypoints and triggers. The `id` is a display/CLI alias, not a globally unique security identity. Durable identity is the host-computed provenance-qualified PluginKey. capabilities.network.domains is workerd-only (hostname allowlist for isolate fetch()). Native guests omit domains and declare capabilities.network.tcp for mediated connect(); ambient AF_INET is denied.\",\n  \"type\": \"object\",\n  \"additionalProperties\": false,\n  \"required\": [\"api_version\", \"id\", \"capabilities\"],\n  \"properties\": {\n    \"api_version\": { \"type\": \"integer\", \"enum\": [3] },\n    \"id\": {\n      \"type\": \"string\",\n      \"minLength\": 2,\n      \"maxLength\": 32,\n      \"pattern\": \"^[a-z0-9]+(?:_[a-z0-9]+)*$\",\n      \"description\": \"Display / CLI alias. Not globally unique and not a privilege. Lowercase letters, digits, and single underscores only (2\u{2013}32 chars); no leading/trailing or doubled `_`. When two installs share an alias, address them with a provenance-qualified PluginKey.\"\n    },\n    \"name\": { \"type\": \"string\" },\n    \"version\": { \"type\": \"string\" },\n    \"logo\": {\n      \"type\": \"string\",\n      \"description\": \"Optional Settings/UI logo: https:// or http:// URL (browser loads directly), or a relative image path under the plugin install root (host serves via GET /api/plugins/{id}/logo when the alias is unambiguous). Embedded paths must not contain \'..\' and must end with .png/.jpg/.jpeg/.gif/.webp/.svg/.ico.\"\n    },\n    \"runtime\": {\n      \"type\": \"string\",\n      \"enum\": [\"native\", \"workerd\"],\n      \"default\": \"native\"\n    },\n    \"command\": { \"type\": \"string\", \"minLength\": 1 },\n    \"args\": {\n      \"type\": \"array\",\n      \"items\": { \"type\": \"string\" }\n    },\n    \"entrypoints\": {\n      \"type\": \"array\",\n      \"description\": \"Named capabilities this plugin exports from PluginWorker.open.\",\n      \"items\": {\n        \"type\": \"string\",\n        \"enum\": [\"storefront\", \"storage\", \"databaseAdapter\", \"remoteLibrary\", \"cli\", \"oidc\", \"metadata\", \"covers\", \"metadataFiles\", \"notifier\", \"ingress\", \"ai\"]\n      }\n    },\n    \"media\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"description\": \"Work kinds and edition carriers the plugin works with. Required, with non-empty works and lists, for a plugin exporting the storefront or metadata entrypoint; forbidden for every other plugin. describe() must declare the same kinds.\",\n      \"properties\": {\n        \"works\": {\n          \"type\": \"array\",\n          \"description\": \"Work kinds the plugin reports.\",\n          \"items\": { \"type\": \"string\", \"enum\": [\"book\", \"podcast\"] }\n        },\n        \"lists\": {\n          \"type\": \"array\",\n          \"description\": \"Edition carriers the plugin reports in scans, catalog search and metadata records.\",\n          \"items\": { \"type\": \"string\", \"enum\": [\"audio\", \"ebook\", \"print\"] }\n        },\n        \"fetches\": {\n          \"type\": \"array\",\n          \"description\": \"Edition carriers fetchTitle can deliver; a subset of lists. Storefronts only.\",\n          \"items\": { \"type\": \"string\", \"enum\": [\"audio\", \"ebook\", \"print\"] }\n        }\n      }\n    },\n    \"metadata_files\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"dialects\"],\n      \"description\": \"Metadata file dialects (sidecars such as metadata.json, OPF, NFO, CUE) the plugin reads and writes. Required, with at least one dialect, for a plugin exporting the metadataFiles entrypoint; forbidden for every other plugin.\",\n      \"properties\": {\n        \"dialects\": {\n          \"type\": \"array\",\n          \"minItems\": 1,\n          \"items\": { \"$ref\": \"#/$defs/MetadataFileDialect\" }\n        }\n      }\n    },\n    \"notifier\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"destinations\"],\n      \"description\": \"What a notifier sends to and in which formats. Required for a plugin exporting the notifier entrypoint; forbidden for every other plugin.\",\n      \"properties\": {\n        \"destinations\": {\n          \"type\": \"array\",\n          \"minItems\": 1,\n          \"uniqueItems\": true,\n          \"description\": \"Destination kinds: channel (one shared target the operator sets up) and personal (a patron\'s own address).\",\n          \"items\": { \"type\": \"string\", \"enum\": [\"channel\", \"personal\"] }\n        },\n        \"account_mail\": {\n          \"type\": \"boolean\",\n          \"description\": \"Whether the plugin can carry account mail (invites, password resets, recovery). Needs a required, non-secret email address field. Defaults to false.\"\n        },\n        \"formats\": {\n          \"type\": \"array\",\n          \"minItems\": 1,\n          \"uniqueItems\": true,\n          \"contains\": { \"const\": \"text\" },\n          \"description\": \"Body formats the service shows; must include text. Defaults to [\\\"text\\\"].\",\n          \"items\": { \"type\": \"string\", \"enum\": [\"text\", \"markdown\", \"html\"] }\n        },\n        \"address_fields\": {\n          \"type\": \"array\",\n          \"maxItems\": 16,\n          \"description\": \"Fields of a personal address; required exactly when destinations names personal, with at least one required field.\",\n          \"items\": { \"$ref\": \"#/$defs/NotifierAddressField\" }\n        }\n      }\n    },\n    \"notifications\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"description\": \"Notification types the plugin raises through env.NOTIFY. Declaring any grants the NOTIFY binding.\",\n      \"properties\": {\n        \"types\": {\n          \"type\": \"array\",\n          \"maxItems\": 64,\n          \"items\": { \"$ref\": \"#/$defs/NotificationType\" }\n        }\n      }\n    },\n    \"ingress\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"kind\"],\n      \"description\": \"How an ingress plugin serves the library publicly. Required for a plugin exporting the ingress entrypoint; forbidden for every other plugin.\",\n      \"properties\": {\n        \"kind\": {\n          \"type\": \"string\",\n          \"enum\": [\"relay\", \"direct\"],\n          \"description\": \"relay: the provider relays each request to the plugin, which hands it to the library through ORIGIN. direct: the public address points at the daemon; the plugin only keeps it current.\"\n        }\n      }\n    },\n    \"ai\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"description\": \"Model tasks the plugin serves on its ai entrypoint and the tasks it calls through env.AI.\",\n      \"properties\": {\n        \"serves\": {\n          \"type\": \"array\",\n          \"uniqueItems\": true,\n          \"description\": \"Tasks the plugin\'s models perform. Required, with at least one task, for a plugin exporting the ai entrypoint; forbidden for every other plugin.\",\n          \"items\": { \"$ref\": \"#/$defs/AiTask\" }\n        },\n        \"calls\": {\n          \"type\": \"array\",\n          \"uniqueItems\": true,\n          \"description\": \"Tasks the plugin runs through env.AI. Declaring any asks the operator for the AI binding.\",\n          \"items\": { \"$ref\": \"#/$defs/AiTask\" }\n        }\n      }\n    },\n    \"workerd\": { \"$ref\": \"#/$defs/WorkerdRuntime\" },\n    \"modules\": {\n      \"type\": \"array\",\n      \"items\": { \"$ref\": \"#/$defs/ModuleSpec\" }\n    },\n    \"triggers\": { \"$ref\": \"#/$defs/Triggers\" },\n    \"events\": { \"$ref\": \"#/$defs/Events\" },\n    \"databases\": {\n      \"type\": \"array\",\n      \"description\": \"Named plugin-owned database bindings (Workers-style).\",\n      \"maxItems\": 8,\n      \"items\": { \"$ref\": \"#/$defs/DatabaseBinding\" }\n    },\n    \"vars\": {\n      \"type\": \"object\",\n      \"description\": \"Operator config binding (`CONFIG`). Declares that the guest receives CONFIG; values come from [[settings]] defaults and the plugin instance document. An empty table is the usual form.\"\n    },\n    \"settings\": {\n      \"type\": \"array\",\n      \"description\": \"Operator settings schema ([[settings]]): keys an instance document may set, their types, enum values, and defaults. The host validates documents against it and renders it in Settings. Non-secret entries require [vars]; type = \\\"secret\\\" entries require [secrets].\",\n      \"maxItems\": 32,\n      \"items\": { \"$ref\": \"#/$defs/SettingSpec\" }\n    },\n    \"secrets\": { \"$ref\": \"#/$defs/NamedBinding\" },\n    \"kv_namespaces\": {\n      \"type\": \"array\",\n      \"description\": \"Durable KV bindings (default name KV) served from the library database: Workers KVNamespace-shaped get/put/delete/list with expiration and metadata, scoped to the plugin and the row\'s namespace. Distinct from [[databases]].\",\n      \"items\": { \"$ref\": \"#/$defs/KvNamespace\" }\n    },\n    \"queues\": { \"$ref\": \"#/$defs/Queues\" },\n    \"work_fs\": { \"$ref\": \"#/$defs/NamedBinding\" },\n    \"oauth\": { \"$ref\": \"#/$defs/NamedBinding\" },\n    \"capabilities\": { \"$ref\": \"#/$defs/Capabilities\" },\n    \"cli\": { \"$ref\": \"#/$defs/CliSchema\" },\n    \"oidc\": { \"$ref\": \"#/$defs/OidcManifest\" }\n  },\n  \"allOf\": [\n    {\n      \"if\": {\n        \"properties\": { \"runtime\": { \"const\": \"workerd\" } },\n        \"required\": [\"runtime\"]\n      },\n      \"then\": { \"required\": [\"workerd\"] }\n    },\n    {\n      \"if\": {\n        \"anyOf\": [\n          { \"properties\": { \"runtime\": { \"const\": \"native\" } } },\n          { \"not\": { \"required\": [\"runtime\"] } }\n        ]\n      },\n      \"then\": {\n        \"required\": [\"command\"],\n        \"properties\": {\n          \"capabilities\": {\n            \"properties\": {\n              \"network\": {\n                \"properties\": {\n                  \"domains\": false\n                }\n              }\n            }\n          }\n        }\n      }\n    },\n    {\n      \"if\": {\n        \"properties\": {\n          \"runtime\": { \"const\": \"workerd\" },\n          \"capabilities\": {\n            \"properties\": {\n              \"network\": {\n                \"properties\": { \"mode\": { \"const\": \"outbound\" } },\n                \"required\": [\"mode\"]\n              }\n            },\n            \"required\": [\"network\"]\n          }\n        },\n        \"required\": [\"runtime\", \"capabilities\"]\n      },\n      \"then\": {\n        \"properties\": {\n          \"capabilities\": {\n            \"properties\": {\n              \"network\": {\n                \"required\": [\"domains\"],\n                \"properties\": {\n                  \"domains\": {\n                    \"type\": \"array\",\n                    \"minItems\": 1,\n                    \"items\": { \"type\": \"string\", \"minLength\": 1 }\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    },\n    {\n      \"if\": {\n        \"properties\": {\n          \"entrypoints\": {\n            \"anyOf\": [{ \"contains\": { \"const\": \"storefront\" } }, { \"contains\": { \"const\": \"metadata\" } }]\n          }\n        },\n        \"required\": [\"entrypoints\"]\n      },\n      \"then\": {\n        \"required\": [\"media\"],\n        \"properties\": {\n          \"media\": {\n            \"required\": [\"works\", \"lists\"],\n            \"properties\": { \"works\": { \"minItems\": 1 }, \"lists\": { \"minItems\": 1 } }\n          }\n        }\n      },\n      \"else\": { \"properties\": { \"media\": false } }\n    },\n    {\n      \"if\": {\n        \"properties\": { \"entrypoints\": { \"contains\": { \"const\": \"metadataFiles\" } } },\n        \"required\": [\"entrypoints\"]\n      },\n      \"then\": { \"required\": [\"metadata_files\"] },\n      \"else\": { \"properties\": { \"metadata_files\": false } }\n    },\n    {\n      \"if\": {\n        \"properties\": { \"entrypoints\": { \"contains\": { \"const\": \"notifier\" } } },\n        \"required\": [\"entrypoints\"]\n      },\n      \"then\": { \"required\": [\"notifier\"] },\n      \"else\": { \"properties\": { \"notifier\": false } }\n    },\n    {\n      \"if\": {\n        \"properties\": { \"entrypoints\": { \"contains\": { \"const\": \"ingress\" } } },\n        \"required\": [\"entrypoints\"]\n      },\n      \"then\": { \"required\": [\"ingress\"] },\n      \"else\": { \"properties\": { \"ingress\": false } }\n    },\n    {\n      \"if\": {\n        \"properties\": { \"entrypoints\": { \"contains\": { \"const\": \"ai\" } } },\n        \"required\": [\"entrypoints\"]\n      },\n      \"then\": {\n        \"required\": [\"ai\"],\n        \"properties\": { \"ai\": { \"required\": [\"serves\"], \"properties\": { \"serves\": { \"minItems\": 1 } } } }\n      },\n      \"else\": { \"properties\": { \"ai\": { \"properties\": { \"serves\": { \"maxItems\": 0 } } } } }\n    }\n  ],\n  \"$defs\": {\n    \"AiTask\": {\n      \"type\": \"string\",\n      \"enum\": [\"textEmbeddings\"],\n      \"description\": \"What a model does: textEmbeddings turns each text into one vector.\"\n    },\n    \"NotifierAddressField\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"key\", \"label\"],\n      \"description\": \"One field of a patron\'s personal address, such as an email address or a chat id.\",\n      \"properties\": {\n        \"key\": {\n          \"type\": \"string\",\n          \"pattern\": \"^[a-z][a-z0-9_]{0,63}$\",\n          \"description\": \"Key in the address document; unique within the plugin.\"\n        },\n        \"label\": { \"type\": \"string\", \"minLength\": 1, \"description\": \"Label shown to the patron.\" },\n        \"required\": { \"type\": \"boolean\", \"description\": \"Whether the patron must fill it in. Defaults to false.\" },\n        \"secret\": {\n          \"type\": \"boolean\",\n          \"description\": \"Whether the value is a secret (a personal token): sealed at rest and never shown again. Defaults to false.\"\n        }\n      }\n    },\n    \"NotificationType\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"id\", \"audience\", \"severity\", \"title\"],\n      \"description\": \"One notification type the plugin raises; the host names it <plugin>:<id>.\",\n      \"properties\": {\n        \"id\": {\n          \"type\": \"string\",\n          \"pattern\": \"^[a-z][a-z0-9_]{0,63}$\",\n          \"description\": \"Type id, unique within the plugin.\"\n        },\n        \"audience\": {\n          \"type\": \"string\",\n          \"enum\": [\"operational\", \"patron\"],\n          \"description\": \"operational goes to administrators\' channels; patron goes to the one patron a raise names. account is reserved to Bookclerk.\"\n        },\n        \"severity\": { \"type\": \"string\", \"enum\": [\"info\", \"warning\", \"critical\"] },\n        \"title\": {\n          \"type\": \"string\",\n          \"minLength\": 1,\n          \"maxLength\": 256,\n          \"description\": \"One-line name shown in notification settings.\"\n        }\n      }\n    },\n    \"MetadataFileDialect\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"id\", \"name\", \"fields\"],\n      \"anyOf\": [\n        { \"required\": [\"file_names\"], \"properties\": { \"file_names\": { \"minItems\": 1 } } },\n        { \"required\": [\"suffixes\"], \"properties\": { \"suffixes\": { \"minItems\": 1 } } }\n      ],\n      \"if\": { \"required\": [\"fields\"], \"properties\": { \"fields\": { \"contains\": { \"const\": \"credits\" } } } },\n      \"then\": { \"required\": [\"credit_roles\"], \"properties\": { \"credit_roles\": { \"minItems\": 1 } } },\n      \"else\": { \"properties\": { \"credit_roles\": { \"maxItems\": 0 } } },\n      \"description\": \"One metadata file format. The host routes a file by exact name first, then by the longest matching suffix, both compared without ASCII case.\",\n      \"properties\": {\n        \"id\": {\n          \"type\": \"string\",\n          \"pattern\": \"^[a-z][a-z0-9_]{0,63}$\",\n          \"description\": \"Dialect id, unique within the plugin; passed back in parse and render.\"\n        },\n        \"name\": { \"type\": \"string\", \"minLength\": 1, \"description\": \"Name shown in settings and on a book\'s files list.\" },\n        \"file_names\": {\n          \"type\": \"array\",\n          \"description\": \"Exact file names the dialect reads (metadata.json).\",\n          \"items\": { \"type\": \"string\", \"minLength\": 1 }\n        },\n        \"suffixes\": {\n          \"type\": \"array\",\n          \"description\": \"File name endings the dialect reads (.opf, .metadata.json); each starts with a dot.\",\n          \"items\": { \"type\": \"string\", \"pattern\": \"^\\\\..+\" }\n        },\n        \"fields\": {\n          \"type\": \"array\",\n          \"minItems\": 1,\n          \"description\": \"Fields the format carries.\",\n          \"items\": { \"type\": \"string\", \"enum\": [\"title\", \"subtitle\", \"description\", \"publisher\", \"publishedAt\", \"language\", \"genres\", \"tags\", \"abridgement\", \"expressionKind\", \"identifiers\", \"credits\", \"series\", \"chapters\", \"duration\"] }\n        },\n        \"credit_roles\": {\n          \"type\": \"array\",\n          \"description\": \"Credit roles the format carries; required exactly when fields names credits.\",\n          \"items\": { \"type\": \"string\", \"enum\": [\"author\", \"narrator\", \"translator\", \"editor\", \"illustrator\", \"publisher\", \"host\", \"cast\", \"adaptor\"] }\n        },\n        \"writes\": { \"type\": \"boolean\", \"description\": \"Whether the dialect also writes files (render). Defaults to false.\" }\n      }\n    },\n    \"Capabilities\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"network\"],\n      \"properties\": {\n        \"network\": { \"$ref\": \"#/$defs/NetworkCapabilities\" }\n      }\n    },\n    \"NetworkCapabilities\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"mode\"],\n      \"properties\": {\n        \"mode\": { \"type\": \"string\", \"enum\": [\"deny\", \"outbound\"] },\n        \"domains\": {\n          \"type\": \"array\",\n          \"description\": \"Workerd-only: initial-request host allowlist for isolate egress. Forbidden on runtime=native. The operator may add destinations beyond this list; the guest cannot.\",\n          \"items\": { \"type\": \"string\", \"minLength\": 1 }\n        },\n        \"tcp\": {\n          \"type\": \"array\",\n          \"description\": \"Raw TCP connect grants (host + ports). Fetch domain grants do not imply TCP.\",\n          \"items\": { \"$ref\": \"#/$defs/TcpCapability\" }\n        },\n        \"allow_undeclared_public_redirects\": {\n          \"type\": \"boolean\",\n          \"description\": \"When true, fetch redirects may target undeclared public hosts. Address-space policy still applies.\"\n        },\n        \"address_cidrs\": {\n          \"type\": \"array\",\n          \"description\": \"Explicit CIDR grants beyond the public Internet. No blanket private=true.\",\n          \"items\": { \"type\": \"string\", \"minLength\": 1 }\n        },\n        \"own_user_agent\": { \"$ref\": \"#/$defs/OwnUserAgent\" }\n      },\n      \"if\": { \"properties\": { \"mode\": { \"const\": \"deny\" } } },\n      \"then\": { \"not\": { \"required\": [\"own_user_agent\"] } }\n    },\n    \"OwnUserAgent\": {\n      \"type\": \"object\",\n      \"description\": \"Hosts that receive the plugin\'s own User-Agent instead of the host\'s bookclerk/<version> agent. Shown on the consent form; the operator may refuse.\",\n      \"additionalProperties\": false,\n      \"required\": [\"hosts\", \"reason\"],\n      \"properties\": {\n        \"hosts\": {\n          \"type\": \"array\",\n          \"description\": \"Exact hosts or *. wildcards (never *).\",\n          \"minItems\": 1,\n          \"maxItems\": 32,\n          \"items\": {\n            \"type\": \"string\",\n            \"minLength\": 1,\n            \"pattern\": \"^(\\\\*\\\\.)?[^*\\\\s,/:%@?#\\\\\\\\]+$\"\n          }\n        },\n        \"reason\": {\n          \"type\": \"string\",\n          \"description\": \"One line for the operator on why these hosts need the plugin\'s own agent, such as the app API contract it follows.\",\n          \"minLength\": 1,\n          \"maxLength\": 300,\n          \"pattern\": \"^[^\\\\r\\\\n]+$\"\n        }\n      }\n    },\n    \"TcpCapability\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"host\", \"ports\"],\n      \"properties\": {\n        \"host\": { \"type\": \"string\", \"minLength\": 1 },\n        \"ports\": {\n          \"type\": \"array\",\n          \"items\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 65535 },\n          \"minItems\": 1\n        }\n      }\n    },\n    \"Triggers\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"properties\": {\n        \"crons\": {\n          \"type\": \"array\",\n          \"description\": \"Five-field UTC cron schedules (minute hour day-of-month month day-of-week) for the default entrypoint\'s scheduled(controller) handler, as in Workers. Values, ranges, lists, */step and JAN-DEC / SUN-SAT names; no L, W, # or @macros. At most 8, no duplicates.\",\n          \"maxItems\": 8,\n          \"uniqueItems\": true,\n          \"items\": {\n            \"type\": \"string\",\n            \"minLength\": 9,\n            \"maxLength\": 128,\n            \"pattern\": \"^\\\\s*\\\\S+(\\\\s+\\\\S+){4}\\\\s*$\"\n          }\n        },\n        \"jobs\": {\n          \"type\": \"array\",\n          \"items\": { \"type\": \"string\", \"minLength\": 1 }\n        }\n      }\n    },\n    \"Events\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"properties\": {\n        \"consumers\": {\n          \"type\": \"array\",\n          \"items\": { \"$ref\": \"#/$defs/EventConsumer\" }\n        },\n        \"producers\": {\n          \"type\": \"array\",\n          \"items\": { \"$ref\": \"#/$defs/EventProducer\" }\n        }\n      }\n    },\n    \"EventConsumer\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"type\"],\n      \"properties\": {\n        \"type\": {\n          \"type\": \"string\",\n          \"minLength\": 1,\n          \"pattern\": \"^[a-z][a-z0-9_]*$\"\n        },\n        \"schema_versions\": {\n          \"type\": \"array\",\n          \"items\": { \"type\": \"integer\", \"minimum\": 1 },\n          \"minItems\": 1\n        },\n        \"supports_suspend\": { \"type\": \"boolean\", \"default\": false },\n        \"resource_class\": { \"type\": \"string\", \"enum\": [\"network\"], \"default\": \"network\" },\n        \"filter\": { \"type\": \"object\" },\n        \"max_retries\": { \"type\": \"integer\", \"minimum\": 0 },\n        \"message_retention_period\": { \"type\": \"integer\", \"minimum\": 60, \"maximum\": 1209600 }\n      }\n    },\n    \"EventProducer\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"type\"],\n      \"properties\": {\n        \"type\": {\n          \"type\": \"string\",\n          \"minLength\": 1,\n          \"pattern\": \"^[a-z][a-z0-9_]*$\"\n        },\n        \"binding\": { \"type\": \"string\", \"minLength\": 1 }\n      }\n    },\n    \"Queues\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"description\": \"Workers Queues: producers are `env` send bindings, consumers are `queue(batch)` triggers. Queue names are `[a-z0-9][a-z0-9._-]*` (at most 63 chars); the `core.` and `host.` prefixes are reserved for the host.\",\n      \"properties\": {\n        \"producers\": { \"type\": \"array\", \"items\": { \"$ref\": \"#/$defs/QueueProducer\" } },\n        \"consumers\": { \"type\": \"array\", \"items\": { \"$ref\": \"#/$defs/QueueConsumer\" } }\n      }\n    },\n    \"QueueProducer\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"queue\", \"binding\"],\n      \"properties\": {\n        \"queue\": {\n          \"type\": \"string\",\n          \"minLength\": 1,\n          \"maxLength\": 63,\n          \"pattern\": \"^[a-z0-9][a-z0-9._-]*$\"\n        },\n        \"binding\": { \"type\": \"string\", \"minLength\": 1, \"pattern\": \"^[A-Z][A-Z0-9_]*$\" }\n      }\n    },\n    \"QueueConsumer\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"queue\"],\n      \"properties\": {\n        \"queue\": {\n          \"type\": \"string\",\n          \"minLength\": 1,\n          \"maxLength\": 63,\n          \"pattern\": \"^[a-z0-9][a-z0-9._-]*$\"\n        },\n        \"max_batch_size\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 100, \"default\": 10 },\n        \"max_batch_timeout\": { \"type\": \"integer\", \"minimum\": 0, \"maximum\": 60, \"default\": 5 },\n        \"max_retries\": { \"type\": \"integer\", \"minimum\": 0, \"maximum\": 100, \"default\": 3 },\n        \"dead_letter_queue\": {\n          \"type\": \"string\",\n          \"minLength\": 1,\n          \"maxLength\": 63,\n          \"pattern\": \"^[a-z0-9][a-z0-9._-]*$\"\n        },\n        \"retry_delay\": { \"type\": \"integer\", \"minimum\": 0, \"maximum\": 43200, \"default\": 0 },\n        \"max_concurrency\": { \"type\": \"integer\", \"minimum\": 1 },\n        \"message_retention_period\": { \"type\": \"integer\", \"minimum\": 60, \"maximum\": 1209600 }\n      }\n    },\n    \"SettingSpec\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"key\", \"type\"],\n      \"properties\": {\n        \"key\": {\n          \"type\": \"string\",\n          \"pattern\": \"^[a-z][a-z0-9_]{0,63}$\",\n          \"description\": \"Setting key, unique within the plugin; the CONFIG / SECRETS property name.\"\n        },\n        \"label\": { \"type\": \"string\", \"description\": \"Operator-facing label; defaults to the key.\" },\n        \"type\": {\n          \"type\": \"string\",\n          \"enum\": [\"string\", \"bool\", \"integer\", \"enum\", \"secret\"],\n          \"description\": \"Value type. `secret` values are sealed by the host and delivered in SECRETS, never stored in the instance document.\"\n        },\n        \"values\": {\n          \"type\": \"array\",\n          \"maxItems\": 64,\n          \"description\": \"Allowed values for type = \\\"enum\\\"; forbidden otherwise.\",\n          \"items\": {\n            \"type\": \"object\",\n            \"additionalProperties\": false,\n            \"required\": [\"id\"],\n            \"properties\": {\n              \"id\": { \"type\": \"string\", \"minLength\": 1, \"maxLength\": 1024 },\n              \"label\": { \"type\": \"string\" }\n            }\n          }\n        },\n        \"default\": {\n          \"type\": [\"string\", \"boolean\", \"integer\"],\n          \"description\": \"Default applied when the instance document omits the key. Not allowed for secrets.\"\n        },\n        \"required\": { \"type\": \"boolean\", \"default\": false },\n        \"description\": { \"type\": \"string\" }\n      }\n    },\n    \"DatabaseBinding\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"binding\"],\n      \"properties\": {\n        \"binding\": {\n          \"type\": \"string\",\n          \"pattern\": \"^[A-Z][A-Z0-9_]*$\",\n          \"maxLength\": 32\n        }\n      }\n    },\n    \"NamedBinding\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"properties\": {\n        \"binding\": { \"type\": \"string\", \"minLength\": 1 }\n      }\n    },\n    \"KvNamespace\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"properties\": {\n        \"binding\": { \"type\": \"string\", \"minLength\": 1 },\n        \"namespace\": {\n          \"type\": \"string\",\n          \"minLength\": 1,\n          \"maxLength\": 63,\n          \"pattern\": \"^[a-z0-9][a-z0-9._-]*$\"\n        },\n        \"max_value_bytes\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 1048576, \"default\": 65536 },\n        \"max_keys\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 1000000, \"default\": 10000 }\n      }\n    },\n    \"WorkerdRuntime\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"compatibility_date\", \"main_module\"],\n      \"properties\": {\n        \"compatibility_date\": {\n          \"type\": \"string\",\n          \"minLength\": 10,\n          \"maxLength\": 10,\n          \"pattern\": \"^[0-9]{4}-[0-9]{2}-[0-9]{2}$\",\n          \"description\": \"Calendar YYYY-MM-DD. A date newer than the pinned workerd compatibility date 2026-11-13 warns and falls back to that pin when the isolate loads. The pattern checks shape only; checkers reject impossible days such as 2026-02-31.\"\n        },\n        \"compatibility_flags\": {\n          \"type\": \"array\",\n          \"description\": \"Exact allowlist: python_workers and disable_python_external_sdk. Both are required together when the guest is Python and forbidden otherwise. The host does not append missing flags.\",\n          \"items\": {\n            \"type\": \"string\",\n            \"enum\": [\"python_workers\", \"disable_python_external_sdk\"]\n          }\n        },\n        \"main_module\": { \"type\": \"string\", \"minLength\": 1 },\n        \"modules_dir\": { \"type\": \"string\", \"default\": \"modules\" },\n        \"entrypoint\": { \"type\": \"string\", \"default\": \"default\" },\n        \"limits\": { \"$ref\": \"#/$defs/WorkerdLimits\" }\n      }\n    },\n    \"WorkerdLimits\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"properties\": {\n        \"cpu_ms\": { \"type\": \"integer\", \"minimum\": 0 },\n        \"subrequests\": { \"type\": \"integer\", \"minimum\": 0 }\n      }\n    },\n    \"ModuleSpec\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"name\"],\n      \"properties\": {\n        \"name\": { \"type\": \"string\" },\n        \"path\": {\n          \"type\": \"string\",\n          \"description\": \"Source file relative to the plugin root. When path is omitted or empty, name is the modules-directory source.\"\n        },\n        \"type\": { \"type\": \"string\", \"default\": \"js\" }\n      }\n    },\n    \"CliSchema\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"properties\": {\n        \"commands\": {\n          \"type\": \"array\",\n          \"items\": { \"$ref\": \"#/$defs/CliCommandSpec\" }\n        }\n      }\n    },\n    \"CliCommandSpec\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"name\"],\n      \"properties\": {\n        \"name\": { \"type\": \"string\" },\n        \"about\": { \"type\": \"string\" },\n        \"args\": {\n          \"type\": \"array\",\n          \"items\": { \"$ref\": \"#/$defs/CliArgSpec\" }\n        }\n      }\n    },\n    \"CliArgSpec\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"name\"],\n      \"properties\": {\n        \"name\": { \"type\": \"string\" },\n        \"long\": { \"type\": \"string\" },\n        \"short\": { \"type\": \"string\", \"maxLength\": 1 },\n        \"kind\": {\n          \"type\": \"string\",\n          \"enum\": [\"string\", \"bool\", \"int\", \"path\"],\n          \"default\": \"string\"\n        },\n        \"required\": { \"type\": \"boolean\" },\n        \"default\": { \"type\": \"string\" },\n        \"about\": { \"type\": \"string\" },\n        \"positional\": { \"type\": \"boolean\" }\n      }\n    },\n    \"OidcManifest\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"properties\": {\n        \"clients\": {\n          \"type\": \"array\",\n          \"items\": { \"$ref\": \"#/$defs/OidcClient\" }\n        }\n      }\n    },\n    \"OidcClient\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"client_id\", \"callback_path\", \"origin_config_key\"],\n      \"properties\": {\n        \"client_id\": { \"type\": \"string\", \"minLength\": 1 },\n        \"display_name\": { \"type\": \"string\" },\n        \"callback_path\": { \"type\": \"string\", \"pattern\": \"^/\" },\n        \"public_client\": { \"type\": \"boolean\", \"default\": true },\n        \"default_scopes\": {\n          \"type\": \"array\",\n          \"items\": { \"type\": \"string\" }\n        },\n        \"issue_refresh_token\": { \"type\": \"boolean\", \"default\": true },\n        \"origin_config_key\": { \"type\": \"string\", \"minLength\": 1 }\n      }\n    }\n  }\n}\n";

Embedded JSON Schema for install plugin.toml files (shared with language SDK author tools and bookclerk plugins validation).

Generated from crates/bookclerk-plugin-abi at main · View as Markdown