bookclerk_plugin_abi::event_read
Validation of one EventPublisher.read request and its opaque cursor.
The request comes from a jailed guest: over Cap'n Proto for native guests
and as JSON on the granted /events/read route for workerd isolates. The
host checks it here, sans-IO, before it touches the outbox. The
event_read fuzz target drives these functions (fuzz/oracles/event_read.rs)
with the same code the host runs.
A cursor names the last outbox row a page scanned: its stored created_at
text and its id. On the wire it is v1.<hex created_at>.<hex id> in
lowercase hex, which guests treat as opaque. Only the canonical spelling
decodes, so a cursor that decodes always re-encodes to the same text.
| Item | Kind | Summary |
|---|---|---|
EventReadRequest |
struct | Request of EventPublisher.read: one page of past outbox events. |
EventReadPage |
struct | Success payload of EventPublisher.read. |
EventCursor |
struct | Position of the last outbox row a read scanned. |
EventReadQuery |
struct | A read request the host accepted. |
EventReadStart |
enum | Where a validated read starts. |
parse_event_read_json |
function | Parses the JSON body of one /events/read request (the workerd route's form of EventReadRequest): a JSON object with only the request's camelCase fields, each optional. |
is_cursor_event_id |
function | True when an outbox event id can be named by an EventCursor: non-empty, at most MAX_CURSOR_EVENT_ID_BYTES, with no whitespace or control characters. The outbox refuses any other caller-chosen id, so every stored row stays reachable by a read. |
validate_event_read_request |
function | Checks one guest read request against the bounds plugin.capnp declares and the instance's consented subscription types. |
MAX_CURSOR_CREATED_AT_BYTES |
constant | Longest stored created_at text a cursor may carry, in bytes. |
MAX_CURSOR_EVENT_ID_BYTES |
constant | Longest outbox event id a cursor may carry, in bytes. |
pub struct EventReadRequest {
pub after: String,
pub since_unix_ms: u64,
pub types: Vec<String>,
pub limit: u32,
}
Request of EventPublisher.read: one page of past outbox events.
Fields
after: Opaque cursor from an earlierEventReadPage::cursor; empty starts atSelf::since_unix_ms.since_unix_ms: UTC Unix milliseconds to start from whenafteris empty; zero starts at the oldest retained event.types: Event types to return; empty means every consented subscription.limit: Most events to return; zero meansmaxListPage.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct EventReadPage {
pub events: Vec<DomainEvent>,
pub cursor: String,
pub more: bool,
pub expired_event_ids: Vec<String>,
pub truncated: bool,
}
Success payload of EventPublisher.read.
Fields
events: Matching events in outbox order.delivery_attemptis zero anddeduplication_keyis the event id.cursor: Opaque position after the last event scanned; empty only when nothing was scanned and the request had no cursor.more: True when more events may follow.expired_event_ids: Ids of the events on this page whose delivery to this plugin expired unleased.truncated: True when the start position is older than the events retention window, so earlier events may be gone.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct EventCursor {
/* private fields */
}
Position of the last outbox row a read scanned.
pub fn new(
created_at: impl Into<String>,
id: impl Into<String>,
) -> Result<Self, PluginError>
Builds a cursor for one outbox row.
created_at- The row's storedcreated_attext.id- The row's event id.
Returns invalid_cursor when created_at is not RFC 3339 or either
part is empty, too long, or contains whitespace or control characters.
pub fn created_at(&self) -> &str
The stored created_at text of the row.
pub fn id(&self) -> &str
The event id of the row.
pub fn encode(&self) -> String
Encodes the cursor as its opaque wire text.
pub fn decode(text: &str) -> Result<Self, PluginError>
Decodes the opaque wire text a guest sent back.
Returns invalid_cursor when text is longer than
maxEventCursorBytes, is not the canonical v1.<hex>.<hex> form, or
names a row Self::new would refuse.
Implements: Clone, Debug, Eq, Ord, PartialEq, PartialOrd
pub struct EventReadQuery {
pub start: EventReadStart,
pub types: BTreeSet<String>,
pub limit: u32,
}
A read request the host accepted.
Fields
start: Where the read starts.types: Consented event types to return; never empty.limit: Most events to return,1..=maxListPage.
Implements: Clone, Debug, Eq, PartialEq
pub enum EventReadStart {
Oldest,
Since(DateTime<Utc>),
After(EventCursor),
}
Where a validated read starts.
Variants
Oldest: The oldest retained event.Since: The first event stored at or after this time.After: The first event after this cursor.
Implements: Clone, Debug, Eq, PartialEq
pub fn parse_event_read_json(body: &[u8]) -> Result<EventReadRequest, PluginError>
Parses the JSON body of one /events/read request (the workerd route's
form of EventReadRequest): a JSON object with only the request's
camelCase fields, each optional.
body- Request body bytes from the isolate (untrusted).
Returns invalid_params when body is not such an object. An array is
refused even though serde could read the struct from one.
pub fn is_cursor_event_id(id: &str) -> bool
True when an outbox event id can be named by an [EventCursor]:
non-empty, at most MAX_CURSOR_EVENT_ID_BYTES, with no whitespace or
control characters. The outbox refuses any other caller-chosen id, so
every stored row stays reachable by a read.
pub fn validate_event_read_request(
request: &EventReadRequest,
consented: &BTreeSet<String>,
) -> Result<EventReadQuery, PluginError>
Checks one guest read request against the bounds plugin.capnp declares
and the instance's consented subscription types.
request- The guest's request.consented- Event types the instance's consented[[events.consumers]]rows subscribe to.
The validated query, with an empty types list widened to consented
and a zero limit raised to maxListPage.
forbiddenwhen the instance consumes no events, or a requested type is not one it consumes.invalid_cursorwhenafterdoes not decode.invalid_paramswhen bothafterandsinceUnixMsare set, whensinceUnixMsis not a representable time, or whenlimitor the type list exceedsmaxListPage.
pub const MAX_CURSOR_CREATED_AT_BYTES: usize = 64;
Longest stored created_at text a cursor may carry, in bytes.
pub const MAX_CURSOR_EVENT_ID_BYTES: usize = 128;
Longest outbox event id a cursor may carry, in bytes.
Generated from crates/bookclerk-plugin-abi at main · View as Markdown