Skip to main content

blitz_control_protocol/
target.rs

1use schemars::JsonSchema;
2use serde::{Deserialize, Serialize};
3
4use crate::{
5    AgentAction, AgentControlRequest, DebugError, DebugEvent, DebugResponse, DiagnosticsRequest,
6};
7
8#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
9#[serde(untagged)]
10pub enum TargetId {
11    Chrome(Chrome),
12    Tab(u64),
13}
14
15#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
16pub enum Chrome {
17    #[serde(rename = "chrome")]
18    Chrome,
19}
20
21impl TargetId {
22    pub fn chrome() -> Self {
23        Self::Chrome(Chrome::Chrome)
24    }
25}
26
27#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
28#[serde(untagged)]
29pub enum TargetSelector {
30    Chrome(Chrome),
31    Tab {
32        #[serde(rename = "tabId")]
33        tab_id: u64,
34    },
35}
36
37impl TargetSelector {
38    pub fn id(&self) -> TargetId {
39        match self {
40            Self::Chrome(_) => TargetId::chrome(),
41            Self::Tab { tab_id } => TargetId::Tab(*tab_id),
42        }
43    }
44}
45
46#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
47#[serde(rename_all = "camelCase")]
48pub struct TargetOptions {
49    #[serde(default, skip_serializing_if = "Option::is_none")]
50    pub target: Option<TargetSelector>,
51    #[serde(default, skip_serializing_if = "Option::is_none")]
52    pub expected_generation: Option<u64>,
53    #[serde(default, skip_serializing_if = "Option::is_none")]
54    pub expected_document_id: Option<u64>,
55    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
56    pub all_targets: bool,
57    #[serde(default, skip_serializing_if = "Option::is_none")]
58    pub after_sequence: Option<u64>,
59}
60
61#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
62pub struct TargetEnvelope<T> {
63    #[serde(flatten)]
64    pub options: TargetOptions,
65    #[serde(flatten)]
66    pub request: T,
67}
68
69#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
70pub enum TargetCommand {
71    Agent(AgentControlRequest),
72    Diagnostics(DiagnosticsRequest),
73}
74
75#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
76pub struct TargetRequest {
77    pub options: TargetOptions,
78    pub command: TargetCommand,
79}
80
81impl TargetRequest {
82    pub fn uses_nodes(&self) -> bool {
83        match &self.command {
84            TargetCommand::Agent(AgentControlRequest::Inspect { root, .. }) => root.is_some(),
85            TargetCommand::Agent(AgentControlRequest::Act(action)) => {
86                !matches!(action, AgentAction::Input(_))
87            }
88            TargetCommand::Diagnostics(DiagnosticsRequest::Snapshot(request)) => {
89                !request.node_ids.is_empty()
90            }
91            TargetCommand::Diagnostics(DiagnosticsRequest::Capture(request)) => {
92                request.node_id.is_some()
93            }
94            _ => false,
95        }
96    }
97
98    pub fn instance_scoped(&self) -> bool {
99        matches!(
100            &self.command,
101            TargetCommand::Agent(
102                AgentControlRequest::ListTargets
103                    | AgentControlRequest::Quit
104                    | AgentControlRequest::Relaunch
105            ) | TargetCommand::Diagnostics(DiagnosticsRequest::WindowComposition)
106        )
107    }
108
109    pub fn validate_options(&self) -> Result<(), DebugError> {
110        let observing = matches!(
111            &self.command,
112            TargetCommand::Diagnostics(DiagnosticsRequest::Observe { .. })
113        );
114        if (self.options.all_targets || self.options.after_sequence.is_some()) && !observing {
115            return Err(error(
116                "invalidArgument",
117                "allTargets and afterSequence are Observe options",
118            ));
119        }
120        if self.options.all_targets && self.options.target.is_some() {
121            return Err(error(
122                "invalidArgument",
123                "allTargets and target are mutually exclusive",
124            ));
125        }
126        Ok(())
127    }
128}
129
130#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
131#[serde(rename_all = "camelCase")]
132pub struct TargetContext {
133    pub target_id: TargetId,
134    pub generation: u64,
135    pub document_id: u64,
136}
137
138impl TargetContext {
139    pub fn validate(&self, request: &TargetRequest) -> Result<(), DebugError> {
140        if matches!(&self.target_id, TargetId::Tab(_))
141            && request.uses_nodes()
142            && (request.options.expected_generation.is_none()
143                || request.options.expected_document_id.is_none())
144        {
145            return Err(error(
146                "targetIdentityRequired",
147                "tab node IDs require expectedGeneration and expectedDocumentId",
148            ));
149        }
150        if request
151            .options
152            .expected_generation
153            .is_some_and(|value| value != self.generation)
154        {
155            return Err(error(
156                "staleGeneration",
157                "the mounted target generation changed",
158            ));
159        }
160        if request
161            .options
162            .expected_document_id
163            .is_some_and(|value| value != self.document_id)
164        {
165            return Err(error("staleDocument", "the mounted document changed"));
166        }
167        Ok(())
168    }
169}
170
171#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
172#[serde(rename_all = "camelCase")]
173pub struct TargetCapabilities {
174    pub agent: bool,
175    pub diagnostics: bool,
176    pub capture: bool,
177    pub console: bool,
178    pub runtime_errors: bool,
179    pub web_gpu: bool,
180}
181
182#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
183#[serde(rename_all = "camelCase")]
184pub struct TargetInfo {
185    pub id: TargetId,
186    pub url: String,
187    pub title: String,
188    pub active: bool,
189    pub generation: u64,
190    pub document_id: Option<u64>,
191    pub capabilities: TargetCapabilities,
192}
193
194#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
195pub struct TargetReply {
196    pub context: TargetContext,
197    #[serde(flatten)]
198    pub response: Box<DebugResponse>,
199}
200
201impl DebugResponse {
202    pub fn with_context(self, context: TargetContext) -> Self {
203        if matches!(&self, Self::Error(_)) {
204            self
205        } else {
206            Self::Targeted(TargetReply {
207                context,
208                response: Box::new(self),
209            })
210        }
211    }
212
213    pub fn unscoped(&self) -> &Self {
214        match self {
215            Self::Targeted(reply) => reply.response.unscoped(),
216            other => other,
217        }
218    }
219}
220
221#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
222#[serde(rename_all = "camelCase")]
223pub struct DiagnosticRecord {
224    #[serde(flatten)]
225    pub context: TargetContext,
226    pub sequence: u64,
227    #[serde(flatten)]
228    pub event: DebugEvent,
229}
230
231pub fn error(code: &str, message: &str) -> DebugError {
232    DebugError {
233        code: code.into(),
234        message: message.into(),
235    }
236}