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

tachyon_api/app.py

@@ -11,6 +11,7 @@ import inspect
 import msgspec
 from functools import partial
 from typing import Any, Dict, Type, Union, Callable
+import typing
 
 from starlette.applications import Starlette
 from starlette.responses import HTMLResponse, JSONResponse, Response
@@ -22,13 +23,26 @@ from .openapi import (
     OpenAPIGenerator,
     OpenAPIConfig,
     create_openapi_config,
-    _generate_schema_for_struct,
 )
 from .params import Body, Query, Path
 from .middlewares.core import (
     apply_middleware_to_router,
     create_decorated_middleware_class,
 )
+from .responses import (
+    TachyonJSONResponse,
+    validation_error_response,
+    response_validation_error_response,
+)
+
+from .utils import TypeConverter, TypeUtils
+
+from .responses import internal_server_error_response
+
+try:
+    from .cache import set_cache_config
+except ImportError:
+    set_cache_config = None  # type: ignore
 
 
 class Tachyon:
@@ -46,13 +60,15 @@ class Tachyon:
         openapi_generator: Generator for OpenAPI schema and documentation
     """
 
-    def __init__(self, openapi_config: OpenAPIConfig = None):
+    def __init__(self, openapi_config: OpenAPIConfig = None, cache_config=None):
         """
         Initialize a new Tachyon application instance.
 
         Args:
             openapi_config: Optional OpenAPI configuration. If not provided,
                           uses default configuration similar to FastAPI.
+            cache_config: Optional cache configuration (tachyon_api.cache.CacheConfig).
+                          If provided, it will be set as the active cache configuration.
         """
         self._router = Starlette()
         self.routes = []
@@ -64,6 +80,15 @@ class Tachyon:
         self.openapi_generator = OpenAPIGenerator(self.openapi_config)
         self._docs_setup = False
 
+        # Apply cache configuration if provided
+        self.cache_config = cache_config
+        if cache_config is not None and set_cache_config is not None:
+            try:
+                set_cache_config(cache_config)
+            except Exception:
+                # Do not break app initialization if cache setup fails
+                pass
+
         # Dynamically create HTTP method decorators (get, post, put, delete, etc.)
         http_methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"]
 
@@ -74,49 +99,6 @@ class Tachyon:
                 partial(self._create_decorator, http_method=method),
             )
 
-    @staticmethod
-    def _convert_value(
-        value_str: str,
-        target_type: Type,
-        param_name: str,
-        is_path_param: bool = False,  # noqa
-    ) -> Union[Any, JSONResponse]:
-        """
-        Convert a string value to the target type with appropriate error handling.
-
-        This method handles type conversion for query and path parameters,
-        including special handling for boolean values and proper error responses.
-
-        Args:
-            value_str: The string value to convert
-            target_type: The target Python type to convert to
-            param_name: Name of the parameter (for error messages)
-            is_path_param: Whether this is a path parameter (affects error response)
-
-        Returns:
-            The converted value, or a JSONResponse with appropriate error code
-
-        Note:
-            - Boolean conversion accepts: "true", "1", "t", "yes" (case-insensitive)
-            - Path parameter errors return 404, query parameter errors return 422
-        """
-        try:
-            if target_type is bool:
-                return value_str.lower() in ("true", "1", "t", "yes")
-            elif target_type is not str:
-                return target_type(value_str)
-            else:
-                return value_str
-        except (ValueError, TypeError):
-            if is_path_param:
-                return JSONResponse({"detail": "Not Found"}, status_code=404)
-            else:
-                type_name = "integer" if target_type is int else target_type.__name__
-                return JSONResponse(
-                    {"detail": f"Invalid value for {type_name} conversion"},
-                    status_code=422,
-                )
-
     def _resolve_dependency(self, cls: Type) -> Any:
         """
         Resolve a dependency and its sub-dependencies recursively.
@@ -210,6 +192,8 @@ class Tachyon:
             4. Path parameters (both explicit with Path() and implicit from URL)
         """
 
+        response_model = kwargs.get("response_model")
+
         async def handler(request):
             """
             Async request handler that processes parameters and calls the endpoint.
