fencekit 0.1.0__py3-none-any.whl

fencekit/__init__.py

@@ -0,0 +1,38 @@
+"""Redis idempotency and fenced locks for background jobs."""
+
+from fencekit._version import __version__
+from fencekit.canonicalize import canonicalize, idempotency_key
+from fencekit.client import RedisClient, SyncRedis
+from fencekit.errors import (
+    CanonicalizeError,
+    FencedOutError,
+    FenceKitError,
+    IdempotencyNotOwned,
+    LockNotAcquired,
+    LockNotOwned,
+    TokenExpiredError,
+)
+from fencekit.fence import FenceGate
+from fencekit.idempotency import IdempotencyGuard
+from fencekit.lock import DistributedLock
+from fencekit.types import FenceToken, LockHandle
+
+__all__ = [
+    "CanonicalizeError",
+    "DistributedLock",
+    "FenceGate",
+    "FenceKitError",
+    "FenceToken",
+    "FencedOutError",
+    "IdempotencyGuard",
+    "IdempotencyNotOwned",
+    "LockHandle",
+    "LockNotAcquired",
+    "LockNotOwned",
+    "RedisClient",
+    "SyncRedis",
+    "TokenExpiredError",
+    "__version__",
+    "canonicalize",
+    "idempotency_key",
+]

fencekit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

fencekit/canonicalize.py

@@ -0,0 +1,85 @@
+"""Deterministic payload canonicalization for idempotency keys."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from collections.abc import Mapping, Sequence
+from typing import TypeAlias
+
+from fencekit.errors import CanonicalizeError
+
+JsonScalar: TypeAlias = str | int | bool | None
+JsonValue: TypeAlias = (
+    JsonScalar | float | Mapping[str, "JsonValue"] | Sequence["JsonValue"]
+)
+
+
+def _normalize(value: object) -> JsonValue:
+    if value is None or isinstance(value, (str, int, bool)):
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise CanonicalizeError(
+                "non-finite floats (NaN/Inf) are not allowed in idempotency payloads"
+            )
+        return value
+    if isinstance(value, Mapping):
+        out: dict[str, JsonValue] = {}
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise CanonicalizeError(
+                    f"mapping keys must be str, got {type(key).__name__}"
+                )
+            out[key] = _normalize(item)
+        return out
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return [_normalize(item) for item in value]
+    raise CanonicalizeError(
+        f"unsupported type for canonicalization: {type(value).__name__}; "
+        "use JSON-serializable values (datetime must be ISO strings)"
+    )
+
+
+def canonicalize(payload: Mapping[str, object]) -> str:
+    """Return a deterministic JSON string for *payload*.
+
+    Rules:
+
+    - Only JSON-serializable mappings, sequences, and scalars.
+    - Keys are sorted; separators are compact ``(",", ":")``; ``ensure_ascii=True``.
+    - Non-finite floats are rejected.
+    - ``datetime`` and other objects are rejected. Pass ISO strings yourself.
+
+    Key stability is the caller's contract: the same business identity must
+    serialize the same way across producers.
+    """
+    if not isinstance(payload, Mapping):
+        raise CanonicalizeError("payload must be a mapping")
+    normalized = _normalize(dict(payload))
+    assert isinstance(normalized, dict)
+    try:
+        return json.dumps(
+            normalized,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=True,
+            allow_nan=False,
+        )
+    except (TypeError, ValueError) as exc:
+        raise CanonicalizeError(str(exc)) from exc
+
+
+def idempotency_key(payload: Mapping[str, object], *, namespace: str) -> str:
+    """Build a deterministic idempotency key from *payload* and *namespace*.
+
+    Returns ``{namespace}:{sha256_hex}``. The idempotency guard and key helpers
+    add the Redis prefix.
+    """
+    if not namespace or not isinstance(namespace, str):
+        raise CanonicalizeError("namespace must be a non-empty str")
+    if ":" in namespace or any(character.isspace() for character in namespace):
+        raise CanonicalizeError("namespace must not contain ':' or whitespace")
+    digest = hashlib.sha256(canonicalize(payload).encode("utf-8")).hexdigest()
+    return f"{namespace}:{digest}"

fencekit/client.py

@@ -0,0 +1,92 @@
+"""Sync Redis client protocol and thin redis-py adapter."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+def integer_response(value: object) -> int:
+    """Normalize an integer Redis reply without weakening types to ``Any``."""
+    if isinstance(value, int):
+        return value
+    raise TypeError(f"expected integer Redis response, got {type(value).__name__}")
+
+
+@runtime_checkable
+class SyncRedis(Protocol):
+    """Minimal sync Redis surface used by fencekit.
+
+    Designed so an asyncio backend can be added later behind a different
+    protocol without changing lock/fence algorithms.
+    """
+
+    def set(
+        self,
+        name: str,
+        value: str,
+        *,
+        nx: bool = False,
+        xx: bool = False,
+        ex: int | None = None,
+        px: int | None = None,
+    ) -> object: ...
+
+    def get(self, name: str) -> object: ...
+
+    def delete(self, *names: str) -> object: ...
+
+    def eval(
+        self,
+        script: str,
+        numkeys: int,
+        *keys_and_args: str | int,
+    ) -> object: ...
+
+
+class RedisClient:
+    """Adapter around ``redis.Redis`` with ``decode_responses=True`` semantics.
+
+    Prefer constructing with an existing client::
+
+        RedisClient(redis.Redis.from_url(url, decode_responses=True))
+    """
+
+    def __init__(self, redis: SyncRedis) -> None:
+        self._redis = redis
+
+    @property
+    def raw(self) -> SyncRedis:
+        return self._redis
+
+    def set(
+        self,
+        name: str,
+        value: str,
+        *,
+        nx: bool = False,
+        xx: bool = False,
+        ex: int | None = None,
+        px: int | None = None,
+    ) -> bool:
+        result = self._redis.set(name, value, nx=nx, xx=xx, ex=ex, px=px)
+        # redis-py returns True/None depending on version and NX
+        return bool(result)
+
+    def get(self, name: str) -> str | None:
+        value = self._redis.get(name)
+        if value is None:
+            return None
+        if isinstance(value, bytes):
+            return value.decode("utf-8")
+        return str(value)
+
+    def delete(self, *names: str) -> int:
+        return integer_response(self._redis.delete(*names))
+
+    def eval(
+        self,
+        script: str,
+        numkeys: int,
+        *keys_and_args: str | int,
+    ) -> object:
+        return self._redis.eval(script, numkeys, *keys_and_args)

