Files
greptimedb/src/servers/AGENTS.md
T

3.8 KiB

servers — Agent & Contributor Guide

Navigation map for src/servers. Repo-wide invariants: .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
Exemplars src/servers/src/exemplar/, src/servers/src/exemplar.rs, src/servers/src/http/prom_store/exemplar.rs Shared row contract, millisecond query API, completion-aware metric/exemplar writes
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.
  • A protocol handler that changes the QueryContext catalog or schema after authentication (HTTP db query/form parameters, MySQL COM_INIT_DB) calls UserProvider::authorize for the new scope before mutating the context. The HTTP middleware authorizes only the scope it extracts itself (extract_catalog_and_schema in http/authorize.rs).
  • 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

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. Remote-write v2 keeps decoder reservations and per-request progress through queued writes; error responses drain those writes before reporting partial counts. 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:

CARGO_MANIFEST_DIR="$PWD/src/servers" ./target/debug/deps/<test_or_bench_binary>