Skip to content

armgit / moli

Public Imported from GitHub
0

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

16.5 KB
Raw Blame
//! Native frontend commands publish from the renderer, just like Inspector.
//!
//! The pending adapter retains only cancellation and Page-cache bookkeeping.
//! Its wake-up order cannot decide when a successful reply reaches the client.
//! Internal queries deliberately keep their ordinary typed result channel.

mod node;
pub(crate) use node::{NodeReferenceParams, with_backend_node};

use serde_json::json;

use moli_core::page::{CompletedPageCommand, PendingPageCommand};
use moli_core::{RendererNativeCommandResponseGuard, RendererNativeProtocolResponse};
use moli_core::{RendererPageCommand, RendererPageReply};

use super::command_output::CommandOutputPlan;
use crate::conn::{
    BackgroundProtocolEvent, CdpConnection, Cmd, CommandDispatchContext, CommandOwnerScope,
    TargetPageResidenceIdentity,
};

pub(crate) fn unit_response(
    reply: anyhow::Result<RendererPageReply>,
) -> RendererNativeProtocolResponse {
    match reply {
        Ok(RendererPageReply::Unit) => RendererNativeProtocolResponse::success(json!({})),
        Err(error) => RendererNativeProtocolResponse::error(-32000, error.to_string()),
        _ => unreachable!("native Unit command reply"),
    }
}

pub(crate) enum NativeCommandStep {
    Pending(PendingNativeCommand),
    Complete(CommandOutputPlan),
}

type UnpublishedFailureProjection =
    Box<dyn FnOnce(&CdpConnection, String) -> CommandOutputPlan + Send>;

pub(crate) struct PendingNativeCommand {
    // Retain wire routing only; Page settlement uses the exact residence.
    session_id: Option<String>,
    residence: TargetPageResidenceIdentity,
    command_id: u64,
    pending: PendingPageCommand,
    guard: RendererNativeCommandResponseGuard,
    unpublished_failure: Option<UnpublishedFailureProjection>,
}

pub(crate) struct CompletedNativeCommand {
    session_id: Option<String>,
    residence: TargetPageResidenceIdentity,
    pub(crate) command_id: u64,
    result: Result<CompletedPageCommand, String>,
    guard: RendererNativeCommandResponseGuard,
    unpublished_failure: Option<UnpublishedFailureProjection>,
}

impl PendingNativeCommand {
    /// Browser policy may outlive a rejected old attachment. This projection
    /// only runs after publication lost; it cannot replace a committed reply.
    pub(crate) fn on_unpublished_failure(
        mut self,
        project: impl FnOnce(&CdpConnection, String) -> CommandOutputPlan + Send + 'static,
    ) -> Self {
        self.unpublished_failure = Some(Box::new(project));
        self
    }

    pub(crate) fn command_id(&self) -> u64 {
        self.command_id
    }

    pub(crate) fn session_id(&self) -> Option<&str> {
        self.session_id.as_deref()
    }

    pub(crate) async fn wait(self) -> CompletedNativeCommand {
        CompletedNativeCommand {
            session_id: self.session_id,
            residence: self.residence,
            command_id: self.command_id,
            result: self.pending.wait().await.map_err(|error| error.to_string()),
            guard: self.guard,
            unpublished_failure: self.unpublished_failure,
        }
    }
}

impl CompletedNativeCommand {
    pub(crate) fn session_id(&self) -> Option<&str> {
        self.session_id.as_deref()
    }

    pub(crate) async fn complete(
        self,
        conn: &mut CdpConnection,
        context: &mut CommandDispatchContext,
    ) -> CommandOutputPlan {
        match self.result {
            Ok(completed) => {
                let output = conn.settle_page_command_turn_for_owner(&self.residence, completed);
                let completion = context.consume_renderer_command_turn_output(output);
                assert!(completion.native_response_was_published());
                CommandOutputPlan::default()
            }
            Err(error) => match self.guard.cancel_or_published().await {
                Some(fence) => {
                    context.set_renderer_output_predecessor(fence);
                    CommandOutputPlan::default()
                }
                None => match self.unpublished_failure {
                    Some(project) => project(conn, error),
                    None => CommandOutputPlan::error(-32000, error),
                },
            },
        }
    }
}

