tachyon-api 0.9.0__py3-none-any.whl

tachyon_api/middlewares/core.py

@@ -0,0 +1,40 @@
+# Internal core helpers for Tachyon middleware integration
+from starlette.middleware import Middleware
+
+
+def apply_middleware_to_router(router_app, middleware_class, **options):
+    """
+    Insert an ASGI middleware into Starlette's stack and rebuild the stack.
+
+    Args:
+        router_app: internal Starlette instance (app._router)
+        middleware_class: ASGI middleware class
+        **options: kwargs passed to the middleware constructor
+    """
+    router_app.user_middleware.insert(0, Middleware(middleware_class, **options))
+    router_app.middleware_stack = router_app.build_middleware_stack()
+
+
+def create_decorated_middleware_class(middleware_func, middleware_type: str = "http"):
+    """
+    Create an ASGI middleware class from a decorated function with the signature
+    (scope, receive, send, app).
+
+    Args:
+        middleware_func: middleware function provided to the decorator
+        middleware_type: type ("http" by default) or "*" for all
+
+    Returns:
+        Middleware class that invokes the decorated function
+    """
+
+    class DecoratedMiddleware:
+        def __init__(self, app):
+            self.app = app
+
+        async def __call__(self, scope, receive, send):
+            if scope.get("type") == middleware_type or middleware_type == "*":
+                return await middleware_func(scope, receive, send, self.app)
+            return await self.app(scope, receive, send)
+
+    return DecoratedMiddleware

tachyon_api/middlewares/cors.py

@@ -0,0 +1,159 @@
+from typing import Iterable, Optional, Sequence, Tuple
+
+
+class CORSMiddleware:
+    """
+    ASGI middleware for handling CORS.
+
+    Parameters:
+    - allow_origins: list of allowed origins (e.g., ["https://foo.com", "*"])
+    - allow_methods: list of allowed methods (default ["*"])
+    - allow_headers: list of allowed headers (default ["*"])
+    - allow_credentials: if True, adds Access-Control-Allow-Credentials: true
+    - expose_headers: list of headers to expose to the client app
+    - max_age: seconds to cache the preflight response
+
+    Behavior:
+    - If it's a preflight (OPTIONS + Access-Control-Request-Method), responds 200 with
+      the appropriate CORS headers.
+    - For normal requests, injects CORS headers into the response.
+    """
+
+    def __init__(
+        self,
+        app,
+        allow_origins: Iterable[str] = ("*",),
+        allow_methods: Iterable[str] = ("*",),
+        allow_headers: Iterable[str] = ("*",),
+        allow_credentials: bool = False,
+        expose_headers: Iterable[str] = (),
+        max_age: int = 600,
+    ):
+        self.app = app
+        self.allow_origins = [o for o in allow_origins]
+        self.allow_methods = [m.upper() for m in allow_methods]
+        self.allow_headers = [h for h in allow_headers]
+        self.allow_credentials = allow_credentials
+        self.expose_headers = [h for h in expose_headers]
+        self.max_age = max_age
+
+    @staticmethod
+    def _get_header(headers: Sequence[Tuple[bytes, bytes]], name: str) -> Optional[str]:
+        # Find a header in a case-insensitive manner and decode it
+        lower = name.lower().encode()
+        for k, v in headers or []:
+            if k.lower() == lower:
+                try:
+                    return v.decode()
+                except Exception:
+                    return None
+        return None
+
+    @staticmethod
+    def _append_header(headers: list[Tuple[bytes, bytes]], name: str, value: str):
+        # Append header encoded as bytes as required by ASGI
+        headers.append((name.encode(), value.encode()))
+
+    def _origin_allowed(self, origin: Optional[str]) -> bool:
+        if origin is None:
+            return False
+        if "*" in self.allow_origins:
+            return True
+        return origin in self.allow_origins
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") != "http":
+            return await self.app(scope, receive, send)
+
+        req_headers: Sequence[Tuple[bytes, bytes]] = scope.get("headers", []) or []
+        origin = self._get_header(req_headers, "origin")
+        method = scope.get("method", "").upper()
+        is_preflight = (
+            method == "OPTIONS"
+            and self._get_header(req_headers, "access-control-request-method")
+            is not None
+        )
+
+        # Build common CORS headers
+        def build_cors_headers() -> list[Tuple[bytes, bytes]]:
+            headers_out: list[Tuple[bytes, bytes]] = []
+            if not self._origin_allowed(origin):
+                return headers_out
+
+            # Access-Control-Allow-Origin
+            if "*" in self.allow_origins and not self.allow_credentials:
+                self._append_header(headers_out, "access-control-allow-origin", "*")
+            else:
+                self._append_header(headers_out, "access-control-allow-origin", origin)
+                # Necessary for proxies/caches when echoing the origin
+                self._append_header(headers_out, "vary", "Origin")
+
+            # Credentials
+            if self.allow_credentials:
+                self._append_header(
+                    headers_out, "access-control-allow-credentials", "true"
+                )
+
+            return headers_out
+
+        # Handle preflight
+        if is_preflight:
+            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
+                )
+
+                # Requested headers or wildcard
+                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
+                    )
+
+                # Max-Age
+                if 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.body", "body": b""})
+                return
+            # If origin not allowed, continue the chain (app will respond accordingly)
+
+        # Normal requests: inject CORS headers into the response
+        cors_headers = build_cors_headers()
+
+        # Expose-Headers
+        if cors_headers and self.expose_headers:
+            expose = ", ".join(self.expose_headers)
+            self._append_header(cors_headers, "access-control-expose-headers", expose)
+
+        async def send_wrapper(message):
+            if message.get("type") == "http.response.start" and cors_headers:
+                headers = list(message.get("headers", []) or [])
+                headers.extend(cors_headers)
+                message["headers"] = headers
+            return await send(message)
+
+        return await self.app(scope, receive, send_wrapper)

