altcodepro-polydb-python 2.5.4__py3-none-any.whl → 2.5.7__py3-none-any.whl

polydb/adapters/VercelKVAdapter.py

@@ -43,6 +43,23 @@ class VercelKVAdapter(NoSQLKVAdapter):
         if self.kv_url.startswith("redis://"):
             self._redis = redis.from_url(self.kv_url, decode_responses=True)
 
+    def _table_name(self, model: type) -> str:
+        """Same convention DynamoDBAdapter/_table_name and
+        FirestoreAdapter/_collection_name already use -- but here it's not
+        optional. Unlike DynamoDB (a real per-model table) or Firestore (a
+        real per-model collection), Vercel KV/Redis is one flat keyspace: a
+        key that was just "{pk}:{rk}" (tenant_id:id) let two different
+        models sharing a tenant_id and, coincidentally, the same id
+        collide on the exact same physical key -- one model's create
+        silently overwriting an unrelated model's row. Reproduced directly:
+        a "notes" row and a "widgets" row both keyed "tenant-a:x1" and the
+        second create clobbered the first. Folding the table name into the
+        key is the fix; every _*_raw method below must use this, not the
+        bare "{pk}:{rk}" shape.
+        """
+        meta = getattr(model, "__polydb__", {})
+        return meta.get("table") or meta.get("collection") or model.__name__.lower()
+
     # ------------------------------------------------------------------
     # PUT
     # ------------------------------------------------------------------
@@ -51,12 +68,20 @@ class VercelKVAdapter(NoSQLKVAdapter):
     def _put_raw(self, model: type, pk: str, rk: str, data: JsonDict) -> JsonDict:
         try:
 
-            key = f"{pk}:{rk}"
+            key = f"{self._table_name(model)}:{pk}:{rk}"
 
             payload = dict(data)
             payload["_pk"] = pk
             payload["_rk"] = rk
-            payload["id"] = pk
+            # NOTE: "id" is intentionally left as whatever the caller supplied
+            # (already present via `dict(data)` above). NoSQLKVAdapter._get_pk_rk
+            # derives `rk` from data.get(rk_field, ...) with rk_field defaulting
+            # to "id" -- i.e. the write-side convention is that a model's "id"
+            # field means "row key", not partition key. Overwriting it with
+            # `pk` here corrupted the caller's own id field and made it
+            # inconsistent with the read-side lookups below, which key on the
+            # record's real "id" value rather than the partition key.
+            payload.setdefault("id", rk)
 
             value = json.dumps(payload, default=json_safe)
 
@@ -89,7 +114,7 @@ class VercelKVAdapter(NoSQLKVAdapter):
 
         try:
 
-            key = f"{pk}:{rk}"
+            key = f"{self._table_name(model)}:{pk}:{rk}"
 
             # LOCAL REDIS
             if self._redis:
@@ -100,7 +125,6 @@ class VercelKVAdapter(NoSQLKVAdapter):
                     return None
 
                 obj = json.loads(value)
-                obj.setdefault("id", obj.get("_pk"))
                 return obj
 
             # REST API
@@ -121,7 +145,6 @@ class VercelKVAdapter(NoSQLKVAdapter):
                 return None
 
             obj = json.loads(result)
-            obj.setdefault("id", obj.get("_pk"))
 
             return obj
 
@@ -143,11 +166,12 @@ class VercelKVAdapter(NoSQLKVAdapter):
         try:
 
             results: List[JsonDict] = []
+            table = self._table_name(model)
 
             # LOCAL REDIS
             if self._redis:
 
-                for key in self._redis.scan_iter("*"):
+                for key in self._redis.scan_iter(f"{table}:*"):
 
                     value: Any = self._redis.get(key)
 
@@ -160,17 +184,11 @@ class VercelKVAdapter(NoSQLKVAdapter):
 
                     for k, v in filters.items():
 
-                        if k == "id":
-                            if obj.get("_pk") != v:
-                                match = False
-                                break
-
-                        elif obj.get(k) != v:
+                        if obj.get(k) != v:
                             match = False
                             break
 
                     if match:
-                        obj.setdefault("id", obj.get("_pk"))
                         results.append(obj)
 
                     if limit and len(results) >= limit:
