bingo-framework 0.2.0__py3-none-any.whl

bingo/__init__.py

@@ -0,0 +1,44 @@
+from bingo.application import Application
+from bingo.channels import Channel, Connection
+from bingo.controller import Controller
+from bingo.exceptions import (
+    BingoChannelError,
+    BingoChannelRejected,
+    BingoConventionError,
+    BingoDatabaseError,
+    BingoError,
+    BingoJSONViewError,
+    BingoNotFoundError,
+    BingoRouteError,
+    BingoTaskError,
+    BingoValidationError,
+    BingoViewError,
+)
+from bingo.management import BaseCommand, manage
+from bingo.routing import Router
+from bingo.settings import settings
+from bingo.tasks import QueuedTask, Task
+
+__all__ = [
+    "Application",
+    "BaseCommand",
+    "BingoChannelError",
+    "BingoChannelRejected",
+    "BingoConventionError",
+    "BingoDatabaseError",
+    "BingoError",
+    "BingoJSONViewError",
+    "BingoNotFoundError",
+    "BingoRouteError",
+    "BingoTaskError",
+    "BingoValidationError",
+    "BingoViewError",
+    "Channel",
+    "Connection",
+    "Controller",
+    "QueuedTask",
+    "Router",
+    "Task",
+    "manage",
+    "settings",
+]

bingo/application.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+from urllib.parse import parse_qs
+
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.middleware.sessions import SessionMiddleware
+from starlette.responses import PlainTextResponse, Response
+from starlette.routing import Route, WebSocketRoute
+
+from bingo.channels import ChannelServer, close_channel_brokers
+from bingo.db.database import database
+from bingo.exceptions import BingoError, BingoNotFoundError, BingoValidationError
+from bingo.routing import Router
+from bingo.settings import settings
+from bingo.templates import TemplateEngine
+
+
+@asynccontextmanager
+async def application_lifespan(_application):
+    yield
+
+    from bingo.tasks import close_task_queues
+
+    await close_task_queues()
+    await close_channel_brokers()
+
+
+class MethodOverrideMiddleware:
+    """Let ordinary HTML forms reach canonical PATCH and DELETE routes."""
+
+    def __init__(self, app) -> None:
+        self.app = app
+
+    async def __call__(self, scope, receive, send) -> None:
+        headers = dict(scope.get("headers", []))
+        content_type = headers.get(b"content-type", b"").decode("latin-1")
+        is_form_post = (
+            scope["type"] == "http"
+            and scope["method"] == "POST"
+            and content_type.startswith("application/x-www-form-urlencoded")
+        )
+        if not is_form_post:
+            await self.app(scope, receive, send)
+            return
+
+        body = b""
+        more_body = True
+        while more_body:
+            message = await receive()
+            body += message.get("body", b"")
+            more_body = message.get("more_body", False)
+
+        form = parse_qs(body.decode("utf-8"), keep_blank_values=True)
+        override = form.get("_method", [""])[-1].upper()
+        if override in {"PATCH", "PUT", "DELETE"}:
+            scope = {**scope, "method": override}
+
+        delivered = False
+
+        async def replay_body():
+            nonlocal delivered
+            if delivered:
+                return {"type": "http.request", "body": b"", "more_body": False}
+            delivered = True
+            return {"type": "http.request", "body": body, "more_body": False}
+
+        await self.app(scope, replay_body, send)
+
+
+class Application:
+    def __init__(
+        self,
+        routes: Router | None = None,
+        *,
+        root_path: str | Path | None = None,
+    ) -> None:
+        self.root_path = Path(root_path or Path.cwd()).resolve()
+        self.settings = settings.load(self.root_path)
+        self.router = routes or Router()
+        self.templates = TemplateEngine(self.root_path / "app" / "views")
+
+        if self.settings.DATABASE_URL:
+            database.configure(self.settings.DATABASE_URL)
+
+        middleware = [
+            Middleware(SessionMiddleware, secret_key=self.settings.SECRET_KEY)
+        ]
+        channel_routes = self._channel_routes()
+        starlette = Starlette(
+            debug=self.settings.DEBUG,
+            routes=[*channel_routes, *self.router.starlette_routes(self)],
+            middleware=middleware,
+            lifespan=application_lifespan,
+            exception_handlers={
+                BingoNotFoundError: self._not_found,
+                BingoValidationError: self._validation_error,
+                BingoError: self._bingo_error,
+            },
+        )
+        self.asgi = MethodOverrideMiddleware(starlette)
+
+    def _channel_routes(self):
+        path = self.settings.CHANNEL_PATH
+        is_valid_path = isinstance(path, str) and path.startswith("/")
+        is_valid_path = is_valid_path and not path.startswith("//")
+        is_valid_path = is_valid_path and not path.endswith("/") and path != "/"
+        if not is_valid_path:
+            raise BingoError(
+                "CHANNEL_PATH must start with '/' and must not end with '/'."
+            )
+
+        javascript = Path(__file__).with_name("channels.js").read_text(encoding="utf-8")
+
+        async def client(_request):
+            return Response(javascript, media_type="application/javascript")
+
+        channel_server = ChannelServer(self.root_path)
+        return [
+            Route(f"{path}.js", client, methods=["GET"]),
+            WebSocketRoute(path, channel_server.handle),
+        ]
+
+    async def __call__(self, scope, receive, send) -> None:
+        await self.asgi(scope, receive, send)
+
+    async def _not_found(self, request, error: BingoNotFoundError):
+        return PlainTextResponse(str(error), status_code=404)
+
+    async def _validation_error(self, request, error: BingoValidationError):
+        return PlainTextResponse(str(error), status_code=422)
+
+    async def _bingo_error(self, request, error: BingoError):
+        return PlainTextResponse(str(error), status_code=500)

