tachyon-api 0.5.5__py3-none-any.whl → 0.5.9__py3-none-any.whl

tachyon_api/cache.py

@@ -0,0 +1,270 @@
+"""
+Cache utilities: decorator with TTL and pluggable backends.
+
+This module provides:
+- BaseCacheBackend protocol and an in-memory implementation
+- CacheConfig dataclass and helpers to set global/app config
+- cache decorator usable on any sync/async function (including routes)
+
+Design notes:
+- Key builder defaults to a stable representation of function + args/kwargs
+- Unless predicate allows opt-out per-call
+- TTL can be provided per-decorator or falls back to global default
+"""
+
+from __future__ import annotations
+
+import time
+import asyncio
+import hashlib
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, Callable, Optional, Tuple
+
+
+class BaseCacheBackend:
+    """Minimal cache backend interface."""
+
+    def get(self, key: str) -> Any:  # pragma: no cover - interface
+        raise NotImplementedError
+
+    def set(
+        self, key: str, value: Any, ttl: Optional[float] = None
+    ) -> None:  # pragma: no cover - interface
+        raise NotImplementedError
+
+    def delete(self, key: str) -> None:  # pragma: no cover - interface
+        raise NotImplementedError
+
+    def clear(self) -> None:  # pragma: no cover - interface
+        raise NotImplementedError
+
+
+class InMemoryCacheBackend(BaseCacheBackend):
+    """Simple in-memory cache with TTL using wall-clock time."""
+
+    def __init__(self) -> None:
+        self._store: dict[str, Tuple[float | None, Any]] = {}
+
+    def _is_expired(self, expires_at: float | None) -> bool:
+        return expires_at is not None and time.time() >= expires_at
+
+    def get(self, key: str) -> Any:
+        item = self._store.get(key)
+        if not item:
+            return None
+        expires_at, value = item
+        if self._is_expired(expires_at):
+            # Lazy expiration
+            try:
+                del self._store[key]
+            except KeyError:
+                pass
+            return None
+        return value
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        expires_at = time.time() + ttl if ttl and ttl > 0 else None
+        self._store[key] = (expires_at, value)
+
+    def delete(self, key: str) -> None:
+        self._store.pop(key, None)
+
+    def clear(self) -> None:
+        self._store.clear()
+
+
+@dataclass
+class CacheConfig:
+    backend: BaseCacheBackend
+    default_ttl: float = 60.0
+    key_builder: Optional[Callable[[Callable, tuple, dict], str]] = None
+    enabled: bool = True
+
+
+_cache_config: Optional[CacheConfig] = None
+
+
+def _default_key_builder(func: Callable, args: tuple, kwargs: dict) -> str:
+    parts = [getattr(func, "__module__", ""), getattr(func, "__qualname__", ""), "|"]
+    # Stable kwargs order
+    items = [repr(a) for a in args] + [
+        f"{k}={repr(v)}" for k, v in sorted(kwargs.items())
+    ]
+    raw_key = ":".join(parts + items)
+    return hashlib.sha256(raw_key.encode("utf-8")).hexdigest()
+
+
+def create_cache_config(
+    backend: Optional[BaseCacheBackend] = None,
+    default_ttl: float = 60.0,
+    key_builder: Optional[Callable[[Callable, tuple, dict], str]] = None,
+    enabled: bool = True,
+) -> CacheConfig:
+    """Create and set the global cache configuration.
+
+    Returns the created CacheConfig and sets it as the active global config.
+    """
+    global _cache_config
+    cfg = CacheConfig(
+        backend=backend or InMemoryCacheBackend(),
+        default_ttl=default_ttl,
+        key_builder=key_builder,
+        enabled=enabled,
+    )
+    _cache_config = cfg
+    return cfg
+
+
+def set_cache_config(config: CacheConfig) -> None:
+    """Set the global cache configuration object."""
+    global _cache_config
+    _cache_config = config
+
+
+def get_cache_config() -> CacheConfig:
+    """Get the current cache configuration, creating a default one if missing."""
+    global _cache_config
+    if _cache_config is None:
+        _cache_config = create_cache_config()
+    return _cache_config
+
+
+def cache(
+    TTL: Optional[float] = None,
+    *,
+    key_builder: Optional[Callable[[Callable, tuple, dict], str]] = None,
+    unless: Optional[Callable[[tuple, dict], bool]] = None,
+    backend: Optional[BaseCacheBackend] = None,
+):
+    """Cache decorator with TTL and pluggable backend.
+
+    Args:
+        TTL: Time-to-live in seconds for this decorator instance. Falls back to config.default_ttl.
+        key_builder: Optional custom function to build cache keys.
+        unless: Predicate receiving (args, kwargs). If returns True, skip cache for that call.
+        backend: Optional backend override for this decorator.
+    """
+
+    def decorator(func: Callable):
+        cfg = get_cache_config()
+        be = backend or cfg.backend
+        ttl_value = cfg.default_ttl if TTL is None else TTL
+        kb = (
+            key_builder
+            or cfg.key_builder
+            or (lambda f, a, kw: _default_key_builder(f, a, kw))
+        )
+
+        if asyncio.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                if not cfg.enabled or (unless and unless(args, kwargs)):
+                    return await func(*args, **kwargs)
+                key = kb(func, args, kwargs)
+                cached = be.get(key)
+                if cached is not None:
+                    return cached
+                result = await func(*args, **kwargs)
+                try:
+                    be.set(key, result, ttl_value)
+                except Exception:
+                    # Backend errors should not break the app
+                    pass
+                return result
+
+            return async_wrapper
+        else:
+
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                if not cfg.enabled or (unless and unless(args, kwargs)):
+                    return func(*args, **kwargs)
+                key = kb(func, args, kwargs)
+                cached = be.get(key)
+                if cached is not None:
+                    return cached
+                result = func(*args, **kwargs)
+                try:
+                    be.set(key, result, ttl_value)
+                except Exception:
+                    pass
+                return result
+
+            return wrapper
+
+    return decorator
+
+
+class RedisCacheBackend(BaseCacheBackend):
+    """Adapter backend for Redis-like clients.
+
+    Expects a client with .get(key) -> bytes|str|None and .set(key, value, ex=ttl_seconds).
+    The stored values should be JSON-serializable or pickled externally by the user.
+    """
+
+    def __init__(self, client) -> None:
+        self.client = client
+
+    def get(self, key: str) -> Any:
+        value = self.client.get(key)
+        # Many clients return bytes; decode if possible
+        if isinstance(value, bytes):
+            try:
+                return value.decode("utf-8")
+            except Exception:
+                return value
+        return value
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        # Use ex (expire seconds) if available
+        kwargs = {}
+        if ttl and ttl > 0:
+            kwargs["ex"] = int(ttl)
+        # Best effort set
+        self.client.set(key, value, **kwargs)
+
+    def delete(self, key: str) -> None:
+        try:
+            self.client.delete(key)
+        except Exception:
+            pass
+
+    def clear(self) -> None:
+        # Not standardized; no-op by default
+        pass
+
+
+class MemcachedCacheBackend(BaseCacheBackend):
+    """Adapter backend for Memcached-like clients.
+
+    Expects a client with .get(key) and .set(key, value, expire=ttl_seconds).
+    """
+
+    def __init__(self, client) -> None:
+        self.client = client
+
+    def get(self, key: str) -> Any:
+        return self.client.get(key)
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        expire = int(ttl) if ttl and ttl > 0 else 0
+        try:
+            # pymemcache: set(key, value, expire=...)
+            self.client.set(key, value, expire=expire)
+        except TypeError:
+            # python-binary-memcached: set(key, value, time=...)
+            self.client.set(key, value, time=expire)
+
+    def delete(self, key: str) -> None:
+        try:
+            self.client.delete(key)
+        except Exception:
+            pass
+
+    def clear(self) -> None:
+        try:
+            self.client.flush_all()
+        except Exception:
+            pass

