Skip to main content

glass_dev/
browser.rs

1//! Resident browser and workflow ownership for the Glass development workspace.
2
3use crate::development::{DevelopmentError, DevelopmentResult};
4use glass_browser::browser::policy::BrowserPolicy;
5use glass_browser::browser::session::{
6    BrowserSession, SemanticObservationLevel, SessionOptions, WorkflowCheckpoint,
7    WorkflowDefinition, WorkflowRunResult,
8};
9use serde::{Deserialize, Serialize};
10use serde_json::Value;
11use std::collections::BTreeMap;
12use std::path::{Path, PathBuf};
13use std::sync::mpsc::{self, SyncSender};
14use std::time::Duration;
15
16const COMMAND_QUEUE: usize = 32;
17const COMMAND_TIMEOUT: Duration = Duration::from_secs(180);
18
19#[derive(Debug, Clone, Serialize, Deserialize)]
20#[serde(default, rename_all = "camelCase")]
21pub struct BrowserStartConfig {
22    pub port: u16,
23    pub attach: bool,
24    pub incognito: bool,
25    pub headed: bool,
26    pub profile: String,
27    pub chrome_path: Option<PathBuf>,
28}
29
30impl Default for BrowserStartConfig {
31    fn default() -> Self {
32        Self {
33            port: default_port(),
34            attach: false,
35            incognito: true,
36            headed: false,
37            profile: default_profile(),
38            chrome_path: None,
39        }
40    }
41}
42
43fn default_port() -> u16 {
44    9222
45}
46
47fn default_profile() -> String {
48    "default".into()
49}
50
51#[derive(Debug, Clone, Serialize)]
52#[serde(rename_all = "camelCase")]
53pub struct BrowserRuntimeState {
54    pub connected: bool,
55    pub browser_process_id: Option<u32>,
56    pub browser_revision: Option<u64>,
57    pub workflow_state: String,
58    pub active_workflow: Option<String>,
59}
60
61enum BrowserCommand {
62    Start(BrowserStartConfig),
63    Reconnect,
64    Stop,
65    State,
66    Observe,
67    Snapshot,
68    Semantic(SemanticObservationLevel),
69    Diff,
70    Targets,
71    SelectTarget(String),
72    Navigate {
73        url: String,
74        expected_revision: u64,
75        timeout: Duration,
76    },
77    Click {
78        target: String,
79        expected_revision: u64,
80    },
81    Type {
82        text: String,
83        target: Option<String>,
84        expected_revision: u64,
85    },
86    Scroll {
87        dx: f64,
88        dy: f64,
89        expected_revision: u64,
90    },
91    Screenshot,
92    RunWorkflow {
93        definition: Value,
94        inputs: BTreeMap<String, Value>,
95    },
96    PauseWorkflow,
97    ResumeWorkflow {
98        definition: Value,
99        inputs: BTreeMap<String, Value>,
100        checkpoint: Value,
101    },
102    ListWorkflows,
103    CancelWorkflow,
104    VerifyWorkflow,
105}
106
107type Reply = SyncSender<DevelopmentResult<Value>>;
108
109/// Cloneable command handle for the one authoritative browser worker.
110#[derive(Clone)]
111pub struct BrowserService {
112    commands: SyncSender<(BrowserCommand, Reply)>,
113}
114
115impl BrowserService {
116    pub fn new(root: impl AsRef<Path>) -> DevelopmentResult<Self> {
117        let root = root.as_ref().to_path_buf();
118        let (commands, receiver) = mpsc::sync_channel::<(BrowserCommand, Reply)>(COMMAND_QUEUE);
119        std::thread::Builder::new()
120            .name("glass-browser-workspace".into())
121            .spawn(move || {
122                let runtime = tokio::runtime::Builder::new_current_thread()
123                    .enable_all()
124                    .build();
125                let Ok(runtime) = runtime else {
126                    return;
127                };
128                let mut worker = BrowserWorker::new(root);
129                while let Ok((command, reply)) = receiver.recv() {
130                    let result = runtime.block_on(worker.execute(command));
131                    let _ = reply.send(result);
132                }
133                runtime.block_on(worker.shutdown());
134            })
135            .map_err(|error| DevelopmentError::Process(error.to_string()))?;
136        Ok(Self { commands })
137    }
138
139    fn call(&self, command: BrowserCommand) -> DevelopmentResult<Value> {
140        let (reply, receiver) = mpsc::sync_channel(1);
141        self.commands
142            .send((command, reply))
143            .map_err(|_| DevelopmentError::Process("resident browser worker stopped".into()))?;
144        receiver.recv_timeout(COMMAND_TIMEOUT).map_err(|error| {
145            DevelopmentError::Process(format!("resident browser command timed out: {error}"))
146        })?
147    }
148
149    pub fn start(&self, config: BrowserStartConfig) -> DevelopmentResult<Value> {
150        self.call(BrowserCommand::Start(config))
151    }
152
153    pub fn stop(&self) -> DevelopmentResult<Value> {
154        self.call(BrowserCommand::Stop)
155    }
156
157    pub fn reconnect(&self) -> DevelopmentResult<Value> {
158        self.call(BrowserCommand::Reconnect)
159    }
160
161    pub fn state(&self) -> DevelopmentResult<Value> {
162        self.call(BrowserCommand::State)
163    }
164
165    pub fn observe(&self) -> DevelopmentResult<Value> {
166        self.call(BrowserCommand::Observe)
167    }
168
169    pub fn snapshot(&self) -> DevelopmentResult<Value> {
170        self.call(BrowserCommand::Snapshot)
171    }
172
173    pub fn semantic(&self, level: SemanticObservationLevel) -> DevelopmentResult<Value> {
174        self.call(BrowserCommand::Semantic(level))
175    }
176
177    pub fn diff(&self) -> DevelopmentResult<Value> {
178        self.call(BrowserCommand::Diff)
179    }
180
181    pub fn targets(&self) -> DevelopmentResult<Value> {
182        self.call(BrowserCommand::Targets)
183    }
184
185    pub fn select_target(&self, target: String) -> DevelopmentResult<Value> {
186        self.call(BrowserCommand::SelectTarget(target))
187    }
188
189    pub fn navigate(
190        &self,
191        url: String,
192        expected_revision: u64,
193        timeout: Duration,
194    ) -> DevelopmentResult<Value> {
195        self.call(BrowserCommand::Navigate {
196            url,
197            expected_revision,
198            timeout,
199        })
200    }
201
202    pub fn click(&self, target: String, expected_revision: u64) -> DevelopmentResult<Value> {
203        self.call(BrowserCommand::Click {
204            target,
205            expected_revision,
206        })
207    }
208
209    pub fn type_text(
210        &self,
211        text: String,
212        target: Option<String>,
213        expected_revision: u64,
214    ) -> DevelopmentResult<Value> {
215        self.call(BrowserCommand::Type {
216            text,
217            target,
218            expected_revision,
219        })
220    }
221
222    pub fn scroll(&self, dx: f64, dy: f64, expected_revision: u64) -> DevelopmentResult<Value> {
223        self.call(BrowserCommand::Scroll {
224            dx,
225            dy,
226            expected_revision,
227        })
228    }
229
230    pub fn screenshot(&self) -> DevelopmentResult<Value> {
231        self.call(BrowserCommand::Screenshot)
232    }
233
234    pub fn run_workflow(
235        &self,
236        definition: Value,
237        inputs: BTreeMap<String, Value>,
238    ) -> DevelopmentResult<Value> {
239        self.call(BrowserCommand::RunWorkflow { definition, inputs })
240    }
241
242    pub fn pause_workflow(&self) -> DevelopmentResult<Value> {
243        self.call(BrowserCommand::PauseWorkflow)
244    }
245
246    pub fn resume_workflow(
247        &self,
248        definition: Value,
249        inputs: BTreeMap<String, Value>,
250        checkpoint: Value,
251    ) -> DevelopmentResult<Value> {
252        self.call(BrowserCommand::ResumeWorkflow {
253            definition,
254            inputs,
255            checkpoint,
256        })
257    }
258
259    pub fn list_workflows(&self) -> DevelopmentResult<Value> {
260        self.call(BrowserCommand::ListWorkflows)
261    }
262
263    pub fn cancel_workflow(&self) -> DevelopmentResult<Value> {
264        self.call(BrowserCommand::CancelWorkflow)
265    }
266
267    pub fn verify_workflow(&self) -> DevelopmentResult<Value> {
268        self.call(BrowserCommand::VerifyWorkflow)
269    }
270}
271
272struct BrowserWorker {
273    root: PathBuf,
274    session: Option<BrowserSession>,
275    revision: Option<u64>,
276    workflow_state: String,
277    active_workflow: Option<String>,
278    last_workflow: Option<(WorkflowDefinition, WorkflowRunResult)>,
279    last_config: Option<BrowserStartConfig>,
280}
281
282impl BrowserWorker {
283    fn new(root: PathBuf) -> Self {
284        Self {
285            root,
286            session: None,
287            revision: None,
288            workflow_state: "idle".into(),
289            active_workflow: None,
290            last_workflow: None,
291            last_config: None,
292        }
293    }
294
295    fn state(&self) -> BrowserRuntimeState {
296        BrowserRuntimeState {
297            connected: self.session.is_some(),
298            browser_process_id: self
299                .session
300                .as_ref()
301                .and_then(BrowserSession::owned_chrome_pid),
302            browser_revision: self.revision,
303            workflow_state: self.workflow_state.clone(),
304            active_workflow: self.active_workflow.clone(),
305        }
306    }
307
308    fn session(&self) -> DevelopmentResult<&BrowserSession> {
309        self.session.as_ref().ok_or_else(|| {
310            DevelopmentError::Conflict(
311                "browser is not connected; call glass.browser.start first".into(),
312            )
313        })
314    }
315
316    async fn shutdown(&mut self) {
317        if let Some(session) = self.session.take() {
318            let _ = session.close().await;
319        }
320        self.revision = None;
321        self.workflow_state = "idle".into();
322        self.active_workflow = None;
323        self.last_workflow = None;
324    }
325
326    async fn start_session(&mut self, config: BrowserStartConfig) -> DevelopmentResult<Value> {
327        if self.session.is_some() {
328            return Err(DevelopmentError::Conflict(
329                "browser workspace already has a connected session".into(),
330            ));
331        }
332        let policy = BrowserPolicy::development(&self.root)
333            .map_err(|error| DevelopmentError::Process(error.to_string()))?;
334        let mut builder = SessionOptions::builder()
335            .port(config.port)
336            .attach(config.attach)
337            .incognito(config.incognito)
338            .headed(config.headed)
339            .profile(config.profile.clone())
340            .policy(policy);
341        if let Some(path) = config.chrome_path.clone() {
342            builder = builder.chrome_path(path);
343        }
344        let options = builder
345            .build()
346            .map_err(|error| DevelopmentError::InvalidInput(error.to_string()))?;
347        let session = BrowserSession::start(&options)
348            .await
349            .map_err(|error| DevelopmentError::Process(error.to_string()))?;
350        self.revision = Some(1);
351        self.session = Some(session);
352        self.last_config = Some(config);
353        serde_json::to_value(self.state()).map_err(Into::into)
354    }
355
356    async fn execute(&mut self, command: BrowserCommand) -> DevelopmentResult<Value> {
357        match command {
358            BrowserCommand::Start(config) => self.start_session(config).await,
359            BrowserCommand::Reconnect => {
360                let config = self.last_config.clone().ok_or_else(|| {
361                    DevelopmentError::Conflict(
362                        "browser has no prior connection configuration to reconnect".into(),
363                    )
364                })?;
365                self.shutdown().await;
366                self.start_session(config).await
367            }
368            BrowserCommand::Stop => {
369                self.shutdown().await;
370                serde_json::to_value(self.state()).map_err(Into::into)
371            }
372            BrowserCommand::State => serde_json::to_value(self.state()).map_err(Into::into),
373            BrowserCommand::Observe => {
374                let context = self
375                    .session()?
376                    .observe_fresh()
377                    .await
378                    .map_err(browser_error)?;
379                self.revision = Some(context.consistency.end_revision);
380                serde_json::to_value(context).map_err(Into::into)
381            }
382            BrowserCommand::Snapshot => {
383                let snapshot = self.session()?.snapshot().await.map_err(browser_error)?;
384                serde_json::to_value(snapshot).map_err(Into::into)
385            }
386            BrowserCommand::Semantic(level) => {
387                let observation = self
388                    .session()?
389                    .semantic_observe(level)
390                    .await
391                    .map_err(browser_error)?;
392                serde_json::to_value(observation).map_err(Into::into)
393            }
394            BrowserCommand::Diff => {
395                let delta = self
396                    .session()?
397                    .observe_delta()
398                    .await
399                    .map_err(browser_error)?;
400                self.revision = Some(delta.to_revision);
401                serde_json::to_value(delta).map_err(Into::into)
402            }
403            BrowserCommand::Targets => {
404                let targets = self
405                    .session()?
406                    .list_targets()
407                    .await
408                    .map_err(browser_error)?;
409                serde_json::to_value(targets).map_err(Into::into)
410            }
411            BrowserCommand::SelectTarget(target) => {
412                let selected = self
413                    .session()?
414                    .select_target(&target)
415                    .await
416                    .map_err(browser_error)?;
417                let observation = self
418                    .session()?
419                    .observe_fresh()
420                    .await
421                    .map_err(browser_error)?;
422                self.revision = Some(observation.consistency.end_revision);
423                Ok(serde_json::json!({"target":selected,"observation":observation}))
424            }
425            BrowserCommand::Navigate {
426                url,
427                expected_revision,
428                timeout,
429            } => {
430                let outcome = self
431                    .session()?
432                    .navigate_with_revision(&url, timeout, expected_revision)
433                    .await
434                    .map_err(browser_error)?;
435                let value = serde_json::to_value(outcome)?;
436                self.revision = value.get("currentRevision").and_then(Value::as_u64);
437                Ok(value)
438            }
439            BrowserCommand::Click {
440                target,
441                expected_revision,
442            } => {
443                let outcome = self
444                    .session()?
445                    .click_with_revision(&target, expected_revision)
446                    .await
447                    .map_err(browser_error)?;
448                self.revision = Some(outcome.current_revision);
449                serde_json::to_value(outcome).map_err(Into::into)
450            }
451            BrowserCommand::Type {
452                text,
453                target,
454                expected_revision,
455            } => {
456                let outcome = self
457                    .session()?
458                    .type_text_with_expected_revision(
459                        &text,
460                        target.as_deref(),
461                        Some(expected_revision),
462                    )
463                    .await
464                    .map_err(browser_error)?;
465                self.revision = Some(outcome.current_revision);
466                serde_json::to_value(outcome).map_err(Into::into)
467            }
468            BrowserCommand::Scroll {
469                dx,
470                dy,
471                expected_revision,
472            } => {
473                let outcome = self
474                    .session()?
475                    .scroll_with_revision(dx, dy, Some(expected_revision))
476                    .await
477                    .map_err(browser_error)?;
478                self.revision = Some(outcome.current_revision);
479                serde_json::to_value(outcome).map_err(Into::into)
480            }
481            BrowserCommand::Screenshot => {
482                let png = self
483                    .session()?
484                    .screenshot_png()
485                    .await
486                    .map_err(browser_error)?;
487                Ok(serde_json::json!({
488                    "mimeType":"image/png",
489                    "bytes":png.len(),
490                    "base64":base64::Engine::encode(&base64::engine::general_purpose::STANDARD, png)
491                }))
492            }
493            BrowserCommand::RunWorkflow { definition, inputs } => {
494                let workflow = WorkflowDefinition::from_value(definition)
495                    .map_err(|error| DevelopmentError::InvalidInput(error.to_string()))?;
496                self.workflow_state = "running".into();
497                self.active_workflow = Some(workflow.name.clone());
498                let result = self.session()?.run_workflow(&workflow, &inputs).await;
499                self.workflow_state = if result.is_ok() {
500                    "completed"
501                } else {
502                    "failed"
503                }
504                .into();
505                let result = result.map_err(browser_error)?;
506                self.revision = Some(result.final_revision);
507                self.last_workflow = Some((workflow, result.clone()));
508                serde_json::to_value(result).map_err(Into::into)
509            }
510            BrowserCommand::PauseWorkflow => {
511                let (workflow, result) = self.last_workflow.as_ref().ok_or_else(|| {
512                    DevelopmentError::Conflict(
513                        "no workflow result is available to checkpoint".into(),
514                    )
515                })?;
516                let checkpoint = self
517                    .session()?
518                    .export_workflow_checkpoint(workflow, result)
519                    .await
520                    .map_err(browser_error)?;
521                self.workflow_state = "paused".into();
522                serde_json::to_value(checkpoint).map_err(Into::into)
523            }
524            BrowserCommand::ResumeWorkflow {
525                definition,
526                inputs,
527                checkpoint,
528            } => {
529                let workflow = WorkflowDefinition::from_value(definition)
530                    .map_err(|error| DevelopmentError::InvalidInput(error.to_string()))?;
531                let checkpoint: WorkflowCheckpoint = serde_json::from_value(checkpoint)?;
532                self.workflow_state = "running".into();
533                self.active_workflow = Some(workflow.name.clone());
534                let result = self
535                    .session()?
536                    .resume_workflow(&workflow, &inputs, &checkpoint)
537                    .await;
538                self.workflow_state = if result.is_ok() {
539                    "completed"
540                } else {
541                    "failed"
542                }
543                .into();
544                let result = result.map_err(browser_error)?;
545                self.revision = Some(result.final_revision);
546                self.last_workflow = Some((workflow, result.clone()));
547                serde_json::to_value(result).map_err(Into::into)
548            }
549            BrowserCommand::ListWorkflows => Ok(serde_json::json!({
550                "state":self.workflow_state,
551                "active":self.active_workflow,
552                "last":self.last_workflow.as_ref().map(|(definition, result)| serde_json::json!({
553                    "name":definition.name,
554                    "version":definition.workflow_version,
555                    "result":result
556                }))
557            })),
558            BrowserCommand::CancelWorkflow => {
559                if self.workflow_state == "running" {
560                    return Err(DevelopmentError::Conflict(
561                        "workflow cancellation cannot preempt an in-flight synchronous browser command"
562                            .into(),
563                    ));
564                }
565                let previous = self.workflow_state.clone();
566                self.workflow_state = "cancelled".into();
567                self.active_workflow = None;
568                Ok(serde_json::json!({"cancelled":true,"previousState":previous}))
569            }
570            BrowserCommand::VerifyWorkflow => {
571                let (definition, result) = self.last_workflow.as_ref().ok_or_else(|| {
572                    DevelopmentError::Conflict("no workflow result is available to verify".into())
573                })?;
574                Ok(serde_json::json!({
575                    "verified":self.workflow_state == "completed",
576                    "name":definition.name,
577                    "version":definition.workflow_version,
578                    "finalRevision":result.final_revision,
579                    "result":result
580                }))
581            }
582        }
583    }
584}
585
586fn browser_error(error: Box<dyn std::error::Error>) -> DevelopmentError {
587    DevelopmentError::Process(error.to_string())
588}
589
590#[cfg(test)]
591mod tests {
592    use super::*;
593    use std::io::{Read, Write};
594    use std::net::{TcpListener, TcpStream};
595    use std::sync::Arc;
596    use std::sync::atomic::{AtomicBool, Ordering};
597
598    #[test]
599    fn disconnected_service_reports_authoritative_state() {
600        let service = BrowserService::new(std::env::temp_dir()).unwrap();
601        let state = service.state().unwrap();
602        assert_eq!(state["connected"], false);
603        assert_eq!(state["workflowState"], "idle");
604        let error = service.observe().unwrap_err();
605        assert!(error.to_string().contains("glass.browser.start"));
606    }
607
608    #[test]
609    fn resident_browser_executes_revision_safe_fixture_flow() {
610        if std::env::var("GLASS_E2E").as_deref() != Ok("1") {
611            return;
612        }
613        let chrome_path =
614            std::env::var("GLASS_CHROME_PATH").expect("GLASS_E2E=1 requires GLASS_CHROME_PATH");
615        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
616        listener.set_nonblocking(true).unwrap();
617        let address = listener.local_addr().unwrap();
618        let running = Arc::new(AtomicBool::new(true));
619        let server_running = Arc::clone(&running);
620        let server = std::thread::spawn(move || {
621            let html = br#"<!doctype html><title>Resident Glass</title><label>Name<input id="name"></label><button id="save" onclick="document.querySelector('p').textContent='Saved '+document.querySelector('#name').value">Save</button><p></p>"#;
622            while server_running.load(Ordering::Relaxed) {
623                match listener.accept() {
624                    Ok((mut stream, _)) => {
625                        let mut request = [0; 4096];
626                        let _ = stream.read(&mut request);
627                        let header = format!(
628                            "HTTP/1.1 200 OK\r\nContent-Type: text/html\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
629                            html.len()
630                        );
631                        let _ = stream.write_all(header.as_bytes());
632                        let _ = stream.write_all(html);
633                    }
634                    Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
635                        std::thread::sleep(Duration::from_millis(5));
636                    }
637                    Err(_) => break,
638                }
639            }
640        });
641        let port_probe = TcpListener::bind("127.0.0.1:0").unwrap();
642        let browser_port = port_probe.local_addr().unwrap().port();
643        drop(port_probe);
644
645        let service = BrowserService::new(std::env::temp_dir()).unwrap();
646        let started = service
647            .start(BrowserStartConfig {
648                port: browser_port,
649                chrome_path: Some(chrome_path.into()),
650                ..BrowserStartConfig::default()
651            })
652            .unwrap();
653        let browser_pid = started["browserProcessId"].as_u64().unwrap() as u32;
654        let initial = service.observe().unwrap();
655        let initial_revision = initial["consistency"]["end_revision"]
656            .as_u64()
657            .or_else(|| initial["consistency"]["endRevision"].as_u64())
658            .unwrap();
659        service
660            .navigate(
661                format!("http://{address}/fixture.html"),
662                initial_revision,
663                Duration::from_secs(30),
664            )
665            .unwrap();
666        assert!(
667            service
668                .navigate(
669                    format!("http://{address}/stale"),
670                    initial_revision,
671                    Duration::from_secs(30),
672                )
673                .unwrap_err()
674                .to_string()
675                .contains("revision")
676        );
677        let observed = service.observe().unwrap();
678        assert_eq!(observed["page"]["title"], "Resident Glass");
679        assert!(
680            service
681                .snapshot()
682                .unwrap()
683                .as_object()
684                .is_some_and(|snapshot| !snapshot.is_empty())
685        );
686        assert_eq!(
687            service
688                .semantic(SemanticObservationLevel::Structured)
689                .unwrap()["page"]["title"],
690            "Resident Glass"
691        );
692        assert!(service.diff().unwrap()["toRevision"].as_u64().is_some());
693        let revision = observed["consistency"]["end_revision"]
694            .as_u64()
695            .or_else(|| observed["consistency"]["endRevision"].as_u64())
696            .unwrap();
697        let typed = service
698            .type_text("Ada".into(), Some("Name".into()), revision)
699            .unwrap();
700        let revision = typed["currentRevision"].as_u64().unwrap();
701        service.click("Save".into(), revision).unwrap();
702        assert!(
703            service.observe().unwrap()["text"]
704                .as_str()
705                .unwrap()
706                .contains("Saved Ada")
707        );
708        service.stop().unwrap();
709        #[cfg(unix)]
710        assert!(unsafe { libc::kill(browser_pid as i32, 0) } == -1);
711        let port_closed = (0..100).any(|_| {
712            if TcpStream::connect(("127.0.0.1", browser_port)).is_err() {
713                true
714            } else {
715                std::thread::sleep(Duration::from_millis(10));
716                false
717            }
718        });
719        assert!(port_closed, "owned browser endpoint survived resident stop");
720        running.store(false, Ordering::Relaxed);
721        server.join().unwrap();
722    }
723}