firebase-functions 6.1.0 → 6.1.2

package/lib/common/providers/https.d.ts

@@ -85,6 +85,27 @@ export interface CallableRequest<T = any> {
      */
     rawRequest: Request;
 }
+/**
+ * CallableProxyResponse exposes subset of express.Response object
+ * to allow writing partial, streaming responses back to the client.
+ */
+export interface CallableProxyResponse {
+    /**
+     * Writes a chunk of the response body to the client. This method can be called
+     * multiple times to stream data progressively.
+     */
+    write: express.Response["write"];
+    /**
+     * Indicates whether the client has requested and can handle streaming responses.
+     * This should be checked before attempting to stream data to avoid compatibility issues.
+     */
+    acceptsStreaming: boolean;
+    /**
+     * An AbortSignal that is triggered when the client disconnects or the
+     * request is terminated prematurely.
+     */
+    signal: AbortSignal;
+}
 /**
  * The set of Firebase Functions status codes. The codes are the same at the
  * ones exposed by {@link https://github.com/grpc/grpc/blob/master/doc/statuscodes.md | gRPC}.

package/lib/common/providers/https.js

@@ -21,7 +21,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.onCallHandler = exports.checkAuthToken = exports.unsafeDecodeAppCheckToken = exports.unsafeDecodeIdToken = exports.unsafeDecodeToken = exports.decode = exports.encode = exports.isValidRequest = exports.HttpsError = exports.ORIGINAL_AUTH_HEADER = exports.CALLABLE_AUTH_HEADER = void 0;
+exports.onCallHandler = exports.checkAuthToken = exports.unsafeDecodeAppCheckToken = exports.unsafeDecodeIdToken = exports.unsafeDecodeToken = exports.decode = exports.encode = exports.isValidRequest = exports.HttpsError = exports.DEFAULT_HEARTBEAT_SECONDS = exports.ORIGINAL_AUTH_HEADER = exports.CALLABLE_AUTH_HEADER = void 0;
 const cors = require("cors");
 const logger = require("../../logger");
 // TODO(inlined): Decide whether we want to un-version apps or whether we want a
@@ -35,6 +35,8 @@ const JWT_REGEX = /^[a-zA-Z0-9\-_=]+?\.[a-zA-Z0-9\-_=]+?\.([a-zA-Z0-9\-_=]+)?$/;
 exports.CALLABLE_AUTH_HEADER = "x-callable-context-auth";
 /** @internal */
 exports.ORIGINAL_AUTH_HEADER = "x-original-auth";
+/** @internal */
+exports.DEFAULT_HEARTBEAT_SECONDS = 30;
 /**
  * Standard error codes and HTTP statuses for different ways a request can fail,
  * as defined by:
@@ -385,8 +387,8 @@ async function checkAppCheckToken(req, ctx, options) {
     }
 }
 /** @internal */