tachyon_api/middlewares/__init__.py

@@ -2,4 +2,3 @@ from .cors import CORSMiddleware
 from .logger import LoggerMiddleware
 
 __all__ = ["CORSMiddleware", "LoggerMiddleware"]
-

tachyon_api/middlewares/cors.py

@@ -70,7 +70,8 @@ class CORSMiddleware:
         method = scope.get("method", "").upper()
         is_preflight = (
             method == "OPTIONS"
-            and self._get_header(req_headers, "access-control-request-method") is not None
+            and self._get_header(req_headers, "access-control-request-method")
+            is not None
         )
 
         # Build common CORS headers
@@ -89,7 +90,9 @@ class CORSMiddleware:
 
             # Credentials
             if self.allow_credentials:
-                self._append_header(headers_out, "access-control-allow-credentials", "true")
+                self._append_header(
+                    headers_out, "access-control-allow-credentials", "true"
+                )
 
             return headers_out
 
@@ -98,28 +101,42 @@ class CORSMiddleware:
             resp_headers = build_cors_headers()
             if resp_headers:
                 # Methods
-                allow_methods = ", ".join(self.allow_methods) if "*" not in self.allow_methods else "*"
-                self._append_header(resp_headers, "access-control-allow-methods", allow_methods)
+                allow_methods = (
+                    ", ".join(self.allow_methods)
+                    if "*" not in self.allow_methods
+                    else "*"
+                )
+                self._append_header(
+                    resp_headers, "access-control-allow-methods", allow_methods
+                )
 
                 # Requested headers or wildcard
