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}