using System.Collections.Frozen;
namespace Febe.Browser.Cdp;
///
/// The CDP commands Febe may send (spec §6.1). Everything else is refused before it reaches the browser.
/// Adding a command requires a line in docs/decisioni.md with the reason.
///
public static class CdpCommandPolicy
{
/// The allowlist of spec §6.1, grouped by purpose.
public static FrozenSet Allowed { get; } = FrozenSet.Create(
StringComparer.Ordinal,
// Navigate and read the state (Runtime.evaluate read-only only, see ReadOnlyScriptGuard).
"Page.enable",
"Page.navigate",
"Page.getFrameTree",
"Runtime.evaluate",
// Capture responses.
"Network.enable",
"Network.getResponseBody",
// Gestures.
"Input.dispatchMouseEvent",
"Input.dispatchKeyEvent",
// Download files.
"Network.loadNetworkResource",
"IO.read",
"IO.close",
// Remote view and preview.
"Page.startScreencast",
"Page.screencastFrameAck",
"Page.stopScreencast",
"Page.captureScreenshot",
// Check the session: existence of the session cookie only.
"Network.getCookies");
/// Commands explicitly forbidden by spec §2 rule 2 and §6.1, refused with a specific message.
public static FrozenSet ForbiddenCommands { get; } = FrozenSet.Create(
StringComparer.Ordinal,
"Network.setUserAgentOverride",
"Network.setExtraHTTPHeaders",
"Page.addScriptToEvaluateOnNewDocument");
/// Whole domains that are forbidden (spec §6.1).
public static IReadOnlyList ForbiddenDomains { get; } = ["Emulation", "Fetch"];
public static bool IsAllowed(string method) => method is not null && Allowed.Contains(method);
public static bool IsExplicitlyForbidden(string method)
{
if (string.IsNullOrEmpty(method))
{
return false;
}
if (ForbiddenCommands.Contains(method))
{
return true;
}
var dot = method.IndexOf('.', StringComparison.Ordinal);
var domain = dot < 0 ? method : method[..dot];
return ForbiddenDomains.Contains(domain, StringComparer.Ordinal);
}
/// Throws unless is on the allowlist.
public static void EnsureAllowed(string method)
{
if (IsExplicitlyForbidden(method))
{
throw new CdpCommandNotAllowedException(
method,
$"Il comando CDP «{method}» è vietato: altera ciò che il browser dichiara o le richieste che invia (specifica §2, regola 2; §6.1).");
}
if (!IsAllowed(method))
{
throw new CdpCommandNotAllowedException(
method,
$"Il comando CDP «{method}» non è nell'elenco dei comandi ammessi (specifica §6.1). Ogni aggiunta va motivata in docs/decisioni.md.");
}
}
}
/// A CDP command was refused by and never sent.
public sealed class CdpCommandNotAllowedException(string method, string message) : InvalidOperationException(message)
{
public string Method { get; } = method;
}
/// The browser answered a command with an error. The message never contains parameters.
public sealed class CdpCommandException(string method, int code, string browserMessage)
: Exception($"Il comando CDP «{method}» è fallito: {browserMessage} (codice {code}).")
{
public string Method { get; } = method;
public int Code { get; } = code;
public string BrowserMessage { get; } = browserMessage;
}
/// The connection to the browser is closed (browser exited, crashed or is restarting).
public sealed class CdpDisconnectedException : Exception
{
public CdpDisconnectedException()
: base("Il collegamento con il browser è chiuso.")
{
}
public CdpDisconnectedException(string message)
: base(message)
{
}
public CdpDisconnectedException(string message, Exception? inner)
: base(message, inner)
{
}
}