postkit 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: postkit
-Version: 0.3.0
+Version: 0.4.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

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

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

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

@@ -240,6 +240,35 @@ class OutboxErrorCode:
     BIZ_POSITION_BEYOND_HEAD = "BIZ_POSITION_BEYOND_HEAD"
 
 
+class PresenceErrorCode:
+    """Error codes for the presence 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_ENTITY_NULL = "VAL_ENTITY_NULL"
+    VAL_ENTITY_EMPTY = "VAL_ENTITY_EMPTY"
+    VAL_ENTITY_TOO_LONG = "VAL_ENTITY_TOO_LONG"
+    VAL_ENTITY_INVALID_CHARS = "VAL_ENTITY_INVALID_CHARS"
+    VAL_ENTITY_WHITESPACE = "VAL_ENTITY_WHITESPACE"
+    VAL_ENTITIES_NULL = "VAL_ENTITIES_NULL"
+    VAL_KIND_NULL = "VAL_KIND_NULL"
+    VAL_KIND_EMPTY = "VAL_KIND_EMPTY"
+    VAL_KIND_TOO_LONG = "VAL_KIND_TOO_LONG"
+    VAL_KIND_FORMAT = "VAL_KIND_FORMAT"
+    VAL_TIMEOUT_NOT_POSITIVE = "VAL_TIMEOUT_NOT_POSITIVE"
+    VAL_STATUS_INVALID = "VAL_STATUS_INVALID"
+    VAL_TRIM_INTERVAL_NOT_POSITIVE = "VAL_TRIM_INTERVAL_NOT_POSITIVE"
+    VAL_NOT_POSITIVE = "VAL_NOT_POSITIVE"
+
+    # Business logic errors
+    ENTITY_UNKNOWN = "ENTITY_UNKNOWN"
+    HOOK_QUEUE_MISSING = "HOOK_QUEUE_MISSING"
+
+
 class QueueErrorCode:
     """Error codes for the queue module."""
 

postkit-0.4.0/src/postkit/presence/__init__.py

@@ -0,0 +1,15 @@
+"""Postkit Presence SDK - heartbeat liveness with transition edge detection."""
+
+from postkit.errors import PresenceErrorCode
+from postkit.presence.client import (
+    PresenceClient,
+    PresenceError,
+    PresenceValidationError,
+)
+
+__all__ = [
+    "PresenceClient",
+    "PresenceError",
+    "PresenceErrorCode",
+    "PresenceValidationError",
+]

postkit-0.4.0/src/postkit/presence/client.py

@@ -0,0 +1,274 @@
+"""Postkit Presence SDK - heartbeat liveness with transition edge detection."""
+
+from __future__ import annotations
+
+import json
+from datetime import timedelta
+from typing import Any
+
+from postkit.base import BaseClient, PostkitError
+
+
+class PresenceError(PostkitError):
+    """Exception for presence operations."""
+
+
+class PresenceValidationError(PresenceError):
+    """Raised when input validation fails."""
+
+
+class PresenceClient(BaseClient):
+    """Client for Postkit presence module.
+
+    Heartbeat liveness for a fleet of entities. Register once, heartbeat
+    periodically, and run sweep() on a timer; the module emits an
+    append-only transition stream (alive -> dead -> alive) and can enqueue
+    alert jobs atomically with each edge when the queue module is
+    installed.
+
+    Example:
+        presence = PresenceClient(cursor, namespace="acme")
+
+        presence.register("worker-7")            # once, idempotent
+        presence.heartbeat("worker-7")           # every 10-60s
+
+        # From a cron, anywhere:
+        for death in presence.sweep():
+            page(death["entity_id"])
+    """
+
+    _schema = "presence"
+    _error_class = PresenceError
+    _module_sqlstate_map = {
+        "22023": PresenceValidationError,  # invalid_parameter_value
+        "22004": PresenceValidationError,  # null_value_not_allowed
+        "22001": PresenceValidationError,  # string_data_right_truncation
+        "22026": PresenceValidationError,  # string_data_length_mismatch
+    }
+
+    def _apply_actor_context(self) -> None:
+        """Apply actor context via presence.set_actor()."""
+        self.cursor.execute(
+            """SELECT presence.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 register(
+        self,
+        entity: str,
+        *,
+        kind: str | None = None,
+        timeout: timedelta | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Register an entity for liveness tracking, or update its attributes.
+
+        Idempotent: None arguments preserve what is stored, so deploys can
+        re-run register safely. Re-registering is an attribute update, not
+        a heartbeat - liveness only changes through heartbeat() and
+        sweep(). A new entity starts at 'unknown' and cannot die before its
+        first heartbeat.
+
+        Args:
+            entity: Entity id (e.g. 'worker-7', 'sensor:eu:42')
+            kind: Entity kind, keys the config row. None means 'default'
+                for a new entity and keeps the current kind on re-register
+            timeout: Per-entity liveness window replacing the kind's
+                dead_after. None keeps the current override
+            metadata: Metadata stored on the entity; None keeps the
+                existing metadata on re-register (new entities start empty)
+
+        Returns:
+            The entity row dict
+        """
+        result = self._fetch_one(
+            """SELECT * FROM presence.register(
+                p_namespace := %s,
+                p_entity := %s,
+                p_kind := %s,
+                p_timeout := %s,
+                p_metadata := %s::jsonb
+            )""",
+            (
+                self.namespace,
+                entity,
+                kind,
+                timeout,
+                json.dumps(metadata) if metadata is not None else None,
+            ),
+            write=True,
+        )
+        if result is None:
+            raise PresenceError("presence.register returned no row")
+        return result
+
+    def heartbeat(self, entity: str) -> str:
+        """Report an entity alive.
+
+        A dead or never-seen entity revives here and now - the revival
+        transition is emitted by this call, never deferred to a sweep. An
+        unregistered entity raises (registration is explicit;
+        heartbeat_many reports 'unknown' instead of raising).
+
+        Args:
+            entity: Entity id (must be registered)
+
+        Returns:
+            The resulting status (always 'alive')
+        """
+        result = self._fetch_val(
+            "SELECT presence.heartbeat(%s, %s)",
+            (self.namespace, entity),
+            write=True,
+        )
+        if result is None:
+            raise PresenceError("presence.heartbeat returned no value")
+        return str(result)
+
+    def heartbeat_many(self, entities: list[str]) -> list[dict[str, Any]]:
+        """Report a batch of entities alive in one round trip.
+
+        Per-entity semantics match heartbeat(), including revivals.
+        Unregistered entities come back with status 'unknown' instead of
+        raising - one typo must not abort a fleet batch.
+
+        Args:
+            entities: Entity ids
+
+        Returns:
+            One dict per distinct entity: entity_id and its resulting status
+        """
+        return self._fetch_all(
+            "SELECT * FROM presence.heartbeat_many(%s, %s)",
+            (self.namespace, entities),
+            write=True,
+        )
+
+    def sweep(self, *, limit: int = 1000) -> list[dict[str, Any]]:
+        """Mark overdue entities dead and deliver deferred death alerts.
+
+        Call from a cron or timer; nothing runs on its own, and death is
+        detected no faster than the sweep cadence. Deaths emit transitions
+        and fire the configured queue hooks in the same transaction.
+
+        Args:
+            limit: Maximum entities to process per call
+
+        Returns:
+            The death transitions emitted by this call
+        """
+        return self._fetch_all(
+            "SELECT * FROM presence.sweep(%s, %s)",
+            (self.namespace, limit),
+            write=True,
+        )
+
+    def deregister(self, entity: str) -> bool:
+        """Remove an entity deliberately, emitting a departed transition.
+
+        Intentional exit is not death: no death hooks fire and nobody gets
+        paged for a planned shutdown. Idempotent - removing an absent
+        entity returns False, never raises.
+
+        Args:
+            entity: Entity id
+
+        Returns:
+            True if the entity existed and was removed
+        """
+        result = self._fetch_val(
+            "SELECT presence.deregister(%s, %s)",
+            (self.namespace, entity),
+            write=True,
+        )
+        return bool(result)
+
+    def status(self, entity: str) -> dict[str, Any] | None:
+        """Inspect one entity, with the wall-clock truth alongside the cache.
+
+        The stored status lags until the next sweep; the returned overdue
+        flag is true when the entity is nominally alive but already past
+        its liveness window.
+
+        Args:
+            entity: Entity id
+
+        Returns:
+            Dict with the liveness fields plus overdue, or None when the
+            entity is not registered
+        """
+        return self._fetch_one(
+            "SELECT * FROM presence.status(%s, %s)", (self.namespace, entity)
+        )
+
+    def list_entities(
+        self, *, kind: str | None = None, status: str | None = None
+    ) -> list[dict[str, Any]]:
+        """List entities in the namespace.
+
+        Args:
+            kind: Kind filter (None = all kinds)
+            status: Status filter: 'unknown', 'alive', or 'dead'
+
+        Returns:
+            List of entity row dicts
+        """
+        return self._fetch_all(
+            "SELECT * FROM presence.list(%s, %s, %s)",
+            (self.namespace, kind, status),
+        )
+
+    def get_transitions(
+        self, entity: str | None = None, *, limit: int = 100
+    ) -> list[dict[str, Any]]:
+        """Read the transition history, newest first.
+
+        History, not a feed: delivery is the queue hooks and NOTIFY; do
+        not poll this by id.
+
+        Args:
+            entity: Entity filter (None = all entities)
+            limit: Maximum transitions to return
+
+        Returns:
+            List of transition dicts with actor context
+        """
+        return self._fetch_all(
+            "SELECT * FROM presence.get_transitions(%s, %s, %s)",
+            (self.namespace, entity, limit),
+        )
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get namespace-wide presence statistics.
+
+        Returns:
+            Dict with total_entities, alive, dead, unknown, overdue, and
+            total_transitions counts
+        """
+        result = self._fetch_one(
+            "SELECT * FROM presence.get_stats(%s)", (self.namespace,)
+        )
+        return result or {}
+
+    def trim(
+        self, older_than: timedelta, *, limit: int = 10000
+    ) -> list[dict[str, Any]]:
+        """Delete old transitions. Retention has no default; pass it explicitly.
+
+        Args:
+            older_than: Delete transitions older than this (required, positive)
+            limit: Maximum transitions to delete per call
+
+        Returns:
+            One dict per namespace touched, with the deleted count
+        """
+        return self._fetch_all(
+            "SELECT * FROM presence.trim(%s, %s, %s)",
+            (older_than, self.namespace, limit),
+            write=True,
+        )

postkit-0.4.0/tests/integration/test_presence_hooks.py

@@ -0,0 +1,189 @@
+"""presence + queue composition: transition hooks enqueue jobs atomically.
+
+These tests need both schemas installed, so they live in the integration
+suite (the module suites run in parallel workers and must not depend on
+each other's schemas being present or absent).
+"""
+
+from datetime import datetime
+from pathlib import Path
+
+import psycopg
+import pytest
+from tests.conftest import DATABASE_URL
+from tests.helpers import make_namespace
+from tests.presence.helpers import PresenceTestHelpers
+from tests.presence.helpers import cleanup_namespace as _cleanup_presence
+
+
+@pytest.fixture(scope="module")
+def hooks_connection():
+    """Module-scoped connection with presence AND queue installed."""
+    conn = psycopg.connect(DATABASE_URL, autocommit=True)
+    conn.execute("DROP SCHEMA IF EXISTS presence CASCADE")
+    conn.execute("DROP SCHEMA IF EXISTS queue CASCADE")
+
+    dist_dir = Path(__file__).parent.parent.parent.parent / "dist"
+    for schema in ["presence", "queue"]:
+        sql_file = dist_dir / f"{schema}.sql"
+        if not sql_file.exists():
+            pytest.fail(f"dist/{schema}.sql not found. Run 'make build' first.")
+        conn.execute(sql_file.read_text())
+
+    yield conn
+
+    conn.execute("DROP SCHEMA IF EXISTS presence CASCADE")
+    conn.execute("DROP SCHEMA IF EXISTS queue CASCADE")
+    conn.close()
+
+
+@pytest.fixture
+def helpers(hooks_connection, request):
+    namespace = make_namespace(request)
+    cursor = hooks_connection.cursor()
+    h = PresenceTestHelpers(cursor, namespace)
+    cursor.execute("SELECT queue.set_tenant(%s)", (namespace,))
+
+    yield h
+
+    _cleanup_presence(cursor, namespace)
+    for table in ("jobs", "dead_letters", "schedules", "config"):
+        cursor.execute(f"DELETE FROM queue.{table} WHERE namespace = %s", (namespace,))
+    cursor.close()
+
+
+def register_and_kill_setup(h, entity="w1", **config):
+    """Register a live entity with a death hook configured, then backdate it."""
+    h.set_config(on_death_queue="alerts", **config)
+    h.cursor.execute("SELECT presence.register(%s, %s)", (h.namespace, entity))
+    h.cursor.execute("SELECT presence.heartbeat(%s, %s)", (h.namespace, entity))
+    h.set_last_seen(entity, "-10 minutes")
+
+
+def alert_jobs(h) -> list[dict]:
+    h.cursor.execute(
+        "SELECT payload FROM queue.jobs "
+        "WHERE namespace = %s AND queue = 'alerts' ORDER BY id",
+        (h.namespace,),
+    )
+    return [r[0] for r in h.cursor.fetchall()]
+
+
+class TestDeathHook:
+    def test_death_pushes_exactly_one_job(self, helpers):
+        register_and_kill_setup(helpers)
+        helpers.cursor.execute(
+            "SELECT entity_id FROM presence.sweep(%s)", (helpers.namespace,)
+        )
+        assert [r[0] for r in helpers.cursor.fetchall()] == ["w1"]
+
+        jobs = alert_jobs(helpers)
+        assert len(jobs) == 1
+        assert jobs[0]["entity_id"] == "w1"
+        assert jobs[0]["to"] == "dead"
+        assert jobs[0]["silent_for"] is not None
+
+    def test_death_and_job_commit_together(self, hooks_connection, helpers):
+        """The atomicity claim: roll back the sweeping transaction and
+        neither the death nor the alert job exists."""
+        register_and_kill_setup(helpers)
+
+        info = hooks_connection.info
+        conn = psycopg.connect(
+            host=info.host,
+            port=info.port,
+            dbname=info.dbname,
+            user=info.user,
+            password=info.password,
+        )
+        cur = conn.cursor()
+        cur.execute("SELECT entity_id FROM presence.sweep(%s)", (helpers.namespace,))
+        assert [r[0] for r in cur.fetchall()] == ["w1"]
+        conn.rollback()
+        conn.close()
+
+        assert alert_jobs(helpers) == []
+        assert helpers.get_entity_row("w1")["status"] == "alive"
+        assert helpers.get_transitions("w1")[-1]["to_status"] == "alive"
+
+    def test_revival_hook_fires_on_revival(self, helpers):
+        helpers.set_config(on_revival_queue="alerts")
+        helpers.cursor.execute(
+            "SELECT presence.register(%s, 'w1')", (helpers.namespace,)
+        )
+        helpers.cursor.execute(
+            "SELECT presence.heartbeat(%s, 'w1')", (helpers.namespace,)
+        )
+
+        jobs = alert_jobs(helpers)
+        assert len(jobs) == 1
+        assert jobs[0]["to"] == "alive"
+        assert jobs[0]["from"] == "unknown"
+
+
+class TestDeferredTerminalAlert:
+    def test_flap_into_suppression_then_real_death_alerts_once(self, helpers):
+        """The P5 catch-up: a death suppressed by flap damping is delivered
+        by a later sweep once the window expires - exactly one job, no new
+        transitions row, flag cleared, payload carrying the REAL death
+        time."""
+        register_and_kill_setup(helpers, flap_threshold=1)
+        # first contact was edge 1; this death is edge 2 > threshold 1
+        helpers.cursor.execute(
+            "SELECT entity_id FROM presence.sweep(%s)", (helpers.namespace,)
+        )
+        assert [r[0] for r in helpers.cursor.fetchall()] == ["w1"]
+        assert alert_jobs(helpers) == []  # suppressed
+        row = helpers.get_entity_row("w1")
+        assert row["hook_suppressed"] is True
+        transitions_before = len(helpers.get_transitions("w1"))
+
+        # The flap window expires while the entity is still dead
+        helpers.set_flap_window_started("w1", "-1 hour")
+        helpers.cursor.execute(
+            "SELECT entity_id FROM presence.sweep(%s)", (helpers.namespace,)
+        )
+        assert helpers.cursor.fetchall() == []  # no new transition returned
+
+        jobs = alert_jobs(helpers)
+        assert len(jobs) == 1
+        assert jobs[0]["to"] == "dead"
+        row = helpers.get_entity_row("w1")
+        assert row["hook_suppressed"] is False
+        assert len(helpers.get_transitions("w1")) == transitions_before
+        # at carries the real death time, not the catch-up sweep's time
+        assert datetime.fromisoformat(jobs[0]["at"]) == row["dead_since"]
+
+    def test_catch_up_fires_only_once(self, helpers):
+        register_and_kill_setup(helpers, flap_threshold=1)
+        helpers.cursor.execute("SELECT * FROM presence.sweep(%s)", (helpers.namespace,))
+        helpers.cursor.fetchall()
+        helpers.set_flap_window_started("w1", "-1 hour")
+
+        for _ in range(3):
+            helpers.cursor.execute(
+                "SELECT * FROM presence.sweep(%s)", (helpers.namespace,)
+            )
+            helpers.cursor.fetchall()
+
+        assert len(alert_jobs(helpers)) == 1
+
+
+class TestAllNamespacesSweep:
+    def test_bypassrls_sweep_pushes_into_tenant_queue(self, hooks_connection, helpers):
+        """The deployment mode: one cron, all namespaces, as a role that
+        bypasses RLS for presence must still land the job in the tenant's
+        queue rows correctly."""
+        register_and_kill_setup(helpers)
+
+        # The superuser session with NULL namespace is the all-namespaces
+        # deployment shape (the test connection is a superuser)
+        cur = hooks_connection.cursor()
+        cur.execute("SELECT namespace, entity_id FROM presence.sweep(NULL)")
+        swept = cur.fetchall()
+        assert (helpers.namespace, "w1") in swept
+
+        jobs = alert_jobs(helpers)
+        assert len(jobs) == 1
+        assert jobs[0]["namespace"] == helpers.namespace
+        cur.close()

postkit-0.4.0/tests/presence/conftest.py

@@ -0,0 +1,81 @@
+"""Pytest fixtures for postkit.presence tests."""
+
+import psycopg
+import pytest
+from postkit.presence import PresenceClient
+
+from tests.helpers import db_connection_for, make_namespace
+from tests.presence.helpers import PresenceTestHelpers, cleanup_namespace
+
+
+@pytest.fixture(scope="session")
+def db_connection():
+    """Session-scoped database connection with the presence schema installed."""
+    yield from db_connection_for("presence")
+
+
+@pytest.fixture
+def presence(db_connection, request):
+    """SDK-style PresenceClient for tests.
+
+    Each test gets its own namespace for isolation.
+    Cleanup is automatic after each test.
+    """
+    namespace = make_namespace(request)
+    cursor = db_connection.cursor()
+    client = PresenceClient(cursor, namespace)
+
+    yield client
+
+    cleanup_namespace(cursor, namespace)
+    cursor.close()
+
+
+@pytest.fixture
+def test_helpers(db_connection, request):
+    """Test helper utilities for direct table access.
+
+    Each test gets its own namespace for isolation.
+    Cleanup is automatic after each test.
+    """
+    namespace = make_namespace(request)
+    cursor = db_connection.cursor()
+    helpers = PresenceTestHelpers(cursor, namespace)
+
+    yield helpers
+
+    cleanup_namespace(cursor, namespace)
+    cursor.close()
+
+
+@pytest.fixture
+def connect(db_connection):
+    """Factory for extra non-autocommit connections (two-connection races).
+
+    Every connection gets a statement_timeout so a locking regression fails
+    the suite loudly instead of hanging CI.
+    """
+    conns: list[psycopg.Connection] = []
+    info = db_connection.info
+
+    def _connect(statement_timeout_ms: int = 10000) -> psycopg.Connection:
+        conn = psycopg.connect(
+            host=info.host,
+            port=info.port,
+            dbname=info.dbname,
+            user=info.user,
+            password=info.password,
+        )
+        conn.execute(f"SET statement_timeout = {statement_timeout_ms}")
+        conn.commit()
+        conns.append(conn)
+        return conn
+
+    yield _connect
+
+    for conn in conns:
+        try:
+            conn.rollback()
+            conn.close()
+        except Exception:
+            pass