fleet-framework 0.1.0__tar.gz → 0.1.2__tar.gz

{fleet_framework-0.1.0 → fleet_framework-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleet-framework
-Version: 0.1.0
+Version: 0.1.2
 Summary: generic distributed-automation framework — master/worker, browser pool, anti-bot helpers, and abstract automation contracts (SERP, content, news, place, marketplace, jobs, social)
 Author: Sarper Avci
 License: MIT
@@ -23,6 +23,9 @@ Requires-Dist: DrissionPage>=4.1.0; extra == "browser"
 Requires-Dist: cryptography>=42.0.0; extra == "browser"
 Provides-Extra: cloudflare
 Requires-Dist: fleet-framework[browser]; extra == "cloudflare"
+Provides-Extra: cloak
+Requires-Dist: fleet-framework[browser]; extra == "cloak"
+Requires-Dist: cloakbrowser>=0.3; extra == "cloak"
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.27.0; extra == "otel"
 Requires-Dist: opentelemetry-sdk>=1.27.0; extra == "otel"
@@ -31,7 +34,7 @@ Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: pytest-asyncio>=0.23; extra == "test"
 Provides-Extra: all
-Requires-Dist: fleet-framework[browser,cloudflare,otel]; extra == "all"
+Requires-Dist: fleet-framework[browser,cloak,cloudflare,otel]; extra == "all"
 Dynamic: license-file
 
 # Fleet

{fleet_framework-0.1.0 → fleet_framework-0.1.2}/fleet/cli.py

@@ -208,6 +208,234 @@ def submit(
     click.echo(json.dumps(r.json()))
 
 
+@cli.command(name="describe")
+@click.argument("automation_type")
+def describe_cmd(automation_type: str) -> None:
+    """Print an automation's TaskPayload, Config and Output schemas.
+
+    Useful before `fleet run`: shows you which `-k key=value` pairs the
+    automation accepts.
+    """
+    from fleet.core.automation import (
+        BatchAutomation,
+        ContinuousAutomation,
+        catalog_doc,
+        load_entry_points,
+    )
+
+    reg = load_entry_points()
+    cls = reg.get(automation_type)
+    if cls is None:
+        available = ", ".join(sorted(reg)) or "(none installed)"
+        click.echo(
+            f"automation '{automation_type}' not registered. available: {available}",
+            err=True,
+        )
+        sys.exit(2)
+
+    if issubclass(cls, BatchAutomation):
+        kind = "BatchAutomation"
+    elif issubclass(cls, ContinuousAutomation):
+        kind = "ContinuousAutomation"
+    else:
+        kind = cls.__mro__[1].__name__
+
+    doc = catalog_doc(cls)
+    click.echo(f"name:   {cls.automation_type}")
+    click.echo(f"class:  {cls.__module__}.{cls.__name__}")
+    click.echo(f"kind:   {kind}")
+    click.echo("")
+    click.echo("config schema:")
+    click.echo(json.dumps(doc["config"], indent=2))
+    if "queue" in doc:
+        click.echo("")
+        click.echo(f"task payload schema (the shape -k / -p builds):")
+        click.echo(json.dumps(doc["queue"]["payload"], indent=2))
+    if "stream" in doc:
+        click.echo("")
+        click.echo("emit (Output) schema:")
+        click.echo(json.dumps(doc["stream"]["payload"], indent=2))
+
+
+def _coerce_kv(value: str) -> object:
+    """Best-effort JSON, falling back to the raw string. So `--kv n=10` is an
+    int while `--kv q=test` is a string and `--kv tags=[\"a\",\"b\"]` is a list."""
+    try:
+        return json.loads(value)
+    except (json.JSONDecodeError, ValueError):
+        return value
+
+
+def _parse_range(spec: str) -> list[int]:
+    """`'1-10'` → [1..10]; `'3'` → [3]."""
+    if "-" not in spec:
+        return [int(spec)]
+    lo, hi = spec.split("-", 1)
+    return list(range(int(lo), int(hi) + 1))
+
+
+@cli.command(name="run", context_settings={"show_default": True})
+@click.argument("automation_type")
+@click.option("-k", "--kv", "kvs", multiple=True, metavar="KEY=VALUE",
+              help="Set a payload field; repeatable. Values are JSON-coerced "
+                   "(so `n=10` is int, `q=test` is str). Combined into a base "
+                   "payload that --pages / --repeat / -p expand from.")
+@click.option("-p", "--payload", "payloads_json", multiple=True, metavar="JSON",
+              help="One full JSON payload per occurrence. Each becomes a "
+                   "separate task. Skips the --kv base payload.")
+@click.option("--pages", "pages_spec", default=None, metavar="N-M",
+              help="Expand the base payload into one task per integer page in "
+                   "[N, M], setting `page=N` on each.")
+@click.option("--repeat", "repeat_n", default=None, type=int,
+              help="Submit the base payload N times.")
+@click.option("--from-jsonl", "from_jsonl", default=None, type=click.Path(exists=True, dir_okay=False),
+              help="Read one JSON payload per line; each line becomes one task.")
+@click.option("--config", "config_json", default=None, metavar="JSON",
+              help="JSON config override for the automation's Config schema.")
+@click.option("--concurrency", default=1, type=int,
+              help="Max parallel tasks. Defaults to 1 for deterministic output.")
+@click.option("--timeout", default=None, type=float,
+              help="Per-task wall-clock timeout, in seconds.")
+@click.option("--duration", "duration_seconds", default=None, type=float,
+              help="ContinuousAutomation only: run for N seconds then stop. "
+                   "Default 5s when running a ContinuousAutomation.")
+@click.option("--slots", "slots", default=1, type=int,
+              help="ContinuousAutomation only: number of parallel slot "
+                   "coroutines to spawn.")
+def run_cmd(
+    automation_type: str,
+    kvs: tuple[str, ...],
+    payloads_json: tuple[str, ...],
+    pages_spec: str | None,
+    repeat_n: int | None,
+    from_jsonl: str | None,
+    config_json: str | None,
+    concurrency: int,
+    timeout: float | None,
+    duration_seconds: float | None,
+    slots: int,
+) -> None:
+    """Run an automation in-process for testing. No master/worker needed.
+
+    Each `ctx.emit(...)` is printed to stdout as one JSON line.
+
+    Works for both BatchAutomation and ContinuousAutomation; use
+    --pages/--repeat/-p for batch, --duration/--slots for continuous.
+
+    Examples:
+
+      Batch (run one task per page):
+        fleet run serp-bing -k q=anthropic -k locale=en-US --pages 1-3
+        fleet run serp-bing -p '{"q":"anthropic","page":1}'
+        fleet run cf-harvester -k url=https://example.com --repeat 5
+        fleet run serp-bing --from-jsonl queries.jsonl
+
+      Continuous (run slot for N seconds):
+        fleet run hello-world --duration 5 --slots 2
+        fleet run news-firehose --duration 30 -k feeds=https://...
+
+    Use `fleet describe <type>` to see the payload + config schemas.
+    """
+    from fleet.core.automation import BatchAutomation, ContinuousAutomation, load_entry_points
+    from fleet.core.local_runner import run_local, run_local_continuous
+
+    reg = load_entry_points()
+    cls = reg.get(automation_type)
+    if cls is None:
+        available = ", ".join(sorted(reg)) or "(none installed)"
+        click.echo(
+            f"automation '{automation_type}' not registered. available: {available}",
+            err=True,
+        )
+        sys.exit(2)
+
+    config = None
+    if config_json:
+        try:
+            config = json.loads(config_json)
+        except json.JSONDecodeError as e:
+            click.echo(f"--config: {e}", err=True)
+            sys.exit(2)
+
+    base: dict[str, object] = {}
+    for spec in kvs:
+        if "=" not in spec:
+            click.echo(f"--kv expects KEY=VALUE, got: {spec!r}", err=True)
+            sys.exit(2)
+        k, v = spec.split("=", 1)
+        base[k] = _coerce_kv(v)
+
+    if issubclass(cls, ContinuousAutomation):
+        cont_config = config if config is not None else (base or None)
+        try:
+            summary = asyncio.run(run_local_continuous(
+                cls,
+                duration_seconds=duration_seconds if duration_seconds is not None else 5.0,
+                config=cont_config,
+                slots=slots,
+            ))
+        except (ValueError, TypeError) as e:
+            click.echo(f"error: {e}", err=True)
+            sys.exit(1)
+        click.echo(f"# ran continuous: {summary['emits']} emits", err=True)
+        return
+
+    if not issubclass(cls, BatchAutomation):
+        click.echo(
+            f"'{automation_type}' is neither BatchAutomation nor ContinuousAutomation",
+            err=True,
+        )
+        sys.exit(1)
+
+    payloads: list[dict] = []
+    if payloads_json:
+        for raw in payloads_json:
+            try:
+                payloads.append(json.loads(raw))
+            except json.JSONDecodeError as e:
+                click.echo(f"--payload {raw!r}: {e}", err=True)
+                sys.exit(2)
+    if from_jsonl:
+        with open(from_jsonl) as f:
+            for lineno, line in enumerate(f, 1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    payloads.append(json.loads(line))
+                except json.JSONDecodeError as e:
+                    click.echo(f"{from_jsonl}:{lineno}: {e}", err=True)
+                    sys.exit(2)
+    if pages_spec:
+        for page in _parse_range(pages_spec):
+            payloads.append({**base, "page": page})
+    elif repeat_n is not None:
+        for _ in range(repeat_n):
+            payloads.append({**base})
+    elif not payloads:
+        payloads.append(base)
+
+    try:
+        summary = asyncio.run(run_local(
+            cls,
+            payloads,
+            config=config,
+            concurrency=concurrency,
+            timeout=timeout,
+        ))
+    except (ValueError, TypeError) as e:
+        click.echo(f"error: {e}", err=True)
+        sys.exit(1)
+
+    click.echo(
+        f"# ran {summary['ok']} ok, {summary['failed']} failed "
+        f"({len(payloads)} total)",
+        err=True,
+    )
+    if summary["failed"] and summary["ok"] == 0:
+        sys.exit(1)
+
+
 @cli.command()
 @click.option("--master-url", envvar="MASTER_URL", default=None)
 @click.option("--admin-token", envvar="FLEET_ADMIN_TOKEN", default=None)

fleet_framework-0.1.2/fleet/core/local_runner.py

@@ -0,0 +1,234 @@
+"""Run an automation in-process without a master/worker/backend stack.
+
+For CLI smoke-tests (`fleet run <type>`) and unit-style integration: spins
+up an InMemoryBackend, stubs the event bus, validates payload/config
+against the automation's declared schemas, and drives the right entry
+point. Each `ctx.emit(...)` is forwarded to an emit callback (stdout by
+default).
+
+- BatchAutomation: drives `run_one` once per payload, returns when all done.
+- ContinuousAutomation: drives `run_slot` for `duration_seconds` then signals
+  shutdown and returns.
+
+Not suitable for production — there's no DLQ, no retries, no observability.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import sys
+from typing import Any, AsyncIterator, Awaitable, Callable, Optional
+
+from pydantic import BaseModel, ValidationError
+
+from fleet.core.automation import (
+    BaseAutomation,
+    BatchAutomation,
+    ContinuousAutomation,
+    Task,
+)
+from fleet.core.context import Context
+from fleet.core.memory_backend import InMemoryBackend
+from fleet.core.metrics import SlotMetrics
+
+
+class _StubEventBus:
+    """No-op event bus for in-process runs. publish/subscribe go nowhere."""
+
+    async def publish(self, topic: str, payload: dict[str, Any]) -> None:
+        return None
+
+    async def subscribe(self, topic: str) -> AsyncIterator[dict[str, Any]]:
+        if False:
+            yield  # type: ignore[unreachable]
+
+
+def _coerce_payload(cls: type[BaseAutomation], raw: dict[str, Any]) -> BaseModel:
+    if cls.TaskPayload is None:
+        raise TypeError(
+            f"{cls.automation_type}: automation has no TaskPayload schema; "
+            "run_local() requires a BatchAutomation"
+        )
+    try:
+        return cls.TaskPayload.model_validate(raw)
+    except ValidationError as e:
+        raise ValueError(
+            f"payload does not match {cls.TaskPayload.__name__} schema: {e}"
+        ) from e
+
+
+async def _default_emit(payload: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(payload, default=str) + "\n")
+    sys.stdout.flush()
+
+
+def _build_context(
+    cls: type[BaseAutomation],
+    cfg: Any,
+    emit_cb: Callable[[dict[str, Any]], Awaitable[None]],
+    backend: InMemoryBackend,
+    log: logging.Logger,
+    worker_id: str,
+    slot_id: int = 0,
+) -> tuple[Context, asyncio.Event]:
+    shutdown = asyncio.Event()
+    ctx = Context(
+        automation_type=cls.automation_type,
+        worker_id=worker_id,
+        slot_id=slot_id,
+        config=cfg,
+        shutdown=shutdown,
+        logger=log,
+        _emit_raw=emit_cb,
+        _backend=backend,
+        _events=_StubEventBus(),  # type: ignore[arg-type]
+        _metrics=SlotMetrics(),
+        _automation_cls=cls,
+    )
+    return ctx, shutdown
+
+
+async def run_local(
+    cls: type[BaseAutomation],
+    payloads: list[dict[str, Any]],
+    *,
+    config: Optional[dict[str, Any]] = None,
+    emit: Optional[Callable[[dict[str, Any]], Awaitable[None]]] = None,
+    worker_id: str = "local",
+    concurrency: int = 1,
+    timeout: Optional[float] = None,
+    logger: Optional[logging.Logger] = None,
+) -> dict[str, int]:
+    """Drive `cls.run_one` for each payload in-process.
+
+    Returns a `{ok, failed}` summary. Validation errors raise before any
+    task runs; per-task runtime errors are logged and counted as `failed`.
+    """
+    if not issubclass(cls, BatchAutomation):
+        raise TypeError(
+            f"{cls.__name__} must be a BatchAutomation to run via run_local "
+            f"(got {cls.__mro__[1].__name__})"
+        )
+
+    automation = cls()
+    backend = InMemoryBackend()
+    log = logger or logging.getLogger(cls.automation_type or cls.__name__)
+
+    cfg = cls.Config.model_validate(config or {})
+
+    tasks = [
+        Task(id=f"local-{i}", payload=_coerce_payload(cls, p))
+        for i, p in enumerate(payloads)
+    ]
+
+    emit_cb = emit or _default_emit
+    ctx, _shutdown = _build_context(cls, cfg, emit_cb, backend, log, worker_id)
+
+    sem = asyncio.Semaphore(max(1, concurrency))
+    ok = 0
+    failed = 0
+
+    async def _run_one(task: Task) -> None:
+        nonlocal ok, failed
+        async with sem:
+            try:
+                coro = automation.run_one(task, ctx)  # type: ignore[attr-defined]
+                if timeout is not None:
+                    await asyncio.wait_for(coro, timeout=timeout)
+                else:
+                    await coro
+                ok += 1
+            except asyncio.TimeoutError:
+                failed += 1
+                log.error("task %s timed out after %.1fs", task.id, timeout)
+            except Exception as e:
+                failed += 1
+                log.exception("task %s failed: %s", task.id, e)
+
+    try:
+        await asyncio.gather(*(_run_one(t) for t in tasks))
+    finally:
+        try:
+            await automation.cleanup(ctx)
+        except Exception:
+            log.exception("cleanup() raised")
+        await backend.aclose()
+
+    return {"ok": ok, "failed": failed}
+
+
+async def run_local_continuous(
+    cls: type[BaseAutomation],
+    *,
+    duration_seconds: float = 5.0,
+    config: Optional[dict[str, Any]] = None,
+    emit: Optional[Callable[[dict[str, Any]], Awaitable[None]]] = None,
+    worker_id: str = "local",
+    slots: int = 1,
+    logger: Optional[logging.Logger] = None,
+) -> dict[str, int]:
+    """Drive `cls.run_slot` for `duration_seconds`, then signal shutdown.
+
+    Spawns `slots` parallel slot coroutines so you can smoke-test
+    cross-slot uniqueness (nonces, dedupe locks). Returns `{emits}` once
+    all slots have stopped.
+    """
+    if not issubclass(cls, ContinuousAutomation):
+        raise TypeError(
+            f"{cls.__name__} must be a ContinuousAutomation to run via "
+            f"run_local_continuous (got {cls.__mro__[1].__name__})"
+        )
+
+    automation = cls()
+    backend = InMemoryBackend()
+    log = logger or logging.getLogger(cls.automation_type or cls.__name__)
+    cfg = cls.Config.model_validate(config or {})
+
+    emit_count = 0
+
+    async def _counting_emit(payload: dict[str, Any]) -> None:
+        nonlocal emit_count
+        emit_count += 1
+        await (emit or _default_emit)(payload)
+
+    contexts = [
+        _build_context(cls, cfg, _counting_emit, backend, log, worker_id, slot_id=i)
+        for i in range(max(1, slots))
+    ]
+
+    async def _drive(ctx: Context, shutdown: asyncio.Event) -> None:
+        try:
+            await automation.run_slot(ctx)  # type: ignore[attr-defined]
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            log.exception("slot %d crashed: %s", ctx.slot_id, e)
+
+    coros = [_drive(ctx, sd) for ctx, sd in contexts]
+    tasks = [asyncio.create_task(c) for c in coros]
+
+    try:
+        await asyncio.sleep(duration_seconds)
+    finally:
+        for _ctx, sd in contexts:
+            sd.set()
+        # Give slots a brief grace period to notice shutdown.
+        try:
+            await asyncio.wait_for(asyncio.gather(*tasks, return_exceptions=True), timeout=2.0)
+        except asyncio.TimeoutError:
+            for t in tasks:
+                if not t.done():
+                    t.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+        try:
+            await automation.cleanup(contexts[0][0])
+        except Exception:
+            log.exception("cleanup() raised")
+        await backend.aclose()
+
+    return {"emits": emit_count}
+
+
+__all__ = ["run_local", "run_local_continuous"]

{fleet_framework-0.1.0 → fleet_framework-0.1.2}/fleet_browser/browser.py

@@ -13,6 +13,12 @@ from typing import Optional
 import psutil
 from DrissionPage import ChromiumOptions, ChromiumPage
 
+from fleet_browser.cloak import (
+    CLOAK_IGNORE_DEFAULT_ARGS,
+    cloak_stealth_args,
+    ensure_cloak_binary,
+    resolve_engine,
+)
 from fleet_browser.proxy_extension import build_proxy_auth_extension, parse_proxy_url
 from fleet_browser.stealth import Stealth
 
@@ -120,6 +126,39 @@ class BrowserConfig:
 
     extra_args: tuple[str, ...] = ()
 
+    engine: str = "auto"
+    """Which Chromium build to launch. `"auto"` picks `"cloak"` when the
+    cloakbrowser package is installed, else falls back to `"chrome"`.
+    Set explicitly to override:
+      - `"chrome"`: use the system Chromium / Brave / Thorium auto-detect path
+      - `"cloak"`: use the CloakBrowser patched binary (downloads on first
+        use, raises if `cloakbrowser` isn't installed)
+    Cloak applies source-level canvas/WebGL/audio/font/WebRTC patches that
+    JS-level stealth can't reach. Stack FingerprintStealth on top to add
+    per-launch UA/version diversity from the uaforge corpus."""
+
+    cloak_cache_dir: Optional[str] = None
+    """Override the cloak binary cache dir (default ~/.cloakbrowser/)."""
+
+    cloak_fingerprint_seed: Optional[int] = None
+    """Force a specific cloak --fingerprint=N seed. Default: random per
+    launch. Pin a seed for reproducible tests."""
+
+    cloak_platform: str = "windows"
+    """`--fingerprint-platform` flag for cloak's binary. Must match the
+    OS family FingerprintStealth's UA claims (uaforge default is Windows).
+    Set 'macos' if you switch uaforge to a Mac corpus."""
+
+    cloak_timezone: Optional[str] = None
+    """IANA timezone for cloak's `--fingerprint-timezone` flag. Set when
+    using residential proxies so the spoofed timezone matches the egress
+    geo (otherwise CF flags the mismatch). Falls back to system tz."""
+
+    cloak_webrtc_ip: Optional[str] = None
+    """Public IP cloak should advertise via WebRTC. Set to the proxy's exit
+    IP when using residential — otherwise WebRTC leaks your real LAN IP
+    and CF correlates the mismatch."""
+
 
 class ChromiumWorker:
 
@@ -133,9 +172,16 @@ class ChromiumWorker:
         if self.page is not None:
             return self.page
 
-        binary = self.config.browser_binary or _find_browser_binary(
-            prefer=self.config.prefer_browser,
-        )
+        engine = resolve_engine(self.config.engine)
+        if engine == "cloak":
+            # Caller may still pin browser_binary explicitly — honor it.
+            binary = self.config.browser_binary or ensure_cloak_binary(
+                self.config.cloak_cache_dir
+            )
+        else:
+            binary = self.config.browser_binary or _find_browser_binary(
+                prefer=self.config.prefer_browser,
+            )
 
         self._user_data_dir = Path(tempfile.mkdtemp(prefix="chromium-worker-"))
         self._owns_user_data_dir = True
@@ -147,6 +193,23 @@ class ChromiumWorker:
         opts.set_user_data_path(str(self._user_data_dir))
         opts.set_argument(f"--window-size={self.config.window_size[0]},{self.config.window_size[1]}")
 
+        if engine == "cloak":
+            for arg in cloak_stealth_args(
+                platform=self.config.cloak_platform,
+                timezone=self.config.cloak_timezone,
+                webrtc_ip=self.config.cloak_webrtc_ip,
+                seed=self.config.cloak_fingerprint_seed,
+            ):
+                opts.set_argument(arg)
+            # Suppress Chromium defaults that leak automation signals.
+            # DrissionPage doesn't expose ignore_default_args; pass as
+            # --disable-features-replacement via plain args. The cloak
+            # binary recognises --no-enable-automation as an inversion.
+            for kill in CLOAK_IGNORE_DEFAULT_ARGS:
+                # Chromium accepts --disable-foo as the inverse of --enable-foo.
+                inv = kill.replace("--enable-", "--disable-", 1)
+                opts.set_argument(inv)
+
         # HttpsUpgrades is off so self-signed HTTPS (TokenServer) isn't rewritten.
         # Brave's ad/tracker/sync features both pollute the fingerprint and
         # sometimes break Turnstile's iframe; disable them when running Brave.

fleet_framework-0.1.2/fleet_browser/cloak.py

@@ -0,0 +1,120 @@
+"""Cloak engine integration — uses the CloakBrowser patched Chromium binary.
+
+CloakBrowser is a separately-licensed binary (free for own-business use,
+OEM license required for browser-as-a-service distribution). See:
+  https://github.com/CloakHQ/CloakBrowser
+
+The wrapper Python package is MIT-licensed and pulled in via the optional
+extra: `pip install fleet-framework[cloak]`. The binary is downloaded on
+first use to ~/.cloakbrowser/ (override with CLOAKBROWSER_CACHE_DIR).
+
+Combining cloak (source-level canvas/WebGL/audio/font/WebRTC patches) with
+FingerprintStealth (CDP-level UA + Sec-CH-UA + navigator overrides) gives:
+  - Deep, JS-undetectable spoofing of low-level signals (cloak)
+  - Per-launch diversity of UA versions from the uaforge corpus (FingerprintStealth)
+
+That diversity matters: cloak's binary patches use the latest Chrome only,
+so without the CDP layer every harvest looks like the same Chrome version.
+With CDP override on top, each launch picks a different version from uaforge
+while keeping the renderer-level fingerprint coherent.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import random
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+_CLOAK_AVAILABLE: Optional[bool] = None
+
+
+def cloak_available() -> bool:
+    """Return True if the cloakbrowser wrapper package is importable.
+
+    The binary may still need to be downloaded — that's `ensure_cloak_binary`'s
+    job. This is just the cheap import probe.
+    """
+    global _CLOAK_AVAILABLE
+    if _CLOAK_AVAILABLE is None:
+        try:
+            import cloakbrowser  # noqa: F401
+            _CLOAK_AVAILABLE = True
+        except ImportError:
+            _CLOAK_AVAILABLE = False
+    return _CLOAK_AVAILABLE
+
+
+def resolve_engine(name: str) -> str:
+    """Resolve `engine="auto"` to `"cloak"` if available, else `"chrome"`."""
+    if name != "auto":
+        return name
+    return "cloak" if cloak_available() else "chrome"
+
+
+def ensure_cloak_binary(cache_dir: Optional[str] = None) -> str:
+    """Return path to the patched Chromium binary; download if missing.
+
+    Delegates to cloakbrowser.download.ensure_binary. ~250-400 MB download
+    on first use; cached at ~/.cloakbrowser/ (or `cache_dir`) thereafter.
+    Cloakbrowser checks for updates hourly when launched.
+    """
+    if not cloak_available():
+        raise RuntimeError(
+            "engine='cloak' requires cloakbrowser. "
+            "Install with: pip install fleet-framework[cloak]"
+        )
+    if cache_dir:
+        os.environ.setdefault("CLOAKBROWSER_CACHE_DIR", str(Path(cache_dir).expanduser()))
+    from cloakbrowser.download import ensure_binary
+    path = ensure_binary()
+    return str(path)
+
+
+def cloak_stealth_args(
+    *,
+    platform: str = "windows",
+    timezone: Optional[str] = None,
+    webrtc_ip: Optional[str] = None,
+    seed: Optional[int] = None,
+) -> tuple[str, ...]:
+    """Return Chromium command-line flags that activate cloak's source patches.
+
+    The `seed` drives canvas/WebGL/audio noise variation per-launch. Pass a
+    stable seed if you need reproducibility (e.g. testing). `platform` should
+    match what FingerprintStealth's UA claims — keep them aligned (default
+    'windows' matches uaforge's Windows corpus).
+    """
+    s = seed if seed is not None else random.randint(10000, 99999)
+    args = [
+        f"--fingerprint={s}",
+        f"--fingerprint-platform={platform}",
+    ]
+    if timezone:
+        args.append(f"--fingerprint-timezone={timezone}")
+    if webrtc_ip:
+        args.append(f"--fingerprint-webrtc-ip={webrtc_ip}")
+    return tuple(args)
+
+
+CLOAK_IGNORE_DEFAULT_ARGS: tuple[str, ...] = (
+    "--enable-automation",
+    "--enable-unsafe-swiftshader",
+)
+"""Default args Playwright/DrissionPage pass that leak automation signals.
+
+`--enable-automation` exposes `navigator.webdriver=true`. `--enable-unsafe-
+swiftshader` forces SwiftShader's distinctive WebGL renderer string. We pass
+these to Chromium's launch options so DrissionPage stops setting them."""
+
+
+__all__ = [
+    "CLOAK_IGNORE_DEFAULT_ARGS",
+    "cloak_available",
+    "cloak_stealth_args",
+    "ensure_cloak_binary",
+    "resolve_engine",
+]

{fleet_framework-0.1.0 → fleet_framework-0.1.2}/fleet_browser/fingerprint.py

@@ -180,7 +180,12 @@ class FingerprintFactory:
                 "pip install git+https://github.com/sarperavci/uaforge.git"
             )
         if allowed_os is None:
-            allowed_os = (_detect_host_os(),)
+            # Default to Windows regardless of host. The host's actual OS
+            # is irrelevant — what matters is which UA + client-hint corpus
+            # the fleet's fingerprints are drawn from. Windows is the highest-
+            # entropy population (~70% of real browsing traffic) and matches
+            # the cloak engine's `--fingerprint-platform=windows` default.
+            allowed_os = ("windows",)
         self._gen = UserAgentGenerator(seed=seed)
         self._rng = random.Random(seed)
         self._min_chromium = min_chromium_version

{fleet_framework-0.1.0 → fleet_framework-0.1.2}/fleet_cloudflare/replay.py

@@ -1,4 +1,4 @@
-"""Replay helpers: turn a HarvestResult into a pre-configured HTTP client.
+"""Replay helpers: turn a HarvestResult into a pre-configured async HTTP client.
 
 Cloudflare ties the clearance cookie to the (IP, UA, Sec-CH-UA-*) tuple
 that earned it. Replaying with the wrong combination earns a fresh
@@ -26,7 +26,7 @@ def replay_with_httpx(
     proxy: Optional[str] = None,
     timeout: float = 30.0,
 ) -> Any:
-    """Return an `httpx.Client` configured with the harvested cookie + headers.
+    """Return an `httpx.AsyncClient` configured with the harvested cookie + headers.
 
     Apply `result.cookies` scoped to the target URL's host, set
     `result.headers` as defaults, and optionally route through a proxy
@@ -39,7 +39,7 @@ def replay_with_httpx(
     cookies = httpx.Cookies()
     for name, value in (result.cookies or {}).items():
         cookies.set(name, value, domain=domain, path="/")
-    return httpx.Client(
+    return httpx.AsyncClient(
         headers={**(result.headers or {})},
         cookies=cookies,
         timeout=timeout,
@@ -56,21 +56,21 @@ def replay_with_curl_cffi(
     timeout: float = 30.0,
     impersonate: str = "chrome",
 ) -> Any:
-    """Return a `curl_cffi.requests.Session` configured the same way.
+    """Return a `curl_cffi.requests.AsyncSession` configured the same way.
 
     Requires `curl_cffi` installed by the caller. Useful when the target
     inspects TLS/JA3 — curl_cffi's `impersonate=` flag matches Chrome's
     fingerprint at the TLS layer, which a vanilla httpx client can't.
     """
     try:
-        from curl_cffi import requests as cffi_requests
+        from curl_cffi.requests import AsyncSession
     except ImportError as e:
         raise RuntimeError(
             "replay_with_curl_cffi requires `pip install curl_cffi`"
         ) from e
 
     domain = _cookie_domain(target_url)
-    sess = cffi_requests.Session(impersonate=impersonate, timeout=timeout)
+    sess = AsyncSession(impersonate=impersonate, timeout=timeout)
     sess.headers.update(result.headers or {})
     for name, value in (result.cookies or {}).items():
         sess.cookies.set(name, value, domain=domain, path="/")

{fleet_framework-0.1.0 → fleet_framework-0.1.2}/fleet_framework.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleet-framework
-Version: 0.1.0
+Version: 0.1.2
 Summary: generic distributed-automation framework — master/worker, browser pool, anti-bot helpers, and abstract automation contracts (SERP, content, news, place, marketplace, jobs, social)
 Author: Sarper Avci
 License: MIT
@@ -23,6 +23,9 @@ Requires-Dist: DrissionPage>=4.1.0; extra == "browser"
 Requires-Dist: cryptography>=42.0.0; extra == "browser"
 Provides-Extra: cloudflare
 Requires-Dist: fleet-framework[browser]; extra == "cloudflare"
+Provides-Extra: cloak
+Requires-Dist: fleet-framework[browser]; extra == "cloak"
+Requires-Dist: cloakbrowser>=0.3; extra == "cloak"
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.27.0; extra == "otel"
 Requires-Dist: opentelemetry-sdk>=1.27.0; extra == "otel"
@@ -31,7 +34,7 @@ Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: pytest-asyncio>=0.23; extra == "test"
 Provides-Extra: all
-Requires-Dist: fleet-framework[browser,cloudflare,otel]; extra == "all"
+Requires-Dist: fleet-framework[browser,cloak,cloudflare,otel]; extra == "all"
 Dynamic: license-file
 
 # Fleet

{fleet_framework-0.1.0 → fleet_framework-0.1.2}/fleet_framework.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ fleet/core/context.py
 fleet/core/contract.py
 fleet/core/country_presets.py
 fleet/core/events.py
+fleet/core/local_runner.py
 fleet/core/logging.py
 fleet/core/memory_backend.py
 fleet/core/metrics.py
@@ -41,6 +42,7 @@ fleet/worker/ws_client.py
 fleet_browser/__init__.py
 fleet_browser/browser.py
 fleet_browser/cert.py
+fleet_browser/cloak.py
 fleet_browser/fingerprint.py
 fleet_browser/humanizer.py
 fleet_browser/pool.py

{fleet_framework-0.1.0 → fleet_framework-0.1.2}/fleet_framework.egg-info/requires.txt

@@ -9,12 +9,16 @@ psutil>=5.9.0
 click>=8.1.0
 
 [all]
-fleet-framework[browser,cloudflare,otel]
+fleet-framework[browser,cloak,cloudflare,otel]
 
 [browser]
 DrissionPage>=4.1.0
 cryptography>=42.0.0
 
+[cloak]
+fleet-framework[browser]
+cloakbrowser>=0.3
+
 [cloudflare]
 fleet-framework[browser]
 

{fleet_framework-0.1.0 → fleet_framework-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fleet-framework"
-version = "0.1.0"
+version = "0.1.2"
 description = "generic distributed-automation framework — master/worker, browser pool, anti-bot helpers, and abstract automation contracts (SERP, content, news, place, marketplace, jobs, social)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,6 +30,10 @@ browser = [
 cloudflare = [
     "fleet-framework[browser]",
 ]
+cloak = [
+    "fleet-framework[browser]",
+    "cloakbrowser>=0.3",
+]
 otel = [
     "opentelemetry-api>=1.27.0",
     "opentelemetry-sdk>=1.27.0",
@@ -40,7 +44,7 @@ test = [
     "pytest-asyncio>=0.23",
 ]
 all = [
-    "fleet-framework[browser,cloudflare,otel]",
+    "fleet-framework[browser,cloudflare,cloak,otel]",
 ]
 
 [project.scripts]