codex-platform 0.1.0__py3-none-any.whl

codex_platform/redis_service/operations/list_.py

@@ -0,0 +1,219 @@
+"""
+codex_platform.redis_service.operations.list_
+==============================================
+Redis List operations.
+"""
+
+import logging
+from typing import Any
+
+from redis.asyncio import Redis
+
+from codex_platform.redis_service.base import catch_redis_errors
+from codex_platform.redis_service.keys import BaseRedisKey, resolve_key
+
+log = logging.getLogger(__name__)
+
+
+class ListOperations:
+    """Redis List operations (RPUSH / LPUSH / LPOP / LRANGE and more).
+
+    Accepts an already-constructed ``redis.asyncio.Redis`` client.
+    All methods wrap Redis errors in typed exceptions.
+
+    Example::
+
+        ops = ListOperations(client)
+        await ops.push("queue:jobs", "job-1", "job-2")
+        job = await ops.pop("queue:jobs")
+    """
+
+    def __init__(self, client: Redis) -> None:
+        self.client = client
+
+    @catch_redis_errors
+    async def push(self, key: "str | BaseRedisKey", *values: str, **kwargs: Any) -> int:
+        """Append one or more values to the end of a list (RPUSH).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            *values: String values to append.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            New length of the list after the operation.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.rpush(real_key, *values))
+
+    @catch_redis_errors
+    async def lpush(self, key: "str | BaseRedisKey", *values: str, **kwargs: Any) -> int:
+        """Prepend one or more values to the beginning of a list (LPUSH).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            *values: String values to prepend.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            New length of the list after the operation.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.lpush(real_key, *values))
+
+    @catch_redis_errors
+    async def pop(self, key: "str | BaseRedisKey", **kwargs: Any) -> str | None:
+        """Remove and return the first element of a list (LPOP).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            The first element, or ``None`` if the list is empty or does not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        value = await self.client.lpop(real_key)
+        return str(value) if value is not None else None
+
+    @catch_redis_errors
+    async def rpop(self, key: "str | BaseRedisKey", **kwargs: Any) -> str | None:
+        """Remove and return the last element of a list (RPOP).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            The last element, or ``None`` if the list is empty or does not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        value = await self.client.rpop(real_key)
+        return str(value) if value is not None else None
+
+    @catch_redis_errors
+    async def brpop(self, *keys: str, timeout: int = 0) -> tuple[str, str] | None:
+        """Blocking pop of the last element from the first non-empty list (BRPOP).
+
+        Args:
+            *keys: One or more Redis key strings to check in order.
+            timeout: Maximum seconds to block. ``0`` blocks indefinitely.
+
+        Returns:
+            ``(key, value)`` tuple when an element is available,
+            or ``None`` if the timeout expires.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        result = await self.client.brpop(list(keys), timeout=timeout)
+        if result:
+            return str(result[0]), str(result[1])
+        return None
+
+    @catch_redis_errors
+    async def range(self, key: "str | BaseRedisKey", start: int = 0, end: int = -1, **kwargs: Any) -> list[str]:
+        """Return a slice of list elements by index range (LRANGE).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            start: Start index (0-based). Negative values count from the end.
+            end: End index inclusive. ``-1`` means the last element.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            List of elements in the requested range.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return await self.client.lrange(real_key, start, end)
+
+    @catch_redis_errors
+    async def length(self, key: "str | BaseRedisKey", **kwargs: Any) -> int:
+        """Return the number of elements in a list (LLEN).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            List length. ``0`` if the key does not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.llen(real_key))
+
+    @catch_redis_errors
+    async def set_index(self, key: "str | BaseRedisKey", index: int, value: str, **kwargs: Any) -> None:
+        """Set the element at a specific list index (LSET).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            index: Zero-based index. Negative values count from the end.
+            value: New value to set at the given index.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        await self.client.lset(real_key, index, value)
+
+    @catch_redis_errors
+    async def trim(self, key: "str | BaseRedisKey", start: int, end: int, **kwargs: Any) -> None:
+        """Trim a list to the specified index range, discarding all other elements (LTRIM).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            start: Start index (inclusive).
+            end: End index (inclusive).
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        await self.client.ltrim(real_key, start, end)
+
+    @catch_redis_errors
+    async def move(self, src: str, dst: str) -> str | None:
+        """Atomically move the last element of ``src`` to the head of ``dst`` (RPOPLPUSH).
+
+        Args:
+            src: Source list key.
+            dst: Destination list key.
+
+        Returns:
+            The moved element, or ``None`` if ``src`` is empty.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        value = await self.client.rpoplpush(src, dst)
+        return str(value) if value is not None else None

codex_platform/redis_service/operations/pipeline.py

