bookclerk_workerd::granted

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

Last updated View as Markdown

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.

Traits

GrantedListener

pub trait GrantedListener {
    type Stream;
    fn accept(&self) -> impl Future<Output = Result<Self::Stream>> + Send;
}

Accept loop abstraction (unix or tcp).

GrantedListener::Stream

type Stream

Accepted connection type.

GrantedListener::accept

fn accept(&self) -> impl Future<Output = Result<Self::Stream>> + Send

Accept one connection.

Implemented by: TcpListener, UnixListener

Structs

GrantedSlot

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 several PUT /put requests 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 /cancel long poll.
  • expires: Absolute expiry; dispatch fails closed after this instant.
  • allow_open: Whether open is permitted on this grant.
  • allow_put: Whether put is permitted on this grant.
  • allow_progress: Whether progress is permitted on this grant.
  • database: Host-mediated typed SQL session, when this invocation is granted one.
  • allow_database: Whether execute is permitted on this grant.
  • sql_policy: Host-issued table/column/function allowlist for guest SQL.
  • max_request_bytes: Negotiated maxRequestBytes. Zero is fail-closed (empty body only), never unlimited; grants with a database must store 1..=MAX_SCALAR_BYTES.
  • events: Host outbox publisher, when this grant carries the EVENTS binding.
  • 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 the SOCKETS binding.
  • webhooks: Host webhook store, when this grant is the WEBHOOKS binding.
  • notify: Host notification router entry, when this grant is the NOTIFY binding.
  • origin: The library, when this grant is a relay ingress plugin's ORIGIN binding.
  • ai: Host model router entry, when this grant is the AI binding.

GrantedSlot::origin_only

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

GrantedSlot::sockets_only

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

GrantedSlot::webhooks_only

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

GrantedSlot::kv_only

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

GrantedSlot::output_only

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

GrantedSlot::queue_only

pub fn queue_only(producer: Rc<dyn QueueProducer>, expires: Instant) -> Self

A grant that only sends into one queue (no streams, no database).

GrantedSlot::notify_only

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

GrantedSlot::ai_only

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

GrantedSlot::events_only

pub fn events_only(events: Rc<dyn EventPublisher>, expires: Instant) -> Self

A grant that only publishes events (no streams, no database).

GrantedSlot::database_only

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.

Functions

spawn_granted

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

parse_event_read_body

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

Errors

Returns invalid_params when the body is not that JSON object.

Type aliases

GrantedTable

pub type GrantedTable = Rc<RefCell<HashMap<String, GrantedSlot>>>;

Invocation-id → granted stubs.

Constants

MAX_EVENT_PUBLISH_BODY_BYTES

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.

MAX_NOTIFY_RAISE_BODY_BYTES

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.

MAX_AI_RUN_BODY_BYTES

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.

MAX_EVENT_READ_BODY_BYTES

pub const MAX_EVENT_READ_BODY_BYTES: u32 = _;

Largest /events/read request body: a cursor plus up to maxListPage event types.

MAX_QUEUE_SEND_BODY_BYTES

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.

CANCEL_POLL_WINDOW

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