# 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`](/docs/internals/crates/bookclerk_workerd/granted_sockets/index.md)).

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`](#grantedlistener) | trait | Accept loop abstraction (unix or tcp). |
| [`GrantedSlot`](#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`](#spawn_granted) | function | Starts the Send HTTP accept loop and the vat-thread command dispatcher. |
| [`parse_event_read_body`](#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`](#grantedtable) | type alias | Invocation-id → granted stubs. |
| [`MAX_EVENT_PUBLISH_BODY_BYTES`](#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`](#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`](#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`](#max_event_read_body_bytes) | constant | Largest `/events/read` request body: a cursor plus up to `maxListPage` event types. |
| [`MAX_QUEUE_SEND_BODY_BYTES`](#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`](#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

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

Accept loop abstraction (unix or tcp).

#### GrantedListener::Stream

```rust
type Stream
```

Accepted connection type.

#### GrantedListener::accept

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

Accept one connection.

Implemented by: `TcpListener`, `UnixListener`

## Structs

### GrantedSlot

```rust
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

```rust
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

```rust
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

```rust
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

```rust
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

```rust
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

```rust
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

```rust
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

```rust
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

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

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

#### GrantedSlot::database_only

```rust
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

```rust
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

```rust
pub fn parse_event_read_body(body: &[u8]) -> Result<EventReadRequest, PluginError>
```

Parses a `/events/read` body: the JSON form of [`EventReadRequest`](/docs/internals/crates/bookclerk_plugin_abi/event_read/index.md#eventreadrequest)
([`bookclerk_plugin_abi::parse_event_read_json`](/docs/internals/crates/bookclerk_plugin_abi/event_read/index.md#parse_event_read_json)). Bounds and consent are
checked later by the host publisher
([`bookclerk_plugin_abi::validate_event_read_request`](/docs/internals/crates/bookclerk_plugin_abi/event_read/index.md#validate_event_read_request)).

#### Errors

Returns `invalid_params` when the body is not that JSON object.

## Type aliases

### GrantedTable

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

Invocation-id → granted stubs.

## Constants

### MAX_EVENT_PUBLISH_BODY_BYTES

```rust
pub const MAX_EVENT_PUBLISH_BODY_BYTES: u32 = _;
```

Largest `/events/publish` request body: a base64 payload at
[`MAX_EVENT_PAYLOAD_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_event_payload_bytes) plus the envelope fields.

### MAX_NOTIFY_RAISE_BODY_BYTES

```rust
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

```rust
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

```rust
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

```rust
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`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_event_payload_bytes) and
every batch at `maxListPage`; this only bounds the read.

### CANCEL_POLL_WINDOW

```rust
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.
