Firebase SDK for Cloud Functions

The firebase-functions package allows you to define Cloud Functions that run in a hosted, private, and scalable Node.js environment. You can write code that responds to events from various Firebase services (like Realtime Database, Firestore, or Authentication) and invokes functionality exposed by the Firebase platform.

To use the SDK, you import specific event triggers from sub-modules (e.g., firebase-functions/database) and use the logger module for structured logging.

// functions/index.js
const { onValueCreated } = require("firebase-functions/database");
const logger = require("firebase-functions/logger");
const notifyUsers = require("./notify-users");

exports.newPost = onValueCreated({ ref: "/posts/{postId}" }, (event) => {
  logger.info("Received new post with ID:", event.params.postId);
  return notifyUsers(event.data.val());
});

To run the integration tests, use the ./run_tests.sh script.

WARNING: Running these tests will wipe the contents of the Firebase project(s) provided. Always use disposable Firebase projects for testing.

The test suite executes multiple cycles: one for Node.js 14 and another for Node.js 16. It relies on a locally installed firebase CLI to deploy functions and requires the gcloud CLI to be installed and authenticated.

./run_tests.sh <project_id> [<project_id2>]

Before running the integration tests, ensure the following environment requirements are met:

1. Firebase CLI: Must be installed locally to allow the script to invoke deployment commands.
2. gcloud CLI: Must be installed and authenticated via gcloud auth login.
3. Disposable Projects: Since the test wipes project contents, ensure you are targeting non-production Firebase projects.

To decode application/protobuf events, you must generate statically-compiled protobufs. This is done by running the provided update script, which clones necessary Google repositories and uses protobufjs-cli to create the compiled .js and .ts files.

Prerequisites:

• The script requires access to the following repositories:
  • https://github.com/googleapis/google-cloudevents
  • https://github.com/googleapis/googleapis
  • https://github.com/google/protobuf
• The protobufjs-cli package must be available to create the TypeScript/JavaScript files.

./update.sh

When FUNCTIONS_MANIFEST_OUTPUT_PATH is not set, the CLI starts a local Express server to emulate the Firebase Functions environment.

Server Configuration

• Port: The server listens on the port specified by the PORT environment variable. If PORT is not set, it defaults to 8080.

Control API

If you set FUNCTIONS_CONTROL_API=true, the server exposes a special endpoint to retrieve the function manifest in YAML-like JSON format:

• GET /__/functions.yaml: Returns the function stack converted to wire format.

Lifecycle Management

The server provides a special endpoint to gracefully shut down the local emulator:

• GET /__/quitquitquit or POST /__/quitquitquit: Responds with ok and closes the server.

Example Setup:

PORT=3000 FUNCTIONS_CONTROL_API=true firebase-functions ./src

Callable functions (especially in v2) provide a structured way to access request data and security context.

CallableRequest<T>

This is the primary object passed to a v2 Callable handler. It contains:

• data: T: The parameters sent by the client.
• auth?: AuthData: Verified Firebase Auth information (UID and decoded token).
• app?: AppCheckData: Verified Firebase App Check information.
• instanceIdToken?: string: An unverified Instance ID token.
• rawRequest: Request: The underlying Express request object.
• acceptsStreaming: boolean: Indicates if the client is requesting a stream (SSE).

CallableContext

Used primarily in v1 handlers, it provides access to auth, app, instanceIdToken, and the rawRequest.

When writing a Task Queue function, the TaskContext object provides metadata about the specific task execution. This is useful for logging, debugging, or implementing custom retry logic based on previous failures.

Key properties:

• id: The unique task ID (the short name).
• queueName: The name of the queue that triggered the task.
• retryCount: How many times this task has been retried (starts at 0).
• executionCount: Total number of times the handler has received a response.
• scheduledTime: The RFC 3339 string representing when the task was scheduled.
• previousResponse?: The HTTP response code from the previous retry attempt.
• retryReason?: The reason provided for the retry.
• headers?: A record of the raw request headers.
• auth?: Metadata about the authorization used to invoke the function (contains uid, token, and rawToken).

AI blocking functions receive an AIBlockingEvent<T>, which extends CloudEvent<T>. This event contains metadata about the caller and the AI context:

Common Metadata Fields:

• authType: The type of authentication ('app_user', 'unauthenticated', or 'unknown').
• authId: The unique identifier for the authenticated user.
• authClaims: Claims associated with the user's authentication.
• resourceName: The name of the resource being accessed.
• appId: The Firebase App ID.
• androidPackageName / iosBundleId: Client identifiers for mobile apps.

Data Payload (event.data):

• For beforeGenerateContent: Contains model, template (optional), api (the provider used), and the original request.
• For afterGenerateContent: Contains all fields from beforeGenerateContent plus the generated response.

The authType field in a DataConnectEvent identifies the type of principal that triggered the mutation. This is useful for implementing permission-based logic within your functions.

Possible values for AuthType:

• app_user: An end user of an application.
• admin: An admin user of an application (e.g., an impersonator using the Admin SDK).
• unknown: A general type for principals that do not fall into the other categories.