tina4-python 3.13.39__tar.gz → 3.13.41__tar.gz

{tina4_python-3.13.39 → tina4_python-3.13.41}/PKG-INFO

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

{tina4_python-3.13.39 → tina4_python-3.13.41}/pyproject.toml

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

{tina4_python-3.13.39 → tina4_python-3.13.41}/tina4_python/CLAUDE.md

@@ -1145,9 +1145,14 @@ for job in queue.consume():
 ```python
 queue = Queue(topic="tasks", max_retries=3)
 
+# Reservation / visibility timeout (seconds): a popped job is reserved this long;
+# if the consumer dies before complete()/fail() the next pop() reclaims it
+# (at-least-once delivery). Default 300; env TINA4_QUEUE_VISIBILITY_TIMEOUT; <= 0 disables.
+queue = Queue(topic="tasks", visibility_timeout=300)
+
 # Check queue size
 queue.size()                    # pending jobs
-queue.size("reserved")          # currently processing
+queue.size("reserved")          # currently reserved (in-flight) jobs
 
 # Retry failed jobs (under max_retries limit)
 queue.retry_failed()
@@ -1159,6 +1164,14 @@ dead = queue.dead_letters()
 queue.purge("completed")
 ```
 
+**At-least-once delivery (file + MongoDB backends).** A popped job is held as a
+reservation for `visibility_timeout` seconds. If the consumer crashes, OOMs, or
+is evicted before calling `job.complete()` / `job.fail()`, the next `pop()`
+reclaims the abandoned reservation: it increments `attempts` and re-enqueues the
+job, or dead-letters it once it has hit `max_retries`. A dead consumer therefore
+never strands a job. RabbitMQ and Kafka delegate redelivery to the broker (the
+framework timeout does not apply there).
+
 ### When to use queues
 - Sending emails or SMS
 - Generating PDFs/reports
@@ -1633,14 +1646,23 @@ TINA4_SESSION_BACKEND=SessionFileHandler  # SessionFileHandler, SessionRedisHand
 TINA4_SESSION_SAMESITE=Lax               # SameSite attribute for session cookies (default: Lax)
 
 # Swagger/OpenAPI
-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
-SWAGGER_CONTACT_URL=              # Contact URL
-SWAGGER_CONTACT_EMAIL=            # Contact email
-SWAGGER_DEV_URL=http://localhost:7145  # Dev server URL for Swagger
-```
+TINA4_SWAGGER_ENABLED=            # on/off for /swagger UI + /swagger/openapi.json. Explicit true/false wins; unset falls back to TINA4_DEBUG. Set false to DISABLE swagger in any environment; true to expose it in production
+TINA4_SWAGGER_TITLE=Tina4 API     # API title (default: "Tina4 API")
+TINA4_SWAGGER_VERSION=1.0.0       # API version
+TINA4_SWAGGER_DESCRIPTION=        # API description
+TINA4_SWAGGER_CONTACT_TEAM=       # Contact name (legacy SWAGGER_CONTACT_TEAM still read as fallback)
+TINA4_SWAGGER_CONTACT_URL=        # Contact URL  (legacy SWAGGER_CONTACT_URL  still read as fallback)
+TINA4_SWAGGER_CONTACT_EMAIL=      # Contact email
+TINA4_SWAGGER_LICENSE=            # SPDX license name (e.g. MIT) for info.license
+TINA4_SWAGGER_SERVERS=            # comma-separated server URLs for the OpenAPI servers[] block; falls back to SWAGGER_DEV_URL
+TINA4_SWAGGER_UI_CDN=             # base URL for the Swagger UI assets (default jsdelivr); point at a self-hosted mirror for air-gapped use
+SWAGGER_DEV_URL=http://localhost:7145  # single dev-server URL (used when TINA4_SWAGGER_SERVERS is unset)
+```
+
+The spec is OpenAPI 3.0.3. ORM models registered via AutoCrud become reusable
+`components.schemas` referenced by `$ref`, and secured routes emit a `bearerAuth`
+security requirement. Set `TINA4_SWAGGER_ENABLED=false` to turn the endpoints off
+anywhere (the production on/off switch, wired for real in 3.13.40).
 
 ### Debug levels
 - `ALL` / `DEBUG` — most verbose; every level on the console

{tina4_python-3.13.39 → tina4_python-3.13.41}/tina4_python/__init__.py

