Skip to content

armgit / moli

Public Imported from GitHub
0

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

17.0 KB
Raw Blame
//! Ready native replies share the renderer's producer-ordered output journal.
//!
//! The adapter chooses terminal delivery at admission and freezes Browser
//! metadata here. Internal queries continue to return their typed values to
//! their continuation; they never acquire this frontend publication capability.

use std::convert::Infallible;

use moli_page_types::{DevToolsSessionKey, FrontendCommandId, RendererAgentAttachmentId};

use crate::devtools::command::RendererDevToolsMainNestedDispatch;

use super::{
    PendingRendererOutputRecord, RendererCommandResponseAuthority, RendererCommandResponseLease,
    RendererOutputFence, RendererOutputItem, RendererTurnOutputJournal,
};
use crate::runtime::{RendererPageCommand, RendererPageReply};

/// A resolved native frontend reply. The projection captures only immutable
/// protocol metadata at admission; it cannot borrow a Browser or live Page.
/// Both success and backend errors are published at the renderer boundary.
#[derive(Clone, Debug, PartialEq)]
pub struct RendererNativeProtocolResponse {
    pub result: Result<serde_json::Value, RendererNativeProtocolError>,
    pub notifications: Vec<RendererNativeProtocolNotification>,
    pub state_updates: Vec<RendererNativeProtocolStateUpdate>,
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RendererNativeProtocolError {
    pub code: i32,
    pub message: String,
}

/// Native notifications keep the semantic sidecars needed by non-CDP
/// observers. JSON-only events and DOM automation events share one ordered
/// prefix; neither can be reconstructed from mutable Page state at drain.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum RendererNativeProtocolNotification {
    Json(serde_json::Value),
    DomSetChildNodes {
        parent_node_id: u32,
        nodes: Vec<serde_json::Value>,
    },
}

impl From<serde_json::Value> for RendererNativeProtocolNotification {
    fn from(value: serde_json::Value) -> Self {
        Self::Json(value)
    }
}

impl RendererNativeProtocolResponse {
    pub fn success(result: serde_json::Value) -> Self {
        Self {
            result: Ok(result),
            notifications: Vec::new(),
            state_updates: Vec::new(),
        }
    }

    pub fn error(code: i32, message: impl Into<String>) -> Self {
        Self {
            result: Err(RendererNativeProtocolError {
                code,
                message: message.into(),
            }),
            notifications: Vec::new(),
            state_updates: Vec::new(),
        }
    }
}

/// Browser mirrors committed with a native terminal. These are frozen data,
/// never callbacks into a live Page. Attachment retirement discards document
/// updates; command-local replay can instead fail the terminal at projection.
#[derive(Clone, Debug, PartialEq)]
pub enum RendererNativeProtocolStateUpdate {
    /// Frozen V8 replay and state, projected by the ordered protocol consumer
    /// before this terminal. Retirement can still turn enable into an error;
    /// neither the adapter waiter nor a replacement attachment owns that choice.
    RuntimeSubscription {
        enabled: bool,
        output: Box<crate::runtime::RendererRuntimeCommandOutput>,
    },
    /// Persistent binding mutations share the subscription's ordered ingress;
    /// adapter completion cannot restore bindings cleared by a later disable.
    RuntimeBinding {
        binding: crate::protocol_types::RuntimeBindingRegistration,
        remove: bool,
        output: Box<crate::runtime::RendererRuntimeCommandOutput>,
    },
    WebMcpEnabled(bool),
    /// Register object IDs from the successful terminal result before delivery.
    /// The reply already owns the payload; this update only retains its group.
    RemoteObjects {
        object_group: Option<String>,
    },
    DomRemoteObjectNode {
        object_id: String,
        node: serde_json::Value,
    },
}

type NativeResponseProjection = Box<
    dyn FnOnce(
            anyhow::Result<RendererPageReply>,
            &crate::runtime::RendererPageState,
        ) -> RendererNativeProtocolResponse
        + Send,
>;

