Server (MySQL protocol)

pkg/server/ is the network layer. It speaks the MySQL wire protocol, terminates TLS, handles authentication, and dispatches each statement to a session.Session.

Purpose

The server turns network connections into SQL execution. It owns:

• The MySQL protocol implementation (auth, COM_*, prepared statements, cursors, compression).
• The HTTP status server (Prometheus, pprof, /info, schema dumps, DDL job inspection).
• The gRPC RPC server used for cross-TiDB queries (e.g., for INFORMATION_SCHEMA cluster views).
• A "mock" server harness used by tests.

Directory layout

pkg/server/
├── server.go            # Server struct, accept loop, listener bookkeeping
├── conn.go              # *clientConn: per-connection state machine
├── conn_stmt.go         # COM_STMT_* handlers (prepared statements)
├── conn_stmt_params.go  # Binary parameter decoding
├── http_handler.go      # HTTP listener for /metrics, /debug/pprof, /api/...
├── http_status.go       # Most HTTP API endpoints (43k+ lines worth of routes)
├── rpc_server.go        # gRPC server for inter-TiDB calls
├── driver.go, driver_tidb.go  # Pluggable QueryCtx interface; the real impl bridges to pkg/session
├── extension.go         # Hooks for pkg/extension at the connection level
├── mock_conn.go         # Test harness for protocol-level tests
├── stat.go              # Per-server runtime stats
├── standby.go           # Standby/active-active glue
├── user_connections.go  # Public tracking of connected users
├── err/                 # Server-specific errors
├── handler/             # Specialised HTTP handlers (regions, schema, ddl jobs, …)
├── internal/            # Private helpers (auth, TLS, packets, parser glue)
├── tests/               # End-to-end protocol tests
└── metrics/             # Prometheus metrics specific to the protocol layer

Key abstractions

Type	File	Purpose
server.Server	pkg/server/server.go	Owns listeners, the connection table, and the lifecycle.
server.clientConn	pkg/server/conn.go	One per connection; reads packets, dispatches commands, writes results.
server.QueryCtx	pkg/server/driver.go	Interface the protocol layer uses to execute queries. The TiDB implementation in driver_tidb.go wires it to pkg/session.
server.ResultSet	pkg/server/driver.go	Iterator over result rows.
server.RPCServer	pkg/server/rpc_server.go	gRPC service used by intra-cluster RPC.
HTTP routes	pkg/server/http_status.go, pkg/server/handler/	The :10080 status surface.

Connection lifecycle

sequenceDiagram
  participant Client
  participant Listener as Server.listenerLoop
  participant Conn as clientConn
  participant Sess as session.Session
  Client->>Listener: TCP/TLS connect
  Listener->>Conn: spawn goroutine, run handshake
  Conn->>Conn: handshake / auth / capabilities
  Conn->>Sess: createSession()
  loop per packet
    Client->>Conn: COM_QUERY / COM_STMT_EXECUTE / ...
    Conn->>Sess: Execute / ExecutePreparedStmt
    Sess-->>Conn: ResultSet
    Conn-->>Client: OK / EOF / Error / rows
  end
  Client->>Conn: COM_QUIT
  Conn->>Sess: Close

The state machine in conn.go is the single largest file in the package. It dispatches per-packet on the MySQL command byte (mysql.Com* constants from pkg/parser/mysql/).

Authentication

Handled in pkg/server/internal/auth/. The pkg/privilege/privileges/ package contributes the actual privilege evaluation; the server only knows about the auth handshake (mysql_native_password, caching_sha2_password, optional plugins via pkg/extension/). LDAP and TLS-client-cert auth are implemented through pluggable auth plugins.

Prepared statements and cursors

• conn_stmt.go implements COM_STMT_PREPARE, COM_STMT_EXECUTE, COM_STMT_FETCH, COM_STMT_CLOSE, COM_STMT_RESET.
• conn_stmt_params.go decodes binary protocol parameters (the BIND row in COM_STMT_EXECUTE).
• Cursors (server-side iteration over result sets) use pkg/session/cursor/ and tie into the executor's staticrecordset/.

HTTP status server

http_status.go registers a large surface; see docs/tidb_http_api.md for a human-readable list. Notable groups:

• /info, /info/all, /labels — server identity and topology.
• /schema/..., /db-table/..., /regions/... — infoschema and TiKV region inspection.
• /ddl/history, /ddl/owner/resign, /ddl/job — DDL framework introspection.
• /stats/dump/... — statistics export for plan replayer / debugging.
• /plan_replayer/dump, /plan_replayer/load — plan replayer bundles.
• /log/level — runtime log level.
• /metrics — Prometheus exposition (registered metrics live in pkg/metrics/).
• /debug/pprof/ — Go pprof endpoints, optionally tied to pkg/util/cpuprofile/.

The HTTP server also serves the HTML frontend for plan-replayer file uploads.

RPC server

rpc_server.go implements gRPC services that other TiDB instances use to:

• Ship slow log / cluster INFORMATION*SCHEMA tables across nodes (so queries on CLUSTER*\* views can collect from every member).
• Ferry top-SQL records (pkg/util/topsql/).
• Coordinate global-kill (tests/globalkilltest/).

Mock server (mock_conn.go)

A minimal in-process implementation of the MySQL protocol used by pkg/testkit/ and protocol-level tests. It exposes the same packet hooks as clientConn but bypasses sockets.

Integration points

• Session (pkg/session/) — every connection owns one.
• Privilege (pkg/privilege/) — auth handshake + per-statement privilege checks.
• Extension (pkg/extension/) — connection-level hooks (custom auth, post-handshake greetings, audit logs).
• Standby (pkg/standby/) — pre-warmed standby that becomes active-active on demand.
• Domain (pkg/domain/) — provides infoschema snapshots and statistics handles.
• Metrics (pkg/metrics/) — per-connection counters, histogram for query latency.

Entry points for modification

• New protocol command → handle the new mysql.Com* byte in conn.go (or the prepared variant in conn_stmt.go) and register matching tests under pkg/server/tests/.
• New HTTP endpoint → add the route in http_status.go (or in pkg/server/handler/ for larger handlers).
• New auth plugin → register in pkg/server/internal/auth/ and in pkg/privilege/privileges/.
• New gRPC service → extend rpc_server.go and the matching .proto definitions.

Per AGENTS.md -> Task -> Validation Matrix, server-protocol changes need targeted package tests plus SQL integration tests for the user-visible behaviour.