plexus-client 0.9.0

wasm-safe client runtime for Plexus RPC: the wire envelope, the Transport trait, and typed event decoding
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
//! The typed, exhaustive vocabulary of call failures.
//!
//! A call fails — as opposed to an activation saying no, which is an `err`
//! item and therefore data — when the service could not or would not run it:
//! no such activation or method, bad params, no credentials, not allowed,
//! or the method itself blew up. The error frame carries exactly one
//! [`RemoteError`], and so does the `data` of a JSON-RPC-level rejection.
//!
//! # Wire shape
//!
//! `kind`-tagged, `snake_case`. [`ParamProblem`] and [`DenyReason`] are
//! flattened into their variant, each under the key its field is named for:
//!
//! ```json
//! {"kind": "activation_not_found", "activation": "tickets"}
//! {"kind": "method_not_found", "activation": "tickets", "method": "frob"}
//! {"kind": "invalid_params", "param": "id", "problem": "missing"}
//! {"kind": "invalid_params", "param": "id", "problem": "malformed", "detail": "expected a string"}
//! {"kind": "unauthenticated"}
//! {"kind": "forbidden", "reason": "missing_scope", "scope": "tickets:write"}
//! {"kind": "forbidden", "reason": "tenant_boundary"}
//! {"kind": "handle_not_supported", "activation": "tickets"}
//! {"kind": "execution", "message": "database is locked"}
//! {"kind": "forbidden", "reason": "missing_grant", "grant": "tickets.create", "scope": "*", "roles": ["editor", "admin"], "held_on": []}
//! {"kind": "too_many_calls", "max": 8}
//! {"kind": "child_unavailable", "child": "echo", "reason": "the connection has closed"}
//! {"kind": "child_timeout", "child": "echo", "timeout_ms": 5000}
//! ```
//!
//! The last four are main's refusals (AUTH-2's typed refusal, spec/05's
//! `too_many_calls`, spec/12's `child_unavailable` and `child_timeout`),
//! brought into this vocabulary by RETURNS-36: every error frame a server
//! sends carries one `RemoteError`, beside spec/05's flattened
//! `code` / `message` / `error_kind` fields.
//!
//! `param` is omitted when the failure is not about one parameter (and
//! decodes as `None` when absent or `null`).
//!
//! # Open, typed
//!
//! A kind this build does not know — menger's `too_many_connections`, or
//! `too_many_writes` with `retry_after_ms` — is [`RemoteError::Other`]: its
//! `kind` and every other field kept, and written back exactly as it came
//! (RETURNS-36, review #4). A known kind that does not fit its variant is
//! still a decode error. The known variants stay exhaustive for a match;
//! adding one means adding its `PlexusError` conversion in plexus-core and
//! its mirrors in the Haskell protocol and the TS/Rust generators.

use std::fmt::{self, Write as _};

use serde::{Deserialize, Serialize};

/// Why a call failed — what an error frame carries, and the `data` of a
/// JSON-RPC-level rejection.
///
/// Its JSON Schema is written by hand (see the `JsonSchema` impl): the known
/// kinds as one `kind`-tagged union, `KnownRemoteError`, and any other kind
/// as [`OtherError`] — the two as an untagged union of references, a form
/// synapse's IR reader takes (RETURNS-40), the wire unchanged.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum RemoteError {
    /// The service has no activation by this name.
    ActivationNotFound { activation: String },

    /// The activation exists but has no method by this name.
    MethodNotFound { activation: String, method: String },

    /// The call's params did not fit the method.
    InvalidParams {
        /// The parameter at fault, when the failure is about one.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        param: Option<String>,
        /// What is wrong with it. Flattened: its `problem` tag sits beside
        /// `param` on the wire.
        #[serde(flatten)]
        problem: ParamProblem,
    },

    /// The method requires credentials and the call carried none that
    /// verified.
    Unauthenticated,

    /// The caller is authenticated but not allowed this call.
    Forbidden {
        /// Which check the caller failed. Flattened: its `reason` tag sits
        /// beside `kind` on the wire.
        #[serde(flatten)]
        reason: DenyReason,
    },

    /// The activation does not resolve handles.
    HandleNotSupported { activation: String },

    /// The method ran and failed for a reason that is not the activation
    /// saying no (that is an `err` item): a panic, a lost dependency.
    Execution { message: String },

    /// spec/05, 09: the connection — or the child the call was routed to —
    /// holds its maximum of open calls; close one and call again.
    TooManyCalls {
        /// The most calls it holds open at once.
        max: u64,
        /// The child whose limit it is, when the limit is a child's.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        child: Option<String>,
    },

    /// spec/12 rule 5: the child the call was routed to is not there.
    ChildUnavailable { child: String, reason: String },

    /// The child the call was routed to did not open it in the service's
    /// time.
    ChildTimeout { child: String, timeout_ms: u64 },

    /// A kind this build does not know, kept whole: its `kind` and every
    /// other field (RETURNS-36), written back as it came. Read only for a
    /// kind no known variant has (see the `Deserialize` impl).
    #[serde(untagged)]
    Other(OtherError),
}

