iii-sdk 0.20.0

SDK for III Engine - a platform for building distributed applications
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

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use thiserror::Error;

/// Errors returned by the III SDK.
#[derive(Debug, Error, Clone, Serialize, JsonSchema)]
pub enum Error {
    #[error("iii is not connected")]
    NotConnected,
    #[error("invocation timed out")]
    Timeout,
    #[error("runtime error: {0}")]
    Runtime(String),
    #[error("remote error ({code}): {message}")]
    Remote {
        code: String,
        message: String,
        stacktrace: Option<String>,
    },
    #[error("handler error: {0}")]
    Handler(String),
    #[error("serialization error: {0}")]
    Serde(String),
    #[error("websocket error: {0}")]
    WebSocket(String),
}

impl From<serde_json::Error> for Error {
    fn from(err: serde_json::Error) -> Self {
        Error::Serde(err.to_string())
    }
}

impl From<String> for Error {
    fn from(msg: String) -> Self {
        Error::Handler(msg)
    }
}

impl From<&str> for Error {
    fn from(msg: &str) -> Self {
        Error::Handler(msg.to_string())
    }
}

impl From<tokio_tungstenite::tungstenite::Error> for Error {
    fn from(err: tokio_tungstenite::tungstenite::Error) -> Self {
        Error::WebSocket(err.to_string())
    }
}

/// Structured invocation failure, mirroring the Node and Python `InvocationError`.
///
/// Produced from the [`Error::Remote`] variant via [`Error::invocation_error`].
/// `function_id` is `None` from that accessor because the wire `Remote` payload
/// does not carry it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct InvocationError {
    pub code: String,
    pub message: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub function_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stacktrace: Option<String>,
}

impl std::fmt::Display for InvocationError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}: {}", self.code, self.message)
    }
}

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

impl Error {
    /// If this is a remote invocation failure (`Error::Remote`), return its
    /// structured form. Returns `None` for transport/serde/handler errors.
    pub fn invocation_error(&self) -> Option<InvocationError> {
        match self {
            Error::Remote {
                code,
                message,
                stacktrace,
            } => Some(InvocationError {
                code: code.clone(),
                message: message.clone(),
                function_id: None,
                stacktrace: stacktrace.clone(),
            }),
            _ => None,
        }
    }
}

#[cfg(test)]
mod invocation_error_tests {
    use super::*;

    #[test]
    fn remote_error_yields_invocation_error() {
        let err = Error::Remote {
            code: "FORBIDDEN".into(),
            message: "nope".into(),
            stacktrace: Some("trace".into()),
        };
        let inv = err.invocation_error().expect("remote -> invocation");
        assert_eq!(inv.code, "FORBIDDEN");
        assert_eq!(inv.message, "nope");
        assert_eq!(inv.stacktrace.as_deref(), Some("trace"));
        assert_eq!(inv.to_string(), "FORBIDDEN: nope");
    }

    #[test]
    fn non_remote_error_yields_none() {
        assert!(Error::Timeout.invocation_error().is_none());
    }
}