@@ -217,124 +201,251 @@ class Tachyon:
             This handler analyzes the endpoint function signature and automatically
             injects the appropriate values based on parameter annotations and defaults.
             """
-            kwargs_to_inject = {}
-            sig = inspect.signature(endpoint_func)
-            query_params = request.query_params
-            path_params = request.path_params
-            _raw_body = None
-
-            # Process each parameter in the endpoint function signature
-            for param in sig.parameters.values():
-                # Determine if this parameter is a dependency
-                is_explicit_dependency = isinstance(param.default, Depends)
-                is_implicit_dependency = (
-                    param.default is inspect.Parameter.empty
-                    and param.annotation in _registry
-                )
-
-                # Process dependencies (explicit and implicit)
-                if is_explicit_dependency or is_implicit_dependency:
-                    target_class = param.annotation
-                    kwargs_to_inject[param.name] = self._resolve_dependency(
-                        target_class
+            try:
+                kwargs_to_inject = {}
+                sig = inspect.signature(endpoint_func)
+                query_params = request.query_params
+                path_params = request.path_params
+                _raw_body = None
+
+                # Process each parameter in the endpoint function signature
+                for param in sig.parameters.values():
+                    # Determine if this parameter is a dependency
+                    is_explicit_dependency = isinstance(param.default, Depends)
+                    is_implicit_dependency = (
+                        param.default is inspect.Parameter.empty
+                        and param.annotation in _registry
                     )
 
-                # Process Body parameters (JSON request body)
-                elif isinstance(param.default, Body):
-                    model_class = param.annotation
-                    if not issubclass(model_class, Struct):
-                        raise TypeError(
-                            "Body type must be an instance of Tachyon_api.models.Struct"
+                    # Process dependencies (explicit and implicit)
+                    if is_explicit_dependency or is_implicit_dependency:
+                        target_class = param.annotation
+                        kwargs_to_inject[param.name] = self._resolve_dependency(
+                            target_class
                         )
 
-                    decoder = msgspec.json.Decoder(model_class)
-                    try:
-                        if _raw_body is None:
-                            _raw_body = await request.body()
-                        validated_data = decoder.decode(_raw_body)
-                        kwargs_to_inject[param.name] = validated_data
-                    except msgspec.ValidationError as e:
-                        return JSONResponse({"detail": str(e)}, status_code=422)
-
-                # Process Query parameters (URL query string)
-                elif isinstance(param.default, Query):
-                    query_info = param.default
-                    param_name = param.name
-
-                    if param_name in query_params:
-                        value_str = query_params[param_name]
-                        converted_value = self._convert_value(
-                            value_str, param.annotation, param_name, is_path_param=False
-                        )
-                        # Return error response if conversion failed
-                        if isinstance(converted_value, JSONResponse):
-                            return converted_value
-                        kwargs_to_inject[param_name] = converted_value
-
-                    elif query_info.default is not ...:
-                        # Use default value if parameter is optional
-                        kwargs_to_inject[param.name] = query_info.default
-                    else:
-                        # Return error if required parameter is missing
-                        return JSONResponse(
-                            {
-                                "detail": f"Missing required query parameter: {param_name}"
-                            },
-                            status_code=422,
-                        )
-
-                # Process explicit Path parameters (with Path() annotation)
-                elif isinstance(param.default, Path):
-                    param_name = param.name
-                    if param_name in path_params:
+                    # Process Body parameters (JSON request body)
+                    elif isinstance(param.default, Body):
+                        model_class = param.annotation
+                        if not issubclass(model_class, Struct):
+                            raise TypeError(
+                                "Body type must be an instance of Tachyon_api.models.Struct"
+                            )
+
+                        decoder = msgspec.json.Decoder(model_class)
+                        try:
+                            if _raw_body is None:
+                                _raw_body = await request.body()
+                            validated_data = decoder.decode(_raw_body)
+                            kwargs_to_inject[param.name] = validated_data
+                        except msgspec.ValidationError as e:
+                            # Attempt to build field errors map using e.path
+                            field_errors = None
+                            try:
+                                path = getattr(e, "path", None)
+                                if path:
+                                    # Choose last string-ish path element as field name
+                                    field_name = None
+                                    for p in reversed(path):
+                                        if isinstance(p, str):
+                                            field_name = p
+                                            break
+                                    if field_name:
+                                        field_errors = {field_name: [str(e)]}
+                            except Exception:
+                                field_errors = None
+                            return validation_error_response(
+                                str(e), errors=field_errors
+                            )
+
+                    # Process Query parameters (URL query string)
+                    elif isinstance(param.default, Query):
+                        query_info = param.default
+                        param_name = param.name
+
+                        # Determine typing for advanced cases
+                        ann = param.annotation
+                        origin = typing.get_origin(ann)
+                        args = typing.get_args(ann)
+
+                        # List[T] handling
+                        if origin in (list, typing.List):
+                            item_type = args[0] if args else str
+                            values = []
+                            # collect repeated params
+                            if hasattr(query_params, "getlist"):
+                                values = query_params.getlist(param_name)
+                            # if not repeated, check for CSV in single value
+                            if not values and param_name in query_params:
+                                raw = query_params[param_name]
+                                values = raw.split(",") if "," in raw else [raw]
+                            # flatten CSV in any element
+                            flat_values = []
+                            for v in values:
+                                if isinstance(v, str) and "," in v:
+                                    flat_values.extend(v.split(","))
+                                else:
+                                    flat_values.append(v)
+                            values = flat_values
+                            if not values:
+                                if query_info.default is not ...:
+                                    kwargs_to_inject[param_name] = query_info.default
+                                    continue
+                                return validation_error_response(
+                                    f"Missing required query parameter: {param_name}"
+                                )
+                            # Unwrap Optional for item type
+                            base_item_type, item_is_opt = TypeUtils.unwrap_optional(
+                                item_type
+                            )
+                            converted_list = []
+                            for v in values:
+                                if item_is_opt and (v == "" or v.lower() == "null"):
+                                    converted_list.append(None)
+                                    continue
+                                converted_value = TypeConverter.convert_value(
+                                    v, base_item_type, param_name, is_path_param=False
+                                )
+                                if isinstance(converted_value, JSONResponse):
+                                    return converted_value
+                                converted_list.append(converted_value)
+                            kwargs_to_inject[param_name] = converted_list
+                            continue
+
+                        # Optional[T] handling for single value
+                        base_type, _is_opt = TypeUtils.unwrap_optional(ann)
+
+                        if param_name in query_params:
+                            value_str = query_params[param_name]
+                            converted_value = TypeConverter.convert_value(
+                                value_str, base_type, param_name, is_path_param=False
+                            )
+                            if isinstance(converted_value, JSONResponse):
+                                return converted_value
+                            kwargs_to_inject[param_name] = converted_value
+
+                        elif query_info.default is not ...:
+                            kwargs_to_inject[param.name] = query_info.default
+                        else:
+                            return validation_error_response(
+                                f"Missing required query parameter: {param_name}"
+                            )
+
+                    # Process explicit Path parameters (with Path() annotation)
+                    elif isinstance(param.default, Path):
+                        param_name = param.name
+                        if param_name in path_params:
+                            value_str = path_params[param_name]
+                            # Support List[T] in path params via CSV
+                            ann = param.annotation
+                            origin = typing.get_origin(ann)
+                            args = typing.get_args(ann)
+                            if origin in (list, typing.List):
+                                item_type = args[0] if args else str
+                                parts = value_str.split(",") if value_str else []
+                                # Unwrap Optional for item type
+                                base_item_type, item_is_opt = TypeUtils.unwrap_optional(
+                                    item_type
+                                )
+                                converted_list = []
+                                for v in parts:
+                                    if item_is_opt and (v == "" or v.lower() == "null"):
+                                        converted_list.append(None)
+                                        continue
+                                    converted_value = TypeConverter.convert_value(
+                                        v,
+                                        base_item_type,
+                                        param_name,
+                                        is_path_param=True,
+                                    )
+                                    if isinstance(converted_value, JSONResponse):
+                                        return converted_value
+                                    converted_list.append(converted_value)
+                                kwargs_to_inject[param_name] = converted_list
+                            else:
+                                converted_value = TypeConverter.convert_value(
+                                    value_str, ann, param_name, is_path_param=True
+                                )
+                                # Return 404 if conversion failed
+                                if isinstance(converted_value, JSONResponse):
+                                    return converted_value
+                                kwargs_to_inject[param_name] = converted_value
+                        else:
+                            return JSONResponse(
+                                {"detail": "Not Found"}, status_code=404
+                            )
+
+                    # Process implicit Path parameters (URL path variables without Path())
+                    elif (
+                        param.default is inspect.Parameter.empty
+                        and param.name in path_params
+                        and not is_explicit_dependency
+                        and not is_implicit_dependency
+                    ):
+                        param_name = param.name
                         value_str = path_params[param_name]
-                        converted_value = self._convert_value(
-                            value_str, param.annotation, param_name, is_path_param=True
-                        )
-                        # Return 404 if conversion failed
-                        if isinstance(converted_value, JSONResponse):
-                            return converted_value
-                        kwargs_to_inject[param_name] = converted_value
-                    else:
-                        return JSONResponse({"detail": "Not Found"}, status_code=404)
-
-                # Process implicit Path parameters (URL path variables without Path())
-                elif (
-                    param.default is inspect.Parameter.empty
-                    and param.name in path_params
-                    and not is_explicit_dependency
-                    and not is_implicit_dependency
-                ):
-                    param_name = param.name
-                    value_str = path_params[param_name]
-                    converted_value = self._convert_value(
-                        value_str, param.annotation, param_name, is_path_param=True
-                    )
-                    # Return 404 if conversion failed
-                    if isinstance(converted_value, JSONResponse):
-                        return converted_value
-                    kwargs_to_inject[param_name] = converted_value
-
-            # Call the endpoint function with injected parameters
-            if asyncio.iscoroutinefunction(endpoint_func):
-                payload = await endpoint_func(**kwargs_to_inject)
-            else:
-                payload = endpoint_func(**kwargs_to_inject)
-
-            # If the endpoint already returned a Response object, return it directly
-            if isinstance(payload, Response):
-                return payload
-
-            # Convert Struct objects to dictionaries for JSON serialization
-            if isinstance(payload, Struct):
-                payload = msgspec.to_builtins(payload)
-            elif isinstance(payload, dict):
-                # Convert any Struct values in the dictionary
-                for key, value in payload.items():
-                    if isinstance(value, Struct):
-                        payload[key] = msgspec.to_builtins(value)
-
-            return JSONResponse(payload)
+                        # Support List[T] via CSV
+                        ann = param.annotation
+                        origin = typing.get_origin(ann)
+                        args = typing.get_args(ann)
+                        if origin in (list, typing.List):
+                            item_type = args[0] if args else str
+                            parts = value_str.split(",") if value_str else []
+                            # Unwrap Optional for item type
+                            base_item_type, item_is_opt = TypeUtils.unwrap_optional(
+                                item_type
+                            )
+                            converted_list = []
+                            for v in parts:
+                                if item_is_opt and (v == "" or v.lower() == "null"):
+                                    converted_list.append(None)
+                                    continue
+                                converted_value = TypeConverter.convert_value(
+                                    v, base_item_type, param_name, is_path_param=True
+                                )
+                                if isinstance(converted_value, JSONResponse):
+                                    return converted_value
+                                converted_list.append(converted_value)
+                            kwargs_to_inject[param_name] = converted_list
+                        else:
+                            converted_value = TypeConverter.convert_value(
+                                value_str, ann, param_name, is_path_param=True
+                            )
+                            # Return 404 if conversion failed
+                            if isinstance(converted_value, JSONResponse):
+                                return converted_value
+                            kwargs_to_inject[param_name] = converted_value
+
+                # Call the endpoint function with injected parameters
+                if asyncio.iscoroutinefunction(endpoint_func):
+                    payload = await endpoint_func(**kwargs_to_inject)
+                else:
+                    payload = endpoint_func(**kwargs_to_inject)
+
+                # If the endpoint already returned a Response object, return it directly
+                if isinstance(payload, Response):
+                    return payload
+
+                # Validate/convert response against response_model if provided
+                if response_model is not None:
+                    try:
+                        payload = msgspec.convert(payload, response_model)
+                    except Exception as e:
+                        return response_validation_error_response(str(e))
+
+                # Convert Struct objects to dictionaries for JSON serialization
+                if isinstance(payload, Struct):
+                    payload = msgspec.to_builtins(payload)
+                elif isinstance(payload, dict):
+                    # Convert any Struct values in the dictionary
+                    for key, value in payload.items():
+                        if isinstance(value, Struct):
+                            payload[key] = msgspec.to_builtins(value)
+
+                return TachyonJSONResponse(payload)
+            except Exception:
+                # Fallback: prevent unhandled exceptions from leaking to the client
+                return internal_server_error_response()
 
         # Register the route with Starlette
         route = Route(path, endpoint=handler, methods=[method])
@@ -365,6 +476,40 @@ class Tachyon:
         """
         sig = inspect.signature(endpoint_func)
 