@@ -0,0 +1,197 @@
+"""
+codex_platform.redis_service.operations.pipeline
+=================================================
+Redis Pipeline & Atomic operations.
+
+Two modes:
+- ``execute``  — pipeline without MULTI/EXEC (batching, not atomic).
+- ``transact`` — pipeline with MULTI/EXEC (atomic transaction).
+- ``atomic``   — async context manager that yields a Pipeline in MULTI/EXEC mode.
+- ``eval_script`` — Lua script execution (always atomic in Redis).
+
+Usage::
+
+    # Batching (faster, not atomic)
+    results = await ops.pipeline.execute(build_fn)
+
+    # Atomic transaction (MULTI/EXEC)
+    results = await ops.pipeline.transact(build_fn)
+
+    # Atomic context manager
+    async with ops.pipeline.atomic() as pipe:
+        await pipe.set("k1", "v1")
+        await pipe.incr("counter")
+    # committed on exit
+
+    # Lua script
+    await ops.pipeline.eval_script(
+        "return redis.call('SET', KEYS[1], ARGV[1])",
+        keys=["mykey"], args=["value"],
+    )
+"""
+
+import logging
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from typing import Any
+
+from redis.asyncio import Redis
+from redis.asyncio.client import Pipeline
+
+from codex_platform.redis_service.base import catch_redis_errors
+from codex_platform.redis_service.exceptions import RedisConnectionError, RedisServiceError
+
+log = logging.getLogger(__name__)
+
+
+class PipelineOperations:
+    """Redis pipeline and atomic transaction operations.
+
+    Provides three execution modes:
+
+    - **Batching** (``execute``) — commands are sent in one round-trip, not atomic.
+    - **Transaction** (``transact``) — commands are wrapped in MULTI/EXEC, atomic.
+    - **Context manager** (``atomic``) — atomic block with automatic EXEC on exit.
+
+    Also exposes Lua script execution via ``eval_script``.
+    """
+
+    def __init__(self, client: Redis) -> None:
+        self.client = client
+
+    @catch_redis_errors
+    async def execute(self, builder_func: Callable[[Pipeline], Awaitable[None]]) -> list[Any]:
+        """Execute a sequence of commands in a pipeline without MULTI/EXEC (batching).
+
+        Commands are sent in a single round-trip but are **not** atomic.
+        Use ``transact`` or ``atomic`` when atomicity is required.
+
+        Args:
+            builder_func: Async function that receives a ``Pipeline`` and queues commands.
+
+        Returns:
+            List of results for each queued command, in order.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+
+        Example::
+
+            async def build(pipe):
+                await pipe.set("k1", "v1")
+                await pipe.set("k2", "v2")
+
+            results = await ops.execute(build)
+        """
+        async with self.client.pipeline(transaction=False) as pipe:
+            await builder_func(pipe)
+            results = await pipe.execute()
+        log.debug("PipelineOps | execute commands=%d", len(results))
+        return results
+
+    @catch_redis_errors
+    async def transact(self, builder_func: Callable[[Pipeline], Awaitable[None]]) -> list[Any]:
+        """Execute commands in an atomic transaction (MULTI/EXEC).
+
+        All commands inside ``builder_func`` are executed atomically.
+        If the server crashes before EXEC, none of the commands are applied.
+
+        Args:
+            builder_func: Async function that receives a ``Pipeline`` and queues commands.
+
+        Returns:
+            List of results for each queued command, in order.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+
+        Example::
+
+            async def transfer(pipe):
+                await pipe.decrby("wallet:from", 100)
+                await pipe.incrby("wallet:to", 100)
+
+            results = await ops.transact(transfer)
+        """
+        async with self.client.pipeline(transaction=True) as pipe:
+            await builder_func(pipe)
+            results = await pipe.execute()
+        log.debug("PipelineOps | transact commands=%d", len(results))
+        return results
+
+    @asynccontextmanager
+    async def atomic(self) -> AsyncIterator[Pipeline]:
+        """Async context manager for an atomic block (MULTI/EXEC).
+
+        Opens a Pipeline in transaction mode. EXEC is called automatically on exit.
+
+        Yields:
+            ``Pipeline`` instance in MULTI/EXEC mode.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+
+        Example::
+
+            async with service.pipeline.atomic() as pipe:
+                await pipe.set("session:abc", "token")
+                await pipe.expire("session:abc", 3600)
+            # EXEC is called automatically on context exit
+        """
+        from redis.exceptions import ConnectionError, RedisError, TimeoutError
+
+        pipe: Pipeline = self.client.pipeline(transaction=True)
+        try:
+            async with pipe as p:
+                yield p
+                await p.execute()
+                log.debug("PipelineOps | atomic block committed")
+        except (ConnectionError, TimeoutError) as e:
+            raise RedisConnectionError(f"Atomic block connection failed: {e}") from e
+        except RedisError as e:
+            raise RedisServiceError(f"Atomic block error: {e}") from e
+
+    @catch_redis_errors
+    async def eval_script(
+        self,
+        script: str,
+        keys: list[str] | None = None,
+        args: list[Any] | None = None,
+    ) -> Any:
+        """Execute a Lua script (EVAL). Lua scripts are always atomic in Redis.
+
+        Use for complex read-modify-write operations that must not be interrupted.
+
+        Args:
+            script: Lua script source code.
+            keys: List of Redis keys accessible as ``KEYS[1]``, ``KEYS[2]``, etc.
+            args: Script arguments accessible as ``ARGV[1]``, ``ARGV[2]``, etc.
+
+        Returns:
+            Value returned by the Lua script.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+
+        Example::
+
+            result = await ops.eval_script(
+                \"\"\"
+                local val = redis.call('GET', KEYS[1])
+                if val == ARGV[1] then
+                    redis.call('SET', KEYS[1], ARGV[2])
+                    return 1
+                end
+                return 0
+                \"\"\",
+                keys=["mykey"],
+                args=["expected", "new_value"],
+            )
+        """
+        result = await self.client.eval(script, len(keys or []), *(keys or []), *(args or []))
+        log.debug("PipelineOps | eval_script keys=%d args=%d", len(keys or []), len(args or []))
+        return result

