mirror of https://github.com/GreptimeTeam/greptimedb.git synced 2026-08-23 06:28:27 +00:00

Files

T

dennis zhuang 3b8f55e490 docs(agents): add per-crate guides, architecture invariants, and generated-files list (#8346 )

* docs(agents): add per-crate guides, architecture invariants, and generated-files list

Add agent/contributor navigation docs modeled on the AGENTS.md convention:

- Per-crate AGENTS.md for hot crates (mito2, metric-engine, flow, frontend,
  meta-srv): module map, read/write paths, change-coupling points, test
  commands, and gotchas.
- .agents/architecture-invariants.md: repo-wide rules that clippy and the
  style guide do not cover (format compatibility, crate layering, async
  runtimes, error handling, experimental gating, the DataFusion fork).
- .agents/generated-files.md: tool-generated artifacts that must not be
  hand-edited (sqlness .result, config.md, dashboards, build.rs output, proto).
- Anchor the .gitignore CLAUDE.md/AGENTS.md rules to the repo root so per-crate
  AGENTS.md files are tracked while root-level personal config stays ignored.

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

* chore: update crate AGENTS.md and fix config.md path

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

* docs(agents): fix DataFusion patch layout and SQL query lifecycle order

Address review feedback on #8346:

- architecture-invariants: the DataFusion sub-crates pin an exact crates.io
  version in [workspace.dependencies] and are redirected to the fork rev in
  [patch.crates-io]; the two sections hold different forms, not the same rev.
- frontend: the SQL query lifecycle runs the pre_parsing/post_parsing
  interceptors around parsing, before the per-statement permission check.

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

---------

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

2026-06-24 09:14:09 +00:00

4.2 KiB

Raw Blame History

frontend — Agent & Contributor Guide

Navigation aid for src/frontend. Keep it short and point to code. Paths are relative to the repo root.

Repo-wide rules that apply here: .agents/architecture-invariants.md.

What this crate does

Frontend is the request entry point and orchestration layer. It accepts multi-protocol requests (gRPC, HTTP, MySQL, PostgreSQL, InfluxDB, OTLP, Jaeger, Prometheus, OpenTSDB), checks permissions, parses/plans SQL, and dispatches: reads go to the query engine (query crate), writes go to the inserter/deleter (operator crate).

Boundary with servers: the servers crate implements the wire protocols and network I/O; frontend provides the business logic by implementing handler traits (SqlQueryHandler, GrpcQueryHandler, InfluxdbLineProtocolHandler, ...). In standalone mode the frontend embeds a datanode RegionServer; in distributed mode it talks to remote datanodes via operator/client.

Module map

Module	Path	Purpose
`instance`	`src/frontend/src/instance.rs`	`Instance`: the core handler; implements `SqlQueryHandler`, `PrometheusHandler`, etc.
`instance/builder`	`src/frontend/src/instance/builder.rs`	`FrontendBuilder` assembles `Instance` from its dependencies
`instance/grpc`	`src/frontend/src/instance/grpc.rs`	`GrpcQueryHandler`: insert/delete/query/promql over gRPC
`instance/standalone`	`src/frontend/src/instance/standalone.rs`	Calls the local `RegionServer` instead of RPC
`instance/region_query`	`src/frontend/src/instance/region_query.rs`	Routes distributed region reads to datanodes
`instance/*`	`src/frontend/src/instance/`	Per-protocol handlers (`influxdb.rs`, `promql.rs`, `otlp/`, `jaeger.rs`, `logs.rs`, `prom_store.rs`, ...)
`frontend`	`src/frontend/src/frontend.rs`	`Frontend` lifecycle wrapper (`FrontendOptions`, start/shutdown)
`server`	`src/frontend/src/server.rs`	`Services`: builds and wires the protocol servers
`heartbeat`	`src/frontend/src/heartbeat.rs`	Heartbeat to metasrv; handles suspend / cache invalidation
`service_config`	`src/frontend/src/service_config/`	Per-protocol option structs

Request lifecycles

SQL query (instance.rs): do_query → pre_parsing interceptor → parse → post_parsing interceptor → then per statement: check_permission → statement_executor.plan (logical plan) → query_engine.execute → for distributed reads, region_query.rs fetches from datanodes → cancellable RecordBatch stream. Interceptors run around parsing, before the per-statement permission check — preserve that ordering.
Insert (instance/grpc.rs): handle_inserts / handle_row_inserts → check_permission → operator's Inserter (schema validation, optional auto-create, partition routing) → local RegionServer (standalone) or RPC to datanodes (distributed).

Public surface

Instance (instance.rs) — the business-logic container.
Frontend (frontend.rs) — lifecycle wrapper around Instance + servers + heartbeat.
Created from cmd: src/cmd/src/frontend.rs (distributed) and src/cmd/src/standalone.rs (standalone, with embedded datanode).

When you change X, also touch Y

servers handler traits: a new/changed protocol handler requires the matching impl here.
operator Inserter/Deleter or query QueryEngine API: update the call sites in instance.rs / instance/grpc.rs.
session::QueryContext: new context fields thread through most handlers.
sql statements: new statement kinds need handling in query_statement.

Testing

cargo nextest run -p frontend

Gotchas

Keep the frontend/servers split straight: wire format and network live in servers; permissions, planning, and routing live here.
Standalone vs distributed diverge in datanode access (local RegionServer vs NodeClients RPC), MetaClient usage, and whether heartbeat matters. In standalone, the cache invalidator is a no-op.

Maintenance contract

Update this file when you add a protocol handler, change the query/insert lifecycle, or change how Instance is constructed or wired to servers.

4.2 KiB Raw Blame History