Soto icon

Soto

AWSClient

The AWSClient is the core of Soto. This is the object that manages your communication with AWS. It manages credential acquisition, takes your request, encodes it, signs it, sends it to AWS and then decodes the response for you. In most situations your application should only require one AWSClient. Create this at startup and use it throughout.

The init for creating an AWSClient looks like the following:

public init(
    credentialProvider credentialProviderFactory: CredentialProviderFactory = .default,
    retryPolicy retryPolicyFactory: RetryPolicyFactory = .default,
    middlewares: [AWSServiceMiddleware] = [],
    httpClientProvider: HTTPClientProvider,
    logger clientLogger: Logger = AWSClient.loggingDisabled
)

Details for each option are below.

Credential Provider

The credentialProvider defines how the client acquires its AWS credentials. Its default is to try four different methods:

  • environment variables
  • ECS container credentials
  • EC2 instance metadata
  • the shared credential file ~/.aws/credential

An alternative is to provide credentials in code. You can do this as follows

let client = AWSClient(
    credentialProvider: .static(
        accessKeyId: "MY_AWS_ACCESS_KEY_ID",
        secretAccessKey: "MY_AWS_SECRET_ACCESS_KEY"
    ),
    ...
)

You can find out more about CredentialProviders here.

Retry policy

The retryPolicy defines how the client reacts to a failed request. There are three retry policies supplied. .noRetry doesn't retry the request if it fails. The other two will retry if the response is a 5xx (server error) or a connection error. They differ in how long they wait before performing the retry. .exponential doubles the wait time after each retry and .jitter is the same as exponential except it adds a random element to the wait time. .jitter is the recommended method from AWS so it is the default.

Middleware

Middleware allows you to insert your own code just as a request has been constructed or a response has been received. You can use this to edit the request/response or just to view it. Soto Core supplies one middleware — AWSLoggingMiddleware — which outputs your request to the console once constructed and the response received from AWS.

HTTP Client provider

The HTTPClientProvider defines where you get your HTTP client from. You have three options:

  • Pass .createNew which indicates the AWSClient should create its own HTTP client. This creates an instance of HTTPClient using AsyncHTTPClient.
  • Supply your own EventLoopGroup with .createNewWithEventLoopGroup(EventLoopGroup). This creates a new HTTPClient but has it use the supplied EventLoopGroup.
  • Supply your own HTTP client with .shared(AWSHTTPClient) as long as it conforms to the protocol AWSHTTPClient. AsyncHTTPClient.HTTPClient already conforms to this protocol.

There are a number of reasons you might want to provide your own client, such as:

  • You have one HTTP client you want to use across all your systems.
  • You want to change the configuration for the HTTP client used, perhaps you are running behind a proxy or want to enable response decompression.
  • You want to provide your own custom HTTP client.

Logger

The final function parameter is the Logger. This Logger is used for logging background processes the client might perform like AWS credential acquisition.

AWSClient Shutdown

The AWSClient requires you shut it down manually before it is deinitialized. The manual shutdown is required to ensure any internal processes are finished before the AWSClient is freed and Soto's event loops and client are shutdown properly. You can either do this asynchronously with AWSClient.shutdown() or do this synchronously with AWSClient.syncShutdown().