py-serverless-kit 0.1.0__py3-none-any.whl

py_serverless_kit/runtime/adapters/tencent.py

@@ -0,0 +1,151 @@
+"""Tencent Cloud SCF adapter.
+
+Handles API Gateway (integrated response), timer triggers, COS triggers and
+direct invocation.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Mapping
+from urllib.parse import parse_qs, unquote_plus
+
+from ..context import Context
+from ..dispatch import execute
+from ..event import Event, EventType, Headers, HttpRequest, Record, parse_time
+from ..response import Response
+from .base import action_from, function_name, maybe_json, unwrap_envelope
+
+PROVIDER = "tencent"
+
+
+def _ctx_get(ctx: Any, key: str, default: Any = None) -> Any:
+    if isinstance(ctx, Mapping):
+        return ctx.get(key, default)
+    return getattr(ctx, key, default)
+
+
+def _http(evt: Dict[str, Any]) -> HttpRequest:
+    rc = evt.get("requestContext") or {}
+    query: Dict[str, str] = {}
+    multi: Dict[str, List[str]] = {}
+    raw_query = evt.get("queryString")
+    if isinstance(raw_query, dict):
+        for key, value in raw_query.items():
+            values = [str(v) for v in value] if isinstance(value, list) else [str(value)]
+            multi[key] = values
+            query[key] = values[-1] if values else ""
+    elif isinstance(raw_query, str) and raw_query:
+        multi = parse_qs(raw_query, keep_blank_values=True)
+        query = {k: v[-1] for k, v in multi.items()}
+    if not query and evt.get("queryStringParameters"):
+        query = {k: str(v) for k, v in evt["queryStringParameters"].items()}
+    return HttpRequest(
+        method=evt.get("httpMethod") or rc.get("httpMethod") or "GET",
+        path=evt.get("path") or rc.get("path") or "/",
+        headers=Headers(evt.get("headers") or {}),
+        query=query,
+        multi_query=multi,
+        path_params={k: str(v) for k, v in (evt.get("pathParameters") or {}).items()},
+        body=HttpRequest.decode_body(evt.get("body"), bool(evt.get("isBase64Encoded"))),
+        source_ip=rc.get("sourceIp"),
+    )
+
+
+def _cos(evt: Dict[str, Any], fn: str) -> Event:
+    records = []
+    for r in evt.get("Records") or []:
+        cos = r.get("cos") or {}
+        obj = cos.get("cosObject") or {}
+        bucket = (cos.get("cosBucket") or {}).get("name")
+        key = obj.get("key") or ""
+        # COS keys look like "/<appid>/<bucket>/<path>"; strip that prefix.
+        parts = key.lstrip("/").split("/", 2)
+        if len(parts) == 3 and parts[0].isdigit():
+            key = parts[2]
+        event_name = (r.get("event") or {}).get("eventName", "")
+        records.append(
+            Record(
+                id=(obj.get("meta") or {}).get("x-cos-request-id"),
+                bucket=bucket,
+                key=unquote_plus(key),
+                size=obj.get("size"),
+                action=action_from(event_name),
+                attributes={"event_name": event_name, "url": obj.get("url")},
+                source="cos",
+                raw=r,
+            )
+        )
+    first = (evt.get("Records") or [{}])[0]
+    return Event(
+        type=EventType.STORAGE,
+        provider=PROVIDER,
+        function=fn,
+        records=records,
+        source="cos",
+        time=parse_time((first.get("event") or {}).get("eventTime")),
+        raw=evt,
+    )
+
+
+def to_event(native: Any, ctx: Any = None) -> Event:
+    fn = function_name(_ctx_get(ctx, "function_name", "") or "")
+    evt = maybe_json(native)
+    wrapped = unwrap_envelope(evt)
+    if wrapped is not None:
+        kind, data, meta = wrapped
+        return Event(type=kind, provider=PROVIDER, function=fn, data=data, source=meta.get("source"), raw=evt)
+    if isinstance(evt, dict):
+        if "httpMethod" in evt and ("requestContext" in evt or "path" in evt):
+            return Event(type=EventType.HTTP, provider=PROVIDER, function=fn, http=_http(evt), raw=evt)
+        if evt.get("Type") == "Timer":
+            message = evt.get("Message")
+            inner = unwrap_envelope(message) if message else None
+            return Event(
+                type=EventType.SCHEDULE,
+                provider=PROVIDER,
+                function=fn,
+                data=inner[1] if inner else (maybe_json(message) if message else None),
+                time=parse_time(evt.get("Time")),
+                source=evt.get("TriggerName"),
+                raw=evt,
+            )
+        records = evt.get("Records")
+        if isinstance(records, list) and records and isinstance(records[0], dict) and "cos" in records[0]:
+            return _cos(evt, fn)
+    return Event(type=EventType.INVOKE, provider=PROVIDER, function=fn, data=evt, raw=native)
+
+
+def to_context(ctx: Any, fn: str) -> Context:
+    if ctx is None:
+        return Context(function=fn, provider=PROVIDER)
+    limit_ms = _ctx_get(ctx, "time_limit_in_ms")
+    memory = _ctx_get(ctx, "memory_limit_in_mb")
+    return Context(
+        request_id=str(_ctx_get(ctx, "request_id", "") or ""),
+        function=fn,
+        provider=PROVIDER,
+        memory_mb=int(memory) if memory else None,
+        deadline=(time.time() + float(limit_ms) / 1000.0) if limit_ms else None,
+        raw=ctx,
+    )
+
+
+def to_native(result: Any, event: Event) -> Any:
+    if event.http is not None:
+        resp: Response = result
+        status, headers, body, is_b64 = resp.render_for_gateway()
+        if resp.cookies:
+            headers["set-cookie"] = resp.cookies[0] if len(resp.cookies) == 1 else ", ".join(resp.cookies)
+        return {"isBase64Encoded": is_b64, "statusCode": status, "headers": headers, "body": body}
+    return result
+
+
+def main_handler(native: Any, ctx: Any = None) -> Any:
+    """SCF entrypoint - the generated ``index.main_handler`` points here."""
+    event = to_event(native, ctx)
+    context = to_context(ctx, event.function)
+    return to_native(execute(event, context), event)
+
+
+handler = main_handler

py_serverless_kit/runtime/batch.py

@@ -0,0 +1,47 @@
+"""Partial batch failure reporting for queue / topic / storage events."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable, List, Optional, Union
+
+from .event import Record
+
+
+class BatchFailure(Exception):
+    """Raised on providers without partial-batch support so the whole batch retries."""
+
+    def __init__(self, failed_ids: List[str]) -> None:
+        self.failed_ids = failed_ids
+        super().__init__(f"{len(failed_ids)} record(s) failed: {', '.join(failed_ids[:10])}")
+
+
+@dataclass
+class BatchResult:
+    """Return this from a batch handler to retry only the records that failed.
+
+    On AWS SQS it becomes ``batchItemFailures``; on every other provider any
+    failure makes the whole invocation fail (and therefore retry).
+    """
+
+    failed: List[str] = field(default_factory=list)
+
+    def fail(self, record: Union[Record, str]) -> None:
+        rid: Optional[str] = record.id if isinstance(record, Record) else record
+        if rid is not None:
+            self.failed.append(rid)
+
+    @classmethod
+    def of(cls, failed: Iterable[Union[Record, str]]) -> BatchResult:
+        result = cls()
+        for item in failed:
+            result.fail(item)
+        return result
+
+    @property
+    def ok(self) -> bool:
+        return not self.failed
+
+    def raise_if_failed(self) -> None:
+        if self.failed:
+            raise BatchFailure(self.failed)

