From 03d0ba52535c4d62856289e24e4cc45b72ff8ead Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antonio=20M=C3=A1rquez=20P=C3=A9rez?= Date: Wed, 25 Oct 2023 18:10:59 +0200 Subject: [PATCH] feat(codestarconnection): add codestar connection L2 construct - Basic L2 Construct to create a Code Star Connection - It validates the connection name lenght --- API.md | 907 +++++++++++++++++- README.md | 2 +- src/code-star-connection.ts | 352 +++++++ src/index.ts | 6 +- .../codestar-connection.snapshot.test.ts.snap | 51 + test/code-star-connection.test.ts | 58 ++ test/codestar-connection.snapshot.test.ts | 21 + test/hello.test.ts | 5 - 8 files changed, 1382 insertions(+), 20 deletions(-) create mode 100644 src/code-star-connection.ts create mode 100644 test/__snapshots__/codestar-connection.snapshot.test.ts.snap create mode 100644 test/code-star-connection.test.ts create mode 100644 test/codestar-connection.snapshot.test.ts delete mode 100644 test/hello.test.ts diff --git a/API.md b/API.md index 5ca197b..5c7f95f 100644 --- a/API.md +++ b/API.md @@ -1,22 +1,289 @@ -# replace this +# AWS CodeStar Connection + # API Reference +## Constructs + +### CodeStarConnection + +Define a CodeStar Connection resource. + +*Example* + +```typescript + new CodeStarConnection(this, 'MyConnection', { + connectionName: 'MyConnection', + providerType: 'GitHub', + tags: [{ + key: 'key', + value: 'value', + }], + } +``` + + +#### Initializers + +```typescript +import { CodeStarConnection } from '@jttc/aws-codestarconnection' + +new CodeStarConnection(scope: Construct, id: string, props: CodeStarConnectionProps) +``` + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| scope | constructs.Construct | *No description.* | +| id | string | *No description.* | +| props | CodeStarConnectionProps | *No description.* | + +--- + +##### `scope`Required + +- *Type:* constructs.Construct + +--- + +##### `id`Required + +- *Type:* string + +--- + +##### `props`Required + +- *Type:* CodeStarConnectionProps + +--- + +#### Methods + +| **Name** | **Description** | +| --- | --- | +| toString | Returns a string representation of this construct. | +| applyRemovalPolicy | Apply the given removal policy to this resource. | + +--- + +##### `toString` + +```typescript +public toString(): string +``` + +Returns a string representation of this construct. + +##### `applyRemovalPolicy` + +```typescript +public applyRemovalPolicy(policy: RemovalPolicy): void +``` + +Apply the given removal policy to this resource. + +The Removal Policy controls what happens to this resource when it stops +being managed by CloudFormation, either because you've removed it from the +CDK application or because you've made a change that requires the resource +to be replaced. + +The resource can be deleted (`RemovalPolicy.DESTROY`), or left in your AWS +account for data recovery and cleanup later (`RemovalPolicy.RETAIN`). + +###### `policy`Required + +- *Type:* aws-cdk-lib.RemovalPolicy + +--- + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| isConstruct | Checks if `x` is a construct. | +| isOwnedResource | Returns true if the construct was created by CDK, and false otherwise. | +| isResource | Check whether the given construct is a Resource. | + +--- + +##### `isConstruct` + +```typescript +import { CodeStarConnection } from '@jttc/aws-codestarconnection' + +CodeStarConnection.isConstruct(x: any) +``` + +Checks if `x` is a construct. + +Use this method instead of `instanceof` to properly detect `Construct` +instances, even when the construct library is symlinked. + +Explanation: in JavaScript, multiple copies of the `constructs` library on +disk are seen as independent, completely different libraries. As a +consequence, the class `Construct` in each copy of the `constructs` library +is seen as a different class, and an instance of one class will not test as +`instanceof` the other class. `npm install` will not create installations +like this, but users may manually symlink construct libraries together or +use a monorepo tool: in those cases, multiple copies of the `constructs` +library can be accidentally installed, and `instanceof` will behave +unpredictably. It is safest to avoid using `instanceof`, and using +this type-testing method instead. + +###### `x`Required + +- *Type:* any + +Any object. + +--- + +##### `isOwnedResource` + +```typescript +import { CodeStarConnection } from '@jttc/aws-codestarconnection' + +CodeStarConnection.isOwnedResource(construct: IConstruct) +``` + +Returns true if the construct was created by CDK, and false otherwise. + +###### `construct`Required + +- *Type:* constructs.IConstruct + +--- + +##### `isResource` + +```typescript +import { CodeStarConnection } from '@jttc/aws-codestarconnection' + +CodeStarConnection.isResource(construct: IConstruct) +``` + +Check whether the given construct is a Resource. + +###### `construct`Required + +- *Type:* constructs.IConstruct + +--- + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| node | constructs.Node | The tree node. | +| env | aws-cdk-lib.ResourceEnvironment | The environment this resource belongs to. | +| stack | aws-cdk-lib.Stack | The stack in which this resource is defined. | +| connectionArn | string | The ARN of the Code Star connection. | +| connectionName | string | The name of the Code Star connection. | + +--- + +##### `node`Required + +```typescript +public readonly node: Node; +``` + +- *Type:* constructs.Node + +The tree node. + +--- + +##### `env`Required + +```typescript +public readonly env: ResourceEnvironment; +``` + +- *Type:* aws-cdk-lib.ResourceEnvironment + +The environment this resource belongs to. + +For resources that are created and managed by the CDK +(generally, those created by creating new class instances like Role, Bucket, etc.), +this is always the same as the environment of the stack they belong to; +however, for imported resources +(those obtained from static methods like fromRoleArn, fromBucketName, etc.), +that might be different than the stack they were imported into. + +--- + +##### `stack`Required + +```typescript +public readonly stack: Stack; +``` + +- *Type:* aws-cdk-lib.Stack + +The stack in which this resource is defined. + +--- + +##### `connectionArn`Required + +```typescript +public readonly connectionArn: string; +``` + +- *Type:* string +The ARN of the Code Star connection. + +--- + +##### `connectionName`Required + +```typescript +public readonly connectionName: string; +``` + +- *Type:* string + +The name of the Code Star connection. + +--- -## Classes -### Hello +### CodeStarConnectionBase -#### Initializers +- *Implements:* ICodeStarConnection + +#### Initializers ```typescript -import { Hello } from '@jttc/aws-codestarconnection' +import { CodeStarConnectionBase } from '@jttc/aws-codestarconnection' -new Hello() +new CodeStarConnectionBase(scope: Construct, id: string, props?: ResourceProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | +| scope | constructs.Construct | *No description.* | +| id | string | *No description.* | +| props | aws-cdk-lib.ResourceProps | *No description.* | + +--- + +##### `scope`Required + +- *Type:* constructs.Construct + +--- + +##### `id`Required + +- *Type:* string + +--- + +##### `props`Optional + +- *Type:* aws-cdk-lib.ResourceProps --- @@ -24,17 +291,639 @@ new Hello() | **Name** | **Description** | | --- | --- | -| sayHello | *No description.* | +| toString | Returns a string representation of this construct. | +| applyRemovalPolicy | Apply the given removal policy to this resource. | + +--- + +##### `toString` + +```typescript +public toString(): string +``` + +Returns a string representation of this construct. + +##### `applyRemovalPolicy` + +```typescript +public applyRemovalPolicy(policy: RemovalPolicy): void +``` + +Apply the given removal policy to this resource. + +The Removal Policy controls what happens to this resource when it stops +being managed by CloudFormation, either because you've removed it from the +CDK application or because you've made a change that requires the resource +to be replaced. + +The resource can be deleted (`RemovalPolicy.DESTROY`), or left in your AWS +account for data recovery and cleanup later (`RemovalPolicy.RETAIN`). + +###### `policy`Required + +- *Type:* aws-cdk-lib.RemovalPolicy + +--- + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| isConstruct | Checks if `x` is a construct. | +| isOwnedResource | Returns true if the construct was created by CDK, and false otherwise. | +| isResource | Check whether the given construct is a Resource. | + +--- + +##### `isConstruct` + +```typescript +import { CodeStarConnectionBase } from '@jttc/aws-codestarconnection' + +CodeStarConnectionBase.isConstruct(x: any) +``` + +Checks if `x` is a construct. + +Use this method instead of `instanceof` to properly detect `Construct` +instances, even when the construct library is symlinked. + +Explanation: in JavaScript, multiple copies of the `constructs` library on +disk are seen as independent, completely different libraries. As a +consequence, the class `Construct` in each copy of the `constructs` library +is seen as a different class, and an instance of one class will not test as +`instanceof` the other class. `npm install` will not create installations +like this, but users may manually symlink construct libraries together or +use a monorepo tool: in those cases, multiple copies of the `constructs` +library can be accidentally installed, and `instanceof` will behave +unpredictably. It is safest to avoid using `instanceof`, and using +this type-testing method instead. + +###### `x`Required + +- *Type:* any + +Any object. + +--- + +##### `isOwnedResource` + +```typescript +import { CodeStarConnectionBase } from '@jttc/aws-codestarconnection' + +CodeStarConnectionBase.isOwnedResource(construct: IConstruct) +``` + +Returns true if the construct was created by CDK, and false otherwise. + +###### `construct`Required + +- *Type:* constructs.IConstruct + +--- + +##### `isResource` + +```typescript +import { CodeStarConnectionBase } from '@jttc/aws-codestarconnection' + +CodeStarConnectionBase.isResource(construct: IConstruct) +``` + +Check whether the given construct is a Resource. + +###### `construct`Required + +- *Type:* constructs.IConstruct + +--- + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| node | constructs.Node | The tree node. | +| env | aws-cdk-lib.ResourceEnvironment | The environment this resource belongs to. | +| stack | aws-cdk-lib.Stack | The stack in which this resource is defined. | +| connectionArn | string | The ARN of the Code Star connection. | +| connectionName | string | The name of the Code Star connection. | + +--- + +##### `node`Required + +```typescript +public readonly node: Node; +``` + +- *Type:* constructs.Node + +The tree node. + +--- + +##### `env`Required + +```typescript +public readonly env: ResourceEnvironment; +``` + +- *Type:* aws-cdk-lib.ResourceEnvironment + +The environment this resource belongs to. + +For resources that are created and managed by the CDK +(generally, those created by creating new class instances like Role, Bucket, etc.), +this is always the same as the environment of the stack they belong to; +however, for imported resources +(those obtained from static methods like fromRoleArn, fromBucketName, etc.), +that might be different than the stack they were imported into. + +--- + +##### `stack`Required + +```typescript +public readonly stack: Stack; +``` + +- *Type:* aws-cdk-lib.Stack + +The stack in which this resource is defined. + +--- + +##### `connectionArn`Required + +```typescript +public readonly connectionArn: string; +``` + +- *Type:* string + +The ARN of the Code Star connection. --- -##### `sayHello` +##### `connectionName`Required ```typescript -public sayHello(): string +public readonly connectionName: string; ``` +- *Type:* string + +The name of the Code Star connection. + +--- + + +## Structs + +### CodeStarConnectionProps + +#### Initializer +```typescript +import { CodeStarConnectionProps } from '@jttc/aws-codestarconnection' + +const codeStarConnectionProps: CodeStarConnectionProps = { ... } +``` +#### Properties +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| connectionName | string | The name of the connection. | +| providerType | CodeStarConnectionProviderType | The type of the connection. | +| hostArn | string | The Amazon Resource Name (ARN) of the host associated with the connection. | +| removalPolicy | aws-cdk-lib.RemovalPolicy | Determine what happens to the repository when the resource/stack is deleted. | +| tags | aws-cdk-lib.Tag[] | The list of tags associated with the connection. | + +--- + +##### `connectionName`Required + +```typescript +public readonly connectionName: string; +``` + +- *Type:* string + +The name of the connection. + +Connection names must be in an AWS user account. + +--- + +##### `providerType`Required + +```typescript +public readonly providerType: CodeStarConnectionProviderType; +``` + +- *Type:* CodeStarConnectionProviderType + +The type of the connection. + +--- + +##### `hostArn`Optional + +```typescript +public readonly hostArn: string; +``` + +- *Type:* string + +The Amazon Resource Name (ARN) of the host associated with the connection. + +--- + +##### `removalPolicy`Optional + +```typescript +public readonly removalPolicy: RemovalPolicy; +``` + +- *Type:* aws-cdk-lib.RemovalPolicy +- *Default:* RemovalPolicy.Retain + +Determine what happens to the repository when the resource/stack is deleted. + +--- + +##### `tags`Optional + +```typescript +public readonly tags: Tag[]; +``` + +- *Type:* aws-cdk-lib.Tag[] + +The list of tags associated with the connection. + +--- + + +## Protocols + +### ICodeStarConnection + +- *Extends:* aws-cdk-lib.IResource + +- *Implemented By:* CodeStarConnection, CodeStarConnectionBase, ICodeStarConnection + + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| node | constructs.Node | The tree node. | +| env | aws-cdk-lib.ResourceEnvironment | The environment this resource belongs to. | +| stack | aws-cdk-lib.Stack | The stack in which this resource is defined. | +| connectionArn | string | The ARN of the connection. | +| connectionName | string | The name of the connection. | + +--- + +##### `node`Required + +```typescript +public readonly node: Node; +``` + +- *Type:* constructs.Node + +The tree node. + +--- + +##### `env`Required + +```typescript +public readonly env: ResourceEnvironment; +``` + +- *Type:* aws-cdk-lib.ResourceEnvironment + +The environment this resource belongs to. + +For resources that are created and managed by the CDK +(generally, those created by creating new class instances like Role, Bucket, etc.), +this is always the same as the environment of the stack they belong to; +however, for imported resources +(those obtained from static methods like fromRoleArn, fromBucketName, etc.), +that might be different than the stack they were imported into. + +--- + +##### `stack`Required + +```typescript +public readonly stack: Stack; +``` + +- *Type:* aws-cdk-lib.Stack + +The stack in which this resource is defined. + +--- + +##### `connectionArn`Required + +```typescript +public readonly connectionArn: string; +``` + +- *Type:* string + +The ARN of the connection. + +--- + +##### `connectionName`Required + +```typescript +public readonly connectionName: string; +``` + +- *Type:* string + +The name of the connection. + +Connection names must be in an AWS user account. + +--- + +## Enums + +### CodeStarConnectionPolicyActions + +Actions defined by AWS CodeStar Connections Service prefix: codestar-connections. + +The Resource Type indicates whether each action supports resource-level permissions. +If there is no value, you must specify all resources ("*") to which the policy applies +in the Resource element of your policy statement + +The Condition Keys includes keys that you can specify in a policy statement's Condition element + +#### Members + +| **Name** | **Description** | +| --- | --- | +| CREATE_CONNECTION | Grants permission to create a Connection resource. | +| CREATE_HOST | Grants permission to create a Host resource. | +| DELETE_CONNECTION | Grants permission to delete a Connection resource. | +| DELETE_HOST | Grants permission to delete a host resource. | +| GET_CONNECTION | Grants permission to get details about a Connection resource. | +| GET_HOST | Grants permission to get details about a host resource. | +| GET_INDIVIDUAL_ACCESS_TOKEN | Grants permission to associate a third party, such as a Bitbucket App installation, with a Connection. | +| GET_INSTALLATION_URL_FOR_APP | Grants permission to associate a third party, such as a Bitbucket App installation, with a Connection. | +| GET_INSTALLATION_URL_FOR_HOST | Grants permission to get the URL to authorize an installation in a third party app. | +| GET_INSTALLATION_URL | Grants permission to get the URL to authorize an installation in a third party app. | +| LIST_CONNECTIONS | Grants permission to list Connection resources. | +| LIST_HOSTS | Grants permission to list host resources. | +| LIST_INDIVIDUAL_ACCESS_TOKENS | Grants permission to list individual access token. | +| LIST_INSTALLATIONS | Grants permission to list installations. | +| LIST_INSTALLATION_TARGETS | Grants permission to associate a third party, such as a Bitbucket App installation, with a Connection. | +| LIST_PASS_CONNECTIONS | Grants permission to list pass connections. | +| LIST_TAGS_FOR_RESOURCE | Grants permission to the set of key-value pairs that are used to manage the resource. | +| PASS_CONNECTION | Grants permission to pass a Connection resource to an AWS service that accepts a Connection ARN as input, such as codepipeline:CreatePipeline. | +| REGISTER_APP_CODE | Grants permission to associate a third party server, such as a GitHub Enterprise Server instance, with a Host. | +| START_APP_REGISTRATION_HANDSHAKE | Grants permission to associate a third party server, such as a GitHub Enterprise Server instance, with a Host. | +| START_OAUTH_HANDSHAKE | Grants permission to associate a third party, such as a Bitbucket App installation, with a Connection. | +| TAG_RESOURCE | Grants permission to add or modify the tags of the given resource. | +| UNTAG_RESOURCE | Grants permission to remove tags from an AWS resource. | +| UPDATE_CONNECTION_INSTALLATION | Grants permission to update a Connection resource with an installation of the CodeStar Connections App. | +| UPDATE_HOST | Grants permission to update a host resource. | +| USE_CONNECTION | Grants permission to use a Connection resource to call provider actions. | + +--- + +##### `CREATE_CONNECTION` + +Grants permission to create a Connection resource. + +--- + + +##### `CREATE_HOST` + +Grants permission to create a Host resource. + +--- + + +##### `DELETE_CONNECTION` + +Grants permission to delete a Connection resource. + +--- + + +##### `DELETE_HOST` + +Grants permission to delete a host resource. + +--- + + +##### `GET_CONNECTION` + +Grants permission to get details about a Connection resource. + +--- + + +##### `GET_HOST` + +Grants permission to get details about a host resource. + +--- + + +##### `GET_INDIVIDUAL_ACCESS_TOKEN` + +Grants permission to associate a third party, such as a Bitbucket App installation, with a Connection. + +--- + + +##### `GET_INSTALLATION_URL_FOR_APP` + +Grants permission to associate a third party, such as a Bitbucket App installation, with a Connection. + +--- + + +##### `GET_INSTALLATION_URL_FOR_HOST` + +Grants permission to get the URL to authorize an installation in a third party app. + +--- + + +##### `GET_INSTALLATION_URL` + +Grants permission to get the URL to authorize an installation in a third party app. + +--- + + +##### `LIST_CONNECTIONS` + +Grants permission to list Connection resources. + +--- + + +##### `LIST_HOSTS` + +Grants permission to list host resources. + +--- + + +##### `LIST_INDIVIDUAL_ACCESS_TOKENS` + +Grants permission to list individual access token. + +--- + + +##### `LIST_INSTALLATIONS` + +Grants permission to list installations. + +--- + + +##### `LIST_INSTALLATION_TARGETS` + +Grants permission to associate a third party, such as a Bitbucket App installation, with a Connection. + +--- + + +##### `LIST_PASS_CONNECTIONS` + +Grants permission to list pass connections. + +--- + + +##### `LIST_TAGS_FOR_RESOURCE` + +Grants permission to the set of key-value pairs that are used to manage the resource. + +--- + + +##### `PASS_CONNECTION` + +Grants permission to pass a Connection resource to an AWS service that accepts a Connection ARN as input, such as codepipeline:CreatePipeline. + +--- + + +##### `REGISTER_APP_CODE` + +Grants permission to associate a third party server, such as a GitHub Enterprise Server instance, with a Host. + +--- + + +##### `START_APP_REGISTRATION_HANDSHAKE` + +Grants permission to associate a third party server, such as a GitHub Enterprise Server instance, with a Host. + +--- + + +##### `START_OAUTH_HANDSHAKE` + +Grants permission to associate a third party, such as a Bitbucket App installation, with a Connection. + +--- + + +##### `TAG_RESOURCE` + +Grants permission to add or modify the tags of the given resource. + +--- + + +##### `UNTAG_RESOURCE` + +Grants permission to remove tags from an AWS resource. + +--- + + +##### `UPDATE_CONNECTION_INSTALLATION` + +Grants permission to update a Connection resource with an installation of the CodeStar Connections App. + +--- + + +##### `UPDATE_HOST` + +Grants permission to update a host resource. + +--- + + +##### `USE_CONNECTION` + +Grants permission to use a Connection resource to call provider actions. + +--- + + +### CodeStarConnectionProviderType + +Connection Provider Type supported. + +#### Members + +| **Name** | **Description** | +| --- | --- | +| GITHUB | Github provider. | +| GITHUB_ENTERPRISE | Github Entrprise provider. | +| GITLAB | Gitlab Provider. | +| BITBUCKET | Bitbucket Provider. | + +--- + +##### `GITHUB` + +Github provider. + +--- + + +##### `GITHUB_ENTERPRISE` + +Github Entrprise provider. + +--- + + +##### `GITLAB` + +Gitlab Provider. + +--- + + +##### `BITBUCKET` + +Bitbucket Provider. + +--- diff --git a/README.md b/README.md index b3fa7dd..b1daa4f 100644 --- a/README.md +++ b/README.md @@ -1 +1 @@ -# replace this \ No newline at end of file +# AWS CodeStar Connection diff --git a/src/code-star-connection.ts b/src/code-star-connection.ts new file mode 100644 index 0000000..b0b0526 --- /dev/null +++ b/src/code-star-connection.ts @@ -0,0 +1,352 @@ +import { + Annotations, + IResource, + RemovalPolicy, + Resource, + Tag, +} from 'aws-cdk-lib'; +import { CfnConnection } from 'aws-cdk-lib/aws-codestarconnections'; + +import { Construct } from 'constructs'; + +/** + * Connection Provider Type supported + */ +export enum CodeStarConnectionProviderType { + /** + * Github provider + */ + GITHUB = 'GitHub', + + /** + * Github Entrprise provider + */ + GITHUB_ENTERPRISE = 'GitHubEnterpriseServer', + + /** + * Gitlab Provider + */ + GITLAB = 'GitLab', + + /** + * Bitbucket Provider + */ + BITBUCKET = 'Bitbucket', +} + +/** + * Actions defined by AWS CodeStar Connections + * Service prefix: codestar-connections + * + * The Resource Type indicates whether each action supports resource-level permissions. + * If there is no value, you must specify all resources ("*") to which the policy applies + * in the Resource element of your policy statement + * + * The Condition Keys includes keys that you can specify in a policy statement's Condition element + */ +export enum CodeStarConnectionPolicyActions { + /** + * Grants permission to create a Connection resource + * @accessLevel Write + * @conditionKeys aws:RequestTag/${aws:TagKeys} + * @conditionKeys aws:TagKeys + * @conditionKeys codestar-connections:ProviderType + */ + CREATE_CONNECTION = 'codestar-connections:CreateConnection', + + /** + * Grants permission to create a Host resource + * @accessLevel Write + * @conditionKeys aws:RequestTag/${aws:TagKeys} + * @conditionKeys aws:TagKeys + * @conditionKeys codestar-connections:ProviderType + */ + CREATE_HOST = 'codestar-connections:CreateHost', + + /** + * Grants permission to delete a Connection resource + * @accessLevel Write + * @resourceTypes arn:${Partition}:codestar-connections:${Region}:${Account}:connection/${ConnectionId} (Required) + */ + DELETE_CONNECTION = 'codestar-connections:DeleteConnection', + + /** + * Grants permission to delete a host resource + * @accessLevel Write + * @resourceTypes arn:${Partition}:codestar-connections:${Region}:${Account}:host/${HostId} (Required) + */ + DELETE_HOST = 'codestar-connections:DeleteHost', + + /** + * Grants permission to get details about a Connection resource + * @accessLevel Read + * @resourceTypes arn:${Partition}:codestar-connections:${Region}:${Account}:connection/${ConnectionId} (Required) + */ + GET_CONNECTION = 'codestar-connections:GetConnection', + + /** + * Grants permission to get details about a host resource + * @accessLevel Read + * @resourceTypes arn:${Partition}:codestar-connections:${Region}:${Account}:host/${HostId} (Required) + */ + GET_HOST = 'codestar-connections:GetHost', + + /** + * Grants permission to associate a third party, such as a Bitbucket App installation, with a Connection + * @accessLevel Read + * @conditionKeys codestar-connections:ProviderType + * @dependsOn codestar-connections:StarOAuthHandshake + */ + GET_INDIVIDUAL_ACCESS_TOKEN = 'codestar-connections:GetIndividualAccessToken', + + /** + * Grants permission to associate a third party, such as a Bitbucket App installation, with a Connection + * @accessLevel Read + * @conditionKeys codestar-connections:ProviderType + * @dependsOn codestar-connections:StarOAuthHandshake + */ + GET_INSTALLATION_URL_FOR_APP = 'codestar-connections:GetInstallationUrlForApp', + + /** + * Grants permission to get the URL to authorize an installation in a third party app + * @accessLevel Read + * @conditionKeys codestar-connections:ProviderType + * @dependsOn codestar-connections:StarOAuthHandshake + */ + GET_INSTALLATION_URL_FOR_HOST = 'codestar-connections:GetInstallationUrlForHost', + + /** + * Grants permission to get the URL to authorize an installation in a third party app + * @accessLevel Read + * @conditionKeys codestar-connections:ProviderType + */ + GET_INSTALLATION_URL = 'codestar-connections:GetInstallationUrl', + + /** + * Grants permission to list Connection resources + * @accessLevel List + * @conditionKeys codestar-connections:ProviderTypeFilter + */ + LIST_CONNECTIONS = 'codestar-connections:ListConnections', + + /** + * Grants permission to list host resources + * @accessLevel List + * @conditionKeys codestar-connections:ProviderTypeFilter + */ + LIST_HOSTS = 'codestar-connections:ListHosts', + + /** + * Grants permission to list individual access token + * @accessLevel List + */ + LIST_INDIVIDUAL_ACCESS_TOKENS = 'codestar-connections:ListIndividualAccessTokens', + + /** + * Grants permission to list installations + * @accessLevel List + */ + LIST_INSTALLATIONS = 'codestar-connections:ListInstallations', + + /** + * Grants permission to associate a third party, such as a Bitbucket App installation, with a Connection + * @accessLevel List + * @dependson codestar-connections:GetIndividualAccessToken + * @dependsOn codestar-connections:StarOAuthHandshake + */ + LIST_INSTALLATION_TARGETS = 'codestar-connections:ListInstallationTargets', + + /** + * Grants permission to list pass connections + * @accessLevel List + */ + LIST_PASS_CONNECTIONS = 'codestar-connections:ListPassConnections', + + /** + * Grants permission to the set of key-value pairs that are used to manage the resource + * @accessList List + * @resouceTypes arn:${Partition}:codestar-connections:${Region}:${Account}:connection/${ConnectionId} (Required) + */ + LIST_TAGS_FOR_RESOURCE = 'codestar-connections:ListTagsForResource', + + /** + * Grants permission to pass a Connection resource to an AWS service that accepts a Connection ARN as input, such as codepipeline:CreatePipeline + * @accessLevel Read + * @resourceTypes arn:${Partition}:codestar-connections:${Region}:${Account}:connection/${ConnectionId} + * @conditionKeys codestar-connections:PassToService + */ + PASS_CONNECTION = 'codestar-connections:PassConnection', + + /** + * Grants permission to associate a third party server, such as a GitHub Enterprise Server instance, with a Host + * @accessLevel Read + * @conditionKeys codestar-connections:HostArn + */ + REGISTER_APP_CODE = 'codestar-connections:RegisterAppCode', + + /** + * Grants permission to associate a third party server, such as a GitHub Enterprise Server instance, with a Host + * @accessLevel Read + * @conditionKeys codestar-connections:HostArn + */ + START_APP_REGISTRATION_HANDSHAKE = 'codestar-connections:StartAppRegistrationHandshake', + + /** + * Grants permission to associate a third party, such as a Bitbucket App installation, with a Connection + * @accessLevel Read + * @conditionKeys codestar-connections:ProviderType + */ + START_OAUTH_HANDSHAKE = 'codestar-connections:StartOAuthHandshake', + + /** + * Grants permission to add or modify the tags of the given resource + * @accessLevel Tagging + * @resourceTypes arn:${Partition}:codestar-connections:${Region}:${Account}:connection/${ConnectionId} (Required) + * @conditionKeys aws:RequestTag/${aws:TagKeys} + * @conditionKeys aws:TagKeys + */ + TAG_RESOURCE = 'codestar-connections:TagResource', + + /** + * Grants permission to remove tags from an AWS resource + * @accessLevel Tagging + * @resourceTypes arn:${Partition}:codestar-connections:${Region}:${Account}:connection/${ConnectionId} (Required) + * @conditionKeys aws:TagKeys + */ + UNTAG_RESOURCE = 'codestar-connections:UntagResource', + + /** + * Grants permission to update a Connection resource with an installation of the CodeStar Connections App + * @accessLevel Write + * @resourceTypes arn:${Partition}:codestar-connections:${Region}:${Account}:connection/${ConnectionId} (Required) + * @dependsOn codestar-connections:GetInstallationUrl + * @dependsOn codestar-connections:GetIndividualAccessToken + * @dependsOn codestar-connections:StarOAuthHandshake + * @dependsOn codestar-connections:ListInstallationTargets + * @conditionKeys codestar-connections:InstallationId + */ + UPDATE_CONNECTION_INSTALLATION = 'codestar-connections:UpdateConnectionInstallation', + + /** + * Grants permission to update a host resource + * @accessLevel Write + * @resourceTypes arn:${Partition}:codestar-connections:${Region}:${Account}:host/${HostId} (Required) + */ + UPDATE_HOST = 'codestar-connections:UpdateHost', + + /** + * Grants permission to use a Connection resource to call provider actions + * @accessLevel Read + * @resourceTypes arn:${Partition}:codestar-connections:${Region}:${Account}:connection/${ConnectionId} (Required) + * @conditionKeys codestar-connections:FullRepositoryId + * @conditionKeys codestar-connections:ProviderAction + * @conditionKeys codestar-connections:ProviderPermissionsRequired + */ + USE_CONNECTION = 'codestar-connections:UseConnection', +} + +export interface ICodeStarConnection extends IResource { + /** + * The name of the connection. + * Connection names must be in an AWS user account. + */ + readonly connectionName: string; + + /** + * The ARN of the connection. + */ + readonly connectionArn: string; +} + +export abstract class CodeStarConnectionBase + extends Resource + implements ICodeStarConnection +{ + /** + * The name of the Code Star connection + */ + public abstract readonly connectionName: string; + + /** + * The ARN of the Code Star connection + */ + public abstract readonly connectionArn: string; +} + +export interface CodeStarConnectionProps { + /** + * The name of the connection. + * Connection names must be in an AWS user account. + */ + readonly connectionName: string; + + /** + * The type of the connection. + */ + readonly providerType: CodeStarConnectionProviderType; + + /** + * The Amazon Resource Name (ARN) of the host associated with the connection. + */ + readonly hostArn?: string; + + /** + * The list of tags associated with the connection. + */ + readonly tags?: Tag[]; + + /** + * Determine what happens to the repository when the resource/stack is deleted. + * + * @default RemovalPolicy.Retain + */ + readonly removalPolicy?: RemovalPolicy; +} + +/** + * Define a CodeStar Connection resource + * @resource AWS::CodeStarConnections::Connection + * @example + * + * new CodeStarConnection(this, 'MyConnection', { + * connectionName: 'MyConnection', + * providerType: 'GitHub', + * tags: [{ + * key: 'key', + * value: 'value', + * }], + * } + */ +export class CodeStarConnection extends CodeStarConnectionBase { + public readonly connectionName: string; + public readonly connectionArn: string; + + constructor(scope: Construct, id: string, props: CodeStarConnectionProps) { + super(scope, id, { + physicalName: props.connectionName, + }); + + this.validateConnectionName(props.connectionName); + + const resource = new CfnConnection(this, 'Resource', { + connectionName: props.connectionName, + providerType: props.providerType, + hostArn: props.hostArn, + tags: props.tags, + }); + + resource.applyRemovalPolicy(props.removalPolicy); + + this.connectionName = props.connectionName; + this.connectionArn = resource.attrConnectionArn; + } + + private validateConnectionName(qualifier: string): void { + // Rules codified from https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codestarconnections-connection.html#cfn-codestarconnections-connection-connectionname + if (qualifier.length < 2 || qualifier.length > 32) { + Annotations.of(this).addError( + 'Connection Name must be at least 1 and no more than 32 characters' + ); + } + } +} diff --git a/src/index.ts b/src/index.ts index fb2fabc..2e619dc 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,5 +1 @@ -export class Hello { - public sayHello() { - return 'hello, world!'; - } -} +export * from './code-star-connection'; diff --git a/test/__snapshots__/codestar-connection.snapshot.test.ts.snap b/test/__snapshots__/codestar-connection.snapshot.test.ts.snap new file mode 100644 index 0000000..b9fcc27 --- /dev/null +++ b/test/__snapshots__/codestar-connection.snapshot.test.ts.snap @@ -0,0 +1,51 @@ +// Jest Snapshot v1, https://goo.gl/fbAQLP + +exports[`Snapshot test validation Code Star Connection validation test 1`] = ` +{ + "Parameters": { + "BootstrapVersion": { + "Default": "/cdk-bootstrap/hnb659fds/version", + "Description": "Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]", + "Type": "AWS::SSM::Parameter::Value", + }, + }, + "Resources": { + "MyConnection5621880D": { + "DeletionPolicy": "Retain", + "Properties": { + "ConnectionName": "MyConnection", + "ProviderType": "GitHub", + }, + "Type": "AWS::CodeStarConnections::Connection", + "UpdateReplacePolicy": "Retain", + }, + }, + "Rules": { + "CheckBootstrapVersion": { + "Assertions": [ + { + "Assert": { + "Fn::Not": [ + { + "Fn::Contains": [ + [ + "1", + "2", + "3", + "4", + "5", + ], + { + "Ref": "BootstrapVersion", + }, + ], + }, + ], + }, + "AssertDescription": "CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI.", + }, + ], + }, + }, +} +`; diff --git a/test/code-star-connection.test.ts b/test/code-star-connection.test.ts new file mode 100644 index 0000000..3de98c8 --- /dev/null +++ b/test/code-star-connection.test.ts @@ -0,0 +1,58 @@ +import { App, Stack } from 'aws-cdk-lib'; +import { Template } from 'aws-cdk-lib/assertions'; +import { CodeStarConnection, CodeStarConnectionProviderType } from '../src'; + +describe('Code Star Connection', () => { + // GIVEN + let stack = new Stack(); + + // WHEN + new CodeStarConnection(stack, 'CodeStarConnection', { + connectionName: 'test-connection', + providerType: CodeStarConnectionProviderType.GITHUB, + }); + + it('should create a Code Star Connection', () => { + // THEN + Template.fromStack(stack).resourceCountIs( + 'AWS::CodeStarConnections::Connection', + 1 + ); + }); + + it('should have a Github provider', () => { + // THEN + Template.fromStack(stack).hasResourceProperties( + 'AWS::CodeStarConnections::Connection', + { + ProviderType: 'GitHub', + } + ); + }); + + it('should have Retention Policy by default', () => { + Template.fromStack(stack).hasResource( + 'AWS::CodeStarConnections::Connection', + { + DeletionPolicy: 'Retain', + UpdateReplacePolicy: 'Retain', + } + ); + }); + + it('should thrown an error if the connection name is to long', () => { + // GIVEN + const app = new App(); + stack = new Stack(app, 'TestStack'); + + // WHEN + new CodeStarConnection(stack, 'CodeStarConnection', { + connectionName: 'test-connection-is-longer-than-32-characters', + providerType: CodeStarConnectionProviderType.GITHUB, + }); + + expect(() => + Template.fromStack(app.synth().getStackArtifact(stack.stackId).template) + ).toThrowError(); + }); +}); diff --git a/test/codestar-connection.snapshot.test.ts b/test/codestar-connection.snapshot.test.ts new file mode 100644 index 0000000..80b9114 --- /dev/null +++ b/test/codestar-connection.snapshot.test.ts @@ -0,0 +1,21 @@ +import { Stack } from 'aws-cdk-lib'; +import { Template } from 'aws-cdk-lib/assertions'; + +import { CodeStarConnection, CodeStarConnectionProviderType } from '../src'; + +describe('Snapshot test validation', () => { + // Given a new Stack + const stack = new Stack(); + + // WHEN + new CodeStarConnection(stack, 'MyConnection', { + connectionName: 'MyConnection', + providerType: CodeStarConnectionProviderType.GITHUB, + }); + + // THEN + it('Code Star Connection validation test', () => { + const template = Template.fromStack(stack); + expect(template.toJSON()).toMatchSnapshot(); + }); +}); diff --git a/test/hello.test.ts b/test/hello.test.ts deleted file mode 100644 index 88b4d93..0000000 --- a/test/hello.test.ts +++ /dev/null @@ -1,5 +0,0 @@ -import { Hello } from '../src'; - -test('hello', () => { - expect(new Hello().sayHello()).toBe('hello, world!'); -});