The AWS SDK for Go V2 introduces a new client-side rate-limiting mechanism +in the standard retry policy to align with the behavior of modern SDKs. This is +behavior is controlled by the RateLimiter +field on a retryer’s options.
+A RateLimiter operates as a token bucket with a set capacity, where operation +attempt failures consume tokens. A retry that attempts to consume more tokens +than what’s available results in operation failure with a +QuotaExceededError.
+The default implementation is parameterized as follows (how to modify each setting):
+If you find that the default behavior does not fit your application’s needs, +you can disable it with ratelimit.None.
+import (
+ "context"
+
+ "github.com/aws/aws-sdk-go-v2/aws"
+ "github.com/aws/aws-sdk-go-v2/aws/ratelimit"
+ "github.com/aws/aws-sdk-go-v2/aws/retry"
+ "github.com/aws/aws-sdk-go-v2/config"
+)
+
+// ...
+
+cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer {
+ return retry.NewStandard(func(o *retry.StandardOptions) {
+ // Makes the rate limiter more permissive in general. These values are
+ // arbitrary for demonstration and may not suit your specific
+ // application's needs.
+ o.RateLimiter = ratelimit.NewTokenRateLimit(1000)
+ o.RetryCost = 1
+ o.RetryTimeoutCost = 3
+ o.NoRetryIncrement = 10
+ })
+}))
+import (
+ "context"
+
+ "github.com/aws/aws-sdk-go-v2/aws"
+ "github.com/aws/aws-sdk-go-v2/aws/ratelimit"
+ "github.com/aws/aws-sdk-go-v2/aws/retry"
+ "github.com/aws/aws-sdk-go-v2/config"
+)
+
+// ...
+
+cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer {
+ return retry.NewStandard(func(o *retry.StandardOptions) {
+ o.RateLimiter = ratelimit.None
+ })
+}))
You use the context package to set timeouts or deadlines when invoking a service client operation. Use the context.WithDeadline to wrap your applications diff --git a/docs/docs/faq/index.html b/docs/docs/faq/index.html index d1bf747ef3f..74b6fbda739 100644 --- a/docs/docs/faq/index.html +++ b/docs/docs/faq/index.html @@ -100,7 +100,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > @@ -122,7 +122,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > diff --git a/docs/docs/faq/timing-operations/index.html b/docs/docs/faq/timing-operations/index.html index cc4b74093da..41e69e520ed 100644 --- a/docs/docs/faq/timing-operations/index.html +++ b/docs/docs/faq/timing-operations/index.html @@ -104,7 +104,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > @@ -126,7 +126,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > diff --git a/docs/docs/getting-started/index.html b/docs/docs/getting-started/index.html index d79a849595c..2d33598dc54 100644 --- a/docs/docs/getting-started/index.html +++ b/docs/docs/getting-started/index.html @@ -112,7 +112,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > @@ -134,7 +134,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > diff --git a/docs/docs/handling-errors/index.html b/docs/docs/handling-errors/index.html index 49c25f2b05b..23de3be7d5d 100644 --- a/docs/docs/handling-errors/index.html +++ b/docs/docs/handling-errors/index.html @@ -104,7 +104,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > @@ -126,7 +126,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > diff --git a/docs/docs/index.html b/docs/docs/index.html index 4c501368cc3..7dc44ba13f9 100644 --- a/docs/docs/index.html +++ b/docs/docs/index.html @@ -101,7 +101,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > @@ -123,7 +123,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > diff --git a/docs/docs/index.xml b/docs/docs/index.xml index 7cbe0ead0bb..dc731bc0d57 100644 --- a/docs/docs/index.xml +++ b/docs/docs/index.xml @@ -3353,6 +3353,68 @@ implementation and include additional API error codes that should be considered </span></span><span style="display:flex;"><span><span style="color:#000;font-weight:bold">}</span> </span></span><span style="display:flex;"><span> </span></span><span style="display:flex;"><span><span style="color:#000">client</span> <span style="color:#ce5c00;font-weight:bold">:=</span> <span style="color:#000">s3</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">NewFromConfig</span><span style="color:#000;font-weight:bold">(</span><span style="color:#000">cfg</span><span style="color:#000;font-weight:bold">)</span> +</span></span></code></pre></div><h3 id="client-side-rate-limiting">Client-side rate limiting</h3> +<p>The AWS SDK for Go V2 introduces a new client-side rate-limiting mechanism +in the standard retry policy to align with the behavior of modern SDKs. This is +behavior is controlled by the <a href="https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#RateLimiter">RateLimiter</a> +field on a retryer’s <a href="https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#StandardOptions">options</a>.</p> +<p>A RateLimiter operates as a token bucket with a set capacity, where operation +attempt failures consume tokens. A retry that attempts to consume more tokens +than what’s available results in operation failure with a +<a href="https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#QuotaExceededError">QuotaExceededError</a>.</p> +<p>The default implementation is parameterized as follows (how to modify each setting):</p> +<ul> +<li>a capacity of 500 (set the value of RateLimiter on StandardOptions using <a href="https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#NewTokenRateLimit">NewTokenRateLimit</a>)</li> +<li>a retry caused by a timeout costs 10 tokens (set RetryCost on StandardOptions)</li> +<li>a retry caused by other errors costs 5 tokens (set RetryTimeoutCost on StandardOptions)</li> +<li>an operation that succeeds on the 1st attempt adds 1 token (set NoRetryIncrement on StandardOptions) +<ul> +<li>operations that succeed on the 2nd or later attempt do not add back any tokens</li> +</ul> +</li> +</ul> +<p>If you find that the default behavior does not fit your application’s needs, +you can disable it with <a href="https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#pkg-variables">ratelimit.None</a>.</p> +<h4 id="example-modified-rate-limiter">Example: modified rate limiter</h4> +<div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-go" data-lang="go"><span style="display:flex;"><span><span style="color:#204a87;font-weight:bold">import</span> <span style="color:#000;font-weight:bold">(</span> +</span></span><span style="display:flex;"><span> <span style="color:#4e9a06">"context"</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> <span style="color:#4e9a06">"github.com/aws/aws-sdk-go-v2/aws"</span> +</span></span><span style="display:flex;"><span> <span style="color:#4e9a06">"github.com/aws/aws-sdk-go-v2/aws/ratelimit"</span> +</span></span><span style="display:flex;"><span> <span style="color:#4e9a06">"github.com/aws/aws-sdk-go-v2/aws/retry"</span> +</span></span><span style="display:flex;"><span> <span style="color:#4e9a06">"github.com/aws/aws-sdk-go-v2/config"</span> +</span></span><span style="display:flex;"><span><span style="color:#000;font-weight:bold">)</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span><span style="color:#8f5902;font-style:italic">// ... +</span></span></span><span style="display:flex;"><span><span style="color:#8f5902;font-style:italic"></span> +</span></span><span style="display:flex;"><span><span style="color:#000">cfg</span><span style="color:#000;font-weight:bold">,</span> <span style="color:#000">err</span> <span style="color:#ce5c00;font-weight:bold">:=</span> <span style="color:#000">config</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">LoadDefaultConfig</span><span style="color:#000;font-weight:bold">(</span><span style="color:#000">context</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">Background</span><span style="color:#000;font-weight:bold">(),</span> <span style="color:#000">config</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">WithRetryer</span><span style="color:#000;font-weight:bold">(</span><span style="color:#204a87;font-weight:bold">func</span><span style="color:#000;font-weight:bold">()</span> <span style="color:#000">aws</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">Retryer</span> <span style="color:#000;font-weight:bold">{</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">return</span> <span style="color:#000">retry</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">NewStandard</span><span style="color:#000;font-weight:bold">(</span><span style="color:#204a87;font-weight:bold">func</span><span style="color:#000;font-weight:bold">(</span><span style="color:#000">o</span> <span style="color:#ce5c00;font-weight:bold">*</span><span style="color:#000">retry</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">StandardOptions</span><span style="color:#000;font-weight:bold">)</span> <span style="color:#000;font-weight:bold">{</span> +</span></span><span style="display:flex;"><span> <span style="color:#8f5902;font-style:italic">// Makes the rate limiter more permissive in general. These values are +</span></span></span><span style="display:flex;"><span><span style="color:#8f5902;font-style:italic"></span> <span style="color:#8f5902;font-style:italic">// arbitrary for demonstration and may not suit your specific +</span></span></span><span style="display:flex;"><span><span style="color:#8f5902;font-style:italic"></span> <span style="color:#8f5902;font-style:italic">// application's needs. +</span></span></span><span style="display:flex;"><span><span style="color:#8f5902;font-style:italic"></span> <span style="color:#000">o</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">RateLimiter</span> <span style="color:#000;font-weight:bold">=</span> <span style="color:#000">ratelimit</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">NewTokenRateLimit</span><span style="color:#000;font-weight:bold">(</span><span style="color:#0000cf;font-weight:bold">1000</span><span style="color:#000;font-weight:bold">)</span> +</span></span><span style="display:flex;"><span> <span style="color:#000">o</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">RetryCost</span> <span style="color:#000;font-weight:bold">=</span> <span style="color:#0000cf;font-weight:bold">1</span> +</span></span><span style="display:flex;"><span> <span style="color:#000">o</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">RetryTimeoutCost</span> <span style="color:#000;font-weight:bold">=</span> <span style="color:#0000cf;font-weight:bold">3</span> +</span></span><span style="display:flex;"><span> <span style="color:#000">o</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">NoRetryIncrement</span> <span style="color:#000;font-weight:bold">=</span> <span style="color:#0000cf;font-weight:bold">10</span> +</span></span><span style="display:flex;"><span> <span style="color:#000;font-weight:bold">})</span> +</span></span><span style="display:flex;"><span><span style="color:#000;font-weight:bold">}))</span> +</span></span></code></pre></div><h4 id="example-no-rate-limit-using-ratelimitnone">Example: no rate limit using ratelimit.None</h4> +<div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-go" data-lang="go"><span style="display:flex;"><span><span style="color:#204a87;font-weight:bold">import</span> <span style="color:#000;font-weight:bold">(</span> +</span></span><span style="display:flex;"><span> <span style="color:#4e9a06">"context"</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> <span style="color:#4e9a06">"github.com/aws/aws-sdk-go-v2/aws"</span> +</span></span><span style="display:flex;"><span> <span style="color:#4e9a06">"github.com/aws/aws-sdk-go-v2/aws/ratelimit"</span> +</span></span><span style="display:flex;"><span> <span style="color:#4e9a06">"github.com/aws/aws-sdk-go-v2/aws/retry"</span> +</span></span><span style="display:flex;"><span> <span style="color:#4e9a06">"github.com/aws/aws-sdk-go-v2/config"</span> +</span></span><span style="display:flex;"><span><span style="color:#000;font-weight:bold">)</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span><span style="color:#8f5902;font-style:italic">// ... +</span></span></span><span style="display:flex;"><span><span style="color:#8f5902;font-style:italic"></span> +</span></span><span style="display:flex;"><span><span style="color:#000">cfg</span><span style="color:#000;font-weight:bold">,</span> <span style="color:#000">err</span> <span style="color:#ce5c00;font-weight:bold">:=</span> <span style="color:#000">config</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">LoadDefaultConfig</span><span style="color:#000;font-weight:bold">(</span><span style="color:#000">context</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">Background</span><span style="color:#000;font-weight:bold">(),</span> <span style="color:#000">config</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">WithRetryer</span><span style="color:#000;font-weight:bold">(</span><span style="color:#204a87;font-weight:bold">func</span><span style="color:#000;font-weight:bold">()</span> <span style="color:#000">aws</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">Retryer</span> <span style="color:#000;font-weight:bold">{</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">return</span> <span style="color:#000">retry</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">NewStandard</span><span style="color:#000;font-weight:bold">(</span><span style="color:#204a87;font-weight:bold">func</span><span style="color:#000;font-weight:bold">(</span><span style="color:#000">o</span> <span style="color:#ce5c00;font-weight:bold">*</span><span style="color:#000">retry</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">StandardOptions</span><span style="color:#000;font-weight:bold">)</span> <span style="color:#000;font-weight:bold">{</span> +</span></span><span style="display:flex;"><span> <span style="color:#000">o</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">RateLimiter</span> <span style="color:#000;font-weight:bold">=</span> <span style="color:#000">ratelimit</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">None</span> +</span></span><span style="display:flex;"><span> <span style="color:#000;font-weight:bold">})</span> +</span></span><span style="display:flex;"><span><span style="color:#000;font-weight:bold">}))</span> </span></span></code></pre></div><h2 id="timeouts">Timeouts</h2> <p>You use the <a href="https://golang.org/pkg/context/">context</a> package to set timeouts or deadlines when invoking a service client operation. Use the <a href="https://golang.org/pkg/context/#WithDeadline">context.WithDeadline</a> to wrap your applications diff --git a/docs/docs/making-requests/index.html b/docs/docs/making-requests/index.html index 99492c4bea4..2eb7fd13dcc 100644 --- a/docs/docs/making-requests/index.html +++ b/docs/docs/making-requests/index.html @@ -104,7 +104,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > @@ -126,7 +126,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > diff --git a/docs/docs/middleware/index.html b/docs/docs/middleware/index.html index 89657a8236d..eb916b612db 100644 --- a/docs/docs/middleware/index.html +++ b/docs/docs/middleware/index.html @@ -104,7 +104,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > @@ -126,7 +126,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > diff --git a/docs/docs/migrating/index.html b/docs/docs/migrating/index.html index bbcdf84ffea..88e2d352416 100644 --- a/docs/docs/migrating/index.html +++ b/docs/docs/migrating/index.html @@ -100,7 +100,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > @@ -122,7 +122,7 @@ aria-label="Search this site…" autocomplete="off" - data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json" + data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.d8f87655e0fa72213f78a940133fec6c.json" data-offline-search-base-href="/" data-offline-search-max-results="10" > @@ -1142,7 +1142,7 @@