@ashishpandeyone/cdk-lambda-web-function 0.1.1 → 0.1.3

package/lib/web-function-endpoint.d.ts

@@ -1,5 +1,23 @@
+import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';
+import * as iam from 'aws-cdk-lib/aws-iam';
 import { Construct } from 'constructs';
 import { WebFunctionAuthType, WebFunctionEndpointType } from './enums';
+import type { IWebFunction } from './web-function';
+import type { WebFunctionDeployment } from './web-function-deployment';
+import { WebFunctionGrants } from './web-function-grants';
+import type { IWebFunctionRevision } from './web-function-revision';
+/**
+ * A revision and the share of an endpoint's traffic it receives.
+ */
+export interface WebFunctionRevisionWeight {
+    /** The revision. */
+    readonly revision: IWebFunctionRevision;
+    /**
+     * The revision's share of the endpoint's traffic, as a fraction (like `lambda.Alias` `additionalVersions`).
+     * Must be a whole percentage from 0.01 to 0.99.
+     */
+    readonly weight: number;
+}
 /**
  * Options for a Web Function's endpoint.
  */
@@ -21,37 +39,95 @@ export interface WebFunctionEndpointOptions {
     readonly regions?: string[];
     /**
      * The endpoint's name, shown in logs (`endpointName`) and in the `lambda-web-endpoint-name` header.
+     * Names are unique per function.
      *
-     * When omitted, the name is `default-<hash>`, with the hash covering the endpoint type and regions,
-     * so changing either deploys a new endpoint cleanly. When set, changing the endpoint type or
-     * regions also requires a new name: two endpoints of one function can't share a name, and
-     * CloudFormation creates the replacement before deleting the old one.
+     * When omitted, the name ends in a hash of the endpoint type and regions, so changing either deploys
+     * a new endpoint cleanly. When set, changing the endpoint type or regions also requires a new name:
+     * two endpoints of one function can't share a name, and CloudFormation creates the replacement
+     * before deleting the old one.
      *
-     * @default - `default-<hash of type and regions>`
+     * @default - `default-<hash>` for the function's default endpoint, `<id>-<hash>` for endpoints added with `addEndpoint`
      */
     readonly endpointName?: string;
+    /**
+     * A description of the endpoint.
+     *
+     * @default - no description
+     */
+    readonly description?: string;
+    /**
+     * The most requests per second the endpoint accepts; excess requests get HTTP 429.
+     * Allowed: 0 (blocks all traffic), 100–1,000 in steps of 100, or 2,000–10,000 in steps of 1,000.
+     *
+     * Enforced separately in each region the endpoint serves from, so a multi-region endpoint
+     * can accept this many requests per second in every region.
+     *
+     * @default - no limit beyond the service quota of 10,000 requests per second per endpoint (per region)
+     */
+    readonly rateLimit?: number;
+    /**
+     * The most execution environments the endpoint may use (2–10,000). Each one uses 2 vCPUs of the account's quota.
+     *
+     * Enforced separately in each region the endpoint serves from.
+     *
+     * @default - scales within the account's vCPU quota
+     */
+    readonly maxEnvironments?: number;
+    /**
+     * How the endpoint moves its traffic to a new revision: all at once, or in steps
+     * (`WebFunctionDeployment.canary()` or `linear()`) that watch CloudWatch alarms and move
+     * the traffic back when one goes into ALARM.
+     *
+     * A deployment in steps can't be combined with `revision`, `additionalRevisions` or `routeTraffic()`.
+     *
+     * @default WebFunctionDeployment.allAtOnce()
+     */
+    readonly deployment?: WebFunctionDeployment;
 }
 /**
- * Internal: how `WebFunction` creates its endpoint. Not part of the public API.
+ * Options for `WebFunction.addEndpoint`.
  */
