eoka-protocol 0.2.1

Protocol and tool catalog definitions for eoka browser automation
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

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
pub struct ErrorDetail {
    pub code: String,
    pub message: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub retryable: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hint: Option<String>,
}

impl ErrorDetail {
    pub fn new(code: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            code: code.into(),
            message: message.into(),
            retryable: None,
            hint: None,
        }
    }

    pub fn retryable(mut self, retryable: bool) -> Self {
        self.retryable = Some(retryable);
        self
    }

    pub fn hint(mut self, hint: impl Into<String>) -> Self {
        self.hint = Some(hint.into());
        self
    }
}

#[derive(Debug, Clone, Default, Serialize, Deserialize, schemars::JsonSchema)]
pub struct ResponseMeta {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub session: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cmd: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub socket: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub log: Option<String>,
}

impl ResponseMeta {
    pub fn is_empty(&self) -> bool {
        self.session.is_none() && self.cmd.is_none() && self.socket.is_none() && self.log.is_none()
    }
}

#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]
pub struct Response {
    pub ok: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub data: Option<serde_json::Value>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error_detail: Option<ErrorDetail>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub meta: Option<ResponseMeta>,
}

impl Response {
    pub fn ok(data: impl Into<serde_json::Value>) -> Self {
        Self {
            ok: true,
            data: Some(data.into()),
            error: None,
            error_detail: None,
            meta: None,
        }
    }

    pub fn ok_text(msg: impl Into<String>) -> Self {
        Self::ok(serde_json::Value::String(msg.into()))
    }

    pub fn err(msg: impl Into<String>) -> Self {
        let msg = msg.into();
        Self {
            ok: false,
            data: None,
            error: Some(msg.clone()),
            error_detail: Some(classify_error(&msg)),
            meta: None,
        }
    }

    pub fn err_detail(detail: ErrorDetail) -> Self {
        Self {
            ok: false,
            data: None,
            error: Some(detail.message.clone()),
            error_detail: Some(detail),
            meta: None,
        }
    }

    pub fn with_meta(mut self, meta: ResponseMeta) -> Self {
        if !meta.is_empty() {
            self.meta = Some(meta);
        }
        self
    }
}

fn classify_error(message: &str) -> ErrorDetail {
    let lower = message.to_ascii_lowercase();
    if lower.contains("no browser open") {
        return ErrorDetail::new("no_browser_open", message)
            .retryable(true)
            .hint("Run eoka open before browser observation or interaction commands.");
    }
    if lower.contains("unknown") || lower.contains("invalid") {
        return ErrorDetail::new("invalid_input", message).retryable(false);
    }
    if lower.contains("daemon failed to start") || lower.contains("transport") {
        return ErrorDetail::new("transport_error", message).retryable(true);
    }
    ErrorDetail::new("eoka_error", message)
}

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

    #[test]
    fn structured_error_keeps_legacy_error_string() {
        let response = Response::err("No browser open. Use 'open' first.");

        assert_eq!(
            response.error.as_deref(),
            Some("No browser open. Use 'open' first.")
        );
        let detail = response.error_detail.unwrap();
        assert_eq!(detail.code, "no_browser_open");
        assert_eq!(detail.retryable, Some(true));
        assert!(detail.hint.unwrap().contains("eoka open"));
    }

    #[test]
    fn empty_meta_is_not_serialized() {
        let value =
            serde_json::to_value(Response::ok("ok").with_meta(ResponseMeta::default())).unwrap();

        assert!(value.get("meta").is_none());
    }
}