bookclerk_workerd::granted_webhooks
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. |
pub struct RouteUrl {
pub name: String,
}
POST /webhooks/url body.
Fields
name:[[webhooks]]name.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
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 tomaxWebhookPullBatch.visibility_timeout_ms: Lease length in milliseconds; zero or absent means one minute.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
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
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
pub enum WebhookReply {
Url(Option<String>),
Pulled(WebhookPullPage),
Done,
}
What the host answered one WebhookCall with.
Variants
Url:urlanswered this URL, or none.Pulled:pullleased these deliveries.Done:ackfinished.
Implements: Clone, Debug, Eq, PartialEq
pub fn parse_webhook_call(op: &str, body: &[u8]) -> Result<WebhookCall, PluginError>
Parses and checks one POST /webhooks/<op> call.
op- Path segment after/webhooks/.body- Request body bytes, already bounded byMAX_WEBHOOK_ROUTE_BODY_BYTES.
The call, with every field within the ABI limits.
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.
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 {}.
Returns the serializer's error, which a well-formed page never produces.
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.
pub const WEBHOOK_ROUTE_OPS: [&str; 3] = _;
Operations the route serves, in path spelling.
Generated from crates/bookclerk-workerd at main · View as Markdown