@@ -8,7 +8,7 @@ Tina4 Python v3.0 — Zero-dependency, lightweight web framework.
 
 One import, everything works.
 """
-__version__ = "3.13.39"
+__version__ = "3.13.41"
 
 # ── Route decorators ──
 from tina4_python.core.router import (  # noqa: E402, F401

{tina4_python-3.13.39 → tina4_python-3.13.41}/tina4_python/auth/__init__.py

@@ -78,7 +78,11 @@ def _is_production() -> bool:
 _BLANK_SECRET_WARNING = (
     "Auth: TINA4_SECRET is not set — JWT signing is insecure. "
     "Set TINA4_SECRET to a random value (e.g. `openssl rand -hex 32`) "
-    "in your environment or .env before serving traffic."
+    "in your environment or .env before serving traffic. "
+    "For LOCAL DEV, set TINA4_DEBUG=true and a per-machine secret is generated "
+    "automatically into .env.local (gitignored). Seeing this warning means the "
+    "run was NOT detected as dev — typically a container or CI without "
+    "TINA4_DEBUG set, or TINA4_ENV=production."
 )
 
 

{tina4_python-3.13.39 → tina4_python-3.13.41}/tina4_python/core/request.py

@@ -71,7 +71,7 @@ class Request:
 
     __slots__ = (
         "method", "path", "url", "query_string", "params", "query", "headers",
-        "body", "raw_body", "cookies", "files", "ip",
+        "body", "raw_body", "cookies", "files", "ip", "remote_ip",
         "content_type", "session", "_route_params",
     )
 
@@ -88,6 +88,7 @@ class Request:
         self.cookies: dict = {}
         self.files: dict = {}
         self.ip: str = ""
+        self.remote_ip: str = ""        # Raw socket peer (never X-Forwarded-For) — for trust decisions
         self.content_type: str = ""
         self.session = None             # Set by session middleware
         self._route_params: dict = {}   # Dynamic route params ({id}, etc.)
@@ -107,6 +108,10 @@ class Request:
 
         req.content_type = req.headers.get("content-type", "")
         req.ip = _extract_ip(scope, req.headers)
+        # Raw socket peer address — NEVER honours X-Forwarded-For, so it can
+        # be trusted for loopback/remote authorisation (e.g. the MCP guard).
+        _client = scope.get("client")
+        req.remote_ip = _client[0] if _client else ""
 
         # Reconstruct the full absolute URL — scheme://host[:port]/path[?query].
         # Honours x-forwarded-proto and x-forwarded-host so apps behind a proxy

{tina4_python-3.13.39 → tina4_python-3.13.41}/tina4_python/core/server.py

@@ -1174,14 +1174,28 @@ async def _handle_dev_admin(request: Request, response: Response) -> Response:
 
 
 def _handle_swagger(request: Request, response: Response) -> Response | None:
-    """Serve /swagger UI and /swagger/openapi.json. Returns Response or None."""
+    """Serve /swagger UI and /swagger/openapi.json. Returns Response or None.
+
+    Self-gated on swagger.is_enabled() (TINA4_SWAGGER_ENABLED, else TINA4_DEBUG)
+    so the documented production on/off switch is actually honoured — before
+    v3.13.40 the dispatch gated only on TINA4_DEBUG and this env var was dead.
+    """
+    from tina4_python.swagger import is_enabled as _swagger_enabled
+    if not _swagger_enabled():
+        return None
     if request.path in ("/swagger", "/swagger/"):
+        # The UI assets load from a CDN by default (keeps the framework
+        # zero-dependency — no vendored ~1.4MB swagger-ui-dist). Air-gapped
+        # deployments point TINA4_SWAGGER_UI_CDN at a self-hosted mirror.
+        _cdn = os.environ.get(
+            "TINA4_SWAGGER_UI_CDN", "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5"
+        ).rstrip("/")
         swagger_html = (
             '<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8">'
             '<title>API Documentation</title>'
-            '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css">'
+            f'<link rel="stylesheet" href="{_cdn}/swagger-ui.css">'
             '</head><body><div id="swagger-ui"></div>'
-            '<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>'
+            f'<script src="{_cdn}/swagger-ui-bundle.js"></script>'
             '<script>SwaggerUIBundle({ url: "/swagger/openapi.json", dom_id: "#swagger-ui" });</script>'
             '</body></html>'
         )
@@ -1715,8 +1729,11 @@ async def handle(request: Request) -> Response:
     ):
         return await _handle_dev_admin(request, response)
 
-    # Swagger
-    if _is_dev and request.method == "GET":
+    # Swagger — _handle_swagger self-gates on swagger.is_enabled()
+    # (TINA4_SWAGGER_ENABLED, else TINA4_DEBUG), so we call it on any GET:
+    # this honours an explicit prod-enable AND an explicit dev-disable, both
+    # of which the old `_is_dev`-only gate silently ignored.
+    if request.method == "GET":
         swagger_resp = _handle_swagger(request, response)
         if swagger_resp is not None:
             return swagger_resp
@@ -2227,8 +2244,13 @@ def _check_legacy_env_vars() -> None:
         new = _LEGACY_ENV_VARS[old]
         msg.append(f"    {old:<28}  →  {new}")
     msg.extend(["",
-                "Run `tina4 env --migrate` to rewrite your .env automatically,",
-                "or rename manually. See https://tina4.com/release/3.12.0",
+                "Note: these may come from a .env file loaded by dotenv, not just",
+                "the runtime environment — check your image / build context (a .env",
+                "baked into a Docker image is loaded at startup) as well as k8s/CI env.",
+                "",
+                "FIX: run `tina4 env --migrate` to rewrite your .env automatically",
+                "(it renames every legacy name to its TINA4_ form in place).",
+                "Or rename manually. See https://tina4.com/release/3.12.0",
                 "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
                 "─" * 72, ""])
     print("\n".join(msg), file=sys.stderr)

{tina4_python-3.13.39 → tina4_python-3.13.41}/tina4_python/crud/__init__.py

@@ -132,6 +132,8 @@ class AutoCrud:
         list_handler.__qualname__ = f"autocrud_list_{table}"
         list_handler._swagger_summary = f"List all {pretty_name}"
         list_handler._swagger_tags = [table]
+        list_handler._swagger_model = model_class
+        list_handler._swagger_model_list = True
         Router.add("GET", base_path, list_handler)
         generated.append({"method": "GET", "path": base_path, "table": table})
 
@@ -147,6 +149,7 @@ class AutoCrud:
         get_handler.__qualname__ = f"autocrud_get_{table}"
         get_handler._swagger_summary = f"Get {pretty_name} by ID"
         get_handler._swagger_tags = [table]
+        get_handler._swagger_model = model_class
         Router.add("GET", f"{base_path}/{{id}}", get_handler)
         generated.append({"method": "GET", "path": f"{base_path}/{{id}}", "table": table})
 
@@ -169,6 +172,7 @@ class AutoCrud:
         create_handler._swagger_summary = f"Create {pretty_name}"
         create_handler._swagger_tags = [table]
         create_handler._swagger_example = example_body
+        create_handler._swagger_model = model_class
         Router.add("POST", base_path, create_handler)
         generated.append({"method": "POST", "path": base_path, "table": table})
 
@@ -201,6 +205,7 @@ class AutoCrud:
         update_handler._swagger_summary = f"Update {pretty_name}"
         update_handler._swagger_tags = [table]
         update_handler._swagger_example = example_body
+        update_handler._swagger_model = model_class
         Router.add("PUT", f"{base_path}/{{id}}", update_handler)
         generated.append({"method": "PUT", "path": f"{base_path}/{{id}}", "table": table})
 

{tina4_python-3.13.39 → tina4_python-3.13.41}/tina4_python/dev_admin/__init__.py

@@ -2864,12 +2864,42 @@ async def _api_git_status(request, response):
 # the same registry, so tools registered via the `@mcp_tool` decorator
 # show up on both immediately.
 
+def _mcp_token_ok(request) -> bool:
+    """Timing-safe check of a remote MCP caller's token against
+    TINA4_MCP_TOKEN (falling back to TINA4_API_KEY). Accepts an
+    `Authorization: Bearer <token>` header, `X-MCP-Token`, or `X-Api-Key`."""
+    import os as _os, hmac as _hmac
+    expected = _os.environ.get("TINA4_MCP_TOKEN") or _os.environ.get("TINA4_API_KEY") or ""
+    if not expected:
+        return False
+    headers = getattr(request, "headers", None) or {}
+    auth = headers.get("authorization", "") or ""
+    provided = auth[7:].strip() if auth[:7].lower() == "bearer " else ""
+    if not provided:
+        provided = headers.get("x-mcp-token", "") or headers.get("x-api-key", "")
+    if not provided:
+        return False
+    return _hmac.compare_digest(str(provided), str(expected))
+
+
+def _mcp_request_allowed(request) -> bool:
+    """Per-request MCP authorisation gate applied by EVERY MCP surface
+    (JSON-RPC, SSE, and the REST shim). Loopback callers are allowed; a
+    non-loopback (remote) caller needs TINA4_MCP_REMOTE + a valid token.
+    Uses the raw socket peer (request.remote_ip), never X-Forwarded-For."""
+    from tina4_python.mcp import is_request_allowed
+    remote_ip = getattr(request, "remote_ip", "") or ""
+    return is_request_allowed(remote_ip, _mcp_token_ok(request))
+
+
 async def _api_mcp_tools(request, response):
     """GET — return the MCP tool registry as a plain JSON list.
 
     Shape matches what dev-admin's `listMcpTools()` expects:
         {"tools": [{"name": "...", "description": "...", "schema": {...}}, ...]}
     """
+    if not _mcp_request_allowed(request):
+        return response({"tools": [], "error": "MCP forbidden"}, 404)
     try:
         from tina4_python.mcp import _get_default_server
         server = _get_default_server()
@@ -2950,8 +2980,8 @@ async def _api_mcp_rpc(request, response):
     (no id) yield an empty 204.
     """
     import json as _json
-    from tina4_python.mcp import _get_default_server, is_enabled
-    if not is_enabled():
+    from tina4_python.mcp import _get_default_server
+    if not _mcp_request_allowed(request):
         return response({"error": "MCP disabled"}, 404)
     server = _get_default_server()
     body = request.body
@@ -2966,8 +2996,7 @@ async def _api_mcp_sse(request, response):
     """GET — SSE handshake. Emits the `endpoint` event telling the client
     where to POST JSON-RPC messages, per the MCP HTTP+SSE transport.
     """
-    from tina4_python.mcp import is_enabled
-    if not is_enabled():
+    if not _mcp_request_allowed(request):
         return response({"error": "MCP disabled"}, 404)
     base = request.path.rsplit("/sse", 1)[0]
     sse = f"event: endpoint\ndata: {base}/message\n\n"