From 929b4212ea3a334aa36d782d3200ee27c13f762b Mon Sep 17 00:00:00 2001 From: Thomas Bouldin Date: Fri, 6 May 2022 16:26:55 -0700 Subject: [PATCH 1/5] Attempted fix; not sure why some things aren't showing up --- src/v2/core.ts | 20 +++++++++++++++++++- src/v2/index.ts | 14 +++++++++++++- src/v2/options.ts | 6 ++++++ 3 files changed, 38 insertions(+), 2 deletions(-) diff --git a/src/v2/core.ts b/src/v2/core.ts index 54d61ff1c..949bfe778 100644 --- a/src/v2/core.ts +++ b/src/v2/core.ts @@ -56,6 +56,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 + * @typeParam T - The tye of the event data. + * @beta */ export interface CloudEvent { /** Version of the CloudEvents spec for this event. */ @@ -80,12 +82,28 @@ export interface CloudEvent { data: T; } -/** A handler for CloudEvents. */ +/** + * A handler for CloudEvents. + * @typeParam EventType - The kind of event this function handles. + * Always a subclass of CloudEvent<> + * @beta + */ export interface CloudFunction> { (raw: CloudEvent): any | Promise; + /** @alpha */ __trigger?: unknown; + /** @alpha */ __endpoint: ManifestEndpoint; + /** + * The callback passed to the CloudFunction constructor. + * Use run to test a CloudFunction + * @param event - The parsed event to handle. + * @returns Any return value. Google Cloud Functions will await any promise + * before shutting down your Cloud Function. Resolved return values + * are only used for unit testing purposes. + * @beta + */ run(event: EventType): any | Promise; } diff --git a/src/v2/index.ts b/src/v2/index.ts index 31070b4dc..d9a6e42dc 100644 --- a/src/v2/index.ts +++ b/src/v2/index.ts @@ -42,6 +42,18 @@ export { eventarc, }; -export { setGlobalOptions, GlobalOptions } from './options'; +export { + setGlobalOptions, + GlobalOptions, + SupportedRegion, + MIN_TIMEOUT_SECONDS, + MAX_EVENT_TIMEOUT_SECONDS, + MAX_HTTPS_TIMEOUT_SECONDS, + MAX_CONCURRENCY, + MemoryOption, + VpcEgressSetting, + IngressSetting, + EventHandlerOptions, +} from './options'; export { CloudFunction, CloudEvent } from './core'; diff --git a/src/v2/options.ts b/src/v2/options.ts index c4e3cd7de..f46a530ef 100644 --- a/src/v2/options.ts +++ b/src/v2/options.ts @@ -73,6 +73,7 @@ export const MAX_CONCURRENCY = 1_000; /** * List of available memory options supported by Cloud Functions. + * @beta */ export const SUPPORTED_MEMORY_OPTIONS = [ '128MiB', @@ -100,6 +101,7 @@ const MemoryOptionToMB: Record = { /** * A supported memory option. + * @beta */ export type MemoryOption = typeof SUPPORTED_MEMORY_OPTIONS[number]; @@ -130,6 +132,7 @@ export type IngressSetting = typeof SUPPORTED_INGRESS_SETTINGS[number]; /** * GlobalOptions are options that can be set across an entire project. * These options are common to HTTPS and Event handling functions. + * @beta */ export interface GlobalOptions { /** @@ -180,6 +183,7 @@ export interface GlobalOptions { * 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 * to the value "gcf_gen1" + * @beta */ cpu?: number | 'gcf_gen1'; @@ -247,6 +251,7 @@ export function getGlobalOptions(): GlobalOptions { /** * Options that can be set on an individual event-handling Cloud Function. + * @{inheritDoc GlobalOptions} */ export interface EventHandlerOptions extends GlobalOptions { retry?: boolean; @@ -361,6 +366,7 @@ export function optionsToEndpoint( /** * @hidden + * @alpha */ export function __getSpec(): { globalOptions: GlobalOptions; From 9835dc24fbcc361e237e92b08329acad15c8c730 Mon Sep 17 00:00:00 2001 From: Thomas Bouldin Date: Mon, 9 May 2022 10:48:30 -0700 Subject: [PATCH 2/5] Update docs; pull params namespace --- src/v2/index.ts | 6 --- src/v2/options.ts | 106 +++++++++++++++++----------------------------- 2 files changed, 38 insertions(+), 74 deletions(-) diff --git a/src/v2/index.ts b/src/v2/index.ts index d9a6e42dc..593967114 100644 --- a/src/v2/index.ts +++ b/src/v2/index.ts @@ -21,7 +21,6 @@ // SOFTWARE. import * as logger from '../logger'; -import * as params from './params'; import * as alerts from './providers/alerts'; import * as eventarc from './providers/eventarc'; import * as https from './providers/https'; @@ -37,7 +36,6 @@ export { pubsub, storage, logger, - params, tasks, eventarc, }; @@ -46,10 +44,6 @@ export { setGlobalOptions, GlobalOptions, SupportedRegion, - MIN_TIMEOUT_SECONDS, - MAX_EVENT_TIMEOUT_SECONDS, - MAX_HTTPS_TIMEOUT_SECONDS, - MAX_CONCURRENCY, MemoryOption, VpcEgressSetting, IngressSetting, diff --git a/src/v2/options.ts b/src/v2/options.ts index f46a530ef..0fdd02b83 100644 --- a/src/v2/options.ts +++ b/src/v2/options.ts @@ -35,57 +35,31 @@ import { HttpsOptions } from './providers/https'; /** * List of all regions supported by Cloud Functions v2 + * @beta */ -export const SUPPORTED_REGIONS = [ - 'asia-northeast1', - 'europe-north1', - 'europe-west1', - 'europe-west4', - 'us-central1', - 'us-east1', - 'us-west1', -] as const; - -/** - * A region known to be supported by CloudFunctions v2 - */ -export type SupportedRegion = typeof SUPPORTED_REGIONS[number]; - -/** - * Cloud Functions v2 min timeout value. - */ -export const MIN_TIMEOUT_SECONDS = 1; - -/** - * Cloud Functions v2 max timeout value for event handlers. - */ -export const MAX_EVENT_TIMEOUT_SECONDS = 540; - -/** - * Cloud Functions v2 max timeout for HTTPS functions. - */ -export const MAX_HTTPS_TIMEOUT_SECONDS = 36_000; - -/** - * Maximum number of requests to serve on a single instance. - */ -export const MAX_CONCURRENCY = 1_000; +export type SupportedRegion = + | 'asia-northeast1' + | 'europe-north1' + | 'europe-west1' + | 'europe-west4' + | 'us-central1' + | 'us-east1' + | 'us-west1'; /** * List of available memory options supported by Cloud Functions. * @beta */ -export const SUPPORTED_MEMORY_OPTIONS = [ - '128MiB', - '256MiB', - '512MiB', - '1GiB', - '2GiB', - '4GiB', - '8GiB', - '16GiB', - '32GiB', -] as const; +export type MemoryOption = + | '128MiB' + | '256MiB' + | '512MiB' + | '1GiB' + | '2GiB' + | '4GiB' + | '8GiB' + | '16GiB' + | '32GiB'; const MemoryOptionToMB: Record = { '128MiB': 128, @@ -99,35 +73,23 @@ const MemoryOptionToMB: Record = { '32GiB': 32768, }; -/** - * A supported memory option. - * @beta - */ -export type MemoryOption = typeof SUPPORTED_MEMORY_OPTIONS[number]; /** * List of available options for VpcConnectorEgressSettings. + * @beta */ -export const SUPPORTED_VPC_EGRESS_SETTINGS = [ - 'PRIVATE_RANGES_ONLY', - 'ALL_TRAFFIC', -] as const; - -/** - * A valid VPC Egress setting. - */ -export type VpcEgressSetting = typeof SUPPORTED_VPC_EGRESS_SETTINGS[number]; +export type VpcEgressSetting = + | 'PRIVATE_RANGES_ONLY' + | 'ALL_TRAFFIC'; /** * List of available options for IngressSettings. + * @beta */ -export const SUPPORTED_INGRESS_SETTINGS = [ - 'ALLOW_ALL', - 'ALLOW_INTERNAL_ONLY', - 'ALLOW_INTERNAL_AND_GCLB', -] as const; - -export type IngressSetting = typeof SUPPORTED_INGRESS_SETTINGS[number]; +export type IngressSetting = + | 'ALLOW_ALL' + | 'ALLOW_INTERNAL_ONLY' + | 'ALLOW_INTERNAL_AND_GCLB'; /** * GlobalOptions are options that can be set across an entire project. @@ -151,6 +113,12 @@ export interface GlobalOptions { * Timeout for the function in sections, possible values are 0 to 540. * HTTPS functions can specify a higher timeout. * A value of null restores the default of 60s + * The minimum timeout for a gen 2 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) + * * TaskQueue functions have a maximum timeout of 1,800s (30 minutes) */ timeoutSeconds?: number | null; @@ -173,6 +141,7 @@ export interface GlobalOptions { * Can only be applied to functions running on Cloud Functions v2. * 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. */ concurrency?: number | null; @@ -232,6 +201,7 @@ let globalOptions: GlobalOptions | undefined; /** * Sets default options for all functions written using the v2 SDK. * @param options Options to set as default + * @beta */ export function setGlobalOptions(options: GlobalOptions) { if (globalOptions) { @@ -250,8 +220,8 @@ export function getGlobalOptions(): GlobalOptions { } /** - * Options that can be set on an individual event-handling Cloud Function. - * @{inheritDoc GlobalOptions} + * Additional fields that can be set on any event-handling Cloud Function. + * @beta */ export interface EventHandlerOptions extends GlobalOptions { retry?: boolean; From 9f840c444115698d8fc8b13116ef3228ceb92139 Mon Sep 17 00:00:00 2001 From: Thomas Bouldin Date: Mon, 9 May 2022 10:54:55 -0700 Subject: [PATCH 3/5] Don't try to use bulleted list in field comments; they don't render --- src/v2/options.ts | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/v2/options.ts b/src/v2/options.ts index 0fdd02b83..f30a9ad8e 100644 --- a/src/v2/options.ts +++ b/src/v2/options.ts @@ -114,11 +114,10 @@ export interface GlobalOptions { * HTTPS functions can specify a higher timeout. * A value of null restores the default of 60s * The minimum timeout for a gen 2 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) - * * TaskQueue functions have a maximum timeout of 1,800s (30 minutes) + * 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). TaskQueue functions have a maximum + * timeout of 1,800s (30 minutes) */ timeoutSeconds?: number | null; From 9eb971e6fb6ed9a8f21bc92cd076a21d55984b18 Mon Sep 17 00:00:00 2001 From: Thomas Bouldin Date: Mon, 9 May 2022 11:01:20 -0700 Subject: [PATCH 4/5] Yank @beta tags; run formatter --- src/v2/index.ts | 11 +---------- src/v2/options.ts | 15 ++------------- 2 files changed, 3 insertions(+), 23 deletions(-) diff --git a/src/v2/index.ts b/src/v2/index.ts index 593967114..fd89e52fa 100644 --- a/src/v2/index.ts +++ b/src/v2/index.ts @@ -29,16 +29,7 @@ import * as pubsub from './providers/pubsub'; import * as storage from './providers/storage'; import * as tasks from './providers/tasks'; -export { - alerts, - https, - identity, - pubsub, - storage, - logger, - tasks, - eventarc, -}; +export { alerts, https, identity, pubsub, storage, logger, tasks, eventarc }; export { setGlobalOptions, diff --git a/src/v2/options.ts b/src/v2/options.ts index f30a9ad8e..a970d7384 100644 --- a/src/v2/options.ts +++ b/src/v2/options.ts @@ -35,9 +35,8 @@ import { HttpsOptions } from './providers/https'; /** * List of all regions supported by Cloud Functions v2 - * @beta */ -export type SupportedRegion = +export type SupportedRegion = | 'asia-northeast1' | 'europe-north1' | 'europe-west1' @@ -48,7 +47,6 @@ export type SupportedRegion = /** * List of available memory options supported by Cloud Functions. - * @beta */ export type MemoryOption = | '128MiB' @@ -73,18 +71,13 @@ const MemoryOptionToMB: Record = { '32GiB': 32768, }; - /** * List of available options for VpcConnectorEgressSettings. - * @beta */ -export type VpcEgressSetting = - | 'PRIVATE_RANGES_ONLY' - | 'ALL_TRAFFIC'; +export type VpcEgressSetting = 'PRIVATE_RANGES_ONLY' | 'ALL_TRAFFIC'; /** * List of available options for IngressSettings. - * @beta */ export type IngressSetting = | 'ALLOW_ALL' @@ -94,7 +87,6 @@ export type IngressSetting = /** * GlobalOptions are options that can be set across an entire project. * These options are common to HTTPS and Event handling functions. - * @beta */ export interface GlobalOptions { /** @@ -151,7 +143,6 @@ export interface GlobalOptions { * 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 * to the value "gcf_gen1" - * @beta */ cpu?: number | 'gcf_gen1'; @@ -200,7 +191,6 @@ let globalOptions: GlobalOptions | undefined; /** * Sets default options for all functions written using the v2 SDK. * @param options Options to set as default - * @beta */ export function setGlobalOptions(options: GlobalOptions) { if (globalOptions) { @@ -220,7 +210,6 @@ export function getGlobalOptions(): GlobalOptions { /** * Additional fields that can be set on any event-handling Cloud Function. - * @beta */ export interface EventHandlerOptions extends GlobalOptions { retry?: boolean; From 7c622ee3399e7807f91a63e64e47a211a82c10ea Mon Sep 17 00:00:00 2001 From: Thomas Bouldin Date: Tue, 10 May 2022 08:28:01 -0700 Subject: [PATCH 5/5] PR feedback --- src/v2/core.ts | 6 +++--- src/v2/options.ts | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/v2/core.ts b/src/v2/core.ts index 949bfe778..533349b55 100644 --- a/src/v2/core.ts +++ b/src/v2/core.ts @@ -56,7 +56,7 @@ 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 - * @typeParam T - The tye of the event data. + * @typeParam T - The type of the event data. * @beta */ export interface CloudEvent { @@ -100,8 +100,8 @@ export interface CloudFunction> { * The callback passed to the CloudFunction constructor. * Use run to test a CloudFunction * @param event - The parsed event to handle. - * @returns Any return value. Google Cloud Functions will await any promise - * before shutting down your Cloud Function. Resolved return values + * @returns Any return value. Google 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/options.ts b/src/v2/options.ts index a970d7384..d3155f3c3 100644 --- a/src/v2/options.ts +++ b/src/v2/options.ts @@ -107,8 +107,8 @@ export interface GlobalOptions { * A value of null restores the default of 60s * The minimum timeout for a gen 2 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). TaskQueue functions have a maximum + * 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) */ timeoutSeconds?: number | null;