+        # Ensure common error schemas exist in components
+        self.openapi_generator.add_schema(
+            "ValidationErrorResponse",
+            {
+                "type": "object",
+                "properties": {
+                    "success": {"type": "boolean"},
+                    "error": {"type": "string"},
+                    "code": {"type": "string"},
+                    "errors": {
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                        },
+                    },
+                },
+                "required": ["success", "error", "code"],
+            },
+        )
+        self.openapi_generator.add_schema(
+            "ResponseValidationError",
+            {
+                "type": "object",
+                "properties": {
+                    "success": {"type": "boolean"},
+                    "error": {"type": "string"},
+                    "detail": {"type": "string"},
+                    "code": {"type": "string"},
+                },
+                "required": ["success", "error", "code"],
+            },
+        )
+
         # Build the OpenAPI operation object
         operation = {
             "summary": kwargs.get(
@@ -375,10 +520,42 @@ class Tachyon:
                 "200": {
                     "description": "Successful Response",
                     "content": {"application/json": {"schema": {"type": "object"}}},
-                }
+                },
+                "422": {
+                    "description": "Validation Error",
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/ValidationErrorResponse"
+                            }
+                        }
+                    },
+                },
+                "500": {
+                    "description": "Response Validation Error",
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/ResponseValidationError"
+                            }
+                        }
+                    },
+                },
             },
         }
 