@@ -182,7 +200,7 @@ class VercelKVAdapter(NoSQLKVAdapter):
             import requests
 
             resp = requests.get(
-                f"{self.kv_url}/keys/*",
+                f"{self.kv_url}/keys/{table}:*",
                 headers={"Authorization": f"Bearer {self.kv_token}"},
                 timeout=self.timeout,
             )
@@ -217,17 +235,11 @@ class VercelKVAdapter(NoSQLKVAdapter):
 
                 for k, v in filters.items():
 
-                    if k == "id":
-                        if obj.get("_pk") != v:
-                            match = False
-                            break
-
-                    elif obj.get(k) != v:
+                    if obj.get(k) != v:
                         match = False
                         break
 
                 if match:
-                    obj.setdefault("id", obj.get("_pk"))
                     results.append(obj)
 
             return results
@@ -250,7 +262,7 @@ class VercelKVAdapter(NoSQLKVAdapter):
 
         try:
 
-            key = f"{pk}:{rk}"
+            key = f"{self._table_name(model)}:{pk}:{rk}"
 
             # LOCAL REDIS
             if self._redis:
@@ -260,7 +272,9 @@ class VercelKVAdapter(NoSQLKVAdapter):
 
                 self._redis.delete(key)
 
-                return {"id": pk}
+                # "id" means row key throughout this adapter (see _put_raw) --
+                # return rk, not pk, for consistency.
+                return {"id": rk}
 
             # REST API
             import requests
@@ -280,7 +294,7 @@ class VercelKVAdapter(NoSQLKVAdapter):
                 timeout=self.timeout,
             ).raise_for_status()
 
-            return {"id": pk}
+            return {"id": rk}
 
         except DatabaseError:
             raise

polydb/adapters/VercelQueueAdapter.py

@@ -1,7 +1,8 @@
 import os
 import json
 import requests
-from typing import Dict, Any, List
+import redis
+from typing import Dict, Any, List, Optional
 
 from ..base.QueueAdapter import QueueAdapter
 from ..errors import QueueError
@@ -14,12 +15,25 @@ class VercelQueueAdapter:
         self.url = url or os.getenv("KV_REST_API_URL")
         self.token = token or os.getenv("KV_REST_API_TOKEN")
 
+        # Same local-testability convention VercelKVAdapter already
+        # established: a plain redis:// URL means "use local Redis
+        # directly," no cloud account or REST endpoint needed. Redis
+        # Streams (XADD/XRANGE/XDEL) are the same primitive the REST
+        # mode already speaks (see send/receive below), so this isn't a
+        # different queue model locally vs. in production, just a
+        # different transport to the same Redis Streams operations.
+        self._redis: Optional["redis.Redis"] = None
+        if self.url and self.url.startswith("redis://"):
+            self._redis = redis.from_url(self.url, decode_responses=True)
+
     @retry(max_attempts=3, delay=1.0, exceptions=(QueueError,))
     def send(self, message: Dict[str, Any], queue_name: str = "default") -> str:
         try:
-
             payload = json.dumps(message)
 
