|
| 1 | +# AGENTS |
| 2 | + |
| 3 | +This file is the local operating guide for agents working in this repository. |
| 4 | +It focuses on two things: |
| 5 | + |
| 6 | +- how the Monkey source tree is organized |
| 7 | +- how commits are written in the existing Git history |
| 8 | + |
| 9 | +## Repository map |
| 10 | + |
| 11 | +Monkey is a small HTTP server written in C. The tree is split by subsystem. |
| 12 | + |
| 13 | +- `mk_core/` |
| 14 | + Core utilities used by the server and plugins. |
| 15 | + Includes memory helpers, strings, files, thread helpers, event loops, |
| 16 | + I/O vectors, config parsing, and generic utilities. |
| 17 | + |
| 18 | +- `mk_server/` |
| 19 | + The HTTP server implementation. |
| 20 | + This is where connection handling, request parsing, header generation, |
| 21 | + virtual hosts, MIME resolution, scheduler integration, streams, plugins, |
| 22 | + and server lifecycle live. |
| 23 | + |
| 24 | +- `mk_bin/` |
| 25 | + The standalone `monkey` executable entrypoints and signal handling. |
| 26 | + |
| 27 | +- `include/monkey/` |
| 28 | + Public and internal headers for the core, server, parser, plugins, |
| 29 | + config, events, streams, and API types. |
| 30 | + |
| 31 | +- `plugins/` |
| 32 | + Optional server features. |
| 33 | + Examples in this tree include `liana`, `mandril`, `dirlisting`, `cgi`, |
| 34 | + `fastcgi`, `auth`, `logger`, `tls`, and `cheetah`. |
| 35 | + |
| 36 | +- `api/` |
| 37 | + Small API-focused programs and tests. |
| 38 | + |
| 39 | +- `test/` |
| 40 | + Native unit/integration-style test targets used by CMake. |
| 41 | + |
| 42 | +- `fuzz/` |
| 43 | + Fuzzing entrypoints and helpers for parser and request handling. |
| 44 | + |
| 45 | +- `conf/` |
| 46 | + Config templates installed or copied at build/install time. |
| 47 | + |
| 48 | +- `htdocs/` |
| 49 | + Default static site content used by the standalone server. |
| 50 | + |
| 51 | +- `cmake/` |
| 52 | + CMake helper modules and build logic. |
| 53 | + |
| 54 | +- `deps/` |
| 55 | + Bundled third-party dependencies such as regex, rbtree, libco, |
| 56 | + and mbedtls sources. |
| 57 | + |
| 58 | +- `qa/` |
| 59 | + Extra request fixtures and local QA artifacts. |
| 60 | + |
| 61 | +## Main runtime flow |
| 62 | + |
| 63 | +When debugging behavior, the usual path is: |
| 64 | + |
| 65 | +1. `mk_bin/monkey.c` |
| 66 | + Starts the binary. |
| 67 | +2. `mk_server/monkey.c`, `mk_server/mk_server.c` |
| 68 | + Initializes the server and worker threads. |
| 69 | +3. `mk_server/mk_scheduler.c` |
| 70 | + Drives socket events into protocol handlers. |
| 71 | +4. `mk_server/mk_http.c` |
| 72 | + Owns HTTP session lifecycle, request preparation, response handling, |
| 73 | + range parsing, file serving, keepalive, and teardown. |
| 74 | +5. `mk_server/mk_http_parser.c` |
| 75 | + Parses the request line, headers, body state, and chunked transfer coding. |
| 76 | +6. `mk_server/mk_header.c`, `mk_server/mk_stream.c` |
| 77 | + Build and send responses. |
| 78 | + |
| 79 | +Useful supporting code: |
| 80 | + |
| 81 | +- `mk_server/mk_vhost.c` |
| 82 | + Virtual host lookup, per-vhost file descriptor table. |
| 83 | +- `mk_server/mk_mimetype.c` |
| 84 | + File extension to MIME mapping. |
| 85 | +- `mk_server/mk_user.c` |
| 86 | + `~user` URI handling. |
| 87 | +- `mk_server/mk_plugin.c` |
| 88 | + Plugin registration and API exposure. |
| 89 | +- `mk_core/mk_event_*.c` |
| 90 | + Backend-specific event loop implementations. |
| 91 | + |
| 92 | +## Build and verification |
| 93 | + |
| 94 | +Typical local build entrypoint: |
| 95 | + |
| 96 | +```bash |
| 97 | +cmake --build build |
| 98 | +``` |
| 99 | + |
| 100 | +If a fresh build tree is needed, inspect `CMakeLists.txt` and the generated |
| 101 | +`build/` layout before changing build flags. The project currently requires |
| 102 | +CMake 3.20 and produces `build/bin/monkey`. |
| 103 | + |
| 104 | +## Commit style used in this repository |
| 105 | + |
| 106 | +Follow the existing Git history, not the older wording in `CONTRIBUTING.md`. |
| 107 | + |
| 108 | +### Subject format |
| 109 | + |
| 110 | +Use a short, lowercase, scope-prefixed subject. The common patterns are: |
| 111 | + |
| 112 | +- `build: bump to v1.8.7` |
| 113 | +- `server: clean thread destroy on worker loop exit` |
| 114 | +- `server: http: move initialization of request headers to request init` |
| 115 | +- `core: event: Plug descriptor leaks in an error case.` |
| 116 | +- `parser: fixed header loss issue caused by duplicated headers` |
| 117 | +- `logger: set log file permissions to 0600, closes CVE-2013-1771 (#413)` |
| 118 | + |
| 119 | +### Prefix rules |
| 120 | + |
| 121 | +Pick the narrowest stable prefix that matches the area being changed. |
| 122 | + |
| 123 | +- `build:` for version bumps, CMake, workflows, packaging |
| 124 | +- `core:` for `mk_core/` functionality |
| 125 | +- `server:` for `mk_server/` functionality |
| 126 | +- `server: http:` for `mk_server/mk_http.c` and closely related request flow |
| 127 | +- `server: parser:` or `server: http_parser:` for parser-specific work |
| 128 | +- `plugin:` or a plugin-specific prefix when the change is isolated there |
| 129 | +- `test:` for tests |
| 130 | +- `logger:`, `scheduler:`, `mimetype:`, `config:` when the change is clearly |
| 131 | + isolated to that subsystem and history already uses that style |
| 132 | +- backend-specific prefixes like `mk_event_kqueue:` are acceptable when the |
| 133 | + change is narrow and entirely local to that backend |
| 134 | + |
| 135 | +### Subject style rules |
| 136 | + |
| 137 | +- keep it concise |
| 138 | +- prefer lowercase after the prefix |
| 139 | +- use colon-separated scopes, not bracket tags |
| 140 | +- do not invent long marketing titles |
| 141 | +- keep the subject under 80 characters |
| 142 | +- match existing nouns already used in history where possible |
| 143 | + |
| 144 | +Good examples for this tree: |
| 145 | + |
| 146 | +- `server: http: reject malformed range delimiters` |
| 147 | +- `server: http: avoid reusing invalid request state` |
| 148 | +- `server: parser: validate chunk length tokens strictly` |
| 149 | +- `core: memory: handle null mk_ptr_to_buf input` |
| 150 | + |
| 151 | +Bad examples for this tree: |
| 152 | + |
| 153 | +- `Fix CVEs` |
| 154 | +- `Monkey: important security fixes` |
| 155 | +- `HTTP: Add Various Improvements` |
| 156 | +- `misc: cleanup` |
| 157 | + |
| 158 | +## Commit body rules |
| 159 | + |
| 160 | +The older contribution guide still applies well here. |
| 161 | + |
| 162 | +- include a body for non-trivial changes |
| 163 | +- wrap body lines at about 80 columns |
| 164 | +- explain the bug, the fix, and any verification done |
| 165 | +- if the change is security-related, describe the faulty path precisely |
| 166 | +- if multiple root causes exist, prefer separate commits |
| 167 | + |
| 168 | +When I am asked to commit in this repository, default behavior should be: |
| 169 | + |
| 170 | +1. split unrelated changes into separate commits |
| 171 | +2. choose the narrowest prefix from the existing history |
| 172 | +3. write a short lowercase subject |
| 173 | +4. add a body for anything beyond trivial cleanup |
| 174 | +5. use `git commit -s` unless the user explicitly asks otherwise |
| 175 | + |
| 176 | +## Working rules for this repository |
| 177 | + |
| 178 | +- Do not touch unrelated untracked files in the worktree. |
| 179 | +- Be careful around parser and request lifecycle code. Many bugs surface later |
| 180 | + in teardown, not at the first invalid input. |
| 181 | +- Prefer minimal targeted fixes over broad refactors unless requested. |
| 182 | +- When a bug crosses files, still group the commit by root cause, not by file. |
| 183 | +- For security fixes, verify behavior on the built binary, not only by code |
| 184 | + inspection. |
0 commit comments