@fireemu/darwin-arm64 0.43.0 → 0.45.0

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

@@ -0,0 +1,65 @@
+"""The HTTP request a CloudEvent function runs inside.
+
+functions-framework serves a CloudEvent function from a Flask view and calls the function inside the request context, so
+`flask.request` shows the delivered request. Production's raw twins were recorded on 2026-11-04 (sandbox run
+PYCHECK-EVENTS-20261104-01): `POST /` with the binary-mode `ce-*` headers, `content-type`, `content-length` and, in the strict
+profile, constants every recorded frame carries (the sender's user agent, the encodings, the protocol) plus Cloud Run's plain
+`traceparent` header. The body is the text the delivery had, not a re-encoding of the event: the layouts recorded per family are in
+`bodies.py` (strict Pub/Sub and Storage; Eventarc keeps the publisher's text), and the emulator and unset profiles carry the framed JSON value text
+of the data as the daemon sent it (a publisher's surrounding white space is trimmed upstream; a Pub/Sub body is the exception, it gets the SDK's snake-case aliases and is rewritten compactly). A Realtime Database body was not recorded. Header policy: a name that is not an HTTP token (or has an underscore) is
+left out of the request, a control character other than TAB in a value becomes a space, and of two names that differ only in case the first one
+is the header; the event the function receives is never changed by the view. The OIDC `Authorization`, `Forwarded`, `X-Forwarded-For`, `Function-Execution-Id`, `X-Cloud-Trace-Context`,
+`From`, `Accept` and the Cloud Run host have no local source and are not invented.
+"""
+
+import contextlib
+import re
+
+import flask
+from werkzeug.test import EnvironBuilder
+
+from .events import is_strict
+
+_APP = flask.Flask("fireemu-cloudevent")
+# What an HTTP header may be called: a token without an underscore. Header names with an underscore are dropped by the usual
+# servers, and Werkzeug folds `foo_bar` into `foo-bar`; both are UNRECORDED, so such an attribute stays out of the request
+# (the event keeps it).
+_HEADER_NAME = re.compile(r"[!#$%&'*+.^`|~0-9A-Za-z-]+")
+# A control character other than the tab cannot be in a header value; it becomes a space, as a line break does.
+_CONTROL = re.compile(r"[\x00-\x08\x0a-\x1f\x7f]")
+# Constant in every recorded Eventarc delivery (the four raw twins of run 57ab27296dedaedc).
+_STRICT_CONSTANTS = {
+    "user-agent": "APIs-Google; (+https://developers.google.com/webmasters/APIs-Google.html)",
+    "accept-encoding": "gzip, deflate, br",
+    "x-forwarded-proto": "https",
+}
+
+
+def request_headers(headers: dict, event: dict) -> dict:
+    """The headers of the request: the event's binary-mode headers, and in the strict profile the recorded constants and the
+    trace context as the plain `traceparent` header.
+
+    The request is what a server would have received, so a name that is not a header name is left out, and when two names
+    differ only in case the first one stays. A control character in a value other than the tab, a line break included, is
+    replaced by a space. The event the function receives keeps every attribute and its text.
+    """
+    view = {}
+    taken = set()
+    for name, value in headers.items():
+        if _HEADER_NAME.fullmatch(name) and name.lower() not in taken:
+            taken.add(name.lower())
+            view[name] = _CONTROL.sub(" ", value)
+    if is_strict():
+        view.update(_STRICT_CONSTANTS)
+        traceparent = event.get("traceparent")
+        if isinstance(traceparent, str):
+            view["traceparent"] = _CONTROL.sub(" ", traceparent)
+    return view
+
+
+@contextlib.contextmanager
+def delivery_request(headers: dict, body: bytes, event: dict):
+    """Runs the block inside the Flask request context of the delivery described by `headers` and `body`."""
+    environ = EnvironBuilder(method="POST", path="/", headers=request_headers(headers, event), data=body).get_environ()
+    with _APP.request_context(environ):
+        yield

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

