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

+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),
};
}