driverclient 0.2.0__py3-none-any.whl

driverclient/core/http.py

@@ -0,0 +1,304 @@
+"""
+client/http.py — HTTP helpers for Driver Server client.
+Stdlib only — no external dependencies (works without venv on target machines).
+Supports streaming downloads, retry with exponential backoff, SHA-256 verification,
+and multipart driver package uploads.
+"""
+import hashlib
+import io
+import json
+import tarfile
+import time
+import urllib.error
+import urllib.request
+import uuid
+from pathlib import Path
+
+from driverclient.config import get
+
+
+# ── Sentinel for rate-limit responses ────────────────────────────────────────
+
+class RateLimitedError(Exception):
+    """HTTP 429 received; retry_after is the suggested wait in seconds."""
+    def __init__(self, retry_after: float = 5.0):
+        self.retry_after = retry_after
+        super().__init__(f"Rate limited — retry after {retry_after:.0f}s")
+
+
+class BadRequestError(Exception):
+    """4xx response from local_repo — permanent error, do not retry."""
+    def __init__(self, status_code: int, message: str = ""):
+        self.status_code = status_code
+        super().__init__(f"HTTP {status_code}: {message}")
+
+
+def _headers() -> dict:
+    cfg = get()
+    h = {"Content-Type": "application/json"}
+    key = cfg.get("node_key", "")
+    if key:
+        h["X-Node-Key"] = key
+    return h
+
+
+def _retry(fn, max_retries: int = 3):
+    """
+    Call fn(); on failure sleep and retry up to max_retries times.
+
+    Retry schedule:
+      - HTTP 429 (RateLimitedError): sleep the server-suggested Retry-After
+        (default 5 s) then retry. Uses a higher ceiling (10 attempts) so a
+        burst of drivers can all make it through without losing any.
+      - Other errors: exponential backoff 2^attempt seconds, up to max_retries.
+    """
+    rate_limit_retries = 0
+    MAX_RATE_LIMIT_RETRIES = 10
+    attempt = 0
+
+    while True:
+        try:
+            return fn()
+        except BadRequestError:
+            raise  # never retry — local_repo itself rejected it
+        except RateLimitedError as e:
+            rate_limit_retries += 1
+            if rate_limit_retries > MAX_RATE_LIMIT_RETRIES:
+                raise
+            wait = e.retry_after
+            print(f"  [rate-limit] server busy — waiting {wait:.0f}s then retrying "
+                  f"(attempt {rate_limit_retries}/{MAX_RATE_LIMIT_RETRIES})…")
+            time.sleep(wait)
+        except Exception:
+            attempt += 1
+            if attempt >= max_retries:
+                raise
+            wait = 2 ** (attempt - 1)
+            time.sleep(wait)
+
+
+def http_get(url: str, timeout: int | None = None) -> dict:
+    cfg = get()
+    t = timeout or cfg["timeout_short"]
+    req = urllib.request.Request(url, headers=_headers())
+    with urllib.request.urlopen(req, timeout=t) as resp:
+        return json.loads(resp.read())
+
+
+def http_post(url: str, data: dict, timeout: int | None = None) -> dict:
+    cfg = get()
+    t = timeout or cfg["timeout_medium"]
+    body = json.dumps(data).encode()
+    req = urllib.request.Request(url, data=body, headers=_headers(), method="POST")
+    with urllib.request.urlopen(req, timeout=t) as resp:
+        return json.loads(resp.read())
+
+
+def http_post_retry(url: str, data: dict, timeout: int | None = None,
+                    max_retries: int = 3) -> dict:
+    return _retry(lambda: http_post(url, data, timeout), max_retries)
+
+
+def http_upload_package(
+    url: str,
+    node_key: str,
+    metadata: dict,
+    archive_bytes: bytes,
+    archive_name: str,
+    content_encoding: str,
+    timeout: int | None = None,
+    max_retries: int = 3,
+) -> dict:
+    """
+    POST a driver package archive to /submit as multipart/form-data.
+    archive_bytes: compressed tar bytes (or plain tar if zstd unavailable).
+    content_encoding: "zstd" | "identity" — describes the archive compression.
+    Returns the parsed JSON response dict.
+    Retries up to max_retries times with exponential backoff.
+    """
+    cfg = get()
+    t = timeout or cfg["timeout_medium"]
+
+    boundary = uuid.uuid4().hex
+    meta_bytes = json.dumps({**metadata, "archive_encoding": content_encoding}).encode()
+
+    body = (
+        f"--{boundary}\r\n"
+        f'Content-Disposition: form-data; name="metadata"\r\n'
+        f"Content-Type: application/json\r\n\r\n"
+    ).encode() + meta_bytes + b"\r\n"
+
+    body += (
+        f"--{boundary}\r\n"
+        f'Content-Disposition: form-data; name="files"; filename="{archive_name}"\r\n'
+        f"Content-Type: application/octet-stream\r\n"
+        f"Content-Encoding: {content_encoding}\r\n\r\n"
+    ).encode() + archive_bytes + b"\r\n"
+
+    body += f"--{boundary}--\r\n".encode()
+
+    headers = {
+        "X-Node-Key": node_key,
+        "Content-Type": f"multipart/form-data; boundary={boundary}",
+        "X-Archive-Format": "tar",
+    }
+
+    def _do_upload():
+        req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=t) as resp:
+                return json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            if e.code == 429:
+                # Parse Retry-After header if present (seconds or HTTP-date).
+                try:
+                    retry_after = float(e.headers.get("Retry-After", "5"))
+                except ValueError:
+                    retry_after = 5.0
+                raise RateLimitedError(retry_after) from e
+            if 400 <= e.code < 500:
+                raise BadRequestError(e.code, e.read().decode(errors="replace")) from e
+            raise
+
+    result = _retry(_do_upload, max_retries)
+
+    status = result.get("status", "")
+    if status in ("already_approved", "already_present"):
+        print("  [skip] already in library (SHA known-clean)")
+    else:
+        print(f"  [submit] job_id={result.get('job_id', '?')} status={status}")
+
+    return result
+
+
+def http_download(url: str, dest: Path, sha256_expected: str,
+                  timeout: int | None = None) -> bool:
+    """
+    Download a file to dest, streaming in 64 KB chunks directly to disk.
+    SHA-256 is computed incrementally as data arrives — the entire file is never
+    held in RAM.  Progress (bytes received) is printed to stdout.
+    Decompresses zstd on-the-fly if the server sends Content-Encoding: zstd.
+    Returns True on success, False on hash mismatch or error.
+    """
+    cfg = get()
+    t = timeout or cfg["timeout_long"]
+    headers = {**_headers(), "Accept-Encoding": "zstd"}
+
+    req = urllib.request.Request(url, headers=headers)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    tmp = dest.with_suffix(dest.suffix + ".part")
+    try:
+        with urllib.request.urlopen(req, timeout=t) as resp:
+            encoding = resp.headers.get("Content-Encoding", "")
+            content_length = resp.headers.get("Content-Length")
+            total = int(content_length) if content_length else None
+
+            hasher = hashlib.sha256()
+            received = 0
+            CHUNK = 65536
+
+            if encoding == "zstd":
+                try:
+                    import zstandard as zstd
+                except ImportError:
+                    print(
+                        f"  [ERROR] zstandard package required to decompress {dest.name} "
+                        "— install it with: pip install zstandard"
+                    )
+                    return False
+
+                dctx = zstd.ZstdDecompressor()
+                with open(tmp, "wb") as fh:
+                    with dctx.stream_writer(fh, closefd=False) as writer:
+                        while chunk := resp.read(CHUNK):
+                            writer.write(chunk)
+                            received += len(chunk)
+                            _print_progress(dest.name, received, total)
+
+                with open(tmp, "rb") as fh:
+                    while chunk := fh.read(CHUNK):
+                        hasher.update(chunk)
+            else:
+                with open(tmp, "wb") as fh:
+                    while chunk := resp.read(CHUNK):
+                        fh.write(chunk)
+                        hasher.update(chunk)
+                        received += len(chunk)
+                        _print_progress(dest.name, received, total)
+
+    except Exception as e:
+        tmp.unlink(missing_ok=True)
+        print(f"  [ERROR] Download failed {dest.name}: {e}")
+        return False
+
+    actual = hasher.hexdigest()
+    if actual != sha256_expected:
+        tmp.unlink(missing_ok=True)
+        print(f"  [ERROR] Hash mismatch {dest.name}: "
+              f"expected {sha256_expected[:8]}… got {actual[:8]}…")
+        return False
+
+    tmp.replace(dest)
+    print(f"  [done]  {dest.name} ({received:,} bytes)")
+    return True
+
+
+def http_download_retry(url: str, dest: Path, sha256_expected: str,
+                        timeout: int | None = None, max_retries: int = 3) -> bool:
+    for attempt in range(max_retries):
+        if http_download(url, dest, sha256_expected, timeout):
+            return True
+        if attempt < max_retries - 1:
+            time.sleep(2 ** attempt)
+    return False
+
+
+def pack_driver_archive(
+    package_dir: Path,
+    source_name: str,
+    allowed_extensions: list[str],
+) -> tuple[bytes, str, str]:
+    """
+    Pack files from package_dir into a tar archive, then compress with zstd.
+    allowed_extensions: [".inf"] | ["*"] | [".inf", ".sys", ".cat"] etc.
+    Returns (archive_bytes, archive_filename, content_encoding).
+    Falls back to uncompressed tar if zstandard is not installed.
+    """
+    filter_all = allowed_extensions == ["*"]
+    files = [
+        f for f in package_dir.rglob("*")
+        if f.is_file() and (filter_all or f.suffix.lower() in allowed_extensions)
+    ]
+
+    if not files:
+        # Nothing matched — fall back to all files so we don't submit empty packages
+        files = [f for f in package_dir.rglob("*") if f.is_file()]
+
+    tar_buf = io.BytesIO()
+    with tarfile.open(fileobj=tar_buf, mode="w") as tar:
+        for f in files:
+            tar.add(f, arcname=f.relative_to(package_dir))
+    tar_bytes = tar_buf.getvalue()
+
+    try:
+        import zstandard as zstd
+        cctx = zstd.ZstdCompressor(level=3)
+        archive_bytes = cctx.compress(tar_bytes)
+        archive_name = f"{source_name}.tar.zst"
+        encoding = "zstd"
+    except ImportError:
+        archive_bytes = tar_bytes
+        archive_name = f"{source_name}.tar"
+        encoding = "identity"
+
+    return archive_bytes, archive_name, encoding
+
+
+def _print_progress(name: str, received: int, total: int | None):
+    if total:
+        pct = received * 100 // total
+        print(f"\r  {name}: {pct:3d}% ({received:,}/{total:,} bytes)", end="", flush=True)
+    else:
+        if received % (512 * 1024) == 0:
+            print(f"\r  {name}: {received:,} bytes…", end="", flush=True)

