Update limits at runtime
Change named rule limits safely across workers without resetting spent budget.
Use managed limits when a provider changes an existing quota while your workers
are running. The store becomes authoritative for each named rule's limit and
GCRA burst; rule names, scopes, algorithms, intervals, and global concurrency
remain fixed.
Managed limits are opt-in. The default limits: 'immutable' behavior is
unchanged and still requires identical complete rules on every worker.
Configure managed limits
Every managed rule needs a unique name. The limit and burst supplied to
createValve are registration seeds: the first worker for a new ID installs
them. Once the ID exists, stored values win, even when another worker starts
with different numeric seeds.
import { createValve } from 'valvejs';
import { redisStore } from 'valvejs/redis';
const api = createValve({
id: 'partner:credential-42',
limits: 'managed',
rate: [
{ name: 'second', limit: 100, interval: '1s', burst: 10 },
{
name: 'day',
limit: 100_000,
interval: '24h',
algorithm: 'fixed-window',
},
],
store: redisStore({ client: redis, subscriber }),
});All workers sharing the ID must still use the same rule names, scopes,
algorithms, intervals, and global concurrency settings. Different managed
limit and burst seeds are accepted; the worker emits a warning when its
first stored snapshot differs from them.
The built-in memory and Redis stores support managed limits. A custom store
must implement the complete store.managed version 1 capability.
Read and update limits
getLimits() reads the authoritative snapshot and registers the configured
seeds first if the store has no managed limits for this ID.
const before = await api.getLimits();
console.log(before.version, before.rules.second.limit);
const after = await api.updateLimits({
second: { limit: 200, burst: 20 },
day: { limit: 120_000 },
});Patches contain absolute values, not increments. Omitted rules and fields keep their current values. A patch that changes nothing returns the current snapshot without advancing its version and emits no notice.
Only limit and GCRA burst can change. Unknown rules or fields, non-positive
or non-safe-integer values, burst on a fixed-window rule, and calls on an
immutable valve reject with INVALID_OPTIONS before a store call.
Snapshots are frozen and have this shape:
interface LimitsSnapshot {
readonly version: string; // Opaque registration epoch and revision.
readonly revision: number; // Starts at 1 for each registration epoch.
readonly rules: Readonly<
Record<
string,
{
readonly algorithm: 'gcra' | 'fixed-window';
readonly intervalMs: number;
readonly limit: number;
readonly burst: number; // Always 1 for fixed-window rules.
readonly scope?: string;
}
>
>;
}Treat version as an opaque comparison token. Do not sort or parse it.
revision can restart after store state loss or failover.
Prevent lost updates with expect
Without expect, writes to the same field are last-writer-wins. Updates to
different fields do not overwrite one another because patches are partial.
Use expect for compare-and-set behavior:
const current = await api.getLimits();
const next = await api.updateLimits(
{ second: { limit: 250 } },
{ expect: { second: { limit: current.rules.second.limit } } },
);Each expected field must equal its current value or already equal the patched
value. The second condition makes the same update safe to repeat after an
unknown outcome. Otherwise nothing changes and the call rejects with
LIMITS_CONFLICT. Read a fresh snapshot, decide whether the competing value is
acceptable, and retry with a new expectation.
A store timeout rejects with STORE_UNAVAILABLE, but the update may have
committed. Repeating the same absolute patch is a no-op if those values still
apply. If another writer changed the same field in between, an unconditional
retry overwrites it. Use expect when that would be incorrect.
Understand admission after an update
The store reads the committed limits inside the same atomic operation that checks and spends budget. Redis performs this in the authoritative Lua script; workers never enforce their cached numeric seeds. Before the first update, managed admission uses the same rate math as immutable admission.
Managed GCRA checks that its virtual-time coordinates can still represent
individual cost units. Extremely large rates, bursts, or accumulated frame
coordinates reject with INVALID_OPTIONS before spending budget. This check
also runs during updates and admission; use a lower rate or a coordinated
migration if it triggers. It never falls back to unrestricted admission under
onStoreError: 'open'.
Updates do not revoke work that is already granted or running. Queued work uses the new values at its next store admission. New values also do not impose a retroactive bound on starts admitted under an older value.
- A fixed window keeps its current window alignment and spent count. Lowering the limit below that count blocks further starts until the next window.
- GCRA keeps outstanding debt in cost units and drains it at the new rate.
For example, after taking 10 units at 10/s with
burst: 10, changing to 20/s permits the next unit after 50 ms; changing to 1/s permits it after 1 second. Changingburstchanges capacity, not existing debt. - A job whose cost exceeds the current GCRA
burstor fixed-windowlimitrejects at admission withCOST_EXCEEDS_LIMIT. This check uses the store's current values, so submission-time cache state is not authoritative. An active shared pause or a full global lease set can block the job before this classification.
For an unscoped queue, only the first ungranted job is classified as impossible in each store batch; later jobs return to the queue for a later admission.
Update one independent group key
With independent keyed groups, return
limits: 'managed' and named rules from the resolver. Call
group.get(key).getLimits() or group.get(key).updateLimits(patch) for that
key. Its stored values are authoritative on every worker sharing the namespace.
Resolver numeric values seed only an unknown key; changing those seeds does
not overwrite an existing policy, including after local eviction.
import { createValveGroup } from 'valvejs/group';
const tenants = createValveGroup({
id: 'crm:tenants',
resolve: () => ({
limits: 'managed',
rate: { name: 'tenant', limit: 10, interval: '1s' },
}),
});
try {
await tenants.get('tenant-42').updateLimits({ tenant: { limit: 40 } });
console.log(await tenants.get('tenant-42').getLimits());
} finally {
await tenants.close({ drain: true });
}Without a supplied store this example is local. Pass a Redis store to share updates across workers. Each key updates separately; there is no cross-key atomic update. Rule structure remains fixed, and immutable mismatches for the same child ID are rejected by the store.
Update scoped limits
The same patch changes the value for every identity under a scoped rule:
const messages = createValve({
id: 'messages:business-42',
limits: 'managed',
rate: [
{ name: 'shared', limit: 80, interval: '1s', burst: 8 },
{
name: 'recipient',
scope: 'recipient',
limit: 1,
interval: '6s',
},
],
store,
});
await messages.updateLimits({ recipient: { limit: 2 } });
await messages.run(() => sendMessage(), {
scopes: { recipient: 'contact-42' },
});Scoped Redis counters migrate lazily; Valve does not scan every identity when a rate changes. After a rate decrease, an identity touched before its old GCRA key expiry has its expiry extended and keeps exact debt. An identity with no admission attempt before that old expiry is treated as fully recovered at that time, which can be earlier than recovery under the new slower rate. This is the bounded cold-identity limitation of managed scoped decreases. Fixed-window counts and alignment are preserved.
The forgiven debt is smaller than the burst in effect at that identity's last
grant, and no larger than the rule's largest historical burst. A window that
starts after the last update still obeys the new GCRA bound of
limit + burst - 1 cost units; a window that straddles an update can include
work admitted under the earlier values. Scheduler lag can also make an
otherwise active identity miss its old expiry.
Observe and propagate changes
Listen for limits to observe a snapshot version that this process had not
seen:
api.on('limits', (snapshot) => {
logger.info(
{ version: snapshot.version, rules: snapshot.rules },
'limits changed',
);
});
api.on('warning', ({ message }) => logger.warn(message));The updating process wakes its own queue. A store notice for a relaxing change
(a limit or burst increase) wakes other waiting valves with up to 25 ms of
jitter; restrictive changes do not need an early wake because every eventual
admission reads authoritative values. Notifications are only wake-up hints.
As a backstop, a valve with a wait farther away than 1 second re-reads limits when the store has no subscriber. With a subscriber, that interval is 10 seconds. A newly observed relaxation re-evaluates waiting jobs. There is no subscriber per scoped identity.
Warnings also report a first-snapshot seed difference, a new registration epoch
after state loss, or a version that moved backwards after failover or restore.
On either state-loss warning, reconcile the snapshot and reapply the intended
values with expect; do not assume an earlier update survived.
Deploy managed limits safely
Immutable and managed workers can temporarily share an ID only while the stored policy has never received a managed update and their complete rules are identical. A managed worker adopts that existing state without resetting spent budget. Different immutable numeric values still reject immediately.
This temporary coexistence relies on the pinned-configuration guard, present in
plain Valve releases from 0.4.0 onward. Upgrade unguarded older binaries before
adoption; they cannot be relied on to fail closed after a managed update.
Before the first managed update, stop and drain every immutable worker for
the ID. That first committed update pins the managed structural policy; any
remaining immutable worker then rejects admissions with INVALID_OPTIONS.
Changing names, scopes, algorithms, intervals, the static/scoped shape, or
global concurrency still requires the coordinated
quota migration procedure.
Never delete Redis keys to apply a runtime update. Use updateLimits so spent
fixed-window counts and GCRA debt carry forward.
Plan for Redis state loss
Managed metadata and rate history must survive together. Use a dedicated
Redis/Valkey deployment with maxmemory-policy noeviction, persistence, memory
headroom, and failover monitoring. Eviction, flushes, restarts outside the
persistence window, or promotion of a lagging replica can reset the registration
epoch and numeric limits as well as spent budget. Valve warns when it observes
the new epoch or a backwards version, but it cannot restore lost state.
See Redis durability for the limits of persistence and replication.
Performance considerations
Managed admission resolves the authoritative snapshot and rate frame inside each atomic store decision. Updates and reads are control-plane operations, but the managed check is also present on the admission hot path. Notifications and polling can add rechecks when queues wait. Benchmark your own Redis latency, rule count, batch size, scoped identity distribution, and update frequency; the checked-in historical benchmark results cover immutable policies and do not establish managed-limit overhead or throughput.