From ab57d2a6aad9e0ffc1d5a50096e9b2e677af05f5 Mon Sep 17 00:00:00 2001 From: Josh Balfour Date: Tue, 24 Oct 2023 15:50:24 +0100 Subject: [PATCH] update readmes --- .../cross-region-stack-export/readme.md | 59 +++++++++++++++ .../constructs/edge-api-swagger/readme.md | 68 ++++++++++++++---- packages/constructs/edge-api/package.json | 3 - packages/constructs/edge-api/readme.md | 2 +- .../constructs/replicated-secret/readme.md | 2 +- packages/modules/edge-api-sdk/readme.md | 2 +- .../modules/email-receiver-types/readme.md | 2 + readme.md | 71 +++++++++++-------- yarn.lock | 3 - 9 files changed, 159 insertions(+), 53 deletions(-) create mode 100644 packages/constructs/cross-region-stack-export/readme.md diff --git a/packages/constructs/cross-region-stack-export/readme.md b/packages/constructs/cross-region-stack-export/readme.md new file mode 100644 index 0000000..254b2d9 --- /dev/null +++ b/packages/constructs/cross-region-stack-export/readme.md @@ -0,0 +1,59 @@ +# @reapit-cdk/cross-region-stack-export + + +![npm version](https://img.shields.io/npm/v/@reapit-cdk/cross-region-stack-export) +![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/cross-region-stack-export) +![coverage: 74.02%25](https://img.shields.io/badge/coverage-74.02%25-orange) +![Integ Tests: X](https://img.shields.io/badge/Integ%20Tests-X-red) + +Allows you to share values between stack across regions and accounts. + +## Package Installation: + +```sh +yarn add --dev @reapit-cdk/cross-region-stack-export +# or +npm install @reapit-cdk/cross-region-stack-export --save-dev +``` + +## Usage +```ts +import { CfnOutput, Stack, App } from 'aws-cdk-lib' +import { CrossRegionStackExport } from '@reapit-cdk/cross-region-stack-export' +import { Bucket } from 'aws-cdk-lib/aws-s3' + +const app = new App() +const euStack = new Stack(app, 'stack-eu', { + env: { + account: '11111111', + region: 'eu-west-1', + }, +}) + +const exporter = new CrossRegionStackExport(euStack, 'exporter') +exporter.setValue('thing', 'avalue') + +const bucket = new Bucket(euStack, 'bucket') +exporter.setValue('bucketArn', bucket.bucketArn) + +const usStack = new Stack(app, 'stack-us', { + env: { + account: '2222222222', + region: 'us-east-1', + }, +}) + +const importer = exporter.getImporter(usStack, 'eu-importer') + +const euThing = importer.getValue('thing') +const euBucket = Bucket.fromBucketArn(usStack, 'eu-bucket', importer.getValue('bucketArn')) + +new CfnOutput(usStack, 'euThing', { + value: euThing, +}) + +new CfnOutput(usStack, 'euBucketName', { + value: euBucket.bucketName, +}) + +``` \ No newline at end of file diff --git a/packages/constructs/edge-api-swagger/readme.md b/packages/constructs/edge-api-swagger/readme.md index 38c91ef..c19cca9 100644 --- a/packages/constructs/edge-api-swagger/readme.md +++ b/packages/constructs/edge-api-swagger/readme.md @@ -1,31 +1,73 @@ -# @reapit-cdk/active-ruleset +# @reapit-cdk/edge-api-swagger -![npm version](https://img.shields.io/npm/v/@reapit-cdk/active-ruleset) -![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/active-ruleset) -![coverage: 99.02%25](https://img.shields.io/badge/coverage-99.02%25-green) -![Integ Tests: ✔](https://img.shields.io/badge/Integ%20Tests-%E2%9C%94-green) +![npm version](https://img.shields.io/npm/v/@reapit-cdk/edge-api-swagger) +![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/edge-api-swagger) +![coverage: 0%25](https://img.shields.io/badge/coverage-0%25-red) +![Integ Tests: X](https://img.shields.io/badge/Integ%20Tests-X-red) -This construct returns the currently active SES receipt RuleSet, or creates one. This enables you to add rules to it. +Add a swagger endpoint to your EdgeAPI ## Package Installation: ```sh -yarn add --dev @reapit-cdk/active-ruleset +yarn add --dev @reapit-cdk/edge-api-swagger # or -npm install @reapit-cdk/active-ruleset --save-dev +npm install @reapit-cdk/edge-api-swagger --save-dev ``` ## Usage ```ts -import { CfnOutput, Stack, App } from 'aws-cdk-lib' -import { ActiveRuleset } from '@reapit-cdk/active-ruleset' +import { Stack, App } from 'aws-cdk-lib' +import { EdgeAPI, EdgeAPILambda } from '@reapit-cdk/edge-api' +import { Code, Runtime } from 'aws-cdk-lib/aws-lambda' +import { EdgeAPISwaggerEndpoint } from '@reapit-cdk/edge-api-swagger' +import { Certificate } from 'aws-cdk-lib/aws-certificatemanager' +import * as path from 'path' const app = new App() const stack = new Stack(app, 'stack-name') -const activeRuleset = new ActiveRuleset(stack, 'active-ruleset') -new CfnOutput(stack, 'activeRulesetName', { - value: activeRuleset.receiptRuleSet.receiptRuleSetName, + +const certificate = new Certificate(stack, 'certificate', { + domainName: 'example.org', +}) +const api = new EdgeAPI(stack, 'api', { + certificate, + domains: ['example.org', 'example.com'], + devMode: false, + defaultEndpoint: { + destination: 'example.com', + }, }) +const lambda = new EdgeAPILambda(stack, 'lambda', { + code: Code.fromAsset(path.resolve('../lambda/dist')), + codePath: path.resolve('../lambda/src/index.ts'), // gets added to the docs + handler: 'index.handler', + runtime: Runtime.NODEJS_18_X, + environment: { + aVariable: 'contents', + }, +}) + +api.addEndpoint({ + pathPattern: '/api/lambda', + lambda, +}) + +api.addEndpoint( + new EdgeAPISwaggerEndpoint(stack, 'docs', { + api, + url: 'https://example.org', + + pathPattern: '/swagger', // optional, defaults to /swagger + + // optional + info: { + title: '', // defaults to Edge API + version: '', // defaults to 1.0.0 + }, + }), +) + ``` \ No newline at end of file diff --git a/packages/constructs/edge-api/package.json b/packages/constructs/edge-api/package.json index 8f5621c..7f4499c 100644 --- a/packages/constructs/edge-api/package.json +++ b/packages/constructs/edge-api/package.json @@ -39,9 +39,6 @@ "constructs": "^10.2.70" }, "devDependencies": { - "@aws-sdk/client-dynamodb": "3.414.0", - "@aws-sdk/client-secrets-manager": "3.414.0", - "@aws-sdk/lib-dynamodb": "3.414.0", "@reapit-cdk/cloudfront-invalidation": "workspace:^", "@reapit-cdk/eslint-config": "workspace:^", "@reapit-cdk/integration-tests": "workspace:^", diff --git a/packages/constructs/edge-api/readme.md b/packages/constructs/edge-api/readme.md index 6343c6d..d932f24 100644 --- a/packages/constructs/edge-api/readme.md +++ b/packages/constructs/edge-api/readme.md @@ -3,7 +3,7 @@ ![npm version](https://img.shields.io/npm/v/@reapit-cdk/edge-api) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/edge-api) -![coverage: 97.85%25](https://img.shields.io/badge/coverage-97.85%25-green) +![coverage: 96.97%25](https://img.shields.io/badge/coverage-96.97%25-green) ![Integ Tests: ✔](https://img.shields.io/badge/Integ%20Tests-%E2%9C%94-green) This construct creates a truly globally available API where code executes at the edge. Because changes take a long time to propagate to all edge locations, there is a `devMode` flag which will instead deploy your API to a [HTTP API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html). This is compatible with hotswapping, so [`cdk watch`](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-deploy-watch) works very well. In order to make it easy to develop APIs which handle both event formats and work around the environment variable limitation, I recommend you use the lightweight request wrapper [@reapit-cdk/edge-api-sdk](../../modules/edge-api-sdk) which normalises the event format and offers some extra helpers. diff --git a/packages/constructs/replicated-secret/readme.md b/packages/constructs/replicated-secret/readme.md index 1d26e2f..4ec448f 100644 --- a/packages/constructs/replicated-secret/readme.md +++ b/packages/constructs/replicated-secret/readme.md @@ -3,7 +3,7 @@ ![npm version](https://img.shields.io/npm/v/@reapit-cdk/replicated-secret) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/replicated-secret) -![coverage: 97.17%25](https://img.shields.io/badge/coverage-97.17%25-green) +![coverage: 97.06%25](https://img.shields.io/badge/coverage-97.06%25-green) ![Integ Tests: ✔](https://img.shields.io/badge/Integ%20Tests-%E2%9C%94-green) Creates a Secret and replicates it across the given regions. Requires a [ReplicatedKey](../replicated-key/readme.md) be passed in. diff --git a/packages/modules/edge-api-sdk/readme.md b/packages/modules/edge-api-sdk/readme.md index f7167ee..b0c68b7 100644 --- a/packages/modules/edge-api-sdk/readme.md +++ b/packages/modules/edge-api-sdk/readme.md @@ -3,7 +3,7 @@ ![npm version](https://img.shields.io/npm/v/@reapit-cdk/edge-api-sdk) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/edge-api-sdk) -![coverage: 96.44%25](https://img.shields.io/badge/coverage-96.44%25-green) +![coverage: 96.68%25](https://img.shields.io/badge/coverage-96.68%25-green) Provides convenience wrappers for accepting and responding to [@reapit-cdk/edge-api]('../../constructs/edge-api/readme.md') lambda requests. diff --git a/packages/modules/email-receiver-types/readme.md b/packages/modules/email-receiver-types/readme.md index acb3869..f13bf6e 100644 --- a/packages/modules/email-receiver-types/readme.md +++ b/packages/modules/email-receiver-types/readme.md @@ -5,6 +5,8 @@ ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/email-receiver-types) ![coverage: 0%25](https://img.shields.io/badge/coverage-0%25-red) +Types for @reapit-cdk/email-receiver and client. + ## Package Installation: ```sh diff --git a/readme.md b/readme.md index 65a778e..3b37b8f 100644 --- a/readme.md +++ b/readme.md @@ -1,5 +1,5 @@ # @reapit-cdk/ts-constructs -![coverage: 95.81%25](https://img.shields.io/badge/coverage-95.81%25-green) +![coverage: 93.49%25](https://img.shields.io/badge/coverage-93.49%25-green) CDK Constructs Monorepo ## Constructs @@ -7,7 +7,7 @@ CDK Constructs Monorepo Packages -