/// [`RemoteError::Other`]'s content: a kind this build does not know and
/// its other fields, exactly as they came.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct OtherError {
    /// The kind, as the server spelled it (`"too_many_writes"`).
    pub kind: String,
    /// Every other field (`retry_after_ms`, `message`, …).
    #[serde(flatten)]
    pub fields: serde_json::Map<String, serde_json::Value>,
}

/// The kinds the known variants take: one of them that does not fit its
/// variant is a decode error, never [`RemoteError::Other`].
const KNOWN_KINDS: &[&str] = &[
    "activation_not_found",
    "method_not_found",
    "invalid_params",
    "unauthenticated",
    "forbidden",
    "handle_not_supported",
    "execution",
    "too_many_calls",
    "child_unavailable",
    "child_timeout",
];

impl<'de> Deserialize<'de> for OtherError {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let mut fields = serde_json::Map::<String, serde_json::Value>::deserialize(d)?;
        let kind = match fields.remove("kind") {
            Some(serde_json::Value::String(k)) => k,
            _ => return Err(serde::de::Error::missing_field("kind")),
        };
        if KNOWN_KINDS.contains(&kind.as_str()) {
            return Err(serde::de::Error::custom(format!("a `{kind}` error that does not fit its fields")));
        }
        Ok(OtherError { kind, fields })
    }
}

/// The known variants, as the wire reads them — the derive the public enum
/// cannot have, since an unknown kind must read as [`RemoteError::Other`]
/// while a known kind that does not fit stays a decode error naming why.
///
/// Its schema is [`RemoteError`]'s known half, `KnownRemoteError`: a
/// `kind`-tagged union every member of which gives `kind` a const.
#[derive(Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(
    feature = "schema",
    schemars(rename = "KnownRemoteError", description = "A call failure of a kind this vocabulary knows.")
)]
#[serde(tag = "kind", rename_all = "snake_case")]
enum Known {
    /// The service has no activation by this name.
    ActivationNotFound { activation: String },
    /// The activation exists but has no method by this name.
    MethodNotFound { activation: String, method: String },
    /// The call's params did not fit the method.
    InvalidParams {
        /// The parameter at fault, when the failure is about one.
        #[serde(default)]
        param: Option<String>,
        /// What is wrong with it. Flattened: its `problem` tag sits beside
        /// `param` on the wire.
        #[serde(flatten)]
        problem: ParamProblem,
    },
    /// The method requires credentials and the call carried none that
    /// verified.
    Unauthenticated,
    /// The caller is authenticated but not allowed this call.
    Forbidden {
        /// Which check the caller failed. Flattened: its `reason` tag sits
        /// beside `kind` on the wire.
        #[serde(flatten)]
        reason: DenyReason,
    },
    /// The activation does not resolve handles.
    HandleNotSupported { activation: String },
    /// The method ran and failed for a reason that is not the activation
    /// saying no (that is an `err` item): a panic, a lost dependency.
    Execution { message: String },
    /// spec/05, 09: the connection — or the child the call was routed to —
    /// holds its maximum of open calls; close one and call again.
    TooManyCalls {
        /// The most calls it holds open at once.
        max: u64,
        /// The child whose limit it is, when the limit is a child's.
        #[serde(default)]
        child: Option<String>,
    },
    /// spec/12 rule 5: the child the call was routed to is not there.
    ChildUnavailable { child: String, reason: String },
    /// The child the call was routed to did not open it in the service's
    /// time.
    ChildTimeout { child: String, timeout_ms: u64 },
}

impl From<Known> for RemoteError {
    fn from(k: Known) -> Self {
        match k {
            Known::ActivationNotFound { activation } => RemoteError::ActivationNotFound { activation },
            Known::MethodNotFound { activation, method } => RemoteError::MethodNotFound { activation, method },
            Known::InvalidParams { param, problem } => RemoteError::InvalidParams { param, problem },
            Known::Unauthenticated => RemoteError::Unauthenticated,
            Known::Forbidden { reason } => RemoteError::Forbidden { reason },
            Known::HandleNotSupported { activation } => RemoteError::HandleNotSupported { activation },
            Known::Execution { message } => RemoteError::Execution { message },
            Known::TooManyCalls { max, child } => RemoteError::TooManyCalls { max, child },
            Known::ChildUnavailable { child, reason } => RemoteError::ChildUnavailable { child, reason },
            Known::ChildTimeout { child, timeout_ms } => RemoteError::ChildTimeout { child, timeout_ms },
        }
    }
}

