|
| 1 | +# Agent Instructions |
| 2 | + |
| 3 | +## Commands |
| 4 | + |
| 5 | +```bash |
| 6 | +go test ./... # run all tests |
| 7 | +golangci-lint run # lint (CI uses golangci-lint-action) |
| 8 | +mockery # regenerate mocks (committed as mock_UserliService.go) |
| 9 | +``` |
| 10 | + |
| 11 | +CI runs: lint → test (with coverage) → goreleaser snapshot build. No required local order. |
| 12 | + |
| 13 | +## Architecture |
| 14 | + |
| 15 | +Single-package `main` app — all `.go` files live in the repo root, no `cmd/` or `internal/`. |
| 16 | + |
| 17 | +Key abstraction: `ConnectionHandler` interface in `tcpserver.go` — both `LookupServer` and `PolicyServer` implement it; `StartTCPServer()` provides shared connection pooling, graceful shutdown, and metrics. |
| 18 | + |
| 19 | +## Design Constraints |
| 20 | + |
| 21 | +- **Fail-open**: API errors must return `DUNNO`/allow and never block mail delivery |
| 22 | +- **No PII in metrics**: aggregate counters only, no email addresses in Prometheus labels |
| 23 | +- Never store `context.Context` in structs — pass through function parameters |
| 24 | + |
| 25 | +## Protocols |
| 26 | + |
| 27 | +Socketmap (lookup): netstring-encoded `<len>:<mapname> <key>,` → `<len>:<status> <data>,` |
| 28 | +Responses: `OK <data>`, `NOTFOUND`, `TEMP <msg>`, `PERM <msg>` |
| 29 | + |
| 30 | +Policy delegation: `name=value\n` pairs, empty line terminates → `action=ACTION\n\n` |
| 31 | +Only process at `protocol_state=END-OF-MESSAGE` for accurate counting. |
| 32 | + |
| 33 | +## Pitfalls |
| 34 | + |
| 35 | +- `USERLI_TOKEN` is required — app exits immediately if missing |
| 36 | +- Rate limiter cleanup runs every 5 minutes in a background goroutine |
| 37 | +- Socketmap names must match exactly: `alias`, `domain`, `mailbox`, `senders` |
| 38 | + |
| 39 | +## Docker Development |
| 40 | + |
| 41 | +```bash |
| 42 | +cp .env.example .env |
| 43 | +docker compose up |
| 44 | +docker compose exec userli bin/console doctrine:schema:create |
| 45 | +docker compose exec userli bin/console doctrine:fixtures:load --no-debug |
| 46 | +``` |
| 47 | + |
| 48 | +Fixtures must be loaded manually after first start. |
| 49 | + |
| 50 | +## Commits |
| 51 | + |
| 52 | +- **Gitmoji** style: e.g., `:sparkles: Add feature`, `:bug: Fix rate limiter`, `:recycle: Refactor server` |
| 53 | +- Add `Co-Authored-By: OpenCode <noreply@opencode.ai>` to the commit message |
| 54 | + |
| 55 | +## Pull Requests |
| 56 | + |
| 57 | +- Open as **draft** |
| 58 | +- Write description in English |
| 59 | +- Label PRs for release-drafter: |
| 60 | + - `feature` (major), `enhancement` (minor) |
| 61 | + - `fix` / `bugfix` / `bug` (patch) |
| 62 | + - `chore` / `dependencies` (patch, maintenance) |
0 commit comments