+        # If a response_model is provided and is a Struct, use it for the 200 response schema
+        response_model = kwargs.get("response_model")
+        if response_model is not None and issubclass(response_model, Struct):
+            from .openapi import build_components_for_struct
+
+            comps = build_components_for_struct(response_model)
+            for name, schema in comps.items():
+                self.openapi_generator.add_schema(name, schema)
+            operation["responses"]["200"]["content"]["application/json"]["schema"] = {
+                "$ref": f"#/components/schemas/{response_model.__name__}"
+            }
+
         # Add tags if provided
         if "tags" in kwargs:
             operation["tags"] = kwargs["tags"]
@@ -402,7 +579,7 @@ class Tachyon:
                         "name": param.name,
                         "in": "query",
                         "required": param.default.default is ...,
-                        "schema": {"type": self._get_openapi_type(param.annotation)},
+                        "schema": self._build_param_openapi_schema(param.annotation),
                         "description": getattr(param.default, "description", ""),
                     }
                 )
@@ -416,7 +593,7 @@ class Tachyon:
                         "name": param.name,
                         "in": "path",
                         "required": True,
-                        "schema": {"type": self._get_openapi_type(param.annotation)},
+                        "schema": self._build_param_openapi_schema(param.annotation),
                         "description": getattr(param.default, "description", "")
                         if isinstance(param.default, Path)
                         else "",
