proactive-gate 0.7.2__tar.gz → 0.8.0__tar.gz

{proactive_gate-0.7.2 → proactive_gate-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: proactive-gate
-Version: 0.7.2
+Version: 0.8.0
 Summary: Decide whether a proactive assistant may speak now: ordered checks, budgets, quiet hours, JSON policies, shared conformance fixtures with the TypeScript package.
 Project-URL: Homepage, https://bubblegunn.github.io/proactive-gate/
 Project-URL: Documentation, https://bubblegunn.github.io/proactive-gate/start/
@@ -128,7 +128,8 @@ runs that loop with values you supply, for tests with no store at all.
 [@LouisDeconinck](https://github.com/LouisDeconinck) in
 [#32](https://github.com/Bubblegunn/proactive-gate/pull/32); the same file and expiry rules
 as `SqliteStore`, without blocking the loop), and `RedisStore` over `redis.asyncio`
-(INCR, then EXPIRE on the first increment). Any object with `get`, `set`, `incr` and
+(INCR, and EXPIRE on the first increment, run as one Lua script through the client's
+`eval`, so a failure between the two cannot leave a counter with no TTL). Any object with `get`, `set`, `incr` and
 `delete` works. `SqliteStore` removes an expired row when a read touches it and clears
 every already-expired row on each `set` or `incr`, so a key nobody reads again still
 disappears.

{proactive_gate-0.7.2 → proactive_gate-0.8.0}/README.md

@@ -88,7 +88,8 @@ runs that loop with values you supply, for tests with no store at all.
 [@LouisDeconinck](https://github.com/LouisDeconinck) in
 [#32](https://github.com/Bubblegunn/proactive-gate/pull/32); the same file and expiry rules
 as `SqliteStore`, without blocking the loop), and `RedisStore` over `redis.asyncio`
-(INCR, then EXPIRE on the first increment). Any object with `get`, `set`, `incr` and
+(INCR, and EXPIRE on the first increment, run as one Lua script through the client's
+`eval`, so a failure between the two cannot leave a counter with no TTL). Any object with `get`, `set`, `incr` and
 `delete` works. `SqliteStore` removes an expired row when a read touches it and clears
 every already-expired row on each `set` or `incr`, so a key nobody reads again still
 disappears.

{proactive_gate-0.7.2 → proactive_gate-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "proactive-gate"
-version = "0.7.2"
+version = "0.8.0"
 description = "Decide whether a proactive assistant may speak now: ordered checks, budgets, quiet hours, JSON policies, shared conformance fixtures with the TypeScript package."
 readme = "README.md"
 requires-python = ">=3.11"

{proactive_gate-0.7.2 → proactive_gate-0.8.0}/src/proactive_gate/__init__.py

@@ -22,7 +22,7 @@ from .types import (
     UserState,
 )
 
-__version__ = "0.7.2"
+__version__ = "0.8.0"
 
 __all__ = [
     "EN", "PRIORITY_RANK", "KNOWN_CHECKS", "AsyncGate", "AsyncMemoryStore", "AsyncSqliteStore", "AsyncStore", "Candidate", "Check",

{proactive_gate-0.7.2 → proactive_gate-0.8.0}/src/proactive_gate/explain.py

@@ -501,10 +501,19 @@ def _summarize(decision: Decision, sentences: Mapping[str, SentenceTemplate]) ->
     clause = _t(sentences, template, facts)
     # For a deferral the hold ends at retryAt; when the clause already names the
     # instant (snooze's reason is "snoozed until X"), naming it twice reads worse.
+    #
+    # The summary may headline an instant ONLY when the decision will actually be
+    # reconsidered at it. quietHours can only reject, and its facts carry the
+    # window end as holdUntil, so this used to render a reject as "held until
+    # 08:00" -- telling the reader the message goes out at 08:00 when nothing
+    # would ever send it. The window is not lost: the clause still names it.
     clause_says_when = "until" in facts
-    until = facts.get("holdUntil")
-    if until is None and not clause_says_when and decision.deferred_by and decision.retry_at is not None:
-        until = iso_z(decision.retry_at)
+    will_be_reconsidered = entry.outcome == "defer"
+    until = None
+    if will_be_reconsidered:
+        until = facts.get("holdUntil")
+        if until is None and not clause_says_when and decision.retry_at is not None:
+            until = iso_z(decision.retry_at)
     held_facts: Facts = {"clause": clause}
     if until is not None:
         held_facts["until"] = until

{proactive_gate-0.7.2 → proactive_gate-0.8.0}/src/proactive_gate/stores.py

@@ -232,8 +232,24 @@ class AsyncSqliteStore:
             await self._conn.close()
 
 
+# INCR, and EXPIRE when the increment created the key. Redis runs a script without interleaving
+# other commands, so the TTL is attached in the same step that creates the counter. The
+# TypeScript RedisStore runs the same script.
+_INCR_SCRIPT = (
+    "local n = redis.call('INCR', KEYS[1]) "
+    "if n == 1 and tonumber(ARGV[1]) > 0 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end "
+    "return n"
+)
+
+
 class RedisStore:
-    """Wraps a ``redis.asyncio`` client. INCR, then EXPIRE on the first increment so a key never lives forever."""
+    """Wraps a ``redis.asyncio`` client.
+
+    ``incr`` runs INCR and, on the first increment, EXPIRE as one server-side script, so a counter
+    can never be left without a TTL. A client object with no ``eval`` method falls back to INCR then
+    a separate EXPIRE; a failure between those two round trips would leave a counter that never
+    expires.
+    """
 
     def __init__(self, client: Any) -> None:
         self.client = client
@@ -251,6 +267,9 @@ class RedisStore:
             await self.client.set(key, value)
 
     async def incr(self, key: str, ttl_seconds: int | None = None) -> int:
+        evaluate = getattr(self.client, "eval", None)
+        if evaluate is not None:
+            return int(await evaluate(_INCR_SCRIPT, 1, key, ttl_seconds or 0))
         value = int(await self.client.incr(key))
         if value == 1 and ttl_seconds:
             await self.client.expire(key, ttl_seconds)

{proactive_gate-0.7.2 → proactive_gate-0.8.0}/tests/test_explain.py

@@ -63,7 +63,21 @@ def test_plain_sentence_and_machine_reason_are_both_on_hand() -> None:
     d = evaluate([checks.QuietHours()], now=NIGHT)
     e = explain(d)
     assert d.reason == "quiet hours 22:00 to 08:00 Europe/Istanbul; priority normal is below the floor (critical)"
-    assert e.summary == "Held until 08:00 because the user's quiet hours run 22:00 to 08:00 Europe/Istanbul and normal priority is below the critical floor needed to override them."
+    # Not "Held until 08:00": QuietHours only rejects, and nothing retries a
+    # reject. The expectation was changed because it pinned a defect, not
+    # because a test failed. See test_a_reject_never_names_an_instant below.
+    assert e.summary == "Held because the user's quiet hours run 22:00 to 08:00 Europe/Istanbul and normal priority is below the critical floor needed to override them."
+
+
+def test_a_reject_never_names_an_instant() -> None:
+    """The summary may headline a time only when the decision is reconsidered at it."""
+    d = evaluate([checks.QuietHours()], now=NIGHT)
+    assert d.allowed is False
+    assert d.retry_at is None, "the fixture must be a reject, or this test proves nothing"
+    assert d.deferred_by is None
+    summary = explain(d).summary
+    assert "until" not in summary, f"a reject must not name an instant: {summary}"
+    assert "quiet hours run 22:00 to 08:00" in summary
 
 
 def test_not_stopped_every_check_gets_a_sentence() -> None:
@@ -353,9 +367,13 @@ def test_language_is_a_parameter() -> None:
     assert explain(d).summary == explain(d, language="en").summary
     with pytest.raises(ValueError, match='no sentence catalog for language "tr"'):
         explain(d, language="tr")
-    tr = {"summary.held": lambda f: f"{f['until']} kadar bekletildi, çünkü {f['clause']}"}
+    # `until` is optional: the summary carries it only when the decision will be
+    # reconsidered at it, so a caller catalog must handle its absence the way the
+    # shipped English one does. This template used to index it directly and only
+    # worked because the fixture happened to be a reject that wrongly named a time.
+    tr = {"summary.held": lambda f: f"{f['until'] + ' kadar ' if f.get('until') else ''}bekletildi, çünkü {f['clause']}"}
     e = explain(d, language="tr", catalogs={"tr": tr})
-    assert e.summary.startswith("08:00 kadar bekletildi, çünkü")
+    assert e.summary.startswith("Bekletildi, çünkü")
     assert len(EN) > 0
 
 

proactive_gate-0.8.0/tests/test_redis.py

@@ -0,0 +1,154 @@
+"""RedisStore: TTL attachment, with a fake client always and against a real server when one is given.
+
+The real-server tests read PROACTIVE_GATE_REDIS_URL and skip with that reason when it is unset,
+so ``pytest`` still passes with no Redis. They use their own key prefix and delete only their own
+keys; nothing is flushed.
+"""
+
+import asyncio
+import os
+import time
+from typing import Any
+
+import pytest
+
+from proactive_gate import RedisStore
+
+URL = os.environ.get("PROACTIVE_GATE_REDIS_URL")
+needs_server = pytest.mark.skipif(URL is None, reason="PROACTIVE_GATE_REDIS_URL is not set")
+
+
+class FaultyClient:
+    """In-memory stand-in. ``eval`` runs the script's two steps in one call, as Redis does for a
+    script; the separate ``expire`` fails, standing in for a connection dropped between two round
+    trips."""
+
+    def __init__(self, with_eval: bool) -> None:
+        self.data: dict[str, tuple[int, int]] = {}
+        self.calls: list[str] = []
+        self.with_eval = with_eval
+
+    def _incr(self, key: str) -> int:
+        value, ttl = self.data.get(key, (0, -1))
+        self.data[key] = (value + 1, ttl)
+        return value + 1
+
+    async def incr(self, key: str) -> int:
+        self.calls.append("incr")
+        return self._incr(key)
+
+    async def expire(self, key: str, seconds: int) -> None:
+        self.calls.append("expire")
+        raise ConnectionError("connection lost before EXPIRE")
+
+    def __getattr__(self, name: str) -> Any:
+        if name == "eval" and self.with_eval:
+            async def eval_(script: str, numkeys: int, key: str, ttl: int) -> int:
+                self.calls.append("eval")
+                value = self._incr(key)
+                if value == 1 and int(ttl) > 0:
+                    self.data[key] = (value, int(ttl))
+                return value
+            return eval_
+        raise AttributeError(name)
+
+
+def test_failure_between_incr_and_expire_cannot_leave_a_counter_without_ttl() -> None:
+    client = FaultyClient(with_eval=True)
+
+    async def run() -> None:
+        try:
+            await RedisStore(client).incr("budget:u1", 60)
+        except ConnectionError:
+            pass
+
+    asyncio.run(run())
+    entry = client.data.get("budget:u1")
+    assert entry is None or entry[1] > 0, f"counter left with no TTL after calls {client.calls}"
+    assert client.calls == ["eval"]
+
+
+def test_client_without_eval_still_works() -> None:
+    class Plain:
+        def __init__(self) -> None:
+            self.n = 0
+
+        async def incr(self, key: str) -> int:
+            self.n += 1
+            return self.n
+
+        async def expire(self, key: str, seconds: int) -> None:
+            return None
+
+    async def run() -> list[int]:
+        store = RedisStore(Plain())
+        return [await store.incr("k", 60), await store.incr("k", 60)]
+
+    assert asyncio.run(run()) == [1, 2]
+
+
+async def _client() -> Any:
+    from redis.asyncio import Redis
+
+    return Redis.from_url(URL or "")
+
+
+@needs_server
+def test_real_server_get_set_incr_delete() -> None:
+    prefix = f"pg-py:{os.getpid()}:{time.time_ns()}:"
+
+    async def run() -> None:
+        client = await _client()
+        store = RedisStore(client)
+        try:
+            assert await store.get(prefix + "a") is None
+            await store.set(prefix + "a", "1")
+            assert await store.get(prefix + "a") == "1"
+            await store.set(prefix + "b", "v", 60)
+            assert 0 < await client.ttl(prefix + "b") <= 60
+            assert await store.incr(prefix + "n", 60) == 1
+            assert await store.incr(prefix + "n", 60) == 2
+            assert 0 < await client.ttl(prefix + "n") <= 60
+            assert await store.incr(prefix + "plain") == 1
+            assert await client.ttl(prefix + "plain") == -1
+            results = await asyncio.gather(*(store.incr(prefix + "c") for _ in range(100)))
+            assert sorted(results) == list(range(1, 101))
+            await store.delete(prefix + "a")
+            assert await store.get(prefix + "a") is None
+        finally:
+            keys = [key async for key in client.scan_iter(match=prefix + "*")]
+            if keys:
+                await client.delete(*keys)
+            await client.aclose()
+
+    asyncio.run(run())
+
+
+@needs_server
+def test_real_server_expire_failing_after_incr_leaves_no_counter_without_ttl() -> None:
+    key = f"pg-py-atomic:{os.getpid()}:{time.time_ns()}"
+
+    class FailingExpire:
+        def __init__(self, inner: Any) -> None:
+            self.inner = inner
+
+        async def expire(self, key: str, seconds: int) -> None:
+            raise ConnectionError("connection lost before EXPIRE")
+
+        def __getattr__(self, name: str) -> Any:
+            return getattr(self.inner, name)
+
+    async def run() -> int:
+        client = await _client()
+        try:
+            try:
+                await RedisStore(FailingExpire(client)).incr(key, 60)
+            except ConnectionError:
+                pass
+            return int(await client.ttl(key))
+        finally:
+            await client.delete(key)
+            await client.aclose()
+
+    ttl = asyncio.run(run())
+    assert ttl == -2 or ttl > 0, f"TTL is {ttl}; -1 means the counter never expires"