Skip to content

Commit 578aea4

Browse files
bneradtbneradt
authored
.claude/CLAUDE.md (#12695)
This starts a .claude/CLAUDE.md file for guiding Claude.
1 parent 20b4cb2 commit 578aea4

File tree

2 files changed

+291
-0
lines changed

2 files changed

+291
-0
lines changed

‎.claude/CLAUDE.md‎

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Apache Traffic Server (ATS) is a high-performance HTTP/HTTPS caching proxy
8+
server written in C++20. It uses an event-driven, multi-threaded architecture
9+
with a sophisticated plugin system.
10+
11+
**Key Technologies:**
12+
- Language: C++20
13+
- Build System: CMake (migrated from autotools in v10)
14+
- Testing: Catch2 (unit tests) + AuTest Python framework (end-to-end tests)
15+
- Protocols: TLS, HTTP/1.1, HTTP/2, HTTP/3 (via Quiche)
16+
17+
## Build Commands
18+
19+
### Basic Build
20+
```bash
21+
# Configure (creates out-of-source build directory)
22+
cmake -B build
23+
24+
# Build everything
25+
cmake --build build
26+
27+
# Install (default: /usr/local)
28+
cmake --install build
29+
```
30+
31+
### Common Build Presets
32+
```bash
33+
# Development build with compile_commands.json for IDE support
34+
cmake --preset dev
35+
cmake --build build-dev
36+
37+
# Release build
38+
cmake --preset release
39+
cmake --build build-release
40+
41+
# Build with autests enabled
42+
cmake --preset ci-fedora-autest
43+
cmake --build build-autest
44+
```
45+
46+
### Useful Build Options
47+
```bash
48+
# Specify dependency locations (like autotools --with-*)
49+
cmake -B build -Djemalloc_ROOT=/opt/jemalloc -DOPENSSL_ROOT_DIR=/opt/boringssl
50+
51+
# Build specific targets
52+
cmake --build build -t traffic_server
53+
cmake --build build -t format # Format code before committing
54+
```
55+
56+
## Testing
57+
58+
### Unit Tests (Catch2)
59+
Built automatically with the project. Run via ctest:
60+
```bash
61+
ctest --test-dir build -j4
62+
```
63+
64+
### Running a Single Unit Test
65+
Unit tests are built into executables. Find the test binary and run it directly:
66+
```bash
67+
# Unit tests are typically in build/src/<component>/
68+
./build/src/tscore/test_tscore
69+
```
70+
71+
### End-to-End Tests (AuTest)
72+
73+
**Enable autests during configuration:**
74+
```bash
75+
cmake -B build -DENABLE_AUTEST=ON
76+
cmake --build build
77+
cmake --install build
78+
```
79+
80+
**Run all autests:**
81+
```bash
82+
cmake --build build -t autest
83+
```
84+
85+
**Run specific test(s):**
86+
```bash
87+
cd build/tests
88+
pipenv install # First time only
89+
./autest.sh --sandbox /tmp/sbcursor --clean=none -f <test_name_without_test_py>
90+
```
91+
92+
For example, to run `cache-auth.test.py`:
93+
```bash
94+
./autest.sh --sandbox /tmp/sbcursor --clean=none -f cache-auth
95+
```
96+
97+
The CI system publishes the following docker image in which the CI runs autests:
98+
99+
```
100+
ci.trafficserver.apache.org/ats/fedora:43
101+
```
102+
103+
The fedora version is updated regularly to the latest fedora release.
104+
105+
### Writing Autests
106+
107+
**New tests should use the `Test.ATSReplayTest()` approach**, which references a
108+
`replay.yaml` file that describes the test configuration and traffic patterns
109+
using the Proxy Verifier format. This is simpler, more maintainable, and
110+
parseable by tools.
111+
112+
**For complete details on writing autests, see:**
113+
- `doc/developer-guide/testing/autests.en.rst` - Comprehensive guide to ATSReplayTest
114+
- Proxy Verifier format: https://github.com/yahoo/proxy-verifier
115+
- AuTest framework: https://autestsuite.bitbucket.io/
116+
117+
## Development Workflow
118+
119+
### Code Formatting
120+
Always format code before committing:
121+
```bash
122+
cmake --build build -t format
123+
```
124+
125+
### Git Workflow
126+
- Branch off `master` for all PRs
127+
- PRs must pass all Jenkins CI jobs before merging
128+
- Use the GitHub PR workflow (not Jira)
129+
- Set appropriate labels: **Backport**, **WIP**, etc.
130+
131+
### Commit Message Format
132+
When Claude Code creates commits, start with a short summary line, use concise
133+
description (1-3 sentences) that focus on "why" rather than "what". If the PR
134+
fixes an issue, add a 'Fixes: #<issue_number>' line.
135+
136+
## Architecture Overview
137+
138+
### Core Components
139+
140+
**I/O Core (`src/iocore/`):**
141+
- `eventsystem/` - Event-driven engine (Continuations, Events, Processors)
142+
- `cache/` - Disk and RAM cache implementation
143+
- `net/` - Network layer with TLS and QUIC support
144+
- `dns/` - Asynchronous DNS resolution
145+
- `hostdb/` - Internal DNS cache
146+
- `aio/` - Asynchronous I/O
147+
148+
**Proxy Logic (`src/proxy/`):**
149+
- `http/` - HTTP/1.1 protocol implementation
150+
- `http2/` - HTTP/2 support
151+
- `http3/` - HTTP/3 implementation
152+
- `hdrs/` - Header parsing and management
153+
- `logging/` - Flexible logging system
154+
- `http/remap/` - URL remapping and routing
155+
156+
**Management (`src/mgmt/`):**
157+
- JSONRPC server for runtime configuration and management
158+
- Configuration file parsing and validation
159+
160+
**Base Libraries (`src/`):**
161+
- `tscore/` - Core utilities and data structures
162+
- `api/` - Plugin API implementation
163+
- `tscpp/api/` - C++ API wrapper for plugins
164+
165+
### Event-Driven Architecture
166+
167+
ATS uses a **Continuation-based** programming model:
168+
- All async operations use Continuations (callback objects)
169+
- Events are dispatched through an event system
170+
- Multiple thread pools handle different event types
171+
- Non-blocking I/O throughout
172+
173+
### Configuration Files
174+
175+
Primary configs (installed to `/etc/trafficserver/` by default):
176+
- `records.yaml` - Main configuration (formerly records.config)
177+
- `remap.config` - URL remapping rules
178+
- `plugin.config` - Plugin loading configuration
179+
- `ip_allow.yaml` - IP access control
180+
- `ssl_multicert.config` - TLS certificate configuration
181+
- `sni.yaml` - SNI-based routing
182+
- `storage.config` - Cache storage configuration
183+
184+
Configuration can be modified at runtime via:
185+
- `traffic_ctl config reload` (for some settings)
186+
- JSONRPC API
187+
188+
## Plugin Development
189+
190+
### Plugin Types
191+
- **Global plugins** - Loaded in `plugin.config`, affect all requests
192+
- **Remap plugins** - Loaded per remap rule, affect specific mapped requests
193+
194+
### Key Plugin APIs
195+
Headers in `include/ts/`:
196+
- `ts.h` - Main plugin API
197+
- `remap.h` - Remap plugin API
198+
- `InkAPIPrivateIOCore.h` - Advanced internal APIs
199+
200+
### Plugin Hooks
201+
Plugins register callbacks at various points in request processing:
202+
- `TS_HTTP_READ_REQUEST_HDR_HOOK`
203+
- `TS_HTTP_SEND_REQUEST_HDR_HOOK`
204+
- `TS_HTTP_READ_RESPONSE_HDR_HOOK`
205+
- `TS_HTTP_SEND_RESPONSE_HDR_HOOK`
206+
- Many more (see `ts.h`)
207+
208+
### Example Plugins
209+
- `example/plugins/` - Simple example plugins
210+
- `plugins/` - Stable core plugins
211+
- `plugins/experimental/` - Experimental plugins
212+
213+
## Common Development Patterns
214+
215+
### When Modifying HTTP Processing
216+
1. Understand the state machine: `src/proxy/http/HttpSM.cc` - HTTP State Machine
217+
2. Hook into the appropriate stage via plugin hooks or core modification
218+
3. Use `HttpTxn` objects to access transaction state
219+
4. Headers are accessed via `HDRHandle` and field APIs
220+
221+
### When Adding Configuration
222+
1. Define record in `src/records/RecordsConfig.cc`
223+
2. Add validation if needed
224+
3. Update documentation in `doc/admin-guide/`
225+
4. Configuration can be read via `REC_` APIs
226+
227+
### When Working with Cache
228+
- Cache is content-addressable, keyed by URL (modifiable via plugins)
229+
- Cache operations are async, continuation-based
230+
- Cache has RAM and disk tiers
231+
- Cache code is in `src/iocore/cache/`
232+
233+
### When Debugging
234+
1. Enable debug tags in `records.yaml`:
235+
```yaml
236+
proxy.config.diags.debug.enabled: 1
237+
proxy.config.diags.debug.tags: http|cache
238+
```
239+
2. Check logs in `/var/log/trafficserver/`:
240+
- `diags.log` - Debug output
241+
- `error.log` - Errors and warnings
242+
3. Use `traffic_top` for live statistics
243+
4. Use `traffic_ctl` for runtime inspection
244+
245+
## Important Conventions
246+
247+
### License Headers
248+
- Always add Apache License 2.0 headers to the top of new source and test files
249+
- This includes `.cc`, `.h`, `.py`, and other code files
250+
- Follow the existing license header format used in the codebase
251+
252+
### Code Style
253+
- C++20 standard
254+
- Use RAII principles
255+
- Prefer smart pointers for ownership
256+
- Run `cmake --build build -t format` before committing
257+
258+
### Memory Management
259+
- Custom allocators supported (jemalloc, mimalloc)
260+
- Use `ats_malloc` family for large allocations
261+
- IOBuffers for network data (zero-copy where possible)
262+
263+
### Threading
264+
- Event threads handle most work
265+
- DNS has dedicated threads
266+
- Disk I/O uses thread pool
267+
- Most code should be async/event-driven, not thread-based
268+
269+
### Error Handling
270+
- Return error codes for recoverable errors
271+
- Use `ink_release_assert` for unrecoverable errors
272+
- Log errors appropriately (ERROR vs WARNING vs NOTE)
273+
274+
## Key Files for Understanding Architecture
275+
276+
- `include/iocore/eventsystem/Continuation.h` - Core async pattern
277+
- `src/proxy/http/HttpSM.cc` - HTTP request state machine
278+
- `src/iocore/net/UnixNetVConnection.cc` - Network connection handling
279+
- `src/iocore/cache/Cache.cc` - Cache implementation
280+
- `src/proxy/http/remap/RemapConfig.cc` - URL remapping logic
281+
- `include/ts/ts.h` - Plugin API
282+
283+
## Resources
284+
285+
- Official docs: https://trafficserver.apache.org/
286+
- Developer wiki: https://cwiki.apache.org/confluence/display/TS/
287+
- CI dashboard: https://ci.trafficserver.apache.org/
288+
- AuTest framework: https://autestsuite.bitbucket.io/
289+
- Proxy Verifier: https://github.com/yahoo/proxy-verifier

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,3 +208,5 @@ tests/gold_tests/tls/ssl-post
208208

209209
src/iocore/cache/test_*
210210
src/iocore/cache/unit_tests/var/trafficserver/cache.db
211+
212+
.claude/settings.local.json

0 commit comments

Comments
 (0)