Documentation
¶
Overview ¶
Package rpcserver exposes the pkg/cortexdb facade over gRPC. It is a pure conversion layer: every handler converts proto messages to the facade's Request/Response structs and delegates to *cortexdb.DB.
Index ¶
- Constants
- func AuthInterceptor(keys *authz.KeySet, db *cortexdb.DB) grpc.UnaryServerInterceptor
- func MetricsInterceptor(reg *observability.Registry) grpc.UnaryServerInterceptor
- func MetricsInterceptorWithTracer(reg *observability.Registry, tracer observability.Tracer) grpc.UnaryServerInterceptor
- func New(db *cortexdb.DB, opts Options) *grpc.Server
- func NewWithPolicy(db *cortexdb.DB, opts Options) (*grpc.Server, error)
- func Register(s *grpc.Server, db *cortexdb.DB, opts Options)
- type Options
Constants ¶
const ( MetricRequestsTotal = "cortexdb_grpc_requests_total" MetricErrorsTotal = "cortexdb_grpc_errors_total" MetricRequestDuration = "cortexdb_grpc_request_duration_seconds" MetricRequestsInFlight = "cortexdb_grpc_requests_in_flight" )
Metric names. They are constants because a dashboard, an alert rule and a scrape config all name them from the outside: renaming one is a breaking change to somebody's paging setup, not a refactor.
const ( LabelMethod = "grpc_method" LabelCode = "grpc_code" )
Label names.
Cardinality discipline: these two are the whole list, and the line is that a label may only take values from a set fixed at compile time. grpc_method is bounded by the service definitions in proto/ — a call to a method the server does not implement is rejected by grpc-go before any interceptor runs, so an attacker cannot mint new series by dialling nonsense. grpc_code is bounded by the seventeen codes in google.golang.org/grpc/codes.
Nothing derived from a request body ever becomes a label. Not a user id, not a scope, not a collection name, not a memory id, and above all not query text. Each distinct value of a label is a permanent time series in the scraper: one endpoint labelled by query text takes down the Prometheus that scrapes it, not the server that emits it, which is why this mistake is usually discovered by somebody else's on-call.
Variables ¶
This section is empty.
Functions ¶
func AuthInterceptor ¶ added in v2.95.0
AuthInterceptor is the authorization this package installs in the servers it builds — bearer lookup, method clearance, row confinement, per-tool classification, SPARQL narrowing and the caller key that ownership checks read — as a value a process can install in a grpc.Server of its own.
It is exported for the process that mounts cortexdb.v1 beside other services on one listener. That process has one interceptor chain, and the choice it faces without this is to rewrite the policy or to drop it; both are worse than routing cortexdb.v1 calls through the interceptor that already knows what a read is. Register attaches the services; this attaches the policy. Together they are NewWithPolicy without the server it constructs.
func MetricsInterceptor ¶ added in v2.91.0
func MetricsInterceptor(reg *observability.Registry) grpc.UnaryServerInterceptor
MetricsInterceptor returns a unary interceptor recording request counts, errors by gRPC status code, in-flight requests and handler latency into reg.
It is exported rather than wired into New so a caller can chain it with the auth interceptor in whatever order it wants. Putting metrics outermost counts requests that auth rejects, which is usually what an operator wants to see; putting it innermost measures only work actually done.
func MetricsInterceptorWithTracer ¶ added in v2.91.0
func MetricsInterceptorWithTracer(reg *observability.Registry, tracer observability.Tracer) grpc.UnaryServerInterceptor
MetricsInterceptorWithTracer is MetricsInterceptor plus a span per RPC. A nil tracer means no tracing at all: observability.NopTracer returns the context unchanged and a zero-size span, so an unconfigured tracer costs a nil check and no allocation.
func New ¶
New returns a grpc.Server with all cortexdb.v1 services registered.
A key file that cannot be loaded yields a server that refuses every RPC. Coming up wide open because the policy failed to parse is the one outcome this must never produce, and the alternative — panicking inside a constructor that has never returned an error — would be worse for callers. Use NewWithPolicy to see that failure at startup instead of at first call.
func NewWithPolicy ¶ added in v2.91.0
NewWithPolicy is New, reporting a key-file load failure to the caller.
Types ¶
type Options ¶
type Options struct {
// Token enables bearer-token auth when non-empty. It grants unconfined
// read/write, which is what it has always meant; KeyFile is how a
// deployment gets anything narrower.
Token string
// KeyFile is the path to a JSON file of scoped API keys. When set it is
// the entire policy and Token is ignored — see authz.Resolve for why
// honouring both would defeat the point.
KeyFile string
// Keys is a pre-loaded policy, for callers that build one in process.
// It takes precedence over Token and KeyFile.
Keys *authz.KeySet
// Interceptors are chained BEFORE authorization, so they observe every
// call including the ones policy rejects. Metrics and tracing go here
// (see MetricsInterceptor).
//
// The ordering was the other way round first, on the reasoning that a
// denied call is not served work. Running it showed what that costs: with
// metrics inside the gate, a brute-forced token produces an empty
// errors_total and the operator of a server whose whole new feature is
// scoped keys cannot see a single denial. Labels here are bounded to
// method and status code, so counting unauthenticated traffic cannot blow
// up cardinality — it is exactly the signal you want.
Interceptors []grpc.UnaryServerInterceptor
// DBPath is reported by AdminService.Info.
DBPath string
// BackupDir confines AdminService.Backup: destinations are relative to it
// and may not leave it. Empty means the directory holding DBPath, which is
// where the server is already known to be able to write.
BackupDir string
}
Options configures the gRPC server wrapper.
Source Files