AGENTS.md@src/servers · diff
git:20261012.f50f421 to git:20261013.863eebd
3 added, 0 removed. Audit A to A.
# servers — Agent & Contributor Guide
Navigation map for `src/servers`. Repo-wide invariants:
[`.agents/architecture-invariants.md`](../../.agents/architecture-invariants.md).
`servers` owns network listeners and protocol translation. Database behavior is
provided through handler traits, mostly implemented by `frontend`.
## Module map
| Area | Path | Entry point |
| --- | --- | --- |
| Lifecycle | `src/servers/src/server.rs` | Shared `Server` trait |
| Handler boundary | `src/servers/src/query_handler.rs`, `src/servers/src/query_handler/` | Protocol-independent handler traits |
| gRPC / Flight | `src/servers/src/grpc.rs`, `src/servers/src/grpc/` | gRPC services, auth, cancellation, builders |
| HTTP | `src/servers/src/http.rs`, `src/servers/src/http/` | Routes, middleware, protocol endpoints, output formats |
| SQL protocols | `src/servers/src/mysql.rs`, `src/servers/src/mysql/`, `src/servers/src/postgres.rs`, `src/servers/src/postgres/` | MySQL/PostgreSQL servers and type conversion |
| Observability protocols | `src/servers/src/prom_remote_write/`, `src/servers/src/prometheus.rs`, `src/servers/src/otlp/`, `src/servers/src/otel_arrow.rs` | Prometheus and OpenTelemetry conversion |
| Resources / TLS | `src/servers/src/request_memory_limiter.rs`, `src/servers/src/tls.rs`, `src/servers/src/addrs.rs` | Memory admission, TLS, listener addresses |
## Change coupling
- Handler trait changes require matching frontend and mock implementations.
- gRPC wire changes start in `greptime-proto`; update builders and handlers here
after bumping it.
- Auth or `QueryContext` changes must cover HTTP, gRPC, MySQL, and PostgreSQL
entry points.
- Internal frontend gRPC listeners set `Channel::Internal` in server-owned request
extensions. Handlers preserve it through query execution and metering; client
flow metadata does not grant an internal channel.
- Finite requests split by wire handlers (Prometheus batching and OpenTSDB
summary/details) admit all rows before dispatch. Admission is process-local
`QueryContext` state; never accept it from headers or serialized contexts.
- New protocols or externally visible routes also require frontend service and
configuration wiring.
## Testing
```bash
cargo nextest run -p servers
```
Keep protocol translation here and permissions/database behavior in frontend.
Async table batching returns storage-completion futures with its early
acknowledgements. Keep completion reporting independent of the caller's lifetime.
+ Logical-table physical flushes retain partition columns in Arrow RPC payloads and
+ pass all region writes to the operator write dispatcher together; the dispatcher
+ owns peer resolution and retries. See `batcher/logical_table/region_write.rs`.
`prom_remote_write/decode.rs` and `benches/prom_decode.rs` resolve
`benches/write_request.pb.data` using `CARGO_MANIFEST_DIR` at **run time**
(`std::env::var`, not `env!`). `cargo nextest run` and `cargo bench` set it;
direct test/benchmark-binary execution requires setting it to the crate directory.
Run this example from the repository root:
```bash
CARGO_MANIFEST_DIR="$PWD/src/servers" ./target/debug/deps/<test_or_bench_binary>
```