Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make aws client creation parameters configurable #453

Open
wants to merge 12 commits into
base: master
Choose a base branch
from
Prev Previous commit
Update README.MD
deepanjan90 committed Apr 28, 2021
commit 688e3e8b69cce4fd2083c98cc5ae72d2970eff15
91 changes: 68 additions & 23 deletions src/main/java/gyro/aws/clientconfiguration/README.MD
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# AWS Client override configuration

The AWS **client-configuration** allows you to override the default client creation options.

You define the `client-configuration` directive in your `.init.gyro` file.
@@ -27,7 +28,9 @@ If no config name is given, it is treated as `default` and is used as the defaul
@end
```

Multiple client-configuration directives can be defined using different names. These can be associated with individual credential directives. In doing so all assets using that credential will create the aws client with overrides as defined by the mentioned client configuration.
Multiple client-configuration directives can be defined using different names. These can be associated with individual
credential directives. In doing so all assets using that credential will create the aws client with overrides as defined
by the mentioned client configuration.

```
@credentials 'enterprise::aws-credentials' 'east-2'
@@ -71,56 +74,98 @@ Multiple client-configuration directives can be defined using different names. T
end
@end
```
In this case, all assets using the `east-2` credentials will create there respective aws clients using the overrides defined in the client-configuration named `east-2-config`.

In this case, all assets using the `east-2` credentials will create there respective aws clients using the overrides
defined in the client-configuration named `east-2-config`.

## Configuration Details

The client-configuration has the following options:

- **http-client-configuration** - Http configuration for the client. [See options](#Http-Client-Configuration)
- **override-client-configuration** - Override configuration for the client. [See options](#Override-Client-Configuration)
- **override-client-configuration** - Override configuration for the
client. [See options](#Override-Client-Configuration)

### Http Client Configuration
- **socket-timeout** - The amount of [time](#Time) to wait for data to be transferred over an established, open connection before the connection is timed out. A duration of `0` means infinity, and is not recommended.
- **connection-timeout** - The amount of [time](#Time) to wait when initially establishing a connection before giving up and timing out. A duration of `0` means infinity, and is not recommended.
- **connection-acquisition-timeout** - The amount of [time](#Time) to wait when acquiring a connection from the pool before giving up and timing out.

- **socket-timeout** - The amount of [time](#Time) to wait for data to be transferred over an established, open
connection before the connection is timed out. A duration of `0` means infinity, and is not recommended.
- **connection-timeout** - The amount of [time](#Time) to wait when initially establishing a connection before giving up
and timing out. A duration of `0` means infinity, and is not recommended.
- **connection-acquisition-timeout** - The amount of [time](#Time) to wait when acquiring a connection from the pool
before giving up and timing out.
- **max-connections** - The maximum number of connections allowed in the connection pool.
- **expect-continue-enabled** - Configure whether the client should send an HTTP expect-continue handshake before each request.
- **connection-time-to-live** - The maximum amount of [time](#Time) that a connection should be allowed to remain open, regardless of usage frequency.
- **connection-max-idle-time** - Configure the maximum amount of [time](#Time) that a connection should be allowed to remain open while idle.
- **expect-continue-enabled** - Configure whether the client should send an HTTP expect-continue handshake before each
request.
- **connection-time-to-live** - The maximum amount of [time](#Time) that a connection should be allowed to remain open,
regardless of usage frequency.
- **connection-max-idle-time** - Configure the maximum amount of [time](#Time) that a connection should be allowed to
remain open while idle.

### Override Client Configuration
- **api-call-timeout** - Specify the amount of [time](#Time) to allow the client to complete the execution of an API call. This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. This value should always be positive, if present.

- **api-call-timeout** - Specify the amount of [time](#Time) to allow the client to complete the execution of an API
call. This timeout covers the entire client execution except for marshalling. This includes request handler execution,
all HTTP requests including retries, unmarshalling, etc. This value should always be positive, if present.
- **retry-policy** - Configure the retry policy that should be used when handling failure cases.
- **retry-count** - Specify the maximum number of times that a single request should be retried, assuming it fails for a retryable error
- **additional-retry-conditions-allowed** - Specify whether further conditions can be added to this policy after it is created.
- **backoff-strategy** - Specify the backoff strategy that should be used for waiting in between retry attempts. If the retry is because of throttling reasons, the `throttling-backoff-strategy` is used instead. [See available Backoff Strategies](#Backoff-Strategies)
- **throttling-backoff-strategy** - Specify the backoff strategy that should be used for waiting in between retry attempts after a throttling error is encountered. If the retry is not because of throttling reasons, the `backoff-strategy` is used instead. [See available Backoff Strategies](#Backoff-Strategies)
- **retry-condition** - Specify the retry condition under which the request should be retried. [See available Retry Conditions](#Retry-Conditions)
- **retry-capacity-condition** - Specify the retry condition that should be used to throttle the number of retries attempted by the SDK client as a whole. [See available Retry Conditions](#Retry-Conditions)
- **retry-count** - Specify the maximum number of times that a single request should be retried, assuming it fails
for a retryable error
- **additional-retry-conditions-allowed** - Specify whether further conditions can be added to this policy after it
is created.
- **backoff-strategy** - Specify the backoff strategy that should be used for waiting in between retry attempts. If
the retry is because of throttling reasons, the `throttling-backoff-strategy` is used
instead. [See available Backoff Strategies](#Backoff-Strategies)
- **throttling-backoff-strategy** - Specify the backoff strategy that should be used for waiting in between retry
attempts after a throttling error is encountered. If the retry is not because of throttling reasons,
the `backoff-strategy` is used instead. [See available Backoff Strategies](#Backoff-Strategies)
- **retry-condition** - Specify the retry condition under which the request should be
retried. [See available Retry Conditions](#Retry-Conditions)
- **retry-capacity-condition** - Specify the retry condition that should be used to throttle the number of retries
attempted by the SDK client as a whole. [See available Retry Conditions](#Retry-Conditions)

### Backoff Strategies

- **equal-jitter** - Backoff strategy that uses equal jitter for computing the delay before the next retry.
- **base-delay** - The base delay to be used for the jitter calculation.
- **max-backoff-time** - The max-backoff [time](#Time) to be used for the jitter calculation.
- **full-jitter** - Backoff strategy that uses a full jitter strategy for computing the next backoff delay.
- **base-delay** - The base delay to be used for the jitter calculation.
- **max-backoff-time** - The max-backoff [time](#Time) to be used for the jitter calculation.
- **fixed-backoff** - Simple backoff strategy that always uses a fixed delay for the delay before the next retry attempt.
- **fixed-backoff** - Simple backoff strategy that always uses a fixed delay for the delay before the next retry
attempt.
- **delay** - The delay between the retry attempts.

### Retry Conditions
- **and-retry-condition** - Composite retry condition that evaluates to true when all contained retry conditions evaluate to true.

- **and-retry-condition** - Composite retry condition that evaluates to true when all contained retry conditions
evaluate to true.
- A list of retry conditions that are checked for all to be true to satisfy the retry condition.
- **or-retry-condition** - Composite retry condition that evaluates to true if any containing condition evaluates to true.
- **or-retry-condition** - Composite retry condition that evaluates to true if any containing condition evaluates to
true.
- A list of retry condition that are checked for any one of them to be true to satisfy teh condition.
- **retry-on-error-codes-condition** - Retry condition implementation that retries if the exception, or the cause of the exception matches the error codes defined.
- **retry-on-error-codes-condition** - Retry condition implementation that retries if the exception, or the cause of the
exception matches the error codes defined.
- **retryable-error-codes** - A list of string specifying the error codes to match for retrying.
- **retry-on-status-codes-condition** - Retry condition implementation that retries if the HTTP status code matches one of the provided status codes.
- **retry-on-status-codes-condition** - Retry condition implementation that retries if the HTTP status code matches one
of the provided status codes.
- **retryable-status-codes** - A list of integers specifying the error codes to match for retrying.
- **max-number-of-retry-condition** - Simple retry condition that allows retries up to a certain max number of retries.
- **retry-count** - An integer specifying the max number of retries allowed.
- **retry-on-throttling-condition** - A retry condition that will return `true` if the provided exception seems to be due to a throttling error from the service to the client.
- **token-bucket-retry-condition** - A retry condition that limits the number of retries made by the SDK using a token
bucket algorithm.
- **bucket-size** - An integer specifying the maximum number of tokens in the token bucket. This is also used as the
initial value for the number of tokens in the bucket.
- **exception-cost** - An integer specifying the number of tokens that should be removed from the token bucket when
no other exception type in this function is matched.
- **throttling-exception-cost** - An integer specifying the number of tokens that should be removed from the token
bucket when throttling exceptions.
- **retry-on-throttling-condition** - A retry condition that will return `true` if the provided exception seems to be
due to a throttling error from the service to the client.
- **retry-on-clock-screw-condition** - A retry condition that will return true if the provided exception seems to be due
to a clock skew between the client and service.

#### Time
Time is specified as a string with formats based on the ISO-8601 duration format `PnDTnHnMn.nS` with days considered to be exactly 24 hours.

Time is specified as a string with formats based on the ISO-8601 duration format `PnDTnHnMn.nS` with days considered to
be exactly 24 hours.
[See here for more details.](https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-)