diff --git a/src/v2/core.ts b/src/v2/core.ts index 54d61ff1c..533349b55 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 type 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 awaits any promise + * before shutting down your 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..fd89e52fa 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'; @@ -30,18 +29,16 @@ 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, - params, - tasks, - eventarc, -}; +export { alerts, https, identity, pubsub, storage, logger, tasks, eventarc }; -export { setGlobalOptions, GlobalOptions } from './options'; +export { + setGlobalOptions, + GlobalOptions, + SupportedRegion, + 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..d3155f3c3 100644 --- a/src/v2/options.ts +++ b/src/v2/options.ts @@ -36,55 +36,28 @@ import { HttpsOptions } from './providers/https'; /** * List of all regions supported by Cloud Functions v2 */ -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. */ -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, @@ -98,34 +71,18 @@ const MemoryOptionToMB: Record = { '32GiB': 32768, }; -/** - * A supported memory option. - */ -export type MemoryOption = typeof SUPPORTED_MEMORY_OPTIONS[number]; - /** * List of available options for VpcConnectorEgressSettings. */ -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. */ -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. @@ -148,6 +105,11 @@ 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). Task queue functions have a maximum + * timeout of 1,800s (30 minutes) */ timeoutSeconds?: number | null; @@ -170,6 +132,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; @@ -246,7 +209,7 @@ export function getGlobalOptions(): GlobalOptions { } /** - * Options that can be set on an individual event-handling Cloud Function. + * Additional fields that can be set on any event-handling Cloud Function. */ export interface EventHandlerOptions extends GlobalOptions { retry?: boolean; @@ -361,6 +324,7 @@ export function optionsToEndpoint( /** * @hidden + * @alpha */ export function __getSpec(): { globalOptions: GlobalOptions;