funcd-shim 0.2.0__tar.gz

funcd_shim-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

funcd_shim-0.2.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.5
+Name: funcd-shim
+Version: 0.2.0
+Summary: The funcd Python runtime shim, the types handlers are written against, and the contract build
+Project-URL: Homepage, https://github.com/pyvvo/funcd-python
+Project-URL: Repository, https://github.com/pyvvo/funcd-python
+Author: The funcd Authors
+License-Expression: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: fastjsonschema>=2.21.2
+Provides-Extra: build
+Requires-Dist: pydantic>=2.13.4; extra == 'build'
+Description-Content-Type: text/markdown
+
+# funcd-shim
+
+The Python side of [funcd](https://github.com/pyvvo/funcd): the runtime shim that loads a
+function's handler inside a funcd worker, the types handlers are written against, and the
+contract build.
+
+```bash
+pip install "funcd-shim[build]"
+```
+
+- `from funcd_shim import CloudEvent, FunctionContext` types a handler.
+- `from funcd_shim.build import build` bakes its input and output contract. It needs the `build`
+  extra.

funcd_shim-0.2.0/README.md

@@ -0,0 +1,13 @@
+# funcd-shim
+
+The Python side of [funcd](https://github.com/pyvvo/funcd): the runtime shim that loads a
+function's handler inside a funcd worker, the types handlers are written against, and the
+contract build.
+
+```bash
+pip install "funcd-shim[build]"
+```
+
+- `from funcd_shim import CloudEvent, FunctionContext` types a handler.
+- `from funcd_shim.build import build` bakes its input and output contract. It needs the `build`
+  extra.

funcd_shim-0.2.0/embed.go

@@ -0,0 +1,68 @@
+// Package python embeds the funcd Python runtime shim (ADR-0049) into the binary, so the single
+// self-contained `funcd` daemon ships it with no sidecar (ADR-0036, mirroring shim/nodejs). The
+// daemon extracts the package tree to its data dir on boot and points WithRuntimeShimFor("python", …)
+// at the extracted entry script. The shim calls the artifact's precompiled fastjsonschema validator
+// (ADR-0058 — pure-Python, subinterpreter-safe); pydantic + fastjsonschema run only at build time.
+package python
+
+import (
+	"embed"
+	"io/fs"
+	"os"
+	"path/filepath"
+)
+
+// Explicit file list (not a directory glob): includes the underscore-prefixed __init__.py /
+// __main__.py that an `all:` glob would need but that would also drag in __pycache__/*.pyc. Listing
+// the sources by name embeds exactly the shim, nothing machine-generated. Every module the extracted
+// shim imports at runtime is listed — solo (shim.py) and pool (pool.py/_poolworker.py) both import
+// funclog + tracespan (+ tracespan→invcontext) at load, and contract.py (ADR-0123) is compiled at
+// worker init; kv.py backs context.kv. build.py is the push-time AST baker (build-only) — not shipped.
+//
+//go:embed src/funcd_shim/__init__.py src/funcd_shim/__main__.py src/funcd_shim/shim.py src/funcd_shim/invoke.py src/funcd_shim/pool.py src/funcd_shim/_poolworker.py src/funcd_shim/runtime.py src/funcd_shim/types.py src/funcd_shim/contract.py src/funcd_shim/funclog.py src/funcd_shim/tracespan.py src/funcd_shim/invcontext.py src/funcd_shim/kv.py src/funcd_shim/blob.py src/funcd_shim/py.typed
+var shimFS embed.FS
+
+// The entry scripts launch the package: Python prepends a script's own directory to sys.path, so
+// placing them beside the extracted `funcd_shim/` package makes `from funcd_shim...` resolve with
+// no PYTHONPATH. Each runs a main() that reads its config (FUNCD_ARTIFACT / FUNCD_POOL_MANIFEST /
+// FUNCD_PORT…) from the env.
+const (
+	shimEntryScript = "from funcd_shim.shim import main\nraise SystemExit(main())\n"
+	poolEntryScript = "from funcd_shim.pool import main\nraise SystemExit(main())\n" // ADR-0050, needs Python ≥3.14
+)
+
+// Extract writes the embedded Python shim package under dir and returns the entry script paths to
+// launch as `python3 <entry>`: shimEntry is the solo shim (ADR-0049), poolEntry the subinterpreter
+// pool host (ADR-0050, requires Python ≥3.14). Idempotent: overwrites whatever is there.
+func Extract(dir string) (shimEntry, poolEntry string, err error) {
+	walkErr := fs.WalkDir(shimFS, "src/funcd_shim", func(path string, d fs.DirEntry, e error) error {
+		if e != nil {
+			return e
+		}
+		rel, rerr := filepath.Rel("src", path) // funcd_shim/...
+		if rerr != nil {
+			return rerr
+		}
+		dst := filepath.Join(dir, rel)
+		if d.IsDir() {
+			return os.MkdirAll(dst, 0o750)
+		}
+		data, readErr := shimFS.ReadFile(path)
+		if readErr != nil {
+			return readErr
+		}
+		return os.WriteFile(dst, data, 0o600)
+	})
+	if walkErr != nil {
+		return "", "", walkErr
+	}
+	shimEntry = filepath.Join(dir, "funcd_shim_entry.py")
+	if werr := os.WriteFile(shimEntry, []byte(shimEntryScript), 0o600); werr != nil {
+		return "", "", werr
+	}
+	poolEntry = filepath.Join(dir, "funcd_pool_entry.py")
+	if werr := os.WriteFile(poolEntry, []byte(poolEntryScript), 0o600); werr != nil {
+		return "", "", werr
+	}
+	return shimEntry, poolEntry, nil
+}

funcd_shim-0.2.0/embed_test.go

@@ -0,0 +1,33 @@
+package python
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestEmbedIncludesEveryRuntimeModule guards against a new funcd_shim module (e.g. blob.py for context.blob)
+// being added to src/funcd_shim/ but forgotten in embed.go's explicit go:embed list — which would ship a shim
+// that ModuleNotFoundErrors the moment a handler touches the missing accessor (the exact ADR-0127 blob.py miss).
+func TestEmbedIncludesEveryRuntimeModule(t *testing.T) {
+	// notShipped: source modules intentionally NOT embedded (build-time only, never imported at runtime).
+	notShipped := map[string]bool{
+		"build.py": true, // the push-time AST baker (pydantic/typia)
+	}
+	srcDir := filepath.Join("src", "funcd_shim")
+	ents, err := os.ReadDir(srcDir)
+	if err != nil {
+		t.Fatalf("read %s: %v", srcDir, err)
+	}
+	for _, e := range ents {
+		name := e.Name()
+		if e.IsDir() || !strings.HasSuffix(name, ".py") || notShipped[name] {
+			continue
+		}
+		if _, oerr := shimFS.Open("src/funcd_shim/" + name); oerr != nil {
+			t.Errorf("source module %q is not in embed.go's go:embed list — the extracted shim would be missing it "+
+				"(add it, or add it to notShipped if build-only): %v", name, oerr)
+		}
+	}
+}

funcd_shim-0.2.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "funcd-shim"
+# Not bumped per release: a bump would make every uv.lock stale. The vX.Y.Z git tag is the version.
+version = "0.2.0"
+description = "The funcd Python runtime shim, the types handlers are written against, and the contract build"
+authors = [{ name = "The funcd Authors" }]
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.12"
+dependencies = [
+    "fastjsonschema>=2.21.2",
+]
+
+[project.optional-dependencies]
+# the contract build (funcd_shim.build) reads FuncInput/FuncOutput through pydantic
+build = ["pydantic>=2.13.4"]
+
+[project.urls]
+Homepage = "https://github.com/pyvvo/funcd-python"
+Repository = "https://github.com/pyvvo/funcd-python"
+
+[project.scripts]
+funcd-shim = "funcd_shim.shim:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/funcd_shim"]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.13",
+    "pydantic>=2.13.4",
+    "pytest>=8.3",
+    "ruff>=0.8",
+]
+
+[tool.mypy]
+strict = true
+python_version = "3.12"
+files = ["src", "tests"]
+
+[[tool.mypy.overrides]]
+module = "fastjsonschema.*"  # ships no type stubs; used only as a build-time validator generator
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 110
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "A", "S"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "S310"]  # asserts are the point of tests; S310 = loopback urllib in tests

