tina4-python 3.9.1__tar.gz → 3.10.0__tar.gz

{tina4_python-3.9.1 → tina4_python-3.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.9.1
+Version: 3.10.0
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT

{tina4_python-3.9.1 → tina4_python-3.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.9.1"
+version = "3.10.0"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}

{tina4_python-3.9.1 → tina4_python-3.10.0}/tina4_python/CLAUDE.md

@@ -233,7 +233,7 @@ Tina4 provides a full toolkit. Before writing custom code, check if the framewor
 | GraphQL API | `GraphQL` from `tina4_python.graphql` |
 | SOAP/WSDL services | `WSDL` from `tina4_python.wsdl` |
 | Database migrations | `migrate`, `create_migration` from `tina4_python.migration` |
-| WebSockets | `WebSocketServer` from `tina4_python.websocket` |
+| WebSockets | `WebSocketServer` from `tina4_python.websocket`. Backplane via Redis pub/sub (`TINA4_WS_BACKPLANE`, `TINA4_WS_BACKPLANE_URL`) |
 | SCSS compilation | Drop `.scss` in `src/scss/` — auto-compiled |
 | Static file serving | Put files in `src/public/` — auto-served |
 | Translations / i18n | `I18n` from `tina4_python.i18n` |
@@ -336,7 +336,7 @@ tina4_python/               # Core framework package (v3.0.0)
 ├── migration/              # SQL-file migrations (migrate, create_migration, rollback)
 │   └── runner.py           # Migration runner
 ├── session/                # Pluggable sessions (Session, FileSessionHandler, DatabaseSessionHandler)
-├── websocket/              # RFC 6455 WebSocket server (WebSocketServer, WebSocketConnection)
+├── websocket/              # RFC 6455 WebSocket server (WebSocketServer, WebSocketConnection, backplane)
 ├── graphql/                # Zero-dep GraphQL engine (GraphQL, Schema)
 ├── wsdl/                   # SOAP 1.1 / WSDL server (WSDL, wsdl_operation)
 ├── crud/                   # Auto-CRUD REST endpoint generator (AutoCrud)
@@ -480,7 +480,7 @@ Response.add_header("X-Custom", "value")
 
 ## Sessions
 
-TINA4_TOKEN_EXPIRES_IN is used to set the session time, recommend 15-60 minutes
+TINA4_TOKEN_LIMIT is used to set the session time, default 60 minutes
 
 ### Session Backends
 
@@ -504,6 +504,7 @@ TINA4_SESSION_MONGO_USERNAME=             # optional
 TINA4_SESSION_MONGO_PASSWORD=             # optional
 TINA4_SESSION_MONGO_DB=tina4_sessions     # default database
 TINA4_SESSION_MONGO_COLLECTION=sessions   # default collection
+TINA4_SESSION_SAMESITE=Lax               # SameSite attribute for session cookies (default: Lax)
 ```
 
 ### Authentication & Security
@@ -836,6 +837,9 @@ result = User().select(filter="name = ?", params=["Alice"], limit=10)
 
 # Convert to dict
 user.to_dict()
+
+# NoSQL support: to_mongo() generates MongoDB query documents from the same fluent API
+result.to_mongo()
 ```
 
 ### Available field types
@@ -1515,8 +1519,8 @@ Key `.env` settings:
 ```bash
 # Authentication
 SECRET=your-jwt-secret            # JWT signing (default uses insecure placeholder)
-API_KEY=your-api-key              # Static bearer token for API auth
-TINA4_TOKEN_EXPIRES_IN=60         # Token lifetime in minutes (default: 60)
+TINA4_API_KEY=your-api-key        # Static bearer token for API auth (API_KEY fallback supported)
+TINA4_TOKEN_LIMIT=60              # Token lifetime in minutes (default: 60)
 
 # Database
 DATABASE_URL=sqlite:///app.db     # Connection URL (driver://host:port/database)
@@ -1525,16 +1529,17 @@ DATABASE_PASSWORD=                 # DB password
 
 # Framework
 TINA4_DEBUG=true                  # Enable dev mode (toolbar, live reload, error overlay)
-TINA4_LOG_LEVEL=ALL               # Log verbosity: ALL, DEBUG, INFO, WARNING, ERROR
+TINA4_LOG_LEVEL=ERROR             # Log verbosity: ALL, DEBUG, INFO, WARNING, ERROR (default: ERROR)
 TINA4_LOCALE=en                   # Language for framework messages (en, fr, af, zh, ja, es)
 TINA4_DEFAULT_WEBSERVER=FALSE     # Set to TRUE to use Tina4's built-in webserver instead of ASGI
 HOST_NAME=localhost:7145
 
 # Sessions
 TINA4_SESSION_HANDLER=SessionFileHandler  # SessionFileHandler, SessionRedisHandler, SessionValkeyHandler, SessionMongoHandler
+TINA4_SESSION_SAMESITE=Lax               # SameSite attribute for session cookies (default: Lax)
 
 # Swagger/OpenAPI
-SWAGGER_TITLE=My API              # API title (default: "Tina4 Python API")
+SWAGGER_TITLE=Tina4 API           # API title (default: "Tina4 API")
 SWAGGER_VERSION=1.0.0             # API version
 SWAGGER_DESCRIPTION=              # API description
 SWAGGER_CONTACT_TEAM=             # Contact name
@@ -1763,11 +1768,15 @@ async def dashboard(request, response):
 - **`tina4python generate`**: model, route, migration, middleware scaffolding
 - **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), query caching (`TINA4_DB_CACHE=true`, `cache_stats()`, `cache_clear()`)
 - **Sessions**: 4 backends (file, Redis/Valkey, MongoDB, database)
-- **Queue**: SQLite/RabbitMQ/Kafka/MongoDB backends, configured via env vars
+- **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars
 - **Cache**: memory/Redis/file backends
 - **Messenger**: .env driven SMTP/IMAP
 - **ORM relationships**: `has_many`, `has_one`, `belongs_to` with eager loading (`include=`)
 - **Frond pre-compilation**: 2.8x template render improvement, `Frond.clear_cache()`
+- **QueryBuilder** with NoSQL/MongoDB support (`to_mongo()`)
+- **WebSocket backplane** (Redis pub/sub) for horizontal scaling
+- **SameSite=Lax** default on session cookies (`TINA4_SESSION_SAMESITE`)
+- **`tina4 init`** generates Dockerfile and .dockerignore
 - **Gallery**: 7 interactive examples with Try It deploy at `/__dev/`
 
 

{tina4_python-3.9.1 → tina4_python-3.10.0}/tina4_python/__init__.py

@@ -8,7 +8,7 @@ Tina4 Python v3.0 — Zero-dependency, lightweight web framework.
 
 One import, everything works.
 """
-__version__ = "3.9.1"
+__version__ = "3.9.2"
 
 # ── HTTP Constants ──
 from tina4_python.core.constants import (  # noqa: E402, F401

{tina4_python-3.9.1 → tina4_python-3.10.0}/tina4_python/cli/__init__.py

@@ -141,6 +141,37 @@ def _init(args):
         if not dst_file.exists() and src_file.exists():
             dst_file.write_text(src_file.read_text(encoding="utf-8"), encoding="utf-8")
 
+    # Create root Dockerfile (uv variant) if it doesn't exist
+    root_dockerfile = target / "Dockerfile"
+    if not root_dockerfile.exists():
+        root_dockerfile.write_text(
+            'FROM python:3.13-slim AS build\n'
+            'WORKDIR /app\n'
+            'COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv\n'
+            'COPY pyproject.toml uv.lock* ./\n'
+            'RUN uv sync --frozen --no-dev\n'
+            'COPY . .\n'
+            '\n'
+            'FROM python:3.13-slim\n'
+            'WORKDIR /app\n'
+            'COPY --from=build /app .\n'
+            'COPY --from=build /usr/local/bin/uv /usr/local/bin/uv\n'
+            'ENV PATH="/app/.venv/bin:$PATH"\n'
+            'ENV HOST=0.0.0.0\n'
+            'ENV PORT=7145\n'
+            'EXPOSE 7145\n'
+            'CMD ["python", "app.py"]\n',
+            encoding="utf-8",
+        )
+
+    # Create root .dockerignore if it doesn't exist
+    root_dockerignore = target / ".dockerignore"
+    if not root_dockerignore.exists():
+        root_dockerignore.write_text(
+            ".venv\n__pycache__\n.git\n.claude\n.env\n*.log\ntests\ntmp\n",
+            encoding="utf-8",
+        )
+
     # Auto-detect AI tools and install context
     from tina4_python.ai import detect_ai_names, install_context, install_all
     detected = detect_ai_names(str(target))

{tina4_python-3.9.1 → tina4_python-3.10.0}/tina4_python/core/response.py

@@ -22,6 +22,54 @@ import mimetypes
 from pathlib import Path
 
 
+# ---------------------------------------------------------------------------
+# Global Frond template engine registry
+# ---------------------------------------------------------------------------
+_global_frond = None
+_framework_frond = None
+
+
+def get_frond():
+    """Return the global Frond engine, creating a default if needed."""
+    global _global_frond
+    if _global_frond is None:
+        from tina4_python.frond.engine import Frond
+        _global_frond = Frond("src/templates")
+    return _global_frond
+
+
+def get_framework_frond():
+    """Return the singleton Frond engine for built-in framework templates."""
+    global _framework_frond
+    framework_dir = Path(__file__).resolve().parent.parent / "templates"
+    if _framework_frond is None and framework_dir.is_dir():
+        from tina4_python.frond.engine import Frond
+        _framework_frond = Frond(str(framework_dir))
+    # Sync custom filters/globals from the user engine
+    if _framework_frond is not None:
+        user_engine = get_frond()
+        _framework_frond._filters.update(user_engine._filters)
+        _framework_frond._globals.update(user_engine._globals)
+    return _framework_frond
+
+
+def set_frond(engine):
+    """Register a pre-configured Frond engine for response.render().
+
+    Call this at startup after registering custom filters and globals:
+
+        from tina4_python.frond import Frond
+        from tina4_python.core.response import set_frond
+
+        engine = Frond("src/templates")
+        engine.add_filter("money", my_money_filter)
+        engine.add_global("APP_VERSION", "1.0")
+        set_frond(engine)
+    """
+    global _global_frond
+    _global_frond = engine
+
+
 class Response:
     """HTTP response builder with compression and ETag support."""
 
@@ -175,27 +223,33 @@ class Response:
         return self
 
     def render(self, template: str, data: dict = None) -> "Response":
-        """Render a Frond/Twig template with data."""
-        from tina4_python.frond.engine import Frond
-        from pathlib import Path
-
-        # Search for templates in user dir first, then framework dir
-        template_dirs = []
-        user_dir = Path("src/templates")
-        if user_dir.is_dir():
-            template_dirs.append(str(user_dir))
-        framework_dir = Path(__file__).resolve().parent.parent / "templates"
-        if framework_dir.is_dir():
-            template_dirs.append(str(framework_dir))
-
-        for tdir in template_dirs:
-            if (Path(tdir) / template).exists():
-                try:
-                    frond = Frond(tdir)
-                    html = frond.render(template, data or {})
-                    return self.html(html)
-                except Exception as e:
-                    return self.html(f"<pre>Template error: {e}</pre>", 500)
+        """Render a Frond/Twig template with data.
+
+        Uses the global Frond engine (registered via set_frond()) so that
+        custom filters and globals are available in all templates.
+        Falls back to framework templates if not found in user dir.
+        """
+        engine = get_frond()
+
+        # Try user templates first (the global engine's directory)
+        try:
+            html = engine.render(template, data or {})
+            return self.html(html)
+        except FileNotFoundError:
+            pass
+        except Exception as e:
+            return self.html(f"<pre>Template error: {e}</pre>", 500)
+
+        # Fallback: framework templates (singleton, filters/globals synced)
+        fw_engine = get_framework_frond()
+        if fw_engine is not None:
+            try:
+                html = fw_engine.render(template, data or {})
+                return self.html(html)
+            except FileNotFoundError:
+                pass
+            except Exception as e:
+                return self.html(f"<pre>Template error: {e}</pre>", 500)
 
         return self.html(f"<pre>Template not found: {template}</pre>", 404)
 

{tina4_python-3.9.1 → tina4_python-3.10.0}/tina4_python/core/server.py

@@ -105,7 +105,7 @@ def _render_error_page(status_code: int, path: str, request_id: str, error_messa
 
     Returns rendered HTML string, or None if no template found.
     """
-    from tina4_python.frond.engine import Frond
+    from tina4_python.core.response import get_frond, get_framework_frond
 
     template_name = f"errors/{status_code}.twig"
     data = {
@@ -115,21 +115,17 @@ def _render_error_page(status_code: int, path: str, request_id: str, error_messa
         "status_code": status_code,
     }
 
-    # 1. Try user override
-    user_dir = Path("src/templates")
-    if (user_dir / template_name).exists():
-        try:
-            engine = Frond(str(user_dir))
-            return engine.render(template_name, data)
-        except Exception:
-            pass
+    # 1. Try user override (singleton engine with custom filters/globals)
+    try:
+        return get_frond().render(template_name, data)
+    except (FileNotFoundError, Exception):
+        pass
 
-    # 2. Try framework default
-    framework_dir = Path(__file__).resolve().parent.parent / "templates"
-    if (framework_dir / template_name).exists():
+    # 2. Try framework default (singleton, filters/globals synced)
+    fw_engine = get_framework_frond()
+    if fw_engine is not None:
         try:
-            engine = Frond(str(framework_dir))
-            return engine.render(template_name, data)
+            return fw_engine.render(template_name, data)
         except Exception:
             pass
 
@@ -848,9 +844,8 @@ async def app(scope: dict, receive, send):
             # Try serving a template file (e.g. /hello -> src/templates/hello.twig or hello.html)
             tpl_file = _resolve_template(request.path)
             if tpl_file:
-                from tina4_python.frond import Frond
-                frond = Frond()
-                html = frond.render(tpl_file, {})
+                from tina4_python.core.response import get_frond
+                html = get_frond().render(tpl_file, {})
                 response.html(html)
             elif request.path == "/":
                 response.html(_render_landing_page())
@@ -911,7 +906,8 @@ async def app(scope: dict, receive, send):
             sid = request.session.session_id if hasattr(request.session, 'session_id') else getattr(request.session, 'id', None)
             if sid:
                 ttl = int(os.environ.get("TINA4_SESSION_TTL", "3600"))
-                response.header("set-cookie", f"tina4_session={sid}; Path=/; HttpOnly; SameSite=Lax; Max-Age={ttl}")
+                samesite = os.environ.get("TINA4_SESSION_SAMESITE", "Lax")
+                response.header("set-cookie", f"tina4_session={sid}; Path=/; HttpOnly; SameSite={samesite}; Max-Age={ttl}")
         except Exception:
             pass
 

{tina4_python-3.9.1 → tina4_python-3.10.0}/tina4_python/messenger/__init__.py

@@ -203,9 +203,8 @@ class Messenger:
             **kwargs: Passed to send() (cc, bcc, attachments, etc.)
         """
         try:
-            from tina4_python.frond import Frond
-            engine = Frond()
-            body = engine.render_string(template, data or {})
+            from tina4_python.core.response import get_frond
+            body = get_frond().render_string(template, data or {})
         except ImportError:
             body = template
 

{tina4_python-3.9.1 → tina4_python-3.10.0}/tina4_python/query_builder/__init__.py

@@ -257,6 +257,152 @@ class QueryBuilder:
         """
         return self.count() > 0
 
+    def to_mongo(self) -> dict:
+        """Convert the fluent builder state into a MongoDB-compatible query.
+
+        Returns:
+            A dict with keys: filter, projection, sort, limit, skip.
+            Only non-empty keys are included.
+        """
+        result = {}
+
+        # -- projection --
+        if self._columns != ["*"]:
+            result["projection"] = {col.strip(): 1 for col in self._columns}
+
+        # -- filter --
+        if self._wheres:
+            param_index = 0
+            and_conditions = []
+            or_conditions = []
+
+            for i, (connector, condition) in enumerate(self._wheres):
+                mongo_cond, param_index = self._parse_condition_to_mongo(
+                    condition, param_index
+                )
+                if i == 0 or connector == "AND":
+                    and_conditions.append(mongo_cond)
+                else:
+                    or_conditions.append(mongo_cond)
+
+            if or_conditions:
+                # Merge AND conditions into a single dict, then $or with OR ones
+                and_merged = self._merge_mongo_conditions(and_conditions)
+                all_branches = [and_merged] + or_conditions
+                result["filter"] = {"$or": all_branches}
+            else:
+                result["filter"] = self._merge_mongo_conditions(and_conditions)
+
+        # -- sort --
+        if self._order_by_cols:
+            sort_list = []
+            for expr in self._order_by_cols:
+                parts = expr.strip().split()
+                field = parts[0]
+                direction = -1 if len(parts) > 1 and parts[1].upper() == "DESC" else 1
+                sort_list.append((field, direction))
+            result["sort"] = sort_list
+
+        # -- limit / skip --
+        if self._limit_val is not None:
+            result["limit"] = self._limit_val
+        if self._offset_val is not None:
+            result["skip"] = self._offset_val
+
+        return result
+
+    def _parse_condition_to_mongo(self, condition: str, param_index: int) -> tuple[dict, int]:
+        """Parse a single SQL condition string into a MongoDB filter dict.
+
+        Returns:
+            (mongo_filter_dict, updated_param_index)
+        """
+        import re
+
+        cond = condition.strip()
+
+        # IS NOT NULL
+        match = re.match(r"^(\w+)\s+IS\s+NOT\s+NULL$", cond, re.IGNORECASE)
+        if match:
+            return {match.group(1): {"$exists": True, "$ne": None}}, param_index
+
+        # IS NULL
+        match = re.match(r"^(\w+)\s+IS\s+NULL$", cond, re.IGNORECASE)
+        if match:
+            return {match.group(1): {"$exists": False}}, param_index
+
+        # NOT IN
+        match = re.match(r"^(\w+)\s+NOT\s+IN\s*\(\s*\?\s*\)$", cond, re.IGNORECASE)
+        if match:
+            val = self._params[param_index] if param_index < len(self._params) else []
+            values = val if isinstance(val, list) else [val]
+            return {match.group(1): {"$nin": values}}, param_index + 1
+
+        # IN
+        match = re.match(r"^(\w+)\s+IN\s*\(\s*\?\s*\)$", cond, re.IGNORECASE)
+        if match:
+            val = self._params[param_index] if param_index < len(self._params) else []
+            values = val if isinstance(val, list) else [val]
+            return {match.group(1): {"$in": values}}, param_index + 1
+
+        # LIKE
+        match = re.match(r"^(\w+)\s+LIKE\s+\?$", cond, re.IGNORECASE)
+        if match:
+            val = self._params[param_index] if param_index < len(self._params) else ""
+            # Convert SQL LIKE pattern to regex: % -> .*, _ -> .
+            pattern = str(val).replace("%", ".*").replace("_", ".")
+            return {match.group(1): {"$regex": pattern, "$options": "i"}}, param_index + 1
+
+        # Comparison operators: >=, <=, <>, !=, >, <, =
+        match = re.match(r"^(\w+)\s*(>=|<=|<>|!=|>|<|=)\s*\?$", cond)
+        if match:
+            field = match.group(1)
+            op = match.group(2)
+            val = self._params[param_index] if param_index < len(self._params) else None
+            op_map = {
+                "=": None,
+                "!=": "$ne",
+                "<>": "$ne",
+                ">": "$gt",
+                ">=": "$gte",
+                "<": "$lt",
+                "<=": "$lte",
+            }
+            mongo_op = op_map.get(op)
+            if mongo_op is None:
+                return {field: val}, param_index + 1
+            return {field: {mongo_op: val}}, param_index + 1
+
+        # Fallback: return condition as-is in $where (raw JS expression)
+        return {"$where": cond}, param_index
+
+    @staticmethod
+    def _merge_mongo_conditions(conditions: list[dict]) -> dict:
+        """Merge a list of single-field mongo condition dicts into one dict.
+
+        If the same field appears in multiple conditions, wraps them in $and.
+        """
+        if len(conditions) == 1:
+            return conditions[0]
+
+        merged = {}
+        conflicts = []
+        for cond in conditions:
+            for key, val in cond.items():
+                if key in merged:
+                    conflicts.append(cond)
+                    break
+                else:
+                    merged[key] = val
+            else:
+                continue
+            # If we broke out due to conflict, don't add to merged
+            pass
+
+        if conflicts:
+            return {"$and": conditions}
+        return merged
+
     # -- Private helpers --
 
     def _build_where(self) -> str:

{tina4_python-3.9.1 → tina4_python-3.10.0}/tina4_python/session/__init__.py

@@ -265,6 +265,11 @@ class Session:
             self.unset(flash_key)
             return val
 
+    def cookie_header(self, cookie_name: str = "tina4_session") -> str:
+        """Return a Set-Cookie header value for this session."""
+        samesite = os.environ.get("TINA4_SESSION_SAMESITE", "Lax")
+        return f"{cookie_name}={self._session_id}; Path=/; HttpOnly; SameSite={samesite}; Max-Age={self._ttl}"
+
     def gc(self):
         """Run garbage collection on the backend."""
         self._handler.gc(self._ttl)

tina4_python-3.10.0/tina4_python/websocket/backplane.py

@@ -0,0 +1,121 @@
+"""
+WebSocket Backplane Abstraction for Tina4 Python.
+
+Enables broadcasting WebSocket messages across multiple server instances
+using a shared pub/sub channel (e.g. Redis). Without a backplane configured,
+broadcast() only reaches connections on the local process.
+
+Configuration via environment variables:
+    TINA4_WS_BACKPLANE     — Backend type: "redis", "nats", or "" (default: none)
+    TINA4_WS_BACKPLANE_URL — Connection string (default: redis://localhost:6379)
+
+Usage:
+    backplane = create_backplane()
+    if backplane:
+        backplane.subscribe("chat", lambda msg: relay_to_local(msg))
+        backplane.publish("chat", '{"user": "A", "text": "hello"}')
+"""
+
+import os
+import threading
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class WebSocketBackplane:
+    """Base backplane interface for scaling WebSocket broadcast across instances.
+
+    Subclasses implement publish/subscribe over a shared message bus so that
+    every server instance receives every broadcast, not just the originator.
+    """
+
+    def publish(self, channel: str, message: str) -> None:
+        """Publish a message to all instances listening on *channel*."""
+        raise NotImplementedError
+
+    def subscribe(self, channel: str, callback) -> None:
+        """Subscribe to *channel*. *callback(message: str)* is invoked for
+        each incoming message. Runs in a background thread."""
+        raise NotImplementedError
+
+    def unsubscribe(self, channel: str) -> None:
+        """Stop listening on *channel*."""
+        raise NotImplementedError
+
+    def close(self) -> None:
+        """Tear down connections and background threads."""
+        raise NotImplementedError
+
+
+class RedisBackplane(WebSocketBackplane):
+    """Redis pub/sub backplane.
+
+    Requires the ``redis`` package (``pip install redis``). The import is
+    deferred so the rest of Tina4 works fine without it installed — an error
+    is raised only when this class is actually instantiated.
+    """
+
+    def __init__(self, url: str | None = None):
+        try:
+            import redis
+        except ImportError:
+            raise ImportError(
+                "The 'redis' package is required for RedisBackplane. "
+                "Install it with: pip install redis"
+            )
+
+        self._url = url or os.environ.get(
+            "TINA4_WS_BACKPLANE_URL", "redis://localhost:6379"
+        )
+        self._redis = redis.Redis.from_url(self._url)
+        self._pubsub = self._redis.pubsub()
+        self._threads: dict[str, threading.Thread] = {}
+        self._running = True
+        logger.info("RedisBackplane connected to %s", self._url)
+
+    def publish(self, channel: str, message: str) -> None:
+        self._redis.publish(channel, message)
+
+    def subscribe(self, channel: str, callback) -> None:
+        self._pubsub.subscribe(**{channel: lambda raw: callback(raw["data"].decode() if isinstance(raw["data"], bytes) else raw["data"])})
+        thread = self._pubsub.run_in_thread(sleep_time=0.01, daemon=True)
+        self._threads[channel] = thread
+        logger.info("RedisBackplane subscribed to channel '%s'", channel)
+
+    def unsubscribe(self, channel: str) -> None:
+        self._pubsub.unsubscribe(channel)
+        thread = self._threads.pop(channel, None)
+        if thread:
+            thread.stop()
+        logger.info("RedisBackplane unsubscribed from channel '%s'", channel)
+
+    def close(self) -> None:
+        self._running = False
+        for thread in self._threads.values():
+            thread.stop()
+        self._threads.clear()
+        self._pubsub.close()
+        self._redis.close()
+        logger.info("RedisBackplane closed")
+
+
+def create_backplane(url: str | None = None) -> WebSocketBackplane | None:
+    """Factory that reads TINA4_WS_BACKPLANE and returns the appropriate
+    backplane instance, or *None* if no backplane is configured.
+
+    This keeps backplane usage entirely optional — callers simply check
+    ``if backplane:`` before publishing.
+    """
+    backend = os.environ.get("TINA4_WS_BACKPLANE", "").strip().lower()
+
+    if backend == "redis":
+        return RedisBackplane(url=url)
+    elif backend == "nats":
+        raise NotImplementedError(
+            "NATS backplane is on the roadmap but not yet implemented."
+        )
+    elif backend == "":
+        return None
+    else:
+        raise ValueError(f"Unknown TINA4_WS_BACKPLANE value: '{backend}'")