/// A complete reply to the original frontend call, not a live Page observation.
/// Its metadata remains valid even if the Page is replaced before projection.
/// The frontend router uses its globally allocated call id to deliver it once.
#[derive(Clone, Debug, PartialEq)]
pub struct RendererNativeCommandTerminal {
    pub command_id: FrontendCommandId,
    pub session: DevToolsSessionKey,
    pub attachment_id: RendererAgentAttachmentId,
    pub reply: RendererNativeProtocolResponse,
}

type Authority = RendererCommandResponseAuthority<Infallible, RendererOutputFence>;
type Lease = RendererCommandResponseLease<Infallible, RendererOutputFence>;

/// Kept by the adapter continuation until its native operation settles.
/// Dropping a pending continuation cancels publication. Dropping it after the
/// producer claimed completion cannot undo the already committed terminal.
pub struct RendererNativeCommandResponseGuard {
    authority: Authority,
    publication: Option<tokio::sync::oneshot::Receiver<RendererOutputFence>>,
}

impl RendererNativeCommandResponseGuard {
    /// After losing the adapter result, cancel only work that has not claimed
    /// completion. If publication won that race, return its exact fence so the
    /// adapter cannot generate a second terminal error. This never delays the
    /// renderer or allocates a journal slot for unfinished work.
    pub async fn cancel_or_published(mut self) -> Option<RendererOutputFence> {
        self.authority.cancel();
        self.publication
            .take()
            .expect("native publication receipt is consumed once")
            .await
            .ok()
    }
}

impl Drop for RendererNativeCommandResponseGuard {
    fn drop(&mut self) {
        self.authority.cancel();
    }
}

/// Native frontend operations use their ordinary backend dispatch. The
/// synchronous projection freezes the complete response before it enters
/// the common journal, without involving an adapter waiter.
pub struct RendererCdpCall {
    pub(crate) operation: RendererNativeOperation,
    response: RendererNativeCommandResponse,
}

struct RendererNativeCommandResponse {
    command_id: FrontendCommandId,
    session: DevToolsSessionKey,
    attachment_id: RendererAgentAttachmentId,
    lease: Lease,
}

impl RendererCdpCall {
    pub fn new(
        command_id: FrontendCommandId,
        session: DevToolsSessionKey,
        attachment_id: RendererAgentAttachmentId,
        operation: RendererNativeOperation,
    ) -> (Self, RendererNativeCommandResponseGuard) {
        let authority = Authority::session();
        let lease = authority
            .activate()
            .expect("new native response authority is open");
        let publication = lease
            .take_session_response_settlement_receiver()
            .expect("native frontend calls retain a publication receipt");
        (
            Self {
                operation,
                response: RendererNativeCommandResponse {
                    command_id,
                    session,
                    attachment_id,
                    lease,
                },
            },
            RendererNativeCommandResponseGuard {
                authority,
                publication: Some(publication),
            },
        )
    }
}

/// Created by the native backend with fully resolved payload, then published
/// by command-turn settlement after earlier facts have reached the journal.
/// Creating this value neither reserves a sequence nor blocks later commands.
pub struct RendererNativeCommandReadyResponse {
    response: RendererNativeCommandResponse,
    reply: NativeReadyReply,
    journal: RendererTurnOutputJournal,
}

impl RendererNativeCommandReadyResponse {
    pub(crate) fn publish(
        self,
        page_state: &crate::runtime::RendererPageState,
    ) -> anyhow::Result<RendererOutputFence> {
        let Self {
            response,
            reply,
            journal,
        } = self;
        let receipt = response
            .lease
            .claim_session()
            .map_err(|()| anyhow::anyhow!("native response was canceled"))?
            .expect("native frontend calls retain a publication receipt");
        // Keep the backend reply alive through owner lifecycle settlement.
        // In particular input navigation is reconciled before projection.
        let reply = match reply {
            NativeReadyReply::Resolved(reply) => reply,
            NativeReadyReply::Projected { reply, project } => project(reply, page_state),
        };
        let terminal = RendererNativeCommandTerminal {
            command_id: response.command_id,
            session: response.session,
            attachment_id: response.attachment_id,
            reply,
        };
        let fence = journal
            .try_publish_terminal_records_and_declare_fence([
                PendingRendererOutputRecord::from_parts(
                    None,
                    RendererOutputItem::NativeTerminal(terminal),
                ),
            ])
            .ok_or_else(|| anyhow::anyhow!("native response output stream closed"))?;
        let _ = receipt.send(fence.clone());
        Ok(fence)
    }
}

