bookclerk_plugin_manifest::types
plugin.toml types: manifest root and nested capability / workerd tables.
These structs are the serde projection of the install descriptor. Unknown
keys are rejected (deny_unknown_fields) so typos fail at parse time.
Semantic rules that cannot be expressed in serde alone live in
PluginManifest::validate. Product narrative: docs/plugins/README.md.
| Item | Kind | Summary |
|---|---|---|
MediaManifest |
struct | [media]: the work kinds and edition carriers a storefront or metadata provider reports, and the carriers a storefront can download. |
AcquireManifest |
struct | [acquire]: how fast the host may download from one store account of this storefront when it starts the downloads itself. |
IngressManifest |
struct | [ingress]: how an ingress plugin gives the library its public address. Required for that entrypoint and forbidden without it. |
MetadataFilesManifest |
struct | [metadata_files]: the metadata file dialects a metadataFiles plugin implements. Required for that entrypoint and forbidden without it. |
MetadataFileDialectManifest |
struct | One [[metadata_files.dialects]] row: a file format the plugin reads, and writes when writes is true. |
NotifierManifest |
struct | [notifier]: what a notifier plugin can carry. Required for that entrypoint and forbidden without it. |
NotifierAddressField |
struct | One [[notifier.address_fields]] row: a value a patron enters to receive notifications on this service. |
NotificationsManifest |
struct | [notifications]: the notification types a plugin raises through its NOTIFY binding. |
NotificationTypeManifest |
struct | One [[notifications.types]] row. |
AiManifest |
struct | [ai]: the model tasks a plugin serves on its ai entrypoint and the tasks it calls through its AI binding. |
TcpCapability |
struct | One raw TCP grant: hostname or wildcard plus allowed destination ports. |
NetworkCapabilities |
struct | [capabilities.network] — mode plus optional workerd host allowlist. |
OwnUserAgent |
struct | [capabilities.network.own_user_agent]: where a plugin keeps its own User-Agent. |
BindingCapabilities |
struct | Host bindings a plugin declared, resolved from the v3 manifest tables. |
DatabaseBindingManifest |
struct | One [[databases]] row — an isolated plugin-owned database binding. |
NamedBinding |
struct | A named host binding ([secrets], [work_fs], [oauth], [[kv_namespaces]]). |
KvNamespaceManifest |
struct | One [[kv_namespaces]] row — a durable key/value namespace the host serves from the library database, scoped to this plugin. |
TriggersManifest |
struct | [triggers] — handlers on the default entrypoint the host invokes. |
CapabilitiesManifest |
struct | Full [capabilities] table required on every manifest. |
EventConsumer |
struct | One [[events.consumers]] row — a durable domain-event trigger for the default entrypoint's event(batch) handler. |
EventProducer |
struct | One [[events.producers]] row — an event type the plugin may publish through its EVENTS binding. |
EventsManifest |
struct | [events] — consumers (triggers) and producers (publish grants). |
QueuesManifest |
struct | [queues] — Workers Queues producers (send bindings) and consumers (queue(batch) triggers). |
QueueProducer |
struct | One [[queues.producers]] row — a queue the plugin may send to through the named env binding. |
QueueConsumer |
struct | One [[queues.consumers]] row — a durable queue trigger for the default entrypoint's queue(batch) handler. |
WorkerdRuntimeManifest |
struct | [workerd] — WorkerCode-equivalent isolate configuration. |
WorkerdLimits |
struct | Optional workerd resource limits under [workerd.limits]. |
EffectiveWorkerdLimits |
struct | Concrete limits after applying host defaults and hard caps. |
ModuleSpec |
struct | One module entry in [[modules]] (workerd script packages). |
PluginManifest |
struct | On-disk plugin descriptor (plugin.toml, api_version = 3). |
OidcManifest |
struct | [[oidc.clients]] install-time OIDC AS templates. |
OidcClientToml |
struct | One [[oidc.clients]] row (snake_case TOML). |
PluginFamily |
enum | Handler family — how the daemon, CLI, and UI group plugins and which config.toml prefix holds their settings. |
PluginRuntimeKind |
enum | Guest runtime selection (runtime key in plugin.toml). |
CredentialSharing |
enum | How a storefront's store credentials may be used from several Bookclerk instances at once (credentials key in plugin.toml). |
IngressKind |
enum | How public requests reach the library. |
NotifierDestination |
enum | Kind of destination a notifier sends to ([notifier].destinations). |
NotifierFormat |
enum | Body format a notifier renders ([notifier].formats). |
NetworkMode |
enum | Network mode declared in [capabilities.network]. |
JailNetworkNeed |
enum | OS jail network capability derived from manifest network + oauth binding. |
entrypoint_family |
function | Handler family an Entrypoint belongs to. |
reaches_notification_host |
function | Whether a declared or granted network host (exact, *. wildcard, or crate::ANY_PUBLIC_HOST) reaches one of KNOWN_NOTIFICATION_HOSTS. |
is_valid_database_binding_name |
function | True when name is a valid Workers-style binding name (A-Z*). |
is_host_event_type |
function | True when event_type is in HOST_EVENT_TYPES. |
is_valid_queue_name |
function | True when name is a valid queue name: a-z0-9*, at most MAX_QUEUE_NAME_LEN characters. |
is_reserved_queue_name |
function | True when name starts with a RESERVED_QUEUE_PREFIXES entry. |
ALL_ENTRYPOINTS |
constant | Every entrypoint in declaration order (mirrors the Cap'n Proto enum). |
REGISTRY_ENTRYPOINTS |
constant | Entrypoints the host loads into their own registry (sources, destinations, database adapters) rather than the integration registry. |
MAX_DOWNLOADS_PER_DAY |
constant | Most downloads a day [acquire].downloads_per_day may declare. |
MAX_MIN_GAP_SECONDS |
constant | Longest gap between downloads [acquire].min_gap_seconds may declare (one day). |
MAX_COOLDOWN_SECONDS |
constant | Longest cool-down [acquire].cooldown_seconds may declare (one week). |
MAX_NOTIFIER_ADDRESS_FIELDS |
constant | Most [[notifier.address_fields]] rows; the same as the most keys an address document may carry. |
MAX_NOTIFICATION_TYPES |
constant | Most [[notifications.types]] rows one plugin may declare. |
KNOWN_NOTIFICATION_HOSTS |
constant | Hosts of chat, push and email services that notifier plugins talk to. A plugin that is not a notifier but asks for one of these is flagged: its consent screen says it can send messages outside Bookclerk. |
SMTP_PORTS |
constant | TCP ports of mail submission and relay (SMTP 25, SMTPS 465, submission 587); a non-notifier asking for them is flagged too. |
MAX_OWN_USER_AGENT_REASON_CHARS |
constant | Longest OwnUserAgent::reason a manifest may declare, in characters. |
MAX_OWN_USER_AGENT_HOSTS |
constant | Most hosts one OwnUserAgent table may list. |
MAX_DATABASE_BINDINGS |
constant | Maximum named database bindings one plugin may declare. |
MAX_DATABASE_BINDING_NAME_LEN |
constant | Maximum length of one database binding name. |
DEFAULT_KV_MAX_VALUE_BYTES |
constant | Default max_value_bytes for [[kv_namespaces]]: 64 KiB. |
MAX_KV_VALUE_BYTES |
constant | Largest max_value_bytes a namespace may declare: 1 MiB (the ABI cap). |
DEFAULT_KV_MAX_KEYS |
constant | Default max_keys for [[kv_namespaces]]. |
MAX_KV_KEYS |
constant | Largest max_keys a namespace may declare. |
DEFAULT_SECRETS_BINDING |
constant | Default binding for [secrets]. |
DEFAULT_WORK_FS_BINDING |
constant | Default binding for [work_fs]. |
DEFAULT_OAUTH_BINDING |
constant | Default binding for [oauth]. |
DEFAULT_SOCKETS_BINDING |
constant | Default binding for [sockets]. |
NOTIFY_BINDING |
constant | The NOTIFY binding a plugin with [[notifications.types]] receives; its name is fixed, so no other binding may take it. |
AI_BINDING |
constant | The AI binding a plugin with [ai].calls receives; its name is fixed, so no other binding may take it. |
DEFAULT_KV_BINDING |
constant | Default binding for [[kv_namespaces]]. |
DEFAULT_EVENTS_BINDING |
constant | Default binding for [[events.producers]]. |
CONFIG_BINDING |
constant | Binding name the host uses for operator config ([vars]). |
NETWORK_BINDING |
constant | Binding name the host uses for the network grant (env.NETWORK); no declared binding may take it. |
MAX_CRON_TRIGGERS |
constant | Most [triggers] crons entries one manifest may declare. |
HOST_EVENT_TYPES |
constant | Domain event types only the host emits. |
MAX_QUEUE_NAME_LEN |
constant | Maximum length of a queue name. |
RESERVED_QUEUE_PREFIXES |
constant | Queue-name prefixes only the host may use (core.events, node.<id>). |
DEFAULT_QUEUE_MAX_BATCH_SIZE |
constant | Default max_batch_size for [[queues.consumers]]. |
MAX_QUEUE_BATCH_SIZE |
constant | Largest max_batch_size a consumer may declare. |
DEFAULT_QUEUE_MAX_BATCH_TIMEOUT_SECS |
constant | Default max_batch_timeout (seconds) for [[queues.consumers]]. |
MAX_QUEUE_BATCH_TIMEOUT_SECS |
constant | Largest max_batch_timeout (seconds) a consumer may declare. |
DEFAULT_QUEUE_MAX_RETRIES |
constant | Default max_retries for [[queues.consumers]]. |
MAX_QUEUE_RETRIES |
constant | Largest max_retries a consumer may declare. |
MAX_QUEUE_RETRY_DELAY_SECS |
constant | Largest retry_delay (seconds) a consumer may declare: 12 hours. |
MIN_MESSAGE_RETENTION_SECS |
constant | Smallest message_retention_period (seconds) an event or queue consumer may declare: one minute, as in Cloudflare Queues. |
MAX_MESSAGE_RETENTION_SECS |
constant | Largest message_retention_period (seconds) an event or queue consumer may declare: 14 days, as in Cloudflare Queues. The host also caps it at events.retention_days. |
bookclerk_plugin_abi::Entrypointbookclerk_plugin_abi::EventConsumerSpecbookclerk_plugin_abi::PluginCapabilities
pub struct MediaManifest {
pub works: Vec<WorkKind>,
pub lists: Vec<MediaKind>,
pub fetches: Vec<MediaKind>,
}
[media]: the work kinds and edition carriers a storefront or metadata
provider reports, and the carriers a storefront can download.
Spellings are the wire names (book, podcast; audio, ebook,
print). There is no default: a storefront or metadata provider
without this table, or with an empty works or lists, is refused.
Fields
works: Work kinds the plugin reports.lists: Edition carriers the plugin reports in scans, catalog search and metadata records.fetches: Edition carriersfetchTitlecan deliver; a subset oflists. Storefronts only.
pub fn to_wire(&self) -> MediaSupport
The declaration in its wire shape, as describe() returns it.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct AcquireManifest {
pub downloads_per_day: Option<i64>,
pub min_gap_seconds: Option<i64>,
pub cooldown_seconds: Option<i64>,
}
[acquire]: how fast the host may download from one store account of
this storefront when it starts the downloads itself.
Stores rarely publish their limits and throttle after the fact, so a
storefront declares a safe pace here and the host keeps every automatic
download (auto-acquire, quality upgrades, acquire-all, requests from
other libraries) under it. Every field is optional: a missing
downloads_per_day means no daily budget, a missing min_gap_seconds
no gap, and a missing cooldown_seconds the host's one-hour default.
Only a plugin with the storefront entrypoint may declare the table.
The fields are signed so a negative value reaches validation and gets the same message in every author tool, rather than a parser error.
Fields
downloads_per_day: Downloads allowed per store account in any rolling 24 hours, from 1 toMAX_DOWNLOADS_PER_DAY;Nonefor no daily budget.min_gap_seconds: Seconds between the start of two downloads on one store account, from 0 toMAX_MIN_GAP_SECONDS;Nonefor no gap.cooldown_seconds: Seconds automatic downloads on an account pause after the store answersrateLimitedwithout saying how long, from 1 toMAX_COOLDOWN_SECONDS;Nonefor the host default.
pub fn validate(&self) -> Result<()>
Checks each declared value against its range.
The same rules, with the same messages, run in the TypeScript and
Python author tools (manifest-cases.json).
Returns Error::Message naming the first field outside its range.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct IngressManifest {
pub kind: IngressKind,
}
[ingress]: how an ingress plugin gives the library its public
address. Required for that entrypoint and forbidden without it.
Fields
kind: Whether requests arrive throughORIGINor straight at the daemon.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct MetadataFilesManifest {
pub dialects: Vec<MetadataFileDialectManifest>,
}
[metadata_files]: the metadata file dialects a metadataFiles plugin
implements. Required for that entrypoint and forbidden without it.
The host routes a file to a dialect from this table alone, so a sleeping plugin is started only when a file it reads turns up.
Fields
dialects: One row per dialect ([[metadata_files.dialects]]); never empty.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct MetadataFileDialectManifest {
pub id: String,
pub name: String,
pub file_names: Vec<String>,
pub suffixes: Vec<String>,
pub fields: Vec<MetadataField>,
pub credit_roles: Vec<CreditRole>,
pub writes: bool,
}
One [[metadata_files.dialects]] row: a file format the plugin reads,
and writes when writes is true.
Fields
id: Dialect id ([a-z][a-z0-9_]{0,63}), unique within the plugin; the host passes it back inparseandrender.name: Name shown in settings and on a book's files list.file_names: Exact file names the dialect reads (metadata.json), compared without ASCII case. An exact name wins over a suffix.suffixes: File name endings the dialect reads (.opf,.metadata.json), compared without ASCII case. Each starts with.; the longest match wins.fields: Fields the format carries (wire names such astitle,publishedAt); never empty.credit_roles: Credit roles the format carries; required exactly whenfieldsnamescredits.writes: Whether the dialect also writes files (render). Read-only formats, such as a store's catalog JSON, leave it false.
pub fn to_dialect(&self) -> MetadataFileDialect
The row as the host's record checks take it.
The dialect's id, fields, credit roles and write flag.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct NotifierManifest {
pub destinations: Vec<NotifierDestination>,
pub account_mail: bool,
pub formats: Vec<NotifierFormat>,
pub address_fields: Vec<NotifierAddressField>,
}
[notifier]: what a notifier plugin can carry. Required for that
entrypoint and forbidden without it.
Fields
destinations: Destination kinds the plugin sends to; never empty.account_mail: Whether administrators may mark an instance for account mail (invites, password resets). Needs apersonaldestination with anemailaddress field.formats: Body formats the plugin renders; must includetext.address_fields: Fields a personal destination's address holds; required exactly whendestinationsnamespersonal.
pub fn sends_to(&self, kind: NotifierDestination) -> bool
Whether the plugin sends to kind.
pub fn address_rules(&self) -> Vec<AddressFieldRule>
The address fields as the host's address checks take them.
One rule per [[notifier.address_fields]] row.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct NotifierAddressField {
pub key: String,
pub label: String,
pub required: bool,
pub secret: bool,
}
One [[notifier.address_fields]] row: a value a patron enters to
receive notifications on this service.
Fields
key: Key in the address document ([a-z][a-z0-9_]{0,63}).label: Label shown on the patron's form.required: Whether a destination must carry it.secret: Whether the value is a secret (a push subscription key): shown masked and never logged.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct NotificationsManifest {
pub types: Vec<NotificationTypeManifest>,
}
[notifications]: the notification types a plugin raises through its
NOTIFY binding.
Fields
types: One row per type ([[notifications.types]]).
pub fn is_default(&self) -> bool
Whether no type is declared (the table is then omitted).
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct NotificationTypeManifest {
pub id: String,
pub audience: NotificationAudience,
pub severity: NotificationSeverity,
pub title: String,
}
One [[notifications.types]] row.
Fields
id: Type id ([a-z][a-z0-9_]{0,63}), unique within the plugin; routed as<plugin id>:<id>.audience: Who it is for:operationalorpatron(accountis the host's).severity: Default severity (info,warning,critical).title: Title administrators and patrons see in the routing matrix and on each notification.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct AiManifest {
pub serves: Vec<AiTask>,
pub calls: Vec<AiTask>,
}
[ai]: the model tasks a plugin serves on its ai entrypoint and the
tasks it calls through its AI binding.
Fields
serves: Tasks the plugin's models perform (serves = ["textEmbeddings"]). Required, and never empty, for a plugin with theaientrypoint; forbidden without it. The plugin may list only models of these tasks.calls: Tasks the plugin runs throughAI(calls = ["textEmbeddings"]). The operator approves them like any capability; a plugin that lists none has noAIbinding.
pub fn is_default(&self) -> bool
Whether neither list names a task (the table is then omitted).
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct TcpCapability {
pub host: String,
pub ports: Vec<u16>,
}
One raw TCP grant: hostname or wildcard plus allowed destination ports.
Fields
host: Hostname or*.prefix wildcard (IDNA-normalized at validate time).ports: Destination ports that may be dialed. Empty is fail-closed (no ports).
Implements: Clone, Debug, Deserialize<'de>, Eq, Ord, PartialEq, PartialOrd, Serialize
pub struct NetworkCapabilities {
pub mode: NetworkMode,
pub domains: Vec<String>,
pub tcp: Vec<TcpCapability>,
pub allow_undeclared_public_redirects: bool,
pub address_cidrs: Vec<String>,
pub own_user_agent: Option<OwnUserAgent>,
}
[capabilities.network] — mode plus optional workerd host allowlist.
Defaults to deny with an empty domain list. Unknown keys are rejected.
Fields
-
mode: Whether the guest may open outbound connections / isolate fetches. -
domains: Workerd-only: initial-request host allowlist for isolate egress.Entries are exact hosts or
*.prefix wildcards; validated with IDNA ToASCII atPluginManifest::validate. Must be empty forruntime = "native"and non-empty for workerd + outbound. -
tcp: Raw TCP (connect) grants. Fetch allowlists do not imply these. -
allow_undeclared_public_redirects: When true, fetch redirects may target undeclared public hosts.Address-space policy still applies: loopback / RFC1918 / link-local / metadata never piggy-back on this flag.
-
address_cidrs: Explicit CIDR grants beyond the public Internet (no blanketprivate). -
own_user_agent: Hosts that receive the plugin's ownUser-Agentinstead of the host's.Every other request carries the host's honest agent (
crate::host_user_agent). Declaring this table asks the operator for permission on the consent form, which shows the hosts and reason.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct OwnUserAgent {
pub hosts: Vec<String>,
pub reason: String,
}
[capabilities.network.own_user_agent]: where a plugin keeps its own
User-Agent.
By default the host replaces every guest request's User-Agent with
bookclerk/<version> (+https://bookclerk.app). A plugin that talks to a
store's app API, which answers only the store's own app, lists those hosts
here with a reason. The operator sees both on the consent form and may
refuse; refused or unlisted hosts get the host's agent.
Fields
hosts: Exact hosts or*.wildcards (never*), IDNA-normalized at validate time. Between 1 andMAX_OWN_USER_AGENT_HOSTSentries.reason: One sentence for the operator on why these hosts need the plugin's own agent, such as the app API contract it follows. Non-empty, at mostMAX_OWN_USER_AGENT_REASON_CHARScharacters, no control characters.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct BindingCapabilities {
pub config: bool,
pub secrets: bool,
pub plugin_kv: bool,
pub work_fs: bool,
pub oauth: bool,
pub sockets: bool,
pub webhooks: bool,
pub databases: Vec<String>,
}
Host bindings a plugin declared, resolved from the v3 manifest tables.
Derived view produced by PluginManifest::bindings; [vars],
[secrets], [[kv_namespaces]], [work_fs], [oauth], and
[[databases]] each map onto one flag or list here so host code can gate
jail layout, consent, and env injection uniformly.
Fields
-
config: Guest may read plugin config delivered by the host ([vars]). -
secrets: Guest may read sealed secrets / credentials via host bindings ([secrets]). -
plugin_kv:[[kv_namespaces]]is declared: the host grants one durable key/value namespace per row, served from the library database. This is a different capability fromSelf::databases. -
work_fs: Guest may use host-mediated work filesystem ([work_fs]). -
oauth: Guest needs an OAuth-style callback tunnel ([oauth]).With native outbound, this upgrades jail network need to
JailNetworkNeed::Listen. -
sockets: Guest may open host-brokered WebSockets ([sockets]): theSocketsbinding plus theSocketHandlerentrypoint that receives pushed messages while the process sleeps. Every target must also pass the[capabilities.network]grant. -
webhooks: Host serves inbound webhooks for the plugin ([[webhooks]]): theWEBHOOKSbinding that pulls stored deliveries, plus the optionalwebhookHandlerentrypoint the host wakes after storing one. -
databases: Named plugin-owned database bindings ([[databases]] binding = "DB").
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct DatabaseBindingManifest {
pub binding: String,
}
One [[databases]] row — an isolated plugin-owned database binding.
Each name binds a database provisioned by the active database adapter —
separate from the Bookclerk library and from every other plugin. Names
must be [A-Z][A-Z0-9_]*, unique, and at most
MAX_DATABASE_BINDING_NAME_LEN chars; the operator consents to each
binding before enable.
Fields
binding: Binding name exposed onenv(Workers-style, e.g."DB").
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct NamedBinding {
pub binding: String,
}
A named host binding ([secrets], [work_fs], [oauth], [[kv_namespaces]]).
The binding key names the property on env; it defaults per table
(SECRETS, WORK_FS, OAUTH, KV) when omitted.
Fields
binding: Binding name exposed onenv; empty means the table default.
pub fn name_or<'a>(&'a self, default: &'a str) -> &'a str
Resolves the binding name, falling back to default.
The author's binding when non-empty, else default.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct KvNamespaceManifest {
pub binding: String,
pub namespace: String,
pub max_value_bytes: u32,
pub max_keys: u32,
}
One [[kv_namespaces]] row — a durable key/value namespace the host
serves from the library database, scoped to this plugin.
The binding key names the property on env (default KV). The
namespace defaults to the binding name lowercased, so two rows are
distinct stores unless they name the same namespace on purpose. Values
live in the library: an instance moved to another host reads its own keys.
Fields
binding: Binding name exposed onenv; empty meansKV.namespace: Namespace the binding is scoped to ([a-z0-9][a-z0-9._-]*); empty means the binding name lowercased.max_value_bytes: Largest value in bytes (defaultDEFAULT_KV_MAX_VALUE_BYTES, at mostMAX_KV_VALUE_BYTES).max_keys: Most live keys in the namespace (defaultDEFAULT_KV_MAX_KEYS, at mostMAX_KV_KEYS); aputpast the cap fails withforbidden.
pub fn name_or<'a>(&'a self, default: &'a str) -> &'a str
Resolves the binding name, falling back to default.
pub fn binding_name(&self) -> &str
Binding name on env (KV when omitted).
pub fn namespace_name(&self) -> String
Namespace the binding is scoped to: the declared name, or the binding name lowercased.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct TriggersManifest {
pub crons: Vec<CronSchedule>,
pub jobs: Vec<String>,
}
[triggers] — handlers on the default entrypoint the host invokes.
Mirrors wrangler.jsonc triggers: crons are Workers-style
scheduled(controller) triggers, and jobs are durable commands
(job(controller)). Event triggers live under [[events.consumers]].
Fields
crons: Five-field UTC cron schedules the default entrypoint'sscheduled(controller)handles (*/30 * * * *). At mostMAX_CRON_TRIGGERS, no duplicates. Empty means no cron trigger.jobs: Command types the default entrypoint'sjob(controller)handles (snake_case, e.g.stream_copy). Empty means no job trigger.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct CapabilitiesManifest {
pub network: NetworkCapabilities,
}
Full [capabilities] table required on every manifest.
Only network remains here in v3 (consent has no Wrangler analogue);
bindings and triggers moved to top-level Wrangler-shaped tables.
Fields
network: Network mode and optional workerd domain allowlist.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct EventConsumer {
pub event_type: String,
pub schema_versions: Vec<u32>,
pub supports_suspend: bool,
pub resource_class: String,
pub filter: Option<Value>,
pub max_retries: Option<u32>,
pub message_retention_period: Option<u32>,
}
One [[events.consumers]] row — a durable domain-event trigger for the
default entrypoint's event(batch) handler.
Fields
event_type: Versioned event type (book_acquired, …).schema_versions: Schema versions this guest can consume (default[1]).supports_suspend: WhetherEventResult::Suspendedis supported for this type.resource_class: Concurrency class copied onto deliveries (default"network").filter: Optional host-owned payload object filter (top-level key equality).max_retries: Redelivery attempts before dead-lettering;Noneuses the host default.message_retention_period: Seconds a delivery may wait, due but never handed to the plugin, before the host expires it (Cloudflare Queues' message retention period).Noneuses the host default; the value isMIN_MESSAGE_RETENTION_SECS..=MAX_MESSAGE_RETENTION_SECS.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct EventProducer {
pub event_type: String,
pub binding: String,
}
One [[events.producers]] row — an event type the plugin may publish
through its EVENTS binding.
Fields
event_type: Event type the plugin publishes (snake_case).binding: Publisher binding name onenv(defaultEVENTS).
pub fn binding_name(&self) -> &str
Resolves the publisher binding name (default DEFAULT_EVENTS_BINDING).
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct EventsManifest {
pub consumers: Vec<EventConsumer>,
pub producers: Vec<EventProducer>,
}
[events] — consumers (triggers) and producers (publish grants).
Fields
consumers: Event types delivered to the default entrypoint'sevent(batch).producers: Event types the plugin may publish.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct QueuesManifest {
pub producers: Vec<QueueProducer>,
pub consumers: Vec<QueueConsumer>,
}
[queues] — Workers Queues producers (send bindings) and consumers
(queue(batch) triggers).
Fields
producers: Queues the plugin may send to, oneenv.<BINDING>each.consumers: Queues delivered to the default entrypoint'squeue(batch).
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct QueueProducer {
pub queue: String,
pub binding: String,
}
One [[queues.producers]] row — a queue the plugin may send to through
the named env binding.
Fields
queue: Queue name ([a-z0-9][a-z0-9._-]*;core.andnode.are reserved).binding: Binding name onenv([A-Z][A-Z0-9_]*); required, as in Wrangler.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct QueueConsumer {
pub queue: String,
pub max_batch_size: u32,
pub max_batch_timeout: u32,
pub max_retries: u32,
pub dead_letter_queue: Option<String>,
pub retry_delay: u32,
pub max_concurrency: Option<u32>,
pub message_retention_period: Option<u32>,
}
One [[queues.consumers]] row — a durable queue trigger for the default
entrypoint's queue(batch) handler.
Fields
queue: Queue name to consume.max_batch_size: Most messages in onequeue(batch)call (defaultDEFAULT_QUEUE_MAX_BATCH_SIZE, at mostMAX_QUEUE_BATCH_SIZE).max_batch_timeout: Longest wait, in seconds, to fill a batch (defaultDEFAULT_QUEUE_MAX_BATCH_TIMEOUT_SECS).max_retries: Redeliveries before a message is dead-lettered (defaultDEFAULT_QUEUE_MAX_RETRIES).dead_letter_queue: Queue that receives messages aftermax_retriesis exhausted.retry_delay: Seconds a retried message waits before redelivery (default0).max_concurrency: Most concurrentqueue(batch)invocations across the library;Nonelets the host choose.message_retention_period: Seconds a message may wait, due but never handed to the plugin, before the host expires it.Noneuses the host default; the value isMIN_MESSAGE_RETENTION_SECS..=MAX_MESSAGE_RETENTION_SECS.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct WorkerdRuntimeManifest {
pub compatibility_date: String,
pub compatibility_flags: Vec<String>,
pub main_module: String,
pub modules_dir: String,
pub entrypoint: String,
pub limits: WorkerdLimits,
}
[workerd] — WorkerCode-equivalent isolate configuration.
Required when PluginRuntimeKind::Workerd. Maps closely to Cloudflare
Worker module config consumed by bookclerk-workerd.
Fields
compatibility_date: Cloudflare compatibility date (YYYY-MM-DD). A date newer than the pin (crate::WORKERD_PIN_COMPAT_DATE) warns and loads at that pin.compatibility_flags: Author compatibility flags. Only the Python pair is allowed, and only when the guest has a Python module. Seecrate::PYTHON_COMPATIBILITY_FLAGS.main_module: Entrypoint module filename relative to the modules tree (e.g.index.js).modules_dir: Directory containing worker modules (default"modules").entrypoint: Named export used as the Worker entrypoint (default"default").limits: Optional CPU / subrequest budgets (host-clamped; seeWorkerdLimits).
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct WorkerdLimits {
pub cpu_ms: Option<u32>,
pub subrequests: Option<u32>,
}
Optional workerd resource limits under [workerd.limits].
Local workerd does not Cap'n Proto-emit cpuMs / subRequests. Bookclerk
clamps these values, injects subrequests into egress policy JSON via
crate::EgressPolicy::from_manifest, and maps cpu_ms onto jail Spec CPU
rate (plus memory/process ceilings) for OS enforcement.
Fields
cpu_ms: Soft CPU budget in milliseconds (unset/0→Self::DEFAULT_CPU_MS, then clamped toSelf::MAX_CPU_MS).subrequests: Soft outbound fetch budget (unset/0→Self::DEFAULT_SUBREQUESTS, then clamped toSelf::MAX_SUBREQUESTS). Injected intoEGRESS_POLICY.subrequestsfor workerd guests.
pub const DEFAULT_CPU_MS: u32 = 30_000
Default CPU budget when unset or 0 (matches Echo examples): 30_000 ms.
pub const DEFAULT_SUBREQUESTS: u32 = 50
Default outbound fetch budget when unset or 0 (matches Echo examples): 50.
pub const MAX_CPU_MS: u32 = 120_000
Hard host cap for CPU budget (ms): 120_000.
pub const MAX_SUBREQUESTS: u32 = 1_000
Hard host cap for outbound fetch budget: 1_000.
pub fn effective(&self) -> EffectiveWorkerdLimits
Resolves concrete limits: unset/0 → defaults, then clamp to hard caps.
EffectiveWorkerdLimits with cpu_ms and subrequests in range
[default, max] (or exactly the author value when already in range).
pub fn clamp(&self) -> EffectiveWorkerdLimits
Alias for Self::effective.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct EffectiveWorkerdLimits {
pub cpu_ms: u32,
pub subrequests: u32,
}
Concrete limits after applying host defaults and hard caps.
Produced by WorkerdLimits::effective.
Fields
cpu_ms: Effective CPU budget in milliseconds.subrequests: Effective outbound fetch / subrequest budget.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct ModuleSpec {
pub name: String,
pub path: String,
pub module_type: String,
}
One module entry in [[modules]] (workerd script packages).
Used for packaging, Python detection (crate::manifest_needs_python),
and documenting the isolate module graph alongside [workerd].main_module.
Fields
-
name: Module name as known to the isolate (often matches the filename). -
path: Path relative to the plugin package root (or modules dir).When omitted or empty,
Self::nameis the source file in the modules directory. An explicit path is the only load-set key. -
module_type: Module type string (TOML keytype; default"js"). Use"python"for Pyodide modules.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct PluginManifest {
pub api_version: u32,
pub id: String,
pub name: Option<String>,
pub version: Option<String>,
pub logo: Option<String>,
pub runtime: PluginRuntimeKind,
pub command: Option<PathBuf>,
pub args: Vec<String>,
pub entrypoints: Vec<Entrypoint>,
pub workerd: Option<WorkerdRuntimeManifest>,
pub modules: Vec<ModuleSpec>,
pub triggers: TriggersManifest,
pub events: EventsManifest,
pub databases: Vec<DatabaseBindingManifest>,
pub vars: Option<BTreeMap<String, Value>>,
pub settings: Vec<SettingSpec>,
pub secrets: Option<NamedBinding>,
pub kv_namespaces: Vec<KvNamespaceManifest>,
pub queues: QueuesManifest,
pub work_fs: Option<NamedBinding>,
pub oauth: Option<NamedBinding>,
pub sockets: Option<NamedBinding>,
pub webhooks: Vec<WebhookManifest>,
pub credentials: Option<CredentialSharing>,
pub media: Option<MediaManifest>,
pub acquire: Option<AcquireManifest>,
pub metadata_files: Option<MetadataFilesManifest>,
pub notifier: Option<NotifierManifest>,
pub notifications: NotificationsManifest,
pub ingress: Option<IngressManifest>,
pub ai: AiManifest,
pub capabilities: CapabilitiesManifest,
pub cli: Option<CliSchema>,
pub oidc: OidcManifest,
}
On-disk plugin descriptor (plugin.toml, api_version = 3).
Root table for install / discovery, shaped after wrangler.jsonc: the
plugin exports named Entrypoints, declares triggers for its default
entrypoint ([triggers], [[events.consumers]]), and lists the host
bindings it expects on env ([vars], [secrets], [[kv_namespaces]],
[work_fs], [oauth], [[databases]], [[events.producers]]). Parse
with Self::parse (deserialize + Self::validate). Unknown keys are
rejected.
api_versionmust equalbookclerk_plugin_abi::PRODUCT_API_VERSIONidmust passcrate::validate_plugin_id- at least one entrypoint or trigger must be declared
- native requires
command; workerd requires[workerd]with date + main domainsforbidden on native (usetcpfor mediated sockets); required for workerd + outbound- optional
logomust passcrate::validate_logo
Fields
-
api_version: ABI / schema version. Must equalbookclerk_plugin_abi::PRODUCT_API_VERSION. -
id: Display / CLI alias ([a-z0-9_]{2,32}grammar). Not a privilege. -
name: Optional human-readable display name for Settings / Accounts UI. -
version: Package version. Required for enrollment andbookclerk plugin checkand must be semver: the host pins the[[settings]]schema with it (seeSelf::package_version). -
logo: Settings / UI logo:https://…URL or relative image path under the plugin root. Validated bycrate::validate_logowhen present. -
runtime: Guest runtime (nativedefault, orworkerd). Selects the backend behindbookclerk-workerd; it does not change the ABI. -
command: Native executable path relative to the install root (required whenruntime = "native"). -
args: Extra argv passed aftercommandfor native guests. -
entrypoints: Named entrypoints this plugin exports (["storefront", "cli"]). -
workerd: Workerd isolate config (required whenruntime = "workerd"). -
modules: Optional module list for workerd packages ([[modules]]). -
triggers: Default-entrypoint triggers other than events ([triggers]). -
events: Event consumers (triggers) and producers (publish grants). -
databases: Isolated plugin-owned database bindings ([[databases]]). -
vars: Operator config binding ([vars]). Declares that the guest receivesCONFIG; an empty table is the usual form. Values come from[[settings]]defaults and the plugin instance document. -
settings: Operator settings schema ([[settings]]): the keys an instance document may set, their types, enum values, and defaults. Non-secret entries need[vars];type = "secret"entries need[secrets]. -
secrets: Sealed secrets binding ([secrets]). -
kv_namespaces: Per-plugin key/value storage bindings ([[kv_namespaces]]).Durable
env.<BINDING>(defaultKV) served from the library database, distinct from [Self::databases]: a WorkersKVNamespacesurface (get/put/delete/list, expiration, metadata) that follows the instance across hosts. -
queues: Workers Queues ([queues]with[[queues.producers]]/[[queues.consumers]]): send bindings andqueue(batch)triggers on the host outbox. The domain-event bus ([events]) is the host's owncore.eventsqueue;[queues]names plugin-owned queues. -
work_fs: Host-mediated work filesystem binding ([work_fs]). -
oauth: OAuth callback tunnel binding ([oauth]). -
sockets: Host-brokered WebSocket binding ([sockets], defaultSOCKETS).The host holds each socket the guest opens, answers declared heartbeats itself, and wakes the guest's
SocketHandleronly when a real message arrives, so the guest process may sleep in between. Needs[capabilities.network] mode = "outbound"; every URL must also pass the network grant. -
webhooks: Inbound webhooks the host serves for each instance ([[webhooks]]); seecrate::webhooks. Declaring any grants the fixedcrate::WEBHOOKS_BINDINGbinding. -
credentials: How the store accounts this storefront connects may be shared between Bookclerk instances (credentials); seeCredentialSharingandSelf::credential_sharing. Only a plugin with thestorefrontentrypoint may set it. -
media: Media the plugin works with ([media]): required for plugins that export thestorefrontormetadataentrypoint and forbidden for every other plugin.describe()must return the same lists; seeMediaManifest. -
acquire: How fast the host may download from one store account ([acquire]): optional, storefronts only; seeAcquireManifest. -
metadata_files: Metadata file dialects ([metadata_files]): required for plugins that export themetadataFilesentrypoint and forbidden for every other plugin; seeMetadataFilesManifest. -
notifier: What a notifier carries ([notifier]): required for plugins that export thenotifierentrypoint and forbidden for every other plugin; seeNotifierManifest. -
notifications: Notification types the plugin raises throughNOTIFY([[notifications.types]]). -
ingress: How the plugin serves the library publicly ([ingress]): required for plugins that export theingressentrypoint and forbidden for every other plugin; seeIngressManifest. -
ai: Model tasks the plugin serves and calls ([ai]); seeAiManifest. -
capabilities: Declared network capability (consent has no Wrangler analogue). -
cli: Optional CLI schema advertised tobookclerk plugins <id>(frombookclerk-plugin-abi::CliSchema). Requires theClientrypoint. -
oidc: Optional Bookclerk-as-IdP client templates ([[oidc.clients]]).
pub fn media_support(&self) -> MediaSupport
The declared [media] in its wire shape; empty lists when the table
is left out (only valid for plugins that are neither storefronts
nor metadata providers).
pub fn credential_sharing(&self) -> CredentialSharing
How this plugin's store credentials may be shared between
instances: the declared credentials, or
CredentialSharing::SingleKeeper when it is left out.
pub fn declares_python(&self) -> bool
True when the manifest itself declares a Python workerd guest.
Python means any of: main_module ending in .py, or a [[modules]]
row with type = "python" or a .py load-set key. An explicit path
is that key; name is the key only when path is omitted. Compatibility
flags are not evidence. A .py file that exists only on disk is not a
declaration: check and materialize reject it.
true when Python flags are required and Pyodide consent hosts apply
for outbound guests.
pub fn unimplemented_surface(&self) -> Option<String>
Spawn/load error when the manifest declares a surface the host cannot run yet.
Every manifest surface is implemented today ([[kv_namespaces]] and
[queues] included); the hook stays so a future declared-but-unbuilt
table can refuse load with "not implemented yet" without touching the
spawn sites.
The first unimplemented surface, or None when load may continue.
pub fn settings_schema(&self) -> SettingsSchema
Operator settings schema declared by [[settings]].
The declared entries in order; empty when the plugin takes no operator settings.
pub fn config_options(&self) -> Vec<ConfigOption>
describe().configOptions derived from [[settings]].
A guest whose describe() returns a non-empty list must return this
list; an empty list means "use the manifest".
pub fn bindings(&self) -> BindingCapabilities
Resolves the declared host bindings into one flat view.
BindingCapabilities with one flag per named-binding table and the
[[databases]] binding names in declaration order.
pub fn has_entrypoint(&self, entrypoint: Entrypoint) -> bool
True when the plugin exports entrypoint.
pub fn consumes_events(&self) -> bool
True when the default entrypoint has an event(batch) trigger.
pub fn runs_jobs(&self) -> bool
True when the default entrypoint has a job(controller) trigger.
pub fn runs_crons(&self) -> bool
True when the default entrypoint has a scheduled(controller)
trigger ([triggers] crons).
pub fn has_registry_entrypoint(&self) -> bool
True when the plugin declares one of the REGISTRY_ENTRYPOINTS.
pub fn produces_events(&self) -> bool
True when the plugin declares any publishable event type.
pub fn consumes_queues(&self) -> bool
True when the default entrypoint has a queue(batch) trigger.
pub fn produces_queues(&self) -> bool
True when the plugin declares any queue send binding.
pub fn queue_consumer_names(&self) -> Vec<String>
Queue names the default entrypoint consumes ([[queues.consumers]]).
pub fn queue_producer_names(&self) -> Vec<String>
Queue names this plugin may send to ([[queues.producers]]),
deduplicated in declaration order.
pub fn families(&self) -> Vec<PluginFamily>
Handler families this plugin belongs to, in
PluginFamily::ALL priority order.
A plugin joins the Source / Output / Database / Ingress families through
the matching named entrypoint and the Integration family through
event consumers, queue consumers, crons, RemoteLibrary, Cli,
Oidc, Metadata, Covers, MetadataFiles, or Notifier.
Job triggers make a plugin an integration only when it has no
storefront, storage, databaseAdapter or ingress entrypoint. Beside one of
those, jobs run on that entrypoint's session (the host's stream_copy
job runs on the storage guest's destination session), so the plugin
stays in that one family and a deployment registers it there instead
of as an integration.
Deduplicated families; never empty for a validated manifest.
pub fn primary_family(&self) -> PluginFamily
Primary handler family: the first of Self::families.
Picks the config.toml settings prefix (database.* > sources.* >
output.* > ingress.* > integrations.*) and the API grouping.
The highest-priority family; Integration for a manifest with no
entrypoint (only reachable before validation).
pub fn producer_types(&self) -> Vec<String>
Event types this plugin may publish (from [[events.producers]]).
pub fn capabilities(&self) -> PluginCapabilities
Typed capability declaration this manifest implies.
Guests return exactly this value from describe() so the host's
widening check (manifest vs describe vs grant) is a plain equality
comparison. Native Rust guests typically call it on the manifest
embedded with include_str!("../plugin.toml").
Entrypoints, event consumers/producers, job types, database binding
names, and named binding names (CONFIG, SECRETS, WORK_FS,
OAUTH, KV, event, and queue bindings) in manifest order.
pub fn binding_names(&self) -> Vec<String>
Names of the non-database bindings this manifest exposes on env.
CONFIG (when [vars] is present), the resolved [secrets],
[work_fs], [oauth], [sockets] names, WEBHOOKS (with [[webhooks]]),
every [[kv_namespaces]] binding,
every distinct [[events.producers]] binding, and every
[[queues.producers]] binding, in that order.
pub fn consent_domains(&self) -> Vec<String>
Returns domains for workerd network consent UI.
IDNA-normalizes author domains and includes Pyodide CDN hosts when this is a Python + outbound guest. On normalization failure, falls back to filtering author domains individually (invalid entries dropped).
Deduplicated host patterns suitable for operator consent display.
pub fn logo_kind(&self) -> Result<Option<LogoKind>>
Classifies the optional logo field after validation.
Ok(None) when logo is unset; Ok(Some(kind)) when valid.
Returns Error from crate::validate_logo when logo is set but
invalid.
pub fn parse(text: &str) -> Result<Self>
Parses and validates a plugin.toml document.
Deserializes with toml::from_str then runs Self::validate.
text- Full UTF-8 contents ofplugin.toml.
A semantically validated PluginManifest.
Returns Error::TomlDe on malformed TOML, or Error::Message from
Self::validate.
use bookclerk_plugin_manifest::PluginManifest;
let m = PluginManifest::parse(r#"
api_version = 3
id = "echo"
runtime = "native"
command = "./echo"
entrypoints = ["cli"]
[capabilities.network]
mode = "deny"
"#).unwrap();
assert_eq!(m.id, "echo");
pub fn package_version(&self) -> Result<String>
Runs semantic validation after deserialize.
The declared version, validated as a semantic version.
Enrollment pins the settings schema under this version and refuses a plugin whose version is older than the pin, so the field is required even though the parser accepts its absence.
Returns Error::Message when version is missing or not semver.
pub fn calls_ai_task(&self, task: AiTask) -> bool
Whether the plugin may run models of task through its AI
binding ([ai].calls).
task- The task of the model a run names.
True when the manifest declares the task.
pub fn notification_hosts_requested(&self) -> Vec<String>
Notification hosts a plugin that is not a notifier asks to reach.
Nothing technical stops a plugin with a network grant from posting to a chat service itself, so the author check warns and the consent screen says the plugin can send messages outside Bookclerk.
The declared domains and TCP grants (host:port) that reach a
KNOWN_NOTIFICATION_HOSTS entry or an SMTP port, in declaration
order; empty for a notifier.
pub fn validate(&self) -> Result<()>
Checks id grammar, api_version, logo, runtime-specific required
fields, and network domain rules (native forbid / workerd outbound
require / IDNA).
Ok(()) when all rules pass.
Returns Error::Message describing the first failed rule.
pub fn spawn_command(&self) -> Option<&PathBuf>
Resolves the process path to spawn for this guest.
Some(command) for native guests; None for workerd (the host
resolves the bookclerk-workerd helper beside itself).
pub fn jail_network_need(&self) -> JailNetworkNeed
Maps manifest network + oauth binding to OS jail network policy.
Native-behind-workerd guests are nested under NetPolicy::Deny; they
must use the SDK socket capability, not ambient AF_INET. Direct-native
diagnostics still map mode = "outbound" to
JailNetworkNeed::Outbound. Fetch hostname allowlists (domains)
remain workerd-only. With [oauth], native guests also need loopback
listen for the host callback tunnel (JailNetworkNeed::Listen).
Workerd always needs loopback listen/connect to its Cloudflare child.
The jail network need the host should apply when spawning the guest.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct OidcManifest {
pub clients: Vec<OidcClientToml>,
}
[[oidc.clients]] install-time OIDC AS templates.
Fields
clients: Client templates materialized when this plugin is installed.
pub fn is_empty(&self) -> bool
True when no clients are declared.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct OidcClientToml {
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,
}
One [[oidc.clients]] row (snake_case TOML).
Fields
client_id: OAuthclient_id.display_name: Operator-facing card title.callback_path: Path appended to the plugin origin.public_client: Public PKCE when true (default).default_scopes: Scopes for first materialization.issue_refresh_token: Whether new rows may issue refresh tokens (default true).origin_config_key: Dotted config key for the player origin.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum PluginFamily {
Source,
Integration,
Output,
Database,
Ingress,
}
Handler family — how the daemon, CLI, and UI group plugins and which
config.toml prefix holds their settings.
Derived from the exported Entrypoints and declared triggers (see
PluginManifest::families); never written to plugin.toml. Wire values
are lowercase (source, integration, output, database, ingress).
Variants
Source: Storefront / library source (Storefrontentrypoint).Integration: Event consumer, job runner, remote library, CLI, OIDC bridge, metadata provider, cover fetcher, metadata file dialects, notifier, or model plugin.Output: Destination / output backend (Storageentrypoint).Database: Library database backend (DatabaseAdapterentrypoint).Ingress: Public address provider (Ingressentrypoint): a relay or a dynamic DNS name for the library.
pub const ALL: [Self; 5] = _
Every family in settings-prefix priority order.
pub fn as_str(self) -> &'static str
Returns the lowercase wire name used in API paths and config prefixes.
One of "source", "integration", "output", "database", or
"ingress".
pub fn parse(name: &str) -> Option<Self>
Parses a wire name produced by Self::as_str.
Some(family) for a known name; None otherwise.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize
pub enum PluginRuntimeKind {
Native,
Workerd,
}
Guest runtime selection (runtime key in plugin.toml).
Defaults to PluginRuntimeKind::Native when omitted.
Variants
-
Native: OS binary speaking the Workers RPC ABI, spawned throughbookclerk-jail.Requires a non-empty
command. Must not declarecapabilities.network.domains(fetch allowlists are workerd-only). Raw TCP usescapabilities.network.tcpvia the Bookclerk socket capability; ambientAF_INETis not a grant. -
Workerd: Author modules loaded by first-partybookclerk-workerd(one jail + one isolate per plugin).Requires a
[workerd]table. Outbound mode requires non-emptycapabilities.network.domains.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum CredentialSharing {
Shareable,
SingleKeeper,
}
How a storefront's store credentials may be used from several
Bookclerk instances at once (credentials key in plugin.toml).
A person's store accounts follow them to every library and branch they
connect ("Accounts on every instance" in the library catalog network
ADR). Only the plugin knows whether its store tolerates one login being
refreshed in several places, so it declares it. Defaults to
CredentialSharing::SingleKeeper, the choice that never logs a
person out, when the key is left out.
Variants
Shareable: Every instance may hold a copy of the account's secrets and refresh them on its own: the store neither rotates its refresh tokens on use nor caps the devices one login may register.SingleKeeper: One instance at a time keeps the account's login fresh (its refresh keeper) and the others receive each new token from it. For stores that rotate refresh tokens on use or register one device per login (Audible).
pub fn as_str(self) -> &'static str
The plugin.toml spelling (shareable or single_keeper).
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum IngressKind {
Relay,
Direct,
}
How public requests reach the library.
Variants
Relay: The provider holds the public address and relays each request to the plugin, which hands it to the library through theORIGINbinding.Direct: The public address points at the daemon itself (port mapping or dynamic DNS); the plugin only keeps the address current and never receivesORIGIN.
pub fn as_str(self) -> &'static str
The plugin.toml spelling: "relay" or "direct".
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum NotifierDestination {
Channel,
Personal,
}
Kind of destination a notifier sends to ([notifier].destinations).
Variants
Channel: A library channel the instance's own settings name (a Slack webhook, a PagerDuty service), which administrators route to.Personal: A patron's own address on the service (an email address, a Telegram chat), described by[[notifier.address_fields]].
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Ord, PartialEq, PartialOrd, Serialize
pub enum NotifierFormat {
Text,
Markdown,
Html,
}
Body format a notifier renders ([notifier].formats).
Variants
Text: Plain text; every notifier takes it.Markdown: Markdown, for chat services.Html: Minimal HTML, for email.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Ord, PartialEq, PartialOrd, Serialize
pub enum NetworkMode {
Deny,
Outbound,
}
Network mode declared in [capabilities.network].
Defaults to NetworkMode::Deny. See docs/plugins/README.md for native vs
workerd semantics.
Variants
-
Deny: No outbound network (default). Jail and isolate both refuse guest fetches / coarse outbound. -
Outbound: Coarse jail outbound (native) or workerd isolate egress.For workerd, pair with
domains(isolate hostname allowlist; required and validated). For native, do not setdomains; declaretcpfor mediatedconnect(). Ambient internet sockets are not a grant (native-behind-workerd sibling jail isNetPolicy::Deny).
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum JailNetworkNeed {
None,
Outbound,
Listen,
}
OS jail network capability derived from manifest network + oauth binding.
Produced by PluginManifest::jail_network_need. Distinct from isolate
hostname allowlists (crate::EgressPolicy), which apply only inside
workerd.
Variants
None: No IP sockets (mode = "deny"on native).Outbound: Nativeoutboundwithout OAuth — coarse jail outbound (no hostname filter).Listen: Nativeoutbound+bindings.oauth, or any workerd guest (loopback listen/connect to the Cloudflare child / OAuth callback tunnel).
Implements: Clone, Copy, Debug, Eq, PartialEq
pub fn entrypoint_family(entrypoint: Entrypoint) -> PluginFamily
Handler family an Entrypoint belongs to.
The PluginFamily whose config.toml prefix and API group hold plugins
exporting this entrypoint.
pub fn reaches_notification_host(declared: &str) -> bool
Whether a declared or granted network host (exact, *. wildcard, or
crate::ANY_PUBLIC_HOST) reaches one of KNOWN_NOTIFICATION_HOSTS.
declared- The host asplugin.tomlor a grant names it.
True when a request to a known notification service would pass it.
pub fn is_valid_database_binding_name(name: &str) -> bool
True when name is a valid Workers-style binding name ([A-Z][A-Z0-9_]*).
pub fn is_host_event_type(event_type: &str) -> bool
True when event_type is in HOST_EVENT_TYPES.
pub fn is_valid_queue_name(name: &str) -> bool
True when name is a valid queue name: [a-z0-9][a-z0-9._-]*, at most
MAX_QUEUE_NAME_LEN characters.
pub fn is_reserved_queue_name(name: &str) -> bool
True when name starts with a RESERVED_QUEUE_PREFIXES entry.
pub const ALL_ENTRYPOINTS: [Entrypoint; 12] = _;
Every entrypoint in declaration order (mirrors the Cap'n Proto enum).
pub const REGISTRY_ENTRYPOINTS: [Entrypoint; 4] = _;
Entrypoints the host loads into their own registry (sources, destinations, database adapters) rather than the integration registry.
Crons are rejected beside these, and job triggers beside them stay on that registry's session instead of making the plugin an integration.
pub const MAX_DOWNLOADS_PER_DAY: i64 = 10_000;
Most downloads a day [acquire].downloads_per_day may declare.
pub const MAX_MIN_GAP_SECONDS: i64 = 86_400;
Longest gap between downloads [acquire].min_gap_seconds may declare
(one day).
pub const MAX_COOLDOWN_SECONDS: i64 = 604_800;
Longest cool-down [acquire].cooldown_seconds may declare (one week).
pub const MAX_NOTIFIER_ADDRESS_FIELDS: usize = bookclerk_plugin_abi::notifications::MAX_NOTIFY_ADDRESS_KEYS;
Most [[notifier.address_fields]] rows; the same as the most keys an
address document may carry.
pub const MAX_NOTIFICATION_TYPES: usize = 64;
Most [[notifications.types]] rows one plugin may declare.
pub const KNOWN_NOTIFICATION_HOSTS: &[&str] = _;
Hosts of chat, push and email services that notifier plugins talk to. A plugin that is not a notifier but asks for one of these is flagged: its consent screen says it can send messages outside Bookclerk.
pub const SMTP_PORTS: [u16; 3] = _;
TCP ports of mail submission and relay (SMTP 25, SMTPS 465, submission 587); a non-notifier asking for them is flagged too.
pub const MAX_OWN_USER_AGENT_REASON_CHARS: usize = 300;
Longest OwnUserAgent::reason a manifest may declare, in characters.
pub const MAX_OWN_USER_AGENT_HOSTS: usize = 32;
Most hosts one OwnUserAgent table may list.
pub const MAX_DATABASE_BINDINGS: usize = 8;
Maximum named database bindings one plugin may declare.
pub const MAX_DATABASE_BINDING_NAME_LEN: usize = 32;
Maximum length of one database binding name.
pub const DEFAULT_KV_MAX_VALUE_BYTES: u32 = 65_536;
Default max_value_bytes for [[kv_namespaces]]: 64 KiB.
pub const MAX_KV_VALUE_BYTES: u32 = 1_048_576;
Largest max_value_bytes a namespace may declare: 1 MiB (the ABI cap).
pub const DEFAULT_KV_MAX_KEYS: u32 = 10_000;
Default max_keys for [[kv_namespaces]].
pub const MAX_KV_KEYS: u32 = 1_000_000;
Largest max_keys a namespace may declare.
pub const DEFAULT_SECRETS_BINDING: &str = "SECRETS";
Default binding for [secrets].
pub const DEFAULT_WORK_FS_BINDING: &str = "WORK_FS";
Default binding for [work_fs].
pub const DEFAULT_OAUTH_BINDING: &str = "OAUTH";
Default binding for [oauth].
pub const DEFAULT_SOCKETS_BINDING: &str = "SOCKETS";
Default binding for [sockets].
pub const NOTIFY_BINDING: &str = "NOTIFY";
The NOTIFY binding a plugin with [[notifications.types]] receives;
its name is fixed, so no other binding may take it.
pub const AI_BINDING: &str = "AI";
The AI binding a plugin with [ai].calls receives; its name is
fixed, so no other binding may take it.
pub const DEFAULT_KV_BINDING: &str = "KV";
Default binding for [[kv_namespaces]].
pub const DEFAULT_EVENTS_BINDING: &str = "EVENTS";
Default binding for [[events.producers]].
pub const CONFIG_BINDING: &str = "CONFIG";
Binding name the host uses for operator config ([vars]).
pub const NETWORK_BINDING: &str = "NETWORK";
Binding name the host uses for the network grant (env.NETWORK); no
declared binding may take it.
pub const MAX_CRON_TRIGGERS: usize = 8;
Most [triggers] crons entries one manifest may declare.
pub const HOST_EVENT_TYPES: [&str; 12] = _;
Domain event types only the host emits.
book_acquired is written by the host's acquire pipeline in the same
transaction as the library row once a source plugin's acquire handler
returns; the source never publishes it. edition_linked,
edition_updated and holding_added are written by the library model
resolver in the same batch as the listing they describe, and
holding_removed in the batch that deletes the holding (a scan no
longer lists it, or its account was revoked or remapped).
edition_acquire_changed is written with an edition's acquire state
when it moves to anything other than acquired (queued, in progress,
failed); becoming acquired publishes book_acquired instead.
ingest_batch_finished is written when an upload or storage intake
batch reaches a final state.
wishlist_changed is written when a wishlist entry is added or changes
status, and listening_synced when a listening sync changed what someone
has started or finished. playback_started is written when someone
opens a play session in the built-in player, playback_progress when a
session closes or progress is set outright, and playback_finished
when a listener reaches the end of an edition. Plugins consume these
types but cannot declare them under [[events.producers]].
pub const MAX_QUEUE_NAME_LEN: usize = 63;
Maximum length of a queue name.
pub const RESERVED_QUEUE_PREFIXES: [&str; 2] = _;
Queue-name prefixes only the host may use (core.events, node.<id>).
pub const DEFAULT_QUEUE_MAX_BATCH_SIZE: u32 = 10;
Default max_batch_size for [[queues.consumers]].
pub const MAX_QUEUE_BATCH_SIZE: u32 = 100;
Largest max_batch_size a consumer may declare.
pub const DEFAULT_QUEUE_MAX_BATCH_TIMEOUT_SECS: u32 = 5;
Default max_batch_timeout (seconds) for [[queues.consumers]].
pub const MAX_QUEUE_BATCH_TIMEOUT_SECS: u32 = 60;
Largest max_batch_timeout (seconds) a consumer may declare.
pub const DEFAULT_QUEUE_MAX_RETRIES: u32 = 3;
Default max_retries for [[queues.consumers]].
pub const MAX_QUEUE_RETRIES: u32 = 100;
Largest max_retries a consumer may declare.
pub const MAX_QUEUE_RETRY_DELAY_SECS: u32 = 43_200;
Largest retry_delay (seconds) a consumer may declare: 12 hours.
pub const MIN_MESSAGE_RETENTION_SECS: u32 = 60;
Smallest message_retention_period (seconds) an event or queue consumer
may declare: one minute, as in Cloudflare Queues.
pub const MAX_MESSAGE_RETENTION_SECS: u32 = 1_209_600;
Largest message_retention_period (seconds) an event or queue consumer
may declare: 14 days, as in Cloudflare Queues. The host also caps it at
events.retention_days.
Generated from crates/bookclerk-plugin-manifest at main · View as Markdown