diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..d2170d47a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,179 @@ +# AsyncHttpClient - AI Agent Guidelines + +Guidelines for AI agents contributing to this repository. + +## Project Information + +* Java baseline is JDK 11. All code must compile and run on JDK 11. Source and target are defined in the root `pom.xml`. +* CI runs on Amazon Corretto JDK 11, 17, 21 and 25 across Linux, macOS and Windows. +* Maven MUST always be invoked through the Maven Wrapper. Use `./mvnw` on Linux and macOS and `mvnw.cmd` on Windows. Do not use a system Maven installation. + +## AI Agent Requirements + +These requirements apply to all AI agents working on this repository. + +### Attribution + +* All AI-generated commits and pull requests MUST clearly identify the AI agent and the human operator. +* Use the format ` on behalf of `. +* Example: `Claude Code on behalf of Alice Smith`. +* Every AI-generated commit MUST include a `Co-Authored-By` trailer for the AI agent. + +### Git + +* Work in topic branches with descriptive names. Never commit directly to `main`. +* Never force-push shared branches. +* Never rewrite repository history unless explicitly instructed. +* Never start a commit message with `[maven-release-plugin]`. The release workflow treats that prefix as release automation. + +### Issues and Pull Requests + +* Use GitHub Issues for bugs and feature requests. Use GitHub Discussions for questions. +* Before implementing a bug fix: + * Reproduce the issue. + * Inspect `git log` and `git blame` for the affected files. + * Search existing issues and pull requests. + * Confirm the change does not revert earlier intentional work. +* Keep pull requests small and focused. One logical change per pull request. +* Do not combine unrelated fixes, refactorings or formatting changes. + +### Testing Gate - Hard Requirement + +Before pushing any commit or opening a pull request, run: + +```sh +./mvnw clean verify +``` + +Requirements: + +* The command MUST be run on JDK 11. +* The build MUST complete successfully. +* Do not disable, skip or weaken tests to obtain a passing build. + +## Build + +Common commands: + +```sh +# Full verification +./mvnw clean verify + +# Compile and API compatibility check only +./mvnw -B -ntp clean verify -DskipTests -Dgpg.skip=true + +# Run a single test class +./mvnw test -Dtest=BasicHttpTest + +# Run a single test method +./mvnw test -Dtest=BasicHttpTest#testMethodName +``` + +### Build Notes + +* Error Prone and NullAway run during compilation. Nullability violations in production code under `org.asynchttpclient` fail the build. +* Respect the JetBrains `@Nullable` and `@NotNull` annotations. Test sources are excluded from NullAway checks. +* Revapi runs during the `verify` phase and compares the public API against the latest release on Maven Central. Treat API compatibility failures as intentional feedback, not build noise. + +## Repository Layout + +* `pom.xml` - parent and aggregator POM +* `client` + + * `src/main/java/org/asynchttpclient` - production sources + * `src/test/java` - test sources + * `src/jmh/java` - JMH benchmarks +* `docs` - design documentation +* `.github/workflows` - CI workflows + +## Testing + +* Use JUnit 5 only. +* Test classes must end with the `Test` suffix and mirror the production package structure. +* Extend `AbstractBasicTest` for tests requiring an embedded Jetty server. +* Extend `AbstractBasicWebSocketTest` for WebSocket tests. +* Never use `Thread.sleep()` for synchronization. Use futures, latches or timeouts. +* Mark known flaky tests with `@RepeatedIfExceptionsTest` instead of `@Test`. +* Do not leak Netty `ByteBuf` instances. The leak detector extension will fail the test. +* Keep the default test suite hermetic. +* Tests requiring public hosts must be tagged `external`. +* Docker-based integration tests must follow the existing Testcontainers gating properties. + +## Coding Conventions + +* Use four spaces for indentation. Never use tabs. +* Files are UTF-8 encoded, but repository content MUST use ASCII characters only. +* Do not use wildcard imports. +* Preserve the surrounding coding style. +* Keep diffs as small as practical. +* Avoid unrelated formatting changes. + +Every new Java file MUST begin with the repository license header: + +```java +/* + * Copyright (c) 2026 AsyncHttpClient Project. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +``` + +## Comments + +* Keep comments minimal. +* Add comments only to explain constraints, invariants or non-obvious reasoning that the code itself cannot express. +* Match the comment density of the surrounding file. +* Do not add comments describing a code change or addressing reviewers. + +## Commit Messages + +Commit messages MUST contain: + +* An imperative summary line of at most 50 characters. +* A blank line. +* A body wrapped at 72 characters explaining why the change was made, not only what changed. +* A reference to the GitHub issue when applicable. +* The required AI attribution trailer. + +## API Compatibility + +* Public API changes MUST be intentional. +* Do not introduce, remove or modify public API unless it is the explicit goal of the change. +* Treat Revapi failures as design feedback rather than something to work around. + +## Security + +Treat all network input as hostile. + +Pay particular attention to: + +* URI parsing and normalization. +* Header values and CRLF injection. +* Request smuggling. +* Credential and `Realm` handling, especially across redirects and origins. +* Proxy and CONNECT handling. +* TLS configuration and hostname verification. +* Decompression limits and memory usage. +* Cookie parsing and storage. + +## Knowledge Verification + +* Do not make factual claims about external projects or dependency versions from memory. +* Verify dependency information against the repository and Maven Central before making assertions. +* When uncertain, state that uncertainty instead of guessing. + +## Links + +* `https://github.com/AsyncHttpClient/async-http-client` +* `https://github.com/AsyncHttpClient/async-http-client/issues` +* `https://github.com/AsyncHttpClient/async-http-client/discussions`