fencekit/errors.py

@@ -0,0 +1,42 @@
+"""Public exception hierarchy for fencekit."""
+
+from __future__ import annotations
+
+
+class FenceKitError(Exception):
+    """Base error for all fencekit failures."""
+
+
+class LockNotAcquired(FenceKitError):
+    """Raised when a lock could not be acquired within the requested wait."""
+
+
+class LockNotOwned(FenceKitError):
+    """Raised when release/extend is attempted without owning the lock.
+
+    Typical causes: lock TTL expired, another owner holds the key, or the
+    handle's owner_id does not match Redis.
+    """
+
+
+class IdempotencyNotOwned(FenceKitError):
+    """Raised when a worker cannot complete an idempotency key it does not own."""
+
+
+class FencedOutError(FenceKitError):
+    """Raised when a write presents a fencing token older than the gate max.
+
+    A stale holder receives this error after a newer owner advances the fence.
+    """
+
+
+class TokenExpiredError(FenceKitError):
+    """Raised when a lock handle is known to be expired before a write.
+
+    Optional fast-path for callers that track local expiry; Redis remains the
+    source of truth for ownership.
+    """
+
+
+class CanonicalizeError(FenceKitError):
+    """Raised when a payload cannot be deterministically canonicalized."""

fencekit/fence.py

