fastapi-startkit 0.67.0__tar.gz → 0.69.0__tar.gz

{fastapi_startkit-0.67.0 → fastapi_startkit-0.69.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-startkit
-Version: 0.67.0
+Version: 0.69.0
 Summary: A modular, provider-driven framework for building async Python web applications with FastAPI — bundling a service container, configuration system, an async-first ORM, facades, and a Cleo-powered console.
 Keywords: fastapi,framework,async,web,asgi,orm,sqlalchemy,pydantic,ioc-container,dependency-injection,service-provider,cli,console,configuration,microservices,starter-kit,boilerplate
 Author: Bedram Tamang

{fastapi_startkit-0.67.0 → fastapi_startkit-0.69.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-startkit"
-version = "0.67.0"
+version = "0.69.0"
 description = "A modular, provider-driven framework for building async Python web applications with FastAPI — bundling a service container, configuration system, an async-first ORM, facades, and a Cleo-powered console."
 readme = "README.md"
 keywords = [

{fastapi_startkit-0.67.0 → fastapi_startkit-0.69.0}/src/fastapi_startkit/application.py

@@ -61,9 +61,8 @@ class Application(Container, Generic[TConfig]):
         self.resolve_environment()
         self.configure_config()
         self.configure_paths()
-        self.register_providers()
-
         self._fastapi: Optional["FastAPI"] = None
+        self.register_providers()
         self.load_providers()
 
     def set_environment(self, env: str):

{fastapi_startkit-0.67.0 → fastapi_startkit-0.69.0}/src/fastapi_startkit/broadcasting/config.py

@@ -8,7 +8,7 @@ from fastapi_startkit.environment import env
 class ReverbConnectionConfig(Config):
     driver: str = "reverb"
     key: str = env("REVERB_APP_KEY", "local")
-    secret: str = env("REVERB_APP_SECRET", "secret")
+    secret: str = env("REVERB_APP_SECRET", "")
     app_id: str = env("REVERB_APP_ID", "1")
     host: str = env("REVERB_HOST", "0.0.0.0")
     port: int = env("REVERB_PORT", 8080)

{fastapi_startkit-0.67.0 → fastapi_startkit-0.69.0}/src/fastapi_startkit/broadcasting/provider.py

@@ -2,13 +2,19 @@ from __future__ import annotations
 
 import importlib
 import importlib.util
+import json
 import sys
+from collections.abc import Mapping
 from pathlib import Path
 
 from fastapi_startkit.support import Provider
 from .config import BroadcastingConfig
 from .manager import BroadcastManager
 from .reverb.server import ReverbServer
+from .reverb.signature import is_presence, requires_auth, sign, valid_channel, valid_socket_id
+
+UNSAFE_SECRETS = ("", "secret")
+INSECURE_ENVIRONMENTS = ("local", "testing")
 
 
 class ReverbProvider(Provider):
@@ -36,7 +42,14 @@ class ReverbProvider(Provider):
         config_data = self.resolve_config(BroadcastingConfig)
         self.merge_config_from(config_data, "broadcasting")
 
-        server = ReverbServer()
+        reverb = config_data.get("connections", {}).get("reverb", {})
+        secret = reverb.get("secret") or ""
+        if secret in UNSAFE_SECRETS and self.app.env not in INSECURE_ENVIRONMENTS:
+            raise RuntimeError(
+                f"REVERB_APP_SECRET must be set to a private value when APP_ENV is {self.app.env!r}; "
+                "private and presence channel signatures would otherwise be forgeable."
+            )
+        server = ReverbServer(key=reverb.get("key", "local"), secret=secret)
         manager = BroadcastManager(config_data, server)
 
         self.app.bind("broadcasting", manager)
@@ -81,91 +94,75 @@ class ReverbProvider(Provider):
         spec.loader.exec_module(module)  # type: ignore[union-attr]
 
     def _mount_websocket(self) -> None:
-        """Mount the Reverb WebSocket endpoint on the FastAPI application.
-
-        The endpoint path is ``/app/{app_key}``, matching the Pusher protocol
-        expected by Laravel Echo.  The ``app_key`` is taken from the
-        ``reverb.connections.reverb.key`` config value (default: ``"local"``).
-        """
         try:
             fastapi_app = self.app.fastapi
         except RuntimeError:
-            # FastAPI not installed or app not yet booted — skip
             return
 
-        config = self.app.make("config").get("broadcasting") or {}
-        connections = config.get("connections", {}) if isinstance(config, dict) else {}
-        reverb_conn = connections.get("reverb", {}) if isinstance(connections, dict) else {}
-        app_key = reverb_conn.get("key", "local") if isinstance(reverb_conn, dict) else "local"
-
         server: ReverbServer = self.app.make("reverb.server")
 
-        from starlette.routing import WebSocketRoute
-        from starlette.applications import Starlette
-
         async def ws_endpoint(websocket):
             await server.handle(websocket)
 
-        ws_app = Starlette(routes=[WebSocketRoute(f"/app/{app_key}", ws_endpoint)])
-        fastapi_app.mount("", ws_app)
+        fastapi_app.router.add_websocket_route(f"/app/{server.key}", ws_endpoint)
 
     def _mount_auth_endpoint(self) -> None:
-        """Mount the ``/broadcasting/auth`` HTTP endpoint.
-
-        The endpoint handles the Laravel Echo authentication handshake for
-        private and presence channels.  It:
-
-        1. Reads ``channel_name`` from the POST body (form or JSON).
-        2. Resolves the current user via the container's ``auth`` binding (if
-           available), falling back to ``request.state.user``.
-        3. Calls :meth:`~.auth.ChannelAuthRegistry.authorize` with the channel
-           name and the resolved user.
-        4. Returns **200** on success or **403** on denial.
-        """
         try:
             fastapi_app = self.app.fastapi
         except RuntimeError:
             return
 
-        from fastapi import Request
-        from fastapi.responses import JSONResponse
+        from starlette.requests import Request
+        from starlette.responses import JSONResponse
 
         application = self.app
 
-        @fastapi_app.post("/broadcasting/auth")
         async def broadcasting_auth(request: Request):
-            # Resolve channel name from form data or JSON body
-            content_type = request.headers.get("content-type", "")
-            if "application/json" in content_type:
-                body = await request.json()
-                channel_name = body.get("channel_name", "")
+            if "application/json" in request.headers.get("content-type", ""):
+                try:
+                    body = await request.json()
+                except ValueError:
+                    return JSONResponse({"error": "Malformed JSON body"}, status_code=400)
             else:
-                form = await request.form()
-                channel_name = form.get("channel_name", "")
-
-            if not isinstance(channel_name, str):
-                return JSONResponse({"error": "channel_name must be a string"}, status_code=422)
+                body = await request.form()
+            if not isinstance(body, Mapping):
+                return JSONResponse({"error": "Request body must be an object"}, status_code=422)
+
+            channel_name = body.get("channel_name", "")
+            socket_id = body.get("socket_id", "")
+            if not valid_socket_id(socket_id):
+                return JSONResponse({"error": "socket_id is invalid"}, status_code=422)
+            if not valid_channel(channel_name):
+                return JSONResponse({"error": "channel_name is invalid"}, status_code=422)
+
+            server: ReverbServer = application.make("reverb.server")
+            user = self._resolve_user(application, request)
+            if not server.secret or not requires_auth(channel_name) or user is None:
+                return JSONResponse({"error": "Forbidden"}, status_code=403)
 
-            # Resolve authenticated user.
-            # Prefer request.state.user (set by auth middleware), then fall
-            # back to the container's "auth" service.
-            user = getattr(request.state, "user", None)
-            if user is None:
-                try:
-                    auth_service = application.make("auth")
-                    user_attr = getattr(auth_service, "user", None)
-                    if callable(user_attr):
-                        user = user_attr()
-                    else:
-                        user = user_attr
-                except Exception:
-                    user = None
-
-            # Authorise
             manager: BroadcastManager = application.make("broadcasting")
-            allowed = await manager.channel_registry.authorize(channel_name, user)
+            if not await manager.channel_registry.authorize(channel_name, user):
+                return JSONResponse({"error": "Forbidden"}, status_code=403)
+
+            if not is_presence(channel_name):
+                return JSONResponse({"auth": sign(server.key, server.secret, socket_id, channel_name)})
 
-            if not allowed:
+            user_id = getattr(user, "id", None)
+            if user_id is None:
                 return JSONResponse({"error": "Forbidden"}, status_code=403)
+            channel_data = json.dumps({"user_id": str(user_id)})
+            auth = sign(server.key, server.secret, socket_id, channel_name, channel_data)
+            return JSONResponse({"auth": auth, "channel_data": channel_data})
 
-            return JSONResponse({"auth": True, "channel_data": {}})
+        fastapi_app.router.add_route("/broadcasting/auth", broadcasting_auth, methods=["POST"])
+
+    @staticmethod
+    def _resolve_user(application, request):
+        user = getattr(request.state, "user", None)
+        if user is not None:
+            return user
+        try:
+            user_attr = getattr(application.make("auth"), "user", None)
+        except Exception:
+            return None
+        return user_attr() if callable(user_attr) else user_attr

fastapi_startkit-0.69.0/src/fastapi_startkit/broadcasting/reverb/channel_manager.py

@@ -0,0 +1,21 @@
+class ChannelManager:
+    def __init__(self):
+        self._subscriptions: dict[str, set[str]] = {}
+
+    def subscribe(self, channel: str, socket_id: str) -> None:
+        self._subscriptions.setdefault(channel, set()).add(socket_id)
+
+    def unsubscribe(self, channel: str, socket_id: str) -> None:
+        subscribers = self._subscriptions.get(channel)
+        if subscribers is None:
+            return
+        subscribers.discard(socket_id)
+        if not subscribers:
+            del self._subscriptions[channel]
+
+    def remove_socket(self, socket_id: str) -> None:
+        for channel in list(self._subscriptions):
+            self.unsubscribe(channel, socket_id)
+
+    def subscribers(self, channel: str) -> set[str]:
+        return set(self._subscriptions.get(channel, set()))

{fastapi_startkit-0.67.0 → fastapi_startkit-0.69.0}/src/fastapi_startkit/broadcasting/reverb/connection.py

@@ -1,4 +1,5 @@
-import uuid
+import secrets
+
 from starlette.websockets import WebSocket
 
 
@@ -7,15 +8,21 @@ class ConnectionManager:
         self._connections: dict[str, WebSocket] = {}
 
     def add(self, websocket: WebSocket) -> str:
-        socket_id = str(uuid.uuid4())
+        socket_id = self._new_socket_id()
+        while socket_id in self._connections:
+            socket_id = self._new_socket_id()
         self._connections[socket_id] = websocket
         return socket_id
 
+    @staticmethod
+    def _new_socket_id() -> str:
+        return f"{secrets.randbelow(10**10)}.{secrets.randbelow(10**10)}"
+
     def remove(self, socket_id: str) -> None:
         self._connections.pop(socket_id, None)
 
     def get(self, socket_id: str):
         return self._connections.get(socket_id)
 
-    def all(self) -> dict:
+    def all(self) -> dict[str, WebSocket]:
         return dict(self._connections)

fastapi_startkit-0.69.0/src/fastapi_startkit/broadcasting/reverb/server.py

@@ -0,0 +1,119 @@
+import json
+
+from starlette.applications import Starlette
+from starlette.routing import WebSocketRoute
+from starlette.websockets import WebSocket, WebSocketDisconnect
+
+from .channel_manager import ChannelManager
+from .connection import ConnectionManager
+from .signature import requires_auth, valid_channel, verify
+
+MESSAGE_TOO_BIG = 1009
+
+
+class ReverbServer:
+    max_message_size = 10_000
+
+    def __init__(self, key: str = "local", secret: str = ""):
+        self.key = key
+        self.secret = secret
+        self.connections = ConnectionManager()
+        self.channels = ChannelManager()
+
+    async def handle(self, websocket: WebSocket):
+        await websocket.accept()
+        socket_id = self.connections.add(websocket)
+        try:
+            await self._send(
+                websocket,
+                "pusher:connection_established",
+                json.dumps({"socket_id": socket_id, "activity_timeout": 120}),
+            )
+            await self._receive_loop(socket_id, websocket)
+        except WebSocketDisconnect:
+            pass
+        finally:
+            self.connections.remove(socket_id)
+            self.channels.remove_socket(socket_id)
+
+    async def _receive_loop(self, socket_id: str, websocket: WebSocket):
+        while True:
+            frame = await websocket.receive()
+            if frame["type"] == "websocket.disconnect":
+                return
+            text = frame.get("text")
+            if text is not None and len(text) > self.max_message_size:
+                await self._error(websocket, "Maximum message size exceeded")
+                await websocket.close(code=MESSAGE_TOO_BIG)
+                return
+            message = self._parse(text)
+            if message is None:
+                await self._error(websocket, "Invalid message format")
+                continue
+            await self._handle_message(socket_id, websocket, message)
+
+    @staticmethod
+    def _parse(text: str | None) -> dict[str, object] | None:
+        if text is None:
+            return None
+        try:
+            message = json.loads(text)
+        except ValueError:
+            return None
+        if not isinstance(message, dict) or not isinstance(message.get("event", ""), str):
+            return None
+        return message
+
+    async def _handle_message(self, socket_id: str, websocket: WebSocket, message: dict[str, object]):
+        event = message.get("event", "")
+        if event == "pusher:ping":
+            await self._send(websocket, "pusher:pong", {})
+        elif event == "pusher:subscribe":
+            await self._subscribe(socket_id, websocket, message.get("data"))
+
+    async def _subscribe(self, socket_id: str, websocket: WebSocket, data: object):
+        if not isinstance(data, dict) or not isinstance(data.get("channel"), str) or not data["channel"]:
+            await self._error(websocket, "Invalid subscription")
+            return
+        channel = data["channel"]
+        if not valid_channel(channel):
+            await self._subscription_error(websocket, channel, "InvalidChannel", "Invalid channel name", 400)
+            return
+        if requires_auth(channel) and not verify(
+            self.key, self.secret, socket_id, channel, data.get("auth"), data.get("channel_data")
+        ):
+            await self._subscription_error(websocket, channel, "AuthError", "Invalid signature", 401)
+            return
+        self.channels.subscribe(channel, socket_id)
+        await self._send(websocket, "pusher_internal:subscription_succeeded", {}, channel)
+
+    async def _subscription_error(self, websocket: WebSocket, channel: str, kind: str, error: str, status: int):
+        await self._send(
+            websocket, "pusher:subscription_error", {"type": kind, "error": error, "status": status}, channel
+        )
+
+    async def _error(self, websocket: WebSocket, message: str):
+        await self._send(websocket, "pusher:error", {"code": 4200, "message": message})
+
+    @staticmethod
+    async def _send(websocket: WebSocket, event: str, data: object, channel: str | None = None):
+        payload: dict[str, object] = {"event": event, "data": data}
+        if channel is not None:
+            payload["channel"] = channel
+        await websocket.send_text(json.dumps(payload))
+
+    async def broadcast_to_channel(self, channel_name: str, event_name: str, data: dict[str, object]):
+        payload = json.dumps({"event": event_name, "channel": channel_name, "data": data})
+        for socket_id in self.channels.subscribers(channel_name):
+            ws = self.connections.get(socket_id)
+            if ws:
+                try:
+                    await ws.send_text(payload)
+                except Exception:
+                    pass
+
+    def as_starlette_app(self, app_key: str = "local") -> Starlette:
+        async def endpoint(ws: WebSocket):
+            await self.handle(ws)
+
+        return Starlette(routes=[WebSocketRoute(f"/app/{app_key}", endpoint)])

fastapi_startkit-0.69.0/src/fastapi_startkit/broadcasting/reverb/signature.py

@@ -0,0 +1,43 @@
+import hashlib
+import hmac
+import re
+
+from typing_extensions import TypeIs
+
+SOCKET_ID = re.compile(r"[0-9]+\.[0-9]+", re.ASCII)
+CHANNEL_NAME = re.compile(r"[A-Za-z0-9_\-=@,.;]{1,200}", re.ASCII)
+
+
+def valid_socket_id(socket_id: object) -> TypeIs[str]:
+    return isinstance(socket_id, str) and SOCKET_ID.fullmatch(socket_id) is not None
+
+
+def valid_channel(channel: object) -> TypeIs[str]:
+    return isinstance(channel, str) and CHANNEL_NAME.fullmatch(channel) is not None
+
+
+def requires_auth(channel: object) -> bool:
+    return isinstance(channel, str) and channel.startswith(("private-", "presence-"))
+
+
+def is_presence(channel: str) -> bool:
+    return channel.startswith("presence-")
+
+
+def sign(key: str, secret: str, socket_id: str, channel: str, channel_data: str | None = None) -> str:
+    parts = [socket_id, channel] if channel_data is None else [socket_id, channel, channel_data]
+    digest = hmac.new(secret.encode(), ":".join(parts).encode(), hashlib.sha256).hexdigest()
+    return f"{key}:{digest}"
+
+
+def verify(key: str, secret: str, socket_id: str, channel: str, auth: object, channel_data: object = None) -> bool:
+    if not secret or not isinstance(auth, str):
+        return False
+    if not valid_socket_id(socket_id) or not valid_channel(channel) or not requires_auth(channel):
+        return False
+    if not is_presence(channel):
+        channel_data = None
+    elif not isinstance(channel_data, str):
+        return False
+    expected = sign(key, secret, socket_id, channel, channel_data)
+    return hmac.compare_digest(auth.encode(), expected.encode())

fastapi_startkit-0.69.0/src/fastapi_startkit/cache/__init__.py

@@ -0,0 +1,30 @@
+from .array_store import ArrayStore
+from .config import ArrayStoreConfig, CacheConfig, DatabaseStoreConfig, FileStoreConfig, RedisStoreConfig
+from .file_store import FileStore
+from .lock import Lock, LockTimeoutError
+from .manager import CacheManager
+from .memo_store import MemoStore
+from .provider import CacheProvider
+from .repository import Repository
+from .store import MISSING, Store
+from .tagged_store import TaggedStore, TagSet
+
+__all__ = [
+    "MISSING",
+    "ArrayStore",
+    "ArrayStoreConfig",
+    "CacheConfig",
+    "CacheManager",
+    "CacheProvider",
+    "DatabaseStoreConfig",
+    "FileStore",
+    "FileStoreConfig",
+    "Lock",
+    "LockTimeoutError",
+    "MemoStore",
+    "RedisStoreConfig",
+    "Repository",
+    "Store",
+    "TagSet",
+    "TaggedStore",
+]

fastapi_startkit-0.69.0/src/fastapi_startkit/cache/array_store.py

@@ -0,0 +1,62 @@
+from typing import Any
+
+from .lock import Lock
+from .store import MISSING, expired, expires_at
+
+
+class ArrayStore:
+    def __init__(self) -> None:
+        self.storage: dict[str, tuple[float | None, Any]] = {}
+        self.locks: dict[str, tuple[str, float | None]] = {}
+
+    async def get(self, key: str) -> Any:
+        entry = self.storage.get(key)
+        if entry is None:
+            return MISSING
+
+        expiration, value = entry
+        if expired(expiration):
+            del self.storage[key]
+            return MISSING
+        return value
+
+    async def put(self, key: str, value: Any, seconds: float | None) -> bool:
+        self.storage[key] = (expires_at(seconds), value)
+        return True
+
+    async def forget(self, key: str) -> bool:
+        return self.storage.pop(key, MISSING) is not MISSING
+
+    async def flush(self) -> bool:
+        self.storage.clear()
+        return True
+
+    def lock(self, name: str, seconds: float = 0, owner: str | None = None) -> "ArrayLock":
+        return ArrayLock(self, name, seconds, owner)
+
+
+class ArrayLock(Lock):
+    def __init__(self, store: ArrayStore, name: str, seconds: float = 0, owner: str | None = None):
+        super().__init__(name, seconds, owner)
+        self.store = store
+
+    def holder(self) -> str | None:
+        entry = self.store.locks.get(self.name)
+        if entry is None or expired(entry[1]):
+            return None
+        return entry[0]
+
+    async def acquire(self) -> bool:
+        if self.holder() is not None:
+            return False
+        self.store.locks[self.name] = (self.owner, expires_at(self.ttl))
+        return True
+
+    async def release(self) -> bool:
+        if self.holder() != self.owner:
+            return False
+        del self.store.locks[self.name]
+        return True
+
+    async def force_release(self) -> None:
+        self.store.locks.pop(self.name, None)

fastapi_startkit-0.69.0/src/fastapi_startkit/cache/config/__init__.py

@@ -0,0 +1,45 @@
+from dataclasses import dataclass, field
+
+from fastapi_startkit.configuration import Config
+from fastapi_startkit.environment import env
+
+
+@dataclass
+class ArrayStoreConfig(Config):
+    driver: str = "array"
+
+
+@dataclass
+class FileStoreConfig(Config):
+    driver: str = "file"
+    path: str = env("CACHE_FILE_PATH", "storage/framework/cache/data")
+
+
+@dataclass
+class DatabaseStoreConfig(Config):
+    driver: str = "database"
+    connection: str | None = env("DB_CACHE_CONNECTION", None, cast=False)
+    table: str = env("DB_CACHE_TABLE", "caches")
+
+
+@dataclass
+class RedisStoreConfig(Config):
+    driver: str = "redis"
+    connection: str = "cache"
+
+
+@dataclass
+class CacheConfig(Config):
+    default: str = env("CACHE_CONNECTION", "database")
+    prefix: str = env("CACHE_PREFIX", "cache")
+    stores: dict[str, Config] = field(
+        default_factory=lambda: {
+            "array": ArrayStoreConfig(),
+            "file": FileStoreConfig(),
+            "database": DatabaseStoreConfig(),
+            "redis": RedisStoreConfig(),
+        }
+    )
+
+
+__all__ = ["ArrayStoreConfig", "CacheConfig", "DatabaseStoreConfig", "FileStoreConfig", "RedisStoreConfig"]

fastapi_startkit-0.69.0/src/fastapi_startkit/cache/database_store.py

@@ -0,0 +1,94 @@
+import base64
+import math
+import pickle
+import time
+from collections.abc import Callable
+from typing import Any
+
+from sqlalchemy.exc import IntegrityError
+
+from fastapi_startkit.masoniteorm.connections.connection import Connection
+from fastapi_startkit.masoniteorm.models.builder import QueryBuilder
+
+from .lock import Lock
+from .store import MISSING, expired, expires_at
+
+
+def encode(value: Any) -> str:
+    return base64.b64encode(pickle.dumps(value)).decode()
+
+
+class DatabaseStore:
+    def __init__(self, connection: Callable[[], Connection], table: str = "caches"):
+        self.connection = connection
+        self.table = table
+
+    def query(self) -> QueryBuilder[Any]:
+        return self.connection().query().table(self.table)
+
+    async def get(self, key: str) -> Any:
+        builder = self.query().where("key", key).limit(1)
+        row = await builder.connection.select_one(builder.to_qmark(), list(builder.get_bindings()))
+        if row is None:
+            return MISSING
+
+        try:
+            value = pickle.loads(base64.b64decode(row["value"]))
+        except Exception:
+            await self.forget(key)
+            return MISSING
+
+        if expired(row["expiration"]):
+            await self.forget(key)
+            return MISSING
+        return value
+
+    async def put(self, key: str, value: Any, seconds: float | None) -> bool:
+        expiration = expires_at(seconds)
+        record = {"value": encode(value), "expiration": None if expiration is None else math.ceil(expiration)}
+        if await self.query().where("key", key).update(record):
+            return True
+        try:
+            await self.query().insert({"key": key, **record})
+        except IntegrityError:
+            await self.query().where("key", key).update(record)
+        return True
+
+    async def forget(self, key: str) -> bool:
+        return bool(await self.query().where("key", key).delete())
+
+    async def flush(self) -> bool:
+        await self.query().delete()
+        return True
+
+    def lock(self, name: str, seconds: float = 0, owner: str | None = None) -> "DatabaseLock":
+        return DatabaseLock(self, name, seconds, owner)
+
+
+class DatabaseLock(Lock):
+    def __init__(self, store: DatabaseStore, name: str, seconds: float = 0, owner: str | None = None):
+        super().__init__(name, seconds, owner)
+        self.store = store
+        self.key = f"lock:{name}"
+
+    async def acquire(self) -> bool:
+        expiration = expires_at(self.ttl)
+        record = {"value": encode(self.owner), "expiration": None if expiration is None else math.ceil(expiration)}
+        try:
+            await self.store.query().insert({"key": self.key, **record})
+        except IntegrityError:
+            expired_lock = self.store.query().where("key", self.key).where("expiration", "<=", time.time())
+            return bool(await expired_lock.update(record))
+        return True
+
+    async def release(self) -> bool:
+        held = (
+            self.store.query()
+            .where("key", self.key)
+            .where("value", encode(self.owner))
+            .where(lambda query: query.where_null("expiration").or_where("expiration", ">", time.time()))
+        )
+        return bool(await held.delete())
+
+    async def force_release(self) -> None:
+        await self.store.query().where("key", self.key).delete()