Skip to content

armgit / moli

Public Imported from GitHub
0

Best headless browser for AI agents. Lite, Fast, High-Compatibility. Built in Rust

12.4 KB
Raw Blame
use std::rc::Rc;

use v8::{Local, Object, PinScope, PropertyAttribute};

use crate::properties::new_null_prototype_object;
use crate::strings::{v8_string, v8str};
use crate::symbols::{get_private_object, set_private_value};

const ECMASCRIPT_CONSTRUCTORS_SLOT: &str = "__moliEcmascriptConstructors";
const ECMASCRIPT_PROTOTYPES_SLOT: &str = "__moliEcmascriptPrototypes";

#[derive(Clone, Copy)]
pub enum WebApiIntrinsicKind {
    Constructor,
    Prototype,
}

pub enum WebApiIntrinsicLookup<'s> {
    /// This name is outside the embedder's Web API registry.
    Unmanaged,
    /// A managed name must never fall back to an author-controlled global,
    /// including when materialization failed or the interface is unavailable.
    Managed(Option<Local<'s, Object>>),
}

pub type WebApiIntrinsicResolver =
    for<'s, 'i> fn(&mut PinScope<'s, 'i>, &str, WebApiIntrinsicKind) -> WebApiIntrinsicLookup<'s>;

struct RealmWebApiIntrinsicResolver(WebApiIntrinsicResolver);

/// Connects shared binding helpers to the embedder's canonical realm cache.
/// Install after eager bootstrap; the resolver stores no intrinsic identities.
pub fn install_web_api_intrinsic_resolver(
    scope: &mut PinScope<'_, '_>,
    resolver: WebApiIntrinsicResolver,
) {
    scope
        .get_current_context()
        .set_slot(Rc::new(RealmWebApiIntrinsicResolver(resolver)));
}

fn intrinsic_registry_object<'s>(
    scope: &mut PinScope<'s, '_>,
    global: Local<'s, Object>,
    slot: &str,
) -> Local<'s, Object> {
    if let Some(registry) = get_private_object(scope, global, slot) {
        return registry;
    }

    let registry = new_null_prototype_object(scope);
    set_private_value(scope, global, slot, registry.into());
    registry
}

/// Ensures that a realm global owns its native-only ECMAScript intrinsic maps.
///
/// The maps are stored under V8 private symbols, so author code cannot observe
/// or replace them through JavaScript reflection. They intentionally contain
/// realm-local V8 objects rather than Rust `Global` handles, allowing V8 to
/// reclaim the whole realm graph when its context becomes unreachable.
pub fn initialize_ecmascript_intrinsic_registry<'s>(
    scope: &mut PinScope<'s, '_>,
    global: Local<'s, Object>,
) {
    let _ = intrinsic_registry_object(scope, global, ECMASCRIPT_CONSTRUCTORS_SLOT);
    let _ = intrinsic_registry_object(scope, global, ECMASCRIPT_PROTOTYPES_SLOT);
}

fn define_intrinsic<'s>(
    scope: &mut PinScope<'s, '_>,
    registry: Local<'s, Object>,
    name: &str,
    value: Local<'s, Object>,
) -> bool {
    let Some(key) = v8_string(scope, name) else {
        return false;
    };
    registry
        .define_own_property(
            scope,
            key.into(),
            value.into(),
            PropertyAttribute::DONT_ENUM
                | PropertyAttribute::READ_ONLY
                | PropertyAttribute::DONT_DELETE,
        )
        .unwrap_or(false)
}