@@ -0,0 +1,114 @@
+"""Redis-backed fencing gate (storage-layer token enforcement)."""
+
+from __future__ import annotations
+
+from fencekit.client import RedisClient, SyncRedis, integer_response
+from fencekit.errors import FencedOutError
+from fencekit.keys import DEFAULT_PREFIX, KeySpace
+from fencekit.scripts import (
+    FENCE_ADVANCE_SCRIPT,
+    FENCE_CHECK_SCRIPT,
+    FENCED_SET_SCRIPT,
+)
+from fencekit.types import FenceToken
+
+
+class FenceGate:
+    """Enforce monotonic fencing tokens on a Redis-backed resource gate.
+
+    Use :meth:`set_if_fresh` to combine a Redis ``SET`` and fence comparison in
+    one atomic script. :meth:`check` is diagnostic only: a separate write after
+    a check has a time-of-check/time-of-use race.
+
+    For PostgreSQL (or other stores), reject stale tokens atomically in the
+    same statement as the mutation, for example::
+
+        UPDATE analysis_job
+        SET progress = %s, fence_token = %s
+        WHERE id = %s AND fence_token <= %s
+
+    Redis alone does not protect writes that bypass this gate.
+    """
+
+    def __init__(
+        self,
+        redis: SyncRedis | RedisClient,
+        *,
+        prefix: str = DEFAULT_PREFIX,
+    ) -> None:
+        self._client = redis if isinstance(redis, RedisClient) else RedisClient(redis)
+        self._keys = KeySpace(prefix)
+
+    def current_max(self, resource: str) -> int:
+        """Return the highest token accepted for *resource* (0 if none)."""
+        raw = self._client.get(self._keys.fence_max(resource))
+        if raw is None:
+            return 0
+        return int(raw)
+
+    def check(self, token: FenceToken) -> None:
+        """Raise :class:`FencedOutError` if *token* is strictly less than max.
+
+        Equal tokens are allowed (same acquire, multiple writes). This method
+        does not advance the gate and must not be used as authorization for a
+        later, separate write.
+        """
+        max_key = self._keys.fence_max(token.resource)
+        result = self._client.eval(
+            FENCE_CHECK_SCRIPT,
+            1,
+            max_key,
+            token.value,
+        )
+        if integer_response(result) != 1:
+            raise FencedOutError(
+                f"token {token.value} for {token.resource!r} is fenced out "
+                f"(max={self.current_max(token.resource)})"
+            )
+
+    def check_and_advance(self, token: FenceToken) -> None:
+        """Accept *token* if ``token >= max``, then set max to *token*.
+
+        Raises :class:`FencedOutError` if a *newer* token was already recorded
+        (stale-holder rejection). The same token may write repeatedly.
+        """
+        max_key = self._keys.fence_max(token.resource)
+        result = self._client.eval(
+            FENCE_ADVANCE_SCRIPT,
+            1,
+            max_key,
+            token.value,
+        )
+        if integer_response(result) != 1:
+            raise FencedOutError(
+                f"token {token.value} for {token.resource!r} is fenced out "
+                f"(max={self.current_max(token.resource)})"
+            )
+
+    def set_if_fresh(self, token: FenceToken, key: str, value: str) -> None:
+        """Atomically set Redis *key* when *token* is not stale.
+
+        The target write and max-token update execute in one Lua script. Raises
+        :class:`FencedOutError` without changing *key* when ``token < max``.
+        Equal tokens are accepted so one lock acquisition can update progress
+        multiple times. The caller owns *key* and must not point it at a
+        fencekit coordination key.
+        """
+        if not key or not isinstance(key, str):
+            raise ValueError("key must be a non-empty str")
+        max_key = self._keys.fence_max(token.resource)
+        if key == max_key:
+            raise ValueError("target key must not be the fence max key")
+        result = self._client.eval(
+            FENCED_SET_SCRIPT,
+            2,
+            max_key,
+            key,
+            token.value,
+            value,
+        )
+        if integer_response(result) != 1:
+            raise FencedOutError(
+                f"token {token.value} for {token.resource!r} is fenced out "
+                f"(max={self.current_max(token.resource)})"
+            )

fencekit/idempotency.py

