bookclerk_plugin_abi
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.
- Guest authors — implement
PluginWorkerand the entrypoint traits against these DTOs (viabookclerk-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.
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).
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.
| 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). |
backup_ops::AdapterBackupOpsbackup_ops::SharedAdapterBackupOpsdb::binding_values_from_adapter_configdb::database_adapter_config_from_bindingsdb::binding_values_from_paramsdb::connect_params_from_bindingsdb::DbConnectParamsdb_execute::lowered_statement_preflight_len_provendb_execute::lowered_statement_preflight_lendb_execute::lowered_statement_upper_bound_lendb_execute::sql_payload_bytesdb_execute::sql_payload_exceedsdb_execute::DbBootstrapdb_execute::DbCapabilitiesdb_execute::DbColumndb_execute::DbIdentityHighWaterdb_execute::DbPlanStatementKinddb_execute::DbResultSelectiondb_execute::DbRowdb_execute::DbTimingdb_execute::ExecuteReplydb_execute::ExecuteRequestdb_execute::IsolationReqdb_execute::StatementResultdb_execute::TypedDbStatementdb_execute::D1_MAX_BINDSdb_execute::D1_MAX_FUNCTION_ARGSdb_execute::D1_MAX_PAYLOAD_BYTESdb_execute::D1_MAX_SCHEMA_COLUMNSdb_execute::D1_MAX_SQL_STATEMENT_BYTESdb_execute::D1_MAX_STREAMED_RESULT_BYTESdb_execute::D1_MAX_STREAMED_RESULT_ROWSdb_execute::FIRST_PARTY_MAX_RESULT_BYTESdb_execute::FIRST_PARTY_MAX_RESULT_ROWSdb_execute::FIRST_PARTY_MAX_STATEMENTSdb_execute::FIRST_PARTY_MAX_STREAMED_RESULT_BYTESdb_execute::FIRST_PARTY_MAX_STREAMED_RESULT_ROWSdb_execute::HOST_MAX_STREAMED_RESULT_BYTESdb_execute::HOST_MAX_STREAMED_RESULT_ROWSdb_execute::HOST_MIN_BINDSdb_execute::HOST_MIN_CELL_BYTESdb_execute::HOST_MIN_FUNCTION_ARGSdb_execute::HOST_MIN_PATTERN_BYTESdb_execute::HOST_MIN_PAYLOAD_BYTESdb_execute::HOST_MIN_REQUEST_BYTESdb_execute::HOST_MIN_RESULT_BYTESdb_execute::HOST_MIN_RESULT_ROWSdb_execute::HOST_MIN_SCHEMA_COLUMNSdb_execute::HOST_MIN_STATEMENTSdb_execute::POSTGRES_MAX_BINDSdb_execute::POSTGRES_MAX_FUNCTION_ARGSdb_execute::POSTGRES_MAX_SCHEMA_COLUMNSdb_execute::SQLITE_MAX_BINDSdb_execute::SQLITE_MAX_FUNCTION_ARGSdb_execute::SQLITE_MAX_PATTERN_BYTESdb_execute::SQLITE_MAX_SCHEMA_COLUMNSdb_execute::SQL_CONTRACT_VERSIONdb_value::db_type_from_declareddb_value::normalize_db_value_for_columndb_value::DbTypedb_value::DbValueerror::LimitExceedederror::PluginErrorerror::PluginErrorCodeerror::Resultevent_read::is_cursor_event_idevent_read::parse_event_read_jsonevent_read::validate_event_read_requestevent_read::EventCursorevent_read::EventReadPageevent_read::EventReadQueryevent_read::EventReadRequestevent_read::EventReadStartevent_read::MAX_CURSOR_CREATED_AT_BYTESevent_read::MAX_CURSOR_EVENT_ID_BYTESguest_sql::authorize_guest_sql_policyguest_sql::guest_statement_kindguest_sql::is_reserved_binding_nameguest_sql::parse_guest_sql_refsguest_sql::returning_single_row_provenguest_sql::statement_is_ddlguest_sql::validate_guest_execute_requestguest_sql::validate_guest_execute_request_for_policyguest_sql::validate_sql_v1_grammarguest_sql::GuestSqlPolicyguest_sql::GuestSqlRefsguest_sql::BOOKCLERK_RESERVED_PREFIXmethods::METHOD_NAMESsql_desugar::desugar_canonical_sqlsql_desugar::desugar_execute_requestsql_types::apply_schema_action_to_envsql_types::apply_schema_sql_to_envsql_types::catalog_companionssql_types::catalog_page_statementsql_types::parse_create_index_sqlsql_types::parse_create_table_schemasql_types::parse_drop_index_namesql_types::parse_drop_table_namesql_types::postgres_identity_function_namesql_types::postgres_identity_object_digestsql_types::postgres_identity_trigger_namesql_types::require_sql_v1_helper_aritysql_types::reserved_catalog_relation_missingsql_types::sql_catalog_create_table_sqlsql_types::sql_catalog_page_rowssql_types::sql_ddl_create_table_sqlsql_types::sql_host_bookkeeping_type_envsql_types::sql_type_env_from_canonical_ddlsql_types::sql_type_env_from_canonical_statementssql_types::sql_v1_helper_aritysql_types::sql_v1_helper_arity_oksql_types::sql_v1_ident_in_boundssql_types::statement_sql_hashsql_types::typecheck_create_index_sqlsql_types::typecheck_execute_requestsql_types::ColumnReferencesql_types::CreateIndexSchemasql_types::CreateTableSchemasql_types::SqlTypesql_types::SqlTypeEnvsql_types::INSERT_SELECT_WRAP_ALIASsql_types::POSTGRES_IDENT_FN_PREFIXsql_types::POSTGRES_IDENT_TRIGGER_PREFIXsql_types::SQL_CATALOG_TABLEsql_types::SQL_DDL_TABLEsql_types::SQL_IDENTITY_TABLEsql_types::SQL_SCHEMA_TABLEsql_types::SQL_V1_JSON_OBJECT_MAX_ARGSsql_types::SQL_V1_MAX_IDENT_BYTESsql_types::catalog_companions_for_actionsql_types::sql_schema_create_table_sqlsql_types::typecheck_execute_request_proofsdb_stream::decode_execute_streamdb_stream::encode_execute_streamdb_stream::encode_execute_stream_errordb_stream::ExecuteStreamdb_stream::ExecuteStreamBodydb_stream::ExecuteStreamDecoderdb_stream::ExecuteStreamFramedb_stream::ExecuteStreamLimitsdb_stream::STREAM_FRAME_TARGET_BYTESmedia::check_record_kindsmedia::decode_plain_fetch_bytesmedia::encode_plain_fetch_bytesmedia::media_support_is_emptymedia::same_media_supportmedia::validate_media_supportmedia::validate_plain_fetchmedia::FetchErrormedia::MediaErrormetadata_files::check_parse_paramsmetadata_files::check_record_against_dialectmetadata_files::check_render_against_dialectmetadata_files::check_render_paramsmetadata_files::check_renderedmetadata_files::decode_metadata_file_record_bytesmetadata_files::encode_metadata_file_record_bytesmetadata_files::validate_metadata_file_recordmetadata_files::MetadataFileDialectmetadata_files::MetadataFileErrornetwork_grant::NetworkGrantnetwork_grant::SettingGrantStatenetwork_grant::SettingNetworkGrantnetwork_grant::MAX_NETWORK_GRANT_ENTRIESquality_offers::decode_quality_offers_bytesquality_offers::encode_quality_offers_bytesquality_offers::validate_quality_offersquality_offers::OfferFieldquality_offers::QualityOffersErrorquality_offers::MAX_OFFER_BITRATE_KBPSquality_offers::MAX_OFFER_CHANNELSquality_offers::MAX_OFFER_SAMPLE_RATE_HZscan_page::decode_scan_page_bytesscan_page::encode_scan_page_bytesscan_page::validate_refreshed_credentialsscan_page::validate_scan_pagescan_page::ScanPageErrorsettings_schema::is_valid_setting_keysettings_schema::EffectiveConfigsettings_schema::SettingKindsettings_schema::SettingNetworksettings_schema::SettingSpecsettings_schema::SettingValueSpecsettings_schema::SettingsSchemasettings_schema::MAX_SETTINGSsettings_schema::MAX_SETTING_STRING_BYTESsettings_schema::MAX_TABLE_COLUMNSsettings_schema::MAX_TABLE_ROWSsettings_schema::SETTINGS_SCHEMA_VERSIONgenerated::Entrypointgenerated::PortalAuthModegenerated::CliArgKindgenerated::WorkKindgenerated::ExpressionKindgenerated::MediaKindgenerated::IdentifierSchemegenerated::CreditRolegenerated::CreditLevelgenerated::FetchedFileRolegenerated::ChapterKindgenerated::CatalogSortgenerated::CatalogFieldgenerated::PriceLookupgenerated::Abridgementgenerated::Explicitnessgenerated::OfferedCodecgenerated::OfferedAacProfilegenerated::MetadataFieldgenerated::NotificationSeveritygenerated::NotificationAudiencegenerated::NotificationAlertActiongenerated::NotifyDestinationKindgenerated::AiTaskgenerated::AiTextRolegenerated::EventConsumerSpecgenerated::PluginCapabilitiesgenerated::CatalogCapabilitiesgenerated::Brandgenerated::ConfigOptiongenerated::ConfigOptionValuegenerated::CliSchemagenerated::CliCommandSpecgenerated::CliArgSpecgenerated::CliArggenerated::CliInvokeParamsgenerated::CliInvokeResultgenerated::DatabaseAdapterConfiggenerated::DiagnoseResultgenerated::SourceAccountgenerated::LoginParamsgenerated::LoginResultgenerated::LoginStartResultgenerated::LoginCompleteParamsgenerated::AccountCredentialgenerated::ScanParamsgenerated::MediaSupportgenerated::Identifiergenerated::Creditgenerated::SeriesEntrygenerated::ScanBookgenerated::ScanPagegenerated::FetchOptionsgenerated::FetchTitleParamsgenerated::FetchedFilegenerated::ChapterMarkergenerated::PlainFetchgenerated::SourceAccountsgenerated::SearchCatalogParamsgenerated::ExpandCandidatesParamsgenerated::PurchaseHintParamsgenerated::ListDealsParamsgenerated::CatalogDetailParamsgenerated::RevokeAccountParamsgenerated::CatalogHitgenerated::CatalogHitsgenerated::CatalogDetailgenerated::PurchaseHintgenerated::PurchaseHintResultgenerated::PricedRecordgenerated::PurchaseHintsParamsgenerated::PurchaseHintsResultgenerated::QualityOffergenerated::QualityOffersParamsgenerated::TitleQualityOffergenerated::QualityOffersResultgenerated::ScanLibraryParamsgenerated::AuthenticateUserParamsgenerated::ExternalUsergenerated::EventPollResultgenerated::ListeningProgressgenerated::SyncListeningResultgenerated::PluginEventgenerated::PublishOkgenerated::Invocationgenerated::QueueMessagegenerated::QueueBatchgenerated::QueueRetrygenerated::QueueResultgenerated::QueueBatchOkgenerated::QueueSendMessagegenerated::QueueSendOkgenerated::KvPutOptionsgenerated::KvGetOkgenerated::KvPutOkgenerated::KvDeleteOkgenerated::KvListOptionsgenerated::KvListKeygenerated::KvListOkgenerated::ScheduledControllergenerated::MetadataLookupParamsgenerated::MetadataSearchParamsgenerated::MetadataChaptersParamsgenerated::MetadataRecordgenerated::MetadataRecordsgenerated::MetadataChaptergenerated::MetadataChaptersgenerated::CoverFetchParamsgenerated::CoverConditiongenerated::CoverImagegenerated::CoverImagesgenerated::MetadataFileRecordgenerated::MetadataFileParseParamsgenerated::MetadataFileParsedgenerated::MetadataAudioFilegenerated::MetadataFileRenderParamsgenerated::MetadataFileRenderedgenerated::NotificationFieldgenerated::NotificationMessagegenerated::NotifyDestinationgenerated::NotifySendParamsgenerated::NotifySentgenerated::NotifyValidateParamsgenerated::NotifyValidatedgenerated::NotifyRaiseParamsgenerated::NotifyRaisedgenerated::AiModelgenerated::AiModelListgenerated::AiEmbedTextgenerated::AiTextEmbeddingsInputgenerated::AiTextEmbeddingsOutputgenerated::AiInputgenerated::AiOutputgenerated::AiRunParamsgenerated::AiRunOkgenerated::SocketFramegenerated::SocketHeadergenerated::SocketAutoResponsegenerated::SocketConnectRequestgenerated::SocketInfogenerated::SocketListgenerated::SocketMessageOkgenerated::SocketMessagegenerated::SocketClosedgenerated::OriginHeadergenerated::OriginRequestgenerated::IngressStartedgenerated::WebhookUrlgenerated::WebhookPullRequestgenerated::WebhookHeadergenerated::WebhookDeliverygenerated::WebhookPullPagegenerated::IngressHealthgenerated::WebhookAckRequestgenerated::WebhookDeliveredgenerated::write_event_consumer_specgenerated::read_event_consumer_specgenerated::write_plugin_capabilitiesgenerated::read_plugin_capabilitiesgenerated::write_catalog_capabilitiesgenerated::read_catalog_capabilitiesgenerated::write_brandgenerated::read_brandgenerated::write_config_optiongenerated::read_config_optiongenerated::write_config_option_valuegenerated::read_config_option_valuegenerated::write_cli_schemagenerated::read_cli_schemagenerated::write_cli_command_specgenerated::read_cli_command_specgenerated::write_cli_arg_specgenerated::read_cli_arg_specgenerated::write_cli_arggenerated::read_cli_arggenerated::write_cli_invoke_paramsgenerated::read_cli_invoke_paramsgenerated::write_cli_invoke_resultgenerated::read_cli_invoke_resultgenerated::write_cli_schema_replygenerated::read_cli_schema_replygenerated::write_cli_invoke_replygenerated::read_cli_invoke_replygenerated::write_database_adapter_configgenerated::read_database_adapter_configgenerated::write_diagnose_resultgenerated::read_diagnose_resultgenerated::write_diagnose_replygenerated::read_diagnose_replygenerated::write_source_accountgenerated::read_source_accountgenerated::write_login_paramsgenerated::read_login_paramsgenerated::write_login_resultgenerated::read_login_resultgenerated::write_login_start_resultgenerated::read_login_start_resultgenerated::write_login_complete_paramsgenerated::read_login_complete_paramsgenerated::write_login_replygenerated::read_login_replygenerated::write_login_start_replygenerated::read_login_start_replygenerated::write_account_credentialgenerated::read_account_credentialgenerated::write_scan_paramsgenerated::read_scan_paramsgenerated::write_media_supportgenerated::read_media_supportgenerated::write_identifiergenerated::read_identifiergenerated::write_creditgenerated::read_creditgenerated::write_series_entrygenerated::read_series_entrygenerated::write_scan_bookgenerated::read_scan_bookgenerated::write_scan_pagegenerated::read_scan_pagegenerated::write_scan_replygenerated::read_scan_replygenerated::write_fetch_optionsgenerated::read_fetch_optionsgenerated::write_fetch_title_paramsgenerated::read_fetch_title_paramsgenerated::write_fetched_filegenerated::read_fetched_filegenerated::write_chapter_markergenerated::read_chapter_markergenerated::write_plain_fetchgenerated::read_plain_fetchgenerated::write_fetch_title_replygenerated::read_fetch_title_replygenerated::write_source_accountsgenerated::read_source_accountsgenerated::write_source_accounts_replygenerated::read_source_accounts_replygenerated::write_search_catalog_paramsgenerated::read_search_catalog_paramsgenerated::write_expand_candidates_paramsgenerated::read_expand_candidates_paramsgenerated::write_purchase_hint_paramsgenerated::read_purchase_hint_paramsgenerated::write_list_deals_paramsgenerated::read_list_deals_paramsgenerated::write_catalog_detail_paramsgenerated::read_catalog_detail_paramsgenerated::write_revoke_account_paramsgenerated::read_revoke_account_paramsgenerated::write_catalog_hitgenerated::read_catalog_hitgenerated::write_catalog_hitsgenerated::read_catalog_hitsgenerated::write_catalog_hits_replygenerated::read_catalog_hits_replygenerated::write_catalog_detailgenerated::read_catalog_detailgenerated::write_catalog_detail_replygenerated::read_catalog_detail_replygenerated::write_purchase_hintgenerated::read_purchase_hintgenerated::write_purchase_hint_resultgenerated::read_purchase_hint_resultgenerated::write_priced_recordgenerated::read_priced_recordgenerated::write_purchase_hint_replygenerated::read_purchase_hint_replygenerated::write_purchase_hints_paramsgenerated::read_purchase_hints_paramsgenerated::write_purchase_hints_resultgenerated::read_purchase_hints_resultgenerated::write_purchase_hints_replygenerated::read_purchase_hints_replygenerated::write_quality_offergenerated::read_quality_offergenerated::write_quality_offers_paramsgenerated::read_quality_offers_paramsgenerated::write_title_quality_offergenerated::read_title_quality_offergenerated::write_quality_offers_resultgenerated::read_quality_offers_resultgenerated::write_quality_offers_replygenerated::read_quality_offers_replygenerated::write_scan_library_paramsgenerated::read_scan_library_paramsgenerated::write_authenticate_user_paramsgenerated::read_authenticate_user_paramsgenerated::write_external_usergenerated::read_external_usergenerated::write_external_user_replygenerated::read_external_user_replygenerated::write_event_poll_resultgenerated::read_event_poll_resultgenerated::write_event_poll_replygenerated::read_event_poll_replygenerated::write_listening_progressgenerated::read_listening_progressgenerated::write_sync_listening_resultgenerated::read_sync_listening_resultgenerated::write_sync_listening_replygenerated::read_sync_listening_replygenerated::write_plugin_eventgenerated::read_plugin_eventgenerated::write_publish_okgenerated::read_publish_okgenerated::write_publish_replygenerated::read_publish_replygenerated::write_invocationgenerated::read_invocationgenerated::write_queue_messagegenerated::read_queue_messagegenerated::write_queue_batchgenerated::read_queue_batchgenerated::write_queue_retrygenerated::read_queue_retrygenerated::write_queue_resultgenerated::read_queue_resultgenerated::write_queue_batch_okgenerated::read_queue_batch_okgenerated::write_queue_batch_replygenerated::read_queue_batch_replygenerated::write_queue_send_messagegenerated::read_queue_send_messagegenerated::write_queue_send_okgenerated::read_queue_send_okgenerated::write_queue_send_replygenerated::read_queue_send_replygenerated::write_kv_put_optionsgenerated::read_kv_put_optionsgenerated::write_kv_get_okgenerated::read_kv_get_okgenerated::write_kv_get_replygenerated::read_kv_get_replygenerated::write_kv_put_okgenerated::read_kv_put_okgenerated::write_kv_delete_okgenerated::read_kv_delete_okgenerated::write_kv_put_replygenerated::read_kv_put_replygenerated::write_kv_delete_replygenerated::read_kv_delete_replygenerated::write_kv_list_optionsgenerated::read_kv_list_optionsgenerated::write_kv_list_keygenerated::read_kv_list_keygenerated::write_kv_list_okgenerated::read_kv_list_okgenerated::write_kv_list_replygenerated::read_kv_list_replygenerated::write_scheduled_controllergenerated::read_scheduled_controllergenerated::write_metadata_lookup_paramsgenerated::read_metadata_lookup_paramsgenerated::write_metadata_search_paramsgenerated::read_metadata_search_paramsgenerated::write_metadata_chapters_paramsgenerated::read_metadata_chapters_paramsgenerated::write_metadata_recordgenerated::read_metadata_recordgenerated::write_metadata_recordsgenerated::read_metadata_recordsgenerated::write_metadata_records_replygenerated::read_metadata_records_replygenerated::write_metadata_chaptergenerated::read_metadata_chaptergenerated::write_metadata_chaptersgenerated::read_metadata_chaptersgenerated::write_metadata_chapters_replygenerated::read_metadata_chapters_replygenerated::write_cover_fetch_paramsgenerated::read_cover_fetch_paramsgenerated::write_cover_conditiongenerated::read_cover_conditiongenerated::write_cover_imagegenerated::read_cover_imagegenerated::write_cover_imagesgenerated::read_cover_imagesgenerated::write_cover_images_replygenerated::read_cover_images_replygenerated::write_metadata_file_recordgenerated::read_metadata_file_recordgenerated::write_metadata_file_parse_paramsgenerated::read_metadata_file_parse_paramsgenerated::write_metadata_file_parsedgenerated::read_metadata_file_parsedgenerated::write_metadata_file_parse_replygenerated::read_metadata_file_parse_replygenerated::write_metadata_audio_filegenerated::read_metadata_audio_filegenerated::write_metadata_file_render_paramsgenerated::read_metadata_file_render_paramsgenerated::write_metadata_file_renderedgenerated::read_metadata_file_renderedgenerated::write_metadata_file_render_replygenerated::read_metadata_file_render_replygenerated::write_notification_fieldgenerated::read_notification_fieldgenerated::write_notification_messagegenerated::read_notification_messagegenerated::write_notify_destinationgenerated::read_notify_destinationgenerated::write_notify_send_paramsgenerated::read_notify_send_paramsgenerated::write_notify_sentgenerated::read_notify_sentgenerated::write_notify_send_replygenerated::read_notify_send_replygenerated::write_notify_validate_paramsgenerated::read_notify_validate_paramsgenerated::write_notify_validatedgenerated::read_notify_validatedgenerated::write_notify_validate_replygenerated::read_notify_validate_replygenerated::write_notify_raise_paramsgenerated::read_notify_raise_paramsgenerated::write_notify_raisedgenerated::read_notify_raisedgenerated::write_notify_raise_replygenerated::read_notify_raise_replygenerated::write_ai_modelgenerated::read_ai_modelgenerated::write_ai_model_listgenerated::read_ai_model_listgenerated::write_ai_models_replygenerated::read_ai_models_replygenerated::write_ai_embed_textgenerated::read_ai_embed_textgenerated::write_ai_text_embeddings_inputgenerated::read_ai_text_embeddings_inputgenerated::write_ai_text_embeddings_outputgenerated::read_ai_text_embeddings_outputgenerated::write_ai_inputgenerated::read_ai_inputgenerated::write_ai_outputgenerated::read_ai_outputgenerated::write_ai_run_paramsgenerated::read_ai_run_paramsgenerated::write_ai_run_okgenerated::read_ai_run_okgenerated::write_ai_run_replygenerated::read_ai_run_replygenerated::write_socket_framegenerated::read_socket_framegenerated::write_socket_headergenerated::read_socket_headergenerated::write_socket_auto_responsegenerated::read_socket_auto_responsegenerated::write_socket_connect_requestgenerated::read_socket_connect_requestgenerated::write_socket_infogenerated::read_socket_infogenerated::write_socket_connect_replygenerated::read_socket_connect_replygenerated::write_socket_listgenerated::read_socket_listgenerated::write_socket_list_replygenerated::read_socket_list_replygenerated::write_socket_message_replygenerated::read_socket_message_replygenerated::write_socket_message_okgenerated::read_socket_message_okgenerated::write_socket_messagegenerated::read_socket_messagegenerated::write_socket_closedgenerated::read_socket_closedgenerated::write_origin_headergenerated::read_origin_headergenerated::write_origin_requestgenerated::read_origin_requestgenerated::write_ingress_startedgenerated::read_ingress_startedgenerated::write_ingress_start_replygenerated::read_ingress_start_replygenerated::write_webhook_urlgenerated::read_webhook_urlgenerated::write_webhook_url_replygenerated::read_webhook_url_replygenerated::write_webhook_pull_requestgenerated::read_webhook_pull_requestgenerated::write_webhook_headergenerated::read_webhook_headergenerated::write_webhook_deliverygenerated::read_webhook_deliverygenerated::write_webhook_pull_pagegenerated::read_webhook_pull_pagegenerated::write_webhook_pull_replygenerated::read_webhook_pull_replygenerated::write_ingress_healthgenerated::read_ingress_healthgenerated::write_ingress_health_replygenerated::read_ingress_health_replygenerated::write_webhook_ack_requestgenerated::read_webhook_ack_requestgenerated::write_webhook_deliveredgenerated::read_webhook_deliveredgenerated::READ_ANY_COUNTgenerated::read_any_messagegenerated::RoundTripFailuregenerated::roundtrip_any_messagekind::S3CredentialsDtokind::OutputS3ContextDtokind::OutputLocalContextDto
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 ofplugin.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 oneEventPublisher.readrequest and its opaque cursor.generated: GENERATED FILE - do not edit. Runpython3 scripts/gen-plugin-abi.py --writeafter 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 ProtoDatafields as base64 text in JSON.kind: Output-plugin configuration DTOs carried asapplication/jsoninsidecrate::ExtensibleConfig(Bindings.configfor thestorageentrypoint).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 ametadataFilesplugin returns and on what it sends one.methods: Role capability method names (camelCase on the wire).network_grant: The network grant a guest sees atopen(Bindings.network).notifications: The checks the host runs on notification requests and replies.origin: Sans-IO checks for theORIGINbinding and theingressentrypoint.package_version:plugin.tomlversionas a semantic version.quality_offers: Validation of oneContentSource.qualityOffersreply before the host compares it with the files it holds.scan_page: Validation of oneContentSource.scanpage before the host writes it.settings_schema: Operator-facing plugin settings schema ([[settings]]inplugin.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).
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).
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).
fn commit<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Commit.
fn rollback<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = Result<()>> + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Rollback.
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.
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.
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.
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).
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.
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.
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).
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).
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
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).
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.
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.
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.
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.
The default fails with unsupported; adapters that advertise a
streamed budget answer with the framed reply.
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.
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.
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.
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).
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).
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).
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.
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.
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.
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.
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
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.
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
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).
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The default answers unsupported; a store's own error fails the
whole batch.
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.
Returns an error when the store rejects the sign-out. The host logs it and revokes the account anyway.
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.
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
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.
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.
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
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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).
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
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.
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
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).
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]].
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.
The default refuses with unsupported; the host publisher validates
the request with crate::validate_event_read_request.
Implemented by: EventPublisherClient
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).
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).
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.
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.
Hosts answer with the adapter's advertisement; the default fails with
unsupported for sessions that predate the method.
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.
The default fails with unsupported for sessions that predate the
method or advertise no streamed budget.
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.
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.
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.
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
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).
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
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.
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.
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.
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.
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
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.
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.
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.
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
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.
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.
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.
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.
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
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.
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
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.
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.
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.
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
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.
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.
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
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.
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.
request- The checked head (crate::origin::check_origin_request).body- The request body;Nonewhen the request has none.
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
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>.
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.
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
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.
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.
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.
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.
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.
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).
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.
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.
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
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).
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.
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
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.
fn health<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = Result<HealthOk>> + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Liveness.
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.
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.
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.
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.
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.
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
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.
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
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.
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.
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
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.
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.
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.
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.
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.
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
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.
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
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.
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
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.
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.
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.
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
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: GuestrequestHashcompared on replay.
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
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.
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.
pub fn with_proofs(self, proofs: Vec<ResolvedStatement>) -> Self
Stamps 1:1 proofs (including receipt wrappers).
pub fn with_isolation(self, isolation: IsolationReq) -> Self
Sets isolation (default IsolationReq::AtomicBatch).
pub fn require_proofs(&self) -> Result<()>
Fail closed unless proofs are 1:1 and hash-bound to each statement.
Returns when the proof count differs or a proof is not bound to its SQL.
Implements: Clone, Debug
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.
pub fn from_desugared(request: ExecuteRequest) -> Self
Wraps already-desugared SQL (for example after crate::desugar_execute_request).
pub fn with_guest_receipt(self, guest_receipt: GuestReceiptPersist) -> Self
Host-stamped finalize hint for guest replay.
pub fn with_isolation(self, isolation: IsolationReq) -> Self
Isolation the adapter must realize.
pub fn bind_proofs(self, proofs: Vec<ResolvedStatement>) -> Result<AdapterExecuteRequest>
Binds 1:1 proofs to the canonical SQL. Fail closed on mismatch.
Returns when the proof count differs or a proof is not bound to its SQL.
Implements: Clone, Debug
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 needNULLS/NULLIFdesugar).guest_receipt: Host-stamped finalize hint for guest replay.isolation: Isolation the adapter must realize.
pub fn new(request: ExecuteRequest) -> Self
Wraps source SQL with default isolation and no receipt hint.
pub fn with_guest_receipt(self, guest_receipt: GuestReceiptPersist) -> Self
Host-stamped finalize hint for guest replay.
pub fn with_isolation(self, isolation: IsolationReq) -> Self
Isolation the adapter must realize.
pub fn canonicalize(self) -> CanonicalExecuteRequest
Applies Bookclerk semantic desugars exactly once.
Implements: Clone, Debug
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
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 + borabs(n)).lhs: Left operand (orabsargument).rhs: Right operand (absrepeatslhs).kind: Operator.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
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 *).Noneis table presence only (FROM / INSERT / UPDATE / DELETE / DROP), not a wildcard.
Implements: Clone, Debug, Deserialize<'de>, Eq, Ord, PartialEq, PartialOrd, Serialize
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
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 forCOLLATE "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.
pub fn bound_empty(sql: &str) -> Self
Proof for sql with empty semantic payloads (wrapper DDL/DML still hash-bound).
pub fn proves(&self, sql: &str) -> bool
True when sql is the exact statement this proof was built from.
pub fn validate_for(&self, sql: &str) -> Result<()>
Rejects a hash-correct proof whose TEXT/arithmetic sidecar cannot be applied.
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
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
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
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
pub struct HostAdapterDatabaseSessionClient {
/* private fields */
}
Host-side client for begin on an open adapter session capability.
pub fn from_session_client(client: Client) -> Self
Casts a public adapter session capability to the host-private interface.
Implements: HostAdapterDatabaseSession
pub struct RpcFeature {
pub name: &'static str,
}
Known RPC feature names.
Fields
name: Wire name (rpc.streams, …).
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct StreamCopyHandler;
Default JobRunner for the stream-copy vertical slice.
Implements: JobRunner
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
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
max_scalar_bytes:MAX_SCALAR_BYTES(or a host-clamped lower value).max_stream_window_bytes:MAX_STREAM_WINDOW_BYTES(or a host-clamped lower value).max_list_page:MAX_LIST_PAGE(or a host-clamped lower value).
pub fn validate(self) -> Result<Self>
Rejects zero or above-product-maxima limits.
Returns crate::PluginError::invalid_params when any component is
zero or larger than the product constant.
pub fn intersect(self, other: Self) -> Self
Intersection of host-offered and guest-accepted limits (component-wise min).
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
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 asapplication/json.secrets:SECRETS: granted secret values asapplication/json; empty payload when the manifest declares no[secrets].adapter: Database-adapter bootstrap for thedatabaseAdapterentrypoint. First-party host-managed adapters receive host-private connect params inSelf::config; third-party adapters receive this typed bootstrap (and an emptyconfig).plugin_data_diris empty whenconfigcarries 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.
pub fn config(config: ExtensibleConfig) -> Self
Bindings carrying only CONFIG.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
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 asapplication/json.secrets:SECRETS: granted secret values; empty payload when none.adapter: Database-adapter bootstrap (seeBindingValues::adapter).events:EVENTS: outbox publisher;Noneunless[[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;Noneunless[work_fs]is granted. Job input/output travel onJobController, 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;Noneunless[sockets]is granted.webhooks:WEBHOOKS: the instance's inbound webhooks;Noneunless the manifest declares[[webhooks]].network:NETWORK: the network grant in effect (seeBindingValues::network).notify:NOTIFY: raises declared notification types;Noneunless the manifest declares[[notifications.types]].origin:ORIGIN: the library, for the active relayingressplugin;Nonefor every other plugin.ai:AI: runs models served by model plugins;Noneunless the manifest declares[ai] callsand the operator approved it.
pub fn from_values(values: BindingValues) -> Self
Bindings with only plain values (no capabilities); tests and in-process hosts.
pub fn take_named_queue(&mut self, name: &str) -> Option<NamedQueueBinding>
Takes the named queue producer binding name, if granted.
pub fn take_named_kv(&mut self, name: &str) -> Option<NamedKvBinding>
Takes the named KV namespace binding name, if granted.
pub fn values(&self) -> BindingValues
Plain-data view (config / secrets / adapter).
pub fn take_named_database(&mut self, name: &str) -> Option<Box<dyn GuestDatabase>>
Takes the named plugin database binding name, if granted.
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;Nonemeans to end of object.
Implements: Clone, Copy, Debug, Eq, PartialEq
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] jobstrigger.storefront:storefrontentrypoint.storage:storageentrypoint.database_adapter:databaseAdapterentrypoint.remote_library:remoteLibraryentrypoint.cli:clientrypoint.oidc:oidcentrypoint.queue_consumer:[[queues.consumers]]trigger.scheduled_handler:[triggers] cronstrigger.metadata:metadataentrypoint.covers:coversentrypoint.socket_handler:[sockets]handler.webhook_handler:[[webhooks]]handler.metadata_files:metadataFilesentrypoint.notifier:notifierentrypoint.ingress:ingressentrypoint.ai:aientrypoint.
Implements: Default
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).
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 onenv([[kv_namespaces]] binding).namespace: Namespace the binding is scoped to.kv: Host-served namespace.
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 onenv([[queues.producers]] binding).queue: Queue the binding sends to.producer: Host-served producer.
pub struct NeverCancel;
Cancellation that never fires (tests / hosts without a fence).
Implements: Cancellation
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;Nonewhen the response has none. Dropping it abandons the rest of the body.
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.
pub struct AdapterSessionHandle {
pub session: Box<dyn AdapterDatabaseSession>,
pub host: HostAdapterDatabaseSessionClient,
}
Public adapter session plus host-private interactive transaction client.
Fields
session: Typedcapabilities/execute/close.host: Host-onlybegin(capability cast on the same session object).
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.
pub fn new(client: Client) -> Self
Wraps an AiModels capability client (any transport that yields
one, including the bookclerk-workerd /invoke hook).
client- The guest'sAiModelscapability.
The typed client.
Implements: AiModels, Clone
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.
pub fn new(client: Client) -> Self
Wraps an AiRunner capability client.
client- The host'sAiRunnercapability.
The typed client.
Implements: AiRunner, Clone
pub struct ContentSourceClient {
/* private fields */
}
Cap'n Proto client for ContentSource.
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
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.
pub fn new(client: Client, window: u32) -> Self
Wraps a CoverFetcher capability client (any transport that yields
one, including the bookclerk-workerd /invoke hook).
client- The guest'sCoverFetchercapability.window- Stream window for the host sink, clamped to1..=MAX_STREAM_WINDOW_BYTES.
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).
params- URLs and the per-image byte cap.sink- TheDestinationcapability the guest puts bodies into.
One answer per URL, in request order.
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
pub struct DatabaseClient {
/* private fields */
}
Cap'n Proto client for Database.
pub fn new(client: Client) -> Self
Wraps a Database capability client (any transport that yields one, including
the bookclerk-workerd /invoke hook).
pub async fn open_session_handle(&self) -> Result<AdapterSessionHandle>
Opens a session and host-private transaction client on one capability.
Returns when openSession fails on the guest.
Implements: Clone, Database
pub struct DestinationClient {
/* private fields */
}
Host-side Destination over a capnp destination stub.
pub fn new(client: Client, window: u32) -> Self
Wraps a capnp destination client.
pub fn with_max_list_page(self, max_list_page: u32) -> Self
Applies negotiated list-page cardinality.
Implements: Clone, Destination
pub struct DestinationServer {
/* private fields */
}
Cap'n Proto server wrapping a Destination trait object.
pub fn new(inner: Arc<dyn Destination>, window: u32) -> Self
Serves inner with the given stream window.
Implements: Server
pub struct EventConsumerClient {
/* private fields */
}
Cap'n Proto client for EventConsumer (host → guest delivery).
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
pub struct EventPublisherClient {
/* private fields */
}
Guest-side client for the host EVENTS binding (EventPublisher).
Implements: Clone, EventPublisher
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:EVENTSpublisher;Noneunless[[events.producers]]is granted.databases: Named plugin-owned[[databases]]sessions.cancel: Invocation-wide cancellation (fence / lease loss).storage:WORK_FSobject storage;Noneunless[work_fs]is granted.queues: Named[[queues.producers]]producers as(binding, queue, producer).kv: Named[[kv_namespaces]]namespaces as(binding, namespace, kv).sockets:SOCKETSbroker link;Noneunless[sockets]is granted.webhooks:WEBHOOKSstore;Noneunless the manifest declares[[webhooks]].notify:NOTIFYraiser;Noneunless the manifest declares[[notifications.types]].origin:ORIGIN: the library;Noneunless the plugin is the active relay ingress.ai:AImodel runner;Noneunless the manifest declares[ai] callsand the operator approved it.
pub fn from_values(values: BindingValues) -> Self
Bindings with only plain values and no cancellation source.
Implements: Default
pub struct IngressClient {
/* private fields */
}
Host-side client for a plugin's ingress entrypoint.
pub fn new(client: Client) -> Self
Wraps the Entrypoints.ingress capability.
pub async fn start_checked(&self) -> Result<IngressOrigin>
Asks the plugin to bring its public address up and checks the origin it reports.
The origin it serves (parse_ingress_origin).
The plugin's error, the RPC error, or invalid_params when the
reported origin is not an https:// host name.
Implements: Clone, Ingress
pub struct JobRunnerClient {
/* private fields */
}
Cap'n Proto client for JobRunner (host → guest job dispatch).
pub fn new(client: Client, window: u32) -> Self
Wraps a JobRunner capability client with the negotiated stream window.
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.
Returns a plugin error when the runner fails.
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.
Returns a plugin error when the runner fails.
Implements: Clone, JobRunner
pub struct KvNamespaceClient {
/* private fields */
}
Guest-side client for a host KV namespace binding (KvNamespace).
pub fn new(client: Client) -> Self
Wraps a KvNamespace capability client.
Implements: Clone, KvNamespace
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.
pub fn new(client: Client) -> Self
Wraps a MetadataFiles capability client (any transport that yields
one, including the bookclerk-workerd /invoke hook).
client- The guest'sMetadataFilescapability.
The typed client.
Implements: Clone, MetadataFiles
pub struct MetadataProviderClient {
/* private fields */
}
Cap'n Proto client for MetadataProvider.
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
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
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.
pub fn new(client: Client) -> Self
Wraps a NotificationRaiser capability client.
client- The host'sNotificationRaisercapability.
The typed client.
Implements: Clone, NotificationRaiser
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.
pub fn new(client: Client) -> Self
Wraps a Notifier capability client (any transport that yields one,
including the bookclerk-workerd /invoke hook).
client- The guest'sNotifiercapability.
The typed client.
Implements: Clone, Notifier
pub struct OidcClient {
/* private fields */
}
Cap'n Proto client for Oidc.
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
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] jobstrigger.storefront:storefrontentrypoint.storage:storageentrypoint.database_adapter:databaseAdapterentrypoint.remote_library:remoteLibraryentrypoint.cli:clientrypoint.oidc:oidcentrypoint.queue_consumer:[[queues.consumers]]trigger.scheduled_handler:[triggers] cronstrigger.metadata:metadataentrypoint.covers:coversentrypoint.socket_handler:[sockets]handler.webhook_handler:[[webhooks]]handler.metadata_files:metadataFilesentrypoint.notifier:notifierentrypoint.ingress:ingressentrypoint.ai:aientrypoint.
Implements: Default
pub struct OriginClient {
/* private fields */
}
Guest-side client for the Origin binding (what a native relay plugin
calls).
pub fn new(client: Client, window: u32) -> Self
Wraps the Bindings.origin capability.
Implements: Origin
pub struct PluginCliClient {
/* private fields */
}
Cap'n Proto client for PluginCli.
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
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.
pub fn new(client: Client, window: u32) -> Self
Wraps a bootstrap client.
pub fn with_limits(self, limits: ScalarLimits) -> Self
Applies negotiated limits (stream window + list page).
pub async fn describe(&self) -> Result<PluginDescribe>
Calls describe.
Returns a plugin error when the RPC fails or apiVersion is not
crate::limits::PRODUCT_API_VERSION.
pub async fn open(
&self,
invocation: &Invocation,
bindings: HostBindings,
) -> Result<OpenedEntrypoints>
Opens the exported entrypoints for invocation with host-granted
bindings.
Returns a plugin error when the RPC fails or the guest refuses the open.
pub async fn database_migrations(&self, binding: &str) -> Result<Vec<PluginMigration>>
Complete ordered plugin-owned migration sequence for one named binding.
Returns a plugin error when the RPC fails.
pub async fn shutdown(&self) -> Result<()>
Asks the guest to release its resources (PluginWorker.shutdown).
Returns a plugin error when the RPC fails or the guest reports one.
Implements: Clone
pub struct PluginServer {
/* private fields */
}
Cap'n Proto server wrapping PluginWorker.
pub fn new(inner: Arc<dyn PluginWorker>, window: u32) -> Self
Serves inner.
Implements: Server
pub struct QueueConsumerClient {
/* private fields */
}
Cap'n Proto client for QueueConsumer (host → guest delivery).
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
pub struct QueueProducerClient {
/* private fields */
}
Guest-side client for a host queue producer binding (QueueProducer).
pub fn new(client: Client) -> Self
Wraps a QueueProducer capability client.
Implements: Clone, QueueProducer
pub struct RemoteLibraryClient {
/* private fields */
}
Cap'n Proto client for RemoteLibrary.
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
pub struct ScheduledHandlerClient {
/* private fields */
}
Cap'n Proto client for ScheduledHandler (host → guest cron fire).
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
pub struct SocketHandlerClient {
/* private fields */
}
Host-side client for a guest's SocketHandler.
pub fn new(client: Client) -> Self
Wraps a SocketHandler capability client.
Implements: Clone, SocketHandler
pub struct SocketsClient {
/* private fields */
}
Guest-side client for the host Sockets binding.
pub fn new(client: Client) -> Self
Wraps a Sockets capability client.
Implements: Clone, Sockets
pub struct SourceClient {
/* private fields */
}
Host-side Source over a capnp source stub.
pub fn new(client: Client, window: u32) -> Self
Wraps a capnp source client.
Implements: Clone, Source
pub struct SourceServer {
/* private fields */
}
Cap'n Proto server wrapping a Source.
pub fn new(inner: Arc<dyn Source>, window: u32) -> Self
Serves inner.
Implements: Server
pub struct WebhookHandlerClient {
/* private fields */
}
Host-side client for a guest's WebhookHandler.
pub fn new(client: Client) -> Self
Wraps a WebhookHandler capability client.
Implements: Clone, WebhookHandler
pub struct WebhooksClient {
/* private fields */
}
Guest-side client for the host Webhooks binding.
pub fn new(client: Client) -> Self
Wraps a Webhooks capability client.
Implements: Clone, Webhooks
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
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 priorEventResult::Suspended(≤MAX_CHECKPOINT_BYTES).checkpoint_schema_version: Schema version ofSelf::checkpoint_json.invocation_sequence: Resume ordinal copied from the delivery row.resume_pending: True when this invocation continues a priorsuspendedresult.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
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 orapplication/json.payload: Bounded payload bytes.
pub fn json(value: &Value) -> Self
Wraps a JSON document as an application/json payload (schema version 1).
pub fn json_from<T: Serialize>(value: &T) -> Result<Self>
Serializes value as an application/json payload (schema version 1).
Returns crate::PluginErrorCode::Internal when value cannot be
serialized.
pub fn is_empty(&self) -> bool
True when no payload was supplied.
pub fn json_value(&self) -> Result<Value>
Decodes the payload as a JSON document; an empty payload is {}.
Returns crate::PluginErrorCode::InvalidParams when the media type is
not JSON or the bytes are not valid JSON.
pub fn json_into<T: DeserializeOwned>(&self) -> Result<T>
Decodes the JSON payload into T; an empty payload decodes {}.
Same as Self::json_value, plus a deserialization failure into T.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
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
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
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 forSelf::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 failureSelf::attempt.step_id: Deterministic step identifier within this invocation.
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.
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
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 priorJobOutcome::Suspended.invocation_sequence: Resume ordinal from the durable payload; distinct fromSelf::attempt.
Implements: Clone, Debug, Eq, PartialEq
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 eachObjectInfo. The reply'sListPage::signatures_includedsays whether the guest did.modified_since_ms: Hint: only objects modified at or after this UTC unix millisecond. The reply'sListPage::modified_since_appliedsays whether the guest filtered; when it did not, the page is unfiltered.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
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;Nonewhen this is the last page.signatures_included: True when every entry carries the signature fields the backend has (ListOptions::with_signatureshonoured).modified_since_applied: True when the guest left out objects modified beforeListOptions::modified_since_ms; false means the page is unfiltered.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
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
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, asObjectInfo::signature.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
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 OAuthclient_idregistered 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/profiletypical).issue_refresh_token: When true,/oidc/tokenmay issue refresh tokens for new rows.origin_config_key: Dotted config key that supplies the player origin.
pub fn scopes_or_default(&self) -> Vec<String>
Scopes used when the guest omitted defaultScopes.
pub fn display_name_or_id(&self) -> &str
Card title, falling back to client_id.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
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 equalcrate::limits::PRODUCT_API_VERSION.id: Plugin id matchingplugin.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 verifiedplugin.tomland 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;Nonewhen the guest has no brand (wirebrand.idis empty) and the host renders a neutral fallback.config_options: Discoverable config option groups for source UIs.cli: Embedded CLI schema (same shape ascliDescribe); 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.
pub fn has_entrypoint(&self, entrypoint: Entrypoint) -> bool
True when the guest exports the named Entrypoint.
pub fn consumes_event(&self, event_type: &str) -> bool
True when the guest's default entrypoint consumes event_type.
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
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
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
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: MaxByteSource.pullwindow in bytes.max_list_page: Max objects per list page.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, From<ScalarLimits>, From<ScalarLimitsDto>, PartialEq, Serialize
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,putstages remotely and does not publish untilcommit.if_match: Conditional write: publish only while the stored object's etag equals this value, else fail withconflict. Sent only to a guest that declaresstorage.conditionalWrite.if_none_match: Conditional write: publish only when no object exists at the key, else fail withconflict. Sent only to a guest that declaresstorage.conditionalWrite.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
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 whilecompletestays 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
pub struct ChangesRequest {
pub cursor: Option<String>,
pub limit: u32,
}
Argument of crate::Destination::changes.
Fields
cursor:ChangesPage::cursorfrom the previous call;Noneasks for the current position (a page with a cursor and no changes).limit: Requested changes per page, clamped toMAX_CHANGES_PAGE; zero means guest default.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
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;Nonewhen it succeeded.
pub fn ok(key: impl Into<String>) -> Self
A successful outcome for key.
pub fn failed(key: impl Into<String>, error: PluginError) -> Self
A failed outcome for key.
Implements: Clone, Debug, Eq, PartialEq
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
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;Nonewhen 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
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_cursorfrom the previous call;Nonestarts. Ignored for pairs.limit: Prefix form: objects to move in this call, clamped toMAX_BATCH_KEYS; zero means guest default.options: Overwrite rule applied to every move (if_source_matchis ignored).
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
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 withconflictinstead 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 withconflict.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
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
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
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).
pub fn sql(&self) -> &str
Canonical BookclerkSQL for this operation.
pub fn is_schema(&self) -> bool
True when this operation is classified as schema DDL.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum OverflowDialect {
SqliteFamily,
Postgres,
}
Engine family for overflow derived-table syntax and i64::MIN CAST.
Variants
SqliteFamily: SQLite / D1: correlatedFROM (SELECT …) _bc_ov,INTEGERmin CAST.Postgres: PostgreSQL:LATERAL+BIGINTmin CAST.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum IntegerArithKind {
Add,
Sub,
Mul,
Abs,
}
INTEGER + - * abs site lowered to overflow → NULL.
Variants
Add:lhs + rhsSub:lhs - rhsMul:lhs * rhsAbs:abs(arg)(lhsis the argument span)
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
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—noopwhen 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
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: SQLNULL(no pattern bytes).
Implements: Clone, Debug, Eq, PartialEq
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
pub enum EventReadMessage {
Request(EventReadRequest),
Page(EventReadPage),
}
A value roundtrip_event_read_message decoded.
Variants
Request: A decodedEventReadRequest.Page: A decodedEventReadPage.
Implements: Clone, Debug, Eq, PartialEq
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
pub enum SocketWireMessage {
ConnectRequest(SocketConnectRequest),
Message(SocketMessage),
}
A value roundtrip_socket_message decoded.
Variants
ConnectRequest: A decodedSocketConnectRequest.Message: A decodedSocketMessage.
Implements: Clone, Debug, Eq, PartialEq
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
pub enum WebhookWireMessage {
PullRequest(WebhookPullRequest),
AckRequest(WebhookAckRequest),
Delivery(WebhookDelivery),
}
A value roundtrip_webhook_message decoded.
Variants
PullRequest: A decodedWebhookPullRequest.AckRequest: A decodedWebhookAckRequest.Delivery: A decodedWebhookDelivery.
Implements: Clone, Debug, Eq, PartialEq
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 afterretry_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.
pub fn from_json_value(value: &Value) -> Result<Self>
Decode JSON {"kind":"ack"|…}. Missing or unknown kind is an error.
Returns crate::PluginErrorCode::InvalidParams when the payload is not
a tagged EventResult, or crate::PluginErrorCode::PayloadTooLarge
when a suspended checkpoint exceeds MAX_CHECKPOINT_BYTES.
pub fn from_json_str(raw: &str) -> Result<Self>
Decode a JSON object string as EventResult.
Same as Self::from_json_value.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
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 afterretry_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 withcheckpointafterwake_at_unix_ms.checkpoint: Checkpoint to restore on wake.wake_at_unix_ms: UTC unix-ms wake hint.
pub fn is_terminal(&self) -> bool
True when the host should treat the invocation as finished.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum MoveManyTarget {
Pairs(Vec<KeyPair>),
Prefix(KeyPair),
}
What a MoveManyRequest moves.
Variants
Pairs: Explicit, independent moves; at mostMAX_BATCH_KEYS.Prefix: Every object underfrommoves underto, keeping the rest of its key. Paged throughMoveManyRequest::cursor.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
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
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: AmoveManypage.DeleteMany:deleteManyoutcomes.HeadMany:headManyprobes.Changes: Achangespage.List: Alistpage.TranslateKeys:translateKeyskeys.
Implements: Clone, Debug, Eq, PartialEq
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
pub fn capnp_u32_len(len: usize, what: &str) -> Result<u32>
Converts a Rust list length into a Cap'n Proto UInt32 list size.
Returns PluginError::payload_too_large when len cannot fit in u32.
pub fn plugin_migration_registration_bytes(migrations: &[PluginMigration]) -> usize
Aggregate UTF-8 bytes of ids plus SQL across a complete registration.
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.
Returns PluginError::payload_too_large when migration count, operations
per migration, or total operations exceed ABI limits.
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:
- migration count:
MAX_LIST_PAGE - operations per migration:
MAX_PLUGIN_MIGRATION_OPS - total operations:
MAX_PLUGIN_MIGRATION_TOTAL_OPS - each SQL text:
MAX_SCALAR_BYTES - aggregate id + SQL bytes:
MAX_PLUGIN_MIGRATION_REGISTRATION_BYTES
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.
Returns PluginError::payload_too_large when any limit is exceeded.
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.
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.
pub fn assert_proof_matches_sql(proof: &ResolvedStatement, sql: &str) -> Result<()>
Require proof to be bound to sql.
Returns when the hashes differ (transformed or reindexed SQL).
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.
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'.
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.
pub fn like_pattern_sources(sql: &str) -> Result<Vec<LikePatternSrc>>
Collects LIKE / NOT LIKE pattern sources with proven lengths when possible.
Returns PluginError::invalid_params when a string, quoted identifier,
or block comment is unterminated.
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.
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.
pub fn require_like_patterns_within(
sql: &str,
parameters: &[DbValue],
max_pattern_bytes: u32,
) -> Result<()>
Enforces crate::DbCapabilities::max_pattern_bytes on LIKE patterns.
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.
pub fn require_portable_text(text: &str) -> Result<()>
Rejects BookclerkSQL TEXT that contains U+0000.
Returns PluginError::invalid_params when text contains NUL.
pub fn require_portable_text_binds(parameters: &[DbValue]) -> Result<()>
Rejects U+0000 in every BookclerkSQL TEXT bind.
Returns PluginError::invalid_params when a crate::DbValue::Text bind
contains NUL.
pub fn sql_v1_function_calls(sql: &str) -> Result<Vec<SqlFnCall>>
Collects helper calls in code spans (strings/comments are skipped).
Returns PluginError::invalid_params when a string, quoted identifier,
or block comment is unterminated.
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).
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.
Returns PluginError::invalid_params when quotes or comments are
unterminated, or when a fragment is not a single SQL-v1 statement.
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.
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.
Returns PluginError::invalid_params when quotes or block comments are
unterminated.
pub fn text_contains_nul(text: &str) -> bool
True when text contains U+0000.
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.
Returns PluginError::internal when the message cannot be serialized.
pub fn decode_db_capabilities_reply_bytes(bytes: &[u8]) -> Result<DbCapabilities>
Decodes a standalone Cap'n DbCapabilitiesReply message.
Returns the guest PluginError on err, or a decode failure on ok.
pub fn decode_db_value_bytes(bytes: &[u8]) -> Result<DbValue>
Decodes a standalone Cap'n DbValue message.
Returns when the buffer is not a valid unpacked DbValue.
pub fn decode_execute_request_bytes(bytes: &[u8]) -> Result<ExecuteRequest>
Decodes a standalone Cap'n ExecuteRequest message.
Returns when the buffer is not a valid unpacked ExecuteRequest.
pub fn decode_execute_result_reply_bytes(bytes: &[u8]) -> Result<ExecuteReply>
Decodes a standalone Cap'n ExecuteAtomicReply message.
Returns the guest PluginError on err, or a decode failure on ok.
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).
Returns when the buffer is not one valid unpacked frame.
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).
Returns PluginError::internal when the message cannot be serialized.
pub fn encoded_db_value_bytes(v: &DbValue) -> Result<Vec<u8>>
Encodes a standalone Cap'n DbValue message (unpacked stream).
Returns PluginError::invalid_params when a DbValue::Text contains
U+0000, or PluginError::internal when the message cannot be serialized.
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.
Returns PluginError::invalid_params when a DbValue::Text contains
U+0000, as encoded_db_value_bytes does.
pub fn encoded_execute_reply_bytes(reply: &ExecuteReply) -> Result<Vec<u8>>
Encodes a standalone Cap'n ExecuteReply message (unpacked stream).
Returns PluginError::invalid_params when a TEXT cell contains U+0000,
or PluginError::internal when the message cannot be serialized.
pub fn encoded_execute_request_bytes(req: &ExecuteRequest) -> Result<Vec<u8>>
Encodes a standalone Cap'n ExecuteRequest message (unpacked stream).
Returns PluginError::invalid_params when SQL or TEXT binds contain
U+0000, or PluginError::internal when the message cannot be serialized.
pub fn encoded_execute_result_reply_bytes(
outcome: Result<ExecuteReply>,
) -> Result<Vec<u8>>
Encodes a standalone Cap'n ExecuteAtomicReply (ok or err).
Returns PluginError::internal when the message cannot be serialized.
pub fn encoded_execute_stream_frame_bytes(frame: &ExecuteStreamFrame) -> Result<Vec<u8>>
Encodes one standalone ExecuteStreamFrame message (unpacked stream, one
segment).
Returns PluginError::invalid_params when a TEXT cell contains U+0000,
or PluginError::internal when the message cannot be serialized.
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.
Returns PluginError::invalid_params when a TEXT cell contains U+0000,
or PluginError::internal when the message cannot be serialized.
pub fn negotiate_rpc_features(
host_offers: &[&str],
guest_accepts: &[String],
) -> Result<Vec<String>>
Intersects host-offered and guest-accepted feature lists.
Returns a message when a required feature is missing or the guest offers an unsafe combination (streams without scalar limits).
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.
Returns PluginError::payload_too_large or an I/O error mapped as
PluginError::internal.
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".
Returns a plugin error when open, put, commit, progress reporting, or cancellation polling fails.
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.
key- The key the guest wrote under (untrusted).slots- Number of URLs in the request; valid indexes are0..slots.
The index, or None when key is not a canonical index below slots.
pub fn hint_result(hint: Option<PurchaseHint>) -> PurchaseHintResult
A bare hint as a PurchaseHintResult with no records.
hint- The store's answer;Nonewhen it did not find the title.
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.
source- The store answering.params- The batch's queries.
One result per query, in order.
The first lookup error, which fails the whole batch.
pub fn byte_source_from_async_read(
reader: Pin<Box<dyn AsyncRead + Send>>,
window: u32,
) -> Client
Returns a ByteSource client that pulls from reader.
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.
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.
reader/writer- The link to the broker.handler- Where the broker delivers messages and closes.
The broker's Sockets and the link's RPC system.
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.
Returns the guest's PluginError for an err reply, or a decode
failure when the buffer is not a valid unpacked single-segment message.
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.
Returns a decode failure when the buffer is not a valid unpacked
single-segment message; the error itself is the Ok value.
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.
Returns a plugin error when the stream or writer fails.
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.
codec- Which struct the message holds.bytes- The message, ascapnp::serializewrites it.
The decoded value, for the caller to check against its own bounds.
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.
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.
codec- Which struct the message holds.bytes- The message, ascapnp::serializewrites it.
The decoded value.
RoundTripFailure::Rejected when the bytes do not decode;
RoundTripFailure::Codec when a decoded value does not survive write
then read intact.
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.
codec- Which struct the message holds.bytes- The message, ascapnp::serializewrites it.
The decoded value.
RoundTripFailure::Rejected when the bytes do not decode;
RoundTripFailure::Codec when a decoded value does not survive write
then read intact.
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.
Returns a plugin error when the vat fails.
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.
Returns a plugin error when the vat fails.
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.
reader/writer- The link to the host.make- Builds the broker'sSocketsfrom the host's handler.
Returns an internal error when the link fails.
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.
kind- Which reply struct the message holds.bytes- The message.
The decoded reply.
Returns PluginError when the framing, the codec or a cap rejects it.
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.
Returns PluginError when a list cannot be encoded.
pub fn require_batch_len(what: &str, len: usize) -> Result<()>
Rejects a batch request the guest is not obliged to serve.
what- The operation name, for the error.len- Keys or pairs in the request.
Returns invalid_params for an empty batch and payload_too_large for
one above MAX_BATCH_KEYS.
pub fn validate_changes_page(sent: Option<&str>, page: &ChangesPage) -> Result<()>
Checks a guest's change feed page against the cursor the host sent.
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.
pub fn validate_head_many(
sent: &[String],
objects: &[Option<ObjectMetadata>],
) -> Result<()>
Checks a guest's headMany probes against the keys the host sent.
Returns internal unless there is one probe per key, in order, and every
found object names the key it was asked for.
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.
what- The operation name, for the error.sent- Keys the host sent, in order.results- Outcomes the guest returned.
Returns internal unless there is exactly one outcome per key, in the
same order and naming the same key.
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.
Returns internal describing the first broken rule.
pub fn validate_translated_keys(sent: &[String], translated: &[String]) -> Result<()>
Checks a guest's translateKeys answer against the host keys it was sent.
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.
pub const MAX_PLUGIN_MIGRATION_ID_BYTES: usize = 128;
Maximum UTF-8 bytes of one plugin-chosen migration id.
pub const PLUGIN_MIGRATIONS_TABLE: &str = "bookclerk_plugin_migrations";
Host-private plugin-binding migration journal (not a plugin-owned table).
pub const PHYSICAL_STAR_COLUMN: &str = "*";
Column name recorded for SELECT * / alias.* / RETURNING * on a physical table.
pub const D1_PHYSICAL_LIKE_GLOB_PATTERN_BYTES: u32 = 50;
Physical D1 LIKE/GLOB pattern cap in 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.
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).
pub const LIKE_GLOB_REWRITE_OVERHEAD: usize = _;
Worst-case extra bytes per LIKE / NOT LIKE after sqlite-family GLOB wrapping.
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.
pub const LIKE_GLOB_WRAP_SUFFIX: &str = "), '[', '[[]'), '*', '[*]'), '?', '[?]'), '%', '*'), '_', '?')";
Suffix of the sqlite-family LIKE→GLOB replace(...) wrap (after the pattern).
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).
pub const SQLITE_FAMILY_DIV_MOD_NULLIF_EXTRA: usize = 11;
Extra bytes for one / or % rewritten to NULLIF(operand, 0).
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).
pub const FEATURE_SCALAR_LIMITS: &str = crate::plugin_capnp::FEATURE_SCALAR_LIMITS;
Guest honors scalar / stream-window / list-page caps.
pub const FEATURE_STORAGE_CHANGES: &str = crate::plugin_capnp::FEATURE_STORAGE_CHANGES;
Guest implements super::Destination::changes.
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.
pub const FEATURE_STORAGE_COPY: &str = crate::plugin_capnp::FEATURE_STORAGE_COPY;
Guest implements server-side super::Destination::copy.
pub const FEATURE_STORAGE_DELETE_MANY: &str = crate::plugin_capnp::FEATURE_STORAGE_DELETE_MANY;
Guest implements super::Destination::delete_many.
pub const FEATURE_STORAGE_HEAD_MANY: &str = crate::plugin_capnp::FEATURE_STORAGE_HEAD_MANY;
Guest implements super::Destination::head_many.
pub const FEATURE_STORAGE_MOVE: &str = crate::plugin_capnp::FEATURE_STORAGE_MOVE;
Guest implements super::Destination::move_object.
pub const FEATURE_STORAGE_MOVE_MANY: &str = crate::plugin_capnp::FEATURE_STORAGE_MOVE_MANY;
Guest implements super::Destination::move_many.
pub const FEATURE_STORAGE_TRANSLATE_KEYS: &str = crate::plugin_capnp::FEATURE_STORAGE_TRANSLATE_KEYS;
Guest implements super::Destination::translate_keys.
pub const FEATURE_STREAMS: &str = crate::plugin_capnp::FEATURE_STREAMS;
Media moves through transferred crate::roles::ByteRange / ByteSource streams.
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.
pub const MAX_AI_EMBED_DIMENSIONS: u32 = crate::plugin_capnp::MAX_AI_EMBED_DIMENSIONS;
Most numbers in one embedding vector.
pub const MAX_AI_EMBED_TEXTS: u32 = crate::plugin_capnp::MAX_AI_EMBED_TEXTS;
Most texts in one text-embedding run.
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.
pub const MAX_AI_LANGUAGES: u32 = crate::plugin_capnp::MAX_AI_LANGUAGES;
Most language tags on one listed model.
pub const MAX_AI_MODELS: u32 = crate::plugin_capnp::MAX_AI_MODELS;
Most models one plugin lists on its ai entrypoint.
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.
pub const MAX_COVER_BYTES: u32 = crate::plugin_capnp::MAX_COVER_BYTES;
Largest image body one CoverFetcher.fetchCovers URL may return.
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.
pub const MAX_COVER_URLS: u32 = crate::plugin_capnp::MAX_COVER_URLS;
Most URLs in one CoverFetcher.fetchCovers call.
pub const MAX_CRON_BYTES: u32 = crate::plugin_capnp::MAX_CRON_BYTES;
Longest [triggers] crons source in bytes (ScheduledController.cron).
pub const MAX_EVENT_CURSOR_BYTES: u32 = crate::plugin_capnp::MAX_EVENT_CURSOR_BYTES;
Longest EventPublisher.read cursor in 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).
pub const MAX_INGRESS_ORIGIN_BYTES: u32 = crate::plugin_capnp::MAX_INGRESS_ORIGIN_BYTES;
Longest host name in IngressStarted.origin, in bytes.
pub const MAX_KV_KEY_BYTES: u32 = crate::plugin_capnp::MAX_KV_KEY_BYTES;
Longest KvNamespace key in UTF-8 bytes.
pub const MAX_KV_METADATA_BYTES: u32 = crate::plugin_capnp::MAX_KV_METADATA_BYTES;
Largest KvNamespace metadata JSON text in 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).
pub const MAX_LIST_PAGE: u32 = crate::plugin_capnp::MAX_LIST_PAGE;
Maximum objects in one Destination.list page.
pub const MAX_METADATA_AUDIO_FILES: u32 = crate::plugin_capnp::MAX_METADATA_AUDIO_FILES;
Most audio files a MetadataFiles.render request names.
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.
pub const MAX_METADATA_FILE_CHAPTERS: u32 = crate::plugin_capnp::MAX_METADATA_FILE_CHAPTERS;
Most chapters in a MetadataFileRecord.
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.
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.
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.
pub const MAX_NOTIFICATION_FIELDS: u32 = crate::plugin_capnp::MAX_NOTIFICATION_FIELDS;
Most labelled fields on one notification message or raise.
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.
pub const MAX_NOTIFICATION_HTML_BYTES: u32 = crate::plugin_capnp::MAX_NOTIFICATION_HTML_BYTES;
Longest notification HTML body, in UTF-8 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.
pub const MAX_NOTIFICATION_TITLE_BYTES: u32 = crate::plugin_capnp::MAX_NOTIFICATION_TITLE_BYTES;
Longest notification title or field name, in UTF-8 bytes.
pub const MAX_NOTIFIER_ADDRESS_BYTES: u32 = crate::plugin_capnp::MAX_NOTIFIER_ADDRESS_BYTES;
Longest notifier destination address document, in UTF-8 bytes.
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.
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.
pub const MAX_ORIGIN_TARGET_BYTES: u32 = crate::plugin_capnp::MAX_ORIGIN_TARGET_BYTES;
Longest OriginRequest.target (path and query), in bytes.
pub const MAX_PLUGIN_MIGRATION_OPS: u32 = crate::plugin_capnp::MAX_PLUGIN_MIGRATION_OPS;
Maximum already-separated operations in one plugin-owned migration.
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).
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).
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).
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).
pub const MAX_SCAN_CURSOR_BYTES: u32 = crate::plugin_capnp::MAX_SCAN_CURSOR_BYTES;
Longest scan cursor or sync token in bytes.
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.
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.
pub const MAX_SOCKET_ATTACHMENT_BYTES: u32 = crate::plugin_capnp::MAX_SOCKET_ATTACHMENT_BYTES;
Largest per-socket attachment the host keeps, in bytes.
pub const MAX_SOCKET_AUTO_RESPONSES: u32 = crate::plugin_capnp::MAX_SOCKET_AUTO_RESPONSES;
Most heartbeat pairs one Sockets.connect may declare.
pub const MAX_SOCKET_AUTO_RESPONSE_BYTES: u32 = crate::plugin_capnp::MAX_SOCKET_AUTO_RESPONSE_BYTES;
Largest heartbeat request or response frame, in 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.
pub const MAX_SOCKET_HEADERS: u32 = crate::plugin_capnp::MAX_SOCKET_HEADERS;
Most request headers, and separately subprotocols, on one
Sockets.connect.
pub const MAX_SOCKET_URL_BYTES: u32 = crate::plugin_capnp::MAX_SOCKET_URL_BYTES;
Longest Sockets.connect URL, in 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).
pub const MAX_WEBHOOK_BODY_BYTES: u32 = crate::plugin_capnp::MAX_WEBHOOK_BODY_BYTES;
Largest stored webhook request body, in bytes (1 MiB).
pub const MAX_WEBHOOK_HEADERS: u32 = crate::plugin_capnp::MAX_WEBHOOK_HEADERS;
Most request headers a [[webhooks]] row keeps.
pub const MAX_WEBHOOK_HEADER_VALUE_BYTES: u32 = crate::plugin_capnp::MAX_WEBHOOK_HEADER_VALUE_BYTES;
Longest kept request header value, in bytes.
pub const MAX_WEBHOOK_LEASE_ID_BYTES: u32 = crate::plugin_capnp::MAX_WEBHOOK_LEASE_ID_BYTES;
Longest WebhookDelivery.leaseId, in bytes.
pub const MAX_WEBHOOK_NAME_BYTES: u32 = crate::plugin_capnp::MAX_WEBHOOK_NAME_BYTES;
Longest [[webhooks]] name, in bytes.
pub const MAX_WEBHOOK_PULL_BATCH: u32 = crate::plugin_capnp::MAX_WEBHOOK_PULL_BATCH;
Most deliveries one Webhooks.pull returns.
pub const MAX_WEBHOOK_VISIBILITY_MS: u32 = crate::plugin_capnp::MAX_WEBHOOK_VISIBILITY_MS;
Longest Webhooks.pull visibility timeout, in milliseconds (12 hours).
pub const PRODUCT_API_VERSION: u32 = crate::plugin_capnp::API_VERSION;
Product ABI version (apiVersion / plugin.toml api_version).
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.
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.
pub const JSON_MEDIA_TYPE: &str = "application/json";
Media type of a JSON ExtensibleConfig payload.
pub const MAX_CHECKPOINT_BYTES: u32 = crate::plugin_capnp::MAX_CHECKPOINT_BYTES;
Maximum checkpoint payload size (bytes).
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.
pub const MAX_CHANGES_CURSOR_BYTES: u32 = crate::plugin_capnp::MAX_CHANGES_CURSOR_BYTES;
Maximum bytes of a Destination.changes cursor.
pub const MAX_CHANGES_PAGE: u32 = crate::plugin_capnp::MAX_CHANGES_PAGE;
Maximum changes in one Destination.changes page.
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).
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