bookclerk_workerd::invoke

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

Last updated View as Markdown

POST /invoke: the Cap'n Proto data plane between the launcher and the adapter isolate.

InvokeClient is a Cap'n Proto ClientHook. Every method call made through a typed client built from it (ContentSourceClient, EventConsumerClient, JobRunnerClient, DatabaseClient, …) becomes one HTTP request whose body is the $Params struct as an unpacked single-segment message and whose 200 reply body is the $Results struct — the same envelopes the generated generated-wire.ts codecs read and write in the isolate. No JSON projection of any ABI struct exists on this path; see docs/internals/workerd-bridge.md.

Unpacked messages carry no capability table, so interface-typed fields are written as capability indexes and the table travels beside the message as the X-Bookclerk-Caps JSON header. Host-served capabilities are GrantCaps — grant tokens the isolate presents on the granted channel — and the only isolate-served kind is an AdapterDatabaseSession, which the reply names by object id and later calls address with X-Bookclerk-Target.

Item Kind Summary
GrantCap struct A capability that exists only to be described: it is never callable from this process. Placed in a $Params capability table it is serialized as its CapDescriptor in X-Bookclerk-Caps, and the isolate reaches the host object behind it through the granted channel with the token.
InvokeClient struct Cap'n Proto client hook whose calls are POST /invoke requests.
CapDescriptor enum One entry of the X-Bookclerk-Caps table. Entry i describes capability index i of the message beside it.
method_headers function Header values for one (interface, method) pair.
MAX_INVOKE_BODY_BYTES constant Largest /invoke request or reply body.

Structs

GrantCap

pub struct GrantCap {
    /* private fields */
}

A capability that exists only to be described: it is never callable from this process. Placed in a $Params capability table it is serialized as its CapDescriptor in X-Bookclerk-Caps, and the isolate reaches the host object behind it through the granted channel with the token.

GrantCap::new

pub fn new(descriptor: CapDescriptor) -> Self

Registers a new grant capability.

GrantCap::client

pub fn client<C: FromClientHook>(descriptor: CapDescriptor) -> C

Builds a typed Cap'n client (e.g. source::Client) over a new grant capability.

GrantCap::descriptor

pub fn descriptor(&self) -> &CapDescriptor

The descriptor this capability serializes as.

Implements: ClientHook, Clone

InvokeClient

pub struct InvokeClient {
    /* private fields */
}

Cap'n Proto client hook whose calls are POST /invoke requests.

InvokeClient::new

pub fn new(http: BridgeHttp, context: Option<String>) -> Self

A hook for calls carrying context (the bridge JSON of one open), or none for PluginWorker.*.

InvokeClient::with_keepalive

pub fn with_keepalive(
    http: BridgeHttp,
    context: Option<String>,
    keepalive: Option<Rc<dyn Any>>,
) -> Self

Like new, also pinning keepalive for as long as any client derived from this hook (including reply capabilities) lives.

InvokeClient::typed

pub fn typed<C: FromClientHook>(&self) -> C

Typed client (content_source::Client, job_runner::Client, …) over this hook.

Implements: ClientHook, Clone

Enums

CapDescriptor

pub enum CapDescriptor {
    Source { token: String },
    Destination { token: String },
    Progress { token: String },
    Cancellation { token: String },
    EventPublisher { token: String },
    GuestDatabase { token: String, binding: String },
    AdapterSession { id: String },
}

One entry of the X-Bookclerk-Caps table. Entry i describes capability index i of the message beside it.

Variants

  • Source: Source → granted GET /open.
    • token: Grant token.
  • Destination: Destination → granted PUT /put.
    • token: Grant token.
  • Progress: ProgressSink → granted POST /progress.
    • token: Grant token.
  • Cancellation: Cancellation → granted GET /cancel long poll.
    • token: Grant token.
  • EventPublisher: EventPublisher → granted POST /events/publish.
    • token: Grant token.
  • GuestDatabase: GuestDatabase → granted POST /db/execute.
    • token: Grant token.
    • binding: [[databases]] binding name.
  • AdapterSession: Isolate-served AdapterDatabaseSession; later calls carry id in X-Bookclerk-Target.
    • id: Isolate-side object id.

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

Functions

method_headers

pub fn method_headers(
    interface_id: u64,
    method_id: u16,
) -> Option<(&'static str, &'static str)>

Header values for one (interface, method) pair.

Returns None for interfaces that are not routed over /invoke (Source, ByteSource, EventPublisher, GuestDatabase, …) and for ordinals outside the schema.

Constants

MAX_INVOKE_BODY_BYTES

pub const MAX_INVOKE_BODY_BYTES: u32 = _;

Largest /invoke request or reply body.

Twice the scalar ceiling so an EventConsumer.event batch or a JobRunner.job invocation with a checkpoint still fits; equal to the isolate codec's traversal budget (MAX_TRAVERSAL_WORDS words in db-capnp.ts), so anything larger would be rejected there anyway.

Generated from crates/bookclerk-workerd at main · View as Markdown