Documentation
¶
Index ¶
Constants ¶
const NoopName = "noop"
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Factory ¶
Factory constructs a quota Provider from shared runtime dependencies and provider-specific parameters. Passing nil args is legal for Providers that take no parameters (e.g. Noop).
type Info ¶ added in v0.0.5
type Info struct {
// Quota is the wire-shape projection of this quota, returned to API
// callers verbatim. Implementations are responsible for populating Id
// and Name (Id MUST be stable across provider restarts; Name is the
// human-readable form for the dashboard).
Quota gen.Quota
// Labels mirrors the source object's labels. Optional; nil when the
// underlying backend has no notion of labels.
Labels map[string]string
// Annotations mirrors the source object's annotations. Optional.
Annotations map[string]string
}
Info is the internal, provider-side view of a quota. It carries the public wire shape together with backend-only metadata (labels/annotations from the underlying CRD or external system) that must not leak to API callers.
The service layer serializes only Info.Quota over the wire; Labels and Annotations stay inside the binary so that internal consumers (the reservation plugin, controllers, etc.) can read provider-specific hints (queue name, parent pool id, scheduler URL, ...) without baking those hints into the public schema.
type Noop ¶
type Noop struct{}
Noop is a Provider that reports the quota feature as disabled. It is the default for open-source builds where no quota backend is configured.
func (Noop) DeriveShortName ¶ added in v0.0.5
DeriveShortName has no usable default extractor in the open-source build — QuotaURL shapes are operator-defined and only the concrete Provider knows how to map them to a short identifier. Returning "" tells the caller to fall back to a deterministic hash-based suffix when naming member pools.
type PoolSizing ¶ added in v0.0.11
type PoolSizing string
PoolSizing says how the member Pools of a SandboxTemplate must be sized.
It has three values rather than two because "billed" and "not billed" are not the whole story: a deployment can also have no rule at all, and collapsing that into "not billed" would silently take a feature away from it. The InstanceType catalog is an open-source feature — a deployment with a catalog and no quota backend sizes Pools by instance type perfectly well — so "nothing here is billed" must keep the caller's choice, not forbid one of the choices.
The three states are therefore:
- Billed: this template's Pools spend quota. A Pool must name the quota it spends (the quota.scitix.ai/url label) AND the instance type its units are counted in.
- FreeForm: the quota Provider governs this deployment, and it says this template is not billed. A Pool is sized by inlineResources alone; an instance type or a quota label is refused, because each asserts something the server would not honour — an instance bought, a quota charged.
- Either: no billing rule applies to this template (the Provider is absent, or implements no policy). Both shapes are accepted, which is what every deployment did before this rule existed.
const ( // PoolSizingBilled — quota AND instance type are required. PoolSizingBilled PoolSizing = "billed" // PoolSizingFreeForm — inlineResources only; instance type and quota label // are refused. PoolSizingFreeForm PoolSizing = "free-form" // PoolSizingEither — no billing rule; the caller picks the shape. PoolSizingEither PoolSizing = "either" )
func SizingFor ¶ added in v0.0.11
func SizingFor(provider Provider, templateAnnotations map[string]string) PoolSizing
SizingFor answers, for a Template carrying these annotations, which sizing shape its Pools take. This is the one place the three states are decided.
A nil Provider, and a Provider that does not implement TemplatePolicy, both yield PoolSizingEither: the absence of a policy is not "nothing spends quota here", it is "this deployment has no opinion", and the open-source meaning of no opinion is that the caller still chooses.
type Provider ¶
type Provider interface {
// Enabled reports whether the provider can answer queries. False means
// the quota feature is unavailable (no backend configured, CRD missing,
// etc.) — callers should skip quota checks gracefully.
Enabled() bool
// ListForUser returns all quotas visible to the (user, team) pair.
// Returns (nil, nil) when the provider is disabled or the user has no
// visible quotas; returns an AppError only on transient/system failures.
//
// Each Info.Quota is the wire-shape value forwarded to API callers;
// Info.Labels / Info.Annotations carry provider-internal metadata that
// MUST NOT be serialized — they exist solely for in-process consumers
// (reservation plugins, scheduler integration, etc.) that need to
// derive backend-specific hints like queue names or scheduler IDs.
ListForUser(ctx context.Context, user, team string) ([]Info, *domain.AppError)
// DeriveShortName returns a stable human-readable short identifier for
// a quota ID, used by the SandboxEnv Reconciler when naming member
// SandboxPools that consume the quota (e.g. "{env-name}-{shortName}").
//
// Quota ID shapes are Provider-defined, so the parsing rule lives with
// the concrete Provider — the open-source Noop returns "" and the
// caller falls back to a deterministic hash-based suffix so naming
// stays idempotent. Closed-source Providers can override this with a
// catalog lookup or a tenant-specific path parser.
DeriveShortName(quotaID string) string
}
Provider exposes read-only access to quota information.
A nil Provider is not valid; callers should always hold at least a Noop. Use Enabled() to decide whether to expose quota-related UI.
type TemplatePolicy ¶ added in v0.0.11
type TemplatePolicy interface {
// RequiresQuota reports whether a SandboxPool rendered from a Template
// carrying these annotations must declare a quota label and an instance
// type. It is the billed/free-form split; "either" is the absence of the
// interface, never a return value.
RequiresQuota(templateAnnotations map[string]string) bool
}
TemplatePolicy is an OPTIONAL interface a quota Provider may implement to say, per template, which of the two governed sizing shapes applies.
The rule is the Provider's to state because only the Provider knows what a Template is billed against: the open-source build has no quota backend at all, and a closed-source one keys the answer off its own annotations. The answer reaches clients as PoolSizing on the Template and on the Env (stamped there by the reconciler so it does not cost a template lookup per read), which is what the console, the CLI and the Pool write path all switch on instead of each re-deriving the rule.
Implementations must be total and cheap: this runs on read paths (Template projection), on every SandboxEnv reconcile, and on every member-Pool write. Annotations are the whole input — a Provider that needs more of the Template is asking the wrong interface for it.
func Policy ¶ added in v0.0.11
func Policy(provider Provider) (TemplatePolicy, bool)
Policy returns a Provider's TemplatePolicy, if it has one. The boolean is the difference between PoolSizingFreeForm and PoolSizingEither, which is why callers should use SizingFor rather than type-asserting themselves.