-                req_acrh = self._get_header(req_headers, "access-control-request-headers")
+                req_acrh = self._get_header(
+                    req_headers, "access-control-request-headers"
+                )
                 if "*" in self.allow_headers:
                     allow_headers = req_acrh or "*"
                 else:
                     allow_headers = ", ".join(self.allow_headers)
                 if allow_headers:
-                    self._append_header(resp_headers, "access-control-allow-headers", allow_headers)
+                    self._append_header(
+                        resp_headers, "access-control-allow-headers", allow_headers
+                    )
 
                 # Max-Age
                 if self.max_age:
-                    self._append_header(resp_headers, "access-control-max-age", str(self.max_age))
+                    self._append_header(
+                        resp_headers, "access-control-max-age", str(self.max_age)
+                    )
 
                 # Respond directly
-                await send({
-                    "type": "http.response.start",
-                    "status": 200,
-                    "headers": resp_headers,
-                })
+                await send(
+                    {
+                        "type": "http.response.start",
+                        "status": 200,
+                        "headers": resp_headers,
+                    }
+                )
                 await send({"type": "http.response.body", "body": b""})
                 return
             # If origin not allowed, continue the chain (app will respond accordingly)

tachyon_api/middlewares/logger.py

@@ -79,7 +79,9 @@ class LoggerMiddleware:
             receive_to_use = receive_passthrough
             if body_chunks and not more_body:
                 try:
-                    request_body_preview = b"".join(body_chunks)[:2048].decode("utf-8", "replace")
+                    request_body_preview = b"".join(body_chunks)[:2048].decode(
+                        "utf-8", "replace"
+                    )
                 except Exception:
                     request_body_preview = "<non-text body>"
         else:
@@ -113,7 +115,9 @@ class LoggerMiddleware:
         finally:
             duration = time.time() - start
             status = status_code_holder["status"] or 0
-            self.logger.log(self.level, f"<-- {method} {path} {status} ({duration:.4f}s)")
+            self.logger.log(
+                self.level, f"<-- {method} {path} {status} ({duration:.4f}s)"
+            )
             if self.include_headers and response_headers_holder:
                 res_headers = _normalized_headers(response_headers_holder)
                 self.logger.log(self.level, f"    res headers: {res_headers}")

tachyon_api/openapi.py

@@ -1,5 +1,9 @@
-from typing import Dict, Any, Optional, List, Type
+from typing import Dict, Any, Optional, List, Type, get_origin, get_args
 from dataclasses import dataclass, field
+import datetime
+import uuid
+import typing
+import json
 
 from .models import Struct
 
@@ -7,30 +11,114 @@ from .models import Struct
 TYPE_MAP = {int: "integer", str: "string", bool: "boolean", float: "number"}
 
 
