From 925141bb37f8c6b97904302ab6bd8bbcac1f5a79 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 13 Oct 2026 15:51:02 +0000 Subject: [PATCH] Strato browser (M0/M2): client CDP con elenco dei comandi ammessi, ChromiumProcessHost e Xvfb sorvegliati, gesti umani, mappa dei bersagli, cattura delle risposte, segnali di arresto, scaricamento dal browser, vista remota, distribuzioni del ritmo; prove unitarie e d'insieme con Chromium su Xvfb; esito locale di S5 e S6 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Mzbb6zeFTjT6Rp8b92AVkA --- docs/sonda/esito-locale.md | 93 ++++ src/Febe.Browser/Capture/ResponseTap.cs | 440 ++++++++++++++++++ src/Febe.Browser/Cdp/CdpClient.cs | 431 +++++++++++++++++ src/Febe.Browser/Cdp/CdpCommandPolicy.cs | 119 +++++ src/Febe.Browser/Cdp/CdpPageExtensions.cs | 121 +++++ src/Febe.Browser/Cdp/CdpTargetDiscovery.cs | 131 ++++++ src/Febe.Browser/Cdp/ReadOnlyScriptGuard.cs | 48 ++ .../Cdp/ReconnectingCdpSession.cs | 131 ++++++ src/Febe.Browser/Diagnostics/IBrowserLog.cs | 48 ++ .../Download/BrowserFileFetcher.cs | 162 +++++++ src/Febe.Browser/Gestures/GestureSettings.cs | 82 ++++ src/Febe.Browser/Gestures/HumanGestures.cs | 381 +++++++++++++++ src/Febe.Browser/Gestures/Keyboard.cs | 177 +++++++ .../Hosting/ChromiumCommandLine.cs | 182 ++++++++ .../Hosting/ChromiumProcessHost.cs | 307 ++++++++++++ src/Febe.Browser/Hosting/HostingHelpers.cs | 157 +++++++ src/Febe.Browser/Hosting/SupervisedProcess.cs | 440 ++++++++++++++++++ src/Febe.Browser/Hosting/XvfbProcess.cs | 204 ++++++++ .../RemoteView/RemoteViewSession.cs | 253 ++++++++++ .../RemoteView/ScreencastSession.cs | 225 +++++++++ src/Febe.Browser/Targets/TargetMap.cs | 223 +++++++++ src/Febe.Browser/Targets/TargetResolver.cs | 302 ++++++++++++ src/Febe.Core/Collection/HostClassifier.cs | 136 ++++++ src/Febe.Core/Collection/IFileFetcher.cs | 49 ++ src/Febe.Core/Collection/IResponseConsumer.cs | 72 +++ src/Febe.Core/Collection/SignalDetector.cs | 242 ++++++++++ src/Febe.Core/Collection/SignalRules.cs | 271 +++++++++++ src/Febe.Core/Config/segnali.json | 72 +++ src/Febe.Core/Config/segnali.prova.json | 36 ++ src/Febe.Core/Febe.Core.csproj | 6 + src/Febe.Core/Pacing/Distributions.cs | 149 ++++++ .../Browser/BrowserIntegrationTests.cs | 401 ++++++++++++++++ .../Browser/BrowserLifecycleTests.cs | 150 ++++++ tests/Febe.Tests/Browser/CaptureUnitTests.cs | 277 +++++++++++ tests/Febe.Tests/Browser/CdpClientTests.cs | 246 ++++++++++ tests/Febe.Tests/Browser/CdpPolicyTests.cs | 104 +++++ tests/Febe.Tests/Browser/GestureTests.cs | 331 +++++++++++++ tests/Febe.Tests/Browser/HostingTests.cs | 151 ++++++ tests/Febe.Tests/Browser/TargetMapTests.cs | 90 ++++ tests/Febe.Tests/Browser/TestSupport/Fakes.cs | 192 ++++++++ .../Browser/TestSupport/LocalTestSite.cs | 223 +++++++++ .../Browser/TestSupport/RealBrowser.cs | 198 ++++++++ tests/Febe.Tests/Collection/SignalTests.cs | 177 +++++++ tests/Febe.Tests/Pacing/DistributionsTests.cs | 166 +++++++ 44 files changed, 8396 insertions(+) create mode 100644 docs/sonda/esito-locale.md create mode 100644 src/Febe.Browser/Capture/ResponseTap.cs create mode 100644 src/Febe.Browser/Cdp/CdpClient.cs create mode 100644 src/Febe.Browser/Cdp/CdpCommandPolicy.cs create mode 100644 src/Febe.Browser/Cdp/CdpPageExtensions.cs create mode 100644 src/Febe.Browser/Cdp/CdpTargetDiscovery.cs create mode 100644 src/Febe.Browser/Cdp/ReadOnlyScriptGuard.cs create mode 100644 src/Febe.Browser/Cdp/ReconnectingCdpSession.cs create mode 100644 src/Febe.Browser/Diagnostics/IBrowserLog.cs create mode 100644 src/Febe.Browser/Download/BrowserFileFetcher.cs create mode 100644 src/Febe.Browser/Gestures/GestureSettings.cs create mode 100644 src/Febe.Browser/Gestures/HumanGestures.cs create mode 100644 src/Febe.Browser/Gestures/Keyboard.cs create mode 100644 src/Febe.Browser/Hosting/ChromiumCommandLine.cs create mode 100644 src/Febe.Browser/Hosting/ChromiumProcessHost.cs create mode 100644 src/Febe.Browser/Hosting/HostingHelpers.cs create mode 100644 src/Febe.Browser/Hosting/SupervisedProcess.cs create mode 100644 src/Febe.Browser/Hosting/XvfbProcess.cs create mode 100644 src/Febe.Browser/RemoteView/RemoteViewSession.cs create mode 100644 src/Febe.Browser/RemoteView/ScreencastSession.cs create mode 100644 src/Febe.Browser/Targets/TargetMap.cs create mode 100644 src/Febe.Browser/Targets/TargetResolver.cs create mode 100644 src/Febe.Core/Collection/HostClassifier.cs create mode 100644 src/Febe.Core/Collection/IFileFetcher.cs create mode 100644 src/Febe.Core/Collection/IResponseConsumer.cs create mode 100644 src/Febe.Core/Collection/SignalDetector.cs create mode 100644 src/Febe.Core/Collection/SignalRules.cs create mode 100644 src/Febe.Core/Config/segnali.json create mode 100644 src/Febe.Core/Config/segnali.prova.json create mode 100644 src/Febe.Core/Pacing/Distributions.cs create mode 100644 tests/Febe.Tests/Browser/BrowserIntegrationTests.cs create mode 100644 tests/Febe.Tests/Browser/BrowserLifecycleTests.cs create mode 100644 tests/Febe.Tests/Browser/CaptureUnitTests.cs create mode 100644 tests/Febe.Tests/Browser/CdpClientTests.cs create mode 100644 tests/Febe.Tests/Browser/CdpPolicyTests.cs create mode 100644 tests/Febe.Tests/Browser/GestureTests.cs create mode 100644 tests/Febe.Tests/Browser/HostingTests.cs create mode 100644 tests/Febe.Tests/Browser/TargetMapTests.cs create mode 100644 tests/Febe.Tests/Browser/TestSupport/Fakes.cs create mode 100644 tests/Febe.Tests/Browser/TestSupport/LocalTestSite.cs create mode 100644 tests/Febe.Tests/Browser/TestSupport/RealBrowser.cs create mode 100644 tests/Febe.Tests/Collection/SignalTests.cs create mode 100644 tests/Febe.Tests/Pacing/DistributionsTests.cs diff --git a/docs/sonda/esito-locale.md b/docs/sonda/esito-locale.md new file mode 100644 index 0000000..331eab7 --- /dev/null +++ b/docs/sonda/esito-locale.md @@ -0,0 +1,93 @@ +# Esito delle prove in locale: S5 e S6 (Chromium su Xvfb) + +Prove del 13 ottobre 2026 sullo strato browser (`Febe.Browser`), fatte **solo in locale**: Chromium su un display virtuale Xvfb e pagine servite dalla prova stessa su `127.0.0.1`. Nessun contatto con Instagram o Meta. Nulla di quanto segue dice qualcosa sul comportamento di Instagram (voci H) o su WebView2 (S1, S2 e la parte Windows di S6): quelle restano **da provare**. + +## Ambiente + +| | | +|---|---| +| Macchina | Linux 6.18.44 (macchina virtuale di sviluppo, non un contenitore Docker), Ubuntu 24.04.5, 4 CPU | +| Browser | Chromium 141.0.7390.37 (build di Playwright `chromium-1194`), **non** il pacchetto `chromium` di Debian che userà l'immagine | +| Display | Xvfb 2:21.1.12 (`Xvfb :N -screen 0 1280x900x24 -nolisten tcp -noreset`) | +| .NET | SDK 10.0.112 | +| Lingua di sistema | solo `C`, `C.utf8`, `POSIX`: la lingua `it_IT.UTF-8` **non è generata** | +| Spazi dei nomi utente | `max_user_namespaces` = 64299; `unshare --user` funziona per un utente normale | + +Il processo delle prove gira come `root`. Per le prove automatiche Chromium parte quindi con `--no-sandbox` (vedi S5); per S5 lo si è avviato anche come utente normale (`ubuntu`, uid 1000) con `runuser`. + +## S5 — La sandbox di Chromium + +Comando di base (cambia solo l'utente e l'eventuale `--no-sandbox`): + +```sh +DISPLAY=:93 LANG=it_IT.UTF-8 TZ=Europe/Rome chrome --user-data-dir= --no-first-run \ + --no-default-browser-check --password-store=basic --disable-dev-shm-usage --window-size=1280,900 \ + --remote-debugging-port= about:blank +``` + +Lo stato della sandbox si è letto aprendo `chrome://sandbox` e leggendo il testo della pagina con `Runtime.evaluate` in sola lettura. + +| Caso | Che cosa è successo | +|---|---| +| `root`, senza `--no-sandbox` | Chromium **non parte**: `ERROR:content/browser/zygote_host/zygote_host_impl_linux.cc:101] Running as root without --no-sandbox is not supported. See https://crbug.com/638180.` | +| `root`, con `--no-sandbox` | Parte. `chrome://sandbox`: `Layer 1 Sandbox None`, `PID namespaces No`, `Network namespaces No`, `Seccomp-BPF sandbox No`, **«You are NOT adequately sandboxed.»** In più Chromium mostra la barra d'avviso sull'opzione non supportata, che ruba circa 50 pixel di altezza alla pagina (vedi S6, dimensioni) | +| `ubuntu` (uid 1000), senza `--no-sandbox` | Parte con la sandbox attiva. `chrome://sandbox`: `Layer 1 Sandbox Namespace`, `PID namespaces Yes`, `Network namespaces Yes`, `Seccomp-BPF sandbox Yes`, `Seccomp-BPF sandbox supports TSYNC Yes`, **«You are adequately sandboxed.»** | + +Che cosa se ne ricava, e che cosa no: + +- Come utente normale, su questa macchina, la sandbox di Chromium parte con le impostazioni normali, grazie agli spazi dei nomi utente. È la condizione che chiede §11 (utente non root con `PUID`/`PGID`). +- **Non è provato in Docker.** Il profilo seccomp predefinito di Docker può impedire la creazione di spazi dei nomi utente: l'esito dentro il contenitore va misurato in M5 con lo stesso controllo (`chrome://sandbox`). Le alternative restano quelle di §11 (profilo seccomp dedicato, oppure `--no-sandbox` scritto nella guida come compromesso). +- `ChromiumProcessHost` aggiunge `--no-sandbox` **solo** se lo si chiede esplicitamente (`ChromiumLaunchOptions.NoSandbox`); non lo decide da sé. Le prove automatiche lo chiedono perché girano come `root`. + +## S6 — Che cosa vede la pagina + +Valori letti con `Runtime.evaluate` in sola lettura su una pagina locale (`/ambiente`) e su `about:blank`, con `LANG=it_IT.UTF-8` e `TZ=Europe/Rome` nell'ambiente del solo processo del browser. Prova automatica: `BrowserIntegrationTests.ThePageSeesAnOrdinaryVisibleBrowser`. Uscita registrata: + +```text +S6 (Chromium su Xvfb): {"webdriver":false,"visibility":"visible","hidden":false,"focus":false,"language":"it-IT", +"languages":["it-IT"],"timeZone":"Europe/Rome","userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 +(KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36","width":1279,"height":759,"outerWidth":1279,"outerHeight":899} +Fuoco dopo il primo movimento del puntatore: true +``` + +| Proprietà | Valore visto | Note | +|---|---|---| +| `navigator.webdriver` con la porta di debug fissa | `false` | Sia come `root` con `--no-sandbox` sia come utente normale con la sandbox | +| `navigator.webdriver` con `--enable-automation` | `true` | Misurato come utente normale; Febe non usa mai questa opzione | +| `navigator.webdriver` con `--remote-debugging-port=0` | `true` | Porta scelta da Chromium e letta da `DevToolsActivePort`; Febe rifiuta la porta 0 | +| `document.visibilityState` / `document.hidden` | `visible` / `false` | Sul display virtuale la pagina è visibile | +| `document.hasFocus()` | `false` all'avvio, `true` dopo il primo evento del puntatore | Senza gestore di finestre nessuno dà il fuoco alla finestra; lo dà il primo evento di `Input.dispatchMouseEvent` | +| `navigator.language` / `languages` | `it-IT` / `["it-IT"]` | Da `LANG`, **anche se la lingua italiana non è generata nel sistema**: Chromium usa i propri file di lingua (`locales/it.pak`) | +| Fuso orario (`Intl…timeZone`) | `Europe/Rome` | Da `TZ` | +| User agent | quello normale di Chrome 141 per Linux, senza «Headless» | Nessuna modifica | +| Finestra | `--window-size=1280,900` → esterno 1279×899; interno 1279×760 con la sandbox, 1279×707 con `--no-sandbox` finché è visibile la sua barra d'avviso (nelle prove automatiche, più avanti, anche 1279×759) | La barra del browser occupa circa 140 pixel; quella d'avviso circa 53 | + +## Altre misure utili per §6.1 + +Tutte dalle prove automatiche in `tests/Febe.Tests/Browser/` (comando in fondo), sempre su pagine locali. + +- **Porta di debug solo su `127.0.0.1`.** L'elenco dei punti di ascolto letto da .NET (`IPGlobalProperties`, cioè `/proc/net/tcp`) mostra solo `127.0.0.1:`. `ChromiumProcessHost` lo controlla a ogni avvio e annulla l'avvio altrimenti. +- **Rotella.** Due raffiche (9 eventi) hanno chiesto 1017 pixel e la pagina è scesa di esattamente 1017; gli eventi `wheel` visti dalla pagina hanno `isTrusted = true`. +- **Clic.** Il clic arriva al pulsante trovato con la mappa dei bersagli, con `isTrusted = true`, preceduto da molti `mousemove` (il puntatore viaggia, non salta). +- **Input appena dopo il caricamento.** Un clic e un tasto inviati pochi millisecondi dopo `readyState = complete` **non sono arrivati** alla pagina; mezzo secondo dopo sì. Probabilmente Chromium scarta l'input che arriva prima del primo disegno della pagina (non verificato oltre). Le ricette aspettano comunque 1–6 s dopo il caricamento (§7.7); le prove aspettano 0,5 s. +- **Vista remota.** `Page.startScreencast` consegna fotogrammi JPEG su una pagina animata (la prova si ferma al quinto; ognuno è confermato con `Page.screencastFrameAck`, senza il quale Chromium non manda il successivo). Clic e tasti inoltrati dalla vista remota hanno scritto «Ciao è» in un campo di testo: è l'equivalente locale di S4, senza rete di mezzo e senza contenitore. +- **Scaricamento.** `Network.loadNetworkResource` (con l'identificativo del frame da `Page.getFrameTree`) e `IO.read` a blocchi da 1 MB hanno scaricato un file di 24 MB (25 165 824 byte) in circa 2,2 s, con SHA-256 identico all'originale. +- **Corpi delle risposte.** `Network.getResponseBody` restituisce i JSON letti dalla pagina. Se la pagina chiama `fetch()` ma non legge il corpo, Chromium **non** manda `Network.loadingFinished` e dopo la navigazione il corpo non è più disponibile («No resource with given identifier found»). La cattura quindi vede solo i corpi che la pagina usa davvero; i segnali basati sullo stato HTTP (429) funzionano comunque, perché arrivano con `Network.responseReceived`. +- **Arresto e sessione (S3 in locale).** Con `SIGTERM` Chromium esce in circa 35 ms e in 3 prove su 4 **non** ha scritto nel profilo un cookie impostato da meno di 30 secondi (resta un `Cookies-journal`). Con `SIGINT` (4 prove su 4) e con `SIGHUP` (3 su 3) esce in 95–130 ms e il cookie è scritto. Dopo 32 secondi il cookie era già nel file anche senza arresto (scrittura periodica di Chromium). Per questo `ChromiumProcessHost` ferma Chromium con `SIGINT`; con questa scelta la prova `TheSessionCookieSurvivesACleanRestartOfTheBrowser` è passata in 3 esecuzioni su 3. +- **Processi figli.** Dopo un arresto con `SIGTERM`, mezzo secondo più tardi 5 degli 8 processi di Chromium (zygote, servizio di rete, GPU) erano ancora vivi; dopo 5 secondi nessuno. Con `SIGINT` non è stato misurato. In Docker, se `Febe.Server` è il processo 1, serve un `init` che raccolga gli orfani (per esempio `init: true` in compose): da verificare in M5. +- **Caduta del browser.** Ucciso Chromium, il supervisore lo riavvia dopo l'attesa prevista, il collegamento CDP si riapre da solo e la cattura delle risposte riprende (`Network.enable` di nuovo) senza che chi la usa debba fare nulla. + +## Come ripetere + +```sh +dotnet build Febe.slnx -warnaserror +dotnet test tests/Febe.Tests --filter "FullyQualifiedName~BrowserIntegrationTests|FullyQualifiedName~BrowserLifecycleTests" --logger "console;verbosity=detailed" +``` + +Le prove cercano Chromium in `FEBE_CHROMIUM` (oppure nel percorso dell'ambiente di sviluppo o nel `PATH`) e Xvfb nel `PATH`; se mancano risultano «inconcludenti», non fallite. Le misure con l'utente normale, con `--enable-automation` e con la porta 0 sono state fatte a mano, avviando Chromium con il comando di S5 e collegandosi con `CdpClient` alla porta indicata. + +## Che cosa resta da provare + +- S5 dentro il contenitore Docker vero, come utente non root, con il profilo seccomp predefinito (M5). +- S6 con il Chromium di Debian e con `chromium-l10n` (M5), e in WebView2 su Windows (M6). +- Tutte le voci H: richiedono Instagram e la sonda passiva guidata da Alberto (M0). diff --git a/src/Febe.Browser/Capture/ResponseTap.cs b/src/Febe.Browser/Capture/ResponseTap.cs new file mode 100644 index 0000000..816cc38 --- /dev/null +++ b/src/Febe.Browser/Capture/ResponseTap.cs @@ -0,0 +1,440 @@ +using System.Collections.Concurrent; +using System.Text; +using System.Text.Json; +using System.Text.Json.Nodes; +using System.Threading.Channels; +using Febe.Browser.Cdp; +using Febe.Browser.Diagnostics; +using Febe.Core.Abstractions; +using Febe.Core.Collection; + +namespace Febe.Browser.Capture; + +/// Options of . +public sealed record ResponseTapOptions +{ + /// Bodies larger than this are not fetched (memory guard). + public long MaxBodyBytes { get; init; } = 32L * 1024 * 1024; + + /// How long to wait for one body before giving up on it (one stuck request must not block the others). + public TimeSpan BodyTimeout { get; init; } = TimeSpan.FromSeconds(15); + + /// Decides from the declared MIME type whether a body is worth parsing as JSON. + public Func IsJsonMimeType { get; init; } = static mime => mime.Contains("json", StringComparison.OrdinalIgnoreCase); + + /// Per-resource buffer of the browser (Network.enable maxResourceBufferSize). + public int BrowserResourceBufferBytes { get; init; } = 32 * 1024 * 1024; + + /// Total buffer of the browser (Network.enable maxTotalBufferSize). + public int BrowserTotalBufferBytes { get; init; } = 128 * 1024 * 1024; +} + +/// Counters for diagnostics (never contents). +public sealed record ResponseTapStats(long Responses, long JsonBodies, long BodyErrors, long ParseErrors, long Skipped); + +/// +/// Listens to the responses the page receives (spec §6.2) and hands JSON bodies to s, +/// and the metadata of every response and main-frame navigation to s. +/// +/// +/// It does not filter by address: readers recognise data by its shape (spec §6.4). Bodies stay in memory for the +/// time of the reading, are never written to disk and never logged. Event handlers only queue work; bodies are +/// fetched and parsed on a background worker, one at a time. +/// +public sealed class ResponseTap : IAsyncDisposable +{ + private readonly ICdpSession _cdp; + private readonly HostClassifier _hosts; + private readonly IClock _clock; + private readonly IBrowserLog _log; + private readonly ResponseTapOptions _options; + private readonly ConcurrentDictionary _inFlight = new(StringComparer.Ordinal); + private readonly Lock _gate = new(); + private readonly List _consumers = []; + private readonly List _observers = []; + private readonly Channel _queue = Channel.CreateUnbounded(new UnboundedChannelOptions { SingleReader = true }); + private readonly CancellationTokenSource _lifetime = new(); + private readonly List _subscriptions = []; + private Task? _worker; + private volatile string? _mainFrameId; + private long _responses; + private long _jsonBodies; + private long _bodyErrors; + private long _parseErrors; + private long _skipped; + + public ResponseTap(ICdpSession cdp, HostClassifier hosts, IClock clock, IBrowserLog? log = null, ResponseTapOptions? options = null) + { + _cdp = cdp ?? throw new ArgumentNullException(nameof(cdp)); + _hosts = hosts ?? throw new ArgumentNullException(nameof(hosts)); + _clock = clock ?? throw new ArgumentNullException(nameof(clock)); + _log = log ?? NullBrowserLog.Instance; + _options = options ?? new ResponseTapOptions(); + } + + /// Raised for every main-frame navigation (sanitized address). + public event EventHandler? Navigated; + + public ResponseTapStats Stats => new( + Interlocked.Read(ref _responses), + Interlocked.Read(ref _jsonBodies), + Interlocked.Read(ref _bodyErrors), + Interlocked.Read(ref _parseErrors), + Interlocked.Read(ref _skipped)); + + public IDisposable AddConsumer(IResponseConsumer consumer) + { + ArgumentNullException.ThrowIfNull(consumer); + lock (_gate) + { + _consumers.Add(consumer); + } + + return new Subscription(() => + { + lock (_gate) + { + _consumers.Remove(consumer); + } + }); + } + + public IDisposable AddObserver(IResponseObserver observer) + { + ArgumentNullException.ThrowIfNull(observer); + lock (_gate) + { + _observers.Add(observer); + } + + return new Subscription(() => + { + lock (_gate) + { + _observers.Remove(observer); + } + }); + } + + /// Subscribes to the page events and enables the Network domain (again after every reconnection). + public async Task StartAsync(CancellationToken ct = default) + { + if (_worker is not null) + { + throw new InvalidOperationException("La cattura è già avviata."); + } + + _subscriptions.Add(_cdp.On("Network.responseReceived", OnResponseReceived)); + _subscriptions.Add(_cdp.On("Network.loadingFinished", OnLoadingFinished)); + _subscriptions.Add(_cdp.On("Network.loadingFailed", OnLoadingFailed)); + _subscriptions.Add(_cdp.On("Page.frameNavigated", OnFrameNavigated)); + _subscriptions.Add(_cdp.On("Page.navigatedWithinDocument", OnNavigatedWithinDocument)); + if (_cdp is ICdpConnectionEvents events) + { + events.Reconnected += OnReconnected; + } + + _worker = Task.Run(() => WorkAsync(_lifetime.Token), CancellationToken.None); + await EnableAsync(ct).ConfigureAwait(false); + _mainFrameId = await _cdp.GetMainFrameIdAsync(ct).ConfigureAwait(false); + } + + public async ValueTask DisposeAsync() + { + if (_cdp is ICdpConnectionEvents events) + { + events.Reconnected -= OnReconnected; + } + + foreach (var subscription in _subscriptions) + { + subscription.Dispose(); + } + + _subscriptions.Clear(); + _queue.Writer.TryComplete(); + await _lifetime.CancelAsync().ConfigureAwait(false); + if (_worker is not null) + { + try + { + await _worker.ConfigureAwait(false); + } + catch (OperationCanceledException) + { + } + } + + _lifetime.Dispose(); + _inFlight.Clear(); + } + + private Task EnableAsync(CancellationToken ct) => + _cdp.SendAsync( + "Network.enable", + new JsonObject + { + ["maxResourceBufferSize"] = _options.BrowserResourceBufferBytes, + ["maxTotalBufferSize"] = _options.BrowserTotalBufferBytes, + }, + ct); + + private void OnReconnected(object? sender, EventArgs e) + { + _inFlight.Clear(); + _ = Task.Run(async () => + { + try + { + await EnableAsync(_lifetime.Token).ConfigureAwait(false); + _mainFrameId = await _cdp.GetMainFrameIdAsync(_lifetime.Token).ConfigureAwait(false); + } + catch (Exception ex) when (ex is not OperationCanceledException) + { + _log.Warn("Cattura: non è stato possibile riattivare l'ascolto delle risposte dopo il riavvio del browser.", ex); + } + }); + } + + private void OnResponseReceived(JsonElement p) + { + if (p.ValueKind != JsonValueKind.Object || !p.TryGetProperty("requestId", out var idElement) || !p.TryGetProperty("response", out var response)) + { + return; + } + + var requestId = idElement.GetString() ?? string.Empty; + var url = response.TryGetProperty("url", out var u) ? u.GetString() : null; + var sanitized = UrlSanitizer.Sanitize(url); + var status = response.TryGetProperty("status", out var s) && s.TryGetInt32(out var si) ? si : 0; + var mime = response.TryGetProperty("mimeType", out var m) ? (m.GetString() ?? string.Empty).Split(';')[0].Trim().ToLowerInvariant() : string.Empty; + var type = p.TryGetProperty("type", out var t) ? t.GetString() : null; + var frameId = p.TryGetProperty("frameId", out var f) ? f.GetString() : null; + var loaderId = p.TryGetProperty("loaderId", out var l) ? l.GetString() : null; + + // A main-frame document: type Document and the request id equals the loader id (the navigation request). + var isMainDocument = type == "Document" && loaderId is not null && loaderId == requestId && IsMainFrame(frameId); + + var descriptor = new ResponseDescriptor( + requestId, + _hosts.Classify(url), + sanitized.Url, + sanitized.Host, + sanitized.Path, + status, + mime, + type, + isMainDocument, + _clock.Now); + + Interlocked.Increment(ref _responses); + foreach (var observer in SnapshotObservers()) + { + try + { + observer.OnResponse(descriptor); + } + catch (Exception ex) + { + _log.Warn("Cattura: errore in un osservatore delle risposte.", ex); + } + } + + if (_options.IsJsonMimeType(mime) && status is >= 200 and < 600 && status != 204) + { + _inFlight[requestId] = descriptor; + } + } + + private void OnLoadingFinished(JsonElement p) + { + if (!p.TryGetProperty("requestId", out var idElement) || idElement.GetString() is not { } requestId + || !_inFlight.TryRemove(requestId, out var descriptor)) + { + return; + } + + var length = p.TryGetProperty("encodedDataLength", out var len) && len.TryGetDouble(out var d) ? d : 0; + if (length > _options.MaxBodyBytes) + { + Interlocked.Increment(ref _skipped); + return; + } + + _queue.Writer.TryWrite(descriptor); + } + + private void OnLoadingFailed(JsonElement p) + { + if (p.TryGetProperty("requestId", out var idElement) && idElement.GetString() is { } requestId) + { + _inFlight.TryRemove(requestId, out _); + } + } + + private bool IsMainFrame(string? frameId) => frameId is null || _mainFrameId is null || frameId == _mainFrameId; + + private void OnFrameNavigated(JsonElement p) + { + if (!p.TryGetProperty("frame", out var frame) || frame.TryGetProperty("parentId", out _)) + { + return; + } + + _mainFrameId = frame.TryGetProperty("id", out var id) ? id.GetString() : _mainFrameId; + + // Requests of the previous document that never finished (e.g. a body the page did not read: Chromium then + // sends no loadingFinished) will not finish any more: forget them. + _inFlight.Clear(); + Publish(frame.TryGetProperty("url", out var u) ? u.GetString() : null, sameDocument: false); + } + + /// + /// Route changes of single-page sites (history.pushState): the address changes without a new document, and + /// only this event tells (e.g. a move to a verification page inside the app). + /// + private void OnNavigatedWithinDocument(JsonElement p) + { + var frameId = p.TryGetProperty("frameId", out var f) ? f.GetString() : null; + if (_mainFrameId is not null && frameId != _mainFrameId) + { + return; + } + + Publish(p.TryGetProperty("url", out var u) ? u.GetString() : null, sameDocument: true); + } + + private void Publish(string? url, bool sameDocument) + { + var sanitized = UrlSanitizer.Sanitize(url); + var navigation = new NavigationDescriptor(_hosts.Classify(url), sanitized.Url, sanitized.Host, sanitized.Path, _clock.Now, sameDocument); + foreach (var observer in SnapshotObservers()) + { + try + { + observer.OnNavigation(navigation); + } + catch (Exception ex) + { + _log.Warn("Cattura: errore in un osservatore della navigazione.", ex); + } + } + + Navigated?.Invoke(this, navigation); + } + + private async Task WorkAsync(CancellationToken ct) + { + await foreach (var descriptor in _queue.Reader.ReadAllAsync(ct).ConfigureAwait(false)) + { + IResponseConsumer[] consumers; + lock (_gate) + { + consumers = [.. _consumers]; + } + + if (consumers.Length == 0) + { + continue; + } + + JsonDocument? document; + try + { + document = await FetchBodyAsync(descriptor.RequestId, ct).ConfigureAwait(false); + } + catch (OperationCanceledException) when (ct.IsCancellationRequested) + { + return; + } + catch (Exception ex) when (ex is CdpCommandException or CdpDisconnectedException or BrowserUnavailableException or TimeoutException) + { + // The body may already be evicted from the browser's buffer, or the page navigated away. + Interlocked.Increment(ref _bodyErrors); + _log.Debug($"Cattura: corpo non disponibile ({ex.GetType().Name})."); + continue; + } + + if (document is null) + { + continue; + } + + using (document) + { + Interlocked.Increment(ref _jsonBodies); + foreach (var consumer in consumers) + { + try + { + await consumer.ConsumeAsync(descriptor, document, ct).ConfigureAwait(false); + } + catch (OperationCanceledException) when (ct.IsCancellationRequested) + { + return; + } + catch (Exception ex) + { + _log.Warn($"Cattura: errore in un lettore ({consumer.GetType().Name}).", ex); + } + } + } + } + } + + private async Task FetchBodyAsync(string requestId, CancellationToken ct) + { + using var timeout = CancellationTokenSource.CreateLinkedTokenSource(ct); + timeout.CancelAfter(_options.BodyTimeout); + JsonElement result; + try + { + result = await _cdp.SendAsync("Network.getResponseBody", new JsonObject { ["requestId"] = requestId }, timeout.Token).ConfigureAwait(false); + } + catch (OperationCanceledException) when (!ct.IsCancellationRequested) + { + throw new TimeoutException("Corpo della risposta non arrivato in tempo."); + } + + if (!result.TryGetProperty("body", out var body)) + { + return null; + } + + var encoded = result.TryGetProperty("base64Encoded", out var b) && b.ValueKind == JsonValueKind.True; + byte[] bytes; + if (encoded) + { + if (!body.TryGetBytesFromBase64(out var decoded)) + { + Interlocked.Increment(ref _parseErrors); + return null; + } + + bytes = decoded; + } + else + { + bytes = Encoding.UTF8.GetBytes(body.GetString() ?? string.Empty); + } + + try + { + return JsonDocument.Parse(bytes, new JsonDocumentOptions { MaxDepth = 256 }); + } + catch (JsonException) + { + // Declared as JSON but it is not (or has a prefix): readers will be told by the probe in M0. + Interlocked.Increment(ref _parseErrors); + return null; + } + } + + private IResponseObserver[] SnapshotObservers() + { + lock (_gate) + { + return [.. _observers]; + } + } +} diff --git a/src/Febe.Browser/Cdp/CdpClient.cs b/src/Febe.Browser/Cdp/CdpClient.cs new file mode 100644 index 0000000..28154e4 --- /dev/null +++ b/src/Febe.Browser/Cdp/CdpClient.cs @@ -0,0 +1,431 @@ +using System.Buffers; +using System.Collections.Concurrent; +using System.Net.WebSockets; +using System.Text.Json; +using System.Text.Json.Nodes; +using Febe.Browser.Diagnostics; +using Febe.Core.Abstractions; + +namespace Febe.Browser.Cdp; + +/// Options of . +/// How long to wait for the answer to a command before giving up. +public sealed record CdpClientOptions(TimeSpan? CommandTimeout = null) +{ + public static CdpClientOptions Default { get; } = new(); + + internal TimeSpan EffectiveTimeout => CommandTimeout ?? TimeSpan.FromSeconds(60); +} + +/// +/// Chrome DevTools Protocol client over a WebSocket (spec §5, §6.1), written by hand on . +/// +/// +/// +/// Only commands of are sent; Runtime.evaluate also passes . +/// The log receives command names only: never parameters, results or event payloads. +/// Event handlers run on the receive loop: they must be quick and must never wait for a command +/// (queue the work instead), or the loop stops. +/// When the connection drops every pending command fails with ; +/// a new client is needed (see ). Disposal is idempotent. +/// +/// +public sealed class CdpClient : ICdpSession, IAsyncDisposable +{ + private const int ReceiveChunk = 64 * 1024; + private const int MaxRetainedBuffer = 4 * 1024 * 1024; + + private static readonly JsonSerializerOptions ParameterOptions = new(JsonSerializerDefaults.Web) + { + DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull, + }; + + private readonly WebSocket _socket; + private readonly IBrowserLog _log; + private readonly CdpClientOptions _options; + private readonly ConcurrentDictionary _pending = new(); + private readonly Dictionary>> _handlers = new(StringComparer.Ordinal); + private readonly Lock _handlersGate = new(); + private readonly SemaphoreSlim _sendLock = new(1, 1); + private readonly CancellationTokenSource _lifetime = new(); + private readonly Task _receiveLoop; + private int _nextId; + private int _disposed; + private int _closed; + private Exception? _closeReason; + + internal CdpClient(WebSocket socket, IBrowserLog? log = null, CdpClientOptions? options = null) + { + _socket = socket ?? throw new ArgumentNullException(nameof(socket)); + _log = log ?? NullBrowserLog.Instance; + _options = options ?? CdpClientOptions.Default; + _receiveLoop = Task.Run(ReceiveLoopAsync); + } + + /// True until the connection closes or the client is disposed. + public bool IsConnected => Volatile.Read(ref _closed) == 0; + + /// Raised once when the connection closes (the argument is the cause, null for a normal close). + public event EventHandler? Disconnected; + + /// Connects to a DevTools WebSocket on the loopback interface (never through a proxy). + public static async Task ConnectAsync(Uri webSocketUrl, IBrowserLog? log = null, CdpClientOptions? options = null, CancellationToken ct = default) + { + ArgumentNullException.ThrowIfNull(webSocketUrl); + CdpTargetDiscovery.EnsureLoopback(webSocketUrl); + + var socket = new ClientWebSocket(); + socket.Options.Proxy = null; + socket.Options.KeepAliveInterval = TimeSpan.FromSeconds(20); + try + { + using var connectTimeout = CancellationTokenSource.CreateLinkedTokenSource(ct); + connectTimeout.CancelAfter(TimeSpan.FromSeconds(10)); + await socket.ConnectAsync(webSocketUrl, connectTimeout.Token).ConfigureAwait(false); + } + catch + { + socket.Dispose(); + throw; + } + + (log ?? NullBrowserLog.Instance).Debug("CDP: collegamento aperto."); + return new CdpClient(socket, log, options); + } + + public async Task SendAsync(string method, object? parameters = null, CancellationToken ct = default) + { + ArgumentException.ThrowIfNullOrEmpty(method); + CdpCommandPolicy.EnsureAllowed(method); + var node = CdpParameters.ToNode(parameters, ParameterOptions); + if (method == "Runtime.evaluate") + { + ReadOnlyScriptGuard.EnsureReadOnly(CdpParameters.GetString(node, "expression")); + } + + ThrowIfClosed(); + + var id = Interlocked.Increment(ref _nextId); + var pending = new Pending(method, new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously)); + _pending[id] = pending; + try + { + var payload = Serialize(id, method, node); + using (var lockWait = CancellationTokenSource.CreateLinkedTokenSource(ct, _lifetime.Token)) + { + await _sendLock.WaitAsync(lockWait.Token).ConfigureAwait(false); + } + + try + { + ThrowIfClosed(); + + // Never pass the caller's token to the socket: cancelling a send aborts the whole connection. + await _socket.SendAsync(payload, WebSocketMessageType.Text, endOfMessage: true, _lifetime.Token).ConfigureAwait(false); + } + finally + { + _sendLock.Release(); + } + + _log.Debug($"CDP → {method}"); + + using var wait = CancellationTokenSource.CreateLinkedTokenSource(ct); + wait.CancelAfter(_options.EffectiveTimeout); + try + { + return await pending.Completion.Task.WaitAsync(wait.Token).ConfigureAwait(false); + } + catch (OperationCanceledException) when (!ct.IsCancellationRequested) + { + ThrowIfClosed(); + throw new TimeoutException($"Il browser non ha risposto al comando «{method}» entro {_options.EffectiveTimeout.TotalSeconds:0} s."); + } + } + catch (Exception ex) when (ex is WebSocketException or ObjectDisposedException || (ex is OperationCanceledException && _lifetime.IsCancellationRequested && !ct.IsCancellationRequested)) + { + throw new CdpDisconnectedException("Il collegamento con il browser si è chiuso durante il comando.", ex); + } + finally + { + _pending.TryRemove(id, out _); + } + } + + public IDisposable On(string eventName, Action handler) + { + ArgumentException.ThrowIfNullOrEmpty(eventName); + ArgumentNullException.ThrowIfNull(handler); + lock (_handlersGate) + { + if (!_handlers.TryGetValue(eventName, out var list)) + { + list = []; + _handlers[eventName] = list; + } + + list.Add(handler); + } + + return new Subscription(() => + { + lock (_handlersGate) + { + if (_handlers.TryGetValue(eventName, out var list)) + { + list.Remove(handler); + if (list.Count == 0) + { + _handlers.Remove(eventName); + } + } + } + }); + } + + public async ValueTask DisposeAsync() + { + if (Interlocked.Exchange(ref _disposed, 1) == 1) + { + return; + } + + if (_socket.State == WebSocketState.Open) + { + try + { + using var closeTimeout = new CancellationTokenSource(TimeSpan.FromSeconds(1)); + await _socket.CloseOutputAsync(WebSocketCloseStatus.NormalClosure, null, closeTimeout.Token).ConfigureAwait(false); + } + catch (Exception ex) when (ex is WebSocketException or OperationCanceledException or ObjectDisposedException) + { + // The browser may already be gone. + } + } + + try + { + await _receiveLoop.WaitAsync(TimeSpan.FromSeconds(1)).ConfigureAwait(false); + } + catch (TimeoutException) + { + // Fall through: cancelling aborts the receive. + } + + await _lifetime.CancelAsync().ConfigureAwait(false); + try + { + await _receiveLoop.ConfigureAwait(false); + } + catch (Exception ex) when (ex is OperationCanceledException or WebSocketException) + { + } + + MarkClosed(null); + _socket.Dispose(); + + // _sendLock and _lifetime are deliberately not disposed: a concurrent SendAsync may still touch them, + // and neither holds unmanaged resources (no wait handle, no timer). + } + + private async Task ReceiveLoopAsync() + { + var buffer = new ArrayBufferWriter(ReceiveChunk); + Exception? failure = null; + try + { + while (!_lifetime.IsCancellationRequested) + { + buffer.ResetWrittenCount(); + ValueWebSocketReceiveResult result; + do + { + result = await _socket.ReceiveAsync(buffer.GetMemory(ReceiveChunk), _lifetime.Token).ConfigureAwait(false); + if (result.MessageType == WebSocketMessageType.Close) + { + return; + } + + buffer.Advance(result.Count); + } + while (!result.EndOfMessage); + + Dispatch(buffer.WrittenSpan); + + if (buffer.Capacity > MaxRetainedBuffer) + { + buffer = new ArrayBufferWriter(ReceiveChunk); + } + } + } + catch (OperationCanceledException) when (_lifetime.IsCancellationRequested) + { + } + catch (Exception ex) when (ex is WebSocketException or ObjectDisposedException or InvalidOperationException) + { + failure = ex; + } + finally + { + MarkClosed(failure); + } + } + + private void Dispatch(ReadOnlySpan message) + { + JsonElement root; + try + { + // ParseValue yields a self-contained element (no JsonDocument to dispose) and needs no serializer, + // so it also works where reflection-based serialization is disabled (trimmed or AOT builds). + var reader = new Utf8JsonReader(message); + root = JsonElement.ParseValue(ref reader); + } + catch (JsonException ex) + { + _log.Warn("CDP: messaggio non leggibile ricevuto dal browser.", ex); + return; + } + + if (root.ValueKind != JsonValueKind.Object) + { + return; + } + + if (root.TryGetProperty("id", out var idElement) && idElement.TryGetInt32(out var id)) + { + if (!_pending.TryGetValue(id, out var pending)) + { + return; + } + + if (root.TryGetProperty("error", out var error)) + { + var code = error.TryGetProperty("code", out var c) && c.TryGetInt32(out var ci) ? ci : 0; + var text = error.TryGetProperty("message", out var m) ? m.GetString() ?? string.Empty : string.Empty; + _log.Debug($"CDP ✗ {pending.Method} (codice {code})"); + pending.Completion.TrySetException(new CdpCommandException(pending.Method, code, text)); + } + else + { + pending.Completion.TrySetResult(root.TryGetProperty("result", out var result) ? result : default); + } + + return; + } + + if (root.TryGetProperty("method", out var methodElement) && methodElement.GetString() is { } eventName) + { + Action[] handlers; + lock (_handlersGate) + { + if (!_handlers.TryGetValue(eventName, out var list) || list.Count == 0) + { + return; + } + + handlers = [.. list]; + } + + var parameters = root.TryGetProperty("params", out var p) ? p : default; + foreach (var handler in handlers) + { + try + { + handler(parameters); + } + catch (Exception ex) + { + _log.Warn($"CDP: errore nel gestore dell'evento {eventName}.", ex); + } + } + } + } + + private void MarkClosed(Exception? reason) + { + if (Interlocked.Exchange(ref _closed, 1) == 1) + { + return; + } + + _closeReason = reason; + var disconnected = new CdpDisconnectedException("Il collegamento con il browser si è chiuso.", reason); + foreach (var (_, pending) in _pending) + { + pending.Completion.TrySetException(disconnected); + } + + if (Volatile.Read(ref _disposed) == 0) + { + _log.Info("CDP: il browser ha chiuso il collegamento."); + } + + try + { + Disconnected?.Invoke(this, reason); + } + catch (Exception ex) + { + _log.Warn("CDP: errore nel gestore della disconnessione.", ex); + } + } + + private void ThrowIfClosed() + { + if (Volatile.Read(ref _closed) == 1 || Volatile.Read(ref _disposed) == 1) + { + throw new CdpDisconnectedException("Il collegamento con il browser è chiuso.", _closeReason); + } + } + + private static ReadOnlyMemory Serialize(int id, string method, JsonNode? parameters) + { + var output = new ArrayBufferWriter(256); + using (var writer = new Utf8JsonWriter(output)) + { + writer.WriteStartObject(); + writer.WriteNumber("id", id); + writer.WriteString("method", method); + if (parameters is not null) + { + writer.WritePropertyName("params"); + parameters.WriteTo(writer); + } + + writer.WriteEndObject(); + } + + return output.WrittenMemory; + } + + private sealed record Pending(string Method, TaskCompletionSource Completion); +} + +/// Disposable that runs an action once. +internal sealed class Subscription(Action dispose) : IDisposable +{ + private Action? _dispose = dispose; + + public void Dispose() => Interlocked.Exchange(ref _dispose, null)?.Invoke(); +} + +/// Converts command parameters (anonymous objects, dictionaries, JSON nodes or elements) to JSON. +internal static class CdpParameters +{ + public static JsonNode? ToNode(object? parameters, JsonSerializerOptions options) => parameters switch + { + null => null, + JsonNode node => node, + JsonElement { ValueKind: JsonValueKind.Undefined or JsonValueKind.Null } => null, + JsonElement element => JsonNode.Parse(element.GetRawText()), + _ when !JsonSerializer.IsReflectionEnabledByDefault => throw new NotSupportedException( + "Senza serializzazione per riflessione i parametri CDP vanno passati come JsonObject."), + _ => JsonSerializer.SerializeToNode(parameters, parameters.GetType(), options), + }; + + public static string? GetString(JsonNode? node, string property) => + node is JsonObject obj && obj.TryGetPropertyValue(property, out var value) && value is JsonValue v && v.TryGetValue(out var s) + ? s + : null; +} diff --git a/src/Febe.Browser/Cdp/CdpCommandPolicy.cs b/src/Febe.Browser/Cdp/CdpCommandPolicy.cs new file mode 100644 index 0000000..bd543f2 --- /dev/null +++ b/src/Febe.Browser/Cdp/CdpCommandPolicy.cs @@ -0,0 +1,119 @@ +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) + { + } +} diff --git a/src/Febe.Browser/Cdp/CdpPageExtensions.cs b/src/Febe.Browser/Cdp/CdpPageExtensions.cs new file mode 100644 index 0000000..99acd9d --- /dev/null +++ b/src/Febe.Browser/Cdp/CdpPageExtensions.cs @@ -0,0 +1,121 @@ +using System.Text.Json; +using System.Text.Json.Nodes; +using Febe.Core.Abstractions; + +namespace Febe.Browser.Cdp; + +/// A read-only evaluation threw inside the page. +public sealed class CdpEvaluationException(string message) : Exception(message); + +/// Result of Page.navigate. +/// Frame that navigated. +/// Browser error (e.g. «net::ERR_CONNECTION_REFUSED»), null on success. +public sealed record NavigationResult(string FrameId, string? ErrorText) +{ + public bool Succeeded => ErrorText is null; +} + +/// Page-level helpers built only on the commands of spec §6.1. +public static class CdpPageExtensions +{ + /// The «rest» page (spec §6.1): no site page stays open outside a session. + public const string RestUrl = "about:blank"; + + /// + /// Evaluates a read-only expression and returns its value (by value). The expression passes + /// in the client. Exceptions in the page become . + /// + public static async Task EvaluateAsync(this ICdpSession cdp, string expression, CancellationToken ct = default) + { + ArgumentNullException.ThrowIfNull(cdp); + var result = await cdp.SendAsync( + "Runtime.evaluate", + new JsonObject + { + ["expression"] = expression, + ["returnByValue"] = true, + ["awaitPromise"] = false, + ["silent"] = true, + }, + ct).ConfigureAwait(false); + + if (result.ValueKind == JsonValueKind.Object && result.TryGetProperty("exceptionDetails", out var details)) + { + var text = details.TryGetProperty("exception", out var ex) && ex.TryGetProperty("description", out var d) + ? d.GetString() + : details.TryGetProperty("text", out var t) ? t.GetString() : null; + var firstLine = (text ?? "errore sconosciuto").Split('\n')[0]; + throw new CdpEvaluationException($"Lettura della pagina fallita: {(firstLine.Length > 200 ? firstLine[..200] : firstLine)}"); + } + + return result.ValueKind == JsonValueKind.Object + && result.TryGetProperty("result", out var remote) + && remote.TryGetProperty("value", out var value) + ? value + : default; + } + + /// Identifier of the main frame (needed by Network.loadNetworkResource). + public static async Task GetMainFrameIdAsync(this ICdpSession cdp, CancellationToken ct = default) + { + ArgumentNullException.ThrowIfNull(cdp); + var tree = await cdp.SendAsync("Page.getFrameTree", null, ct).ConfigureAwait(false); + return tree.GetProperty("frameTree").GetProperty("frame").GetProperty("id").GetString() + ?? throw new InvalidOperationException("Il browser non ha indicato il frame principale."); + } + + /// Address of the main frame (may contain data: never log it unsanitized). + public static async Task GetMainFrameUrlAsync(this ICdpSession cdp, CancellationToken ct = default) + { + ArgumentNullException.ThrowIfNull(cdp); + var tree = await cdp.SendAsync("Page.getFrameTree", null, ct).ConfigureAwait(false); + return tree.GetProperty("frameTree").GetProperty("frame").GetProperty("url").GetString() ?? string.Empty; + } + + /// Page.navigate. Returns when the navigation commits (not when the page has finished loading). + public static async Task NavigateAsync(this ICdpSession cdp, string url, CancellationToken ct = default) + { + ArgumentNullException.ThrowIfNull(cdp); + ArgumentException.ThrowIfNullOrEmpty(url); + var result = await cdp.SendAsync("Page.navigate", new JsonObject { ["url"] = url }, ct).ConfigureAwait(false); + var frameId = result.TryGetProperty("frameId", out var f) ? f.GetString() ?? string.Empty : string.Empty; + var error = result.TryGetProperty("errorText", out var e) ? e.GetString() : null; + return new NavigationResult(frameId, string.IsNullOrEmpty(error) ? null : error); + } + + /// Puts the browser at rest on the blank page (spec §6.1, §7.2). + public static Task RestAsync(this ICdpSession cdp, CancellationToken ct = default) => + cdp.NavigateAsync(RestUrl, ct); + + /// + /// Waits until document.readyState is «complete» (read-only polling), up to . + /// Returns false on timeout. Uses for the pauses between polls. + /// + public static async Task WaitForLoadAsync(this ICdpSession cdp, IClock clock, TimeSpan timeout, CancellationToken ct = default) + { + ArgumentNullException.ThrowIfNull(clock); + var deadline = clock.Now + timeout; + while (true) + { + try + { + var state = await cdp.EvaluateAsync("document.readyState", ct).ConfigureAwait(false); + if (state.ValueKind == JsonValueKind.String && state.GetString() == "complete") + { + return true; + } + } + catch (CdpCommandException) + { + // The context may be swapped during a navigation: poll again. + } + + if (clock.Now >= deadline) + { + return false; + } + + await clock.Delay(TimeSpan.FromMilliseconds(100), ct).ConfigureAwait(false); + } + } +} diff --git a/src/Febe.Browser/Cdp/CdpTargetDiscovery.cs b/src/Febe.Browser/Cdp/CdpTargetDiscovery.cs new file mode 100644 index 0000000..0a89394 --- /dev/null +++ b/src/Febe.Browser/Cdp/CdpTargetDiscovery.cs @@ -0,0 +1,131 @@ +using System.Net; +using System.Net.Http.Json; +using System.Text.Json; +using System.Text.Json.Serialization; + +namespace Febe.Browser.Cdp; + +/// A DevTools target listed by /json/list. The address may hold data: never log it. +public sealed record CdpTarget(string Id, string Type, string Url, Uri WebSocketDebuggerUrl); + +/// +/// Finds the page target through the DevTools HTTP endpoint on http://127.0.0.1:<port> (spec §6.1). +/// Only the loopback interface is ever contacted, never through a proxy. +/// +public static class CdpTargetDiscovery +{ + private static readonly HttpClient Http = new(new SocketsHttpHandler + { + UseProxy = false, + ConnectTimeout = TimeSpan.FromSeconds(2), + AllowAutoRedirect = false, + }) + { + Timeout = TimeSpan.FromSeconds(5), + }; + + /// Base address of the DevTools HTTP endpoint for . + public static Uri EndpointFor(int port) + { + ValidatePort(port); + return new Uri($"http://127.0.0.1:{port.ToString(System.Globalization.CultureInfo.InvariantCulture)}/"); + } + + /// True when the DevTools endpoint answers /json/version. + public static async Task IsAvailableAsync(int port, CancellationToken ct) + { + try + { + using var response = await Http.GetAsync(new Uri(EndpointFor(port), "json/version"), ct).ConfigureAwait(false); + return response.StatusCode == HttpStatusCode.OK; + } + catch (HttpRequestException) + { + return false; + } + catch (TaskCanceledException) when (!ct.IsCancellationRequested) + { + return false; + } + } + + /// Browser version string from /json/version (e.g. «Chrome/141.0.7390.37»), or null. + public static async Task GetBrowserVersionAsync(int port, CancellationToken ct) + { + var version = await Http.GetFromJsonAsync(new Uri(EndpointFor(port), "json/version"), CdpDiscoveryJsonContext.Default.VersionDto, ct).ConfigureAwait(false); + return version?.Browser; + } + + public static async Task> ListAsync(int port, CancellationToken ct) + { + var items = await Http.GetFromJsonAsync(new Uri(EndpointFor(port), "json/list"), CdpDiscoveryJsonContext.Default.ListTargetDto, ct).ConfigureAwait(false); + var targets = new List(); + foreach (var item in items ?? []) + { + if (string.IsNullOrEmpty(item.Id) || string.IsNullOrEmpty(item.WebSocketDebuggerUrl) + || !Uri.TryCreate(item.WebSocketDebuggerUrl, UriKind.Absolute, out var ws)) + { + continue; + } + + EnsureLoopback(ws, port); + targets.Add(new CdpTarget(item.Id, item.Type ?? string.Empty, item.Url ?? string.Empty, ws)); + } + + return targets; + } + + /// The first target of type «page», or null when the browser has none. + public static async Task FindPageAsync(int port, CancellationToken ct) + { + var targets = await ListAsync(port, ct).ConfigureAwait(false); + return targets.FirstOrDefault(t => t.Type == "page"); + } + + /// Refuses any DevTools address that is not on the loopback interface (and, when given, on the expected port). + public static void EnsureLoopback(Uri address, int? expectedPort = null) + { + ArgumentNullException.ThrowIfNull(address); + var host = address.IdnHost.Trim('[', ']'); + var loopback = host.Equals("localhost", StringComparison.OrdinalIgnoreCase) + || (IPAddress.TryParse(host, out var ip) && IPAddress.IsLoopback(ip)); + if (!loopback || address.Scheme is not ("ws" or "http")) + { + throw new InvalidOperationException("Il protocollo DevTools si usa solo su 127.0.0.1 (specifica §6.1)."); + } + + if (expectedPort is { } port && address.Port != port) + { + throw new InvalidOperationException("Il browser ha indicato una porta DevTools diversa da quella fissata."); + } + } + + internal static void ValidatePort(int port) + { + if (port is < 1024 or > 65535) + { + throw new ArgumentOutOfRangeException(nameof(port), port, "La porta di debug deve essere fissa, fra 1024 e 65535 (mai 0)."); + } + } +} + +internal sealed class TargetDto +{ + public string? Id { get; set; } + + public string? Type { get; set; } + + public string? Url { get; set; } + + public string? WebSocketDebuggerUrl { get; set; } +} + +internal sealed class VersionDto +{ + public string? Browser { get; set; } +} + +[JsonSourceGenerationOptions(PropertyNameCaseInsensitive = true)] +[JsonSerializable(typeof(List), TypeInfoPropertyName = "ListTargetDto")] +[JsonSerializable(typeof(VersionDto))] +internal sealed partial class CdpDiscoveryJsonContext : JsonSerializerContext; diff --git a/src/Febe.Browser/Cdp/ReadOnlyScriptGuard.cs b/src/Febe.Browser/Cdp/ReadOnlyScriptGuard.cs new file mode 100644 index 0000000..f08e1e6 --- /dev/null +++ b/src/Febe.Browser/Cdp/ReadOnlyScriptGuard.cs @@ -0,0 +1,48 @@ +using System.Text.RegularExpressions; + +namespace Febe.Browser.Cdp; + +/// +/// Defense in depth for Runtime.evaluate, which spec §6.1 allows only read-only (element positions, +/// address, presence of dialogs). Expressions that click, scroll, focus, fire events, change the DOM or storage, +/// navigate, override properties or build requests by hand are refused before they reach the browser. +/// +/// +/// A deny-list cannot prove an expression harmless: it catches mistakes in Febe's own scripts, which are the only +/// expressions ever evaluated. Gestures go through Input.* only. +/// +public static partial class ReadOnlyScriptGuard +{ + public static void EnsureReadOnly(string? expression) + { + if (string.IsNullOrWhiteSpace(expression)) + { + throw new CdpCommandNotAllowedException("Runtime.evaluate", "Runtime.evaluate senza espressione."); + } + + var match = Forbidden().Match(expression); + if (match.Success) + { + throw new CdpCommandNotAllowedException( + "Runtime.evaluate", + $"Runtime.evaluate si usa solo in sola lettura (specifica §6.1): l'espressione contiene «{match.Value.Trim()}»."); + } + } + + public static bool IsReadOnly(string? expression) => + !string.IsNullOrWhiteSpace(expression) && !Forbidden().IsMatch(expression); + + // Gestures and focus; DOM and attribute changes; navigation and history; property overrides; + // hand-built requests; storage and cookies; synthetic events; assignments to DOM state. + [GeneratedRegex( + @"\.\s*(click|focus|blur|submit|requestSubmit|reset|remove|append|prepend|scroll|scrollTo|scrollBy|scrollIntoView|scrollIntoViewIfNeeded|dispatchEvent|setAttribute|setAttributeNS|removeAttribute|toggleAttribute|appendChild|removeChild|replaceChild|replaceWith|insertBefore|insertAdjacentHTML|insertAdjacentElement|insertAdjacentText|showModal|setSelectionRange|pushState|replaceState|assign|reload|defineProperty|defineProperties|__defineGetter__|__defineSetter__|setItem|removeItem|execCommand)\s*\(" + + @"|\b(fetch|XMLHttpRequest|sendBeacon|WebSocket|EventSource|importScripts|import)\s*\(" + + @"|\bnew\s+(XMLHttpRequest|WebSocket|EventSource|Worker|SharedWorker|\w*Event)\b" + + @"|\b(document\.cookie|localStorage|sessionStorage|indexedDB|cookieStore)\b" + + @"|\.\s*(innerHTML|outerHTML|textContent|innerText|outerText|value|checked|selected|scrollTop|scrollLeft|src|href|cookie|title|hash|search|pathname)\s*(=(?!=)|\+=)" + + @"|\b(location|window\.location|document\.location)\s*=(?!=)" + + @"|\bnavigator\s*\.\s*\w+\s*=(?!=)" + + @"|\b(window\.open|document\.write|document\.writeln|document\.open)\s*\(", + RegexOptions.CultureInvariant)] + private static partial Regex Forbidden(); +} diff --git a/src/Febe.Browser/Cdp/ReconnectingCdpSession.cs b/src/Febe.Browser/Cdp/ReconnectingCdpSession.cs new file mode 100644 index 0000000..cb0b94d --- /dev/null +++ b/src/Febe.Browser/Cdp/ReconnectingCdpSession.cs @@ -0,0 +1,131 @@ +using System.Text.Json; +using Febe.Core.Abstractions; + +namespace Febe.Browser.Cdp; + +/// Notifies components that the CDP connection was replaced (browser restarted). +public interface ICdpConnectionEvents +{ + /// + /// Raised after a new connection replaced a lost one. Domain state (Network.enable, a screencast) + /// is lost with the old connection: components re-enable what they need. Not raised for the first connection. + /// + event EventHandler? Reconnected; +} + +/// Raised by while no browser connection is available. +public sealed class BrowserUnavailableException() + : InvalidOperationException("Il browser non è disponibile in questo momento (avvio o riavvio in corso)."); + +/// +/// A stable on top of a sequence of s: subscriptions survive +/// browser restarts, and commands fail fast with while detached. +/// +public sealed class ReconnectingCdpSession : ICdpSession, ICdpConnectionEvents +{ + private readonly Lock _gate = new(); + private readonly List _registrations = []; + private CdpClient? _client; + private bool _everAttached; + + public event EventHandler? Reconnected; + + public bool IsAttached + { + get + { + lock (_gate) + { + return _client is { IsConnected: true }; + } + } + } + + /// Uses from now on. The caller keeps ownership (and disposes it). + public void Attach(CdpClient client) + { + ArgumentNullException.ThrowIfNull(client); + bool reconnect; + lock (_gate) + { + DetachLocked(); + _client = client; + foreach (var registration in _registrations) + { + registration.Inner = client.On(registration.EventName, registration.Handler); + } + + reconnect = _everAttached; + _everAttached = true; + } + + if (reconnect) + { + Reconnected?.Invoke(this, EventArgs.Empty); + } + } + + /// Stops using the current client (it is not disposed here). + public void Detach() + { + lock (_gate) + { + DetachLocked(); + } + } + + public Task SendAsync(string method, object? parameters = null, CancellationToken ct = default) + { + // Policy first, so a forbidden command is reported as such even while the browser is down. + CdpCommandPolicy.EnsureAllowed(method); + CdpClient? client; + lock (_gate) + { + client = _client; + } + + return client is null ? Task.FromException(new BrowserUnavailableException()) : client.SendAsync(method, parameters, ct); + } + + public IDisposable On(string eventName, Action handler) + { + ArgumentException.ThrowIfNullOrEmpty(eventName); + ArgumentNullException.ThrowIfNull(handler); + var registration = new Registration(eventName, handler); + lock (_gate) + { + _registrations.Add(registration); + registration.Inner = _client?.On(eventName, handler); + } + + return new Subscription(() => + { + lock (_gate) + { + _registrations.Remove(registration); + registration.Inner?.Dispose(); + registration.Inner = null; + } + }); + } + + private void DetachLocked() + { + foreach (var registration in _registrations) + { + registration.Inner?.Dispose(); + registration.Inner = null; + } + + _client = null; + } + + private sealed class Registration(string eventName, Action handler) + { + public string EventName { get; } = eventName; + + public Action Handler { get; } = handler; + + public IDisposable? Inner { get; set; } + } +} diff --git a/src/Febe.Browser/Diagnostics/IBrowserLog.cs b/src/Febe.Browser/Diagnostics/IBrowserLog.cs new file mode 100644 index 0000000..f07da3f --- /dev/null +++ b/src/Febe.Browser/Diagnostics/IBrowserLog.cs @@ -0,0 +1,48 @@ +namespace Febe.Browser.Diagnostics; + +public enum BrowserLogLevel +{ + Debug, + Information, + Warning, + Error, +} + +/// +/// Log sink of the browser layer. The host application adapts it to its own logging. +/// Messages never contain parameters or results of CDP commands, cookies, keystrokes, bodies or CDN addresses +/// (spec §2 rule 11, §13.2): only command and event names, states and counts. +/// +public interface IBrowserLog +{ + void Write(BrowserLogLevel level, string message, Exception? exception = null); +} + +/// Discards everything. +public sealed class NullBrowserLog : IBrowserLog +{ + public static NullBrowserLog Instance { get; } = new(); + + public void Write(BrowserLogLevel level, string message, Exception? exception = null) + { + } +} + +/// Forwards to a delegate (handy for tests and console tools). +public sealed class DelegateBrowserLog(Action write) : IBrowserLog +{ + public void Write(BrowserLogLevel level, string message, Exception? exception = null) => write(level, message, exception); +} + +internal static class BrowserLogExtensions +{ + public static void Debug(this IBrowserLog log, string message) => log.Write(BrowserLogLevel.Debug, message); + + public static void Info(this IBrowserLog log, string message) => log.Write(BrowserLogLevel.Information, message); + + public static void Warn(this IBrowserLog log, string message, Exception? exception = null) => + log.Write(BrowserLogLevel.Warning, message, exception); + + public static void Error(this IBrowserLog log, string message, Exception? exception = null) => + log.Write(BrowserLogLevel.Error, message, exception); +} diff --git a/src/Febe.Browser/Download/BrowserFileFetcher.cs b/src/Febe.Browser/Download/BrowserFileFetcher.cs new file mode 100644 index 0000000..92d0a04 --- /dev/null +++ b/src/Febe.Browser/Download/BrowserFileFetcher.cs @@ -0,0 +1,162 @@ +using System.Text; +using System.Text.Json; +using System.Text.Json.Nodes; +using Febe.Browser.Cdp; +using Febe.Browser.Diagnostics; +using Febe.Core.Abstractions; +using Febe.Core.Collection; + +namespace Febe.Browser.Download; + +/// Options of . +public sealed record BrowserFetchOptions +{ + /// Bytes requested per IO.read. + public int ChunkBytes { get; init; } = 1024 * 1024; + + /// + /// Whether the browser attaches its cookies for the file's host (includeCredentials). Off by default: + /// CDN addresses are signed and need none. To revisit with H7 in M0. + /// + public bool IncludeCredentials { get; init; } + + /// Host kinds that may be downloaded: the CDN only, by default (spec §2 rule 1, §6.5). + public IReadOnlySet AllowedHostKinds { get; init; } = new HashSet { HostKind.Cdn }; +} + +/// +/// Downloads a file through the browser itself (spec §6.5 point 2): Page.getFrameTree for the frame id, +/// Network.loadNetworkResource, then IO.read in chunks into the caller's stream and IO.close. +/// +/// The address is never logged (it carries signatures, spec §13.2). +public sealed class BrowserFileFetcher : IFileFetcher +{ + private readonly ICdpSession _cdp; + private readonly HostClassifier _hosts; + private readonly IBrowserLog _log; + private readonly BrowserFetchOptions _options; + + public BrowserFileFetcher(ICdpSession cdp, HostClassifier hosts, IBrowserLog? log = null, BrowserFetchOptions? options = null) + { + _cdp = cdp ?? throw new ArgumentNullException(nameof(cdp)); + _hosts = hosts ?? throw new ArgumentNullException(nameof(hosts)); + _log = log ?? NullBrowserLog.Instance; + _options = options ?? new BrowserFetchOptions(); + if (_options.ChunkBytes is < 4096 or > 16 * 1024 * 1024) + { + throw new ArgumentOutOfRangeException(nameof(options), "La dimensione dei blocchi deve stare fra 4 KB e 16 MB."); + } + } + + public async Task FetchAsync(Uri address, Stream destination, FetchOptions? options, CancellationToken ct) + { + ArgumentNullException.ThrowIfNull(address); + ArgumentNullException.ThrowIfNull(destination); + if (!_options.AllowedHostKinds.Contains(_hosts.Classify(address))) + { + return new FetchResult(FetchOutcome.HostNotAllowed, 0, null, "Indirizzo fuori dai domini ammessi per lo scaricamento."); + } + + var frameId = await _cdp.GetMainFrameIdAsync(ct).ConfigureAwait(false); + var loaded = await _cdp.SendAsync( + "Network.loadNetworkResource", + new JsonObject + { + ["frameId"] = frameId, + ["url"] = address.AbsoluteUri, + ["options"] = new JsonObject + { + ["disableCache"] = false, + ["includeCredentials"] = _options.IncludeCredentials, + }, + }, + ct).ConfigureAwait(false); + + if (loaded.ValueKind != JsonValueKind.Object || !loaded.TryGetProperty("resource", out var resource)) + { + return new FetchResult(FetchOutcome.NetworkError, 0, null, "Il browser non ha descritto la risorsa."); + } + + var status = resource.TryGetProperty("httpStatusCode", out var s) && s.TryGetDouble(out var sd) ? (int?)sd : null; + var success = resource.TryGetProperty("success", out var ok) && ok.ValueKind == JsonValueKind.True; + var handle = resource.TryGetProperty("stream", out var st) ? st.GetString() : null; + + if (!success) + { + if (handle is not null) + { + await CloseQuietlyAsync(handle).ConfigureAwait(false); + } + + var netError = resource.TryGetProperty("netErrorName", out var n) ? n.GetString() : null; + return status is { } code and >= 400 + ? new FetchResult(FetchOutcome.HttpError, 0, code, $"Il server ha risposto {code}.") + : new FetchResult(FetchOutcome.NetworkError, 0, status, netError ?? "Errore di rete."); + } + + if (handle is null) + { + return new FetchResult(FetchOutcome.NetworkError, 0, status, "Il browser non ha aperto il flusso dei dati."); + } + + long written = 0; + try + { + while (true) + { + ct.ThrowIfCancellationRequested(); + var chunk = await _cdp.SendAsync( + "IO.read", + new JsonObject { ["handle"] = handle, ["size"] = _options.ChunkBytes }, + ct).ConfigureAwait(false); + + var data = chunk.TryGetProperty("data", out var d) ? d : default; + var base64 = chunk.TryGetProperty("base64Encoded", out var b) && b.ValueKind == JsonValueKind.True; + var eof = chunk.TryGetProperty("eof", out var e) && e.ValueKind == JsonValueKind.True; + + if (data.ValueKind == JsonValueKind.String) + { + var bytes = base64 ? data.GetBytesFromBase64() : Encoding.UTF8.GetBytes(data.GetString() ?? string.Empty); + if (options?.MaxBytes is { } max && written + bytes.Length > max) + { + var allowed = (int)Math.Max(0, max - written); + await destination.WriteAsync(bytes.AsMemory(0, allowed), ct).ConfigureAwait(false); + written += allowed; + return new FetchResult(FetchOutcome.TooLarge, written, status, "Il file supera la dimensione massima ammessa."); + } + + await destination.WriteAsync(bytes, ct).ConfigureAwait(false); + written += bytes.Length; + options?.Progress?.Report(written); + } + + if (eof) + { + break; + } + } + } + finally + { + await CloseQuietlyAsync(handle).ConfigureAwait(false); + } + + await destination.FlushAsync(ct).ConfigureAwait(false); + return status is { } httpStatus and >= 400 + ? new FetchResult(FetchOutcome.HttpError, written, httpStatus, $"Il server ha risposto {httpStatus}.") + : new FetchResult(FetchOutcome.Completed, written, status, null); + } + + private async Task CloseQuietlyAsync(string handle) + { + try + { + using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(5)); + await _cdp.SendAsync("IO.close", new JsonObject { ["handle"] = handle }, timeout.Token).ConfigureAwait(false); + } + catch (Exception ex) when (ex is CdpCommandException or CdpDisconnectedException or BrowserUnavailableException or OperationCanceledException or TimeoutException) + { + _log.Debug("Scaricamento: chiusura del flusso non riuscita."); + } + } +} diff --git a/src/Febe.Browser/Gestures/GestureSettings.cs b/src/Febe.Browser/Gestures/GestureSettings.cs new file mode 100644 index 0000000..1e83e73 --- /dev/null +++ b/src/Febe.Browser/Gestures/GestureSettings.cs @@ -0,0 +1,82 @@ +namespace Febe.Browser.Gestures; + +/// A point in CSS pixels relative to the page viewport (the coordinate space of Input.*). +public readonly record struct PagePoint(double X, double Y) +{ + public double DistanceTo(PagePoint other) => Math.Sqrt(((X - other.X) * (X - other.X)) + ((Y - other.Y) * (Y - other.Y))); +} + +/// A rectangle in CSS pixels relative to the page viewport. +public readonly record struct PageRect(double X, double Y, double Width, double Height) +{ + public PagePoint Center => new(X + (Width / 2), Y + (Height / 2)); + + public double Right => X + Width; + + public double Bottom => Y + Height; + + public bool Contains(PagePoint p) => p.X >= X && p.X <= Right && p.Y >= Y && p.Y <= Bottom; +} + +/// An interval «from a to b» with an optional median (spec §7.2), in the unit of its use. +public readonly record struct Interval(double Min, double Max, double? Median = null); + +/// +/// Gesture timings for the «naturale» pace (spec §7.7). Every wait is multiplied by the session mood and by the +/// pace factor. Milliseconds unless stated otherwise. +/// +public sealed record GestureSettings +{ + public static GestureSettings Natural { get; } = new(); + + /// Pointer travel time. + public Interval MoveDurationMs { get; init; } = new(250, 900); + + /// Interval between pointer events: about 60 per second. + public double PointerEventIntervalMs { get; init; } = 1000.0 / 60.0; + + /// Largest sideways bend of the path, as a fraction of the distance (a slightly curved path). + public Interval PathBendFraction { get; init; } = new(0.02, 0.12); + + /// Part of the target, around its centre, where the pointer lands (0.6 = central 60% in each direction). + public double CentralFraction { get; init; } = 0.6; + + /// Hover on the target before pressing. + public Interval HoverMs { get; init; } = new(80, 300); + + /// Time between press and release. + public Interval PressMs { get; init; } = new(50, 140); + + /// Wheel events in a burst. + public (int Min, int Max) WheelEventsPerBurst { get; init; } = (3, 8); + + /// Pixels per wheel event. + public Interval WheelDeltaPx { get; init; } = new(80, 140); + + /// Interval between the wheel events of a burst. + public Interval WheelIntervalMs { get; init; } = new(12, 40); + + /// Pause between bursts. + public Interval BetweenBurstsMs { get; init; } = new(400, 4000, 1100); + + /// Bursts between two reading pauses. + public (int Min, int Max) BurstsBeforeReading { get; init; } = (6, 10); + + /// Reading pause. + public Interval ReadingPauseMs { get; init; } = new(3000, 20000, 6000); + + /// Probability of a small scroll back after a burst. + public double ScrollBackProbability { get; init; } = 0.1; + + /// Pixels per wheel event of a scroll back. + public Interval ScrollBackDeltaPx { get; init; } = new(40, 100); + + /// Wait after a page load before the first gesture. + public Interval AfterLoadMs { get; init; } = new(1000, 6000, 2200); + + /// Probability of a distraction after an action. + public double DistractionProbability { get; init; } = 0.08; + + /// Length of a distraction. + public Interval DistractionMs { get; init; } = new(15000, 90000); +} diff --git a/src/Febe.Browser/Gestures/HumanGestures.cs b/src/Febe.Browser/Gestures/HumanGestures.cs new file mode 100644 index 0000000..388932d --- /dev/null +++ b/src/Febe.Browser/Gestures/HumanGestures.cs @@ -0,0 +1,381 @@ +using System.Text.Json.Nodes; +using Febe.Core.Abstractions; +using Febe.Core.Domain; +using Febe.Core.Pacing; + +namespace Febe.Browser.Gestures; + +/// A gesture was not performed because Alberto is using the browser (spec §4.1: the engine stays still). +public sealed class GestureInterruptedException() + : OperationCanceledException("Alberto sta usando il browser: il gesto non è stato eseguito."); + +/// +/// Human gestures through Input.* only (spec §6.1, §7.7): never Runtime.evaluate to scroll or click. +/// All timing goes through and every draw through , so tests run +/// under a virtual clock with a fixed seed. +/// +/// +/// Rules: the pointer never jumps (it travels along a slightly curved path at about 60 events per second); +/// it lands on a random point in the central part of the target, never the exact centre; every wait is multiplied +/// by the session mood and the pace factor. Not thread-safe: one gesture at a time. +/// +public sealed class HumanGestures +{ + private readonly ICdpSession _cdp; + private readonly IClock _clock; + private readonly IRandomSource _random; + private readonly Func _userIsDriving; + private int _burstsUntilReading; + private PagePoint? _pointer; + + /// Page session. + /// Time source for every wait. + /// Random source for every draw. + /// Session mood (see ), drawn once per session. + /// The «Ritmo dei gesti» slider. + /// When it returns true, gestures throw . + /// Timings; by default. + public HumanGestures( + ICdpSession cdp, + IClock clock, + IRandomSource random, + double mood = 1.0, + GesturePace pace = GesturePace.Natural, + Func? userIsDriving = null, + GestureSettings? settings = null) + { + _cdp = cdp ?? throw new ArgumentNullException(nameof(cdp)); + _clock = clock ?? throw new ArgumentNullException(nameof(clock)); + _random = random ?? throw new ArgumentNullException(nameof(random)); + if (mood <= 0 || double.IsNaN(mood)) + { + throw new ArgumentOutOfRangeException(nameof(mood), mood, "The mood must be positive."); + } + + Mood = mood; + Pace = pace; + _userIsDriving = userIsDriving ?? (static () => false); + Settings = settings ?? GestureSettings.Natural; + _burstsUntilReading = _random.CountBetween(Settings.BurstsBeforeReading.Min, Settings.BurstsBeforeReading.Max); + } + + public double Mood { get; } + + public GesturePace Pace { get; } + + public GestureSettings Settings { get; } + + /// Factor applied to every wait: mood × pace. + public double Multiplier => Mood * GesturePaceFactors.For(Pace); + + /// Where the pointer is, or null before the first gesture. + public PagePoint? Pointer => _pointer; + + /// Viewport size in CSS pixels; used to place the pointer before its first move. + public (double Width, double Height) Viewport { get; set; } = (1280, 900); + + /// Moves the pointer to along a slightly curved, eased path. + public async Task MoveToAsync(PagePoint target, CancellationToken ct = default) + { + EnsureUserNotDriving(); + var start = _pointer ?? InitialPointer(); + var distance = start.DistanceTo(target); + if (distance < 0.5) + { + _pointer = target; + return; + } + + var duration = Draw(Settings.MoveDurationMs) * Multiplier; + var path = BuildPath(start, target); + var steps = Math.Max(3, (int)Math.Ceiling(duration / Settings.PointerEventIntervalMs)); + var stepDelay = duration / steps; + + // Plan the events first: a step that does not change pixel sends nothing (a mouse that does not move + // fires no event) and its time is added to the next event; the still tail at the end is dropped, so the + // movement ends with its last visible event. + var plan = new List<(double DelayMs, PagePoint At)>(steps); + var pending = 0.0; + var last = new PagePoint(Math.Round(start.X), Math.Round(start.Y)); + for (var i = 1; i <= steps; i++) + { + pending += stepDelay * _random.Between(0.85, 1.15); + var p = i == steps ? target : path.At(EaseInOut((double)i / steps)); + var rounded = new PagePoint(Math.Round(p.X), Math.Round(p.Y)); + if (rounded == last) + { + continue; + } + + plan.Add((pending, rounded)); + pending = 0; + last = rounded; + } + + foreach (var (delay, at) in plan) + { + await _clock.Delay(TimeSpan.FromMilliseconds(delay), ct).ConfigureAwait(false); + EnsureUserNotDriving(); + await DispatchMouseAsync("mouseMoved", at, "none", buttons: 0, clickCount: 0, ct).ConfigureAwait(false); + _pointer = at; + } + + _pointer = target; + } + + /// + /// A point inside the central part of , never its exact centre + /// (offsets follow a normal distribution, kept within the central fraction). + /// + public PagePoint ChooseTargetPoint(PageRect box) + { + var half = Settings.CentralFraction / 2; + var dx = DrawOffset(half) * box.Width; + var dy = DrawOffset(half) * box.Height; + if (Math.Abs(dx) < 1 && Math.Abs(dy) < 1) + { + // Never the exact centre: nudge by at least one pixel when the box allows it. + dx = Math.Min(box.Width * half, 1 + (box.Width * 0.05)) * (_random.Chance(0.5) ? 1 : -1); + } + + var center = box.Center; + return new PagePoint(center.X + dx, center.Y + dy); + } + + /// Travels to a random point of the central part of , hovers, presses and releases. + public async Task ClickAsync(PageRect box, CancellationToken ct = default) + { + var point = ChooseTargetPoint(box); + await MoveToAsync(point, ct).ConfigureAwait(false); + var at = new PagePoint(Math.Round(point.X), Math.Round(point.Y)); + await WaitAsync(Settings.HoverMs, ct).ConfigureAwait(false); + EnsureUserNotDriving(); + await DispatchMouseAsync("mousePressed", at, "left", buttons: 1, clickCount: 1, ct).ConfigureAwait(false); + await WaitAsync(Settings.PressMs, ct).ConfigureAwait(false); + await DispatchMouseAsync("mouseReleased", at, "left", buttons: 0, clickCount: 1, ct).ConfigureAwait(false); + return at; + } + + /// + /// One burst of wheel events (3–8 of 80–140 px, 12–40 ms apart) with decreasing speed: deltas shrink and + /// intervals grow. is +1 down, -1 up. Returns the pixels requested. + /// + public async Task ScrollBurstAsync(int direction = 1, CancellationToken ct = default) + { + EnsureUserNotDriving(); + var count = _random.CountBetween(Settings.WheelEventsPerBurst.Min, Settings.WheelEventsPerBurst.Max); + var deltas = Enumerable.Range(0, count).Select(_ => Math.Round(Draw(Settings.WheelDeltaPx))).OrderByDescending(d => d).ToArray(); + var intervals = Enumerable.Range(0, count - 1).Select(_ => Draw(Settings.WheelIntervalMs) * Multiplier).Order().ToArray(); + return await WheelAsync(deltas, intervals, Math.Sign(direction == 0 ? 1 : direction), ct).ConfigureAwait(false); + } + + /// A small scroll back: one or two short wheel events in the opposite direction. + public async Task ScrollBackAsync(int direction = 1, CancellationToken ct = default) + { + EnsureUserNotDriving(); + var count = _random.Chance(0.5) ? 1 : 2; + var deltas = Enumerable.Range(0, count).Select(_ => Math.Round(Draw(Settings.ScrollBackDeltaPx))).OrderByDescending(d => d).ToArray(); + var intervals = Enumerable.Range(0, count - 1).Select(_ => Draw(Settings.WheelIntervalMs) * Multiplier).Order().ToArray(); + return await WheelAsync(deltas, intervals, -Math.Sign(direction == 0 ? 1 : direction), ct).ConfigureAwait(false); + } + + /// + /// The pause after a burst: normally 0.4–4 s (median 1.1 s); every 6–10 bursts a reading pause of 3–20 s (median 6 s). + /// Returns true when it was a reading pause. + /// + public async Task PauseAfterBurstAsync(CancellationToken ct = default) + { + if (--_burstsUntilReading <= 0) + { + _burstsUntilReading = _random.CountBetween(Settings.BurstsBeforeReading.Min, Settings.BurstsBeforeReading.Max); + await WaitAsync(Settings.ReadingPauseMs, ct).ConfigureAwait(false); + return true; + } + + await WaitAsync(Settings.BetweenBurstsMs, ct).ConfigureAwait(false); + return false; + } + + /// + /// Scrolls with up to bursts, with pauses, reading pauses and occasional small scroll + /// backs. After each burst and its pause decides whether to go on (e.g. the + /// recipe met known content). Returns the number of bursts. + /// + public async Task ScrollAsync(int maxBursts, Func>? shouldContinue = null, int direction = 1, CancellationToken ct = default) + { + var bursts = 0; + while (bursts < maxBursts) + { + await ScrollBurstAsync(direction, ct).ConfigureAwait(false); + bursts++; + if (_random.Chance(Settings.ScrollBackProbability)) + { + await WaitAsync(new Interval(150, 600), ct).ConfigureAwait(false); + await ScrollBackAsync(direction, ct).ConfigureAwait(false); + } + + await PauseAfterBurstAsync(ct).ConfigureAwait(false); + if (shouldContinue is not null && !await shouldContinue(ct).ConfigureAwait(false)) + { + break; + } + } + + return bursts; + } + + /// The wait after a page load before the first gesture (median 2.2 s, 1–6 s). + public Task WaitAfterLoadAsync(CancellationToken ct = default) => WaitAsync(Settings.AfterLoadMs, ct); + + /// With 8% probability, an extra wait of 15–90 s after an action. Returns true when it happened. + public async Task MaybeDistractionAsync(CancellationToken ct = default) + { + if (!_random.Chance(Settings.DistractionProbability)) + { + return false; + } + + await WaitAsync(Settings.DistractionMs, ct).ConfigureAwait(false); + return true; + } + + /// Waits a drawn time from (milliseconds), multiplied by mood and pace. + public async Task WaitAsync(Interval interval, CancellationToken ct = default) + { + var wait = TimeSpan.FromMilliseconds(Draw(interval) * Multiplier); + await _clock.Delay(wait, ct).ConfigureAwait(false); + return wait; + } + + private async Task WheelAsync(double[] deltas, double[] intervals, int sign, CancellationToken ct) + { + if (_pointer is not { } at) + { + // The page has never seen the pointer: it enters where the mouse rests, as when it enters the window. + at = InitialPointer(); + await DispatchMouseAsync("mouseMoved", at, "none", buttons: 0, clickCount: 0, ct).ConfigureAwait(false); + await WaitAsync(new Interval(120, 500), ct).ConfigureAwait(false); + } + + var position = new PagePoint(Math.Round(at.X), Math.Round(at.Y)); + double total = 0; + for (var i = 0; i < deltas.Length; i++) + { + if (i > 0) + { + await _clock.Delay(TimeSpan.FromMilliseconds(intervals[i - 1]), ct).ConfigureAwait(false); + } + + EnsureUserNotDriving(); + await _cdp.SendAsync( + "Input.dispatchMouseEvent", + new JsonObject + { + ["type"] = "mouseWheel", + ["x"] = position.X, + ["y"] = position.Y, + ["deltaX"] = 0, + ["deltaY"] = sign * deltas[i], + ["pointerType"] = "mouse", + }, + ct).ConfigureAwait(false); + total += deltas[i]; + } + + return sign * total; + } + + private Task DispatchMouseAsync(string type, PagePoint at, string button, int buttons, int clickCount, CancellationToken ct) + { + var parameters = new JsonObject + { + ["type"] = type, + ["x"] = at.X, + ["y"] = at.Y, + ["button"] = button, + ["buttons"] = buttons, + ["pointerType"] = "mouse", + }; + if (clickCount > 0) + { + parameters["clickCount"] = clickCount; + } + + return _cdp.SendAsync("Input.dispatchMouseEvent", parameters, ct); + } + + private void EnsureUserNotDriving() + { + if (_userIsDriving()) + { + throw new GestureInterruptedException(); + } + } + + private PagePoint InitialPointer() + { + // Somewhere in the middle of the page, as if the mouse had been left there. + var x = Viewport.Width * _random.Between(0.35, 0.65); + var y = Viewport.Height * _random.Between(0.35, 0.65); + var p = new PagePoint(Math.Round(x), Math.Round(y)); + _pointer = p; + return p; + } + + private double Draw(Interval interval) => _random.Between(interval.Min, interval.Max, interval.Median); + + /// Offset in [-limit, limit] around 0, normal with σ = limit/2, never exactly 0. + private double DrawOffset(double limit) + { + for (var attempt = 0; attempt < 16; attempt++) + { + var value = _random.Normal(0, limit / 2); + if (Math.Abs(value) <= limit) + { + return value; + } + } + + return limit / 3; + } + + private BezierPath BuildPath(PagePoint start, PagePoint end) + { + var dx = end.X - start.X; + var dy = end.Y - start.Y; + var length = Math.Sqrt((dx * dx) + (dy * dy)); + var nx = -dy / length; + var ny = dx / length; + + // An arc most of the time, an S now and then; both bends are a small fraction of the distance. + var side = _random.Chance(0.5) ? 1 : -1; + var bend1 = Draw(Settings.PathBendFraction) * length * side; + var bend2 = Draw(Settings.PathBendFraction) * length * (_random.Chance(0.8) ? side : -side); + var t1 = _random.Between(0.2, 0.4); + var t2 = _random.Between(0.6, 0.8); + var c1 = new PagePoint(start.X + (dx * t1) + (nx * bend1), start.Y + (dy * t1) + (ny * bend1)); + var c2 = new PagePoint(start.X + (dx * t2) + (nx * bend2), start.Y + (dy * t2) + (ny * bend2)); + return new BezierPath(start, c1, c2, end); + } + + /// + /// Ease-in-out with the minimum-jerk profile of human reaching movements (10t³ − 15t⁴ + 6t⁵): + /// slow start, slow arrival, peak speed 1.875 times the average. + /// + internal static double EaseInOut(double t) => t * t * t * (10 + (t * ((6 * t) - 15))); + + private readonly record struct BezierPath(PagePoint P0, PagePoint P1, PagePoint P2, PagePoint P3) + { + public PagePoint At(double t) + { + var u = 1 - t; + var a = u * u * u; + var b = 3 * u * u * t; + var c = 3 * u * t * t; + var d = t * t * t; + return new PagePoint( + (a * P0.X) + (b * P1.X) + (c * P2.X) + (d * P3.X), + (a * P0.Y) + (b * P1.Y) + (c * P2.Y) + (d * P3.Y)); + } + } +} diff --git a/src/Febe.Browser/Gestures/Keyboard.cs b/src/Febe.Browser/Gestures/Keyboard.cs new file mode 100644 index 0000000..431acb3 --- /dev/null +++ b/src/Febe.Browser/Gestures/Keyboard.cs @@ -0,0 +1,177 @@ +using System.Globalization; +using System.Text.Json.Nodes; +using Febe.Core.Abstractions; +using Febe.Core.Pacing; + +namespace Febe.Browser.Gestures; + +/// Modifier keys, with the bit values of Input.dispatchKeyEvent. +[Flags] +public enum KeyModifiers +{ + None = 0, + Alt = 1, + Control = 2, + Meta = 4, + Shift = 8, +} + +/// Keys that are not text. +public enum SpecialKey +{ + Enter, + Tab, + Backspace, + Delete, + Escape, + ArrowLeft, + ArrowRight, + ArrowUp, + ArrowDown, + Home, + End, + PageUp, + PageDown, +} + +/// +/// One key as the interface reports it (DOM KeyboardEvent fields). Contains what Alberto types: +/// it is never logged or stored (spec §13.2). +/// +/// DOM key («a», «Enter», «è»). +/// DOM code («KeyA», «Enter»); may be empty. +/// Windows virtual key code (DOM keyCode); 0 when unknown. +/// Modifier keys held. +/// Text the key produces, or null for keys that produce none. +public sealed record KeyStroke(string Key, string Code, int KeyCode, KeyModifiers Modifiers, string? Text) +{ + public override string ToString() => "KeyStroke(…)"; +} + +/// Keyboard input through Input.dispatchKeyEvent only. +public static class Keyboard +{ + public static KeyStroke Special(SpecialKey key, KeyModifiers modifiers = KeyModifiers.None) => key switch + { + SpecialKey.Enter => new("Enter", "Enter", 13, modifiers, "\r"), + SpecialKey.Tab => new("Tab", "Tab", 9, modifiers, null), + SpecialKey.Backspace => new("Backspace", "Backspace", 8, modifiers, null), + SpecialKey.Delete => new("Delete", "Delete", 46, modifiers, null), + SpecialKey.Escape => new("Escape", "Escape", 27, modifiers, null), + SpecialKey.ArrowLeft => new("ArrowLeft", "ArrowLeft", 37, modifiers, null), + SpecialKey.ArrowUp => new("ArrowUp", "ArrowUp", 38, modifiers, null), + SpecialKey.ArrowRight => new("ArrowRight", "ArrowRight", 39, modifiers, null), + SpecialKey.ArrowDown => new("ArrowDown", "ArrowDown", 40, modifiers, null), + SpecialKey.Home => new("Home", "Home", 36, modifiers, null), + SpecialKey.End => new("End", "End", 35, modifiers, null), + SpecialKey.PageUp => new("PageUp", "PageUp", 33, modifiers, null), + SpecialKey.PageDown => new("PageDown", "PageDown", 34, modifiers, null), + _ => throw new ArgumentOutOfRangeException(nameof(key), key, null), + }; + + /// The key for one character of text. + public static KeyStroke ForText(string character) + { + ArgumentException.ThrowIfNullOrEmpty(character); + if (character is "\n" or "\r") + { + return Special(SpecialKey.Enter); + } + + var code = string.Empty; + var keyCode = 0; + if (character.Length == 1) + { + var c = character[0]; + if (c is >= 'a' and <= 'z' or >= 'A' and <= 'Z') + { + code = "Key" + char.ToUpperInvariant(c).ToString(CultureInfo.InvariantCulture); + keyCode = char.ToUpperInvariant(c); + } + else if (c is >= '0' and <= '9') + { + code = "Digit" + c.ToString(CultureInfo.InvariantCulture); + keyCode = c; + } + else if (c == ' ') + { + code = "Space"; + keyCode = 32; + } + } + + var shift = character.Length == 1 && char.IsUpper(character[0]) ? KeyModifiers.Shift : KeyModifiers.None; + return new KeyStroke(character, code, keyCode, shift, character); + } + + public static Task KeyDownAsync(ICdpSession cdp, KeyStroke key, CancellationToken ct = default) + { + ArgumentNullException.ThrowIfNull(key); + + // «keyDown» with text inserts it; keys without text (or with Ctrl/Meta shortcuts) use «rawKeyDown». + var producesText = key.Text is not null && (key.Modifiers & (KeyModifiers.Control | KeyModifiers.Meta)) == 0; + var parameters = Build(producesText ? "keyDown" : "rawKeyDown", key); + if (producesText) + { + parameters["text"] = key.Text; + parameters["unmodifiedText"] = key.Text; + } + + return cdp.SendAsync("Input.dispatchKeyEvent", parameters, ct); + } + + public static Task KeyUpAsync(ICdpSession cdp, KeyStroke key, CancellationToken ct = default) => + cdp.SendAsync("Input.dispatchKeyEvent", Build("keyUp", key), ct); + + /// Presses and releases one key, with a human hold time when a clock is given. + public static async Task PressAsync(ICdpSession cdp, KeyStroke key, IClock? clock = null, IRandomSource? random = null, CancellationToken ct = default) + { + await KeyDownAsync(cdp, key, ct).ConfigureAwait(false); + if (clock is not null && random is not null) + { + await clock.Delay(TimeSpan.FromMilliseconds(random.Between(40, 120)), ct).ConfigureAwait(false); + } + + await KeyUpAsync(cdp, key, ct).ConfigureAwait(false); + } + + /// Types one character at a time, 60–250 ms apart. + public static async Task TypeTextAsync(ICdpSession cdp, string text, IClock clock, IRandomSource random, CancellationToken ct = default) + { + ArgumentNullException.ThrowIfNull(text); + var enumerator = StringInfo.GetTextElementEnumerator(text); + var first = true; + while (enumerator.MoveNext()) + { + if (!first) + { + await clock.Delay(TimeSpan.FromMilliseconds(random.Between(60, 250, 110)), ct).ConfigureAwait(false); + } + + first = false; + await PressAsync(cdp, ForText(enumerator.GetTextElement()), clock, random, ct).ConfigureAwait(false); + } + } + + private static JsonObject Build(string type, KeyStroke key) + { + var parameters = new JsonObject + { + ["type"] = type, + ["key"] = key.Key, + ["modifiers"] = (int)key.Modifiers, + }; + if (!string.IsNullOrEmpty(key.Code)) + { + parameters["code"] = key.Code; + } + + if (key.KeyCode > 0) + { + parameters["windowsVirtualKeyCode"] = key.KeyCode; + parameters["nativeVirtualKeyCode"] = key.KeyCode; + } + + return parameters; + } +} diff --git a/src/Febe.Browser/Hosting/ChromiumCommandLine.cs b/src/Febe.Browser/Hosting/ChromiumCommandLine.cs new file mode 100644 index 0000000..c7546a4 --- /dev/null +++ b/src/Febe.Browser/Hosting/ChromiumCommandLine.cs @@ -0,0 +1,182 @@ +using System.Globalization; +using Febe.Core.Abstractions; + +namespace Febe.Browser.Hosting; + +/// Where the session cookie is looked for (existence only, never the value). +/// Cookie name. Instagram's is «sessionid» (public knowledge; hypothesis H10, to confirm in M0). +/// Address whose cookies are listed. +public sealed record SessionCookieOptions(string CookieName, string SiteUrl) +{ + public static SessionCookieOptions Instagram { get; } = new("sessionid", "https://www.instagram.com/"); +} + +/// Chromium-specific launch settings, on top of . +public sealed record ChromiumLaunchOptions +{ + /// + /// Adds --no-sandbox. Only as the documented compromise of S5 (spec §11), never by default: + /// as root Chromium refuses to start without it; as a normal user with user namespaces it is not needed. + /// + public bool NoSandbox { get; init; } + + /// Extra arguments, checked by . + public IReadOnlyList ExtraArguments { get; init; } = []; + + /// Environment overrides for the browser process (e.g. LANG, TZ in tests). A null value removes the variable. + public IReadOnlyDictionary Environment { get; init; } = new Dictionary(); + + /// Start page: always the rest page. + public string StartUrl { get; init; } = "about:blank"; + + public TimeSpan StartupTimeout { get; init; } = TimeSpan.FromSeconds(30); + + public RestartPolicy Restart { get; init; } = RestartPolicy.Default; + + public SessionCookieOptions SessionCookie { get; init; } = SessionCookieOptions.Instagram; + + /// + /// On a new profile, writes preferences that turn off password saving and autofill (spec §6.1, §11). + /// The Docker image also ships a policy file for the same purpose. + /// + public bool SeedProfilePreferences { get; init; } = true; +} + +/// +/// Builds Chromium's command line (spec §6.1, §11): a normal windowed browser with a fixed debugging port on +/// 127.0.0.1. Never headless, never automation mode, never user agent, language or proxy overrides: +/// language comes from LANG and the time zone from TZ. +/// +public static class ChromiumCommandLine +{ + /// Arguments refused in , by prefix. + public static IReadOnlyList ForbiddenPrefixes { get; } = + [ + "--headless", + "--enable-automation", + "--remote-debugging-pipe", + "--remote-debugging-port", + "--remote-debugging-address", + "--remote-allow-origins", + "--user-agent", + "--lang", + "--accept-lang", + "--proxy-server", + "--proxy-pac-url", + "--proxy-auto-detect", + "--proxy-bypass-list", + "--no-proxy-server", + "--host-resolver-rules", + "--disable-blink-features", + "--enable-blink-features", + "--blink-settings", + "--disable-web-security", + "--load-extension", + "--disable-extensions-except", + "--user-data-dir", + "--window-size", + "--use-mobile-user-agent", + "--force-device-scale-factor", + "--auto-open-devtools-for-tabs", + "--no-sandbox", + ]; + + public static IReadOnlyList Build(BrowserOptions options, ChromiumLaunchOptions launch) + { + ArgumentNullException.ThrowIfNull(options); + ArgumentNullException.ThrowIfNull(launch); + if (options.DebugPort is < 1024 or > 65535) + { + throw new ArgumentOutOfRangeException(nameof(options), options.DebugPort, "La porta di debug deve essere fissa, fra 1024 e 65535: mai 0 (specifica §6.1)."); + } + + if (options.WindowWidth < 400 || options.WindowHeight < 300) + { + throw new ArgumentOutOfRangeException(nameof(options), "La finestra del browser è troppo piccola."); + } + + ArgumentException.ThrowIfNullOrWhiteSpace(options.ProfileDirectory); + + var inv = CultureInfo.InvariantCulture; + var args = new List + { + $"--remote-debugging-port={options.DebugPort.ToString(inv)}", + $"--user-data-dir={Path.GetFullPath(options.ProfileDirectory)}", + "--no-first-run", + "--no-default-browser-check", + $"--window-size={options.WindowWidth.ToString(inv)},{options.WindowHeight.ToString(inv)}", + "--window-position=0,0", + "--password-store=basic", + "--disable-dev-shm-usage", + }; + + if (launch.NoSandbox) + { + args.Add("--no-sandbox"); + } + + foreach (var extra in launch.ExtraArguments) + { + EnsureAllowed(extra); + args.Add(extra); + } + + // The start page goes last, as a plain argument. + args.Add(string.IsNullOrWhiteSpace(launch.StartUrl) ? "about:blank" : launch.StartUrl); + return args; + } + + /// Refuses arguments that change what the browser declares, put it in automation mode or are set by Febe itself. + public static void EnsureAllowed(string argument) + { + ArgumentNullException.ThrowIfNull(argument); + var trimmed = argument.Trim(); + if (!trimmed.StartsWith("--", StringComparison.Ordinal)) + { + throw new ArgumentException("Gli argomenti aggiuntivi di Chromium devono essere opzioni «--nome».", nameof(argument)); + } + + foreach (var prefix in ForbiddenPrefixes) + { + if (trimmed.Equals(prefix, StringComparison.OrdinalIgnoreCase) + || trimmed.StartsWith(prefix + "=", StringComparison.OrdinalIgnoreCase)) + { + throw new ArgumentException($"L'opzione «{prefix}» di Chromium è vietata o la imposta già Febe (specifica §2, regola 2; §6.1; §11).", nameof(argument)); + } + } + } + + /// + /// Finds Chromium: explicit path, then the FEBE_CHROMIUM variable, then PATH and the usual places + /// (Debian's «chromium» first; Edge on Windows as the S2 fallback). + /// + public static string? FindExecutable(string? explicitPath = null) + { + if (!string.IsNullOrWhiteSpace(explicitPath)) + { + return File.Exists(explicitPath) ? explicitPath : null; + } + + var fromEnv = System.Environment.GetEnvironmentVariable("FEBE_CHROMIUM"); + if (!string.IsNullOrWhiteSpace(fromEnv) && File.Exists(fromEnv)) + { + return fromEnv; + } + + if (OperatingSystem.IsWindows()) + { + var programFilesX86 = System.Environment.GetFolderPath(System.Environment.SpecialFolder.ProgramFilesX86); + var programFiles = System.Environment.GetFolderPath(System.Environment.SpecialFolder.ProgramFiles); + return ExecutableSearch.Find( + ["msedge", "chrome"], + [ + Path.Combine(programFilesX86, "Microsoft", "Edge", "Application", "msedge.exe"), + Path.Combine(programFiles, "Microsoft", "Edge", "Application", "msedge.exe"), + ]); + } + + return ExecutableSearch.Find( + ["chromium", "chromium-browser", "google-chrome-stable", "google-chrome"], + ["/usr/bin/chromium", "/usr/lib/chromium/chromium"]); + } +} diff --git a/src/Febe.Browser/Hosting/ChromiumProcessHost.cs b/src/Febe.Browser/Hosting/ChromiumProcessHost.cs new file mode 100644 index 0000000..d4374bf --- /dev/null +++ b/src/Febe.Browser/Hosting/ChromiumProcessHost.cs @@ -0,0 +1,307 @@ +using System.Diagnostics; +using Febe.Browser.Cdp; +using Febe.Browser.Diagnostics; +using Febe.Core.Abstractions; + +namespace Febe.Browser.Hosting; + +/// +/// The browser host of the Docker version (spec §5, §6.1, §11): the distribution's Chromium, started as a normal +/// windowed browser on a display (Xvfb), driven through its fixed DevTools port on 127.0.0.1. +/// +/// +/// +/// Supervised: if Chromium exits it is restarted with backoff and reconnects by itself +/// (subscriptions survive; see ). +/// The DevTools port must listen on loopback only, or the start is aborted. +/// Stopping sends SIGINT first (not SIGTERM: see ), so the profile and the +/// session are written to disk; the process tree is killed only if it does not exit within the grace period. +/// +/// +public sealed class ChromiumProcessHost : IBrowserHost +{ + private static readonly TimeSpan StopGrace = TimeSpan.FromSeconds(10); + + private readonly ChromiumLaunchOptions _launch; + private readonly IClock _clock; + private readonly IBrowserLog _log; + private readonly ReconnectingCdpSession _session = new(); + private readonly SemaphoreSlim _connectLock = new(1, 1); + // Not disposed on purpose: background reconnection may still read its token; it holds no timer or handle. + private readonly CancellationTokenSource _lifetime = new(); + private SupervisedProcess? _supervisor; + private CdpClient? _client; + private BrowserOptions? _options; + private int _stopping; + + public ChromiumProcessHost(ChromiumLaunchOptions? launch = null, IClock? clock = null, IBrowserLog? log = null) + { + _launch = launch ?? new ChromiumLaunchOptions(); + _clock = clock ?? new SystemClock(); + _log = log ?? NullBrowserLog.Instance; + } + + /// The page session. Stable across restarts; commands fail with while the browser is down. + public ICdpSession Cdp => _session; + + /// Raised when the connection was replaced after a restart. + public ICdpConnectionEvents Connection => _session; + + /// Leases taken while Alberto uses the browser (remote view, connection page). + public UserDrivingGate UserDriving { get; } = new(); + + public bool UserIsDriving => UserDriving.IsDriving; + + public BrowserOptions? Options => _options; + + public SupervisedState State => _supervisor?.State ?? SupervisedState.Stopped; + + public int? ProcessId => _supervisor?.ProcessId; + + public int Restarts => _supervisor?.Restarts ?? 0; + + public event EventHandler? StateChanged; + + public async Task StartAsync(BrowserOptions options, CancellationToken ct) + { + ArgumentNullException.ThrowIfNull(options); + if (_supervisor is not null) + { + throw new InvalidOperationException("Il browser è già avviato."); + } + + var executable = ChromiumCommandLine.FindExecutable(options.ExecutablePath) + ?? throw new FileNotFoundException("Chromium non è installato o non si trova (si può indicare con FEBE_CHROMIUM)."); + var arguments = ChromiumCommandLine.Build(options, _launch); + if (LoopbackPortCheck.IsInUse(options.DebugPort)) + { + throw new InvalidOperationException($"La porta di debug {options.DebugPort} è già occupata da un altro programma."); + } + + ChromiumProfile.Prepare(options.ProfileDirectory, _launch.SeedProfilePreferences); + _options = options; + + var supervisor = new SupervisedProcess( + "Chromium", + () => BuildStartInfo(executable, arguments, options), + WaitReadyAndConnectAsync, + _clock, + _log, + _launch.Restart, + // Measured locally: on SIGTERM Chromium exits in ~35 ms and usually loses cookies set in the last 30 s; + // on SIGINT it takes ~100 ms and writes them. The session must survive a restart (S3). + ProcessSignals.SigInt); + supervisor.ExitedUnexpectedly += (_, _) => _ = DropClientAsync(); + supervisor.StateChanged += (_, state) => StateChanged?.Invoke(this, state); + _supervisor = supervisor; + + try + { + await supervisor.StartAsync(ct).ConfigureAwait(false); + } + catch + { + _supervisor = null; + throw; + } + + _log.Info("Chromium è in funzione."); + } + + /// Windows only: the Docker browser is seen through the remote view. + public Task ShowToUserAsync() => Task.CompletedTask; + + public Task HideFromUserAsync() => Task.CompletedTask; + + /// Puts the browser at rest on the blank page (spec §6.1). + public Task RestAsync(CancellationToken ct = default) => _session.RestAsync(ct); + + /// Whether the session cookie exists. Never reads its value. + public Task HasSessionCookieAsync(CancellationToken ct = default) => + SessionCookieProbe.HasSessionCookieAsync(_session, _launch.SessionCookie, ct); + + /// Kills the browser as if it had crashed (tests and «riavvia il browser»). The supervisor restarts it. + public void KillForRestart() => _supervisor?.KillCurrent(); + + public async Task StopAsync() + { + if (Interlocked.Exchange(ref _stopping, 1) == 1) + { + return; + } + + await _lifetime.CancelAsync().ConfigureAwait(false); + await DropClientAsync().ConfigureAwait(false); + if (_supervisor is { } supervisor) + { + await supervisor.StopAsync(StopGrace).ConfigureAwait(false); + } + + _log.Info("Chromium è fermo."); + } + + /// Same as . A stopped host cannot be started again: create a new one. + public ValueTask DisposeAsync() => new(StopAsync()); + + private ProcessStartInfo BuildStartInfo(string executable, IReadOnlyList arguments, BrowserOptions options) + { + var info = new ProcessStartInfo(executable); + foreach (var argument in arguments) + { + info.ArgumentList.Add(argument); + } + + if (!string.IsNullOrEmpty(options.Display)) + { + info.Environment["DISPLAY"] = options.Display; + } + + foreach (var (name, value) in _launch.Environment) + { + if (value is null) + { + info.Environment.Remove(name); + } + else + { + info.Environment[name] = value; + } + } + + return info; + } + + private async Task WaitReadyAndConnectAsync(Process process, CancellationToken ct) + { + var options = _options ?? throw new InvalidOperationException("Opzioni mancanti."); + var port = options.DebugPort; + var deadline = _clock.Now + _launch.StartupTimeout; + while (!await CdpTargetDiscovery.IsAvailableAsync(port, ct).ConfigureAwait(false)) + { + if (process.HasExited) + { + throw new InvalidOperationException($"Chromium si è chiuso all'avvio (codice {process.ExitCode}). {_supervisor?.StderrTail()}".TrimEnd()); + } + + if (_clock.Now >= deadline) + { + throw new TimeoutException($"Chromium non ha aperto la porta di debug entro {_launch.StartupTimeout.TotalSeconds:0} s."); + } + + await _clock.Delay(TimeSpan.FromMilliseconds(100), ct).ConfigureAwait(false); + } + + if (!LoopbackPortCheck.IsLoopbackOnly(port, out var listeners)) + { + throw new InvalidOperationException( + $"La porta di debug {port} non è limitata a 127.0.0.1 ({listeners.Count} punti di ascolto): avvio annullato (specifica §6.1)."); + } + + await ConnectAsync(port, ct).ConfigureAwait(false); + } + + private async Task ConnectAsync(int port, CancellationToken ct) + { + await _connectLock.WaitAsync(ct).ConfigureAwait(false); + try + { + CdpTarget? page = null; + for (var attempt = 0; attempt < 50 && page is null; attempt++) + { + page = await CdpTargetDiscovery.FindPageAsync(port, ct).ConfigureAwait(false); + if (page is null) + { + await _clock.Delay(TimeSpan.FromMilliseconds(100), ct).ConfigureAwait(false); + } + } + + if (page is null) + { + throw new InvalidOperationException("Chromium non ha nessuna scheda aperta."); + } + + var client = await CdpClient.ConnectAsync(page.WebSocketDebuggerUrl, _log, null, ct).ConfigureAwait(false); + try + { + await client.SendAsync("Page.enable", null, ct).ConfigureAwait(false); + } + catch + { + await client.DisposeAsync().ConfigureAwait(false); + throw; + } + + client.Disconnected += OnClientDisconnected; + var previous = Interlocked.Exchange(ref _client, client); + _session.Attach(client); + if (previous is not null) + { + previous.Disconnected -= OnClientDisconnected; + await previous.DisposeAsync().ConfigureAwait(false); + } + } + finally + { + _connectLock.Release(); + } + } + + private void OnClientDisconnected(object? sender, Exception? reason) + { + if (Volatile.Read(ref _stopping) == 1 || !ReferenceEquals(sender, Volatile.Read(ref _client))) + { + return; + } + + _session.Detach(); + _ = Task.Run(ReconnectAfterDropAsync); + } + + /// + /// The page connection dropped. If the process is gone the supervisor restarts it (and reconnects); + /// if it is alive, reconnect to its page, or restart it when that fails. + /// + private async Task ReconnectAfterDropAsync() + { + var ct = _lifetime.Token; + try + { + await _clock.Delay(TimeSpan.FromMilliseconds(500), ct).ConfigureAwait(false); + if (_supervisor is not { } supervisor || supervisor.State != SupervisedState.Running || supervisor.ProcessId is null || _options is null) + { + return; + } + + for (var attempt = 0; attempt < 3; attempt++) + { + try + { + await ConnectAsync(_options.DebugPort, ct).ConfigureAwait(false); + _log.Info("Collegamento con Chromium ripristinato."); + return; + } + catch (Exception ex) when (ex is not OperationCanceledException) + { + await _clock.Delay(TimeSpan.FromSeconds(1), ct).ConfigureAwait(false); + } + } + + _log.Warn("Collegamento con Chromium perso: riavvio del browser."); + supervisor.KillCurrent(); + } + catch (OperationCanceledException) + { + } + } + + private async Task DropClientAsync() + { + _session.Detach(); + var client = Interlocked.Exchange(ref _client, null); + if (client is not null) + { + client.Disconnected -= OnClientDisconnected; + await client.DisposeAsync().ConfigureAwait(false); + } + } +} diff --git a/src/Febe.Browser/Hosting/HostingHelpers.cs b/src/Febe.Browser/Hosting/HostingHelpers.cs new file mode 100644 index 0000000..f7bab57 --- /dev/null +++ b/src/Febe.Browser/Hosting/HostingHelpers.cs @@ -0,0 +1,157 @@ +using System.Net; +using System.Net.NetworkInformation; +using System.Text.Json; +using System.Text.Json.Nodes; +using Febe.Core.Abstractions; + +namespace Febe.Browser.Hosting; + +/// Checks who listens on a TCP port (spec §6.1: the debugging port listens on 127.0.0.1 only). +public static class LoopbackPortCheck +{ + public static IReadOnlyList ListenersOn(int port) => + [.. IPGlobalProperties.GetIPGlobalProperties().GetActiveTcpListeners().Where(e => e.Port == port)]; + + /// True when something listens on and every listener is a loopback address. + public static bool IsLoopbackOnly(int port, out IReadOnlyList listeners) + { + listeners = ListenersOn(port); + return listeners.Count > 0 && listeners.All(e => IPAddress.IsLoopback(e.Address)); + } + + public static bool IsInUse(int port) => ListenersOn(port).Count > 0; +} + +/// +/// «Alberto is using the browser» (spec §4.1, §5): while at least one lease is open — the remote view, the +/// connection page, the M0 probe — the engine does not act. +/// +public sealed class UserDrivingGate +{ + private readonly Lock _gate = new(); + private int _leases; + + public bool IsDriving + { + get + { + lock (_gate) + { + return _leases > 0; + } + } + } + + /// Raised when changes; the argument is the new value. + public event EventHandler? Changed; + + /// Opens a lease; dispose it when Alberto is done. Leases nest. + public IDisposable Begin() + { + bool changed; + lock (_gate) + { + changed = _leases++ == 0; + } + + if (changed) + { + Changed?.Invoke(this, true); + } + + return new Lease(this); + } + + private void End() + { + bool changed; + lock (_gate) + { + changed = --_leases == 0; + } + + if (changed) + { + Changed?.Invoke(this, false); + } + } + + private sealed class Lease(UserDrivingGate owner) : IDisposable + { + private UserDrivingGate? _owner = owner; + + public void Dispose() => Interlocked.Exchange(ref _owner, null)?.End(); + } +} + +/// +/// Tells whether the session cookie exists (spec §6.1, §7.6) through Network.getCookies. +/// Only the cookie names are looked at: values are never read, kept or logged. +/// +public static class SessionCookieProbe +{ + public static async Task HasSessionCookieAsync(ICdpSession cdp, SessionCookieOptions options, CancellationToken ct = default) + { + ArgumentNullException.ThrowIfNull(cdp); + ArgumentNullException.ThrowIfNull(options); + var result = await cdp.SendAsync( + "Network.getCookies", + new JsonObject { ["urls"] = new JsonArray(options.SiteUrl) }, + ct).ConfigureAwait(false); + + if (result.ValueKind != JsonValueKind.Object || !result.TryGetProperty("cookies", out var cookies) || cookies.ValueKind != JsonValueKind.Array) + { + return false; + } + + foreach (var cookie in cookies.EnumerateArray()) + { + if (cookie.TryGetProperty("name", out var name) && name.ValueEquals(options.CookieName)) + { + return true; + } + } + + return false; + } +} + +/// Prepares a new browser profile folder. +internal static class ChromiumProfile +{ + /// + /// Creates the folder (owner-only on Unix: it will hold the session) and, on a brand new profile, + /// preferences that turn off password saving and autofill (spec §6.1). Existing profiles are left untouched. + /// + public static void Prepare(string profileDirectory, bool seedPreferences) + { + var full = Path.GetFullPath(profileDirectory); + var isNew = !Directory.Exists(full) || !Directory.EnumerateFileSystemEntries(full).Any(); + if (!Directory.Exists(full)) + { + if (OperatingSystem.IsWindows()) + { + Directory.CreateDirectory(full); + } + else + { + Directory.CreateDirectory(full, UnixFileMode.UserRead | UnixFileMode.UserWrite | UnixFileMode.UserExecute); + } + } + + if (!isNew || !seedPreferences) + { + return; + } + + var defaultDir = Path.Combine(full, "Default"); + Directory.CreateDirectory(defaultDir); + var preferences = new JsonObject + { + ["credentials_enable_service"] = false, + ["profile"] = new JsonObject { ["password_manager_enabled"] = false }, + ["autofill"] = new JsonObject { ["profile_enabled"] = false, ["credit_card_enabled"] = false }, + }; + File.WriteAllText(Path.Combine(defaultDir, "Preferences"), preferences.ToJsonString()); + } +} diff --git a/src/Febe.Browser/Hosting/SupervisedProcess.cs b/src/Febe.Browser/Hosting/SupervisedProcess.cs new file mode 100644 index 0000000..986e3e0 --- /dev/null +++ b/src/Febe.Browser/Hosting/SupervisedProcess.cs @@ -0,0 +1,440 @@ +using System.Diagnostics; +using System.Runtime.InteropServices; +using System.Text.RegularExpressions; +using Febe.Browser.Diagnostics; +using Febe.Core.Abstractions; + +namespace Febe.Browser.Hosting; + +/// How a supervised process is restarted after an unexpected exit. +/// Wait before the first restart. +/// Upper bound of the exponential backoff. +/// A process that ran at least this long resets the backoff. +public sealed record RestartPolicy(TimeSpan InitialDelay, TimeSpan MaxDelay, TimeSpan StableAfter) +{ + public static RestartPolicy Default { get; } = new(TimeSpan.FromSeconds(2), TimeSpan.FromMinutes(5), TimeSpan.FromMinutes(2)); + + /// Delay before restart number (0-based): doubles each time, capped. + public TimeSpan DelayFor(int attempt) + { + var factor = Math.Pow(2, Math.Min(attempt, 20)); + var ms = Math.Min(InitialDelay.TotalMilliseconds * factor, MaxDelay.TotalMilliseconds); + return TimeSpan.FromMilliseconds(ms); + } +} + +public enum SupervisedState +{ + Stopped, + Starting, + Running, + Restarting, + Stopping, +} + +/// +/// Starts a process, waits until it is ready, and restarts it with exponential backoff when it exits on its own +/// (spec §11: Febe.Server supervises Xvfb and Chromium; no shell script acts as supervisor). +/// +/// +/// Standard output and error are drained and dropped: they may contain addresses. Only a short tail of the error +/// stream, with addresses removed, is kept to explain a failed start. +/// +public sealed partial class SupervisedProcess : IAsyncDisposable +{ + private readonly string _name; + private readonly Func _startInfo; + private readonly Func _waitReady; + private readonly IClock _clock; + private readonly IBrowserLog _log; + private readonly RestartPolicy _policy; + private readonly int _stopSignal; + private readonly Lock _gate = new(); + private readonly Queue _stderrTail = new(); + private CancellationTokenSource? _lifetime; + private Task? _supervision; + private Process? _process; + private SupervisedState _state = SupervisedState.Stopped; + + /// Name shown in messages (e.g. «Chromium», «Xvfb»). + /// Builds the start information (called at every start, so it can be refreshed). + /// Completes when the started process is ready; throws if it cannot become ready. + /// Unix signal of the polite stop ( by default; + /// Chromium needs to write its profile, see ChromiumProcessHost). + public SupervisedProcess( + string name, + Func startInfo, + Func waitReady, + IClock clock, + IBrowserLog? log = null, + RestartPolicy? policy = null, + int stopSignal = ProcessSignals.SigTerm) + { + _stopSignal = stopSignal; + _name = name; + _startInfo = startInfo; + _waitReady = waitReady; + _clock = clock; + _log = log ?? NullBrowserLog.Instance; + _policy = policy ?? RestartPolicy.Default; + } + + public SupervisedState State + { + get + { + lock (_gate) + { + return _state; + } + } + } + + /// Process id of the current instance, if running. + public int? ProcessId + { + get + { + lock (_gate) + { + return _process is { HasExited: false } p ? p.Id : null; + } + } + } + + /// Number of restarts since . + public int Restarts { get; private set; } + + /// Raised when the process exited without being asked to (before any restart). + public event EventHandler? ExitedUnexpectedly; + + /// Raised after a restarted process became ready again. + public event EventHandler? Restarted; + + public event EventHandler? StateChanged; + + /// Starts the process and waits until it is ready. A failed first start throws (no retry). + public async Task StartAsync(CancellationToken ct) + { + lock (_gate) + { + if (_state != SupervisedState.Stopped) + { + throw new InvalidOperationException($"{_name} è già avviato."); + } + } + + SetState(SupervisedState.Starting); + var lifetime = new CancellationTokenSource(); + try + { + var process = await LaunchAsync(ct).ConfigureAwait(false); + lock (_gate) + { + _lifetime = lifetime; + _process = process; + } + + SetState(SupervisedState.Running); + _supervision = Task.Run(() => SuperviseAsync(process, lifetime.Token), CancellationToken.None); + } + catch + { + lifetime.Dispose(); + SetState(SupervisedState.Stopped); + throw; + } + } + + /// Stops supervising and ends the process: politely first, by force after . + public async Task StopAsync(TimeSpan grace) + { + CancellationTokenSource? lifetime; + Process? process; + Task? supervision; + lock (_gate) + { + if (_state == SupervisedState.Stopped) + { + return; + } + + lifetime = _lifetime; + process = _process; + supervision = _supervision; + _lifetime = null; + } + + SetState(SupervisedState.Stopping); + if (lifetime is not null) + { + await lifetime.CancelAsync().ConfigureAwait(false); + } + + if (supervision is not null) + { + try + { + await supervision.ConfigureAwait(false); + } + catch (OperationCanceledException) + { + } + } + + lock (_gate) + { + process = _process ?? process; + _process = null; + } + + if (process is not null) + { + await TerminateAsync(process, grace, _stopSignal).ConfigureAwait(false); + process.Dispose(); + } + + lifetime?.Dispose(); + SetState(SupervisedState.Stopped); + } + + public ValueTask DisposeAsync() => new(StopAsync(TimeSpan.FromSeconds(5))); + + /// Ends the current instance by force (used when it is alive but unusable). The supervisor restarts it. + public void KillCurrent() + { + Process? process; + lock (_gate) + { + process = _process; + } + + try + { + if (process is { HasExited: false }) + { + process.Kill(entireProcessTree: true); + } + } + catch (InvalidOperationException) + { + } + } + + /// Last lines of the error stream, addresses removed. For explaining a failed start only. + public string StderrTail() + { + lock (_stderrTail) + { + return string.Join(Environment.NewLine, _stderrTail); + } + } + + private async Task SuperviseAsync(Process process, CancellationToken lifetime) + { + var attempt = 0; + while (!lifetime.IsCancellationRequested) + { + var startedAt = _clock.Now; + try + { + await process.WaitForExitAsync(lifetime).ConfigureAwait(false); + } + catch (OperationCanceledException) + { + return; + } + + var code = SafeExitCode(process); + _log.Warn($"{_name} si è chiuso inaspettatamente (codice {code})."); + ExitedUnexpectedly?.Invoke(this, code); + if (_clock.Now - startedAt >= _policy.StableAfter) + { + attempt = 0; + } + + while (!lifetime.IsCancellationRequested) + { + SetState(SupervisedState.Restarting); + var delay = _policy.DelayFor(attempt++); + _log.Info($"{_name}: nuovo avvio fra {delay.TotalSeconds:0.#} s."); + try + { + await _clock.Delay(delay, lifetime).ConfigureAwait(false); + var next = await LaunchAsync(lifetime).ConfigureAwait(false); + lock (_gate) + { + _process?.Dispose(); + _process = next; + } + + process = next; + Restarts++; + SetState(SupervisedState.Running); + _log.Info($"{_name} è di nuovo in funzione."); + Restarted?.Invoke(this, EventArgs.Empty); + break; + } + catch (OperationCanceledException) when (lifetime.IsCancellationRequested) + { + return; + } + catch (Exception ex) + { + _log.Warn($"{_name}: nuovo avvio fallito.", ex); + } + } + } + } + + private async Task LaunchAsync(CancellationToken ct) + { + lock (_stderrTail) + { + _stderrTail.Clear(); + } + + var info = _startInfo(); + info.UseShellExecute = false; + info.RedirectStandardOutput = true; + info.RedirectStandardError = true; + info.RedirectStandardInput = false; + + var process = new Process { StartInfo = info, EnableRaisingEvents = true }; + process.OutputDataReceived += static (_, _) => { }; + process.ErrorDataReceived += (_, e) => RememberStderr(e.Data); + if (!process.Start()) + { + process.Dispose(); + throw new InvalidOperationException($"{_name} non è partito."); + } + + process.BeginOutputReadLine(); + process.BeginErrorReadLine(); + try + { + await _waitReady(process, ct).ConfigureAwait(false); + return process; + } + catch + { + await TerminateAsync(process, TimeSpan.FromSeconds(2), _stopSignal).ConfigureAwait(false); + process.Dispose(); + throw; + } + } + + private void RememberStderr(string? line) + { + if (string.IsNullOrWhiteSpace(line)) + { + return; + } + + var clean = Addresses().Replace(line, ""); + if (clean.Length > 300) + { + clean = clean[..300]; + } + + lock (_stderrTail) + { + _stderrTail.Enqueue(clean); + while (_stderrTail.Count > 12) + { + _stderrTail.Dequeue(); + } + } + } + + private void SetState(SupervisedState state) + { + lock (_gate) + { + if (_state == state) + { + return; + } + + _state = state; + } + + StateChanged?.Invoke(this, state); + } + + private static int SafeExitCode(Process process) + { + try + { + return process.ExitCode; + } + catch (InvalidOperationException) + { + return -1; + } + } + + /// Asks the process to end ( on Unix, close on Windows), then kills the tree after . + internal static async Task TerminateAsync(Process process, TimeSpan grace, int signal = ProcessSignals.SigTerm) + { + try + { + if (process.HasExited) + { + return; + } + + ProcessSignals.TryTerminate(process, signal); + using var timeout = new CancellationTokenSource(grace); + try + { + await process.WaitForExitAsync(timeout.Token).ConfigureAwait(false); + return; + } + catch (OperationCanceledException) + { + } + + process.Kill(entireProcessTree: true); + using var killTimeout = new CancellationTokenSource(TimeSpan.FromSeconds(5)); + await process.WaitForExitAsync(killTimeout.Token).ConfigureAwait(false); + } + catch (Exception ex) when (ex is InvalidOperationException or OperationCanceledException or System.ComponentModel.Win32Exception) + { + // Already gone, or not ours to wait for. + } + } + + [GeneratedRegex(@"\b[a-zA-Z][a-zA-Z0-9+.-]*://\S+", RegexOptions.CultureInvariant)] + private static partial Regex Addresses(); +} + +/// Polite termination signals. +public static class ProcessSignals +{ + /// SIGINT: Chromium shuts down cleanly and writes its cookie store (measured, see docs/sonda/esito-locale.md). + public const int SigInt = 2; + + /// SIGTERM: the usual polite stop (Xvfb). + public const int SigTerm = 15; + + internal static bool TryTerminate(Process process, int signal) + { + try + { + if (OperatingSystem.IsLinux() || OperatingSystem.IsMacOS() || OperatingSystem.IsFreeBSD()) + { + return Kill(process.Id, signal) == 0; + } + + return OperatingSystem.IsWindows() && process.CloseMainWindow(); + } + catch (Exception ex) when (ex is InvalidOperationException or DllNotFoundException or EntryPointNotFoundException) + { + return false; + } + } + + [DllImport("libc", EntryPoint = "kill", SetLastError = true)] + private static extern int Kill(int pid, int signal); +} diff --git a/src/Febe.Browser/Hosting/XvfbProcess.cs b/src/Febe.Browser/Hosting/XvfbProcess.cs new file mode 100644 index 0000000..060c612 --- /dev/null +++ b/src/Febe.Browser/Hosting/XvfbProcess.cs @@ -0,0 +1,204 @@ +using System.Diagnostics; +using System.Globalization; +using Febe.Browser.Diagnostics; +using Febe.Core.Abstractions; + +namespace Febe.Browser.Hosting; + +/// +/// The virtual display of the Docker version (spec §6.1, §11): Chromium runs as a normal windowed browser on it. +/// Supervised: restarted with backoff if it exits; Chromium, which loses its display, is restarted by its own host. +/// +public sealed class XvfbProcess : IAsyncDisposable +{ + private readonly SupervisedProcess _supervisor; + private readonly int _displayNumber; + + /// Display name, e.g. «:99». + /// Screen width: at least the browser window width. + /// Screen height: at least the browser window height. + /// Xvfb executable; null searches PATH. + public XvfbProcess( + string display = ":99", + int width = 1280, + int height = 900, + string? executable = null, + IClock? clock = null, + IBrowserLog? log = null, + RestartPolicy? restart = null) + { + _displayNumber = ParseDisplay(display); + Display = display; + Width = width; + Height = height; + var exe = executable ?? FindExecutable() ?? throw new FileNotFoundException("Xvfb non è installato."); + var effectiveClock = clock ?? new SystemClock(); + _supervisor = new SupervisedProcess( + "Xvfb", + () => BuildStartInfo(exe), + (process, ct) => WaitForSocketAsync(process, effectiveClock, ct), + effectiveClock, + log, + restart); + } + + public string Display { get; } + + public int Width { get; } + + public int Height { get; } + + public SupervisedState State => _supervisor.State; + + public int? ProcessId => _supervisor.ProcessId; + + /// Path of the X socket that appears when the display is ready. + public string SocketPath => $"/tmp/.X11-unix/X{_displayNumber.ToString(CultureInfo.InvariantCulture)}"; + + public event EventHandler? Restarted + { + add => _supervisor.Restarted += value; + remove => _supervisor.Restarted -= value; + } + + public Task StartAsync(CancellationToken ct) + { + if (!OperatingSystem.IsLinux()) + { + throw new PlatformNotSupportedException("Xvfb serve solo su Linux (Docker)."); + } + + if (IsLockHeldByLiveProcess()) + { + throw new InvalidOperationException($"Il display {Display} è già in uso da un altro processo."); + } + + return _supervisor.StartAsync(ct); + } + + public Task StopAsync() => _supervisor.StopAsync(TimeSpan.FromSeconds(3)); + + public ValueTask DisposeAsync() => _supervisor.DisposeAsync(); + + /// Finds Xvfb in PATH or in the usual places. + public static string? FindExecutable() => ExecutableSearch.Find(["Xvfb"], ["/usr/bin/Xvfb", "/usr/local/bin/Xvfb"]); + + /// First display number in [, ] with neither socket nor lock file. + public static string? FindFreeDisplay(int from = 90, int to = 199) + { + for (var n = from; n <= to; n++) + { + var id = n.ToString(CultureInfo.InvariantCulture); + if (!File.Exists($"/tmp/.X11-unix/X{id}") && !File.Exists($"/tmp/.X{id}-lock")) + { + return $":{id}"; + } + } + + return null; + } + + private ProcessStartInfo BuildStartInfo(string exe) + { + var info = new ProcessStartInfo(exe); + info.ArgumentList.Add(Display); + info.ArgumentList.Add("-screen"); + info.ArgumentList.Add("0"); + info.ArgumentList.Add(string.Create(CultureInfo.InvariantCulture, $"{Width}x{Height}x24")); + info.ArgumentList.Add("-nolisten"); + info.ArgumentList.Add("tcp"); + info.ArgumentList.Add("-noreset"); + return info; + } + + private async Task WaitForSocketAsync(Process process, IClock clock, CancellationToken ct) + { + var deadline = clock.Now + TimeSpan.FromSeconds(10); + while (!File.Exists(SocketPath) || LockOwner() != process.Id) + { + if (process.HasExited) + { + throw new InvalidOperationException($"Xvfb si è chiuso all'avvio (codice {process.ExitCode}). {_supervisor.StderrTail()}"); + } + + if (clock.Now >= deadline) + { + throw new TimeoutException($"Il display {Display} non è pronto dopo 10 secondi."); + } + + await clock.Delay(TimeSpan.FromMilliseconds(50), ct).ConfigureAwait(false); + } + } + + /// Process id written in the X lock file, or null. + private int? LockOwner() + { + var lockFile = $"/tmp/.X{_displayNumber.ToString(CultureInfo.InvariantCulture)}-lock"; + try + { + return File.Exists(lockFile) && int.TryParse(File.ReadAllText(lockFile).Trim(), NumberStyles.None, CultureInfo.InvariantCulture, out var pid) + ? pid + : null; + } + catch (Exception ex) when (ex is IOException or UnauthorizedAccessException) + { + return null; + } + } + + private bool IsLockHeldByLiveProcess() + { + if (LockOwner() is not { } pid) + { + return false; + } + + try + { + using var holder = Process.GetProcessById(pid); + return !holder.HasExited; + } + catch (Exception ex) when (ex is ArgumentException or InvalidOperationException) + { + return false; + } + } + + private static int ParseDisplay(string display) + { + if (string.IsNullOrEmpty(display) || display[0] != ':' + || !int.TryParse(display.AsSpan(1).ToString().Split('.')[0], NumberStyles.None, CultureInfo.InvariantCulture, out var number)) + { + throw new ArgumentException($"Display «{display}» non valido: si scrive come «:99».", nameof(display)); + } + + return number; + } +} + +/// Looks for executables in PATH and in a few known places. +internal static class ExecutableSearch +{ + public static string? Find(IEnumerable names, IEnumerable knownPaths) + { + var path = Environment.GetEnvironmentVariable("PATH") ?? string.Empty; + foreach (var name in names) + { + foreach (var dir in path.Split(Path.PathSeparator, StringSplitOptions.RemoveEmptyEntries)) + { + var candidate = Path.Combine(dir, name); + if (File.Exists(candidate)) + { + return candidate; + } + + if (OperatingSystem.IsWindows() && File.Exists(candidate + ".exe")) + { + return candidate + ".exe"; + } + } + } + + return knownPaths.FirstOrDefault(File.Exists); + } +} diff --git a/src/Febe.Browser/RemoteView/RemoteViewSession.cs b/src/Febe.Browser/RemoteView/RemoteViewSession.cs new file mode 100644 index 0000000..572f8c8 --- /dev/null +++ b/src/Febe.Browser/RemoteView/RemoteViewSession.cs @@ -0,0 +1,253 @@ +using System.Text.Json; +using System.Text.Json.Nodes; +using Febe.Browser.Cdp; +using Febe.Browser.Diagnostics; +using Febe.Browser.Gestures; +using Febe.Browser.Hosting; +using Febe.Core.Abstractions; + +namespace Febe.Browser.RemoteView; + +public enum RemoteMouseAction +{ + Move, + Down, + Up, + Wheel, +} + +public enum RemoteMouseButton +{ + None, + Left, + Middle, + Right, +} + +/// A mouse event from the interface's remote view. +/// Move, press, release or wheel. +/// Horizontal position: 0–1 of the frame when , CSS pixels otherwise. +/// Vertical position: 0–1 of the frame when , CSS pixels otherwise. +/// Button pressed or released. +/// 1 for a click, 2 for a double click. +/// Horizontal wheel delta in CSS pixels. +/// Vertical wheel delta in CSS pixels (positive scrolls down). +/// Modifier keys held. +/// Whether X and Y are fractions of the frame. +public sealed record RemoteMouseEvent( + RemoteMouseAction Action, + double X, + double Y, + RemoteMouseButton Button = RemoteMouseButton.None, + int ClickCount = 1, + double DeltaX = 0, + double DeltaY = 0, + KeyModifiers Modifiers = KeyModifiers.None, + bool Normalized = true); + +/// A key event from the interface's remote view. Never logged or stored (spec §13.2). +public sealed record RemoteKeyEvent(bool Down, KeyStroke Key) +{ + public override string ToString() => "RemoteKeyEvent(…)"; +} + +/// +/// The remote view used by Alberto from the interface (spec §4.1, §11, mockup 10): the screencast goes to the page, +/// mouse and keys come back to the browser through Input.*. While the session is active the +/// holds a lease, so the engine stays still. Keys are forwarded, never logged. +/// +public sealed class RemoteViewSession : IAsyncDisposable +{ + private readonly ICdpSession _cdp; + private readonly UserDrivingGate _gate; + private readonly IBrowserLog _log; + private IDisposable? _lease; + private int _buttons; + + public RemoteViewSession(ICdpSession cdp, UserDrivingGate gate, IBrowserLog? log = null) + { + _cdp = cdp ?? throw new ArgumentNullException(nameof(cdp)); + _gate = gate ?? throw new ArgumentNullException(nameof(gate)); + _log = log ?? NullBrowserLog.Instance; + Screencast = new ScreencastSession(cdp, _log); + } + + public ScreencastSession Screencast { get; } + + public bool IsActive => _lease is not null; + + /// Takes the «Alberto is driving» lease and starts the frames. + public async Task StartAsync(ScreencastOptions? options = null, CancellationToken ct = default) + { + if (_lease is not null) + { + throw new InvalidOperationException("La vista remota è già attiva."); + } + + _lease = _gate.Begin(); + try + { + await Screencast.StartAsync(options, ct).ConfigureAwait(false); + } + catch + { + _lease.Dispose(); + _lease = null; + throw; + } + + _log.Info("Vista remota aperta: il motore resta fermo finché Alberto usa il browser."); + } + + public async Task MouseAsync(RemoteMouseEvent e, CancellationToken ct = default) + { + ArgumentNullException.ThrowIfNull(e); + EnsureActive(); + var (x, y) = ToPage(e); + var button = e.Button switch + { + RemoteMouseButton.Left => "left", + RemoteMouseButton.Middle => "middle", + RemoteMouseButton.Right => "right", + _ => "none", + }; + var bit = e.Button switch + { + RemoteMouseButton.Left => 1, + RemoteMouseButton.Right => 2, + RemoteMouseButton.Middle => 4, + _ => 0, + }; + + var parameters = new JsonObject + { + ["x"] = x, + ["y"] = y, + ["modifiers"] = (int)e.Modifiers, + ["pointerType"] = "mouse", + }; + + switch (e.Action) + { + case RemoteMouseAction.Move: + parameters["type"] = "mouseMoved"; + parameters["button"] = "none"; + parameters["buttons"] = _buttons; + break; + case RemoteMouseAction.Down: + _buttons |= bit; + parameters["type"] = "mousePressed"; + parameters["button"] = button; + parameters["buttons"] = _buttons; + parameters["clickCount"] = Math.Max(1, e.ClickCount); + break; + case RemoteMouseAction.Up: + _buttons &= ~bit; + parameters["type"] = "mouseReleased"; + parameters["button"] = button; + parameters["buttons"] = _buttons; + parameters["clickCount"] = Math.Max(1, e.ClickCount); + break; + case RemoteMouseAction.Wheel: + parameters["type"] = "mouseWheel"; + parameters["deltaX"] = e.DeltaX; + parameters["deltaY"] = e.DeltaY; + break; + default: + throw new ArgumentOutOfRangeException(nameof(e), e.Action, null); + } + + await _cdp.SendAsync("Input.dispatchMouseEvent", parameters, ct).ConfigureAwait(false); + } + + public Task KeyAsync(RemoteKeyEvent e, CancellationToken ct = default) + { + ArgumentNullException.ThrowIfNull(e); + EnsureActive(); + return e.Down ? Keyboard.KeyDownAsync(_cdp, e.Key, ct) : Keyboard.KeyUpAsync(_cdp, e.Key, ct); + } + + /// Opens an address chosen by Alberto (e.g. the login page from the connection page). + public Task NavigateAsync(string url, CancellationToken ct = default) + { + EnsureActive(); + return _cdp.NavigateAsync(url, ct); + } + + /// Stops the frames and releases the lease: the engine may act again. + public async Task StopAsync(CancellationToken ct = default) + { + try + { + await Screencast.StopAsync(ct).ConfigureAwait(false); + } + finally + { + Interlocked.Exchange(ref _lease, null)?.Dispose(); + _buttons = 0; + } + + _log.Info("Vista remota chiusa."); + } + + public async ValueTask DisposeAsync() + { + if (_lease is not null) + { + await StopAsync().ConfigureAwait(false); + } + + await Screencast.DisposeAsync().ConfigureAwait(false); + } + + private (double X, double Y) ToPage(RemoteMouseEvent e) + { + if (!e.Normalized) + { + return (e.X, e.Y); + } + + var frame = Screencast.LastFrame; + if (frame is null || frame.DeviceWidth <= 0 || frame.DeviceHeight <= 0) + { + throw new InvalidOperationException("Nessun fotogramma ricevuto: posizione del puntatore non calcolabile."); + } + + var scale = frame.PageScaleFactor > 0 ? frame.PageScaleFactor : 1; + var x = Math.Clamp(e.X, 0, 1) * frame.DeviceWidth / scale; + var y = Math.Clamp(e.Y, 0, 1) * frame.DeviceHeight / scale; + return (Math.Round(x, 1), Math.Round(y, 1)); + } + + private void EnsureActive() + { + if (_lease is null) + { + throw new InvalidOperationException("La vista remota non è attiva."); + } + } +} + +/// The still preview of the Activity page (mockup 06): one frame every few seconds, not a video. +public static class PagePreview +{ + /// Captures the visible page as JPEG through Page.captureScreenshot. + public static async Task CaptureAsync(ICdpSession cdp, int quality = 60, CancellationToken ct = default) + { + ArgumentNullException.ThrowIfNull(cdp); + var result = await cdp.SendAsync( + "Page.captureScreenshot", + new JsonObject + { + ["format"] = "jpeg", + ["quality"] = Math.Clamp(quality, 0, 100), + ["fromSurface"] = true, + ["captureBeyondViewport"] = false, + }, + ct).ConfigureAwait(false); + + return result.TryGetProperty("data", out var data) && data.ValueKind == JsonValueKind.String + ? data.GetBytesFromBase64() + : []; + } +} diff --git a/src/Febe.Browser/RemoteView/ScreencastSession.cs b/src/Febe.Browser/RemoteView/ScreencastSession.cs new file mode 100644 index 0000000..530f9a0 --- /dev/null +++ b/src/Febe.Browser/RemoteView/ScreencastSession.cs @@ -0,0 +1,225 @@ +using System.Runtime.CompilerServices; +using System.Text.Json; +using System.Text.Json.Nodes; +using System.Threading.Channels; +using Febe.Browser.Cdp; +using Febe.Browser.Diagnostics; +using Febe.Core.Abstractions; + +namespace Febe.Browser.RemoteView; + +/// Settings of a screencast (Page.startScreencast). +/// JPEG quality, 0–100. +/// Largest frame width in pixels. +/// Largest frame height in pixels. +/// Send one frame out of this many. +public sealed record ScreencastOptions(int Quality = 70, int MaxWidth = 1280, int MaxHeight = 900, int EveryNthFrame = 1); + +/// One frame of the remote view. +/// The image. +/// Page width in CSS pixels the frame represents. +/// Page height in CSS pixels the frame represents. +/// Page zoom. +/// Top offset in CSS pixels (browser controls). +/// Horizontal scroll position. +/// Vertical scroll position. +/// Browser timestamp (seconds), when given. +public sealed record ScreencastFrame( + byte[] Jpeg, + double DeviceWidth, + double DeviceHeight, + double PageScaleFactor, + double OffsetTop, + double ScrollOffsetX, + double ScrollOffsetY, + double? Timestamp); + +/// +/// The remote view's video (spec §4.1, §11): Page.startScreencast in JPEG, every frame acknowledged with +/// Page.screencastFrameAck, stopped with Page.stopScreencast. Frames are delivered through +/// (only the latest ones are kept when the reader is slow) and . +/// +public sealed class ScreencastSession : IAsyncDisposable +{ + private readonly ICdpSession _cdp; + private readonly IBrowserLog _log; + private readonly Channel _frames = Channel.CreateBounded( + new BoundedChannelOptions(2) { FullMode = BoundedChannelFullMode.DropOldest, SingleReader = true }); + + private readonly Channel _acks = Channel.CreateUnbounded(new UnboundedChannelOptions { SingleReader = true }); + private readonly CancellationTokenSource _lifetime = new(); + private IDisposable? _subscription; + private Task? _ackPump; + private ScreencastOptions? _options; + private int _stopped; + private long _framesReceived; + + public ScreencastSession(ICdpSession cdp, IBrowserLog? log = null) + { + _cdp = cdp ?? throw new ArgumentNullException(nameof(cdp)); + _log = log ?? NullBrowserLog.Instance; + } + + /// Raised on the browser event thread for every frame: handlers must be quick. + public event EventHandler? FrameReceived; + + /// The last frame received, for mapping input coordinates. + public ScreencastFrame? LastFrame { get; private set; } + + public long FramesReceived => Interlocked.Read(ref _framesReceived); + + public async Task StartAsync(ScreencastOptions? options = null, CancellationToken ct = default) + { + if (_subscription is not null) + { + throw new InvalidOperationException("La vista remota è già avviata."); + } + + _options = options ?? new ScreencastOptions(); + _subscription = _cdp.On("Page.screencastFrame", OnFrame); + if (_cdp is ICdpConnectionEvents events) + { + events.Reconnected += OnReconnected; + } + + _ackPump = Task.Run(() => AckPumpAsync(_lifetime.Token), CancellationToken.None); + await SendStartAsync(ct).ConfigureAwait(false); + _log.Debug("Vista remota avviata."); + } + + /// Frames as they arrive; the oldest are dropped if the reader falls behind. Ends when the session stops. + public async IAsyncEnumerable ReadFramesAsync([EnumeratorCancellation] CancellationToken ct = default) + { + await foreach (var frame in _frames.Reader.ReadAllAsync(ct).ConfigureAwait(false)) + { + yield return frame; + } + } + + public async Task StopAsync(CancellationToken ct = default) + { + if (Interlocked.Exchange(ref _stopped, 1) == 1) + { + return; + } + + if (_cdp is ICdpConnectionEvents events) + { + events.Reconnected -= OnReconnected; + } + + if (_subscription is not null) + { + _subscription.Dispose(); + try + { + await _cdp.SendAsync("Page.stopScreencast", null, ct).ConfigureAwait(false); + } + catch (Exception ex) when (ex is CdpDisconnectedException or BrowserUnavailableException or CdpCommandException) + { + // The browser is gone: nothing to stop. + } + } + + _frames.Writer.TryComplete(); + _acks.Writer.TryComplete(); + await _lifetime.CancelAsync().ConfigureAwait(false); + if (_ackPump is not null) + { + try + { + await _ackPump.ConfigureAwait(false); + } + catch (OperationCanceledException) + { + } + } + + _log.Debug("Vista remota fermata."); + } + + public async ValueTask DisposeAsync() + { + await StopAsync().ConfigureAwait(false); + _lifetime.Dispose(); + } + + private Task SendStartAsync(CancellationToken ct) + { + var o = _options ?? new ScreencastOptions(); + return _cdp.SendAsync( + "Page.startScreencast", + new JsonObject + { + ["format"] = "jpeg", + ["quality"] = Math.Clamp(o.Quality, 0, 100), + ["maxWidth"] = o.MaxWidth, + ["maxHeight"] = o.MaxHeight, + ["everyNthFrame"] = Math.Max(1, o.EveryNthFrame), + }, + ct); + } + + private void OnReconnected(object? sender, EventArgs e) => + _ = Task.Run(async () => + { + try + { + await SendStartAsync(_lifetime.Token).ConfigureAwait(false); + } + catch (Exception ex) when (ex is not OperationCanceledException) + { + _log.Warn("Vista remota: non è ripartita dopo il riavvio del browser.", ex); + } + }); + + private void OnFrame(JsonElement p) + { + if (!p.TryGetProperty("sessionId", out var sid) || !sid.TryGetInt32(out var sessionId)) + { + return; + } + + // Acknowledge first, from the pump: the browser sends the next frame only after the ack. + _acks.Writer.TryWrite(sessionId); + + if (!p.TryGetProperty("data", out var data) || !data.TryGetBytesFromBase64(out var jpeg)) + { + return; + } + + var meta = p.TryGetProperty("metadata", out var m) ? m : default; + var frame = new ScreencastFrame( + jpeg, + Read(meta, "deviceWidth"), + Read(meta, "deviceHeight"), + Read(meta, "pageScaleFactor", 1), + Read(meta, "offsetTop"), + Read(meta, "scrollOffsetX"), + Read(meta, "scrollOffsetY"), + meta.ValueKind == JsonValueKind.Object && meta.TryGetProperty("timestamp", out var ts) && ts.TryGetDouble(out var t) ? t : null); + + LastFrame = frame; + Interlocked.Increment(ref _framesReceived); + _frames.Writer.TryWrite(frame); + FrameReceived?.Invoke(this, frame); + } + + private async Task AckPumpAsync(CancellationToken ct) + { + await foreach (var sessionId in _acks.Reader.ReadAllAsync(ct).ConfigureAwait(false)) + { + try + { + await _cdp.SendAsync("Page.screencastFrameAck", new JsonObject { ["sessionId"] = sessionId }, ct).ConfigureAwait(false); + } + catch (Exception ex) when (ex is CdpDisconnectedException or BrowserUnavailableException or CdpCommandException or TimeoutException) + { + // A lost ack only pauses frames until the next start. + } + } + } + + private static double Read(JsonElement meta, string name, double fallback = 0) => + meta.ValueKind == JsonValueKind.Object && meta.TryGetProperty(name, out var v) && v.TryGetDouble(out var d) ? d : fallback; +} diff --git a/src/Febe.Browser/Targets/TargetMap.cs b/src/Febe.Browser/Targets/TargetMap.cs new file mode 100644 index 0000000..55cbaad --- /dev/null +++ b/src/Febe.Browser/Targets/TargetMap.cs @@ -0,0 +1,223 @@ +using System.Text; +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Text.RegularExpressions; + +namespace Febe.Browser.Targets; + +/// +/// How to find one thing in the page (spec §6.3): element role, accessible name, link shape, optional index. +/// Never fixed coordinates, never generated class names. +/// +/// Identifier used by recipes (e.g. «viewer-next»). +/// Accepted ARIA roles, explicit or implicit («link», «button», ...). Empty: any. +/// Regular expression (case-insensitive) on the accessible name; may contain {parameters}. +/// Link shape on the path, e.g. «/{username}/», «/stories/**»: {name} or * is one segment, ** the rest. +/// Which of the visible matches, in document order (0 = first, -1 = last). +/// Hypothesis of spec §6.6 the target depends on (e.g. «H11»), when not yet confirmed. +public sealed record TargetSpec(string Id, IReadOnlyList Roles, string? NamePattern, string? HrefPattern, int Index, string? Hypothesis); + +/// +/// The target map of one site (bersagli.instagram.json, bersagli.prova.json), editable without +/// recompiling: it is the second thing to touch, after the readers, when the site changes. +/// +/// +/// Format: +/// +/// { +/// "site": "prova", +/// "note": "testo libero", +/// "targets": { +/// "viewer-next": { "role": "button", "name": "^avanti$", "note": "..." }, +/// "profile-stories": { "role": "link", "href": "/stories/{username}/", "index": 0, "hypothesis": "H11" } +/// } +/// } +/// +/// «role» may list alternatives with «|» («button|link»). At least one of role, name and href is required. +/// Unknown keys are refused, so coordinates or class names cannot slip in. +/// +public sealed partial class TargetMap +{ + private readonly Dictionary _targets; + + public TargetMap(string? site, IEnumerable targets, string? source = null) + { + Site = site; + Source = source; + _targets = targets.ToDictionary(t => t.Id, StringComparer.Ordinal); + } + + public string? Site { get; } + + public string? Source { get; } + + public IReadOnlyDictionary Targets => _targets; + + public bool Contains(string id) => _targets.ContainsKey(id); + + public TargetSpec Get(string id) => + _targets.TryGetValue(id, out var spec) + ? spec + : throw new KeyNotFoundException($"Il bersaglio «{id}» non è nella mappa {Source ?? Site ?? string.Empty}.".TrimEnd()); + + public static TargetMap Load(string path) => Parse(File.ReadAllText(path), path); + + public static TargetMap Parse(string json, string? source = null) + { + var name = source ?? "bersagli"; + TargetMapFile? file; + try + { + file = JsonSerializer.Deserialize(json, TargetMapJsonContext.Default.TargetMapFile); + } + catch (JsonException ex) + { + throw new InvalidDataException($"{name}: file non valido ({ex.Message.Split('.')[0]}).", ex); + } + + if (file?.Targets is null || file.Targets.Count == 0) + { + throw new InvalidDataException($"{name}: manca l'elenco «targets»."); + } + + var specs = new List(); + foreach (var (id, dto) in file.Targets) + { + var where = $"{name}, bersaglio «{id}»"; + if (!IdShape().IsMatch(id)) + { + throw new InvalidDataException($"{where}: l'identificativo usa solo lettere minuscole, cifre e trattini."); + } + + var roles = (dto.Role ?? string.Empty).Split('|', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries) + .Select(r => r.ToLowerInvariant()) + .ToArray(); + if (roles.Length == 0 && string.IsNullOrWhiteSpace(dto.Name) && string.IsNullOrWhiteSpace(dto.Href)) + { + throw new InvalidDataException($"{where}: serve almeno uno fra «role», «name» e «href»."); + } + + if (!string.IsNullOrWhiteSpace(dto.Name)) + { + try + { + _ = new Regex(PlaceholderToken().Replace(dto.Name, "x"), RegexOptions.CultureInvariant, TimeSpan.FromMilliseconds(100)); + } + catch (ArgumentException ex) + { + throw new InvalidDataException($"{where}: espressione «name» non valida.", ex); + } + } + + if (!string.IsNullOrWhiteSpace(dto.Href) && !dto.Href.StartsWith('/')) + { + throw new InvalidDataException($"{where}: «href» descrive un percorso e comincia con «/»."); + } + + specs.Add(new TargetSpec(id, roles, NullIfBlank(dto.Name), NullIfBlank(dto.Href), dto.Index ?? 0, NullIfBlank(dto.Hypothesis))); + } + + return new TargetMap(file.Site, specs, source); + } + + /// + /// Turns a link shape into an anchored, case-insensitive-ready regular expression on the path. + /// {name} becomes the escaped parameter value when given, otherwise one segment; * is one segment; ** the rest. + /// + public static string HrefPatternToRegex(string pattern, IReadOnlyDictionary? parameters = null) + { + ArgumentNullException.ThrowIfNull(pattern); + var sb = new StringBuilder("^"); + var i = 0; + while (i < pattern.Length) + { + if (pattern[i] == '{') + { + var end = pattern.IndexOf('}', i); + if (end < 0) + { + throw new FormatException($"Segnaposto non chiuso in «{pattern}»."); + } + + var key = pattern[(i + 1)..end]; + sb.Append(parameters is not null && parameters.TryGetValue(key, out var value) ? EscapeForRegex(value) : "[^/]+"); + i = end + 1; + } + else if (pattern[i] == '*') + { + var isDouble = i + 1 < pattern.Length && pattern[i + 1] == '*'; + sb.Append(isDouble ? ".*" : "[^/]+"); + i += isDouble ? 2 : 1; + } + else + { + sb.Append(EscapeForRegex(pattern[i].ToString())); + i++; + } + } + + return sb.Append('$').ToString(); + } + + /// Replaces {parameters} in a name pattern with their escaped values. + public static string ExpandNamePattern(string pattern, IReadOnlyDictionary? parameters) => + PlaceholderToken().Replace(pattern, m => + parameters is not null && parameters.TryGetValue(m.Groups[1].Value, out var value) ? EscapeForRegex(value) : ".+"); + + /// Escapes regular-expression metacharacters in a way valid both for .NET and JavaScript. + internal static string EscapeForRegex(string text) + { + var sb = new StringBuilder(text.Length); + foreach (var c in text) + { + if (@"\^$.|?*+()[]{}/".Contains(c, StringComparison.Ordinal)) + { + sb.Append('\\'); + } + + sb.Append(c); + } + + return sb.ToString(); + } + + private static string? NullIfBlank(string? s) => string.IsNullOrWhiteSpace(s) ? null : s.Trim(); + + [GeneratedRegex("^[a-z0-9]+(-[a-z0-9]+)*$", RegexOptions.CultureInvariant)] + private static partial Regex IdShape(); + + [GeneratedRegex(@"\{([A-Za-z][A-Za-z0-9_]*)\}", RegexOptions.CultureInvariant)] + private static partial Regex PlaceholderToken(); +} + +internal sealed class TargetMapFile +{ + public string? Site { get; set; } + + public string? Note { get; set; } + + public Dictionary? Targets { get; set; } +} + +internal sealed class TargetDto +{ + public string? Role { get; set; } + + public string? Name { get; set; } + + public string? Href { get; set; } + + public int? Index { get; set; } + + public string? Hypothesis { get; set; } + + public string? Note { get; set; } +} + +[JsonSourceGenerationOptions( + PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase, + ReadCommentHandling = JsonCommentHandling.Skip, + AllowTrailingCommas = true, + UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow)] +[JsonSerializable(typeof(TargetMapFile))] +internal sealed partial class TargetMapJsonContext : JsonSerializerContext; diff --git a/src/Febe.Browser/Targets/TargetResolver.cs b/src/Febe.Browser/Targets/TargetResolver.cs new file mode 100644 index 0000000..8308709 --- /dev/null +++ b/src/Febe.Browser/Targets/TargetResolver.cs @@ -0,0 +1,302 @@ +using System.Text.Json; +using System.Text.Json.Nodes; +using Febe.Browser.Cdp; +using Febe.Browser.Gestures; +using Febe.Core.Abstractions; + +namespace Febe.Browser.Targets; + +/// Outcome of looking a target up. +public enum TargetStatus +{ + Found, + + /// No element matches role, name and link shape. + NotFound, + + /// Elements match but none is rendered (hidden, zero size, transparent). + NotVisible, + + /// Fewer visible matches than the index asks for. + IndexOutOfRange, + + /// The element exists but could not be brought into the viewport. + OutOfView, + + /// Something covers the element (e.g. a dialog): clicking would hit something else. + Obstructed, +} + +/// One element matched by a target, as measured by the page. +/// Bounding box in viewport CSS pixels. +/// Rendered: non-zero size, not hidden, not transparent. +/// At least partly inside the viewport. +/// The centre of its visible part hits the element itself. +public sealed record TargetElement(PageRect Rect, bool Visible, bool InViewport, bool Unobstructed); + +/// Result of a lookup. When not found, recipes stop and report: they never click at random (spec §7.7). +public sealed record TargetLookup(string Id, TargetStatus Status, TargetElement? Element, int Matches, double ViewportWidth, double ViewportHeight) +{ + public bool Found => Status == TargetStatus.Found; + + /// Message for the interface and the log (Italian, no page content). + public string Message => Status switch + { + TargetStatus.Found => $"Bersaglio «{Id}» trovato.", + TargetStatus.NotFound => $"Bersaglio «{Id}» non trovato: nessun elemento della pagina corrisponde alla mappa.", + TargetStatus.NotVisible => $"Bersaglio «{Id}» presente ma non visibile.", + TargetStatus.IndexOutOfRange => $"Bersaglio «{Id}»: trovati {Matches} elementi visibili, meno di quanti ne chiede la mappa.", + TargetStatus.OutOfView => $"Bersaglio «{Id}» fuori dalla parte visibile della pagina.", + TargetStatus.Obstructed => $"Bersaglio «{Id}» coperto da un altro elemento.", + _ => $"Bersaglio «{Id}»: esito sconosciuto.", + }; +} + +/// +/// Finds targets of a through one read-only Runtime.evaluate: it queries the DOM +/// (roles, accessible names, link paths), measures rectangles and hit-tests, and never modifies the page. +/// +public sealed class TargetResolver +{ + private const string Script = """ + (() => { + const spec = __SPEC__; + const clean = (s) => (s || '').replace(/\s+/g, ' ').trim(); + const roleOf = (el) => { + const explicit = clean(el.getAttribute('role')).split(' ')[0]; + if (explicit) return explicit.toLowerCase(); + const tag = el.tagName.toLowerCase(); + const type = (el.getAttribute('type') || '').toLowerCase(); + switch (tag) { + case 'a': case 'area': return el.hasAttribute('href') ? 'link' : ''; + case 'button': return 'button'; + case 'input': + if (['button', 'submit', 'reset', 'image'].includes(type)) return 'button'; + if (type === 'checkbox') return 'checkbox'; + if (type === 'radio') return 'radio'; + if (type === 'search') return 'searchbox'; + if (['', 'text', 'email', 'tel', 'url', 'password'].includes(type)) return 'textbox'; + return ''; + case 'textarea': return 'textbox'; + case 'select': return 'combobox'; + case 'img': return el.getAttribute('alt') === '' ? 'presentation' : 'img'; + case 'h1': case 'h2': case 'h3': case 'h4': case 'h5': case 'h6': return 'heading'; + case 'nav': return 'navigation'; + case 'main': return 'main'; + case 'dialog': return 'dialog'; + case 'article': return 'article'; + case 'ul': case 'ol': return 'list'; + case 'li': return 'listitem'; + case 'section': return (el.hasAttribute('aria-label') || el.hasAttribute('aria-labelledby')) ? 'region' : ''; + default: return ''; + } + }; + const textOf = (node, depth) => { + if (depth > 25) return ''; + let out = ''; + for (const child of node.childNodes) { + if (child.nodeType === 3) { out += child.nodeValue + ' '; continue; } + if (child.nodeType !== 1) continue; + if (child.getAttribute('aria-hidden') === 'true') continue; + const label = clean(child.getAttribute('aria-label')); + if (label) { out += label + ' '; continue; } + const tag = child.tagName.toLowerCase(); + if (tag === 'img') { out += (child.getAttribute('alt') || '') + ' '; continue; } + if (tag === 'script' || tag === 'style' || tag === 'template') continue; + out += textOf(child, depth + 1) + ' '; + } + return out; + }; + const fromContent = new Set(['button', 'link', 'tab', 'menuitem', 'heading', 'cell', 'gridcell', 'option', + 'checkbox', 'radio', 'switch', 'listitem', 'treeitem', 'columnheader', 'rowheader', 'tooltip']); + const nameOf = (el, role) => { + const ids = clean(el.getAttribute('aria-labelledby')); + if (ids) { + const joined = clean(ids.split(' ').map((id) => document.getElementById(id)).filter(Boolean).map((e) => e.textContent).join(' ')); + if (joined) return joined; + } + const aria = clean(el.getAttribute('aria-label')); + if (aria) return aria; + const tag = el.tagName.toLowerCase(); + const type = (el.getAttribute('type') || '').toLowerCase(); + if (tag === 'img' || (tag === 'input' && type === 'image')) { + const alt = clean(el.getAttribute('alt')); + if (alt) return alt; + } + if (tag === 'input' && ['button', 'submit', 'reset'].includes(type)) { + const label = clean(el.getAttribute('value')); + if (label) return label; + } + if (fromContent.has(role)) { + const text = clean(textOf(el, 0)); + if (text) return text; + } + return clean(el.getAttribute('title') || el.getAttribute('placeholder')); + }; + const nameRe = spec.name ? new RegExp(spec.name, 'i') : null; + const hrefRe = spec.href ? new RegExp(spec.href, 'i') : null; + const candidates = document.querySelectorAll(hrefRe ? 'a[href], area[href]' : '*'); + const vw = window.innerWidth; + const vh = window.innerHeight; + const matches = []; + for (const el of candidates) { + const role = roleOf(el); + if (spec.roles.length > 0 && !spec.roles.includes(role)) continue; + if (hrefRe) { + let path; + try { path = new URL(el.getAttribute('href'), document.baseURI).pathname; } catch { continue; } + if (!hrefRe.test(path)) continue; + } + if (nameRe && !nameRe.test(nameOf(el, role))) continue; + const r = el.getBoundingClientRect(); + let visible = r.width > 0 && r.height > 0; + if (visible && typeof el.checkVisibility === 'function') { + visible = el.checkVisibility({ opacityProperty: true, visibilityProperty: true }); + } else if (visible) { + const cs = getComputedStyle(el); + visible = cs.visibility !== 'hidden' && cs.display !== 'none' && parseFloat(cs.opacity) > 0; + } + const left = Math.max(r.left, 0); + const top = Math.max(r.top, 0); + const right = Math.min(r.right, vw); + const bottom = Math.min(r.bottom, vh); + const inViewport = visible && right > left && bottom > top; + let unobstructed = false; + if (inViewport) { + const hit = document.elementFromPoint((left + right) / 2, (top + bottom) / 2); + unobstructed = !!hit && (hit === el || el.contains(hit)); + } + matches.push({ x: r.left, y: r.top, width: r.width, height: r.height, visible, inViewport, unobstructed }); + if (matches.length >= 200) break; + } + return { viewportWidth: vw, viewportHeight: vh, matches }; + })() + """; + + private readonly ICdpSession _cdp; + private readonly TargetMap _map; + + public TargetResolver(ICdpSession cdp, TargetMap map) + { + _cdp = cdp ?? throw new ArgumentNullException(nameof(cdp)); + _map = map ?? throw new ArgumentNullException(nameof(map)); + } + + public TargetMap Map => _map; + + /// Finds target ; fill the {placeholders} of the map. + public async Task ResolveAsync(string id, IReadOnlyDictionary? parameters = null, CancellationToken ct = default) + { + var spec = _map.Get(id); + var (all, width, height) = await MeasureAsync(spec, parameters, ct).ConfigureAwait(false); + var visible = all.Where(e => e.Visible).ToList(); + if (all.Count == 0) + { + return new TargetLookup(id, TargetStatus.NotFound, null, 0, width, height); + } + + if (visible.Count == 0) + { + return new TargetLookup(id, TargetStatus.NotVisible, null, 0, width, height); + } + + var index = spec.Index < 0 ? visible.Count + spec.Index : spec.Index; + return index < 0 || index >= visible.Count + ? new TargetLookup(id, TargetStatus.IndexOutOfRange, null, visible.Count, width, height) + : new TargetLookup(id, TargetStatus.Found, visible[index], visible.Count, width, height); + } + + /// Every element matching , visible or not, in document order (at most 200). + public async Task> FindAllAsync(string id, IReadOnlyDictionary? parameters = null, CancellationToken ct = default) + { + var (all, _, _) = await MeasureAsync(_map.Get(id), parameters, ct).ConfigureAwait(false); + return all; + } + + /// The expression sent to Runtime.evaluate for (exposed for tests). + public static string BuildExpression(TargetSpec spec, IReadOnlyDictionary? parameters) + { + ArgumentNullException.ThrowIfNull(spec); + var json = new JsonObject + { + ["roles"] = new JsonArray([.. spec.Roles.Select(r => (JsonNode?)JsonValue.Create(r))]), + ["name"] = spec.NamePattern is null ? null : TargetMap.ExpandNamePattern(spec.NamePattern, parameters), + ["href"] = spec.HrefPattern is null ? null : TargetMap.HrefPatternToRegex(spec.HrefPattern, parameters), + }; + return Script.Replace("__SPEC__", json.ToJsonString(), StringComparison.Ordinal); + } + + private async Task<(List All, double Width, double Height)> MeasureAsync(TargetSpec spec, IReadOnlyDictionary? parameters, CancellationToken ct) + { + var value = await _cdp.EvaluateAsync(BuildExpression(spec, parameters), ct).ConfigureAwait(false); + var list = new List(); + if (value.ValueKind != JsonValueKind.Object) + { + return (list, 0, 0); + } + + foreach (var m in value.GetProperty("matches").EnumerateArray()) + { + list.Add(new TargetElement( + new PageRect(m.GetProperty("x").GetDouble(), m.GetProperty("y").GetDouble(), m.GetProperty("width").GetDouble(), m.GetProperty("height").GetDouble()), + m.GetProperty("visible").GetBoolean(), + m.GetProperty("inViewport").GetBoolean(), + m.GetProperty("unobstructed").GetBoolean())); + } + + return (list, value.GetProperty("viewportWidth").GetDouble(), value.GetProperty("viewportHeight").GetDouble()); + } +} + +/// Result of clicking a target. +/// True when the click was performed. +/// The last lookup (its status says why there was no click). +/// Where the click landed. +public sealed record TargetClickResult(bool Clicked, TargetLookup Lookup, PagePoint? At); + +/// +/// Clicks map targets with human gestures. When a target is missing, hidden or covered nothing is clicked and +/// the result says why: recipes stop and report (spec §7.7). +/// +public sealed class TargetActions(TargetResolver resolver, HumanGestures gestures) +{ + /// Brings the target into view with wheel bursts if needed (at most ), then clicks it. + public async Task ClickAsync(string id, IReadOnlyDictionary? parameters = null, int maxScrollBursts = 6, CancellationToken ct = default) + { + var lookup = await resolver.ResolveAsync(id, parameters, ct).ConfigureAwait(false); + for (var burst = 0; lookup is { Found: true, Element.InViewport: false } && burst < maxScrollBursts; burst++) + { + var rect = lookup.Element!.Rect; + var direction = rect.Bottom <= 0 ? -1 : 1; + gestures.Viewport = (lookup.ViewportWidth, lookup.ViewportHeight); + await gestures.ScrollBurstAsync(direction, ct).ConfigureAwait(false); + await gestures.WaitAsync(gestures.Settings.BetweenBurstsMs, ct).ConfigureAwait(false); + lookup = await resolver.ResolveAsync(id, parameters, ct).ConfigureAwait(false); + } + + if (!lookup.Found) + { + return new TargetClickResult(false, lookup, null); + } + + var element = lookup.Element!; + if (!element.InViewport) + { + return new TargetClickResult(false, lookup with { Status = TargetStatus.OutOfView }, null); + } + + if (!element.Unobstructed) + { + return new TargetClickResult(false, lookup with { Status = TargetStatus.Obstructed }, null); + } + + // Aim at the visible part of the element only. + var left = Math.Max(element.Rect.X, 0); + var top = Math.Max(element.Rect.Y, 0); + var right = Math.Min(element.Rect.Right, lookup.ViewportWidth); + var bottom = Math.Min(element.Rect.Bottom, lookup.ViewportHeight); + gestures.Viewport = (lookup.ViewportWidth, lookup.ViewportHeight); + var at = await gestures.ClickAsync(new PageRect(left, top, right - left, bottom - top), ct).ConfigureAwait(false); + return new TargetClickResult(true, lookup, at); + } +} diff --git a/src/Febe.Core/Collection/HostClassifier.cs b/src/Febe.Core/Collection/HostClassifier.cs new file mode 100644 index 0000000..385e827 --- /dev/null +++ b/src/Febe.Core/Collection/HostClassifier.cs @@ -0,0 +1,136 @@ +namespace Febe.Core.Collection; + +/// An address reduced to what may be kept: scheme, host and path. Never query string or fragment. +/// The sanitized address, e.g. «https://www.example.org/a/b/». +/// Scheme in lower case («https», «about», «data»...). +/// Host in lower case, with the port when it is not the default one; empty when there is none. +/// Path without query and fragment; empty for opaque addresses (data:, blob:). +public sealed record SanitizedUrl(string Url, string Scheme, string Host, string Path) +{ + public override string ToString() => Url; +} + +/// Strips query strings, fragments and credentials from addresses (spec §7.6, §13.2). +public static class UrlSanitizer +{ + public static SanitizedUrl Sanitize(string? url) + { + if (string.IsNullOrWhiteSpace(url)) + { + return new SanitizedUrl(string.Empty, string.Empty, string.Empty, string.Empty); + } + + if (!Uri.TryCreate(url, UriKind.Absolute, out var uri)) + { + // Not an absolute address: keep nothing that could carry data. + return new SanitizedUrl("(indirizzo non valido)", string.Empty, string.Empty, string.Empty); + } + + var scheme = uri.Scheme.ToLowerInvariant(); + if (scheme is "http" or "https" or "ws" or "wss") + { + var host = HostWithPort(uri); + var path = string.IsNullOrEmpty(uri.AbsolutePath) ? "/" : uri.AbsolutePath; + return new SanitizedUrl($"{scheme}://{host}{path}", scheme, host, path); + } + + if (scheme == "about") + { + // about:blank, about:srcdoc: no data inside. + var opaque = uri.AbsolutePath.ToLowerInvariant(); + return new SanitizedUrl($"about:{opaque}", scheme, string.Empty, opaque); + } + + // data:, blob:, chrome:, file: ... only the scheme survives. + return new SanitizedUrl($"{scheme}:", scheme, string.Empty, string.Empty); + } + + internal static string HostWithPort(Uri uri) + { + var host = uri.IdnHost.ToLowerInvariant(); + if (uri.HostNameType == UriHostNameType.IPv6 && !host.StartsWith('[')) + { + host = $"[{host}]"; + } + + return uri.IsDefaultPort ? host : $"{host}:{uri.Port}"; + } +} + +/// +/// Tells site, CDN and other hosts apart. Entries are host names that also match their sub-domains +/// («instagram.com» matches «www.instagram.com»), or exact «host:port» pairs (used by the local test site). +/// +public sealed class HostClassifier +{ + private readonly string[] _site; + private readonly string[] _cdn; + + public HostClassifier(IEnumerable siteHosts, IEnumerable cdnHosts) + { + _site = Normalize(siteHosts); + _cdn = Normalize(cdnHosts); + } + + /// + /// Instagram's public host names: the site and the two CDN families its pages load files from. + /// Public knowledge, not response formats; still to be confirmed by the M0 probe. + /// + public static HostClassifier Instagram { get; } = new( + ["instagram.com"], + ["cdninstagram.com", "fbcdn.net"]); + + public IReadOnlyList SiteHosts => _site; + + public IReadOnlyList CdnHosts => _cdn; + + public HostKind Classify(string? url) => + Uri.TryCreate(url, UriKind.Absolute, out var uri) ? Classify(uri) : HostKind.Other; + + public HostKind Classify(Uri uri) + { + ArgumentNullException.ThrowIfNull(uri); + if (uri.Scheme is not ("http" or "https")) + { + return HostKind.Other; + } + + var host = uri.IdnHost.ToLowerInvariant(); + var hostWithPort = UrlSanitizer.HostWithPort(uri); + var explicitPort = $"{host}:{uri.Port}"; + + // CDN first: a CDN entry is more specific than a site entry when both could match. + if (Matches(_cdn, host, hostWithPort, explicitPort)) + { + return HostKind.Cdn; + } + + return Matches(_site, host, hostWithPort, explicitPort) ? HostKind.Site : HostKind.Other; + } + + private static bool Matches(string[] entries, string host, string hostWithPort, string explicitPort) + { + foreach (var entry in entries) + { + if (entry.Contains(':', StringComparison.Ordinal)) + { + if (entry == hostWithPort || entry == explicitPort) + { + return true; + } + } + else if (host == entry || host.EndsWith("." + entry, StringComparison.Ordinal)) + { + return true; + } + } + + return false; + } + + private static string[] Normalize(IEnumerable hosts) + { + ArgumentNullException.ThrowIfNull(hosts); + return [.. hosts.Select(h => h.Trim().TrimStart('.').ToLowerInvariant()).Where(h => h.Length > 0).Distinct()]; + } +} diff --git a/src/Febe.Core/Collection/IFileFetcher.cs b/src/Febe.Core/Collection/IFileFetcher.cs new file mode 100644 index 0000000..2035a7e --- /dev/null +++ b/src/Febe.Core/Collection/IFileFetcher.cs @@ -0,0 +1,49 @@ +namespace Febe.Core.Collection; + +/// How a file download ended. +public enum FetchOutcome +{ + /// All bytes were written to the destination. + Completed, + + /// The server answered with an error status (e.g. an expired signed address, spec §6.5 point 5). + HttpError, + + /// The request failed before a response (network error, refused by the browser). + NetworkError, + + /// The file exceeded the maximum size allowed by the caller; the destination holds a partial copy. + TooLarge, + + /// The address is not on an allowed host (only CDN addresses may be downloaded). + HostNotAllowed, +} + +/// Result of a download. Never contains the address: it carries signatures (spec §13.2). +/// How it ended. +/// Bytes written to the destination. +/// HTTP status code, when a response arrived. +/// Short error description without the address, when it failed. +public sealed record FetchResult(FetchOutcome Outcome, long Bytes, int? HttpStatus, string? Error) +{ + public bool Succeeded => Outcome == FetchOutcome.Completed; +} + +/// Options of a single download. +/// Abort with past this size; null for no limit. +/// Receives the number of bytes written so far. +public sealed record FetchOptions(long? MaxBytes = null, IProgress? Progress = null); + +/// +/// Downloads one file indicated by the page into a stream (spec §6.5). The preferred implementation goes through +/// the browser (Network.loadNetworkResource + IO.read); a fallback through HttpClient to CDN hosts +/// only may be added if M0 shows the first one does not work with the real CDN (H7). +/// +/// +/// The caller owns the destination: it writes to a temporary name, hashes and renames (spec §6.5 point 4). +/// Implementations never log the address. Cancellation throws . +/// +public interface IFileFetcher +{ + Task FetchAsync(Uri address, Stream destination, FetchOptions? options, CancellationToken ct); +} diff --git a/src/Febe.Core/Collection/IResponseConsumer.cs b/src/Febe.Core/Collection/IResponseConsumer.cs new file mode 100644 index 0000000..034f68f --- /dev/null +++ b/src/Febe.Core/Collection/IResponseConsumer.cs @@ -0,0 +1,72 @@ +using System.Text.Json; + +namespace Febe.Core.Collection; + +/// Which kind of host served a response (spec §14.5: only the site/CDN distinction is kept). +public enum HostKind +{ + /// The site itself (Instagram pages and data, or the local test site). + Site, + + /// The content delivery network that serves photos and videos. + Cdn, + + /// Anything else the page happens to contact. + Other, +} + +/// +/// Sanitized description of a response seen by the page: never the query string, never headers, never the body. +/// +/// Browser request identifier (opaque, only meaningful inside one browser session). +/// Site, CDN or other. +/// Scheme, host and path, without query string and fragment (see ). +/// For CDN responses it must not be logged: it identifies files (spec §13.2). +/// Host name, with the port when it is not the default one. +/// Path without query string and fragment. +/// HTTP status code. +/// MIME type declared by the response, lower case, without parameters. +/// Browser resource type (Document, XHR, Fetch, Image, ...), when known. +/// True for the document of the main frame (a page load). +/// When the response was seen. +public sealed record ResponseDescriptor( + string RequestId, + HostKind HostKind, + string Url, + string Host, + string Path, + int Status, + string MimeType, + string? ResourceType, + bool IsMainFrameDocument, + DateTimeOffset At); + +/// A main-frame navigation: a new document, or a route change inside a single-page site. +/// Site, CDN or other. +/// Address without query string and fragment. +/// Host name (with port when not default); empty for about:blank and similar. +/// Path without query string and fragment. +/// When the navigation was seen. +/// True for a route change without a new document (history.pushState). +public sealed record NavigationDescriptor(HostKind HostKind, string Url, string Host, string Path, DateTimeOffset At, bool SameDocument = false); + +/// +/// Receives the JSON bodies captured by the response tap (spec §6.2): readers and signal detection. +/// +/// +/// The is owned by the caller and disposed right after the call returns: +/// consumers must not keep references to it or to its elements. Bodies live only in memory and are never logged. +/// +public interface IResponseConsumer +{ + ValueTask ConsumeAsync(ResponseDescriptor response, JsonDocument body, CancellationToken ct); +} + +/// Receives metadata of every response and every main-frame navigation (no bodies). +/// Called on the browser event thread: implementations must be quick and must not block. +public interface IResponseObserver +{ + void OnResponse(ResponseDescriptor response); + + void OnNavigation(NavigationDescriptor navigation); +} diff --git a/src/Febe.Core/Collection/SignalDetector.cs b/src/Febe.Core/Collection/SignalDetector.cs new file mode 100644 index 0000000..4ce5e71 --- /dev/null +++ b/src/Febe.Core/Collection/SignalDetector.cs @@ -0,0 +1,242 @@ +using System.Text.Json; +using System.Text.RegularExpressions; +using Febe.Core.Abstractions; + +namespace Febe.Core.Collection; + +/// +/// Turns what the page sees (responses, navigations, JSON bodies, empty pages, the session cookie) into stop +/// signals (spec §7.6) and reports them to the circuit breaker. It never logs or keeps bodies. +/// +/// +/// The same signal code is reported at most once per : a page that receives ten 429 +/// responses in a second is one throttle, not ten. Thread-safe. +/// +public sealed class SignalDetector : IResponseObserver, IResponseConsumer +{ + private readonly SignalRules _rules; + private readonly ICircuitBreaker _breaker; + private readonly IClock _clock; + private readonly Dictionary _lastReported = new(StringComparer.Ordinal); + private readonly Lock _gate = new(); + private int _consecutiveEmpty; + + public SignalDetector(SignalRules rules, ICircuitBreaker breaker, IClock clock, TimeSpan? dedupeWindow = null) + { + _rules = rules ?? throw new ArgumentNullException(nameof(rules)); + _breaker = breaker ?? throw new ArgumentNullException(nameof(breaker)); + _clock = clock ?? throw new ArgumentNullException(nameof(clock)); + DedupeWindow = dedupeWindow ?? TimeSpan.FromSeconds(60); + } + + public TimeSpan DedupeWindow { get; } + + /// Raised after a signal has been reported to the breaker. + public event EventHandler? SignalRaised; + + void IResponseObserver.OnResponse(ResponseDescriptor response) => ObserveResponse(response); + + void IResponseObserver.OnNavigation(NavigationDescriptor navigation) => ObserveNavigation(navigation); + + ValueTask IResponseConsumer.ConsumeAsync(ResponseDescriptor response, JsonDocument body, CancellationToken ct) + { + ObserveJsonBody(response, body.RootElement); + return ValueTask.CompletedTask; + } + + /// Status and path rules on a response. + public Signal? ObserveResponse(ResponseDescriptor response) + { + ArgumentNullException.ThrowIfNull(response); + var scope = response.IsMainFrameDocument ? SignalScope.Document : SignalScope.Subresource; + foreach (var rule in _rules.Rules) + { + if (!rule.HostKinds.Contains(response.HostKind) || (rule.Scope & scope) == 0) + { + continue; + } + + if ((rule.Statuses.Count > 0 && rule.Statuses.Contains(response.Status)) + || (rule.Path is not null && SafeIsMatch(rule.Path, response.Path))) + { + return Raise(rule.Level, rule.Code, response.Url); + } + } + + return null; + } + + /// Path rules on a main-frame navigation. + public Signal? ObserveNavigation(NavigationDescriptor navigation) + { + ArgumentNullException.ThrowIfNull(navigation); + foreach (var rule in _rules.Rules) + { + if (rule.Path is null || (rule.Scope & SignalScope.Navigation) == 0 || !rule.HostKinds.Contains(navigation.HostKind)) + { + continue; + } + + if (SafeIsMatch(rule.Path, navigation.Path)) + { + return Raise(rule.Level, rule.Code, navigation.Url); + } + } + + return null; + } + + /// Text rules on the string values of a short JSON response. + public Signal? ObserveJsonBody(ResponseDescriptor response, JsonElement root) + { + ArgumentNullException.ThrowIfNull(response); + foreach (var rule in _rules.Rules) + { + if (rule.Text is null || !rule.HostKinds.Contains(response.HostKind)) + { + continue; + } + + if (ContainsText(root, rule.Text, rule.MaxTextChars)) + { + return Raise(rule.Level, rule.Code, response.Url); + } + } + + return null; + } + + /// + /// A recipe loaded a page (or a page of data) that turned out empty. After the configured number of + /// consecutive empty pages a throttle signal is raised. The caller decides what «empty» means. + /// + public Signal? ObserveEmptyPage(string? url = null) + { + if (_rules.EmptyPages is not { } rule) + { + return null; + } + + lock (_gate) + { + _consecutiveEmpty++; + if (_consecutiveEmpty < rule.Consecutive) + { + return null; + } + + _consecutiveEmpty = 0; + } + + return Raise(rule.Level, rule.Code, url is null ? null : UrlSanitizer.Sanitize(url).Url); + } + + /// A recipe loaded a page with content: resets the empty-page counter. + public void ObserveNonEmptyPage() + { + lock (_gate) + { + _consecutiveEmpty = 0; + } + } + + /// Result of the session-cookie check: a missing cookie is a disconnection (spec §7.6). + public Signal? ObserveSessionCookie(bool present) => + present ? null : Raise(SignalLevel.Disconnect, SignalRules.SessionCookieMissingCode, null); + + private Signal? Raise(SignalLevel level, string code, string? url) + { + var now = _clock.Now; + lock (_gate) + { + if (_lastReported.TryGetValue(code, out var last) && now - last < DedupeWindow) + { + return null; + } + + _lastReported[code] = now; + } + + var signal = new Signal(level, code, url, now); + _breaker.Report(signal); + SignalRaised?.Invoke(this, signal); + return signal; + } + + private static bool SafeIsMatch(Regex regex, string input) + { + try + { + return regex.IsMatch(input); + } + catch (RegexMatchTimeoutException) + { + return false; + } + } + + /// Looks for in the string values, giving up when they exceed . + private static bool ContainsText(JsonElement root, Regex regex, int maxChars) + { + var budget = maxChars; + var strings = new List(); + if (!Collect(root, strings, ref budget, depth: 0)) + { + return false; + } + + foreach (var s in strings) + { + if (SafeIsMatch(regex, s)) + { + return true; + } + } + + return false; + } + + private static bool Collect(JsonElement element, List strings, ref int budget, int depth) + { + if (depth > 32) + { + return false; + } + + switch (element.ValueKind) + { + case JsonValueKind.String: + var value = element.GetString() ?? string.Empty; + budget -= value.Length; + if (budget < 0) + { + return false; + } + + strings.Add(value); + return true; + case JsonValueKind.Object: + foreach (var property in element.EnumerateObject()) + { + if (!Collect(property.Value, strings, ref budget, depth + 1)) + { + return false; + } + } + + return true; + case JsonValueKind.Array: + foreach (var item in element.EnumerateArray()) + { + if (!Collect(item, strings, ref budget, depth + 1)) + { + return false; + } + } + + return true; + default: + return true; + } + } +} diff --git a/src/Febe.Core/Collection/SignalRules.cs b/src/Febe.Core/Collection/SignalRules.cs new file mode 100644 index 0000000..0150a34 --- /dev/null +++ b/src/Febe.Core/Collection/SignalRules.cs @@ -0,0 +1,271 @@ +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Text.RegularExpressions; +using Febe.Core.Abstractions; + +namespace Febe.Core.Collection; + +/// Where a path rule looks. +[Flags] +public enum SignalScope +{ + None = 0, + + /// Main-frame navigations (the address the page moved to). + Navigation = 1, + + /// Main-frame document responses (page loads, redirects included). + Document = 2, + + /// Every other response (data requests, files). + Subresource = 4, + + Any = Navigation | Document | Subresource, +} + +/// One rule of segnali.json: exactly one matcher among status, path and text. +public sealed record SignalRule +{ + public required string Code { get; init; } + + public required SignalLevel Level { get; init; } + + /// HTTP status codes that trigger the rule. + public IReadOnlySet Statuses { get; init; } = new HashSet(); + + /// Regular expression on the address path (no query string). + public Regex? Path { get; init; } + + /// Regular expression on the string values of short JSON responses. + public Regex? Text { get; init; } + + /// Text rules only look at responses whose strings total at most this many characters. + public int MaxTextChars { get; init; } = SignalRules.DefaultMaxTextChars; + + public IReadOnlySet HostKinds { get; init; } = new HashSet { HostKind.Site, HostKind.Cdn }; + + public SignalScope Scope { get; init; } = SignalScope.Any; + + /// Hypothesis of spec §6.6 the rule depends on (e.g. «H8»), when it is not yet confirmed. + public string? Hypothesis { get; init; } +} + +/// Threshold of the «repeated empty pages» throttle signal. +public sealed record EmptyPagesRule(string Code, SignalLevel Level, int Consecutive); + +/// +/// The stop-signal rules (spec §7.6), loaded from segnali.json so they can change without recompiling. +/// +public sealed class SignalRules +{ + public const int DefaultMaxTextChars = 4000; + + /// Code of the built-in rule «the session cookie is gone» (spec §7.6, Disconnessione). + public const string SessionCookieMissingCode = "session-cookie-missing"; + + private static readonly TimeSpan RegexTimeout = TimeSpan.FromMilliseconds(250); + + public SignalRules(IReadOnlyList rules, EmptyPagesRule? emptyPages, string? source = null) + { + Rules = rules; + EmptyPages = emptyPages; + Source = source; + } + + public IReadOnlyList Rules { get; } + + public EmptyPagesRule? EmptyPages { get; } + + /// Where the rules came from (file path or embedded resource name), for messages. + public string? Source { get; } + + /// The shipped Instagram rules (embedded copy of config/segnali.json). + public static SignalRules LoadDefault() => LoadEmbedded("segnali.json"); + + /// The rules of the local test site (embedded copy of config/segnali.prova.json). + public static SignalRules LoadTestSite() => LoadEmbedded("segnali.prova.json"); + + /// Loads when it exists, otherwise the shipped default rules. + public static SignalRules LoadOrDefault(string? path) => + !string.IsNullOrEmpty(path) && File.Exists(path) ? Load(path) : LoadDefault(); + + public static SignalRules Load(string path) => Parse(File.ReadAllText(path), path); + + public static SignalRules LoadEmbedded(string fileName) + { + var resource = $"Febe.Core.Config.{fileName}"; + using var stream = typeof(SignalRules).Assembly.GetManifestResourceStream(resource) + ?? throw new FileNotFoundException($"Risorsa incorporata mancante: {resource}"); + using var reader = new StreamReader(stream); + return Parse(reader.ReadToEnd(), fileName); + } + + public static SignalRules Parse(string json, string? source = null) + { + var name = source ?? "segnali.json"; + SignalRulesFile? file; + try + { + file = JsonSerializer.Deserialize(json, SignalRulesJsonContext.Default.SignalRulesFile); + } + catch (JsonException ex) + { + throw new InvalidDataException($"{name}: il file non è un JSON valido (riga {ex.LineNumber + 1}).", ex); + } + + if (file?.Rules is null) + { + throw new InvalidDataException($"{name}: manca l'elenco «rules»."); + } + + var rules = new List(file.Rules.Count); + for (var i = 0; i < file.Rules.Count; i++) + { + rules.Add(ToRule(file.Rules[i], $"{name}, regola {i + 1}")); + } + + // The same code may appear in several rules (e.g. two challenge paths): that is allowed. + EmptyPagesRule? empty = null; + if (file.EmptyPages is { } e) + { + if (e.Consecutive < 2) + { + throw new InvalidDataException($"{name}: «emptyPages.consecutive» deve essere almeno 2."); + } + + empty = new EmptyPagesRule(RequireCode(e.Code, $"{name}, emptyPages"), ParseLevel(e.Level, $"{name}, emptyPages"), e.Consecutive); + } + + return new SignalRules(rules, empty, source); + } + + /// Parses a level name, in English (code) or Italian (interface) form. + public static SignalLevel ParseLevel(string? value, string where) => value?.Trim().ToLowerInvariant() switch + { + "throttle" or "rallentamento" => SignalLevel.Throttle, + "challenge" or "verifica" => SignalLevel.Challenge, + "disconnect" or "disconnessione" => SignalLevel.Disconnect, + _ => throw new InvalidDataException($"{where}: livello «{value}» sconosciuto (ammessi: throttle, challenge, disconnect)."), + }; + + private static SignalRule ToRule(SignalRuleDto dto, string where) + { + var code = RequireCode(dto.Code, where); + var level = ParseLevel(dto.Level, where); + + var matchers = (dto.Status is { Count: > 0 } ? 1 : 0) + (string.IsNullOrEmpty(dto.Path) ? 0 : 1) + (string.IsNullOrEmpty(dto.Text) ? 0 : 1); + if (matchers != 1) + { + throw new InvalidDataException($"{where}: serve esattamente uno fra «status», «path» e «text»."); + } + + var hostKinds = dto.HostKinds is { Count: > 0 } + ? dto.HostKinds.Select(k => ParseHostKind(k, where)).ToHashSet() + : (dto.Text is null ? new HashSet { HostKind.Site, HostKind.Cdn } : new HashSet { HostKind.Site }); + + var scope = dto.On is { Count: > 0 } + ? dto.On.Aggregate(SignalScope.None, (acc, s) => acc | ParseScope(s, where)) + : (string.IsNullOrEmpty(dto.Path) ? SignalScope.Any : SignalScope.Navigation | SignalScope.Document); + + return new SignalRule + { + Code = code, + Level = level, + Statuses = dto.Status is { Count: > 0 } ? dto.Status.ToHashSet() : new HashSet(), + Path = CompileRegex(dto.Path, where), + Text = CompileRegex(dto.Text, where), + MaxTextChars = dto.MaxTextChars is > 0 ? dto.MaxTextChars.Value : DefaultMaxTextChars, + HostKinds = hostKinds, + Scope = scope, + Hypothesis = string.IsNullOrWhiteSpace(dto.Hypothesis) ? null : dto.Hypothesis.Trim(), + }; + } + + private static string RequireCode(string? code, string where) => + string.IsNullOrWhiteSpace(code) ? throw new InvalidDataException($"{where}: manca «code».") : code.Trim(); + + private static Regex? CompileRegex(string? pattern, string where) + { + if (string.IsNullOrEmpty(pattern)) + { + return null; + } + + try + { + return new Regex(pattern, RegexOptions.CultureInvariant | RegexOptions.IgnoreCase, RegexTimeout); + } + catch (ArgumentException ex) + { + throw new InvalidDataException($"{where}: espressione «{pattern}» non valida.", ex); + } + } + + private static HostKind ParseHostKind(string value, string where) => value.Trim().ToLowerInvariant() switch + { + "site" or "sito" => HostKind.Site, + "cdn" => HostKind.Cdn, + "other" or "altro" => HostKind.Other, + _ => throw new InvalidDataException($"{where}: tipo di host «{value}» sconosciuto (ammessi: site, cdn, other)."), + }; + + private static SignalScope ParseScope(string value, string where) => value.Trim().ToLowerInvariant() switch + { + "navigation" => SignalScope.Navigation, + "document" => SignalScope.Document, + "subresource" => SignalScope.Subresource, + "any" => SignalScope.Any, + _ => throw new InvalidDataException($"{where}: ambito «{value}» sconosciuto (ammessi: navigation, document, subresource, any)."), + }; +} + +internal sealed class SignalRulesFile +{ + public string? Note { get; set; } + + public List? Rules { get; set; } + + public EmptyPagesDto? EmptyPages { get; set; } +} + +internal sealed class SignalRuleDto +{ + public string? Code { get; set; } + + public string? Level { get; set; } + + public List? Status { get; set; } + + public string? Path { get; set; } + + public string? Text { get; set; } + + public int? MaxTextChars { get; set; } + + public List? HostKinds { get; set; } + + public List? On { get; set; } + + public string? Hypothesis { get; set; } + + public string? Note { get; set; } +} + +internal sealed class EmptyPagesDto +{ + public string? Code { get; set; } + + public string? Level { get; set; } + + public int Consecutive { get; set; } + + public string? Note { get; set; } +} + +[JsonSourceGenerationOptions( + PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase, + ReadCommentHandling = JsonCommentHandling.Skip, + AllowTrailingCommas = true, + UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow)] +[JsonSerializable(typeof(SignalRulesFile))] +internal sealed partial class SignalRulesJsonContext : JsonSerializerContext; diff --git a/src/Febe.Core/Config/segnali.json b/src/Febe.Core/Config/segnali.json new file mode 100644 index 0000000..80f0e79 --- /dev/null +++ b/src/Febe.Core/Config/segnali.json @@ -0,0 +1,72 @@ +{ + "note": "Segnali di arresto per Instagram (specifica §7.6). Si modifica senza ricompilare. Ogni regola ha uno solo fra status (codici HTTP), path (espressione sul percorso, senza parametri) e text (espressione sui testi di una risposta JSON breve). level: throttle = rallentamento, challenge = verifica, disconnect = disconnessione. Le regole con hypothesis H8 sono ipotesi da confermare in M0 con la sonda: nessuna è stata vista su Instagram.", + "rules": [ + { + "code": "http-429", + "level": "throttle", + "status": [429], + "hostKinds": ["site", "cdn"], + "note": "Troppe richieste: stato HTTP standard, vale per sito e CDN." + }, + { + "code": "challenge-url", + "level": "challenge", + "path": "^/challenge(/|$)", + "hostKinds": ["site"], + "on": ["navigation", "document"], + "hypothesis": "H8", + "note": "Pagina di verifica. Percorso noto pubblicamente, da confermare in M0." + }, + { + "code": "checkpoint-url", + "level": "challenge", + "path": "(^|/)checkpoint(/|$)", + "hostKinds": ["site"], + "on": ["navigation", "document"], + "hypothesis": "H8", + "note": "Pagina di controllo. Da confermare in M0." + }, + { + "code": "suspended-url", + "level": "challenge", + "path": "^/accounts/(suspended|disabled)(/|$)", + "hostKinds": ["site"], + "on": ["navigation", "document"], + "hypothesis": "H8", + "note": "Account sospeso o disattivato. Da confermare in M0." + }, + { + "code": "login-url", + "level": "disconnect", + "path": "^/accounts/login(/|$)", + "hostKinds": ["site"], + "on": ["navigation", "document"], + "hypothesis": "H8", + "note": "La pagina torna all'accesso. Da confermare in M0." + }, + { + "code": "wait-text", + "level": "throttle", + "text": "please wait a few minutes|attendi qualche minuto", + "hostKinds": ["site"], + "maxTextChars": 4000, + "hypothesis": "H8", + "note": "Risposta che chiede di attendere. Si cerca solo nelle risposte JSON brevi, per non scambiare una didascalia per un segnale. Testo da confermare in M0." + }, + { + "code": "automation-warning", + "level": "challenge", + "text": "automated behaviou?r|comportamento automatizzato", + "hostKinds": ["site"], + "maxTextChars": 4000, + "hypothesis": "H8", + "note": "Avviso di comportamento automatico. Testo da confermare in M0." + } + ], + "emptyPages": { + "code": "empty-pages", + "level": "throttle", + "consecutive": 3, + "note": "Pagine o risposte vuote ripetute: le segnala la ricetta, che sa che cosa vuol dire vuoto." + } +} diff --git a/src/Febe.Core/Config/segnali.prova.json b/src/Febe.Core/Config/segnali.prova.json new file mode 100644 index 0000000..8f58d16 --- /dev/null +++ b/src/Febe.Core/Config/segnali.prova.json @@ -0,0 +1,36 @@ +{ + "note": "Segnali di arresto del sito di prova locale (specifica §14.2): stessi livelli di segnali.json, percorsi del sito di prova.", + "rules": [ + { + "code": "http-429", + "level": "throttle", + "status": [429], + "hostKinds": ["site", "cdn"] + }, + { + "code": "challenge-url", + "level": "challenge", + "path": "^/verifica(/|$)", + "hostKinds": ["site"], + "on": ["navigation", "document"] + }, + { + "code": "login-url", + "level": "disconnect", + "path": "^/accesso(/|$)", + "hostKinds": ["site"], + "on": ["navigation", "document"] + }, + { + "code": "wait-text", + "level": "throttle", + "text": "attendi qualche minuto", + "hostKinds": ["site"] + } + ], + "emptyPages": { + "code": "empty-pages", + "level": "throttle", + "consecutive": 3 + } +} diff --git a/src/Febe.Core/Febe.Core.csproj b/src/Febe.Core/Febe.Core.csproj index 0f2215c..ce06a54 100644 --- a/src/Febe.Core/Febe.Core.csproj +++ b/src/Febe.Core/Febe.Core.csproj @@ -4,6 +4,12 @@ + + + + + diff --git a/src/Febe.Core/Pacing/Distributions.cs b/src/Febe.Core/Pacing/Distributions.cs new file mode 100644 index 0000000..f665698 --- /dev/null +++ b/src/Febe.Core/Pacing/Distributions.cs @@ -0,0 +1,149 @@ +using Febe.Core.Abstractions; +using Febe.Core.Domain; + +namespace Febe.Core.Pacing; + +/// +/// The random draws of spec §7.2, all driven by so that a fixed seed reproduces them. +/// Durations, pauses and waits are never uniform: they come from truncated log-normal distributions. +/// +public static class Distributions +{ + /// Maximum rejection attempts before falling back to clamping (only reachable with a degenerate source). + private const int MaxRejections = 64; + + /// Standard normal value N(0, 1) by the Box-Muller transform. + public static double StandardNormal(this IRandomSource random) + { + ArgumentNullException.ThrowIfNull(random); + + // 1 - u lies in (0, 1], so the logarithm is always finite. + var u1 = 1.0 - random.NextDouble(); + var u2 = random.NextDouble(); + return Math.Sqrt(-2.0 * Math.Log(u1)) * Math.Cos(2.0 * Math.PI * u2); + } + + /// Normal value with the given mean and standard deviation. + public static double Normal(this IRandomSource random, double mean, double standardDeviation) => + mean + (standardDeviation * random.StandardNormal()); + + /// Log-normal value with the given median and σ (of the underlying normal). + public static double LogNormal(this IRandomSource random, double median, double sigma) + { + if (median <= 0 || double.IsNaN(median)) + { + throw new ArgumentOutOfRangeException(nameof(median), median, "The median must be positive."); + } + + if (sigma < 0 || double.IsNaN(sigma)) + { + throw new ArgumentOutOfRangeException(nameof(sigma), sigma, "Sigma cannot be negative."); + } + + return median * Math.Exp(sigma * random.StandardNormal()); + } + + /// + /// Log-normal value truncated to [, ] by rejection + /// (the shape inside the interval is preserved; nothing piles up on the bounds). + /// + public static double TruncatedLogNormal(this IRandomSource random, double median, double sigma, double min, double max) + { + if (min <= 0 || max < min) + { + throw new ArgumentOutOfRangeException(nameof(min), $"Invalid interval [{min}, {max}]."); + } + + if (min == max || sigma == 0) + { + return Math.Clamp(median, min, max); + } + + for (var attempt = 0; attempt < MaxRejections; attempt++) + { + var value = random.LogNormal(median, sigma); + if (value >= min && value <= max) + { + return value; + } + } + + return Math.Clamp(median, min, max); + } + + /// + /// An interval «from a to b» (spec §7.2): log-normal with median √(a·b), or when given, + /// σ = ln(b/a)/4, truncated to [a, b]. + /// + public static double Between(this IRandomSource random, double a, double b, double? median = null) + { + if (a <= 0 || b < a) + { + throw new ArgumentOutOfRangeException(nameof(a), $"Invalid interval [{a}, {b}]: both ends must be positive and a ≤ b."); + } + + if (median is { } m && (m < a || m > b)) + { + throw new ArgumentOutOfRangeException(nameof(median), m, $"The median must lie in [{a}, {b}]."); + } + + var sigma = Math.Log(b / a) / 4.0; + return random.TruncatedLogNormal(median ?? Math.Sqrt(a * b), sigma, a, b); + } + + /// Same as for durations. + public static TimeSpan Between(this IRandomSource random, TimeSpan a, TimeSpan b, TimeSpan? median = null) => + TimeSpan.FromMilliseconds(random.Between(a.TotalMilliseconds, b.TotalMilliseconds, median?.TotalMilliseconds)); + + /// + /// Integer count «from a to b», inclusive (e.g. 3–8 wheel events). Drawn from the same log-normal over + /// [a, b + 1) and floored, so it is never uniform and both ends remain reachable. + /// + public static int CountBetween(this IRandomSource random, int a, int b) + { + if (a < 1 || b < a) + { + throw new ArgumentOutOfRangeException(nameof(a), $"Invalid count interval [{a}, {b}]."); + } + + if (a == b) + { + return a; + } + + var value = (int)Math.Floor(random.Between(a, b + 1 - 1e-9)); + return Math.Clamp(value, a, b); + } + + /// Session mood (spec §7.2): log-normal, median 1, σ 0.2, truncated to [0.7, 1.5]. Multiplies every wait. + public static double SessionMood(this IRandomSource random) => + random.TruncatedLogNormal(1.0, 0.2, 0.7, 1.5); + + /// Next-check jitter (spec §7.2): log-normal, median 1, σ 0.25, truncated to [0.6, 1.8]. Multiplies an interval. + public static double NextCheckJitter(this IRandomSource random) => + random.TruncatedLogNormal(1.0, 0.25, 0.6, 1.8); + + /// The next check after , scaled by . + public static TimeSpan JitteredInterval(this IRandomSource random, TimeSpan interval) => + TimeSpan.FromTicks((long)(interval.Ticks * random.NextCheckJitter())); + + /// True with probability (a Bernoulli draw, not a duration). + public static bool Chance(this IRandomSource random, double probability) + { + ArgumentNullException.ThrowIfNull(random); + return probability > 0 && random.NextDouble() < probability; + } +} + +/// Factors of the «Ritmo dei gesti» slider (spec §7.7): they multiply every gesture wait. +public static class GesturePaceFactors +{ + /// Multiplier of waits for : slow 1.35, natural 1, brisk 0.75. + public static double For(GesturePace pace) => pace switch + { + GesturePace.Slow => 1.35, + GesturePace.Natural => 1.0, + GesturePace.Brisk => 0.75, + _ => throw new ArgumentOutOfRangeException(nameof(pace), pace, null), + }; +} diff --git a/tests/Febe.Tests/Browser/BrowserIntegrationTests.cs b/tests/Febe.Tests/Browser/BrowserIntegrationTests.cs new file mode 100644 index 0000000..794aeaf --- /dev/null +++ b/tests/Febe.Tests/Browser/BrowserIntegrationTests.cs @@ -0,0 +1,401 @@ +using System.Collections.Concurrent; +using System.Diagnostics; +using System.Security.Cryptography; +using System.Text.Json; +using System.Text.Json.Nodes; +using Febe.Browser.Capture; +using Febe.Browser.Cdp; +using Febe.Browser.Download; +using Febe.Browser.Gestures; +using Febe.Browser.Hosting; +using Febe.Browser.RemoteView; +using Febe.Browser.Targets; +using Febe.Core.Abstractions; +using Febe.Core.Collection; +using Febe.Tests.Browser.TestSupport; + +namespace Febe.Tests.Browser; + +/// +/// The browser layer against a real Chromium on a private Xvfb display and a local site served by the test. +/// Never Instagram. One browser is shared by the whole class; the tests run one at a time. +/// +[TestClass] +[DoNotParallelize] +public sealed class BrowserIntegrationTests +{ + private const string Targets = """ + { + "site": "prova-integrazione", + "targets": { + "avanti": { "role": "button", "name": "^avanti$" }, + "coperto": { "role": "button", "name": "^coperto$" }, + "lontano": { "role": "button", "name": "^lontano$" }, + "profilo": { "role": "link", "href": "/profilo/{username}/" }, + "storia": { "role": "link", "href": "/stories/{username}/**", "name": "storia" }, + "inesistente": { "role": "button", "name": "^non c'è$" }, + "campo": { "role": "textbox", "name": "^campo$" } + } + } + """; + + private static RealBrowser? s_browser; + private static string? s_unavailable; + + public TestContext TestContext { get; set; } = null!; + + private static RealBrowser Browser => s_browser ?? throw new InvalidOperationException("Browser non avviato."); + + [ClassInitialize] + public static async Task StartBrowserAsync(TestContext context) + { + s_unavailable = RealBrowser.UnavailableReason(); + if (s_unavailable is null) + { + s_browser = await RealBrowser.StartAsync(); + } + } + + [ClassCleanup] + public static async Task StopBrowserAsync() + { + if (s_browser is not null) + { + await s_browser.DisposeAsync(); + s_browser = null; + } + } + + [TestInitialize] + public void RequireBrowser() + { + if (s_unavailable is not null) + { + Assert.Inconclusive(s_unavailable); + } + } + + [TestMethod] + public async Task ThePageSeesAnOrdinaryVisibleBrowser() + { + await Browser.GoAsync("/ambiente"); + var seen = await Browser.Cdp.EvaluateAsync(""" + ({ + webdriver: navigator.webdriver, + visibility: document.visibilityState, + hidden: document.hidden, + focus: document.hasFocus(), + language: navigator.language, + languages: navigator.languages, + timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone, + userAgent: navigator.userAgent, + width: window.innerWidth, + height: window.innerHeight, + outerWidth: window.outerWidth, + outerHeight: window.outerHeight + }) + """); + TestContext.WriteLine("S6 (Chromium su Xvfb): " + seen.GetRawText()); + await new HumanGestures(Browser.Cdp, Browser.Clock, new SeededRandom(9)).MoveToAsync(new PagePoint(300, 300)); + TestContext.WriteLine("Fuoco dopo il primo movimento del puntatore: " + (await Browser.Cdp.EvaluateAsync("document.hasFocus()")).GetRawText()); + TestContext.WriteLine("Sandbox disattivata (utente root): " + RealBrowser.IsRoot); + + Assert.IsFalse(seen.GetProperty("webdriver").GetBoolean(), "With a fixed debugging port navigator.webdriver stays false."); + Assert.AreEqual("visible", seen.GetProperty("visibility").GetString()); + Assert.IsFalse(seen.GetProperty("hidden").GetBoolean()); + Assert.AreEqual("Europe/Rome", seen.GetProperty("timeZone").GetString(), "The time zone comes from TZ."); + Assert.IsFalse(seen.GetProperty("userAgent").GetString()!.Contains("Headless", StringComparison.OrdinalIgnoreCase)); + } + + [TestMethod] + public void TheDebugPortListensOnLoopbackOnly() + { + Assert.IsTrue(LoopbackPortCheck.IsLoopbackOnly(Browser.Port, out var listeners)); + TestContext.WriteLine("Punti di ascolto della porta di debug: " + string.Join(", ", listeners)); + } + + [TestMethod] + public async Task ForbiddenCommandsAreRejectedAndChangeNothing() + { + await Browser.GoAsync("/ambiente"); + await Assert.ThrowsExactlyAsync(() => Browser.Cdp.SendAsync("Emulation.setTimezoneOverride", new JsonObject { ["timezoneId"] = "America/New_York" })); + await Assert.ThrowsExactlyAsync(() => Browser.Cdp.SendAsync("Network.setUserAgentOverride", new JsonObject { ["userAgent"] = "Febe" })); + await Assert.ThrowsExactlyAsync(() => Browser.Cdp.SendAsync("Network.setExtraHTTPHeaders", new JsonObject { ["headers"] = new JsonObject() })); + await Assert.ThrowsExactlyAsync(() => Browser.Cdp.SendAsync("Page.addScriptToEvaluateOnNewDocument", new JsonObject { ["source"] = "1" })); + await Assert.ThrowsExactlyAsync(() => Browser.Cdp.SendAsync("Fetch.enable")); + await Assert.ThrowsExactlyAsync(() => Browser.Cdp.SendAsync("Target.createTarget", new JsonObject { ["url"] = "about:blank" })); + await Assert.ThrowsExactlyAsync(() => Browser.Cdp.EvaluateAsync("window.scrollBy(0, 500)")); + + Assert.AreEqual("Europe/Rome", await Browser.EvalAsync("Intl.DateTimeFormat().resolvedOptions().timeZone")); + Assert.AreEqual(0, await Browser.EvalAsync("window.scrollY")); + } + + [TestMethod] + public async Task WheelBurstsReallyScrollThePage() + { + await Browser.GoAsync("/lunga"); + Assert.AreEqual(0, await Browser.EvalAsync("window.scrollY")); + var gestures = new HumanGestures(Browser.Cdp, Browser.Clock, new SeededRandom(1)); + + var requested = await gestures.ScrollBurstAsync(); + requested += await gestures.ScrollBurstAsync(); + await Task.Delay(600); + + var scrolled = await Browser.EvalAsync("window.scrollY"); + var wheel = await Browser.Cdp.EvaluateAsync("window.__wheel"); + TestContext.WriteLine($"Pixel chiesti {requested}, pagina scesa di {scrolled}, eventi rotella {wheel.GetRawText()}"); + Assert.IsTrue(scrolled > 200, $"The page scrolled by {scrolled} px."); + Assert.IsTrue(wheel.GetProperty("count").GetInt32() >= 6); + Assert.IsTrue(wheel.GetProperty("trusted").GetBoolean(), "Wheel events are trusted, as real ones."); + + await gestures.ScrollBackAsync(); + await Task.Delay(400); + Assert.IsTrue(await Browser.EvalAsync("window.scrollY") < scrolled, "A scroll back goes up."); + } + + [TestMethod] + public async Task PointerClicksTheButtonFoundThroughTheTargetMap() + { + await Browser.GoAsync("/bottoni"); + var map = TargetMap.Parse(Targets); + var resolver = new TargetResolver(Browser.Cdp, map); + var gestures = new HumanGestures(Browser.Cdp, Browser.Clock, new SeededRandom(2)); + var actions = new TargetActions(resolver, gestures); + + var avanti = await resolver.ResolveAsync("avanti"); + Assert.IsTrue(avanti.Found, avanti.Message); + // The body keeps its default 8 px margin. + Assert.AreEqual(new PageRect(408, 308, 160, 50), avanti.Element!.Rect, "The visible «Avanti», not the hidden one."); + Assert.AreEqual(1, avanti.Matches); + + var click = await actions.ClickAsync("avanti"); + Assert.IsTrue(click.Clicked); + var clicks = await Browser.Cdp.EvaluateAsync("window.__clicks"); + TestContext.WriteLine("Clic registrati dalla pagina: " + clicks.GetRawText()); + var first = clicks.EnumerateArray().Single(); + Assert.AreEqual("b2", first.GetProperty("id").GetString()); + Assert.IsTrue(first.GetProperty("trusted").GetBoolean()); + Assert.AreEqual(click.At!.Value.X, first.GetProperty("x").GetDouble(), 1); + Assert.IsTrue(await Browser.EvalAsync("window.__moves") >= 10, "The pointer travelled: many mousemove events."); + + var covered = await actions.ClickAsync("coperto"); + Assert.IsFalse(covered.Clicked); + Assert.AreEqual(TargetStatus.Obstructed, covered.Lookup.Status); + + var missing = await actions.ClickAsync("inesistente"); + Assert.IsFalse(missing.Clicked); + Assert.AreEqual(TargetStatus.NotFound, missing.Lookup.Status); + + var profile = await resolver.ResolveAsync("profilo", new Dictionary { ["username"] = "alice" }); + Assert.IsTrue(profile.Found, "Link shape /profilo/{username}/ matches."); + Assert.IsFalse((await resolver.ResolveAsync("profilo", new Dictionary { ["username"] = "bob" })).Found); + Assert.IsTrue((await resolver.ResolveAsync("storia", new Dictionary { ["username"] = "alice" })).Found, "Name from content plus link shape."); + + var far = await actions.ClickAsync("lontano", maxScrollBursts: 12); + Assert.IsTrue(far.Clicked, far.Lookup.Message); + Assert.IsTrue(await Browser.EvalAsync("window.scrollY") > 1000, "Wheel bursts brought it into view."); + var ids = (await Browser.Cdp.EvaluateAsync("window.__clicks.map((c) => c.id)")).Deserialize(); + CollectionAssert.AreEqual(new[] { "b2", "b5" }, ids, "Only the two targets were clicked."); + } + + [TestMethod] + public async Task RemoteViewDeliversFramesAndForwardsTyping() + { + await Browser.GoAsync("/animata"); + await using var view = new RemoteViewSession(Browser.Cdp, Browser.Host.UserDriving); + await view.StartAsync(new ScreencastOptions(Quality: 60, MaxWidth: 1280, MaxHeight: 900)); + Assert.IsTrue(Browser.Host.UserIsDriving); + + var frames = new List(); + using (var cts = new CancellationTokenSource(TimeSpan.FromSeconds(15))) + { + await foreach (var frame in view.Screencast.ReadFramesAsync(cts.Token)) + { + frames.Add(frame); + if (frames.Count >= 5) + { + break; + } + } + } + + TestContext.WriteLine($"Fotogrammi: {frames.Count}, primo {frames[0].Jpeg.Length} byte, pagina {frames[0].DeviceWidth}×{frames[0].DeviceHeight}"); + Assert.IsTrue(frames.Count >= 5, "Several frames: each one was acknowledged."); + Assert.IsTrue(frames.All(f => f.Jpeg.Length > 100 && f.Jpeg[0] == 0xFF && f.Jpeg[1] == 0xD8), "JPEG frames."); + + // S4 locally: click into a field through the remote view and type. + await view.NavigateAsync(Browser.Site.Url("/modulo")); + await Browser.Cdp.WaitForLoadAsync(Browser.Clock, TimeSpan.FromSeconds(10)); + await Task.Delay(RealBrowser.SettleAfterLoad); + var field = await new TargetResolver(Browser.Cdp, TargetMap.Parse(Targets)).ResolveAsync("campo"); + Assert.IsTrue(field.Found, field.Message); + var frameNow = view.Screencast.LastFrame!; + var nx = field.Element!.Rect.Center.X / frameNow.DeviceWidth; + var ny = field.Element.Rect.Center.Y / frameNow.DeviceHeight; + await view.MouseAsync(new RemoteMouseEvent(RemoteMouseAction.Move, nx, ny)); + await view.MouseAsync(new RemoteMouseEvent(RemoteMouseAction.Down, nx, ny, RemoteMouseButton.Left)); + await view.MouseAsync(new RemoteMouseEvent(RemoteMouseAction.Up, nx, ny, RemoteMouseButton.Left)); + foreach (var ch in new[] { "C", "i", "a", "o", " ", "è" }) + { + var key = Keyboard.ForText(ch); + await view.KeyAsync(new RemoteKeyEvent(true, key)); + await view.KeyAsync(new RemoteKeyEvent(false, key)); + } + + Assert.AreEqual("Ciao è", await Browser.EvalAsync("document.getElementById('campo').value")); + + await view.StopAsync(); + Assert.IsFalse(Browser.Host.UserIsDriving); + } + + [TestMethod] + public async Task PreviewIsASingleJpegFrame() + { + await Browser.GoAsync("/animata"); + var jpeg = await PagePreview.CaptureAsync(Browser.Cdp, 50); + Assert.IsTrue(jpeg.Length > 1000 && jpeg[0] == 0xFF && jpeg[1] == 0xD8); + } + + [TestMethod] + public async Task DownloadThroughTheBrowserIsIntact() + { + await Browser.GoAsync("/"); + var fetcher = new BrowserFileFetcher(Browser.Cdp, Browser.Hosts); + var target = Path.Combine(Path.GetTempPath(), "febe-scaricamento-" + Guid.NewGuid().ToString("N") + ".tmp"); + try + { + var watch = Stopwatch.StartNew(); + FetchResult result; + await using (var file = File.Create(target)) + { + result = await fetcher.FetchAsync(new Uri(Browser.Site.CdnUrl("/file.bin")), file, null, CancellationToken.None); + } + + watch.Stop(); + TestContext.WriteLine($"Scaricati {result.Bytes} byte in {watch.Elapsed.TotalSeconds:F1} s attraverso il browser."); + Assert.AreEqual(FetchOutcome.Completed, result.Outcome, result.Error); + Assert.AreEqual(LocalTestSite.BigFileBytes, result.Bytes); + await using var read = File.OpenRead(target); + Assert.AreEqual(LocalTestSite.BigFileSha256, Convert.ToHexString(await SHA256.HashDataAsync(read)), "SHA-256 matches: the file is intact."); + + var site = await fetcher.FetchAsync(new Uri(Browser.Site.Url("/api/dati.json")), Stream.Null, null, CancellationToken.None); + Assert.AreEqual(FetchOutcome.HostNotAllowed, site.Outcome, "Only CDN addresses are downloaded."); + + var missing = await fetcher.FetchAsync(new Uri(Browser.Site.CdnUrl("/manca.bin")), Stream.Null, null, CancellationToken.None); + Assert.AreEqual(FetchOutcome.HttpError, missing.Outcome); + Assert.AreEqual(404, missing.HttpStatus); + } + finally + { + File.Delete(target); + } + } + + [TestMethod] + public async Task ResponseTapDeliversJsonBodies() + { + var consumer = new Collector(); + await using var tap = new ResponseTap(Browser.Cdp, Browser.Hosts, Browser.Clock); + tap.AddConsumer(consumer); + await tap.StartAsync(); + + await Browser.GoAsync("/cattura"); + await WaitUntilAsync(() => consumer.Bodies.Any(b => b.Response.Path == "/api/dati.json")); + + var (response, json) = consumer.Bodies.First(b => b.Response.Path == "/api/dati.json"); + Assert.AreEqual(HostKind.Site, response.HostKind); + Assert.AreEqual(200, response.Status); + Assert.AreEqual("application/json", response.MimeType); + using var doc = JsonDocument.Parse(json); + Assert.AreEqual("mondo", doc.RootElement.GetProperty("elementi")[1].GetProperty("testo").GetString()); + Assert.IsTrue(tap.Stats.JsonBodies >= 1); + } + + [TestMethod] + public async Task StopSignalsComeFromStatusAndNavigation() + { + var breaker = new RecordingBreaker(); + var detector = new SignalDetector(SignalRules.LoadTestSite(), breaker, Browser.Clock); + await using var tap = new ResponseTap(Browser.Cdp, Browser.Hosts, Browser.Clock); + tap.AddObserver(detector); + tap.AddConsumer(detector); + await tap.StartAsync(); + + await Browser.GoAsync("/cattura-429"); + await WaitUntilAsync(() => breaker.Signals.Any(s => s.Code == "http-429")); + var throttle = breaker.Signals.First(s => s.Code == "http-429"); + Assert.AreEqual(SignalLevel.Throttle, throttle.Level); + Assert.AreEqual(Browser.Site.Url("/api/troppe"), throttle.Url); + + await Browser.GoAsync("/vai-a-verifica"); + await WaitUntilAsync(() => breaker.Signals.Any(s => s.Code == "challenge-url")); + var challenge = breaker.Signals.First(s => s.Code == "challenge-url"); + Assert.AreEqual(SignalLevel.Challenge, challenge.Level); + Assert.AreEqual(Browser.Site.Url("/verifica"), challenge.Url, "Address without query string."); + + await Browser.GoAsync("/accesso"); + await WaitUntilAsync(() => breaker.Signals.Any(s => s.Code == "login-url")); + Assert.AreEqual(SignalLevel.Disconnect, breaker.Signals.First(s => s.Code == "login-url").Level); + + await Browser.GoAsync("/cattura-attendi"); + await WaitUntilAsync(() => breaker.Signals.Any(s => s.Code == "wait-text")); + + TestContext.WriteLine("Segnali: " + string.Join(", ", breaker.Signals.Select(s => $"{s.Level}/{s.Code}"))); + Assert.AreEqual(4, breaker.Signals.Select(s => s.Code).Distinct().Count()); + } + + [TestMethod] + public async Task ARouteChangeInsideTheAppIsSeenToo() + { + var breaker = new RecordingBreaker(); + var detector = new SignalDetector(SignalRules.LoadTestSite(), breaker, Browser.Clock); + await using var tap = new ResponseTap(Browser.Cdp, Browser.Hosts, Browser.Clock); + tap.AddObserver(detector); + await tap.StartAsync(); + + await Browser.GoAsync("/spa"); + await WaitUntilAsync(() => breaker.Signals.Any(s => s.Code == "challenge-url")); + Assert.AreEqual(Browser.Site.Url("/verifica/interna"), breaker.Signals.Single().Url, "history.pushState to a verification page is a signal."); + } + + [TestMethod] + public async Task SessionCookieCheckOnlyTellsWhetherItExists() + { + await Browser.GoAsync("/cookie"); + var site = Browser.Site.Url("/"); + Assert.IsTrue(await SessionCookieProbe.HasSessionCookieAsync(Browser.Cdp, new SessionCookieOptions("sessionid", site))); + Assert.IsFalse(await SessionCookieProbe.HasSessionCookieAsync(Browser.Cdp, new SessionCookieOptions("altro", site))); + Assert.IsFalse(Browser.Log.Any(l => l.Contains("valore-finto", StringComparison.Ordinal)), "The value never reaches the log."); + } + + [TestMethod] + public async Task RestLeavesTheBrowserOnTheBlankPage() + { + await Browser.GoAsync("/ambiente"); + await Browser.Host.RestAsync(); + await Browser.Cdp.WaitForLoadAsync(Browser.Clock, TimeSpan.FromSeconds(5)); + Assert.AreEqual("about:blank", await Browser.Cdp.GetMainFrameUrlAsync()); + } + + private static async Task WaitUntilAsync(Func condition, int seconds = 10) + { + var watch = Stopwatch.StartNew(); + while (!condition() && watch.Elapsed < TimeSpan.FromSeconds(seconds)) + { + await Task.Delay(50); + } + + Assert.IsTrue(condition(), "Condition not reached in time."); + } + + private sealed class Collector : IResponseConsumer + { + public ConcurrentQueue<(ResponseDescriptor Response, string Json)> Bodies { get; } = new(); + + public ValueTask ConsumeAsync(ResponseDescriptor response, JsonDocument body, CancellationToken ct) + { + Bodies.Enqueue((response, body.RootElement.GetRawText())); + return ValueTask.CompletedTask; + } + } +} diff --git a/tests/Febe.Tests/Browser/BrowserLifecycleTests.cs b/tests/Febe.Tests/Browser/BrowserLifecycleTests.cs new file mode 100644 index 0000000..8558731 --- /dev/null +++ b/tests/Febe.Tests/Browser/BrowserLifecycleTests.cs @@ -0,0 +1,150 @@ +using System.Collections.Concurrent; +using System.Diagnostics; +using System.Text.Json; +using Febe.Browser.Capture; +using Febe.Browser.Cdp; +using Febe.Browser.Hosting; +using Febe.Core.Collection; +using Febe.Tests.Browser.TestSupport; + +namespace Febe.Tests.Browser; + +/// Supervision of the real browser: crash and restart, clean stop, session kept in the profile. +[TestClass] +[DoNotParallelize] +public sealed class BrowserLifecycleTests +{ + public TestContext TestContext { get; set; } = null!; + + [TestInitialize] + public void RequireBrowser() + { + if (RealBrowser.UnavailableReason() is { } reason) + { + Assert.Inconclusive(reason); + } + } + + [TestMethod] + public async Task AfterACrashChromiumRestartsAndSubscriptionsSurvive() + { + await using var browser = await RealBrowser.StartAsync(); + var reconnected = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + browser.Host.Connection.Reconnected += (_, _) => reconnected.TrySetResult(); + + var consumer = new Collector(); + await using var tap = new ResponseTap(browser.Cdp, browser.Hosts, browser.Clock); + tap.AddConsumer(consumer); + await tap.StartAsync(); + + var firstPid = browser.Host.ProcessId; + browser.Host.KillForRestart(); + await reconnected.Task.WaitAsync(TimeSpan.FromSeconds(30)); + var watch = Stopwatch.StartNew(); + while (browser.Host.Restarts == 0 && watch.Elapsed < TimeSpan.FromSeconds(10)) + { + await Task.Delay(20); + } + + Assert.AreEqual(1, browser.Host.Restarts, "The supervisor restarted the process (not just the connection)."); + Assert.AreNotEqual(firstPid, browser.Host.ProcessId); + Assert.AreEqual(SupervisedState.Running, browser.Host.State); + Assert.AreEqual(2, (await browser.Cdp.EvaluateAsync("1 + 1")).GetInt32(), "The same session object works after the restart."); + Assert.IsTrue(LoopbackPortCheck.IsLoopbackOnly(browser.Port, out _)); + + // The tap subscribed before the crash: it re-enabled the Network domain by itself. + await browser.GoAsync("/cattura"); + watch.Restart(); + while (!consumer.Paths.Contains("/api/dati.json") && watch.Elapsed < TimeSpan.FromSeconds(10)) + { + await Task.Delay(50); + } + + Assert.IsTrue(consumer.Paths.Contains("/api/dati.json"), "Responses are captured after the restart."); + TestContext.WriteLine(string.Join(Environment.NewLine, browser.Log)); + } + + [TestMethod] + public async Task TheSessionCookieSurvivesACleanRestartOfTheBrowser() + { + var profile = Path.Combine(Path.GetTempPath(), "febe-profilo-" + Guid.NewGuid().ToString("N")); + using var site = new LocalTestSite(); + try + { + var first = await RealBrowser.StartAsync(profile, site); + await first.GoAsync("/cookie"); + var options = new SessionCookieOptions("sessionid", site.Url("/")); + Assert.IsTrue(await SessionCookieProbe.HasSessionCookieAsync(first.Cdp, options)); + var pid = first.Host.ProcessId!.Value; + + var watch = Stopwatch.StartNew(); + await first.StopBrowserAsync(); + TestContext.WriteLine($"Arresto ordinato di Chromium in {watch.Elapsed.TotalSeconds:F1} s."); + Assert.IsFalse(Process.GetProcesses().Any(p => p.Id == pid), "Chromium has exited."); + Assert.AreEqual(SupervisedState.Stopped, first.Host.State); + + await using var second = await RealBrowser.StartAsync(profile, site); + Assert.IsTrue(await SessionCookieProbe.HasSessionCookieAsync(second.Cdp, options), "The cookie written before the stop is still in the profile."); + Assert.AreEqual("about:blank", await second.Cdp.GetMainFrameUrlAsync(), "A restart opens the rest page, not the last site page."); + } + finally + { + RealBrowser.TryDelete(profile); + } + } + + [TestMethod] + public async Task XvfbIsRestartedWhenItDies() + { + var display = XvfbProcess.FindFreeDisplay(100, 199)!; + await using var xvfb = new XvfbProcess(display, 800, 600, restart: new RestartPolicy(TimeSpan.FromMilliseconds(200), TimeSpan.FromSeconds(2), TimeSpan.FromMinutes(1))); + var restarted = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + xvfb.Restarted += (_, _) => restarted.TrySetResult(); + await xvfb.StartAsync(CancellationToken.None); + Assert.IsTrue(File.Exists(xvfb.SocketPath)); + var pid = xvfb.ProcessId!.Value; + + using (var process = Process.GetProcessById(pid)) + { + process.Kill(); + } + + await restarted.Task.WaitAsync(TimeSpan.FromSeconds(20)); + Assert.AreNotEqual(pid, xvfb.ProcessId); + Assert.AreEqual(SupervisedState.Running, xvfb.State); + + await xvfb.StopAsync(); + Assert.AreEqual(SupervisedState.Stopped, xvfb.State); + Assert.IsFalse(File.Exists(xvfb.SocketPath), "A polite stop removes the X socket."); + } + + [TestMethod] + public async Task APortAlreadyInUseIsRefusedBeforeLaunching() + { + var listener = new System.Net.Sockets.TcpListener(System.Net.IPAddress.Loopback, 0); + listener.Start(); + try + { + var port = ((System.Net.IPEndPoint)listener.LocalEndpoint).Port; + await using var host = new ChromiumProcessHost(new ChromiumLaunchOptions { NoSandbox = RealBrowser.IsRoot }); + var options = new Febe.Core.Abstractions.BrowserOptions(Path.Combine(Path.GetTempPath(), "febe-non-usato"), DebugPort: port, ExecutablePath: RealBrowser.ChromiumPath()); + var ex = await Assert.ThrowsExactlyAsync(() => host.StartAsync(options, CancellationToken.None)); + StringAssert.Contains(ex.Message, "già occupata"); + } + finally + { + listener.Stop(); + } + } + + private sealed class Collector : IResponseConsumer + { + public ConcurrentBag Paths { get; } = []; + + public ValueTask ConsumeAsync(ResponseDescriptor response, JsonDocument body, CancellationToken ct) + { + Paths.Add(response.Path); + return ValueTask.CompletedTask; + } + } +} diff --git a/tests/Febe.Tests/Browser/CaptureUnitTests.cs b/tests/Febe.Tests/Browser/CaptureUnitTests.cs new file mode 100644 index 0000000..74edcb7 --- /dev/null +++ b/tests/Febe.Tests/Browser/CaptureUnitTests.cs @@ -0,0 +1,277 @@ +using System.Collections.Concurrent; +using System.Security.Cryptography; +using System.Text; +using System.Text.Json; +using System.Text.Json.Nodes; +using Febe.Browser.Capture; +using Febe.Browser.Download; +using Febe.Browser.Hosting; +using Febe.Browser.RemoteView; +using Febe.Core.Collection; +using Febe.Tests.Browser.TestSupport; + +namespace Febe.Tests.Browser; + +[TestClass] +public sealed class CaptureUnitTests +{ + private static readonly HostClassifier Hosts = new(["127.0.0.1:5000"], ["127.0.0.1:5001"]); + + [TestMethod] + public async Task JsonBodiesReachConsumersWithASanitizedDescriptor() + { + var clock = new VirtualClock(); + var cdp = new FakeCdpSession(clock); + cdp.Responder = (method, p) => method switch + { + "Page.getFrameTree" => new JsonObject { ["frameTree"] = new JsonObject { ["frame"] = new JsonObject { ["id"] = "F1", ["url"] = "about:blank" } } }, + "Network.getResponseBody" when p!["requestId"]!.GetValue() == "r1" => new JsonObject { ["body"] = """{"a":1}""", ["base64Encoded"] = false }, + "Network.getResponseBody" => new JsonObject { ["body"] = Convert.ToBase64String(Encoding.UTF8.GetBytes("""{"b":[2]}""")), ["base64Encoded"] = true }, + _ => null, + }; + var consumer = new CollectingConsumer(); + var observer = new CollectingObserver(); + await using var tap = new ResponseTap(cdp, Hosts, clock); + tap.AddConsumer(consumer); + tap.AddObserver(observer); + await tap.StartAsync(); + + Assert.IsTrue(cdp.Sent.Any(c => c.Method == "Network.enable")); + cdp.Raise("Network.responseReceived", Received("r1", "http://127.0.0.1:5000/api/dati.json?token=segreto", 200, "application/json; charset=utf-8")); + cdp.Raise("Network.loadingFinished", new JsonObject { ["requestId"] = "r1", ["encodedDataLength"] = 7 }); + cdp.Raise("Network.responseReceived", Received("r2", "http://127.0.0.1:5000/api/b", 200, "application/json")); + cdp.Raise("Network.loadingFinished", new JsonObject { ["requestId"] = "r2", ["encodedDataLength"] = 9 }); + cdp.Raise("Network.responseReceived", Received("r3", "http://127.0.0.1:5001/foto.jpg", 200, "image/jpeg")); + cdp.Raise("Network.loadingFinished", new JsonObject { ["requestId"] = "r3", ["encodedDataLength"] = 10 }); + cdp.Raise("Network.responseReceived", Received("r4", "http://127.0.0.1:5000/troppe", 429, "application/json")); + + await WaitUntilAsync(() => consumer.Items.Count == 2); + var first = consumer.Items.Single(i => i.Descriptor.RequestId == "r1"); + Assert.AreEqual("http://127.0.0.1:5000/api/dati.json", first.Descriptor.Url, "No query string."); + Assert.AreEqual(HostKind.Site, first.Descriptor.HostKind); + Assert.AreEqual("application/json", first.Descriptor.MimeType); + Assert.AreEqual("""{"a":1}""", first.Json); + Assert.AreEqual("""{"b":[2]}""", consumer.Items.Single(i => i.Descriptor.RequestId == "r2").Json, "Base64 bodies are decoded."); + + Assert.AreEqual(4, observer.Responses.Count, "Observers see every response, bodies or not."); + Assert.AreEqual(HostKind.Cdn, observer.Responses.Single(r => r.RequestId == "r3").HostKind); + Assert.AreEqual(429, observer.Responses.Single(r => r.RequestId == "r4").Status); + Assert.AreEqual(2, cdp.Sent.Count(c => c.Method == "Network.getResponseBody"), "Only JSON bodies are fetched."); + } + + [TestMethod] + public async Task MainFrameNavigationsAreReported() + { + var clock = new VirtualClock(); + var cdp = new FakeCdpSession(clock); + cdp.Responder = (method, _) => method == "Page.getFrameTree" + ? new JsonObject { ["frameTree"] = new JsonObject { ["frame"] = new JsonObject { ["id"] = "F1", ["url"] = "about:blank" } } } + : null; + var observer = new CollectingObserver(); + await using var tap = new ResponseTap(cdp, Hosts, clock); + tap.AddObserver(observer); + await tap.StartAsync(); + + cdp.Raise("Page.frameNavigated", new JsonObject { ["frame"] = new JsonObject { ["id"] = "F1", ["url"] = "http://127.0.0.1:5000/verifica?da=x" } }); + cdp.Raise("Page.frameNavigated", new JsonObject { ["frame"] = new JsonObject { ["id"] = "F2", ["parentId"] = "F1", ["url"] = "http://127.0.0.1:5000/iframe" } }); + + var navigation = observer.Navigations.Single(); + Assert.AreEqual("/verifica", navigation.Path); + Assert.AreEqual("http://127.0.0.1:5000/verifica", navigation.Url); + Assert.IsFalse(navigation.SameDocument); + + // A single-page route change (history.pushState) is a navigation too. + cdp.Raise("Page.navigatedWithinDocument", new JsonObject { ["frameId"] = "F1", ["url"] = "http://127.0.0.1:5000/accesso/?next=x" }); + cdp.Raise("Page.navigatedWithinDocument", new JsonObject { ["frameId"] = "F2", ["url"] = "http://127.0.0.1:5000/iframe-route" }); + Assert.AreEqual(2, observer.Navigations.Count); + var route = observer.Navigations.Last(); + Assert.IsTrue(route.SameDocument); + Assert.AreEqual("/accesso/", route.Path); + } + + [TestMethod] + public async Task BrowserFetcherStreamsChunksAndClosesTheHandle() + { + var payload = RandomNumberGenerator.GetBytes(300_000); + var offset = 0; + var cdp = new FakeCdpSession(new VirtualClock()); + cdp.Responder = (method, p) => + { + switch (method) + { + case "Page.getFrameTree": + return new JsonObject { ["frameTree"] = new JsonObject { ["frame"] = new JsonObject { ["id"] = "F1", ["url"] = "http://127.0.0.1:5000/" } } }; + case "Network.loadNetworkResource": + Assert.AreEqual("F1", p!["frameId"]!.GetValue()); + return new JsonObject { ["resource"] = new JsonObject { ["success"] = true, ["httpStatusCode"] = 200, ["stream"] = "S1" } }; + case "IO.read": + var size = p!["size"]!.GetValue(); + var take = Math.Min(size, payload.Length - offset); + var chunk = Convert.ToBase64String(payload, offset, take); + offset += take; + return new JsonObject { ["base64Encoded"] = true, ["data"] = chunk, ["eof"] = offset >= payload.Length }; + default: + return null; + } + }; + + var fetcher = new BrowserFileFetcher(cdp, Hosts, options: new BrowserFetchOptions { ChunkBytes = 64 * 1024 }); + using var destination = new MemoryStream(); + var progress = new List(); + var result = await fetcher.FetchAsync(new Uri("http://127.0.0.1:5001/f.bin"), destination, new FetchOptions(Progress: new SyncProgress(progress)), CancellationToken.None); + + Assert.AreEqual(FetchOutcome.Completed, result.Outcome); + Assert.AreEqual(payload.Length, result.Bytes); + CollectionAssert.AreEqual(payload, destination.ToArray()); + Assert.AreEqual(5, cdp.Sent.Count(c => c.Method == "IO.read")); + Assert.AreEqual(1, cdp.Sent.Count(c => c.Method == "IO.close")); + Assert.AreEqual(payload.Length, progress[^1]); + } + + [TestMethod] + public async Task BrowserFetcherRefusesTheSiteAndStopsAtTheSizeLimit() + { + var cdp = new FakeCdpSession(new VirtualClock()); + cdp.Responder = (method, _) => method switch + { + "Page.getFrameTree" => new JsonObject { ["frameTree"] = new JsonObject { ["frame"] = new JsonObject { ["id"] = "F1" } } }, + "Network.loadNetworkResource" => new JsonObject { ["resource"] = new JsonObject { ["success"] = true, ["httpStatusCode"] = 200, ["stream"] = "S1" } }, + "IO.read" => new JsonObject { ["data"] = Convert.ToBase64String(new byte[10_000]), ["base64Encoded"] = true, ["eof"] = false }, + _ => null, + }; + var fetcher = new BrowserFileFetcher(cdp, Hosts); + + var refused = await fetcher.FetchAsync(new Uri("http://127.0.0.1:5000/api"), Stream.Null, null, CancellationToken.None); + Assert.AreEqual(FetchOutcome.HostNotAllowed, refused.Outcome); + Assert.AreEqual(0, cdp.Sent.Count, "Nothing is sent for an address outside the CDN."); + + using var destination = new MemoryStream(); + var tooLarge = await fetcher.FetchAsync(new Uri("http://127.0.0.1:5001/big"), destination, new FetchOptions(MaxBytes: 25_000), CancellationToken.None); + Assert.AreEqual(FetchOutcome.TooLarge, tooLarge.Outcome); + Assert.AreEqual(25_000, destination.Length); + Assert.AreEqual(1, cdp.Sent.Count(c => c.Method == "IO.close"), "The stream is closed even when stopping early."); + } + + [TestMethod] + public async Task BrowserFetcherReportsHttpErrors() + { + var cdp = new FakeCdpSession(new VirtualClock()); + cdp.Responder = (method, _) => method switch + { + "Page.getFrameTree" => new JsonObject { ["frameTree"] = new JsonObject { ["frame"] = new JsonObject { ["id"] = "F1" } } }, + "Network.loadNetworkResource" => new JsonObject { ["resource"] = new JsonObject { ["success"] = false, ["httpStatusCode"] = 403, ["netErrorName"] = "net::ERR_HTTP_RESPONSE_CODE_FAILURE" } }, + _ => null, + }; + var result = await new BrowserFileFetcher(cdp, Hosts).FetchAsync(new Uri("http://127.0.0.1:5001/scaduto.jpg"), Stream.Null, null, CancellationToken.None); + Assert.AreEqual(FetchOutcome.HttpError, result.Outcome); + Assert.AreEqual(403, result.HttpStatus); + Assert.IsFalse(result.Error!.Contains("5001", StringComparison.Ordinal), "Errors never carry the address."); + } + + [TestMethod] + public async Task ScreencastAcknowledgesEveryFrameAndDeliversIt() + { + var cdp = new FakeCdpSession(new VirtualClock()); + await using var screencast = new ScreencastSession(cdp); + await screencast.StartAsync(new ScreencastOptions(Quality: 50, MaxWidth: 800, MaxHeight: 600, EveryNthFrame: 2)); + + var start = cdp.Sent.Single(c => c.Method == "Page.startScreencast").Parameters!; + Assert.AreEqual("jpeg", start["format"]!.GetValue()); + Assert.AreEqual(2, start["everyNthFrame"]!.GetValue()); + + var jpeg = new byte[] { 0xFF, 0xD8, 0xFF, 0xD9 }; + cdp.Raise("Page.screencastFrame", new JsonObject + { + ["sessionId"] = 7, + ["data"] = Convert.ToBase64String(jpeg), + ["metadata"] = new JsonObject { ["deviceWidth"] = 1280, ["deviceHeight"] = 900, ["pageScaleFactor"] = 1, ["offsetTop"] = 0, ["scrollOffsetX"] = 0, ["scrollOffsetY"] = 120 }, + }); + + using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5)); + await using var frames = screencast.ReadFramesAsync(cts.Token).GetAsyncEnumerator(cts.Token); + Assert.IsTrue(await frames.MoveNextAsync()); + CollectionAssert.AreEqual(jpeg, frames.Current.Jpeg); + Assert.AreEqual(120, frames.Current.ScrollOffsetY); + await WaitUntilAsync(() => cdp.Sent.Any(c => c.Method == "Page.screencastFrameAck" && c.Parameters!["sessionId"]!.GetValue() == 7)); + + await screencast.StopAsync(); + Assert.AreEqual(1, cdp.Sent.Count(c => c.Method == "Page.stopScreencast")); + } + + [TestMethod] + public async Task RemoteViewHoldsTheDrivingLeaseAndMapsCoordinates() + { + var cdp = new FakeCdpSession(new VirtualClock()); + var gate = new UserDrivingGate(); + await using var view = new RemoteViewSession(cdp, gate); + await Assert.ThrowsExactlyAsync(() => view.MouseAsync(new RemoteMouseEvent(RemoteMouseAction.Move, 0.5, 0.5))); + + await view.StartAsync(); + Assert.IsTrue(gate.IsDriving, "The engine stays still while Alberto uses the remote view."); + cdp.Raise("Page.screencastFrame", new JsonObject + { + ["sessionId"] = 1, + ["data"] = Convert.ToBase64String([1, 2, 3]), + ["metadata"] = new JsonObject { ["deviceWidth"] = 1000, ["deviceHeight"] = 800, ["pageScaleFactor"] = 1 }, + }); + + await view.MouseAsync(new RemoteMouseEvent(RemoteMouseAction.Down, 0.25, 0.5, RemoteMouseButton.Left)); + var press = cdp.Mouse("mousePressed").Single(); + Assert.AreEqual(250, press.X); + Assert.AreEqual(400, press.Y); + Assert.AreEqual(1, press.Parameters!["buttons"]!.GetValue()); + + await view.KeyAsync(new RemoteKeyEvent(true, Febe.Browser.Gestures.Keyboard.ForText("a"))); + Assert.AreEqual("keyDown", cdp.Sent.Last(c => c.Method == "Input.dispatchKeyEvent").Type); + Assert.AreEqual("RemoteKeyEvent(…)", new RemoteKeyEvent(true, Febe.Browser.Gestures.Keyboard.ForText("p")).ToString()); + + await view.StopAsync(); + Assert.IsFalse(gate.IsDriving); + } + + private static JsonObject Received(string id, string url, int status, string mime) => new() + { + ["requestId"] = id, + ["loaderId"] = "L1", + ["frameId"] = "F1", + ["type"] = "Fetch", + ["response"] = new JsonObject { ["url"] = url, ["status"] = status, ["mimeType"] = mime }, + }; + + private static async Task WaitUntilAsync(Func condition) + { + for (var i = 0; i < 300 && !condition(); i++) + { + await Task.Delay(10); + } + + Assert.IsTrue(condition(), "Condition not reached in time."); + } + + private sealed class CollectingConsumer : IResponseConsumer + { + public ConcurrentBag<(ResponseDescriptor Descriptor, string Json)> Items { get; } = []; + + public ValueTask ConsumeAsync(ResponseDescriptor response, JsonDocument body, CancellationToken ct) + { + Items.Add((response, body.RootElement.GetRawText())); + return ValueTask.CompletedTask; + } + } + + private sealed class CollectingObserver : IResponseObserver + { + public ConcurrentQueue Responses { get; } = new(); + + public ConcurrentQueue Navigations { get; } = new(); + + public void OnResponse(ResponseDescriptor response) => Responses.Enqueue(response); + + public void OnNavigation(NavigationDescriptor navigation) => Navigations.Enqueue(navigation); + } + + private sealed class SyncProgress(List values) : IProgress + { + public void Report(long value) => values.Add(value); + } +} diff --git a/tests/Febe.Tests/Browser/CdpClientTests.cs b/tests/Febe.Tests/Browser/CdpClientTests.cs new file mode 100644 index 0000000..34480a0 --- /dev/null +++ b/tests/Febe.Tests/Browser/CdpClientTests.cs @@ -0,0 +1,246 @@ +using System.Collections.Concurrent; +using System.Net; +using System.Net.Sockets; +using System.Net.WebSockets; +using System.Text; +using System.Text.Json; +using System.Text.Json.Nodes; +using Febe.Browser.Cdp; +using Febe.Browser.Diagnostics; + +namespace Febe.Tests.Browser; + +/// The CDP client against a scripted WebSocket peer on a loopback TCP pair (no browser). +[TestClass] +public sealed class CdpClientTests +{ + [TestMethod] + public async Task AnswersAreMatchedByIdEvenOutOfOrder() + { + await using var pair = await SocketPair.CreateAsync(); + var first = pair.Client.SendAsync("Page.getFrameTree"); + var second = pair.Client.SendAsync("Runtime.evaluate", new JsonObject { ["expression"] = "1+1" }); + + var a = await pair.ReceiveAsync(); + var b = await pair.ReceiveAsync(); + await pair.SendAsync(new JsonObject { ["id"] = b["id"]!.GetValue(), ["result"] = new JsonObject { ["who"] = "second" } }); + await pair.SendAsync(new JsonObject { ["id"] = a["id"]!.GetValue(), ["result"] = new JsonObject { ["who"] = "first" } }); + + Assert.AreEqual("first", (await first).GetProperty("who").GetString()); + Assert.AreEqual("second", (await second).GetProperty("who").GetString()); + Assert.AreEqual("Page.getFrameTree", a["method"]!.GetValue()); + Assert.AreEqual("1+1", b["params"]!["expression"]!.GetValue()); + } + + [TestMethod] + public async Task ErrorsBecomeCdpCommandExceptions() + { + await using var pair = await SocketPair.CreateAsync(); + var call = pair.Client.SendAsync("Page.navigate", new JsonObject { ["url"] = "about:blank" }); + var request = await pair.ReceiveAsync(); + await pair.SendAsync(new JsonObject + { + ["id"] = request["id"]!.GetValue(), + ["error"] = new JsonObject { ["code"] = -32000, ["message"] = "Cannot navigate" }, + }); + + var ex = await Assert.ThrowsExactlyAsync(() => call); + Assert.AreEqual(-32000, ex.Code); + Assert.AreEqual("Page.navigate", ex.Method); + } + + [TestMethod] + public async Task EventsReachSubscribersUntilTheyUnsubscribe() + { + await using var pair = await SocketPair.CreateAsync(); + var received = new ConcurrentQueue(); + var subscription = pair.Client.On("Page.frameNavigated", p => received.Enqueue(p.GetProperty("frame").GetProperty("url").GetString()!)); + + await pair.SendAsync(new JsonObject { ["method"] = "Page.frameNavigated", ["params"] = new JsonObject { ["frame"] = new JsonObject { ["url"] = "uno" } } }); + await WaitUntilAsync(() => received.Count == 1); + subscription.Dispose(); + await pair.SendAsync(new JsonObject { ["method"] = "Page.frameNavigated", ["params"] = new JsonObject { ["frame"] = new JsonObject { ["url"] = "due" } } }); + + // A round trip proves the second event was processed before we look. + var ping = pair.Client.SendAsync("Page.enable"); + var request = await pair.ReceiveAsync(); + await pair.SendAsync(new JsonObject { ["id"] = request["id"]!.GetValue(), ["result"] = new JsonObject() }); + await ping; + + CollectionAssert.AreEqual(new[] { "uno" }, received.ToArray()); + } + + [TestMethod] + public async Task ForbiddenCommandsNeverReachTheSocket() + { + await using var pair = await SocketPair.CreateAsync(); + await Assert.ThrowsExactlyAsync(() => pair.Client.SendAsync("Emulation.setTimezoneOverride", new { timezoneId = "UTC" })); + await Assert.ThrowsExactlyAsync(() => pair.Client.SendAsync("Network.setUserAgentOverride", new { userAgent = "x" })); + await Assert.ThrowsExactlyAsync(() => pair.Client.SendAsync("Runtime.evaluate", new { expression = "document.body.click()" })); + + // The first frame the peer sees is the allowed command sent afterwards. + var allowed = pair.Client.SendAsync("Page.enable"); + var first = await pair.ReceiveAsync(); + Assert.AreEqual("Page.enable", first["method"]!.GetValue()); + await pair.SendAsync(new JsonObject { ["id"] = first["id"]!.GetValue(), ["result"] = new JsonObject() }); + await allowed; + } + + [TestMethod] + public async Task ClosingTheConnectionFailsPendingCallsAndLaterOnes() + { + await using var pair = await SocketPair.CreateAsync(); + var disconnected = new TaskCompletionSource(); + pair.Client.Disconnected += (_, _) => disconnected.TrySetResult(); + var pending = pair.Client.SendAsync("Page.getFrameTree"); + await pair.ReceiveAsync(); + + await pair.CloseServerAsync(); + + await Assert.ThrowsExactlyAsync(() => pending); + await disconnected.Task.WaitAsync(TimeSpan.FromSeconds(5)); + Assert.IsFalse(pair.Client.IsConnected); + await Assert.ThrowsExactlyAsync(() => pair.Client.SendAsync("Page.enable")); + } + + [TestMethod] + public async Task CancellingACallKeepsTheConnectionUsable() + { + await using var pair = await SocketPair.CreateAsync(); + using var cts = new CancellationTokenSource(); + var call = pair.Client.SendAsync("Page.getFrameTree", null, cts.Token); + await pair.ReceiveAsync(); + await cts.CancelAsync(); + await Assert.ThrowsAsync(() => call); + + var next = pair.Client.SendAsync("Page.enable"); + var request = await pair.ReceiveAsync(); + await pair.SendAsync(new JsonObject { ["id"] = request["id"]!.GetValue(), ["result"] = new JsonObject() }); + await next; + Assert.IsTrue(pair.Client.IsConnected); + } + + [TestMethod] + public async Task DisposingFailsPendingCallsAndIsIdempotent() + { + var pair = await SocketPair.CreateAsync(); + var pending = pair.Client.SendAsync("Page.getFrameTree"); + await pair.ReceiveAsync(); + + await pair.Client.DisposeAsync(); + await pair.Client.DisposeAsync(); + + await Assert.ThrowsExactlyAsync(() => pending); + await Assert.ThrowsExactlyAsync(() => pair.Client.SendAsync("Page.enable")); + await pair.DisposeAsync(); + } + + [TestMethod] + public async Task TheLogHoldsCommandNamesOnly() + { + var log = new ConcurrentQueue(); + await using var pair = await SocketPair.CreateAsync(new DelegateBrowserLog((_, message, ex) => log.Enqueue(message + ex?.Message))); + pair.Client.On("Network.responseReceived", _ => throw new InvalidOperationException("boom")); + + var call = pair.Client.SendAsync("Runtime.evaluate", new JsonObject { ["expression"] = "'parola-segreta-1'" }); + var request = await pair.ReceiveAsync(); + await pair.SendAsync(new JsonObject + { + ["method"] = "Network.responseReceived", + ["params"] = new JsonObject { ["response"] = new JsonObject { ["url"] = "https://example.invalid/?token=segreto-2" } }, + }); + await pair.SendAsync(new JsonObject + { + ["id"] = request["id"]!.GetValue(), + ["result"] = new JsonObject { ["result"] = new JsonObject { ["value"] = "valore-segreto-3" } }, + }); + await call; + + var all = string.Join("\n", log); + StringAssert.Contains(all, "Runtime.evaluate"); + Assert.IsFalse(all.Contains("segret", StringComparison.Ordinal), "Parameters, events and results never reach the log."); + } + + private static async Task WaitUntilAsync(Func condition) + { + for (var i = 0; i < 200 && !condition(); i++) + { + await Task.Delay(10); + } + + Assert.IsTrue(condition()); + } + + /// A CdpClient connected to a server-side WebSocket over a loopback TCP connection. + private sealed class SocketPair : IAsyncDisposable + { + private readonly TcpClient _tcpClient; + private readonly TcpClient _tcpServer; + private readonly WebSocket _server; + + private SocketPair(TcpClient tcpClient, TcpClient tcpServer, WebSocket server, CdpClient client) + { + _tcpClient = tcpClient; + _tcpServer = tcpServer; + _server = server; + Client = client; + } + + public CdpClient Client { get; } + + public static async Task CreateAsync(IBrowserLog? log = null) + { + var listener = new TcpListener(IPAddress.Loopback, 0); + listener.Start(); + var tcpClient = new TcpClient(); + var accept = listener.AcceptTcpClientAsync(); + await tcpClient.ConnectAsync(IPAddress.Loopback, ((IPEndPoint)listener.LocalEndpoint).Port); + var tcpServer = await accept; + listener.Stop(); + + var server = WebSocket.CreateFromStream(tcpServer.GetStream(), new WebSocketCreationOptions { IsServer = true }); + var clientSocket = WebSocket.CreateFromStream(tcpClient.GetStream(), new WebSocketCreationOptions { IsServer = false }); + var client = new CdpClient(clientSocket, log, new CdpClientOptions(TimeSpan.FromSeconds(10))); + return new SocketPair(tcpClient, tcpServer, server, client); + } + + public async Task ReceiveAsync() + { + using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(5)); + var buffer = new byte[64 * 1024]; + using var message = new MemoryStream(); + WebSocketReceiveResult result; + do + { + result = await _server.ReceiveAsync(buffer, timeout.Token); + message.Write(buffer, 0, result.Count); + } + while (!result.EndOfMessage); + + return JsonNode.Parse(message.ToArray())!; + } + + public Task SendAsync(JsonNode message) => + _server.SendAsync(Encoding.UTF8.GetBytes(message.ToJsonString()), WebSocketMessageType.Text, true, CancellationToken.None); + + public async Task CloseServerAsync() + { + using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(2)); + try + { + await _server.CloseOutputAsync(WebSocketCloseStatus.NormalClosure, null, timeout.Token); + } + catch (WebSocketException) + { + } + } + + public async ValueTask DisposeAsync() + { + await Client.DisposeAsync(); + _server.Dispose(); + _tcpClient.Dispose(); + _tcpServer.Dispose(); + } + } +} diff --git a/tests/Febe.Tests/Browser/CdpPolicyTests.cs b/tests/Febe.Tests/Browser/CdpPolicyTests.cs new file mode 100644 index 0000000..6137d6f --- /dev/null +++ b/tests/Febe.Tests/Browser/CdpPolicyTests.cs @@ -0,0 +1,104 @@ +using Febe.Browser.Cdp; +using Febe.Browser.Targets; + +namespace Febe.Tests.Browser; + +[TestClass] +public sealed class CdpPolicyTests +{ + [TestMethod] + public void AllowlistIsExactlyTheTableOfSection61() + { + string[] expected = + [ + "Page.enable", "Page.navigate", "Page.getFrameTree", "Runtime.evaluate", + "Network.enable", "Network.getResponseBody", + "Input.dispatchMouseEvent", "Input.dispatchKeyEvent", + "Network.loadNetworkResource", "IO.read", "IO.close", + "Page.startScreencast", "Page.screencastFrameAck", "Page.stopScreencast", "Page.captureScreenshot", + "Network.getCookies", + ]; + + CollectionAssert.AreEquivalent(expected, CdpCommandPolicy.Allowed.ToArray()); + foreach (var method in expected) + { + CdpCommandPolicy.EnsureAllowed(method); + } + } + + [TestMethod] + [DataRow("Network.setUserAgentOverride")] + [DataRow("Network.setExtraHTTPHeaders")] + [DataRow("Page.addScriptToEvaluateOnNewDocument")] + [DataRow("Emulation.setTimezoneOverride")] + [DataRow("Emulation.setLocaleOverride")] + [DataRow("Emulation.setUserAgentOverride")] + [DataRow("Fetch.enable")] + [DataRow("Fetch.continueRequest")] + public void ForbiddenCommandsAreRefusedExplicitly(string method) + { + Assert.IsTrue(CdpCommandPolicy.IsExplicitlyForbidden(method)); + var ex = Assert.ThrowsExactly(() => CdpCommandPolicy.EnsureAllowed(method)); + Assert.AreEqual(method, ex.Method); + StringAssert.Contains(ex.Message, "vietato"); + } + + [TestMethod] + [DataRow("Target.createTarget")] + [DataRow("Page.reload")] + [DataRow("Input.insertText")] + [DataRow("Runtime.callFunctionOn")] + [DataRow("Storage.getCookies")] + [DataRow("Browser.close")] + public void CommandsOutsideTheAllowlistAreRefused(string method) + { + var ex = Assert.ThrowsExactly(() => CdpCommandPolicy.EnsureAllowed(method)); + StringAssert.Contains(ex.Message, "non è nell'elenco"); + } + + [TestMethod] + [DataRow("document.readyState")] + [DataRow("navigator.webdriver")] + [DataRow("({ w: window.innerWidth, h: window.innerHeight })")] + [DataRow("document.getElementById('campo').value === 'x'")] + [DataRow("location.href")] + [DataRow("Intl.DateTimeFormat().resolvedOptions().timeZone")] + public void ReadOnlyExpressionsPass(string expression) => ReadOnlyScriptGuard.EnsureReadOnly(expression); + + [TestMethod] + [DataRow("document.body.click()")] + [DataRow("window.scrollBy(0, 400)")] + [DataRow("window.scrollTo(0, 0)")] + [DataRow("el.scrollIntoView()")] + [DataRow("input.focus()")] + [DataRow("el.dispatchEvent(new MouseEvent('click'))")] + [DataRow("fetch('/api/v1/feed')")] + [DataRow("new XMLHttpRequest()")] + [DataRow("navigator.sendBeacon('/x')")] + [DataRow("document.cookie")] + [DataRow("localStorage.getItem('x')")] + [DataRow("el.value = 'x'")] + [DataRow("el.innerHTML += 'x'")] + [DataRow("location.href = '/'")] + [DataRow("location = '/'")] + [DataRow("history.pushState({}, '', '/x')")] + [DataRow("Object.defineProperty(navigator, 'webdriver', { get: () => false })")] + [DataRow("navigator.webdriver = false")] + [DataRow("el.remove()")] + [DataRow("document.body.appendChild(x)")] + [DataRow("el.setAttribute('a', 'b')")] + [DataRow("window.open('/x')")] + public void MutatingExpressionsAreRefused(string expression) + { + Assert.IsFalse(ReadOnlyScriptGuard.IsReadOnly(expression)); + Assert.ThrowsExactly(() => ReadOnlyScriptGuard.EnsureReadOnly(expression)); + } + + [TestMethod] + public void TheTargetScriptPassesTheGuard() + { + var spec = new TargetSpec("x", ["button", "link"], "^avanti$", "/{username}/", 0, null); + var expression = TargetResolver.BuildExpression(spec, new Dictionary { ["username"] = "alice" }); + ReadOnlyScriptGuard.EnsureReadOnly(expression); + } +} diff --git a/tests/Febe.Tests/Browser/GestureTests.cs b/tests/Febe.Tests/Browser/GestureTests.cs new file mode 100644 index 0000000..5ca88ce --- /dev/null +++ b/tests/Febe.Tests/Browser/GestureTests.cs @@ -0,0 +1,331 @@ +using System.Text.Json.Nodes; +using Febe.Browser.Gestures; +using Febe.Browser.Targets; +using Febe.Core.Abstractions; +using Febe.Core.Domain; +using Febe.Tests.Browser.TestSupport; + +namespace Febe.Tests.Browser; + +[TestClass] +public sealed class GestureTests +{ + [TestMethod] + public async Task PointerTravelsSmoothlyAlongACurveInHumanTime() + { + for (var seed = 0; seed < 40; seed++) + { + var (gestures, cdp, clock) = Create(seed); + var start = new PagePoint(100, 700); + var target = new PagePoint(900, 200); + await gestures.MoveToAsync(start); + cdp.ClearSent(); + var t0 = clock.Now; + + await gestures.MoveToAsync(target); + + var moves = cdp.Mouse("mouseMoved"); + Assert.IsTrue(moves.All(m => m.Method == "Input.dispatchMouseEvent")); + var duration = (moves[^1].At - t0).TotalMilliseconds; + Assert.IsTrue(duration is >= 250 * 0.85 and <= 900 * 1.15, $"seed {seed}: travel took {duration:F0} ms."); + + var intervals = moves.Zip(moves.Skip(1), (a, b) => (b.At - a.At).TotalMilliseconds).ToArray(); + var medianInterval = intervals.Order().ElementAt(intervals.Length / 2); + Assert.IsTrue(medianInterval is >= 12 and <= 22, $"seed {seed}: about 60 events per second (median {medianInterval:F1} ms)."); + + Assert.AreEqual(target.X, moves[^1].X); + Assert.AreEqual(target.Y, moves[^1].Y); + + // Never a jump: no step longer than a fraction of the distance. + var points = new[] { start }.Concat(moves.Select(m => new PagePoint(m.X, m.Y))).ToArray(); + var steps = points.Zip(points.Skip(1), (a, b) => a.DistanceTo(b)).ToArray(); + var distance = start.DistanceTo(target); + Assert.IsTrue(moves.Count >= 10, $"seed {seed}: only {moves.Count} pointer events."); + Assert.IsTrue(steps.Max() < distance / 5, $"seed {seed}: largest step {steps.Max():F0} px of {distance:F0}."); + + // Eased: the first and last steps are shorter than the steps in the middle. + var middle = steps.Skip(steps.Length / 3).Take(steps.Length / 3).Average(); + Assert.IsTrue(steps[0] < middle && steps[^1] < middle, $"seed {seed}: start and arrival are soft."); + + // Slightly curved: off the straight line, but not by much. + var deviation = points.Max(p => DistanceFromLine(p, start, target)); + Assert.IsTrue(deviation > 1 && deviation < distance * 0.15, $"seed {seed}: bend of {deviation:F1} px."); + } + } + + [TestMethod] + public async Task ClickLandsInTheCentralPartNeverTheExactCentreWithHumanTimings() + { + var box = new PageRect(400, 300, 120, 40); + for (var seed = 0; seed < 200; seed++) + { + var (gestures, cdp, _) = Create(seed); + var at = await gestures.ClickAsync(box); + + var central = new PageRect(box.X + (box.Width * 0.2) - 0.5, box.Y + (box.Height * 0.2) - 0.5, (box.Width * 0.6) + 1, (box.Height * 0.6) + 1); + Assert.IsTrue(central.Contains(at), $"seed {seed}: {at} is outside the central part."); + Assert.AreNotEqual(box.Center, at, $"seed {seed}: exact centre."); + + var events = cdp.Mouse(); + var press = events.Single(e => e.Type == "mousePressed"); + var release = events.Single(e => e.Type == "mouseReleased"); + var lastMove = events.Last(e => e.Type == "mouseMoved"); + Assert.AreEqual("left", press.Parameters!["button"]!.GetValue()); + Assert.AreEqual(at.X, press.X); + Assert.AreEqual(at.Y, press.Y); + + var hover = (press.At - lastMove.At).TotalMilliseconds; + var hold = (release.At - press.At).TotalMilliseconds; + Assert.IsTrue(hover is >= 80 and <= 300, $"seed {seed}: hover {hover:F0} ms."); + Assert.IsTrue(hold is >= 50 and <= 140, $"seed {seed}: press-release {hold:F0} ms."); + Assert.IsTrue(events.IndexOf(press) > events.IndexOf(lastMove) && events.IndexOf(release) == events.Count - 1); + } + } + + [TestMethod] + public async Task ClickOnATinyTargetStaysInside() + { + var box = new PageRect(10, 10, 6, 6); + for (var seed = 0; seed < 100; seed++) + { + var (gestures, _, _) = Create(seed); + var at = await gestures.ClickAsync(box); + Assert.IsTrue(box.Contains(at), $"seed {seed}: {at} outside {box}."); + } + } + + [TestMethod] + public async Task WheelBurstsSlowDown() + { + for (var seed = 0; seed < 100; seed++) + { + var (gestures, cdp, _) = Create(seed); + await gestures.MoveToAsync(new PagePoint(640, 450)); + cdp.ClearSent(); + + var total = await gestures.ScrollBurstAsync(); + + var wheels = cdp.Mouse("mouseWheel"); + Assert.IsTrue(wheels.Count is >= 3 and <= 8, $"seed {seed}: {wheels.Count} events."); + Assert.IsTrue(wheels.All(w => w.DeltaY is >= 80 and <= 140), $"seed {seed}: deltas out of range."); + Assert.IsTrue(wheels.Zip(wheels.Skip(1), (a, b) => b.DeltaY <= a.DeltaY).All(x => x), "Deltas shrink."); + var intervals = wheels.Zip(wheels.Skip(1), (a, b) => (b.At - a.At).TotalMilliseconds).ToArray(); + Assert.IsTrue(intervals.All(i => i is >= 12 and <= 40), $"seed {seed}: intervals out of range."); + Assert.IsTrue(intervals.Zip(intervals.Skip(1), (a, b) => b >= a).All(x => x), "Intervals grow."); + Assert.IsTrue(wheels.All(w => w.X == 640 && w.Y == 450), "The wheel turns where the pointer is."); + Assert.AreEqual(wheels.Sum(w => w.DeltaY), total); + } + } + + [TestMethod] + public async Task PausesBetweenBurstsAndReadingPausesFollowTheTable() + { + var (gestures, _, clock) = Create(11); + var readingAt = new List(); + var normal = new List(); + var reading = new List(); + for (var burst = 1; burst <= 400; burst++) + { + var before = clock.Now; + if (await gestures.PauseAfterBurstAsync()) + { + readingAt.Add(burst); + reading.Add((clock.Now - before).TotalSeconds); + } + else + { + normal.Add((clock.Now - before).TotalSeconds); + } + } + + var gaps = readingAt.Zip(readingAt.Skip(1), (a, b) => b - a).ToArray(); + Assert.IsTrue(gaps.All(g => g is >= 6 and <= 10), "A reading pause every 6–10 bursts."); + Assert.IsTrue(normal.All(s => s is >= 0.4 and <= 4)); + Assert.AreEqual(1.1, normal.Order().ElementAt(normal.Count / 2), 0.2); + Assert.IsTrue(reading.All(s => s is >= 3 and <= 20)); + } + + [TestMethod] + public async Task ScrollStopsWhenTheRecipeSaysSo() + { + var (gestures, cdp, _) = Create(3); + var calls = 0; + var bursts = await gestures.ScrollAsync(8, _ => ValueTask.FromResult(++calls < 2)); + Assert.AreEqual(2, bursts); + Assert.IsTrue(cdp.Sent.All(c => c.Method == "Input.dispatchMouseEvent"), "Scrolling never uses Runtime.evaluate."); + } + + [TestMethod] + public async Task ScrollingSometimesGoesBackALittle() + { + var (gestures, cdp, _) = Create(5); + await gestures.ScrollAsync(200); + var up = cdp.Mouse("mouseWheel").Where(w => w.DeltaY < 0).ToList(); + Assert.IsTrue(up.Count > 0, "Some small scroll backs happen."); + Assert.IsTrue(up.All(w => w.DeltaY is >= -100 and <= -40)); + } + + [TestMethod] + public async Task WaitAfterLoadHasMedian22Seconds() + { + var (gestures, _, clock) = Create(21); + var waits = new List(); + for (var i = 0; i < 3000; i++) + { + var before = clock.Now; + await gestures.WaitAfterLoadAsync(); + waits.Add((clock.Now - before).TotalSeconds); + } + + Assert.IsTrue(waits.All(w => w is >= 1 and <= 6)); + Assert.AreEqual(2.2, waits.Order().ElementAt(waits.Count / 2), 0.1); + } + + [TestMethod] + public async Task DistractionsHappenAboutEightPercentOfTheTime() + { + var (gestures, _, clock) = Create(31); + var lengths = new List(); + const int Trials = 5000; + for (var i = 0; i < Trials; i++) + { + var before = clock.Now; + if (await gestures.MaybeDistractionAsync()) + { + lengths.Add((clock.Now - before).TotalSeconds); + } + } + + Assert.AreEqual(0.08, lengths.Count / (double)Trials, 0.012); + Assert.IsTrue(lengths.All(l => l is >= 15 and <= 90)); + } + + [TestMethod] + public async Task MoodAndPaceMultiplyEveryWait() + { + var cdp = new FakeCdpSession(new VirtualClock()); + var clock = new VirtualClock(); + var slow = new HumanGestures(cdp, clock, new SeededRandom(1), mood: 1.5, pace: GesturePace.Slow); + Assert.AreEqual(1.5 * 1.35, slow.Multiplier, 1e-9); + for (var i = 0; i < 500; i++) + { + var waited = await slow.WaitAsync(slow.Settings.AfterLoadMs); + Assert.IsTrue(waited.TotalSeconds >= 1 * slow.Multiplier - 1e-6 && waited.TotalSeconds <= 6 * slow.Multiplier + 1e-6); + } + } + + [TestMethod] + public async Task NothingMovesWhileAlbertoIsDriving() + { + var clock = new VirtualClock(); + var cdp = new FakeCdpSession(clock); + var driving = true; + var gestures = new HumanGestures(cdp, clock, new SeededRandom(1), userIsDriving: () => driving); + + await Assert.ThrowsExactlyAsync(() => gestures.ClickAsync(new PageRect(10, 10, 50, 20))); + await Assert.ThrowsExactlyAsync(() => gestures.ScrollBurstAsync()); + Assert.AreEqual(0, cdp.Sent.Count); + + driving = false; + await gestures.ScrollBurstAsync(); + Assert.IsTrue(cdp.Sent.Count > 0); + } + + [TestMethod] + public async Task KeyboardTypesThroughDispatchKeyEvent() + { + var clock = new VirtualClock(); + var cdp = new FakeCdpSession(clock); + await Keyboard.TypeTextAsync(cdp, "Ab è", clock, new SeededRandom(1)); + + Assert.IsTrue(cdp.Sent.All(c => c.Method == "Input.dispatchKeyEvent")); + var downs = cdp.Sent.Where(c => c.Type == "keyDown").Select(c => c.Parameters!["text"]!.GetValue()).ToArray(); + CollectionAssert.AreEqual(new[] { "A", "b", " ", "è" }, downs); + Assert.AreEqual(4, cdp.Sent.Count(c => c.Type == "keyUp")); + + Assert.AreEqual("\r", Keyboard.Special(SpecialKey.Enter).Text); + cdp.ClearSent(); + await Keyboard.KeyDownAsync(cdp, Keyboard.ForText("a") with { Modifiers = KeyModifiers.Control }); + Assert.AreEqual("rawKeyDown", cdp.Sent.Single().Type, "Shortcuts do not insert text."); + Assert.AreEqual("KeyStroke(…)", Keyboard.ForText("x").ToString(), "Keys never print themselves."); + } + + [TestMethod] + public async Task TargetActionsClickOnlyWhatTheMapFinds() + { + var map = TargetMap.Parse("""{ "targets": { "avanti": { "role": "button", "name": "^avanti$" } } }"""); + + // Found and unobstructed: one click inside the element. + var (gestures, cdp, _) = Create(1); + cdp.Responder = (method, _) => method == "Runtime.evaluate" ? Matches((300, 200, 80, 30, true, true, true)) : null; + var result = await new TargetActions(new TargetResolver(cdp, map), gestures).ClickAsync("avanti"); + Assert.IsTrue(result.Clicked); + Assert.IsTrue(new PageRect(300, 200, 80, 30).Contains(result.At!.Value)); + Assert.AreEqual(1, cdp.Mouse("mousePressed").Count); + + // Not found: no input at all, and a clear reason. + (gestures, cdp, _) = Create(2); + cdp.Responder = (method, _) => method == "Runtime.evaluate" ? Matches() : null; + result = await new TargetActions(new TargetResolver(cdp, map), gestures).ClickAsync("avanti"); + Assert.IsFalse(result.Clicked); + Assert.AreEqual(TargetStatus.NotFound, result.Lookup.Status); + StringAssert.Contains(result.Lookup.Message, "non trovato"); + Assert.AreEqual(0, cdp.Mouse().Count); + + // Covered by something else: no click. + (gestures, cdp, _) = Create(3); + cdp.Responder = (method, _) => method == "Runtime.evaluate" ? Matches((300, 200, 80, 30, true, true, false)) : null; + result = await new TargetActions(new TargetResolver(cdp, map), gestures).ClickAsync("avanti"); + Assert.AreEqual(TargetStatus.Obstructed, result.Lookup.Status); + Assert.AreEqual(0, cdp.Mouse("mousePressed").Count); + + // Below the fold: wheel bursts until it is in view, then click. + (gestures, cdp, _) = Create(4); + var lookups = 0; + cdp.Responder = (method, _) => method != "Runtime.evaluate" + ? null + : ++lookups < 3 ? Matches((300, 1500, 80, 30, true, false, false)) : Matches((300, 400, 80, 30, true, true, true)); + result = await new TargetActions(new TargetResolver(cdp, map), gestures).ClickAsync("avanti"); + Assert.IsTrue(result.Clicked); + Assert.IsTrue(cdp.Mouse("mouseWheel").Count >= 6, "Two bursts of at least three events."); + Assert.IsTrue(cdp.Mouse("mouseWheel").All(w => w.DeltaY > 0), "Scrolled down toward the target."); + } + + private static JsonNode Matches(params (double X, double Y, double W, double H, bool Visible, bool InViewport, bool Unobstructed)[] items) => + new JsonObject + { + ["result"] = new JsonObject + { + ["type"] = "object", + ["value"] = new JsonObject + { + ["viewportWidth"] = 1280, + ["viewportHeight"] = 900, + ["matches"] = new JsonArray([.. items.Select(i => (JsonNode)new JsonObject + { + ["x"] = i.X, + ["y"] = i.Y, + ["width"] = i.W, + ["height"] = i.H, + ["visible"] = i.Visible, + ["inViewport"] = i.InViewport, + ["unobstructed"] = i.Unobstructed, + })]), + }, + }, + }; + + private static (HumanGestures Gestures, FakeCdpSession Cdp, VirtualClock Clock) Create(int seed) + { + var clock = new VirtualClock(); + var cdp = new FakeCdpSession(clock); + return (new HumanGestures(cdp, clock, new SeededRandom(seed)), cdp, clock); + } + + private static double DistanceFromLine(PagePoint p, PagePoint a, PagePoint b) + { + var dx = b.X - a.X; + var dy = b.Y - a.Y; + return Math.Abs((dy * p.X) - (dx * p.Y) + (b.X * a.Y) - (b.Y * a.X)) / Math.Sqrt((dx * dx) + (dy * dy)); + } +} diff --git a/tests/Febe.Tests/Browser/HostingTests.cs b/tests/Febe.Tests/Browser/HostingTests.cs new file mode 100644 index 0000000..a44cc66 --- /dev/null +++ b/tests/Febe.Tests/Browser/HostingTests.cs @@ -0,0 +1,151 @@ +using System.Diagnostics; +using Febe.Browser.Hosting; +using Febe.Core.Abstractions; + +namespace Febe.Tests.Browser; + +[TestClass] +public sealed class HostingTests +{ + private static readonly BrowserOptions Options = new("/tmp/febe-profilo", 1280, 900, 9333); + + [TestMethod] + public void CommandLineIsANormalWindowedBrowserWithFixedLoopbackPort() + { + var args = ChromiumCommandLine.Build(Options, new ChromiumLaunchOptions()); + + CollectionAssert.Contains(args.ToList(), "--remote-debugging-port=9333"); + CollectionAssert.Contains(args.ToList(), "--user-data-dir=/tmp/febe-profilo"); + CollectionAssert.Contains(args.ToList(), "--no-first-run"); + CollectionAssert.Contains(args.ToList(), "--no-default-browser-check"); + CollectionAssert.Contains(args.ToList(), "--window-size=1280,900"); + CollectionAssert.Contains(args.ToList(), "--password-store=basic"); + CollectionAssert.Contains(args.ToList(), "--disable-dev-shm-usage"); + Assert.AreEqual("about:blank", args[^1]); + + string[] never = ["--headless", "--enable-automation", "--remote-debugging-pipe", "--user-agent", "--lang", "--no-sandbox", "--proxy-server", "--remote-debugging-address"]; + foreach (var flag in never) + { + Assert.IsFalse(args.Any(a => a.StartsWith(flag, StringComparison.Ordinal)), $"{flag} must not be on the command line."); + } + } + + [TestMethod] + [DataRow(0)] + [DataRow(80)] + [DataRow(70000)] + public void PortZeroOrPrivilegedIsRefused(int port) => + Assert.ThrowsExactly(() => ChromiumCommandLine.Build(Options with { DebugPort = port }, new ChromiumLaunchOptions())); + + [TestMethod] + public void NoSandboxOnlyWhenAskedExplicitly() + { + var args = ChromiumCommandLine.Build(Options, new ChromiumLaunchOptions { NoSandbox = true }); + CollectionAssert.Contains(args.ToList(), "--no-sandbox"); + } + + [TestMethod] + [DataRow("--headless")] + [DataRow("--headless=new")] + [DataRow("--enable-automation")] + [DataRow("--remote-debugging-pipe")] + [DataRow("--remote-debugging-port=0")] + [DataRow("--user-agent=Febe")] + [DataRow("--lang=en-US")] + [DataRow("--proxy-server=socks5://x")] + [DataRow("--disable-blink-features=AutomationControlled")] + [DataRow("--no-sandbox")] + [DataRow("headless")] + public void ForbiddenExtraArgumentsAreRefused(string argument) => + Assert.ThrowsExactly(() => ChromiumCommandLine.Build(Options, new ChromiumLaunchOptions { ExtraArguments = [argument] })); + + [TestMethod] + public void HarmlessExtraArgumentsPass() + { + var args = ChromiumCommandLine.Build(Options, new ChromiumLaunchOptions { ExtraArguments = ["--force-color-profile=srgb"] }); + CollectionAssert.Contains(args.ToList(), "--force-color-profile=srgb"); + } + + [TestMethod] + public void RestartBackoffDoublesUpToTheCap() + { + var policy = new RestartPolicy(TimeSpan.FromSeconds(2), TimeSpan.FromSeconds(30), TimeSpan.FromMinutes(2)); + Assert.AreEqual(TimeSpan.FromSeconds(2), policy.DelayFor(0)); + Assert.AreEqual(TimeSpan.FromSeconds(4), policy.DelayFor(1)); + Assert.AreEqual(TimeSpan.FromSeconds(16), policy.DelayFor(3)); + Assert.AreEqual(TimeSpan.FromSeconds(30), policy.DelayFor(4)); + Assert.AreEqual(TimeSpan.FromSeconds(30), policy.DelayFor(100)); + } + + [TestMethod] + public void UserDrivingGateNestsLeases() + { + var gate = new UserDrivingGate(); + var changes = new List(); + gate.Changed += (_, value) => changes.Add(value); + + var remoteView = gate.Begin(); + var loginPage = gate.Begin(); + Assert.IsTrue(gate.IsDriving); + remoteView.Dispose(); + remoteView.Dispose(); + Assert.IsTrue(gate.IsDriving, "Still driving while the second lease is open."); + loginPage.Dispose(); + Assert.IsFalse(gate.IsDriving); + CollectionAssert.AreEqual(new[] { true, false }, changes); + } + + [TestMethod] + public async Task SupervisorRestartsAProcessThatExitsAndStopsCleanly() + { + if (!OperatingSystem.IsLinux() || !File.Exists("/bin/sleep")) + { + Assert.Inconclusive("Serve /bin/sleep (Linux)."); + } + + var restarted = 0; + await using var supervisor = new SupervisedProcess( + "prova", + () => new ProcessStartInfo("/bin/sleep", "0.2"), + (_, _) => Task.CompletedTask, + new SystemClock(), + policy: new RestartPolicy(TimeSpan.FromMilliseconds(50), TimeSpan.FromMilliseconds(200), TimeSpan.FromMinutes(1))); + supervisor.Restarted += (_, _) => Interlocked.Increment(ref restarted); + + await supervisor.StartAsync(CancellationToken.None); + for (var i = 0; i < 100 && Volatile.Read(ref restarted) < 2; i++) + { + await Task.Delay(50); + } + + Assert.IsTrue(Volatile.Read(ref restarted) >= 2, "The process was restarted after exiting."); + await supervisor.StopAsync(TimeSpan.FromSeconds(2)); + Assert.AreEqual(SupervisedState.Stopped, supervisor.State); + var after = Volatile.Read(ref restarted); + await Task.Delay(600); + Assert.AreEqual(after, Volatile.Read(ref restarted), "No restarts after stop."); + } + + [TestMethod] + public async Task SupervisorEndsALongRunningProcessPolitely() + { + if (!OperatingSystem.IsLinux() || !File.Exists("/bin/sleep")) + { + Assert.Inconclusive("Serve /bin/sleep (Linux)."); + } + + await using var supervisor = new SupervisedProcess( + "prova", + () => new ProcessStartInfo("/bin/sleep", "60"), + (_, _) => Task.CompletedTask, + new SystemClock()); + await supervisor.StartAsync(CancellationToken.None); + var pid = supervisor.ProcessId; + Assert.IsNotNull(pid); + + var watch = Stopwatch.StartNew(); + await supervisor.StopAsync(TimeSpan.FromSeconds(5)); + Assert.IsTrue(watch.Elapsed < TimeSpan.FromSeconds(4), "SIGTERM ends sleep at once; no need to wait for the kill."); + Assert.IsFalse(Process.GetProcesses().Any(p => p.Id == pid && !p.HasExited && p.ProcessName == "sleep")); + } +} diff --git a/tests/Febe.Tests/Browser/TargetMapTests.cs b/tests/Febe.Tests/Browser/TargetMapTests.cs new file mode 100644 index 0000000..9240f68 --- /dev/null +++ b/tests/Febe.Tests/Browser/TargetMapTests.cs @@ -0,0 +1,90 @@ +using System.Text.RegularExpressions; +using Febe.Browser.Targets; + +namespace Febe.Tests.Browser; + +[TestClass] +public sealed class TargetMapTests +{ + private const string Sample = """ + { + "site": "prova", + "note": "Mappa di esempio", + // comments are allowed + "targets": { + "viewer-next": { "role": "button", "name": "^avanti$" }, + "viewer-close": { "role": "button|link", "name": "chiudi", "index": -1 }, + "profile-stories": { "role": "link", "href": "/stories/{username}/", "hypothesis": "H11" }, + "profile-link": { "href": "/{username}/", "index": 2 } + } + } + """; + + [TestMethod] + public void ParsesRolesNamesShapesAndIndexes() + { + var map = TargetMap.Parse(Sample, "bersagli.prova.json"); + + Assert.AreEqual("prova", map.Site); + Assert.AreEqual(4, map.Targets.Count); + CollectionAssert.AreEqual(new[] { "button", "link" }, map.Get("viewer-close").Roles.ToArray()); + Assert.AreEqual(-1, map.Get("viewer-close").Index); + Assert.AreEqual("/stories/{username}/", map.Get("profile-stories").HrefPattern); + Assert.AreEqual("H11", map.Get("profile-stories").Hypothesis); + Assert.AreEqual(2, map.Get("profile-link").Index); + Assert.AreEqual(0, map.Get("profile-link").Roles.Count); + Assert.ThrowsExactly(() => map.Get("non-esiste")); + } + + [TestMethod] + public void LinkShapesBecomeAnchoredPathExpressions() + { + var anyUser = TargetMap.HrefPatternToRegex("/{username}/"); + Assert.AreEqual("^\\/[^/]+\\/$", anyUser); + Assert.IsTrue(Regex.IsMatch("/alice/", anyUser)); + Assert.IsFalse(Regex.IsMatch("/alice/tagged/", anyUser)); + + var alice = TargetMap.HrefPatternToRegex("/{username}/", new Dictionary { ["username"] = "a.lice" }); + Assert.IsTrue(Regex.IsMatch("/a.lice/", alice)); + Assert.IsFalse(Regex.IsMatch("/aXlice/", alice), "Parameter values are escaped."); + + var stories = TargetMap.HrefPatternToRegex("/stories/**"); + Assert.IsTrue(Regex.IsMatch("/stories/alice/123/", stories)); + Assert.IsFalse(Regex.IsMatch("/alice/stories/", stories)); + + var oneSegment = TargetMap.HrefPatternToRegex("/p/*/"); + Assert.IsTrue(Regex.IsMatch("/p/ABC123/", oneSegment)); + Assert.IsFalse(Regex.IsMatch("/p/ABC/123/", oneSegment)); + } + + [TestMethod] + public void NamePatternsTakeEscapedParameters() + { + var expanded = TargetMap.ExpandNamePattern("^foto profilo di {username}$", new Dictionary { ["username"] = "a.b" }); + Assert.IsTrue(Regex.IsMatch("foto profilo di a.b", expanded)); + Assert.IsFalse(Regex.IsMatch("foto profilo di aXb", expanded)); + Assert.AreEqual("^x .+$", TargetMap.ExpandNamePattern("^x {missing}$", null)); + } + + [TestMethod] + [DataRow("""{ "targets": { "a": { "role": "button", "x": 10, "y": 20 } } }""", DisplayName = "Coordinates are refused")] + [DataRow("""{ "targets": { "a": { "role": "button", "selector": ".x1ab2c" } } }""", DisplayName = "Class selectors are refused")] + [DataRow("""{ "targets": { "a": { "index": 1 } } }""", DisplayName = "Role, name or href is required")] + [DataRow("""{ "targets": { "a": { "href": "stories/" } } }""", DisplayName = "href is a path")] + [DataRow("""{ "targets": { "A_b": { "role": "button" } } }""", DisplayName = "Identifiers are kebab-case")] + [DataRow("""{ "targets": { "a": { "name": "([" } } }""", DisplayName = "Invalid name expression")] + [DataRow("""{ "targets": {} }""", DisplayName = "Empty map")] + [DataRow("""{ "targets": """, DisplayName = "Broken JSON")] + public void InvalidMapsAreRefused(string json) => + Assert.ThrowsExactly(() => TargetMap.Parse(json, "bersagli.test.json")); + + [TestMethod] + public void TheExpressionCarriesTheSpecAsJson() + { + var map = TargetMap.Parse(Sample); + var expression = TargetResolver.BuildExpression(map.Get("profile-stories"), new Dictionary { ["username"] = "alice" }); + StringAssert.Contains(expression, "\"roles\":[\"link\"]"); + StringAssert.Contains(expression, "stories"); + Assert.IsFalse(expression.Contains("__SPEC__", StringComparison.Ordinal)); + } +} diff --git a/tests/Febe.Tests/Browser/TestSupport/Fakes.cs b/tests/Febe.Tests/Browser/TestSupport/Fakes.cs new file mode 100644 index 0000000..ad775f9 --- /dev/null +++ b/tests/Febe.Tests/Browser/TestSupport/Fakes.cs @@ -0,0 +1,192 @@ +using System.Text.Json; +using System.Text.Json.Nodes; +using Febe.Core.Abstractions; + +namespace Febe.Tests.Browser.TestSupport; + +/// Virtual clock: advances time instantly, so timing can be asserted without waiting. +public sealed class VirtualClock(DateTimeOffset? start = null) : IClock +{ + private readonly Lock _gate = new(); + private DateTimeOffset _now = start ?? new DateTimeOffset(2026, 10, 13, 9, 0, 0, TimeSpan.Zero); + + public DateTimeOffset Now + { + get + { + lock (_gate) + { + return _now; + } + } + } + + public TimeZoneInfo LocalZone => TimeZoneInfo.Utc; + + public List Delays { get; } = []; + + public Task Delay(TimeSpan time, CancellationToken ct) + { + ct.ThrowIfCancellationRequested(); + lock (_gate) + { + if (time > TimeSpan.Zero) + { + _now += time; + } + + Delays.Add(time); + } + + return Task.CompletedTask; + } + + public void Advance(TimeSpan time) + { + lock (_gate) + { + _now += time; + } + } +} + +/// A command recorded by . +public sealed record SentCommand(string Method, JsonNode? Parameters, DateTimeOffset At) +{ + public string? Type => Parameters?["type"]?.GetValue(); + + public double X => Parameters?["x"]?.GetValue() ?? double.NaN; + + public double Y => Parameters?["y"]?.GetValue() ?? double.NaN; + + public double DeltaY => Parameters?["deltaY"]?.GetValue() ?? 0; +} + +/// Records commands with the virtual time at which they were sent, and answers with canned results. +public sealed class FakeCdpSession(IClock clock) : ICdpSession +{ + private readonly Lock _gate = new(); + private readonly Dictionary>> _handlers = new(StringComparer.Ordinal); + + private readonly List _sent = []; + + /// Snapshot of the commands sent so far (background pumps may add more concurrently). + public IReadOnlyList Sent + { + get + { + lock (_gate) + { + return [.. _sent]; + } + } + } + + public void ClearSent() + { + lock (_gate) + { + _sent.Clear(); + } + } + + /// Returns the result for a command; null means an empty object. + public Func Responder { get; set; } = (_, _) => null; + + public Task SendAsync(string method, object? parameters = null, CancellationToken ct = default) + { + ct.ThrowIfCancellationRequested(); + var node = parameters switch + { + null => null, + JsonNode n => JsonNode.Parse(n.ToJsonString()), + _ => JsonSerializer.SerializeToNode(parameters, parameters.GetType()), + }; + + lock (_gate) + { + _sent.Add(new SentCommand(method, node, clock.Now)); + } + + var result = Responder(method, node) ?? new JsonObject(); + return Task.FromResult(JsonSerializer.Deserialize(result.ToJsonString())); + } + + public IDisposable On(string eventName, Action handler) + { + lock (_gate) + { + if (!_handlers.TryGetValue(eventName, out var list)) + { + list = []; + _handlers[eventName] = list; + } + + list.Add(handler); + } + + return new Unsubscribe(() => + { + lock (_gate) + { + _handlers[eventName].Remove(handler); + } + }); + } + + public void Raise(string eventName, JsonNode payload) + { + Action[] handlers; + lock (_gate) + { + handlers = _handlers.TryGetValue(eventName, out var list) ? [.. list] : []; + } + + var element = JsonSerializer.Deserialize(payload.ToJsonString()); + foreach (var handler in handlers) + { + handler(element); + } + } + + public List Mouse(string? type = null) + { + lock (_gate) + { + return [.. _sent.Where(c => c.Method == "Input.dispatchMouseEvent" && (type is null || c.Type == type))]; + } + } + + private sealed class Unsubscribe(Action action) : IDisposable + { + public void Dispose() => action(); + } +} + +/// Circuit breaker that only records what it receives. +public sealed class RecordingBreaker : ICircuitBreaker +{ + private readonly Lock _gate = new(); + private readonly List _signals = []; + + public BreakerState State => BreakerState.Normal; + + public IReadOnlyList Signals + { + get + { + lock (_gate) + { + return [.. _signals]; + } + } + } + + public void Report(Signal signal) + { + lock (_gate) + { + _signals.Add(signal); + } + } +} diff --git a/tests/Febe.Tests/Browser/TestSupport/LocalTestSite.cs b/tests/Febe.Tests/Browser/TestSupport/LocalTestSite.cs new file mode 100644 index 0000000..4c76bd4 --- /dev/null +++ b/tests/Febe.Tests/Browser/TestSupport/LocalTestSite.cs @@ -0,0 +1,223 @@ +using System.Net; +using System.Net.Sockets; +using System.Security.Cryptography; +using System.Text; + +namespace Febe.Tests.Browser.TestSupport; + +/// +/// Tiny local site served by the test itself on 127.0.0.1 (never Instagram): one port plays the site, another the CDN. +/// +public sealed class LocalTestSite : IDisposable +{ + public const int BigFileBytes = 24 * 1024 * 1024; + + private static readonly Lazy<(byte[] Bytes, string Sha256)> BigFile = new(() => + { + var bytes = new byte[BigFileBytes]; + new Random(20261013).NextBytes(bytes); + return (bytes, Convert.ToHexString(SHA256.HashData(bytes))); + }); + + private readonly HttpListener _listener = new(); + private readonly CancellationTokenSource _stop = new(); + + public LocalTestSite() + { + SitePort = FreePort(); + CdnPort = FreePort(); + _listener.Prefixes.Add($"http://127.0.0.1:{SitePort}/"); + _listener.Prefixes.Add($"http://127.0.0.1:{CdnPort}/"); + _listener.Start(); + _ = Task.Run(LoopAsync); + } + + public int SitePort { get; } + + public int CdnPort { get; } + + public string SiteHost => $"127.0.0.1:{SitePort}"; + + public string CdnHost => $"127.0.0.1:{CdnPort}"; + + public static string BigFileSha256 => BigFile.Value.Sha256; + + public string Url(string path) => $"http://{SiteHost}{path}"; + + public string CdnUrl(string path) => $"http://{CdnHost}{path}"; + + public static int FreePort() + { + var probe = new TcpListener(IPAddress.Loopback, 0); + probe.Start(); + var port = ((IPEndPoint)probe.LocalEndpoint).Port; + probe.Stop(); + return port; + } + + private int _disposed; + + public void Dispose() + { + if (Interlocked.Exchange(ref _disposed, 1) == 1) + { + return; + } + + _stop.Cancel(); + try + { + _listener.Stop(); + _listener.Close(); + } + catch (ObjectDisposedException) + { + } + + _stop.Dispose(); + } + + private async Task LoopAsync() + { + while (!_stop.IsCancellationRequested) + { + HttpListenerContext context; + try + { + context = await _listener.GetContextAsync(); + } + catch (Exception ex) when (ex is HttpListenerException or ObjectDisposedException or InvalidOperationException) + { + return; + } + + _ = Task.Run(() => HandleAsync(context)); + } + } + + private async Task HandleAsync(HttpListenerContext context) + { + var response = context.Response; + try + { + var path = context.Request.Url!.AbsolutePath; + if (context.Request.Url.Port == CdnPort) + { + if (path == "/file.bin") + { + response.ContentType = "application/octet-stream"; + response.ContentLength64 = BigFile.Value.Bytes.Length; + await response.OutputStream.WriteAsync(BigFile.Value.Bytes); + } + else + { + response.StatusCode = 404; + } + + return; + } + + switch (path) + { + case "/api/dati.json": + await JsonAsync(response, 200, """{"elementi":[{"id":"1","testo":"ciao"},{"id":"2","testo":"mondo"}]}"""); + return; + case "/api/troppe": + await JsonAsync(response, 429, """{"messaggio":"troppe richieste"}"""); + return; + case "/api/attendi.json": + await JsonAsync(response, 200, """{"messaggio":"Attendi qualche minuto prima di riprovare."}"""); + return; + case "/vai-a-verifica": + response.StatusCode = 302; + response.RedirectLocation = "/verifica?da=prova"; + return; + case "/cookie": + response.AppendHeader("Set-Cookie", "sessionid=valore-finto-di-prova; Path=/; Max-Age=86400; SameSite=Lax"); + await HtmlAsync(response, "

Cookie impostato

"); + return; + default: + await HtmlAsync(response, Page(path)); + return; + } + } + catch (Exception ex) when (ex is HttpListenerException or IOException or ObjectDisposedException) + { + } + finally + { + try + { + response.Close(); + } + catch (Exception ex) when (ex is HttpListenerException or ObjectDisposedException or InvalidOperationException) + { + } + } + } + + private static string Page(string path) => path switch + { + "/lunga" => string.Concat(Enumerable.Range(1, 300).Select(i => $"

Riga {i} di una pagina lunga.

")) + + "", + "/bottoni" => """ +
+ + + + alice + Storia di alice + +
+ +
+ + """, + "/cattura" => "

Cattura

", + "/cattura-429" => "

Troppe

", + "/cattura-attendi" => "

Attendi

", + "/animata" => """ + +
+ """, + "/modulo" => """ + + + """, + "/spa" => "

Applicazione

", + "/verifica" => "

Verifica

", + "/accesso" => "

Accesso

", + _ => "

Pagina di prova

", + }; + + private static Task HtmlAsync(HttpListenerResponse response, string body) => + WriteAsync(response, 200, "text/html; charset=utf-8", $"Prova{body}"); + + private static Task JsonAsync(HttpListenerResponse response, int status, string json) => + WriteAsync(response, status, "application/json; charset=utf-8", json); + + private static async Task WriteAsync(HttpListenerResponse response, int status, string contentType, string body) + { + var bytes = Encoding.UTF8.GetBytes(body); + response.StatusCode = status; + response.ContentType = contentType; + response.ContentLength64 = bytes.Length; + response.AddHeader("Cache-Control", "no-store"); + await response.OutputStream.WriteAsync(bytes); + } +} diff --git a/tests/Febe.Tests/Browser/TestSupport/RealBrowser.cs b/tests/Febe.Tests/Browser/TestSupport/RealBrowser.cs new file mode 100644 index 0000000..f04b4ac --- /dev/null +++ b/tests/Febe.Tests/Browser/TestSupport/RealBrowser.cs @@ -0,0 +1,198 @@ +using System.Collections.Concurrent; +using System.Text.Json; +using Febe.Browser.Cdp; +using Febe.Browser.Diagnostics; +using Febe.Browser.Hosting; +using Febe.Core.Abstractions; +using Febe.Core.Collection; + +namespace Febe.Tests.Browser.TestSupport; + +/// +/// A real Chromium on a private Xvfb display, driven by , plus a local test site. +/// Integration tests become inconclusive when Chromium or Xvfb is missing. +/// +public sealed class RealBrowser : IAsyncDisposable +{ + /// Chromium of this development environment; FEBE_CHROMIUM overrides it. + private const string KnownChromium = "/opt/pw-browsers/chromium-1194/chrome-linux/chrome"; + + private RealBrowser(XvfbProcess xvfb, ChromiumProcessHost host, LocalTestSite site, string profileDirectory, int port, bool ownsProfile, bool ownsSite, ConcurrentQueue log) + { + Log = log; + OwnsSite = ownsSite; + Xvfb = xvfb; + Host = host; + Site = site; + ProfileDirectory = profileDirectory; + Port = port; + OwnsProfile = ownsProfile; + } + + public XvfbProcess Xvfb { get; } + + public ChromiumProcessHost Host { get; } + + public LocalTestSite Site { get; } + + public string ProfileDirectory { get; } + + public int Port { get; } + + public ICdpSession Cdp => Host.Cdp; + + public IClock Clock { get; } = new SystemClock(); + + public HostClassifier Hosts => new([Site.SiteHost], [Site.CdnHost]); + + public ConcurrentQueue Log { get; } + + private bool OwnsProfile { get; } + + private bool OwnsSite { get; } + + public static bool IsRoot => Environment.UserName == "root"; + + public static string? ChromiumPath() + { + var fromEnv = Environment.GetEnvironmentVariable("FEBE_CHROMIUM"); + if (!string.IsNullOrWhiteSpace(fromEnv) && File.Exists(fromEnv)) + { + return fromEnv; + } + + return File.Exists(KnownChromium) ? KnownChromium : ChromiumCommandLine.FindExecutable(); + } + + public static string? UnavailableReason() + { + if (!OperatingSystem.IsLinux()) + { + return "Le prove con Chromium su Xvfb girano solo su Linux."; + } + + if (ChromiumPath() is null) + { + return "Chromium non trovato (impostare FEBE_CHROMIUM)."; + } + + return XvfbProcess.FindExecutable() is null ? "Xvfb non trovato." : null; + } + + /// Environment of the browser process: Italian language and Rome time zone; no proxy for the test browser. + public static IReadOnlyDictionary BrowserEnvironment => new Dictionary + { + ["LANG"] = "it_IT.UTF-8", + ["TZ"] = "Europe/Rome", + ["LANGUAGE"] = null, + ["LC_ALL"] = null, + ["http_proxy"] = null, + ["https_proxy"] = null, + ["HTTP_PROXY"] = null, + ["HTTPS_PROXY"] = null, + ["ALL_PROXY"] = null, + ["all_proxy"] = null, + ["no_proxy"] = null, + ["NO_PROXY"] = null, + }; + + public static async Task StartAsync(string? profileDirectory = null, LocalTestSite? site = null, RestartPolicy? restart = null) + { + var display = XvfbProcess.FindFreeDisplay(100, 199) ?? throw new InvalidOperationException("Nessun display libero."); + var log = new ConcurrentQueue(); + var browserLog = new DelegateBrowserLog((level, message, ex) => log.Enqueue($"{level}: {message} {ex?.Message}")); + var xvfb = new XvfbProcess(display, 1280, 900, log: browserLog); + await xvfb.StartAsync(CancellationToken.None); + + var ownsProfile = profileDirectory is null; + var profile = profileDirectory ?? Path.Combine(Path.GetTempPath(), "febe-prova-" + Guid.NewGuid().ToString("N")); + var port = LocalTestSite.FreePort(); + var host = new ChromiumProcessHost( + new ChromiumLaunchOptions + { + NoSandbox = IsRoot, + Environment = BrowserEnvironment, + Restart = restart ?? new RestartPolicy(TimeSpan.FromMilliseconds(500), TimeSpan.FromSeconds(5), TimeSpan.FromMinutes(2)), + }, + log: browserLog); + + var testSite = site ?? new LocalTestSite(); + try + { + await host.StartAsync(new BrowserOptions(profile, 1280, 900, port, ChromiumPath(), display), CancellationToken.None); + } + catch + { + await host.DisposeAsync(); + await xvfb.DisposeAsync(); + if (site is null) + { + testSite.Dispose(); + } + + throw; + } + + return new RealBrowser(xvfb, host, testSite, profile, port, ownsProfile, site is null, log); + } + + /// Opens a page of the test site and waits until it has loaded. + public async Task GoAsync(string path) + { + var result = await Cdp.NavigateAsync(Site.Url(path)); + if (!result.Succeeded) + { + throw new InvalidOperationException($"Navigazione fallita: {result.ErrorText}"); + } + + if (!await Cdp.WaitForLoadAsync(Clock, TimeSpan.FromSeconds(15))) + { + throw new TimeoutException("La pagina non ha finito di caricare."); + } + + // Like the post-load wait of the recipes (1–6 s, shortened here): Chromium ignores input that arrives + // right after a navigation, before the page has painted. + await Task.Delay(SettleAfterLoad); + } + + public static TimeSpan SettleAfterLoad { get; } = TimeSpan.FromMilliseconds(500); + + public async Task EvalAsync(string expression) => + (await Cdp.EvaluateAsync(expression)).Deserialize()!; + + /// Stops the browser but keeps the profile and the site (for restart tests). + public async Task StopBrowserAsync() + { + await Host.DisposeAsync(); + await Xvfb.DisposeAsync(); + } + + public async ValueTask DisposeAsync() + { + await Host.DisposeAsync(); + await Xvfb.DisposeAsync(); + if (OwnsSite) + { + Site.Dispose(); + } + + if (OwnsProfile) + { + TryDelete(ProfileDirectory); + } + } + + public static void TryDelete(string directory) + { + try + { + if (Directory.Exists(directory)) + { + Directory.Delete(directory, recursive: true); + } + } + catch (Exception ex) when (ex is IOException or UnauthorizedAccessException) + { + } + } +} diff --git a/tests/Febe.Tests/Collection/SignalTests.cs b/tests/Febe.Tests/Collection/SignalTests.cs new file mode 100644 index 0000000..0287a78 --- /dev/null +++ b/tests/Febe.Tests/Collection/SignalTests.cs @@ -0,0 +1,177 @@ +using System.Text.Json; +using Febe.Core.Abstractions; +using Febe.Core.Collection; +using Febe.Tests.Browser.TestSupport; + +namespace Febe.Tests.Collection; + +[TestClass] +public sealed class SignalTests +{ + [TestMethod] + public void ShippedRulesLoadFromResourcesAndFromTheConfigFolder() + { + var embedded = SignalRules.LoadDefault(); + Assert.IsTrue(embedded.Rules.Any(r => r.Statuses.Contains(429) && r.Level == SignalLevel.Throttle)); + Assert.IsTrue(embedded.Rules.Where(r => r.Path is not null || r.Text is not null).All(r => r.Hypothesis == "H8"), + "Every Instagram-specific pattern is marked as hypothesis H8."); + Assert.IsNotNull(embedded.EmptyPages); + + var onDisk = Path.Combine(AppContext.BaseDirectory, "config", "segnali.json"); + Assert.IsTrue(File.Exists(onDisk), "segnali.json is copied next to the program, editable without recompiling."); + Assert.AreEqual(embedded.Rules.Count, SignalRules.Load(onDisk).Rules.Count); + Assert.AreEqual(embedded.Rules.Count, SignalRules.LoadOrDefault(Path.Combine(AppContext.BaseDirectory, "manca.json")).Rules.Count); + + var testSite = SignalRules.LoadTestSite(); + Assert.IsTrue(File.Exists(Path.Combine(AppContext.BaseDirectory, "config", "segnali.prova.json"))); + Assert.AreEqual(4, testSite.Rules.Count); + } + + [TestMethod] + public void TestSiteSignalsMapToTheRightLevels() + { + var (detector, breaker, clock) = Create(); + + Assert.AreEqual(SignalLevel.Throttle, detector.ObserveResponse(Response("/api/feed", 429))?.Level); + Assert.AreEqual(SignalLevel.Challenge, detector.ObserveNavigation(Navigation("/verifica/"))?.Level); + Assert.AreEqual(SignalLevel.Disconnect, detector.ObserveNavigation(Navigation("/accesso"))?.Level); + + Assert.AreEqual(3, breaker.Signals.Count); + Assert.AreEqual("http-429", breaker.Signals[0].Code); + Assert.AreEqual("http://127.0.0.1:5000/api/feed", breaker.Signals[0].Url, "Address without query string."); + Assert.AreEqual(clock.Now, breaker.Signals[0].At); + } + + [TestMethod] + public void OrdinaryTrafficRaisesNothing() + { + var (detector, breaker, _) = Create(); + Assert.IsNull(detector.ObserveResponse(Response("/api/feed", 200))); + Assert.IsNull(detector.ObserveResponse(Response("/verifica", 200, mainDocument: false)), "Path rules look at navigations and page loads only."); + Assert.IsNull(detector.ObserveNavigation(Navigation("/profilo/verifica-mente/"))); + Assert.IsNull(detector.ObserveResponse(Response("/x", 429, HostKind.Other)), "Third-party hosts are not the site."); + Assert.AreEqual(0, breaker.Signals.Count); + } + + [TestMethod] + public void TheSameSignalIsReportedOncePerWindow() + { + var (detector, breaker, clock) = Create(); + Assert.IsNotNull(detector.ObserveResponse(Response("/a", 429))); + Assert.IsNull(detector.ObserveResponse(Response("/b", 429))); + Assert.IsNotNull(detector.ObserveResponse(Response("/verifica", 200, mainDocument: true)), "Another code is reported."); + clock.Advance(TimeSpan.FromMinutes(2)); + Assert.IsNotNull(detector.ObserveResponse(Response("/c", 429))); + Assert.AreEqual(3, breaker.Signals.Count); + } + + [TestMethod] + public void WaitTextIsFoundOnlyInShortResponses() + { + var (detector, breaker, _) = Create(); + using var shortBody = JsonDocument.Parse("""{ "stato": "errore", "messaggio": "Attendi qualche minuto prima di riprovare." }"""); + Assert.AreEqual(SignalLevel.Throttle, detector.ObserveJsonBody(Response("/api", 200), shortBody.RootElement)?.Level); + + var (detector2, breaker2, _) = Create(); + var caption = "Attendi qualche minuto " + new string('x', 5000); + using var longBody = JsonDocument.Parse(JsonSerializer.Serialize(new { didascalia = caption })); + Assert.IsNull(detector2.ObserveJsonBody(Response("/api", 200), longBody.RootElement), "A long feed with that phrase in a caption is not a signal."); + Assert.AreEqual(1, breaker.Signals.Count); + Assert.AreEqual(0, breaker2.Signals.Count); + } + + [TestMethod] + public void RepeatedEmptyPagesThrottle() + { + var (detector, breaker, _) = Create(); + Assert.IsNull(detector.ObserveEmptyPage()); + Assert.IsNull(detector.ObserveEmptyPage()); + detector.ObserveNonEmptyPage(); + Assert.IsNull(detector.ObserveEmptyPage()); + Assert.IsNull(detector.ObserveEmptyPage()); + Assert.AreEqual("empty-pages", detector.ObserveEmptyPage("http://127.0.0.1:5000/griglia?pagina=3")?.Code); + Assert.AreEqual("http://127.0.0.1:5000/griglia", breaker.Signals.Single().Url); + } + + [TestMethod] + public void MissingSessionCookieIsADisconnection() + { + var (detector, breaker, _) = Create(); + Assert.IsNull(detector.ObserveSessionCookie(true)); + Assert.AreEqual(SignalLevel.Disconnect, detector.ObserveSessionCookie(false)?.Level); + Assert.AreEqual(SignalRules.SessionCookieMissingCode, breaker.Signals.Single().Code); + } + + [TestMethod] + public void InstagramHypothesesMatchTheirPaths() + { + var clock = new VirtualClock(); + var breaker = new RecordingBreaker(); + var detector = new SignalDetector(SignalRules.LoadDefault(), breaker, clock); + NavigationDescriptor Nav(string path) => new(HostKind.Site, "https://www.instagram.com" + path, "www.instagram.com", path, clock.Now); + + Assert.AreEqual(SignalLevel.Challenge, detector.ObserveNavigation(Nav("/challenge/abc/"))?.Level); + Assert.AreEqual(SignalLevel.Disconnect, detector.ObserveNavigation(Nav("/accounts/login/"))?.Level); + Assert.AreEqual(SignalLevel.Challenge, detector.ObserveNavigation(Nav("/accounts/suspended/"))?.Level); + Assert.IsNull(detector.ObserveNavigation(Nav("/challenger_fan/")), "A username that starts like a rule is not a signal."); + } + + [TestMethod] + [DataRow("""{ "rules": [ { "code": "a", "level": "throttle", "status": [429], "path": "^/x" } ] }""", DisplayName = "Two matchers")] + [DataRow("""{ "rules": [ { "code": "a", "level": "boh", "status": [429] } ] }""", DisplayName = "Unknown level")] + [DataRow("""{ "rules": [ { "level": "throttle", "status": [429] } ] }""", DisplayName = "Missing code")] + [DataRow("""{ "rules": [ { "code": "a", "level": "throttle", "path": "([" } ] }""", DisplayName = "Invalid expression")] + [DataRow("""{ "rules": [ { "code": "a", "level": "throttle", "status": [429], "colore": "rosso" } ] }""", DisplayName = "Unknown key")] + [DataRow("""{ "rules": [], "emptyPages": { "code": "e", "level": "throttle", "consecutive": 1 } }""", DisplayName = "Threshold too low")] + public void InvalidRulesAreRefused(string json) => + Assert.ThrowsExactly(() => SignalRules.Parse(json)); + + [TestMethod] + public void ItalianLevelNamesAreAccepted() + { + var rules = SignalRules.Parse("""{ "rules": [ { "code": "a", "level": "Verifica", "path": "^/x" }, { "code": "b", "level": "rallentamento", "status": [503] } ] }"""); + Assert.AreEqual(SignalLevel.Challenge, rules.Rules[0].Level); + Assert.AreEqual(SignalLevel.Throttle, rules.Rules[1].Level); + } + + [TestMethod] + public void HostsAreClassifiedOnDomainBoundaries() + { + var ig = HostClassifier.Instagram; + Assert.AreEqual(HostKind.Site, ig.Classify("https://www.instagram.com/alice/")); + Assert.AreEqual(HostKind.Site, ig.Classify("https://instagram.com/")); + Assert.AreEqual(HostKind.Cdn, ig.Classify("https://scontent-mxp1-1.cdninstagram.com/v/t51/x.jpg?oe=1")); + Assert.AreEqual(HostKind.Cdn, ig.Classify("https://video.fmxp1-1.fna.fbcdn.net/o1/v.mp4")); + Assert.AreEqual(HostKind.Other, ig.Classify("https://evil-instagram.com/")); + Assert.AreEqual(HostKind.Other, ig.Classify("https://instagram.com.evil.example/")); + Assert.AreEqual(HostKind.Other, ig.Classify("about:blank")); + + var local = new HostClassifier(["127.0.0.1:5000"], ["127.0.0.1:5001"]); + Assert.AreEqual(HostKind.Site, local.Classify("http://127.0.0.1:5000/a")); + Assert.AreEqual(HostKind.Cdn, local.Classify("http://127.0.0.1:5001/file.bin")); + Assert.AreEqual(HostKind.Other, local.Classify("http://127.0.0.1:5002/")); + } + + [TestMethod] + public void AddressesLoseQueryFragmentAndCredentials() + { + Assert.AreEqual("https://www.example.org/a/b/", UrlSanitizer.Sanitize("https://user:pw@www.example.org/a/b/?token=x#frag").Url); + Assert.AreEqual("http://127.0.0.1:5000/verifica", UrlSanitizer.Sanitize("http://127.0.0.1:5000/verifica?next=/x").Url); + Assert.AreEqual("about:blank", UrlSanitizer.Sanitize("about:blank").Url); + Assert.AreEqual("data:", UrlSanitizer.Sanitize("data:text/plain;base64,c2VncmV0bw==").Url); + Assert.AreEqual(string.Empty, UrlSanitizer.Sanitize(null).Url); + } + + private static (SignalDetector Detector, RecordingBreaker Breaker, VirtualClock Clock) Create() + { + var clock = new VirtualClock(); + var breaker = new RecordingBreaker(); + return (new SignalDetector(SignalRules.LoadTestSite(), breaker, clock), breaker, clock); + } + + private static ResponseDescriptor Response(string path, int status, HostKind kind = HostKind.Site, bool mainDocument = false) => + new("1", kind, "http://127.0.0.1:5000" + path, "127.0.0.1:5000", path, status, "application/json", mainDocument ? "Document" : "Fetch", mainDocument, DateTimeOffset.UnixEpoch); + + private static NavigationDescriptor Navigation(string path) => + new(HostKind.Site, "http://127.0.0.1:5000" + path, "127.0.0.1:5000", path, DateTimeOffset.UnixEpoch); +} diff --git a/tests/Febe.Tests/Pacing/DistributionsTests.cs b/tests/Febe.Tests/Pacing/DistributionsTests.cs new file mode 100644 index 0000000..1b4b8bc --- /dev/null +++ b/tests/Febe.Tests/Pacing/DistributionsTests.cs @@ -0,0 +1,166 @@ +using Febe.Core.Abstractions; +using Febe.Core.Domain; +using Febe.Core.Pacing; + +namespace Febe.Tests.Pacing; + +[TestClass] +public sealed class DistributionsTests +{ + private const int Samples = 40_000; + + [TestMethod] + public void BoxMullerGivesAStandardNormal() + { + var random = new SeededRandom(1); + var values = Enumerable.Range(0, Samples).Select(_ => random.StandardNormal()).ToArray(); + var mean = values.Average(); + var sd = Math.Sqrt(values.Select(v => (v - mean) * (v - mean)).Average()); + + Assert.AreEqual(0, mean, 0.03); + Assert.AreEqual(1, sd, 0.03); + Assert.IsTrue(values.All(double.IsFinite)); + } + + [TestMethod] + public void BetweenStaysInsideTheIntervalWithGeometricMedian() + { + var random = new SeededRandom(2); + var values = Enumerable.Range(0, Samples).Select(_ => random.Between(1, 100)).Order().ToArray(); + + Assert.IsTrue(values[0] >= 1 && values[^1] <= 100, "Every value must lie in [a, b]."); + Assert.AreEqual(10, Quantile(values, 0.5), 0.5, "Median must be √(a·b)."); + + // σ = ln(b/a)/4; truncation at ±2σ puts the quartiles at about ±0.640σ in log space. + var sigma = Math.Log(100) / 4; + var median = Quantile(values, 0.5); + Assert.AreEqual(0.640 * sigma, Math.Log(Quantile(values, 0.75) / median), 0.05); + Assert.AreEqual(0.640 * sigma, Math.Log(median / Quantile(values, 0.25)), 0.05); + } + + [TestMethod] + public void BetweenHonoursAnExplicitMedianAndIsNotUniform() + { + var random = new SeededRandom(3); + var values = Enumerable.Range(0, Samples).Select(_ => random.Between(1000, 6000, 2200)).Order().ToArray(); + + Assert.IsTrue(values[0] >= 1000 && values[^1] <= 6000); + Assert.AreEqual(2200, Quantile(values, 0.5), 2200 * 0.03); + + // A uniform draw would put 1/5 of the mass in each fifth; the log-normal crowds the lower part. + var lowFifth = values.Count(v => v < 2000) / (double)values.Length; + var highFifth = values.Count(v => v > 5000) / (double)values.Length; + Assert.IsTrue(lowFifth > 0.35, $"Lower fifth holds {lowFifth:P1}."); + Assert.IsTrue(highFifth < 0.05, $"Upper fifth holds {highFifth:P1}."); + } + + [TestMethod] + public void TimeSpanOverloadUsesTheSameDistribution() + { + var random = new SeededRandom(4); + var values = Enumerable.Range(0, 5_000) + .Select(_ => random.Between(TimeSpan.FromSeconds(0.4), TimeSpan.FromSeconds(4), TimeSpan.FromSeconds(1.1)).TotalSeconds) + .Order() + .ToArray(); + + Assert.IsTrue(values[0] >= 0.4 && values[^1] <= 4); + Assert.AreEqual(1.1, Quantile(values, 0.5), 0.06); + } + + [TestMethod] + public void SessionMoodHasMedianOneAndStaysInRange() + { + var random = new SeededRandom(5); + var values = Enumerable.Range(0, Samples).Select(_ => random.SessionMood()).Order().ToArray(); + + Assert.IsTrue(values[0] >= 0.7 && values[^1] <= 1.5); + Assert.AreEqual(1, Quantile(values, 0.5), 0.02); + var logSd = Math.Sqrt(values.Select(v => Math.Log(v) * Math.Log(v)).Average()); + Assert.IsTrue(logSd is > 0.15 and < 0.21, $"σ of ln(mood) is {logSd:F3}."); + Assert.IsTrue(values.Count(v => v < 0.8) > 0 && values.Count(v => v > 1.3) > 0, "Slow and fast sessions both occur."); + } + + [TestMethod] + public void NextCheckJitterHasMedianOneAndStaysInRange() + { + var random = new SeededRandom(6); + var values = Enumerable.Range(0, Samples).Select(_ => random.NextCheckJitter()).Order().ToArray(); + + Assert.IsTrue(values[0] >= 0.6 && values[^1] <= 1.8); + Assert.AreEqual(1, Quantile(values, 0.5), 0.02); + + var interval = TimeSpan.FromHours(3); + var jittered = random.JitteredInterval(interval); + Assert.IsTrue(jittered >= interval * 0.6 && jittered <= interval * 1.8); + } + + [TestMethod] + public void CountBetweenReachesBothEndsAndFavoursTheMiddle() + { + var random = new SeededRandom(7); + var counts = new int[11]; + for (var i = 0; i < Samples; i++) + { + counts[random.CountBetween(3, 8)]++; + } + + Assert.AreEqual(Samples, counts.Skip(3).Take(6).Sum(), "Every value lies in [3, 8]."); + Assert.IsTrue(counts[3] > 0 && counts[8] > 0, "Both ends are reachable."); + Assert.IsTrue(counts[5] > counts[3] && counts[5] > counts[8], "Not uniform: the middle is more frequent."); + } + + [TestMethod] + public void SameSeedSameSequence() + { + var a = new SeededRandom(42); + var b = new SeededRandom(42); + for (var i = 0; i < 100; i++) + { + Assert.AreEqual(a.Between(1, 6, 2.2), b.Between(1, 6, 2.2)); + } + } + + [TestMethod] + public void ChanceMatchesItsProbability() + { + var random = new SeededRandom(8); + var hits = Enumerable.Range(0, Samples).Count(_ => random.Chance(0.08)); + Assert.AreEqual(0.08, hits / (double)Samples, 0.006); + Assert.IsFalse(random.Chance(0)); + } + + [TestMethod] + public void InvalidIntervalsAreRefused() + { + var random = new SeededRandom(9); + Assert.ThrowsExactly(() => random.Between(0, 10)); + Assert.ThrowsExactly(() => random.Between(5, 1)); + Assert.ThrowsExactly(() => random.Between(1, 6, 7)); + Assert.ThrowsExactly(() => random.LogNormal(-1, 0.2)); + Assert.AreEqual(3, random.Between(3, 3)); + } + + [TestMethod] + public void DegenerateSourceFallsBackToTheMedian() + { + // A source that always returns the same value cannot loop forever. + var constant = new ConstantRandom(0.999999); + var value = constant.TruncatedLogNormal(1, 3, 0.9, 1.1); + Assert.IsTrue(value is >= 0.9 and <= 1.1); + } + + [TestMethod] + public void PaceFactorsOrderSlowNaturalBrisk() + { + Assert.AreEqual(1.0, GesturePaceFactors.For(GesturePace.Natural)); + Assert.IsTrue(GesturePaceFactors.For(GesturePace.Slow) > 1.0); + Assert.IsTrue(GesturePaceFactors.For(GesturePace.Brisk) < 1.0); + } + + private static double Quantile(double[] sorted, double q) => sorted[(int)Math.Clamp(q * (sorted.Length - 1), 0, sorted.Length - 1)]; + + private sealed class ConstantRandom(double value) : IRandomSource + { + public double NextDouble() => value; + } +}