-interface WebFunctionEndpointProps extends WebFunctionEndpointOptions {
-    /** Literal name of the Web Function (the provider's IAM must not reference resource attributes). */
-    readonly functionName: string;
-    /** The Web Function's ARN. */
-    readonly functionArn: string;
-    /** ID of the revision the endpoint serves. */
-    readonly revisionId: string;
-    /** How callers are authenticated. */
+export interface AddWebFunctionEndpointOptions extends WebFunctionEndpointOptions {
+    /**
+     * How callers of this endpoint are authenticated.
+     */
     readonly authType: WebFunctionAuthType;
+    /**
+     * The revision the endpoint serves, e.g. an earlier one from `WebFunctionRevision.fromRevisionAttributes`
+     * to keep this endpoint on it while others move on. Same as calling `routeTraffic`.
+     *
+     * @default - the function's current revision (`currentRevision`)
+     */
+    readonly revision?: IWebFunctionRevision;
+    /**
+     * A second revision and its share of the endpoint's traffic; `revision` gets the rest.
+     * An endpoint routes to at most two revisions.
+     *
+     * @default - all traffic goes to `revision`
+     */
+    readonly additionalRevisions?: WebFunctionRevisionWeight[];
+}
+/**
+ * Internal: how `WebFunction` creates its endpoints. Not part of the public API.
+ */
+interface WebFunctionEndpointProps extends AddWebFunctionEndpointOptions {
+    /** The function that owns the endpoint. */
+    readonly webFunction: IWebFunction;
+    /** The function's current revision, served unless `revision` is given. */
+    readonly currentRevision: IWebFunctionRevision;
+    /** Prefix of the generated endpoint name. */
+    readonly namePrefix: string;
+    /** Extra input to the generated name's hash (the construct ID of an added endpoint). */
+    readonly nameSeed?: string;
 }
 /**
- * The HTTPS endpoint of a Web Function. Created by `WebFunction`; access it as `fn.endpoint`.
+ * An HTTPS endpoint of a Web Function: `fn.endpoint` (the default one) or the result of `fn.addEndpoint()`.
  *
- * Only `WebFunction` creates endpoints in this version (one per function), so the constructor is private.
+ * Endpoints are created only through `WebFunction`, which owns their log groups in every region, so the constructor is private.
  */
 export declare class WebFunctionEndpoint extends Construct {
     /**
-     * Creates the endpoint of a Web Function. Used by `WebFunction`.
+     * Creates an endpoint of a Web Function. Used by `WebFunction`.
      *
      * @internal
      */
@@ -62,6 +138,8 @@ export declare class WebFunctionEndpoint extends Construct {
     readonly endpointArn: string;
     /** Where the endpoint serves traffic from. */
     readonly endpointType: WebFunctionEndpointType;
+    /** How callers of the endpoint are authenticated. */
+    readonly authType: WebFunctionAuthType;
     /** Every region the endpoint serves from: the home region first, then the others in alphabetical order. */
     readonly regions: string[];
     /**
@@ -72,9 +150,19 @@ export declare class WebFunctionEndpoint extends Construct {
      * The endpoint's URL: the global URL for `MULTI_REGION`, otherwise the home region's.
      */
     readonly url: string;
+    /** Grants on this endpoint (e.g. `grants.invoke(principal)`). */
+    readonly grants: WebFunctionGrants;
+    /**
+     * The alarms this endpoint created for its deployment's `rollbackOn`, one per threshold in every region it serves from
+     * (the home region's first). Empty without `rollbackOn`.
+     */
+    readonly rollbackAlarms: cloudwatch.IAlarm[];
     private readonly homeRegion;
-    private readonly functionName;
-    private readonly functionArn;
+    private readonly webFunction;
+    private readonly resource;
+    private weights;
+    private routed;
+    private readonly gradual;
     private lookup?;
     private constructor();
     /**
@@ -83,5 +171,66 @@ export declare class WebFunctionEndpoint extends Construct {
      * @param region one of `regions`
      */
     regionalUrl(region: string): string;
+    /**
+     * Routes the endpoint to `revision` instead of the function's current revision, optionally sharing
+     * traffic with one more revision (`additionalRevisions`, which gets its weight; `revision` gets the rest).
+     *
+     * Use it to keep an endpoint on an earlier revision (`WebFunctionRevision.fromRevisionAttributes`),
+     * or to send part of the traffic to the current revision:
+     * `fn.endpoint.routeTraffic(previous, [{ revision: fn.currentRevision, weight: 0.1 }])`.
+     * Can be called once per endpoint, and not on one created with `revision` or `additionalRevisions`.
+     */
+    routeTraffic(revision: IWebFunctionRevision, additionalRevisions?: WebFunctionRevisionWeight[]): void;
+    /**
+     * The IDs of the revisions this endpoint routes to.
+     *
+     * @internal
+     */
+    _revisionIds(): string[];
+    /**
+     * A metric of this endpoint in `AWS/Lambda/Web` (dimensions `FunctionName` and `EndpointName`).
+     *
+     * Metrics are published in the region that served the request: pass `region` for one of the endpoint's
+     * other regions. An alarm can only use metrics from its own stack's region.
+     *
+     * @default - sum over 1 minute, in the home region
+     */
+    metric(metricName: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /** Requests the endpoint served (`ExecutedRequests`). There's no separate count of successful (2XX) responses. */
+    metricRequests(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /**
+     * Requests answered with a 4XX status (`HTTPResponseStatusClass4XX`), including 429s from `rateLimit` and `maxEnvironments`.
+     * The metric only exists once it's non-zero, so alarms should treat missing data as not breaching.
+     */
+    metricClientErrors(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /**
+     * Requests answered with a 5XX status (`HTTPResponseStatusClass5XX`). Includes the platform's 503s while the endpoint
+     * scales up for a sudden burst, not only your application's errors. The metric only exists once it's non-zero.
+     */
+    metricServerErrors(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /** The percentage of requests answered with a 4XX status (math expression; periods with no 4XX count as 0). */
+    metricClientErrorRate(props?: cloudwatch.MetricOptions): cloudwatch.MathExpression;
+    /** The percentage of requests answered with a 5XX status (math expression; periods with no 5XX count as 0). */
+    metricServerErrorRate(props?: cloudwatch.MetricOptions): cloudwatch.MathExpression;
+    /**
+     * Execution environments serving the endpoint (`EndpointActiveEnvironments`), to compare with `maxEnvironments`.
+     *
+     * @default - maximum over 1 minute, in the home region
+     */
+    metricActiveEnvironments(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /** Requests rejected with 429 because the endpoint reached its `rateLimit` (`EndpointRequestThrottles`). */
+    metricRequestThrottles(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /** Requests rejected with 429 because the endpoint reached `maxEnvironments` (`EndpointActiveEnvironmentThrottles`). */
+    metricEnvironmentThrottles(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /**
+     * Allows `grantee` to call this endpoint. Shortcut for `grants.invoke(grantee)`.
+     * [disable-awslint:no-grants]
+     */
+    grantInvoke(grantee: iam.IGrantable): iam.Grant;
+    private metricIds;
+    private rate;
+    private usageMetric;
+    /** One alarm per threshold in every serving region: a CloudFormation alarm at home, a custom resource elsewhere. Returns their ARNs. */
+    private createRollbackAlarms;
 }
 export {};