tessl/maven-software-amazon-awssdk--netty-nio-client

A non-blocking HTTP client implementation for AWS SDK Java applications using Netty framework, enabling efficient network communication with AWS services through asynchronous I/O operations

Overview

Eval results

Files

Proxy Configuration

Name: tessl/maven-software-amazon-awssdk--netty-nio-client
Author: tessl

Comprehensive proxy support with automatic system property and environment variable integration for enterprise environments. Supports HTTP and HTTPS proxies with authentication and host exclusions.

Capabilities

ProxyConfiguration

Configuration class for HTTP/HTTPS proxy settings including host, port, credentials, and non-proxy hosts. Supports automatic resolution from system properties and environment variables.

/**
 * ProxyConfiguration provides HTTP and HTTPS proxy settings with automatic system integration.
 * Supports authentication, host exclusions, and fallback to system properties and environment variables.
 */
public final class ProxyConfiguration implements ToCopyableBuilder<ProxyConfiguration.Builder, ProxyConfiguration> {
    /**
     * Returns the proxy scheme (http or https)
     * @return proxy scheme
     */
    public String scheme();
    
    /**
     * Returns the proxy host from configuration, system properties, or environment variables
     * Checks: configured value -> system properties -> environment variables
     * @return proxy host name or IP address
     */
    public String host();
    
    /**
     * Returns the proxy port from configuration, system properties, or environment variables
     * Checks: configured value -> system properties -> environment variables
     * @return proxy port number
     */
    public int port();
    
    /**
     * Returns the proxy username from configuration, system properties, or environment variables
     * @return proxy username for authentication (null if not configured)
     */
    public String username();
    
    /**
     * Returns the proxy password from configuration, system properties, or environment variables
     * @return proxy password for authentication (null if not configured)
     */
    public String password();
    
    /**
     * Returns hosts that should bypass the proxy
     * @return unmodifiable set of hosts to exclude from proxy
     */
    public Set<String> nonProxyHosts();
    
    /**
     * Creates a new builder from this configuration
     * @return builder initialized with current values
     */
    public Builder toBuilder();
    
    /**
     * Creates a new builder instance
     * @return new Builder for proxy configuration
     */
    public static Builder builder();
    
    /**
     * Standard equals implementation
     */
    public boolean equals(Object obj);
    
    /**
     * Standard hashCode implementation
     */
    public int hashCode();
}

Usage Examples:

import software.amazon.awssdk.http.nio.netty.ProxyConfiguration;
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;

// Basic proxy configuration
ProxyConfiguration proxyConfig = ProxyConfiguration.builder()
    .scheme("http")
    .host("proxy.company.com")
    .port(8080)
    .build();

// Proxy with authentication
ProxyConfiguration proxyConfig = ProxyConfiguration.builder()
    .scheme("http")
    .host("proxy.company.com")
    .port(8080)
    .username("myuser")
    .password("mypassword")
    .build();

// Use with HTTP client
NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
    .proxyConfiguration(proxyConfig)
    .build();

ProxyConfiguration Builder

Builder interface for configuring proxy settings with support for system property and environment variable fallbacks.

/**
 * Builder for configuring proxy settings with system integration
 */
public interface Builder extends CopyableBuilder<Builder, ProxyConfiguration> {
    /**
     * Sets the proxy host name or IP address
     * @param host proxy host
     * @return this builder for method chaining
     */
    Builder host(String host);
    
    /**
     * Sets the proxy port number
     * @param port proxy port (typically 8080, 3128, or 80/443)
     * @return this builder for method chaining
     */
    Builder port(int port);
    
    /**
     * Sets the proxy scheme (http or https)
     * @param scheme "http" or "https" (default: "http")
     * @return this builder for method chaining
     */
    Builder scheme(String scheme);
    
    /**
     * Sets hosts that should bypass the proxy.
     * Supports wildcards and patterns for flexible host matching.
     * @param nonProxyHosts set of hosts to exclude from proxy
     * @return this builder for method chaining
     */
    Builder nonProxyHosts(Set<String> nonProxyHosts);
    
    /**
     * Sets the proxy username for authentication
     * @param username proxy username
     * @return this builder for method chaining
     */
    Builder username(String username);
    
    /**
     * Sets the proxy password for authentication
     * @param password proxy password
     * @return this builder for method chaining
     */
    Builder password(String password);
    
    /**
     * Enables or disables fallback to system properties for proxy configuration.
     * When enabled, checks standard Java system properties like http.proxyHost.
     * @param useSystemPropertyValues true to enable system property fallback (default: true)
     * @return this builder for method chaining
     */
    Builder useSystemPropertyValues(Boolean useSystemPropertyValues);
    
    /**
     * Enables or disables fallback to environment variables for proxy configuration.
     * When enabled, checks environment variables like HTTP_PROXY, HTTPS_PROXY.
     * @param useEnvironmentVariableValues true to enable environment variable fallback (default: false)
     * @return this builder for method chaining
     */
    Builder useEnvironmentVariableValues(Boolean useEnvironmentVariableValues);
    
    /**
     * Builds the proxy configuration instance
     * @return configured ProxyConfiguration
     */
    ProxyConfiguration build();
}

Configuration Examples:

// Enterprise proxy with exclusions
Set<String> nonProxyHosts = Set.of(
    "localhost",
    "127.0.0.1", 
    "*.internal.company.com",
    "*.amazonaws.com"
);

ProxyConfiguration enterpriseProxy = ProxyConfiguration.builder()
    .scheme("http")
    .host("corporate-proxy.company.com")
    .port(8080)
    .username("domain\\username")
    .password("password")
    .nonProxyHosts(nonProxyHosts)
    .useSystemPropertyValues(true)
    .build();

// Automatic system property resolution
ProxyConfiguration systemProxy = ProxyConfiguration.builder()
    .useSystemPropertyValues(true)        // Use http.proxyHost, http.proxyPort, etc.
    .useEnvironmentVariableValues(false)
    .build();

// Environment variable resolution (common in containers)
ProxyConfiguration envProxy = ProxyConfiguration.builder()
    .useSystemPropertyValues(false)
    .useEnvironmentVariableValues(true)   // Use HTTP_PROXY, HTTPS_PROXY, NO_PROXY
    .build();

// Hybrid approach - explicit config with fallbacks
ProxyConfiguration hybridProxy = ProxyConfiguration.builder()
    .host("primary-proxy.com")
    .port(8080)
    .useSystemPropertyValues(true)        // Fallback to system properties
    .useEnvironmentVariableValues(true)   // Fallback to environment variables
    .build();

System Integration

System Properties

The proxy configuration integrates with standard Java system properties:

// System properties checked when useSystemPropertyValues(true)
System.setProperty("http.proxyHost", "proxy.company.com");
System.setProperty("http.proxyPort", "8080");
System.setProperty("http.proxyUser", "username");
System.setProperty("http.proxyPassword", "password");
System.setProperty("http.nonProxyHosts", "localhost|127.0.0.1|*.internal.com");

// HTTPS proxy properties
System.setProperty("https.proxyHost", "secure-proxy.company.com");
System.setProperty("https.proxyPort", "8443");
System.setProperty("https.proxyUser", "username");
System.setProperty("https.proxyPassword", "password");

// Configuration will automatically use these values
ProxyConfiguration config = ProxyConfiguration.builder()
    .useSystemPropertyValues(true)
    .build();

Environment Variables

Support for container and cloud-native proxy configurations:

# Environment variables checked when useEnvironmentVariableValues(true)
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://secure-proxy.company.com:8443
export NO_PROXY=localhost,127.0.0.1,*.internal.com

# With authentication
export HTTP_PROXY=http://username:password@proxy.company.com:8080
export HTTPS_PROXY=http://username:password@secure-proxy.company.com:8443

// Configuration will automatically parse environment variables
ProxyConfiguration config = ProxyConfiguration.builder()
    .useEnvironmentVariableValues(true)
    .build();

Precedence Order

Configuration values are resolved in this order (first found wins):

Explicitly configured values (via builder methods)
System properties (if useSystemPropertyValues(true))
Environment variables (if useEnvironmentVariableValues(true))
Default values (where applicable)