pub(crate) fn start(
    conn: &mut CdpConnection,
    cmd: &Cmd<'_>,
    operation: RendererPageCommand,
    project: impl FnOnce(anyhow::Result<RendererPageReply>) -> RendererNativeProtocolResponse
    + Send
    + 'static,
) -> NativeCommandStep {
    start_operation(
        conn,
        cmd,
        moli_core::RendererNativeOperation::new(operation, project),
    )
}

pub(crate) fn start_operation(
    conn: &mut CdpConnection,
    cmd: &Cmd<'_>,
    operation: moli_core::RendererNativeOperation,
) -> NativeCommandStep {
    let owner = CommandOwnerScope::capture(conn, cmd.session_id);
    let Some(residence) = conn.target_page_residence_identity_for_owner(&owner) else {
        return NativeCommandStep::Complete(CommandOutputPlan::error(-32000, "NoDocumentLoaded"));
    };
    let page = match conn.loaded_page_mut_for_protocol_access_for_owner(&owner) {
        Ok(page) => page,
        Err(error) => return NativeCommandStep::Complete(CommandOutputPlan::error(-32000, error)),
    };
    let command_id = cmd.id.expect("a native frontend command has a call id");
    match page.start_cdp_call(command_id, cmd.session_id, operation) {
        Ok((pending, guard)) => NativeCommandStep::Pending(PendingNativeCommand {
            session_id: cmd.session_id.map(str::to_owned),
            residence,
            command_id,
            pending,
            guard,
            unpublished_failure: None,
        }),
        Err(error) => {
            NativeCommandStep::Complete(CommandOutputPlan::error(-32000, error.to_string()))
        }
    }
}

/// Admit only frontend calls with an accessible document and renderer.
/// Return the checked attachment so preparation can retain its replay identity.
/// Enqueue revalidates access after preparation, which may update Browser policy.
pub(crate) fn frontend_attachment(
    conn: &mut CdpConnection,
    cmd: &Cmd<'_>,
) -> Option<moli_page_types::RendererAgentAttachmentId> {
    if cmd.id.is_none()
        || cmd.terminal_response_delivery()
            != moli_page_types::RendererInspectorResponseDelivery::SessionSink
    {
        return None;
    }
    conn.loaded_page_mut_for_protocol_access_for_owner(&CommandOwnerScope::capture(
        conn,
        cmd.session_id,
    ))
    .ok()?
    .renderer_agent_attachment_id()
}

