Merge branch 'w1/browser' into febe-v1

This commit is contained in:
Claude committed 2026-10-13 16:07:27 +00:00
commit 4f55fbed8e
44 files changed
+8396

No files matched your search

+93
View File
@@ -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=<profilo> --no-first-run \
--no-default-browser-check --password-store=basic --disable-dev-shm-usage --window-size=1280,900 \
--remote-debugging-port=<porta fissa> 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:<porta>`. `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).
+440
View File
@@ -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;
/// <summary>Options of <see cref="ResponseTap"/>.</summary>
public sealed record ResponseTapOptions
{
/// <summary>Bodies larger than this are not fetched (memory guard).</summary>
public long MaxBodyBytes { get; init; } = 32L * 1024 * 1024;
/// <summary>How long to wait for one body before giving up on it (one stuck request must not block the others).</summary>
public TimeSpan BodyTimeout { get; init; } = TimeSpan.FromSeconds(15);
/// <summary>Decides from the declared MIME type whether a body is worth parsing as JSON.</summary>
public Func<string, bool> IsJsonMimeType { get; init; } = static mime => mime.Contains("json", StringComparison.OrdinalIgnoreCase);
/// <summary>Per-resource buffer of the browser (<c>Network.enable</c> maxResourceBufferSize).</summary>
public int BrowserResourceBufferBytes { get; init; } = 32 * 1024 * 1024;
/// <summary>Total buffer of the browser (<c>Network.enable</c> maxTotalBufferSize).</summary>
public int BrowserTotalBufferBytes { get; init; } = 128 * 1024 * 1024;
}
/// <summary>Counters for diagnostics (never contents).</summary>
public sealed record ResponseTapStats(long Responses, long JsonBodies, long BodyErrors, long ParseErrors, long Skipped);
/// <summary>
/// Listens to the responses the page receives (spec §6.2) and hands JSON bodies to <see cref="IResponseConsumer"/>s,
/// and the metadata of every response and main-frame navigation to <see cref="IResponseObserver"/>s.
/// </summary>
/// <remarks>
/// 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.
/// </remarks>
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<string, ResponseDescriptor> _inFlight = new(StringComparer.Ordinal);
private readonly Lock _gate = new();
private readonly List<IResponseConsumer> _consumers = [];
private readonly List<IResponseObserver> _observers = [];
private readonly Channel<ResponseDescriptor> _queue = Channel.CreateUnbounded<ResponseDescriptor>(new UnboundedChannelOptions { SingleReader = true });
private readonly CancellationTokenSource _lifetime = new();
private readonly List<IDisposable> _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();
}
/// <summary>Raised for every main-frame navigation (sanitized address).</summary>
public event EventHandler<NavigationDescriptor>? 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);
}
});
}
/// <summary>Subscribes to the page events and enables the Network domain (again after every reconnection).</summary>
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);
}
/// <summary>
/// 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).
/// </summary>
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<JsonDocument?> 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];
}
}
}
+431
View File
@@ -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;
/// <summary>Options of <see cref="CdpClient"/>.</summary>
/// <param name="CommandTimeout">How long to wait for the answer to a command before giving up.</param>
public sealed record CdpClientOptions(TimeSpan? CommandTimeout = null)
{
public static CdpClientOptions Default { get; } = new();
internal TimeSpan EffectiveTimeout => CommandTimeout ?? TimeSpan.FromSeconds(60);
}
/// <summary>
/// Chrome DevTools Protocol client over a WebSocket (spec §5, §6.1), written by hand on <see cref="ClientWebSocket"/>.
/// </summary>
/// <remarks>
/// <list type="bullet">
/// <item>Only commands of <see cref="CdpCommandPolicy"/> are sent; <c>Runtime.evaluate</c> also passes <see cref="ReadOnlyScriptGuard"/>.</item>
/// <item>The log receives command names only: never parameters, results or event payloads.</item>
/// <item>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.</item>
/// <item>When the connection drops every pending command fails with <see cref="CdpDisconnectedException"/>;
/// a new client is needed (see <see cref="ReconnectingCdpSession"/>). Disposal is idempotent.</item>
/// </list>
/// </remarks>
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<int, Pending> _pending = new();
private readonly Dictionary<string, List<Action<JsonElement>>> _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);
}
/// <summary>True until the connection closes or the client is disposed.</summary>
public bool IsConnected => Volatile.Read(ref _closed) == 0;
/// <summary>Raised once when the connection closes (the argument is the cause, null for a normal close).</summary>
public event EventHandler<Exception?>? Disconnected;
/// <summary>Connects to a DevTools WebSocket on the loopback interface (never through a proxy).</summary>
public static async Task<CdpClient> 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<JsonElement> 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<JsonElement>(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<JsonElement> 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<byte>(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<byte>(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<byte> 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<JsonElement>[] 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<byte> Serialize(int id, string method, JsonNode? parameters)
{
var output = new ArrayBufferWriter<byte>(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<JsonElement> Completion);
}
/// <summary>Disposable that runs an action once.</summary>
internal sealed class Subscription(Action dispose) : IDisposable
{
private Action? _dispose = dispose;
public void Dispose() => Interlocked.Exchange(ref _dispose, null)?.Invoke();
}
/// <summary>Converts command parameters (anonymous objects, dictionaries, JSON nodes or elements) to JSON.</summary>
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<string>(out var s)
? s
: null;
}
+119
View File
@@ -0,0 +1,119 @@
using System.Collections.Frozen;
namespace Febe.Browser.Cdp;
/// <summary>
/// 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.
/// </summary>
public static class CdpCommandPolicy
{
/// <summary>The allowlist of spec §6.1, grouped by purpose.</summary>
public static FrozenSet<string> 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");
/// <summary>Commands explicitly forbidden by spec §2 rule 2 and §6.1, refused with a specific message.</summary>
public static FrozenSet<string> ForbiddenCommands { get; } = FrozenSet.Create(
StringComparer.Ordinal,
"Network.setUserAgentOverride",
"Network.setExtraHTTPHeaders",
"Page.addScriptToEvaluateOnNewDocument");
/// <summary>Whole domains that are forbidden (spec §6.1).</summary>
public static IReadOnlyList<string> 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);
}
/// <summary>Throws <see cref="CdpCommandNotAllowedException"/> unless <paramref name="method"/> is on the allowlist.</summary>
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.");
}
}
}
/// <summary>A CDP command was refused by <see cref="CdpCommandPolicy"/> and never sent.</summary>
public sealed class CdpCommandNotAllowedException(string method, string message) : InvalidOperationException(message)
{
public string Method { get; } = method;
}
/// <summary>The browser answered a command with an error. The message never contains parameters.</summary>
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;
}
/// <summary>The connection to the browser is closed (browser exited, crashed or is restarting).</summary>
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)
{
}
}
+121
View File
@@ -0,0 +1,121 @@
using System.Text.Json;
using System.Text.Json.Nodes;
using Febe.Core.Abstractions;
namespace Febe.Browser.Cdp;
/// <summary>A read-only evaluation threw inside the page.</summary>
public sealed class CdpEvaluationException(string message) : Exception(message);
/// <summary>Result of <c>Page.navigate</c>.</summary>
/// <param name="FrameId">Frame that navigated.</param>
/// <param name="ErrorText">Browser error (e.g. «net::ERR_CONNECTION_REFUSED»), null on success.</param>
public sealed record NavigationResult(string FrameId, string? ErrorText)
{
public bool Succeeded => ErrorText is null;
}
/// <summary>Page-level helpers built only on the commands of spec §6.1.</summary>
public static class CdpPageExtensions
{
/// <summary>The «rest» page (spec §6.1): no site page stays open outside a session.</summary>
public const string RestUrl = "about:blank";
/// <summary>
/// Evaluates a read-only expression and returns its value (by value). The expression passes
/// <see cref="ReadOnlyScriptGuard"/> in the client. Exceptions in the page become <see cref="CdpEvaluationException"/>.
/// </summary>
public static async Task<JsonElement> 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;
}
/// <summary>Identifier of the main frame (needed by <c>Network.loadNetworkResource</c>).</summary>
public static async Task<string> 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.");
}
/// <summary>Address of the main frame (may contain data: never log it unsanitized).</summary>
public static async Task<string> 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;
}
/// <summary><c>Page.navigate</c>. Returns when the navigation commits (not when the page has finished loading).</summary>
public static async Task<NavigationResult> 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);
}
/// <summary>Puts the browser at rest on the blank page (spec §6.1, §7.2).</summary>
public static Task<NavigationResult> RestAsync(this ICdpSession cdp, CancellationToken ct = default) =>
cdp.NavigateAsync(RestUrl, ct);
/// <summary>
/// Waits until <c>document.readyState</c> is «complete» (read-only polling), up to <paramref name="timeout"/>.
/// Returns false on timeout. Uses <paramref name="clock"/> for the pauses between polls.
/// </summary>
public static async Task<bool> 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);
}
}
}
+131
View File
@@ -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;
/// <summary>A DevTools target listed by <c>/json/list</c>. The address may hold data: never log it.</summary>
public sealed record CdpTarget(string Id, string Type, string Url, Uri WebSocketDebuggerUrl);
/// <summary>
/// Finds the page target through the DevTools HTTP endpoint on <c>http://127.0.0.1:&lt;port&gt;</c> (spec §6.1).
/// Only the loopback interface is ever contacted, never through a proxy.
/// </summary>
public static class CdpTargetDiscovery
{
private static readonly HttpClient Http = new(new SocketsHttpHandler
{
UseProxy = false,
ConnectTimeout = TimeSpan.FromSeconds(2),
AllowAutoRedirect = false,
})
{
Timeout = TimeSpan.FromSeconds(5),
};
/// <summary>Base address of the DevTools HTTP endpoint for <paramref name="port"/>.</summary>
public static Uri EndpointFor(int port)
{
ValidatePort(port);
return new Uri($"http://127.0.0.1:{port.ToString(System.Globalization.CultureInfo.InvariantCulture)}/");
}
/// <summary>True when the DevTools endpoint answers <c>/json/version</c>.</summary>
public static async Task<bool> 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;
}
}
/// <summary>Browser version string from <c>/json/version</c> (e.g. «Chrome/141.0.7390.37»), or null.</summary>
public static async Task<string?> 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<IReadOnlyList<CdpTarget>> 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<CdpTarget>();
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;
}
/// <summary>The first target of type «page», or null when the browser has none.</summary>
public static async Task<CdpTarget?> FindPageAsync(int port, CancellationToken ct)
{
var targets = await ListAsync(port, ct).ConfigureAwait(false);
return targets.FirstOrDefault(t => t.Type == "page");
}
/// <summary>Refuses any DevTools address that is not on the loopback interface (and, when given, on the expected port).</summary>
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<TargetDto>), TypeInfoPropertyName = "ListTargetDto")]
[JsonSerializable(typeof(VersionDto))]
internal sealed partial class CdpDiscoveryJsonContext : JsonSerializerContext;
@@ -0,0 +1,48 @@
using System.Text.RegularExpressions;
namespace Febe.Browser.Cdp;
/// <summary>
/// Defense in depth for <c>Runtime.evaluate</c>, 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.
/// </summary>
/// <remarks>
/// 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 <c>Input.*</c> only.
/// </remarks>
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();
}
@@ -0,0 +1,131 @@
using System.Text.Json;
using Febe.Core.Abstractions;
namespace Febe.Browser.Cdp;
/// <summary>Notifies components that the CDP connection was replaced (browser restarted).</summary>
public interface ICdpConnectionEvents
{
/// <summary>
/// Raised after a new connection replaced a lost one. Domain state (<c>Network.enable</c>, a screencast)
/// is lost with the old connection: components re-enable what they need. Not raised for the first connection.
/// </summary>
event EventHandler? Reconnected;
}
/// <summary>Raised by <see cref="ReconnectingCdpSession"/> while no browser connection is available.</summary>
public sealed class BrowserUnavailableException()
: InvalidOperationException("Il browser non è disponibile in questo momento (avvio o riavvio in corso).");
/// <summary>
/// A stable <see cref="ICdpSession"/> on top of a sequence of <see cref="CdpClient"/>s: subscriptions survive
/// browser restarts, and commands fail fast with <see cref="BrowserUnavailableException"/> while detached.
/// </summary>
public sealed class ReconnectingCdpSession : ICdpSession, ICdpConnectionEvents
{
private readonly Lock _gate = new();
private readonly List<Registration> _registrations = [];
private CdpClient? _client;
private bool _everAttached;
public event EventHandler? Reconnected;
public bool IsAttached
{
get
{
lock (_gate)
{
return _client is { IsConnected: true };
}
}
}
/// <summary>Uses <paramref name="client"/> from now on. The caller keeps ownership (and disposes it).</summary>
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);
}
}
/// <summary>Stops using the current client (it is not disposed here).</summary>
public void Detach()
{
lock (_gate)
{
DetachLocked();
}
}
public Task<JsonElement> 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<JsonElement>(new BrowserUnavailableException()) : client.SendAsync(method, parameters, ct);
}
public IDisposable On(string eventName, Action<JsonElement> 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<JsonElement> handler)
{
public string EventName { get; } = eventName;
public Action<JsonElement> Handler { get; } = handler;
public IDisposable? Inner { get; set; }
}
}
@@ -0,0 +1,48 @@
namespace Febe.Browser.Diagnostics;
public enum BrowserLogLevel
{
Debug,
Information,
Warning,
Error,
}
/// <summary>
/// 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.
/// </summary>
public interface IBrowserLog
{
void Write(BrowserLogLevel level, string message, Exception? exception = null);
}
/// <summary>Discards everything.</summary>
public sealed class NullBrowserLog : IBrowserLog
{
public static NullBrowserLog Instance { get; } = new();
public void Write(BrowserLogLevel level, string message, Exception? exception = null)
{
}
}
/// <summary>Forwards to a delegate (handy for tests and console tools).</summary>
public sealed class DelegateBrowserLog(Action<BrowserLogLevel, string, Exception?> 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);
}
@@ -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;
/// <summary>Options of <see cref="BrowserFileFetcher"/>.</summary>
public sealed record BrowserFetchOptions
{
/// <summary>Bytes requested per <c>IO.read</c>.</summary>
public int ChunkBytes { get; init; } = 1024 * 1024;
/// <summary>
/// Whether the browser attaches its cookies for the file's host (<c>includeCredentials</c>). Off by default:
/// CDN addresses are signed and need none. To revisit with H7 in M0.
/// </summary>
public bool IncludeCredentials { get; init; }
/// <summary>Host kinds that may be downloaded: the CDN only, by default (spec §2 rule 1, §6.5).</summary>
public IReadOnlySet<HostKind> AllowedHostKinds { get; init; } = new HashSet<HostKind> { HostKind.Cdn };
}
/// <summary>
/// Downloads a file through the browser itself (spec §6.5 point 2): <c>Page.getFrameTree</c> for the frame id,
/// <c>Network.loadNetworkResource</c>, then <c>IO.read</c> in chunks into the caller's stream and <c>IO.close</c>.
/// </summary>
/// <remarks>The address is never logged (it carries signatures, spec §13.2).</remarks>
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<FetchResult> 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.");
}
}
}
@@ -0,0 +1,82 @@
namespace Febe.Browser.Gestures;
/// <summary>A point in CSS pixels relative to the page viewport (the coordinate space of <c>Input.*</c>).</summary>
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)));
}
/// <summary>A rectangle in CSS pixels relative to the page viewport.</summary>
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;
}
/// <summary>An interval «from a to b» with an optional median (spec §7.2), in the unit of its use.</summary>
public readonly record struct Interval(double Min, double Max, double? Median = null);
/// <summary>
/// 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.
/// </summary>
public sealed record GestureSettings
{
public static GestureSettings Natural { get; } = new();
/// <summary>Pointer travel time.</summary>
public Interval MoveDurationMs { get; init; } = new(250, 900);
/// <summary>Interval between pointer events: about 60 per second.</summary>
public double PointerEventIntervalMs { get; init; } = 1000.0 / 60.0;
/// <summary>Largest sideways bend of the path, as a fraction of the distance (a slightly curved path).</summary>
public Interval PathBendFraction { get; init; } = new(0.02, 0.12);
/// <summary>Part of the target, around its centre, where the pointer lands (0.6 = central 60% in each direction).</summary>
public double CentralFraction { get; init; } = 0.6;
/// <summary>Hover on the target before pressing.</summary>
public Interval HoverMs { get; init; } = new(80, 300);
/// <summary>Time between press and release.</summary>
public Interval PressMs { get; init; } = new(50, 140);
/// <summary>Wheel events in a burst.</summary>
public (int Min, int Max) WheelEventsPerBurst { get; init; } = (3, 8);
/// <summary>Pixels per wheel event.</summary>
public Interval WheelDeltaPx { get; init; } = new(80, 140);
/// <summary>Interval between the wheel events of a burst.</summary>
public Interval WheelIntervalMs { get; init; } = new(12, 40);
/// <summary>Pause between bursts.</summary>
public Interval BetweenBurstsMs { get; init; } = new(400, 4000, 1100);
/// <summary>Bursts between two reading pauses.</summary>
public (int Min, int Max) BurstsBeforeReading { get; init; } = (6, 10);
/// <summary>Reading pause.</summary>
public Interval ReadingPauseMs { get; init; } = new(3000, 20000, 6000);
/// <summary>Probability of a small scroll back after a burst.</summary>
public double ScrollBackProbability { get; init; } = 0.1;
/// <summary>Pixels per wheel event of a scroll back.</summary>
public Interval ScrollBackDeltaPx { get; init; } = new(40, 100);
/// <summary>Wait after a page load before the first gesture.</summary>
public Interval AfterLoadMs { get; init; } = new(1000, 6000, 2200);
/// <summary>Probability of a distraction after an action.</summary>
public double DistractionProbability { get; init; } = 0.08;
/// <summary>Length of a distraction.</summary>
public Interval DistractionMs { get; init; } = new(15000, 90000);
}
+381
View File
@@ -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;
/// <summary>A gesture was not performed because Alberto is using the browser (spec §4.1: the engine stays still).</summary>
public sealed class GestureInterruptedException()
: OperationCanceledException("Alberto sta usando il browser: il gesto non è stato eseguito.");
/// <summary>
/// Human gestures through <c>Input.*</c> only (spec §6.1, §7.7): never <c>Runtime.evaluate</c> to scroll or click.
/// All timing goes through <see cref="IClock"/> and every draw through <see cref="IRandomSource"/>, so tests run
/// under a virtual clock with a fixed seed.
/// </summary>
/// <remarks>
/// 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.
/// </remarks>
public sealed class HumanGestures
{
private readonly ICdpSession _cdp;
private readonly IClock _clock;
private readonly IRandomSource _random;
private readonly Func<bool> _userIsDriving;
private int _burstsUntilReading;
private PagePoint? _pointer;
/// <param name="cdp">Page session.</param>
/// <param name="clock">Time source for every wait.</param>
/// <param name="random">Random source for every draw.</param>
/// <param name="mood">Session mood (see <see cref="Distributions.SessionMood"/>), drawn once per session.</param>
/// <param name="pace">The «Ritmo dei gesti» slider.</param>
/// <param name="userIsDriving">When it returns true, gestures throw <see cref="GestureInterruptedException"/>.</param>
/// <param name="settings">Timings; <see cref="GestureSettings.Natural"/> by default.</param>
public HumanGestures(
ICdpSession cdp,
IClock clock,
IRandomSource random,
double mood = 1.0,
GesturePace pace = GesturePace.Natural,
Func<bool>? 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; }
/// <summary>Factor applied to every wait: mood × pace.</summary>
public double Multiplier => Mood * GesturePaceFactors.For(Pace);
/// <summary>Where the pointer is, or null before the first gesture.</summary>
public PagePoint? Pointer => _pointer;
/// <summary>Viewport size in CSS pixels; used to place the pointer before its first move.</summary>
public (double Width, double Height) Viewport { get; set; } = (1280, 900);
/// <summary>Moves the pointer to <paramref name="target"/> along a slightly curved, eased path.</summary>
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;
}
/// <summary>
/// A point inside the central part of <paramref name="box"/>, never its exact centre
/// (offsets follow a normal distribution, kept within the central fraction).
/// </summary>
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);
}
/// <summary>Travels to a random point of the central part of <paramref name="box"/>, hovers, presses and releases.</summary>
public async Task<PagePoint> 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;
}
/// <summary>
/// One burst of wheel events (3–8 of 80–140 px, 12–40 ms apart) with decreasing speed: deltas shrink and
/// intervals grow. <paramref name="direction"/> is +1 down, -1 up. Returns the pixels requested.
/// </summary>
public async Task<double> 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);
}
/// <summary>A small scroll back: one or two short wheel events in the opposite direction.</summary>
public async Task<double> 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);
}
/// <summary>
/// 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.
/// </summary>
public async Task<bool> 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;
}
/// <summary>
/// Scrolls with up to <paramref name="maxBursts"/> bursts, with pauses, reading pauses and occasional small scroll
/// backs. After each burst and its pause <paramref name="shouldContinue"/> decides whether to go on (e.g. the
/// recipe met known content). Returns the number of bursts.
/// </summary>
public async Task<int> ScrollAsync(int maxBursts, Func<CancellationToken, ValueTask<bool>>? 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;
}
/// <summary>The wait after a page load before the first gesture (median 2.2 s, 1–6 s).</summary>
public Task WaitAfterLoadAsync(CancellationToken ct = default) => WaitAsync(Settings.AfterLoadMs, ct);
/// <summary>With 8% probability, an extra wait of 15–90 s after an action. Returns true when it happened.</summary>
public async Task<bool> MaybeDistractionAsync(CancellationToken ct = default)
{
if (!_random.Chance(Settings.DistractionProbability))
{
return false;
}
await WaitAsync(Settings.DistractionMs, ct).ConfigureAwait(false);
return true;
}
/// <summary>Waits a drawn time from <paramref name="interval"/> (milliseconds), multiplied by mood and pace.</summary>
public async Task<TimeSpan> 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<double> 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);
/// <summary>Offset in [-limit, limit] around 0, normal with σ = limit/2, never exactly 0.</summary>
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);
}
/// <summary>
/// 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.
/// </summary>
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));
}
}
}
+177
View File
@@ -0,0 +1,177 @@
using System.Globalization;
using System.Text.Json.Nodes;
using Febe.Core.Abstractions;
using Febe.Core.Pacing;
namespace Febe.Browser.Gestures;
/// <summary>Modifier keys, with the bit values of <c>Input.dispatchKeyEvent</c>.</summary>
[Flags]
public enum KeyModifiers
{
None = 0,
Alt = 1,
Control = 2,
Meta = 4,
Shift = 8,
}
/// <summary>Keys that are not text.</summary>
public enum SpecialKey
{
Enter,
Tab,
Backspace,
Delete,
Escape,
ArrowLeft,
ArrowRight,
ArrowUp,
ArrowDown,
Home,
End,
PageUp,
PageDown,
}
/// <summary>
/// One key as the interface reports it (DOM KeyboardEvent fields). Contains what Alberto types:
/// it is never logged or stored (spec §13.2).
/// </summary>
/// <param name="Key">DOM <c>key</c> («a», «Enter», «è»).</param>
/// <param name="Code">DOM <c>code</c> («KeyA», «Enter»); may be empty.</param>
/// <param name="KeyCode">Windows virtual key code (DOM <c>keyCode</c>); 0 when unknown.</param>
/// <param name="Modifiers">Modifier keys held.</param>
/// <param name="Text">Text the key produces, or null for keys that produce none.</param>
public sealed record KeyStroke(string Key, string Code, int KeyCode, KeyModifiers Modifiers, string? Text)
{
public override string ToString() => "KeyStroke(…)";
}
/// <summary>Keyboard input through <c>Input.dispatchKeyEvent</c> only.</summary>
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),
};
/// <summary>The key for one character of text.</summary>
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);
/// <summary>Presses and releases one key, with a human hold time when a clock is given.</summary>
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);
}
/// <summary>Types <paramref name="text"/> one character at a time, 60–250 ms apart.</summary>
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;
}
}
@@ -0,0 +1,182 @@
using System.Globalization;
using Febe.Core.Abstractions;
namespace Febe.Browser.Hosting;
/// <summary>Where the session cookie is looked for (existence only, never the value).</summary>
/// <param name="CookieName">Cookie name. Instagram's is «sessionid» (public knowledge; hypothesis H10, to confirm in M0).</param>
/// <param name="SiteUrl">Address whose cookies are listed.</param>
public sealed record SessionCookieOptions(string CookieName, string SiteUrl)
{
public static SessionCookieOptions Instagram { get; } = new("sessionid", "https://www.instagram.com/");
}
/// <summary>Chromium-specific launch settings, on top of <see cref="BrowserOptions"/>.</summary>
public sealed record ChromiumLaunchOptions
{
/// <summary>
/// Adds <c>--no-sandbox</c>. 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.
/// </summary>
public bool NoSandbox { get; init; }
/// <summary>Extra arguments, checked by <see cref="ChromiumCommandLine.EnsureAllowed"/>.</summary>
public IReadOnlyList<string> ExtraArguments { get; init; } = [];
/// <summary>Environment overrides for the browser process (e.g. LANG, TZ in tests). A null value removes the variable.</summary>
public IReadOnlyDictionary<string, string?> Environment { get; init; } = new Dictionary<string, string?>();
/// <summary>Start page: always the rest page.</summary>
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;
/// <summary>
/// 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.
/// </summary>
public bool SeedProfilePreferences { get; init; } = true;
}
/// <summary>
/// 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.
/// </summary>
public static class ChromiumCommandLine
{
/// <summary>Arguments refused in <see cref="ChromiumLaunchOptions.ExtraArguments"/>, by prefix.</summary>
public static IReadOnlyList<string> 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<string> 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<string>
{
$"--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;
}
/// <summary>Refuses arguments that change what the browser declares, put it in automation mode or are set by Febe itself.</summary>
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));
}
}
}
/// <summary>
/// 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).
/// </summary>
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"]);
}
}
@@ -0,0 +1,307 @@
using System.Diagnostics;
using Febe.Browser.Cdp;
using Febe.Browser.Diagnostics;
using Febe.Core.Abstractions;
namespace Febe.Browser.Hosting;
/// <summary>
/// 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.
/// </summary>
/// <remarks>
/// <list type="bullet">
/// <item>Supervised: if Chromium exits it is restarted with backoff and <see cref="Cdp"/> reconnects by itself
/// (subscriptions survive; see <see cref="ICdpConnectionEvents.Reconnected"/>).</item>
/// <item>The DevTools port must listen on loopback only, or the start is aborted.</item>
/// <item>Stopping sends SIGINT first (not SIGTERM: see <see cref="ProcessSignals.SigInt"/>), 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.</item>
/// </list>
/// </remarks>
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;
}
/// <summary>The page session. Stable across restarts; commands fail with <see cref="BrowserUnavailableException"/> while the browser is down.</summary>
public ICdpSession Cdp => _session;
/// <summary>Raised when the connection was replaced after a restart.</summary>
public ICdpConnectionEvents Connection => _session;
/// <summary>Leases taken while Alberto uses the browser (remote view, connection page).</summary>
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<SupervisedState>? 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.");
}
/// <summary>Windows only: the Docker browser is seen through the remote view.</summary>
public Task ShowToUserAsync() => Task.CompletedTask;
public Task HideFromUserAsync() => Task.CompletedTask;
/// <summary>Puts the browser at rest on the blank page (spec §6.1).</summary>
public Task<NavigationResult> RestAsync(CancellationToken ct = default) => _session.RestAsync(ct);
/// <summary>Whether the session cookie exists. Never reads its value.</summary>
public Task<bool> HasSessionCookieAsync(CancellationToken ct = default) =>
SessionCookieProbe.HasSessionCookieAsync(_session, _launch.SessionCookie, ct);
/// <summary>Kills the browser as if it had crashed (tests and «riavvia il browser»). The supervisor restarts it.</summary>
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.");
}
/// <summary>Same as <see cref="StopAsync"/>. A stopped host cannot be started again: create a new one.</summary>
public ValueTask DisposeAsync() => new(StopAsync());
private ProcessStartInfo BuildStartInfo(string executable, IReadOnlyList<string> 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);
}
/// <summary>
/// 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.
/// </summary>
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);
}
}
}
+157
View File
@@ -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;
/// <summary>Checks who listens on a TCP port (spec §6.1: the debugging port listens on 127.0.0.1 only).</summary>
public static class LoopbackPortCheck
{
public static IReadOnlyList<IPEndPoint> ListenersOn(int port) =>
[.. IPGlobalProperties.GetIPGlobalProperties().GetActiveTcpListeners().Where(e => e.Port == port)];
/// <summary>True when something listens on <paramref name="port"/> and every listener is a loopback address.</summary>
public static bool IsLoopbackOnly(int port, out IReadOnlyList<IPEndPoint> 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;
}
/// <summary>
/// «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.
/// </summary>
public sealed class UserDrivingGate
{
private readonly Lock _gate = new();
private int _leases;
public bool IsDriving
{
get
{
lock (_gate)
{
return _leases > 0;
}
}
}
/// <summary>Raised when <see cref="IsDriving"/> changes; the argument is the new value.</summary>
public event EventHandler<bool>? Changed;
/// <summary>Opens a lease; dispose it when Alberto is done. Leases nest.</summary>
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();
}
}
/// <summary>
/// Tells whether the session cookie exists (spec §6.1, §7.6) through <c>Network.getCookies</c>.
/// Only the cookie names are looked at: values are never read, kept or logged.
/// </summary>
public static class SessionCookieProbe
{
public static async Task<bool> 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;
}
}
/// <summary>Prepares a new browser profile folder.</summary>
internal static class ChromiumProfile
{
/// <summary>
/// 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.
/// </summary>
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());
}
}
@@ -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;
/// <summary>How a supervised process is restarted after an unexpected exit.</summary>
/// <param name="InitialDelay">Wait before the first restart.</param>
/// <param name="MaxDelay">Upper bound of the exponential backoff.</param>
/// <param name="StableAfter">A process that ran at least this long resets the backoff.</param>
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));
/// <summary>Delay before restart number <paramref name="attempt"/> (0-based): doubles each time, capped.</summary>
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,
}
/// <summary>
/// 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).
/// </summary>
/// <remarks>
/// 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.
/// </remarks>
public sealed partial class SupervisedProcess : IAsyncDisposable
{
private readonly string _name;
private readonly Func<ProcessStartInfo> _startInfo;
private readonly Func<Process, CancellationToken, Task> _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<string> _stderrTail = new();
private CancellationTokenSource? _lifetime;
private Task? _supervision;
private Process? _process;
private SupervisedState _state = SupervisedState.Stopped;
/// <param name="name">Name shown in messages (e.g. «Chromium», «Xvfb»).</param>
/// <param name="startInfo">Builds the start information (called at every start, so it can be refreshed).</param>
/// <param name="waitReady">Completes when the started process is ready; throws if it cannot become ready.</param>
/// <param name="stopSignal">Unix signal of the polite stop (<see cref="ProcessSignals.SigTerm"/> by default;
/// Chromium needs <see cref="ProcessSignals.SigInt"/> to write its profile, see ChromiumProcessHost).</param>
public SupervisedProcess(
string name,
Func<ProcessStartInfo> startInfo,
Func<Process, CancellationToken, Task> 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;
}
}
}
/// <summary>Process id of the current instance, if running.</summary>
public int? ProcessId
{
get
{
lock (_gate)
{
return _process is { HasExited: false } p ? p.Id : null;
}
}
}
/// <summary>Number of restarts since <see cref="StartAsync"/>.</summary>
public int Restarts { get; private set; }
/// <summary>Raised when the process exited without being asked to (before any restart).</summary>
public event EventHandler<int>? ExitedUnexpectedly;
/// <summary>Raised after a restarted process became ready again.</summary>
public event EventHandler? Restarted;
public event EventHandler<SupervisedState>? StateChanged;
/// <summary>Starts the process and waits until it is ready. A failed first start throws (no retry).</summary>
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;
}
}
/// <summary>Stops supervising and ends the process: politely first, by force after <paramref name="grace"/>.</summary>
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)));
/// <summary>Ends the current instance by force (used when it is alive but unusable). The supervisor restarts it.</summary>
public void KillCurrent()
{
Process? process;
lock (_gate)
{
process = _process;
}
try
{
if (process is { HasExited: false })
{
process.Kill(entireProcessTree: true);
}
}
catch (InvalidOperationException)
{
}
}
/// <summary>Last lines of the error stream, addresses removed. For explaining a failed start only.</summary>
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<Process> 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, "<indirizzo>");
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;
}
}
/// <summary>Asks the process to end (<paramref name="signal"/> on Unix, close on Windows), then kills the tree after <paramref name="grace"/>.</summary>
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();
}
/// <summary>Polite termination signals.</summary>
public static class ProcessSignals
{
/// <summary>SIGINT: Chromium shuts down cleanly and writes its cookie store (measured, see docs/sonda/esito-locale.md).</summary>
public const int SigInt = 2;
/// <summary>SIGTERM: the usual polite stop (Xvfb).</summary>
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);
}
+204
View File
@@ -0,0 +1,204 @@
using System.Diagnostics;
using System.Globalization;
using Febe.Browser.Diagnostics;
using Febe.Core.Abstractions;
namespace Febe.Browser.Hosting;
/// <summary>
/// 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.
/// </summary>
public sealed class XvfbProcess : IAsyncDisposable
{
private readonly SupervisedProcess _supervisor;
private readonly int _displayNumber;
/// <param name="display">Display name, e.g. «:99».</param>
/// <param name="width">Screen width: at least the browser window width.</param>
/// <param name="height">Screen height: at least the browser window height.</param>
/// <param name="executable">Xvfb executable; null searches PATH.</param>
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;
/// <summary>Path of the X socket that appears when the display is ready.</summary>
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();
/// <summary>Finds Xvfb in PATH or in the usual places.</summary>
public static string? FindExecutable() => ExecutableSearch.Find(["Xvfb"], ["/usr/bin/Xvfb", "/usr/local/bin/Xvfb"]);
/// <summary>First display number in [<paramref name="from"/>, <paramref name="to"/>] with neither socket nor lock file.</summary>
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);
}
}
/// <summary>Process id written in the X lock file, or null.</summary>
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;
}
}
/// <summary>Looks for executables in PATH and in a few known places.</summary>
internal static class ExecutableSearch
{
public static string? Find(IEnumerable<string> names, IEnumerable<string> 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);
}
}
@@ -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,
}
/// <summary>A mouse event from the interface's remote view.</summary>
/// <param name="Action">Move, press, release or wheel.</param>
/// <param name="X">Horizontal position: 0–1 of the frame when <paramref name="Normalized"/>, CSS pixels otherwise.</param>
/// <param name="Y">Vertical position: 0–1 of the frame when <paramref name="Normalized"/>, CSS pixels otherwise.</param>
/// <param name="Button">Button pressed or released.</param>
/// <param name="ClickCount">1 for a click, 2 for a double click.</param>
/// <param name="DeltaX">Horizontal wheel delta in CSS pixels.</param>
/// <param name="DeltaY">Vertical wheel delta in CSS pixels (positive scrolls down).</param>
/// <param name="Modifiers">Modifier keys held.</param>
/// <param name="Normalized">Whether X and Y are fractions of the frame.</param>
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);
/// <summary>A key event from the interface's remote view. Never logged or stored (spec §13.2).</summary>
public sealed record RemoteKeyEvent(bool Down, KeyStroke Key)
{
public override string ToString() => "RemoteKeyEvent(…)";
}
/// <summary>
/// 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 <c>Input.*</c>. While the session is active the
/// <see cref="UserDrivingGate"/> holds a lease, so the engine stays still. Keys are forwarded, never logged.
/// </summary>
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;
/// <summary>Takes the «Alberto is driving» lease and starts the frames.</summary>
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);
}
/// <summary>Opens an address chosen by Alberto (e.g. the login page from the connection page).</summary>
public Task<NavigationResult> NavigateAsync(string url, CancellationToken ct = default)
{
EnsureActive();
return _cdp.NavigateAsync(url, ct);
}
/// <summary>Stops the frames and releases the lease: the engine may act again.</summary>
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.");
}
}
}
/// <summary>The still preview of the Activity page (mockup 06): one frame every few seconds, not a video.</summary>
public static class PagePreview
{
/// <summary>Captures the visible page as JPEG through <c>Page.captureScreenshot</c>.</summary>
public static async Task<byte[]> 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()
: [];
}
}
@@ -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;
/// <summary>Settings of a screencast (<c>Page.startScreencast</c>).</summary>
/// <param name="Quality">JPEG quality, 0–100.</param>
/// <param name="MaxWidth">Largest frame width in pixels.</param>
/// <param name="MaxHeight">Largest frame height in pixels.</param>
/// <param name="EveryNthFrame">Send one frame out of this many.</param>
public sealed record ScreencastOptions(int Quality = 70, int MaxWidth = 1280, int MaxHeight = 900, int EveryNthFrame = 1);
/// <summary>One frame of the remote view.</summary>
/// <param name="Jpeg">The image.</param>
/// <param name="DeviceWidth">Page width in CSS pixels the frame represents.</param>
/// <param name="DeviceHeight">Page height in CSS pixels the frame represents.</param>
/// <param name="PageScaleFactor">Page zoom.</param>
/// <param name="OffsetTop">Top offset in CSS pixels (browser controls).</param>
/// <param name="ScrollOffsetX">Horizontal scroll position.</param>
/// <param name="ScrollOffsetY">Vertical scroll position.</param>
/// <param name="Timestamp">Browser timestamp (seconds), when given.</param>
public sealed record ScreencastFrame(
byte[] Jpeg,
double DeviceWidth,
double DeviceHeight,
double PageScaleFactor,
double OffsetTop,
double ScrollOffsetX,
double ScrollOffsetY,
double? Timestamp);
/// <summary>
/// The remote view's video (spec §4.1, §11): <c>Page.startScreencast</c> in JPEG, every frame acknowledged with
/// <c>Page.screencastFrameAck</c>, stopped with <c>Page.stopScreencast</c>. Frames are delivered through
/// <see cref="ReadFramesAsync"/> (only the latest ones are kept when the reader is slow) and <see cref="FrameReceived"/>.
/// </summary>
public sealed class ScreencastSession : IAsyncDisposable
{
private readonly ICdpSession _cdp;
private readonly IBrowserLog _log;
private readonly Channel<ScreencastFrame> _frames = Channel.CreateBounded<ScreencastFrame>(
new BoundedChannelOptions(2) { FullMode = BoundedChannelFullMode.DropOldest, SingleReader = true });
private readonly Channel<int> _acks = Channel.CreateUnbounded<int>(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;
}
/// <summary>Raised on the browser event thread for every frame: handlers must be quick.</summary>
public event EventHandler<ScreencastFrame>? FrameReceived;
/// <summary>The last frame received, for mapping input coordinates.</summary>
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.");
}
/// <summary>Frames as they arrive; the oldest are dropped if the reader falls behind. Ends when the session stops.</summary>
public async IAsyncEnumerable<ScreencastFrame> 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;
}
+223
View File
@@ -0,0 +1,223 @@
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Text.RegularExpressions;
namespace Febe.Browser.Targets;
/// <summary>
/// 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.
/// </summary>
/// <param name="Id">Identifier used by recipes (e.g. «viewer-next»).</param>
/// <param name="Roles">Accepted ARIA roles, explicit or implicit («link», «button», ...). Empty: any.</param>
/// <param name="NamePattern">Regular expression (case-insensitive) on the accessible name; may contain {parameters}.</param>
/// <param name="HrefPattern">Link shape on the path, e.g. «/{username}/», «/stories/**»: {name} or * is one segment, ** the rest.</param>
/// <param name="Index">Which of the visible matches, in document order (0 = first, -1 = last).</param>
/// <param name="Hypothesis">Hypothesis of spec §6.6 the target depends on (e.g. «H11»), when not yet confirmed.</param>
public sealed record TargetSpec(string Id, IReadOnlyList<string> Roles, string? NamePattern, string? HrefPattern, int Index, string? Hypothesis);
/// <summary>
/// The target map of one site (<c>bersagli.instagram.json</c>, <c>bersagli.prova.json</c>), editable without
/// recompiling: it is the second thing to touch, after the readers, when the site changes.
/// </summary>
/// <remarks>
/// Format:
/// <code>
/// {
/// "site": "prova",
/// "note": "testo libero",
/// "targets": {
/// "viewer-next": { "role": "button", "name": "^avanti$", "note": "..." },
/// "profile-stories": { "role": "link", "href": "/stories/{username}/", "index": 0, "hypothesis": "H11" }
/// }
/// }
/// </code>
/// «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.
/// </remarks>
public sealed partial class TargetMap
{
private readonly Dictionary<string, TargetSpec> _targets;
public TargetMap(string? site, IEnumerable<TargetSpec> 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<string, TargetSpec> 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<TargetSpec>();
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);
}
/// <summary>
/// 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.
/// </summary>
public static string HrefPatternToRegex(string pattern, IReadOnlyDictionary<string, string>? 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();
}
/// <summary>Replaces {parameters} in a name pattern with their escaped values.</summary>
public static string ExpandNamePattern(string pattern, IReadOnlyDictionary<string, string>? parameters) =>
PlaceholderToken().Replace(pattern, m =>
parameters is not null && parameters.TryGetValue(m.Groups[1].Value, out var value) ? EscapeForRegex(value) : ".+");
/// <summary>Escapes regular-expression metacharacters in a way valid both for .NET and JavaScript.</summary>
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<string, TargetDto>? 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;
+302
View File
@@ -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;
/// <summary>Outcome of looking a target up.</summary>
public enum TargetStatus
{
Found,
/// <summary>No element matches role, name and link shape.</summary>
NotFound,
/// <summary>Elements match but none is rendered (hidden, zero size, transparent).</summary>
NotVisible,
/// <summary>Fewer visible matches than the index asks for.</summary>
IndexOutOfRange,
/// <summary>The element exists but could not be brought into the viewport.</summary>
OutOfView,
/// <summary>Something covers the element (e.g. a dialog): clicking would hit something else.</summary>
Obstructed,
}
/// <summary>One element matched by a target, as measured by the page.</summary>
/// <param name="Rect">Bounding box in viewport CSS pixels.</param>
/// <param name="Visible">Rendered: non-zero size, not hidden, not transparent.</param>
/// <param name="InViewport">At least partly inside the viewport.</param>
/// <param name="Unobstructed">The centre of its visible part hits the element itself.</param>
public sealed record TargetElement(PageRect Rect, bool Visible, bool InViewport, bool Unobstructed);
/// <summary>Result of a lookup. When not found, recipes stop and report: they never click at random (spec §7.7).</summary>
public sealed record TargetLookup(string Id, TargetStatus Status, TargetElement? Element, int Matches, double ViewportWidth, double ViewportHeight)
{
public bool Found => Status == TargetStatus.Found;
/// <summary>Message for the interface and the log (Italian, no page content).</summary>
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.",
};
}
/// <summary>
/// Finds targets of a <see cref="TargetMap"/> through one read-only <c>Runtime.evaluate</c>: it queries the DOM
/// (roles, accessible names, link paths), measures rectangles and hit-tests, and never modifies the page.
/// </summary>
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;
/// <summary>Finds target <paramref name="id"/>; <paramref name="parameters"/> fill the {placeholders} of the map.</summary>
public async Task<TargetLookup> ResolveAsync(string id, IReadOnlyDictionary<string, string>? 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);
}
/// <summary>Every element matching <paramref name="id"/>, visible or not, in document order (at most 200).</summary>
public async Task<IReadOnlyList<TargetElement>> FindAllAsync(string id, IReadOnlyDictionary<string, string>? parameters = null, CancellationToken ct = default)
{
var (all, _, _) = await MeasureAsync(_map.Get(id), parameters, ct).ConfigureAwait(false);
return all;
}
/// <summary>The expression sent to <c>Runtime.evaluate</c> for <paramref name="spec"/> (exposed for tests).</summary>
public static string BuildExpression(TargetSpec spec, IReadOnlyDictionary<string, string>? 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<TargetElement> All, double Width, double Height)> MeasureAsync(TargetSpec spec, IReadOnlyDictionary<string, string>? parameters, CancellationToken ct)
{
var value = await _cdp.EvaluateAsync(BuildExpression(spec, parameters), ct).ConfigureAwait(false);
var list = new List<TargetElement>();
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());
}
}
/// <summary>Result of clicking a target.</summary>
/// <param name="Clicked">True when the click was performed.</param>
/// <param name="Lookup">The last lookup (its status says why there was no click).</param>
/// <param name="At">Where the click landed.</param>
public sealed record TargetClickResult(bool Clicked, TargetLookup Lookup, PagePoint? At);
/// <summary>
/// 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).
/// </summary>
public sealed class TargetActions(TargetResolver resolver, HumanGestures gestures)
{
/// <summary>Brings the target into view with wheel bursts if needed (at most <paramref name="maxScrollBursts"/>), then clicks it.</summary>
public async Task<TargetClickResult> ClickAsync(string id, IReadOnlyDictionary<string, string>? 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);
}
}
+136
View File
@@ -0,0 +1,136 @@
namespace Febe.Core.Collection;
/// <summary>An address reduced to what may be kept: scheme, host and path. Never query string or fragment.</summary>
/// <param name="Url">The sanitized address, e.g. «https://www.example.org/a/b/».</param>
/// <param name="Scheme">Scheme in lower case («https», «about», «data»...).</param>
/// <param name="Host">Host in lower case, with the port when it is not the default one; empty when there is none.</param>
/// <param name="Path">Path without query and fragment; empty for opaque addresses (data:, blob:).</param>
public sealed record SanitizedUrl(string Url, string Scheme, string Host, string Path)
{
public override string ToString() => Url;
}
/// <summary>Strips query strings, fragments and credentials from addresses (spec §7.6, §13.2).</summary>
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}";
}
}
/// <summary>
/// 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).
/// </summary>
public sealed class HostClassifier
{
private readonly string[] _site;
private readonly string[] _cdn;
public HostClassifier(IEnumerable<string> siteHosts, IEnumerable<string> cdnHosts)
{
_site = Normalize(siteHosts);
_cdn = Normalize(cdnHosts);
}
/// <summary>
/// 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.
/// </summary>
public static HostClassifier Instagram { get; } = new(
["instagram.com"],
["cdninstagram.com", "fbcdn.net"]);
public IReadOnlyList<string> SiteHosts => _site;
public IReadOnlyList<string> 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<string> hosts)
{
ArgumentNullException.ThrowIfNull(hosts);
return [.. hosts.Select(h => h.Trim().TrimStart('.').ToLowerInvariant()).Where(h => h.Length > 0).Distinct()];
}
}
+49
View File
@@ -0,0 +1,49 @@
namespace Febe.Core.Collection;
/// <summary>How a file download ended.</summary>
public enum FetchOutcome
{
/// <summary>All bytes were written to the destination.</summary>
Completed,
/// <summary>The server answered with an error status (e.g. an expired signed address, spec §6.5 point 5).</summary>
HttpError,
/// <summary>The request failed before a response (network error, refused by the browser).</summary>
NetworkError,
/// <summary>The file exceeded the maximum size allowed by the caller; the destination holds a partial copy.</summary>
TooLarge,
/// <summary>The address is not on an allowed host (only CDN addresses may be downloaded).</summary>
HostNotAllowed,
}
/// <summary>Result of a download. Never contains the address: it carries signatures (spec §13.2).</summary>
/// <param name="Outcome">How it ended.</param>
/// <param name="Bytes">Bytes written to the destination.</param>
/// <param name="HttpStatus">HTTP status code, when a response arrived.</param>
/// <param name="Error">Short error description without the address, when it failed.</param>
public sealed record FetchResult(FetchOutcome Outcome, long Bytes, int? HttpStatus, string? Error)
{
public bool Succeeded => Outcome == FetchOutcome.Completed;
}
/// <summary>Options of a single download.</summary>
/// <param name="MaxBytes">Abort with <see cref="FetchOutcome.TooLarge"/> past this size; null for no limit.</param>
/// <param name="Progress">Receives the number of bytes written so far.</param>
public sealed record FetchOptions(long? MaxBytes = null, IProgress<long>? Progress = null);
/// <summary>
/// Downloads one file indicated by the page into a stream (spec §6.5). The preferred implementation goes through
/// the browser (<c>Network.loadNetworkResource</c> + <c>IO.read</c>); a fallback through <c>HttpClient</c> to CDN hosts
/// only may be added if M0 shows the first one does not work with the real CDN (H7).
/// </summary>
/// <remarks>
/// 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 <see cref="OperationCanceledException"/>.
/// </remarks>
public interface IFileFetcher
{
Task<FetchResult> FetchAsync(Uri address, Stream destination, FetchOptions? options, CancellationToken ct);
}
@@ -0,0 +1,72 @@
using System.Text.Json;
namespace Febe.Core.Collection;
/// <summary>Which kind of host served a response (spec §14.5: only the site/CDN distinction is kept).</summary>
public enum HostKind
{
/// <summary>The site itself (Instagram pages and data, or the local test site).</summary>
Site,
/// <summary>The content delivery network that serves photos and videos.</summary>
Cdn,
/// <summary>Anything else the page happens to contact.</summary>
Other,
}
/// <summary>
/// Sanitized description of a response seen by the page: never the query string, never headers, never the body.
/// </summary>
/// <param name="RequestId">Browser request identifier (opaque, only meaningful inside one browser session).</param>
/// <param name="HostKind">Site, CDN or other.</param>
/// <param name="Url">Scheme, host and path, without query string and fragment (see <see cref="UrlSanitizer"/>).
/// For CDN responses it must not be logged: it identifies files (spec §13.2).</param>
/// <param name="Host">Host name, with the port when it is not the default one.</param>
/// <param name="Path">Path without query string and fragment.</param>
/// <param name="Status">HTTP status code.</param>
/// <param name="MimeType">MIME type declared by the response, lower case, without parameters.</param>
/// <param name="ResourceType">Browser resource type (Document, XHR, Fetch, Image, ...), when known.</param>
/// <param name="IsMainFrameDocument">True for the document of the main frame (a page load).</param>
/// <param name="At">When the response was seen.</param>
public sealed record ResponseDescriptor(
string RequestId,
HostKind HostKind,
string Url,
string Host,
string Path,
int Status,
string MimeType,
string? ResourceType,
bool IsMainFrameDocument,
DateTimeOffset At);
/// <summary>A main-frame navigation: a new document, or a route change inside a single-page site.</summary>
/// <param name="HostKind">Site, CDN or other.</param>
/// <param name="Url">Address without query string and fragment.</param>
/// <param name="Host">Host name (with port when not default); empty for about:blank and similar.</param>
/// <param name="Path">Path without query string and fragment.</param>
/// <param name="At">When the navigation was seen.</param>
/// <param name="SameDocument">True for a route change without a new document (history.pushState).</param>
public sealed record NavigationDescriptor(HostKind HostKind, string Url, string Host, string Path, DateTimeOffset At, bool SameDocument = false);
/// <summary>
/// Receives the JSON bodies captured by the response tap (spec §6.2): readers and signal detection.
/// </summary>
/// <remarks>
/// The <see cref="JsonDocument"/> 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.
/// </remarks>
public interface IResponseConsumer
{
ValueTask ConsumeAsync(ResponseDescriptor response, JsonDocument body, CancellationToken ct);
}
/// <summary>Receives metadata of every response and every main-frame navigation (no bodies).</summary>
/// <remarks>Called on the browser event thread: implementations must be quick and must not block.</remarks>
public interface IResponseObserver
{
void OnResponse(ResponseDescriptor response);
void OnNavigation(NavigationDescriptor navigation);
}
+242
View File
@@ -0,0 +1,242 @@
using System.Text.Json;
using System.Text.RegularExpressions;
using Febe.Core.Abstractions;
namespace Febe.Core.Collection;
/// <summary>
/// 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.
/// </summary>
/// <remarks>
/// The same signal code is reported at most once per <see cref="DedupeWindow"/>: a page that receives ten 429
/// responses in a second is one throttle, not ten. Thread-safe.
/// </remarks>
public sealed class SignalDetector : IResponseObserver, IResponseConsumer
{
private readonly SignalRules _rules;
private readonly ICircuitBreaker _breaker;
private readonly IClock _clock;
private readonly Dictionary<string, DateTimeOffset> _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; }
/// <summary>Raised after a signal has been reported to the breaker.</summary>
public event EventHandler<Signal>? 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;
}
/// <summary>Status and path rules on a response.</summary>
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;
}
/// <summary>Path rules on a main-frame navigation.</summary>
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;
}
/// <summary>Text rules on the string values of a short JSON response.</summary>
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;
}
/// <summary>
/// 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.
/// </summary>
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);
}
/// <summary>A recipe loaded a page with content: resets the empty-page counter.</summary>
public void ObserveNonEmptyPage()
{
lock (_gate)
{
_consecutiveEmpty = 0;
}
}
/// <summary>Result of the session-cookie check: a missing cookie is a disconnection (spec §7.6).</summary>
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;
}
}
/// <summary>Looks for <paramref name="regex"/> in the string values, giving up when they exceed <paramref name="maxChars"/>.</summary>
private static bool ContainsText(JsonElement root, Regex regex, int maxChars)
{
var budget = maxChars;
var strings = new List<string>();
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<string> 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;
}
}
}
+271
View File
@@ -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;
/// <summary>Where a path rule looks.</summary>
[Flags]
public enum SignalScope
{
None = 0,
/// <summary>Main-frame navigations (the address the page moved to).</summary>
Navigation = 1,
/// <summary>Main-frame document responses (page loads, redirects included).</summary>
Document = 2,
/// <summary>Every other response (data requests, files).</summary>
Subresource = 4,
Any = Navigation | Document | Subresource,
}
/// <summary>One rule of <c>segnali.json</c>: exactly one matcher among status, path and text.</summary>
public sealed record SignalRule
{
public required string Code { get; init; }
public required SignalLevel Level { get; init; }
/// <summary>HTTP status codes that trigger the rule.</summary>
public IReadOnlySet<int> Statuses { get; init; } = new HashSet<int>();
/// <summary>Regular expression on the address path (no query string).</summary>
public Regex? Path { get; init; }
/// <summary>Regular expression on the string values of short JSON responses.</summary>
public Regex? Text { get; init; }
/// <summary>Text rules only look at responses whose strings total at most this many characters.</summary>
public int MaxTextChars { get; init; } = SignalRules.DefaultMaxTextChars;
public IReadOnlySet<HostKind> HostKinds { get; init; } = new HashSet<HostKind> { HostKind.Site, HostKind.Cdn };
public SignalScope Scope { get; init; } = SignalScope.Any;
/// <summary>Hypothesis of spec §6.6 the rule depends on (e.g. «H8»), when it is not yet confirmed.</summary>
public string? Hypothesis { get; init; }
}
/// <summary>Threshold of the «repeated empty pages» throttle signal.</summary>
public sealed record EmptyPagesRule(string Code, SignalLevel Level, int Consecutive);
/// <summary>
/// The stop-signal rules (spec §7.6), loaded from <c>segnali.json</c> so they can change without recompiling.
/// </summary>
public sealed class SignalRules
{
public const int DefaultMaxTextChars = 4000;
/// <summary>Code of the built-in rule «the session cookie is gone» (spec §7.6, Disconnessione).</summary>
public const string SessionCookieMissingCode = "session-cookie-missing";
private static readonly TimeSpan RegexTimeout = TimeSpan.FromMilliseconds(250);
public SignalRules(IReadOnlyList<SignalRule> rules, EmptyPagesRule? emptyPages, string? source = null)
{
Rules = rules;
EmptyPages = emptyPages;
Source = source;
}
public IReadOnlyList<SignalRule> Rules { get; }
public EmptyPagesRule? EmptyPages { get; }
/// <summary>Where the rules came from (file path or embedded resource name), for messages.</summary>
public string? Source { get; }
/// <summary>The shipped Instagram rules (embedded copy of <c>config/segnali.json</c>).</summary>
public static SignalRules LoadDefault() => LoadEmbedded("segnali.json");
/// <summary>The rules of the local test site (embedded copy of <c>config/segnali.prova.json</c>).</summary>
public static SignalRules LoadTestSite() => LoadEmbedded("segnali.prova.json");
/// <summary>Loads <paramref name="path"/> when it exists, otherwise the shipped default rules.</summary>
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<SignalRule>(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);
}
/// <summary>Parses a level name, in English (code) or Italian (interface) form.</summary>
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> { HostKind.Site, HostKind.Cdn } : new HashSet<HostKind> { 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<int>(),
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<SignalRuleDto>? Rules { get; set; }
public EmptyPagesDto? EmptyPages { get; set; }
}
internal sealed class SignalRuleDto
{
public string? Code { get; set; }
public string? Level { get; set; }
public List<int>? Status { get; set; }
public string? Path { get; set; }
public string? Text { get; set; }
public int? MaxTextChars { get; set; }
public List<string>? HostKinds { get; set; }
public List<string>? 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;
+72
View File
@@ -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."
}
}
+36
View File
@@ -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
}
}
+6
View File
@@ -4,6 +4,12 @@
<ItemGroup>
<PackageReference Include="SkiaSharp" />
</ItemGroup>
<ItemGroup>
<!-- File di configurazione per sito (specifica §6.3, §7.6): una copia incorporata come valore predefinito
e una copia accanto all'eseguibile, in config/, modificabile senza ricompilare. -->
<EmbeddedResource Include="Config\*.json" LogicalName="Febe.Core.Config.%(Filename)%(Extension)" />
<None Include="Config\*.json" Link="config\%(Filename)%(Extension)" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
<ItemGroup>
<InternalsVisibleTo Include="Febe.Tests" />
</ItemGroup>
+149
View File
@@ -0,0 +1,149 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
namespace Febe.Core.Pacing;
/// <summary>
/// The random draws of spec §7.2, all driven by <see cref="IRandomSource"/> so that a fixed seed reproduces them.
/// Durations, pauses and waits are never uniform: they come from truncated log-normal distributions.
/// </summary>
public static class Distributions
{
/// <summary>Maximum rejection attempts before falling back to clamping (only reachable with a degenerate source).</summary>
private const int MaxRejections = 64;
/// <summary>Standard normal value N(0, 1) by the Box-Muller transform.</summary>
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);
}
/// <summary>Normal value with the given mean and standard deviation.</summary>
public static double Normal(this IRandomSource random, double mean, double standardDeviation) =>
mean + (standardDeviation * random.StandardNormal());
/// <summary>Log-normal value with the given median and σ (of the underlying normal).</summary>
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());
}
/// <summary>
/// Log-normal value truncated to [<paramref name="min"/>, <paramref name="max"/>] by rejection
/// (the shape inside the interval is preserved; nothing piles up on the bounds).
/// </summary>
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);
}
/// <summary>
/// An interval «from a to b» (spec §7.2): log-normal with median √(a·b), or <paramref name="median"/> when given,
/// σ = ln(b/a)/4, truncated to [a, b].
/// </summary>
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);
}
/// <summary>Same as <see cref="Between(IRandomSource, double, double, double?)"/> for durations.</summary>
public static TimeSpan Between(this IRandomSource random, TimeSpan a, TimeSpan b, TimeSpan? median = null) =>
TimeSpan.FromMilliseconds(random.Between(a.TotalMilliseconds, b.TotalMilliseconds, median?.TotalMilliseconds));
/// <summary>
/// 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.
/// </summary>
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);
}
/// <summary>Session mood (spec §7.2): log-normal, median 1, σ 0.2, truncated to [0.7, 1.5]. Multiplies every wait.</summary>
public static double SessionMood(this IRandomSource random) =>
random.TruncatedLogNormal(1.0, 0.2, 0.7, 1.5);
/// <summary>Next-check jitter (spec §7.2): log-normal, median 1, σ 0.25, truncated to [0.6, 1.8]. Multiplies an interval.</summary>
public static double NextCheckJitter(this IRandomSource random) =>
random.TruncatedLogNormal(1.0, 0.25, 0.6, 1.8);
/// <summary>The next check after <paramref name="interval"/>, scaled by <see cref="NextCheckJitter"/>.</summary>
public static TimeSpan JitteredInterval(this IRandomSource random, TimeSpan interval) =>
TimeSpan.FromTicks((long)(interval.Ticks * random.NextCheckJitter()));
/// <summary>True with probability <paramref name="probability"/> (a Bernoulli draw, not a duration).</summary>
public static bool Chance(this IRandomSource random, double probability)
{
ArgumentNullException.ThrowIfNull(random);
return probability > 0 && random.NextDouble() < probability;
}
}
/// <summary>Factors of the «Ritmo dei gesti» slider (spec §7.7): they multiply every gesture wait.</summary>
public static class GesturePaceFactors
{
/// <summary>Multiplier of waits for <paramref name="pace"/>: slow 1.35, natural 1, brisk 0.75.</summary>
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),
};
}
@@ -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;
/// <summary>
/// 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.
/// </summary>
[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<CdpCommandNotAllowedException>(() => Browser.Cdp.SendAsync("Emulation.setTimezoneOverride", new JsonObject { ["timezoneId"] = "America/New_York" }));
await Assert.ThrowsExactlyAsync<CdpCommandNotAllowedException>(() => Browser.Cdp.SendAsync("Network.setUserAgentOverride", new JsonObject { ["userAgent"] = "Febe" }));
await Assert.ThrowsExactlyAsync<CdpCommandNotAllowedException>(() => Browser.Cdp.SendAsync("Network.setExtraHTTPHeaders", new JsonObject { ["headers"] = new JsonObject() }));
await Assert.ThrowsExactlyAsync<CdpCommandNotAllowedException>(() => Browser.Cdp.SendAsync("Page.addScriptToEvaluateOnNewDocument", new JsonObject { ["source"] = "1" }));
await Assert.ThrowsExactlyAsync<CdpCommandNotAllowedException>(() => Browser.Cdp.SendAsync("Fetch.enable"));
await Assert.ThrowsExactlyAsync<CdpCommandNotAllowedException>(() => Browser.Cdp.SendAsync("Target.createTarget", new JsonObject { ["url"] = "about:blank" }));
await Assert.ThrowsExactlyAsync<CdpCommandNotAllowedException>(() => Browser.Cdp.EvaluateAsync("window.scrollBy(0, 500)"));
Assert.AreEqual("Europe/Rome", await Browser.EvalAsync<string>("Intl.DateTimeFormat().resolvedOptions().timeZone"));
Assert.AreEqual(0, await Browser.EvalAsync<double>("window.scrollY"));
}
[TestMethod]
public async Task WheelBurstsReallyScrollThePage()
{
await Browser.GoAsync("/lunga");
Assert.AreEqual(0, await Browser.EvalAsync<double>("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<double>("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<double>("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<int>("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<string, string> { ["username"] = "alice" });
Assert.IsTrue(profile.Found, "Link shape /profilo/{username}/ matches.");
Assert.IsFalse((await resolver.ResolveAsync("profilo", new Dictionary<string, string> { ["username"] = "bob" })).Found);
Assert.IsTrue((await resolver.ResolveAsync("storia", new Dictionary<string, string> { ["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<double>("window.scrollY") > 1000, "Wheel bursts brought it into view.");
var ids = (await Browser.Cdp.EvaluateAsync("window.__clicks.map((c) => c.id)")).Deserialize<string[]>();
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<ScreencastFrame>();
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<string>("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<bool> 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;
}
}
}
@@ -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;
/// <summary>Supervision of the real browser: crash and restart, clean stop, session kept in the profile.</summary>
[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<InvalidOperationException>(() => host.StartAsync(options, CancellationToken.None));
StringAssert.Contains(ex.Message, "già occupata");
}
finally
{
listener.Stop();
}
}
private sealed class Collector : IResponseConsumer
{
public ConcurrentBag<string> Paths { get; } = [];
public ValueTask ConsumeAsync(ResponseDescriptor response, JsonDocument body, CancellationToken ct)
{
Paths.Add(response.Path);
return ValueTask.CompletedTask;
}
}
}
@@ -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<string>() == "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<string>());
return new JsonObject { ["resource"] = new JsonObject { ["success"] = true, ["httpStatusCode"] = 200, ["stream"] = "S1" } };
case "IO.read":
var size = p!["size"]!.GetValue<int>();
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<long>();
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<string>());
Assert.AreEqual(2, start["everyNthFrame"]!.GetValue<int>());
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<int>() == 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<InvalidOperationException>(() => 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<int>());
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<bool> 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<ResponseDescriptor> Responses { get; } = new();
public ConcurrentQueue<NavigationDescriptor> Navigations { get; } = new();
public void OnResponse(ResponseDescriptor response) => Responses.Enqueue(response);
public void OnNavigation(NavigationDescriptor navigation) => Navigations.Enqueue(navigation);
}
private sealed class SyncProgress(List<long> values) : IProgress<long>
{
public void Report(long value) => values.Add(value);
}
}
+246
View File
@@ -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;
/// <summary>The CDP client against a scripted WebSocket peer on a loopback TCP pair (no browser).</summary>
[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<int>(), ["result"] = new JsonObject { ["who"] = "second" } });
await pair.SendAsync(new JsonObject { ["id"] = a["id"]!.GetValue<int>(), ["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<string>());
Assert.AreEqual("1+1", b["params"]!["expression"]!.GetValue<string>());
}
[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<int>(),
["error"] = new JsonObject { ["code"] = -32000, ["message"] = "Cannot navigate" },
});
var ex = await Assert.ThrowsExactlyAsync<CdpCommandException>(() => 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<string>();
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<int>(), ["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<CdpCommandNotAllowedException>(() => pair.Client.SendAsync("Emulation.setTimezoneOverride", new { timezoneId = "UTC" }));
await Assert.ThrowsExactlyAsync<CdpCommandNotAllowedException>(() => pair.Client.SendAsync("Network.setUserAgentOverride", new { userAgent = "x" }));
await Assert.ThrowsExactlyAsync<CdpCommandNotAllowedException>(() => 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<string>());
await pair.SendAsync(new JsonObject { ["id"] = first["id"]!.GetValue<int>(), ["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<CdpDisconnectedException>(() => pending);
await disconnected.Task.WaitAsync(TimeSpan.FromSeconds(5));
Assert.IsFalse(pair.Client.IsConnected);
await Assert.ThrowsExactlyAsync<CdpDisconnectedException>(() => 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<OperationCanceledException>(() => call);
var next = pair.Client.SendAsync("Page.enable");
var request = await pair.ReceiveAsync();
await pair.SendAsync(new JsonObject { ["id"] = request["id"]!.GetValue<int>(), ["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<CdpDisconnectedException>(() => pending);
await Assert.ThrowsExactlyAsync<CdpDisconnectedException>(() => pair.Client.SendAsync("Page.enable"));
await pair.DisposeAsync();
}
[TestMethod]
public async Task TheLogHoldsCommandNamesOnly()
{
var log = new ConcurrentQueue<string>();
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<int>(),
["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<bool> condition)
{
for (var i = 0; i < 200 && !condition(); i++)
{
await Task.Delay(10);
}
Assert.IsTrue(condition());
}
/// <summary>A CdpClient connected to a server-side WebSocket over a loopback TCP connection.</summary>
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<SocketPair> 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<JsonNode> 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();
}
}
}
+104
View File
@@ -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<CdpCommandNotAllowedException>(() => 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<CdpCommandNotAllowedException>(() => 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<CdpCommandNotAllowedException>(() => 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<string, string> { ["username"] = "alice" });
ReadOnlyScriptGuard.EnsureReadOnly(expression);
}
}
+331
View File
@@ -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<string>());
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<int>();
var normal = new List<double>();
var reading = new List<double>();
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<double>();
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<double>();
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<GestureInterruptedException>(() => gestures.ClickAsync(new PageRect(10, 10, 50, 20)));
await Assert.ThrowsExactlyAsync<GestureInterruptedException>(() => 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<string>()).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));
}
}
+151
View File
@@ -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<ArgumentOutOfRangeException>(() => 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<ArgumentException>(() => 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<bool>();
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"));
}
}
@@ -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<KeyNotFoundException>(() => 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<string, string> { ["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<string, string> { ["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<InvalidDataException>(() => 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<string, string> { ["username"] = "alice" });
StringAssert.Contains(expression, "\"roles\":[\"link\"]");
StringAssert.Contains(expression, "stories");
Assert.IsFalse(expression.Contains("__SPEC__", StringComparison.Ordinal));
}
}
@@ -0,0 +1,192 @@
using System.Text.Json;
using System.Text.Json.Nodes;
using Febe.Core.Abstractions;
namespace Febe.Tests.Browser.TestSupport;
/// <summary>Virtual clock: <see cref="Delay"/> advances time instantly, so timing can be asserted without waiting.</summary>
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<TimeSpan> 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;
}
}
}
/// <summary>A command recorded by <see cref="FakeCdpSession"/>.</summary>
public sealed record SentCommand(string Method, JsonNode? Parameters, DateTimeOffset At)
{
public string? Type => Parameters?["type"]?.GetValue<string>();
public double X => Parameters?["x"]?.GetValue<double>() ?? double.NaN;
public double Y => Parameters?["y"]?.GetValue<double>() ?? double.NaN;
public double DeltaY => Parameters?["deltaY"]?.GetValue<double>() ?? 0;
}
/// <summary>Records commands with the virtual time at which they were sent, and answers with canned results.</summary>
public sealed class FakeCdpSession(IClock clock) : ICdpSession
{
private readonly Lock _gate = new();
private readonly Dictionary<string, List<Action<JsonElement>>> _handlers = new(StringComparer.Ordinal);
private readonly List<SentCommand> _sent = [];
/// <summary>Snapshot of the commands sent so far (background pumps may add more concurrently).</summary>
public IReadOnlyList<SentCommand> Sent
{
get
{
lock (_gate)
{
return [.. _sent];
}
}
}
public void ClearSent()
{
lock (_gate)
{
_sent.Clear();
}
}
/// <summary>Returns the result for a command; null means an empty object.</summary>
public Func<string, JsonNode?, JsonNode?> Responder { get; set; } = (_, _) => null;
public Task<JsonElement> 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<JsonElement>(result.ToJsonString()));
}
public IDisposable On(string eventName, Action<JsonElement> 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<JsonElement>[] handlers;
lock (_gate)
{
handlers = _handlers.TryGetValue(eventName, out var list) ? [.. list] : [];
}
var element = JsonSerializer.Deserialize<JsonElement>(payload.ToJsonString());
foreach (var handler in handlers)
{
handler(element);
}
}
public List<SentCommand> 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();
}
}
/// <summary>Circuit breaker that only records what it receives.</summary>
public sealed class RecordingBreaker : ICircuitBreaker
{
private readonly Lock _gate = new();
private readonly List<Signal> _signals = [];
public BreakerState State => BreakerState.Normal;
public IReadOnlyList<Signal> Signals
{
get
{
lock (_gate)
{
return [.. _signals];
}
}
}
public void Report(Signal signal)
{
lock (_gate)
{
_signals.Add(signal);
}
}
}
@@ -0,0 +1,223 @@
using System.Net;
using System.Net.Sockets;
using System.Security.Cryptography;
using System.Text;
namespace Febe.Tests.Browser.TestSupport;
/// <summary>
/// Tiny local site served by the test itself on 127.0.0.1 (never Instagram): one port plays the site, another the CDN.
/// </summary>
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, "<p>Cookie impostato</p>");
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 => $"<p>Riga {i} di una pagina lunga.</p>"))
+ "<script>window.__wheel = { count: 0, trusted: true };"
+ "addEventListener('wheel', (e) => { window.__wheel.count++; window.__wheel.trusted = window.__wheel.trusted && e.isTrusted; }, { passive: true });</script>",
"/bottoni" => """
<div style="height:3000px;position:relative">
<button id="b1" aria-label="Indietro" style="position:absolute;left:100px;top:100px;width:120px;height:40px">‹</button>
<button id="b2" aria-label="Avanti" style="position:absolute;left:400px;top:300px;width:160px;height:50px">›</button>
<button id="b3" aria-label="Avanti" style="display:none">nascosto</button>
<a id="l1" href="/profilo/alice/" style="position:absolute;left:100px;top:500px">alice</a>
<a id="l2" href="/stories/alice/123/" style="position:absolute;left:300px;top:500px"><span>Storia di alice</span></a>
<button id="b4" aria-label="Coperto" style="position:absolute;left:700px;top:100px;width:100px;height:40px">x</button>
<div style="position:absolute;left:690px;top:90px;width:140px;height:70px;background:#ddd"></div>
<button id="b5" style="position:absolute;left:400px;top:2400px;width:120px;height:40px">Lontano</button>
</div>
<script>
window.__clicks = [];
window.__moves = 0;
document.addEventListener('mousemove', () => { window.__moves++; });
document.addEventListener('click', (e) => {
const t = e.target.closest('[id]');
window.__clicks.push({ id: t ? t.id : '', x: e.clientX, y: e.clientY, trusted: e.isTrusted });
});
</script>
""",
"/cattura" => "<p>Cattura</p><script>addEventListener('load', () => fetch('/api/dati.json').then((r) => r.json()).then(() => { document.title = 'caricato'; }));</script>",
"/cattura-429" => "<p>Troppe</p><script>addEventListener('load', () => fetch('/api/troppe').then((r) => r.text()));</script>",
"/cattura-attendi" => "<p>Attendi</p><script>addEventListener('load', () => fetch('/api/attendi.json').then((r) => r.json()));</script>",
"/animata" => """
<style>@keyframes giro { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
#q { width: 200px; height: 200px; margin: 100px; background: #c63; animation: giro 1s linear infinite; }</style>
<div id="q"></div>
""",
"/modulo" => """
<input id="campo" aria-label="Campo" style="position:absolute;left:200px;top:200px;width:300px;height:30px">
<script>
window.__keys = 0;
window.__clicks = 0;
document.addEventListener('keydown', () => { window.__keys++; });
document.addEventListener('mousedown', () => { window.__clicks++; });
</script>
""",
"/spa" => "<p>Applicazione</p><script>addEventListener('load', () => setTimeout(() => history.pushState({}, '', '/verifica/interna?x=1'), 300));</script>",
"/verifica" => "<h1>Verifica</h1>",
"/accesso" => "<h1>Accesso</h1>",
_ => "<p>Pagina di prova</p>",
};
private static Task HtmlAsync(HttpListenerResponse response, string body) =>
WriteAsync(response, 200, "text/html; charset=utf-8", $"<!doctype html><html lang=\"it\"><head><meta charset=\"utf-8\"><title>Prova</title></head><body>{body}</body></html>");
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);
}
}
@@ -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;
/// <summary>
/// A real Chromium on a private Xvfb display, driven by <see cref="ChromiumProcessHost"/>, plus a local test site.
/// Integration tests become inconclusive when Chromium or Xvfb is missing.
/// </summary>
public sealed class RealBrowser : IAsyncDisposable
{
/// <summary>Chromium of this development environment; FEBE_CHROMIUM overrides it.</summary>
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<string> 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<string> 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;
}
/// <summary>Environment of the browser process: Italian language and Rome time zone; no proxy for the test browser.</summary>
public static IReadOnlyDictionary<string, string?> BrowserEnvironment => new Dictionary<string, string?>
{
["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<RealBrowser> 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<string>();
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);
}
/// <summary>Opens a page of the test site and waits until it has loaded.</summary>
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<T> EvalAsync<T>(string expression) =>
(await Cdp.EvaluateAsync(expression)).Deserialize<T>()!;
/// <summary>Stops the browser but keeps the profile and the site (for restart tests).</summary>
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)
{
}
}
}
+177
View File
@@ -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<InvalidDataException>(() => 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);
}
@@ -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<ArgumentOutOfRangeException>(() => random.Between(0, 10));
Assert.ThrowsExactly<ArgumentOutOfRangeException>(() => random.Between(5, 1));
Assert.ThrowsExactly<ArgumentOutOfRangeException>(() => random.Between(1, 6, 7));
Assert.ThrowsExactly<ArgumentOutOfRangeException>(() => 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;
}
}