@reapit-cdk/active-ruleset

+

@reapit-cdk/active-ruleset

![npm version](https://img.shields.io/npm/v/@reapit-cdk/active-ruleset) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/active-ruleset) @@ -15,7 +15,7 @@ CDK Constructs Monorepo ![Integ Tests: ✔](https://img.shields.io/badge/Integ%20Tests-%E2%9C%94-green) This construct returns the currently active SES receipt RuleSet, or creates one. This enables you to add rules to it. -

@reapit-cdk/cloudfront-invalidation

+

@reapit-cdk/cloudfront-invalidation

![npm version](https://img.shields.io/npm/v/@reapit-cdk/cloudfront-invalidation) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/cloudfront-invalidation) @@ -23,15 +23,31 @@ This construct returns the currently active SES receipt RuleSet, or creates one. ![Integ Tests: ✔](https://img.shields.io/badge/Integ%20Tests-%E2%9C%94-green) CloudFront invalidations are [very error prone](https://github.com/aws/aws-cdk/issues/15891#issuecomment-966456154), making it hard to invalidate distributions reliably. This construct aims to solve this problem by using a step function which is triggered on stack update, and uses exponential backoff to retry the invalidation. Inspired by https://github.com/aws/aws-cdk/issues/15891#issuecomment-1362163142. -

@reapit-cdk/edge-api

+

@reapit-cdk/cross-region-stack-export

+ +![npm version](https://img.shields.io/npm/v/@reapit-cdk/cross-region-stack-export) +![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/cross-region-stack-export) +![coverage: 74.02%25](https://img.shields.io/badge/coverage-74.02%25-orange) +![Integ Tests: X](https://img.shields.io/badge/Integ%20Tests-X-red) + +Allows you to share values between stack across regions and accounts. +

@reapit-cdk/edge-api

![npm version](https://img.shields.io/npm/v/@reapit-cdk/edge-api) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/edge-api) -![coverage: 97.85%25](https://img.shields.io/badge/coverage-97.85%25-green) +![coverage: 96.97%25](https://img.shields.io/badge/coverage-96.97%25-green) ![Integ Tests: ✔](https://img.shields.io/badge/Integ%20Tests-%E2%9C%94-green) This construct creates a truly globally available API where code executes at the edge. Because changes take a long time to propagate to all edge locations, there is a `devMode` flag which will instead deploy your API to a [HTTP API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html). This is compatible with hotswapping, so [`cdk watch`](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-deploy-watch) works very well. In order to make it easy to develop APIs which handle both event formats and work around the environment variable limitation, I recommend you use the lightweight request wrapper [@reapit-cdk/edge-api-sdk](../../modules/edge-api-sdk) which normalises the event format and offers some extra helpers. -

@reapit-cdk/email-receiver

+

@reapit-cdk/edge-api-swagger

+ +![npm version](https://img.shields.io/npm/v/@reapit-cdk/edge-api-swagger) +![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/edge-api-swagger) +![coverage: 0%25](https://img.shields.io/badge/coverage-0%25-red) +![Integ Tests: X](https://img.shields.io/badge/Integ%20Tests-X-red) + +Add a swagger endpoint to your EdgeAPI +

@reapit-cdk/email-receiver

![npm version](https://img.shields.io/npm/v/@reapit-cdk/email-receiver) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/email-receiver) @@ -39,7 +55,7 @@ This construct creates a truly globally available API where code executes at the ![Integ Tests: ✔](https://img.shields.io/badge/Integ%20Tests-%E2%9C%94-green) This construct sets up everything necessary to receive email. The emails get stored in a dynamodb table, queryable by recipient. This is designed to be used in end-to-end tests, with the [@reapit-cdk/email-receiver-client](../../libs/email-receiver-client) helper library. -

@reapit-cdk/replicated-key

+

@reapit-cdk/replicated-key

![npm version](https://img.shields.io/npm/v/@reapit-cdk/replicated-key) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/replicated-key) @@ -47,15 +63,15 @@ This construct sets up everything necessary to receive email. The emails get sto ![Integ Tests: ✔](https://img.shields.io/badge/Integ%20Tests-%E2%9C%94-green) Creates a KMS key and replicates it to the desired regions. Useful when replicating secrets across regions. -

@reapit-cdk/replicated-secret

+

@reapit-cdk/replicated-secret

![npm version](https://img.shields.io/npm/v/@reapit-cdk/replicated-secret) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/replicated-secret) -![coverage: 97.17%25](https://img.shields.io/badge/coverage-97.17%25-green) +![coverage: 97.06%25](https://img.shields.io/badge/coverage-97.06%25-green) ![Integ Tests: ✔](https://img.shields.io/badge/Integ%20Tests-%E2%9C%94-green) Creates a Secret and replicates it across the given regions. Requires a [ReplicatedKey](../replicated-key/readme.md) be passed in. -

@reapit-cdk/userpool-domain

+

@reapit-cdk/userpool-domain

![npm version](https://img.shields.io/npm/v/@reapit-cdk/userpool-domain) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/userpool-domain) @@ -63,7 +79,7 @@ Creates a Secret and replicates it across the given regions. Requires a [Replica ![Integ Tests: ✔](https://img.shields.io/badge/Integ%20Tests-%E2%9C%94-green) This construct returns the given Cognito UserPool's UserPoolDomain, or creates one. This resolves an issue with [AWS::Cognito::UserPoolDomain](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cognito-userpooldomain.html), since that will fail if one already exists. -

@reapit-cdk/wildcard-certificate

+

@reapit-cdk/wildcard-certificate

![npm version](https://img.shields.io/npm/v/@reapit-cdk/wildcard-certificate) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/wildcard-certificate) @@ -81,41 +97,34 @@ This construct returns a wildcard certificate valid for subdomains of the given Packages -

@reapit-cdk/common

- -![npm version](https://img.shields.io/npm/v/@reapit-cdk/common) -![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/common) -![coverage: 99.02%25](https://img.shields.io/badge/coverage-99.02%25-green) - -Common types and small utilities. -

@reapit-cdk/custom-resource-wrapper

+

@reapit-cdk/custom-resource-wrapper

![npm version](https://img.shields.io/npm/v/@reapit-cdk/custom-resource-wrapper) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/custom-resource-wrapper) ![coverage: 99.02%25](https://img.shields.io/badge/coverage-99.02%25-green) This module helps write custom resource handlers. It's designed to work with the [Custom Resource Provider Framework](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CustomResource.html). It accepts an object which contains event handlers for `onCreate`, and optionally, `onUpdate`, and `onDelete`. Anything returned from `onCreate` and `onUpdate` is returned as data attributes on the resulting custom resource. -

@reapit-cdk/edge-api-sdk

+

@reapit-cdk/edge-api-sdk

![npm version](https://img.shields.io/npm/v/@reapit-cdk/edge-api-sdk) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/edge-api-sdk) -![coverage: 96.44%25](https://img.shields.io/badge/coverage-96.44%25-green) +![coverage: 96.68%25](https://img.shields.io/badge/coverage-96.68%25-green) Provides convenience wrappers for accepting and responding to [@reapit-cdk/edge-api]('../../constructs/edge-api/readme.md') lambda requests. -

@reapit-cdk/email-receiver-client

+

@reapit-cdk/email-receiver-client

![npm version](https://img.shields.io/npm/v/@reapit-cdk/email-receiver-client) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/email-receiver-client) ![coverage: 99.02%25](https://img.shields.io/badge/coverage-99.02%25-green) This module helps you write tests which rely on receiving emails. Once you have set up [@reapit-cdk/email-receiver](../../constructs/email-receiver/), this module helps you interact with the dynamodb table it creates. You'll have to export the table arn and domain name from your stack and import them to be used here, using [something like this](https://gist.github.com/joshbalfour/c0deb95f1e5938434ed6f6117dec8662). -

@reapit-cdk/email-receiver-types

+

@reapit-cdk/email-receiver-types

![npm version](https://img.shields.io/npm/v/@reapit-cdk/email-receiver-types) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/email-receiver-types) ![coverage: 0%25](https://img.shields.io/badge/coverage-0%25-red) - +Types for @reapit-cdk/email-receiver and client. @@ -126,49 +135,49 @@ This module helps you write tests which rely on receiving emails. Once you have Packages -

@reapit-cdk/eslint-config

+

@reapit-cdk/eslint-config

![npm version](https://img.shields.io/npm/v/@reapit-cdk/eslint-config) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/eslint-config) ![coverage: 0%25](https://img.shields.io/badge/coverage-0%25-red) @reapit-cdk eslint config. -

@reapit-cdk/generate-readme

+

@reapit-cdk/generate-readme

![npm version](https://img.shields.io/npm/v/@reapit-cdk/generate-readme) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/generate-readme) ![coverage: 0%25](https://img.shields.io/badge/coverage-0%25-red) Generates package readmes. -

@reapit-cdk/integration-tests

+

@reapit-cdk/integration-tests

![npm version](https://img.shields.io/npm/v/@reapit-cdk/integration-tests) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/integration-tests) ![coverage: 0%25](https://img.shields.io/badge/coverage-0%25-red) Easily run integration tests for CDK constructs using Jest. On successful test suite run, snapshots the stack which gets stored in your repo alongside the test. Subsequent test runs will diff the stack against the snapshot, and only run the tests if something changes. -

@reapit-cdk/jsii

+

@reapit-cdk/jsii

![npm version](https://img.shields.io/npm/v/@reapit-cdk/jsii) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/jsii) ![coverage: 0%25](https://img.shields.io/badge/coverage-0%25-red) JSII tools for @reapit-cdk. -

@reapit-cdk/tsconfig

+

@reapit-cdk/tsconfig

![npm version](https://img.shields.io/npm/v/@reapit-cdk/tsconfig) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/tsconfig) ![coverage: 0%25](https://img.shields.io/badge/coverage-0%25-red) tsconfig for @reapit-cdk. -

@reapit-cdk/tsup

+

@reapit-cdk/tsup

![npm version](https://img.shields.io/npm/v/@reapit-cdk/tsup) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/tsup) ![coverage: 0%25](https://img.shields.io/badge/coverage-0%25-red) Easily build @reapit-cdk constructs and custom resource lambdas. -

@reapit-cdk/version-package

+

@reapit-cdk/version-package

![npm version](https://img.shields.io/npm/v/@reapit-cdk/version-package) ![npm downloads](https://img.shields.io/npm/dm/@reapit-cdk/version-package) diff --git a/yarn.lock b/yarn.lock index 8a4e8f4..dcc95dd 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2893,9 +2893,6 @@ __metadata: dependencies: "@aws-cdk/aws-apigatewayv2-alpha": "npm:2.96.2-alpha.0" "@aws-cdk/aws-apigatewayv2-integrations-alpha": "npm:2.96.2-alpha.0" - "@aws-sdk/client-dynamodb": "npm:3.414.0" - "@aws-sdk/client-secrets-manager": "npm:3.414.0" - "@aws-sdk/lib-dynamodb": "npm:3.414.0" "@reapit-cdk/cloudfront-invalidation": "workspace:^" "@reapit-cdk/eslint-config": "workspace:^" "@reapit-cdk/integration-tests": "workspace:^"