AGENTS.md

1# Agent Guidelines (Ktor)
2 
3This file is the primary playbook for agentic coding tools working in this repository.
4 
5## Critical Workflow Rule
6 
7**NEVER return control to the user without ensuring:**
81. Tests pass: `./gradlew :module-name:jvmTest` (and other platforms if touched)
92. Code compiles: `./gradlew :module-name:assemble`
103. Code is formatted and linting passes: run `./gradlew :module-name:formatKotlin`, then `./gradlew :module-name:lintKotlin`
114. ABI validated: `./gradlew :module-name:updateKotlinAbi` (if public/protected API changed)
12 
13Prefer this order to fail fast.
14Always prefer **module-specific** commands (`:module-name:task`) over project-wide commands.
15 
16## Project Requirements
17 
18- JDK 21 is required.
19- Kotlin Multiplatform: JVM, JS, Native.
20- Apple targets require Xcode + command line tools.
21- Android targets are optional and enabled when Android SDK is available (`ANDROID_HOME` or `local.properties` `sdk.dir`).
22 
23## Project Layout
24 
25### Gradle module structure (flattened)
26The project uses a **flattened Gradle structure** (see `settings.gradle.kts`). Nested directory paths do NOT translate to nested Gradle project names.
27Example: `ktor-client/ktor-client-curl` → `:ktor-client-curl` (not `:ktor-client:ktor-client-curl`).
28 
29### Source set layout (platform-centric)
30Kotlin Multiplatform sources use a flattened, platform-centric layout (do not re-introduce `src/<platform>Main/...`).
31 
32```text
33common/src
34jvm/src
35jvm/resources
36jvm/test
37jvm/test-resources
38...
39```
40 
41Build logic enforces "no surprise source sets": manually registering extra source sets is rejected.
42To add a new target/source set, add the directory or enable the target via `gradle.properties` (`target.<name>=true`).
43 
44## Build Commands
45 
46**Important**: Always prefer running tasks on the specific module you touched, not the entire project.
47 
48### Common tasks
49```bash
50./gradlew :module-name:assemble          # Build the module
51```
52 
53Run tests:
54```bash
55./gradlew :module-name:jvmTest           # Run JVM tests for the module
56./gradlew :module-name:allTests          # Run tests across all platforms for the module
57./gradlew :module-name:jvmTest --tests &quot;fully.qualified.TestClassName&quot; # Run a specific test
58./gradlew :module-name:jvmTest --tests &quot;fully.qualified.TestClassName.methodName&quot; # Run a specific test method
59```
60 
61Linting:
62```bash
63./gradlew :module-name:formatKotlin      # Format the module
64./gradlew :module-name:lintKotlin        # Lint the module
65```
66 
67## Code Style Guidelines
68 
69### Formatting (EditorConfig is authoritative)
70- Kotlin style: IntelliJ + `KOTLIN_OFFICIAL` (`.editorconfig`).
71- Indent: 4 spaces (JSON/YAML: 2); max line length: 120; end of line: LF.
72- Use `./gradlew :module-name:formatKotlin` rather than manual formatting.
73 
74### Imports
75- Star imports are preferred for `io.ktor.*` (configured in `.editorconfig`).
76 
77### Naming
78- Follow Kotlin conventions unless the surrounding package has a strong established pattern.
79- Tests: prefer descriptive test names in backticks: `describe what is being tested`.
80 
81### Types and API design
82- Prefer `internal` by default; keep the public surface intentional.
83- Public API requires KDoc (parameters, return, and notable exceptions).
84- Public-but-not-for-users APIs that cannot be `internal` should use `@InternalAPI`.
85- Keep `@OptIn(...)` scope minimal.
86- All types used as receivers in DSL should be annotated with `@KtorDsl` (for example, all plugin configs).
87 
88### Error handling
89- `require(...)` for argument validation, `check(...)` for state validation, `error("...")` for unreachable states.
90- Throw specific exceptions appropriate to the layer (IO parsing: `IOException`/`EOFException`; validation: Ktor exceptions like `BadRequestException`).
91- Make error messages actionable; include the problematic value/context.
92 
93### Logging
94- Prefer Ktor log helpers where present.
95- Avoid noisy logs in hot paths.
96 
97### Documentation and comments
98- Avoid redundant comments; add them only for tricky invariants or platform-specific behavior.
99- Keep KDoc correct when behavior/signatures change.
100- New source files must include the repository copyright header.
101 
102## Development Practices
103 
104- Prefer TDD where feasible: add/adjust tests, then implement.
105- For multiplatform changes: start JVM-first unless the task requires another platform.
106- Keep local-only build knobs (for example, developer `gradle.properties` overrides) out of commits.
107- If asked to create commits: use imperative mood and include `KTOR-<NUM>` when there is a related YouTrack issue.
108 
109### Adding or removing modules
110 
111- Module names must start with `ktor-`.
112- The project uses a flattened Gradle structure with custom DSL in `settings.gradle.kts` (see Project Layout section).
113- When modules are added/removed or new targets enabled, run `./update-artifact-dumps.sh` to update published artifact lists in `gradle/artifacts`.
114  Publishing will fail if these dumps are stale.
115 
116## Binary Compatibility and ABI Validation
117 
118Binary compatibility is **enforced** using Kotlin Gradle Plugin ABI validation.
119All public API changes must be tracked in `/api/` directories within modules.
120 
121### Release branches and API policy
122 
123- Patch releases are maintained in `release/<major>.x` (for example, v3 uses `release/3.x`, v4 uses `release/4.x`).
124- The next minor release is developed on `main`.
125- Public API changes are allowed only for minor/major releases (typically on `main`), not for patch releases (on `release/<major>.x`).
126- Breaking changes are **only allowed in major version releases**.
127- The repo includes an interactive helper `./switch-base-branch.sh` for switching a feature branch base between `main` and `release/<major>.x`.
128  For agents: use `--dry-run` to print the git commands, then run them after user approval.
129 
130### Validation commands
131```bash
132./gradlew :module-name:checkKotlinAbi    # Validate ABI compatibility
133./gradlew :module-name:updateKotlinAbi   # Update ABI signature files after changes
134```
135 
136### Rules
137- **All** `public`/`protected` API changes require updating `api/*.api` dumps.
138- API changes must be **intentional and well-documented**.
139