actionwait: add polling library for actions #44465

YakDriver · 2025-09-26T04:01:13Z

Rollback Plan

If a change needs to be reverted, we will publish an updated version of the library.

Changes to Security Controls

Are there any changes to security controls (access controls, encryption, logging) in this pull request? If so, explain.

Description

Introduces a new internal actionwait package: a lightweight, action-focused polling helper tailored for asynchronous AWS operation actions (e.g., EC2 stop, CloudFront invalidation, CodeBuild build) where we need deterministic status progression tracking and periodic user-facing progress updates without the heavier resource lifecycle semantics of retry.StateChangeConf.

It provides a clear state taxonomy (success, transitional, failure, unexpected), pluggable interval strategies including fixed intervals and backoff integration via a bridge adapter to internal/backoff for sophisticated delay algorithms, throttled progress callbacks decoupled from poll cadence, typed errors (TimeoutError, FailureStateError, UnexpectedStateError) with dedicated helper functions for error type checking, and optional typed payloads via generics to return rich SDK objects without wrappers.

The package is organized into separate files (wait.go for core logic, errors.go for error types and helpers) for better maintainability. This refactor reduces duplicated bespoke loops (deadline math, sleep, transitional guards), improves safety by uniformly surfacing unexpected states, provides flexible polling strategies (fixed for predictable operations like EC2 instance transitions, backoff for variable-duration operations like CodeBuild), and future‑proofs consecutive success handling.

Comprehensive unit tests cover validation, success after transitions, failures, unexpected states, timeout, context cancel, fetch errors, progress throttling, consecutive success logic, and backoff adapter integration, ensuring behavior is well specified and stable for current and upcoming action implementations.

Relations

References

Output from Acceptance Testing

% go test ./internal/actionwait         
ok  	github.com/hashicorp/terraform-provider-aws/internal/actionwait	0.235s
% make t T=TestAccCloudFrontCreateInvalidationAction_basic K=cloudfront    
make: Verifying source code with gofmt...
==> Checking that code complies with gofmt requirements...
make: Running acceptance tests on branch: 🌿 f-polling-library-for-actions 🌿...
TF_ACC=1 go1.24.6 test ./internal/service/cloudfront/... -v -count 1 -parallel 20 -run='TestAccCloudFrontCreateInvalidationAction_basic'  -timeout 360m -vet=off
2025/09/25 20:54:37 Creating Terraform AWS Provider (SDKv2-style)...
2025/09/25 20:54:37 Initializing Terraform AWS Provider (SDKv2-style)...
=== RUN   TestAccCloudFrontCreateInvalidationAction_basic
=== PAUSE TestAccCloudFrontCreateInvalidationAction_basic
=== CONT  TestAccCloudFrontCreateInvalidationAction_basic
--- PASS: TestAccCloudFrontCreateInvalidationAction_basic (467.02s)
PASS
ok  	github.com/hashicorp/terraform-provider-aws/internal/service/cloudfront	472.441s
% make t T=TestAccCodeBuildStartBuildAction_basic K=codebuild       
make: Verifying source code with gofmt...
==> Checking that code complies with gofmt requirements...
make: Running acceptance tests on branch: 🌿 f-polling-library-for-actions 🌿...
TF_ACC=1 go1.24.6 test ./internal/service/codebuild/... -v -count 1 -parallel 20 -run='TestAccCodeBuildStartBuildAction_basic'  -timeout 360m -vet=off
2025/09/25 20:51:07 Creating Terraform AWS Provider (SDKv2-style)...
2025/09/25 20:51:07 Initializing Terraform AWS Provider (SDKv2-style)...
=== RUN   TestAccCodeBuildStartBuildAction_basic
=== PAUSE TestAccCodeBuildStartBuildAction_basic
=== CONT  TestAccCodeBuildStartBuildAction_basic
--- PASS: TestAccCodeBuildStartBuildAction_basic (68.17s)
PASS
ok  	github.com/hashicorp/terraform-provider-aws/internal/service/codebuild	73.697s
% make t T=TestAccEC2StopInstanceAction_basic K=ec2          
make: Verifying source code with gofmt...
==> Checking that code complies with gofmt requirements...
make: Running acceptance tests on branch: 🌿 f-polling-library-for-actions 🌿...
TF_ACC=1 go1.24.6 test ./internal/service/ec2/... -v -count 1 -parallel 20 -run='TestAccEC2StopInstanceAction_basic'  -timeout 360m -vet=off
2025/09/25 20:57:18 Creating Terraform AWS Provider (SDKv2-style)...
2025/09/25 20:57:18 Initializing Terraform AWS Provider (SDKv2-style)...
=== RUN   TestAccEC2StopInstanceAction_basic
=== PAUSE TestAccEC2StopInstanceAction_basic
=== CONT  TestAccEC2StopInstanceAction_basic
    ec2_stop_instance_action_test.go:328: Progress: Starting stop operation for EC2 instance i-02812c4aac946f11e...
    ec2_stop_instance_action_test.go:328: Progress: Sending stop command to EC2 instance i-02812c4aac946f11e...
    ec2_stop_instance_action_test.go:328: Progress: Stop command sent to EC2 instance i-02812c4aac946f11e, waiting for instance to stop...
    ec2_stop_instance_action_test.go:328: Progress: EC2 instance i-02812c4aac946f11e is currently in state 'running', continuing to wait for 'stopped'...
    ec2_stop_instance_action_test.go:328: Progress: EC2 instance i-02812c4aac946f11e is currently in state 'stopping', continuing to wait for 'stopped'...
    ec2_stop_instance_action_test.go:328: Progress: EC2 instance i-02812c4aac946f11e is currently in state 'stopping', continuing to wait for 'stopped'...
    ec2_stop_instance_action_test.go:328: Progress: EC2 instance i-02812c4aac946f11e has been successfully stopped
