modmex-lambda 0.1.0__py3-none-any.whl

modmex_lambda/logging.py

@@ -0,0 +1,99 @@
+"""Lightweight structured logger for Lambda workloads."""
+
+from __future__ import annotations
+
+import json
+import sys
+import traceback
+from datetime import datetime, timezone
+from typing import Any, Callable, TextIO
+
+
+class Logger:
+    def __init__(
+        self,
+        *,
+        service: str,
+        stream: TextIO | None = None,
+        json_serializer: Callable[[dict[str, Any]], str] | None = None,
+        correlation_id_header: str = "x-correlation-id",
+    ) -> None:
+        self._service = service
+        self._stream = stream or sys.stdout
+        self._serialize = json_serializer or (lambda payload: json.dumps(payload, separators=(",", ":"), default=str))
+        self._correlation_id_header = correlation_id_header.lower()
+        self._persistent_keys: dict[str, Any] = {}
+        self._context: object | None = None
+        self._event: dict[str, Any] | None = None
+
+    def set_context(self, *, context: object | None = None, event: dict[str, Any] | None = None) -> None:
+        self._context = context
+        self._event = event
+
+    def append_keys(self, **kwargs: Any) -> None:
+        self._persistent_keys.update(kwargs)
+
+    def clear_state(self) -> None:
+        self._persistent_keys.clear()
+
+    def debug(self, message: str, **kwargs: Any) -> None:
+        self._log("DEBUG", message, **kwargs)
+
+    def info(self, message: str, **kwargs: Any) -> None:
+        self._log("INFO", message, **kwargs)
+
+    def warning(self, message: str, **kwargs: Any) -> None:
+        self._log("WARNING", message, **kwargs)
+
+    def error(self, message: str, *, exc_info: bool = False, **kwargs: Any) -> None:
+        self._log("ERROR", message, exc_info=exc_info, **kwargs)
+
+    def critical(self, message: str, *, exc_info: bool = False, **kwargs: Any) -> None:
+        self._log("CRITICAL", message, exc_info=exc_info, **kwargs)
+
+    def _log(self, level: str, message: str, *, exc_info: bool = False, **kwargs: Any) -> None:
+        record: dict[str, Any] = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "level": level,
+            "service": self._service,
+            "message": message,
+        }
+        record.update(self._persistent_keys)
+
+        request_id = self._extract_request_id()
+        if request_id:
+            record["request_id"] = request_id
+
+        correlation_id = self._extract_correlation_id()
+        if correlation_id and "correlation_id" not in record:
+            record["correlation_id"] = correlation_id
+
+        record.update(kwargs)
+
+        if exc_info:
+            record["exception"] = traceback.format_exc()
+
+        self._stream.write(self._serialize(record) + "\n")
+
+    def _extract_request_id(self) -> str | None:
+        if self._context is None:
+            return None
+        value = getattr(self._context, "aws_request_id", None)
+        return str(value) if value else None
+
+    def _extract_correlation_id(self) -> str | None:
+        event = self._event
+        if not isinstance(event, dict):
+            return None
+
+        headers = event.get("headers")
+        if not isinstance(headers, dict):
+            return None
+
+        for key, value in headers.items():
+            if str(key).lower() == self._correlation_id_header and value is not None:
+                return str(value)
+        return None
+
+
+__all__ = ["Logger"]

modmex_lambda/params.py

@@ -0,0 +1,3 @@
+"""Compatibility re-export for event handler parameter markers."""
+
+from modmex_lambda.event_handler.params import *  # noqa: F403

modmex_lambda/parser.py

