|
| 1 | +# lib-httpx |
| 2 | + |
| 3 | +Enhanced HTTP client extension for Java `HttpClient` with built-in retry logic and JWT token refresh capabilities. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- **Retry Logic**: Automatic retry for configurable HTTP status codes (default: 429, 500, 502, 503, 504) |
| 8 | +- **JWT Token Refresh**: Automatic JWT token refresh when receiving 401 Unauthorized responses |
| 9 | +- **Configurable**: Customizable retry policies, timeouts, and token refresh settings |
| 10 | +- **Generic Integration**: Compatible with any `Retryable.Config` for flexible retry configuration |
| 11 | +- **Thread-safe**: Safe for concurrent use |
| 12 | +- **Async Support**: Support for both synchronous and asynchronous requests |
| 13 | + |
| 14 | +## Usage |
| 15 | + |
| 16 | +### Basic Usage |
| 17 | + |
| 18 | +```groovy |
| 19 | +// Create with default configuration |
| 20 | +def client = HxClient.create() |
| 21 | +
|
| 22 | +// Create with custom configuration |
| 23 | +def config = HxConfig.builder() |
| 24 | + .withMaxAttempts(3) |
| 25 | + .withRetryStatusCodes([429, 503] as Set) |
| 26 | + .build() |
| 27 | +def client = HxClient.create(config) |
| 28 | +
|
| 29 | +// Make HTTP requests |
| 30 | +def request = HttpRequest.newBuilder() |
| 31 | + .uri(URI.create("https://api.example.com/data")) |
| 32 | + .GET() |
| 33 | + .build() |
| 34 | +
|
| 35 | +def response = client.send(request, HttpResponse.BodyHandlers.ofString()) |
| 36 | +``` |
| 37 | + |
| 38 | +### JWT Token Configuration |
| 39 | + |
| 40 | +```groovy |
| 41 | +def config = HxConfig.builder() |
| 42 | + .withJwtToken("your-jwt-token") |
| 43 | + .withRefreshToken("your-refresh-token") |
| 44 | + .withRefreshTokenUrl("https://api.example.com/oauth/token") |
| 45 | + .build() |
| 46 | +
|
| 47 | +def client = HxClient.create(config) |
| 48 | +``` |
| 49 | + |
| 50 | +### Custom Retry Configuration |
| 51 | + |
| 52 | +```groovy |
| 53 | +def config = HxConfig.builder() |
| 54 | + .withMaxAttempts(5) |
| 55 | + .withDelay(Duration.ofSeconds(1)) |
| 56 | + .withMaxDelay(Duration.ofMinutes(2)) |
| 57 | + .withJitter(0.5) |
| 58 | + .withMultiplier(2.0) |
| 59 | + .withRetryStatusCodes([429, 500, 502, 503, 504] as Set) |
| 60 | + .build() |
| 61 | +``` |
| 62 | + |
| 63 | +### Integration with Existing Retry Configuration |
| 64 | + |
| 65 | +```groovy |
| 66 | +// Use any existing Retryable.Config |
| 67 | +def retryConfig = Retryable.ofDefaults().config() |
| 68 | +def client = HxClient.create(retryConfig) |
| 69 | +
|
| 70 | +// Or combine with HTTP-specific settings |
| 71 | +def config = HxConfig.builder() |
| 72 | + .withRetryConfig(retryConfig) |
| 73 | + .withJwtToken("your-jwt-token") |
| 74 | + .withRetryStatusCodes([429, 503] as Set) |
| 75 | + .build() |
| 76 | +def client = HxClient.create(config) |
| 77 | +``` |
| 78 | + |
| 79 | +## Configuration Options |
| 80 | + |
| 81 | +| Option | Description | Default | |
| 82 | +|--------|-------------|---------| |
| 83 | +| `maxAttempts` | Maximum number of retry attempts | 5 | |
| 84 | +| `delay` | Initial delay between retries | 500ms | |
| 85 | +| `maxDelay` | Maximum delay between retries | 30s | |
| 86 | +| `jitter` | Random jitter factor (0-1) | 0.25 | |
| 87 | +| `multiplier` | Exponential backoff multiplier | 2.0 | |
| 88 | +| `retryStatusCodes` | HTTP status codes to retry | [429, 500, 502, 503, 504] | |
| 89 | +| `tokenRefreshTimeout` | Timeout for token refresh requests | 30s | |
| 90 | + |
| 91 | +## API Documentation |
| 92 | + |
| 93 | +All classes and methods include comprehensive Javadoc documentation covering: |
| 94 | + |
| 95 | +- **Class-level documentation**: Complete overview of functionality and usage patterns |
| 96 | +- **Method documentation**: Detailed parameter descriptions, return values, and behavior |
| 97 | +- **Usage examples**: Code samples showing common use cases |
| 98 | +- **Thread safety notes**: Concurrency guarantees and synchronization details |
| 99 | +- **Error handling**: Exception types and retry behavior |
| 100 | + |
| 101 | +### Key Classes |
| 102 | + |
| 103 | +- **`HxClient`** (Http eXtended Client): Main client class with retry and JWT functionality |
| 104 | +- **`HxConfig`**: Configuration builder with all available options including Retryable.Config integration |
| 105 | +- **`HxTokenManager`**: Thread-safe JWT token lifecycle management |
| 106 | + |
| 107 | +## Dependencies |
| 108 | + |
| 109 | +- `lib-retry`: Provides the underlying retry mechanism using Failsafe |
| 110 | +- `groovy-json`: For JSON processing during token refresh |
| 111 | +- `dev.failsafe:failsafe`: Core retry and circuit breaker library |
0 commit comments