bladekit 4.5.0__py3-none-any.whl

bladekit/_secret.py

@@ -0,0 +1,52 @@
+"""``bladekit.Secret`` — a named secret reference.
+
+A ``Secret`` is just a *reference by name*; values never live in the SDK object.
+It is passed to ``@app.function(secrets=[bladekit.Secret.from_name("hf-token")])``
+and resolved by the control plane at run creation (404 SECRET_NOT_FOUND if
+unknown) and again at scheduling (contracts/openapi.yaml, conventions.md §11).
+
+Creating / replacing secret *values* is done by the CLI (``blade secret set``),
+which reads the value from stdin or ``--from-env`` and NEVER from a positional
+argument (argv leaks into ``ps``).
+"""
+
+from __future__ import annotations
+
+import re
+
+from . import exceptions as exc
+
+# conventions.md §6: ^[a-z0-9][a-z0-9._-]{0,63}$
+_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")
+
+
+class Secret:
+    """Reference to a named secret stored (encrypted) on the control plane."""
+
+    __slots__ = ("name",)
+
+    def __init__(self, name: str) -> None:
+        # Private: use :meth:`from_name`.
+        self.name = name
+
+    @classmethod
+    def from_name(cls, name: str) -> "Secret":
+        """Reference an existing secret by name (resolved server-side at run time)."""
+        if not isinstance(name, str) or not _NAME_RE.match(name):
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                f"invalid secret name {name!r}; must match "
+                "'^[a-z0-9][a-z0-9._-]{0,63}$'",
+            )
+        return cls(name)
+
+    def __repr__(self) -> str:
+        return f"<bladekit.Secret name={self.name!r}>"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Secret):
+            return NotImplemented
+        return self.name == other.name
+
+    def __hash__(self) -> int:
+        return hash(self.name)

bladekit/_serialize.py