funcd_shim-0.2.0/src/funcd_shim/__init__.py

@@ -0,0 +1,20 @@
+"""funcd Python runtime shim + the typed authoring contract.
+
+Function authors import the contract types::
+
+    from funcd_shim import Handler, CloudEvent, FunctionContext
+
+    def handle(context: FunctionContext, event: CloudEvent) -> dict:
+        ...
+
+The shim entrypoint is ``python -m funcd_shim`` (see :mod:`funcd_shim.shim`). It serves the
+runtime-shim HTTP contract and validates ``event.data`` / the result against the optional
+``FuncInput`` / ``FuncOutput`` **pydantic models** an artifact declares (ADR-0058, supersedes the
+ADR-0038 JTD ``event_schema``). Requires pydantic at runtime.
+"""
+
+from __future__ import annotations
+
+from .types import CloudEvent, FunctionContext, Handler, Json
+
+__all__ = ["CloudEvent", "FunctionContext", "Handler", "Json"]

funcd_shim-0.2.0/src/funcd_shim/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m funcd_shim`` entrypoint — runs the runtime shim (ADR-0049)."""
+
+from __future__ import annotations
+
+import sys
+
+from .shim import main
+
+if __name__ == "__main__":
+    sys.exit(main())

funcd_shim-0.2.0/src/funcd_shim/_poolworker.py

@@ -0,0 +1,134 @@
+"""Worker-side logic for the funcd Python pool host (ADR-0050), run INSIDE each subinterpreter by
+``InterpreterPoolExecutor``. ``init`` loads the handler + the optional I/O validators once per worker
+interpreter (state persists across invocations); ``invoke`` runs the contract + handler for one
+request and returns a status-tagged envelope; ``ready`` is a side-effect-free load probe.
+
+No ``concurrent.*`` here — plain per-interpreter Python. ``init``/``invoke``/``ready`` are referenced
+by the executor across the interpreter boundary, so they live in this small importable module (the
+host puts the package dir on ``PYTHONPATH`` so the worker can import ``funcd_shim``)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TYPE_CHECKING, Any
+
+from .runtime import Validators
+from .types import CloudEvent, Handler
+
+if TYPE_CHECKING:
+    from .blob import BlobClient
+    from .kv import KVClient
+
+# Per-interpreter state, set by init() and read by invoke() — isolated to this worker interpreter.
+_handler: Handler | None = None
+_validators: Validators = Validators()
+_channel: Any = None  # the shared telemetry channel (ADR-0101), opened once in init()
+
+
+def init(src: str, artifact: str, handler: str, contract_path: str | None = None) -> None:
+    """Load the handler + I/O validators into this interpreter (the materialization shape-gate,
+    ADR-0058/0123). Runs once per worker; a failure breaks the pool → exit 3.
+
+    ADR-0123: when *contract_path* is given, compile the validators from the delivered schema
+    (``fastjsonschema.compile``) **before** the untrusted handler module is imported — the bounded
+    eval-free reversal + the m3 reorder. A set-but-broken path fails the worker closed. When absent,
+    fall back to the module-baked ``__funcd_validate_*`` (transition back-compat)."""
+    global _handler, _validators, _channel
+    if src not in sys.path:
+        sys.path.insert(0, src)
+    from funcd_shim import contract, runtime
+    from funcd_shim.funclog import install_log_capture, open_channel
+
+    # Path B capture (ADR-0081) + traces (ADR-0101): each pool worker runs in its own subinterpreter
+    # with its own root logger, so open the channel + install capture here (per-interpreter), before
+    # the handler loads. One shared channel per worker. No-op unless FUNCD_LOG_FD/SOCK is set.
+    _channel = open_channel()
+    install_log_capture(_channel)
+
+    # ADR-0123: compile the delivered contract AHEAD of the handler import (m3 reorder).
+    delivered = contract.load_from_path(contract_path) if contract_path else None
+    module = runtime.load_module(artifact)
+    _handler = runtime.resolve_handler(module, handler)
+    _validators = delivered if delivered is not None else runtime.resolve_validators(module)
+
+
+def ready() -> bool:
+    """A load probe: True once init() succeeded (no handler call). The host submits this at startup
+    so a bad member surfaces as a broken pool before serving."""
+    return _handler is not None
+
+
+class _Ctx:
+    def log(self, *args: object) -> None:
+        print(*args, flush=True)
+
+    def invoke(self, alias: str, payload: Any) -> Any:
+        from .invoke import invoke as _invoke
+
+        return _invoke(alias, payload)
+
+    @property
+    def kv(self) -> KVClient:
+        from .kv import KVClient
+
+        return KVClient()
+
+    @property
+    def blob(self) -> BlobClient:
+        from .blob import BlobClient
+
+        return BlobClient()
+
+
+def invoke(
+    body: str,
+    traceparent: str | None = None,
+    fn_name: str = "invoke",
+    span_id: str | None = None,
+    links: list[str] | None = None,
+) -> dict[str, Any]:
+    """Run one request: parse → optional input validation → handler → optional output validation →
+    a status-tagged envelope the host maps to the HTTP response (identical to the solo shim). ADR-0101:
+    a successful-past-input-validation request emits a SERVER span on the worker's channel."""
+    if _handler is None:  # defensive — init() always runs first
+        return {"status": 500, "body": {"error": "handler not loaded"}}
+    try:
+        event: CloudEvent[Any] = json.loads(body) if body else CloudEvent()
+    except (json.JSONDecodeError, ValueError):
+        return {"status": 400, "body": {"error": "request body is not valid JSON"}}
+    if not isinstance(event, dict):
+        # A valid-JSON but non-object body (null / array / scalar) is not a CloudEvent envelope.
+        # Reject it cleanly — never let `event.get("data")` raise AttributeError and crash the pooled
+        # worker (that surfaced as a gateway `proxy error: EOF` / empty-body 502).
+        return {
+            "status": 400,
+            "body": {"error": "request body must be a JSON object (CloudEvent envelope)"},
+        }
+    if _validators.input is not None:
+        errors = _validators.input(event.get("data"))
+        if errors:
+            # ADR-0101: input-mismatch short-circuits before the handler → no invocation, no span.
+            return {
+                "status": 422,
+                "body": {"error": "event data does not match the input contract", "details": errors},
+            }
+    from .tracespan import InvocationSpan
+
+    with InvocationSpan(_channel, fn_name, traceparent, span_id, links) as span:
+        try:
+            result = _handler(_Ctx(), event)
+        except Exception as err:  # noqa: BLE001 - user handler errors become 500
+            span.fail(str(err))
+            return {"status": 500, "body": {"error": str(err)}}
+        if _validators.output is not None:
+            errors = _validators.output(result)
+            if errors:
+                span.fail("handler result does not match the output contract")
+                return {
+                    "status": 500,
+                    "body": {"error": "handler result does not match the output contract", "details": errors},
+                }
+        if result is None:
+            return {"status": 204}
+        return {"status": 200, "body": result}