tachyon_api/middlewares/logger.py

@@ -0,0 +1,123 @@
+import logging
+import time
+from typing import Optional, Sequence, Tuple
+
+
+class LoggerMiddleware:
+    """
+    ASGI middleware for logging requests and responses.
+
+    Options:
+    - logger: logging.Logger instance (defaults to "tachyon.logger")
+    - level: log level (defaults to logging.INFO)
+    - include_headers: if True, log request and response headers
+    - redact_headers: list of header names to redact
+    - log_request_body: if True, try to read and log the request body (HTTP)
+
+    Note: To keep it simple and non-intrusive, the body is only logged if it's
+    available in a single body message (typical in tests/sync). In production,
+    reading the body implies buffering receive/send, which we intentionally avoid
+    here to prevent side effects.
+    """
+
+    def __init__(
+        self,
+        app,
+        logger: Optional[logging.Logger] = None,
+        level: int = logging.INFO,
+        include_headers: bool = False,
+        redact_headers: Optional[Sequence[str]] = None,
+        log_request_body: bool = False,
+    ):
+        self.app = app
+        self.logger = logger or logging.getLogger("tachyon.logger")
+        self.level = level
+        self.include_headers = include_headers
+        self.redact_headers = {h.lower() for h in (redact_headers or [])}
+        self.log_request_body = log_request_body
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") != "http":
+            return await self.app(scope, receive, send)
+
+        method: str = scope.get("method", "")
+        path: str = scope.get("path", "")
+        start = time.time()
+        status_code_holder = {"status": None}
+        response_headers_holder: list[Tuple[bytes, bytes]] = []
+
+        # Simple, non-intrusive request body preview
+        request_body_preview = None
+        if self.log_request_body:
+            # Non-intrusive attempt: peek the body if the first receive contains it fully
+            body_chunks = []
+            more_body = True
+
+            async def recv_wrapper():
+                nonlocal more_body
+                message = await receive()
+                if message.get("type") == "http.request":
+                    body = message.get("body", b"")
+                    if body:
+                        body_chunks.append(body)
+                    more_body = message.get("more_body", False)
+                return message
+
+            # Perform a one-time peek without fully consuming the stream
+            # If body is present and more_body is False, log a small preview
+            first_msg = await recv_wrapper()
+
+            async def receive_passthrough():
+                # Return the pre-received message first, then pass-through
+                nonlocal first_msg
+                if first_msg is not None:
+                    m = first_msg
+                    first_msg = None
+                    return m
+                return await receive()
+
+            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"
+                    )
+                except Exception:
+                    request_body_preview = "<non-text body>"
+        else:
+            receive_to_use = receive
+
+        def _normalized_headers(headers: Sequence[Tuple[bytes, bytes]]):
+            out = []
+            for k, v in headers:
+                name = k.decode().lower()
+                if name in self.redact_headers:
+                    out.append((name, "<redacted>"))
+                else:
+                    out.append((name, v.decode(errors="replace")))
+            return out
+
+        self.logger.log(self.level, f"--> {method} {path}")
+        if self.include_headers:
+            req_headers = _normalized_headers(scope.get("headers", []) or [])
+            self.logger.log(self.level, f"    req headers: {req_headers}")
+        if request_body_preview is not None:
+            self.logger.log(self.level, f"    req body: {request_body_preview}")
+
+        async def send_wrapper(message):
+            if message.get("type") == "http.response.start":
+                status_code_holder["status"] = message.get("status", 0)
+                response_headers_holder[:] = list(message.get("headers", []) or [])
+            return await send(message)
+
+        try:
+            await self.app(scope, receive_to_use, send_wrapper)
+        finally:
+            duration = time.time() - start
+            status = status_code_holder["status"] or 0
+            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/models.py

