From ba368e88c1cbcf6cf9475f72afc5ba4bf4d32207 Mon Sep 17 00:00:00 2001 From: egilmorez Date: Mon, 10 Jul 2023 08:13:55 -0700 Subject: [PATCH 1/2] Adding some format and style edits for common or top-level reference pages. (#1438) --- src/common/change.ts | 10 +++++----- src/v2/core.ts | 16 +++++++-------- src/v2/index.ts | 8 ++++---- src/v2/options.ts | 46 ++++++++++++++++++++++++-------------------- 4 files changed, 42 insertions(+), 38 deletions(-) diff --git a/src/common/change.ts b/src/common/change.ts index 95afdb4eb..d81b7c1fb 100644 --- a/src/common/change.ts +++ b/src/common/change.ts @@ -21,7 +21,7 @@ // SOFTWARE. /** - * `ChangeJson` is the JSON format used to construct a Change object. + * `ChangeJson` is the JSON format used to construct a `Change` object. */ export interface ChangeJson { /** @@ -64,8 +64,8 @@ export function applyFieldMask(sparseBefore: any, after: any, fieldMask: string) } /** - * The Functions interface for events that change state, such as - * Realtime Database or Cloud Firestore `onWrite` and `onUpdate`. + * The Cloud Functions interface for events that change state, such as + * Realtime Database or Cloud Firestore `onWrite` and `onUpdate` events. * * For more information about the format used to construct `Change` objects, see * {@link ChangeJson} below. @@ -73,7 +73,7 @@ export function applyFieldMask(sparseBefore: any, after: any, fieldMask: string) */ export class Change { /** - * Factory method for creating a Change from a `before` object and an `after` + * Factory method for creating a `Change` from a `before` object and an `after` * object. */ static fromObjects(before: T, after: T) { @@ -81,7 +81,7 @@ export class Change { } /** - * Factory method for creating a Change from a JSON and an optional customizer + * Factory method for creating a `Change` from JSON and an optional customizer * function to be applied to both the `before` and the `after` fields. */ static fromJSON(json: ChangeJson, customizer: (x: any) => T = (x) => x as T): Change { diff --git a/src/v2/core.ts b/src/v2/core.ts index 72c7e8e7d..fb7fc1e32 100644 --- a/src/v2/core.ts +++ b/src/v2/core.ts @@ -21,7 +21,7 @@ // SOFTWARE. /** - * Core functionality of the Firebase Functions v2 SDK. + * Core functionality of the Cloud Functions for Firebase 2nd gen SDK. * @packageDocumentation */ @@ -64,8 +64,8 @@ export interface TriggerAnnotation { } /** - * A CloudEventBase is the base of a cross-platform format for encoding a serverless event. - * More information can be found in https://github.com/cloudevents/spec + * A `CloudEventBase` is the base of a cross-platform format for encoding a serverless event. + * For more information, see https://github.com/cloudevents/spec. * @typeParam T - The type of the event data. * @beta */ @@ -76,10 +76,10 @@ export interface CloudEvent { /** A globally unique ID for this event. */ id: string; - /** The resource which published this event. */ + /** The resource that published this event. */ source: string; - /** The resource, provided by source, that this event relates to */ + /** The resource, provided by source, that this event relates to. */ subject?: string; /** The type of event that this represents. */ @@ -107,10 +107,10 @@ export interface CloudFunction> { __endpoint: ManifestEndpoint; /** - * The callback passed to the CloudFunction constructor. - * Use run to test a CloudFunction + * The callback passed to the `CloudFunction` constructor. + * Use `run` to test a function. * @param event - The parsed event to handle. - * @returns Any return value. Google Cloud Functions awaits any promise + * @returns Any return value. Cloud Functions awaits any promise * before shutting down your function. Resolved return values * are only used for unit testing purposes. * @beta diff --git a/src/v2/index.ts b/src/v2/index.ts index 4bcedb3ad..7a1d89ef6 100644 --- a/src/v2/index.ts +++ b/src/v2/index.ts @@ -21,10 +21,10 @@ // SOFTWARE. /** - * The V2 API for Cloud Functions for Firebase. - * This SDK also supports deep imports. For example, the namespace - * 'pubsub' is available at 'firebase-functions/v2' or is directly importable - * from 'firebase-functions/v2/pubsub'. + * The 2nd gen API for Cloud Functions for Firebase. + * This SDK supports deep imports. For example, the namespace + * `pubsub` is available at `firebase-functions/v2` or is directly importable + * from `firebase-functions/v2/pubsub`. * @packageDocumentation */ diff --git a/src/v2/options.ts b/src/v2/options.ts index 5726fdd1b..6b0480510 100644 --- a/src/v2/options.ts +++ b/src/v2/options.ts @@ -42,7 +42,7 @@ import * as logger from "../logger"; export { RESET_VALUE } from "../common/options"; /** - * List of all regions supported by Cloud Functions v2 + * List of all regions supported by Cloud Functions (2nd gen). */ export type SupportedRegion = | "asia-east1" @@ -98,18 +98,18 @@ const MemoryOptionToMB: Record = { }; /** - * List of available options for VpcConnectorEgressSettings. + * List of available options for `VpcConnectorEgressSettings`. */ export type VpcEgressSetting = "PRIVATE_RANGES_ONLY" | "ALL_TRAFFIC"; /** - * List of available options for IngressSettings. + * List of available options for `IngressSettings`. */ export type IngressSetting = "ALLOW_ALL" | "ALLOW_INTERNAL_ONLY" | "ALLOW_INTERNAL_AND_GCLB"; /** - * GlobalOptions are options that can be set across an entire project. - * These options are common to HTTPS and Event handling functions. + * `GlobalOptions` are options that can be set across an entire project. + * These options are common to HTTPS and event handling functions. */ export interface GlobalOptions { /** @@ -132,25 +132,25 @@ export interface GlobalOptions { * HTTPS functions can specify a higher timeout. * * @remarks - * The minimum timeout for a gen 2 function is 1s. The maximum timeout for a + * The minimum timeout for a 2nd gen function is 1s. The maximum timeout for a * function depends on the type of function: Event handling functions have a * maximum timeout of 540s (9 minutes). HTTPS and callable functions have a * maximum timeout of 36,00s (1 hour). Task queue functions have a maximum - * timeout of 1,800s (30 minutes) + * timeout of 1,800s (30 minutes). */ timeoutSeconds?: number | Expression | ResetValue; /** - * Min number of actual instances to be running at a given time. + * Minimum number of actual instances to be running at a given time. * * @remarks - * Instances will be billed for memory allocation and 10% of CPU allocation + * Instances are billed for memory allocation and 10% of CPU allocation * while idle. */ minInstances?: number | Expression | ResetValue; /** - * Max number of instances to be running in parallel. + * Max number of instances that can be running in parallel. */ maxInstances?: number | Expression | ResetValue; @@ -158,7 +158,7 @@ export interface GlobalOptions { * Number of requests a function can serve at once. * * @remarks - * Can only be applied to functions running on Cloud Functions v2. + * Can be applied only to functions running on Cloud Functions (2nd gen)). * A value of null restores the default concurrency (80 when CPU >= 1, 1 otherwise). * Concurrency cannot be set to any value other than 1 if `cpu` is less than 1. * The maximum value for concurrency is 1,000. @@ -171,14 +171,14 @@ export interface GlobalOptions { * @remarks * Defaults to 1 for functions with <= 2GB RAM and increases for larger memory sizes. * This is different from the defaults when using the gcloud utility and is different from - * the fixed amount assigned in Google Cloud Functions generation 1. - * To revert to the CPU amounts used in gcloud or in Cloud Functions generation 1, set this + * the fixed amount assigned in Cloud Functions (1st gen). + * To revert to the CPU amounts used in gcloud or in Cloud Functions (1st gen), set this * to the value "gcf_gen1" */ cpu?: number | "gcf_gen1"; /** - * Connect cloud function to specified VPC connector. + * Connect a function to a specified VPC connector. */ vpcConnector?: string | Expression | ResetValue; @@ -198,7 +198,7 @@ export interface GlobalOptions { ingressSettings?: IngressSetting | ResetValue; /** - * Invoker to set access control on https functions. + * Invoker to set access control on HTTPS functions. */ invoker?: "public" | "private" | string | string[]; @@ -213,12 +213,12 @@ export interface GlobalOptions { secrets?: (string | SecretParam)[]; /** - * Determines whether Firebase AppCheck is enforced. Defaults to false. + * Determines whether Firebase App Check is enforced. Defaults to false. * * @remarks * When true, requests with invalid tokens autorespond with a 401 * (Unauthorized) error. - * When false, requests with invalid tokens set event.app to undefined. + * When false, requests with invalid tokens set `event.app` to `undefined`. */ enforceAppCheck?: boolean; @@ -226,8 +226,8 @@ export interface GlobalOptions { * Controls whether function configuration modified outside of function source is preserved. Defaults to false. * * @remarks - * When setting configuration available in the underlying platform that is not yet available in the Firebase Functions - * SDK, we highly recommend setting `preserveExternalChanges` to `true`. Otherwise, when the Firebase Functions SDK releases + * When setting configuration available in an underlying platform that is not yet available in the Firebase SDK + * for Cloud Functions, we recommend setting `preserveExternalChanges` to `true`. Otherwise, when Google releases * a new version of the SDK with support for the missing configuration, your function's manually configured setting * may inadvertently be wiped out. */ @@ -237,7 +237,7 @@ export interface GlobalOptions { let globalOptions: GlobalOptions | undefined; /** - * Sets default options for all functions written using the v2 SDK. + * Sets default options for all functions written using the 2nd gen SDK. * @param options Options to set as default */ export function setGlobalOptions(options: GlobalOptions) { @@ -257,12 +257,16 @@ export function getGlobalOptions(): GlobalOptions { } /** - * Additional fields that can be set on any event-handling Cloud Function. + * Additional fields that can be set on any event-handling function. */ export interface EventHandlerOptions extends Omit { + /** Type of the event. Valid values are TODO */ eventType?: string; + /** TODO */ eventFilters?: Record>; + + /** TODO */ eventFilterPathPatterns?: Record>; /** Whether failed executions should be delivered again. */ From 41d616fc9c4e81a8196ac56e1a02cecdc811d5a2 Mon Sep 17 00:00:00 2001 From: Milo Hill Date: Fri, 14 Jul 2023 00:01:40 +0100 Subject: [PATCH 2/2] Wrap v2 firestore functions with trace context (#1440) * Wrap v2 firestore functions with trace context * Add changelog --- CHANGELOG.md | 1 + src/v2/providers/firestore.ts | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 14d4358cc..f96d0b994 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1 +1,2 @@ - Add features to task queue functions. (#1423) +- Add traces to V2 Firestore trigger logs. (#1440) diff --git a/src/v2/providers/firestore.ts b/src/v2/providers/firestore.ts index 03a910d3d..619e089e3 100644 --- a/src/v2/providers/firestore.ts +++ b/src/v2/providers/firestore.ts @@ -34,6 +34,7 @@ import { createSnapshotFromJson, createSnapshotFromProtobuf, } from "../../common/providers/firestore"; +import { wrapTraceContext } from "../trace"; export { Change }; @@ -445,7 +446,7 @@ export function onOperation( const event = raw as RawFirestoreEvent; const params = makeParams(event.document, documentPattern) as unknown as ParamsOf; const firestoreEvent = makeFirestoreEvent(eventType, event, params); - return handler(firestoreEvent); + return wrapTraceContext(handler)(firestoreEvent); }; func.run = handler;