funcd_shim-0.2.0/src/funcd_shim/blob.py

@@ -0,0 +1,117 @@
+"""Function-facing blob over the worker-node local API (HTTP-over-UDS, ADR-0127).
+
+Dials the same per-sandbox socket as ``context.kv``/``context.invoke`` (``FUNCD_INVOKE_SOCKET``); the
+platform routes ``/blob/…`` to the binding-gated, PDP-authorized Facade with the sandbox's function
+identity (bind-as-grant on ``spec.blob``). Stdlib-only — no boto3, no keypair. The blob twin of
+``context.kv``; v1 is bytes-in-memory (streaming is a v2 follow-up).
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import socket
+from urllib.parse import quote
+
+
+class _UnixHTTPConnection(http.client.HTTPConnection):
+    """An HTTPConnection that dials a Unix domain socket instead of TCP."""
+
+    def __init__(self, socket_path: str) -> None:
+        super().__init__("localhost")
+        self._socket_path = socket_path
+
+    def connect(self) -> None:
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.connect(self._socket_path)
+        self.sock = sock
+
+
+def _conn() -> _UnixHTTPConnection:
+    socket_path = os.environ.get("FUNCD_INVOKE_SOCKET")
+    if not socket_path:
+        raise RuntimeError(
+            "context.blob: worker-node local API socket unavailable (FUNCD_INVOKE_SOCKET unset)"
+        )
+    return _UnixHTTPConnection(socket_path)
+
+
+def _key_path(binding: str, key: str) -> str:
+    # key may be hierarchical ("a/b"); keep the "/" separators (the server's {key...} captures them).
+    segs = "/".join(quote(s, safe="") for s in key.split("/"))
+    return f"/blob/{quote(binding, safe='')}/{segs}"
+
+
+class BlobClient:
+    """A function's binding-scoped blob storage (ADR-0127): get/put/delete/list a bound prefix's objects,
+    or mint a presigned URL — the blob twin of :class:`KVClient`."""
+
+    def get(self, binding: str, key: str) -> bytes | None:
+        conn = _conn()
+        try:
+            conn.request("GET", _key_path(binding, key))
+            resp = conn.getresponse()
+            data = resp.read()
+            if resp.status == 404:
+                return None
+            if not 200 <= resp.status < 300:
+                text = data.decode("utf-8", "replace")
+                raise RuntimeError(f"context.blob.get failed: {resp.status} {text}")
+            return data
+        finally:
+            conn.close()
+
+    def put(self, binding: str, key: str, data: bytes) -> None:
+        conn = _conn()
+        try:
+            conn.request("PUT", _key_path(binding, key), body=data)
+            resp = conn.getresponse()
+            text = resp.read().decode("utf-8", "replace")
+            if not 200 <= resp.status < 300:
+                raise RuntimeError(f"context.blob.put failed: {resp.status} {text}")
+        finally:
+            conn.close()
+
+    def delete(self, binding: str, key: str) -> None:
+        conn = _conn()
+        try:
+            conn.request("DELETE", _key_path(binding, key))
+            resp = conn.getresponse()
+            text = resp.read().decode("utf-8", "replace")
+            if not 200 <= resp.status < 300:
+                raise RuntimeError(f"context.blob.delete failed: {resp.status} {text}")
+        finally:
+            conn.close()
+
+    def list(self, binding: str, prefix: str = "") -> list[str]:
+        path = f"/blob/{quote(binding, safe='')}"
+        if prefix:
+            path += f"?prefix={quote(prefix, safe='')}"
+        conn = _conn()
+        try:
+            conn.request("GET", path)
+            resp = conn.getresponse()
+            text = resp.read().decode("utf-8")
+            if not 200 <= resp.status < 300:
+                raise RuntimeError(f"context.blob.list failed: {resp.status} {text}")
+            return json.loads(text) if text else []
+        finally:
+            conn.close()
+
+    def signed_url(self, binding: str, key: str, method: str = "GET", expiry: float | None = None) -> str:
+        """Return a presigned external URL for the object. ``method`` is GET (read) / PUT / DELETE (write);
+        ``expiry`` is in seconds (the driver's default when ``None``). A PUT/DELETE URL requires s3::write."""
+        path = f"{_key_path(binding, key)}?sign=1&method={quote(method, safe='')}"
+        if expiry is not None:
+            path += f"&expiry={expiry}s"
+        conn = _conn()
+        try:
+            conn.request("GET", path)
+            resp = conn.getresponse()
+            text = resp.read().decode("utf-8", "replace")
+            if not 200 <= resp.status < 300:
+                raise RuntimeError(f"context.blob.signed_url failed: {resp.status} {text}")
+            return text
+        finally:
+            conn.close()