quota

package
v0.0.13 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 8, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Index

Constants

View Source
const NoopName = "noop"

Variables

This section is empty.

Functions

func Register

func Register(name string, f Factory)

Register adds a Factory under the given name. Panics on duplicate — see pkg/plugins.Register for the rationale.

Types

type Factory

type Factory func(h framework.Handle, args framework.Args) (Provider, error)

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).

func Get

func Get(name string) (Factory, error)

Get looks up a registered Factory.

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

func (Noop) DeriveShortName(_ string) string

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.

func (Noop) Enabled

func (Noop) Enabled() bool

func (Noop) ListForUser

func (Noop) ListForUser(_ context.Context, _, _ string) ([]Info, *domain.AppError)

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.

func Build

func Build(name string, h framework.Handle, args framework.Args) (Provider, error)

Build looks up a Factory by name and invokes it.

func NewNoop

func NewNoop() Provider

NewNoop returns a disabled quota Provider. Safe to share.

func NoopFactory

func NoopFactory(_ framework.Handle, _ framework.Args) (Provider, error)

NoopFactory is the Factory form of NewNoop — no Handle or Args are used. Registered at package init() so callers can Build("noop", h, nil) without any extra wiring.

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.

Directories

Path Synopsis
Package quotatest holds the quota Provider doubles the rest of the tree shares.
Package quotatest holds the quota Provider doubles the rest of the tree shares.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL