Configurar tempos limite no AWS SDK for Java 2.x

O AWS SDK for Java 2.x fornece várias camadas de configuração de tempo limite para ajudar a criar aplicações resilientes. O SDK oferece diferentes tipos de tempos limite que funcionam juntos para otimizar o desempenho e a confiabilidade da aplicação.

Existem quatro categorias principais de tempo limite no SDK:

Tempo limite do cliente de serviço

O tempo limite do cliente de serviço opera no nível da API e controla o comportamento geral das operações de serviço, incluindo novas tentativas e várias tentativas.

Tempo limite de chamada de API

O tempo limite de chamada de API define a quantidade máxima de tempo para toda a operação de API, incluindo todas as novas tentativas. Esse tempo limite impõe um limite rígido de quanto tempo a aplicação deve esperar até que uma operação completa seja concluída.

S3Client s3Client = S3Client.builder()
    .overrideConfiguration(ClientOverrideConfiguration.builder()
        .apiCallTimeout(Duration.ofMinutes(2))  // Total time for entire operation, such as when you call the getObject method.
        .build())
    .build();

Características principais:

Tempo limite da tentativa de chamada de API

O tempo limite da tentativa de chamada de API define o tempo máximo para uma única tentativa de uma operação de API. Se esse tempo limite for excedido, o SDK repetirá a operação (se houver uma configuração de novas tentativas) em vez de falhar em toda a chamada.

S3Client s3Client = S3Client.builder()
    .overrideConfiguration(ClientOverrideConfiguration.builder()
        .apiCallAttemptTimeout(Duration.ofSeconds(30))  // Time for single attempt.
        .build())
    .build();

Características principais:

Configurar o tempo limite do cliente de serviço

É possível configurar o tempo limite do cliente de serviço globalmente para todas as operações ou por solicitação:

Configuração global:

S3Client s3Client = S3Client.builder()
    .overrideConfiguration(b -> b
        .apiCallTimeout(Duration.ofSeconds(105L))
        .apiCallAttemptTimeout(Duration.ofSeconds(25L)))
    .build();
// When you use the s3Client for an API operation, the SDK uses the configured timeout values.

Configuração por solicitação:

S3Client basicS3Client = S3Client.create();

// The following configuration uses the same settings as shown before, but these settings
// apply to only the `putObject` call. When you use `basicS3Client` in another API call without
// supplying the override configuration, there are no API timeout limits. No timeout limits is the default for the SDK.
AwsRequestOverrideConfiguration overrideConfiguration = AwsRequestOverrideConfiguration.builder()
    .apiCallTimeout(Duration.ofSeconds(105L))
    .apiCallAttemptTimeout(Duration.ofSeconds(25L))
    .build();

basicS3Client.putObject(b -> b
        .bucket("amzn-s3-demo-bucket")
        .key("example-key")
        .overrideConfiguration(overrideConfiguration),
    RequestBody.fromString("test"));

Práticas recomendadas para tempo limite de API

O SDK para Java 2.x não define o tempo limite de chamada de API nem o tempo limite de tentativas de chamada de API individuais por padrão. Defina o tempo limite tanto para as tentativas individuais como para toda a solicitação. Isso ajuda a aplicação a antecipar-se à falha quando problemas transitórios fazem com que as tentativas de solicitação demorem mais ou quando ocorrem problemas fatais de rede.

Tempo limite do cliente HTTP

O tempo limite do cliente HTTP opera no nível da rede e controla vários aspectos da comunicação HTTP. Esse tempo limite varia de acordo com a implementação do cliente HTTP que você usa.

Tempo limite da conexão

O tempo limite da conexão controla quanto tempo esperar ao estabelecer uma nova conexão com o endpoint do AWS service (Serviço da AWS).

// Available with all HTTP clients.
ApacheHttpClient.builder()
    .connectionTimeout(Duration.ofSeconds(5L))
    .build();

Finalidade:

Tempo limite do soquete (clientes Apache e URLConnection)

O tempo limite do soquete controla quanto tempo esperar pelos dados em uma conexão estabelecida.

ApacheHttpClient.builder()
    .socketTimeout(Duration.ofSeconds(30L))  // Time to wait for response data.
    .build();

Tempo limite de leitura e gravação (cliente Netty)

O cliente Netty fornece um tempo limite distinto para operações de leitura e gravação:

NettyNioAsyncHttpClient.builder()
    .readTimeout(Duration.ofSeconds(30L))   // Reading response data.
    .writeTimeout(Duration.ofSeconds(30L))  // Writing request data.
    .build();

Tempo limite de negociação do TLS (cliente Netty)

Controla o tempo permitido para o handshake TLS/SSL:

NettyNioAsyncHttpClient.builder()
    .tlsNegotiationTimeout(Duration.ofSeconds(3L))
    .build();

Tempo limite do grupo de conexão

Alguns clientes HTTP fornecem um tempo limite para operações do pool de conexões:

ApacheHttpClient.builder()
    .connectionAcquisitionTimeout(Duration.ofSeconds(10L))  // Wait for pool connection.
    .connectionTimeToLive(Duration.ofMinutes(5L))           // Maximum connection age.
    .connectionMaxIdleTime(Duration.ofSeconds(60L))         // Maximum idle time.
    .build()

O Configurar clientes HTTP contém mais informações sobre clientes HTTP no AWS SDK for Java 2.x

Hierarquia e interações do tempo limite

Noções básicas de como os diferentes tempos limite interagem é crucial para uma configuração adequada:

Hierarquia de tempo limite

API Call Timeout (2 minutes)
├── Retry Attempt 1
│   ├── API Call Attempt Timeout (45 seconds)
│   └── HTTP Client Timeouts
│       ├── Connection Timeout (5 seconds)
│       ├── TLS Negotiation Timeout (3 seconds)
│       └── Read/Write Timeout (30 seconds)
├── Retry Attempt 2
│   └── [Same structure as Attempt 1]
└── Retry Attempt 3
    └── [Same structure as Attempt 1]

Regras de configuração

Usar padrões de configuração inteligentes

O SDK fornece padrões inteligentes que configuram automaticamente os valores de tempo limite apropriados:

// Enable smart defaults.
S3Client client = S3Client.builder()
    .defaultsMode(DefaultsMode.AUTO)  // Automatically choose appropriate defaults.
    .build();

// Available modes:
// - STANDARD: Balanced defaults
// - IN_REGION: Optimized for same-region calls
// - CROSS_REGION: Optimized for cross-region calls  
// - MOBILE: Optimized for mobile applications
// - AUTO: Automatically detect and choose appropriate mode
// - LEGACY: Provides settings that were used before smart defaults existed.

Os padrões inteligentes configuram automaticamente:

Resumo

A configuração efetiva do tempo limite no AWS SDK for Java 2.x requer a compreensão da interação entre o tempo limite do cliente de serviço e o tempo limite do cliente HTTP:

Configure os tempos limite de acordo com seu caso de uso para criar aplicações que sejam resilientes a problemas de rede e responsivos aos usuários.