driverclient/events.py

@@ -0,0 +1,141 @@
+"""
+driverclient/events.py — structured, real-time progress events.
+
+Every op reports progress by calling emit()/start()/progress()/ok()/... with a
+ClientEvent. By default an event is formatted to a line and printed (plus routed
+through logging.getLogger("driverclient")), reproducing the pre-0.2.0 terminal
+output so nothing regresses when no consumer is attached.
+
+An embedding application (e.g. a PyQt front-end) installs its own sink for the
+duration of a run via DriverClient.run(on_event=...) — see using_sink(). The sink
+receives ClientEvent objects synchronously, in real time, on the calling thread.
+
+`phase` and `status` are a FIXED, DOCUMENTED vocabulary — this is the interface a
+GUI binds to. Treat any change to PHASES / STATUSES as an API change.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass, field
+from typing import Callable, Iterator
+
+# ── Vocabulary (documented interface — see README events table) ──────────────
+PHASES = (
+    "scan", "resolve", "install", "capture", "windows_update",
+    "dump", "upload", "pipeline", "done",
+)
+STATUSES = ("start", "progress", "ok", "warn", "error", "done")
+
+_log = logging.getLogger("driverclient")
+
+
+@dataclass(frozen=True)
+class ClientEvent:
+    """One progress event. Immutable so a sink can safely stash/forward it."""
+    phase:   str
+    status:  str
+    message: str            = ""
+    current: int | None     = None
+    total:   int | None     = None
+    percent: float | None   = None
+    data:    dict           = field(default_factory=dict)
+    ts:      float          = field(default_factory=time.time)
+
+    def to_dict(self) -> dict:
+        """Plain dict for transport across a Qt signal or into a log record."""
+        return asdict(self)
+
+
+EventSink = Callable[[ClientEvent], None]
+
+_sink: EventSink | None = None
+
+
+# ── Sink management ──────────────────────────────────────────────────────────
+
+def set_sink(sink: EventSink | None) -> None:
+    """Install a global sink (None restores the default print/log fallback)."""
+    global _sink
+    _sink = sink
+
+
+def clear_sink() -> None:
+    """Remove any installed sink; the default print/log fallback takes over."""
+    global _sink
+    _sink = None
+
+
+@contextmanager
+def using_sink(sink: EventSink | None) -> Iterator[None]:
+    """
+    Install `sink` for the duration of the block, then restore the previous one.
+
+    If `sink` is None the currently-active sink (default print/log fallback) is
+    left in place. try/finally guarantees the previous sink is restored even on
+    error, so one run's callback never leaks into the next.
+    """
+    global _sink
+    prev = _sink
+    if sink is not None:
+        _sink = sink
+    try:
+        yield
+    finally:
+        _sink = prev
+
+
+# ── Emit + default fallback ──────────────────────────────────────────────────
+
+def emit(event: ClientEvent) -> None:
+    """Route one event to the installed sink, else to the default fallback."""
+    if _sink is not None:
+        _sink(event)
+    else:
+        _default_sink(event)
+
+
+def _default_sink(event: ClientEvent) -> None:
+    """Reproduce today's terminal output: print the message, mirror to the log."""
+    print(event.message)
+    _log.debug("%s", event.message)
+
+
+# ── Thin constructors (keep op call-sites terse) ─────────────────────────────
+
+def _emit(phase, status, message, current, total, percent, data) -> None:
+    emit(ClientEvent(
+        phase=phase, status=status, message=message,
+        current=current, total=total, percent=percent, data=data,
+    ))
+
+
+def start(phase: str, message: str = "", *, current=None, total=None,
+          percent=None, **data) -> None:
+    _emit(phase, "start", message, current, total, percent, data)
+
+
+def progress(phase: str, message: str = "", *, current=None, total=None,
+             percent=None, **data) -> None:
+    _emit(phase, "progress", message, current, total, percent, data)
+
+
+def ok(phase: str, message: str = "", *, current=None, total=None,
+       percent=None, **data) -> None:
+    _emit(phase, "ok", message, current, total, percent, data)
+
+
+def warn(phase: str, message: str = "", *, current=None, total=None,
+         percent=None, **data) -> None:
+    _emit(phase, "warn", message, current, total, percent, data)
+
+
+def error(phase: str, message: str = "", *, current=None, total=None,
+          percent=None, **data) -> None:
+    _emit(phase, "error", message, current, total, percent, data)
+
+
+def done(phase: str, message: str = "", *, current=None, total=None,
+         percent=None, **data) -> None:
+    _emit(phase, "done", message, current, total, percent, data)