--- PASS: TestAccEC2StopInstanceAction_basic (115.45s)
PASS
ok  	github.com/hashicorp/terraform-provider-aws/internal/service/ec2	120.987s

github-actions · 2025-09-26T04:01:28Z

Community Guidelines

This comment is added to every new Pull Request to provide quick reference to how the Terraform AWS Provider is maintained. Please review the information below, and thank you for contributing to the community that keeps the provider thriving! 🚀

Voting for Prioritization

Please vote on this Pull Request by adding a 👍 reaction to the original post to help the community and maintainers prioritize it.
Please see our prioritization guide for additional information on how the maintainers handle prioritization.
Please do not leave +1 or other comments that do not add relevant new information or questions; they generate extra noise for others following the Pull Request and do not help prioritize the request.

Pull Request Authors

Review the contribution guide relating to the type of change you are making to ensure all of the necessary steps have been taken.
Whether or not the branch has been rebased will not impact prioritization, but doing so is always a welcome surprise.

YakDriver · 2025-09-29T21:10:36Z

~~I'm thinking this could be genericized to reduce waiter boilerplate at the same time. That might be too much for one side project PR though.~~

YakDriver · 2025-09-30T21:49:44Z

Most recent:

% make t T=TestAccEC2StopInstanceAction_basic K=ec2
make: Verifying source code with gofmt...
==> Checking that code complies with gofmt requirements...
make: Running acceptance tests on branch: 🌿 f-polling-library-for-actions 🌿...
TF_ACC=1 go1.24.6 test ./internal/service/ec2/... -v -count 1 -parallel 20 -run='TestAccEC2StopInstanceAction_basic'  -timeout 360m -vet=off
2025/09/30 17:45:05 Creating Terraform AWS Provider (SDKv2-style)...
2025/09/30 17:45:05 Initializing Terraform AWS Provider (SDKv2-style)...
=== RUN   TestAccEC2StopInstanceAction_basic
=== PAUSE TestAccEC2StopInstanceAction_basic
=== CONT  TestAccEC2StopInstanceAction_basic
    ec2_stop_instance_action_test.go:328: Progress: Starting stop operation for EC2 instance i-04068524d01beb19b...
    ec2_stop_instance_action_test.go:328: Progress: Sending stop command to EC2 instance i-04068524d01beb19b...
    ec2_stop_instance_action_test.go:328: Progress: Stop command sent to EC2 instance i-04068524d01beb19b, waiting for instance to stop...
    ec2_stop_instance_action_test.go:328: Progress: EC2 instance i-04068524d01beb19b is currently in state 'running', continuing to wait for 'stopped'...
    ec2_stop_instance_action_test.go:328: Progress: EC2 instance i-04068524d01beb19b is currently in state 'stopping', continuing to wait for 'stopped'...
    ec2_stop_instance_action_test.go:328: Progress: EC2 instance i-04068524d01beb19b has been successfully stopped
