postkit 0.2.0__tar.gz → 0.3.0__tar.gz

{postkit-0.2.0 → postkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: postkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: PostgreSQL-native auth, permissions, versioned config, usage tracking, and job queues
 Project-URL: Homepage, https://github.com/varunchopra/postkit
 Project-URL: Repository, https://github.com/varunchopra/postkit
@@ -54,6 +54,7 @@ cursor = conn.cursor()
 
 # Authorization
 authz = AuthzClient(cursor, namespace="my-app")
+authz.set_hierarchy("repo", "admin", "write", "read")
 authz.grant("admin", resource=("repo", "api"), subject=("user", "alice"))
 if authz.check(("user", "alice"), "read", ("repo", "api")):
     print("Access granted")

{postkit-0.2.0 → postkit-0.3.0}/README.md

@@ -20,6 +20,7 @@ cursor = conn.cursor()
 
 # Authorization
 authz = AuthzClient(cursor, namespace="my-app")
+authz.set_hierarchy("repo", "admin", "write", "read")
 authz.grant("admin", resource=("repo", "api"), subject=("user", "alice"))
 if authz.check(("user", "alice"), "read", ("repo", "api")):
     print("Access granted")

{postkit-0.2.0 → postkit-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "postkit"
-version = "0.2.0"
+version = "0.3.0"
 description = "PostgreSQL-native auth, permissions, versioned config, usage tracking, and job queues"
 readme = "README.md"
 license = "Apache-2.0"

{postkit-0.2.0 → postkit-0.3.0}/src/postkit/authz/client.py

@@ -9,6 +9,8 @@ This module provides:
 
 from __future__ import annotations
 
+from collections.abc import Iterator
+from contextlib import contextmanager
 from datetime import datetime, timedelta
 
 import psycopg
@@ -84,6 +86,17 @@ class AuthzClient(BaseClient):
         to see grants where they are the recipient across ALL namespaces.
         Required for "Shared with me" / external resources functionality.
 
+        The setting is session-scoped. With an in-process connection pool,
+        prefer viewer_context(), which clears it however the block exits.
+        Behind PgBouncer in session pooling mode, DISCARD ALL between
+        clients also clears it; in transaction pooling mode session-scoped
+        settings are unsafe (they persist on some server connection for a
+        later client) AND unreliable (your next statement may run on a
+        different server connection), so do not use set_viewer there - set
+        the context transaction-locally instead (inside a transaction, run
+        set_config('authz.viewer_type', ..., true) and the same for
+        viewer_id).
+
         Args:
             subject: The subject as (type, id) tuple (e.g., ("user", "alice"))
 
@@ -116,6 +129,35 @@ class AuthzClient(BaseClient):
             "set_config('authz.viewer_id', '', false)"
         )
 
+    @contextmanager
+    def viewer_context(self, subject: Entity) -> Iterator[None]:
+        """Set the viewer context for the duration of a block.
+
+        Equivalent to set_viewer() followed by a guaranteed clear_viewer(),
+        so the session-scoped viewer identity cannot leak to the next user
+        of a pooled connection, whichever way the block exits. Exiting
+        clears the viewer entirely; it does not restore one that was set
+        before the block.
+
+        If the connection died inside the block, the clearing call raises
+        too; the original exception is chained as its __context__, and a
+        dead session cannot leak, so nothing is suppressed here.
+
+        Args:
+            subject: The subject as (type, id) tuple (e.g., ("user", "alice"))
+
+        Example:
+            with authz.viewer_context(("user", "alice")):
+                shared = authz.list_external_resources(
+                    ("user", "alice"), "note", "view"
+                )
+        """
+        self.set_viewer(subject)
+        try:
+            yield
+        finally:
+            self.clear_viewer()
+
     def _apply_actor_context(self) -> None:
         """Apply actor context via authz.set_actor()."""
         self.cursor.execute(

{postkit-0.2.0 → postkit-0.3.0}/src/postkit/base.py

@@ -200,7 +200,7 @@ class BaseClient(ABC):
         context automatically clears on commit, preventing cross-tenant
         leakage in connection pools.
 
-        Safe to call repeatedly within the same transaction — set_config
+        Safe to call repeatedly within the same transaction - set_config
         with the same value is a no-op at the PostgreSQL level.
         """
         try:

{postkit-0.2.0 → postkit-0.3.0}/src/postkit/config/client.py

@@ -41,7 +41,7 @@ class ConfigClient(BaseClient):
     """Client for Postkit config module.
 
     Manages versioned configuration including prompts, feature flags, secrets,
-    and settings. All config types use the same API — differentiate by key
+    and settings. All config types use the same API - differentiate by key
     naming conventions.
 
     Example:

{postkit-0.2.0 → postkit-0.3.0}/src/postkit/errors.py

@@ -142,6 +142,38 @@ class ConfigErrorCode:
     BIZ_DELETE_ACTIVE_VERSION = "BIZ_DELETE_ACTIVE_VERSION"
 
 
+class LeaseErrorCode:
+    """Error codes for the lease module."""
+
+    # Validation errors (VAL_)
+    VAL_NAMESPACE_NULL = "VAL_NAMESPACE_NULL"
+    VAL_NAMESPACE_EMPTY = "VAL_NAMESPACE_EMPTY"
+    VAL_NAMESPACE_TOO_LONG = "VAL_NAMESPACE_TOO_LONG"
+    VAL_NAMESPACE_INVALID_CHARS = "VAL_NAMESPACE_INVALID_CHARS"
+    VAL_NAMESPACE_WHITESPACE = "VAL_NAMESPACE_WHITESPACE"
+    VAL_LEASE_NAME_NULL = "VAL_LEASE_NAME_NULL"
+    VAL_LEASE_NAME_EMPTY = "VAL_LEASE_NAME_EMPTY"
+    VAL_LEASE_NAME_TOO_LONG = "VAL_LEASE_NAME_TOO_LONG"
+    VAL_LEASE_NAME_INVALID_CHARS = "VAL_LEASE_NAME_INVALID_CHARS"
+    VAL_LEASE_NAME_WHITESPACE = "VAL_LEASE_NAME_WHITESPACE"
+    VAL_HOLDER_NULL = "VAL_HOLDER_NULL"
+    VAL_HOLDER_EMPTY = "VAL_HOLDER_EMPTY"
+    VAL_HOLDER_TOO_LONG = "VAL_HOLDER_TOO_LONG"
+    VAL_HOLDER_INVALID_CHARS = "VAL_HOLDER_INVALID_CHARS"
+    VAL_HOLDER_WHITESPACE = "VAL_HOLDER_WHITESPACE"
+    VAL_TTL_NOT_POSITIVE = "VAL_TTL_NOT_POSITIVE"
+    VAL_TTL_EXCEEDS_MAX = "VAL_TTL_EXCEEDS_MAX"
+    VAL_FENCE_NULL = "VAL_FENCE_NULL"
+    VAL_NOT_POSITIVE = "VAL_NOT_POSITIVE"
+    VAL_PRUNE_INTERVAL_NOT_POSITIVE = "VAL_PRUNE_INTERVAL_NOT_POSITIVE"
+
+    # Fencing (raised with SQLSTATE 40001, serialization_failure)
+    FENCE_STALE = "FENCE_STALE"
+
+    # Internal errors (INT_)
+    INT_COUNTER_MISSING = "INT_COUNTER_MISSING"
+
+
 class MeterErrorCode:
     """Error codes for the meter module."""
 
@@ -173,6 +205,41 @@ class MeterErrorCode:
     DATA_ACCOUNT_NOT_FOUND = "DATA_ACCOUNT_NOT_FOUND"
 
 
+class OutboxErrorCode:
+    """Error codes for the outbox module."""
+
+    # Validation errors (VAL_)
+    VAL_NAMESPACE_NULL = "VAL_NAMESPACE_NULL"
+    VAL_NAMESPACE_EMPTY = "VAL_NAMESPACE_EMPTY"
+    VAL_NAMESPACE_TOO_LONG = "VAL_NAMESPACE_TOO_LONG"
+    VAL_NAMESPACE_INVALID_CHARS = "VAL_NAMESPACE_INVALID_CHARS"
+    VAL_NAMESPACE_WHITESPACE = "VAL_NAMESPACE_WHITESPACE"
+    VAL_TOPIC_NULL = "VAL_TOPIC_NULL"
+    VAL_TOPIC_EMPTY = "VAL_TOPIC_EMPTY"
+    VAL_TOPIC_TOO_LONG = "VAL_TOPIC_TOO_LONG"
+    VAL_TOPIC_RESERVED = "VAL_TOPIC_RESERVED"
+    VAL_TOPIC_FORMAT = "VAL_TOPIC_FORMAT"
+    VAL_CONSUMER_NULL = "VAL_CONSUMER_NULL"
+    VAL_CONSUMER_EMPTY = "VAL_CONSUMER_EMPTY"
+    VAL_CONSUMER_TOO_LONG = "VAL_CONSUMER_TOO_LONG"
+    VAL_CONSUMER_FORMAT = "VAL_CONSUMER_FORMAT"
+    VAL_EVENT_TYPE_NULL = "VAL_EVENT_TYPE_NULL"
+    VAL_EVENT_TYPE_EMPTY = "VAL_EVENT_TYPE_EMPTY"
+    VAL_EVENT_TYPE_TOO_LONG = "VAL_EVENT_TYPE_TOO_LONG"
+    VAL_EVENT_TYPE_FORMAT = "VAL_EVENT_TYPE_FORMAT"
+    VAL_PAYLOAD_NULL = "VAL_PAYLOAD_NULL"
+    VAL_NOT_POSITIVE = "VAL_NOT_POSITIVE"
+    VAL_POSITION_INVALID = "VAL_POSITION_INVALID"
+    VAL_SUBSCRIBE_FROM_REQUIRED = "VAL_SUBSCRIBE_FROM_REQUIRED"
+    VAL_TRIM_INTERVAL_NOT_POSITIVE = "VAL_TRIM_INTERVAL_NOT_POSITIVE"
+
+    # Business logic errors (BIZ_)
+    BIZ_CONSUMER_EXISTS = "BIZ_CONSUMER_EXISTS"
+    BIZ_CONSUMER_UNKNOWN = "BIZ_CONSUMER_UNKNOWN"
+    BIZ_CURSOR_LOST = "BIZ_CURSOR_LOST"
+    BIZ_POSITION_BEYOND_HEAD = "BIZ_POSITION_BEYOND_HEAD"
+
+
 class QueueErrorCode:
     """Error codes for the queue module."""
 

postkit-0.3.0/src/postkit/lease/__init__.py

@@ -0,0 +1,17 @@
+"""Postkit Lease SDK - Postgres-native leases with fencing tokens."""
+
+from postkit.errors import LeaseErrorCode
+from postkit.lease.client import (
+    LeaseClient,
+    LeaseError,
+    LeaseFencingError,
+    LeaseValidationError,
+)
+
+__all__ = [
+    "LeaseClient",
+    "LeaseError",
+    "LeaseErrorCode",
+    "LeaseFencingError",
+    "LeaseValidationError",
+]

postkit-0.3.0/src/postkit/lease/client.py

@@ -0,0 +1,319 @@
+"""Postkit Lease SDK - Postgres-native leases with fencing tokens."""
+
+from __future__ import annotations
+
+import json
+from datetime import timedelta
+from typing import Any, NoReturn
+
+import psycopg
+
+from postkit.base import BaseClient, PostkitError
+
+
+class LeaseError(PostkitError):
+    """Exception for lease operations."""
+
+
+class LeaseValidationError(LeaseError):
+    """Raised when input validation fails."""
+
+
+class LeaseFencingError(LeaseError):
+    """Raised by verify() when the lease is lost, expired, or taken over.
+
+    The fence is dead: the correct recovery is RE-ACQUIRE, THEN REDO the
+    work – never replay the same transaction with the same fence (the replay
+    fails deterministically, so a naive retry loop spins).
+    """
+
+
+class LeaseClient(BaseClient):
+    """Client for Postkit lease module.
+
+    TTL-based named locks with fencing tokens. Call verify() inside the same
+    transaction as the writes the lease protects – the fence check and the
+    protected writes then commit or abort together.
+
+    Example:
+        lease = LeaseClient(cursor, namespace="acme")
+
+        got = lease.acquire("scheduler", holder="worker-1")
+        if got["acquired"]:
+            fence = got["fence_token"]
+            # ... inside the protected transaction:
+            lease.verify("scheduler", "worker-1", fence)  # raises if lost
+            # ... protected writes ...
+            lease.release("scheduler", "worker-1", fence)
+    """
+
+    _schema = "lease"
+    _error_class = LeaseError
+    _module_sqlstate_map = {
+        "22023": LeaseValidationError,  # invalid_parameter_value
+        "22004": LeaseValidationError,  # null_value_not_allowed
+        "22001": LeaseValidationError,  # string_data_right_truncation
+        "22026": LeaseValidationError,  # string_data_length_mismatch
+    }
+
+    def _handle_error(self, e: psycopg.Error) -> NoReturn:
+        # 40001 is a SHARED sqlstate: FOR SHARE under REPEATABLE READ can
+        # raise a genuine serialization failure inside any lease call. Only
+        # our hint makes it a fencing error; everything else must surface as
+        # the retryable serialization error it is (generic LeaseError,
+        # .sqlstate intact).
+        sqlstate = getattr(e, "sqlstate", None)
+        hint = e.diag.message_hint if hasattr(e, "diag") and e.diag else None
+        if sqlstate == "40001" and hint == "postkit:lease:FENCE_STALE":
+            raise LeaseFencingError(str(e), sqlstate, hint) from e
+        super()._handle_error(e)
+
+    def _apply_actor_context(self) -> None:
+        """Apply actor context via lease.set_actor()."""
+        self.cursor.execute(
+            """SELECT lease.set_actor(
+                p_actor_id := %s,
+                p_request_id := %s,
+                p_on_behalf_of := %s,
+                p_reason := %s
+            )""",
+            (self._actor_id, self._request_id, self._on_behalf_of, self._reason),
+        )
+
+    def acquire(
+        self,
+        name: str,
+        holder: str,
+        *,
+        ttl: timedelta | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Acquire or take over a named lease.
+
+        A free or expired lease makes the caller the holder with a new fence
+        token (takeovers are event-logged). Re-acquiring a lease you already
+        hold live extends it with the SAME fence; passing metadata replaces
+        the stored value, passing None keeps it. A lease held live by
+        someone else is not touched.
+
+        Do not call verify() then acquire() on the same name inside one
+        transaction: under concurrency that can abort as a deadlock
+        (SQLSTATE 40P01, retryable).
+
+        Args:
+            name: Lease name (e.g. 'scheduler', 'exporter:cust_42')
+            holder: Opaque holder identity (hostname, pod name, worker ID)
+            ttl: Lease duration (default from config; capped at max_ttl)
+            metadata: Metadata stored on the lease; None keeps the existing
+                metadata on a live re-acquire (new acquisitions start empty)
+
+        Returns:
+            Dict with acquired (bool), fence_token (None when held by
+            another live holder), expires_at, and current_holder (all
+            None on a lock timeout - an ordinary contended miss).
+        """
+        result = self._fetch_one(
+            """SELECT * FROM lease.acquire(
+                p_namespace := %s,
+                p_name := %s,
+                p_holder := %s,
+                p_ttl := %s,
+                p_metadata := %s::jsonb
+            )""",
+            (
+                self.namespace,
+                name,
+                holder,
+                ttl,
+                json.dumps(metadata) if metadata is not None else None,
+            ),
+            write=True,
+        )
+        if result is None:
+            raise LeaseError("lease.acquire returned no row")
+        return result
+
+    def renew(
+        self,
+        name: str,
+        holder: str,
+        fence: int,
+        *,
+        ttl: timedelta | None = None,
+    ) -> dict[str, Any]:
+        """Extend a live lease you hold.
+
+        Fails (renewed=False) once the lease is past its expiry – even if
+        nobody else has taken it. Re-acquire to continue, receiving a new
+        fence. Does not update metadata (acquire's same-holder path does).
+
+        Args:
+            name: Lease name
+            holder: Holder identity (must match the lease)
+            fence: Fence token from acquire (must match the lease)
+            ttl: New duration from now (default from config; capped at max_ttl)
+
+        Returns:
+            Dict with renewed (bool) and expires_at (None when not renewed)
+        """
+        result = self._fetch_one(
+            """SELECT * FROM lease.renew(
+                p_namespace := %s,
+                p_name := %s,
+                p_holder := %s,
+                p_fence := %s,
+                p_ttl := %s
+            )""",
+            (self.namespace, name, holder, fence, ttl),
+            write=True,
+        )
+        if result is None:
+            raise LeaseError("lease.renew returned no row")
+        return result
+
+    def release(self, name: str, holder: str, fence: int) -> bool:
+        """Release a lease you hold.
+
+        Idempotent: releasing a lease you no longer hold returns False,
+        never raises.
+
+        Args:
+            name: Lease name
+            holder: Holder identity (must match the lease)
+            fence: Fence token from acquire (must match the lease)
+
+        Returns:
+            True if released, False if not held with this holder and fence
+        """
+        result = self._fetch_val(
+            "SELECT lease.release(%s, %s, %s, %s)",
+            (self.namespace, name, holder, fence),
+            write=True,
+        )
+        return bool(result)
+
+    def verify(self, name: str, holder: str, fence: int) -> None:
+        """Assert, inside your transaction, that you still hold a lease.
+
+        Must be called inside the same open transaction as the writes the
+        lease protects; the check and the writes then commit or abort
+        together. Without one (autocommit, or between transactions) the
+        fence lock would be released immediately and protect nothing, so
+        this method refuses to run.
+
+        Do not call verify() then acquire() on the same name inside one
+        transaction: under concurrency that can abort as a deadlock
+        (SQLSTATE 40P01, retryable).
+
+        Args:
+            name: Lease name
+            holder: Holder identity (must match the lease)
+            fence: Fence token from acquire (must match the lease)
+
+        Raises:
+            LeaseError: No transaction is open on the connection.
+            LeaseFencingError: The lease is lost, expired, or taken over.
+                Re-acquire, then redo – never replay with the same fence.
+        """
+        # Same check _with_context uses: without an open transaction it
+        # would wrap verify in its own transaction that commits at return,
+        # releasing the FOR SHARE lock and silently voiding the guarantee.
+        if self.cursor.connection.info.transaction_status == 0:
+            raise LeaseError(
+                "verify() requires an open transaction: without one the "
+                "fence lock is released immediately and protects nothing. "
+                "Open a transaction around verify() and the writes it "
+                "protects."
+            )
+        self._fetch_val(
+            "SELECT lease.verify(%s, %s, %s, %s)",
+            (self.namespace, name, holder, fence),
+        )
+
+    def current(self, name: str) -> dict[str, Any] | None:
+        """Inspect a lease without locking it.
+
+        Returns the row even when past its expiry (compare expires_at to
+        judge liveness); use verify() for a fenced check.
+
+        Args:
+            name: Lease name
+
+        Returns:
+            Dict with holder_id, fence_token, expires_at, metadata,
+            or None when no lease row exists
+        """
+        return self._fetch_one(
+            "SELECT * FROM lease.current(%s, %s)", (self.namespace, name)
+        )
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get namespace-wide lease statistics.
+
+        Returns:
+            Dict with total_leases, live, expired, total_names (every lease
+            name ever used), and total_events counts
+        """
+        result = self._fetch_one(
+            "SELECT * FROM lease.get_stats(%s)",
+            (self.namespace,),
+        )
+        return result or {}
+
+    def get_events(
+        self, name: str | None = None, *, limit: int = 100
+    ) -> list[dict[str, Any]]:
+        """Read the lease event log, newest first.
+
+        Args:
+            name: Lease name filter (None = all names)
+            limit: Maximum events to return
+
+        Returns:
+            List of event dicts (acquired, released, taken_over) with
+            actor context
+        """
+        return self._fetch_all(
+            "SELECT * FROM lease.get_events(%s, %s, %s)",
+            (self.namespace, name, limit),
+        )
+
+    def prune_events(
+        self, older_than: timedelta, name: str | None = None, *, limit: int = 10000
+    ) -> int:
+        """Delete old lease events.
+
+        The event log is the module's audit surface, so retention has no
+        default – pass it explicitly and call this from a maintenance loop.
+        Each call deletes at most `limit` events; call repeatedly until the
+        return value is below the limit.
+
+        Args:
+            older_than: Delete events older than this (required, positive)
+            name: Lease name filter (None = all names)
+            limit: Maximum events to delete per call
+
+        Returns:
+            Count of deleted events
+        """
+        result = self._fetch_val(
+            "SELECT lease.prune_events(%s, %s, %s, %s)",
+            (self.namespace, older_than, name, limit),
+            write=True,
+        )
+        if result is None:
+            raise LeaseError("lease.prune_events returned no value")
+        return int(result)
+
+    def list_leases(self, *, include_expired: bool = True) -> list[dict[str, Any]]:
+        """List leases in the namespace, most recently acquired first.
+
+        Args:
+            include_expired: Include rows past their expiry (default True)
+
+        Returns:
+            List of lease row dicts
+        """
+        return self._fetch_all(
+            "SELECT * FROM lease.list(%s, %s)", (self.namespace, include_expired)
+        )

postkit-0.3.0/src/postkit/outbox/__init__.py

@@ -0,0 +1,17 @@
+"""Postkit Outbox SDK - transactional event feed with durable cursors."""
+
+from postkit.errors import OutboxErrorCode
+from postkit.outbox.client import (
+    OutboxClient,
+    OutboxCursorLostError,
+    OutboxError,
+    OutboxValidationError,
+)
+
+__all__ = [
+    "OutboxClient",
+    "OutboxCursorLostError",
+    "OutboxError",
+    "OutboxErrorCode",
+    "OutboxValidationError",
+]