@@ -0,0 +1,87 @@
+"""Scheduled runs: the request Cloud Scheduler sends a Gen2 function, built in process.
+
+A Gen2 `on_schedule` function is an HTTP function. Production's Scheduler calls it with `POST /`, the job id in
+`X-CloudScheduler-JobName` and the schedule time in `X-CloudScheduler-ScheduleTime`, and judges the attempt by the
+status the SDK wrapper answers: 200, or 500 when the handler raised (the wrapper logs the error and answers its
+message, `scheduler_fn.py:99-137`). The Node runner does the same in the strict profile
+(`tools/runner-node/schedule-delivery.mjs`, recorded in run 156715222b86ea44).
+"""
+
+import datetime
+import os
+import re
+from zoneinfo import ZoneInfo
+
+import flask
+from werkzeug.test import EnvironBuilder
+
+_INSTANT = re.compile(r"^(\d{4})-(\d\d)-(\d\d)T(\d\d):(\d\d):(\d\d)(?:\.(\d{1,9}))?Z$")
+_LOS_ANGELES = ZoneInfo("America/Los_Angeles")
+_JOB_NAME = re.compile(r"projects/([^/]*)/locations/([^/]*)/jobs/")
+_NAME = re.compile(r"[A-Za-z0-9-]+")
+_MAX_ANSWER_CHARS = 256
+
+
+class SchedulerFailure(Exception):
+    """A scheduled attempt that failed: the run was malformed or the function answered 400 or more."""
+
+
+def _schedule_time(instant) -> str:
+    """The schedule time as the header carries it: Los Angeles with its offset in the strict profile (whatever the
+    job's own zone, as recorded), the daemon's UTC instant otherwise."""
+    match = _INSTANT.match(instant) if isinstance(instant, str) else None
+    if match is None:
+        raise SchedulerFailure(f"the scheduled time is not an RFC 3339 UTC instant: {instant!r}")
+    year, month, day, hour, minute, second = (int(part) for part in match.groups()[:6])
+    try:
+        moment = datetime.datetime(year, month, day, hour, minute, second, tzinfo=datetime.timezone.utc)
+    except ValueError:
+        raise SchedulerFailure(f"the scheduled time is not an RFC 3339 UTC instant: {instant!r}") from None
+    if os.environ.get("FIREEMU_HTTP_PROFILE", "emulator") != "strict":
+        return instant
+    local = moment.astimezone(_LOS_ANGELES)
+    fraction = (match.group(7) or "").rstrip("0")
+    offset = local.strftime("%z")
+    return local.strftime("%Y-%m-%dT%H:%M:%S") + (f".{fraction}" if fraction else "") + f"{offset[:3]}:{offset[3:]}"
+
+
+def _function_host(job: str) -> str | None:
+    """The public host of a function, `<region>-<project>.cloudfunctions.net`, from a job's resource name.
+
+    Recorded for us-central1 only (all 76 distinct Gen2 frames of run 156715222b86ea44); another region follows the
+    same rule, unrecorded. A name without a project and a location in this form invents no host (the Node runner's
+    `functionHost`).
+    """
+    match = _JOB_NAME.match(job)
+    if match is None or not _NAME.fullmatch(match.group(1)) or not _NAME.fullmatch(match.group(2)):
+        return None
+    return f"{match.group(2)}-{match.group(1)}.cloudfunctions.net"
+
+
+def scheduler_headers(data) -> dict:
+    """The headers of the request for one scheduled run (`{jobName, scheduleTime}`)."""
+    job = data.get("jobName") if isinstance(data, dict) else None
+    if not isinstance(job, str) or not job:
+        raise SchedulerFailure("the scheduled run names no job name")
+    host = _function_host(job)
+    return {
+        "x-cloudscheduler": "true",
+        "x-cloudscheduler-jobname": job.rsplit("/", 1)[-1],
+        "x-cloudscheduler-scheduletime": _schedule_time(data.get("scheduleTime")),
+        "user-agent": "Google-Cloud-Scheduler",
+        "content-length": "0",
+        # Constant in every recorded frame: the front end's encodings and protocol.
+        "accept-encoding": "gzip, deflate, br",
+        "x-forwarded-proto": "https",
+        **({"host": host} if host else {}),
+    }
+
+
+def deliver_schedule(function, data) -> None:
+    """Calls the SDK wrapper with the scheduler's request. Returns when it answers below 400; raises otherwise."""
+    environ = EnvironBuilder(method="POST", path="/", headers=scheduler_headers(data)).get_environ()
+    with flask.Flask("fireemu-scheduler").request_context(environ):
+        response = function(flask.request)
+    if response.status_code >= 400:
+        body = response.get_data(as_text=True)[:_MAX_ANSWER_CHARS]
+        raise SchedulerFailure(f"the scheduled function answered {response.status_code}" + (f": {body}" if body else ""))

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

