bookclerk_workerd::granted_webhooks

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

Last updated View as Markdown

POST /webhooks/<op> on the granted reverse channel: a workerd isolate's env.WEBHOOKS calls, parsed and answered over plain byte slices.

The isolate holds a webhooks-only grant token minted at open; each call names its operation in the path (url, pull, ack) and carries that operation's fields as JSON. Every request is checked with the same bookclerk_plugin_abi::webhooks rules the host applies again when it serves Webhooks, so a malformed call fails here with a typed error and never reaches the host. Keeping parsing sans-IO lets the webhook_route fuzz target drive the code the bridge runs.

Item Kind Summary
RouteUrl struct POST /webhooks/url body.
RoutePull struct POST /webhooks/pull body.
RouteAck struct POST /webhooks/ack body.
WebhookCall enum One checked env.WEBHOOKS call, ready for the host's Webhooks stub.
WebhookReply enum What the host answered one WebhookCall with.
parse_webhook_call function Parses and checks one POST /webhooks/<op> call.
webhook_reply_json function Encodes a host answer as the route's JSON reply body.
MAX_WEBHOOK_ROUTE_BODY_BYTES constant Largest /webhooks/* request body: an ack naming the most leases in both lists at their longest, with JSON quoting, plus room for the name. The ABI checks bound each field once decoded; this only bounds the read.
WEBHOOK_ROUTE_OPS constant Operations the route serves, in path spelling.

Structs

RouteUrl

pub struct RouteUrl {
    pub name: String,
}

POST /webhooks/url body.

Fields

  • name: [[webhooks]] name.

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

RoutePull

pub struct RoutePull {
    pub name: String,
    pub batch_size: u32,
    pub visibility_timeout_ms: u32,
}

POST /webhooks/pull body.

Fields

  • name: [[webhooks]] name.
  • batch_size: Most deliveries to lease, 1 to maxWebhookPullBatch.
  • visibility_timeout_ms: Lease length in milliseconds; zero or absent means one minute.

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

RouteAck

pub struct RouteAck {
    pub name: String,
    pub acks: Vec<String>,
    pub retries: Vec<String>,
}

POST /webhooks/ack body.

Fields

  • name: [[webhooks]] name.
  • acks: Leases whose deliveries are done.
  • retries: Leases whose deliveries the next pull offers again.

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

Enums

WebhookCall

pub enum WebhookCall {
    Url(String),
    Pull(WebhookPullRequest),
    Ack(WebhookAckRequest),
}

One checked env.WEBHOOKS call, ready for the host's Webhooks stub.

Variants

  • Url: Webhooks.url.
  • Pull: Webhooks.pull.
  • Ack: Webhooks.ack.

Implements: Clone, Debug, Eq, PartialEq

WebhookReply

pub enum WebhookReply {
    Url(Option<String>),
    Pulled(WebhookPullPage),
    Done,
}

What the host answered one WebhookCall with.

Variants

  • Url: url answered this URL, or none.
  • Pulled: pull leased these deliveries.
  • Done: ack finished.

Implements: Clone, Debug, Eq, PartialEq

Functions

parse_webhook_call

pub fn parse_webhook_call(op: &str, body: &[u8]) -> Result<WebhookCall, PluginError>

Parses and checks one POST /webhooks/<op> call.

Arguments

Returns

The call, with every field within the ABI limits.

Errors

Returns not_found for an operation the route does not serve, and invalid_params for malformed JSON, an unknown field, a malformed name or lease id, or a batch size or lease length out of range.

webhook_reply_json

pub fn webhook_reply_json(reply: &WebhookReply) -> Result<Vec<u8>>

Encodes a host answer as the route's JSON reply body.

url answers {"url": "..."} (or null), pull answers the WebhookPullPage (bodies as base64), and ack answers {}.

Errors

Returns the serializer's error, which a well-formed page never produces.

Constants

MAX_WEBHOOK_ROUTE_BODY_BYTES

pub const MAX_WEBHOOK_ROUTE_BODY_BYTES: u32 = _;

Largest /webhooks/* request body: an ack naming the most leases in both lists at their longest, with JSON quoting, plus room for the name. The ABI checks bound each field once decoded; this only bounds the read.

WEBHOOK_ROUTE_OPS

pub const WEBHOOK_ROUTE_OPS: [&str; 3] = _;

Operations the route serves, in path spelling.

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