-def _generate_schema_for_struct(struct_class: Type[Struct]) -> Dict[str, Any]:
+def _schema_for_python_type(
+    py_type: Type,
+    components: Dict[str, Dict[str, Any]],
+    visited: set[Type],
+) -> Dict[str, Any]:
+    """Return OpenAPI schema for a Python type, adding components for Structs if needed."""
+    origin = get_origin(py_type)
+    args = get_args(py_type)
+
+    # Optional[T] (Union[T, None])
+    if origin is typing.Union and args:
+        non_none = [a for a in args if a is not type(None)]  # noqa: E721
+        if len(non_none) == 1:
+            inner = non_none[0]
+            schema = _schema_for_python_type(inner, components, visited)
+            schema["nullable"] = True
+            return schema
+
+    # List[T]
+    if origin in (list, List):
+        item = args[0] if args else str
+        item_schema = _schema_for_python_type(item, components, visited)
+        return {"type": "array", "items": item_schema}
+
+    # Struct subclass
+    if isinstance(py_type, type) and issubclass(py_type, Struct):
+        name = py_type.__name__
+        if py_type not in visited:
+            visited.add(py_type)
+            components[name] = _generate_struct_schema(py_type, components, visited)
+        return {"$ref": f"#/components/schemas/{name}"}
+
+    # Special formats
+    if py_type is uuid.UUID:
+        return {"type": "string", "format": "uuid"}
+    if py_type is datetime.datetime:
+        return {"type": "string", "format": "date-time"}
+    if py_type is datetime.date:
+        return {"type": "string", "format": "date"}
+
+    # Scalars
+    return {"type": TYPE_MAP.get(py_type, "string")}
+
+
+def _unwrap_optional(py_type: Type) -> tuple[Type, bool]:
+    origin = get_origin(py_type)
+    args = get_args(py_type)
+    if origin is typing.Union and args:
+        non_none = [a for a in args if a is not type(None)]  # noqa: E721
+        if len(non_none) == 1:
+            return non_none[0], True
+    return py_type, False
+
+
+def _generate_struct_schema(
+    struct_class: Type[Struct],
+    components: Dict[str, Dict[str, Any]],
+    visited: set[Type],
+) -> Dict[str, Any]:
+    """
+    Generate a JSON Schema dictionary for a msgspec Struct, populating components for nested Structs.
     """
-    Generate a JSON Schema dictionary from a tachyon_api.models.Struct.
+    properties: Dict[str, Any] = {}
+    required: List[str] = []
 
-    Args:
-        struct_class: The Struct class to generate schema for
+    annotations = getattr(struct_class, "__annotations__", {})
+    for field_name in getattr(struct_class, "__struct_fields__", annotations.keys()):
+        field_type = annotations.get(field_name, str)
+        base_type, is_opt = _unwrap_optional(field_type)
 
-    Returns:
-        Dictionary containing the OpenAPI schema for the struct
+        # Build property schema
+        prop_schema = _schema_for_python_type(base_type, components, visited)
+        if is_opt:
+            prop_schema["nullable"] = True
+
+        properties[field_name] = prop_schema
+
+        # Determine required: mark non-Optional fields as required
+        if not is_opt:
+            required.append(field_name)
+
+    schema: Dict[str, Any] = {"type": "object", "properties": properties}
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def build_components_for_struct(
+    struct_class: Type[Struct],
+) -> Dict[str, Dict[str, Any]]:
     """
-    properties = {}
-    required = []
-
-    # Use msgspec's introspection tools
-    for field_name in struct_class.__struct_fields__:
-        field_type = struct_class.__annotations__.get(field_name)
-        properties[field_name] = {
-            "type": TYPE_MAP.get(field_type, "string"),
-            "title": field_name.replace("_", " ").title(),
-        }
-        # For now, assume all fields are required (can be enhanced later)
-        required.append(field_name)
+    Build components schemas for the given Struct and all nested Structs.
+
+    Returns a dict mapping component name to schema, including the top-level struct.
+    """
+    components: Dict[str, Dict[str, Any]] = {}
+    visited: set[Type] = set()
+    name = struct_class.__name__
+    components[name] = _generate_struct_schema(struct_class, components, visited)
+    return components
+
 
