Skip to content

README.md

Latest commit

 

History

History
187 lines (135 loc) · 8.72 KB

README.md

File metadata and controls

187 lines (135 loc) · 8.72 KB
Raw

⚡ BrowserSync

Deterministic, Enterprise-Hardened Realtime Browser Synchronization Engine for Chromium over Chrome DevTools Protocol (CDP)

.NET 9.0 License: MIT Tests: 34 Passed Architecture: 3--Plane

🌐 Select Language / Chọn Ngôn Ngữ / 选择语言

English • Tiếng Việt • 简体中文

🌟 Overview

BrowserSync is an enterprise-grade real-time browser synchronization engine. It enables controlling a primary browser instance (Master Controller) and mirroring user interactions with sub-millisecond latency and pixel-perfect precision across multiple secondary browser instances (Slaves) via the Chrome DevTools Protocol (CDP).

Engineered to industrial standards, BrowserSync features a 3-Plane Protocol Separation, 3-Lane Deterministic Event Routing, a 50,000-slot In-Memory Event Journal, Dual-Tier Bounded Recovery, and Stable DOM Element Identity Tracking.

🎬 Live Synchronization Demo

▶️ Click to Watch BrowserSync Realtime Demo

▶️ Click to Watch Live Synchronization Video Demo (assets/browsersync-live-demo.mp4)

Watch BrowserSync orchestrate multi-instance browser sessions with sub-millisecond synchronization.

graph TD
    subgraph Master ["Master Controller (Capture Plane)"]
        CDP_M["CDP Observer & TargetManager"]
        DOM_INJ["DOM Instrumentation Script"]
        DOM_INJ -->|bindingCalled| CDP_M
    end

    subgraph Core ["BrowserSync Protocol Core"]
        SEQ["GlobalSequencer (Monotonic Epoch + Seq)"]
        JOURNAL["EventJournal RingBuffer (50,000 slots)"]
        COORD["SequenceCoordinator (3-Lane Routing + Barrier)"]
        
        CDP_M -->|Data Plane| SEQ
        SEQ --> JOURNAL
        JOURNAL --> COORD
        CDP_M -->|Control Plane| CTRL_ROUTER["Control Plane Router"]
    end

    subgraph Slaves ["Slaves Execution Pool (Replay & Dispatch Plane)"]
        DISP["SyncDispatcher"]
        NODE1["SlaveNode #1 (StreamController + Actor)"]
        NODE2["SlaveNode #2 (StreamController + Actor)"]
        
        COORD --> DISP
        DISP --> NODE1
        DISP --> NODE2
    end
Loading

🚀 Core Architectural Highlights

1. 3-Plane Protocol Separation

  • Data Plane (23 Semantic Sync Events): Strictly ordered by GlobalSequence, persisted in the EventJournal ring buffer, routed through a 3-lane priority queue.
  • Control Plane (ControlMessage): ApplicationReadyMessage, HeartbeatMessage, ClockSyncMessage, and BackpressureSignal execute out-of-band with zero sequence overhead and zero journal pollution.
  • Recovery Plane (RecoveryMessage): Dedicated ReplayRequestMessage, ReplayBatchMessage, SnapshotRequestMessage, and StateSnapshotMessage orchestrate packet gap repairs and state synchronization.

2. 3-Lane Deterministic Routing & Viewport Barriers

  • Lane 0 (Lossless FIFO): Prioritizes critical actions (MouseDown, MouseUp, KeyDown, TextInput, Navigate, TabCreated).
  • Lane 1 (High-Fidelity Motion): Optimized for real-time interactive canvas drawing, drag-and-drop, and touch gestures.
  • Lane 2 (Adaptive Coalescing): Coalesces continuous ViewportResize and idle mouse events. Ordering Barrier: Enforces a synchronous flush of pending resize events before releasing any subsequent critical action to prevent coordinate drift.

3. Dual-Tier Bounded Recovery

  • Tier 1 (In-Memory Journal Replay): Detects network gaps and replays historical events directly from the journal. The ReplayBatch validator enforces strict contiguity and epoch matching.
  • Tier 2 (Canonical State Snapshot): Automatically escalates to full state snapshot reconstruction when journal retention limits are exceeded.

