feat(cli-plugin-contract): introduce a public contract between CLI and plugins #32111

otaviomacedo · 2024-11-13T14:20:24Z

The contract between the CLI and credential provider plugins is not publicly defined.

Extract the types involved in the CLI-plugin communication into a new package, @aws-cdk/cli-plugin-contract, and update all references in the CLI code.

Closes #32099, closes https://github.com/aws/aws-cdk-cli/issues/6, closes #19564

Checklist

My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

…d plugins

aws-cdk-automation

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

codecov · 2024-11-13T14:43:42Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 80.64%. Comparing base (07e6dd3) to head (87de2e2).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #32111      +/-   ##
==========================================
- Coverage   80.64%   80.64%   -0.01%     
==========================================
  Files         107      107              
  Lines        6996     6994       -2     
  Branches     1290     1290              
==========================================
- Hits         5642     5640       -2     
  Misses       1175     1175              
  Partials      179      179

Flag	Coverage Δ
suite.unit	`80.64% <100.00%> (-0.01%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
packages/aws-cdk	`80.64% <100.00%> (-0.01%)`	⬇️

mrgrain · 2024-11-13T15:47:01Z

packages/@aws-cdk/cli-plugin-contract/lib/index.ts

+   *
+   * Guaranteed to be called only if canProvideCredentails() returned true at some point.
+   */
+  getProvider(accountId: string, mode: Mode): Promise<AwsCredentials>;


We change this to a strongly typed string, we can make this package types only.

Suggested change

getProvider(accountId: string, mode: Mode): Promise<AwsCredentials>;

getProvider(accountId: string, mode: 'ForReading' | 'ForWriting'): Promise<AwsCredentials>;

This would be a breaking change for plugins, which are expecting a number (ForReading = 0, ForWriting = 1).

getProvider(accountId: string, mode: 0 | 1): Promise<AwsCredentials>; getProviderEx(accountId: string, mode: 'ForReading' | 'ForWriting'): Promise<AwsCredentials>;

?

This reverts commit 16d3d4d.

otaviomacedo · 2024-11-25T11:21:24Z

packages/@aws-cdk/cli-plugin-contract/lib/index.ts

+/**
+ * A list of credential provider sources
+ */
+export interface CredentialProviderSourceRepository {


I'd happily rename this interface if someone has a better suggestion.

PluginHost ?

It's technically also for lookup plugins, for example.

If we call it PluginHost, what should we call the class that implements it in the CLI?

otaviomacedo · 2024-11-25T11:28:49Z

packages/@aws-cdk/cli-plugin-contract/lib/index.ts

+  getPromise?: () => Promise<void>;
+}
+
+export enum Mode {


I've considered making this a const enum but, given the documented pitfalls, I've decided against it. This value will probably be used only once during the execution of the plugin, which itself is part of much bigger CDK command execution. So the cost of additional indirection when accessing enum values is negligible.

The goal of that was more to avoid having plugins take a runtime dependency on this package. They should be able to take only a devDependency on this package.

What is the concrete pitfall you're concerned about?

All three of them. If you look at the approaches to avoid them, they boil down to "do not use this feature if an external package is going to consume this enum", which is exactly the case here.

The CLI immediately invokes credential *providers* to produce *credentials*, and passes the credentials around instead of the providers. This means that if short-lived credentials expire (like session credentials from roles), there is no way to refresh them. CLI calls will start to fail if that happens. To fix this, instead of resolving providers to credentials, pass providers around instead. Implications for auth plugins ------------- This widens the plugin protocol: the new plugin protocol *forced* a translation to V3 credentials, and had no way to return V3 providers. While it is now possible to return V3 Credential Providers from the plugin protocol, plugin writers cannot easily take advantage of that protocol because there have been ~8 CLI releases that only support V3 credentials and will fail at runtime of V3 providers are returned. To support this, pass a new options argument into `getProvider()`: this will indicate whether V3 Providers are supported or not. Plugins can return a provider if the CLI indicates that it supports V3 providers, and avoid doing that if the CLI indicates it won't. That way, plugins can be rewritten to take advantage of returning V3 providers without crashing on CLI versions `2.167.0..(this releases)`. This also affects #32111 in which the plugin contract is being moved.

The CLI immediately invokes credential *providers* to produce *credentials*, and passes the credentials around instead of the providers. This means that if short-lived credentials expire (like session credentials from roles), there is no way to refresh them. CLI calls will start to fail if that happens. To fix this, instead of resolving providers to credentials, pass providers around instead. Implications for auth plugins ------------- This widens the plugin protocol: the new plugin protocol *forced* a translation to V3 credentials, and had no way to return V3 providers. While it is now possible to return V3 Credential Providers from the plugin protocol, plugin writers cannot easily take advantage of that protocol because there have been ~8 CLI releases that only support V3 credentials and will fail at runtime of V3 providers are returned. To support this, pass a new options argument into `getProvider()`: this will indicate whether V3 Providers are supported or not. Plugins can return a provider if the CLI indicates that it supports V3 providers, and avoid doing that if the CLI indicates it won't. That way, plugins can be rewritten to take advantage of returning V3 providers without crashing on CLI versions `2.167.0..(this releases)`. This also affects #32111 in which the plugin contract is being moved. Closes #32287. ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

…ntract

aws-cdk-automation · 2024-12-24T18:43:52Z

➡️ PR build request submitted to test-main-pipeline ⬅️

A maintainer must now check the pipeline and add the pr-linter/cli-integ-tested label once the pipeline succeeds.

…ntract

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

aws-cdk-automation · 2024-12-27T10:04:54Z

AWS CodeBuild CI Report

CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
Commit ID: 87de2e2
Result: SUCCEEDED
Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

mergify · 2024-12-27T10:09:47Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

github-actions · 2024-12-27T10:10:09Z

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.

otaviomacedo added 3 commits November 13, 2024 12:07

feat(cli-plugin-contract): introduce a public contract between CLI an…

797f920

…d plugins

README update

af8d279

Fixes

819ca45

aws-cdk-automation requested a review from a team November 13, 2024 14:20

github-actions bot added effort/medium Medium work item – several days of effort feature-request A feature should be added or improved. p2 labels Nov 13, 2024

mergify bot added the contribution/core This is a PR that came from AWS. label Nov 13, 2024

otaviomacedo temporarily deployed to test-pipeline November 13, 2024 14:21 — with GitHub Actions Inactive

aws-cdk-automation previously requested changes Nov 13, 2024

View reviewed changes

aws-cdk-automation added the pr/needs-cli-test-run This PR needs CLI tests run against it. label Nov 13, 2024

otaviomacedo added the pr-linter/exempt-integ-test The PR linter will not require integ test changes label Nov 13, 2024

yarn build && yarn test

54dac39

otaviomacedo had a problem deploying to test-pipeline November 13, 2024 14:32 — with GitHub Actions Failure

New test

d7b671a

otaviomacedo temporarily deployed to test-pipeline November 13, 2024 15:40 — with GitHub Actions Inactive

mrgrain reviewed Nov 13, 2024

View reviewed changes

const enum

16d3d4d

otaviomacedo had a problem deploying to test-pipeline November 15, 2024 15:53 — with GitHub Actions Failure

otaviomacedo added 2 commits November 25, 2024 10:37

Revert "const enum"

3aa719b

This reverts commit 16d3d4d.

More details on getPromise()

2dad460

otaviomacedo had a problem deploying to test-pipeline November 25, 2024 10:44 — with GitHub Actions Failure

Add expiration field.

ddd6733

otaviomacedo had a problem deploying to test-pipeline November 25, 2024 11:18 — with GitHub Actions Failure

Formatting

390e99f

otaviomacedo had a problem deploying to test-pipeline November 25, 2024 11:21 — with GitHub Actions Failure

otaviomacedo commented Nov 25, 2024

View reviewed changes

otaviomacedo marked this pull request as ready for review November 25, 2024 11:29

otaviomacedo requested a review from a team as a code owner November 25, 2024 11:29

github-actions bot mentioned this pull request Dec 1, 2024

Monthly PR metrics report #32340

Open

rix0rrr mentioned this pull request Dec 2, 2024

fix(cli): short-lived credentials are not refreshed #32354

Merged

Merge remote-tracking branch 'origin/main' into otaviom/cli-plugin-co…

e250b6c

…ntract

rix0rrr requested a deployment to test-pipeline December 24, 2024 13:32 — with GitHub Actions Waiting

rix0rrr added 2 commits December 24, 2024 15:38

Redo mode to be type-only

d7eda00

Make plugin contract import type

d96bcfa

rix0rrr requested a deployment to test-pipeline December 24, 2024 14:40 — with GitHub Actions Waiting

Fix linter errors

398905e

rix0rrr requested a deployment to test-pipeline December 24, 2024 15:26 — with GitHub Actions Waiting

Remove peerDependency, this is really dev-only

6d2c547

rix0rrr temporarily deployed to test-pipeline December 24, 2024 15:34 — with GitHub Actions Inactive

Update test

b919b96

rix0rrr temporarily deployed to test-pipeline December 24, 2024 18:42 — with GitHub Actions Inactive

rix0rrr added the pr-linter/cli-integ-tested Assert that any CLI changes have been integ tested label Dec 27, 2024

Merge remote-tracking branch 'origin/main' into otaviom/cli-plugin-co…

87de2e2

…ntract

aws-cdk-automation removed the pr/needs-cli-test-run This PR needs CLI tests run against it. label Dec 27, 2024

rix0rrr requested a deployment to test-pipeline December 27, 2024 09:35 — with GitHub Actions Waiting

github-actions bot added p1 and removed p2 labels Dec 27, 2024

rix0rrr approved these changes Dec 27, 2024

View reviewed changes

mergify bot merged commit fbaab1d into main Dec 27, 2024
25 of 26 checks passed

mergify bot deleted the otaviom/cli-plugin-contract branch December 27, 2024 10:09

github-actions bot locked as resolved and limited conversation to collaborators Dec 27, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(cli-plugin-contract): introduce a public contract between CLI and plugins #32111

feat(cli-plugin-contract): introduce a public contract between CLI and plugins #32111

otaviomacedo commented Nov 13, 2024 •

edited by rix0rrr

Loading

aws-cdk-automation left a comment

codecov bot commented Nov 13, 2024 •

edited

Loading

mrgrain Nov 13, 2024 •

edited

Loading

otaviomacedo Nov 13, 2024

rix0rrr Nov 25, 2024

otaviomacedo Nov 25, 2024

rix0rrr Nov 25, 2024

otaviomacedo Nov 25, 2024

otaviomacedo Nov 25, 2024

rix0rrr Nov 25, 2024

otaviomacedo Nov 25, 2024

aws-cdk-automation commented Dec 24, 2024

aws-cdk-automation commented Dec 27, 2024

mergify bot commented Dec 27, 2024

github-actions bot commented Dec 27, 2024

	getProvider(accountId: string, mode: Mode): Promise<AwsCredentials>;
	getProvider(accountId: string, mode: 'ForReading' \| 'ForWriting'): Promise<AwsCredentials>;

feat(cli-plugin-contract): introduce a public contract between CLI and plugins #32111

feat(cli-plugin-contract): introduce a public contract between CLI and plugins #32111

Conversation

otaviomacedo commented Nov 13, 2024 • edited by rix0rrr Loading

Checklist

aws-cdk-automation left a comment

Choose a reason for hiding this comment

codecov bot commented Nov 13, 2024 • edited Loading

Codecov Report

mrgrain Nov 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aws-cdk-automation commented Dec 24, 2024

aws-cdk-automation commented Dec 27, 2024

AWS CodeBuild CI Report

mergify bot commented Dec 27, 2024

github-actions bot commented Dec 27, 2024

otaviomacedo commented Nov 13, 2024 •

edited by rix0rrr

Loading

codecov bot commented Nov 13, 2024 •

edited

Loading

mrgrain Nov 13, 2024 •

edited

Loading