@quadnix/octo-aws-cdk 0.0.19 → 0.2.0

package/dist/resources/cloudfront-distribution/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/resources/cloudfront-distribution/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC"}

package/dist/resources/cloudfront-distribution/index.schema.d.ts

@@ -0,0 +1,522 @@
+import { BaseResourceSchema } from '@quadnix/octo';
+/**
+ * Where a behavior reads a cache, origin request, or response headers policy from.
+ * * `managed` names one of AWS's own policies, e.g. `CachingOptimized`. It is looked up by name, so
+ * the id AWS assigns is never written down.
+ * * `custom` names one of the policies this distribution declares in its own properties.
+ *
+ * There is deliberately no way to pass a raw policy id. A name is enough for both, and offering two
+ * ways to say one thing only makes a caller wonder which is right.
+ *
+ * @group Resources/CloudFrontDistribution
+ */
+export type ICloudFrontPolicyReference = {
+    kind: 'custom' | 'managed';
+    name: string;
+};
+/**
+ * Where an origin's hostname comes from.
+ * * `resource` reads it out of another octo resource's response, which is what makes terraform order
+ * the two and what makes terragrunt wire the folders together. `responseKey` names the key holding
+ * the hostname, because resources do not agree on what to call it - an ALB publishes `DNSName`, an
+ * S3 website bucket publishes `RegionalDomainName`. The module author writes this next to the
+ * resource they are pointing at, so it is never an end user's problem.
+ * * `literal` is a hostname octo does not manage - a legacy origin, or a third party.
+ *
+ * @group Resources/CloudFrontDistribution
+ */
+export type ICloudFrontOriginSource = {
+    domainName: string;
+    kind: 'literal';
+} | {
+    kind: 'resource';
+    resourceId: string;
+    responseKey: string;
+};
+/**
+ * How a cache key or an origin request policy selects headers, cookies, or query strings.
+ * * `none` selects nothing.
+ * * `all` selects everything the viewer sent.
+ * * `allViewerAndWhitelistCloudFront` is an origin-request-only selection that forwards everything
+ * the viewer sent plus the named CloudFront headers.
+ * * `allowList` selects only the named values.
+ *
+ * @group Resources/CloudFrontDistribution
+ */
+export type ICloudFrontValueSelection = {
+    kind: 'all' | 'allViewerAndWhitelistCloudFront' | 'none';
+} | {
+    kind: 'allowList';
+    values: string[];
+};
+/**
+ * Which event in the request lifecycle an edge function runs on.
+ * CloudFront Functions may only run on a viewer event; Lambda@Edge may run on any of the four.
+ *
+ * @group Resources/CloudFrontDistribution
+ */
+export type ICloudFrontFunctionEventType = 'origin-request' | 'origin-response' | 'viewer-request' | 'viewer-response';
+/**
+ * One origin the distribution can serve from.
+ *
+ * @group Resources/CloudFrontDistribution
+ *
+ * @hideconstructor
+ */
+export declare class CloudFrontOriginSchema {
+    /**
+     * How many times CloudFront retries the origin before giving up. Between 1 and 3.
+     */
+    connectionAttempts?: number | undefined;
+    /**
+     * How long CloudFront waits to establish a connection to the origin, in seconds. Between 1 and 10.
+     */
+    connectionTimeout?: number | undefined;
+    /**
+     * Headers CloudFront adds to every request it sends to this origin.
+     * This is how a load balancer rejects anything that did not arrive through the distribution.
+     */
+    customHeaders?: {
+        [key: string]: string;
+    } | undefined;
+    /**
+     * What kind of origin this is, and the settings that only apply to that kind.
+     *
+     * * `s3` is a bucket reached privately. The distribution emits an origin access control for it,
+     * and builds the hostname from `bucketName` and `bucketRegion` rather than referencing the bucket,
+     * because the bucket's own policy already references this distribution. Granting the distribution
+     * read on the bucket is the bucket's job, driven by an overlay.
+     * * `custom` is anything that speaks HTTP - a load balancer, an EC2 instance, an API, a third
+     * party, or an S3 website endpoint.
+     */
+    kind: {
+        bucketName: string;
+        bucketRegion: string;
+        kind: "s3";
+    } | {
+        httpPort: number;
+        httpsPort: number;
+        keepaliveTimeout: number;
+        kind: "custom";
+        originProtocolPolicy: "http-only" | "https-only" | "match-viewer";
+        readTimeout: number;
+        source: ICloudFrontOriginSource;
+        sslProtocols: string[];
+    };
+    /**
+     * How this origin is named by behaviors and origin groups. Unique across origins and origin groups.
+     */
+    originId: string;
+    /**
+     * A prefix CloudFront prepends to the path before asking the origin for it.
+     * Empty asks the origin for the path the viewer requested.
+     */
+    originPath?: string | undefined;
+}
+/**
+ * A primary origin and the origin CloudFront falls back to when the primary answers with one of
+ * `failoverStatusCodes`.
+ *
+ * @group Resources/CloudFrontDistribution
+ *
+ * @hideconstructor
+ */
+export declare class CloudFrontOriginGroupSchema {
+    /**
+     * The origin id CloudFront falls back to.
+     */
+    failoverOriginId: string;
+    /**
+     * The status codes from the primary origin that trigger the failover.
+     */
+    failoverStatusCodes: number[];
+    /**
+     * How this group is named by behaviors. Unique across origins and origin groups.
+     */
+    originGroupId: string;
+    /**
+     * The origin id CloudFront tries first.
+     */
+    primaryOriginId: string;
+}
+/**
+ * An edge function CloudFront runs for a behavior. The function itself is not created here - pass
+ * the ARN of one that already exists.
+ *
+ * @group Resources/CloudFrontDistribution
+ *
+ * @hideconstructor
+ */
+export declare class CloudFrontFunctionAssociationSchema {
+    /**
+     * The ARN of the CloudFront Function or the Lambda@Edge function version.
+     */
+    arn: string;
+    /**
+     * Which lifecycle event the function runs on. See {@link ICloudFrontFunctionEventType}.
+     */
+    eventType: ICloudFrontFunctionEventType;
+    /**
+     * Which engine runs it. A `cloudfront-function` is JavaScript at the edge and may only bind to a
+     * viewer event; `lambda-edge` may bind to any of the four.
+     */
+    kind: "cloudfront-function" | "lambda-edge";
+}
+/**
+ * One rule binding a set of paths to an origin, and deciding everything about how those paths are
+ * served.
+ *
+ * @group Resources/CloudFrontDistribution
+ *
+ * @hideconstructor
+ */
+export declare class CloudFrontBehaviorSchema {
+    /**
+     * The HTTP methods CloudFront forwards to the origin.
+     * `['GET', 'HEAD']` is a CDN; the full set makes the distribution a reverse proxy.
+     */
+    allowedMethods?: string[] | undefined;
+    /**
+     * The subset of `allowedMethods` whose responses CloudFront caches.
+     */
+    cachedMethods?: string[] | undefined;
+    /**
+     * Which policy decides the cache key and the TTLs. See {@link ICloudFrontPolicyReference}.
+     */
+    cachePolicy: ICloudFrontPolicyReference;
+    /**
+     * Whether CloudFront compresses the response for viewers that accept it.
+     */
+    compress?: boolean | undefined;
+    /**
+     * Edge functions to run for this behavior. See {@link CloudFrontFunctionAssociationSchema}.
+     */
+    functionAssociations?: CloudFrontFunctionAssociationSchema[] | undefined;
+    /**
+     * Which policy decides what reaches the origin, independently of the cache key.
+     * `null` forwards only what the cache policy already selected.
+     */
+    originRequestPolicy?: ICloudFrontPolicyReference | null | undefined;
+    /**
+     * The paths this behavior claims, e.g. `/api/*`. Absent on the default behavior, which claims
+     * everything no other behavior did.
+     */
+    pathPattern?: string | null | undefined;
+    /**
+     * Which policy decides the headers CloudFront adds on the way out - CORS, HSTS, and the app's own
+     * content security policy. `null` adds nothing.
+     */
+    responseHeadersPolicy?: ICloudFrontPolicyReference | null | undefined;
+    /**
+     * The origin or origin group serving these paths.
+     */
+    targetOriginId: string;
+    /**
+     * What CloudFront does with a plain HTTP request.
+     */
+    viewerProtocolPolicy?: "https-only" | "allow-all" | "redirect-to-https" | undefined;
+}
+/**
+ * What the viewer gets when the origin answers with a status code CloudFront was told to handle.
+ *
+ * The same field set expresses opposite intents. A single-page app maps `403` and `404` to a `200`
+ * carrying `/index.html` with a short TTL, so the client-side router can take over; a content site
+ * maps them to a real `404` carrying an error page.
+ *
+ * @group Resources/CloudFrontDistribution
+ *
+ * @hideconstructor
+ */
+export declare class CloudFrontCustomErrorResponseSchema {
+    /**
+     * How long CloudFront caches this error before asking the origin again, in seconds.
+     */
+    errorCachingMinTtl?: number | undefined;
+    /**
+     * The status code the origin answered with.
+     */
+    errorCode: number;
+    /**
+     * The status code the viewer sees.
+     */
+    responseCode: number;
+    /**
+     * The object served in place of the error, e.g. `/index.html`.
+     */
+    responsePagePath: string;
+}
+/**
+ * A cache policy this distribution declares, referenced by a behavior under
+ * `{ kind: 'custom', name }`.
+ *
+ * @group Resources/CloudFrontDistribution
+ *
+ * @hideconstructor
+ */
+export declare class CloudFrontCachePolicySchema {
+    /**
+     * Which cookies are part of the cache key.
+     */
+    cookies?: ICloudFrontValueSelection | undefined;
+    /**
+     * How long CloudFront serves an object without asking the origin, when the origin sent no
+     * caching headers of its own. In seconds.
+     */
+    defaultTtl?: number | undefined;
+    /**
+     * Whether CloudFront may store and serve a brotli-compressed copy.
+     */
+    enableBrotli?: boolean | undefined;
+    /**
+     * Whether CloudFront may store and serve a gzip-compressed copy.
+     */
+    enableGzip?: boolean | undefined;
+    /**
+     * Which request headers are part of the cache key.
+     */
+    headers?: ICloudFrontValueSelection | undefined;
+    /**
+     * The longest CloudFront will serve an object without asking the origin, whatever the origin's
+     * own caching headers said. In seconds.
+     */
+    maxTtl?: number | undefined;
+    /**
+     * The shortest CloudFront will serve an object without asking the origin. In seconds.
+     */
+    minTtl?: number | undefined;
+    /**
+     * How a behavior names this policy.
+     */
+    name: string;
+    /**
+     * Which query strings are part of the cache key.
+     */
+    queryStrings?: ICloudFrontValueSelection | undefined;
+}
+/**
+ * An origin request policy this distribution declares, referenced by a behavior under
+ * `{ kind: 'custom', name }`.
+ *
+ * This is what reaches the origin, and it is separate from the cache key on purpose: an origin can
+ * be told the viewer's `Authorization` header without every distinct token becoming its own cache
+ * entry.
+ *
+ * @group Resources/CloudFrontDistribution
+ *
+ * @hideconstructor
+ */
+export declare class CloudFrontOriginRequestPolicySchema {
+    /**
+     * Which cookies reach the origin.
+     */
+    cookies?: ICloudFrontValueSelection | undefined;
+    /**
+     * Which request headers reach the origin.
+     */
+    headers?: ICloudFrontValueSelection | undefined;
+    /**
+     * How a behavior names this policy.
+     */
+    name: string;
+    /**
+     * Which query strings reach the origin.
+     */
+    queryStrings?: ICloudFrontValueSelection | undefined;
+}
+/**
+ * The security headers a response headers policy adds. Every field is optional; a `null` field adds
+ * nothing for that header.
+ *
+ * @group Resources/CloudFrontDistribution
+ *
+ * @hideconstructor
+ */
+export declare class CloudFrontSecurityHeadersSchema {
+    /**
+     * The app's own content security policy, verbatim.
+     */
+    contentSecurityPolicy?: string | null | undefined;
+    /**
+     * Whether to send `X-Content-Type-Options`, which tells a browser to trust the declared content
+     * type rather than guessing one from the bytes.
+     */
+    contentTypeOptions?: boolean | undefined;
+    /**
+     * The value of `X-Frame-Options`, or `null` to send none.
+     */
+    frameOptions?: "DENY" | "SAMEORIGIN" | null | undefined;
+    /**
+     * The value of `Referrer-Policy`, or `null` to send none.
+     */
+    referrerPolicy?: string | null | undefined;
+    /**
+     * How long a viewer should keep using HTTPS for this host, in seconds. `null` sends no
+     * `Strict-Transport-Security` header at all.
+     */
+    strictTransportSecurityMaxAge?: number | null | undefined;
+}
+/**
+ * A response headers policy this distribution declares, referenced by a behavior under
+ * `{ kind: 'custom', name }`.
+ *
+ * @group Resources/CloudFrontDistribution
+ *
+ * @hideconstructor
+ */
+export declare class CloudFrontResponseHeadersPolicySchema {
+    /**
+     * A cross-origin resource sharing configuration, or `null` for none.
+     */
+    cors?: {
+        allowCredentials: boolean;
+        allowHeaders: string[];
+        allowMethods: string[];
+        allowOrigins: string[];
+        maxAgeSeconds: number;
+    } | null | undefined;
+    /**
+     * Headers CloudFront adds verbatim. `override` decides what happens when the origin already sent
+     * one of the same name.
+     */
+    customHeaders?: {
+        header: string;
+        override: boolean;
+        value: string;
+    }[] | undefined;
+    /**
+     * How a behavior names this policy.
+     */
+    name: string;
+    /**
+     * Headers CloudFront strips from the origin's response before the viewer sees it.
+     */
+    removeHeaders?: string[] | undefined;
+    /**
+     * The security headers to add, or `null` to add none.
+     * See {@link CloudFrontSecurityHeadersSchema}.
+     */
+    securityHeaders?: CloudFrontSecurityHeadersSchema | null | undefined;
+}
+/**
+ * The `CloudFrontDistributionSchema` class is the schema for the `CloudFrontDistribution` resource,
+ * which represents an AWS CloudFront distribution. Terraform provisions it as
+ * [`aws_cloudfront_distribution`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudfront_distribution),
+ * alongside an
+ * [`aws_cloudfront_origin_access_control`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudfront_origin_access_control)
+ * per S3 origin and one terraform resource per policy the distribution declares.
+ *
+ * The distribution is deliberately open. It carries several origins of mixed kinds, a routing table
+ * of behaviors over them, and the security layer around both, so that one module can serve a
+ * single-page app out of a bucket while another puts the same resource in front of a load balancer.
+ * The opinion about which of those a caller gets belongs to the module, not here.
+ *
+ * @group Resources/CloudFrontDistribution
+ *
+ * @hideconstructor
+ *
+ * @overrideProperty parents - Every managed origin that is not an S3 bucket. The distribution reads
+ * such an origin's hostname out of its response, so it is a child of it. An S3 origin runs the other
+ * way - the bucket's policy has to name this distribution's ARN, which AWS assigns, so the bucket is
+ * the child and this distribution writes the bucket's hostname literally.
+ * ```mermaid
+ * graph TD;
+ *   origin((Origin<br>Resource)) --> cloudfront_distribution((CloudFront<br>Distribution))
+ *   cloudfront_distribution --> s3_bucket((S3<br>Bucket))
+ * ```
+ * @overrideProperty resourceId - The resource id is of format `cloudfront-<distribution-name>`.
+ * There is no region in it: CloudFront is global, and the provider is found on the account alone.
+ */
+export declare class CloudFrontDistributionSchema extends BaseResourceSchema {
+    /**
+     * Input properties.
+     * * `properties.aliases` - The custom domain names the distribution answers on. Each one needs a
+     * DNS record pointing at the distribution, which this resource does not create. Empty serves only
+     * the `*.cloudfront.net` domain CloudFront assigns.
+     * * `properties.awsAccountId` - The AWS account id.
+     * * `properties.behaviors` - The routing table. Exactly one entry has no `pathPattern` and is the
+     * default behavior; the rest are matched in order before it.
+     * See {@link CloudFrontBehaviorSchema}.
+     * * `properties.cachePolicies` - Cache policies this distribution declares.
+     * See {@link CloudFrontCachePolicySchema}.
+     * * `properties.comment` - A human-readable label. It is the only name a distribution carries in
+     * the console.
+     * * `properties.customErrorResponses` - What the viewer gets for an origin error.
+     * See {@link CloudFrontCustomErrorResponseSchema}.
+     * * `properties.defaultRootObject` - The object served for a request to the site root.
+     * * `properties.distributionName` - What names this distribution. Part of its identity.
+     * * `properties.enabled` - Whether the distribution serves traffic. Disabling is also the first
+     * half of deleting one, which AWS makes a slow operation.
+     * * `properties.geoRestriction` - Which countries may reach the distribution.
+     * * `properties.httpVersion` - The newest HTTP version viewers may negotiate.
+     * * `properties.isIpv6Enabled` - Whether the distribution answers over IP version 6.
+     * * `properties.logging` - Where CloudFront writes its access logs, or `null` for none. The bucket
+     * is not created here.
+     * * `properties.originGroups` - Fail-over pairs over the origins.
+     * See {@link CloudFrontOriginGroupSchema}.
+     * * `properties.originRequestPolicies` - Origin request policies this distribution declares.
+     * See {@link CloudFrontOriginRequestPolicySchema}.
+     * * `properties.origins` - Where content comes from. See {@link CloudFrontOriginSchema}.
+     * * `properties.priceClass` - Which edge locations serve the traffic, which is what the
+     * distribution costs. `PriceClass_100` is North America and Europe alone.
+     * * `properties.responseHeadersPolicies` - Response headers policies this distribution declares.
+     * See {@link CloudFrontResponseHeadersPolicySchema}.
+     * * `properties.viewerCertificate` - The certificate viewers see. `default` serves CloudFront's
+     * own, which is valid only for the assigned `*.cloudfront.net` domain; `acm` serves a certificate
+     * of yours, which CloudFront reads from `us-east-1` alone.
+     * * `properties.webAclArn` - The web ACL guarding the distribution, or `null` for none. The
+     * ACL is not created here, and CloudFront reads it from `us-east-1` alone.
+     */
+    properties: {
+        aliases: string[];
+        awsAccountId: string;
+        behaviors: CloudFrontBehaviorSchema[];
+        cachePolicies: CloudFrontCachePolicySchema[];
+        comment: string;
+        customErrorResponses: CloudFrontCustomErrorResponseSchema[];
+        defaultRootObject: string;
+        distributionName: string;
+        enabled: boolean;
+        geoRestriction: {
+            countries: string[];
+            kind: "allow" | "block";
+        } | {
+            kind: "none";
+        };
+        httpVersion: "http1.1" | "http2" | "http2and3";
+        isIpv6Enabled: boolean;
+        logging: {
+            bucketDomainName: string;
+            includeCookies: boolean;
+            prefix: string;
+        } | null;
+        originGroups: CloudFrontOriginGroupSchema[];
+        originRequestPolicies: CloudFrontOriginRequestPolicySchema[];
+        origins: CloudFrontOriginSchema[];
+        priceClass: "PriceClass_100" | "PriceClass_200" | "PriceClass_All";
+        responseHeadersPolicies: CloudFrontResponseHeadersPolicySchema[];
+        viewerCertificate: {
+            certificateArn: string;
+            kind: "acm";
+            minimumProtocolVersion: string;
+        } | {
+            kind: "default";
+        };
+        webAclArn: string | null;
+    };
+    /**
+     * Saved response.
+     * * `response.Arn` - The ARN of the distribution. A bucket admitting this distribution names it.
+     * * `response.DistributionId` - The distribution id, which is what an invalidation is issued against.
+     * * `response.DomainName` - The `*.cloudfront.net` domain CloudFront assigned. Point a DNS record
+     * at this.
+     * * `response.HostedZoneId` - The zone a Route 53 alias record pointing at this distribution needs.
+     * It is the same constant for every CloudFront distribution, and it is published here so that a
+     * DNS module never has to know that.
+     */
+    response: {
+        Arn?: string;
+        DistributionId?: string;
+        DomainName?: string;
+        HostedZoneId?: string;
+    };
+}