@@ -0,0 +1,88 @@
+"""cloudpickle serialization helpers and the inline/object-store boundary.
+
+conventions.md §8: the format is ``cloudpickle``; payloads <= 1 MiB raw go inline
+as base64, larger ones go through a presigned ``pl_`` payload.
+
+``cloudpickle`` is imported lazily inside functions so that ``import bladekit`` stays
+cheap (test requirement: no heavy top-level import).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+from typing import Any, Tuple
+
+from ._constants import INLINE_PAYLOAD_MAX_BYTES, PAYLOAD_FORMAT
+
+
+def cloudpickle_version() -> str:
+    """Return cloudpickle version truncated to ``major.minor`` (handshake §5)."""
+    import cloudpickle  # local import keeps top-level import light
+
+    parts = cloudpickle.__version__.split(".")
+    return f"{parts[0]}.{parts[1]}"
+
+
+def dumps(obj: Any) -> bytes:
+    import cloudpickle
+
+    return cloudpickle.dumps(obj)
+
+
+def loads(data: bytes) -> Any:
+    import cloudpickle
+
+    return cloudpickle.loads(data)
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def dumps_args(args: tuple, kwargs: dict) -> bytes:
+    """Serialize the ``(args, kwargs)`` tuple — the unit a call carries."""
+    return dumps((args, kwargs))
+
+
+def make_payload_in(raw: bytes) -> Tuple[dict, bytes | None]:
+    """Build a ``PayloadIn`` dict from raw serialized bytes.
+
+    Returns ``(payload_in, object_bytes)``. When the payload exceeds the inline
+    ceiling, ``payload_in`` carries no ``inline_b64`` and ``object_bytes`` holds
+    the bytes to PUT to a presigned URL (the caller declares the ``pl_`` payload
+    and fills ``payload_id``). Otherwise ``object_bytes`` is ``None``.
+    """
+    body: dict[str, Any] = {
+        "format": PAYLOAD_FORMAT,
+        "size_bytes": len(raw),
+        "sha256": sha256_hex(raw),
+    }
+    if len(raw) <= INLINE_PAYLOAD_MAX_BYTES:
+        body["inline_b64"] = base64.b64encode(raw).decode("ascii")
+        return body, None
+    return body, raw
+
+
+def decode_payload_out(payload: dict, *, fetch=None) -> bytes:
+    """Materialize a ``PayloadOut`` to raw bytes, verifying the sha256.
+
+    ``fetch(url) -> bytes`` is used when the payload lives in the object store
+    (``get_url`` present). Injecting it keeps this module free of any HTTP
+    dependency and trivially testable.
+    """
+    inline = payload.get("inline_b64")
+    if inline is not None:
+        raw = base64.b64decode(inline)
+    else:
+        get_url = payload.get("get_url")
+        if not get_url or fetch is None:
+            raise ValueError(
+                "payload has no inline_b64 and no usable get_url to download from"
+            )
+        raw = fetch(get_url)
+
+    expected = payload.get("sha256")
+    if expected and sha256_hex(raw) != expected:
+        raise ValueError("payload checksum mismatch")
+    return raw

bladekit/_serve.py

@@ -0,0 +1,188 @@
+"""``blade serve script.py`` — dev loop: watch files, hot-reload the bundle.
+
+Flow (runner-protocol.md §9):
+
+1. Load the script, create the run with ``serve=true`` (so the container never
+   drains on idle), via the first remote invocation in the entrypoint.
+2. Stream the run's logs continuously in the background.
+3. Watch the bundle root for file changes (``watchfiles``). On each change:
+   re-bundle (deduplicated by sha256 → usually instant, no upload), POST
+   ``/v1/runs/{id}/bundle``, print ``reloaded in X.Xs``.
+4. Ctrl-C → cancel the run cleanly and exit.
+
+``watchfiles`` is imported lazily *inside* this module's functions so that
+``import bladekit`` (and ``blade --help``) never pulls it in.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+# ``watchfiles`` is imported lazily here so that the *top-level* ``import bladekit``
+# (and ``blade --help``) never pulls it in — _serve is only imported on demand
+# by the CLI's ``serve`` command. The module-level name allows test patching via
+# ``patch("bladekit._serve.watch", ...)``.
+try:
+    from watchfiles import watch
+except ImportError:  # pragma: no cover
+    watch = None  # type: ignore[assignment]
+
+
+def serve(client: Any, forge_app: Any, entrypoint: Any, bundle_root: Path) -> int:
+    """Run the serve dev loop. Returns the process exit code."""
+    from . import _app as app_mod
+    from . import exceptions as exc
+    from ._render import console, err_console
+
+    # Mark every function on the app as serve=true so its run never drains on
+    # idle — the reload needs a live container (runner-protocol.md §9).
+    for fn in forge_app.functions.values():
+        fn.serve = True
+    for cls in forge_app.classes.values():
+        cls._serve = True  # consumed when the method's Function is built
+        # Clear any Function objects already built with serve=False (e.g. from
+        # a prior invocation or an eager call during module load). The next
+        # _function_for() call will rebuild them with serve=True.
+        cls._functions.clear()
+
+    stop_event = threading.Event()
+    streamed = {"run_id": None}
+
+    def _log_pump():
+        from .cli import _stream_run_logs
+
+        while not stop_event.is_set():
+            run_ids = list(app_mod._SESSION.open_run_ids)
+            if run_ids:
+                streamed["run_id"] = run_ids[0]
+                break
+            stop_event.wait(0.1)
+        rid = streamed["run_id"]
+        if rid:
+            _stream_run_logs(client, rid, stop_event)
+
+    log_thread = threading.Thread(target=_log_pump, daemon=True)
+    log_thread.start()
+
+    # Watch the bundle CONCURRENTLY with the entrypoint. The entrypoint may be a
+    # long-running dev loop (`for _ in range(N): fn.remote(); sleep`) — the whole
+    # point of serve is to edit code *while it runs* and have the next call pick
+    # up the new bundle. A sequential "run entrypoint to completion, then watch"
+    # would never reload such an entrypoint. The watcher waits for the run to
+    # appear (created by the first .remote() in the entrypoint), then hot-reloads
+    # on every change until stop_event.
+    watch_started = threading.Event()
+
+    def _watch_pump():
+        run_id = None
+        while not stop_event.is_set():
+            run_ids = list(app_mod._SESSION.open_run_ids)
+            if run_ids:
+                run_id = run_ids[0]
+                break
+            stop_event.wait(0.1)
+        if run_id is None:
+            return
+        console.print(
+            f"[green]serving[/green] run {run_id} — watching {bundle_root} "
+            "for changes. Ctrl-C to stop."
+        )
+        watch_started.set()
+        try:
+            _watch_loop(client, forge_app, run_id, bundle_root, stop_event)
+        except exc.FabricError as e:  # pragma: no cover - surfaced, non-fatal
+            err_console.print(f"[red]watch error[/red]: {e}")
+
+    watch_thread = threading.Thread(target=_watch_pump, daemon=True)
+    watch_thread.start()
+
+    exit_code = 0
+    try:
+        # First invocation: creates the serve run + the first call. May return
+        # quickly (one call) or loop for a while (a dev iterating); the watcher
+        # above is already running either way.
+        console.print("[cyan]blade serve[/cyan]: starting run (serve mode)…")
+        entrypoint()
+        run_ids = list(app_mod._SESSION.open_run_ids)
+        if not run_ids:
+            err_console.print(
+                "[yellow]no run was created by the entrypoint; nothing to "
+                "serve.[/yellow]"
+            )
+            stop_event.set()
+            return 0
+        # The entrypoint returned (or never blocked): keep serving until Ctrl-C
+        # so the dev can still edit + reload after a quick entrypoint.
+        while not stop_event.is_set():
+            stop_event.wait(0.5)
+    except KeyboardInterrupt:
+        console.print("\n[magenta]Ctrl-C — stopping serve…[/magenta]")
+        exit_code = 130
+    except exc.FabricError as e:
+        err_console.print(f"[red]serve error[/red]: {e}")
+        exit_code = 1
+    finally:
+        # Cancel every run this serve session opened (clean shutdown).
+        # Only swallow ConflictError (RUN_NOT_CANCELLABLE = already terminal).
+        # Network or auth errors are caught by the broad except below so they
+        # don't abort the rest of the cleanup, but they are not silenced for
+        # runs that follow — the broad catch at the finally level handles them.
+        for rid in list(app_mod._SESSION.open_run_ids):
+            try:
+                client.cancel_run(rid)
+            except exc.ConflictError:
+                # Run already terminal — expected, ignore.
+                pass
+            except Exception:  # noqa: BLE001
+                # Network / auth failure on cancel: don't abort cleanup of
+                # remaining runs; the run will time out server-side.
+                pass
+        stop_event.set()
+        log_thread.join(timeout=3.0)
+        watch_thread.join(timeout=3.0)
+    return exit_code
+
+
+def _watch_loop(
+    client: Any,
+    forge_app: Any,
+    run_id: str,
+    bundle_root: Path,
+    stop_event: threading.Event,
+) -> None:
+    """Watch ``bundle_root`` and hot-reload the bundle on each change."""
+    from . import exceptions as exc
+    from ._render import console, err_console
+
+    if watch is None:  # pragma: no cover
+        err_console.print(
+            "[red]blade serve needs 'watchfiles'[/red]: pip install "
+            "'watchfiles'."
+        )
+        return
+
+    last_sha: Optional[str] = forge_app._bundle_sha256
+    for _changes in watch(str(bundle_root), stop_event=stop_event):
+        if stop_event.is_set():
+            break
+        t0 = time.perf_counter()
+        try:
+            new_id, new_sha = forge_app._rebuild_bundle()
+        except exc.FabricError as e:
+            err_console.print(f"[red]re-bundle failed[/red]: {e}")
+            continue
+        if new_sha == last_sha:
+            # Editor touched a file without changing content (or only ignored
+            # files changed): nothing to push.
+            continue
+        try:
+            client.update_run_bundle(run_id, new_id)
+        except exc.FabricError as e:
+            err_console.print(f"[red]reload failed[/red]: {e}")
+            continue
+        last_sha = new_sha
+        elapsed = time.perf_counter() - t0
+        console.print(f"[green]reloaded in {elapsed:.1f}s[/green] [dim]({new_sha[:12]}…)[/dim]")