@@ -1,4 +1,4 @@
-"""The HTTP server for `onRequest` and `onCall` functions.
+"""The HTTP server for `onRequest`, `onCall`, task queue and Auth blocking 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
@@ -6,16 +6,22 @@ function sees the path below its mount point, as it does in production, and answ
 `flask.Request` handlers the SDK wraps. An unhandled error is functions-framework's crash response.
 """
 
+import contextlib
 import hmac
 import os
+import sys
 
 import flask
 from functions_framework import crash_handler, read_request
 from werkzeug.serving import WSGIRequestHandler, make_server
 
+from .diagnostics import ASYNC_HANDLER, describe, is_async_handler
+from .environment import EnvironmentGate
 from .manifest import DEFAULT_REGION
 
 SECRET_ENVIRON_KEY = "HTTP_X_FIREEMU_RUNNER_SECRET"
+# Task queue and Auth blocking functions enter through the HTTP wrapper as well (the Node runner's `signatureType`).
+HTTP_TRIGGERS = frozenset(("http", "tasks", "blockingAuth"))
 _METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
 
 
@@ -33,20 +39,68 @@ def _flask_app() -> flask.Flask:
     return app
 
 
+class ResponseBodyFailed(Exception):
+    """A response body failed while it was being sent. The details were logged inside the function's environment."""
+
+
+def _log_failure(name: str, error: BaseException) -> None:
+    diagnostic, _ = describe(error)
+    sys.stderr.write(f"[functions] {name}: {diagnostic[:8192]}\n")
+
+
+class _HeldBody:
+    """A response body that keeps its function's environment until the body is finished, whatever happens to it.
+
+    Closing the body, and running the callbacks `Response.call_on_close` registered, is user code: if it raises the
+    gate must still be released, or the process is locked with a secret in its environment. Errors are described
+    here, while the environment is still held, and the server sees only a plain exception.
+    """
+
+    def __init__(self, body, held: contextlib.ExitStack, name: str):
+        self._body = body
+        self._iterator = iter(body)
+        self._held = held
+        self._name = name
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        try:
+            return next(self._iterator)
+        except StopIteration:
+            raise
+        except BaseException as error:
+            _log_failure(self._name, error)
+            raise ResponseBodyFailed(type(error).__name__) from None
+
+    def close(self):
+        try:
+            close = getattr(self._body, "close", None)
+            if close is not None:
+                close()
+        except BaseException as error:  # the response has been sent; there is nobody to tell but the log
+            _log_failure(self._name, error)
+        finally:
+            self._held.close()
+
+
 class RunnerRouter:
     """Admission and routing in front of the Flask app."""
 
-    def __init__(self, functions: dict, manifest: dict, project: str, secret: str):
+    def __init__(self, functions: dict, manifest: dict, project: str, secret: str, gate: EnvironmentGate | None = None):
         self._app = _flask_app()
+        self._gate = gate if gate is not None else EnvironmentGate({})
         self._project = project
         self._secret = secret.encode()
         self._routes = {}
         for spec in manifest["functions"]:
-            if spec["trigger"]["type"] == "http":
+            if spec["trigger"]["type"] in HTTP_TRIGGERS:
                 self._routes[spec["name"]] = (
                     spec.get("region", DEFAULT_REGION),
                     functions[spec["entryPoint"]],
                     spec["entryPoint"],
+                    spec.get("platformOptions", {}).get("secrets"),
                 )
 
     @staticmethod
@@ -57,6 +111,10 @@ class RunnerRouter:
 
     def __call__(self, environ, start_response):
         presented = environ.pop(SECRET_ENVIRON_KEY, "").encode()
+        if not self._secret:
+            # A runner with no secret would accept any request without the header (an empty value equals an empty
+            # secret). The Node runner answers every request this way (`http-admission.mjs`).
+            return self._plain(start_response, "500 Internal Server Error", "FIREEMU_RUNNER_SECRET is required")
         if not hmac.compare_digest(presented, self._secret):
             return self._plain(start_response, "403 Forbidden", "forbidden")
         parts = environ.get("PATH_INFO", "").split("/")
@@ -70,12 +128,26 @@ class RunnerRouter:
         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)
+        if is_async_handler(route[1]):
+            # Production answers 500 as well (the coroutine is not a response); this says why.
+            sys.stderr.write(f"[functions] {name}: {ASYNC_HANDLER}\n")
+            return self._plain(start_response, "500 Internal Server Error", ASYNC_HANDLER)
+        # The environment this function is entitled to is held until its response is finished, a streamed body
+        # included: the secrets it declares are in the process environment for exactly that long.
+        held = contextlib.ExitStack()
+        held.enter_context(self._gate.hold(route[3]))
+        try:
+            # 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
+            body = self._app(environ, start_response)
+        except BaseException as error:
+            _log_failure(name, error)
+            held.close()
+            raise ResponseBodyFailed(type(error).__name__) from None
+        return _HeldBody(body, held, name)
 
 
 class _QuietHandler(WSGIRequestHandler):
@@ -83,9 +155,9 @@ class _QuietHandler(WSGIRequestHandler):
         pass
 
 
-def start_server(functions: dict, manifest: dict, secret: str):
+def start_server(functions: dict, manifest: dict, secret: str, gate: EnvironmentGate | None = None):
     """Starts the server on a free loopback port; returns `(server, port)`."""
-    router = RunnerRouter(functions, manifest, os.environ.get("GCLOUD_PROJECT", ""), secret)
+    router = RunnerRouter(functions, manifest, os.environ.get("GCLOUD_PROJECT", ""), secret, gate)
     server = make_server("127.0.0.1", 0, router, threaded=True, request_handler=_QuietHandler)
     import threading
 

package/package.json

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