codex_platform/redis_service/operations/set_.py

@@ -0,0 +1,212 @@
+"""
+codex_platform.redis_service.operations.set_
+=============================================
+Redis Set operations.
+"""
+
+import logging
+from typing import Any
+
+from redis.asyncio import Redis
+
+from codex_platform.redis_service.base import catch_redis_errors
+from codex_platform.redis_service.keys import BaseRedisKey, resolve_key
+
+log = logging.getLogger(__name__)
+
+
+class SetOperations:
+    """Redis Set operations (SADD / SREM / SMEMBERS / SISMEMBER and more).
+
+    Accepts an already-constructed ``redis.asyncio.Redis`` client.
+    All methods wrap Redis errors in typed exceptions.
+
+    Example::
+
+        ops = SetOperations(client)
+        await ops.add("tags:post:42", "python", "redis")
+        has_tag = await ops.is_member("tags:post:42", "python")
+    """
+
+    def __init__(self, client: Redis) -> None:
+        self.client = client
+
+    @catch_redis_errors
+    async def add(self, key: "str | BaseRedisKey", *values: str | int, **kwargs: Any) -> int:
+        """Add one or more members to a set (SADD).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            *values: Values to add. Integers are coerced to strings.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Number of members actually added (already-existing members are not counted).
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.sadd(real_key, *[str(v) for v in values]))
+
+    @catch_redis_errors
+    async def remove(self, key: "str | BaseRedisKey", *values: str | int, **kwargs: Any) -> int:
+        """Remove one or more members from a set (SREM).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            *values: Values to remove. Integers are coerced to strings.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Number of members actually removed.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.srem(real_key, *[str(v) for v in values]))
+
+    @catch_redis_errors
+    async def members(self, key: "str | BaseRedisKey", **kwargs: Any) -> set[str]:
+        """Return all members of a set (SMEMBERS).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Set of all member strings. Empty set if the key does not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return await self.client.smembers(real_key)
+
+    @catch_redis_errors
+    async def is_member(self, key: "str | BaseRedisKey", value: str | int, **kwargs: Any) -> bool:
+        """Check whether a value is a member of a set (SISMEMBER).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            value: Value to check. Integers are coerced to strings.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            ``True`` if the value is in the set, ``False`` otherwise.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return bool(await self.client.sismember(real_key, str(value)))
+
+    @catch_redis_errors
+    async def card(self, key: "str | BaseRedisKey", **kwargs: Any) -> int:
+        """Return the number of members in a set (SCARD).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Set cardinality. ``0`` if the key does not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.scard(real_key))
+
+    @catch_redis_errors
+    async def pop(self, key: "str | BaseRedisKey", count: int = 1, **kwargs: Any) -> set[str]:
+        """Remove and return random members from a set (SPOP).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            count: Number of members to pop. Defaults to ``1``.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Set of popped members. Empty set if the key does not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        result = await self.client.spop(real_key, count)
+        return set(result) if result else set()
+
+    @catch_redis_errors
+    async def random(self, key: "str | BaseRedisKey", count: int = 1, **kwargs: Any) -> list[str]:
+        """Return random members without removing them (SRANDMEMBER).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            count: Number of random members to return.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            List of random members (may contain duplicates if ``count > cardinality``).
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return await self.client.srandmember(real_key, count)
+
+    @catch_redis_errors
+    async def union(self, *keys: str) -> set[str]:
+        """Return the union of multiple sets (SUNION).
+
+        Args:
+            *keys: Redis key strings.
+
+        Returns:
+            Set containing all members from all given sets.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        return await self.client.sunion(list(keys))
+
+    @catch_redis_errors
+    async def inter(self, *keys: str) -> set[str]:
+        """Return the intersection of multiple sets (SINTER).
+
+        Args:
+            *keys: Redis key strings.
+
+        Returns:
+            Set containing only members present in all given sets.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        return await self.client.sinter(list(keys))
+
+    @catch_redis_errors
+    async def diff(self, *keys: str) -> set[str]:
+        """Return the difference between the first set and all subsequent sets (SDIFF).
+
+        Args:
+            *keys: Redis key strings. The first key is the base set.
+
+        Returns:
+            Set of members present in the first set but not in any of the others.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        return await self.client.sdiff(list(keys))