@@ -0,0 +1,47 @@
+"""Lightweight event parser APIs."""
+
+from __future__ import annotations
+
+import json
+from functools import wraps
+from typing import Any, Callable, TYPE_CHECKING
+
+from modmex.errors import ValidationError
+
+if TYPE_CHECKING:
+    from .validation import Validator
+
+
+def parse(*, event: Any, model: Any, validator: "Validator | None" = None) -> Any:
+    """Validate/transform a raw event into ``model`` using the selected validator."""
+    selected_validator = validator
+    if selected_validator is None:
+        from .validation import ModmexValidator
+
+        selected_validator = ModmexValidator()
+
+    raw_event = event
+    if isinstance(event, str):
+        try:
+            raw_event = json.loads(event)
+        except json.JSONDecodeError as exc:
+            raise ValidationError(errors=[{"loc": [], "msg": str(exc), "type": "value_error.jsondecode"}]) from exc
+
+    return selected_validator.validate(raw_event, model)
+
+
+def event_parser(*, model: Any, validator: "Validator | None" = None) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator that parses Lambda ``event`` into ``model`` before handler execution."""
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(func)
+        def wrapper(event: Any, context: object, *args: Any, **kwargs: Any) -> Any:
+            parsed_event = parse(event=event, model=model, validator=validator)
+            return func(parsed_event, context, *args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+__all__ = ["parse", "event_parser"]

modmex_lambda/request.py

@@ -0,0 +1,3 @@
+"""Compatibility re-export for event handler request models."""
+
+from modmex_lambda.event_handler.request import *  # noqa: F403

modmex_lambda/resolver.py

@@ -0,0 +1,3 @@
+"""Compatibility re-export for API Gateway resolvers."""
+
+from modmex_lambda.event_handler.api_gateway import *  # noqa: F403

modmex_lambda/response.py

@@ -0,0 +1,3 @@
+"""Compatibility re-export for event handler response helpers."""
+
+from modmex_lambda.event_handler.response import *  # noqa: F403

modmex_lambda/routing.py

@@ -0,0 +1,3 @@
+"""Compatibility re-export for event handler routing internals."""
+
+from modmex_lambda.event_handler.routing import *  # noqa: F403

modmex_lambda/shared/cookies.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from enum import Enum
+from io import StringIO
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+
+class SameSite(Enum):
+
+    DEFAULT_MODE = ""
+    LAX_MODE = "Lax"
+    STRICT_MODE = "Strict"
+    NONE_MODE = "None"
+
+
+def _format_date(timestamp: datetime) -> str:
+    return timestamp.strftime("%a, %d %b %Y %H:%M:%S GMT")
+
+
+class Cookie:
+
+    def __init__(
+        self,
+        name: str,
+        value: str,
+        path: str = "",
+        domain: str = "",
+        secure: bool = True,
+        http_only: bool = False,
+        max_age: int | None = None,
+        expires: datetime | None = None,
+        same_site: SameSite | None = None,
+        custom_attributes: list[str] | None = None,
+    ):
+
+        self.name = name
+        self.value = value
+        self.path = path
+        self.domain = domain
+        self.secure = secure
+        self.expires = expires
+        self.max_age = max_age
+        self.http_only = http_only
+        self.same_site = same_site
+        self.custom_attributes = custom_attributes
+
+    def __str__(self) -> str:
+        payload = StringIO()
+        payload.write(f"{self.name}={self.value}")
+
+        if self.path:
+            payload.write(f"; Path={self.path}")
+
+        if self.domain:
+            payload.write(f"; Domain={self.domain}")
+
+        if self.expires:
+            payload.write(f"; Expires={_format_date(self.expires)}")
+
+        if self.max_age:
+            if self.max_age > 0:
+                payload.write(f"; Max-Age={self.max_age}")
+            else:
+                # negative or zero max-age should be set to 0
+                payload.write("; Max-Age=0")
+
+        if self.http_only:
+            payload.write("; HttpOnly")
+
+        if self.secure:
+            payload.write("; Secure")
+
+        if self.same_site:
+            payload.write(f"; SameSite={self.same_site.value}")
+
+        if self.custom_attributes:
+            for attr in self.custom_attributes:
+                payload.write(f"; {attr}")
+
+        return payload.getvalue()
+

modmex_lambda/shared/headers_serializer.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+
+from abc import ABC, abstractmethod
+from collections import defaultdict
+from typing import  Any
+from modmex_lambda.shared.cookies import Cookie
+
+
+class BaseHeadersSerializer(ABC):
+
+    @abstractmethod
+    def serialize(self, headers: dict[str, str | list[str]], cookies: list[Cookie]) -> dict[str, Any]:
+        raise NotImplementedError()
+
+
+class HttpApiHeadersSerializer(BaseHeadersSerializer):
+    def serialize(self, headers: dict[str, str | list[str]], cookies: list[Cookie]) -> dict[str, Any]:
+        """
+        When using HTTP APIs or LambdaFunctionURLs, everything is taken care automatically for us.
+        We can directly assign a list of cookies and a dict of headers to the response payload, and the
+        runtime will automatically serialize them correctly on the output.
+        """
+
+        # Format 2.0 doesn't have multiValueHeaders or multiValueQueryStringParameters fields.
+        # Duplicate headers are combined with commas and included in the headers field.
+        combined_headers: dict[str, str] = {}
+        for key, values in headers.items():
+            # omit headers with explicit null values
+            if values is None:
+                continue
+
+            if isinstance(values, str):
+                combined_headers[key] = values
+            else:
+                combined_headers[key] = ", ".join(values)
+
+        return {"headers": combined_headers, "cookies": list(map(str, cookies))}
+
+
+class MultiValueHeadersSerializer(BaseHeadersSerializer):
+    def serialize(self, headers: dict[str, str | list[str]], cookies: list[Cookie]) -> dict[str, Any]:
+        """
+        When using REST APIs, headers can be encoded using the `multiValueHeaders` key on the response.
+        This is also the case when using an ALB integration with the `multiValueHeaders` option enabled.
+        The solution covers headers with just one key or multiple keys.
+        """
+        payload: dict[str, list[str]] = defaultdict(list)
+        for key, values in headers.items():
+            # omit headers with explicit null values
+            if values is None:
+                continue
+
+            if isinstance(values, str):
+                payload[key].append(values)
+            else:
+                payload[key].extend(values)
+
+        if cookies:
+            payload.setdefault("Set-Cookie", [])
+            for cookie in cookies:
+                payload["Set-Cookie"].append(str(cookie))
+
+        return {"multiValueHeaders": payload}
+

modmex_lambda/shared/json_encoder.py

@@ -0,0 +1,53 @@
+from json import JSONEncoder as BaseJSONEncoder
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from enum import Enum
+
+
+class JSONEncoder(BaseJSONEncoder):
+    
+    def default(self, obj: object) -> object:
+        
+        if is_modmex(obj):
+            return obj.model_dump_json()
+        
+        if is_dataclass(obj):
+            return dataclass_to_dict(obj)
+        
+        if is_pydantic(obj):
+            return obj.model_dump_json()
+        
+        if isinstance(obj, Enum):
+            return obj.value
+    
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+    
+        if isinstance(obj, date):
+            return obj.isoformat()
+    
+        if isinstance(obj, time):
+            return obj.isoformat()
+    
+        if isinstance(obj, timedelta):
+            return obj.total_seconds()
+    
+        if isinstance(obj, Decimal):
+            return float(obj)
+    
+        return super().default(obj)
+    
+
+def is_dataclass(obj) -> bool:
+    return hasattr(obj, "__dataclass_fields__")
+
+def is_modmex(obj) -> bool:
+    return hasattr(obj, "model_dump_json")
+
+def is_pydantic(obj) -> bool:
+    return hasattr(obj, "model_dump_json")
+
+def dataclass_to_dict(obj) -> dict:
+    import dataclasses
+
+    return dataclasses.asdict(obj)

modmex_lambda/shared/types.py

@@ -0,0 +1,4 @@
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+AnyCallableT = TypeVar("AnyCallableT", bound=Callable[..., Any])

modmex_lambda/validation.py

@@ -0,0 +1,178 @@
+"""Validation adapter layer backed by Modmex."""
+
+from __future__ import annotations
+
+import inspect
+import json
+import types
+from collections.abc import Mapping, Sequence
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+from typing import Annotated, Any, Literal, Protocol, Union, get_args, get_origin
+
+from modmex import BaseModel
+from modmex.errors import ValidationError
+from modmex.validation import (
+    bool_validator,
+    decimal_validator,
+    float_validator,
+    int_validator,
+    parse_date,
+    parse_datetime,
+    str_validator,
+)
+
+
+class Validator(Protocol):
+    def validate(self, value: Any, target_type: Any, loc: list[Any] | None = None) -> Any:
+        """Validate/coerce ``value`` into ``target_type``."""
+
+    def serialize(self, value: Any) -> Any:
+        """Serialize a model-like value into Python primitives."""
+
+    def dumps(self, value: Any) -> str:
+        """Serialize a value to JSON."""
+
+
+class ModmexValidator:
+    def __init__(self) -> None:
+        self._primitive_validators = {
+            str: str_validator,
+            int: int_validator,
+            bool: bool_validator,
+            float: float_validator,
+            datetime: parse_datetime,
+            date: parse_date,
+            Decimal: decimal_validator,
+        }
+
+    def validate(self, value: Any, target_type: Any, loc: list[Any] | None = None) -> Any:
+        return self._validate_value(target_type, value, list(loc or []))
+
+    def serialize(self, value: Any) -> Any:
+        if hasattr(value, "model_dump"):
+            return value.model_dump()
+        if hasattr(value, "to_dict"):
+            return value.to_dict()
+        return value
+
+    def dumps(self, value: Any) -> str:
+        if hasattr(value, "model_dump_json"):
+            return value.model_dump_json()
+        return json.dumps(self.serialize(value), separators=(",", ":"), default=self.serialize)
+
+    def _validate_value(self, annotation: Any, value: Any, loc: list[Any]) -> Any:
+        if annotation is inspect.Signature.empty or annotation is Any:
+            return value
+
+        if value is None:
+            if self._accepts_none(annotation):
+                return None
+            raise ValidationError(errors=[{"loc": loc, "msg": "Field required", "type": "missing"}])
+
+        origin = get_origin(annotation)
+        args = get_args(annotation)
+
+        if origin is not None:
+            if origin is Annotated:
+                return self._validate_value(args[0], value, loc)
+
+            if origin in (list, Sequence):
+                item_type = args[0] if args else Any
+                return [self._validate_value(item_type, item, loc + [idx]) for idx, item in enumerate(value)]
+
+            if origin is tuple:
+                return self._validate_tuple(args, value, loc)
+
+            if origin is dict:
+                return self._validate_dict(args, value, loc)
+
+            if origin in (Union, types.UnionType):
+                return self._validate_union(args, value, loc)
+
+        if self._is_literal(annotation):
+            return self._validate_literal(annotation, value, loc)
+
+        return self._validate_leaf(annotation, value, loc)
+
+    def _validate_tuple(self, args: tuple[Any, ...], value: Any, loc: list[Any]) -> tuple[Any, ...]:
+        if not isinstance(value, tuple):
+            raise ValidationError(errors=[{"loc": loc, "msg": "must be a tuple", "type": "type_error.tuple"}])
+        if len(args) == 2 and args[1] is Ellipsis:
+            return tuple(self._validate_value(args[0], item, loc + [idx]) for idx, item in enumerate(value))
+        if len(value) != len(args):
+            raise ValidationError(errors=[{"loc": loc, "msg": "Tuple length mismatch", "type": "type_error"}])
+        return tuple(self._validate_value(arg, item, loc + [idx]) for idx, (arg, item) in enumerate(zip(args, value)))
+
+    def _validate_dict(self, args: tuple[Any, ...], value: Any, loc: list[Any]) -> dict[Any, Any]:
+        if not isinstance(value, Mapping):
+            raise ValidationError(errors=[{"loc": loc, "msg": "must be a dict", "type": "type_error.dict"}])
+        key_type, value_type = args if args else (Any, Any)
+        validated: dict[Any, Any] = {}
+        for key, item in value.items():
+            valid_key = self._validate_value(key_type, key, loc + ["<key>"])
+            validated[valid_key] = self._validate_value(value_type, item, loc + [key])
+        return validated
+
+    def _validate_union(self, args: tuple[Any, ...], value: Any, loc: list[Any]) -> Any:
+        candidate_errors: list[dict[str, Any]] = []
+        for candidate in args:
+            try:
+                return self._validate_value(candidate, value, loc)
+            except ValidationError as exc:
+                candidate_errors.extend(exc.errors)
+        raise ValidationError(
+            errors=candidate_errors or [{"loc": loc, "msg": "Invalid union type", "type": "type_error"}]
+        )
+
+    def _validate_literal(self, annotation: Any, value: Any, loc: list[Any]) -> Any:
+        if value in get_args(annotation):
+            return value
+        raise ValidationError(
+            errors=[{"loc": loc, "msg": f"Unexpected literal value: {value}", "type": "literal_error"}]
+        )
+
+    def _validate_leaf(self, annotation: Any, value: Any, loc: list[Any]) -> Any:
+        try:
+            primitive_validator = self._primitive_validators.get(annotation)
+            if primitive_validator is not None:
+                return primitive_validator(value)
+
+            if inspect.isclass(annotation) and issubclass(annotation, Enum):
+                return annotation(value)
+
+            if inspect.isclass(annotation) and issubclass(annotation, BaseModel):
+                if isinstance(value, annotation):
+                    return value
+                if not isinstance(value, Mapping):
+                    raise ValidationError(errors=[{"loc": loc, "msg": "Expected object", "type": "type_error"}])
+                return annotation(**value)
+
+            if isinstance(value, annotation):
+                return value
+
+            if isinstance(value, Mapping):
+                return annotation(**value)
+
+            return annotation(value)
+        except ValidationError as exc:
+            raise ValidationError(errors=[self._prefix_error(error, loc) for error in exc.errors]) from exc
+        except (TypeError, ValueError) as exc:
+            raise ValidationError(errors=[{"loc": loc, "msg": str(exc), "type": "type_error"}]) from exc
+
+    def _accepts_none(self, annotation: Any) -> bool:
+        origin = get_origin(annotation)
+        if origin is None:
+            return annotation is type(None)
+        return any(arg is type(None) for arg in get_args(annotation))
+
+    def _is_literal(self, annotation: Any) -> bool:
+        return get_origin(annotation) is Literal
+
+    def _prefix_error(self, error: dict[str, Any], prefix: list[Any]) -> dict[str, Any]:
+        return {
+            "loc": [*prefix, *list(error.get("loc", []))],
+            "msg": error.get("msg", "Validation error"),
+            "type": error.get("type", "type_error"),
+        }