Adds package documentation, examples for retry package. Update aws.Co…

…nfig#Retryer to be a provider. (#1033)

* Add retry package documentation and examples. Refactor interface usage.
* Update imds and endpoint client to use aws.Retryer interface.
* Update codegen clients to use aws.Retryer interface.
* Change aws.Config#Retryer to be a value provider.
* Codegen changes for aws.Config#Retryer changes

.changes/next-release/config-feature-1610496608654196000.json

@@ -0,0 +1,9 @@
+{
+ "ID": "config-feature-1610496608654196000",
+ "SchemaVersion": 1,
+ "Module": "config",
+ "Type": "feature",
+ "Description": "Breaking Change: WithRetryer and LoadOptions has been updated to make Retryer a provider function",
+ "MinVersion": "",
+ "AffectedModules": null
+}

.changes/next-release/credentials-feature-1610496796301711000.json

@@ -0,0 +1,9 @@
+{
+ "ID": "credentials-feature-1610496796301711000",
+ "SchemaVersion": 1,
+ "Module": "credentials",
+ "Type": "feature",
+ "Description": "endpointcreds Options Retryer member has been updated to be type aws.Retryer",
+ "MinVersion": "",
+ "AffectedModules": null
+}

.changes/next-release/feature.ec2.imds-feature-1610496712636622000.json

@@ -0,0 +1,9 @@
+{
+ "ID": "feature.ec2.imds-feature-1610496712636622000",
+ "SchemaVersion": 1,
+ "Module": "feature/ec2/imds",
+ "Type": "feature",
+ "Description": "IMDS Client has been updated to utilize the Retryer provider function from aws.Config",
+ "MinVersion": "",
+ "AffectedModules": null
+}

.changes/next-release/service.wildcard-feature-1610496371066060000.json

