Best headless browser for AI agents. Lite, Fast, High-Compatibility. Built in Rust
Rust ai-agentsai-toolsbrowserbrowser-automationcloud-browserheadlessheadless-browserkitesurfplaywrightpuppeteerrustservoweb-crawlerweb-crawlingweb-scraperweb-scraping
use std::{
collections::{HashMap, hash_map::Entry},
fmt,
num::NonZeroI32,
};
use moli_core::{
RendererRuntimeInspectorAsyncCompletion, RendererRuntimeInspectorResponseChannel,
RendererRuntimeInspectorResponseSender,
};
use moli_page_types::{
DevToolsSessionKey, FrontendCommandId, RendererAgentAttachmentId, RendererCallId,
RendererInspectorResponseDelivery,
};
use moli_protocol_cdp::{
CdpRendererCommandPolicy, CdpRendererCommandReplacement, CdpRendererCommandReplayDispatch,
ParsedCdpCommand,
};
#[cfg(test)]
use serde_json::Value;
#[derive(Clone, Debug, Eq, PartialEq)]
pub(crate) struct RendererCommandDescriptor {
replacement: CdpRendererCommandReplacement,
replay: RendererCommandReplay,
response_delivery: RendererInspectorResponseDelivery,
frontend_payload: String,
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub(crate) enum RendererCommandReplay {
Inspector(CdpRendererCommandReplayDispatch),
PerformanceGetMetrics,
SetScriptExecutionDisabled { disabled: bool },
}
impl RendererCommandDescriptor {
/// Builds a replay descriptor from the policy already derived at typed CDP
/// ingress. Production frontend commands must use this constructor.
pub(crate) fn from_frontend_policy(
frontend_payload: String,
policy: CdpRendererCommandPolicy,
response_delivery: RendererInspectorResponseDelivery,
) -> Self {
Self {
replacement: policy.replacement(),
replay: RendererCommandReplay::Inspector(policy.replay_dispatch()),
response_delivery,
frontend_payload,
}
}
pub(crate) fn performance_get_metrics(
frontend_payload: String,
policy: CdpRendererCommandPolicy,
response_delivery: RendererInspectorResponseDelivery,
) -> Self {
Self {
replacement: policy.replacement(),
replay: RendererCommandReplay::PerformanceGetMetrics,
response_delivery,
frontend_payload,
}
}
pub(crate) fn set_script_execution_disabled(
frontend_payload: String,
policy: CdpRendererCommandPolicy,
disabled: bool,
response_delivery: RendererInspectorResponseDelivery,
) -> Self {
Self {
replacement: policy.replacement(),
replay: RendererCommandReplay::SetScriptExecutionDisabled { disabled },
response_delivery,
frontend_payload,
}
}
/// Validates an internally synthesized Inspector payload that has no
/// `ParsedCdpCommand` ingress residence of its own.
///
/// This is deliberately named as a fallback: a frontend command reaching
/// this constructor would reintroduce method-policy reconstruction.
pub(crate) fn from_synthesized_payload(frontend_payload: String) -> Result<Self, String> {
let command = ParsedCdpCommand::parse_str(&frontend_payload)
.map_err(|error| format!("invalid renderer Inspector command JSON: {error}"))?;
let policy = command.renderer_policy();
Ok(Self {
replacement: policy.replacement(),
replay: RendererCommandReplay::Inspector(policy.replay_dispatch()),
// Internal Classic/BiDi adapters own their reply channel. A
// method being eligible for frontend session output must never
// redirect a synthesized adapter command implicitly.
response_delivery: RendererInspectorResponseDelivery::AdapterReply,
frontend_payload,
})
}
pub(crate) const fn replacement(&self) -> CdpRendererCommandReplacement {
self.replacement
}
pub(crate) fn replay(&self) -> &RendererCommandReplay {
&self.replay
}
pub(crate) const fn response_delivery(&self) -> RendererInspectorResponseDelivery {
self.response_delivery
}
pub(crate) fn frontend_payload(&self) -> &str {
&self.frontend_payload
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) struct DuplicatePendingRendererCommand {
frontend_command_id: FrontendCommandId,
}
impl DuplicatePendingRendererCommand {
#[cfg(test)]
pub(crate) const fn frontend_command_id(self) -> FrontendCommandId {
self.frontend_command_id
}
}
impl fmt::Display for DuplicatePendingRendererCommand {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(formatter, "Duplicate `id` in protocol request")
}
}
impl std::error::Error for DuplicatePendingRendererCommand {}
#[derive(Clone, Debug, Eq, Hash, PartialEq)]
pub(crate) struct PendingRendererCommandKey {
session_key: DevToolsSessionKey,
frontend_command_id: FrontendCommandId,
}
impl PendingRendererCommandKey {
pub(crate) fn new(session_id: Option<&str>, frontend_command_id: u64) -> Self {
Self {
session_key: DevToolsSessionKey::from_wire_session_id(session_id),
frontend_command_id: FrontendCommandId::new(frontend_command_id),
}
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) struct RendererCallIdExhausted;
impl fmt::Display for RendererCallIdExhausted {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("renderer Inspector call-id space exhausted")
}
}
impl std::error::Error for RendererCallIdExhausted {}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum RegisterRendererCallError {
Duplicate(DuplicatePendingRendererCommand),
Exhausted(RendererCallIdExhausted),
}
impl fmt::Display for RegisterRendererCallError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Duplicate(error) => error.fmt(formatter),
Self::Exhausted(error) => error.fmt(formatter),
}
}
}
impl std::error::Error for RegisterRendererCallError {}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) struct RendererCommandCorrelation {
frontend_command_id: FrontendCommandId,
renderer_call_id: RendererCallId,
dispatched_attachment_id: Option<RendererAgentAttachmentId>,
}
impl RendererCommandCorrelation {
pub(crate) const fn frontend_command_id(self) -> FrontendCommandId {
self.frontend_command_id
}
pub(crate) const fn renderer_call_id(self) -> RendererCallId {
self.renderer_call_id
}
pub(crate) const fn dispatched_attachment_id(self) -> Option<RendererAgentAttachmentId> {
self.dispatched_attachment_id
}
}
#[derive(Debug)]
pub(crate) struct PreparedRendererCallDispatch {
correlation: RendererCommandCorrelation,
response_sender: RendererRuntimeInspectorResponseSender,
response_receiver:
Option<tokio::sync::oneshot::Receiver<RendererRuntimeInspectorAsyncCompletion>>,
}
impl PreparedRendererCallDispatch {
pub(crate) const fn correlation(&self) -> RendererCommandCorrelation {
self.correlation
}
pub(crate) fn into_parts(
self,
) -> (
RendererCommandCorrelation,
RendererRuntimeInspectorResponseSender,
Option<tokio::sync::oneshot::Receiver<RendererRuntimeInspectorAsyncCompletion>>,
) {
(
self.correlation,
self.response_sender,
self.response_receiver,
)
}
}
#[derive(Debug)]
pub(crate) struct PreparedRendererCallReplay {
correlation: RendererCommandCorrelation,
replay: RendererCommandReplay,
response_delivery: RendererInspectorResponseDelivery,
frontend_payload: String,
response_sender: RendererRuntimeInspectorResponseSender,
}
#[derive(Debug)]
pub(crate) enum PreparedRendererCallTermination {
/// Internal adapters await a private receiver, so navigation rotates the
/// lease to a synthetic terminal completion owned by the replacement.
AdapterReply {
correlation: RendererCommandCorrelation,
response_sender: RendererRuntimeInspectorResponseSender,
},
/// Frontend calls remain owned by their protocol session. Navigation only
/// revokes the retired renderer lease; the session consumes this original
/// correlation when it emits the terminal response directly.
SessionSink {
correlation: RendererCommandCorrelation,
},
}
impl PreparedRendererCallTermination {
#[cfg(test)]
pub(crate) const fn correlation(&self) -> RendererCommandCorrelation {
match self {
Self::AdapterReply { correlation, .. } | Self::SessionSink { correlation } => {
*correlation
}
}
}
}
impl PreparedRendererCallReplay {
#[cfg(test)]
pub(crate) const fn correlation(&self) -> RendererCommandCorrelation {
self.correlation
}
#[cfg(test)]
pub(crate) fn frontend_payload(&self) -> &str {
&self.frontend_payload
}
#[cfg(test)]
pub(crate) const fn response_delivery(&self) -> RendererInspectorResponseDelivery {
self.response_delivery
}
#[cfg(test)]
pub(crate) fn into_response_sender(self) -> RendererRuntimeInspectorResponseSender {
self.response_sender
}
pub(crate) fn into_parts(
self,
) -> (
RendererCommandCorrelation,
RendererCommandReplay,
RendererInspectorResponseDelivery,
String,
RendererRuntimeInspectorResponseSender,
) {
(
self.correlation,
self.replay,
self.response_delivery,
self.frontend_payload,
self.response_sender,
)
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
struct RegisteredRendererCall {
renderer_call_id: RendererCallId,
dispatched_attachment_id: Option<RendererAgentAttachmentId>,
descriptor: RendererCommandDescriptor,
response_channel: RendererRuntimeInspectorResponseChannel,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) struct PendingRendererCommandRegistry<T> {
entries: HashMap<FrontendCommandId, T>,
renderer_calls_by_frontend: HashMap<FrontendCommandId, RegisteredRendererCall>,
frontend_commands_by_renderer: HashMap<RendererCallId, FrontendCommandId>,
next_renderer_call_id: Option<NonZeroI32>,
}
impl<T> Default for PendingRendererCommandRegistry<T> {
fn default() -> Self {
Self {
entries: HashMap::new(),
renderer_calls_by_frontend: HashMap::new(),
frontend_commands_by_renderer: HashMap::new(),
next_renderer_call_id: NonZeroI32::new(1),
}
}
}
impl<T> PendingRendererCommandRegistry<T> {
pub(crate) fn try_insert(
&mut self,
frontend_command_id: FrontendCommandId,
command: T,
) -> Result<(), DuplicatePendingRendererCommand> {
match self.entries.entry(frontend_command_id) {
Entry::Vacant(entry) => {
entry.insert(command);
Ok(())
}
Entry::Occupied(_) => Err(DuplicatePendingRendererCommand {
frontend_command_id,
}),
}
}
pub(crate) fn try_register_renderer_call(
&mut self,
frontend_command_id: FrontendCommandId,
dispatched_attachment_id: Option<RendererAgentAttachmentId>,
descriptor: RendererCommandDescriptor,
) -> Result<PreparedRendererCallDispatch, RegisterRendererCallError> {
if self
.renderer_calls_by_frontend
.contains_key(&frontend_command_id)
{
return Err(RegisterRendererCallError::Duplicate(
DuplicatePendingRendererCommand {
frontend_command_id,
},
));
}
let renderer_call_id = self
.allocate_renderer_call_id()
.map_err(RegisterRendererCallError::Exhausted)?;
let response_delivery = descriptor.response_delivery();
let (response_channel, response_receiver) =
RendererRuntimeInspectorResponseChannel::new_for_delivery(response_delivery);
let response_sender =
response_channel.activate_sender(renderer_call_id.get(), dispatched_attachment_id);
let previous_renderer_call = self.renderer_calls_by_frontend.insert(
frontend_command_id,
RegisteredRendererCall {
renderer_call_id,
dispatched_attachment_id,
descriptor,
response_channel,
},
);
let previous_frontend_command = self
.frontend_commands_by_renderer
.insert(renderer_call_id, frontend_command_id);
debug_assert!(previous_renderer_call.is_none());
debug_assert!(previous_frontend_command.is_none());
Ok(PreparedRendererCallDispatch {
correlation: RendererCommandCorrelation {
frontend_command_id,
renderer_call_id,
dispatched_attachment_id,
},
response_sender,
response_receiver,
})
}
pub(crate) fn prepare_replays_from_attachment(
&mut self,
old_attachment_id: RendererAgentAttachmentId,
new_attachment_id: RendererAgentAttachmentId,
) -> Result<Vec<PreparedRendererCallReplay>, RendererCallIdExhausted> {
let mut frontend_command_ids = self
.renderer_calls_by_frontend
.iter()
.filter_map(|(frontend_command_id, call)| {
(call.dispatched_attachment_id == Some(old_attachment_id)
&& call.descriptor.replacement() == CdpRendererCommandReplacement::Replay)
.then_some(*frontend_command_id)
})
.collect::<Vec<_>>();
frontend_command_ids.sort_by_key(|command_id| command_id.get());
let mut replays = Vec::with_capacity(frontend_command_ids.len());
for frontend_command_id in frontend_command_ids {
let renderer_call_id = self.allocate_renderer_call_id()?;
let response_sender = {
let call = self
.renderer_calls_by_frontend
.get(&frontend_command_id)
.expect("selected replay command must remain registered");
call.response_channel
.try_activate_sender(renderer_call_id.get(), Some(new_attachment_id))
};
let Some(response_sender) = response_sender else {
continue;
};
let call = self
.renderer_calls_by_frontend
.get_mut(&frontend_command_id)
.expect("selected replay command must remain registered");
let old_renderer_call_id = call.renderer_call_id;
let removed_frontend = self
.frontend_commands_by_renderer
.remove(&old_renderer_call_id);
debug_assert_eq!(removed_frontend, Some(frontend_command_id));
let previous_frontend = self
.frontend_commands_by_renderer
.insert(renderer_call_id, frontend_command_id);
debug_assert!(previous_frontend.is_none());
call.renderer_call_id = renderer_call_id;
call.dispatched_attachment_id = Some(new_attachment_id);
replays.push(PreparedRendererCallReplay {
correlation: RendererCommandCorrelation {
frontend_command_id,
renderer_call_id,
dispatched_attachment_id: Some(new_attachment_id),
},
replay: call.descriptor.replay().clone(),
response_delivery: call.descriptor.response_delivery(),
frontend_payload: call.descriptor.frontend_payload().to_owned(),
response_sender,
});
}
Ok(replays)
}
pub(crate) fn prepare_terminations_from_attachment(
&mut self,
old_attachment_id: RendererAgentAttachmentId,
terminal_attachment_id: RendererAgentAttachmentId,
) -> Result<Vec<PreparedRendererCallTermination>, RendererCallIdExhausted> {
let mut frontend_command_ids = self
.renderer_calls_by_frontend
.iter()
.filter_map(|(frontend_command_id, call)| {
(call.dispatched_attachment_id == Some(old_attachment_id)
&& call.descriptor.replacement() == CdpRendererCommandReplacement::Terminate)
.then_some(*frontend_command_id)
})
.collect::<Vec<_>>();
frontend_command_ids.sort_by_key(|command_id| command_id.get());
let mut terminations = Vec::with_capacity(frontend_command_ids.len());
for frontend_command_id in frontend_command_ids {
let response_delivery = self
.renderer_calls_by_frontend
.get(&frontend_command_id)
.expect("selected terminal command must remain registered")
.descriptor
.response_delivery();
match response_delivery {
RendererInspectorResponseDelivery::SessionSink => {
let call = self
.renderer_calls_by_frontend
.get(&frontend_command_id)
.expect("selected terminal command must remain registered");
if !call.response_channel.try_revoke_active_lease() {
continue;
}
terminations.push(PreparedRendererCallTermination::SessionSink {
correlation: RendererCommandCorrelation {
frontend_command_id,
renderer_call_id: call.renderer_call_id,
dispatched_attachment_id: call.dispatched_attachment_id,
},
});
continue;
}
RendererInspectorResponseDelivery::AdapterReply => {}
}
let renderer_call_id = self.allocate_renderer_call_id()?;
let response_sender = {
let call = self
.renderer_calls_by_frontend
.get(&frontend_command_id)
.expect("selected terminal command must remain registered");
call.response_channel
.try_activate_sender(renderer_call_id.get(), Some(terminal_attachment_id))
};
let Some(response_sender) = response_sender else {
continue;
};
let call = self
.renderer_calls_by_frontend
.get_mut(&frontend_command_id)
.expect("selected terminal command must remain registered");
let old_renderer_call_id = call.renderer_call_id;
let removed_frontend = self
.frontend_commands_by_renderer
.remove(&old_renderer_call_id);
debug_assert_eq!(removed_frontend, Some(frontend_command_id));
let previous_frontend = self
.frontend_commands_by_renderer
.insert(renderer_call_id, frontend_command_id);
debug_assert!(previous_frontend.is_none());
call.renderer_call_id = renderer_call_id;
call.dispatched_attachment_id = Some(terminal_attachment_id);
terminations.push(PreparedRendererCallTermination::AdapterReply {
correlation: RendererCommandCorrelation {
frontend_command_id,
renderer_call_id,
dispatched_attachment_id: Some(terminal_attachment_id),
},
response_sender,
});
}
Ok(terminations)
}
pub(crate) fn terminate_all_renderer_calls(
&mut self,
reason: &str,
) -> Vec<RendererCommandCorrelation> {
let mut frontend_command_ids = self
.renderer_calls_by_frontend
.keys()
.copied()
.collect::<Vec<_>>();
frontend_command_ids.sort_by_key(|command_id| command_id.get());
let mut terminated = Vec::with_capacity(frontend_command_ids.len());
for frontend_command_id in frontend_command_ids {
let (correlation, response_sender) = {
let call = self
.renderer_calls_by_frontend
.get_mut(&frontend_command_id)
.expect("selected terminal command must remain registered");
call.dispatched_attachment_id = None;
let correlation = RendererCommandCorrelation {
frontend_command_id,
renderer_call_id: call.renderer_call_id,
dispatched_attachment_id: None,
};
let response_sender = call
.response_channel
.try_activate_sender(call.renderer_call_id.get(), None);
(correlation, response_sender)
};
if let Some(response_sender) = response_sender {
let _ = response_sender.send(serde_json::json!({
"id": correlation.renderer_call_id().get(),
"error": {
"code": -32000,
"message": reason,
},
}));
}
let removed = self.take_renderer_call_for_frontend_if_matches(
frontend_command_id,
correlation.renderer_call_id(),
None,
);
debug_assert_eq!(removed, Some(correlation));
terminated.push(correlation);
}
terminated
}
pub(crate) fn take_renderer_call_for_frontend(
&mut self,
frontend_command_id: FrontendCommandId,
) -> Option<RendererCommandCorrelation> {
let registered_call = self
.renderer_calls_by_frontend
.remove(&frontend_command_id)?;
registered_call.response_channel.cancel();
let removed_frontend = self
.frontend_commands_by_renderer
.remove(®istered_call.renderer_call_id);
debug_assert_eq!(removed_frontend, Some(frontend_command_id));
Some(RendererCommandCorrelation {
frontend_command_id,
renderer_call_id: registered_call.renderer_call_id,
dispatched_attachment_id: registered_call.dispatched_attachment_id,
})
}
pub(crate) fn renderer_call_for_frontend(
&self,
frontend_command_id: FrontendCommandId,
) -> Option<RendererCommandCorrelation> {
let registered_call = self.renderer_calls_by_frontend.get(&frontend_command_id)?;
Some(RendererCommandCorrelation {
frontend_command_id,
renderer_call_id: registered_call.renderer_call_id,
dispatched_attachment_id: registered_call.dispatched_attachment_id,
})
}
pub(crate) fn renderer_command_descriptor_for_renderer_if_attachment_matches(
&self,
renderer_call_id: RendererCallId,
dispatched_attachment_id: Option<RendererAgentAttachmentId>,
) -> Option<RendererCommandDescriptor> {
let frontend_command_id = self.frontend_commands_by_renderer.get(&renderer_call_id)?;
let registered_call = self.renderer_calls_by_frontend.get(frontend_command_id)?;
(registered_call.dispatched_attachment_id == dispatched_attachment_id)
.then(|| registered_call.descriptor.clone())
}
#[cfg(test)]
pub(crate) fn renderer_command_descriptor_for_frontend(
&self,
frontend_command_id: FrontendCommandId,
) -> Option<&RendererCommandDescriptor> {
self.renderer_calls_by_frontend
.get(&frontend_command_id)
.map(|call| &call.descriptor)
}
pub(crate) fn take_renderer_call_for_frontend_if_matches(
&mut self,
frontend_command_id: FrontendCommandId,
renderer_call_id: RendererCallId,
dispatched_attachment_id: Option<RendererAgentAttachmentId>,
) -> Option<RendererCommandCorrelation> {
let registered_call = self.renderer_calls_by_frontend.get(&frontend_command_id)?;
if registered_call.renderer_call_id != renderer_call_id
|| registered_call.dispatched_attachment_id != dispatched_attachment_id
{
return None;
}
self.take_renderer_call_for_frontend(frontend_command_id)
}
pub(crate) fn take_frontend_command_for_renderer(
&mut self,
renderer_call_id: RendererCallId,
) -> Option<RendererCommandCorrelation> {
let frontend_command_id = self
.frontend_commands_by_renderer
.remove(&renderer_call_id)?;
let removed_renderer = self.renderer_calls_by_frontend.remove(&frontend_command_id);
if let Some(call) = &removed_renderer {
call.response_channel.cancel();
}
debug_assert_eq!(
removed_renderer.as_ref().map(|call| call.renderer_call_id),
Some(renderer_call_id)
);
Some(RendererCommandCorrelation {
frontend_command_id,
renderer_call_id,
dispatched_attachment_id: removed_renderer
.and_then(|call| call.dispatched_attachment_id),
})
}
pub(crate) fn take_frontend_command_for_renderer_if_attachment_matches(
&mut self,
renderer_call_id: RendererCallId,
dispatched_attachment_id: Option<RendererAgentAttachmentId>,
) -> Option<RendererCommandCorrelation> {
let frontend_command_id = *self.frontend_commands_by_renderer.get(&renderer_call_id)?;
let registered_call = self.renderer_calls_by_frontend.get(&frontend_command_id)?;
if registered_call.dispatched_attachment_id != dispatched_attachment_id {
return None;
}
self.take_frontend_command_for_renderer(renderer_call_id)
}
pub(crate) fn is_empty(&self) -> bool {
self.entries.is_empty()
}
pub(crate) fn get_mut(&mut self, frontend_command_id: FrontendCommandId) -> Option<&mut T> {
self.entries.get_mut(&frontend_command_id)
}
pub(crate) fn len(&self) -> usize {
self.entries.len()
}
pub(crate) fn remove(&mut self, frontend_command_id: FrontendCommandId) -> Option<T> {
self.entries.remove(&frontend_command_id)
}
pub(crate) fn iter(&self) -> impl Iterator<Item = (&FrontendCommandId, &T)> {
self.entries.iter()
}
fn allocate_renderer_call_id(&mut self) -> Result<RendererCallId, RendererCallIdExhausted> {
let renderer_call_id = self.next_renderer_call_id.ok_or(RendererCallIdExhausted)?;
self.next_renderer_call_id = renderer_call_id
.get()
.checked_add(1)
.and_then(NonZeroI32::new);
Ok(RendererCallId::new(renderer_call_id.get()))
}
}
#[cfg(test)]
mod tests {
use super::*;
fn descriptor(frontend_command_id: u64, method: &str) -> RendererCommandDescriptor {
RendererCommandDescriptor::from_synthesized_payload(
serde_json::json!({
"id": frontend_command_id,
"method": method,
"params": {},
})
.to_string(),
)
.unwrap()
}
#[test]
fn duplicate_frontend_id_does_not_replace_original_command() {
let id = FrontendCommandId::new(7);
let mut registry = PendingRendererCommandRegistry::default();
registry.try_insert(id, "original").unwrap();
let duplicate = registry.try_insert(id, "replacement").unwrap_err();
assert_eq!(duplicate.frontend_command_id(), id);
assert_eq!(duplicate.to_string(), "Duplicate `id` in protocol request");
assert_eq!(registry.remove(id), Some("original"));
}
#[test]
fn same_frontend_id_is_independent_across_session_owned_registries() {
let id = FrontendCommandId::new(9);
let mut primary = PendingRendererCommandRegistry::default();
let mut attached = PendingRendererCommandRegistry::default();
primary.try_insert(id, "primary").unwrap();
attached.try_insert(id, "attached").unwrap();
assert_eq!(primary.remove(id), Some("primary"));
assert_eq!(attached.remove(id), Some("attached"));
}
#[test]
fn renderer_call_ids_are_internal_and_session_scoped() {
let large_frontend_id = FrontendCommandId::new(i32::MAX as u64 + 41);
let mut primary = PendingRendererCommandRegistry::<()>::default();
let mut attached = PendingRendererCommandRegistry::<()>::default();
let primary_first = primary
.try_register_renderer_call(
large_frontend_id,
None,
descriptor(large_frontend_id.get(), "Runtime.evaluate"),
)
.unwrap()
.correlation();
let attached_first = attached
.try_register_renderer_call(
large_frontend_id,
None,
descriptor(large_frontend_id.get(), "Runtime.evaluate"),
)
.unwrap()
.correlation();
let primary_second = primary
.try_register_renderer_call(
FrontendCommandId::new(2),
None,
descriptor(2, "Console.enable"),
)
.unwrap()
.correlation();
assert_eq!(primary_first.renderer_call_id(), RendererCallId::new(1));
assert_eq!(attached_first.renderer_call_id(), RendererCallId::new(1));
assert_eq!(primary_second.renderer_call_id(), RendererCallId::new(2));
assert_eq!(
primary.take_frontend_command_for_renderer(RendererCallId::new(1)),
Some(primary_first)
);
assert_eq!(
attached.take_renderer_call_for_frontend(large_frontend_id),
Some(attached_first)
);
}
#[test]
fn duplicate_renderer_call_registration_preserves_original_correlation() {
let frontend_id = FrontendCommandId::new(17);
let mut registry = PendingRendererCommandRegistry::<()>::default();
let original = registry
.try_register_renderer_call(
frontend_id,
None,
descriptor(frontend_id.get(), "Runtime.getProperties"),
)
.unwrap()
.correlation();
let error = registry
.try_register_renderer_call(
frontend_id,
None,
descriptor(frontend_id.get(), "Runtime.evaluate"),
)
.unwrap_err();
assert_eq!(error.to_string(), "Duplicate `id` in protocol request");
assert_eq!(
registry.take_renderer_call_for_frontend(frontend_id),
Some(original)
);
}
#[test]
fn mismatched_renderer_or_attachment_does_not_consume_correlation() {
let frontend_id = FrontendCommandId::new(23);
let dispatched_attachment_id = RendererAgentAttachmentId::allocate();
let stale_attachment_id = RendererAgentAttachmentId::allocate();
let mut registry = PendingRendererCommandRegistry::<()>::default();
let correlation = registry
.try_register_renderer_call(
frontend_id,
Some(dispatched_attachment_id),
descriptor(frontend_id.get(), "Runtime.evaluate"),
)
.unwrap()
.correlation();
assert_eq!(
registry.take_renderer_call_for_frontend_if_matches(
frontend_id,
RendererCallId::new(correlation.renderer_call_id().get() + 1),
Some(dispatched_attachment_id),
),
None
);
assert_eq!(
registry.take_renderer_call_for_frontend_if_matches(
frontend_id,
correlation.renderer_call_id(),
Some(stale_attachment_id),
),
None
);
assert_eq!(
registry.take_frontend_command_for_renderer_if_attachment_matches(
correlation.renderer_call_id(),
Some(stale_attachment_id),
),
None
);
assert_eq!(
registry.take_renderer_call_for_frontend_if_matches(
frontend_id,
correlation.renderer_call_id(),
Some(dispatched_attachment_id),
),
Some(correlation)
);
}
#[test]
fn registered_command_preserves_frontend_payload_and_typed_replacement_traits() {
let frontend_id = FrontendCommandId::new(31);
let mut registry = PendingRendererCommandRegistry::<()>::default();
let registered_descriptor = descriptor(frontend_id.get(), "Profiler.stop");
let expected_payload = registered_descriptor.frontend_payload().to_owned();
registry
.try_register_renderer_call(frontend_id, None, registered_descriptor)
.unwrap();
let registered = registry
.renderer_command_descriptor_for_frontend(frontend_id)
.expect("registered descriptor");
assert_eq!(
registered.replacement(),
CdpRendererCommandReplacement::Replay
);
assert_eq!(
registered.replay(),
&RendererCommandReplay::Inspector(CdpRendererCommandReplayDispatch::Direct)
);
assert_eq!(registered.frontend_payload(), expected_payload);
let add_binding = descriptor(32, "Runtime.addBinding");
assert_eq!(
add_binding.replay(),
&RendererCommandReplay::Inspector(
CdpRendererCommandReplayDispatch::ResolveRuntimeContext
)
);
}
#[test]
fn frontend_descriptor_uses_ingress_policy_without_reparsing_payload() {
let ingress = ParsedCdpCommand::parse_str(
r#"{"id":32,"method":"Runtime.addBinding","params":{"name":"exposed"}}"#,
)
.expect("frontend command must parse at ingress");
let normalized_payload =
r#"{"id":91,"method":"Runtime.evaluate","params":{"expression":"1"}}"#.to_owned();
let descriptor = RendererCommandDescriptor::from_frontend_policy(
normalized_payload.clone(),
ingress.renderer_policy(),
RendererInspectorResponseDelivery::AdapterReply,
);
assert_eq!(descriptor.frontend_payload(), normalized_payload);
assert_eq!(
descriptor.replay(),
&RendererCommandReplay::Inspector(
CdpRendererCommandReplayDispatch::ResolveRuntimeContext
),
"descriptor construction must consume the ingress policy instead of deriving it from the normalized payload"
);
}
#[test]
fn concrete_target_capability_selects_the_response_sink() {
let frontend = ParsedCdpCommand::parse_str(
r#"{"id":33,"method":"Debugger.getScriptSource","params":{"scriptId":"1"}}"#,
)
.expect("frontend command must parse at ingress");
let page_descriptor = RendererCommandDescriptor::from_frontend_policy(
frontend.json().to_owned(),
frontend.renderer_policy(),
RendererInspectorResponseDelivery::SessionSink,
);
let worker_descriptor = RendererCommandDescriptor::from_frontend_policy(
frontend.json().to_owned(),
frontend.renderer_policy(),
RendererInspectorResponseDelivery::SessionSink,
);
let adapter_descriptor =
RendererCommandDescriptor::from_synthesized_payload(frontend.json().to_owned())
.expect("adapter payload must be valid Inspector JSON");
assert_eq!(
page_descriptor.response_delivery(),
RendererInspectorResponseDelivery::SessionSink
);
assert_eq!(
worker_descriptor.response_delivery(),
RendererInspectorResponseDelivery::SessionSink,
"external Worker commands must publish through their DevTools session"
);
assert_eq!(
adapter_descriptor.response_delivery(),
RendererInspectorResponseDelivery::AdapterReply,
"method policy must not redirect an internal adapter reply to a frontend session"
);
}
#[test]
fn non_v8_page_io_descriptors_keep_typed_replay_operations() {
let performance = ParsedCdpCommand::parse_str(
r#"{"id":34,"method":"Performance.getMetrics","params":{}}"#,
)
.expect("Performance command must parse at ingress");
let performance_descriptor = RendererCommandDescriptor::performance_get_metrics(
performance.json().to_owned(),
performance.renderer_policy(),
RendererInspectorResponseDelivery::SessionSink,
);
assert_eq!(
performance_descriptor.replay(),
&RendererCommandReplay::PerformanceGetMetrics
);
assert_eq!(
performance_descriptor.response_delivery(),
RendererInspectorResponseDelivery::SessionSink
);
let emulation = ParsedCdpCommand::parse_str(
r#"{"id":35,"method":"Emulation.setScriptExecutionDisabled","params":{"value":true}}"#,
)
.expect("Emulation command must parse at ingress");
let emulation_descriptor = RendererCommandDescriptor::set_script_execution_disabled(
emulation.json().to_owned(),
emulation.renderer_policy(),
true,
RendererInspectorResponseDelivery::SessionSink,
);
assert_eq!(
emulation_descriptor.replay(),
&RendererCommandReplay::SetScriptExecutionDisabled { disabled: true }
);
assert_eq!(
emulation_descriptor.response_delivery(),
RendererInspectorResponseDelivery::SessionSink
);
}
#[tokio::test]
async fn session_replay_rotates_renderer_id_and_lease_without_adapter_reply_receiver() {
let frontend_id = FrontendCommandId::new(41);
let old_attachment = RendererAgentAttachmentId::allocate();
let new_attachment = RendererAgentAttachmentId::allocate();
let mut registry = PendingRendererCommandRegistry::<()>::default();
let frontend = ParsedCdpCommand::parse_str(
serde_json::json!({
"id": frontend_id.get(),
"method": "Debugger.getScriptSource",
"params": { "scriptId": "1" },
})
.to_string(),
)
.expect("frontend command must parse at ingress");
let prepared = registry
.try_register_renderer_call(
frontend_id,
Some(old_attachment),
RendererCommandDescriptor::from_frontend_policy(
frontend.json().to_owned(),
frontend.renderer_policy(),
RendererInspectorResponseDelivery::SessionSink,
),
)
.unwrap();
let (old_correlation, old_sender, response_receiver) = prepared.into_parts();
assert!(
response_receiver.is_none(),
"SessionSink delivery must not allocate an adapter-reply receiver"
);
let mut replays = registry
.prepare_replays_from_attachment(old_attachment, new_attachment)
.unwrap();
assert_eq!(replays.len(), 1);
let replay = replays.pop().unwrap();
let new_correlation = replay.correlation();
assert_eq!(new_correlation.frontend_command_id(), frontend_id);
assert_ne!(
new_correlation.renderer_call_id(),
old_correlation.renderer_call_id()
);
assert_eq!(
new_correlation.dispatched_attachment_id(),
Some(new_attachment)
);
let payload: Value = serde_json::from_str(replay.frontend_payload()).unwrap();
assert_eq!(payload["id"], frontend_id.get());
assert_eq!(
replay.response_delivery(),
RendererInspectorResponseDelivery::SessionSink,
"attachment replacement must preserve the frontend session output capability"
);
assert!(
old_sender
.send(serde_json::json!({
"id": old_correlation.renderer_call_id().get(),
"result": { "stale": true },
}))
.is_err(),
"rotating the registry lease must invalidate the old sender"
);
assert!(
replay
.into_response_sender()
.send(serde_json::json!({
"id": new_correlation.renderer_call_id().get(),
"result": { "current": true },
}))
.is_err(),
"a session response cannot publish until its concrete output host is bound"
);
assert_eq!(
registry.take_frontend_command_for_renderer_if_attachment_matches(
old_correlation.renderer_call_id(),
Some(old_attachment),
),
None
);
assert_eq!(
registry.take_frontend_command_for_renderer_if_attachment_matches(
new_correlation.renderer_call_id(),
Some(new_attachment),
),
Some(new_correlation)
);
}
#[tokio::test]
async fn completed_response_is_not_rotated_during_attachment_replacement() {
let frontend_id = FrontendCommandId::new(42);
let old_attachment = RendererAgentAttachmentId::allocate();
let new_attachment = RendererAgentAttachmentId::allocate();
let mut registry = PendingRendererCommandRegistry::<()>::default();
let prepared = registry
.try_register_renderer_call(
frontend_id,
Some(old_attachment),
descriptor(frontend_id.get(), "Console.clearMessages"),
)
.unwrap();
let (correlation, sender, response_receiver) = prepared.into_parts();
let response_receiver = response_receiver
.expect("a synthesized AdapterReply call must allocate a response receiver");
sender
.send(serde_json::json!({
"id": correlation.renderer_call_id().get(),
"result": {},
}))
.expect("old attachment response should complete before cutover");
assert!(
registry
.prepare_replays_from_attachment(old_attachment, new_attachment)
.unwrap()
.is_empty(),
"a completed response has already won its frontend completion"
);
assert_eq!(
registry.renderer_call_for_frontend(frontend_id),
Some(correlation),
"the completed response keeps its old attachment-qualified correlation until routing"
);
let completion = response_receiver.await.unwrap();
assert_eq!(
registry.take_frontend_command_for_renderer_if_attachment_matches(
RendererCallId::new(completion.call_id),
completion.renderer_agent_attachment_id(),
),
Some(correlation)
);
}
#[tokio::test]
async fn adapter_reply_termination_rotates_attachment_and_invalidates_old_response_lease() {
let frontend_id = FrontendCommandId::new(42);
let old_attachment = RendererAgentAttachmentId::allocate();
let new_attachment = RendererAgentAttachmentId::allocate();
let mut registry = PendingRendererCommandRegistry::<()>::default();
let prepared = registry
.try_register_renderer_call(
frontend_id,
Some(old_attachment),
descriptor(frontend_id.get(), "Runtime.awaitPromise"),
)
.unwrap();
let (old_correlation, old_sender, response_receiver) = prepared.into_parts();
let response_receiver = response_receiver
.expect("a synthesized AdapterReply call must allocate a response receiver");
let mut terminations = registry
.prepare_terminations_from_attachment(old_attachment, new_attachment)
.unwrap();
assert_eq!(terminations.len(), 1);
let termination = terminations.pop().unwrap();
let terminal_correlation = termination.correlation();
assert_eq!(
terminal_correlation.frontend_command_id(),
old_correlation.frontend_command_id()
);
assert_ne!(
terminal_correlation.renderer_call_id(),
old_correlation.renderer_call_id()
);
assert_eq!(
terminal_correlation.dispatched_attachment_id(),
Some(new_attachment)
);
assert!(
old_sender
.send(serde_json::json!({
"id": old_correlation.renderer_call_id().get(),
"result": {},
}))
.is_err(),
"replacement must invalidate an old renderer callback before Page teardown"
);
let PreparedRendererCallTermination::AdapterReply {
correlation,
response_sender,
} = termination
else {
panic!("a synthesized command must use AdapterReply termination")
};
assert_eq!(correlation, terminal_correlation);
response_sender
.send(serde_json::json!({
"id": terminal_correlation.renderer_call_id().get(),
"error": {
"code": -32000,
"message": "Inspected target navigated or closed",
},
}))
.unwrap();
let completion = response_receiver.await.unwrap();
assert_eq!(
completion.call_id,
terminal_correlation.renderer_call_id().get()
);
assert_eq!(
completion.renderer_agent_attachment_id(),
Some(new_attachment)
);
assert_eq!(
registry.take_frontend_command_for_renderer_if_attachment_matches(
old_correlation.renderer_call_id(),
Some(old_attachment),
),
None
);
assert_eq!(
registry.take_frontend_command_for_renderer_if_attachment_matches(
terminal_correlation.renderer_call_id(),
Some(new_attachment),
),
Some(terminal_correlation)
);
}
#[test]
fn devtools_session_termination_revokes_without_renderer_identity_rotation() {
let frontend_id = FrontendCommandId::new(43);
let old_attachment = RendererAgentAttachmentId::allocate();
let new_attachment = RendererAgentAttachmentId::allocate();
let frontend = ParsedCdpCommand::parse_str(
r#"{"id":43,"method":"Runtime.evaluate","params":{"expression":"43"}}"#,
)
.expect("frontend command must parse at ingress");
let mut registry = PendingRendererCommandRegistry::<()>::default();
let prepared = registry
.try_register_renderer_call(
frontend_id,
Some(old_attachment),
RendererCommandDescriptor::from_frontend_policy(
frontend.json().to_owned(),
frontend.renderer_policy(),
RendererInspectorResponseDelivery::SessionSink,
),
)
.unwrap();
let (old_correlation, old_sender, response_receiver) = prepared.into_parts();
assert!(response_receiver.is_none());
registry.next_renderer_call_id = None;
let mut terminations = registry
.prepare_terminations_from_attachment(old_attachment, new_attachment)
.expect("session termination must not allocate a renderer call id");
assert_eq!(terminations.len(), 1);
let termination = terminations.pop().unwrap();
assert_eq!(termination.correlation(), old_correlation);
assert!(matches!(
termination,
PreparedRendererCallTermination::SessionSink {
correlation
} if correlation == old_correlation
));
assert_eq!(
registry.renderer_call_for_frontend(frontend_id),
Some(old_correlation),
"the session owner consumes the original correlation when it emits the error"
);
assert!(
old_sender
.send(serde_json::json!({
"id": old_correlation.renderer_call_id().get(),
"result": {},
}))
.is_err(),
"preparing the direct session error must revoke the old renderer lease"
);
assert_eq!(
registry.take_frontend_command_for_renderer_if_attachment_matches(
old_correlation.renderer_call_id(),
Some(old_attachment),
),
Some(old_correlation)
);
}
#[tokio::test]
async fn terminal_drain_completes_receivers_and_removes_all_correlations() {
let first_id = FrontendCommandId::new(51);
let second_id = FrontendCommandId::new(52);
let attachment = RendererAgentAttachmentId::allocate();
let mut registry = PendingRendererCommandRegistry::<()>::default();
let first = registry
.try_register_renderer_call(
first_id,
Some(attachment),
descriptor(first_id.get(), "Runtime.evaluate"),
)
.unwrap();
let second = registry
.try_register_renderer_call(
second_id,
Some(attachment),
descriptor(second_id.get(), "Console.clearMessages"),
)
.unwrap();
let (_, first_sender, first_receiver) = first.into_parts();
let (_, second_sender, second_receiver) = second.into_parts();
let first_receiver = first_receiver
.expect("a synthesized AdapterReply call must allocate a response receiver");
let second_receiver = second_receiver
.expect("a synthesized AdapterReply call must allocate a response receiver");
let terminated = registry.terminate_all_renderer_calls("Inspector detached");
assert_eq!(
terminated
.iter()
.map(|correlation| correlation.frontend_command_id().get())
.collect::<Vec<_>>(),
vec![first_id.get(), second_id.get()]
);
assert!(first_sender.send(serde_json::json!({"id": 1})).is_err());
assert!(second_sender.send(serde_json::json!({"id": 2})).is_err());
for completion in [
first_receiver.await.unwrap(),
second_receiver.await.unwrap(),
] {
assert_eq!(completion.renderer_agent_attachment_id(), None);
let response = completion
.output
.protocol_response(completion.call_id)
.expect("terminal response");
assert_eq!(response["error"]["code"], -32000);
assert_eq!(response["error"]["message"], "Inspector detached");
}
assert!(registry.renderer_calls_by_frontend.is_empty());
assert!(registry.frontend_commands_by_renderer.is_empty());
}
#[test]
fn terminate_policy_is_not_prepared_for_replay() {
let frontend_id = FrontendCommandId::new(43);
let old_attachment = RendererAgentAttachmentId::allocate();
let new_attachment = RendererAgentAttachmentId::allocate();
let mut registry = PendingRendererCommandRegistry::<()>::default();
let correlation = registry
.try_register_renderer_call(
frontend_id,
Some(old_attachment),
descriptor(frontend_id.get(), "Runtime.evaluate"),
)
.unwrap()
.correlation();
assert!(
registry
.prepare_replays_from_attachment(old_attachment, new_attachment)
.unwrap()
.is_empty()
);
assert_eq!(
registry.renderer_call_for_frontend(frontend_id),
Some(correlation)
);
}
}