4. DOM Semantics & Vietnamese IME Support

  • Stable Element Identity: Identifies DOM elements using persistent data-browser-sync-id attributes, avoiding brittle CSS path dependencies.
  • Semantic Separation: Decouples FocusChanged (Active Element), SelectionChanged (DOM Selection & Caret Range), EditableStateChanged (Committed Form Value), and ImeComposition (Telex/VNI input methods).
  • Clipboard Sync: Direct synchronization of paste payloads via ClipboardPastePayload.

5. Process Safety & Anti-Zombie Invariants

  • Dual-validates Chromium process identity via PID and ProcessStartTimeUtc (Invariants 10 & 14) to protect against PID reuse hazards.

6. Zero Automation Footprint & Undetected CAPTCHA Bypass

  • No Selenium / Playwright / ChromeDriver Dependencies: Interacts directly with genuine browser sessions through raw Chrome DevTools Protocol (CDP) WebSocket sessions.
  • Zero Bot Fingerprints: Eliminates navigator.webdriver flags, synthetic automation runtime signatures, and fake user-agent spoofing.
  • Undetected CAPTCHA Traversal: Natively bypasses strict anti-bot systems such as Cloudflare Turnstile, Cloudflare Challenge (5s shield), reCAPTCHA, and hCaptcha across all synchronized slave browsers simultaneously without risk of blocks.
BrowserSync Cloudflare Turnstile & CAPTCHA Bypass Demonstration

Figure 1: BrowserSync natively passing Cloudflare Turnstile verification simultaneously across synchronized instances.

📁 Repository Structure

BrowserSync/
├── assets/                     # Visual assets, architecture diagrams & demo proofs
├── csharp/                     # C# .NET 9 Implementation
│   ├── src/                    # App, Capture, Cdp, Core, State, Sync projects
│   ├── tests/                  # xUnit Test Suite (34 tests)
│   ├── BrowserSync.slnx        # Solution file
│   └── Start-BrowserSync.bat   # C# 1-Click Launcher
├── python/                     # Python 3 Implementation
│   ├── browsersync/            # app, capture, cdp, core, state, sync packages
│   ├── tests/                  # pytest Suite (12 tests)
│   ├── requirements.txt        # Python dependencies (websockets, pytest)
│   └── Start-BrowserSync.bat   # Python 1-Click Launcher
├── test_page.html              # Interactive benchmark for Canvas, Forms, IME, Tabs & Panning
├── Start-BrowserSync-CSharp.bat# Root shortcut to run C# Engine
├── Start-BrowserSync-Python.bat# Root shortcut to run Python Engine
├── README.md                   # English Documentation (Default)
├── README.vn.md                # Tài liệu Tiếng Việt
└── README.zh.md                # 简体中文 文档

📊 Verification Matrix

Automated test suites across both runtimes execute with a 100% Pass Rate:

Test Group Verification Target C# (.NET 9) Python (3.14)
Protocol Separation Sequence isolation across Data, Control, Recovery 34 Passed 12 Passed
Ordering Barriers ViewportResize barrier before critical inputs PASSED PASSED
Replay Validation Strict contiguity and epoch validation for ReplayBatch PASSED PASSED
Invariants 1-14 Monotonic ordering, Process Safety & PID Reuse PASSED PASSED
Workloads A-D 100k event burst, motion coalescing, fault injection PASSED PASSED
Micro-Telemetry $T_0 \to T_5$ latency tracking with sub-ms p95/p99 PASSED PASSED

🛠️ Quickstart

Prerequisites:

  • OS: Windows 10 / 11 or Windows Server.
  • C# Runtime: .NET 9.0 SDK or higher.
  • Python Runtime: Python 3.10+ with websockets.
  • Browser: Google Chrome or Microsoft Edge.

1-Click Launch:

  • Run C# Engine: Run .\Start-BrowserSync-CSharp.bat
  • Run Python Engine: Run .\Start-BrowserSync-Python.bat

Or via CLI:

C# (.NET 9):

cd csharp
dotnet build
dotnet test tests/BrowserSync.Core.Tests/BrowserSync.Core.Tests.csproj
dotnet run --project src/BrowserSync.App/BrowserSync.App.csproj

Python 3:

cd python
pip install -r requirements.txt
pytest tests
python browsersync/app/main.py