sloop/
protocol.rs

1use std::fmt;
2
3use serde::{Deserialize, Serialize};
4use serde_json::{Value, json};
5
6pub const PROTOCOL_VERSION: u32 = 1;
7
8#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
9#[serde(transparent)]
10pub struct RequestId(String);
11
12impl RequestId {
13    pub fn new(value: impl Into<String>) -> Self {
14        Self(value.into())
15    }
16
17    pub fn as_str(&self) -> &str {
18        &self.0
19    }
20}
21
22#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
23pub struct RequestEnvelope {
24    pub v: u32,
25    pub id: RequestId,
26    #[serde(flatten)]
27    pub request: Request,
28    pub token: Option<String>,
29}
30
31impl RequestEnvelope {
32    pub fn new(id: RequestId, request: Request, token: Option<String>) -> Self {
33        Self {
34            v: PROTOCOL_VERSION,
35            id,
36            request,
37            token,
38        }
39    }
40
41    pub fn decode(line: &str) -> Result<Self, ProtocolError> {
42        let value: Value = serde_json::from_str(line)
43            .map_err(|error| ProtocolError::invalid_request(format!("malformed JSON: {error}")))?;
44        let object = value
45            .as_object()
46            .ok_or_else(|| ProtocolError::invalid_request("request must be a JSON object"))?;
47
48        let version = object.get("v").and_then(Value::as_u64).ok_or_else(|| {
49            ProtocolError::invalid_request("request field `v` must be an integer")
50        })?;
51        if version != u64::from(PROTOCOL_VERSION) {
52            return Err(ProtocolError::new(
53                ErrorCode::UnsupportedVersion,
54                format!("unsupported protocol version {version}"),
55                json!({"supported": [PROTOCOL_VERSION], "received": version}),
56            ));
57        }
58
59        let verb = object.get("verb").and_then(Value::as_str).ok_or_else(|| {
60            ProtocolError::invalid_request("request field `verb` must be a string")
61        })?;
62        if !Request::is_known_verb(verb) {
63            return Err(ProtocolError::new(
64                ErrorCode::UnknownVerb,
65                format!("unknown verb `{verb}`"),
66                json!({"verb": verb}),
67            ));
68        }
69
70        serde_json::from_value(value).map_err(|error| {
71            ProtocolError::invalid_request(format!("invalid request envelope: {error}"))
72        })
73    }
74
75    pub fn encode(&self) -> Result<String, serde_json::Error> {
76        serde_json::to_string(self)
77    }
78}
79
80#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
81#[serde(tag = "verb", content = "args", rename_all = "snake_case")]
82pub enum Request {
83    Init(EmptyArgs),
84    Daemon(EmptyArgs),
85    Restart(EmptyArgs),
86    Post(PostArgs),
87    Run(RunArgs),
88    Retry(TicketReferenceArgs),
89    Hold(TicketReferenceArgs),
90    Ready(TicketReferenceArgs),
91    List(EmptyArgs),
92    Status(EmptyArgs),
93    Pause(EmptyArgs),
94    Resume(EmptyArgs),
95    Stop(StopArgs),
96    Cancel(RunReferenceArgs),
97    Logs(RunReferenceArgs),
98    Wait(RunReferenceArgs),
99    Events(EventsArgs),
100    Reindex(EmptyArgs),
101    Brief(EmptyArgs),
102    Show(ShowArgs),
103    Note(NoteArgs),
104    Verdict(VerdictArgs),
105}
106
107impl Request {
108    pub fn verb(&self) -> &'static str {
109        match self {
110            Self::Init(_) => "init",
111            Self::Daemon(_) => "daemon",
112            Self::Restart(_) => "restart",
113            Self::Post(_) => "post",
114            Self::Run(_) => "run",
115            Self::Retry(_) => "retry",
116            Self::Hold(_) => "hold",
117            Self::Ready(_) => "ready",
118            Self::List(_) => "list",
119            Self::Status(_) => "status",
120            Self::Pause(_) => "pause",
121            Self::Resume(_) => "resume",
122            Self::Stop(_) => "stop",
123            Self::Cancel(_) => "cancel",
124            Self::Logs(_) => "logs",
125            Self::Wait(_) => "wait",
126            Self::Events(_) => "events",
127            Self::Reindex(_) => "reindex",
128            Self::Brief(_) => "brief",
129            Self::Show(_) => "show",
130            Self::Note(_) => "note",
131            Self::Verdict(_) => "verdict",
132        }
133    }
134
135    pub fn capability(&self) -> Capability {
136        match self {
137            Self::Brief(_) | Self::Note(_) | Self::Verdict(_) => Capability::Worker,
138            Self::Show(_) => Capability::Both,
139            _ => Capability::Operator,
140        }
141    }
142
143    fn is_known_verb(verb: &str) -> bool {
144        matches!(
145            verb,
146            "init"
147                | "daemon"
148                | "restart"
149                | "post"
150                | "run"
151                | "retry"
152                | "hold"
153                | "ready"
154                | "list"
155                | "status"
156                | "pause"
157                | "resume"
158                | "stop"
159                | "cancel"
160                | "logs"
161                | "wait"
162                | "events"
163                | "reindex"
164                | "brief"
165                | "show"
166                | "note"
167                | "verdict"
168        )
169    }
170}
171
172#[derive(Debug, Clone, Copy, PartialEq, Eq)]
173pub enum Capability {
174    Operator,
175    Worker,
176    Both,
177}
178
179#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
180#[serde(deny_unknown_fields)]
181pub struct EmptyArgs {}
182
183#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
184#[serde(deny_unknown_fields)]
185pub struct PostArgs {
186    pub file: String,
187    #[serde(default, skip_serializing_if = "Option::is_none")]
188    pub project: Option<String>,
189    #[serde(default, skip_serializing_if = "Option::is_none")]
190    pub flow: Option<String>,
191    pub activation: PostActivation,
192}
193
194#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
195#[serde(tag = "kind", rename_all = "snake_case")]
196pub enum PostActivation {
197    Auto,
198    At { time: String },
199    Manual,
200    Hold,
201}
202
203#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
204#[serde(deny_unknown_fields)]
205pub struct RunArgs {
206    #[serde(default, skip_serializing_if = "Option::is_none")]
207    pub ticket: Option<String>,
208    #[serde(default, skip_serializing_if = "Option::is_none")]
209    pub project: Option<String>,
210    pub activation: RunActivation,
211    pub only: Vec<String>,
212}
213
214#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
215#[serde(tag = "kind", rename_all = "snake_case")]
216pub enum RunActivation {
217    Now,
218    At { local_time: String },
219    Every { interval_ms: u64 },
220    Overnight,
221}
222
223#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
224#[serde(deny_unknown_fields)]
225pub struct StopArgs {
226    #[serde(default)]
227    pub force: bool,
228}
229
230#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
231#[serde(deny_unknown_fields)]
232pub struct RunReferenceArgs {
233    pub run: String,
234}
235
236/// A cursor-paginated read of the activity feed. `after` resumes from a
237/// previously returned cursor; `tail` starts that many events before the
238/// newest one and wins when both are given. One page per request — clients
239/// stream by polling with the returned cursor.
240#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
241#[serde(deny_unknown_fields)]
242pub struct EventsArgs {
243    #[serde(default, skip_serializing_if = "Option::is_none")]
244    pub after: Option<i64>,
245    #[serde(default, skip_serializing_if = "Option::is_none")]
246    pub tail: Option<u32>,
247    #[serde(default, skip_serializing_if = "Option::is_none")]
248    pub limit: Option<u32>,
249}
250
251#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
252#[serde(deny_unknown_fields)]
253pub struct TicketReferenceArgs {
254    pub ticket: String,
255}
256
257#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
258#[serde(deny_unknown_fields)]
259pub struct ShowArgs {
260    #[serde(rename = "ref")]
261    pub reference: String,
262}
263
264#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
265#[serde(deny_unknown_fields)]
266pub struct NoteArgs {
267    pub text: String,
268}
269
270#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
271#[serde(deny_unknown_fields)]
272pub struct VerdictArgs {
273    pub verdict: VerdictValue,
274    #[serde(default, skip_serializing_if = "Option::is_none")]
275    pub reason: Option<String>,
276}
277
278#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
279#[serde(rename_all = "snake_case")]
280pub enum VerdictValue {
281    Pass,
282    Fail,
283}
284
285#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
286#[serde(rename_all = "snake_case")]
287pub enum ErrorCode {
288    InvalidArguments,
289    InvalidRequest,
290    UnsupportedVersion,
291    UnknownVerb,
292    DaemonUnavailable,
293    Unauthorized,
294    NotFound,
295    Conflict,
296    CooldownActive,
297    Internal,
298}
299
300#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
301pub struct ErrorBody {
302    pub code: ErrorCode,
303    pub message: String,
304    pub details: Value,
305}
306
307#[derive(Debug, Clone, PartialEq)]
308pub struct ProtocolError {
309    pub body: ErrorBody,
310}
311
312impl ProtocolError {
313    pub fn new(code: ErrorCode, message: impl Into<String>, details: Value) -> Self {
314        Self {
315            body: ErrorBody {
316                code,
317                message: message.into(),
318                details,
319            },
320        }
321    }
322
323    fn invalid_request(message: impl Into<String>) -> Self {
324        Self::new(ErrorCode::InvalidRequest, message, json!({}))
325    }
326}
327
328impl fmt::Display for ProtocolError {
329    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
330        formatter.write_str(&self.body.message)
331    }
332}
333
334impl std::error::Error for ProtocolError {}
335
336#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
337pub struct ResponseEnvelope {
338    pub id: Option<RequestId>,
339    pub ok: bool,
340    #[serde(skip_serializing_if = "Option::is_none")]
341    pub data: Option<Value>,
342    #[serde(skip_serializing_if = "Option::is_none")]
343    pub error: Option<ErrorBody>,
344}
345
346impl ResponseEnvelope {
347    pub fn success(id: Option<RequestId>, data: Value) -> Self {
348        Self {
349            id,
350            ok: true,
351            data: Some(data),
352            error: None,
353        }
354    }
355
356    pub fn failure(id: Option<RequestId>, error: ErrorBody) -> Self {
357        Self {
358            id,
359            ok: false,
360            data: None,
361            error: Some(error),
362        }
363    }
364}
365
366#[cfg(test)]
367mod tests {
368    use serde_json::{Value, json};
369
370    use super::{
371        EmptyArgs, ErrorBody, ErrorCode, Request, RequestEnvelope, RequestId, ResponseEnvelope,
372        RunActivation, RunArgs,
373    };
374
375    #[test]
376    fn request_envelope_serializes_to_the_public_wire_shape() {
377        let envelope = RequestEnvelope::new(
378            RequestId::new("req-123"),
379            Request::Run(RunArgs {
380                ticket: Some("T1".into()),
381                project: None,
382                activation: RunActivation::Now,
383                only: Vec::new(),
384            }),
385            None,
386        );
387
388        let value: Value = serde_json::from_str(&envelope.encode().unwrap()).unwrap();
389        assert_eq!(
390            value,
391            json!({
392                "v": 1,
393                "id": "req-123",
394                "verb": "run",
395                "args": {
396                    "ticket": "T1",
397                    "activation": {"kind": "now"},
398                    "only": []
399                },
400                "token": null
401            })
402        );
403    }
404
405    #[test]
406    fn request_envelope_round_trips() {
407        let expected = RequestEnvelope::new(
408            RequestId::new("req-1"),
409            Request::Brief(EmptyArgs::default()),
410            Some("worker-token".into()),
411        );
412
413        let decoded = RequestEnvelope::decode(&expected.encode().unwrap()).unwrap();
414        assert_eq!(decoded, expected);
415    }
416
417    #[test]
418    fn restart_is_a_public_operator_verb() {
419        let request = RequestEnvelope::decode(
420            r#"{"v":1,"id":"req-1","verb":"restart","args":{},"token":null}"#,
421        )
422        .unwrap()
423        .request;
424
425        assert!(matches!(request, Request::Restart(_)));
426        assert_eq!(request.capability(), super::Capability::Operator);
427    }
428
429    #[test]
430    fn malformed_json_is_an_invalid_request() {
431        let error = RequestEnvelope::decode("{").unwrap_err();
432        assert_eq!(error.body.code, ErrorCode::InvalidRequest);
433    }
434
435    #[test]
436    fn unsupported_versions_have_a_stable_error_code() {
437        let error = RequestEnvelope::decode(
438            r#"{"v":2,"id":"req-1","verb":"status","args":{},"token":null}"#,
439        )
440        .unwrap_err();
441
442        assert_eq!(error.body.code, ErrorCode::UnsupportedVersion);
443        assert_eq!(error.body.details["received"], 2);
444    }
445
446    #[test]
447    fn unknown_verbs_have_a_stable_error_code() {
448        let error = RequestEnvelope::decode(
449            r#"{"v":1,"id":"req-1","verb":"merge","args":{},"token":null}"#,
450        )
451        .unwrap_err();
452
453        assert_eq!(error.body.code, ErrorCode::UnknownVerb);
454        assert_eq!(error.body.details["verb"], "merge");
455    }
456
457    #[test]
458    fn known_verbs_reject_invalid_arguments() {
459        let error = RequestEnvelope::decode(
460            r#"{"v":1,"id":"req-1","verb":"show","args":{},"token":"token"}"#,
461        )
462        .unwrap_err();
463
464        assert_eq!(error.body.code, ErrorCode::InvalidRequest);
465    }
466
467    #[test]
468    fn response_envelopes_have_exclusive_success_and_error_payloads() {
469        let success = serde_json::to_value(ResponseEnvelope::success(
470            Some(RequestId::new("req-1")),
471            json!({"paused": false}),
472        ))
473        .unwrap();
474        assert_eq!(
475            success,
476            json!({"id": "req-1", "ok": true, "data": {"paused": false}})
477        );
478
479        let failure = serde_json::to_value(ResponseEnvelope::failure(
480            Some(RequestId::new("req-2")),
481            ErrorBody {
482                code: ErrorCode::Conflict,
483                message: "ticket is already claimed".into(),
484                details: json!({"ticket": "T1"}),
485            },
486        ))
487        .unwrap();
488        assert_eq!(
489            failure,
490            json!({
491                "id": "req-2",
492                "ok": false,
493                "error": {
494                    "code": "conflict",
495                    "message": "ticket is already claimed",
496                    "details": {"ticket": "T1"}
497                }
498            })
499        );
500    }
501}
sloop/protocol.rs

sloop/
protocol.rs
