postkit 0.3.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: postkit
-Version: 0.3.0
+Version: 0.5.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
@@ -65,6 +65,14 @@ user_id = authn.create_user("alice@example.com", password_hash="argon2...")
 session_id = authn.create_session(user_id, token_hash="sha256...")
 ```
 
+## Tenant Context and Transactions
+
+Constructing a client calls `{module}.set_tenant(namespace)` immediately. The setting is transaction-scoped, so inside an open transaction the constructor taints that transaction's context for the module until commit or rollback; an unrelated client built mid-transaction can therefore change which rows a later raw SQL statement sees.
+
+Every SDK call needs a transaction for that context. On autocommit connections each call runs in its own transaction and commits immediately. On non-autocommit connections each call joins the connection's open transaction: nothing is durable until you commit, and a rollback takes it all with it, including a queue claim from `pull()`. That is the intended model for transactional consumers; `nack`/`fail` accept the pending job a rollback leaves behind.
+
+In CI, call `client.assert_rls_active()` during setup. A suite connecting as a superuser or `BYPASSRLS` role (the docker default) bypasses every RLS policy and exercises none of the tenancy model.
+
 ## Requirements
 
 - PostgreSQL 14+

postkit-0.5.0/README.md

@@ -0,0 +1,47 @@
+# postkit SDK
+
+Python client for postkit.
+
+## Installation
+
+```bash
+pip install postkit
+```
+
+## Usage
+
+```python
+import psycopg
+from postkit.authz import AuthzClient
+from postkit.authn import AuthnClient
+
+conn = psycopg.connect("postgresql://...")
+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")
+
+# Authentication
+authn = AuthnClient(cursor, namespace="my-app")
+user_id = authn.create_user("alice@example.com", password_hash="argon2...")
+session_id = authn.create_session(user_id, token_hash="sha256...")
+```
+
+## Tenant Context and Transactions
+
+Constructing a client calls `{module}.set_tenant(namespace)` immediately. The setting is transaction-scoped, so inside an open transaction the constructor taints that transaction's context for the module until commit or rollback; an unrelated client built mid-transaction can therefore change which rows a later raw SQL statement sees.
+
+Every SDK call needs a transaction for that context. On autocommit connections each call runs in its own transaction and commits immediately. On non-autocommit connections each call joins the connection's open transaction: nothing is durable until you commit, and a rollback takes it all with it, including a queue claim from `pull()`. That is the intended model for transactional consumers; `nack`/`fail` accept the pending job a rollback leaves behind.
+
+In CI, call `client.assert_rls_active()` during setup. A suite connecting as a superuser or `BYPASSRLS` role (the docker default) bypasses every RLS policy and exercises none of the tenancy model.
+
+## Requirements
+
+- PostgreSQL 14+
+- The postkit SQL schema installed in your database
+
+See the [main repository](https://github.com/varunchopra/postkit) for SQL installation instructions.

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

@@ -1,6 +1,6 @@
 [project]
 name = "postkit"
-version = "0.3.0"
+version = "0.5.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.5.0}/src/postkit/base.py

@@ -399,6 +399,29 @@ class BaseClient(ABC):
         self._on_behalf_of = None
         self._reason = None
 
+    def assert_rls_active(self) -> None:
+        """Raise unless row-level security applies to the connection's role.
+
+        Call from CI setup: a suite connecting as a superuser or BYPASSRLS
+        role bypasses every policy and exercises none of the tenancy model.
+
+        Raises:
+            The module's error class with error_code BIZ_RLS_NOT_ACTIVE
+            when the current role bypasses RLS.
+        """
+
+        def execute() -> None:
+            try:
+                self.cursor.execute(
+                    sql.SQL("SELECT {}.assert_rls_active()").format(
+                        sql.Identifier(self._schema)
+                    )
+                )
+            except psycopg.Error as e:
+                self._handle_error(e)
+
+        self._with_context(execute)
+
     @staticmethod
     def _encode_cursor(event_time: datetime, event_id: int) -> str:
         """Encode pagination cursor as opaque string.

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

@@ -64,6 +64,7 @@ class AuthnErrorCode:
     # Business logic errors (BIZ_)
     BIZ_IMPERSONATE_SELF = "BIZ_IMPERSONATE_SELF"
     BIZ_IMPERSONATE_CHAIN = "BIZ_IMPERSONATE_CHAIN"
+    BIZ_RLS_NOT_ACTIVE = "BIZ_RLS_NOT_ACTIVE"
 
     # Credential state errors (CRED_)
     CRED_NO_MATERIAL = "CRED_NO_MATERIAL"
@@ -109,6 +110,7 @@ class AuthzErrorCode:
     BIZ_BULK_GROUP_MEMBERSHIP = "BIZ_BULK_GROUP_MEMBERSHIP"
     BIZ_BULK_PARENT_RELATION = "BIZ_BULK_PARENT_RELATION"
     BIZ_GRANT_NO_EXPIRATION = "BIZ_GRANT_NO_EXPIRATION"
+    BIZ_RLS_NOT_ACTIVE = "BIZ_RLS_NOT_ACTIVE"
 
     # Data state errors (DATA_)
     DATA_GRANT_NOT_FOUND = "DATA_GRANT_NOT_FOUND"
@@ -140,6 +142,7 @@ class ConfigErrorCode:
 
     # Business logic errors (BIZ_)
     BIZ_DELETE_ACTIVE_VERSION = "BIZ_DELETE_ACTIVE_VERSION"
+    BIZ_RLS_NOT_ACTIVE = "BIZ_RLS_NOT_ACTIVE"
 
 
 class LeaseErrorCode:
@@ -173,6 +176,9 @@ class LeaseErrorCode:
     # Internal errors (INT_)
     INT_COUNTER_MISSING = "INT_COUNTER_MISSING"
 
+    # Business logic errors (BIZ_)
+    BIZ_RLS_NOT_ACTIVE = "BIZ_RLS_NOT_ACTIVE"
+
 
 class MeterErrorCode:
     """Error codes for the meter module."""
@@ -200,6 +206,8 @@ class MeterErrorCode:
 
     # Business logic errors (BIZ_)
     BIZ_LEDGER_IMMUTABLE = "BIZ_LEDGER_IMMUTABLE"
+    BIZ_RLS_NOT_ACTIVE = "BIZ_RLS_NOT_ACTIVE"
+    BIZ_ALL_NAMESPACES_REQUIRES_BYPASS = "BIZ_ALL_NAMESPACES_REQUIRES_BYPASS"
 
     # Data state errors (DATA_)
     DATA_ACCOUNT_NOT_FOUND = "DATA_ACCOUNT_NOT_FOUND"
@@ -238,6 +246,39 @@ class OutboxErrorCode:
     BIZ_CONSUMER_UNKNOWN = "BIZ_CONSUMER_UNKNOWN"
     BIZ_CURSOR_LOST = "BIZ_CURSOR_LOST"
     BIZ_POSITION_BEYOND_HEAD = "BIZ_POSITION_BEYOND_HEAD"
+    BIZ_RLS_NOT_ACTIVE = "BIZ_RLS_NOT_ACTIVE"
+    BIZ_ALL_NAMESPACES_REQUIRES_BYPASS = "BIZ_ALL_NAMESPACES_REQUIRES_BYPASS"
+
+
+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"
+    BIZ_RLS_NOT_ACTIVE = "BIZ_RLS_NOT_ACTIVE"
+    BIZ_ALL_NAMESPACES_REQUIRES_BYPASS = "BIZ_ALL_NAMESPACES_REQUIRES_BYPASS"
 
 
 class QueueErrorCode:
@@ -270,10 +311,13 @@ class QueueErrorCode:
 
     # Business logic errors (BIZ_)
     BIZ_JOB_NOT_RUNNING = "BIZ_JOB_NOT_RUNNING"
+    BIZ_JOB_NOT_YOURS = "BIZ_JOB_NOT_YOURS"
     BIZ_SCHEDULE_DUPLICATE = "BIZ_SCHEDULE_DUPLICATE"
     BIZ_SCHEDULE_REQUIRES_SCHEDULE = "BIZ_SCHEDULE_REQUIRES_SCHEDULE"
     BIZ_SCHEDULE_CRON_AND_INTERVAL = "BIZ_SCHEDULE_CRON_AND_INTERVAL"
     BIZ_DEAD_LETTER_ALREADY_RETRIED = "BIZ_DEAD_LETTER_ALREADY_RETRIED"
+    BIZ_RLS_NOT_ACTIVE = "BIZ_RLS_NOT_ACTIVE"
+    BIZ_ALL_NAMESPACES_REQUIRES_BYPASS = "BIZ_ALL_NAMESPACES_REQUIRES_BYPASS"
 
     # Data state errors (DATA_)
     DATA_JOB_NOT_FOUND = "DATA_JOB_NOT_FOUND"

{postkit-0.3.0 → postkit-0.5.0}/src/postkit/outbox/client.py

@@ -341,3 +341,16 @@ class OutboxClient(BaseClient):
         return self._fetch_all(
             "SELECT * FROM outbox.list_consumers(%s, %s)", (self.namespace, topic)
         )
+
+    def horizon_blockers(self) -> list[dict[str, Any]]:
+        """Backends whose open write transactions pin the visibility horizon.
+
+        Database-global, like the horizon itself. Seeing other sessions
+        requires pg_read_all_stats (or superuser).
+
+        Returns:
+            One dict per in-progress write transaction, oldest first:
+            pid, datname, xact_age, state, application_name, query,
+            is_horizon
+        """
+        return self._fetch_all("SELECT * FROM outbox.horizon_blockers()", ())

postkit-0.5.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.5.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.3.0 → postkit-0.5.0}/src/postkit/queue/client.py

@@ -359,19 +359,25 @@ class QueueClient(BaseClient):
         *,
         error: str | None = None,
         backoff: timedelta | None = None,
+        worker_id: str | None = None,
     ) -> bool:
         """Return job to queue for retry (temporary failure).
 
+        Valid on running jobs and on pending jobs whose claim was rolled
+        back with the consumer's transaction.
+
         Args:
             job_id: Job ID
             error: Error message (stored for debugging)
             backoff: Custom backoff delay (default: exponential)
+            worker_id: If set, refuse jobs running under a different worker
 
         Returns:
             True if returned to queue, False if max attempts exceeded (moved to DLQ)
 
         Raises:
-            QueueValidationError: If job exists but is not in running status
+            QueueValidationError: If job is settled (completed or dead), or
+                running under a different worker than worker_id
             QueueError: If job does not exist
         """
         result = self._fetch_val(
@@ -379,13 +385,15 @@ class QueueClient(BaseClient):
                 p_namespace := %s,
                 p_job_id := %s,
                 p_error := %s,
-                p_backoff := %s
+                p_backoff := %s,
+                p_worker_id := %s
             )""",
             (
                 self.namespace,
                 job_id,
                 error,
                 backoff,
+                worker_id,
             ),
             write=True,
         )
@@ -396,26 +404,34 @@ class QueueClient(BaseClient):
         job_id: int,
         *,
         error: str | None = None,
+        worker_id: str | None = None,
     ) -> bool:
         """Move job to dead letter queue (permanent failure).
 
+        Valid on running jobs and on pending jobs whose claim was rolled
+        back with the consumer's transaction.
+
         Args:
             job_id: Job ID
             error: Error message
+            worker_id: If set, refuse jobs running under a different worker
 
         Returns:
-            True if moved to DLQ, False if job not found or not running
+            True if moved to DLQ, False if job settled, missing, or owned
+            by another worker
         """
         result = self._fetch_val(
             """SELECT queue.fail(
                 p_namespace := %s,
                 p_job_id := %s,
-                p_error := %s
+                p_error := %s,
+                p_worker_id := %s
             )""",
             (
                 self.namespace,
                 job_id,
                 error,
+                worker_id,
             ),
             write=True,
         )

postkit-0.5.0/tests/authn/test_rls_active.py

@@ -0,0 +1,26 @@
+"""assert_rls_active: catch test setups whose role bypasses RLS."""
+
+import pytest
+from postkit.authn import AuthnClient, AuthnError, AuthnErrorCode
+
+from tests.helpers import connect_as_rls_user, ensure_rls_role
+
+
+class TestAssertRlsActive:
+    """Raises for bypass roles, passes when RLS applies."""
+
+    def test_raises_for_bypass_role(self, db_connection):
+        client = AuthnClient(db_connection.cursor(), "rls_assert")
+
+        with pytest.raises(AuthnError) as exc_info:
+            client.assert_rls_active()
+        assert exc_info.value.error_code == AuthnErrorCode.BIZ_RLS_NOT_ACTIVE
+
+    def test_passes_for_rls_role(self, db_connection):
+        ensure_rls_role(db_connection, "authn")
+        conn = connect_as_rls_user(db_connection, "authn")
+        try:
+            AuthnClient(conn.cursor(), "rls_assert").assert_rls_active()
+            conn.rollback()
+        finally:
+            conn.close()

postkit-0.5.0/tests/authz/test_rls_active.py

@@ -0,0 +1,26 @@
+"""assert_rls_active: catch test setups whose role bypasses RLS."""
+
+import pytest
+from postkit.authz import AuthzClient, AuthzError, AuthzErrorCode
+
+from tests.helpers import connect_as_rls_user, ensure_rls_role
+
+
+class TestAssertRlsActive:
+    """Raises for bypass roles, passes when RLS applies."""
+
+    def test_raises_for_bypass_role(self, db_connection):
+        client = AuthzClient(db_connection.cursor(), "rls_assert")
+
+        with pytest.raises(AuthzError) as exc_info:
+            client.assert_rls_active()
+        assert exc_info.value.error_code == AuthzErrorCode.BIZ_RLS_NOT_ACTIVE
+
+    def test_passes_for_rls_role(self, db_connection):
+        ensure_rls_role(db_connection, "authz")
+        conn = connect_as_rls_user(db_connection, "authz")
+        try:
+            AuthzClient(conn.cursor(), "rls_assert").assert_rls_active()
+            conn.rollback()
+        finally:
+            conn.close()

postkit-0.5.0/tests/config/test_rls_active.py

@@ -0,0 +1,26 @@
+"""assert_rls_active: catch test setups whose role bypasses RLS."""
+
+import pytest
+from postkit.config import ConfigClient, ConfigError, ConfigErrorCode
+
+from tests.helpers import connect_as_rls_user, ensure_rls_role
+
+
+class TestAssertRlsActive:
+    """Raises for bypass roles, passes when RLS applies."""
+
+    def test_raises_for_bypass_role(self, db_connection):
+        client = ConfigClient(db_connection.cursor(), "rls_assert")
+
+        with pytest.raises(ConfigError) as exc_info:
+            client.assert_rls_active()
+        assert exc_info.value.error_code == ConfigErrorCode.BIZ_RLS_NOT_ACTIVE
+
+    def test_passes_for_rls_role(self, db_connection):
+        ensure_rls_role(db_connection, "config")
+        conn = connect_as_rls_user(db_connection, "config")
+        try:
+            ConfigClient(conn.cursor(), "rls_assert").assert_rls_active()
+            conn.rollback()
+        finally:
+            conn.close()