@@ -0,0 +1,73 @@
+"""
+Tachyon Web Framework - Data Models Module
+
+This module provides the base model class for request/response data validation
+using msgspec for high-performance JSON serialization and validation.
+The module enhances msgspec with orjson for even faster JSON processing.
+"""
+
+import datetime
+import uuid
+from typing import Any, Dict, Type, TypeVar, Optional, Union
+
+import msgspec
+import orjson
+from msgspec import Struct, Meta
+
+__all__ = ["Struct", "Meta", "encode_json", "decode_json"]
+
+T = TypeVar("T")
+
+
+def _orjson_default(obj: Any) -> Any:
+    """Default function for orjson to serialize types it doesn't support natively."""
+    if isinstance(obj, (datetime.date, datetime.datetime)):
+        return obj.isoformat()
+    if isinstance(obj, uuid.UUID):
+        return str(obj)
+    if isinstance(obj, Struct):
+        return msgspec.to_builtins(obj)
+    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
+
+
+def encode_json(obj: Any, option: Optional[int] = None) -> bytes:
+    """
+    Encode a Python object to JSON using orjson.
+
+    Args:
+        obj: Object to encode (can be a Struct instance or any JSON-serializable object)
+        option: orjson option flags (e.g., orjson.OPT_INDENT_2)
+
+    Returns:
+        JSON-encoded bytes
+    """
+    opts = (
+        option
+        or orjson.OPT_SERIALIZE_DATACLASS | orjson.OPT_SERIALIZE_UUID | orjson.OPT_UTC_Z
+    )
+    return orjson.dumps(obj, default=_orjson_default, option=opts)
+
+
+def decode_json(data: Union[bytes, str], type_: Type[T] = Dict[str, Any]) -> T:
+    """
+    Decode JSON to a Python object using orjson.
+    If a Struct type is provided, the decoded data will be converted to that type.
+
+    Args:
+        data: JSON data as bytes or string
+        type_: Target type (default is Dict[str, Any])
+
+    Returns:
+        Decoded object of the specified type
+    """
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+
+    # First use orjson for fast JSON parsing
+    parsed_data = orjson.loads(data)
+
+    # If the target type is a Struct or similar msgspec type, use msgspec.convert
+    if isinstance(type_, type) and issubclass(type_, Struct):
+        return msgspec.convert(parsed_data, type_)
+
+    return parsed_data