Merge branch 'main' into james/oss-3397-ssh-file-handle-leaks

Author: james00012

README.md

@@ -22,7 +22,23 @@ variety of helper functions and patterns for common infrastructure testing tasks
 - Running shell commands
 - And much more
 
-Please see the following for more info:
+## Install
+
+```bash
+go get github.com/gruntwork-io/terratest@latest
+```
+
+Requires Go 1.26 or later.
+
+## Stability and versioning
+
+Starting with v1.0.0, Terratest follows [semantic versioning](https://semver.org/). Breaking changes to the public API
+only happen in major releases (e.g. v2.0.0).
+
+Symbols renamed or replaced in v1 are kept with `// Deprecated:` annotations pointing at the new name; removals happen
+in v2. Migrating from v0.x: see [`MIGRATION.md`](./MIGRATION.md).
+
+## More info
 
 - [Terratest Website](https://terratest.gruntwork.io)
 - [Getting started with Terratest](https://terratest.gruntwork.io/docs/getting-started/quick-start/)

go.mod

@@ -99,6 +99,7 @@ require (
 	github.com/lib/pq v1.10.9
 	github.com/microsoft/go-mssqldb v1.9.8
 	github.com/slack-go/slack v0.15.0
+	golang.org/x/sync v0.20.0
 	google.golang.org/grpc v1.80.0
 	gopkg.in/yaml.v3 v3.0.1
 	gotest.tools/v3 v3.5.2
@@ -223,7 +224,6 @@ require (
 	go.yaml.in/yaml/v2 v2.4.3 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/mod v0.33.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
 	golang.org/x/sys v0.42.0 // indirect
 	golang.org/x/term v0.41.0 // indirect
 	golang.org/x/text v0.35.0 // indirect

modules/aws/account.go

@@ -59,13 +59,17 @@ func GetAccountIDE(t testing.TestingT) (string, error) {
 	return GetAccountIDContextE(t, context.Background())
 }
 
+// GetAccountId gets the Account ID for the currently logged in IAM User.
+//
 // Deprecated: Use [GetAccountID] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name
 func GetAccountId(t testing.TestingT) string {
 	return GetAccountID(t)
 }
 
+// GetAccountIdE gets the Account ID for the currently logged in IAM User.
+//
 // Deprecated: Use [GetAccountIDE] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name

modules/aws/ami.go

@@ -209,13 +209,19 @@ func GetMostRecentAmiIDE(t testing.TestingT, region string, ownerID string, filt
 	return GetMostRecentAmiIDContextE(t, context.Background(), region, ownerID, filters)
 }
 
+// GetMostRecentAmiId gets the ID of the most recent AMI in the given region that has the given owner and matches
+// the given filters.
+//
 // Deprecated: Use [GetMostRecentAmiID] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name
 func GetMostRecentAmiId(t testing.TestingT, region string, ownerId string, filters map[string][]string) string {
 	return GetMostRecentAmiID(t, region, ownerId, filters)
 }
 
+// GetMostRecentAmiIdE gets the ID of the most recent AMI in the given region that has the given owner and matches
+// the given filters.
+//
 // Deprecated: Use [GetMostRecentAmiIDE] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name

modules/aws/auth.go

@@ -17,7 +17,9 @@ import (
 )
 
 const (
-	AuthAssumeRoleEnvVar = "TERRATEST_IAM_ROLE" // OS environment variable name through which Assume Role ARN may be passed for authentication
+	// AuthAssumeRoleEnvVar is the OS environment variable name through which an
+	// Assume Role ARN may be passed for authentication.
+	AuthAssumeRoleEnvVar = "TERRATEST_IAM_ROLE"
 )
 
 // NewAuthenticatedSessionContext creates an AWS Config following to standard AWS authentication workflow.

modules/aws/dynamodb.go

@@ -74,6 +74,8 @@ func GetDynamoDBTableTagsE(t testing.TestingT, region string, tableName string)
 	return GetDynamoDBTableTagsContextE(t, context.Background(), region, tableName)
 }
 
+// GetDynamoDbTableTags fetches resource tags of a specified dynamoDB table. This will fail the test if there are any errors.
+//
 // Deprecated: Use [GetDynamoDBTableTagsContext] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name
@@ -82,6 +84,8 @@ func GetDynamoDbTableTags(t testing.TestingT, region string, tableName string) [
 	return GetDynamoDBTableTagsContext(t, context.Background(), region, tableName)
 }
 
+// GetDynamoDbTableTagsE fetches resource tags of a specified dynamoDB table.
+//
 // Deprecated: Use [GetDynamoDBTableTagsContextE] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name

modules/aws/ec2-files.go

@@ -394,6 +394,10 @@ func FetchFilesFromAsgsPE(t testing.TestingT, awsRegion string, spec *RemoteFile
 	return FetchFilesFromAsgsPContextE(t, context.Background(), awsRegion, spec)
 }
 
+// FetchFilesFromAsgs looks up the EC2 Instances in all the ASGs given in the
+// RemoteFileSpecification, downloads the matching files from each instance,
+// and stores them locally as described in [FetchFilesFromAsgsPContext].
+//
 // Deprecated: Use [FetchFilesFromAsgsPContext] instead.
 //
 //nolint:staticcheck,revive,gocritic // preserving deprecated function name
@@ -403,6 +407,8 @@ func FetchFilesFromAsgs(t testing.TestingT, awsRegion string, spec RemoteFileSpe
 	FetchFilesFromAsgsPContext(t, context.Background(), awsRegion, &spec)
 }
 
+// FetchFilesFromAsgsE is the error-returning equivalent of [FetchFilesFromAsgs].
+//
 // Deprecated: Use [FetchFilesFromAsgsPContextE] instead.
 //
 //nolint:staticcheck,revive,gocritic // preserving deprecated function name

modules/aws/errors.go

@@ -5,6 +5,8 @@ import (
 )
 
 // IpForEc2InstanceNotFound is an error that occurs when the IP for an EC2 instance is not found.
+//
+// Deprecated: Use [IPForEc2InstanceNotFound] instead.
 type IpForEc2InstanceNotFound struct { //nolint:staticcheck,revive // preserving deprecated type name
 	InstanceId string //nolint:staticcheck,revive // preserving existing field name
 	AwsRegion  string
@@ -40,6 +42,7 @@ func (err NotFoundError) Error() string {
 	return fmt.Sprintf("Object of type %s with id %s not found in region %s", err.objectType, err.objectID, err.region)
 }
 
+// NewNotFoundError returns a [NotFoundError] for the given object type, ID, and region.
 func NewNotFoundError(objectType string, objectID string, region string) NotFoundError {
 	return NotFoundError{objectType, objectID, region}
 }
@@ -60,6 +63,8 @@ func (err AsgCapacityNotMetError) Error() string {
 	)
 }
 
+// NewAsgCapacityNotMetError returns an [AsgCapacityNotMetError] describing
+// the given ASG's desired and current capacities.
 func NewAsgCapacityNotMetError(asgName string, desiredCapacity int64, currentCapacity int64) AsgCapacityNotMetError {
 	return AsgCapacityNotMetError{asgName, desiredCapacity, currentCapacity}
 }
@@ -80,6 +85,8 @@ func (err BucketVersioningNotEnabledError) Error() string {
 	)
 }
 
+// NewBucketVersioningNotEnabledError returns a [BucketVersioningNotEnabledError]
+// for the given S3 bucket, region, and observed versioning status.
 func NewBucketVersioningNotEnabledError(s3BucketName string, awsRegion string, versioningStatus string) BucketVersioningNotEnabledError {
 	return BucketVersioningNotEnabledError{s3BucketName: s3BucketName, awsRegion: awsRegion, versioningStatus: versioningStatus}
 }
@@ -99,6 +106,8 @@ func (err NoBucketPolicyError) Error() string {
 	)
 }
 
+// NewNoBucketPolicyError returns a [NoBucketPolicyError] for the given S3
+// bucket, region, and bucket policy.
 func NewNoBucketPolicyError(s3BucketName string, awsRegion string, bucketPolicy string) NoBucketPolicyError {
 	return NoBucketPolicyError{s3BucketName: s3BucketName, awsRegion: awsRegion, bucketPolicy: bucketPolicy}
 }

modules/aws/lambda.go

@@ -12,13 +12,24 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+// InvocationTypeOption identifies the invocation mode passed to AWS Lambda
+// when calling [InvokeFunctionWithParamsContextE]. See the
+// InvocationType-prefixed constants for the supported values.
 type InvocationTypeOption string
 
+// Supported [InvocationTypeOption] values for Lambda invocation modes.
 const (
+	// InvocationTypeRequestResponse invokes the function synchronously, keeping
+	// the connection open until the function returns a response or times out.
 	InvocationTypeRequestResponse InvocationTypeOption = "RequestResponse"
-	InvocationTypeDryRun          InvocationTypeOption = "DryRun"
+	// InvocationTypeDryRun validates parameter values and verifies that the user
+	// or role has permission to invoke the function, without actually invoking it.
+	InvocationTypeDryRun InvocationTypeOption = "DryRun"
 )
 
+// Value returns the string form of the [InvocationTypeOption], defaulting to
+// [InvocationTypeRequestResponse] when itype is nil. It returns an error if
+// itype is set to a value that is not one of the supported invocation types.
 func (itype *InvocationTypeOption) Value() (string, error) {
 	if itype != nil {
 		switch *itype {
@@ -212,6 +223,9 @@ func InvokeFunctionWithParamsE(t testing.TestingT, region, functionName string,
 	return InvokeFunctionWithParamsContextE(t, context.Background(), region, functionName, input)
 }
 
+// FunctionError is returned when an AWS Lambda invocation reports a function
+// error in its response. It carries the error message, the HTTP status code,
+// and the raw payload returned by the function.
 type FunctionError struct {
 	Message    string
 	Payload    []byte

modules/aws/rds.go

@@ -698,6 +698,8 @@ func GetValidEngineVersionE(t testing.TestingT, region string, engine string, ma
 
 // ParameterForDbInstanceNotFound is an error that occurs when the parameter group specified is not found for the DB instance.
 //
+// Deprecated: Use [ParameterForDBInstanceNotFound] instead.
+//
 //nolint:staticcheck,revive // preserving existing type name
 type ParameterForDbInstanceNotFound struct {
 	ParameterName string
@@ -714,6 +716,8 @@ func (err ParameterForDbInstanceNotFound) Error() string {
 
 // OptionGroupOptionSettingForDbInstanceNotFound is an error that occurs when the option setting specified is not found in the option group of the DB instance.
 //
+// Deprecated: Use [OptionGroupOptionSettingForDBInstanceNotFound] instead.
+//
 //nolint:staticcheck,revive // preserving existing type name
 type OptionGroupOptionSettingForDbInstanceNotFound struct {
 	OptionName        string