+            if self._redis:
+                return self._redis.xadd(queue_name, {"payload": payload})
+
             r = requests.post(
                 f"{self.url}/xadd/{queue_name}",
                 headers={"Authorization": f"Bearer {self.token}"},
@@ -37,6 +51,14 @@ class VercelQueueAdapter:
     def receive(self, queue_name: str = "default", max_messages: int = 1) -> List[Dict]:
 
         try:
+            if self._redis:
+                entries = self._redis.xrange(queue_name, count=max_messages)
+                messages = []
+                for entry_id, fields in entries:
+                    data = json.loads(fields["payload"])
+                    data["_id"] = entry_id
+                    messages.append(data)
+                return messages
 
             r = requests.get(
                 f"{self.url}/xrange/{queue_name}/-/{max_messages}",
@@ -60,6 +82,12 @@ class VercelQueueAdapter:
             raise QueueError(f"Vercel queue receive failed: {e}")
 
     def delete(self, message_id: str, queue_name: str = "default", pop_receipt: str = "") -> bool:
+        if self._redis:
+            # Real deletion locally -- unlike the REST-mode no-op below
+            # (Redis Streams via the Vercel KV REST API has no XDEL
+            # endpoint exposed, same limitation ack() below documents for
+            # explicit ACK), local Redis has the primitive natively.
+            return bool(self._redis.xdel(queue_name, message_id))
         return True
 
     # ---------------------------------------------------------

polydb/base/QueueAdapter.py

@@ -2,7 +2,7 @@ from polydb.utils import setup_logger
 
 
 from abc import ABC, abstractmethod
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 
 
 class QueueAdapter(ABC):
@@ -25,3 +25,125 @@ class QueueAdapter(ABC):
     def delete(self, message_id: str, queue_name: str = "default", pop_receipt: str = "") -> bool:
         """Delete message from queue"""
         pass
+
+    # ------------------------------------------------------------------
+    # Extended queue management -- regular (non-abstract) methods, not
+    # `@abstractmethod`, on purpose. `send`/`receive`/`delete` above are
+    # the original contract every adapter (SQS/Azure/GCP/Vercel/
+    # Blockchain/Kafka/RabbitMQ) already implements; making the methods
+    # below abstract too would force every one of those subclasses to
+    # grow a stub the instant this file changes, even the ones nobody has
+    # actually implemented these for yet. Matches the same pattern
+    # `NoSQLKVAdapter`/`SecretsAdapter` already use for their own
+    # not-yet-universal capabilities (a bare `raise NotImplementedError`
+    # in the base, overridden only where a subclass genuinely supports
+    # it) -- a subclass that doesn't override one of these raises here,
+    # loudly and by name, instead of silently doing nothing.
+    # ------------------------------------------------------------------
+
+    def nack(self, ack_id: str, queue_name: str = "default") -> bool:
+        """Negative-acknowledge: put the message back for redelivery
+        immediately, without waiting out any natural visibility/
+        redelivery timeout the backend might otherwise enforce."""
+        raise NotImplementedError(f"{self.__class__.__name__} does not implement nack()")
+
+    def purge(self, queue_name: str = "default") -> int:
+        """Delete every message currently in the queue. Returns the
+        number purged where the backend reports one; adapters that
+        implement this and genuinely cannot get a count from the backend
+        document their own sentinel return value in their override --
+        this base default never guesses one for an adapter nobody has
+        implemented purge() for yet."""
+        raise NotImplementedError(f"{self.__class__.__name__} does not implement purge()")
+
+    def declare(
+        self,
+        queue_name: str = "default",
+        *,
+        durable: bool = True,
+        dead_letter_queue: Optional[str] = None,
+    ) -> bool:
+        """Explicit queue provisioning ahead of first use -- distinct
+        from the auto-create-on-first-send/receive some adapters already
+        do implicitly. When `dead_letter_queue` is given, wires up
+        dead-lettering to a second queue by that name (adapter-specific
+        mechanism; see each override for what "dead-lettering" actually
+        means on that backend)."""
+        raise NotImplementedError(f"{self.__class__.__name__} does not implement declare()")
+
+    def status(self, queue_name: str = "default") -> Dict[str, Any]:
+        """At minimum `{"message_count": int}`; an override may add other
+        fields the backend genuinely exposes."""
+        raise NotImplementedError(f"{self.__class__.__name__} does not implement status()")
+
+    # ------------------------------------------------------------------
+    # extend / delay / cancel -- the same "regular method, not abstract,
+    # base raises loudly by name" shape as nack/purge/declare/status
+    # above, for the identical reason: adding these to every existing
+    # subclass at once the moment this file changes would be a false
+    # claim of support nobody actually verified. Each is real ONLY where
+    # a genuine backend primitive exists for it -- checked per adapter,
+    # per method, against the real installed SDK, not assumed uniform:
+    #   - extend(): SQS (ChangeMessageVisibility), Azure Queue
+    #     (UpdateMessage with no content= change), GCP Pub/Sub
+    #     (ModifyAckDeadline) all have a REAL "keep this ALREADY-RECEIVED
+    #     message invisible a while longer" primitive. RabbitMQ/Kafka do
+    #     not -- AMQP's consumer model has no per-message renewable
+    #     visibility timer at all (ack/nack/reject only), and Kafka's
+    #     offset-based model has no per-message delivery state to extend
+    #     either -- so neither adapter overrides this.
+    #   - delay(): SQS (SendMessage's own DelaySeconds, real, capped at
+    #     900s by SQS itself), Azure Queue (send_message's own
+    #     visibility_timeout param), and RabbitMQ (a real, plugin-free
+    #     AMQP pattern: publish to a per-duration queue declared with
+    #     x-message-ttl + a dead-letter-exchange pointing at the real
+    #     queue_name, so the message lands there automatically once the
+    #     TTL elapses) all have a real "don't make this NEW message
+    #     visible until N seconds from now" primitive. GCP Pub/Sub has no
+    #     such primitive (a published message is deliverable immediately;
+    #     Cloud Tasks/Scheduler is a genuinely different GCP service, out
+    #     of scope for a Pub/Sub adapter) and Kafka doesn't either.
+    #   - cancel(): only meaningful for a message a delay() call has not
+    #     yet delivered. Azure Queue is real (the id+pop_receipt
+    #     send_message's own response returns are already enough to
+    #     delete that exact message before its visibility_timeout
+    #     elapses). RabbitMQ is real too, via a bounded scan-and-requeue
+    #     of the one specific per-duration delay queue this message was
+    #     published to (see RabbitMQAdapter.cancel's own docstring for
+    #     why this is the honest, bounded shape rather than an unbounded
+    #     one). SQS has none: a delayed SQS message is not receivable
+    #     (no ReceiptHandle exists) until its own DelaySeconds elapses,
+    #     so there is no real API call that can remove it earlier.
+    # ------------------------------------------------------------------
+
+    def extend(
+        self, ack_id: str, queue_name: str = "default", *, visibility_timeout: int = 30
+    ) -> bool:
+        """Extend how long an already-received, not-yet-acked message
+        stays invisible to other consumers, without acknowledging or
+        requeuing it -- the redelivery-window equivalent of "I'm still
+        working on this, don't hand it to anyone else yet." `ack_id` is
+        the same receipt/handle `receive()` returned for this message."""
+        raise NotImplementedError(f"{self.__class__.__name__} does not implement extend()")
+
+    def delay(
+        self, message: Dict[str, Any], queue_name: str = "default", *, delay_seconds: int = 0
+    ) -> str:
+        """Send a NEW message that will not become visible/deliverable
+        until `delay_seconds` from now. Returns an id `cancel()` can use
+        to remove it again before that happens -- not necessarily the
+        same string shape `send()` returns, since some backends (Azure)
+        need more than a bare message id to cancel a not-yet-visible
+        message."""
+        raise NotImplementedError(f"{self.__class__.__name__} does not implement delay()")
+
+    def cancel(self, message_id: str, queue_name: str = "default") -> bool:
+        """Cancel a still-delayed message (one a prior `delay()` call has
+        not yet made visible) before it is ever delivered. `message_id`
+        is whatever `delay()` returned for it. Returns whether a
+        matching still-pending message was actually found and removed --
+        `False`, not an exception, when it already fired or never
+        existed, the same "unknown id is a no-op, not an error"
+        convention `RabbitMQAdapter._ack_delivery` already establishes
+        for a different method."""
+        raise NotImplementedError(f"{self.__class__.__name__} does not implement cancel()")

polydb/base/SecretsAdapter.py

@@ -0,0 +1,30 @@
+from ..utils import setup_logger
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class SecretsAdapter(ABC):
+    """Base class for cloud secret managers (Key Vault / Secrets Manager /
+    Secret Manager / Vault) -- same shape as the other base adapters
+    (ObjectStorageAdapter, QueueAdapter, ...), dispatched the same way via
+    CloudDatabaseFactory.get_secrets()."""
+
+    def __init__(self):
+        self.logger = setup_logger(self.__class__.__name__)
+
+    @abstractmethod
+    def get_secret(self, key: str) -> Optional[str]:
+        """Return the current value of a secret, or None if it doesn't exist."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def set_secret(self, key: str, value: str) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_secret(self, key: str) -> bool:
+        raise NotImplementedError
+
+    @abstractmethod
+    def list_secrets(self, prefix: str = "") -> list[str]:
+        raise NotImplementedError

polydb/cache.py

@@ -204,6 +204,96 @@ class RedisCacheEngine:
         except Exception:
             pass
 
+    # ---------------------------------------------------------
+    # Generic raw KV operations -- for a caller that wants a plain
+    # Redis get/set/incr under an explicit key it picked itself, not the
+    # query-result caching get()/set() above (which hash a query dict
+    # into the key). Reuses the same _make_raw_key (no hashing) as the
+    # zset methods above, so a raw KV key and a zset key never collide
+    # as long as the caller doesn't reuse the same `key` for both.
+    #
+    # Unlike get()/set()/invalidate() above -- which are an *automatic*,
+    # best-effort read-through cache where a Redis hiccup or missing
+    # backend should never break the underlying query -- these raw
+    # methods back a caller's own explicit business logic (e.g. a
+    # workflow step doing rate limiting or a distributed lock via
+    # incrby()). Silently returning None/0/False there would hide a real
+    # misconfiguration (no REDIS_CACHE_URL set) behind wrong-looking
+    # business results instead of a clear error, so these raise
+    # CacheError when no client is configured or the operation itself
+    # fails, rather than swallowing the exception.
+    # ---------------------------------------------------------
+
+    def get_raw(self, model: str, key: str) -> Optional[Any]:
+        from .errors import CacheError
+
+        if not self._client:
+            raise CacheError("No Redis cache backend configured (set REDIS_CACHE_URL/REDIS_URL)")
+        redis_key = self._make_raw_key(model, key)
+        try:
+            data = self._client.get(redis_key)
+            if data is None:
+                return None
+            if isinstance(data, bytes):
+                data = data.decode("utf-8")
+            return json.loads(data)
+        except Exception as e:
+            raise CacheError(f"Redis get failed: {e}")
+
+    def set_raw(self, model: str, key: str, value: Any, ttl: Optional[int] = None) -> bool:
+        from .errors import CacheError
+
+        if not self._client:
+            raise CacheError("No Redis cache backend configured (set REDIS_CACHE_URL/REDIS_URL)")
+        redis_key = self._make_raw_key(model, key)
+        data = json.dumps(value, default=json_safe)
+        try:
+            if ttl:
+                self._client.setex(redis_key, ttl, data)
+            else:
+                self._client.set(redis_key, data)
+            return True
+        except Exception as e:
+            raise CacheError(f"Redis set failed: {e}")
+
+    def incrby(self, model: str, key: str, amount: int = 1) -> int:
+        """Atomic increment (INCRBY) of a raw key, creating it at 0 first
+        if absent -- the primitive a rate-limiter/counter workflow step
+        needs, distinct from the zset-based rate limiting above."""
+        from .errors import CacheError
+
+        if not self._client:
+            raise CacheError("No Redis cache backend configured (set REDIS_CACHE_URL/REDIS_URL)")
+        redis_key = self._make_raw_key(model, key)
+        try:
+            return int(self._client.incrby(redis_key, amount))
+        except Exception as e:
+            raise CacheError(f"Redis incrby failed: {e}")
+
+    def exists_raw(self, model: str, key: str) -> bool:
+        from .errors import CacheError
+
+        if not self._client:
+            raise CacheError("No Redis cache backend configured (set REDIS_CACHE_URL/REDIS_URL)")
+        redis_key = self._make_raw_key(model, key)
+        try:
+            return bool(self._client.exists(redis_key))
+        except Exception as e:
+            raise CacheError(f"Redis exists failed: {e}")
+
+    def ttl_raw(self, model: str, key: str) -> int:
+        """Seconds until expiry; -1 means the key exists with no TTL, -2
+        means the key doesn't exist -- standard Redis TTL semantics."""
+        from .errors import CacheError
+
+        if not self._client:
+            raise CacheError("No Redis cache backend configured (set REDIS_CACHE_URL/REDIS_URL)")
+        redis_key = self._make_raw_key(model, key)
+        try:
+            return int(self._client.ttl(redis_key))
+        except Exception as e:
+            raise CacheError(f"Redis ttl failed: {e}")
+
 
 class CacheWarmer:
     """Pre-populate cache with frequently accessed data"""