/// Records a trusted ECMAScript constructor and prototype. Web API identities
/// belong to the embedder's realm cache, accessed through its resolver.
///
/// Registrations are immutable. Returning `false` means allocation failed or
/// an entry with the same name was already finalized; callers should treat
/// that as a bootstrap/materialization error rather than silently replacing an
/// intrinsic identity.
pub fn register_ecmascript_intrinsic<'s>(
    scope: &mut PinScope<'s, '_>,
    global: Local<'s, Object>,
    name: &str,
    constructor: Local<'s, Object>,
    prototype: Local<'s, Object>,
) -> bool {
    let constructors = intrinsic_registry_object(scope, global, ECMASCRIPT_CONSTRUCTORS_SLOT);
    let prototypes = intrinsic_registry_object(scope, global, ECMASCRIPT_PROTOTYPES_SLOT);

    let Some(key) = v8_string(scope, name) else {
        return false;
    };
    if constructors.has_own_property(scope, key.into()) != Some(false)
        || prototypes.has_own_property(scope, key.into()) != Some(false)
    {
        return false;
    }

    if !define_intrinsic(scope, constructors, name, constructor) {
        return false;
    }
    if !define_intrinsic(scope, prototypes, name, prototype) {
        // A failed second definition is only realistically possible after an
        // allocation failure. Leave the constructor entry intact so callers
        // cannot mistake a partially initialized interface for an ambient
        // public-global lookup.
        return false;
    }
    true
}

fn registered_intrinsic<'s>(
    scope: &mut PinScope<'s, '_>,
    global: Local<'s, Object>,
    slot: &str,
    name: &str,
) -> Option<Local<'s, Object>> {
    let registry = get_private_object(scope, global, slot)?;
    let key = v8_string(scope, name)?;
    registry
        .get(scope, key.into())
        .and_then(|value| Local::<Object>::try_from(value).ok())
}

pub fn registered_ecmascript_constructor<'s>(
    scope: &mut PinScope<'s, '_>,
    global: Local<'s, Object>,
    name: &str,
) -> Option<Local<'s, Object>> {
    registered_intrinsic(scope, global, ECMASCRIPT_CONSTRUCTORS_SLOT, name)
}

pub fn registered_ecmascript_prototype<'s>(
    scope: &mut PinScope<'s, '_>,
    global: Local<'s, Object>,
    name: &str,
) -> Option<Local<'s, Object>> {
    registered_intrinsic(scope, global, ECMASCRIPT_PROTOTYPES_SLOT, name)
}

pub fn constructor_object<'s>(
    scope: &mut PinScope<'s, '_>,
    global: Local<'s, Object>,
    name: &str,
) -> Option<Local<'s, Object>> {
    let key = v8_string(scope, name)?;
    global
        .get_real_named_property(scope, key.into())
        .or_else(|| global.get(scope, key.into()))
        .and_then(|value| Local::<Object>::try_from(value).ok())
}

pub fn constructor_prototype_object<'s>(
    scope: &mut PinScope<'s, '_>,
    constructor: Local<'s, Object>,
) -> Option<Local<'s, Object>> {
    constructor
        .get(scope, v8str(scope, "prototype").into())
        .and_then(|value| Local::<Object>::try_from(value).ok())
}

pub fn constructor_prototype<'s>(
    scope: &mut PinScope<'s, '_>,
    global: Local<'s, Object>,
    name: &str,
) -> Option<Local<'s, Object>> {
    constructor_object(scope, global, name)
        .and_then(|ctor| constructor_prototype_object(scope, ctor))
}

pub fn global_constructor_object<'s>(
    scope: &mut PinScope<'s, '_>,
    name: &str,
) -> Option<Local<'s, Object>> {
    if let Some(resolver) = scope
        .get_current_context()
        .get_slot::<RealmWebApiIntrinsicResolver>()
        && let WebApiIntrinsicLookup::Managed(constructor) =
            (resolver.0)(scope, name, WebApiIntrinsicKind::Constructor)
    {
        return constructor;
    }
    let global = scope.get_current_context().global(scope);
    registered_ecmascript_constructor(scope, global, name)
        .or_else(|| constructor_object(scope, global, name))
}

pub fn global_constructor_prototype<'s>(
    scope: &mut PinScope<'s, '_>,
    name: &str,
) -> Option<Local<'s, Object>> {
    if let Some(resolver) = scope
        .get_current_context()
        .get_slot::<RealmWebApiIntrinsicResolver>()
        && let WebApiIntrinsicLookup::Managed(prototype) =
            (resolver.0)(scope, name, WebApiIntrinsicKind::Prototype)
    {
        return prototype;
    }
    let global = scope.get_current_context().global(scope);
    registered_ecmascript_prototype(scope, global, name)
        .or_else(|| constructor_prototype(scope, global, name))
}

#[cfg(test)]
mod tests {
    use std::pin::pin;

    use moli_v8_test_util::ensure_v8;