@@ -0,0 +1,81 @@
+"""Idempotency guard via Redis SET NX EX."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import timedelta
+
+from fencekit.client import RedisClient, SyncRedis, integer_response
+from fencekit.errors import IdempotencyNotOwned
+from fencekit.keys import DEFAULT_PREFIX, KeySpace
+from fencekit.scripts import MARK_DONE_SCRIPT
+
+
+def _ttl_seconds(ttl: timedelta) -> int:
+    seconds = int(ttl.total_seconds())
+    if seconds < 1:
+        raise ValueError("ttl must be at least 1 second for idempotency keys")
+    return seconds
+
+
+class IdempotencyGuard:
+    """At-most-once *start* of a named unit of work under Redis availability.
+
+    Uses ``SET key pending:{owner_id} NX EX ttl``. Concurrent workers: only one
+    begins, and completion is owner-checked. Pair with
+    :class:`~fencekit.lock.DistributedLock` and
+    :class:`~fencekit.fence.FenceGate` for long jobs with crash/redelivery.
+    """
+
+    def __init__(
+        self,
+        redis: SyncRedis | RedisClient,
+        *,
+        prefix: str = DEFAULT_PREFIX,
+        owner_id: str | None = None,
+    ) -> None:
+        self._client = redis if isinstance(redis, RedisClient) else RedisClient(redis)
+        self._keys = KeySpace(prefix)
+        self._owner_id = owner_id or str(uuid.uuid4())
+
+    def try_begin(self, key: str, *, ttl: timedelta) -> bool:
+        """Return True if this caller won the right to begin work for *key*."""
+        redis_key = self._keys.idempotency(key)
+        return self._client.set(
+            redis_key,
+            f"pending:{self._owner_id}",
+            nx=True,
+            ex=_ttl_seconds(ttl),
+        )
+
+    def mark_done(self, key: str, *, ttl: timedelta | None = None) -> None:
+        """Mark *key* as done (refresh TTL if provided).
+
+        Raises :class:`IdempotencyNotOwned` if the key expired, was reclaimed by
+        another guard, or was not begun by this guard. This prevents a stale
+        worker from completing a newer worker's attempt.
+        """
+        redis_key = self._keys.idempotency(key)
+        ttl_arg = _ttl_seconds(ttl) if ttl is not None else 0
+        result = self._client.eval(
+            MARK_DONE_SCRIPT,
+            1,
+            redis_key,
+            self._owner_id,
+            ttl_arg,
+        )
+        if integer_response(result) != 1:
+            raise IdempotencyNotOwned(
+                f"cannot complete idempotency key {key!r}: not owned or expired"
+            )
+
+    def clear(self, key: str) -> None:
+        """Delete the idempotency key (intentional replay / admin)."""
+        self._client.delete(self._keys.idempotency(key))
+
+    def status(self, key: str) -> str | None:
+        """Return ``pending``, ``done``, or ``None`` if absent."""
+        status = self._client.get(self._keys.idempotency(key))
+        if status is not None and status.startswith("pending:"):
+            return "pending"
+        return status

fencekit/keys.py

@@ -0,0 +1,41 @@
+"""Redis key naming helpers.
+
+Default prefix is ``fencekit``. Apps sharing a Redis DB should use distinct
+prefixes to avoid collisions.
+"""
+
+from __future__ import annotations
+
+DEFAULT_PREFIX = "fencekit"
+
+
+def _validate_segment(name: str, label: str) -> str:
+    if not name or not isinstance(name, str):
+        raise ValueError(f"{label} must be a non-empty str")
+    if any(character.isspace() for character in name):
+        raise ValueError(f"{label} must not contain whitespace")
+    return name
+
+
+class KeySpace:
+    """Build namespaced Redis keys for locks, fences, and idempotency."""
+
+    def __init__(self, prefix: str = DEFAULT_PREFIX) -> None:
+        self.prefix = _validate_segment(prefix, "prefix")
+
+    def idempotency(self, key: str) -> str:
+        """Build ``{prefix}:idem:{namespace}:{sha256}`` from a namespaced key."""
+        key = _validate_segment(key, "idempotency key")
+        return f"{self.prefix}:idem:{key}"
+
+    def lock(self, resource: str) -> str:
+        resource = _validate_segment(resource, "resource")
+        return f"{self.prefix}:lock:{resource}"
+
+    def fence_seq(self, resource: str) -> str:
+        resource = _validate_segment(resource, "resource")
+        return f"{self.prefix}:fence:seq:{resource}"
+
+    def fence_max(self, resource: str) -> str:
+        resource = _validate_segment(resource, "resource")
+        return f"{self.prefix}:fence:max:{resource}"

fencekit/lock.py

@@ -0,0 +1,167 @@
+"""Distributed lock with atomic fencing-token issuance."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import Iterator
+from contextlib import contextmanager, suppress
+from datetime import timedelta
+
+from fencekit.client import RedisClient, SyncRedis, integer_response
+from fencekit.errors import LockNotAcquired, LockNotOwned
+from fencekit.keys import DEFAULT_PREFIX, KeySpace
+from fencekit.scripts import ACQUIRE_SCRIPT, EXTEND_SCRIPT, RELEASE_SCRIPT
+from fencekit.types import FenceToken, LockHandle
+
+_DEFAULT_RETRY_INTERVAL = timedelta(milliseconds=50)
+
+
+def _ttl_ms(ttl: timedelta) -> int:
+    ms = int(ttl.total_seconds() * 1000)
+    if ms < 1:
+        raise ValueError("ttl must be at least 1ms")
+    return ms
+
+
+class DistributedLock:
+    """Single-instance Redis lock with fencing tokens.
+
+    Acquire uses a Lua script that ``SET``s the lock ``NX PX`` and ``INCR``s the
+    fence sequence in one atomic step. Release/extend only succeed if the
+    caller still owns the lock key.
+
+    This is **not** Redlock. See DESIGN.md for guarantees and caveats.
+    """
+
+    def __init__(
+        self,
+        redis: SyncRedis | RedisClient,
+        *,
+        prefix: str = DEFAULT_PREFIX,
+    ) -> None:
+        self._client = redis if isinstance(redis, RedisClient) else RedisClient(redis)
+        self._keys = KeySpace(prefix)
+
+    def acquire(
+        self,
+        resource: str,
+        *,
+        ttl: timedelta,
+        owner_id: str | None = None,
+        blocking: bool = False,
+        wait: timedelta | None = None,
+        retry_interval: timedelta = _DEFAULT_RETRY_INTERVAL,
+    ) -> LockHandle:
+        """Acquire *resource* and return a :class:`LockHandle` with a fence token.
+
+        If *blocking* is False (default), raises :class:`LockNotAcquired` on
+        contention. If True, retries until *wait* elapses (required when
+        blocking).
+        """
+        if retry_interval.total_seconds() <= 0:
+            raise ValueError("retry_interval must be positive")
+        owner = owner_id or str(uuid.uuid4())
+        deadline: float | None = None
+        if blocking:
+            if wait is None:
+                raise ValueError("wait is required when blocking=True")
+            if wait.total_seconds() < 0:
+                raise ValueError("wait must not be negative")
+            deadline = time.monotonic() + wait.total_seconds()
+
+        while True:
+            handle = self._try_acquire(resource, ttl=ttl, owner_id=owner)
+            if handle is not None:
+                return handle
+            if not blocking or deadline is None:
+                raise LockNotAcquired(f"could not acquire lock for {resource!r}")
+            if time.monotonic() >= deadline:
+                raise LockNotAcquired(
+                    f"timed out waiting for lock {resource!r} after {wait}"
+                )
+            time.sleep(retry_interval.total_seconds())
+
+    def _try_acquire(
+        self,
+        resource: str,
+        *,
+        ttl: timedelta,
+        owner_id: str,
+    ) -> LockHandle | None:
+        lock_key = self._keys.lock(resource)
+        seq_key = self._keys.fence_seq(resource)
+        result = self._client.eval(
+            ACQUIRE_SCRIPT,
+            2,
+            lock_key,
+            seq_key,
+            owner_id,
+            _ttl_ms(ttl),
+        )
+        if result is None or result is False:
+            return None
+        token_value = integer_response(result)
+        return LockHandle(
+            resource=resource,
+            owner_id=owner_id,
+            token=FenceToken(value=token_value, resource=resource),
+            ttl=ttl,
+        )
+
+    def release(self, handle: LockHandle) -> None:
+        """Release *handle* if still owned; raise :class:`LockNotOwned` otherwise."""
+        lock_key = self._keys.lock(handle.resource)
+        result = self._client.eval(
+            RELEASE_SCRIPT,
+            1,
+            lock_key,
+            handle.owner_id,
+        )
+        if integer_response(result) != 1:
+            raise LockNotOwned(
+                f"cannot release lock {handle.resource!r}: not owned or expired"
+            )
+
+    def extend(self, handle: LockHandle, *, ttl: timedelta) -> None:
+        """Extend lock TTL if still owned (heartbeat)."""
+        lock_key = self._keys.lock(handle.resource)
+        result = self._client.eval(
+            EXTEND_SCRIPT,
+            1,
+            lock_key,
+            handle.owner_id,
+            _ttl_ms(ttl),
+        )
+        if integer_response(result) != 1:
+            raise LockNotOwned(
+                f"cannot extend lock {handle.resource!r}: not owned or expired"
+            )
+
+    @contextmanager
+    def hold(
+        self,
+        resource: str,
+        *,
+        ttl: timedelta,
+        owner_id: str | None = None,
+        blocking: bool = False,
+        wait: timedelta | None = None,
+    ) -> Iterator[LockHandle]:
+        """Context-manager helper: ``with lock.hold("res", ttl=...) as handle``."""
+        handle = self.acquire(
+            resource,
+            ttl=ttl,
+            owner_id=owner_id,
+            blocking=blocking,
+            wait=wait,
+        )
+        try:
+            yield handle
+        except BaseException:
+            # Preserve the critical-section exception if the lease also expired.
+            with suppress(LockNotOwned):
+                self.release(handle)
+            raise
+        else:
+            self.release(handle)