@@ -0,0 +1,260 @@
+{
+ "ID": "service.wildcard-feature-1610496371066060000",
+ "SchemaVersion": 1,
+ "Module": "service/...",
+ "Type": "feature",
+ "Description": "Breaking Change: The Options Retryer memeber has been updated to be type aws.Retryer",
+ "MinVersion": "",
+ "AffectedModules": [
+  "service/accessanalyzer",
+  "service/acm",
+  "service/acmpca",
+  "service/alexaforbusiness",
+  "service/amplify",
+  "service/apigateway",
+  "service/apigatewaymanagementapi",
+  "service/apigatewayv2",
+  "service/appconfig",
+  "service/appflow",
+  "service/appintegrations",
+  "service/applicationautoscaling",
+  "service/applicationdiscoveryservice",
+  "service/applicationinsights",
+  "service/appmesh",
+  "service/appstream",
+  "service/appsync",
+  "service/athena",
+  "service/auditmanager",
+  "service/autoscaling",
+  "service/autoscalingplans",
+  "service/backup",
+  "service/batch",
+  "service/braket",
+  "service/budgets",
+  "service/chime",
+  "service/cloud9",
+  "service/clouddirectory",
+  "service/cloudformation",
+  "service/cloudfront",
+  "service/cloudhsm",
+  "service/cloudhsmv2",
+  "service/cloudsearch",
+  "service/cloudsearchdomain",
+  "service/cloudtrail",
+  "service/cloudwatch",
+  "service/cloudwatchevents",
+  "service/cloudwatchlogs",
+  "service/codeartifact",
+  "service/codebuild",
+  "service/codecommit",
+  "service/codedeploy",
+  "service/codeguruprofiler",
+  "service/codegurureviewer",
+  "service/codepipeline",
+  "service/codestar",
+  "service/codestarconnections",
+  "service/codestarnotifications",
+  "service/cognitoidentity",
+  "service/cognitoidentityprovider",
+  "service/cognitosync",
+  "service/comprehend",
+  "service/comprehendmedical",
+  "service/computeoptimizer",
+  "service/configservice",
+  "service/connect",
+  "service/connectcontactlens",
+  "service/connectparticipant",
+  "service/costandusagereportservice",
+  "service/costexplorer",
+  "service/customerprofiles",
+  "service/databasemigrationservice",
+  "service/databrew",
+  "service/dataexchange",
+  "service/datapipeline",
+  "service/datasync",
+  "service/dax",
+  "service/detective",
+  "service/devicefarm",
+  "service/devopsguru",
+  "service/directconnect",
+  "service/directoryservice",
+  "service/dlm",
+  "service/docdb",
+  "service/dynamodb",
+  "service/dynamodbstreams",
+  "service/ebs",
+  "service/ec2",
+  "service/ec2instanceconnect",
+  "service/ecr",
+  "service/ecrpublic",
+  "service/ecs",
+  "service/efs",
+  "service/eks",
+  "service/elasticache",
+  "service/elasticbeanstalk",
+  "service/elasticinference",
+  "service/elasticloadbalancing",
+  "service/elasticloadbalancingv2",
+  "service/elasticsearchservice",
+  "service/elastictranscoder",
+  "service/emr",
+  "service/emrcontainers",
+  "service/eventbridge",
+  "service/firehose",
+  "service/fms",
+  "service/forecast",
+  "service/forecastquery",
+  "service/frauddetector",
+  "service/fsx",
+  "service/gamelift",
+  "service/glacier",
+  "service/globalaccelerator",
+  "service/glue",
+  "service/greengrass",
+  "service/greengrassv2",
+  "service/groundstation",
+  "service/guardduty",
+  "service/health",
+  "service/healthlake",
+  "service/honeycode",
+  "service/iam",
+  "service/identitystore",
+  "service/imagebuilder",
+  "service/inspector",
+  "service/iot",
+  "service/iot1clickdevicesservice",
+  "service/iot1clickprojects",
+  "service/iotanalytics",
+  "service/iotdataplane",
+  "service/iotdeviceadvisor",
+  "service/iotevents",
+  "service/ioteventsdata",
+  "service/iotfleethub",
+  "service/iotjobsdataplane",
+  "service/iotsecuretunneling",
+  "service/iotsitewise",
+  "service/iotthingsgraph",
+  "service/iotwireless",
+  "service/ivs",
+  "service/kafka",
+  "service/kendra",
+  "service/kinesis",
+  "service/kinesisanalytics",
+  "service/kinesisanalyticsv2",
+  "service/kinesisvideo",
+  "service/kinesisvideoarchivedmedia",
+  "service/kinesisvideomedia",
+  "service/kinesisvideosignaling",
+  "service/kms",
+  "service/lakeformation",
+  "service/lambda",
+  "service/lexmodelbuildingservice",
+  "service/lexruntimeservice",
+  "service/licensemanager",
+  "service/lightsail",
+  "service/lookoutvision",
+  "service/machinelearning",
+  "service/macie",
+  "service/macie2",
+  "service/managedblockchain",
+  "service/marketplacecatalog",
+  "service/marketplacecommerceanalytics",
+  "service/marketplaceentitlementservice",
+  "service/marketplacemetering",
+  "service/mediaconnect",
+  "service/mediaconvert",
+  "service/medialive",
+  "service/mediapackage",
+  "service/mediapackagevod",
+  "service/mediastore",
+  "service/mediastoredata",
+  "service/mediatailor",
+  "service/migrationhub",
+  "service/migrationhubconfig",
+  "service/mobile",
+  "service/mq",
+  "service/mturk",
+  "service/neptune",
+  "service/networkfirewall",
+  "service/networkmanager",
+  "service/opsworks",
+  "service/opsworkscm",
+  "service/organizations",
+  "service/outposts",
+  "service/personalize",
+  "service/personalizeevents",
+  "service/personalizeruntime",
+  "service/pi",
+  "service/pinpoint",
+  "service/pinpointemail",
+  "service/pinpointsmsvoice",
+  "service/polly",
+  "service/pricing",
+  "service/qldb",
+  "service/qldbsession",
+  "service/quicksight",
+  "service/ram",
+  "service/rds",
+  "service/rdsdata",
+  "service/redshift",
+  "service/redshiftdata",
+  "service/rekognition",
+  "service/resourcegroups",
+  "service/resourcegroupstaggingapi",
+  "service/robomaker",
+  "service/route53",
+  "service/route53domains",
+  "service/route53resolver",
+  "service/s3",
+  "service/s3control",
+  "service/s3outposts",
+  "service/sagemaker",
+  "service/sagemakera2iruntime",
+  "service/sagemakeredge",
+  "service/sagemakerfeaturestoreruntime",
+  "service/sagemakerruntime",
+  "service/savingsplans",
+  "service/schemas",
+  "service/secretsmanager",
+  "service/securityhub",
+  "service/serverlessapplicationrepository",
+  "service/servicecatalog",
+  "service/servicecatalogappregistry",
+  "service/servicediscovery",
+  "service/servicequotas",
+  "service/ses",
+  "service/sesv2",
+  "service/sfn",
+  "service/shield",
+  "service/signer",
+  "service/sms",
+  "service/snowball",
+  "service/sns",
+  "service/sqs",
+  "service/ssm",
+  "service/sso",
+  "service/ssoadmin",
+  "service/ssooidc",
+  "service/storagegateway",
+  "service/sts",
+  "service/support",
+  "service/swf",
+  "service/synthetics",
+  "service/textract",
+  "service/timestreamquery",
+  "service/timestreamwrite",
+  "service/transcribe",
+  "service/transfer",
+  "service/translate",
+  "service/waf",
+  "service/wafregional",
+  "service/wafv2",
+  "service/wellarchitected",
+  "service/workdocs",
+  "service/worklink",
+  "service/workmail",
+  "service/workmailmessageflow",
+  "service/workspaces",
+  "service/xray"
+ ]
+}

aws/config.go

