ff-rdp-cli 0.2.0

CLI for Firefox Remote Debugging Protocol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

use std::time::Duration;

use ff_rdp_core::{
    ActorId, ProtocolError, RdpConnection, RdpTransport, RootActor, TabActor, TargetInfo,
};

use crate::cli::args::Cli;
use crate::daemon::client::{ConnectionTarget, resolve_connection_target};
use crate::error::AppError;

/// Shared state after connecting to Firefox and resolving a tab target.
pub struct ConnectedTab {
    connection: RdpConnection,
    pub(crate) target: TargetInfo,
    tab_actor: ActorId,
    /// Whether this connection goes through the daemon proxy.
    pub(crate) via_daemon: bool,
}

/// Connect to Firefox (directly or via daemon), resolve the target tab, and
/// call `getTarget` on it.
///
/// When a daemon is available, the CLI connects to the daemon's proxy port on
/// localhost.  The daemon transparently forwards RDP frames, so the rest of
/// the protocol handshake is identical.
pub fn connect_and_get_target(cli: &Cli) -> Result<ConnectedTab, AppError> {
    let target = resolve_connection_target(&cli.host, cli.port, cli.daemon_timeout, cli.no_daemon);

    let (connect_host, connect_port, via_daemon, deferred_warning) = match target {
        ConnectionTarget::Daemon { port } => ("127.0.0.1".to_owned(), port, true, None),
        ConnectionTarget::Direct { deferred_warning } => {
            (cli.host.clone(), cli.port, false, deferred_warning)
        }
    };

    let connection = connect_to_firefox(&connect_host, connect_port, cli, via_daemon)
        .inspect_err(|_| {
            // The direct fallback failed too — surface the original
            // daemon-side warning alongside the connection error so the user
            // sees the full picture.
            if let Some(w) = &deferred_warning {
                eprintln!("{w}");
            }
        })?;

    handshake_and_resolve_tab(connection, cli, via_daemon)
}

/// Like [`connect_and_get_target`] but always bypasses the daemon and
/// connects directly to Firefox.  Use this for commands (e.g. screenshot)
/// whose protocol interactions are incompatible with the daemon proxy.
pub fn connect_direct(cli: &Cli) -> Result<ConnectedTab, AppError> {
    let connection = connect_to_firefox(&cli.host, cli.port, cli, false)?;

    handshake_and_resolve_tab(connection, cli, false)
}

/// Establish a TCP connection to Firefox (or daemon proxy) and produce
/// user-friendly errors on failure.
fn connect_to_firefox(
    host: &str,
    port: u16,
    cli: &Cli,
    via_daemon: bool,
) -> Result<RdpConnection, AppError> {
    RdpConnection::connect(host, port, Duration::from_millis(cli.timeout)).map_err(|e| match e {
        ProtocolError::ConnectionFailed(_) | ProtocolError::Timeout if !via_daemon => {
            AppError::User(format!(
                "could not connect to Firefox at {}:{} — is Firefox running with --start-debugger-server {}?\n\
                 hint: run `ff-rdp doctor` for a full diagnostic, or `ff-rdp launch` to start Firefox with debugging enabled.",
                cli.host, cli.port, cli.port
            ))
        }
        ProtocolError::ConnectionFailed(_) | ProtocolError::Timeout if via_daemon => {
            AppError::User(format!(
                "could not connect to daemon on port {port} — try --no-daemon to connect directly to Firefox.\n\
                 hint: run `ff-rdp doctor` to inspect daemon health."
            ))
        }
        other => AppError::from(other),
    })
}

/// Run the RDP handshake: list tabs, resolve the target tab, call `getTarget`.
fn handshake_and_resolve_tab(
    mut connection: RdpConnection,
    cli: &Cli,
    via_daemon: bool,
) -> Result<ConnectedTab, AppError> {
    connection.warn_if_version_unsupported();

    crate::connection_meta::remember_version(connection.firefox_version());

    let tabs = RootActor::list_tabs(connection.transport_mut()).map_err(AppError::from)?;

    let tab = crate::tab_target::resolve_tab_with_context(
        &tabs,
        cli.tab.as_deref(),
        cli.tab_id.as_deref(),
        &cli.host,
        cli.port,
    )?;
    let tab_actor = tab.actor.clone();

    let target_info =
        TabActor::get_target(connection.transport_mut(), &tab_actor).map_err(AppError::from)?;

    Ok(ConnectedTab {
        connection,
        target: target_info,
        tab_actor,
        via_daemon,
    })
}

impl ConnectedTab {
    pub fn transport_mut(&mut self) -> &mut RdpTransport {
        self.connection.transport_mut()
    }

    pub fn target_tab_actor(&self) -> &ActorId {
        &self.tab_actor
    }
}