driverclient/main.py

@@ -0,0 +1,71 @@
+"""
+driverclient/main.py — Driver Server client entry point.
+
+Reads default_command from config.json and dispatches to the matching
+operation. No CLI arguments — config.json is the sole source of truth.
+
+Programmatic use (PyQt or other embedding): prefer the DriverClient
+connector (``from driverclient import DriverClient``). The bare run()
+helper below is also available:
+    from driverclient.main import run
+    run("capture-all")
+    run()                  # uses default_command from config.json
+"""
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from driverclient import events
+from driverclient.config import get
+from driverclient.ops.automate import run_automation
+from driverclient.ops.capture import capture_all, capture_missing, wu_full, wu_update
+from driverclient.ops.install import resolve_and_install
+from driverclient.ops.resolve import resolve
+from driverclient.ops.scan import scan
+
+_OPERATIONS: dict[str, callable] = {
+    "scan":                scan,
+    "resolve":             resolve,
+    "resolve-and-install": resolve_and_install,
+    "capture-all":         capture_all,
+    "capture-missing":     capture_missing,
+    "wu-update":           wu_update,
+    "wu-full":             wu_full,
+    "automate":            run_automation,
+}
+
+
+def run(command: str | None = None) -> object:
+    """
+    Run a client operation.
+
+    Args:
+        command: one of the keys in _OPERATIONS.
+                 If None, checks DS_CLIENT_COMMAND env var, then
+                 default_command from config.json, then "automate".
+
+    Returns:
+        The result object from the operation (ScanResult, InstallResult, etc.).
+
+    After the operation completes, cache_dir (C:\\DriverServer\\client\\ by default)
+    is deleted so no cached files persist between runs.
+    """
+    cfg = get()
+    cmd = command or os.environ.get("DS_CLIENT_COMMAND") or cfg.get("default_command", "automate")
+
+    fn = _OPERATIONS.get(cmd)
+    if fn is None:
+        events.error("pipeline", f"[error] Unknown command: '{cmd}'", command=cmd)
+        events.error("pipeline", f"        Valid commands: {', '.join(_OPERATIONS)}")
+        sys.exit(1)
+
+    try:
+        return fn()
+    finally:
+        cache_dir = Path(cfg.get("cache_dir", "C:\\DriverServer\\client"))
+        shutil.rmtree(cache_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    run()

driverclient/ops/__init__.py

@@ -0,0 +1,15 @@
+from driverclient.ops.automate import AutomateResult, run_automation
+from driverclient.ops.capture import CaptureResult, capture_all, capture_missing, wu_update
+from driverclient.ops.install import InstallResult, resolve_and_install
+from driverclient.ops.resolve import ResolveResult, resolve
+from driverclient.ops.scan import ScanResult, scan
+
+__all__ = [
+    "scan",                "ScanResult",
+    "resolve",             "ResolveResult",
+    "resolve_and_install", "InstallResult",
+    "capture_all",
+    "capture_missing",
+    "wu_update",           "CaptureResult",
+    "run_automation",      "AutomateResult",
+]

driverclient/ops/automate.py

@@ -0,0 +1,118 @@
+"""
+client/ops/automate.py — Full end-to-end driver management pipeline.
+
+Steps:
+  1. Scan    — enumerate hardware, build device + HWID list
+  2. Resolve — query local repo: available drivers vs not-found HWIDs
+  3. Install — download + install available drivers from repo
+  4. WU      — (if still missing) trigger Windows Update, wait, capture + submit
+
+Public API:
+    run_automation() -> AutomateResult
+"""
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from driverclient import events
+from driverclient.config import get
+from driverclient.ops.capture import CaptureResult, wu_update
+from driverclient.ops.install import InstallResult, resolve_and_install
+from driverclient.ops.resolve import ResolveResult, resolve
+from driverclient.ops.scan import ScanResult, scan
+
+
+@dataclass
+class AutomateResult:
+    run_id:          str           = field(default_factory=lambda: str(uuid.uuid4()))
+    scan:            ScanResult    | None = None
+    resolve:         ResolveResult | None = None
+    install:         InstallResult | None = None
+    wu:              CaptureResult | None = None
+    duration_s:      int           = 0
+
+
+def run_automation() -> AutomateResult:
+    cfg    = get()
+    result = AutomateResult()
+    t0     = time.monotonic()
+
+    _header("Automate — full pipeline")
+
+    # ── Step 1: Scan ──────────────────────────────────────────────────────────
+    _step(1, "Scan")
+    result.scan = scan(force=True)
+
+    # ── Step 2: Resolve ───────────────────────────────────────────────────────
+    _step(2, "Resolve")
+    # Reuse the fresh scan just done — force=False reads the just-saved cache
+    result.resolve = resolve(force=False)
+
+    if not result.resolve.has_drivers and not result.resolve.has_missing:
+        events.done("pipeline", "[automate] Machine fully up to date — nothing to do")
+        result.duration_s = int(time.monotonic() - t0)
+        _summary(result)
+        return result
+
+    # ── Step 3: Install from repo ─────────────────────────────────────────────
+    _step(3, f"Install  ({len(result.resolve.drivers)} driver(s) from repo)")
+    if result.resolve.has_drivers:
+        result.install = resolve_and_install(force=False)
+    else:
+        events.progress("pipeline", "[automate] No drivers available in repo — skipping install")
+        result.install = InstallResult(trace_id=result.resolve.trace_id)
+
+    # ── Step 4: Windows Update fallback ──────────────────────────────────────
+    wu_enabled = cfg.get("automate_wu_fallback", True)
+    still_missing = len(result.resolve.not_found)
+
+    if still_missing > 0 and wu_enabled:
+        _step(4, f"Windows Update  ({still_missing} HWID(s) not in repo)")
+        result.wu = wu_update(force=False)
+    else:
+        reason = "disabled in config" if not wu_enabled else "nothing missing"
+        events.progress("pipeline", f"\n[automate] Step 4 — WU fallback skipped ({reason})",
+                        reason=reason)
+        result.wu = CaptureResult(still_missing=still_missing)
+
+    result.duration_s = int(time.monotonic() - t0)
+    _summary(result)
+    return result
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+
+def _header(title: str) -> None:
+    events.start("pipeline", "")
+    events.start("pipeline", "=" * 60)
+    events.start("pipeline", f"  {title}", title=title)
+    events.start("pipeline", f"  {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')}")
+    events.start("pipeline", "=" * 60)
+
+
+def _step(n: int, label: str) -> None:
+    events.progress("pipeline", f"\n── Step {n}: {label} {'─' * max(0, 50 - len(label))}",
+                    step=n, label=label)
+
+
+def _summary(r: AutomateResult) -> None:
+    inst   = r.install or InstallResult()
+    wu     = r.wu      or CaptureResult()
+
+    events.done("done", "")
+    events.done("done", "=" * 60)
+    events.done("done", "  Summary")
+    events.done("done", f"  Duration : {r.duration_s}s", duration_s=r.duration_s)
+    events.done("done", f"  Installed: {inst.ok_count} ok  {inst.fail_count} failed",
+                installed_ok=inst.ok_count, installed_failed=inst.fail_count)
+    if r.wu and r.wu.wu_triggered:
+        events.done("done",
+                    f"  WU       : {wu.submitted} captured  {wu.still_missing} still missing",
+                    wu_submitted=wu.submitted, wu_still_missing=wu.still_missing)
+    else:
+        missing = len(r.resolve.not_found) if r.resolve else 0
+        if missing:
+            events.done("done", f"  Missing  : {missing} HWID(s) not in repo (WU not run)",
+                        missing=missing)
+    events.done("done", "=" * 60)