// Example showing precedence
ProxyConfiguration config = ProxyConfiguration.builder()
    .host("explicit-proxy.com")           // 1. Explicit value wins
    .useSystemPropertyValues(true)        // 2. Fallback to system properties
    .useEnvironmentVariableValues(true)   // 3. Fallback to environment variables
    .build();

// Even if HTTP_PROXY is set, explicit host takes precedence

Host Exclusion Patterns

Non-Proxy Hosts

The nonProxyHosts setting supports various patterns for excluding hosts from proxy:

Set<String> exclusions = Set.of(
    "localhost",                    // Exact match
    "127.0.0.1",                   // IP address
    "*.internal.company.com",      // Wildcard subdomain
    "*.amazonaws.com",             // AWS services
    "10.*",                        // IP range pattern
    "192.168.*"                    // Private network ranges
);

ProxyConfiguration config = ProxyConfiguration.builder()
    .host("proxy.company.com")
    .port(8080)
    .nonProxyHosts(exclusions)
    .build();

Pattern Matching

Host exclusion supports shell-style patterns:

* matches any sequence of characters
? matches any single character
Character classes like [a-z] are not supported
Case-insensitive matching

// Common exclusion patterns
Set<String> patterns = Set.of(
    "*.local",                     // All .local domains
    "*.localhost",                 // All localhost variants
    "10.*",                        // All 10.x.x.x addresses
    "192.168.*",                   // All 192.168.x.x addresses
    "*internal*",                  // Any host containing "internal"
    "test-*"                       // Any host starting with "test-"
);

Integration with HTTP Client

Basic Proxy Setup

import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
import software.amazon.awssdk.http.nio.netty.ProxyConfiguration;

// Configure proxy for all requests
ProxyConfiguration proxyConfig = ProxyConfiguration.builder()
    .scheme("http")
    .host("proxy.company.com")
    .port(8080)
    .username("user")
    .password("pass")
    .build();

NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
    .proxyConfiguration(proxyConfig)
    .build();

// Use with AWS services
S3AsyncClient s3 = S3AsyncClient.builder()
    .httpClient(client)
    .build();

Advanced Enterprise Setup

// Enterprise configuration with comprehensive settings
Set<String> nonProxyHosts = Set.of(
    "localhost", "127.0.0.1", "::1",
    "*.internal.company.com",
    "*.amazonaws.com", 
    "*.s3.*.amazonaws.com",
    "10.*", "192.168.*", "172.16.*"
);

ProxyConfiguration enterpriseConfig = ProxyConfiguration.builder()
    .scheme("http")
    .host("corporate-proxy.company.com")
    .port(8080)
    .username(System.getProperty("proxy.username"))
    .password(System.getProperty("proxy.password"))
    .nonProxyHosts(nonProxyHosts)
    .useSystemPropertyValues(true)        // Corporate system properties
    .useEnvironmentVariableValues(false)  // Disable for security
    .build();

NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
    .proxyConfiguration(enterpriseConfig)
    .connectionTimeout(Duration.ofSeconds(30))  // Longer timeout through proxy
    .readTimeout(Duration.ofMinutes(2))
    .build();

Types

Proxy Configuration Types

interface ToCopyableBuilder<B extends CopyableBuilder<B, T>, T> {
    B toBuilder();
}

interface CopyableBuilder<B extends CopyableBuilder<B, T>, T> {
    T build();
}

// Standard Java collections for host exclusions
interface Set<E> extends Collection<E> {
    boolean contains(Object o);
    int size();
    boolean isEmpty();
}

System Integration Types

// System property access
class System {
    static String getProperty(String key);
    static String getProperty(String key, String def);
    static void setProperty(String key, String value);
}

// Environment variable access
class System {
    static Map<String, String> getenv();
    static String getenv(String name);
}

Security Considerations

Credential Handling

Proxy passwords are stored in memory as strings (not secured)
Consider using system properties or environment variables for credentials
Avoid hardcoding credentials in source code
Use secure credential management systems in production

Network Security

Proxy connections may be monitored by network administrators
HTTPS traffic through HTTP proxies uses CONNECT tunneling
Consider using HTTPS proxies for sensitive applications
Validate proxy certificates when using HTTPS proxies

Install with Tessl CLI

npx tessl i tessl/maven-software-amazon-awssdk--netty-nio-client

docs