Documentation
¶
Overview ¶
Package server is the HTTP layer with Prometheus / Loki / Tempo API compatibility.
Translators emit a plan.Plan; the server runs it via plan.Execute against an injected plan.Runner, then formats the response per the plan's plan.OutputKind. Currently only `/api/v1/query` (Prometheus instant) is wired; everything else still returns 501 Not Implemented.
Package server – TLS certificate loader with SIGHUP-driven atomic reload.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MarkUnimplementedSink ¶
MarkUnimplementedSink is a small helper to keep govet happy on the observation-side helpers that intentionally don't return values.
Types ¶
type ClickHouseConfig ¶
type ClickHouseConfig struct {
Addr string // host:port, e.g. "localhost:9000"
Database string
Username string
Password string
}
ClickHouseConfig is the connection configuration for the production runner.
type ClickHouseRunner ¶
type ClickHouseRunner struct {
// contains filtered or unexported fields
}
ClickHouseRunner is the production plan.Runner backed by the official ClickHouse driver. It decodes rows by column name into plan.Row — translators emit SQL whose columns are named to match the fields the Plan executor and response formatter expect (`TimeUnix`, `Value`, `Attributes` for metrics; `Timestamp`, `Body`, `ResourceAttributes`, `LogAttributes` for logs; `TraceId`, `SpanId`, `ServiceName`, `SpanName`, `Duration`, `SpanAttributes` for traces).
func NewClickHouseRunner ¶
func NewClickHouseRunner(cfg ClickHouseConfig) (*ClickHouseRunner, error)
NewClickHouseRunner opens a connection pool to ClickHouse using the given config.
func (*ClickHouseRunner) Close ¶
func (e *ClickHouseRunner) Close() error
Close shuts the connection pool.
type Config ¶
type Config struct {
Layout schema.Layout
ClickHouse ClickHouseConfig
// Observability is the optional self-observability provider. When
// nil the server constructs a defaults-only provider (text logs,
// no-op metrics, no-op tracer) so existing call sites keep working.
Observability *observability.Provider
// MetricsPath is the path the `/metrics` handler is mounted on.
// Empty falls back to "/metrics".
MetricsPath string
// ReadyGracePeriod is the cold-start window during which `/readyz`
// returns 200 unconditionally. Zero means "no grace period; always
// probe ClickHouse".
ReadyGracePeriod time.Duration
// ReadyChecker is the function used by `/readyz` to verify the
// ClickHouse pool. Nil falls back to a built-in `SELECT 1` against
// the runner. The function should return a non-nil error if the
// dependency is unhealthy.
ReadyChecker func(context.Context) error
// Auth is the optional authentication middleware. When nil, all
// requests are allowed through (equivalent to mode=none).
Auth *auth.Auth
// Tenant is the optional multi-tenant configuration. When nil (or
// Mode == ModeDisabled) all requests use ClickHouse.Database.
Tenant *tenant.Config
// RateLimit is the optional per-key token-bucket rate limit. When nil
// (or RPS <= 0), rate limiting is disabled.
RateLimit *RateLimitConfig
// MaxBodyBytes caps the request body size via http.MaxBytesReader.
// Zero or negative means no cap. Default: 1 MiB (1<<20).
MaxBodyBytes int64
// QueryTimeout is the per-request context deadline applied by the
// Timeout middleware. Zero means no timeout.
QueryTimeout time.Duration
// PanicRecovery enables the Recover middleware when true. Defaults
// to true; set to false only for debugging (panics will crash the
// process, exposing the full stack to stderr rather than swallowing
// it silently).
PanicRecovery bool
}
Config holds the server's runtime configuration.
type RateLimitConfig ¶
RateLimitConfig holds the parameters for the per-key token-bucket rate limiter. RPS is the sustained request rate in requests/second; Burst is the maximum instantaneous burst size.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server bundles the HTTP layer + dependencies. The Plan runner is injectable so tests can swap a stub for ClickHouse.
func New ¶
New builds a Server backed by the given Plan runner. Pass a real ClickHouseRunner in production; pass a stub in tests.
func (*Server) MetricsHandler ¶
MetricsHandler returns a standalone http.Handler serving the Prometheus registry. Used by `cmd/cerberus serve` when the operator requests a separate `--metrics-listen` listener.
type TLSReloader ¶
type TLSReloader struct {
// contains filtered or unexported fields
}
TLSReloader holds a *tls.Certificate in an atomic pointer so it can be swapped at runtime (e.g. on SIGHUP) without dropping in-flight connections.
func NewTLSReloader ¶
func NewTLSReloader(certFile, keyFile string) (*TLSReloader, error)
NewTLSReloader loads the certificate pair from disk and returns a TLSReloader ready for use. Returns an error if the initial load fails.
func (*TLSReloader) GetCertificate ¶
func (r *TLSReloader) GetCertificate(_ *tls.ClientHelloInfo) (*tls.Certificate, error)
GetCertificate implements the tls.Config.GetCertificate callback. The returned certificate is whatever was last successfully loaded.
func (*TLSReloader) Reload ¶
func (r *TLSReloader) Reload() error
Reload re-reads the cert and key files from disk. Intended to be called from a SIGHUP handler. Returns an error if the new pair is invalid; the old certificate remains active in that case.
func (*TLSReloader) TLSConfig ¶
func (r *TLSReloader) TLSConfig() *tls.Config
TLSConfig returns a *tls.Config wired to use the reloader's GetCertificate. TLS 1.2 is the minimum version.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package middleware contains HTTP middleware used by the cerberus server: per-request structured logging, Prometheus metrics instrumentation, and OTel span correlation.
|
Package middleware contains HTTP middleware used by the cerberus server: per-request structured logging, Prometheus metrics instrumentation, and OTel span correlation. |