tina4-python 3.1.3__tar.gz → 3.3.0__tar.gz

{tina4_python-3.1.3 → tina4_python-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.1.3
+Version: 3.3.0
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT
@@ -115,7 +115,7 @@ Every feature is built from scratch -- no pip install, no node_modules, no third
 | **Database** | SQLite, PostgreSQL, MySQL, MSSQL, Firebird -- unified adapter interface, query caching (TINA4_DB_CACHE=true for 4x speedup) |
 | **Auth** | Zero-dep JWT (HS256), sessions (file/Redis/Valkey/MongoDB/database), password hashing, form tokens |
 | **API** | Swagger/OpenAPI auto-generation, GraphQL with ORM auto-schema and GraphiQL IDE, WSDL/SOAP with auto WSDL |
-| **Background** | Queue (SQLite/RabbitMQ/Kafka) with priority, delayed jobs, retry, batch processing |
+| **Background** | Queue (SQLite/RabbitMQ/Kafka/MongoDB) with priority, delayed jobs, retry, batch processing |
 | **Real-time** | Native asyncio WebSocket (RFC 6455), per-path routing, connection manager |
 | **Frontend** | tina4-css (~24 KB), frond.js helper, SCSS compiler, live reload, CSS hot-reload |
 | **DX** | Dev admin dashboard (11 tabs), error overlay, request inspector, AI tool integration, Carbonah green benchmarks |

{tina4_python-3.1.3 → tina4_python-3.3.0}/README.md

@@ -83,7 +83,7 @@ Every feature is built from scratch -- no pip install, no node_modules, no third
 | **Database** | SQLite, PostgreSQL, MySQL, MSSQL, Firebird -- unified adapter interface, query caching (TINA4_DB_CACHE=true for 4x speedup) |
 | **Auth** | Zero-dep JWT (HS256), sessions (file/Redis/Valkey/MongoDB/database), password hashing, form tokens |
 | **API** | Swagger/OpenAPI auto-generation, GraphQL with ORM auto-schema and GraphiQL IDE, WSDL/SOAP with auto WSDL |
-| **Background** | Queue (SQLite/RabbitMQ/Kafka) with priority, delayed jobs, retry, batch processing |
+| **Background** | Queue (SQLite/RabbitMQ/Kafka/MongoDB) with priority, delayed jobs, retry, batch processing |
 | **Real-time** | Native asyncio WebSocket (RFC 6455), per-path routing, connection manager |
 | **Frontend** | tina4-css (~24 KB), frond.js helper, SCSS compiler, live reload, CSS hot-reload |
 | **DX** | Dev admin dashboard (11 tabs), error overlay, request inspector, AI tool integration, Carbonah green benchmarks |

{tina4_python-3.1.3 → tina4_python-3.3.0}/pyproject.toml

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

{tina4_python-3.1.3 → tina4_python-3.3.0}/tina4_python/CLAUDE.md

@@ -154,7 +154,7 @@ Never use raw `requests` or `urllib` directly. Use the built-in `Api` class —
 
 ### 7. Use Queues for Long-Running Work
 
-Route handlers must respond fast. Any operation that takes more than a second (sending emails, generating reports, calling slow external APIs, processing files) must be pushed to a Queue and processed by a Consumer.
+Route handlers must respond fast. Any operation that takes more than a second (sending emails, generating reports, calling slow external APIs, processing files) must be pushed to a Queue and consumed via `queue.consume()`.
 
 **Bad — blocking the request:**
 ```python
@@ -170,8 +170,8 @@ async def generate_report(request, response):
 ```python
 @post("/api/reports")
 async def generate_report(request, response):
-    producer = Producer(Queue(db, topic="reports"))
-    producer.push({"user_id": request.body["user_id"], "type": "monthly"})
+    queue = Queue(topic="reports")
+    queue.push({"user_id": request.body["user_id"], "type": "monthly"})
     return response({"status": "queued"})
 ```
 
@@ -219,7 +219,7 @@ Tina4 provides a full toolkit. Before writing custom code, check if the framewor
 
 | Need | Use this — don't build your own |
 |------|--------------------------------|
-| Background jobs / async work | `Queue`, `Producer`, `Consumer` from `tina4_python.queue` |
+| Background jobs / async work | `Queue` from `tina4_python.queue` (use `queue.push()`, `queue.consume()`) |
 | HTTP calls to external APIs | `Api` from `tina4_python.api` |
 | JWT tokens & auth | `Auth` from `tina4_python.auth` (create_token, validate_token, get_payload) |
 | Password hashing | `Auth.hash_password()` / `Auth.check_password()` from `tina4_python.auth` |
@@ -254,8 +254,8 @@ task_queue = queue.Queue()  # Don't do this!
 
 **Good — use Tina4's Queue:**
 ```python
-from tina4_python.queue import Queue, Producer
-Producer(Queue(db, topic="tasks")).push({"action": "send_email"})
+from tina4_python.queue import Queue
+Queue(topic="tasks").push({"action": "send_email"})
 ```
 
 ### 11. Key tina4_python Gotchas
@@ -331,7 +331,7 @@ tina4_python/               # Core framework package (v3.0.0)
 ├── frond/                  # Template engine (Frond — Jinja2/Twig-compatible)
 │   └── engine.py           # Frond class (render, add_filter, add_global, add_test)
 ├── api/                    # HTTP client (Api — urllib, zero deps)
-├── queue/                  # Database-backed job queue (Queue, Producer, Consumer)
+├── queue/                  # Database-backed job queue (Queue, Job)
 ├── swagger/                # OpenAPI 3.0.3 generator (Swagger, description, tags, example)
 ├── migration/              # SQL-file migrations (migrate, create_migration, rollback)
 │   └── runner.py           # Migration runner
@@ -1017,48 +1017,43 @@ async def admin_dashboard(request, response):
 
 Supports: litequeue (default/SQLite, zero-config), RabbitMQ, Kafka, MongoDB.
 
-### Producer — enqueue work from a route
+### Producing — enqueue work from a route
 
 ```python
-from tina4_python.queue import Queue, Producer
+from tina4_python.queue import Queue
 
 @post("/api/reports/generate")
 async def request_report(request, response):
-    queue = Queue(db, topic="reports")
-    producer = Producer(queue)
-    producer.push({
+    queue = Queue(topic="reports")
+    queue.push({
         "user_id": request.body["user_id"],
         "report_type": "monthly",
     })
     return response({"status": "queued"})
 ```
 
-### Consumer — process work in a background worker
+### Consuming — process work in a background worker
 
 ```python
 # worker.py (run separately: python worker.py)
-from tina4_python.queue import Queue, Consumer
+from tina4_python.queue import Queue
 from tina4_python.database import Database
 
 db = Database("sqlite:///app.db")
+queue = Queue(topic="reports")
 
-def handle_report(job):
+for job in queue.consume("reports"):
     data = job.data
     report = generate_report(data["user_id"], data["report_type"])
     send_email(data["user_id"], report)
-
-queue = Queue(db, topic="reports")
-consumer = Consumer(queue, callback=handle_report)
-consumer.run_forever()
+    job.complete()
 ```
 
 ### Poll once for available jobs
 
 ```python
-queue = Queue(db, topic="logs")
-consumer = Consumer(queue)
-jobs = consumer.poll()  # Returns list of Job objects
-for job in jobs:
+queue = Queue(topic="logs")
+for job in queue.consume():
     process(job.data)
     job.complete()
 ```
@@ -1066,7 +1061,7 @@ for job in jobs:
 ### Queue management
 
 ```python
-queue = Queue(db, topic="tasks", max_retries=3)
+queue = Queue(topic="tasks", max_retries=3)
 
 # Check queue size
 queue.size()                    # pending jobs
@@ -1681,7 +1676,7 @@ async def upload(request, response):
     file_list = uploaded if isinstance(uploaded, list) else [uploaded]
     for f in file_list:
         content = base64.b64decode(f["content"])
-        with open(os.path.join("src/public/uploads", f["file_name"]), "wb") as fh:
+        with open(os.path.join("src/public/uploads", f["filename"]), "wb") as fh:
             fh.write(content)
     return response({"uploaded": len(file_list)})
 ```
@@ -1715,8 +1710,8 @@ async def charge(request, response):
 # In route — fast response
 @post("/api/invite")
 async def invite(request, response):
-    producer = Producer(Queue(db, topic="emails"))
-    producer.push({
+    queue = Queue(topic="emails")
+    queue.push({
         "to": request.body["email"],
         "template": "invite",
         "data": {"name": request.body["name"]}
@@ -1724,13 +1719,12 @@ async def invite(request, response):
     return response({"sent": True})
 
 # In worker — separate process
-def send_email(message):
-    email = message.data
+queue = Queue(topic="emails")
+for job in queue.consume("emails"):
+    email = job.data
     html = Template.render(f"emails/{email['template']}.twig", email["data"])
     # ... send via SMTP
-
-queue = Queue(topic="emails", callback=send_email)
-Consumer(queue).run_forever()
+    job.complete()
 ```
 
 ### Full page with template inheritance
@@ -1770,7 +1764,7 @@ 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 backends, configured via env vars
+- **Queue**: SQLite/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=`)

{tina4_python-3.1.3 → tina4_python-3.3.0}/tina4_python/__init__.py

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

{tina4_python-3.1.3 → tina4_python-3.3.0}/tina4_python/ai/__init__.py

@@ -169,7 +169,7 @@ frontend/         — Frontend framework source (builds to public/)
 | WebSocket | websocket | `from tina4_python.websocket import WebSocketServer` |
 | SOAP/WSDL | wsdl | `from tina4_python.wsdl import WSDL, wsdl_operation` |
 | Email (SMTP+IMAP) | messenger | `from tina4_python.messenger import Messenger` |
-| Background Queue | queue | `from tina4_python.queue import Queue, Producer, Consumer` |
+| Background Queue | queue | `from tina4_python.queue import Queue` |
 | SCSS Compilation | scss | Auto-compiled from src/scss/ |
 | Migrations | migration | `tina4python migrate` CLI command |
 | Seeder | seeder | `from tina4_python.seeder import FakeData, seed_table` |

{tina4_python-3.1.3 → tina4_python-3.3.0}/tina4_python/auth/__init__.py

@@ -6,6 +6,10 @@ No PyJWT, no cryptography package.
     from tina4_python.auth import Auth
 
     auth = Auth(secret="my-secret")
+    token = auth.get_token({"user_id": 1, "role": "admin"})
+    payload = auth.valid_token(token)
+
+    # Legacy aliases also work:
     token = auth.create_token({"user_id": 1, "role": "admin"})
     payload = auth.validate_token(token)
 
@@ -34,7 +38,7 @@ class Auth:
 
     # ── JWT ────────────────────────────────────────────────────────
 
-    def create_token(self, payload: dict, expiry_minutes: int = None) -> str:
+    def get_token(self, payload: dict, expiry_minutes: int = None) -> str:
         """Create a signed JWT token.
 
         Returns: header.payload.signature
@@ -53,7 +57,7 @@ class Auth:
 
         return f"{h}.{p}.{signature}"
 
-    def validate_token(self, token: str) -> dict | None:
+    def valid_token(self, token: str) -> dict | None:
         """Validate a JWT and return the payload. None if invalid/expired."""
         try:
             parts = token.split(".")
@@ -86,12 +90,12 @@ class Auth:
 
     def refresh_token(self, token: str, expiry_minutes: int = None) -> str | None:
         """Validate and issue a fresh token with the same claims."""
-        payload = self.validate_token(token)
+        payload = self.valid_token(token)
         if payload is None:
             return None
         payload.pop("iat", None)
         payload.pop("exp", None)
-        return self.create_token(payload, expiry_minutes)
+        return self.get_token(payload, expiry_minutes)
 
     def _sign(self, message: str) -> str:
         sig = hmac.new(
@@ -99,6 +103,11 @@ class Auth:
         ).digest()
         return _b64url_encode(sig)
 
+    # ── Legacy aliases ─────────────────────────────────────────────
+
+    create_token = get_token
+    validate_token = valid_token
+
     # ── Password Hashing ──────────────────────────────────────────
 
     @staticmethod
@@ -149,7 +158,7 @@ class Auth:
 
         if auth_header.startswith("Bearer "):
             token = auth_header[7:]
-            payload = self.validate_token(token)
+            payload = self.valid_token(token)
             if payload:
                 return payload
             if self.validate_api_key(token):

{tina4_python-3.1.3 → tina4_python-3.3.0}/tina4_python/cli/__init__.py

@@ -7,6 +7,7 @@ CLI commands for development workflow.
     tina4python migrate           # Run pending migrations
     tina4python migrate:create    # Create a migration file
     tina4python migrate:rollback  # Rollback last batch
+    tina4python migrate:status    # Show completed and pending migrations
     tina4python seed              # Run seeders
     tina4python routes            # List registered routes
     tina4python test              # Run tests
@@ -34,6 +35,7 @@ def main():
         "migrate": _migrate,
         "migrate:create": _migrate_create,
         "migrate:rollback": _migrate_rollback,
+        "migrate:status": _migrate_status,
         "seed": _seed,
         "routes": _routes,
         "test": _test,
@@ -63,6 +65,7 @@ Commands:
   migrate               Run pending database migrations
   migrate:create <desc> Create a new migration file
   migrate:rollback      Rollback last migration batch
+  migrate:status        Show completed and pending migrations
   seed                  Run database seeders
   routes                List all registered routes
   test                  Run test suite
@@ -233,7 +236,8 @@ def _migrate_rollback(args):
 
     db_url = os.environ.get("DATABASE_URL", "sqlite:///data/app.db")
     db = Database(db_url)
-    rolled = rollback(db, "migrations")
+    mig_dir = args[0] if args else "migrations"
+    rolled = rollback(db, mig_dir)
     if rolled:
         for f in rolled:
             print(f"  Rolled back: {f}")
@@ -243,6 +247,38 @@ def _migrate_rollback(args):
     db.close()
 
 
+def _migrate_status(args):
+    """Show completed and pending migrations."""
+    _load_env()
+    from tina4_python.database import Database
+    from tina4_python.migration import status
+
+    db_url = os.environ.get("DATABASE_URL", "sqlite:///data/app.db")
+    db = Database(db_url)
+    mig_dir = args[0] if args else "migrations"
+    result = status(db, mig_dir)
+
+    completed = result["completed"]
+    pending = result["pending"]
+
+    if completed:
+        print("\nCompleted migrations:")
+        for m in completed:
+            print(f"  [batch {m['batch']}] {m['migration_id']}  ({m['executed_at']})")
+    else:
+        print("\nNo completed migrations.")
+
+    if pending:
+        print("\nPending migrations:")
+        for m in pending:
+            print(f"  {m['migration_id']}  ({m['description']})")
+    else:
+        print("\nNo pending migrations.")
+
+    print(f"\nTotal: {len(completed)} completed, {len(pending)} pending.")
+    db.close()
+
+
 def _seed(args):
     """Run seeders from src/seeds/."""
     _load_env()

{tina4_python-3.1.3 → tina4_python-3.3.0}/tina4_python/core/__init__.py

@@ -14,7 +14,7 @@ from tina4_python.core.request import Request
 from tina4_python.core.response import Response
 from tina4_python.core.router import (
     Router, get, post, put, patch, delete, any_method,
-    noauth, secured, middleware, cached,
+    noauth, secured, middleware, cached, websocket,
 )
 from tina4_python.core.middleware import CorsMiddleware, RateLimiter
 from tina4_python.core.cache import Cache
@@ -23,7 +23,7 @@ from tina4_python.core.server import run, resolve_config
 
 __all__ = [
     "Request", "Response", "Router",
-    "get", "post", "put", "patch", "delete", "any_method",
+    "get", "post", "put", "patch", "delete", "any_method", "websocket",
     "noauth", "secured", "middleware", "cached",
     "CorsMiddleware", "RateLimiter",
     "Cache",

{tina4_python-3.1.3 → tina4_python-3.3.0}/tina4_python/core/request.py

@@ -65,9 +65,14 @@ class Request:
 
         return req
 
+    def merge_route_params(self):
+        """Merge route params into params dict (route params take priority)."""
+        if self._route_params:
+            self.params.update(self._route_params)
+
     def param(self, key: str, default=None):
-        """Get a route parameter (from URL path)."""
-        return self._route_params.get(key, default)
+        """Get a route parameter (from URL path). Alias for params[key]."""
+        return self.params.get(key, self._route_params.get(key, default))
 
 
 def _extract_ip(scope: dict, headers: dict) -> str:
@@ -134,9 +139,10 @@ def _parse_multipart(body: bytes, content_type: str) -> dict:
         header_section = part[:header_end].decode(errors="replace")
         content = part[header_end + 4:].rstrip(b"\r\n")
 
-        # Parse Content-Disposition
+        # Parse Content-Disposition and Content-Type
         name = None
         filename = None
+        file_type = "application/octet-stream"
         for line in header_section.split("\r\n"):
             if "Content-Disposition" in line:
                 for token in line.split(";"):
@@ -145,15 +151,17 @@ def _parse_multipart(body: bytes, content_type: str) -> dict:
                         name = token[5:].strip('"')
                     elif token.startswith("filename="):
                         filename = token[9:].strip('"')
+            elif "Content-Type" in line:
+                file_type = line.split(":", 1)[1].strip()
 
         if not name:
             continue
 
         if filename:
-            import base64
             result[name] = {
-                "file_name": filename,
-                "content": base64.b64encode(content).decode(),
+                "filename": filename,
+                "type": file_type,
+                "content": bytes(content),
                 "size": len(content),
             }
         else:

{tina4_python-3.1.3 → tina4_python-3.3.0}/tina4_python/core/router.py

@@ -23,12 +23,146 @@ from tina4_python.debug import Log
 # Global route registry
 _routes: list[dict] = []
 
+# Global WebSocket route registry
+_ws_routes: list[dict] = []
+
+
+class RouteRef:
+    """Thin wrapper around a registered route dict, enabling chained modifiers.
+
+    Usage::
+
+        Router.get("/api/data", handler).secure().cache()
+    """
+
+    __slots__ = ("_route",)
+
+    def __init__(self, route: dict):
+        self._route = route
+
+    def secure(self):
+        """Mark this route as requiring bearer-token authentication."""
+        self._route["auth_required"] = True
+        return self
+
+    def cache(self, max_age: int | None = None):
+        """Mark this route as cacheable.
+
+        Args:
+            max_age: Optional TTL override in seconds.
+        """
+        self._route["cached"] = True
+        if max_age is not None:
+            self._route["cache_max_age"] = max_age
+        return self
+
 
 class Router:
     """Route registry and matcher."""
 
+    # ── Group state (used by Router.group) ────────────────────────
+    _group_prefix: str = ""
+    _group_middleware: list = []
+
+    @classmethod
+    def group(cls, prefix: str, callback, middleware=None):
+        """Register routes with a shared prefix and optional middleware.
+
+        Saves/restores static prefix and middleware state around the
+        callback so that nested groups concatenate correctly.
+
+        Usage::
+
+            Router.group("/api", lambda: [
+                Router.get("/users", handler),
+                Router.post("/users", handler),
+            ], middleware=[auth_check])
+        """
+        prev_prefix = cls._group_prefix
+        prev_middleware = list(cls._group_middleware)
+
+        cls._group_prefix = prev_prefix + prefix.rstrip("/")
+        cls._group_middleware = prev_middleware + (middleware or [])
+
+        try:
+            callback()
+        finally:
+            cls._group_prefix = prev_prefix
+            cls._group_middleware = prev_middleware
+
+    @classmethod
+    def websocket(cls, path: str, handler) -> None:
+        """Register a WebSocket route (imperative, non-decorator style).
+
+        The handler signature is::
+
+            async def handler(connection, event, data):
+                ...
+
+        Where:
+        - ``connection`` is a :class:`WebSocketConnection`
+        - ``event`` is ``"open"``, ``"message"``, or ``"close"``
+        - ``data`` is the message payload (str for message, None for open/close)
+        """
+        pattern, param_names = _compile_pattern(path)
+        route = {
+            "path": path,
+            "pattern": pattern,
+            "param_names": param_names,
+            "handler": handler,
+        }
+        _ws_routes.append(route)
+        Log.debug(f"WebSocket route registered: {path}")
+
+    @staticmethod
+    def match_ws(path: str) -> tuple[dict | None, dict]:
+        """Find a WebSocket route matching the given path. Returns (route, params)."""
+        for route in _ws_routes:
+            m = route["pattern"].match(path)
+            if m:
+                params = {}
+                for i, name in enumerate(route["param_names"]):
+                    params[name] = m.group(i + 1)
+                return route, params
+        return None, {}
+
     @staticmethod
-    def add(method: str, path: str, handler, **options):
+    def all_ws() -> list[dict]:
+        """Return all registered WebSocket routes."""
+        return _ws_routes
+
+    @classmethod
+    def get(cls, path: str, handler, **options) -> "RouteRef":
+        """Register a GET route (imperative, non-decorator style)."""
+        return cls.add("GET", path, handler, **options)
+
+    @classmethod
+    def post(cls, path: str, handler, **options) -> "RouteRef":
+        """Register a POST route (imperative, non-decorator style)."""
+        return cls.add("POST", path, handler, **options)
+
+    @classmethod
+    def put(cls, path: str, handler, **options) -> "RouteRef":
+        """Register a PUT route (imperative, non-decorator style)."""
+        return cls.add("PUT", path, handler, **options)
+
+    @classmethod
+    def patch(cls, path: str, handler, **options) -> "RouteRef":
+        """Register a PATCH route (imperative, non-decorator style)."""
+        return cls.add("PATCH", path, handler, **options)
+
+    @classmethod
+    def delete(cls, path: str, handler, **options) -> "RouteRef":
+        """Register a DELETE route (imperative, non-decorator style)."""
+        return cls.add("DELETE", path, handler, **options)
+
+    @classmethod
+    def any(cls, path: str, handler, **options) -> "RouteRef":
+        """Register a route for any HTTP method (imperative, non-decorator style)."""
+        return cls.add("ANY", path, handler, **options)
+
+    @classmethod
+    def add(cls, method: str, path: str, handler, **options) -> "RouteRef":
         """Register a route handler.
 
         Auth defaults:
@@ -36,7 +170,21 @@ class Router:
         - POST/PUT/PATCH/DELETE require auth by default
         - Use @noauth() to make a write route public
         - Use @secured() to protect a GET route
+
+        Returns a :class:`RouteRef` so callers can chain ``.secure()`` /
+        ``.cache()``::
+
+            Router.get("/api/data", handler).secure().cache()
         """
+        # Apply group prefix
+        if cls._group_prefix:
+            path = cls._group_prefix + path
+
+        # Merge group middleware with route-level middleware
+        if cls._group_middleware:
+            route_mw = options.get("middleware", [])
+            options["middleware"] = list(cls._group_middleware) + list(route_mw)
+
         pattern, param_names = _compile_pattern(path)
 
         # Auth default: GET=public, writes=secured
@@ -50,7 +198,7 @@ class Router:
         else:
             auth_required = m not in ("GET", "ANY")
 
-        _routes.append({
+        route = {
             "method": m,
             "path": path,
             "pattern": pattern,
@@ -60,8 +208,10 @@ class Router:
             "auth_required": auth_required,
             "cached": options.get("cached", False),
             "cache_max_age": options.get("cache_max_age", 60),
-        })
+        }
+        _routes.append(route)
         Log.debug(f"Route registered: {m} {path} (auth={'required' if auth_required else 'public'})")
+        return RouteRef(route)
 
     @staticmethod
     def match(method: str, path: str) -> tuple[dict | None, dict]:
@@ -87,6 +237,7 @@ class Router:
     def clear():
         """Clear all routes (for testing)."""
         _routes.clear()
+        _ws_routes.clear()
 
 
 def _compile_pattern(path: str) -> tuple[re.Pattern, list[str]]:
@@ -173,6 +324,27 @@ def any_method(path: str, **options):
         return fn
     return decorator
 
+# Alias — @any() is the standard name across all Tina4 frameworks
+any = any_method
+
+
+def websocket(path: str):
+    """Register a WebSocket route.
+
+    Usage::
+
+        @websocket("/ws/chat/{room}")
+        async def chat(connection, event, data):
+            if event == "message":
+                await connection.broadcast(data)
+            elif event == "open":
+                await connection.send(f"Welcome to {connection.params['room']}")
+    """
+    def decorator(fn):
+        Router.websocket(path, fn)
+        return fn
+    return decorator
+
 
 # ── Auth Decorators ────────────────────────────────────────────