    use super::{
        ECMASCRIPT_CONSTRUCTORS_SLOT, ECMASCRIPT_PROTOTYPES_SLOT, global_constructor_object,
        global_constructor_prototype, initialize_ecmascript_intrinsic_registry,
        register_ecmascript_intrinsic, registered_ecmascript_constructor,
        registered_ecmascript_prototype,
    };
    use crate::strings::v8str;

    #[test]
    fn registered_intrinsics_survive_public_global_overrides() {
        ensure_v8();
        let mut isolate = v8::Isolate::new(v8::CreateParams::default());
        let scope = 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 global = context.global(scope);

        initialize_ecmascript_intrinsic_registry(scope, global);
        let intrinsic_constructor = v8::Object::new(scope);
        let intrinsic_prototype = v8::Object::new(scope);
        assert!(register_ecmascript_intrinsic(
            scope,
            global,
            "Sample",
            intrinsic_constructor,
            intrinsic_prototype,
        ));

        let public_constructor = v8::Object::new(scope);
        let public_prototype = v8::Object::new(scope);
        assert_eq!(
            public_constructor.set(
                scope,
                v8str(scope, "prototype").into(),
                public_prototype.into(),
            ),
            Some(true),
        );
        assert_eq!(
            global.set(
                scope,
                v8str(scope, "Sample").into(),
                public_constructor.into(),
            ),
            Some(true),
        );

        assert!(
            registered_ecmascript_constructor(scope, global, "Sample")
                .is_some_and(|value| value.strict_equals(intrinsic_constructor.into()))
        );
        assert!(
            registered_ecmascript_prototype(scope, global, "Sample")
                .is_some_and(|value| value.strict_equals(intrinsic_prototype.into()))
        );
        assert!(
            global_constructor_object(scope, "Sample")
                .is_some_and(|value| value.strict_equals(intrinsic_constructor.into()))
        );
        assert!(
            global_constructor_prototype(scope, "Sample")
                .is_some_and(|value| value.strict_equals(intrinsic_prototype.into()))
        );
    }

    #[test]
    fn unregistered_constructors_still_fall_back_to_the_public_global() {
        ensure_v8();
        let mut isolate = v8::Isolate::new(v8::CreateParams::default());
        let scope = 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 global = context.global(scope);

        initialize_ecmascript_intrinsic_registry(scope, global);
        let constructor = v8::Object::new(scope);
        let prototype = v8::Object::new(scope);
        assert_eq!(
            constructor.set(scope, v8str(scope, "prototype").into(), prototype.into()),
            Some(true),
        );
        assert_eq!(
            global.set(scope, v8str(scope, "Fallback").into(), constructor.into()),
            Some(true),
        );

        assert!(
            global_constructor_object(scope, "Fallback")
                .is_some_and(|value| value.strict_equals(constructor.into()))
        );
        assert!(
            global_constructor_prototype(scope, "Fallback")
                .is_some_and(|value| value.strict_equals(prototype.into()))
        );
    }

    #[test]
    fn intrinsic_registrations_are_immutable_and_private() {
        ensure_v8();
        let mut isolate = v8::Isolate::new(v8::CreateParams::default());
        let scope = 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 global = context.global(scope);

        let constructor = v8::Object::new(scope);
        let prototype = v8::Object::new(scope);
        assert!(register_ecmascript_intrinsic(
            scope,
            global,
            "Sample",
            constructor,
            prototype,
        ));
        let replacement_constructor = v8::Object::new(scope);
        let replacement_prototype = v8::Object::new(scope);
        assert!(!register_ecmascript_intrinsic(
            scope,
            global,
            "Sample",
            replacement_constructor,
            replacement_prototype,
        ));

        let names = global
            .get_own_property_names(scope, Default::default())
            .expect("global own property names");
        for index in 0..names.length() {
            let name = names
                .get_index(scope, index)
                .and_then(|value| value.to_string(scope))
                .map(|value| value.to_rust_string_lossy(scope));
            assert_ne!(name.as_deref(), Some(ECMASCRIPT_CONSTRUCTORS_SLOT));
            assert_ne!(name.as_deref(), Some(ECMASCRIPT_PROTOTYPES_SLOT));
        }
    }
}