@fireemu/darwin-x64 0.41.0 → 0.43.0

package/README.md

@@ -1,7 +1,7 @@
 # @fireemu/darwin-x64
 
 The [fireemu](https://www.npmjs.com/package/fireemu) daemon built for `darwin-x64`
-(Rust target `x86_64-apple-darwin`), version 0.41.0.
+(Rust target `x86_64-apple-darwin`), version 0.43.0.
 
 macOS 13 or newer on Intel. Cross-compiled from the Apple silicon runner against the same universal SDK; its unit tests run on the arm64 host, which builds the same code.
 
@@ -13,5 +13,6 @@ npm install -D fireemu
 ```
 
 It contains the daemon (`bin/fireemu`, with the Emulator UI compiled in) and the
-Node runner that hosts a Functions codebase (`bin/runner-node/`). Nothing is downloaded at
+Node runner that hosts a Functions codebase (`bin/runner-node/`) and the Python runner for
+Python codebases (`bin/runner-python/`). Nothing is downloaded at
 install time and there is no install script.

package/bin/fireemu

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/fireemu
-size: 40357016 bytes
-sha256: 8e1d6c3e408c7e874b846e6bb5daded879765ebe22e457a3f7f84c80076170b6
+size: 40488344 bytes
+sha256: c69d7b7ff0a2ade2bc47f666dfcfa531f1edcdd7d303edf522593bfcd8852d73

package/bin/runner-python/fireemu_runner/__init__.py

@@ -0,0 +1,5 @@
+"""The fireemu runner for Python Functions codebases (see docs/specifications and the design memo).
+
+The daemon speaks to a runner over its stdin and stdout with length-prefixed JSON frames. This
+package is imported by `runner.py`, which sits beside it.
+"""

package/bin/runner-python/fireemu_runner/dispatch.py

@@ -0,0 +1,104 @@
+"""Invocation frames: checked against the manifest, run on their own thread, answered with a result."""
+
+import os
+import threading
+import traceback
+
+from .events import (
+    database_cloud_event,
+    eventarc_cloud_event,
+    firestore_cloud_event,
+    pubsub_cloud_event,
+    storage_cloud_event,
+)
+from .framing import FrameWriter
+
+MAX_ACTIVE_INVOCATIONS = 4096
+_MAX_ERROR_CHARS = 4096
+_MAX_DIAGNOSTIC_CHARS = 256 * 1024
+
+# Trigger types that arrive as an `invoke` frame, and how each becomes the handler's argument.
+_EVENT_ADAPTERS = {
+    "firestore": firestore_cloud_event,
+    "pubsub": pubsub_cloud_event,
+    "storage": storage_cloud_event,
+    "eventarc": eventarc_cloud_event,
+    "database": database_cloud_event,
+}
+
+
+def _bound(text: str, limit: int) -> str:
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+class Dispatcher:
+    """Runs `invoke` frames against the functions the manifest serves."""
+
+    def __init__(self, functions: dict, manifest: dict, writer: FrameWriter):
+        self._functions = functions
+        self._specs = {spec["name"]: spec for spec in manifest["functions"]}
+        self._writer = writer
+        self._active = 0
+        self._lock = threading.Lock()
+
+    def _check(self, message: dict) -> tuple[dict, object]:
+        spec = self._specs.get(message["function"])
+        if spec is None:
+            raise LookupError("unknown function")
+        if "entryPoint" in message and message["entryPoint"] != spec["entryPoint"]:
+            raise LookupError("entry point does not match the function manifest")
+        trigger = spec["trigger"]["type"]
+        if message["trigger"] != trigger or trigger not in _EVENT_ADAPTERS:
+            raise LookupError("trigger does not match the function manifest")
+        function = self._functions.get(spec["entryPoint"])
+        if not callable(function):
+            raise LookupError("missing function entry point")
+        return spec, function
+
+    def reserve(self) -> bool:
+        with self._lock:
+            if self._active >= MAX_ACTIVE_INVOCATIONS:
+                return False
+            self._active += 1
+            return True
+
+    def start(self, message: dict) -> None:
+        """Runs one invoke frame on a new thread; the caller has reserved a slot with `reserve`."""
+        threading.Thread(target=self._run, args=(message,), daemon=True, name=f"invoke-{message['invocationId']}").start()
+
+    def _run(self, message: dict) -> None:
+        invocation = message["invocationId"]
+        try:
+            try:
+                spec, function = self._check(message)
+                # One process serves the whole codebase, so these name the invocation that started most
+                # recently, not a fixed target (the design memo, section 5).
+                os.environ["FUNCTION_TARGET"] = spec["entryPoint"]
+                os.environ["FUNCTION_SIGNATURE_TYPE"] = "cloudevent"
+                os.environ["K_SERVICE"] = spec["name"]
+                function(_EVENT_ADAPTERS[message["trigger"]](message["event"]))
+                result = {"type": "result", "invocationId": invocation, "ok": True}
+            except BaseException as error:  # a SystemExit in user code must still answer the daemon
+                diagnostic = "".join(traceback.format_exception(error))
+                self._send_log("error", f"{message['function']}: {diagnostic}", invocation, message["function"])
+                text = str(error) or type(error).__name__
+                result = {"type": "result", "invocationId": invocation, "ok": False, "error": _bound(text, _MAX_ERROR_CHARS)}
+            self._writer.write(result)
+        finally:
+            with self._lock:
+                self._active -= 1
+
+    def _send_log(self, level: str, text: str, invocation: str, function: str) -> None:
+        try:
+            self._writer.write(
+                {
+                    "type": "log",
+                    "level": level,
+                    "message": _bound(text, _MAX_DIAGNOSTIC_CHARS),
+                    "invocationId": invocation,
+                    "functionName": function,
+                    "user": False,
+                }
+            )
+        except Exception:  # a diagnostic can never suppress the result
+            pass

package/bin/runner-python/fireemu_runner/events.py

@@ -0,0 +1,113 @@
+"""Event adapters: the daemon's structured event as the CloudEvent the Python SDK expects.
+
+Production delivers a Firestore event as a binary-mode CloudEvent (`ce-*` headers) whose body is a
+protobuf `DocumentEventData`; the SDK's JSON branch needs a JSON *string* and fails on a decoded
+dict (`firestore_fn.py:108-131`). The adapter therefore builds the production form and lets
+`cloudevents.http.from_http` produce the object, exactly the path functions-framework takes
+(`functions_framework/__init__.py:174-188`).
+"""
+
+import json
+import os
+import re
+
+from cloudevents.http import from_http
+from google.events.cloud import firestore as firestore_events
+
+_NOT_AN_ATTRIBUTE = frozenset({"data", "datacontenttype"})
+
+
+_WHOLE_SECOND_TIME = re.compile(r"^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(Z|[+-]\d{2}:\d{2})$")
+
+
+def _attribute_headers(event: dict) -> dict:
+    """The binary-mode `ce-*` headers of an event: its string members, except the data and the content type."""
+    if not isinstance(event.get("specversion"), str):
+        # Without it `from_http` would read the body as a structured JSON event and fail on the body.
+        raise ValueError("the event has no specversion")
+    return {
+        f"ce-{name}": value
+        for name, value in event.items()
+        if name not in _NOT_AN_ATTRIBUTE and isinstance(value, str)
+    }
+
+
+def _is_json(content_type: str) -> bool:
+    media = content_type.split(";", 1)[0].strip().lower()
+    return media == "application/json" or media.endswith("+json")
+
+
+def _json_cloud_event(event: dict):
+    """The `CloudEvent` for an event whose data is JSON (or text, with a text content type).
+
+    Eventarc delivers these in binary content mode: attributes as `ce-*` headers and the data as the body,
+    which functions-framework hands to `cloudevents.http.from_http` (`functions_framework/__init__.py:174-188`).
+    A delivery without a content type is JSON.
+    """
+    headers = _attribute_headers(event)
+    declared = event.get("datacontenttype")
+    content_type = declared if isinstance(declared, str) and declared else "application/json"
+    headers["content-type"] = content_type
+    if "data" not in event:
+        body = b""
+    elif isinstance(event["data"], str) and not _is_json(content_type):
+        body = event["data"].encode()
+    else:
+        body = json.dumps(event["data"]).encode()
+    return from_http(headers, body)
+
+
+def _lenient_time(event: dict) -> dict:
+    """The emulator profile gives a whole-second `time` a fraction.
+
+    `storage_fn` and `eventarc_fn` parse `time` with `%f` (`storage_fn.py:249-252`, `eventarc_fn.py:65-68`) and
+    fail on `2026-01-01T00:00:02Z`. The official emulator always prints milliseconds, so what it served the
+    emulator profile must serve; the strict profile delivers the time as production's event has it.
+    """
+    time = event.get("time")
+    if os.environ.get("FIREEMU_HTTP_PROFILE", "emulator") == "strict" or not isinstance(time, str):
+        return event
+    match = _WHOLE_SECOND_TIME.match(time)
+    return event if match is None else {**event, "time": f"{match.group(1)}.000{match.group(2)}"}
+
+
+def pubsub_cloud_event(event: dict):
+    """The `CloudEvent` for a Pub/Sub message event.
+
+    The SDK reads `message_id` and `publish_time` (`pubsub_fn.py:98-160`), the snake-case spellings Pub/Sub's
+    push body carries next to `messageId` and `publishTime`. `orderingKey` has no alternative: the SDK pops
+    it and passes `ordering_key=` itself, so a copied key would be passed twice (`TypeError`).
+    """
+    data = event.get("data")
+    message = data.get("message") if isinstance(data, dict) else None
+    if not isinstance(message, dict):
+        return _json_cloud_event(event)
+    message = dict(message)
+    for camel, snake in (("messageId", "message_id"), ("publishTime", "publish_time")):
+        if snake not in message and camel in message and message[camel] is not None:
+            message[snake] = message[camel]
+    return _json_cloud_event({**event, "data": {**data, "message": message}})
+
+
+def storage_cloud_event(event: dict):
+    """The `CloudEvent` for a Storage object event."""
+    return _json_cloud_event(_lenient_time(event))
+
+
+def eventarc_cloud_event(event: dict):
+    """The `CloudEvent` for a custom Eventarc event."""
+    return _json_cloud_event(_lenient_time(event))
+
+
+def database_cloud_event(event: dict):
+    """The `CloudEvent` for a Realtime Database event."""
+    return _json_cloud_event(event)
+
+
+def firestore_cloud_event(event: dict):
+    """The `CloudEvent` for a Firestore event frame (`created`, `updated`, `deleted`, `written`)."""
+    headers = _attribute_headers(event)
+    data = event.get("data")
+    message = firestore_events.DocumentEventData.from_json(json.dumps(data if isinstance(data, dict) else {}))
+    headers["content-type"] = "application/protobuf"
+    return from_http(headers, firestore_events.DocumentEventData.serialize(message))

package/bin/runner-python/fireemu_runner/framing.py

@@ -0,0 +1,95 @@
+"""The frame codec: `<decimal byte length>\\n<UTF-8 JSON object>`.
+
+It matches `crates/fireemu-adapter-functions/src/protocol.rs` and `tools/runner-node/protocol.mjs`:
+a canonical decimal length (no sign, no leading zero, at most 8 digits), a cap of 16 MiB, and only
+the daemon messages this runner serves (`invoke` and `shutdown`). Diagnostics are fixed strings:
+a JSON parser error can quote the payload.
+"""
+
+import json
+import threading
+
+MAX_FRAME_BYTES = 16 * 1024 * 1024
+_MAX_HEADER_DIGITS = len(str(MAX_FRAME_BYTES))
+
+
+class ProtocolError(Exception):
+    """A frame the runner cannot accept; the reason is a fixed string."""
+
+    def __init__(self, reason: str):
+        super().__init__(f"invalid runner frame ({reason})")
+
+
+def encode_frame(message: dict) -> bytes:
+    payload = json.dumps(message, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    if len(payload) > MAX_FRAME_BYTES:
+        raise ProtocolError("frame too large")
+    return str(len(payload)).encode("ascii") + b"\n" + payload
+
+
+def _text(value) -> bool:
+    return isinstance(value, str) and len(value) > 0
+
+
+def _decode_message(payload: bytes) -> dict:
+    try:
+        message = json.loads(payload.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError):
+        raise ProtocolError("UTF-8 or JSON") from None
+    if not isinstance(message, dict):
+        raise ProtocolError("message object")
+    if message.get("type") == "shutdown":
+        return message
+    if (
+        message.get("type") != "invoke"
+        or not _text(message.get("invocationId"))
+        or not _text(message.get("function"))
+        or not _text(message.get("trigger"))
+        or not isinstance(message.get("event"), dict)
+        or ("entryPoint" in message and not _text(message["entryPoint"]))
+    ):
+        raise ProtocolError("message fields")
+    return message
+
+
+def read_frame(stream) -> dict | None:
+    """Reads one message from a binary stream; `None` at a clean end between frames."""
+    length = 0
+    digits = 0
+    while True:
+        byte = stream.read(1)
+        if not byte:
+            if digits == 0:
+                return None
+            raise ProtocolError("truncated")
+        value = byte[0]
+        if value == 10:
+            if digits == 0:
+                raise ProtocolError("empty length")
+            break
+        if value < 48 or value > 57 or (digits == 0 and value == 48):
+            raise ProtocolError("decimal length")
+        digits += 1
+        length = length * 10 + value - 48
+        if digits > _MAX_HEADER_DIGITS or length > MAX_FRAME_BYTES:
+            raise ProtocolError("frame too large")
+    payload = stream.read(length)
+    if len(payload) != length:
+        raise ProtocolError("truncated")
+    return _decode_message(payload)
+
+
+class FrameWriter:
+    """Writes frames to the protocol channel, one whole frame at a time."""
+
+    def __init__(self, stream):
+        self._stream = stream
+        self._lock = threading.Lock()
+
+    def write(self, message: dict) -> None:
+        data = encode_frame(message)
+        with self._lock:
+            self._stream.write(data)
+            flush = getattr(self._stream, "flush", None)
+            if flush is not None:
+                flush()

package/bin/runner-python/fireemu_runner/main.py

@@ -0,0 +1,82 @@
+"""The runner process: load the codebase, say hello, serve frames until told to stop."""
+
+import argparse
+import os
+import platform
+import sys
+import traceback
+
+from .dispatch import Dispatcher
+from .framing import FrameWriter, ProtocolError, read_frame
+from .manifest import build_manifest
+from .serve import start_server
+
+
+def _parse(argv):
+    parser = argparse.ArgumentParser(prog="runner.py")
+    parser.add_argument("--source", required=True)
+    parser.add_argument("--codebase", default="default")
+    return parser.parse_args(argv)
+
+
+def load_codebase(source: str) -> dict:
+    """Imports the codebase's `main.py` the way the SDK's own admin server does and returns its functions."""
+    os.chdir(source)
+    from firebase_functions.private import serving
+
+    return serving.get_functions()
+
+
+def serve(functions: dict, codebase: str, secret: str, stdin, writer: FrameWriter) -> int:
+    """Says hello, then serves frames from `stdin` until `shutdown` or the end of the stream."""
+    manifest = build_manifest(functions)
+    server = None
+    port = None
+    if any(spec["trigger"]["type"] == "http" for spec in manifest["functions"]):
+        server, port = start_server(functions, manifest, secret)
+    writer.write(
+        {
+            "type": "hello",
+            "runner": "python",
+            "codebase": codebase,
+            "version": platform.python_version(),
+            "httpPort": port,
+            "manifest": manifest,
+        }
+    )
+    dispatcher = Dispatcher(functions, manifest, writer)
+    try:
+        while True:
+            message = read_frame(stdin)
+            if message is None or message["type"] == "shutdown":
+                return 0
+            if not dispatcher.reserve():
+                sys.stderr.write("[functions] too many active invocations\n")
+                return 2
+            dispatcher.start(message)
+    except ProtocolError as error:
+        sys.stderr.write(f"[functions] {error}\n")
+        return 2
+    finally:
+        if server is not None:
+            server.shutdown()
+
+
+def run(argv) -> int:
+    args = _parse(argv)
+    # The protocol owns the original stdout. Everything that writes to file descriptor 1 afterwards
+    # (print, C extensions, child processes, the SDK logger) goes to stderr instead.
+    protocol = os.fdopen(os.dup(1), "wb", buffering=0)
+    os.dup2(2, 1)
+    writer = FrameWriter(protocol)
+    secret = os.environ.get("FIREEMU_RUNNER_SECRET", "")
+    # The daemon's local secrets are for the SDK's parameter lookup; user code does not see the channel
+    # that carried them, nor the key to this runner's HTTP port.
+    os.environ.pop("FIREEMU_LOCAL_SECRETS_JSON", None)
+    os.environ.pop("FIREEMU_RUNNER_SECRET", None)
+    try:
+        functions = load_codebase(args.source)
+    except BaseException:  # a failing import in user code is reported with its traceback
+        traceback.print_exc()
+        return 1
+    return serve(functions, args.codebase, secret, sys.stdin.buffer, writer)

package/bin/runner-python/fireemu_runner/manifest.py

@@ -0,0 +1,287 @@
+"""The endpoints the Python SDK declares, as fireemu's canonical manifest.
+
+`firebase_functions.private.serving.get_functions()` returns the decorated functions, each with a
+`__firebase_endpoint__` (the SDK's `ManifestEndpoint`, the same v1alpha1 endpoint schema the Node
+SDK produces). This module is the Python counterpart of `describe()` in
+`tools/runner-node/index.mjs`: it resolves option expressions, treats `None` and the SDK's reset
+sentinel as unset, and maps each trigger to the daemon's `functions[]` entry
+(`crates/fireemu-adapter-functions/src/manifest_json.rs`). A function it cannot serve is reported
+under `ignored[]`, never dropped.
+"""
+
+import enum
+from typing import Any
+
+from firebase_functions.params import Expression
+from firebase_functions.private.util import Sentinel
+
+DEFAULT_REGION = "us-central1"
+
+_FIRESTORE_PREFIX = "google.cloud.firestore."
+_PUBSUB_EVENT = "google.cloud.pubsub.topic.v1.messagePublished"
+_STORAGE_EVENTS = frozenset(
+    "google.cloud.storage.object.v1." + kind for kind in ("finalized", "deleted", "archived", "metadataUpdated")
+)
+_DATABASE_EVENTS = frozenset("google.firebase.database.ref.v1." + kind for kind in ("created", "updated", "deleted", "written"))
+# Products the official emulator has a trigger service for and fireemu does not serve, matched on a substring of
+# the event type as the Node runner does (`DEFERRED_TRIGGER_PRODUCTS` in `tools/runner-node/index.mjs`).
+_UNSERVED_PRODUCTS = (
+    ("remoteconfig", "remoteConfig", "deferred", "deferred: Remote Config has no emulator in the active supported surface"),
+    ("dataconnect", "dataconnect", "deferred", "deferred: the Data Connect emulator is not in the active supported surface"),
+    ("ailogic", "ai", "notPlanned", "not planned: Firebase AI Logic blocking triggers have no local emulator"),
+    ("analytics", "analytics", "notPlanned", "not planned: Google Analytics triggers have no local emulator"),
+    ("testing", "testLab", "notPlanned", "not planned: Test Lab triggers have no local emulator"),
+)
+_PLANNED = "Python {family} triggers are planned for a later slice and are not served yet"
+
+
+class Unserved(Exception):
+    """A function the runner reports under `ignored[]`."""
+
+    def __init__(self, trigger_type: str, scope: str, reason: str):
+        super().__init__(reason)
+        self.trigger_type = trigger_type
+        self.scope = scope
+        self.reason = reason
+
+
+def _unset(value: Any) -> bool:
+    return value is None or isinstance(value, Sentinel)
+
+
+def _resolved(value: Any, field: str) -> Any:
+    """An option's concrete value, or None when it is unset. Expressions read their parameter."""
+    if _unset(value):
+        return None
+    if isinstance(value, enum.Enum):
+        return value.value
+    if isinstance(value, Expression):
+        resolved = value.value
+        if resolved is None:
+            raise Unserved("unknown", "unsupported", f"{field} expression did not resolve to a value")
+        return resolved
+    return value
+
+
+def _non_negative_integer(value: Any, field: str):
+    resolved = _resolved(value, field)
+    if resolved is None:
+        return None
+    if isinstance(resolved, bool) or not isinstance(resolved, int) or resolved < 0:
+        raise Unserved("unknown", "unsupported", f"{field} did not resolve to a non-negative integer")
+    return resolved
+
+
+def _first_region(endpoint) -> str | None:
+    regions = _resolved(endpoint.region, "region")
+    if regions is None:
+        return None
+    values = [_resolved(region, "region") for region in (regions if isinstance(regions, list) else [regions])]
+    for value in values:
+        if not isinstance(value, str) or not value:
+            raise Unserved("unknown", "unsupported", "region did not resolve to a non-empty string")
+    return values[0] if values else None
+
+
+def _platform_options(endpoint) -> dict | None:
+    options: dict[str, Any] = {}
+    for field, key in (
+        ("availableMemoryMb", "availableMemoryMb"),
+        ("minInstances", "minInstances"),
+        ("maxInstances", "maxInstances"),
+    ):
+        value = _non_negative_integer(getattr(endpoint, field), field)
+        if value is not None:
+            options[key] = value
+    for field, key in (("ingressSettings", "ingressSettings"), ("serviceAccountEmail", "serviceAccountEmail")):
+        value = _resolved(getattr(endpoint, field), field)
+        if value is not None:
+            options[key] = value
+    invoker = (endpoint.httpsTrigger or {}).get("invoker") if isinstance(endpoint.httpsTrigger, dict) else None
+    if invoker:
+        options["invoker"] = invoker
+    vpc = endpoint.vpc if isinstance(endpoint.vpc, dict) else None
+    if vpc:
+        if not _unset(vpc.get("connector")):
+            options["vpcConnector"] = vpc["connector"]
+        egress = _resolved(vpc.get("egressSettings"), "vpc.egressSettings")
+        if egress is not None:
+            options["vpcEgressSettings"] = egress
+        if isinstance(vpc.get("networkInterfaces"), list):
+            options["networkInterfaces"] = vpc["networkInterfaces"]
+    if isinstance(endpoint.labels, dict) and endpoint.labels:
+        options["labels"] = endpoint.labels
+    cpu = _resolved(endpoint.cpu, "cpu")
+    if cpu is not None:
+        options["cpu"] = str(cpu)
+    if isinstance(endpoint.secretEnvironmentVariables, list):
+        secrets = [secret["key"] for secret in endpoint.secretEnvironmentVariables if secret.get("key")]
+        if secrets:
+            options["secrets"] = secrets
+    return options or None
+
+
+def _mapping(value) -> dict:
+    return value if isinstance(value, dict) else {}
+
+
+def _text(filters: dict, key: str, field: str, family: str, *, required: bool = False, allow_empty: bool = True):
+    """A string filter, resolved. Absent is None (or an error when required); another type is an error."""
+    value = _resolved(filters.get(key), field)
+    if value is None and not required:
+        return None
+    if not isinstance(value, str) or (not allow_empty and not value):
+        what = "a string" if allow_empty else "a non-empty string"
+        raise Unserved(family, "unsupported", f"{field} did not resolve to {what}")
+    return value
+
+
+def _firestore_trigger(event_trigger: dict) -> dict:
+    filters = _mapping(event_trigger.get("eventFilters"))
+    patterns = _mapping(event_trigger.get("eventFilterPathPatterns"))
+    # The SDK keeps a document path without wildcards in `eventFilters.document` and one with
+    # wildcards in `eventFilterPathPatterns.document` (`options.py:1065-1075`).
+    document = _text(patterns, "document", "eventFilterPathPatterns.document", "firestore") or _text(
+        filters, "document", "eventFilters.document", "firestore"
+    )
+    if not document:
+        raise Unserved("firestore", "unsupported", "the Firestore trigger names no document (eventFilters.document)")
+    return {
+        "type": "firestore",
+        "eventType": event_trigger["eventType"],
+        "database": _text(filters, "database", "eventFilters.database", "firestore") or "(default)",
+        "document": document,
+    }
+
+
+def _pubsub_trigger(event_trigger: dict) -> dict:
+    topic = _text(_mapping(event_trigger.get("eventFilters")), "topic", "eventFilters.topic", "pubsub", required=True, allow_empty=False)
+    # A full resource name is reduced to the short name the daemon matches on.
+    short = topic.rsplit("/topics/", 1)[-1] if "/topics/" in topic else topic
+    if not short:
+        raise Unserved("pubsub", "unsupported", "eventFilters.topic resolved to an empty topic")
+    return {"type": "pubsub", "topic": short}
+
+
+def _storage_trigger(event_trigger: dict, event_type: str) -> dict:
+    bucket = _text(_mapping(event_trigger.get("eventFilters")), "bucket", "eventFilters.bucket", "storage")
+    trigger = {"type": "storage", "eventType": event_type}
+    if bucket is not None:
+        trigger["bucket"] = bucket
+    return trigger
+
+
+def _database_trigger(event_trigger: dict, event_type: str) -> dict:
+    filters = _mapping(event_trigger.get("eventFilters"))
+    patterns = _mapping(event_trigger.get("eventFilterPathPatterns"))
+    # The SDK keeps a reference without wildcards in `eventFilters` and one with wildcards in
+    # `eventFilterPathPatterns`; the Node runner reads the patterns first as well.
+    reference = _text(patterns, "ref", "eventFilterPathPatterns.ref", "database")
+    if reference is None:
+        reference = _text(filters, "ref", "eventFilters.ref", "database", required=True)
+    instance = _text(patterns, "instance", "eventFilterPathPatterns.instance", "database")
+    if instance is None:
+        instance = _text(filters, "instance", "eventFilters.instance", "database")
+    return {
+        "type": "database",
+        "eventType": event_type,
+        "ref": "/" + reference.strip("/"),
+        "instance": instance if instance is not None else "*",
+    }
+
+
+def _eventarc_trigger(event_trigger: dict, event_type: str, channel: str) -> dict:
+    filters = _mapping(event_trigger.get("eventFilters"))
+    return {
+        "type": "eventarc",
+        "eventType": event_type,
+        "channel": channel,
+        "filters": {key: _text(filters, key, f"eventFilters.{key}", "eventarc", required=True) for key in filters},
+    }
+
+
+def _event_trigger(event_trigger: dict) -> dict:
+    """The canonical trigger of an `eventTrigger`, or `Unserved` for an event type fireemu does not serve."""
+    event_type = str(_resolved(event_trigger.get("eventType"), "eventType") or "")
+    if event_type.startswith(_FIRESTORE_PREFIX):
+        return _firestore_trigger({**event_trigger, "eventType": event_type})
+    if event_type == _PUBSUB_EVENT:
+        return _pubsub_trigger(event_trigger)
+    if event_type in _STORAGE_EVENTS:
+        return _storage_trigger(event_trigger, event_type)
+    if event_type in _DATABASE_EVENTS:
+        return _database_trigger(event_trigger, event_type)
+    # `onCustomEventPublished` is the only SDK trigger that names a channel.
+    channel = _text(event_trigger, "channel", "eventTrigger.channel", "eventarc")
+    if channel is not None:
+        return _eventarc_trigger(event_trigger, event_type, channel)
+    for fragment, trigger_type, scope, reason in _UNSERVED_PRODUCTS:
+        if fragment in event_type:
+            raise Unserved(trigger_type, scope, reason)
+    family = "storage" if event_type.startswith("google.cloud.storage.") else (
+        "database" if event_type.startswith("google.firebase.database.") else "unknown"
+    )
+    raise Unserved(family, "unsupported", f"event type {event_type} is not recognised")
+
+
+def describe_endpoint(name: str, endpoint) -> dict:
+    """The canonical `functions[]` entry of one endpoint, or `Unserved` when it cannot be served."""
+    if endpoint.platform != "gcfv2":
+        raise Unserved("unknown", "unsupported", "endpoint platform is not recognised")
+    described: dict[str, Any] = {"name": name, "entryPoint": name, "generation": 2}
+    region = _first_region(endpoint)
+    if region:
+        described["region"] = region
+    timeout = _non_negative_integer(endpoint.timeoutSeconds, "timeoutSeconds")
+    if timeout:
+        described["timeoutSeconds"] = timeout
+    concurrency = _non_negative_integer(endpoint.concurrency, "concurrency")
+    if concurrency is not None:
+        described["concurrency"] = concurrency
+    options = _platform_options(endpoint)
+    if options:
+        described["platformOptions"] = options
+    if endpoint.taskQueueTrigger is not None:
+        raise Unserved("tasks", "planned", _PLANNED.format(family="task queue"))
+    if endpoint.httpsTrigger is not None:
+        described["trigger"] = {"type": "http", "callable": False}
+    elif endpoint.callableTrigger is not None:
+        described["trigger"] = {"type": "http", "callable": True}
+    elif endpoint.scheduleTrigger is not None:
+        raise Unserved("schedule", "planned", _PLANNED.format(family="schedule"))
+    elif endpoint.blockingTrigger is not None:
+        raise Unserved("blockingAuth", "planned", _PLANNED.format(family="Auth blocking"))
+    elif endpoint.eventTrigger is not None:
+        described["trigger"] = _event_trigger(endpoint.eventTrigger)
+        retry = _resolved(endpoint.eventTrigger.get("retry"), "eventTrigger.retry")
+        if retry is not None and not isinstance(retry, bool):
+            raise Unserved(described["trigger"]["type"], "unsupported", "eventTrigger.retry did not resolve to a boolean")
+        described["retry"] = retry is True
+    else:
+        raise Unserved("unknown", "unsupported", "the endpoint declares no trigger")
+    return described
+
+
+def build_manifest(functions: dict) -> dict:
+    """`{"functions": [...], "ignored": [...]}` for the decorated functions of a codebase."""
+    served: list[dict] = []
+    ignored: list[dict] = []
+    for name, function in functions.items():
+        endpoint = function.__firebase_endpoint__
+        try:
+            served.append(describe_endpoint(name, endpoint))
+        except Unserved as unserved:
+            try:
+                region = _first_region(endpoint) or DEFAULT_REGION
+            except Unserved:
+                region = DEFAULT_REGION
+            ignored.append(
+                {
+                    "name": name,
+                    "region": region,
+                    "triggerType": unserved.trigger_type,
+                    "scope": unserved.scope,
+                    "reason": unserved.reason,
+                }
+            )
+    return {"functions": served, "ignored": ignored}

package/bin/runner-python/fireemu_runner/serve.py

@@ -0,0 +1,93 @@
+"""The HTTP server for `onRequest` and `onCall` functions.
+
+The daemon proxies `/<project>/<region>/<name>/...` here with the `x-fireemu-runner-secret` header
+(`crates/fireemu-adapter-functions/src/http.rs`, `tools/runner-node/http-admission.mjs`). The
+function sees the path below its mount point, as it does in production, and answers through the same
+`flask.Request` handlers the SDK wraps. An unhandled error is functions-framework's crash response.
+"""
+
+import hmac
+import os
+
+import flask
+from functions_framework import crash_handler, read_request
+from werkzeug.serving import WSGIRequestHandler, make_server
+
+from .manifest import DEFAULT_REGION
+
+SECRET_ENVIRON_KEY = "HTTP_X_FIREEMU_RUNNER_SECRET"
+_METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
+
+
+def _flask_app() -> flask.Flask:
+    app = flask.Flask("fireemu-runner")
+    app.register_error_handler(500, crash_handler)
+    app.after_request(read_request)
+
+    def run(path):
+        return flask.request.environ["fireemu.function"](flask.request._get_current_object())
+
+    # "OPTIONS" is listed so that Flask does not answer a callable's preflight itself.
+    app.add_url_rule("/", endpoint="run", view_func=run, defaults={"path": ""}, methods=_METHODS)
+    app.add_url_rule("/<path:path>", endpoint="run", view_func=run, methods=_METHODS)
+    return app
+
+
+class RunnerRouter:
+    """Admission and routing in front of the Flask app."""
+
+    def __init__(self, functions: dict, manifest: dict, project: str, secret: str):
+        self._app = _flask_app()
+        self._project = project
+        self._secret = secret.encode()
+        self._routes = {}
+        for spec in manifest["functions"]:
+            if spec["trigger"]["type"] == "http":
+                self._routes[spec["name"]] = (
+                    spec.get("region", DEFAULT_REGION),
+                    functions[spec["entryPoint"]],
+                    spec["entryPoint"],
+                )
+
+    @staticmethod
+    def _plain(start_response, status: str, text: str):
+        body = text.encode()
+        start_response(status, [("Content-Type", "text/plain; charset=utf-8"), ("Content-Length", str(len(body)))])
+        return [body]
+
+    def __call__(self, environ, start_response):
+        presented = environ.pop(SECRET_ENVIRON_KEY, "").encode()
+        if not hmac.compare_digest(presented, self._secret):
+            return self._plain(start_response, "403 Forbidden", "forbidden")
+        parts = environ.get("PATH_INFO", "").split("/")
+        # ["", project, region, name, *rest]
+        if len(parts) < 4 or parts[0] != "" or parts[1] != self._project:
+            return self._plain(start_response, "404 Not Found", "no HTTP function")
+        region, name = parts[2], parts[3]
+        route = self._routes.get(name)
+        if route is None or route[0] != region:
+            return self._plain(start_response, "404 Not Found", f"no HTTP function {parts[1]}/{region}/{name}")
+        environ["SCRIPT_NAME"] = environ.get("SCRIPT_NAME", "") + "/".join(parts[:4])
+        environ["PATH_INFO"] = "/" + "/".join(parts[4:])
+        environ["fireemu.function"] = route[1]
+        # The variables a production instance has from its start name the function it serves. One process
+        # serves the whole codebase here, so they name the call that started most recently, as for events.
+        os.environ["FUNCTION_TARGET"] = route[2]
+        os.environ["FUNCTION_SIGNATURE_TYPE"] = "http"
+        os.environ["K_SERVICE"] = name
+        return self._app(environ, start_response)
+
+
+class _QuietHandler(WSGIRequestHandler):
+    def log_request(self, *args, **kwargs):  # the daemon logs requests; the runner's stderr is for user output
+        pass
+
+
+def start_server(functions: dict, manifest: dict, secret: str):
+    """Starts the server on a free loopback port; returns `(server, port)`."""
+    router = RunnerRouter(functions, manifest, os.environ.get("GCLOUD_PROJECT", ""), secret)
+    server = make_server("127.0.0.1", 0, router, threaded=True, request_handler=_QuietHandler)
+    import threading
+
+    threading.Thread(target=server.serve_forever, daemon=True, name="http").start()
+    return server, server.server_port

package/bin/runner-python/runner.py

@@ -0,0 +1,19 @@
+"""Entry point of the fireemu Python runner: `python runner.py --source <dir> --codebase <name>`.
+
+It is started by the fireemu daemon with the interpreter of the codebase's `venv` and speaks the
+frame protocol on stdin and stdout (see `fireemu_runner/framing.py`).
+"""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from fireemu_runner.main import run  # noqa: E402
+
+if __name__ == "__main__":
+    code = run(sys.argv[1:])
+    sys.stdout.flush()
+    sys.stderr.flush()
+    # Handlers may have left non-daemon threads behind; the daemon already decided to stop us.
+    os._exit(code)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fireemu/darwin-x64",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "description": "The fireemu daemon for darwin-x64",
   "homepage": "https://t-k.github.io/fireemu/",
   "repository": {