@@ -427,17 +604,17 @@ class Tachyon:
             elif isinstance(param.default, Body):
                 model_class = param.annotation
                 if issubclass(model_class, Struct):
-                    schema_name = model_class.__name__
-                    # Add schema to components
-                    self.openapi_generator.add_schema(
-                        schema_name, _generate_schema_for_struct(model_class)
-                    )
+                    from .openapi import build_components_for_struct
+
+                    comps = build_components_for_struct(model_class)
+                    for name, schema in comps.items():
+                        self.openapi_generator.add_schema(name, schema)
 
                     request_body_schema = {
                         "content": {
                             "application/json": {
                                 "schema": {
-                                    "$ref": f"#/components/schemas/{schema_name}"
+                                    "$ref": f"#/components/schemas/{model_class.__name__}"
                                 }
                             }
                         },
@@ -448,11 +625,9 @@ class Tachyon:
         if parameters:
             operation["parameters"] = parameters
 
-        # Add request body if it exists
         if request_body_schema:
             operation["requestBody"] = request_body_schema
 
-        # Add the operation to the OpenAPI schema
         self.openapi_generator.add_path(path, method, operation)
 
     @staticmethod
@@ -476,6 +651,44 @@ class Tachyon:
         }
         return type_map.get(python_type, "string")
 
