xlambda-redis 0.2.0__tar.gz

xlambda_redis-0.2.0/.gitignore

@@ -0,0 +1,23 @@
+node_modules/
+dist/
+.env
+*.log
+.DS_Store
+cpp/build/
+cpp/*.o
+cpp/image-processor
+cpp/video-processor
+cpp/tour360-processor
+temp/
+.pnpm-store/
+.vscode/*
+.claude/*
+
+# Python - the SDK packages under packages-python/, plus the captions/ and
+# moderation/ workers. `dist/` above already covers built wheels.
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+.venv/
+venv/

xlambda_redis-0.2.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: xlambda-redis
+Version: 0.2.0
+Summary: xlambda managed Redis SDK: provisioning, sub-users, backups, and a get_client() convenience.
+Project-URL: Homepage, https://xlambda.tech
+Project-URL: Source, https://github.com/randyryan177-cloud/media-server/tree/main/packages-python/redis
+Author: xlambda
+License-Expression: MIT
+Keywords: cache,redis,sdk,xlambda
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: xlambda-core==0.2.0
+Provides-Extra: client
+Requires-Dist: redis>=5.0; extra == 'client'
+Description-Content-Type: text/markdown
+
+# xlambda-redis
+
+Managed Redis: provisioning, sub-users, backups, and a `get_client()`
+convenience.
+
+```
+pip install xlambda-redis            # provisioning only
+pip install "xlambda-redis[client]"  # plus redis-py, for get_client()
+```
+
+Python port of [`@xlambda-tech/redis`](../../packages/redis).
+
+`xlambda.redis` and redis-py's top-level `redis` coexist without shadowing
+each other — Python 3 imports are absolute, so importing one never resolves
+to the other.
+
+## Provisioning
+
+```python
+from xlambda.redis import RedisClient
+
+client = RedisClient(api_key=os.environ["XLAMBDA_API_KEY"])
+
+instance = client.instances.create(
+    project_id="proj_123",
+    name="cache",
+    tier="starter",              # shared; 'pro'/'business' are dedicated
+    persistence_mode="rdb",      # 'none' | 'rdb' | 'rdb_aof'
+)
+```
+
+`create()`, `rotate_password()`, and `reveal_connection()` return a
+`RedisInstanceHandle` — a plain `dict` subclass, so every response field reads
+normally, with client constructors added on top:
+
+```python
+cache = instance.get_client()              # redis-py, blocking
+cache.set("hello", "world")
+
+acache = instance.get_async_client()       # redis.asyncio
+await acache.set("hello", "world")
+```
+
+On shared-tier instances every key is namespaced behind `instance["keyPrefix"]`.
+
+`reveal_connection()` discloses the *current* password rather than changing
+it. It 404s for instances that predate the feature or were created without
+`CONSOLE_CREDENTIAL_ENCRYPTION_KEY` configured — rotate to recover.
+
+## Sub-users and backups
+
+```python
+user = client.instances.users(instance["id"]).create(permission="readonly")
+user["password"]     # shown once
+
+backups = client.instances.backups(instance["id"])
+backups.create()
+backups.restore("bkp_123")   # overwrites all current data; cannot be undone
+```
+
+## What this doesn't wrap
+
+The dashboard's own command / EVAL / pub-sub browser. Running commands isn't
+something the REST API mediates, so once an instance is provisioned you talk
+to it with redis-py through the handle above. `get_client()` is a thin
+ergonomic wrapper, not a reimplementation, and redis-py stays an optional
+extra so provisioning-only callers don't install a driver they never use.
+
+## Async
+
+```python
+from xlambda.redis import AsyncRedisClient
+
+async with AsyncRedisClient(api_key=...) as client:
+    instance = await client.instances.create(project_id="proj_123", name="cache", tier="starter")
+```
+
+Note the two axes are independent: `AsyncRedisClient` is about the
+*provisioning* API, `get_async_client()` about talking to Redis itself. You
+can mix them freely.
+
+## Conventions
+
+Arguments are snake_case; responses are the API's own camelCase, returned as
+plain dicts typed by `TypedDict`. `memoryBytes` and backup `sizeBytes` are
+bigints server-side and arrive as strings. See
+[xlambda-core](../core#conventions).

xlambda_redis-0.2.0/README.md

@@ -0,0 +1,87 @@
+# xlambda-redis
+
+Managed Redis: provisioning, sub-users, backups, and a `get_client()`
+convenience.
+
+```
+pip install xlambda-redis            # provisioning only
+pip install "xlambda-redis[client]"  # plus redis-py, for get_client()
+```
+
+Python port of [`@xlambda-tech/redis`](../../packages/redis).
+
+`xlambda.redis` and redis-py's top-level `redis` coexist without shadowing
+each other — Python 3 imports are absolute, so importing one never resolves
+to the other.
+
+## Provisioning
+
+```python
+from xlambda.redis import RedisClient
+
+client = RedisClient(api_key=os.environ["XLAMBDA_API_KEY"])
+
+instance = client.instances.create(
+    project_id="proj_123",
+    name="cache",
+    tier="starter",              # shared; 'pro'/'business' are dedicated
+    persistence_mode="rdb",      # 'none' | 'rdb' | 'rdb_aof'
+)
+```
+
+`create()`, `rotate_password()`, and `reveal_connection()` return a
+`RedisInstanceHandle` — a plain `dict` subclass, so every response field reads
+normally, with client constructors added on top:
+
+```python
+cache = instance.get_client()              # redis-py, blocking
+cache.set("hello", "world")
+
+acache = instance.get_async_client()       # redis.asyncio
+await acache.set("hello", "world")
+```
+
+On shared-tier instances every key is namespaced behind `instance["keyPrefix"]`.
+
+`reveal_connection()` discloses the *current* password rather than changing
+it. It 404s for instances that predate the feature or were created without
+`CONSOLE_CREDENTIAL_ENCRYPTION_KEY` configured — rotate to recover.
+
+## Sub-users and backups
+
+```python
+user = client.instances.users(instance["id"]).create(permission="readonly")
+user["password"]     # shown once
+
+backups = client.instances.backups(instance["id"])
+backups.create()
+backups.restore("bkp_123")   # overwrites all current data; cannot be undone
+```
+
+## What this doesn't wrap
+
+The dashboard's own command / EVAL / pub-sub browser. Running commands isn't
+something the REST API mediates, so once an instance is provisioned you talk
+to it with redis-py through the handle above. `get_client()` is a thin
+ergonomic wrapper, not a reimplementation, and redis-py stays an optional
+extra so provisioning-only callers don't install a driver they never use.
+
+## Async
+
+```python
+from xlambda.redis import AsyncRedisClient
+
+async with AsyncRedisClient(api_key=...) as client:
+    instance = await client.instances.create(project_id="proj_123", name="cache", tier="starter")
+```
+
+Note the two axes are independent: `AsyncRedisClient` is about the
+*provisioning* API, `get_async_client()` about talking to Redis itself. You
+can mix them freely.
+
+## Conventions
+
+Arguments are snake_case; responses are the API's own camelCase, returned as
+plain dicts typed by `TypedDict`. `memoryBytes` and backup `sizeBytes` are
+bigints server-side and arrive as strings. See
+[xlambda-core](../core#conventions).

xlambda_redis-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xlambda-redis"
+version = "0.2.0"
+description = "xlambda managed Redis SDK: provisioning, sub-users, backups, and a get_client() convenience."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "xlambda" }]
+keywords = ["xlambda", "redis", "cache", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Database",
+  "Typing :: Typed",
+]
+dependencies = ["xlambda-core==0.2.0"]
+
+[project.optional-dependencies]
+client = ["redis>=5.0"]
+
+[project.urls]
+Homepage = "https://xlambda.tech"
+Source = "https://github.com/randyryan177-cloud/media-server/tree/main/packages-python/redis"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/xlambda"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

xlambda_redis-0.2.0/src/xlambda/redis/__init__.py

@@ -0,0 +1,68 @@
+"""xlambda-redis: managed Redis provisioning, sub-users, backups, clients.
+
+    from xlambda.redis import RedisClient
+
+Deliberately doesn't wrap the dashboard's own command/EVAL/pub-sub browser (a
+dashboard feature, not something a backend app calls) - once an instance is
+provisioned, talk to it with redis-py through the handle's get_client().
+
+``xlambda.redis`` and top-level ``redis`` (redis-py) coexist fine: Python 3
+imports are absolute, so neither shadows the other.
+"""
+
+from __future__ import annotations
+
+from xlambda.core import XlambdaError
+
+from .backups import (
+    AsyncRedisBackupsResource,
+    RedisBackup,
+    RedisBackupList,
+    RedisBackupsResource,
+)
+from .client import AsyncRedisClient, RedisClient
+from .connection import RedisInstanceHandle
+from .instances import (
+    AsyncRedisInstancesResource,
+    IsolationModel,
+    PersistenceMode,
+    RedisInstance,
+    RedisInstanceList,
+    RedisInstancesResource,
+    RedisInstanceWithSecrets,
+)
+from .users import (
+    AsyncRedisUsersResource,
+    Permission,
+    RedisUser,
+    RedisUserList,
+    RedisUsersResource,
+    RedisUserWithSecret,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AsyncRedisBackupsResource",
+    "AsyncRedisClient",
+    "AsyncRedisInstancesResource",
+    "AsyncRedisUsersResource",
+    "IsolationModel",
+    "Permission",
+    "PersistenceMode",
+    "RedisBackup",
+    "RedisBackupList",
+    "RedisBackupsResource",
+    "RedisClient",
+    "RedisInstance",
+    "RedisInstanceHandle",
+    "RedisInstanceList",
+    "RedisInstanceWithSecrets",
+    "RedisInstancesResource",
+    "RedisUser",
+    "RedisUserList",
+    "RedisUserWithSecret",
+    "RedisUsersResource",
+    "XlambdaError",
+    "__version__",
+]

xlambda_redis-0.2.0/src/xlambda/redis/backups.py

@@ -0,0 +1,73 @@
+"""Backups for one managed Redis instance."""
+
+from __future__ import annotations
+
+from typing import List, Optional, TypedDict
+
+from xlambda.core import AsyncXlambdaClient, XlambdaClient
+from xlambda.core._transport import quote_segment
+
+
+class RedisBackup(TypedDict):
+    id: str
+    managedRedisInstanceId: str
+    status: str
+    # A bigint server-side, so it arrives as a string rather than losing
+    # precision in JSON.
+    sizeBytes: Optional[str]
+    triggeredBy: str
+    startedAt: str
+    completedAt: Optional[str]
+    failureReason: Optional[str]
+
+
+class RedisBackupList(TypedDict):
+    backups: List[RedisBackup]
+
+
+class RestoreResult(TypedDict):
+    success: bool
+
+
+def _backups_path(instance_id: str) -> str:
+    return f"/v1/redis/{quote_segment(instance_id)}/backups"
+
+
+def _restore_path(instance_id: str, backup_id: str) -> str:
+    return f"{_backups_path(instance_id)}/{quote_segment(backup_id)}/restore"
+
+
+class RedisBackupsResource:
+    """``client.instances.backups(instance_id)`` - blocking."""
+
+    def __init__(self, http: XlambdaClient, instance_id: str) -> None:
+        self._http = http
+        self._instance_id = instance_id
+
+    def create(self) -> RedisBackup:
+        return self._http.request(_backups_path(self._instance_id), method="POST")
+
+    def list(self) -> RedisBackupList:
+        return self._http.request(_backups_path(self._instance_id))
+
+    def restore(self, backup_id: str) -> RestoreResult:
+        """Overwrites all current data with this backup's contents. Cannot be undone."""
+        return self._http.request(_restore_path(self._instance_id, backup_id), method="POST")
+
+
+class AsyncRedisBackupsResource:
+    """``client.instances.backups(instance_id)`` - awaitable."""
+
+    def __init__(self, http: AsyncXlambdaClient, instance_id: str) -> None:
+        self._http = http
+        self._instance_id = instance_id
+
+    async def create(self) -> RedisBackup:
+        return await self._http.request(_backups_path(self._instance_id), method="POST")
+
+    async def list(self) -> RedisBackupList:
+        return await self._http.request(_backups_path(self._instance_id))
+
+    async def restore(self, backup_id: str) -> RestoreResult:
+        """Overwrites all current data with this backup's contents. Cannot be undone."""
+        return await self._http.request(_restore_path(self._instance_id, backup_id), method="POST")

xlambda_redis-0.2.0/src/xlambda/redis/client.py

@@ -0,0 +1,86 @@
+"""The two entry points: ``RedisClient`` and ``AsyncRedisClient``.
+
+Named for the managed service, not for redis-py - this client talks to
+xlambda's provisioning API. The thing that runs GET/SET is redis-py, reached
+through ``handle.get_client()``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from xlambda.core import AsyncXlambdaClient, XlambdaClient
+from xlambda.core._transport import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_SECONDS
+
+from .instances import AsyncRedisInstancesResource, RedisInstancesResource
+
+
+class RedisClient:
+    """Blocking managed-Redis client.
+
+        client = RedisClient(api_key=os.environ["XLAMBDA_API_KEY"])
+        instance = client.instances.create(project_id="proj_123", name="cache", tier="starter")
+        cache = instance.get_client()
+
+    See :class:`xlambda.core.XlambdaClient` for what the shared options do.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._http = XlambdaClient(
+            api_key,
+            base_url=base_url,
+            max_retries=max_retries,
+            timeout=timeout,
+            http_client=http_client,
+        )
+        self.instances = RedisInstancesResource(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "RedisClient":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+
+class AsyncRedisClient:
+    """Awaitable twin of :class:`RedisClient`."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._http = AsyncXlambdaClient(
+            api_key,
+            base_url=base_url,
+            max_retries=max_retries,
+            timeout=timeout,
+            http_client=http_client,
+        )
+        self.instances = AsyncRedisInstancesResource(self._http)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncRedisClient":
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()

xlambda_redis-0.2.0/src/xlambda/redis/connection.py

@@ -0,0 +1,47 @@
+"""Client convenience over a provisioned instance's credentials.
+
+``redis`` (redis-py) is an optional dependency
+(``pip install "xlambda-redis[client]"``) imported lazily here, so a consumer
+who never calls get_client() doesn't need it installed. Same reasoning as
+xlambda-postgres's pool.py: the platform's REST API never mediates actual Redis
+commands (the dashboard's own command/EVAL/pub-sub browser does that,
+deliberately not wrapped here), so this is a thin ergonomic wrapper, not a
+reimplementation.
+
+Note the absolute import below resolves to redis-py, not this module - Python 3
+imports are absolute, so ``xlambda.redis`` and top-level ``redis`` coexist
+without shadowing each other.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+_MISSING_DRIVER = (
+    'get_client() requires redis-py - install it with `pip install "xlambda-redis[client]"`.'
+)
+
+
+class RedisInstanceHandle(Dict[str, Any]):
+    """A provisioned instance, plus client constructors.
+
+    Subclasses ``dict``, so every field of the API response is still read the
+    normal way (``handle["connectionString"]``, ``handle["keyPrefix"]``) - the
+    methods are additive.
+    """
+
+    def get_client(self, **kwargs: Any) -> Any:
+        """A blocking redis-py client bound to this instance's connection string."""
+        try:
+            import redis
+        except ImportError as err:  # pragma: no cover - depends on the environment
+            raise ImportError(_MISSING_DRIVER) from err
+        return redis.Redis.from_url(self["connectionString"], **kwargs)
+
+    def get_async_client(self, **kwargs: Any) -> Any:
+        """An asyncio redis-py client bound to this instance's connection string."""
+        try:
+            import redis.asyncio as redis_asyncio
+        except ImportError as err:  # pragma: no cover
+            raise ImportError(_MISSING_DRIVER) from err
+        return redis_asyncio.Redis.from_url(self["connectionString"], **kwargs)

xlambda_redis-0.2.0/src/xlambda/redis/instances.py

@@ -0,0 +1,224 @@
+"""Provisioning and lifecycle for managed Redis instances."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict
+
+from xlambda.core import AsyncXlambdaClient, XlambdaClient
+from xlambda.core._transport import compact, quote_segment
+
+from .backups import AsyncRedisBackupsResource, RedisBackupsResource
+from .connection import RedisInstanceHandle
+from .users import AsyncRedisUsersResource, RedisUsersResource
+
+REDIS_PATH = "/v1/redis"
+
+PersistenceMode = Literal["none", "rdb", "rdb_aof"]
+IsolationModel = Literal["shared", "dedicated"]
+
+
+class RedisInstance(TypedDict):
+    id: str
+    projectId: str
+    name: str
+    isolationModel: IsolationModel
+    status: str
+    tier: str
+    maxMemoryMb: int
+    maxMemoryPolicy: str
+    persistenceMode: PersistenceMode
+    connectionLimit: Optional[int]
+    # A bigint server-side, so it arrives as a string.
+    memoryBytes: str
+    activeConnections: int
+    backupRetentionDays: int
+    lastBackupAt: Optional[str]
+    suspendedAt: Optional[str]
+    createdAt: str
+    updatedAt: str
+    host: Optional[str]
+    port: Optional[int]
+    username: str
+    # Set on shared-tier instances, which namespace every key behind it.
+    keyPrefix: Optional[str]
+
+
+class RedisInstanceWithSecrets(RedisInstance):
+    """Only returned by create(), rotate_password(), and reveal_connection()."""
+
+    password: str
+    connectionString: str
+
+
+class RedisInstanceList(TypedDict):
+    instances: List[RedisInstance]
+
+
+class DeleteResult(TypedDict):
+    success: bool
+
+
+def _instance_path(instance_id: str) -> str:
+    return f"{REDIS_PATH}/{quote_segment(instance_id)}"
+
+
+def _create_body(
+    *,
+    project_id: str,
+    name: str,
+    tier: str,
+    max_memory_mb: Optional[int],
+    max_memory_policy: Optional[str],
+    persistence_mode: Optional[PersistenceMode],
+    connection_limit: Optional[int],
+) -> Dict[str, Any]:
+    return compact(
+        {
+            "projectId": project_id,
+            "name": name,
+            "tier": tier,
+            "maxMemoryMb": max_memory_mb,
+            "maxMemoryPolicy": max_memory_policy,
+            "persistenceMode": persistence_mode,
+            "connectionLimit": connection_limit,
+        }
+    )
+
+
+class RedisInstancesResource:
+    """``client.instances`` - blocking."""
+
+    def __init__(self, http: XlambdaClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        project_id: str,
+        name: str,
+        tier: str,
+        max_memory_mb: Optional[int] = None,
+        max_memory_policy: Optional[str] = None,
+        persistence_mode: Optional[PersistenceMode] = None,
+        connection_limit: Optional[int] = None,
+    ) -> RedisInstanceHandle:
+        """Provision an instance. The returned handle also builds redis-py clients.
+
+        ``tier`` is e.g. 'starter' (shared) or 'pro'/'business' (dedicated) -
+        see the dashboard for the current tier list.
+        """
+        return RedisInstanceHandle(
+            self._http.request(
+                REDIS_PATH,
+                method="POST",
+                body=_create_body(
+                    project_id=project_id,
+                    name=name,
+                    tier=tier,
+                    max_memory_mb=max_memory_mb,
+                    max_memory_policy=max_memory_policy,
+                    persistence_mode=persistence_mode,
+                    connection_limit=connection_limit,
+                ),
+            )
+        )
+
+    def list(self, *, project_id: Optional[str] = None) -> RedisInstanceList:
+        return self._http.request(REDIS_PATH, query=compact({"projectId": project_id}))
+
+    def get(self, instance_id: str) -> RedisInstance:
+        return self._http.request(_instance_path(instance_id))
+
+    def delete(self, instance_id: str) -> DeleteResult:
+        return self._http.request(_instance_path(instance_id), method="DELETE")
+
+    def rotate_password(self, instance_id: str) -> RedisInstanceHandle:
+        return RedisInstanceHandle(
+            self._http.request(f"{_instance_path(instance_id)}/rotate-password", method="POST")
+        )
+
+    def reveal_connection(self, instance_id: str) -> RedisInstanceHandle:
+        """Disclose the CURRENT password rather than changing it.
+
+        404s if the instance predates this feature or was created without
+        CONSOLE_CREDENTIAL_ENCRYPTION_KEY configured - rotate to recover.
+        """
+        return RedisInstanceHandle(
+            self._http.request(f"{_instance_path(instance_id)}/reveal-connection", method="POST")
+        )
+
+    def set_connection_limit(self, instance_id: str, limit: int) -> RedisInstance:
+        return self._http.request(
+            f"{_instance_path(instance_id)}/connection-limit", method="POST", body={"limit": limit}
+        )
+
+    def users(self, instance_id: str) -> RedisUsersResource:
+        return RedisUsersResource(self._http, instance_id)
+
+    def backups(self, instance_id: str) -> RedisBackupsResource:
+        return RedisBackupsResource(self._http, instance_id)
+
+
+class AsyncRedisInstancesResource:
+    """``client.instances`` - awaitable."""
+
+    def __init__(self, http: AsyncXlambdaClient) -> None:
+        self._http = http
+
+    async def create(
+        self,
+        *,
+        project_id: str,
+        name: str,
+        tier: str,
+        max_memory_mb: Optional[int] = None,
+        max_memory_policy: Optional[str] = None,
+        persistence_mode: Optional[PersistenceMode] = None,
+        connection_limit: Optional[int] = None,
+    ) -> RedisInstanceHandle:
+        return RedisInstanceHandle(
+            await self._http.request(
+                REDIS_PATH,
+                method="POST",
+                body=_create_body(
+                    project_id=project_id,
+                    name=name,
+                    tier=tier,
+                    max_memory_mb=max_memory_mb,
+                    max_memory_policy=max_memory_policy,
+                    persistence_mode=persistence_mode,
+                    connection_limit=connection_limit,
+                ),
+            )
+        )
+
+    async def list(self, *, project_id: Optional[str] = None) -> RedisInstanceList:
+        return await self._http.request(REDIS_PATH, query=compact({"projectId": project_id}))
+
+    async def get(self, instance_id: str) -> RedisInstance:
+        return await self._http.request(_instance_path(instance_id))
+
+    async def delete(self, instance_id: str) -> DeleteResult:
+        return await self._http.request(_instance_path(instance_id), method="DELETE")
+
+    async def rotate_password(self, instance_id: str) -> RedisInstanceHandle:
+        return RedisInstanceHandle(
+            await self._http.request(f"{_instance_path(instance_id)}/rotate-password", method="POST")
+        )
+
+    async def reveal_connection(self, instance_id: str) -> RedisInstanceHandle:
+        """See :meth:`RedisInstancesResource.reveal_connection`."""
+        return RedisInstanceHandle(
+            await self._http.request(f"{_instance_path(instance_id)}/reveal-connection", method="POST")
+        )
+
+    async def set_connection_limit(self, instance_id: str, limit: int) -> RedisInstance:
+        return await self._http.request(
+            f"{_instance_path(instance_id)}/connection-limit", method="POST", body={"limit": limit}
+        )
+
+    def users(self, instance_id: str) -> AsyncRedisUsersResource:
+        return AsyncRedisUsersResource(self._http, instance_id)
+
+    def backups(self, instance_id: str) -> AsyncRedisBackupsResource:
+        return AsyncRedisBackupsResource(self._http, instance_id)

xlambda_redis-0.2.0/src/xlambda/redis/users.py

@@ -0,0 +1,97 @@
+"""Sub-users scoped to one managed Redis instance."""
+
+from __future__ import annotations
+
+from typing import List, Literal, Optional, TypedDict
+
+from xlambda.core import AsyncXlambdaClient, XlambdaClient
+from xlambda.core._transport import compact, quote_segment
+
+Permission = Literal["readonly", "readwrite"]
+
+
+class RedisUser(TypedDict):
+    id: str
+    managedRedisInstanceId: str
+    permission: Permission
+    expiresAt: Optional[str]
+    revokedAt: Optional[str]
+    createdAt: str
+    lastRotatedAt: Optional[str]
+    username: str
+
+
+class RedisUserWithSecret(RedisUser):
+    password: str
+
+
+class RedisUserList(TypedDict):
+    users: List[RedisUser]
+
+
+class DeleteResult(TypedDict):
+    success: bool
+
+
+def _users_path(instance_id: str) -> str:
+    return f"/v1/redis/{quote_segment(instance_id)}/users"
+
+
+def _user_path(instance_id: str, user_id: str) -> str:
+    return f"{_users_path(instance_id)}/{quote_segment(user_id)}"
+
+
+def _create_body(permission: Optional[Permission], expires_at: Optional[str]) -> dict:
+    return compact({"permission": permission, "expiresAt": expires_at})
+
+
+class RedisUsersResource:
+    """``client.instances.users(instance_id)`` - blocking."""
+
+    def __init__(self, http: XlambdaClient, instance_id: str) -> None:
+        self._http = http
+        self._instance_id = instance_id
+
+    def create(
+        self, *, permission: Optional[Permission] = None, expires_at: Optional[str] = None
+    ) -> RedisUserWithSecret:
+        return self._http.request(
+            _users_path(self._instance_id), method="POST", body=_create_body(permission, expires_at)
+        )
+
+    def list(self) -> RedisUserList:
+        return self._http.request(_users_path(self._instance_id))
+
+    def delete(self, user_id: str) -> DeleteResult:
+        return self._http.request(_user_path(self._instance_id, user_id), method="DELETE")
+
+    def rotate_password(self, user_id: str) -> RedisUserWithSecret:
+        return self._http.request(
+            f"{_user_path(self._instance_id, user_id)}/rotate-password", method="POST"
+        )
+
+
+class AsyncRedisUsersResource:
+    """``client.instances.users(instance_id)`` - awaitable."""
+
+    def __init__(self, http: AsyncXlambdaClient, instance_id: str) -> None:
+        self._http = http
+        self._instance_id = instance_id
+
+    async def create(
+        self, *, permission: Optional[Permission] = None, expires_at: Optional[str] = None
+    ) -> RedisUserWithSecret:
+        return await self._http.request(
+            _users_path(self._instance_id), method="POST", body=_create_body(permission, expires_at)
+        )
+
+    async def list(self) -> RedisUserList:
+        return await self._http.request(_users_path(self._instance_id))
+
+    async def delete(self, user_id: str) -> DeleteResult:
+        return await self._http.request(_user_path(self._instance_id, user_id), method="DELETE")
+
+    async def rotate_password(self, user_id: str) -> RedisUserWithSecret:
+        return await self._http.request(
+            f"{_user_path(self._instance_id, user_id)}/rotate-password", method="POST"
+        )

xlambda_redis-0.2.0/tests/test_redis.py

@@ -0,0 +1,128 @@
+"""Route shapes, the instance handle, and the xlambda.redis / redis-py coexistence."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import httpx
+import pytest
+
+from xlambda.redis import AsyncRedisClient, RedisClient, RedisInstanceHandle
+
+CREATED = {
+    "id": "red_1",
+    "projectId": "p1",
+    "name": "cache",
+    "isolationModel": "shared",
+    "status": "ready",
+    "tier": "starter",
+    "maxMemoryMb": 256,
+    "username": "u",
+    "password": "secret",
+    "keyPrefix": "red_1:",
+    "connectionString": "redis://u:secret@redis.example.com:6379",
+}
+
+
+def recorder(response=None):
+    seen = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(
+            {
+                "method": request.method,
+                "url": str(request.url),
+                "body": json.loads(request.content) if request.content else None,
+            }
+        )
+        return httpx.Response(200, json=response if response is not None else {"ok": True})
+
+    return handler, seen
+
+
+def sync_client(handler) -> RedisClient:
+    return RedisClient("key", http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+
+
+def test_create_sends_camel_case_and_omits_unset_options():
+    handler, seen = recorder(CREATED)
+    sync_client(handler).instances.create(
+        project_id="p1", name="cache", tier="starter", persistence_mode="rdb"
+    )
+
+    assert seen[0]["url"] == "https://api.xlambda.tech/v1/redis"
+    assert seen[0]["body"] == {
+        "projectId": "p1",
+        "name": "cache",
+        "tier": "starter",
+        "persistenceMode": "rdb",
+    }
+
+
+def test_create_returns_a_handle_that_is_still_a_plain_dict():
+    handler, _ = recorder(CREATED)
+    instance = sync_client(handler).instances.create(project_id="p1", name="cache", tier="starter")
+
+    assert isinstance(instance, RedisInstanceHandle)
+    assert isinstance(instance, dict)
+    # Shared-tier instances namespace every key behind this prefix.
+    assert instance["keyPrefix"] == "red_1:"
+
+
+def test_get_client_raises_a_useful_error_when_redis_py_is_missing(monkeypatch):
+    import builtins
+
+    real_import = builtins.__import__
+
+    def blocked(name, *args, **kwargs):
+        if name == "redis" or name.startswith("redis."):
+            raise ImportError("no redis-py here")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", blocked)
+
+    with pytest.raises(ImportError, match="xlambda-redis\\[client\\]"):
+        RedisInstanceHandle(CREATED).get_client()
+
+
+def test_this_package_does_not_shadow_redis_py():
+    """xlambda.redis and top-level redis have to coexist - Python 3 imports are
+    absolute, so importing one must never resolve to the other."""
+    import xlambda.redis
+
+    assert xlambda.redis.__name__ == "xlambda.redis"
+    assert hasattr(xlambda.redis, "RedisClient")
+
+
+def test_nested_user_and_backup_routes():
+    handler, seen = recorder()
+    instances = sync_client(handler).instances
+
+    instances.users("red_1").create(permission="readwrite")
+    instances.backups("red_1").restore("bkp_1")
+    instances.reveal_connection("red_1")
+    instances.set_connection_limit("red_1", 10)
+
+    assert seen[0]["url"] == "https://api.xlambda.tech/v1/redis/red_1/users"
+    assert seen[0]["body"] == {"permission": "readwrite"}
+    assert seen[1]["url"] == "https://api.xlambda.tech/v1/redis/red_1/backups/bkp_1/restore"
+    assert seen[2]["url"] == "https://api.xlambda.tech/v1/redis/red_1/reveal-connection"
+    assert seen[3]["body"] == {"limit": 10}
+
+
+def test_async_client_produces_the_same_requests():
+    sync_handler, sync_seen = recorder(CREATED)
+    async_handler, async_seen = recorder(CREATED)
+
+    sync_client(sync_handler).instances.create(project_id="p1", name="cache", tier="starter")
+
+    async def run():
+        async with AsyncRedisClient(
+            "key", http_client=httpx.AsyncClient(transport=httpx.MockTransport(async_handler))
+        ) as client:
+            instance = await client.instances.create(project_id="p1", name="cache", tier="starter")
+            assert isinstance(instance, RedisInstanceHandle)
+
+    asyncio.run(run())
+    assert sync_seen == async_seen