bookclerk_plugin_abi::error
Plugin error model shared by host and guests.
Capability failures serialize as PluginError in the Cap'n Proto
PluginError struct (or the equivalent workerd reject payload). Codes are
stable snake_case strings matching the PluginErrorCode enum in
schema/plugin.capnp. Unknown future codes are preserved as
PluginErrorCode::Unknown plus the raw wire string — they are never
collapsed to PluginErrorCode::Internal.
| Item | Kind | Summary |
|---|---|---|
PluginError |
struct | RPC / plugin failure payload returned to the host. |
LimitExceeded |
struct | One exceeded negotiated limit: which cap, its value, and the value that exceeded it. |
PluginErrorCode |
enum | Stable error codes for plugin RPC failures (schema PluginError.code). |
Result |
type alias | Result alias for ABI operations that fail as PluginError. |
pub struct PluginError {
pub code: PluginErrorCode,
pub message: String,
pub details: Option<Map<String, Value>>,
pub wire_code: Option<String>,
}
RPC / plugin failure payload returned to the host.
Wire shape: { "code": "…", "message": "…", "details"?: {…} }. Display
formats as {code}: {message}. Unknown codes keep the raw wire string in
Self::wire_code / Self::wire_str.
Fields
code: Machine-stable failure category (wirecode).message: Operator-facing explanation; must not embed secrets.details: Optional structured extras (validation paths, store status codes, …). Omitted from JSON whenNone.wire_code: Raw wire code whenSelf::codeisPluginErrorCode::Unknown.
pub fn new(code: PluginErrorCode, message: impl Into<String>) -> Self
Builds an error with the given code and message and no details.
code- StablePluginErrorCodefor the wirecodefield.message- Human-readable explanation shown to operators.
pub fn from_wire(code: &str, message: impl Into<String>) -> Self
Reconstruct from a wire code string without collapsing unknown codes.
pub fn wire_str(&self) -> &str
Wire code string (raw unknown code when present).
pub fn invalid_params(message: impl Into<String>) -> Self
Convenience for PluginErrorCode::InvalidParams.
pub fn unsupported(message: impl Into<String>) -> Self
Convenience for PluginErrorCode::Unsupported.
pub fn internal(message: impl Into<String>) -> Self
Convenience for PluginErrorCode::Internal.
pub fn not_found(message: impl Into<String>) -> Self
Convenience for PluginErrorCode::NotFound.
pub fn unavailable(message: impl Into<String>) -> Self
Convenience for PluginErrorCode::Unavailable.
Use for ambiguous transport failures (lost HTTP/RPC responses, timeouts) where the caller should retry the same idempotency key.
pub fn network_not_granted(destination: &str, setting: Option<&str>) -> Self
Convenience for PluginErrorCode::NetworkNotGranted.
destination- The refusedhost:port; stored asdetails.destination.setting- The network setting whose value names the destination and awaits approval, when one does; stored asdetails.setting.
pub fn rate_limited(message: impl Into<String>, retry_after: Option<Duration>) -> Self
Convenience for PluginErrorCode::RateLimited.
message- Human-readable explanation (which backend, which call).retry_after- How long the backend asked to be left alone, when it said (itsRetry-After); stored asdetails.retryAfterMs.
pub fn retry_after(&self) -> Option<Duration>
How long a PluginErrorCode::RateLimited error asks the caller to
wait, when the backend said (details.retryAfterMs).
pub fn payload_too_large(message: impl Into<String>) -> Self
Convenience for PluginErrorCode::PayloadTooLarge.
pub fn deadline_exceeded(message: impl Into<String>) -> Self
Convenience for PluginErrorCode::DeadlineExceeded.
pub fn forbidden(message: impl Into<String>) -> Self
Convenience for PluginErrorCode::Forbidden.
pub fn invalid_cursor(message: impl Into<String>) -> Self
Convenience for PluginErrorCode::InvalidCursor.
pub fn cancelled(message: impl Into<String>) -> Self
Convenience for PluginErrorCode::Cancelled.
pub fn conflict(message: impl Into<String>) -> Self
Convenience for PluginErrorCode::Conflict.
pub fn limit_exceeded(limit: LimitExceeded) -> Self
Builds a PluginErrorCode::LimitExceeded error whose details
carry limit, cap and used and whose message is
LimitExceeded::to_message.
pub fn limit(&self) -> Option<LimitExceeded>
The exceeded limit when this is a PluginErrorCode::LimitExceeded
error.
Reads the structured details first and falls back to the message
text, so an error relayed by a hop that dropped details still
names its limit.
Implements: Clone, Debug, Deserialize<'de>, Display, Eq, Error, From<AiError>, From<NotificationError>, From<QualityOffersError>, From<ScanPageError>, PartialEq, Serialize
pub struct LimitExceeded {
pub limit: String,
pub cap: u64,
pub used: u64,
}
One exceeded negotiated limit: which cap, its value, and the value that exceeded it.
Every emitter (adapter SDK, host reply checks, SDK request checks) formats
the same message through Self::to_message, and every classifier parses
it back through Self::from_message, so a limit error stays typed across
a DbErr string hop.
Fields
limit: Capability field name as advertised (maxResultBytes,maxResultRows,maxRequestBytes, ...).cap: The negotiated cap.used: The observed value that exceededcap.
pub fn new(limit: impl Into<String>, cap: u64, used: u64) -> Self
Builds the record.
pub fn to_message(&self) -> String
Canonical message: limit exceeded: maxResultBytes is 262144; used 300000.
pub fn from_message(message: &str) -> Option<Self>
Parses a message produced by Self::to_message, possibly followed by
further text after a ; or :.
pub fn details(&self) -> Map<String, Value>
The details object: { "limit": ..., "cap": ..., "used": ... }.
pub fn from_details(details: &Map<String, Value>) -> Option<Self>
Reads the record back from a details object; None when any field
is missing or not of the expected type, or when limit is not a
name Self::from_message would accept, so a record read from
details always round-trips through its canonical message.
Implements: Clone, Debug, Display, Eq, PartialEq
pub enum PluginErrorCode {
InvalidParams,
Unauthorized,
Forbidden,
NotFound,
Unavailable,
Unsupported,
Internal,
PayloadTooLarge,
DeadlineExceeded,
InvalidCursor,
Cancelled,
Conflict,
LimitExceeded,
RateLimited,
NetworkNotGranted,
Unknown,
}
Stable error codes for plugin RPC failures (schema PluginError.code).
Serialized with snake_case wire names (invalid_params, not_found, …).
Variants
InvalidParams: Request params failed validation or are missing required fields.Unauthorized: Caller is not authenticated for this method (credentials / token).Forbidden: Caller is authenticated but not allowed to perform this operation.NotFound: Requested account, object key, session, or row does not exist.Unavailable: Backend or dependency is temporarily unreachable (store API, DB, …).Unsupported: Method or capability is not implemented by this guest.Internal: Unexpected guest or host failure; seePluginError::message.PayloadTooLarge: A scalar RPC value exceededcrate::MAX_SCALAR_BYTES.DeadlineExceeded: The invocation deadline elapsed before the call completed.InvalidCursor: List cursor is missing, stale, or not from this backend.Cancelled: The invocation was cancelled (host fence / guest abort).Conflict: The operation conflicts with current state (conditional put, …).LimitExceeded: A negotiated database limit was exceeded;PluginError::limitnames which one.RateLimited: The backend asked the guest to slow down (HTTP 429 or its equivalent);PluginError::retry_aftersays for how long.NetworkNotGranted: The network grant does not cover the destination;detailsnames it (destination) and the network setting that names it (setting), when one does.Unknown: Unrecognized wire code. SeePluginError::wire_str.
pub fn as_str(self) -> &'static str
Returns the canonical wire / schema string for this known code.
pub fn from_wire(code: &str) -> Self
Maps a wire code string onto a known variant, or Self::Unknown.
Implements: Clone, Copy, Debug, Deserialize<'de>, Display, Eq, PartialEq, Serialize
pub type Result<T> = Result<T, PluginError>;
Result alias for ABI operations that fail as PluginError.
Generated from crates/bookclerk-plugin-abi at main · View as Markdown