+    @staticmethod
+    def _build_param_openapi_schema(python_type: Type) -> Dict[str, Any]:
+        """Build OpenAPI schema for parameter types, supporting Optional[T] and List[T]."""
+        origin = typing.get_origin(python_type)
+        args = typing.get_args(python_type)
+        nullable = False
+        # Optional[T]
+        if origin is Union and args:
+            non_none = [a for a in args if a is not type(None)]  # noqa: E721
+            if len(non_none) == 1:
+                python_type = non_none[0]
+                nullable = True
+        # List[T] (and List[Optional[T]])
+        origin = typing.get_origin(python_type)
+        args = typing.get_args(python_type)
+        if origin in (list, typing.List):
+            item_type = args[0] if args else str
+            # Unwrap Optional in items for List[Optional[T]]
+            item_origin = typing.get_origin(item_type)
+            item_args = typing.get_args(item_type)
+            item_nullable = False
+            if item_origin is Union and item_args:
+                item_non_none = [a for a in item_args if a is not type(None)]  # noqa: E721
+                if len(item_non_none) == 1:
+                    item_type = item_non_none[0]
+                    item_nullable = True
+            schema = {
+                "type": "array",
+                "items": {"type": Tachyon._get_openapi_type(item_type)},
+            }
+            if item_nullable:
+                schema["items"]["nullable"] = True
+        else:
+            schema = {"type": Tachyon._get_openapi_type(python_type)}
+        if nullable:
+            schema["nullable"] = True
+        return schema
+
     def _setup_docs(self):
         """
         Setup OpenAPI documentation endpoints.
@@ -576,7 +789,7 @@ class Tachyon:
             middleware_class: The middleware class.
             **options: Options to be passed to the middleware constructor.
         """
-        # Usar helper centralizado para aplicar el middleware sobre Starlette
+        # Use centralized helper to apply middleware to internal Starlette app
         apply_middleware_to_router(self._router, middleware_class, **options)
 
         if not hasattr(self, "middleware_stack"):
@@ -596,11 +809,11 @@ class Tachyon:
         """
 
         def decorator(middleware_func):
-            # Crear una clase de middleware a partir de la función decorada
+            # Create a middleware class from the decorated function
             DecoratedMiddleware = create_decorated_middleware_class(
                 middleware_func, middleware_type
             )
-            # Registrar el middleware usando el método existente
+            # Register the middleware using the existing method
             self.add_middleware(DecoratedMiddleware)
             return middleware_func