/// A bounded native handler. Lookups may select the next backend operation
/// inside the same renderer turn; only the terminal projection can publish a
/// frontend response. These continuations never await Browser state or I/O.
pub struct RendererNativeOperation {
    // Breaks the Native call -> operation -> page command type cycle.
    pub(crate) command: Box<RendererPageCommand>,
    completion: NativeOperationCompletion,
    nested_dispatch: RendererDevToolsMainNestedDispatch,
}

pub enum RendererNativeOperationStep {
    Continue(RendererNativeOperation),
    Complete(RendererNativeProtocolResponse),
}

enum NativeOperationCompletion {
    Terminal(NativeResponseProjection),
    Lookup(
        Box<dyn FnOnce(anyhow::Result<RendererPageReply>) -> RendererNativeOperationStep + Send>,
    ),
}

impl RendererNativeOperation {
    pub fn new(
        command: RendererPageCommand,
        project: impl FnOnce(anyhow::Result<RendererPageReply>) -> RendererNativeProtocolResponse
        + Send
        + 'static,
    ) -> Self {
        Self::with_page_state(command, move |reply, _state| project(reply))
    }

    /// A terminal may use the immutable state captured by this renderer turn.
    /// This avoids consulting a lagging Browser Page mirror, and ensures the
    /// reply and its earlier observations describe the same completed turn.
    pub fn with_page_state(
        command: RendererPageCommand,
        project: impl FnOnce(
            anyhow::Result<RendererPageReply>,
            &crate::runtime::RendererPageState,
        ) -> RendererNativeProtocolResponse
        + Send
        + 'static,
    ) -> Self {
        let nested_dispatch = match &command {
            RendererPageCommand::Inspector(envelope)
                if envelope.runtime_binding_removal_name().is_some() =>
            {
                RendererDevToolsMainNestedDispatch::NativeInspectorSession
            }
            _ if command.nested_dispatch() == RendererDevToolsMainNestedDispatch::PageAgent => {
                RendererDevToolsMainNestedDispatch::PageAgent
            }
            _ => RendererDevToolsMainNestedDispatch::OwnerOnly,
        };
        Self {
            nested_dispatch,
            command: Box::new(command),
            completion: NativeOperationCompletion::Terminal(Box::new(project)),
        }
    }

    /// An opaque continuation may enter the isolate. Keep the entire chain
    /// on the owner turn unless its author explicitly supplies a native-only
    /// continuation with `then_on_nested_main`.
    pub fn then(
        command: RendererPageCommand,
        next: impl FnOnce(anyhow::Result<RendererPageReply>) -> RendererNativeOperationStep
        + Send
        + 'static,
    ) -> Self {
        Self {
            command: Box::new(command),
            completion: NativeOperationCompletion::Lookup(Box::new(next)),
            nested_dispatch: RendererDevToolsMainNestedDispatch::OwnerOnly,
        }
    }

    /// The lookup and every continuation use the existing nested Page-agent
    /// boundary. They must not acquire an owner-only Inspector/isolate borrow.
    pub fn then_on_nested_main(
        command: RendererPageCommand,
        next: impl FnOnce(anyhow::Result<RendererPageReply>) -> RendererNativeOperationStep
        + Send
        + 'static,
    ) -> Self {
        let nested_dispatch =
            if command.nested_dispatch() == RendererDevToolsMainNestedDispatch::PageAgent {
                RendererDevToolsMainNestedDispatch::PageAgent
            } else {
                RendererDevToolsMainNestedDispatch::OwnerOnly
            };
        let mut operation = Self::then(command, next);
        operation.nested_dispatch = nested_dispatch;
        operation
    }

