Best headless browser for AI agents. Lite, Fast, High-Compatibility. Built in Rust
Rust ai-agentsai-toolsbrowserbrowser-automationcloud-browserheadlessheadless-browserkitesurfplaywrightpuppeteerrustservoweb-crawlerweb-crawlingweb-scraperweb-scraping
//! Shared owner-local Web API state and its Context entry point.
//!
//! A Context locates its owner through a weak binding. Window Realm tokens and
//! Worker run state remain the authoritative execution identities; retaining a
//! Context must not independently root its host or its callback graph.
mod callback_registry;
pub(crate) use callback_registry::{
CallbackRegistrationId, CallbackRegistrationKind, CallbackResidence,
};
use callback_registry::CallbackRegistry;
use std::{
cell::{Cell, RefCell},
rc::{Rc, Weak},
sync::{
Arc,
atomic::{AtomicBool, Ordering},
},
};
use crate::{
native_bridge::JsContextHost,
text_codec::TextCodecStore,
util::{ContextHostLifecycle, page_context_is_disconnected},
v8_finalizer::V8FinalizerRegistry,
worker::WorkerGlobalState,
};
#[derive(Default)]
pub(crate) struct CommonRuntimeState {
pub(crate) finalizers: RefCell<V8FinalizerRegistry>,
pub(crate) text_codecs: TextCodecStore,
pub(crate) callbacks: CallbackRegistry,
}
impl CommonRuntimeState {
/// Resolve native components without borrowing the Window or Worker
/// host. Retained backing state and callback execution permission remain
/// separate: asynchronous callbacks must still revalidate their identities.
pub(crate) fn from_scope(scope: &mut v8::PinScope<'_, '_>) -> Option<Rc<Self>> {
Self::from_context(scope.get_current_context())
}
/// Native components for an explicit target Realm. Borrowed methods must
/// resolve the receiver's owner rather than the method's current Context.
pub(crate) fn from_context(context: v8::Local<'_, v8::Context>) -> Option<Rc<Self>> {
let binding = context.get_slot::<CommonRuntimeBinding>()?;
let (runtime, _) = binding.resolve_owner(context)?;
Some(runtime)
}
pub(crate) fn clear_for_context_teardown(&self) {
self.callbacks.clear_for_context_teardown();
// Cleanup may reenter native components. Drop the component borrow
// before executing any cleanup, just as registration releases owner
// borrows before allocating a V8 weak handle.
let mut finalizers = std::mem::take(&mut *self.finalizers.borrow_mut());
finalizers.clear_for_context_teardown();
}
#[cfg(test)]
pub(crate) fn finalizer_count(&self) -> usize {
self.finalizers.borrow().len()
}
}
pub(crate) struct CommonRuntimeBinding {
common: Weak<CommonRuntimeState>,
owner: RuntimeOwner,
}
enum RuntimeOwner {
Window {
host_ptr: *mut JsContextHost,
lifecycle: Weak<Cell<ContextHostLifecycle>>,
},
Worker {
state: Weak<RefCell<WorkerGlobalState>>,
termination_requested: Arc<AtomicBool>,
},
}
#[derive(Clone, Copy)]
pub(crate) enum RuntimeExecutionContext {
Window(*mut JsContextHost),
Worker,
}
impl CommonRuntimeBinding {
pub(crate) fn install_window(
context: v8::Local<'_, v8::Context>,
common: &Rc<CommonRuntimeState>,
host_ptr: *mut JsContextHost,
lifecycle: &Rc<Cell<ContextHostLifecycle>>,
) {
if let Some(existing) = context.get_slot::<Self>() {
assert!(
Weak::ptr_eq(&existing.common, &Rc::downgrade(common))
&& matches!(existing.owner, RuntimeOwner::Window { host_ptr: installed, .. } if installed == host_ptr),
"a Context's common runtime owner must not be rebound"
);
return;
}
let previous = context.set_slot(Rc::new(Self {
common: Rc::downgrade(common),
owner: RuntimeOwner::Window {
host_ptr,
lifecycle: Rc::downgrade(lifecycle),
},
}));
debug_assert!(previous.is_none());
}
pub(crate) fn install_worker(
context: v8::Local<'_, v8::Context>,
state: &Rc<RefCell<WorkerGlobalState>>,
) {
let (common, termination_requested) = {
let state = state.borrow();
(
Rc::clone(&state.common),
Arc::clone(&state.termination_requested),
)
};
let previous = context.set_slot(Rc::new(Self {
common: Rc::downgrade(&common),
owner: RuntimeOwner::Worker {
state: Rc::downgrade(state),
termination_requested,
},
}));
assert!(
previous.is_none(),
"a Worker Context must have one common runtime binding"
);
}
/// Resolve the current Context and its owner once for immediate native
/// dispatch. This result is not permission to invoke a later callback:
/// invocation must revalidate the binding through `callback_execution_context`.
pub(crate) fn from_scope(
scope: &mut v8::PinScope<'_, '_>,
) -> Option<(Rc<Self>, RuntimeExecutionContext)> {
let context = scope.get_current_context();
let binding = context.get_slot::<Self>()?;
let (_, owner) = binding.resolve_owner(context)?;
Some((binding, owner))
}
pub(crate) fn runtime(&self) -> Option<Rc<CommonRuntimeState>> {
self.common.upgrade()
}
fn resolve_owner(
&self,
context: v8::Local<'_, v8::Context>,
) -> Option<(Rc<CommonRuntimeState>, RuntimeExecutionContext)> {
let runtime = self.runtime()?;
let owner = match &self.owner {
RuntimeOwner::Window {
host_ptr,
lifecycle,
} => {
if page_context_is_disconnected(context)
|| lifecycle.upgrade()?.get() == ContextHostLifecycle::Destroyed
{
return None;
}
RuntimeExecutionContext::Window(*host_ptr)
}
RuntimeOwner::Worker { state, .. } => {
state.upgrade()?;
RuntimeExecutionContext::Worker
}
};
Some((runtime, owner))
}
pub(crate) fn execution_context(
&self,
scope: &mut v8::PinScope<'_, '_>,
) -> Option<RuntimeExecutionContext> {
let context = scope.get_current_context();
let installed = context.get_slot::<Self>()?;
if !std::ptr::eq(self, installed.as_ref()) {
return None;
}
self.resolve_owner(context).map(|(_, owner)| owner)
}
/// Recheck the exact Context and owner immediately before author code.
/// Worker termination is checked in the same pass as owner resolution;
/// `close()` remains the task owner's separate delivery policy.
pub(crate) fn callback_execution_context(
&self,
scope: &mut v8::PinScope<'_, '_>,
) -> Option<RuntimeExecutionContext> {
let context = self.execution_context(scope)?;
if let RuntimeOwner::Worker {
termination_requested,
..
} = &self.owner
&& termination_requested.load(Ordering::Acquire)
{
return None;
}
Some(context)
}
pub(crate) fn window_host_ptr(&self) -> Option<*mut JsContextHost> {
self.runtime()?;
let RuntimeOwner::Window {
host_ptr,
lifecycle,
} = &self.owner
else {
return None;
};
(lifecycle.upgrade()?.get() != ContextHostLifecycle::Destroyed).then_some(*host_ptr)
}
pub(crate) fn worker_can_deliver_task(&self) -> bool {
self.runtime().is_some()
&& match &self.owner {
RuntimeOwner::Worker { state, .. } => state
.upgrade()
.is_some_and(|state| state.borrow().callback_task_delivery_allowed()),
RuntimeOwner::Window { .. } => false,
}
}
}
#[cfg(test)]
mod benchmarks;
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn context_bindings_share_components_without_rooting_or_confusing_owners() {
crate::ensure_v8_for_test();
let mut isolate = v8::Isolate::new(Default::default());
let scope = std::pin::pin!(v8::HandleScope::new(&mut isolate));
let scope = &mut scope.init();
let first = v8::Context::new(scope, Default::default());
let second = v8::Context::new(scope, Default::default());
let other = v8::Context::new(scope, Default::default());
let common = Rc::new(CommonRuntimeState::default());
let other_common = Rc::new(CommonRuntimeState::default());
let lifecycle = Rc::new(Cell::new(ContextHostLifecycle::Active));
let other_lifecycle = Rc::new(Cell::new(ContextHostLifecycle::Active));
// This test exercises component ownership and Context identity only.
// The opaque host address is never dereferenced by a host API.
let host = std::ptr::NonNull::<JsContextHost>::dangling().as_ptr();
CommonRuntimeBinding::install_window(first, &common, host, &lifecycle);
CommonRuntimeBinding::install_window(second, &common, host, &lifecycle);
CommonRuntimeBinding::install_window(other, &other_common, host, &other_lifecycle);
let first_binding = {
let scope = &mut v8::ContextScope::new(scope, first);
let (binding, owner) = CommonRuntimeBinding::from_scope(scope).unwrap();
assert!(matches!(owner, RuntimeExecutionContext::Window(ptr) if ptr == host));
assert!(Rc::ptr_eq(&binding.runtime().unwrap(), &common));
assert!(Rc::ptr_eq(
&CommonRuntimeState::from_scope(scope).unwrap(),
&common
));
assert!(binding.callback_execution_context(scope).is_some());
binding
};
{
let scope = &mut v8::ContextScope::new(scope, second);
let (binding, _) = CommonRuntimeBinding::from_scope(scope).unwrap();
assert!(Rc::ptr_eq(&binding.runtime().unwrap(), &common));
assert!(!Rc::ptr_eq(&binding, &first_binding));
assert!(first_binding.execution_context(scope).is_none());
assert!(first_binding.callback_execution_context(scope).is_none());
}
{
let scope = &mut v8::ContextScope::new(scope, other);
let (binding, _) = CommonRuntimeBinding::from_scope(scope).unwrap();
assert!(!Rc::ptr_eq(&binding.runtime().unwrap(), &common));
assert!(Rc::ptr_eq(
&CommonRuntimeState::from_context(first).unwrap(),
&common
));
other_lifecycle.set(ContextHostLifecycle::Destroyed);
assert!(CommonRuntimeBinding::from_scope(scope).is_none());
assert!(CommonRuntimeState::from_scope(scope).is_none());
assert!(CommonRuntimeState::from_context(other).is_none());
// A previously resolved owner is not a cached execution permit.
assert!(binding.callback_execution_context(scope).is_none());
}
drop(common);
let scope = &mut v8::ContextScope::new(scope, first);
assert!(CommonRuntimeBinding::from_scope(scope).is_none());
assert!(first_binding.runtime().is_none());
assert!(first_binding.callback_execution_context(scope).is_none());
}
#[test]
fn missing_context_binding_rejects_callback_before_reading_its_carrier() {
crate::ensure_v8_for_test();
let mut isolate = v8::Isolate::new(Default::default());
let scope = std::pin::pin!(v8::HandleScope::new(&mut isolate));
let scope = &mut scope.init();
let context = v8::Context::new(scope, Default::default());
let scope = &mut v8::ContextScope::new(scope, context);
let object = v8::Object::new(scope);
assert!(CommonRuntimeBinding::from_scope(scope).is_none());
assert!(
crate::webidl_callback_execution::PreparedWebIdlCallbackExecution::from_traced(
scope, object
)
.is_none()
);
}
}