https://github.com/yskszk63/flaky-okhttp-agent
A Java agent that makes OkHttp requests flaky on purpose.
https://github.com/yskszk63/flaky-okhttp-agent
429-too-many-requests java javaagent okhttp3
Last synced: about 2 months ago
JSON representation
A Java agent that makes OkHttp requests flaky on purpose.
- Host: GitHub
- URL: https://github.com/yskszk63/flaky-okhttp-agent
- Owner: yskszk63
- License: mit
- Created: 2026-01-25T01:54:13.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-01-25T04:21:07.000Z (2 months ago)
- Last Synced: 2026-01-25T18:45:47.139Z (2 months ago)
- Topics: 429-too-many-requests, java, javaagent, okhttp3
- Language: Java
- Homepage:
- Size: 26.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# flaky-okhttp-agent
A Java agent that makes **OkHttp requests flaky on purpose**.
This agent intercepts OkHttp calls and intentionally returns **HTTP 429 (Too Many Requests)**,
allowing you to test retry logic, backoff strategies, and failure handling
*without modifying application code*.
---
## What this agent does
- Intercepts **OkHttp** requests via Java Agent instrumentation
- Returns **HTTP 429** for most requests
- Allows **1 successful request every N calls**
- Works with:
- HTTPS
- Proxy
- HTTP/1.1 and HTTP/2
- Requires **no changes** to application source code
This is useful for:
- Testing retry / backoff logic
- Simulating rate limits
- Chaos / fault injection in development or CI
---
## Usage
Attach the agent using `-javaagent`:
```bash
java -javaagent:flaky-okhttp-agent.jar -jar your-app.jar
```
or
```bash
export JAVA_TOOL_OPTIONS='-javaagent:/path/to/flaky-okhttp-agent.jar'
java -jar your-app.jar
```
No application code changes are required.
## Download
[Latest build](https://github.com/yskszk63/flaky-okhttp-agent/releases/latest/download/flaky-okhttp-agent.jar)
## How it behaves
By default:
- **Only 1 out of N requests succeeds**
- The remaining requests return **429 Too Many Requests**
Example with `FOA_SUCCESS_EVERY_NTH_REQUEST=5`:
| Request # | Result |
|----------:|---------------|
| 1 | 429 |
| 2 | 429 |
| 3 | 429 |
| 4 | 429 |
| 5 | ✅ success |
| 6 | 429 |
| ... | ... |
---
## Configuration
Configuration is done via **environment variables**.
### `FOA_SUCCESS_EVERY_NTH_REQUEST`
Controls how often a request is allowed to succeed.
- Type: integer
- Meaning: **1 successful request every N requests**
- Default: `2`
### `FOA_TARGET_HOST`
Limits the agent behavior to a specific host.
- Type: string
- Matching: **exact match**
- Default: *(not set)* — applies to **all hosts**
When this variable is set, the agent logic is applied **only if the request host exactly matches**
the specified value.
### `FOA_FAILURE_STATUS`
Specifies the HTTP status code returned for injected failures.
- Type: integer (HTTP status code)
- Default: `429`
When this variable is set, the agent returns the specified status code
instead of `429 Too Many Requests` for failure responses.
---
## Scope and limitations
- This agent only targets OkHttp
- Other HTTP clients (HttpURLConnection, Apache HttpClient, etc.) are not affected
- Designed for testing and development
- Not recommended for production environments
### Limitations: Multiple ClassLoaders
This agent is designed to work with applications that use a **single application classloader**
or a relatively simple classloader hierarchy.
It may **not work correctly** in environments that heavily rely on
**multiple or isolated classloaders**, such as:
- Servlet containers (e.g. Tomcat, Jetty)
- Application servers
- OSGi-based runtimes
- Other plugin-based architectures
In such environments, OkHttp may be loaded by a different classloader than the one
instrumented by the agent, causing the interception logic to be skipped or applied inconsistently.
#### Notes
- This agent targets OkHttp clients created in the main application classloader
- Behavior in multi-classloader environments is **undefined**
- This is a known limitation of the current implementation. Improved support for multi-classloader environments may be explored in the future.
For these reasons, this agent is intended for:
- Standalone applications
- CLI tools
- Test environments
- CI pipelines
and is **not recommended** for servlet-based or application-server deployments.
---
## Implementation notes
- Uses OkHttp's internal interceptor chain
- Does not modify sockets, TLS, or proxy settings
- Safe to use with shaded or relocated OkHttp dependencies
---
## Why not randomness?
This agent uses deterministic failure (N requests → 1 success)
instead of probability-based failure.
Reasons:
- Reproducible behavior
- Easier debugging
- More predictable tests
---
## License
MIT