impl<'de> Deserialize<'de> for RemoteError {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        use serde::de::Error as _;
        let v = serde_json::Value::deserialize(d)?;
        let known = match v.get("kind") {
            Some(serde_json::Value::String(k)) => KNOWN_KINDS.contains(&k.as_str()),
            _ => return Err(D::Error::missing_field("kind")),
        };
        if known {
            Known::deserialize(v).map(RemoteError::from).map_err(D::Error::custom)
        } else {
            OtherError::deserialize(v).map(RemoteError::Other).map_err(D::Error::custom)
        }
    }
}

impl std::hash::Hash for OtherError {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        self.kind.hash(state);
        serde_json::to_string(&self.fields).unwrap_or_default().hash(state);
    }
}

#[cfg(feature = "schema")]
impl schemars::JsonSchema for OtherError {
    fn schema_name() -> std::borrow::Cow<'static, str> {
        "OtherError".into()
    }

    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
        // No `additionalProperties`: JSON Schema's default lets the other
        // fields through, and synapse's IR reader has no form for a map
        // beside properties (RETURNS-40) — so it reads as a struct of `kind`.
        schemars::json_schema!({
            "description": "A kind this build does not know: its `kind`, and any other fields beside it, kept as they came.",
            "type": "object",
            "properties": { "kind": { "type": "string" } },
            "required": ["kind"]
        })
    }
}

/// The known kinds (`KnownRemoteError`) or any other ([`OtherError`]), as an
/// untagged union of the two references — what synapse's IR reader takes
/// for an open union (RETURNS-40); a tagged union cannot hold a member whose
/// `kind` is no const. The wire is [`RemoteError`]'s serde, unchanged.
#[cfg(feature = "schema")]
impl schemars::JsonSchema for RemoteError {
    fn schema_name() -> std::borrow::Cow<'static, str> {
        "RemoteError".into()
    }

    fn schema_id() -> std::borrow::Cow<'static, str> {
        concat!(module_path!(), "::RemoteError").into()
    }

    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
        let known = generator.subschema_for::<Known>();
        let other = generator.subschema_for::<OtherError>();
        schemars::json_schema!({
            "description": "Why a call failed — what an error frame carries, and the `data` of a JSON-RPC-level rejection: a kind this vocabulary knows, or another kept whole.",
            "anyOf": [known, other]
        })
    }
}

/// What is wrong with a call's params. Flattened into
/// [`RemoteError::InvalidParams`] under the `problem` key.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(tag = "problem", rename_all = "snake_case")]
pub enum ParamProblem {
    /// A required parameter was not supplied.
    Missing,
    /// A parameter was supplied but did not decode; `detail` says how.
    Malformed { detail: String },
}

/// Why an authenticated caller was refused. Flattened into
/// [`RemoteError::Forbidden`] under the `reason` key.
///
/// Each variant carries at most the single fact the caller already failed
/// (AUTHZ-CORE-1/5, rendered per AUTHZ-PRIVACY-4): the first unmet scope,
/// never the method's full requirement set or the registry's taxonomy.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(tag = "reason", rename_all = "snake_case")]
pub enum DenyReason {
    /// The caller's scopes do not include `scope` — the first unmet one.
    MissingScope { scope: String },
    /// The call reaches across the caller's tenant boundary.
    TenantBoundary,
    /// The call was not accepted in the caller's action context.
    NotAccepted,
    /// AUTH-2: the grant gate's refusal — the caller does not hold `grant`
    /// on `scope`. Names what was needed and where the caller does hold it
    /// (owner, 2026-10-10: "return the grants required to hit an
    /// endpoint").
    MissingGrant {
        /// The method's grant, `<activation>.<method>`.
        grant: String,
        /// Where it was needed: the target's innermost scope, or `*`.
        scope: String,
        /// The roles that list the grant, `admin` last.
        #[serde(default)]
        roles: Vec<String>,
        /// Where the caller holds it.
        #[serde(default)]
        held_on: Vec<String>,
    },
}