bingo/channel_backends.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+from bingo.exceptions import BingoChannelError
+
+
+class MemorySubscription:
+    def __init__(
+        self,
+        backend: MemoryChannelBackend,
+        stream: str,
+        queue: asyncio.Queue,
+    ) -> None:
+        self.backend = backend
+        self.stream = stream
+        self.queue = queue
+
+    async def messages(self) -> AsyncIterator[dict[str, Any]]:
+        while True:
+            yield await self.queue.get()
+
+    async def close(self) -> None:
+        subscribers = self.backend.subscribers.get(self.stream, set())
+        subscribers.discard(self.queue)
+        if not subscribers:
+            self.backend.subscribers.pop(self.stream, None)
+
+
+class MemoryChannelBackend:
+    def __init__(self) -> None:
+        self.subscribers: dict[str, set[asyncio.Queue]] = {}
+
+    async def subscribe(self, stream: str) -> MemorySubscription:
+        queue: asyncio.Queue = asyncio.Queue()
+        self.subscribers.setdefault(stream, set()).add(queue)
+        return MemorySubscription(self, stream, queue)
+
+    async def publish(self, stream: str, message: dict[str, Any]) -> None:
+        for queue in self.subscribers.get(stream, set()):
+            queue.put_nowait(message)
+
+    async def close(self) -> None:
+        self.subscribers.clear()
+
+
+class RedisSubscription:
+    def __init__(self, pubsub, stream: str) -> None:
+        self.pubsub = pubsub
+        self.stream = stream
+
+    async def messages(self) -> AsyncIterator[dict[str, Any]]:
+        async for message in self.pubsub.listen():
+            if message["type"] != "message":
+                continue
+            try:
+                yield json.loads(message["data"])
+            except (TypeError, ValueError) as error:
+                raise BingoChannelError(
+                    f"Channel stream {self.stream!r} received invalid JSON."
+                ) from error
+
+    async def close(self) -> None:
+        await self.pubsub.unsubscribe(self.stream)
+        await self.pubsub.aclose()
+
+
+class RedisChannelBackend:
+    def __init__(self, url: str) -> None:
+        from redis.asyncio import Redis
+
+        self.client = Redis.from_url(url, decode_responses=True)
+
+    async def subscribe(self, stream: str) -> RedisSubscription:
+        pubsub = self.client.pubsub()
+        await pubsub.subscribe(stream)
+        return RedisSubscription(pubsub, stream)
+
+    async def publish(self, stream: str, message: dict[str, Any]) -> None:
+        await self.client.publish(stream, json.dumps(message, allow_nan=False))
+
+    async def close(self) -> None:
+        await self.client.aclose()
+
+
+class PostgresSubscription:
+    def __init__(self, connection, channel: str, stream: str) -> None:
+        self.connection = connection
+        self.channel = channel
+        self.stream = stream
+
+    async def messages(self) -> AsyncIterator[dict[str, Any]]:
+        async for notification in self.connection.notifies():
+            try:
+                yield json.loads(notification.payload)
+            except (TypeError, ValueError) as error:
+                raise BingoChannelError(
+                    f"Channel stream {self.stream!r} received invalid JSON."
+                ) from error
+
+    async def close(self) -> None:
+        await self.connection.close()
+
+
+class PostgresChannelBackend:
+    def __init__(self, url: str) -> None:
+        self.url = url
+        self.publisher = None
+        self.publisher_lock = asyncio.Lock()
+
+    async def subscribe(self, stream: str) -> PostgresSubscription:
+        from psycopg import AsyncConnection, sql
+
+        connection = await AsyncConnection.connect(self.url, autocommit=True)
+        channel = _postgres_channel(stream)
+        statement = sql.SQL("LISTEN {}").format(sql.Identifier(channel))
+        await connection.execute(statement)
+        return PostgresSubscription(connection, channel, stream)
+
+    async def publish(self, stream: str, message: dict[str, Any]) -> None:
+        from psycopg import AsyncConnection
+
+        payload = json.dumps(message, allow_nan=False)
+        if len(payload.encode("utf-8")) >= 8_000:
+            raise BingoChannelError(
+                "PostgreSQL channel broadcasts must be smaller than 8,000 bytes."
+            )
+
+        async with self.publisher_lock:
+            if self.publisher is None or self.publisher.closed:
+                self.publisher = await AsyncConnection.connect(
+                    self.url,
+                    autocommit=True,
+                )
+            channel = _postgres_channel(stream)
+            await self.publisher.execute(
+                "SELECT pg_notify(%s, %s)",
+                (channel, payload),
+            )
+
+    async def close(self) -> None:
+        if self.publisher is not None and not self.publisher.closed:
+            await self.publisher.close()
+
+
+def channel_backend(url: str):
+    scheme = url.split(":", 1)[0].lower()
+    if scheme == "memory":
+        return MemoryChannelBackend()
+    if scheme in {"redis", "rediss"}:
+        return RedisChannelBackend(url)
+    if scheme in {"postgres", "postgresql"}:
+        return PostgresChannelBackend(url)
+    raise BingoChannelError("CHANNEL_URL supports memory, Redis, and PostgreSQL URLs.")
+
+
+def _postgres_channel(stream: str) -> str:
+    digest = hashlib.sha256(stream.encode("utf-8")).hexdigest()[:48]
+    return f"bingo_{digest}"