--- PASS: TestAccEC2StopInstanceAction_basic (93.68s)
PASS
ok  	github.com/hashicorp/terraform-provider-aws/internal/service/ec2	99.190s
% make t T=TestAccCodeBuildStartBuildAction_ K=codebuild               
make: Verifying source code with gofmt...
==> Checking that code complies with gofmt requirements...
make: Running acceptance tests on branch: 🌿 f-polling-library-for-actions 🌿...
TF_ACC=1 go1.24.6 test ./internal/service/codebuild/... -v -count 1 -parallel 20 -run='TestAccCodeBuildStartBuildAction_'  -timeout 360m -vet=off
2025/09/30 17:16:16 Creating Terraform AWS Provider (SDKv2-style)...
2025/09/30 17:16:16 Initializing Terraform AWS Provider (SDKv2-style)...
=== RUN   TestAccCodeBuildStartBuildAction_basic
=== PAUSE TestAccCodeBuildStartBuildAction_basic
=== RUN   TestAccCodeBuildStartBuildAction_withEnvironmentVariables
=== PAUSE TestAccCodeBuildStartBuildAction_withEnvironmentVariables
=== CONT  TestAccCodeBuildStartBuildAction_basic
=== CONT  TestAccCodeBuildStartBuildAction_withEnvironmentVariables
--- PASS: TestAccCodeBuildStartBuildAction_withEnvironmentVariables (62.24s)
--- PASS: TestAccCodeBuildStartBuildAction_basic (62.26s)
PASS
ok  	github.com/hashicorp/terraform-provider-aws/internal/service/codebuild	67.772s
% make t T=TestAccCloudFrontCreateInvalidationAction_basic K=cloudfront
make: Verifying source code with gofmt...
==> Checking that code complies with gofmt requirements...
make: Running acceptance tests on branch: 🌿 f-polling-library-for-actions 🌿...
TF_ACC=1 go1.24.6 test ./internal/service/cloudfront/... -v -count 1 -parallel 20 -run='TestAccCloudFrontCreateInvalidationAction_basic'  -timeout 360m -vet=off
2025/09/30 16:57:24 Creating Terraform AWS Provider (SDKv2-style)...
2025/09/30 16:57:24 Initializing Terraform AWS Provider (SDKv2-style)...
=== RUN   TestAccCloudFrontCreateInvalidationAction_basic
=== PAUSE TestAccCloudFrontCreateInvalidationAction_basic
=== CONT  TestAccCloudFrontCreateInvalidationAction_basic
--- PASS: TestAccCloudFrontCreateInvalidationAction_basic (449.17s)
PASS
ok  	github.com/hashicorp/terraform-provider-aws/internal/service/cloudfront	454.859s

internal/actionwait/wait.go

ewbankkit

LGTM 🚀.

github-actions · 2025-10-03T19:43:54Z

Warning

This Issue has been closed, meaning that any additional comments are much easier for the maintainers to miss. Please assume that the maintainers will not see them.

