From ed30ecdc8f9f2dae741ffb4db407364bb06db1d5 Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Thu, 11 Jul 2019 16:44:49 -0700 Subject: [PATCH 1/5] Adding comments for EventContext and main CloudFunctions methods. --- src/cloud-functions.ts | 104 +++++++++++++++++++++++++++++++++-------- 1 file changed, 85 insertions(+), 19 deletions(-) diff --git a/src/cloud-functions.ts b/src/cloud-functions.ts index 686e9e31e..6a1ab7605 100644 --- a/src/cloud-functions.ts +++ b/src/cloud-functions.ts @@ -25,11 +25,13 @@ import * as _ from 'lodash'; import { DeploymentOptions, Schedule } from './function-configuration'; export { Request, Response }; +/** @hidden */ const WILDCARD_REGEX = new RegExp('{[^/{}]*}', 'g'); /** - * Wire format for an event. * @hidden + * + * Wire format for an event. */ export interface Event { context: { @@ -53,38 +55,92 @@ export interface Event { */ export interface EventContext { /** - * Firebase auth variable for the user whose action triggered the function. - * Field will be null for unauthenticated users, and will not exist for admin - * users. Only available for database functions. + * Authentication information for the user that triggered the function. + * This object contains `uid` and `token` properties for authenticated users. + * For more detail including token keys, see the + * [security rules reference](/docs/firestore/reference/security/#properties). + * + * This field is only populated for Realtime Database triggers and Callable + * functions. For an unauthenticated user, this field is null. For Firebase + * admin users and event types that do not provide user information, this field + * does not exist. */ auth?: { token: object; uid: string; }; + /** - * Type of authentication for the triggering action. Only available for - * database functions. + * The level of permissions for a user. Valid values are: + * + * * `ADMIN` Developer user or user authenticated via a service account. + * * `USER` Known user. + * * `UNAUTHENTICATED` Unauthenticated action + * * `null` For event types that do not provide user information (all except + * Realtime Database). + * */ authType?: 'ADMIN' | 'USER' | 'UNAUTHENTICATED'; + /** - * ID of the event + * The event’s unique identifier. */ eventId: string; + /** - * Type of event + * Type of event. Valid values are: + * + * * `providers/google.firebase.analytics/eventTypes/event.log` + * * `providers/firebase.auth/eventTypes/user.create` + * * `providers/firebase.auth/eventTypes/user.delete` + * * `providers/firebase.crashlytics/eventTypes/issue.new` + * * `providers/firebase.crashlytics/eventTypes/issue.regressed` + * * `providers/firebase.crashlytics/eventTypes/issue.velocityAlert` + * * `providers/google.firebase.database/eventTypes/ref.write` + * * `providers/google.firebase.database/eventTypes/ref.create` + * * `providers/google.firebase.database/eventTypes/ref.update` + * * `providers/google.firebase.database/eventTypes/ref.delete` + * * `providers/cloud.firestore/eventTypes/document.write` + * * `providers/cloud.firestore/eventTypes/document.create` + * * `providers/cloud.firestore/eventTypes/document.update` + * * `providers/cloud.firestore/eventTypes/document.delete` + * * `google.pubsub.topic.publish` + * * `google.storage.object.finalize` + * * `google.storage.object.archive` + * * `google.storage.object.delete` + * * `google.storage.object.metadataUpdate` + * * `google.firebase.remoteconfig.update` */ eventType: string; + /** - * Key-value pairs that represent the values of wildcards in a database - * reference. Cannot be accessed while inside the handler namespace. + * An object containing the values of the wildcards in the `path` parameter + * provided to the [`ref()`](functions.database#.ref) method for a Realtime + * Database trigger. Cannot be accessed while inside the handler namespace. */ params: { [option: string]: any }; + /** - * Resource that triggered the event + * The resource that emitted the event. Valid values are: + * + * * Analytics — `projects//events/` + * * Realtime Database — + `projects/_/instances//refs/` + * * Storage — + `projects/_/buckets//objects/#` + * * Authentication — `projects/` + * * Pub/Sub — `projects//topics/` + * + * Because Realtime Database instances and Cloud Storage buckets are globally + * unique and not tied to the project, their resources start with `projects/_`. + * Underscore is not a valid project name. + * */ resource: Resource; /** - * Timestamp for when the event ocurred (ISO 8601 string) + * Timestamp for the event as an + * [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) string. + * */ timestamp: string; } @@ -179,7 +235,7 @@ export interface Resource { labels?: { [tag: string]: string }; } -/** +/** @hidden * TriggerAnnotated is used internally by the firebase CLI to understand what * type of Cloud Function to deploy. */ @@ -208,17 +264,23 @@ export interface Runnable { } /** - * An HttpsFunction is both an object that exports its trigger definitions at - * __trigger and can be called as a function that takes an express.js Request - * and Response object. + * The Cloud Function type for HTTPS triggers. This should be exported from your + * JavaScript file to define a Cloud Function. + * + * This type is a special JavaScript function which takes Express + * [`Request`](https://expressjs.com/en/api.html#req) and + * [`Response`](https://expressjs.com/en/api.html#res) objects as its only + * arguments. */ export type HttpsFunction = TriggerAnnotated & ((req: Request, resp: Response) => void); /** - * A CloudFunction is both an object that exports its trigger definitions at - * __trigger and can be called as a function using the raw JS API for Google - * Cloud Functions. + * The Cloud Function type for all non-HTTPS triggers. This should be exported + * from your JavaScript file to define a Cloud Function. + * + * This type is a special JavaScript function which takes a templated + * [`Event`](functions.Event) object as its only argument. */ export type CloudFunction = Runnable & TriggerAnnotated & @@ -346,6 +408,7 @@ export function makeCloudFunction({ return cloudFunction; } +/** @hidden */ function _makeParams( context: EventContext, triggerResourceGetter: () => string @@ -373,6 +436,7 @@ function _makeParams( return params; } +/** @hidden */ function _makeAuth(event: Event, authType: string) { if (authType === 'UNAUTHENTICATED') { return null; @@ -383,6 +447,7 @@ function _makeAuth(event: Event, authType: string) { }; } +/** @hidden */ function _detectAuthType(event: Event) { if (_.get(event, 'context.auth.admin')) { return 'ADMIN'; @@ -393,6 +458,7 @@ function _detectAuthType(event: Event) { return 'UNAUTHENTICATED'; } +/** @hidden */ export function optionsToTrigger(options: DeploymentOptions) { const trigger: any = {}; if (options.regions) { From ca192548079c5a84510102b223c265bd0d81ab3e Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Fri, 12 Jul 2019 09:09:12 -0700 Subject: [PATCH 2/5] Fixing spacing and alignment issues found by thechenky. --- src/cloud-functions.ts | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/src/cloud-functions.ts b/src/cloud-functions.ts index 6a1ab7605..dd41cb510 100644 --- a/src/cloud-functions.ts +++ b/src/cloud-functions.ts @@ -30,7 +30,7 @@ const WILDCARD_REGEX = new RegExp('{[^/{}]*}', 'g'); /** * @hidden - * + * * Wire format for an event. */ export interface Event { @@ -54,6 +54,7 @@ export interface Event { * available. */ export interface EventContext { + /** * Authentication information for the user that triggered the function. * This object contains `uid` and `token` properties for authenticated users. @@ -78,7 +79,6 @@ export interface EventContext { * * `UNAUTHENTICATED` Unauthenticated action * * `null` For event types that do not provide user information (all except * Realtime Database). - * */ authType?: 'ADMIN' | 'USER' | 'UNAUTHENTICATED'; @@ -89,7 +89,7 @@ export interface EventContext { /** * Type of event. Valid values are: - * + * * * `providers/google.firebase.analytics/eventTypes/event.log` * * `providers/firebase.auth/eventTypes/user.create` * * `providers/firebase.auth/eventTypes/user.delete` @@ -119,28 +119,26 @@ export interface EventContext { * Database trigger. Cannot be accessed while inside the handler namespace. */ params: { [option: string]: any }; - + /** * The resource that emitted the event. Valid values are: * * * Analytics — `projects//events/` * * Realtime Database — `projects/_/instances//refs/` - * * Storage — + * * Storage — `projects/_/buckets//objects/#` - * * Authentication — `projects/` - * * Pub/Sub — `projects//topics/` - * - * Because Realtime Database instances and Cloud Storage buckets are globally - * unique and not tied to the project, their resources start with `projects/_`. - * Underscore is not a valid project name. - * + * * Authentication — `projects/` + * * Pub/Sub — `projects//topics/` + * + * Because Realtime Database instances and Cloud Storage buckets are globally + * unique and not tied to the project, their resources start with `projects/_`. + * Underscore is not a valid project name. */ resource: Resource; /** * Timestamp for the event as an * [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) string. - * */ timestamp: string; } @@ -235,7 +233,8 @@ export interface Resource { labels?: { [tag: string]: string }; } -/** @hidden +/** + * @hidden * TriggerAnnotated is used internally by the firebase CLI to understand what * type of Cloud Function to deploy. */ @@ -280,7 +279,7 @@ export type HttpsFunction = TriggerAnnotated & * from your JavaScript file to define a Cloud Function. * * This type is a special JavaScript function which takes a templated - * [`Event`](functions.Event) object as its only argument. + * `Event` object as its only argument. */ export type CloudFunction = Runnable & TriggerAnnotated & From 9e82955449698f37b4a9de667846866a5e57be86 Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Fri, 12 Jul 2019 10:04:46 -0700 Subject: [PATCH 3/5] Committing edits from npm run format:fix. --- src/cloud-functions.ts | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/cloud-functions.ts b/src/cloud-functions.ts index dd41cb510..b35ba6ee1 100644 --- a/src/cloud-functions.ts +++ b/src/cloud-functions.ts @@ -30,7 +30,7 @@ const WILDCARD_REGEX = new RegExp('{[^/{}]*}', 'g'); /** * @hidden - * + * * Wire format for an event. */ export interface Event { @@ -54,7 +54,6 @@ export interface Event { * available. */ export interface EventContext { - /** * Authentication information for the user that triggered the function. * This object contains `uid` and `token` properties for authenticated users. @@ -89,7 +88,7 @@ export interface EventContext { /** * Type of event. Valid values are: - * + * * * `providers/google.firebase.analytics/eventTypes/event.log` * * `providers/firebase.auth/eventTypes/user.create` * * `providers/firebase.auth/eventTypes/user.delete` @@ -119,7 +118,7 @@ export interface EventContext { * Database trigger. Cannot be accessed while inside the handler namespace. */ params: { [option: string]: any }; - + /** * The resource that emitted the event. Valid values are: * @@ -233,7 +232,7 @@ export interface Resource { labels?: { [tag: string]: string }; } -/** +/** * @hidden * TriggerAnnotated is used internally by the firebase CLI to understand what * type of Cloud Function to deploy. From ca65e9f04c991765a340c407ec54655c8a04d91d Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Mon, 15 Jul 2019 13:40:58 -0700 Subject: [PATCH 4/5] Adding comments to try and populate information for Change and ChangeJson. --- docgen/content-sources/toc.yaml | 2 ++ src/cloud-functions.ts | 16 ++++++++++++---- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/docgen/content-sources/toc.yaml b/docgen/content-sources/toc.yaml index c2766e430..9ba761c15 100644 --- a/docgen/content-sources/toc.yaml +++ b/docgen/content-sources/toc.yaml @@ -12,6 +12,8 @@ toc: path: /docs/reference/functions/function_builder_.functionbuilder.html - title: 'Change' path: /docs/reference/functions/cloud_functions_.change.html + - title: 'ChangeJson' + path: /docs/reference/functions/cloud_functions_.changejson.html - title: 'functions.config' path: /docs/reference/functions/config_.html diff --git a/src/cloud-functions.ts b/src/cloud-functions.ts index b35ba6ee1..4509706b3 100644 --- a/src/cloud-functions.ts +++ b/src/cloud-functions.ts @@ -143,15 +143,19 @@ export interface EventContext { } /** - * Change describes a change of state - "before" represents the state prior to - * the event, "after" represents the state after the event. + * The Functions interface for events that change state, such as + * Realtime Database or Cloud Firestore `onWrite` and `onUpdate`. + * + * For more information about the format used to construct `Change` objects, see + * [`cloud-functions.ChangeJson`](/docs/reference/functions/cloud_functions_.changejson). + * */ export class Change { constructor(public before: T, public after: T) {} } /** - * 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 { /** @@ -164,17 +168,20 @@ export interface ChangeJson { */ before?: any; /** - * Comma-separated string that represents names of field that changed. + * @hidden + * Comma-separated string that represents names of fields that changed. */ fieldMask?: string; } export namespace Change { + /** @hidden */ function reinterpretCast(x: any) { return x as T; } /** + * @hidden * Factory method for creating a Change from a `before` object and an `after` * object. */ @@ -183,6 +190,7 @@ export namespace Change { } /** + * @hidden * Factory method for creating a Change from a JSON and an optional customizer * function to be applied to both the `before` and the `after` fields. */ From 1146c2edd1223af36139991b1b55bd9e0c1876a8 Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Mon, 15 Jul 2019 15:57:06 -0700 Subject: [PATCH 5/5] Remembered to run npm run format:fix! --- src/cloud-functions.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/cloud-functions.ts b/src/cloud-functions.ts index 4509706b3..e8d099dca 100644 --- a/src/cloud-functions.ts +++ b/src/cloud-functions.ts @@ -145,10 +145,10 @@ export interface EventContext { /** * The Functions interface for events that change state, such as * Realtime Database or Cloud Firestore `onWrite` and `onUpdate`. - * + * * For more information about the format used to construct `Change` objects, see * [`cloud-functions.ChangeJson`](/docs/reference/functions/cloud_functions_.changejson). - * + * */ export class Change { constructor(public before: T, public after: T) {}