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

py_serverless_kit/runtime/event.py

@@ -0,0 +1,267 @@
+"""Provider-neutral event model.
+
+Every provider adapter converts its native payload into an :class:`Event`, so a
+handler written against this module runs unchanged on any supported cloud.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterator, List, Mapping, Optional, Tuple, Union
+
+from .errors import BadRequest
+
+_MISSING = object()
+
+
+class EventType:
+    HTTP = "http"
+    SCHEDULE = "schedule"
+    QUEUE = "queue"
+    STORAGE = "storage"
+    TOPIC = "topic"
+    INVOKE = "invoke"
+    WORKFLOW = "workflow"
+
+    ALL = (HTTP, SCHEDULE, QUEUE, STORAGE, TOPIC, INVOKE, WORKFLOW)
+
+
+class Headers(Mapping[str, str]):
+    """Case-insensitive, read-only header mapping.
+
+    Multi-value headers are joined with ``", "`` (RFC 9110 section 5.3).
+    """
+
+    __slots__ = ("_data",)
+
+    def __init__(self, raw: Union[Mapping[str, Any], List[Tuple[str, Any]], None] = None) -> None:
+        self._data: Dict[str, str] = {}
+        items = raw.items() if isinstance(raw, Mapping) else (raw or [])
+        for key, value in items:
+            if value is None:
+                continue
+            if isinstance(value, (list, tuple)):
+                value = ", ".join(str(v) for v in value)
+            k = str(key).lower()
+            self._data[k] = f"{self._data[k]}, {value}" if k in self._data else str(value)
+
+    def __getitem__(self, key: str) -> str:
+        return self._data[key.lower()]
+
+    def __contains__(self, key: object) -> bool:
+        return isinstance(key, str) and key.lower() in self._data
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def get(self, key: str, default: Any = None) -> Any:  # type: ignore[override]
+        return self._data.get(key.lower(), default)
+
+    def to_dict(self) -> Dict[str, str]:
+        return dict(self._data)
+
+    def __repr__(self) -> str:
+        return f"Headers({self._data!r})"
+
+
+def _decode_json(raw: Union[str, bytes], what: str) -> Any:
+    if isinstance(raw, bytes):
+        raw = raw.decode("utf-8")
+    if raw == "":
+        raise BadRequest(f"{what} is empty, expected JSON")
+    try:
+        return json.loads(raw)
+    except ValueError as exc:
+        raise BadRequest(f"{what} is not valid JSON", details=str(exc)) from exc
+
+
+def parse_cookies(header: Optional[str]) -> Dict[str, str]:
+    cookies: Dict[str, str] = {}
+    if not header:
+        return cookies
+    for part in header.split(";"):
+        if "=" in part:
+            name, _, value = part.strip().partition("=")
+            cookies[name] = value
+    return cookies
+
+
+@dataclass
+class HttpRequest:
+    method: str = "GET"
+    path: str = "/"
+    headers: Headers = field(default_factory=Headers)
+    query: Dict[str, str] = field(default_factory=dict)
+    multi_query: Dict[str, List[str]] = field(default_factory=dict)
+    path_params: Dict[str, str] = field(default_factory=dict)
+    body: bytes = b""
+    source_ip: Optional[str] = None
+    route: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        self.method = self.method.upper()
+        if not isinstance(self.headers, Headers):
+            self.headers = Headers(self.headers)
+        if isinstance(self.body, str):
+            self.body = self.body.encode("utf-8")
+        elif self.body is None:
+            self.body = b""
+        if self.query and not self.multi_query:
+            self.multi_query = {k: [v] for k, v in self.query.items()}
+
+    @property
+    def content_type(self) -> str:
+        return self.headers.get("content-type", "").split(";")[0].strip().lower()
+
+    @property
+    def cookies(self) -> Dict[str, str]:
+        return parse_cookies(self.headers.get("cookie"))
+
+    def text(self, encoding: str = "utf-8") -> str:
+        return self.body.decode(encoding)
+
+    def json(self, default: Any = _MISSING) -> Any:
+        """Parse the body as JSON. Raises :class:`BadRequest` (HTTP 400) on bad input
+        unless ``default`` is supplied."""
+        try:
+            return _decode_json(self.body, "Request body")
+        except BadRequest:
+            if default is not _MISSING:
+                return default
+            raise
+
+    def form(self) -> Dict[str, str]:
+        from urllib.parse import parse_qsl
+
+        return dict(parse_qsl(self.text(), keep_blank_values=True))
+
+    @staticmethod
+    def decode_body(body: Any, is_base64: bool = False) -> bytes:
+        if body is None:
+            return b""
+        if isinstance(body, (dict, list)):
+            return json.dumps(body).encode("utf-8")
+        if isinstance(body, bytes):
+            return base64.b64decode(body) if is_base64 else body
+        if is_base64:
+            return base64.b64decode(body)
+        return str(body).encode("utf-8")
+
+
+@dataclass
+class Record:
+    """One message / object notification inside a batch event."""
+
+    id: Optional[str] = None
+    body: Any = None
+    attributes: Dict[str, Any] = field(default_factory=dict)
+    source: Optional[str] = None
+    # Storage-only fields.
+    bucket: Optional[str] = None
+    key: Optional[str] = None
+    size: Optional[int] = None
+    action: Optional[str] = None  # "created" | "deleted"
+    raw: Any = None
+
+    def text(self) -> str:
+        if isinstance(self.body, bytes):
+            return self.body.decode("utf-8")
+        if isinstance(self.body, (dict, list)):
+            return json.dumps(self.body)
+        return "" if self.body is None else str(self.body)
+
+    def json(self, default: Any = _MISSING) -> Any:
+        if isinstance(self.body, (dict, list)):
+            return self.body
+        try:
+            return _decode_json(self.text(), f"Record {self.id or ''} body".strip())
+        except BadRequest:
+            if default is not _MISSING:
+                return default
+            raise
+
+
+@dataclass
+class Event:
+    type: str
+    provider: str = "local"
+    function: str = ""
+    http: Optional[HttpRequest] = None
+    records: List[Record] = field(default_factory=list)
+    data: Any = None
+    time: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    source: Optional[str] = None
+    raw: Any = None
+
+    @property
+    def is_http(self) -> bool:
+        return self.type == EventType.HTTP
+
+    @property
+    def is_batch(self) -> bool:
+        return self.type in (EventType.QUEUE, EventType.TOPIC, EventType.STORAGE)
+
+    def json(self, default: Any = _MISSING) -> Any:
+        """Best-effort JSON payload regardless of event type.
+
+        * HTTP: the parsed request body
+        * queue/topic/storage: the first record's parsed body
+        * schedule/invoke/workflow: ``data``
+        """
+        if self.http is not None:
+            return self.http.json(default) if default is not _MISSING else self.http.json()
+        if self.records:
+            return self.records[0].json(default) if default is not _MISSING else self.records[0].json()
+        return self.data
+
+    def __iter__(self) -> Iterator[Record]:
+        return iter(self.records)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """JSON-friendly summary, handy for logging."""
+        out: Dict[str, Any] = {
+            "type": self.type,
+            "provider": self.provider,
+            "function": self.function,
+            "time": self.time.isoformat(),
+            "source": self.source,
+        }
+        if self.http is not None:
+            out["http"] = {
+                "method": self.http.method,
+                "path": self.http.path,
+                "query": self.http.query,
+                "path_params": self.http.path_params,
+            }
+        if self.records:
+            out["records"] = len(self.records)
+        if self.data is not None:
+            out["data"] = self.data
+        return out
+
+
+def parse_time(value: Any) -> datetime:
+    """Parse the many timestamp shapes providers emit; fall back to *now*."""
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+    if isinstance(value, (int, float)):
+        seconds = value / 1000.0 if value > 1e11 else float(value)
+        return datetime.fromtimestamp(seconds, tz=timezone.utc)
+    if isinstance(value, str) and value:
+        text = value.strip()
+        if text.isdigit():
+            return parse_time(int(text))
+        if text.endswith("Z"):
+            text = text[:-1] + "+00:00"
+        try:
+            parsed = datetime.fromisoformat(text)
+            return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+        except ValueError:
+            pass
+    return datetime.now(timezone.utc)

py_serverless_kit/runtime/invoke.py

@@ -0,0 +1,119 @@
+"""Portable function-to-function invocation.
+
+``invoke("billing", {"order": 1})`` calls another function of the *same
+service* regardless of the cloud it runs on:
+
+* ``PSKIT_ENDPOINT_<NAME>`` env var set -> HTTP POST to that URL (any provider)
+* local (CLI / tests)                   -> in-process call through the dispatcher
+* aws                                   -> ``lambda:InvokeFunction`` via boto3
+* gcp                                   -> authenticated HTTPS call (ID token from metadata server)
+
+Other providers need ``PSKIT_ENDPOINT_<NAME>`` in the caller's ``environment``
+(for example the target's HTTP URL from ``pskit info``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.request
+from typing import Any, Dict, Optional
+
+from .adapters.base import envelope
+from .manifest import load_manifest
+
+
+class InvokeError(RuntimeError):
+    pass
+
+
+def _env_key(name: str) -> str:
+    return "PSKIT_ENDPOINT_" + re.sub(r"[^A-Za-z0-9]", "_", name).upper()
+
+
+def physical_name(function: str) -> str:
+    manifest = load_manifest()
+    spec = manifest.functions.get(function)
+    if spec is not None and spec.resource_name:
+        return spec.resource_name
+    service = manifest.service or os.environ.get("PSKIT_SERVICE", "")
+    stage = manifest.stage or os.environ.get("PSKIT_STAGE", "")
+    return "-".join(p for p in (service, stage, function) if p)
+
+
+def _http_post(url: str, payload: Any, timeout: float, headers: Optional[Dict[str, str]] = None) -> Any:
+    if not url.lower().startswith(("https://", "http://")):
+        raise InvokeError(f"invoke endpoint must be an http(s) URL, got {url!r}")
+    data = json.dumps(envelope("invoke", payload)).encode("utf-8")
+    req = urllib.request.Request(url, data=data, method="POST")  # noqa: S310 - scheme checked above
+    req.add_header("content-type", "application/json")
+    for key, value in (headers or {}).items():
+        req.add_header(key, value)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 - URL is operator supplied
+            raw = resp.read()
+    except Exception as exc:  # pragma: no cover - network
+        raise InvokeError(f"HTTP invoke of {url} failed: {exc}") from exc
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except ValueError:
+        return raw.decode("utf-8", "replace")
+
+
+def _gcp_id_token(audience: str) -> str:  # pragma: no cover - needs GCP metadata server
+    url = (
+        "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity"
+        f"?audience={audience}"
+    )
+    req = urllib.request.Request(url, headers={"Metadata-Flavor": "Google"})  # noqa: S310 - fixed http URL
+    with urllib.request.urlopen(req, timeout=5) as resp:  # noqa: S310
+        return resp.read().decode("utf-8")
+
+
+def invoke(function: str, payload: Any = None, *, asynchronous: bool = False, timeout: float = 30.0) -> Any:
+    """Invoke another function of this service and return its result."""
+    override = os.environ.get(_env_key(function))
+    if override:
+        return _http_post(override, payload, timeout)
+
+    provider = os.environ.get("PSKIT_PROVIDER", "local")
+    if provider == "local":
+        from .context import Context
+        from .dispatch import execute
+        from .event import Event, EventType
+
+        event = Event(type=EventType.INVOKE, provider="local", function=function, data=payload)
+        return execute(event, Context(function=function), function)
+
+    if provider == "aws":
+        try:
+            import boto3  # type: ignore[import-not-found]
+        except ImportError as exc:  # pragma: no cover
+            raise InvokeError("boto3 is required for invoke() on AWS") from exc
+        client = boto3.client("lambda")
+        resp = client.invoke(
+            FunctionName=physical_name(function),
+            InvocationType="Event" if asynchronous else "RequestResponse",
+            Payload=json.dumps(envelope("invoke", payload)).encode("utf-8"),
+        )
+        if asynchronous:
+            return None
+        body = resp["Payload"].read()
+        if resp.get("FunctionError"):
+            raise InvokeError(f"{function} failed: {body.decode('utf-8', 'replace')}")
+        return json.loads(body) if body else None
+
+    if provider == "gcp":  # pragma: no cover - needs GCP
+        project = os.environ.get("PSKIT_GCP_PROJECT") or os.environ.get("GOOGLE_CLOUD_PROJECT", "")
+        region = os.environ.get("PSKIT_REGION", "")
+        url = f"https://{region}-{project}.cloudfunctions.net/{physical_name(function)}"
+        token = _gcp_id_token(url)
+        return _http_post(url, payload, timeout, {"authorization": f"Bearer {token}"})
+
+    raise InvokeError(
+        f"invoke() on provider {provider!r} needs the target URL in ${_env_key(function)}. "
+        "Give the target function an http event and set that URL in the caller's environment."
+    )

py_serverless_kit/runtime/log.py

@@ -0,0 +1,69 @@
+"""Structured JSON logging that every provider's log pipeline can ingest.
+
+Set ``PSKIT_LOG_FORMAT=text`` for human readable output (the local CLI does this)
+and ``LOG_LEVEL`` / ``PSKIT_LOG_LEVEL`` to control verbosity.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from datetime import datetime, timezone
+from typing import Any, Dict
+
+_CONFIGURED = False
+_RESERVED = set(vars(logging.LogRecord("", 0, "", 0, "", (), None))) | {"message", "asctime"}
+
+
+class JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        payload: Dict[str, Any] = {
+            "ts": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        for key, value in record.__dict__.items():
+            if key not in _RESERVED and not key.startswith("_"):
+                payload[key] = value
+        if record.exc_info:
+            payload["exception"] = self.formatException(record.exc_info)
+        return json.dumps(payload, default=str)
+
+
+def _configure() -> None:
+    global _CONFIGURED
+    if _CONFIGURED:
+        return
+    _CONFIGURED = True
+    logger = logging.getLogger("pskit")
+    level = os.environ.get("PSKIT_LOG_LEVEL") or os.environ.get("LOG_LEVEL") or "INFO"
+    logger.setLevel(level.upper() if isinstance(level, str) else level)
+    handler = logging.StreamHandler(sys.stdout)
+    if os.environ.get("PSKIT_LOG_FORMAT", "json").lower() == "text":
+        handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)-7s %(name)s: %(message)s"))
+    else:
+        handler.setFormatter(JsonFormatter())
+    logger.addHandler(handler)
+    logger.propagate = False
+
+
+class _FieldsAdapter(logging.LoggerAdapter):
+    """Like LoggerAdapter, but merges call-site ``extra=`` with the bound fields
+    (the stdlib adapter replaces them before Python 3.13)."""
+
+    def process(self, msg: Any, kwargs: Any) -> Any:
+        merged = {**(self.extra or {}), **(kwargs.get("extra") or {})}
+        # Keys such as "name" or "message" are reserved by LogRecord and would make
+        # logging raise KeyError - a log call must never crash a handler.
+        kwargs["extra"] = {(f"{k}_" if k in _RESERVED else k): v for k, v in merged.items()}
+        return msg, kwargs
+
+
+def get_logger(name: str = "pskit.function", **fields: Any) -> logging.LoggerAdapter:
+    _configure()
+    if not name.startswith("pskit"):
+        name = f"pskit.{name}"
+    return _FieldsAdapter(logging.getLogger(name), fields)

py_serverless_kit/runtime/manifest.py

@@ -0,0 +1,121 @@
+"""Reads ``pskit_manifest.json`` - the per-bundle description of every function.
+
+The CLI writes this file into the root of each deployment artifact. It lets a
+single shared bundle serve many functions (Azure Function Apps, the embedded
+workflow engine, ...) without depending on per-function environment variables.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+MANIFEST_FILE = "pskit_manifest.json"
+
+
+@dataclass
+class Route:
+    method: str
+    path: str
+    cors: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class FunctionSpec:
+    name: str
+    handler: str
+    routes: List[Route] = field(default_factory=list)
+    timeout: Optional[int] = None
+    memory: Optional[int] = None
+    resource_name: Optional[str] = None
+
+
+@dataclass
+class BundleManifest:
+    service: str = ""
+    stage: str = ""
+    provider: str = "local"
+    region: str = ""
+    functions: Dict[str, FunctionSpec] = field(default_factory=dict)
+    workflows: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, raw: Dict[str, Any]) -> BundleManifest:
+        functions = {}
+        for name, spec in (raw.get("functions") or {}).items():
+            routes = [Route(r["method"], r["path"], r.get("cors")) for r in spec.get("routes", [])]
+            functions[name] = FunctionSpec(
+                name=name,
+                handler=spec["handler"],
+                routes=routes,
+                timeout=spec.get("timeout"),
+                memory=spec.get("memory"),
+                resource_name=spec.get("resource_name"),
+            )
+        return cls(
+            service=raw.get("service", ""),
+            stage=raw.get("stage", ""),
+            provider=raw.get("provider", "local"),
+            region=raw.get("region", ""),
+            functions=functions,
+            workflows=raw.get("workflows") or {},
+        )
+
+
+_CACHE: Optional[BundleManifest] = None
+
+
+def _candidates() -> List[Path]:
+    here = Path(__file__).resolve()
+    paths = []
+    if os.environ.get("PSKIT_MANIFEST"):
+        paths.append(Path(os.environ["PSKIT_MANIFEST"]))
+    paths.append(here.parents[2] / MANIFEST_FILE)  # <bundle>/py_serverless_kit/runtime/manifest.py
+    for env in ("LAMBDA_TASK_ROOT", "FC_FUNC_CODE_PATH", "RUNTIME_CODE_ROOT"):
+        if os.environ.get(env):
+            paths.append(Path(os.environ[env]) / MANIFEST_FILE)
+    paths.append(Path.cwd() / MANIFEST_FILE)
+    return paths
+
+
+def load_manifest(reload: bool = False) -> BundleManifest:
+    global _CACHE
+    if _CACHE is not None and not reload:
+        return _CACHE
+    for path in _candidates():
+        if path.is_file():
+            _CACHE = BundleManifest.from_dict(json.loads(path.read_text("utf-8")))
+            return _CACHE
+    _CACHE = BundleManifest(
+        service=os.environ.get("PSKIT_SERVICE", ""),
+        stage=os.environ.get("PSKIT_STAGE", ""),
+        provider=os.environ.get("PSKIT_PROVIDER", "local"),
+    )
+    return _CACHE
+
+
+def set_manifest(manifest: Optional[BundleManifest]) -> None:
+    """Install a manifest programmatically (local runner and tests)."""
+    global _CACHE
+    _CACHE = manifest
+
+
+def resolve_function(name: Optional[str] = None) -> FunctionSpec:
+    """Find the spec for ``name`` (default: ``$PSKIT_FUNCTION``)."""
+    manifest = load_manifest()
+    name = name or os.environ.get("PSKIT_FUNCTION", "")
+    if name and name in manifest.functions:
+        return manifest.functions[name]
+    handler = os.environ.get("PSKIT_HANDLER")
+    if handler:
+        return FunctionSpec(name=name or handler, handler=handler)
+    if len(manifest.functions) == 1 and not name:
+        return next(iter(manifest.functions.values()))
+    known = ", ".join(sorted(manifest.functions)) or "<none>"
+    raise LookupError(
+        f"Cannot resolve function {name!r}. Set PSKIT_FUNCTION/PSKIT_HANDLER or check "
+        f"{MANIFEST_FILE}. Known functions: {known}"
+    )