impl RemoteError {
    /// The variant's `kind` tag, as on the wire (`"method_not_found"`, …) —
    /// for a log line or an exit code; match on the variant to handle it.
    pub fn kind(&self) -> &str {
        match self {
            RemoteError::Other(other) => &other.kind,
            RemoteError::ActivationNotFound { .. } => "activation_not_found",
            RemoteError::MethodNotFound { .. } => "method_not_found",
            RemoteError::InvalidParams { .. } => "invalid_params",
            RemoteError::Unauthenticated => "unauthenticated",
            RemoteError::Forbidden { .. } => "forbidden",
            RemoteError::HandleNotSupported { .. } => "handle_not_supported",
            RemoteError::Execution { .. } => "execution",
            RemoteError::TooManyCalls { .. } => "too_many_calls",
            RemoteError::ChildUnavailable { .. } => "child_unavailable",
            RemoteError::ChildTimeout { .. } => "child_timeout",
        }
    }
}

/// Writes `s` with every line break folded to a space, so the line a CLI
/// prints stays one line whatever the server put in a free-text field.
fn one_line(f: &mut fmt::Formatter<'_>, s: &str) -> fmt::Result {
    for c in s.chars() {
        f.write_char(if matches!(c, '\n' | '\r') { ' ' } else { c })?;
    }
    Ok(())
}

impl fmt::Display for RemoteError {
    /// One line, for a human — what a CLI prints.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            RemoteError::ActivationNotFound { activation } => {
                f.write_str("activation not found: ")?;
                one_line(f, activation)
            }
            RemoteError::MethodNotFound { activation, method } => {
                f.write_str("method not found: ")?;
                one_line(f, activation)?;
                f.write_char('.')?;
                one_line(f, method)
            }
            RemoteError::InvalidParams { param, problem } => {
                f.write_str("invalid params: ")?;
                match (problem, param) {
                    (ParamProblem::Missing, Some(p)) => {
                        f.write_str("missing `")?;
                        one_line(f, p)?;
                        f.write_char('`')
                    }
                    (ParamProblem::Missing, None) => f.write_str("a required parameter is missing"),
                    (ParamProblem::Malformed { detail }, Some(p)) => {
                        f.write_str("malformed `")?;
                        one_line(f, p)?;
                        f.write_str("`: ")?;
                        one_line(f, detail)
                    }
                    (ParamProblem::Malformed { detail }, None) => {
                        f.write_str("malformed: ")?;
                        one_line(f, detail)
                    }
                }
            }
            RemoteError::Unauthenticated => f.write_str("unauthenticated: credentials required"),
            RemoteError::Forbidden { reason } => {
                f.write_str("forbidden: ")?;
                match reason {
                    DenyReason::MissingScope { scope } => {
                        f.write_str("missing required scope `")?;
                        one_line(f, scope)?;
                        f.write_char('`')
                    }
                    DenyReason::TenantBoundary => f.write_str("tenant boundary"),
                    DenyReason::NotAccepted => f.write_str("call not accepted"),
                    DenyReason::MissingGrant { grant, scope, .. } => {
                        f.write_str("needs `")?;
                        one_line(f, grant)?;
                        f.write_char('`')?;
                        if scope != "*" {
                            f.write_str(" on `")?;
                            one_line(f, scope)?;
                            f.write_char('`')?;
                        }
                        Ok(())
                    }
                }
            }
            RemoteError::HandleNotSupported { activation } => {
                f.write_str("handle resolution not supported by activation: ")?;
                one_line(f, activation)
            }
            RemoteError::Execution { message } => {
                f.write_str("execution failed: ")?;
                one_line(f, message)
            }
            RemoteError::TooManyCalls { max, child } => {
                f.write_str("too many calls open")?;
                if let Some(child) = child {
                    f.write_str(" on child ")?;
                    one_line(f, child)?;
                }
                write!(f, " (at most {max}): close one, or call again later")
            }
            RemoteError::ChildUnavailable { child, reason } => {
                f.write_str("child ")?;
                one_line(f, child)?;
                f.write_str(" is unavailable: ")?;
                one_line(f, reason)
            }
            RemoteError::ChildTimeout { child, timeout_ms } => {
                f.write_str("child ")?;
                one_line(f, child)?;
                write!(f, " did not open the call in {timeout_ms} ms")
            }
            RemoteError::Other(other) => {
                one_line(f, &other.kind)?;
                if let Some(message) = other.fields.get("message").and_then(|m| m.as_str()) {
                    f.write_str(": ")?;
                    one_line(f, message)?;
                }
                Ok(())
            }
        }
    }
}

impl std::error::Error for RemoteError {}