Ongoing conversations amongst community members are welcome, however, the issue will be locked after 30 days. Moving conversations to another venue, such as the AWS Provider forum, is recommended. If you have additional concerns, please open a new issue, referencing this one where needed.

github-actions · 2025-10-09T18:48:54Z

This functionality has been released in v6.16.0 of the Terraform AWS Provider. Please see the Terraform documentation on provider versioning or reach out if you need any assistance upgrading.

For further feature requests or bug reports with this functionality, please create a new GitHub issue following the template. Thank you!

actionwait: add polling library for actions

5035e95

YakDriver requested a review from a team as a code owner September 26, 2025 04:01

YakDriver added 3 commits September 25, 2025 21:01

Update stop instance action to use actionwait

cf036b9

Update start build action to use actionwait

1a77068

Update create invalidation action to use actionwait

94cc263

github-actions bot added service/ec2 Issues and PRs that pertain to the ec2 service. service/codebuild Issues and PRs that pertain to the codebuild service. service/cloudfront Issues and PRs that pertain to the cloudfront service. labels Sep 26, 2025

Remove comments

15e8770

YakDriver mentioned this pull request Sep 26, 2025

New action: aws_transcribe_start_transcription_job #44445

Merged

YakDriver added 4 commits September 25, 2025 21:37

Linting

684dbb3

Modern

1596894

Service name in var

235adba

Stack/heap

b181b5b

YakDriver added the no-changelog-needed Indicates that a changelog entry is not necessary label Sep 26, 2025

make gen

76b288a

YakDriver mentioned this pull request Sep 29, 2025

New action: aws_events_put_events #44487

Merged

YakDriver added 3 commits September 30, 2025 16:56

Improve early returns

939bdf3

Fix tests

cd48e50

Modern errors

5cdef32

ewbankkit reviewed Oct 1, 2025

View reviewed changes

internal/actionwait/wait.go Outdated Show resolved Hide resolved

ewbankkit reviewed Oct 1, 2025

View reviewed changes

internal/actionwait/wait.go Show resolved Hide resolved

YakDriver added 2 commits October 2, 2025 18:11

Split errors from wait

6362445

Add backoff strategy

a70a78a

YakDriver added 2 commits October 2, 2025 18:28

Switch codebuild to backoff

1cac773

Remove explicit implementation check

a9c99d8

ewbankkit approved these changes Oct 3, 2025

View reviewed changes

YakDriver merged commit a73675d into main Oct 3, 2025
54 checks passed

YakDriver deleted the f-polling-library-for-actions branch October 3, 2025 19:43

github-actions bot added this to the v6.16.0 milestone Oct 3, 2025

github-actions bot removed the prioritized Part of the maintainer teams immediate focus. To be addressed within the current quarter. label Oct 9, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

actionwait: add polling library for actions #44465

actionwait: add polling library for actions #44465

Uh oh!

YakDriver commented Sep 26, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Sep 26, 2025

Uh oh!

YakDriver commented Sep 29, 2025 •

edited

Loading

Uh oh!

YakDriver commented Sep 30, 2025

Uh oh!

Uh oh!

Uh oh!

ewbankkit left a comment

Uh oh!

Uh oh!

github-actions bot commented Oct 3, 2025

Uh oh!

github-actions bot commented Oct 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

actionwait: add polling library for actions #44465

actionwait: add polling library for actions #44465

Uh oh!

Conversation

YakDriver commented Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rollback Plan

Changes to Security Controls

Description

Relations

References

Output from Acceptance Testing

Uh oh!

github-actions bot commented Sep 26, 2025

Community Guidelines

Voting for Prioritization

Pull Request Authors

Uh oh!

YakDriver commented Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

YakDriver commented Sep 30, 2025

Uh oh!

Uh oh!

Uh oh!

ewbankkit left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Oct 3, 2025

Uh oh!

github-actions bot commented Oct 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

YakDriver commented Sep 26, 2025 •

edited

Loading

YakDriver commented Sep 29, 2025 •

edited

Loading