Documentation
¶
Overview ¶
Package xstenant reads the per-cell admin store that the control plane publishes to object storage: tenant state, resolved per-engine limits and API key hashes. A Reader polls the bucket, verifies every object against the manifest and swaps in an immutable Snapshot atomically.
The package applies no policy. Engines decide what to do before the first snapshot exists or when it goes stale.
Index ¶
- Constants
- Variables
- type AuthDecision
- type AuthRequest
- type Bucket
- type Config
- type DecodeFunc
- type EnforceMode
- type Kind
- type Principal
- type Reader
- func (r *Reader) Authorize(req AuthRequest) AuthDecision
- func (r *Reader) CheckAuth(req AuthRequest, mode EnforceMode) AuthDecision
- func (r *Reader) CheckPush(tenant string, mode EnforceMode) (deny bool, reason string)
- func (r *Reader) OnUpdate(f func(*Snapshot))
- func (r *Reader) PushAllowed(tenant string) (allowed bool, reason string)
- func (r *Reader) Ready() bool
- func (r *Reader) Run(ctx context.Context) error
- func (r *Reader) Snapshot() *Snapshot
- func (r *Reader) Start(parent context.Context) (stop func())
- type Snapshot
- func (s *Snapshot) Authenticate(token string) (Principal, error)
- func (s *Snapshot) Authorize(req AuthRequest) AuthDecision
- func (s *Snapshot) Generation() int64
- func (s *Snapshot) HasLimits(engine string) bool
- func (s *Snapshot) Limits(engine string) map[string]json.RawMessage
- func (s *Snapshot) PublishedAt() time.Time
- func (s *Snapshot) PushAllowed(tenant string) (allowed bool, reason string)
- func (s *Snapshot) State(tenant string) (TenantState, bool)
- type Source
- type TenantState
Constants ¶
const ( ReasonAuthAllowed = "none" ReasonMissingToken = "missing_token" ReasonMissingScopeOrgID = "missing_scope_orgid" ReasonUnknownToken = "unknown_token" ReasonKeyExpired = "key_expired" ReasonTenantInactive = "tenant_inactive" ReasonScopeOrgIDMismatch = "scope_orgid_mismatch" ReasonPathNotAllowed = "path_not_allowed" ReasonScopeReadMissing = "scope_read_missing" ReasonScopeWriteMissing = "scope_write_missing" )
Reasons returned with an authorization decision. ReasonAuthAllowed is the reason of an allowed request.
const ( // ReasonSoftLocked is the only reason a push is ever denied. ReasonSoftLocked = "billing_soft_locked" // ReasonNoState means no snapshot is available yet. ReasonNoState = "no_state" // ReasonUnknownTenant means the snapshot has no entry for the tenant. ReasonUnknownTenant = "unknown_tenant" // ReasonAllowed is the reason for a tenant with a state other than soft_locked. ReasonAllowed = "allowed" )
Reasons returned with a push decision.
const ( StateActive = "active" StateSoftLocked = "soft_locked" StateSuspended = "suspended" )
Tenant states as published in tenants.json.
Variables ¶
var ( // ErrUnknownKey is returned by Authenticate for a token with no entry. ErrUnknownKey = errors.New("xstenant: unknown key") // ErrExpiredKey is returned by Authenticate for an expired key. ErrExpiredKey = errors.New("xstenant: key expired") )
Functions ¶
This section is empty.
Types ¶
type AuthDecision ¶ added in v0.3.0
type AuthDecision struct {
Allowed bool
Enforced bool
Tenant string
// KeyID and Managed are the key's optional key_id and managed fields
// from keys.json, set only when the request is allowed. They are empty
// and false for a key that does not carry them.
KeyID string
Managed bool
// Path, Push and RequiredScope report how Authorize classified the
// request, so a caller does not re-derive it from the raw request path.
// Path is the cleaned path: query and fragment removed, route prefix
// stripped, percent-encoding decoded once. Push is true when that path is
// a push path for the Kind (a trailing slash included), the same rule
// that selects the write scope. RequiredScope is "read" or "write".
//
// Path is set whenever the path was cleaned, allowed or denied, including
// a path_not_allowed denial. Push and RequiredScope are set once the path
// passed the allowlist, so they are also set on scope_read_missing and
// scope_write_missing. All three are empty or false for a denial before
// the path step (missing_token, missing_scope_orgid, state_unavailable,
// unknown_token, key_expired, tenant_inactive, scope_orgid_mismatch), for
// a path that does not clean, and for a decision CheckAuth returns in
// mode off.
Path string
Push bool
RequiredScope string
// SoftLocked is true when the request is allowed, is a push, and the
// tenant is soft_locked. It is the push gate on the same classification
// as Push, so a caller can answer 429 with Retry-After: 60 without a
// second look at the path. It reports state only; it does not apply a
// rollout mode. A caller with a mode uses CheckPush(d.Tenant, mode) when
// d.Push is true.
SoftLocked bool
Status int
Reason string
Message string
}
AuthDecision is the outcome. Status is the HTTP status to answer with when Allowed is false (0 when allowed). Message is the client-facing text; it is opaque for unknown, expired and inactive credentials so a caller cannot probe which tokens or tenants exist. Reason is the precise cause for logs and metrics. Tenant is the key's tenant and is set only when the rules allowed the request.
Enforced is set by CheckAuth only in mode on for an allowed request. An engine replaces X-Scope-OrgID with Tenant only when Enforced is true; in shadow and off it leaves the request as received.
type AuthRequest ¶ added in v0.3.0
type AuthRequest struct {
Kind Kind
Method, Path string
Authorization string
OrgID string
// PathPrefix is the route prefix the engine's own router adds, for
// example "/prometheus" for Mimir behind a gateway that rewrites
// /api/v1/query to /prometheus/api/v1/query. When Path starts with it, it
// is removed before every check. A Path without it (the public form) is
// used as is.
PathPrefix string
// ExtraReadPaths lists additional paths the caller serves next to the
// engine and wants API keys to reach for this request's Kind. Each entry
// is matched exactly against the path after query-string removal and
// prefix stripping: no prefix, case or trailing-slash variants. A match
// needs the read scope for every method and is never treated as a push
// or config path. The path hygiene checks (dot segments, encoded dots
// and slashes) run first. A path the built-in allowlist already covers
// keeps its built-in classification. Unset, behaviour is unchanged.
ExtraReadPaths []string
}
AuthRequest is what the decision needs from an HTTP request. Path may carry a query string and fragment; both are removed before any path check. Authorization and OrgID are the raw header values.
type Bucket ¶
type Bucket interface {
Get(ctx context.Context, name string) (io.ReadCloser, error)
IsObjNotFoundErr(err error) bool
}
Bucket is the read side of an object store. The thanos objstore BucketReader satisfies it structurally.
type Config ¶
type Config struct {
// Prefix is the key prefix of the admin store in the bucket.
Prefix string
// PollInterval is the time between manifest polls.
PollInterval time.Duration
// CacheDir, when set, keeps the last applied generation on disk so a
// restart can serve it while the bucket is unreachable.
CacheDir string
// CacheKey identifies the bucket and prefix the cache belongs to
// (engines pass bucket name plus prefix). A cache written under a
// different key is ignored. Empty matches only caches written with an
// empty key.
CacheKey string
// MaxObjectBytes caps the size of any single object, manifest included.
MaxObjectBytes int64
}
Config configures a Reader.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a Config with the defaults filled in.
type DecodeFunc ¶
type DecodeFunc[T any] func(tenant string, raw json.RawMessage) (T, error)
DecodeFunc turns the engine-native limits block of one tenant into the engine's own type.
type EnforceMode ¶ added in v0.2.0
type EnforceMode int
EnforceMode selects what CheckPush does with a soft locked tenant. The zero value is EnforceOff. It implements flag.Value.
const ( // EnforceOff never denies and does not count decisions. EnforceOff EnforceMode = iota // EnforceShadow allows every push and counts the ones that would be denied. EnforceShadow // EnforceOn denies pushes from soft locked tenants. EnforceOn )
func ParseEnforceMode ¶ added in v0.2.0
func ParseEnforceMode(s string) (EnforceMode, error)
ParseEnforceMode parses "off", "shadow" or "on" (case-insensitive).
func (*EnforceMode) Set ¶ added in v0.2.0
func (m *EnforceMode) Set(s string) error
Set implements flag.Value.
func (EnforceMode) String ¶ added in v0.2.0
func (m EnforceMode) String() string
String returns the flag form of the mode.
type Kind ¶ added in v0.3.0
type Kind string
Kind is the signal a backend serves. It selects the path allowlist. An empty or unknown Kind is treated as KindMetrics.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader polls the admin store and serves the latest verified Snapshot.
func New ¶
func New(cfg Config, bucket Bucket, logger log.Logger, reg prometheus.Registerer) (*Reader, error)
New returns a Reader. A valid disk cache, if configured, is loaded here so Snapshot is available before the first poll. reg may be nil.
func (*Reader) Authorize ¶ added in v0.3.0
func (r *Reader) Authorize(req AuthRequest) AuthDecision
Authorize applies Snapshot.Authorize to the snapshot currently served. It is safe on a nil Reader (no snapshot, 503 state_unavailable) and does not count a decision.
func (*Reader) CheckAuth ¶ added in v0.3.0
func (r *Reader) CheckAuth(req AuthRequest, mode EnforceMode) AuthDecision
CheckAuth applies Authorize under a rollout mode.
- EnforceOff: Allowed is true, nothing is counted, and no hashing or lookup happens.
- EnforceShadow: Allowed is true; a request Authorize would deny is counted as would_deny, anything else as allow. Status, Reason and Message still describe the would-be denial.
- EnforceOn: the Authorize result, counted as allow or deny.
Enforced is true only in mode on for an allowed request. Tenant is empty unless the rules allowed the request, in every mode.
Counted in xscaler_admin_store_auth_decisions_total{mode,kind,decision,reason}.
func (*Reader) CheckPush ¶ added in v0.2.0
func (r *Reader) CheckPush(tenant string, mode EnforceMode) (deny bool, reason string)
CheckPush applies the push gate for the tenant. deny is true only in mode EnforceOn and only for a soft locked tenant; reason is the PushAllowed reason. In EnforceShadow and EnforceOn the decision is counted in xscaler_admin_store_state_decisions_total. In EnforceOff (and any mode this version does not know) the push is allowed and nothing is counted.
func (*Reader) OnUpdate ¶
OnUpdate registers f to run after each snapshot swap, including the swap of a snapshot restored from the disk cache (run at the start of Run).
func (*Reader) PushAllowed ¶ added in v0.2.0
PushAllowed applies Snapshot.PushAllowed to the snapshot currently served. It is safe to call on a nil Reader and does not count a decision.
func (*Reader) Ready ¶
Ready reports whether a snapshot is available, from the bucket or the disk cache. It says nothing about whether an engine has applied that snapshot; engines gate on Source.Applied instead.
type Snapshot ¶
type Snapshot struct {
// contains filtered or unexported fields
}
Snapshot is one applied generation of the admin store. It is immutable and safe for concurrent use.
func (*Snapshot) Authenticate ¶
Authenticate looks the token up by its sha256 hash.
func (*Snapshot) Authorize ¶ added in v0.3.0
func (s *Snapshot) Authorize(req AuthRequest) AuthDecision
Authorize decides whether the request may reach the backend. It applies the gateway authorization decision, in this order:
- Authorization is not "Bearer <token>": 401 missing_token.
- OrgID is empty after trimming: 401 missing_scope_orgid.
- nil snapshot: 503 state_unavailable.
- sha256 of the token not in keys.json: 401 unknown_token.
- key expired: 401 key_expired.
- tenant state suspended: 401 tenant_inactive.
- OrgID differs from the key's tenant: 401 scope_orgid_mismatch.
- path empty, ambiguous, encoded in a way that hides a separator or dot, or not allowed for the Kind: 403 path_not_allowed. A path in ExtraReadPaths is allowed here and needs the read scope.
- key lacks the scope the request needs: 403 scope_read_missing or scope_write_missing.
A tenant absent from tenants.json is allowed, as in PushAllowed. A soft locked tenant is allowed here; the push gate handles it. It is safe on a nil Snapshot.
func (*Snapshot) Generation ¶
Generation returns the generation counter of the manifest.
func (*Snapshot) HasLimits ¶
HasLimits reports whether the snapshot lists and decoded a limits object for the engine.
func (*Snapshot) Limits ¶
func (s *Snapshot) Limits(engine string) map[string]json.RawMessage
Limits returns the engine-native limits per tenant, as published. The map and its values must not be modified.
func (*Snapshot) PublishedAt ¶
PublishedAt returns the time the control plane published the generation.
func (*Snapshot) PushAllowed ¶ added in v0.2.0
PushAllowed reports whether the tenant may push. Only a soft locked tenant is denied. A nil snapshot, an unknown tenant, and any other state (active, suspended, or a value this version does not know) are allowed. It is safe to call on a nil Snapshot.
type Source ¶
type Source[T any] struct { // contains filtered or unexported fields }
Source holds the decoded per-tenant limits of one engine. It follows a Reader and swaps in a new immutable map for each applied generation.
func NewSource ¶
func NewSource[T any](r *Reader, engine string, decode DecodeFunc[T], logger log.Logger, reg prometheus.Registerer) *Source[T]
NewSource registers on r and applies r's snapshot at once if it already has one (restored from the disk cache), so Applied is true on return in that case. reg may be nil.
func (*Source[T]) All ¶
All returns every tenant's value. The map is built once per applied generation and must not be modified.
func (*Source[T]) Applied ¶
Applied reports whether a snapshot containing this engine's limits object has been decoded and swapped in. A snapshot without it does not count.
type TenantState ¶
type TenantState struct {
OrgID string `json:"org_id"`
State string `json:"state"`
PlanID string `json:"plan_id"`
}
TenantState is one tenant's entry in tenants.json.