Firebase Functions HTTP integration compatibility
This page tracks an integration contract: unchanged Firebase code run through a Pyric runtime seam, so there is no separate Firebase public API to measure. The rows below are its signed behavior inventory.
Status legend
Conforming: unchanged source matches production under replay
Not implemented yet: explicitly outside the implemented slice
Unverified: production target or local replay is incomplete
onRequest serving, request, and response contract
onRequest(handler) / onRequest(options, handler)A discovered v2 onRequest export is served at /{projectId}/{region}/{name} on the sandbox server and the Vite dev server; the region comes from the options, then setGlobalOptions, then us-central1.
upstream: the emulator routes /{projectId}/:region/:trigger_name (firebase-tools
lib/emulator/functionsEmulator.js:151-153) and the SDK sets __endpoint.httpsTrigger and region (lib/v2/providers/https.js:44-108). Region resolution: packages/cli/test/functions-http/discovery.test.ts; the Vite plane: packages/cli/test/functions-http/vite-plane.test.ts. Local assertion: packages/cli/test/functions-http/oracle-conformance.test.ts assertion set functions-http#1. (Structured evidence: routes.test.ts)functions.https.onRequest(handler) (v1)v1 functions.https.onRequest and functions.region(r).https.onRequest exports are served the same way as v2, with us-central1 when no region is set.
upstream: v1 sets the same
httpsTrigger with platform: "gcfv1" (lib/v1/providers/https.js:33-50). Production behavior needs functions-http-onrequest-v1.req.method, req.query, req.headersThe request method, the parsed query (repeated and bracketed keys), and the request headers reach the handler; the names of the headers production adds or strips match.
Production behavior needs
functions-http-onrequest-basic-get.req.path, req.url, req.originalUrl, req.baseUrlThe handler sees the path after the function name, with / for the function root, as production shows it on cloudfunctions.net and on the run.app URL.
upstream: the emulator strips the /{project}/{region}/{name} prefix (
functionsEmulator.js:1264). Production behavior needs functions-http-onrequest-subpath.req.body, req.rawBodyA JSON body is parsed to req.body, and req.rawBody holds the exact request bytes.
upstream: functions-framework-nodejs parses json and saves rawBody; the emulator matches the parser order (
functionsEmulatorRuntime.js:543-561). Production behavior needs functions-http-onrequest-body-parsing.req.body, req.rawBodytext, urlencoded (extended), octet-stream, an unknown content type, no content type, and an empty body map to req.body and req.rawBody as production maps them.
Production behavior needs
functions-http-onrequest-body-parsing.onRequest body parsingA JSON body that does not parse is refused before the handler runs, with the status, content type, and body production answers.
Production behavior needs
functions-http-onrequest-malformed-json.res.status, res.set, res.json, res.redirect, res.cookie, res.writeStatus codes, headers, JSON bodies, redirects, cookies, empty responses, and streamed res.write chunks arrive unchanged, with no x-powered-by header.
upstream: functions-framework-nodejs disables
x-powered-by. Production behavior needs functions-http-onrequest-response-shapes.onRequest handler failureA handler that throws, or returns a rejected promise, before responding answers 500 Internal Server Error.
upstream:
withErrorHandler logs "Unhandled error" and answers 500 when headers are unsent (lib/common/providers/https.js:563-574). Production behavior needs functions-http-onrequest-handler-failure.onRequest handler failureA handler that throws after sending headers and part of the body ends the response; the client receives what production shows.
Production behavior needs
functions-http-onrequest-headers-sent-failure.onRequest({ timeoutSeconds }, handler)A handler that never responds is cut at timeoutSeconds (60 when unset) with the status production answers.
upstream: the emulator defaults timeoutSeconds to 60 (
functionsEmulatorShared.js:97) and destroys the socket on expiry (functionsRuntimeWorker.js:115-141), which production need not match. Production behavior needs functions-http-onrequest-no-response-timeout.onRequest handler failureAn exception thrown asynchronously outside the handler (a timer callback) has the production outcome for the request; RTDB triggers served by the same pyric child keep running.
Owner decision: the shared pyric child catches the exception rather than restarting, because RTDB triggers run in it. Production behavior needs
functions-http-onrequest-uncaught-async.onRequest({ cors }, handler)With cors unset, responses carry no CORS headers and an OPTIONS request reaches the handler, unlike the Functions emulator, which enables CORS for every onRequest function.
upstream: the emulator forces
enableCors: true unless cors: false (functionsEmulator.js:990-993, https.js:55-57). Production behavior needs functions-http-onrequest-cors-unset.onRequest({ cors }, handler)cors: true, a string list, and a RegExp answer preflights in the SDK middleware and reflect an allowed origin or omit the header for a denied one.
upstream: the SDK wraps the handler in the
cors package with origin from the option (https.js:53-71). Production behavior needs functions-http-onrequest-cors-configured.onRequest({ invoker: 'private' }, handler)Production refuses an unauthenticated call to an invoker: 'private' function with 403. Pyric serves it without authentication to the app's own pages and to callers that are not browser pages, refuses another page (a foreign Origin, or Sec-Fetch-Site cross-site or same-site with no Origin) with 403, warns once per function, and records the difference as a by-design divergence.
upstream: the emulator never enforces
invoker (no reference in lib/emulator). Owner decision: serve and warn. Production behavior needs functions-http-onrequest-invoker-private.onRequest routingA request for a function name the project does not define answers with the production 404 shape.
upstream: the emulator answers
404 Function X does not exist, valid functions are: ... (functionsEmulator.js:1233-1247). Production behavior needs functions-http-onrequest-not-found.firebase.json hosting.rewrites[].functionA hosting rewrite to a function routes the full original path and query, honors { functionId, region }, takes the region from the function's source when the rewrite names none (us-central1 only when the source names none either), cuts the request at Hosting's 60 s, and forwards only the __session cookie.
upstream: firebase-tools appends the original req.url and sets X-Forwarded-Host and X-Original-Url (
lib/hosting/functionsProxy.js:20-31, lib/hosting/proxy.js:29-50). The __session-only cookie rule comes from the Hosting docs (https://firebase.google.com/docs/hosting/manage-cache#using_cookies); the emulator forwards every cookie, because proxy.js copies the full Cookie header after setting __session. Production behavior needs functions-http-hosting-rewrite.firebase-admin inside onRequestA firebase-admin write the handler awaits is visible to a client of the same sandbox before the HTTP response arrives.
The child runs with PYRIC_SANDBOX=remote:<serveUrl> and pre-initializes the ambient firebase-admin app; a bare initializeApp() returns it (
pyric-admin/src/app/index.ts:131-139). Both planes: the suite and packages/cli/test/functions-http/vite-plane.test.ts read the document from the peer sandbox as soon as the response arrives. Local assertion: packages/cli/test/functions-http/oracle-conformance.test.ts assertion set functions-http#18.onRequest({ maxInstances, minInstances, concurrency, memory, cpu }, handler)Requests to one function run concurrently. maxInstances, minInstances, concurrency, memory, and cpu are deploy-time scaling options that pyric reads and does not apply: it has no instance model.
upstream: these options only shape the deployed Cloud Run service (
__endpoint fields read by firebase-tools at deploy). Local assertion: packages/cli/test/functions-http/oracle-conformance.test.ts assertion set functions-http#19.onRequest routingA request to a discovered function while the child is starting, reloading, or waiting for a sandbox peer answers 503 with a message naming the cause, never a static 404.
Pyric-owned lifecycle (
packages/cli/src/functions/development-runtime.ts, functions/http/gateway.ts). Each cause (waiting for a peer, starting, reloading, failed) is pinned in packages/cli/test/functions-http/gateway.test.ts; both planes answer 503 on the emulator path and a hosting rewrite before a peer connects. Local assertion: packages/cli/test/functions-http/oracle-conformance.test.ts assertion set functions-http#20. (Structured evidence: vite-plane.test.ts)onRequest execution recordEach request a function serves lands one execution record with an http cause (method, path, status); in browser mode the first slice records it as a log line.
Pyric-owned. Owner decision: log lines only, in browser mode, for the first slice; no
execution_finished event on the sandbox stream yet. The line names the export, method, path, status, and duration (packages/cli/src/functions/http/report.ts); both planes print one per request. Local assertion: packages/cli/test/functions-http/oracle-conformance.test.ts assertion set functions-http#21. (Structured evidence: gateway.test.ts, vite-plane.test.ts)Current gaps
Not implemented yet
Tracked behavior that is not implemented in the current contract.
onRequest({ maxInstances, minInstances, concurrency, memory, cpu }, handler)Requests to one function run concurrently. maxInstances, minInstances, concurrency, memory, and cpu are deploy-time scaling options that pyric reads and does not apply: it has no instance model.
upstream: these options only shape the deployed Cloud Run service (
__endpoint fields read by firebase-tools at deploy). Local assertion: packages/cli/test/functions-http/oracle-conformance.test.ts assertion set functions-http#19.Unverified
Tracked behavior whose available evidence does not yet establish the production result.
functions.https.onRequest(handler) (v1)v1 functions.https.onRequest and functions.region(r).https.onRequest exports are served the same way as v2, with us-central1 when no region is set.
upstream: v1 sets the same
httpsTrigger with platform: "gcfv1" (lib/v1/providers/https.js:33-50). Production behavior needs functions-http-onrequest-v1.req.method, req.query, req.headersThe request method, the parsed query (repeated and bracketed keys), and the request headers reach the handler; the names of the headers production adds or strips match.
Production behavior needs
functions-http-onrequest-basic-get.req.path, req.url, req.originalUrl, req.baseUrlThe handler sees the path after the function name, with / for the function root, as production shows it on cloudfunctions.net and on the run.app URL.
upstream: the emulator strips the /{project}/{region}/{name} prefix (
functionsEmulator.js:1264). Production behavior needs functions-http-onrequest-subpath.req.body, req.rawBodyA JSON body is parsed to req.body, and req.rawBody holds the exact request bytes.
upstream: functions-framework-nodejs parses json and saves rawBody; the emulator matches the parser order (
functionsEmulatorRuntime.js:543-561). Production behavior needs functions-http-onrequest-body-parsing.req.body, req.rawBodytext, urlencoded (extended), octet-stream, an unknown content type, no content type, and an empty body map to req.body and req.rawBody as production maps them.
Production behavior needs
functions-http-onrequest-body-parsing.onRequest body parsingA JSON body that does not parse is refused before the handler runs, with the status, content type, and body production answers.
Production behavior needs
functions-http-onrequest-malformed-json.res.status, res.set, res.json, res.redirect, res.cookie, res.writeStatus codes, headers, JSON bodies, redirects, cookies, empty responses, and streamed res.write chunks arrive unchanged, with no x-powered-by header.
upstream: functions-framework-nodejs disables
x-powered-by. Production behavior needs functions-http-onrequest-response-shapes.onRequest handler failureA handler that throws, or returns a rejected promise, before responding answers 500 Internal Server Error.
upstream:
withErrorHandler logs "Unhandled error" and answers 500 when headers are unsent (lib/common/providers/https.js:563-574). Production behavior needs functions-http-onrequest-handler-failure.onRequest handler failureA handler that throws after sending headers and part of the body ends the response; the client receives what production shows.
Production behavior needs
functions-http-onrequest-headers-sent-failure.onRequest({ timeoutSeconds }, handler)A handler that never responds is cut at timeoutSeconds (60 when unset) with the status production answers.
upstream: the emulator defaults timeoutSeconds to 60 (
functionsEmulatorShared.js:97) and destroys the socket on expiry (functionsRuntimeWorker.js:115-141), which production need not match. Production behavior needs functions-http-onrequest-no-response-timeout.onRequest handler failureAn exception thrown asynchronously outside the handler (a timer callback) has the production outcome for the request; RTDB triggers served by the same pyric child keep running.
Owner decision: the shared pyric child catches the exception rather than restarting, because RTDB triggers run in it. Production behavior needs
functions-http-onrequest-uncaught-async.onRequest({ cors }, handler)With cors unset, responses carry no CORS headers and an OPTIONS request reaches the handler, unlike the Functions emulator, which enables CORS for every onRequest function.
upstream: the emulator forces
enableCors: true unless cors: false (functionsEmulator.js:990-993, https.js:55-57). Production behavior needs functions-http-onrequest-cors-unset.onRequest({ cors }, handler)cors: true, a string list, and a RegExp answer preflights in the SDK middleware and reflect an allowed origin or omit the header for a denied one.
upstream: the SDK wraps the handler in the
cors package with origin from the option (https.js:53-71). Production behavior needs functions-http-onrequest-cors-configured.onRequest({ invoker: 'private' }, handler)Production refuses an unauthenticated call to an invoker: 'private' function with 403. Pyric serves it without authentication to the app's own pages and to callers that are not browser pages, refuses another page (a foreign Origin, or Sec-Fetch-Site cross-site or same-site with no Origin) with 403, warns once per function, and records the difference as a by-design divergence.
upstream: the emulator never enforces
invoker (no reference in lib/emulator). Owner decision: serve and warn. Production behavior needs functions-http-onrequest-invoker-private.onRequest routingA request for a function name the project does not define answers with the production 404 shape.
upstream: the emulator answers
404 Function X does not exist, valid functions are: ... (functionsEmulator.js:1233-1247). Production behavior needs functions-http-onrequest-not-found.firebase.json hosting.rewrites[].functionA hosting rewrite to a function routes the full original path and query, honors { functionId, region }, takes the region from the function's source when the rewrite names none (us-central1 only when the source names none either), cuts the request at Hosting's 60 s, and forwards only the __session cookie.
upstream: firebase-tools appends the original req.url and sets X-Forwarded-Host and X-Original-Url (
lib/hosting/functionsProxy.js:20-31, lib/hosting/proxy.js:29-50). The __session-only cookie rule comes from the Hosting docs (https://firebase.google.com/docs/hosting/manage-cache#using_cookies); the emulator forwards every cookie, because proxy.js copies the full Cookie header after setting __session. Production behavior needs functions-http-hosting-rewrite.