    /// Preserve an enclosing handler's isolate-entry requirement even when
    /// its first lookup happens to be a native node/realm query.
    pub fn require_owner_turn(mut self) -> Self {
        self.nested_dispatch = RendererDevToolsMainNestedDispatch::OwnerOnly;
        self
    }

    pub(crate) fn nested_dispatch(&self) -> RendererDevToolsMainNestedDispatch {
        self.nested_dispatch
    }
}

enum NativeReadyReply {
    Resolved(RendererNativeProtocolResponse),
    Projected {
        reply: anyhow::Result<RendererPageReply>,
        project: NativeResponseProjection,
    },
}

impl RendererCdpCall {
    pub(crate) fn runtime_binding_removal_name(&self) -> &str {
        let RendererPageCommand::Inspector(envelope) = self.operation.command.as_ref() else {
            unreachable!("nested native Inspector dispatch requires an Inspector payload")
        };
        envelope
            .runtime_binding_removal_name()
            .expect("only removeBinding supports nested native Inspector dispatch")
    }

    pub(crate) fn into_runtime_binding_removal_commit(
        mut self,
        output: Result<crate::runtime::RendererRuntimeCommandOutput, String>,
    ) -> RendererPageCommand {
        let RendererPageCommand::Inspector(envelope) = *self.operation.command else {
            unreachable!("nested native Inspector dispatch requires an Inspector payload")
        };
        self.operation.command = Box::new(RendererPageCommand::Inspector(
            envelope.into_runtime_binding_removal_commit(output),
        ));
        self.operation.nested_dispatch = RendererDevToolsMainNestedDispatch::PageAgent;
        // Keep the original response lease and terminal projection. Neither
        // the V8 response capture nor the adapter can publish another reply.
        RendererPageCommand::Native(self)
    }

    pub(crate) fn dispatch(
        self,
        vm: &mut crate::runtime::PageVm,
    ) -> RendererNativeCommandReadyResponse {
        let Self {
            mut operation,
            response,
        } = self;
        let nested_main =
            operation.nested_dispatch == RendererDevToolsMainNestedDispatch::PageAgent;
        let reply = loop {
            // A lookup may construct another Inspector operation. Bind
            // each one to the attachment captured for the original call.
            operation
                .command
                .bind_inspector_attachment(response.attachment_id);
            let reply = vm.dispatch_renderer_page_command(*operation.command);
            match operation.completion {
                NativeOperationCompletion::Terminal(project) => {
                    break NativeReadyReply::Projected { reply, project };
                }
                NativeOperationCompletion::Lookup(next) => match next(reply) {
                    RendererNativeOperationStep::Continue(next) => {
                        assert!(
                            !nested_main
                                || next.nested_dispatch
                                    == RendererDevToolsMainNestedDispatch::PageAgent,
                            "a nested native continuation cannot acquire an owner-only isolate"
                        );
                        operation = next;
                    }
                    RendererNativeOperationStep::Complete(reply) => {
                        break NativeReadyReply::Resolved(reply);
                    }
                },
            }
        };
        RendererNativeCommandReadyResponse {
            response,
            reply,
            journal: vm.vm().renderer_command_output_journal(),
        }
    }
}

impl RendererNativeCommandReadyResponse {
    pub(crate) fn input_dispatch_outcome(
        &self,
    ) -> Option<&crate::runtime::RendererInputDispatchOutcome> {
        match &self.reply {
            NativeReadyReply::Projected {
                reply: Ok(reply), ..
            } => reply.input_dispatch_outcome(),
            _ => None,
        }
    }

    pub(crate) fn input_dispatch_outcome_mut(
        &mut self,
    ) -> Option<&mut crate::runtime::RendererInputDispatchOutcome> {
        match &mut self.reply {
            NativeReadyReply::Projected {
                reply: Ok(reply), ..
            } => reply.input_dispatch_outcome_mut(),
            _ => None,
        }
    }
}