bingo/channels.js

@@ -0,0 +1,145 @@
+(function (global) {
+  "use strict";
+
+  class Subscription {
+    constructor(consumer, identifier, channel, params, callbacks) {
+      this.consumer = consumer;
+      this.identifier = identifier;
+      this.channel = channel;
+      this.params = params;
+      Object.assign(this, callbacks || {});
+    }
+
+    send(data) {
+      this.consumer.send({
+        command: "message",
+        identifier: this.identifier,
+        data: data,
+      });
+    }
+
+    unsubscribe() {
+      this.consumer.unsubscribe(this.identifier);
+    }
+  }
+
+  class ChannelConsumer {
+    constructor(path) {
+      this.path = path || "/channels";
+      this.socket = null;
+      this.subscriptions = new Map();
+      this.nextIdentifier = 1;
+      this.reconnectDelay = 500;
+      this.reconnectTimer = null;
+    }
+
+    subscribe(channel, params, callbacks) {
+      const identifier = String(this.nextIdentifier++);
+      const subscription = new Subscription(
+        this,
+        identifier,
+        channel,
+        params || {},
+        callbacks,
+      );
+      this.subscriptions.set(identifier, subscription);
+      this.connect();
+      if (this.socket && this.socket.readyState === WebSocket.OPEN) {
+        this.sendSubscription(subscription);
+      }
+      return subscription;
+    }
+
+    connect() {
+      const isConnecting = this.socket && (
+        this.socket.readyState === WebSocket.OPEN ||
+        this.socket.readyState === WebSocket.CONNECTING
+      );
+      if (isConnecting) return;
+
+      const protocol = global.location.protocol === "https:" ? "wss:" : "ws:";
+      const url = `${protocol}//${global.location.host}${this.path}`;
+      this.socket = new WebSocket(url);
+      this.socket.addEventListener("open", () => this.opened());
+      this.socket.addEventListener("message", (event) => this.received(event));
+      this.socket.addEventListener("close", () => this.closed());
+    }
+
+    opened() {
+      this.reconnectDelay = 500;
+      for (const subscription of this.subscriptions.values()) {
+        this.sendSubscription(subscription);
+      }
+    }
+
+    received(event) {
+      let message;
+      try {
+        message = JSON.parse(event.data);
+      } catch (_error) {
+        return;
+      }
+
+      const subscription = this.subscriptions.get(message.identifier);
+      if (!subscription) return;
+
+      if (message.type === "subscribed" && subscription.connected) {
+        subscription.connected();
+      } else if (message.type === "message" && subscription.received) {
+        subscription.received(message.event, message.data);
+      } else if (message.type === "rejected") {
+        this.subscriptions.delete(message.identifier);
+        if (subscription.rejected) subscription.rejected(message.error);
+        if (this.subscriptions.size === 0 && this.socket) this.socket.close();
+      } else if (message.type === "error" && subscription.errored) {
+        subscription.errored(message.error);
+      }
+    }
+
+    closed() {
+      this.socket = null;
+      for (const subscription of this.subscriptions.values()) {
+        if (subscription.disconnected) subscription.disconnected();
+      }
+      if (this.subscriptions.size === 0) return;
+
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = setTimeout(() => this.connect(), this.reconnectDelay);
+      this.reconnectDelay = Math.min(this.reconnectDelay * 2, 10000);
+    }
+
+    unsubscribe(identifier) {
+      if (!this.subscriptions.has(identifier)) return;
+      this.send({ command: "unsubscribe", identifier: identifier });
+      this.subscriptions.delete(identifier);
+      if (this.subscriptions.size === 0 && this.socket) {
+        this.socket.close();
+      }
+    }
+
+    sendSubscription(subscription) {
+      this.send({
+        command: "subscribe",
+        identifier: subscription.identifier,
+        channel: subscription.channel,
+        params: subscription.params,
+      });
+    }
+
+    send(message) {
+      if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+        throw new Error("The Bingo channel connection is not open.");
+      }
+      this.socket.send(JSON.stringify(message));
+    }
+  }
+
+  const Bingo = global.Bingo || {};
+  const script = global.document.currentScript;
+  const defaultPath = script
+    ? new URL(script.src, global.location.href).pathname.replace(/\.js$/, "")
+    : "/channels";
+  Bingo.channels = new ChannelConsumer(defaultPath);
+  Bingo.ChannelConsumer = ChannelConsumer;
+  global.Bingo = Bingo;
+})(window);