pub(crate) fn try_start(conn: &mut CdpConnection, cmd: &Cmd<'_>) -> Option<NativeCommandStep> {
    let start: fn(&mut CdpConnection, &Cmd<'_>) -> Option<NativeCommandStep> =
        match cmd.method.split_once('.')?.0 {
            "DOMDebugger" => super::dom_debugger::native::try_start,
            "Autofill" => super::autofill::try_start_native_command,
            "WebMCP" => super::web_mcp::try_start_native_command,
            "Page" => super::page::native::try_start,
            "DOM" => super::dom::try_start_native_command,
            "DOMSnapshot" => super::dom_snapshot::try_start_native_command,
            "CSS" => super::css::native::try_start,
            "Accessibility" => super::accessibility::native::try_start,
            "Runtime" => super::runtime::try_start_native_command,
            _ => return None,
        };
    frontend_attachment(conn, cmd)?;
    start(conn, cmd)
}

/// Apply Browser mirrors at the same ordered boundary as the response. The
/// Snapshot results survive retirement; document caches and node events are
/// valid only for the exact attachment that produced them. Runtime.enable also
/// commits session state and projects its frozen replay here, or fails the
/// terminal if its original owner has retired.
pub(crate) fn project_terminal_for_owner(
    conn: &mut CdpConnection,
    publication_owner: Option<&CommandOwnerScope>,
    mut terminal: moli_core::RendererNativeCommandTerminal,
) -> Vec<BackgroundProtocolEvent> {
    let owner = publication_owner.map(|owner| match terminal.session.wire_session_id() {
        Some(session) => CommandOwnerScope::for_session(session),
        None => owner.clone(),
    });
    let owner = owner.filter(|owner| {
        conn.runtime_session_owner_slot_for_owner(owner)
            .is_some_and(|slot| {
                slot.has_loaded_page()
                    && slot
                        .current_renderer_attachment()
                        .is_some_and(|attachment| attachment.id() == terminal.attachment_id)
            })
    });
    let response = &mut terminal.reply;
    let mut events = Vec::new();
    if owner.is_none() {
        response.notifications.clear();
    }
    for update in std::mem::take(&mut response.state_updates) {
        match (owner.as_ref(), update) {
            (
                owner,
                moli_core::RendererNativeProtocolStateUpdate::RuntimeBinding {
                    binding,
                    remove,
                    output,
                },
            ) => {
                match super::runtime::project_binding_terminal(
                    conn, owner, binding, remove, *output,
                ) {
                    Ok(replay) => events.extend(replay),
                    Err(message) => {
                        response.notifications.clear();
                        response.result = Err(moli_core::RendererNativeProtocolError {
                            code: -32000,
                            message,
                        });
                    }
                }
            }
            (
                owner,
                moli_core::RendererNativeProtocolStateUpdate::RuntimeSubscription {
                    enabled,
                    output,
                },
            ) => {
                match super::runtime::project_subscription_terminal(conn, owner, enabled, *output) {
                    Ok(replay) => events.extend(replay),
                    Err(message) => {
                        response.notifications.clear();
                        response.result = Err(moli_core::RendererNativeProtocolError {
                            code: -32000,
                            message,
                        });
                    }
                }
            }
            (Some(owner), moli_core::RendererNativeProtocolStateUpdate::WebMcpEnabled(enabled)) => {
                conn.with_target_devtools_session_state_for_owner_mut(owner, |state| {
                    state.web_mcp_enabled = enabled
                });
            }
            (
                Some(owner),
                moli_core::RendererNativeProtocolStateUpdate::RemoteObjects { object_group },
            ) => {
                let Ok(result) = &response.result else {
                    continue;
                };
                if let Some(group) = object_group {
                    conn.register_runtime_remote_object_ids_from_value_for_owner_with_group(
                        owner, result, &group,
                    );
                } else {
                    conn.register_runtime_remote_object_ids_from_value_for_owner(owner, result);
                }
            }
            (
                Some(owner),
                moli_core::RendererNativeProtocolStateUpdate::DomRemoteObjectNode {
                    object_id,
                    node,
                },
            ) => {
                super::dom::cache_dom_remote_object_node_for_owner(conn, owner, object_id, node);
            }
            (None, _) => {}
        }
    }
    events.extend(project_terminal(terminal));
    events
}

/// Bounded projection of a terminal already committed by its renderer owner.
/// It intentionally needs no live Page: replacing a document cannot change
/// an earlier snapshot or steal the original frontend call's response.
pub(crate) fn project_terminal(
    terminal: moli_core::RendererNativeCommandTerminal,
) -> Vec<BackgroundProtocolEvent> {
    let mut events = Vec::new();
    for notification in terminal.reply.notifications {
        let session = terminal.session.wire_session_id();
        events.push(match notification {
            moli_core::RendererNativeProtocolNotification::Json(mut notification) => {
                if let Some(session) = session {
                    notification["sessionId"] = json!(session);
                }
                BackgroundProtocolEvent::immediate(notification)
            }
            moli_core::RendererNativeProtocolNotification::DomSetChildNodes {
                parent_node_id,
                nodes,
            } => BackgroundProtocolEvent::dom_set_child_nodes(session, parent_node_id, nodes),
        });
    }
    let mut message = json!({ "id": terminal.command_id.get() });
    match terminal.reply.result {
        Ok(result) => message["result"] = result,
        Err(error) => message["error"] = json!({ "code": error.code, "message": error.message }),
    }
    if let Some(session) = terminal.session.wire_session_id() {
        message["sessionId"] = json!(session);
    }
    events.push(BackgroundProtocolEvent::immediate(message));
    events
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn retired_native_terminal_keeps_response_and_discards_document_side_effects() {
        use moli_core::{
            RendererNativeCommandTerminal, RendererNativeProtocolNotification,
            RendererNativeProtocolStateUpdate,
        };
        use moli_page_types::{DevToolsSessionKey, FrontendCommandId, RendererAgentAttachmentId};
        let mut ctx = crate::testing::TestContext::new();
        let mut response = RendererNativeProtocolResponse::success(
            json!({"object": {"objectId": "retired-object"}}),
        );
        response
            .notifications
            .push(RendererNativeProtocolNotification::DomSetChildNodes {
                parent_node_id: 3,
                nodes: vec![json!({"nodeId": 7})],
            });
        response
            .state_updates
            .push(RendererNativeProtocolStateUpdate::DomRemoteObjectNode {
                object_id: "retired-object".to_owned(),
                node: json!({"nodeId": 7}),
            });
        let messages = project_terminal_for_owner(
            &mut ctx.conn,
            None,
            RendererNativeCommandTerminal {
                command_id: FrontendCommandId::new(42),
                session: DevToolsSessionKey::Attached("retired-session".to_owned()),
                attachment_id: RendererAgentAttachmentId::allocate(),
                reply: response,
            },
        );
        assert_eq!(
            messages.len(),
            1,
            "a retired document cannot emit node notifications"
        );
        assert_eq!(
            messages.into_iter().next().unwrap().into_parts().0,
            json!({
                "id": 42, "sessionId": "retired-session", "result": {"object": {"objectId": "retired-object"}},
            })
        );
        assert!(
            ctx.conn.browser_context.is_none(),
            "projection cannot recreate a retired owner"
        );
    }

    #[test]
    fn native_dom_notification_keeps_automation_sidecar_before_terminal() {
        use moli_core::{RendererNativeCommandTerminal, RendererNativeProtocolNotification};
        use moli_page_types::{DevToolsSessionKey, FrontendCommandId, RendererAgentAttachmentId};
        let nodes = vec![json!({"nodeId": 7, "nodeName": "BUTTON"})];
        let mut response = RendererNativeProtocolResponse::success(json!({"nodeId": 7}));
        response
            .notifications
            .push(RendererNativeProtocolNotification::DomSetChildNodes {
                parent_node_id: 3,
                nodes: nodes.clone(),
            });
        let mut events = project_terminal(RendererNativeCommandTerminal {
            command_id: FrontendCommandId::new(42),
            session: DevToolsSessionKey::Attached("SID-native".to_owned()),
            attachment_id: RendererAgentAttachmentId::allocate(),
            reply: response,
        })
        .into_iter();
        let (event, sidecar) = events.next().unwrap().into_parts();
        assert_eq!(event["method"], "DOM.setChildNodes");
        assert_eq!(event["sessionId"], "SID-native");
        let Some(crate::automation::AutomationEvent::DomSetChildNodes(sidecar)) = sidecar else {
            panic!("native DOM notifications retain their typed automation event");
        };
        assert_eq!(sidecar.parent_node_id, 3);
        assert_eq!(sidecar.nodes, nodes);
        let (terminal, _) = events.next().unwrap().into_parts();
        assert_eq!(terminal["id"], 42);
        assert_eq!(terminal["sessionId"], "SID-native");
        assert_eq!(terminal["result"]["nodeId"], 7);
        assert!(events.next().is_none());
    }
}