Unified Admission Control: Rate, Concurrency, Cost

import {
  unifiedAdmission,
  rateLimit,
  adaptiveConcurrency,
  gcra,
  tokenBucket,
} from "throttlekit";

const admit = unifiedAdmission({
  rate: rateLimit({ strategy: gcra({ limit: 60, periodMs: 60_000 }) }),
  concurrency: adaptiveConcurrency({ minLimit: 4, maxLimit: 16 }),
  cost: rateLimit({ strategy: tokenBucket({ capacity: 100_000, refillPerSec: 1_667 }) }),
});

// In a request handler:
const { decision, release } = await admit.admit({
  key: req.user.id,
  cost: req.body.maxTokens ?? 1_000,
});

if (!decision.allowed) {
  res.status(429).json({ retryAfterMs: decision.retryAfterMs });
  return;
}

res.on("finish", () => release({ dropped: false }));
res.on("close", () => release({ dropped: true }));

combine(a, b) = {
  allowed:      a.allowed && b.allowed,         // AND
  limit:        min(a.limit, b.limit),           // binding ceiling
  remaining:    min(a.remaining, b.remaining),
  resetAt:      max(a.resetAt, b.resetAt),       // dominant wait
  retryAfterMs: max(a.retryAfterMs, b.retryAfterMs),
}

interface UnifiedAdmitter {
  admit(opts?: UnifiedAdmitOptions): Promise<UnifiedAdmission>;
  admitSync(opts?: UnifiedAdmitOptions): UnifiedAdmission;
  lastDecisions(): Readonly<Partial<Record<UnifiedAxis, Decision | undefined>>>;
}

const { decision, release, bindingAxis } = await admit.admit({ key: userId, cost: tokens });

if (!decision.allowed) {
  console.log("denied by:", bindingAxis); // "rate" | "concurrency" | "cost" | undefined
  return;
}

try {
  await doWork();
} finally {
  release({ dropped: false }); // normal completion
  // or: release({ dropped: true }) on timeout/error to signal overload
}

import { tokenBudget } from "throttlekit";

const meter = tokenBudget({ budget: 100_000, windowMs: 60_000 });

for await (const tok of completion) {
  if (!meter.debitSync(1).allowed) break; // budget spent — stop generating
  emit(tok);
}

import { learnedReservation, tokenBudget } from "throttlekit";

const meter  = tokenBudget({ budget: 100_000, windowMs: 60_000 });
const policy = learnedReservation({
  holdCost: 1,
  overrunCost: 4,
  maxReservation: 4_096,
});

// At admission:
if (policy.reserve() <= meter.remaining()) {
  let produced = 0;
  for await (const tok of completion) {
    if (!meter.debitSync(1).allowed) break;
    produced++;
    emit(tok);
  }
  policy.observe(produced); // learn from the realised cost
}

import { weightedMaxMin } from "throttlekit";

const credits = weightedMaxMin(
  [800, 400, 200],    // demands
  [4, 2, 1],          // weights (enterprise, pro, free)
  1000                // total limit
);
// credits = [571, 286, 143]  (weighted water-fill, ≤ demand, sum = 1000)

import { weightedFairShare } from "throttlekit";

const limiter = weightedFairShare({
  limit: 1_000,
  windowMs: 60_000,
  weightOf: (tenant) => tenantWeight(tenant),
});

const d = limiter.checkSync("enterprise:alpha", 100, 4); // cost=100, weight=4

p = max(0, (requests − K × accepts) / (requests + 1))

import { adaptiveThrottle } from "throttlekit";

const throttle = adaptiveThrottle({ k: 2, windowMs: 10_000 });

// Before each outbound call:
if (throttle.request()) {
  const ok = await callBackend();
  throttle.record(ok); // feed back: accepted or rejected
} else {
  // shed locally — do not call the backend
}

admit iff: value ≥ p_R + p_C × cost

const admit = unifiedAdmission({
  rate: rateLimiter,
  cost: costLimiter,
  policy: "joint-lp",
  jointLp: {
    workload: {
      types: [
        { cost: 200,   value: 1, weight: 0.7 },  // small completions
        { cost: 8_000, value: 3, weight: 0.3 },  // large completions
      ],
      rateBudget: 60,
      costBudget: 100_000,
    },
  },
});

// Per-request: provide a value signal
const { decision } = await admit.admit({
  key: userId,
  cost: requestedTokens,
  value: requestPriority,
});

import {
  ManualClock,
  adaptiveConcurrency,
  gcra,
  rateLimit,
  tokenBucket,
  unifiedAdmission,
} from "throttlekit";
import { bindingAxisOf } from "throttlekit/otel";

const clock = new ManualClock(0);

const admit = unifiedAdmission({
  rate: rateLimit({ strategy: gcra({ limit: 60, periodMs: 60_000 }), clock }),
  concurrency: adaptiveConcurrency({ clock, minLimit: 4, initialLimit: 4, maxLimit: 4 }),
  cost: rateLimit({
    strategy: tokenBucket({ capacity: 100_000, refillPerSec: 100_000 / 60 }),
    clock,
  }),
  clock,
});

const calls = [
  { tenant: "alice", tokens: 200 },
  { tenant: "bob",   tokens: 8_000 },
];

const heldReleases: Array<() => void> = [];
for (const call of calls) {
  const { decision, release } = admit.admitSync({ key: call.tenant, cost: call.tokens });
  if (decision.allowed) {
    heldReleases.push(release);
  } else {
    const axis = bindingAxisOf(admit.lastDecisions());
    console.log(`denied by ${axis}: retryAfter ${decision.retryAfterMs}ms`);
  }
}

// Release all held slots when work completes
for (const r of heldReleases) r();