Skip to main content

subc_control/
app_open.rs

1//! Wire shapes for `app.open`, which asks the daemon to start a known operator
2//! app from its installed location. They are standalone bodies, kept out of
3//! the exhaustive control enums so adding them changes no existing match.
4//!
5//! The daemon answers with an [`AppOpenReply`] or an error frame carrying one
6//! of the codes below. It checks, in order: whether the platform uses
7//! `app.open` at all ([`APP_OPEN_NOT_USED`]), whether it is switched on
8//! ([`APP_OPEN_DISABLED`]), whether the app is known ([`APP_UNKNOWN`]),
9//! whether the app is already running (an `already_running` reply), whether it
10//! is installed ([`APP_NOT_INSTALLED`]), and whether the installed binary
11//! passes verification ([`APP_VERIFICATION_FAILED`]).
12
13use serde::{Deserialize, Serialize};
14
15/// Refusal code on a platform that never launches apps through the daemon.
16pub const APP_OPEN_NOT_USED: &str = "app_open_not_used";
17/// Refusal code when the platform supports `app.open` but this daemon build
18/// has it switched off.
19pub const APP_OPEN_DISABLED: &str = "app_open_disabled";
20/// Refusal code for an app id the daemon does not know.
21pub const APP_UNKNOWN: &str = "app_unknown";
22/// Refusal code for a known app that is not installed where the daemon looks.
23pub const APP_NOT_INSTALLED: &str = "app_not_installed";
24/// Refusal code for an installed binary that failed the daemon's checks. No
25/// process was started.
26pub const APP_VERIFICATION_FAILED: &str = "app_verification_failed";
27
28/// Every `app.open` refusal code, in the order the daemon checks them.
29pub const APP_OPEN_ERROR_CODES: [&str; 5] = [
30    APP_OPEN_NOT_USED,
31    APP_OPEN_DISABLED,
32    APP_UNKNOWN,
33    APP_NOT_INSTALLED,
34    APP_VERIFICATION_FAILED,
35];
36
37/// Ask the daemon to start the operator app named `app`.
38///
39/// Starting the app grants nothing by itself.
40#[non_exhaustive]
41#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
42pub struct AppOpenRequest {
43    op: AppOpenOp,
44    /// The app's identifier in the daemon's compiled app table.
45    pub app: String,
46}
47
48impl AppOpenRequest {
49    pub fn new(app: impl Into<String>) -> Self {
50        Self {
51            op: AppOpenOp::Open,
52            app: app.into(),
53        }
54    }
55}
56
57open_string_enum! {
58    /// What an `app.open` call did.
59    AppOpenStatus {
60        /// The daemon started a new process.
61        Launched => "launched",
62        /// A process the daemon started earlier is still running. The daemon
63        /// started nothing and did not bring the app to the foreground.
64        AlreadyRunning => "already_running",
65    }
66}
67
68/// A successful `app.open` reply.
69#[non_exhaustive]
70#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
71pub struct AppOpenReply {
72    op: AppOpenOp,
73    pub status: AppOpenStatus,
74    /// The process id of the started or still-running app.
75    pub pid: u32,
76}
77
78impl AppOpenReply {
79    /// The daemon started a new process with this pid.
80    pub fn launched(pid: u32) -> Self {
81        Self {
82            op: AppOpenOp::Open,
83            status: AppOpenStatus::Launched,
84            pid,
85        }
86    }
87
88    /// The process the daemon started earlier, with this pid, is still running.
89    pub fn already_running(pid: u32) -> Self {
90        Self {
91            op: AppOpenOp::Open,
92            status: AppOpenStatus::AlreadyRunning,
93            pid,
94        }
95    }
96}
97
98// A required, single-valued field both emits the op and refuses a missing or
99// different op when decoding, without exposing a caller-editable tag.
100#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
101enum AppOpenOp {
102    #[serde(rename = "app.open")]
103    Open,
104}
105
106#[cfg(test)]
107mod tests {
108    use super::*;
109
110    #[test]
111    fn app_open_bodies_require_the_op() {
112        assert!(serde_json::from_value::<AppOpenRequest>(serde_json::json!({"app": "a"})).is_err());
113        assert!(serde_json::from_value::<AppOpenRequest>(
114            serde_json::json!({"op": "route.open", "app": "a"})
115        )
116        .is_err());
117        assert!(serde_json::from_value::<AppOpenReply>(
118            serde_json::json!({"status": "launched", "pid": 1})
119        )
120        .is_err());
121    }
122
123    #[test]
124    fn an_app_open_status_from_a_newer_daemon_round_trips_as_unknown() {
125        let wire = r#"{"op":"app.open","status":"focused","pid":7}"#;
126        let reply: AppOpenReply = serde_json::from_str(wire).unwrap();
127        assert_eq!(reply.status, AppOpenStatus::Unknown("focused".to_string()));
128        assert_eq!(serde_json::to_string(&reply).unwrap(), wire);
129    }
130}