firebase-functions 6.1.2 → 6.2.0

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

@@ -84,22 +84,27 @@ export interface CallableRequest<T = any> {
      * The raw request handled by the callable.
      */
     rawRequest: Request;
+    /**
+     * Whether this is a streaming request.
+     * Code can be optimized by not trying to generate a stream of chunks to
+     * call response.sendChunk on if request.acceptsStreaming is false.
+     * It is always safe, however, to call response.sendChunk as this will
+     * noop if acceptsStreaming is false.
+     */
+    acceptsStreaming: boolean;
 }
 /**
- * CallableProxyResponse exposes subset of express.Response object
- * to allow writing partial, streaming responses back to the client.
+ * CallableProxyResponse allows streaming response chunks and listening to signals
+ * triggered in events such as a disconnect.
  */
-export interface CallableProxyResponse {
+export interface CallableResponse<T = unknown> {
     /**
      * Writes a chunk of the response body to the client. This method can be called
      * multiple times to stream data progressively.
+     * Returns a promise of whether the data was written. This can be false, for example,
+     * if the request was not a streaming request. Rejects if there is a network error.
      */
-    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;
+    sendChunk: (chunk: T) => Promise<boolean>;
     /**
      * An AbortSignal that is triggered when the client disconnects or the
      * request is terminated prematurely.

package/lib/common/providers/https.js

@@ -283,13 +283,9 @@ async function checkTokens(req, ctx, options) {
         app: "INVALID",
         auth: "INVALID",
     };
-    await Promise.all([
-        Promise.resolve().then(async () => {
-            verifications.auth = await checkAuthToken(req, ctx);
-        }),
-        Promise.resolve().then(async () => {
-            verifications.app = await checkAppCheckToken(req, ctx, options);
-        }),
+    [verifications.auth, verifications.app] = await Promise.all([
+        checkAuthToken(req, ctx),
+        checkAppCheckToken(req, ctx, options),
     ]);
     const logPayload = {
         verifications,
@@ -405,6 +401,7 @@ function encodeSSE(data) {
 /** @internal */
 function wrapOnCallHandler(options, handler, version) {
     return async (req, res) => {
+        var _a;
         const abortController = new AbortController();
         let heartbeatInterval = null;
         const heartbeatSeconds = options.heartbeatSeconds === undefined ? exports.DEFAULT_HEARTBEAT_SECONDS : options.heartbeatSeconds;
@@ -487,6 +484,12 @@ function wrapOnCallHandler(options, handler, version) {
                 throw new HttpsError("invalid-argument", "Unsupported Accept header 'text/event-stream'");
             }
             const data = decode(req.body.data);
+            if (options.authPolicy) {
+                const authorized = await options.authPolicy((_a = context.auth) !== null && _a !== void 0 ? _a : null, data);
+                if (!authorized) {
+                    throw new HttpsError("permission-denied", "Permission Denied");
+                }
+            }
             let result;
             if (version === "gcfv1") {
                 result = await handler(data, context);
@@ -495,26 +498,38 @@ function wrapOnCallHandler(options, handler, version) {
                 const arg = {
                     ...context,
                     data,
+                    acceptsStreaming,
                 };
                 const responseProxy = {
-                    write(chunk) {
+                    sendChunk(chunk) {
                         // if client doesn't accept sse-protocol, response.write() is no-op.
                         if (!acceptsStreaming) {
-                            return false;
+                            return Promise.resolve(false);
                         }
                         // if connection is already closed, response.write() is no-op.
                         if (abortController.signal.aborted) {
-                            return false;
+                            return Promise.resolve(false);
                         }
                         const formattedData = encodeSSE({ message: chunk });
-                        const wrote = res.write(formattedData);
+                        let resolve;
+                        let reject;
+                        const p = new Promise((res, rej) => {
+                            resolve = res;
+                            reject = rej;
+                        });
+                        const wrote = res.write(formattedData, (error) => {
+                            if (error) {
+                                reject(error);
+                                return;
+                            }
+                            resolve(wrote);
+                        });
                         // Reset heartbeat timer after successful write
                         if (wrote && heartbeatInterval !== null && heartbeatSeconds > 0) {
                             scheduleHeartbeat();
                         }
-                        return wrote;
+                        return p;
                     },
-                    acceptsStreaming,
                     signal: abortController.signal,
                 };
                 if (acceptsStreaming) {

package/lib/runtime/loader.js

@@ -40,8 +40,8 @@ async function loadModule(functionsDir) {
         return require(path.resolve(absolutePath));
     }
     catch (e) {
-        if (e.code === "ERR_REQUIRE_ESM") {
-            // This is an ESM package!
+        if (e.code === "ERR_REQUIRE_ESM" || e.code === "ERR_REQUIRE_ASYNC_MODULE") {
+            // This is an ESM package, or one containing top-level awaits!
             const modulePath = require.resolve(absolutePath);
             // Resolve module path to file:// URL. Required for windows support.
             const moduleURL = url.pathToFileURL(modulePath).href;

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

@@ -1,6 +1,6 @@
 import * as express from "express";
 import { ResetValue } from "../../common/options";
-import { CallableRequest, CallableProxyResponse, FunctionsErrorCode, HttpsError, Request } from "../../common/providers/https";
+import { CallableRequest, CallableResponse, FunctionsErrorCode, HttpsError, Request, AuthData } from "../../common/providers/https";
 import { ManifestEndpoint } from "../../runtime/manifest";
 import { GlobalOptions, SupportedRegion } from "../options";
 import { Expression } from "../../params";
@@ -101,7 +101,7 @@ export interface HttpsOptions extends Omit<GlobalOptions, "region" | "enforceApp
 /**
  * Options that can be set on a callable HTTPS function.
  */
-export interface CallableOptions extends HttpsOptions {
+export interface CallableOptions<T = any> extends HttpsOptions {
     /**
      * Determines whether Firebase AppCheck is enforced.
      * When true, requests with invalid tokens autorespond with a 401
@@ -139,7 +139,22 @@ export interface CallableOptions extends HttpsOptions {
      * Defaults to 30 seconds.
      */
     heartbeatSeconds?: number | null;
+    /**
+     * Callback for whether a request is authorized.
+     *
+     * Designed to allow reusable auth policies to be passed as an options object. Two built-in reusable policies exist:
+     * isSignedIn and hasClaim.
+     */
+    authPolicy?: (auth: AuthData | null, data: T) => boolean | Promise<boolean>;
 }
+/**
+ * An auth policy that requires a user to be signed in.
+ */
+export declare const isSignedIn: () => (auth: AuthData | null) => boolean;
+/**
+ * An auth policy that requires a user to be both signed in and have a specific claim (optionally with a specific value)
+ */
+export declare const hasClaim: (claim: string, value?: string) => (auth: AuthData | null) => boolean;
 /**
  * Handles HTTPS requests.
  */
@@ -156,12 +171,16 @@ res: express.Response) => void | Promise<void>) & {
 /**
  * Creates a callable method for clients to call using a Firebase SDK.
  */
-export interface CallableFunction<T, Return> extends HttpsFunction {
+export interface CallableFunction<T, Return, Stream = unknown> extends HttpsFunction {
     /** Executes the handler function with the provided data as input. Used for unit testing.
      * @param data - An input for the handler function.
      * @returns The output of the handler function.
      */
-    run(data: CallableRequest<T>): Return;
+    run(request: CallableRequest<T>): Return;
+    stream(request: CallableRequest<T>, response: CallableResponse<Stream>): {
+        stream: AsyncIterator<Stream>;
+        output: Return;
+    };
 }
 /**
  * Handles HTTPS requests.
@@ -182,10 +201,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>, response?: CallableProxyResponse) => Return): CallableFunction<T, Return extends Promise<unknown> ? Return : Promise<Return>>;
+export declare function onCall<T = any, Return = any | Promise<any>, Stream = unknown>(opts: CallableOptions<T>, handler: (request: CallableRequest<T>, response?: CallableResponse<Stream>) => Return): CallableFunction<T, Return extends Promise<unknown> ? Return : Promise<Return>, Stream>;
 /**
  * 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>, response?: CallableProxyResponse) => Return): CallableFunction<T, Return extends Promise<unknown> ? Return : Promise<Return>>;
+export declare function onCall<T = any, Return = any | Promise<any>, Stream = unknown>(handler: (request: CallableRequest<T>, response?: CallableResponse<Stream>) => Return): CallableFunction<T, Return extends Promise<unknown> ? Return : Promise<Return>>;

package/lib/v2/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.onCall = exports.onRequest = exports.HttpsError = void 0;
+exports.onCall = exports.onRequest = exports.hasClaim = exports.isSignedIn = exports.HttpsError = void 0;
 /**
  * Cloud functions to handle HTTPS request or callable RPCs.
  * @packageDocumentation
@@ -35,6 +35,24 @@ Object.defineProperty(exports, "HttpsError", { enumerable: true, get: function (
 const manifest_1 = require("../../runtime/manifest");
 const options = require("../options");
 const onInit_1 = require("../../common/onInit");
+/**
+ * An auth policy that requires a user to be signed in.
+ */
+const isSignedIn = () => (auth) => !!auth;
+exports.isSignedIn = isSignedIn;
+/**
+ * An auth policy that requires a user to be both signed in and have a specific claim (optionally with a specific value)
+ */
+const hasClaim = (claim, value) => (auth) => {
+    if (!auth) {
+        return false;
+    }
+    if (!(claim in auth.token)) {
+        return false;
+    }
+    return !value || auth.token[claim] === value;
+};
+exports.hasClaim = hasClaim;
 function onRequest(optsOrHandler, handler) {
     let opts;
     if (arguments.length === 1) {
@@ -131,12 +149,13 @@ function onCall(optsOrHandler, handler) {
         origin = origin[0];
     }
     // fix the length of handler to make the call to handler consistent
-    const fixedLen = (req, resp) => (0, onInit_1.withInit)(handler)(req, resp);
+    const fixedLen = (req, resp) => 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,
         heartbeatSeconds: opts.heartbeatSeconds,
+        authPolicy: opts.authPolicy,
     }, fixedLen, "gcfv2");
     func = (0, trace_1.wrapTraceContext)((0, onInit_1.withInit)(func));
     Object.defineProperty(func, "__trigger", {
@@ -175,7 +194,18 @@ function onCall(optsOrHandler, handler) {
         },
         callableTrigger: {},
     };
+    // TODO: in the next major version, do auth/appcheck in these helper methods too.
     func.run = (0, onInit_1.withInit)(handler);
+    func.stream = () => {
+        return {
+            stream: {
+                next() {
+                    return Promise.reject("Coming soon");
+                },
+            },
+            output: Promise.reject("Coming soon"),
+        };
+    };
     return func;
 }
 exports.onCall = onCall;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firebase-functions",
-  "version": "6.1.2",
+  "version": "6.2.0",
   "description": "Firebase SDK for Cloud Functions",
   "keywords": [
     "firebase",