bookclerk_workerd::granted
Host-granted HTTP reverse channel for workerd isolates: JobRunner.job
streams (Source / Destination / ProgressSink), the job's
Cancellation long poll (/cancel), named database sessions
(/db/execute, /db/execute-streamed), and the EVENTS outbox binding
(/events/publish, /events/read), the NOTIFY binding
(/notify/raise), the AI binding (/ai/run), and the SOCKETS broker binding
(/sockets/*, parsed in crate::granted_sockets).
HTTP accept/read/write runs on the multi-thread runtime (tokio::spawn) so
it is not starved by the Cap'n Proto vat LocalSet. Stub calls stay on the
vat thread via a command channel.
| Item | Kind | Summary |
|---|---|---|
GrantedListener |
trait | Accept loop abstraction (unix or tcp). |
GrantedSlot |
struct | One grant token's host stubs (vat-thread only): a JobRunner.job invocation, a CoverFetcher.fetchCovers sink, a named database binding, or an EVENTS publisher. |
spawn_granted |
function | Starts the Send HTTP accept loop and the vat-thread command dispatcher. |
parse_event_read_body |
function | Parses a /events/read body: the JSON form of EventReadRequest (bookclerk_plugin_abi::parse_event_read_json). Bounds and consent are checked later by the host publisher (bookclerk_plugin_abi::validate_event_read_request). |
GrantedTable |
type alias | Invocation-id → granted stubs. |
MAX_EVENT_PUBLISH_BODY_BYTES |
constant | Largest /events/publish request body: a base64 payload at MAX_EVENT_PAYLOAD_BYTES plus the envelope fields. |
MAX_NOTIFY_RAISE_BODY_BYTES |
constant | Largest /notify/raise request body: a raise of up to maxNotificationFields fields at their caps with every character JSON-escaped to two bytes (about 70 KiB), plus the envelope. |
MAX_AI_RUN_BODY_BYTES |
constant | Largest /ai/run request body: maxAiEmbedTexts texts at maxAiEmbedTextBytes each is 1 MiB of text, and ordinary prose grows little as JSON. A run made mostly of characters that JSON escapes to several bytes can pass that and is refused with 413; split it. |
MAX_EVENT_READ_BODY_BYTES |
constant | Largest /events/read request body: a cursor plus up to maxListPage event types. |
MAX_QUEUE_SEND_BODY_BYTES |
constant | Largest /queues/send request body: a sendBatch of base64 bodies. The host producer still caps every message at MAX_EVENT_PAYLOAD_BYTES and every batch at maxListPage; this only bounds the read. |
CANCEL_POLL_WINDOW |
constant | How long one GET /cancel long poll waits before answering 204 so the isolate re-arms; short enough that a dropped isolate cannot pin the cancellation stub for long. |
pub trait GrantedListener {
type Stream;
fn accept(&self) -> impl Future<Output = Result<Self::Stream>> + Send;
}
Accept loop abstraction (unix or tcp).
type Stream
Accepted connection type.
fn accept(&self) -> impl Future<Output = Result<Self::Stream>> + Send
Accept one connection.
Implemented by: TcpListener, UnixListener
pub struct GrantedSlot {
pub input: Option<Box<dyn Source>>,
pub output: Option<Rc<dyn Destination>>,
pub progress: Option<Box<dyn ProgressSink>>,
pub cancel: Option<Box<dyn Cancellation>>,
pub expires: Instant,
pub allow_open: bool,
pub allow_put: bool,
pub allow_progress: bool,
pub database: Option<Rc<dyn GuestDatabase>>,
pub allow_database: bool,
pub sql_policy: GuestSqlPolicy,
pub max_request_bytes: u32,
pub events: Option<Rc<dyn EventPublisher>>,
pub queue: Option<Rc<dyn QueueProducer>>,
pub kv: Option<Rc<dyn KvNamespace>>,
pub sockets: Option<Rc<dyn Sockets>>,
pub webhooks: Option<Rc<dyn Webhooks>>,
pub notify: Option<Rc<dyn NotificationRaiser>>,
pub origin: Option<Rc<dyn Origin>>,
pub ai: Option<Rc<dyn AiRunner>>,
}
One grant token's host stubs (vat-thread only): a JobRunner.job
invocation, a CoverFetcher.fetchCovers sink, a named database binding,
or an EVENTS publisher.
Fields
input: Host-granted input source.output: Host-granted output destination. Shared, so severalPUT /putrequests on one grant may stream at once (a cover fetcher puts each image as it arrives).progress: Progress sink.cancel: Host cancellation stub behind the/cancellong poll.expires: Absolute expiry; dispatch fails closed after this instant.allow_open: Whetheropenis permitted on this grant.allow_put: Whetherputis permitted on this grant.allow_progress: Whetherprogressis permitted on this grant.database: Host-mediated typed SQL session, when this invocation is granted one.allow_database: Whetherexecuteis permitted on this grant.sql_policy: Host-issued table/column/function allowlist for guest SQL.max_request_bytes: NegotiatedmaxRequestBytes. Zero is fail-closed (empty body only), never unlimited; grants with a database must store1..=MAX_SCALAR_BYTES.events: Host outbox publisher, when this grant carries theEVENTSbinding.queue: Host queue producer, when this grant is one[[queues.producers]]binding.kv: Host KV namespace, when this grant is one[[kv_namespaces]]binding.sockets: Host socket broker, when this grant is theSOCKETSbinding.webhooks: Host webhook store, when this grant is theWEBHOOKSbinding.notify: Host notification router entry, when this grant is theNOTIFYbinding.origin: The library, when this grant is a relay ingress plugin'sORIGINbinding.ai: Host model router entry, when this grant is theAIbinding.
pub fn origin_only(origin: Rc<dyn Origin>, expires: Instant) -> Self
A grant that only reaches the library over /origin/fetch (no
streams, no database, no events, no KV, no sockets).
pub fn sockets_only(sockets: Rc<dyn Sockets>, expires: Instant) -> Self
A grant that only reaches the instance's socket broker over
/sockets/* (no streams, no database, no events, no KV).
pub fn webhooks_only(webhooks: Rc<dyn Webhooks>, expires: Instant) -> Self
A grant that only reaches the instance's webhook store over
/webhooks/* (no streams, no database, no events, no KV).
pub fn kv_only(kv: Rc<dyn KvNamespace>, expires: Instant) -> Self
A grant that only reaches one KV namespace over /kv/* (no streams,
no database, no events).
pub fn output_only(output: Rc<dyn Destination>, expires: Instant) -> Self
A grant that only streams bodies into one host destination over
PUT /put (no source, progress, database, events or KV).
pub fn queue_only(producer: Rc<dyn QueueProducer>, expires: Instant) -> Self
A grant that only sends into one queue (no streams, no database).
pub fn notify_only(notify: Rc<dyn NotificationRaiser>, expires: Instant) -> Self
A grant that only raises notifications over /notify/raise (no
streams, no database, no events).
pub fn ai_only(ai: Rc<dyn AiRunner>, expires: Instant) -> Self
A grant that only runs models over /ai/run (no streams, no
database, no events).
pub fn events_only(events: Rc<dyn EventPublisher>, expires: Instant) -> Self
A grant that only publishes events (no streams, no database).
pub fn database_only(database: Rc<dyn GuestDatabase>, expires: Instant) -> Self
A grant that only reaches one named plugin database over
/db/execute (no streams, no events). The host-side binding session
enforces the binding-owned scope; the broker defers to it.
pub fn spawn_granted<L>(listener: L, token: String, table: GrantedTable)
where
L: GrantedListener + Send + 'static,
<L as >::Stream: AsyncRead + AsyncWrite + Unpin + Send + 'static,
Starts the Send HTTP accept loop and the vat-thread command dispatcher.
Must be called from a LocalSet (dispatcher is spawn_local).
pub fn parse_event_read_body(body: &[u8]) -> Result<EventReadRequest, PluginError>
Parses a /events/read body: the JSON form of EventReadRequest
(bookclerk_plugin_abi::parse_event_read_json). Bounds and consent are
checked later by the host publisher
(bookclerk_plugin_abi::validate_event_read_request).
Returns invalid_params when the body is not that JSON object.
pub type GrantedTable = Rc<RefCell<HashMap<String, GrantedSlot>>>;
Invocation-id → granted stubs.
pub const MAX_EVENT_PUBLISH_BODY_BYTES: u32 = _;
Largest /events/publish request body: a base64 payload at
MAX_EVENT_PAYLOAD_BYTES plus the envelope fields.
pub const MAX_NOTIFY_RAISE_BODY_BYTES: u32 = _;
Largest /notify/raise request body: a raise of up to
maxNotificationFields fields at their caps with every character
JSON-escaped to two bytes (about 70 KiB), plus the envelope.
pub const MAX_AI_RUN_BODY_BYTES: u32 = _;
Largest /ai/run request body: maxAiEmbedTexts texts at
maxAiEmbedTextBytes each is 1 MiB of text, and ordinary prose grows
little as JSON. A run made mostly of characters that JSON escapes to
several bytes can pass that and is refused with 413; split it.
pub const MAX_EVENT_READ_BODY_BYTES: u32 = _;
Largest /events/read request body: a cursor plus up to maxListPage
event types.
pub const MAX_QUEUE_SEND_BODY_BYTES: u32 = _;
Largest /queues/send request body: a sendBatch of base64 bodies. The
host producer still caps every message at MAX_EVENT_PAYLOAD_BYTES and
every batch at maxListPage; this only bounds the read.
pub const CANCEL_POLL_WINDOW: Duration = _;
How long one GET /cancel long poll waits before answering 204 so the
isolate re-arms; short enough that a dropped isolate cannot pin the
cancellation stub for long.
Generated from crates/bookclerk-workerd at main · View as Markdown