fencekit/scripts.py

@@ -0,0 +1,96 @@
+"""Lua scripts for atomic lock and fence operations.
+
+Scripts are evaluated with EVAL so they work without prior SCRIPT LOAD.
+"""
+
+from __future__ import annotations
+
+# KEYS[1]=lock_key, KEYS[2]=seq_key; ARGV[1]=owner_id, ARGV[2]=ttl_ms.
+# Returns a fencing token (integer) or false. INCR happens before SET because
+# Redis scripts are atomic but do not roll back writes after a runtime error:
+# a corrupt/overflowing counter must not leave a lock without a token.
+ACQUIRE_SCRIPT = """
+if redis.call('EXISTS', KEYS[1]) == 1 then
+  return false
+end
+local token = redis.call('INCR', KEYS[2])
+if redis.call('SET', KEYS[1], ARGV[1], 'PX', ARGV[2], 'NX') then
+  return token
+end
+return false
+"""
+
+# KEYS[1]=lock_key; ARGV[1]=owner_id
+# Returns 1 if deleted, 0 otherwise.
+RELEASE_SCRIPT = """
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('DEL', KEYS[1])
+end
+return 0
+"""
+
+# KEYS[1]=lock_key; ARGV[1]=owner_id, ARGV[2]=ttl_ms
+# Returns 1 if extended, 0 otherwise.
+EXTEND_SCRIPT = """
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('PEXPIRE', KEYS[1], ARGV[2])
+end
+return 0
+"""
+
+# KEYS[1]=max_key; ARGV[1]=token
+# Returns 1 if accepted (token >= max), 0 if fenced out (token < max).
+# Equal tokens are allowed so one acquire can write multiple times.
+FENCE_ADVANCE_SCRIPT = """
+local max = tonumber(redis.call('GET', KEYS[1]) or '0')
+local token = tonumber(ARGV[1])
+if token < max then
+  return 0
+end
+redis.call('SET', KEYS[1], ARGV[1])
+return 1
+"""
+
+# KEYS[1]=max_key; ARGV[1]=token
+# Returns 1 if token >= max (allowed), 0 if fenced out. Does not advance.
+FENCE_CHECK_SCRIPT = """
+local max = tonumber(redis.call('GET', KEYS[1]) or '0')
+local token = tonumber(ARGV[1])
+if token < max then
+  return 0
+end
+return 1
+"""
+
+# KEYS[1]=max_key, KEYS[2]=target_key; ARGV[1]=token, ARGV[2]=value.
+# The fence comparison and target mutation are one atomic Redis operation.
+FENCED_SET_SCRIPT = """
+local max = tonumber(redis.call('GET', KEYS[1]) or '0')
+local token = tonumber(ARGV[1])
+if token < max then
+  return 0
+end
+redis.call('SET', KEYS[1], ARGV[1])
+redis.call('SET', KEYS[2], ARGV[2])
+return 1
+"""
+
+# KEYS[1]=idem_key; ARGV[1]=owner_id, ARGV[2]=ttl_seconds.
+# Mark done only for the worker that began. Returns 1 if completed.
+MARK_DONE_SCRIPT = """
+local expected = 'pending:' .. ARGV[1]
+if redis.call('GET', KEYS[1]) ~= expected then
+  return 0
+end
+local ttl = tonumber(ARGV[2])
+if ttl ~= nil and ttl > 0 then
+  redis.call('SET', KEYS[1], 'done', 'EX', ttl)
+else
+  local pttl = redis.call('PTTL', KEYS[1])
+  redis.call('SET', KEYS[1], 'done')
+  if pttl > 0 then
+    redis.call('PEXPIRE', KEYS[1], pttl)
+  end
+end
+return 1
+"""