@@ -42,10 +42,15 @@ type Config struct {
 	// service and region Please see the `aws.EndpointResolver` documentation on usage.
 	EndpointResolver EndpointResolver
 
-	// Retryer guides how HTTP requests should be retried in case of
-	// recoverable failures. When nil the API client will use a default
+	// Retryer is a function that provides a Retryer implementation. A Retryer guides how HTTP requests should be
+	// retried in case of recoverable failures. When nil the API client will use a default
 	// retryer.
-	Retryer Retryer
+	//
+	// In general, the provider function should return a new instance of a Retyer if you are attempting
+	// to provide a consistent Retryer configuration across all clients. This will ensure that each client will be
+	// provided a new instance of the Retryer implementation, and will avoid issues such as sharing the same retry token
+	// bucket across services.
+	Retryer func() Retryer
 
 	// ConfigSources are the sources that were used to construct the Config.
 	// Allows for additional configuration to be loaded by clients.

aws/retry/doc.go

@@ -0,0 +1,80 @@
+// Package retry provides interfaces and implementations for SDK request retry behavior.
+//
+// Retryer Interface and Implementations
+//
+// This packages defines Retryer interface that is used to either implement custom retry behavior
+// or to extend the existing retry implementations provided by the SDK. This packages provides a single
+// retry implementations: Standard.
+//
+// Standard
+//
+// Standard is the default retryer implementation used by service clients. The standard retryer is a rate limited
+// retryer that has a configurable max attempts to limit the number of retry attempts when a retryable error occurs.
+// In addition, the retryer uses a configurable token bucket to rate limit the retry attempts across the client,
+// and uses an additional delay policy to limit the time between a requests subsequent attempts.
+//
+// By default the standard retryer uses the DefaultRetryables slice of IsErrorRetryable types to determine whether
+// a given error is retryable. By default this list of retryables includes the following:
+//  - Retrying errors that implement the RetryableError method, and return true.
+//  - Connection Errors
+//    - Errors that implement a ConnectionError, Temporary, or Timeout method that return true.
+//    - Connection Reset Errors.
+//    - net.OpErr types that are dialing errors or are temporary.
+//    - HTTP Status Codes: 500, 502, 503, and 504.
+//  - API Error Codes
+//    - RequestTimeout, RequestTimeoutException
+//    - Throttling, ThrottlingException, ThrottledException, RequestThrottledException, TooManyRequestsException,
+//      RequestThrottled, SlowDown, EC2ThrottledException
+//    - ProvisionedThroughputExceededException, RequestLimitExceeded, BandwidthLimitExceeded, LimitExceededException
+//    - TransactionInProgressException, PriorRequestNotComplete
+//
+// The standard retryer will not retry a request in the event if the context associated with the request
+// has been cancelled. Applications must handle this case explicitly if they wish to retry with a different context
+// value.
+//
+// You can configure the standard retryer implementation to fit your applications by constructing a standard retryer
+// using the NewStandard function, and providing one more functional arguments that mutate the StandardOptions
+// structure. StandardOptions provides the ability to modify the token bucket rate limiter, retryable error conditions,
+// and the retry delay policy.
+//
+// For example to modify the default retry attempts for the standard retryer:
+//
+//  // configure the custom retryer
+//  customRetry := retry.NewStandard(func(o *retry.StandardOptions) {
+//      o.MaxAttempts = 5
+//  })
+//
+//  // create a service client with the retryer
+//  s3.NewFromConfig(cfg, func(o *s3.Options) {
+//      o.Retryer = customRetry
+//  })
+//
+// Utilities
+//
+// A number of package functions have been provided to easily wrap retryer implementations in an implementation agnostic
+// way. These are:
+//
+//   AddWithErrorCodes      - Provides the ability to add additional API error codes that should be considered retryable
+//                           in addition to those considered retryable by the provided retryer.
+//
+//   AddWithMaxAttempts     - Provides the ability to set the max number of attempts for retrying a request by wrapping
+//                            a retryer implementation.
+//
+//   AddWithMaxBackoffDelay - Provides the ability to set the max back off delay that can occur before retrying a
+//                            request by wrapping a retryer implementation.
+//
+// The following package functions have been provided to easily satisfy different retry interfaces to further customize
+// a given retryer's behavior:
+//
+//   BackoffDelayerFunc   - Can be used to wrap a function to satisfy the BackoffDelayer interface. For example,
+//                          you can use this method to easily create custom back off policies to be used with the
+//                          standard retryer.
+//
+//   IsErrorRetryableFunc - Can be used to wrap a function to satisfy the IsErrorRetryable interface. For example,
+//                          this can be used to extend the standard retryer to add additional logic ot determine if a
+//                          error should be retried.
+//
+//   IsErrorTimeoutFunc   - Can be used to wrap a function to satisfy IsErrorTimeout interface. For example,
+//                          this can be used to extend the standard retryer to add additional logic to determine if an
+//                           error should be considered a timeout.
+package retry