-function onCallHandler(options, handler) {
-    const wrapped = wrapOnCallHandler(options, handler);
+function onCallHandler(options, handler, version) {
+    const wrapped = wrapOnCallHandler(options, handler, version);
     return (req, res) => {
         return new Promise((resolve) => {
             res.on("finish", resolve);
@@ -397,9 +399,36 @@ function onCallHandler(options, handler) {
     };
 }
 exports.onCallHandler = onCallHandler;
+function encodeSSE(data) {
+    return `data: ${JSON.stringify(data)}\n`;
+}
 /** @internal */
-function wrapOnCallHandler(options, handler) {
+function wrapOnCallHandler(options, handler, version) {
     return async (req, res) => {
+        const abortController = new AbortController();
+        let heartbeatInterval = null;
+        const heartbeatSeconds = options.heartbeatSeconds === undefined ? exports.DEFAULT_HEARTBEAT_SECONDS : options.heartbeatSeconds;
+        const clearScheduledHeartbeat = () => {
+            if (heartbeatInterval) {
+                clearTimeout(heartbeatInterval);
+                heartbeatInterval = null;
+            }
+        };
+        const scheduleHeartbeat = () => {
+            clearScheduledHeartbeat();
+            if (!abortController.signal.aborted) {
+                heartbeatInterval = setTimeout(() => {
+                    if (!abortController.signal.aborted) {
+                        res.write(": ping\n");
+                        scheduleHeartbeat();
+                    }
+                }, heartbeatSeconds * 1000);
+            }
+        };
+        res.on("close", () => {
+            clearScheduledHeartbeat();
+            abortController.abort();
+        });
         try {
             if (!isValidRequest(req)) {
                 logger.error("Invalid request, unable to process.");
@@ -413,7 +442,7 @@ function wrapOnCallHandler(options, handler) {
             // The original monkey-patched code lived in the functionsEmulatorRuntime
             // (link: https://github.com/firebase/firebase-tools/blob/accea7abda3cc9fa6bb91368e4895faf95281c60/src/emulator/functionsEmulatorRuntime.ts#L480)
             // and was not compatible with how monorepos separate out packages (see https://github.com/firebase/firebase-tools/issues/5210).
-            if ((0, debug_1.isDebugFeatureEnabled)("skipTokenVerification") && handler.length === 2) {
+            if ((0, debug_1.isDebugFeatureEnabled)("skipTokenVerification") && version === "gcfv1") {
                 const authContext = context.rawRequest.header(exports.CALLABLE_AUTH_HEADER);
                 if (authContext) {
                     logger.debug("Callable functions auth override", {
@@ -452,9 +481,14 @@ function wrapOnCallHandler(options, handler) {
                 // pushes with FCM. In that case, the FCM APIs will validate the token.
                 context.instanceIdToken = req.header("Firebase-Instance-ID-Token");
             }
+            const acceptsStreaming = req.header("accept") === "text/event-stream";
+            if (acceptsStreaming && version === "gcfv1") {
+                // streaming responses are not supported in v1 callable
+                throw new HttpsError("invalid-argument", "Unsupported Accept header 'text/event-stream'");
+            }
             const data = decode(req.body.data);
             let result;
-            if (handler.length === 2) {
+            if (version === "gcfv1") {
                 result = await handler(data, context);
             }
             else {
@@ -462,26 +496,79 @@ function wrapOnCallHandler(options, handler) {
                     ...context,
                     data,
                 };
+                const responseProxy = {
+                    write(chunk) {
+                        // if client doesn't accept sse-protocol, response.write() is no-op.
+                        if (!acceptsStreaming) {
+                            return false;
+                        }
+                        // if connection is already closed, response.write() is no-op.
+                        if (abortController.signal.aborted) {
+                            return false;
+                        }
+                        const formattedData = encodeSSE({ message: chunk });
+                        const wrote = res.write(formattedData);
+                        // Reset heartbeat timer after successful write
+                        if (wrote && heartbeatInterval !== null && heartbeatSeconds > 0) {
+                            scheduleHeartbeat();
+                        }
+                        return wrote;
+                    },
+                    acceptsStreaming,
+                    signal: abortController.signal,
+                };
+                if (acceptsStreaming) {
+                    // SSE always responds with 200
+                    res.status(200);
+                    if (heartbeatSeconds !== null && heartbeatSeconds > 0) {
+                        scheduleHeartbeat();
+                    }
+                }
                 // For some reason the type system isn't picking up that the handler
                 // is a one argument function.
-                result = await handler(arg);
+                result = await handler(arg, responseProxy);
+                clearScheduledHeartbeat();
+            }
+            if (!abortController.signal.aborted) {
+                // Encode the result as JSON to preserve types like Dates.
+                result = encode(result);
+                // If there was some result, encode it in the body.
+                const responseBody = { result };
+                if (acceptsStreaming) {
+                    res.write(encodeSSE(responseBody));
+                    res.end();
+                }
+                else {
+                    res.status(200).send(responseBody);
+                }
+            }
+            else {
+                res.end();
             }
-            // Encode the result as JSON to preserve types like Dates.
-            result = encode(result);
-            // If there was some result, encode it in the body.
-            const responseBody = { result };
-            res.status(200).send(responseBody);
         }
         catch (err) {
-            let httpErr = err;
-            if (!(err instanceof HttpsError)) {
-                // This doesn't count as an 'explicit' error.
-                logger.error("Unhandled error", err);
-                httpErr = new HttpsError("internal", "INTERNAL");
+            if (!abortController.signal.aborted) {
+                let httpErr = err;
+                if (!(err instanceof HttpsError)) {
+                    // This doesn't count as an 'explicit' error.
+                    logger.error("Unhandled error", err);
+                    httpErr = new HttpsError("internal", "INTERNAL");
+                }
+                const { status } = httpErr.httpErrorCode;
+                const body = { error: httpErr.toJSON() };
+                if (version === "gcfv2" && req.header("accept") === "text/event-stream") {
+                    res.send(encodeSSE(body));
+                }
+                else {
+                    res.status(status).send(body);
+                }
             }
-            const { status } = httpErr.httpErrorCode;
-            const body = { error: httpErr.toJSON() };
-            res.status(status).send(body);
+            else {
+                res.end();
+            }
+        }
+        finally {
+            clearScheduledHeartbeat();
         }
     };
 }

package/lib/v1/providers/https.js

@@ -70,9 +70,8 @@ function _onRequestWithOptions(handler, options) {
 exports._onRequestWithOptions = _onRequestWithOptions;
 /** @internal */
 function _onCallWithOptions(handler, options) {
-    // onCallHandler sniffs the function length of the passed-in callback
-    // and the user could have only tried to listen to data. Wrap their handler
-    // in another handler to avoid accidentally triggering the v2 API
+    // fix the length of handler to make the call to handler consistent
+    // in the onCallHandler
     const fixedLen = (data, context) => {
         return (0, onInit_1.withInit)(handler)(data, context);
     };
@@ -80,7 +79,7 @@ function _onCallWithOptions(handler, options) {
         enforceAppCheck: options.enforceAppCheck,
         consumeAppCheckToken: options.consumeAppCheckToken,
         cors: { origin: true, methods: "POST" },
-    }, fixedLen));
+    }, fixedLen, "gcfv1"));
     func.__trigger = {
         labels: {},
         ...(0, cloud_functions_1.optionsToTrigger)(options),

package/lib/v2/providers/https.d.ts

@@ -1,6 +1,6 @@
 import * as express from "express";
 import { ResetValue } from "../../common/options";
-import { CallableRequest, FunctionsErrorCode, HttpsError, Request } from "../../common/providers/https";
+import { CallableRequest, CallableProxyResponse, FunctionsErrorCode, HttpsError, Request } from "../../common/providers/https";
 import { ManifestEndpoint } from "../../runtime/manifest";
 import { GlobalOptions, SupportedRegion } from "../options";
 import { Expression } from "../../params";
@@ -132,6 +132,13 @@ export interface CallableOptions extends HttpsOptions {
      * further decisions, such as requiring additional security checks or rejecting the request.
      */
     consumeAppCheckToken?: boolean;
+    /**
+     * Time in seconds between sending heartbeat messages to keep the connection
+     * alive. Set to `null` to disable heartbeats.
+     *
+     * Defaults to 30 seconds.
+     */
+    heartbeatSeconds?: number | null;
 }
 /**
  * Handles HTTPS requests.
@@ -175,10 +182,10 @@ export declare function onRequest(handler: (request: Request, response: express.
  * @param handler - A function that takes a {@link https.CallableRequest}.
  * @returns A function that you can export and deploy.
  */
-export declare function onCall<T = any, Return = any | Promise<any>>(opts: CallableOptions, handler: (request: CallableRequest<T>) => Return): CallableFunction<T, Return extends Promise<unknown> ? Return : Promise<Return>>;
+export declare function onCall<T = any, Return = any | Promise<any>>(opts: CallableOptions, handler: (request: CallableRequest<T>, response?: CallableProxyResponse) => Return): CallableFunction<T, Return extends Promise<unknown> ? Return : Promise<Return>>;
 /**
  * Declares a callable method for clients to call using a Firebase SDK.
  * @param handler - A function that takes a {@link https.CallableRequest}.
  * @returns A function that you can export and deploy.
  */
-export declare function onCall<T = any, Return = any | Promise<any>>(handler: (request: CallableRequest<T>) => Return): CallableFunction<T, Return extends Promise<unknown> ? Return : Promise<Return>>;
+export declare function onCall<T = any, Return = any | Promise<any>>(handler: (request: CallableRequest<T>, response?: CallableProxyResponse) => Return): CallableFunction<T, Return extends Promise<unknown> ? Return : Promise<Return>>;

package/lib/v2/providers/https.js

@@ -130,15 +130,15 @@ function onCall(optsOrHandler, handler) {
     if (Array.isArray(origin) && origin.length === 1) {
         origin = origin[0];
     }
-    // onCallHandler sniffs the function length to determine which API to present.
-    // fix the length to prevent api versions from being mismatched.
-    const fixedLen = (req) => (0, onInit_1.withInit)(handler)(req);
+    // fix the length of handler to make the call to handler consistent
+    const fixedLen = (req, resp) => (0, onInit_1.withInit)(handler)(req, resp);
     let func = (0, https_1.onCallHandler)({
         cors: { origin, methods: "POST" },
         enforceAppCheck: (_a = opts.enforceAppCheck) !== null && _a !== void 0 ? _a : options.getGlobalOptions().enforceAppCheck,
         consumeAppCheckToken: opts.consumeAppCheckToken,
-    }, fixedLen);
-    func = (0, trace_1.wrapTraceContext)(func);
+        heartbeatSeconds: opts.heartbeatSeconds,
+    }, fixedLen, "gcfv2");
+    func = (0, trace_1.wrapTraceContext)((0, onInit_1.withInit)(func));
     Object.defineProperty(func, "__trigger", {
         get: () => {
             const baseOpts = options.optionsToTriggerAnnotations(options.getGlobalOptions());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firebase-functions",
-  "version": "6.1.0",
+  "version": "6.1.2",
   "description": "Firebase SDK for Cloud Functions",
   "keywords": [
     "firebase",
@@ -287,7 +287,7 @@
     "@types/nock": "^10.0.3",
     "@types/node": "^14.18.24",
     "@types/node-fetch": "^3.0.3",
-    "@types/sinon": "^7.0.13",
+    "@types/sinon": "^9.0.11",
     "@typescript-eslint/eslint-plugin": "^5.33.1",
     "@typescript-eslint/parser": "^5.33.1",
     "api-extractor-model-me": "^0.1.1",
@@ -299,7 +299,7 @@
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-jsdoc": "^39.2.9",
     "eslint-plugin-prettier": "^4.0.0",
-    "firebase-admin": "^12.1.0",
+    "firebase-admin": "^13.0.0",
     "js-yaml": "^3.13.1",
     "jsdom": "^16.2.1",
     "jsonwebtoken": "^9.0.0",
@@ -313,13 +313,13 @@
     "prettier": "^2.7.1",
     "protobufjs-cli": "^1.1.1",
     "semver": "^7.3.5",
-    "sinon": "^7.3.2",
+    "sinon": "^9.2.4",
     "ts-node": "^10.4.0",
     "typescript": "^4.3.5",
     "yargs": "^15.3.1"
   },
   "peerDependencies": {
-    "firebase-admin": "^11.10.0 || ^12.0.0"
+    "firebase-admin": "^11.10.0 || ^12.0.0 || ^13.0.0"
   },
   "engines": {
     "node": ">=14.10.0"