fencekit/types.py

@@ -0,0 +1,42 @@
+"""Shared value types for locks and fencing tokens."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+
+
+@dataclass(frozen=True, slots=True)
+class FenceToken:
+    """Monotonic token issued on each successful lock acquire.
+
+    Pass this token to :class:`~fencekit.fence.FenceGate` (and to your own
+    storage layer) on every write under the lock.
+    """
+
+    value: int
+    resource: str
+
+    def __post_init__(self) -> None:
+        if self.value < 1:
+            raise ValueError("fence token value must be positive")
+        if not self.resource:
+            raise ValueError("fence token resource must be non-empty")
+
+
+@dataclass(frozen=True, slots=True)
+class LockHandle:
+    """Proof of lock ownership returned by :meth:`DistributedLock.acquire`."""
+
+    resource: str
+    owner_id: str
+    token: FenceToken
+    ttl: timedelta
+
+    def __post_init__(self) -> None:
+        if not self.owner_id:
+            raise ValueError("lock owner_id must be non-empty")
+        if self.token.resource != self.resource:
+            raise ValueError("lock token resource must match handle resource")
+        if self.ttl.total_seconds() <= 0:
+            raise ValueError("lock ttl must be positive")

fencekit-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: fencekit
+Version: 0.1.0
+Summary: Redis-backed idempotent task primitives: fencing tokens and distributed locks
+Project-URL: Homepage, https://github.com/ahmed5145/fencekit
+Project-URL: Documentation, https://github.com/ahmed5145/fencekit/blob/main/DESIGN.md
+Project-URL: Changelog, https://github.com/ahmed5145/fencekit/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/ahmed5145/fencekit
+Author-email: Ahmed Mohamed <ahmed5145@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: celery,distributed-lock,fencing-token,idempotency,redis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: redis>=5.0.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fencekit
+
+Redis-backed idempotency and fenced locks for background jobs. A destination that
+atomically checks the fencing token can reject writes from a stale lock holder.
+
+## Why
+
+ChessMate ([chess-mate.online](https://chess-mate.online)) runs imported games
+through Stockfish before writing a coaching report. With Redis as the Celery broker
+and late acknowledgements enabled, a worker crash can cause the same job to be
+delivered again. I saw batches progress twice. That wasted Stockfish CPU and left
+the recorded progress ambiguous.
+
+Celery requires late-ack tasks to be idempotent, but each task still needs code to
+enforce that property. fencekit collects the Redis operations I used in ChessMate.
+Its tests reproduce worker death and lock-expiry races.
+
+## Install
+
+```bash
+pip install fencekit
+# or
+uv add fencekit
+```
+
+Requires Redis 6+ (tested with Redis 7) and Python 3.10+.
+
+## 30-second example
+
+```python
+from datetime import timedelta
+from redis import Redis
+
+from fencekit import (
+    DistributedLock,
+    FenceGate,
+    IdempotencyGuard,
+    idempotency_key,
+)
+
+r = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
+guard = IdempotencyGuard(r)
+lock = DistributedLock(r)
+fence = FenceGate(r)
+
+def analyze_batch() -> None:
+    key = idempotency_key(
+        {"game_ids": ["abc", "def"], "engine": "sf16"},
+        namespace="analysis",
+    )
+    if not guard.try_begin(key, ttl=timedelta(hours=24)):
+        return  # already started or completed
+
+    handle = lock.acquire("analysis:batch-42", ttl=timedelta(minutes=5))
+    try:
+        # Atomic fence check + Redis progress write:
+        fence.set_if_fresh(handle.token, "analysis:batch-42:status", "running")
+        # Extend the lock on heartbeats and fence every durable write.
+        guard.mark_done(key)
+    finally:
+        lock.release(handle)
+```
+
+## Guarantees
+
+| Claim | Status |
+|-------|--------|
+| At-most-once *start* within the idempotency TTL (Redis available) | Yes (`SET NX`) |
+| Mutual exclusion while lock TTL held (single Redis primary) | Best-effort lease |
+| Stale holder cannot overwrite via atomic `FenceGate.set_if_fresh` | Yes |
+| Exactly-once delivery | No |
+| Safety under Redis failover / split brain | No (v0.1) |
+| Safety if the app writes without presenting the token | No |
+
+See [DESIGN.md](DESIGN.md) for the threat model, Lua algorithms, TTL guidance, and
+crash/restart semantics. fencekit does not implement Redlock.
+
+Fencing covers stale overwrites. Exactly-once external effects also require the
+destination to enforce the fence token and a unique business-operation key in
+one atomic operation.
+
+## Running tests
+
+```bat
+REM CMD (Windows), no uv required
+cd fencekit
+python -m pip install -e ".[dev]"
+python -m ruff check --fix src tests
+python -m ruff check src tests
+python -m mypy src
+python -m pytest -m "not integration" -q
+```
+
+The full suite needs Redis on `localhost:6379`:
+
+```bat
+set FENCEKIT_REDIS_URL=redis://localhost:6379/15
+python -m pytest -q
+```
+
+Integration tests skip cleanly when Redis is unreachable or `FENCEKIT_REDIS_URL` is unset.
+
+```bash
+# Linux/macOS with uv + Docker
+uv sync --extra dev
+uv run pytest -m "not integration"
+docker run -d -p 6379:6379 --name fencekit-redis redis:7
+export FENCEKIT_REDIS_URL=redis://localhost:6379/15
+uv run pytest
+```
+
+v0.1 has no Celery adapter. A later release may add one as an optional extra.
+
+## License
+
+MIT

fencekit-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+fencekit/__init__.py,sha256=6GL2fPRMmixEg-9ksteFsTOYuh0k7LW1XORBEkK72wc,956
+fencekit/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+fencekit/canonicalize.py,sha256=MyF5QQT91pOR8Vxrbdw1q0_9HKGqgfr4JGKRt6VSIio,3103
+fencekit/client.py,sha256=iLUSyvodgVpA_UCo-y7uhRoiqSTb20CnOxmL1T60SMU,2363
+fencekit/errors.py,sha256=ZZD_I-QTP9HPN73KDHl9P8wSEj0Xw_UlkGcrcitk1OQ,1203
+fencekit/fence.py,sha256=cGfU83ULag1qd_6UNBs3VdO8G5xigALjpCQm5uxY7Nk,4181
+fencekit/idempotency.py,sha256=FJcomc5yB3s3TQypaMOKPy6DSeGdF74zl-jvQVGq0HY,2891
+fencekit/keys.py,sha256=f6wN1Y-bQa4DMoabHDanXjwpk4y4urW1VO1SMFlJMMw,1412
+fencekit/lock.py,sha256=X1sMTCZKtxyeDcPdpMvFV8QpNxNDKqzEw2JmNMdQSw4,5450
+fencekit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fencekit/scripts.py,sha256=S9hwlczjXty0s5nPOfdcbDRkBjJGfdt1NDSC4DFh8VE,2657
+fencekit/types.py,sha256=xDz17F3YGRHCnE3sEmopOvGwx2OUjoIHJYodf9holsQ,1250
+fencekit-0.1.0.dist-info/METADATA,sha256=3CsN_STn830fvmsyjG4UcZix8EYaxsml7bODdT911ww,4823
+fencekit-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+fencekit-0.1.0.dist-info/licenses/LICENSE,sha256=dIUelP4H--LLD133BC9h2F8JORlyOr9dm6TCijqQXIo,1070
+fencekit-0.1.0.dist-info/RECORD,,

fencekit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fencekit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Mohamed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.