-    return {"type": "object", "properties": properties, "required": required}
+def _generate_schema_for_struct(struct_class: Type[Struct]) -> Dict[str, Any]:
+    """
+    Backward-compatible API: generate only the schema for the provided Struct (no nested components registration).
+    """
+    comps = build_components_for_struct(struct_class)
+    return comps[struct_class.__name__]
 
 
 @dataclass
@@ -175,13 +263,8 @@ class OpenAPIGenerator:
         """Generate HTML for Swagger UI"""
         swagger_ui_parameters = self.config.swagger_ui_parameters or {}
 
-        # Convert parameters to JSON string, handling Python booleans correctly
-        params_json = (
-            str(swagger_ui_parameters)
-            .replace("'", '"')
-            .replace("True", "true")
-            .replace("False", "false")
-        )
+        # Serialize parameters to JSON safely
+        params_json = json.dumps(swagger_ui_parameters)
 
         html = f"""<!DOCTYPE html>
 <html>
@@ -268,7 +351,6 @@ class OpenAPIGenerator:
         """
         if self._openapi_schema is None:
             self._openapi_schema = self.config.to_openapi_dict()
-
         if path not in self._openapi_schema["paths"]:
             self._openapi_schema["paths"][path] = {}
 

tachyon_api/responses.py

@@ -6,12 +6,23 @@ with Starlette responses.
 """
 
 from starlette.responses import JSONResponse, HTMLResponse  # noqa
+from .models import encode_json
+
+
+class TachyonJSONResponse(JSONResponse):
+    """High-performance JSON response using orjson for serialization."""
+
+    media_type = "application/json"
+
+    def render(self, content) -> bytes:  # type: ignore[override]
+        # Use centralized encoder to support Struct, UUID, date, datetime, etc.
+        return encode_json(content)
 
 
 # Simple helper functions for common response patterns
 def success_response(data=None, message="Success", status_code=200):
     """Create a success response with consistent structure"""
-    return JSONResponse(
+    return TachyonJSONResponse(
         {"success": True, "message": message, "data": data}, status_code=status_code
     )
 
@@ -22,7 +33,7 @@ def error_response(error, status_code=400, code=None):
     if code:
         response_data["code"] = code
 
-    return JSONResponse(response_data, status_code=status_code)
+    return TachyonJSONResponse(response_data, status_code=status_code)
 
 
 def not_found_response(error="Resource not found"):
@@ -41,7 +52,39 @@ def validation_error_response(error="Validation failed", errors=None):
     if errors:
         response_data["errors"] = errors
 
-    return JSONResponse(response_data, status_code=422)
+    return TachyonJSONResponse(response_data, status_code=422)
+
+
+def response_validation_error_response(error="Response validation error"):
+    """Create a 500 response validation error response"""
+    # Normalize message with prefix and include 'detail' for backward compatibility
+    msg = str(error)
+    if not msg.lower().startswith("response validation error"):
+        msg = f"Response validation error: {msg}"
+    return TachyonJSONResponse(
+        {
+            "success": False,
+            "error": msg,
+            "detail": msg,
+            "code": "RESPONSE_VALIDATION_ERROR",
+        },
+        status_code=500,
+    )
+
+
+def internal_server_error_response():
+    """Create a 500 internal server error response for unhandled exceptions.
+
+    This intentionally avoids leaking internal exception details in the payload.
+    """
+    return TachyonJSONResponse(
+        {
+            "success": False,
+            "error": "Internal Server Error",
+            "code": "INTERNAL_SERVER_ERROR",
+        },
+        status_code=500,
+    )
 
 
 # Re-export Starlette responses for convenience

tachyon_api/utils/__init__.py

@@ -0,0 +1,14 @@
+"""
+Tachyon API - Utilities Module
+
+This package contains utility functions and classes that provide common functionality
+across the Tachyon framework, including type conversion, validation, and helper functions.
+"""
+
+from .type_utils import TypeUtils
+from .type_converter import TypeConverter
+
+__all__ = [
+    "TypeUtils",
+    "TypeConverter",
+]