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

py_serverless_kit/runtime/response.py

@@ -0,0 +1,177 @@
+"""Provider-neutral HTTP response model."""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from decimal import Decimal
+from typing import Any, Dict, List, Optional, Tuple
+from uuid import UUID
+
+_TEXT_PREFIXES = ("text/",)
+_TEXT_TYPES = (
+    "application/json",
+    "application/xml",
+    "application/javascript",
+    "application/x-www-form-urlencoded",
+    "image/svg+xml",
+)
+
+
+def json_default(value: Any) -> Any:
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    if isinstance(value, Decimal):
+        return int(value) if value == value.to_integral_value() else float(value)
+    if isinstance(value, (UUID, bytes)):
+        return value.decode("utf-8", "replace") if isinstance(value, bytes) else str(value)
+    if isinstance(value, (set, frozenset)):
+        return sorted(value)
+    if hasattr(value, "model_dump"):  # pydantic v2
+        return value.model_dump()
+    if hasattr(value, "to_dict"):
+        return value.to_dict()
+    if hasattr(value, "__dataclass_fields__"):
+        from dataclasses import asdict
+
+        return asdict(value)
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+def dumps(value: Any) -> str:
+    return json.dumps(value, default=json_default, separators=(",", ":"))
+
+
+def is_text_content_type(content_type: str) -> bool:
+    ct = content_type.split(";")[0].strip().lower()
+    return ct.startswith(_TEXT_PREFIXES) or ct in _TEXT_TYPES or ct.endswith("+json")
+
+
+@dataclass
+class Response:
+    status: int = 200
+    body: Any = None
+    headers: Dict[str, str] = field(default_factory=dict)
+    cookies: List[str] = field(default_factory=list)
+
+    # ---- constructors -------------------------------------------------
+    @classmethod
+    def json(cls, data: Any, status: int = 200, headers: Optional[Dict[str, str]] = None) -> Response:
+        return cls(status, dumps(data), {"content-type": "application/json", **(headers or {})})
+
+    @classmethod
+    def text(cls, text: str, status: int = 200, headers: Optional[Dict[str, str]] = None) -> Response:
+        return cls(status, text, {"content-type": "text/plain; charset=utf-8", **(headers or {})})
+
+    @classmethod
+    def html(cls, html: str, status: int = 200, headers: Optional[Dict[str, str]] = None) -> Response:
+        return cls(status, html, {"content-type": "text/html; charset=utf-8", **(headers or {})})
+
+    @classmethod
+    def binary(
+        cls,
+        data: bytes,
+        content_type: str = "application/octet-stream",
+        status: int = 200,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Response:
+        return cls(status, bytes(data), {"content-type": content_type, **(headers or {})})
+
+    @classmethod
+    def redirect(cls, location: str, status: int = 302) -> Response:
+        return cls(status, "", {"location": location})
+
+    @classmethod
+    def no_content(cls) -> Response:
+        return cls(204, "")
+
+    # ---- helpers ------------------------------------------------------
+    def set_cookie(
+        self,
+        name: str,
+        value: str,
+        *,
+        max_age: Optional[int] = None,
+        path: str = "/",
+        http_only: bool = True,
+        secure: bool = True,
+        same_site: str = "Lax",
+    ) -> Response:
+        parts = [f"{name}={value}", f"Path={path}", f"SameSite={same_site}"]
+        if max_age is not None:
+            parts.append(f"Max-Age={max_age}")
+        if http_only:
+            parts.append("HttpOnly")
+        if secure:
+            parts.append("Secure")
+        self.cookies.append("; ".join(parts))
+        return self
+
+    @property
+    def content_type(self) -> str:
+        for key, value in self.headers.items():
+            if key.lower() == "content-type":
+                return value
+        return ""
+
+    def render(self) -> Tuple[int, Dict[str, str], bytes]:
+        """Return ``(status, headers, body_bytes)`` with lower-cased header names
+        and a content-type guaranteed to be set when there is a body."""
+        headers = {k.lower(): str(v) for k, v in self.headers.items()}
+        body = self.body
+        if body is None:
+            raw = b""
+        elif isinstance(body, bytes):
+            raw = body
+            if raw:
+                headers.setdefault("content-type", "application/octet-stream")
+        elif isinstance(body, str):
+            raw = body.encode("utf-8")
+            if raw:
+                headers.setdefault("content-type", "text/plain; charset=utf-8")
+        else:
+            raw = dumps(body).encode("utf-8")
+            headers.setdefault("content-type", "application/json")
+        return int(self.status), headers, raw
+
+    def render_for_gateway(self) -> Tuple[int, Dict[str, str], str, bool]:
+        """Like :meth:`render` but returns a ``str`` body plus an ``is_base64`` flag,
+        which is what API-gateway style integrations expect."""
+        status, headers, raw = self.render()
+        if not raw:
+            return status, headers, "", False
+        if is_text_content_type(headers.get("content-type", "")):
+            try:
+                return status, headers, raw.decode("utf-8"), False
+            except UnicodeDecodeError:
+                pass
+        return status, headers, base64.b64encode(raw).decode("ascii"), True
+
+
+def to_response(result: Any) -> Response:
+    """Coerce whatever a handler returned into a :class:`Response`.
+
+    * ``Response``                    -> unchanged
+    * ``None``                        -> 204 No Content
+    * ``dict`` / ``list`` / numbers   -> JSON 200
+    * ``str``                         -> text/plain 200
+    * ``bytes``                       -> application/octet-stream 200
+    * ``(body, status)`` / ``(body, status, headers)`` -> Flask-style tuple
+    """
+    if isinstance(result, Response):
+        return result
+    if result is None:
+        return Response.no_content()
+    if isinstance(result, tuple) and 2 <= len(result) <= 3 and isinstance(result[1], int):
+        base = to_response(result[0])
+        base.status = result[1]
+        if len(result) == 3 and result[2]:
+            base.headers.update(result[2])
+        return base
+    if isinstance(result, bytes):
+        return Response.binary(result)
+    if isinstance(result, str):
+        return Response.text(result)
+    return Response.json(result)

py_serverless_kit/runtime/routing.py

@@ -0,0 +1,74 @@
+"""Tiny route matcher used where the provider has no API gateway in front of the
+function (GCP, IBM, DigitalOcean, Cloudflare, ...) and by the local dev server.
+
+Patterns use ``{name}`` for one segment and ``{name+}`` for a greedy tail,
+the same syntax as AWS API Gateway, Azure Functions and the YAML config.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Sequence
+
+
+def split_path(path: str) -> List[str]:
+    return [seg for seg in path.split("?")[0].split("/") if seg]
+
+
+def _is_param(seg: str) -> bool:
+    return seg.startswith("{") and seg.endswith("}")
+
+
+def _match_segments(pattern: Sequence[str], parts: Sequence[str]) -> Optional[Dict[str, str]]:
+    params: Dict[str, str] = {}
+    for i, seg in enumerate(pattern):
+        if _is_param(seg):
+            name = seg[1:-1]
+            if name.endswith("+"):
+                if i != len(pattern) - 1 or i >= len(parts):
+                    return None
+                params[name[:-1]] = "/".join(parts[i:])
+                return params
+            if i >= len(parts):
+                return None
+            params[name] = parts[i]
+        elif i >= len(parts) or seg != parts[i]:
+            return None
+    return params if len(parts) == len(pattern) else None
+
+
+def match_path(pattern: str, path: str, *, tolerant: bool = True) -> Optional[Dict[str, str]]:
+    """Return path params if ``path`` matches ``pattern`` else ``None``.
+
+    With ``tolerant=True`` two platform quirks are accepted as well:
+
+    * the platform *prepended* a fixed prefix (Azure ``/api/users/7``) - the
+      whole pattern must then match the tail of the path;
+    * the platform *stripped* the pattern's leading static segments (GCP serves
+      ``/users/{id}`` at ``https://.../fn-name/7``) - the remaining
+      pattern must then match the whole path.
+    """
+    pat = split_path(pattern)
+    parts = split_path(path)
+    exact = _match_segments(pat, parts)
+    if exact is not None or not tolerant:
+        return exact
+    if any(not _is_param(seg) for seg in pat):
+        for drop in range(1, len(parts)):
+            got = _match_segments(pat, parts[drop:])
+            if got is not None:
+                return got
+    leading_static = 0
+    for seg in pat:
+        if _is_param(seg):
+            break
+        leading_static += 1
+    if leading_static:
+        rest = pat[leading_static:]
+        if rest or not parts:
+            return _match_segments(rest, parts)
+    return None
+
+
+def method_matches(allowed: str, method: str) -> bool:
+    allowed = allowed.upper()
+    return allowed in ("ANY", "*") or allowed == method.upper()

py_serverless_kit/runtime/workflow.py

@@ -0,0 +1,312 @@
+"""Embedded workflow (state machine) engine.
+
+The same definition the CLI compiles to AWS Step Functions (ASL) or Google
+Cloud Workflows is interpreted here for:
+
+* ``pskit workflow run --local`` - test workflows on your laptop;
+* providers without a native orchestrator - the CLI deploys an extra
+  *orchestrator* function whose handler is :func:`orchestrate`, and which calls
+  task handlers in-process (they live in the same bundle).
+
+Supported state types: task, choice, wait, pass, parallel, map, succeed, fail.
+"""
+
+from __future__ import annotations
+
+import copy
+import fnmatch
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional
+
+from .context import Context
+from .event import Event, EventType
+from .response import Response
+
+TaskRunner = Callable[[str, Any], Any]
+ALL_ERRORS = ("*", "States.ALL")
+
+
+class WorkflowFailed(Exception):
+    def __init__(self, error: str, cause: str = "", history: Optional[List[Dict[str, Any]]] = None) -> None:
+        self.error = error
+        self.cause = cause
+        self.history = history or []
+        super().__init__(f"{error}: {cause}" if cause else error)
+
+
+# --------------------------------------------------------------------- JSON path
+
+
+def _tokens(path: str) -> List[Any]:
+    if path in ("$", "", None):
+        return []
+    if not path.startswith("$"):
+        raise ValueError(f"JSON path must start with '$': {path!r}")
+    tokens: List[Any] = []
+    for part in path[1:].replace("[", ".[").split("."):
+        if not part:
+            continue
+        if part.startswith("[") and part.endswith("]"):
+            inner = part[1:-1].strip("'\"")
+            tokens.append(int(inner) if inner.lstrip("-").isdigit() else inner)
+        else:
+            tokens.append(part)
+    return tokens
+
+
+_MISSING = object()  # "no default given" marker for get_path
+_ABSENT = object()  # "path not present" value used by choice rules
+
+
+def get_path(data: Any, path: str, default: Any = _MISSING) -> Any:
+    current = data
+    for tok in _tokens(path):
+        try:
+            current = current[tok]
+        except (KeyError, IndexError, TypeError):
+            if default is _MISSING:
+                raise KeyError(path) from None
+            return default
+    return current
+
+
+def set_path(data: Any, path: Optional[str], value: Any) -> Any:
+    """Return ``data`` with ``value`` written at ``path`` (``$`` replaces; ``None`` discards)."""
+    if path is None:
+        return data
+    tokens = _tokens(path)
+    if not tokens:
+        return value
+    root = copy.deepcopy(data) if isinstance(data, (dict, list)) else {}
+    current = root
+    for tok in tokens[:-1]:
+        if isinstance(current, dict):
+            current = current.setdefault(tok, {})
+        else:
+            current = current[tok]
+    current[tokens[-1]] = value
+    return root
+
+
+# --------------------------------------------------------------------- choice
+
+
+_OPS: Dict[str, Callable[[Any, Any], bool]] = {
+    "equals": lambda a, b: a == b,
+    "not_equals": lambda a, b: a != b,
+    "gt": lambda a, b: a is not None and a > b,
+    "gte": lambda a, b: a is not None and a >= b,
+    "lt": lambda a, b: a is not None and a < b,
+    "lte": lambda a, b: a is not None and a <= b,
+    "in": lambda a, b: a in b,
+    "contains": lambda a, b: a is not None and b in a,
+    "matches": lambda a, b: isinstance(a, str) and fnmatch.fnmatchcase(a, b),
+    "is_null": lambda a, b: (a is None) == bool(b),
+    "is_present": lambda a, b: (a is not _ABSENT) == bool(b),
+}
+CHOICE_OPERATORS = tuple(_OPS)
+
+
+def evaluate_rule(rule: Dict[str, Any], data: Any) -> bool:
+    if "and" in rule:
+        return all(evaluate_rule(r, data) for r in rule["and"])
+    if "or" in rule:
+        return any(evaluate_rule(r, data) for r in rule["or"])
+    if "not" in rule:
+        return not evaluate_rule(rule["not"], data)
+    variable = rule.get("variable", "$")
+    for op, fn in _OPS.items():
+        if op in rule:
+            value = get_path(data, variable, _ABSENT)
+            if op == "is_present":
+                return fn(value, rule[op])
+            if value is _ABSENT:
+                return False
+            try:
+                return bool(fn(value, rule[op]))
+            except TypeError:
+                return False
+    raise ValueError(f"Choice rule has no operator (one of {', '.join(_OPS)}): {rule}")
+
+
+# --------------------------------------------------------------------- engine
+
+
+def _error_name(exc: BaseException) -> str:
+    return getattr(exc, "error", None) or type(exc).__name__
+
+
+def _matches(errors: List[str], name: str) -> bool:
+    return any(e in ALL_ERRORS or e == name for e in (errors or ["*"]))
+
+
+@dataclass
+class WorkflowEngine:
+    definition: Dict[str, Any]
+    task_runner: TaskRunner
+    sleep: Callable[[float], None] = time.sleep
+    max_steps: int = 10_000
+    history: List[Dict[str, Any]] = field(default_factory=list)
+
+    def run(self, data: Any = None) -> Any:
+        return self._run_machine(self.definition, data)
+
+    # ------------------------------------------------------------------
+    def _record(self, state: str, kind: str, **extra: Any) -> None:
+        self.history.append({"ts": datetime.now(timezone.utc).isoformat(), "state": state, "type": kind, **extra})
+
+    def _run_machine(self, machine: Dict[str, Any], data: Any) -> Any:
+        states: Dict[str, Dict[str, Any]] = machine["states"]
+        name: Optional[str] = machine["start_at"]
+        steps = 0
+        while name is not None:
+            steps += 1
+            if steps > self.max_steps:
+                raise WorkflowFailed("States.Runtime", f"exceeded {self.max_steps} steps", self.history)
+            state = states[name]
+            kind = state["type"]
+            self._record(name, kind, event="enter")
+            if kind == "succeed":
+                return data
+            if kind == "fail":
+                raise WorkflowFailed(state.get("error", "States.Fail"), state.get("cause", ""), self.history)
+            if kind == "choice":
+                name = self._choose(state, data)
+                continue
+            try:
+                data = self._execute(state, data)
+            except WorkflowFailed:
+                raise
+            except Exception as exc:  # noqa: BLE001 - mapped onto catch rules
+                handler = next(
+                    (c for c in state.get("catch") or [] if _matches(c.get("errors", ["*"]), _error_name(exc))),
+                    None,
+                )
+                if handler is None:
+                    raise WorkflowFailed(_error_name(exc), str(exc), self.history) from exc
+                self._record(name, kind, event="caught", error=_error_name(exc))
+                info = {"error": _error_name(exc), "cause": str(exc)}
+                data = set_path(data, handler.get("result_path", "$.error"), info)
+                name = handler["next"]
+                continue
+            if state.get("end") or not state.get("next"):
+                return data
+            name = state["next"]
+        return data
+
+    def _choose(self, state: Dict[str, Any], data: Any) -> str:
+        for rule in state.get("choices") or []:
+            if evaluate_rule(rule, data):
+                return rule["next"]
+        if state.get("default"):
+            return state["default"]
+        raise WorkflowFailed("States.NoChoiceMatched", "no choice rule matched and no default", self.history)
+
+    def _execute(self, state: Dict[str, Any], data: Any) -> Any:
+        kind = state["type"]
+        input_data = get_path(data, state["input_path"]) if state.get("input_path") else data
+        if kind == "task":
+            result = self._with_retry(state, lambda: self.task_runner(state["function"], input_data))
+        elif kind == "pass":
+            result = state.get("result", input_data)
+        elif kind == "wait":
+            if state.get("seconds_path"):
+                seconds = float(get_path(data, state["seconds_path"]))
+            else:
+                seconds = float(state.get("seconds", 0))
+            self.sleep(seconds)
+            result = input_data
+        elif kind == "parallel":
+            branches = state.get("branches") or []
+
+            def run_branch(branch: Dict[str, Any]) -> Any:
+                return self._run_machine(branch, copy.deepcopy(input_data))
+
+            with ThreadPoolExecutor(max_workers=max(1, len(branches))) as pool:
+                result = list(pool.map(run_branch, branches))
+        elif kind == "map":
+            items = get_path(input_data, state.get("items_path", "$"))
+            if not isinstance(items, list):
+                raise TypeError(f"map items_path did not resolve to a list: {type(items).__name__}")
+            iterator = state["iterator"]
+            workers = int(state.get("max_concurrency") or 0) or min(32, max(1, len(items)))
+            with ThreadPoolExecutor(max_workers=workers) as pool:
+                result = list(pool.map(lambda item: self._run_machine(iterator, item), items))
+        else:
+            raise WorkflowFailed("States.Runtime", f"unknown state type {kind!r}", self.history)
+        return set_path(data, state.get("result_path", "$"), result)
+
+    def _with_retry(self, state: Dict[str, Any], call: Callable[[], Any]) -> Any:
+        attempts: Dict[int, int] = {}
+        while True:
+            try:
+                return call()
+            except Exception as exc:  # noqa: BLE001
+                name = _error_name(exc)
+                rules = state.get("retry") or []
+                # Like ASL, the first retrier whose errors match is the one used.
+                idx = next((i for i, r in enumerate(rules) if _matches(r.get("errors", ["*"]), name)), None)
+                if idx is None:
+                    raise
+                rule = rules[idx]
+                count = attempts.get(idx, 0)
+                if count >= int(rule.get("max_attempts", 3)):
+                    raise
+                attempts[idx] = count + 1
+                delay = float(rule.get("interval_seconds", 1)) * float(rule.get("backoff_rate", 2.0)) ** count
+                self._record(state.get("function", "?"), "task", event="retry", attempt=count + 1, error=name)
+                self.sleep(min(delay, float(rule.get("max_delay_seconds", 300))))
+
+
+def in_process_runner(provider: str = "local") -> TaskRunner:
+    """Task runner that invokes handlers from the current bundle via the dispatcher."""
+    from .dispatch import execute
+
+    def run(function: str, data: Any) -> Any:
+        event = Event(type=EventType.WORKFLOW, provider=provider, function=function, data=data)
+        result = execute(event, Context(function=function, provider=provider), function)
+        return result
+
+    return run
+
+
+def orchestrate(event: Event, context: Context) -> Any:
+    """Handler of the auto-generated ``<workflow>-orchestrator`` function."""
+    from .manifest import load_manifest
+
+    manifest = load_manifest()
+    target = next(
+        (
+            (name, wf)
+            for name, wf in manifest.workflows.items()
+            if wf.get("orchestrator") == (event.function or context.function)
+        ),
+        None,
+    )
+    if target is None:
+        raise LookupError(f"No workflow is orchestrated by function {event.function!r}")
+    name, wf = target
+    if event.http is not None:
+        data = event.http.json(default=None) if event.http.body else dict(event.http.query)
+    else:
+        data = event.data
+    engine = WorkflowEngine(wf["definition"], in_process_runner(event.provider))
+    started = time.time()
+    try:
+        output = engine.run(data)
+    except WorkflowFailed as exc:
+        failure = {"workflow": name, "status": "FAILED", "error": exc.error, "cause": exc.cause}
+        context.logger.error("workflow failed", extra=failure)
+        if event.http is not None:
+            return Response.json(failure, 500)
+        raise
+    body: Dict[str, Any] = {
+        "workflow": name,
+        "status": "SUCCEEDED",
+        "output": output,
+        "duration_ms": round((time.time() - started) * 1000, 2),
+    }
+    return body

py_serverless_kit/terraform/__init__.py

@@ -0,0 +1,3 @@
+from .runner import TerraformError, TerraformRunner, find_binary
+
+__all__ = ["TerraformError", "TerraformRunner", "find_binary"]

py_serverless_kit/terraform/runner.py

@@ -0,0 +1,104 @@
+"""Thin, testable wrapper around the ``terraform`` / ``tofu`` binary."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+
+class TerraformError(Exception):
+    pass
+
+
+def find_binary(preferred: Optional[str] = None) -> str:
+    candidates = [c for c in (preferred, os.environ.get("PSKIT_TERRAFORM_BIN"), "terraform", "tofu") if c]
+    for cand in candidates:
+        found = shutil.which(cand)
+        if found:
+            return found
+    raise TerraformError(
+        "Neither `terraform` nor `tofu` was found on PATH. Install Terraform >= 1.5 "
+        "(https://developer.hashicorp.com/terraform/install) or OpenTofu, "
+        "or set PSKIT_TERRAFORM_BIN."
+    )
+
+
+@dataclass
+class TerraformRunner:
+    work_dir: Path
+    binary: Optional[str] = None
+    env: Optional[Dict[str, str]] = None
+    echo: Callable[[str], None] = print
+
+    def _bin(self) -> str:
+        if self.binary is None or not Path(self.binary).is_file():
+            self.binary = find_binary(self.binary)
+        return self.binary
+
+    def _run(self, args: List[str], *, capture: bool = False, check: bool = True) -> subprocess.CompletedProcess:
+        env = dict(os.environ)
+        env.setdefault("TF_IN_AUTOMATION", "1")
+        env.setdefault("TF_INPUT", "0")
+        env.update(self.env or {})
+        cmd = [self._bin(), *args]
+        if capture:
+            proc = subprocess.run(cmd, cwd=self.work_dir, env=env, capture_output=True, text=True)
+        else:
+            proc = subprocess.run(cmd, cwd=self.work_dir, env=env, text=True)
+        if check and proc.returncode != 0:
+            detail = (proc.stderr or proc.stdout or "")[-6000:] if capture else ""
+            raise TerraformError(f"`{' '.join(cmd[1:3])}` failed with exit code {proc.returncode}\n{detail}".rstrip())
+        return proc
+
+    def init(self, upgrade: bool = False, reconfigure: bool = False) -> None:
+        args = ["init", "-input=false", "-no-color"]
+        if upgrade:
+            args.append("-upgrade")
+        if reconfigure:
+            args.append("-reconfigure")
+        self._run(args)
+
+    def validate(self) -> None:
+        self._run(["validate", "-no-color"])
+
+    def plan(self, destroy: bool = False, out: Optional[str] = "tfplan") -> bool:
+        """Return ``True`` when the plan has changes."""
+        args = ["plan", "-input=false", "-no-color", "-detailed-exitcode"]
+        if destroy:
+            args.append("-destroy")
+        if out:
+            args += ["-out", out]
+        proc = self._run(args, check=False)
+        if proc.returncode == 1:
+            raise TerraformError("terraform plan failed")
+        return proc.returncode == 2
+
+    def apply(self, plan_file: Optional[str] = None, auto_approve: bool = True) -> None:
+        args = ["apply", "-input=false", "-no-color"]
+        if plan_file:
+            args.append(plan_file)
+        elif auto_approve:
+            args.append("-auto-approve")
+        self._run(args)
+
+    def destroy(self, auto_approve: bool = True) -> None:
+        args = ["destroy", "-input=false", "-no-color"]
+        if auto_approve:
+            args.append("-auto-approve")
+        self._run(args)
+
+    def output(self) -> Dict[str, Any]:
+        proc = self._run(["output", "-json", "-no-color"], capture=True)
+        try:
+            raw = json.loads(proc.stdout or "{}")
+        except ValueError as exc:
+            raise TerraformError(f"could not parse terraform output: {exc}") from exc
+        return {k: v.get("value") for k, v in raw.items()}
+
+    def passthrough(self, args: List[str]) -> int:
+        return self._run(args, check=False).returncode