Administration and token-free inspection for max-active-run admission.
Caps are integers in 1..2_147_483_647. Updates are compare-and-set when
:expected_version is supplied.
Summary
Functions
Returns the persisted domain default and its version.
Returns the effective cap and aggregate, token-free admission state.
Sets the persisted domain default.
Sets a cap override for one owner scope.
Clears one owner scope's override so it inherits the domain default.
Types
@type cap() :: 1..2_147_483_647
@type effective_policy() :: %{ owner_scope: Docket.Backend.owner_scope(), max_active_runs: cap(), source: :default | :override, default_version: non_neg_integer(), override_version: non_neg_integer(), queued: non_neg_integer(), admitted_ready: non_neg_integer(), admitted_claimed: non_neg_integer(), debt: non_neg_integer() }
@type policy() :: %{ :max_active_runs => cap() | nil, :version => non_neg_integer(), :updated_at => DateTime.t(), optional(:admission_mode) => :legacy | :tenant_fair }
Functions
@spec get_default(Docket.Backend.ctx()) :: {:ok, policy()} | {:error, term()}
Returns the persisted domain default and its version.
Before the policy is initialized, max_active_runs is nil and version
is zero.
@spec get_effective(Docket.Backend.ctx(), Docket.Backend.owner_scope()) :: {:ok, effective_policy()} | {:error, :not_initialized | :inactive_engine | term()}
Returns the effective cap and aggregate, token-free admission state.
queued counts due, healthy, unclaimed rows without admission;
admitted_ready counts due, healthy, unclaimed admitted rows;
admitted_claimed counts healthy admitted rows with a claim; and debt is
the admitted count above the effective cap. An uninitialized domain returns
{:error, :not_initialized}; a persisted cap under an inactive engine
returns {:error, :inactive_engine}.
@spec put_default(Docket.Backend.ctx(), cap(), keyword()) :: {:ok, policy()} | {:error, :stale | term()}
Sets the persisted domain default.
max_active_runs must be in 1..2_147_483_647. Pass
expected_version: version for compare-and-set behavior; a version mismatch
returns {:error, :stale} without changing the policy.
@spec put_override( Docket.Backend.ctx(), Docket.Backend.owner_scope(), cap(), keyword() ) :: {:ok, policy()} | {:error, :stale | term()}
Sets a cap override for one owner scope.
owner_scope must be :tenantless or {:tenant, non_empty_binary} and the
cap must be in 1..2_147_483_647. The partition is created if necessary.
Pass expected_version: 0 to create its first override with CAS semantics;
a version mismatch returns {:error, :stale}.
@spec reset_override(Docket.Backend.ctx(), Docket.Backend.owner_scope(), keyword()) :: {:ok, policy()} | {:error, :stale | term()}
Clears one owner scope's override so it inherits the domain default.
Pass expected_version: version for compare-and-set behavior; a missing or
mismatched partition version returns {:error, :stale}.