bladekit/_volume.py

@@ -0,0 +1,232 @@
+"""``bladekit.Volume`` — a named network volume reference, with in-container ``.commit()``.
+
+Two roles, one object:
+
+1. **Client-side reference**: ``bladekit.Volume.from_name("datasets")`` passed via
+   ``@app.function(volumes={"/data": vol})``. ``create_if_missing=True`` makes
+   the run-creation path create-or-get the volume (openapi createVolume is
+   idempotent by name). The mount generation is resolved at scheduling, frozen
+   on the run (a concurrent commit never changes a scheduled container's view).
+
+2. **In-container handle**: inside an AI Fabric container the user calls
+   ``vol.commit()`` to publish local writes as a new generation. The SDK detects
+   the container context via ``FABRIC_VOLUMES`` and drives the commit through the
+   *runner-internal* API with the run token (the runner never talks to the
+   agent — invariant kept, runner-protocol.md §11).
+
+Resolution rule (§11): ``commit()`` finds the matching mount in ``FABRIC_VOLUMES``
+by name; if absent it raises ``bladekit.VolumeError`` locally rather than letting
+the server answer 404. ``read_only`` mounts raise immediately.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from typing import Any, Dict, List, Optional
+
+from . import exceptions as exc
+
+_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")
+
+# Commit poll backoff (runner-protocol.md §11: 1 s → 5 s).
+_COMMIT_POLL_INITIAL = 1.0
+_COMMIT_POLL_MAX = 5.0
+_COMMIT_TERMINAL = frozenset({"committed", "failed"})
+
+
+class Volume:
+    """Reference to a named network volume (and in-container commit handle)."""
+
+    __slots__ = (
+        "name",
+        "_create_if_missing",
+        "_auto_commit_on_ready",
+        "_auto_commit_every",
+        "_read_only",
+    )
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        create_if_missing: bool = False,
+        auto_commit_on_ready: bool = False,
+        auto_commit_every: int = 0,
+        read_only: bool = False,
+    ) -> None:
+        # Private: use :meth:`from_name`.
+        self.name = name
+        self._create_if_missing = create_if_missing
+        self._auto_commit_on_ready = auto_commit_on_ready
+        self._auto_commit_every = auto_commit_every
+        self._read_only = read_only
+
+    @classmethod
+    def from_name(
+        cls,
+        name: str,
+        *,
+        create_if_missing: bool = False,
+        auto_commit_on_ready: bool = False,
+        auto_commit_every: int = 0,
+        read_only: bool = False,
+    ) -> "Volume":
+        """Reference a volume by name.
+
+        ``create_if_missing=True`` creates it (generation 0, empty) if it does
+        not exist yet, the first time the run that mounts it is created.
+
+        ``auto_commit_on_ready=True`` (deployed ``web_server``/``asgi_app``
+        endpoints only) commits the mount automatically once the replica
+        reports serving-ready — no ``vol.commit()`` needed in user code. Made
+        for server warm-up caches (e.g. vLLM ``VLLM_CACHE_ROOT``): whatever the
+        server wrote under the mount during startup is published for the next
+        cold start, on any node. Best-effort and non-blocking: the commit runs
+        after traffic starts flowing, and a failure never affects the replica.
+
+        ``auto_commit_every=N`` (seconds, same endpoint kinds) commits the mount
+        every N seconds from container boot, WITHOUT waiting for serving-ready.
+        Use it when the thing being cached is what makes the boot slow: a first
+        ``torch.compile`` that outruns ``startup_timeout`` kills the replica
+        before ``auto_commit_on_ready`` can fire, so the cache it just built is
+        lost and the next replica rebuilds it and fails identically. A periodic
+        commit breaks that loop because it does not wait for the boot to
+        succeed. Minimum 60; 0 (the default) is off. Combines with
+        ``auto_commit_on_ready``.
+        """
+        if not isinstance(name, str) or not _NAME_RE.match(name):
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                f"invalid volume name {name!r}; must match "
+                "'^[a-z0-9][a-z0-9._-]{0,63}$'",
+            )
+        if not isinstance(auto_commit_every, int) or isinstance(
+            auto_commit_every, bool
+        ):
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT", "auto_commit_every must be an integer"
+            )
+        if auto_commit_every != 0 and auto_commit_every < 60:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                "auto_commit_every must be 0 (off) or at least 60 seconds",
+            )
+        return cls(
+            name,
+            create_if_missing=create_if_missing,
+            auto_commit_on_ready=auto_commit_on_ready,
+            auto_commit_every=auto_commit_every,
+            read_only=read_only,
+        )
+
+    def __repr__(self) -> str:
+        return f"<bladekit.Volume name={self.name!r}>"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Volume):
+            return NotImplemented
+        return self.name == other.name
+
+    def __hash__(self) -> int:
+        return hash(self.name)
+
+    # -- in-container commit (runner-protocol.md §11) -----------------------
+
+    # Default poll timeout (seconds). Large commits — model weights pushed via
+    # S3 multipart — legitimately run well past 10 minutes, so the client must
+    # not give up early; the server-side stall watcher (FORGE_COMMIT_STALL_AFTER)
+    # is what actually bounds a genuinely stuck commit. Override per-call via
+    # ``timeout=`` for very large volumes.
+    _COMMIT_DEFAULT_TIMEOUT = 3600.0
+
+    def commit(self, *, poll: bool = True, timeout: Optional[float] = _COMMIT_DEFAULT_TIMEOUT) -> int:
+        """Publish this container's local writes as a new volume generation.
+
+        Only valid inside an AI Fabric container (``FABRIC_VOLUMES`` or ``FORGE_VOLUMES`` set). Resolves the
+        mount by name, POSTs the runner-internal commit, then polls until the
+        commit is ``committed`` (returns the new generation) or ``failed``
+        (raises :class:`bladekit.VolumeCommitError`).
+
+        ``timeout`` caps the total poll time in seconds (default 600 s, matching
+        the server-side commit watcher). Pass ``None`` for no timeout (not
+        recommended in production).
+
+        A failed commit is never fatal: the container keeps running and the call
+        may retry (runner-protocol.md §11).
+        """
+        mount = _resolve_mount(self.name)
+        if mount is None:
+            raise exc.VolumeError(
+                f"volume {self.name!r} is not mounted in this container; "
+                "pass it via volumes={'/path': vol} on @app.function."
+            )
+        if mount.get("read_only"):
+            raise exc.VolumeCommitError(
+                "VOLUME_READ_ONLY",
+                f"volume {self.name!r} is mounted read-only; commit() is refused.",
+            )
+        volume_id = mount["volume_id"]
+
+        from ._runner_api import RunnerApiClient
+
+        client = RunnerApiClient.from_env()
+        commit = client.commit_volume(volume_id)
+        commit_id = commit["commit_id"]
+        if not poll:
+            return commit  # type: ignore[return-value]
+
+        deadline = None if timeout is None else time.monotonic() + timeout
+        interval = _COMMIT_POLL_INITIAL
+        while True:
+            state = commit.get("state")
+            if state in _COMMIT_TERMINAL:
+                if state == "committed":
+                    return int(commit["generation"])
+                err = commit.get("error") or {}
+                raise exc.VolumeCommitError(
+                    str(err.get("code", "VOLUME_COMMIT_FAILED")),
+                    str(err.get("message", "volume commit failed")),
+                )
+            if deadline is not None and time.monotonic() >= deadline:
+                raise exc.VolumeCommitError(
+                    "VOLUME_COMMIT_FAILED",
+                    f"timed out after {timeout}s waiting for commit {commit_id}",
+                )
+            time.sleep(interval)
+            interval = min(interval * 1.5, _COMMIT_POLL_MAX)
+            commit = client.get_volume_commit(commit_id)
+
+
+def _mounted_volumes() -> List[Dict[str, Any]]:
+    """Parse ``FABRIC_VOLUMES`` / ``FORGE_VOLUMES`` (JSON list) — empty/absent ⇒ no volumes.
+
+    An unparseable value is logged as a warning rather than silently returning
+    [] — an injection bug (platform side) would otherwise surface only as a
+    confusing "volume not mounted" error from commit().
+    """
+    from . import _env
+
+    raw, var = _env.lookup("VOLUMES")
+    if not raw:
+        return []
+    try:
+        data = json.loads(raw)
+    except ValueError:
+        import warnings
+        warnings.warn(
+            f"{var} is set but contains invalid JSON; no volumes will be "
+            "resolved. This is a platform configuration bug.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return []
+    return data if isinstance(data, list) else []
+
+
+def _resolve_mount(name: str) -> Optional[Dict[str, Any]]:
+    for m in _mounted_volumes():
+        if isinstance(m, dict) and m.get("name") == name:
+            return m
+    return None

bladekit/_webhook.py

@@ -0,0 +1,90 @@
+"""Completion-webhook config + receiver-side verification (async-jobs-study.md).
+
+A deployed endpoint job spawned with ``webhook=`` gets a POST to your URL when
+it finishes. The control plane signs the body Stripe-style with
+``Forge-Signature: t=<unix>,v1=<hex hmac-sha256(secret, "<t>.<raw_body>")>`` —
+``verify_webhook`` checks it and returns the parsed payload.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional, Tuple
+
+
+@dataclass
+class Webhook:
+    """Completion webhook for ``spawn(webhook=...)``.
+
+    ``secret`` is the HMAC signing secret; leave it None and the control plane
+    generates one, returned ONCE on the spawn response
+    (``DeployedFunctionCall.webhook_secret``). ``signed=False`` opts out of
+    signing (no FORGE_SECRET_KEY needed on the control plane).
+    """
+
+    url: str
+    secret: Optional[str] = None
+    signed: bool = True
+    events: Tuple[str, ...] = field(default_factory=lambda: ("completed",))
+
+
+def _webhook_dict(w: "Webhook | dict | str | None") -> Optional[dict]:
+    """Normalize a webhook spec (Webhook | dict | bare-URL str) to the wire dict."""
+    if w is None:
+        return None
+    if isinstance(w, dict):
+        return w
+    if isinstance(w, str):
+        return {"url": w}
+    if isinstance(w, Webhook):
+        d: dict[str, Any] = {"url": w.url, "signed": w.signed, "events": list(w.events)}
+        if w.secret:
+            d["secret"] = w.secret
+        return d
+    raise TypeError(f"webhook must be a bladekit.Webhook, dict, url str or None, got {type(w)!r}")
+
+
+def _header(headers: Mapping[str, Any], name: str) -> Optional[str]:
+    lname = name.lower()
+    for k, v in headers.items():
+        if k.lower() == lname:
+            # Header values may be a list (Forge web_endpoint item.headers gives
+            # {name: [values]}, mirroring Go's http.Header) or a plain string
+            # (WSGI/ASGI request.headers). Normalize to the first string value.
+            if isinstance(v, (list, tuple)):
+                return str(v[0]) if v else None
+            return str(v)
+    return None
+
+
+def verify_webhook(
+    secret: str,
+    headers: Mapping[str, str],
+    raw_body: "bytes | str",
+    *,
+    tolerance: int = 300,
+) -> dict:
+    """Verify an AI Fabric completion-webhook and return its parsed JSON payload.
+
+    Raises ValueError on a missing/malformed/stale/forged signature. ``raw_body``
+    MUST be the exact bytes received (do not re-serialize). ``tolerance`` is the
+    max clock skew in seconds (0 disables the timestamp check).
+    """
+    sig = _header(headers, "Forge-Signature")
+    if not sig:
+        raise ValueError("missing Forge-Signature header")
+    parts = dict(p.split("=", 1) for p in sig.split(",") if "=" in p)
+    ts, v1 = parts.get("t"), parts.get("v1")
+    if not ts or not v1:
+        raise ValueError("malformed Forge-Signature header")
+    if tolerance and abs(time.time() - int(ts)) > tolerance:
+        raise ValueError("webhook timestamp outside tolerance (possible replay)")
+    body = raw_body if isinstance(raw_body, (bytes, bytearray)) else raw_body.encode()
+    mac = hmac.new(secret.encode(), (ts + ".").encode() + body, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(mac, v1):
+        raise ValueError("webhook signature mismatch")
+    return json.loads(body)