1use glass_browser::browser::policy::BrowserPolicy;
4use glass_browser::browser::session::{
5 BrowserSession, SemanticObservationLevel, SessionOptions, WorkflowCheckpoint,
6 WorkflowDefinition, WorkflowRunResult,
7};
8use glass_browser::development::{DevelopmentError, DevelopmentResult};
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#[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}