py_serverless_kit/runtime/context.py

@@ -0,0 +1,45 @@
+"""Provider-neutral invocation context."""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, Optional
+
+from .log import get_logger
+
+
+@dataclass
+class Context:
+    request_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    function: str = ""
+    provider: str = "local"
+    service: str = field(default_factory=lambda: os.environ.get("PSKIT_SERVICE", ""))
+    stage: str = field(default_factory=lambda: os.environ.get("PSKIT_STAGE", ""))
+    region: str = field(default_factory=lambda: os.environ.get("PSKIT_REGION", ""))
+    memory_mb: Optional[int] = None
+    deadline: Optional[float] = None  # unix epoch seconds
+    raw: Any = None
+    _remaining: Optional[Callable[[], int]] = field(default=None, repr=False)
+    _logger: Optional[logging.LoggerAdapter] = field(default=None, repr=False)
+
+    @property
+    def env(self) -> Mapping[str, str]:
+        return os.environ
+
+    @property
+    def logger(self) -> logging.LoggerAdapter:
+        if self._logger is None:
+            self._logger = get_logger(function=self.function, request_id=self.request_id, provider=self.provider)
+        return self._logger
+
+    def remaining_time_ms(self) -> Optional[int]:
+        """Milliseconds until the platform kills this invocation, if known."""
+        if self._remaining is not None:
+            return int(self._remaining())
+        if self.deadline is not None:
+            return max(0, int((self.deadline - time.time()) * 1000))
+        return None

py_serverless_kit/runtime/dispatch.py

@@ -0,0 +1,277 @@
+"""Calls the user's handler with a normalized event and normalizes the result.
+
+This is the single choke-point shared by every provider adapter, so behaviour
+(error mapping, CORS, routing, logging) is identical on every cloud.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import inspect
+import os
+import sys
+import time
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from .batch import BatchResult
+from .context import Context
+from .errors import HandlerNotFound, HttpError
+from .event import Event, EventType
+from .log import get_logger
+from .manifest import FunctionSpec, Route, resolve_function
+from .response import Response, to_response
+from .routing import match_path, method_matches
+
+_HANDLERS: Dict[str, Tuple[Callable[..., Any], int]] = {}
+_log = get_logger("pskit.runtime")
+
+DEFAULT_CORS = {
+    "origins": ["*"],
+    "methods": ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+    "headers": ["Content-Type", "Authorization", "X-Requested-With"],
+    "expose_headers": [],
+    "allow_credentials": False,
+    "max_age": 600,
+}
+
+
+def _ensure_bundle_on_path() -> None:
+    # <bundle>/py_serverless_kit/runtime/dispatch.py -> make <bundle> importable.
+    root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    if root not in sys.path:
+        sys.path.insert(0, root)
+
+
+def resolve_handler(path: str) -> Tuple[Callable[..., Any], int]:
+    """Import ``package.module.function`` (or ``package.module:function``).
+
+    Returns the callable and how many positional args it accepts (1 or 2).
+    """
+    cached = _HANDLERS.get(path)
+    if cached is not None:
+        return cached
+    if ":" in path:
+        module_name, _, attr = path.partition(":")
+    else:
+        module_name, _, attr = path.rpartition(".")
+    if not module_name or not attr:
+        raise HandlerNotFound(f"Handler {path!r} must look like 'package.module.function'")
+    _ensure_bundle_on_path()
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as exc:
+        raise HandlerNotFound(f"Cannot import module {module_name!r} for handler {path!r}: {exc}") from exc
+    target: Any = module
+    for part in attr.split("."):
+        target = getattr(target, part, None)
+        if target is None:
+            raise HandlerNotFound(f"Module {module_name!r} has no attribute {attr!r}")
+    if not callable(target):
+        raise HandlerNotFound(f"Handler {path!r} is not callable")
+    arity = 2
+    try:
+        params = [
+            p
+            for p in inspect.signature(target).parameters.values()
+            if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD, p.VAR_POSITIONAL)
+        ]
+        if len(params) == 1 and params[0].kind != params[0].VAR_POSITIONAL:
+            arity = 1
+    except (TypeError, ValueError):
+        pass
+    _HANDLERS[path] = (target, arity)
+    return target, arity
+
+
+# ---------------------------------------------------------------- routing / CORS
+
+
+def _select_route(spec: FunctionSpec, event: Event) -> Tuple[Optional[Route], Optional[Response]]:
+    """Match the request against configured routes, filling ``path_params``.
+
+    Returns ``(route, early_response)``; ``early_response`` is a 405 when the
+    path matched but no route allows the method.
+    """
+    req = event.http
+    if req is None or not spec.routes:
+        return None, None
+    path_matched: Optional[Route] = None
+    # Exact matches win over tolerant ones (e.g. GET /hello vs GET /hello/{name}).
+    for tolerant in (False, True):
+        for route in spec.routes:
+            params = match_path(route.path, req.path, tolerant=tolerant)
+            if params is None:
+                continue
+            path_matched = path_matched or route
+            if method_matches(route.method, req.method) or req.method == "OPTIONS":
+                if not req.path_params:
+                    req.path_params = params
+                req.route = route.path
+                return route, None
+        if path_matched is not None:
+            break
+    if path_matched is not None:
+        allowed = sorted({r.method.upper() for r in spec.routes if match_path(r.path, req.path) is not None})
+        resp = Response.json({"error": "Method Not Allowed", "status": 405}, 405, {"allow": ", ".join(allowed)})
+        return path_matched, resp
+    return None, None
+
+
+def _cors_config(route: Optional[Route], spec: FunctionSpec) -> Optional[Dict[str, Any]]:
+    cors = route.cors if route is not None else next((r.cors for r in spec.routes if r.cors), None)
+    if not cors:
+        return None
+    merged = dict(DEFAULT_CORS)
+    if isinstance(cors, dict):
+        merged.update({k: v for k, v in cors.items() if v is not None})
+    return merged
+
+
+def _apply_cors(resp: Response, cors: Dict[str, Any], origin: Optional[str], preflight: bool) -> Response:
+    origins = cors.get("origins") or ["*"]
+    if "*" in origins and not cors.get("allow_credentials"):
+        allow_origin = "*"
+    elif origin and (origin in origins or "*" in origins):
+        allow_origin = origin
+    else:
+        return resp
+    headers = {"access-control-allow-origin": allow_origin}
+    if allow_origin != "*":
+        headers["vary"] = "Origin"
+    if cors.get("allow_credentials"):
+        headers["access-control-allow-credentials"] = "true"
+    if cors.get("expose_headers"):
+        headers["access-control-expose-headers"] = ", ".join(cors["expose_headers"])
+    if preflight:
+        headers["access-control-allow-methods"] = ", ".join(cors.get("methods") or [])
+        headers["access-control-allow-headers"] = ", ".join(cors.get("headers") or [])
+        headers["access-control-max-age"] = str(cors.get("max_age", 600))
+    for key, value in headers.items():
+        resp.headers.setdefault(key, value)
+    return resp
+
+
+# ---------------------------------------------------------------- execution
+
+
+def _error_response(exc: BaseException, context: Context) -> Response:
+    if isinstance(exc, HttpError):
+        return Response.json(exc.to_body(), exc.status, exc.headers)
+    body: Dict[str, Any] = {"error": "Internal Server Error", "status": 500, "request_id": context.request_id}
+    if os.environ.get("PSKIT_DEBUG", "").lower() in ("1", "true", "yes"):
+        body["detail"] = f"{type(exc).__name__}: {exc}"
+    return Response.json(body, 500)
+
+
+class _Prepared:
+    __slots__ = ("spec", "route", "cors", "early", "started")
+
+    def __init__(self) -> None:
+        self.spec: Optional[FunctionSpec] = None
+        self.route: Optional[Route] = None
+        self.cors: Optional[Dict[str, Any]] = None
+        self.early: Optional[Response] = None
+        self.started = time.perf_counter()
+
+
+def _prepare(event: Event, context: Context, function: Optional[str]) -> _Prepared:
+    prep = _Prepared()
+    spec = resolve_function(function or event.function or None)
+    prep.spec = spec
+    event.function = event.function or spec.name
+    context.function = context.function or spec.name
+    if event.http is not None:
+        prep.route, prep.early = _select_route(spec, event)
+        prep.cors = _cors_config(prep.route, spec)
+        if prep.early is None and prep.cors and event.http.method == "OPTIONS":
+            prep.early = Response(204, "")
+    return prep
+
+
+def _finish(prep: _Prepared, event: Event, context: Context, result: Any, error: Optional[BaseException]) -> Any:
+    elapsed_ms = round((time.perf_counter() - prep.started) * 1000, 2)
+    if event.http is None:
+        if error is not None:
+            context.logger.error(
+                "handler failed",
+                exc_info=(type(error), error, error.__traceback__),
+                extra={"event_type": event.type, "duration_ms": elapsed_ms},
+            )
+            raise error
+        context.logger.debug("handler ok", extra={"event_type": event.type, "duration_ms": elapsed_ms})
+        # AWS reports partial failures natively; local runs show them; elsewhere the
+        # whole batch must fail so the platform redelivers it.
+        if isinstance(result, BatchResult) and event.provider not in ("aws", "local"):
+            result.raise_if_failed()
+            return None
+        return result
+    if error is not None:
+        if not isinstance(error, HttpError) or error.status >= 500:
+            context.logger.error(
+                "handler failed",
+                exc_info=(type(error), error, error.__traceback__),
+                extra={"method": event.http.method, "path": event.http.path},
+            )
+        resp = _error_response(error, context)
+    else:
+        resp = to_response(result)
+    if prep.cors:
+        _apply_cors(resp, prep.cors, event.http.headers.get("origin"), event.http.method == "OPTIONS")
+    context.logger.info(
+        "request",
+        extra={
+            "method": event.http.method,
+            "path": event.http.path,
+            "status": resp.status,
+            "duration_ms": elapsed_ms,
+        },
+    )
+    return resp
+
+
+def execute(event: Event, context: Context, function: Optional[str] = None) -> Any:
+    """Run the handler synchronously.
+
+    For HTTP events always returns a :class:`Response`; for everything else
+    returns the handler's raw result and lets exceptions propagate so the
+    platform's retry policy applies.
+    """
+    prep = _prepare(event, context, function)
+    if prep.early is not None:
+        return _finish(prep, event, context, prep.early, None)
+    try:
+        fn, arity = resolve_handler(prep.spec.handler)  # type: ignore[union-attr]
+        result = fn(event) if arity == 1 else fn(event, context)
+        if inspect.isawaitable(result):
+            result = asyncio.run(_await(result))
+    except BaseException as exc:  # noqa: BLE001 - re-raised for non-HTTP events
+        if isinstance(exc, (KeyboardInterrupt, SystemExit)):
+            raise
+        return _finish(prep, event, context, None, exc)
+    return _finish(prep, event, context, result, None)
+
+
+async def execute_async(event: Event, context: Context, function: Optional[str] = None) -> Any:
+    """Async variant for runtimes that already run an event loop (Cloudflare, Azure async)."""
+    prep = _prepare(event, context, function)
+    if prep.early is not None:
+        return _finish(prep, event, context, prep.early, None)
+    try:
+        fn, arity = resolve_handler(prep.spec.handler)  # type: ignore[union-attr]
+        result = fn(event) if arity == 1 else fn(event, context)
+        if inspect.isawaitable(result):
+            result = await result
+    except BaseException as exc:  # noqa: BLE001
+        if isinstance(exc, (KeyboardInterrupt, SystemExit)):
+            raise
+        return _finish(prep, event, context, None, exc)
+    return _finish(prep, event, context, result, None)
+
+
+async def _await(awaitable: Any) -> Any:
+    return await awaitable
+
+
+def is_http(event: Event) -> bool:
+    return event.type == EventType.HTTP

py_serverless_kit/runtime/errors.py

@@ -0,0 +1,83 @@
+"""Exceptions a handler can raise to produce a well-formed HTTP error response.
+
+For non-HTTP events these are re-raised so the platform's retry / dead-letter
+semantics apply unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class PskitError(Exception):
+    """Base class for runtime errors raised by the kit itself."""
+
+
+class HandlerNotFound(PskitError):
+    """The configured ``module.function`` handler could not be imported."""
+
+
+class HttpError(Exception):
+    status: int = 500
+    default_message: str = "Internal Server Error"
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        *,
+        status: Optional[int] = None,
+        details: Any = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self.message = message or self.default_message
+        if status is not None:
+            self.status = status
+        self.details = details
+        self.headers = dict(headers or {})
+        super().__init__(self.message)
+
+    def to_body(self) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"error": self.message, "status": self.status}
+        if self.details is not None:
+            body["details"] = self.details
+        return body
+
+
+class BadRequest(HttpError):
+    status = 400
+    default_message = "Bad Request"
+
+
+class Unauthorized(HttpError):
+    status = 401
+    default_message = "Unauthorized"
+
+
+class Forbidden(HttpError):
+    status = 403
+    default_message = "Forbidden"
+
+
+class NotFound(HttpError):
+    status = 404
+    default_message = "Not Found"
+
+
+class MethodNotAllowed(HttpError):
+    status = 405
+    default_message = "Method Not Allowed"
+
+
+class Conflict(HttpError):
+    status = 409
+    default_message = "Conflict"
+
+
+class UnprocessableEntity(HttpError):
+    status = 422
+    default_message = "Unprocessable Entity"
+
+
+class TooManyRequests(HttpError):
+    status = 429
+    default_message = "Too Many Requests"