Quick Start

Get adaptive gating running in your application in three steps.

1. Create an API key pair

Sign up and create a key pair in the dashboard. You'll get a publishKey (identifies your org) and a secretKey (signs telemetry). The secret is shown once.

2. Install and configure the SDK

npm install @waitstate/sdk

import { WaitState } from '@waitstate/sdk';

const ws = new WaitState({
  publishKey: process.env.WAITSTATE_PUBLISH_KEY,
  secretKey: process.env.WAITSTATE_SECRET_KEY,
});

3. Gate traffic

Call gate(tag, weight) before processing a request. It's synchronous, in-memory, and never makes a network call.

const decision = ws.gate('free', 1);

if (decision.allowed) {
  // proceed with request
} else {
  // respond with 429 or queue
  res.status(429).json({ error: 'rate_limited' });
}

Tags & Weights

Tags categorize traffic. Weights determine priority. When the reflex engine fires, low-weight traffic is shed first.

• Pass a tag and weight to gate() on each call.
• Create tags in the dashboard with default weights. The SDK doesn't need to know about tags ahead of time.
• Reflex rules can target specific tags (e.g. block "free" when latency > 500ms) or apply to all traffic.

How weight-based gating works

The control plane sets a globalMaxWeight and per-tag tagMaxWeights in the policy. When you call gate(tag, weight), the SDK compares your weight against these limits. If your weight exceeds the max, you're denied.

Example: during a latency spike, the policy might set globalMaxWeight: 5. Traffic with weight 1 ("free") gets blocked. Traffic with weight 10 ("enterprise") still gets blocked because 10 > 5. But the policy can also set tagMaxWeights to {"enterprise": Infinity} to exempt specific tags.

Reflex Rules

Reflex rules define automated responses to backend health metrics. They run in the control plane's PulseAggregator and affect the policy that gets pushed to your SDK instances.

Rule schema

{
  "tagName": "free",
  "metric": "latency",
  "operator": "gt",
  "threshold": 500,
  "action": "block",
  "actionValue": null,
  "enabled": true,
  "priority": 1
}

Throttle vs Block

Throttle example

{
  "tagName": "pro",
  "metric": "latency",
  "operator": "gt",
  "threshold": 500,
  "action": "throttle",
  "actionValue": 0.5,
  "enabled": true,
  "priority": 2
}

When latency exceeds 500ms, the reflex engine multiplies pro's max weight by 0.5. If the default max weight for pro is 10, it drops to 5. A gate('pro', 5) call still passes, but gate('pro', 7) would be denied.

Scenario: layered rules

Three rules, evaluated by priority:

1. Block free tier when latency is critical

{
  "tagName": "free",
  "metric": "latency",
  "operator": "gt",
  "threshold": 1000,
  "action": "block",
  "priority": 1
}

2. Throttle free tier when latency is elevated

{
  "tagName": "free",
  "metric": "latency",
  "operator": "gt",
  "threshold": 500,
  "action": "throttle",
  "actionValue": 0.5,
  "priority": 2
}

3. Throttle pro tier when errors spike

{
  "tagName": "pro",
  "metric": "errors",
  "operator": "gt",
  "threshold": 50,
  "action": "throttle",
  "actionValue": 0.7,
  "priority": 3
}

Progressive load shedding

As conditions worsen, more rules fire and lower tiers are shed first:

Manage rules in the dashboard or via the management API.

Pulse & Policy Flow

The SDK communicates with the control plane through two channels. You don't interact with either directly.

Pulses (SDK → Control Plane)

The SDK periodically sends a pulse containing gate() call counts, per-tag metrics, and process-level latency and error counts. Pulses are HMAC-signed with your secret key.

Pulse headers

POST /v1/pulse
x-waitstate-id: ws_pub_xxx          # your publishKey
x-waitstate-signature: <hmac-hex>   # HMAC-SHA256(body + '.' + timestamp, secretKey)
x-waitstate-timestamp: 1740000060000
content-type: application/json

Pulse payload

{
  "instanceId": "web-01",
  "siteId": "site-prod",
  "usageDelta": 967,
  "bouncedUnits": 47,
  "metrics": { "latency": 142, "errors": 0 },
  "tagMetrics": [
    { "tag": "free", "latency": 0, "count": 847 },
    { "tag": "pro",  "latency": 0, "count": 120,
      "customMetrics": {
        "queue_depth": { "min": 3, "max": 87, "sum": 450, "count": 10 }
      }
    }
  ],
  "ts": 1740000060000
}

Policy (Control Plane → SDK)

The pulse response contains the current policy. The SDK also polls GET /v1/policy/{orgId} with a JWT for edge-cached reads. Both sources update the same in-memory policy cache.

Policy shape

{
  "globalMaxWeight": 5,
  "tagMaxWeights": { "free": 0, "pro": 3 },
  "pulseInterval": 2000,
  "leaseDurationSeconds": 120,
  "status": "ok"            // "ok" | "cap_exceeded"
}

Authentication

WaitState uses a two-key model:

Pulse auth (HMAC-SHA256)

Each pulse is signed: HMAC-SHA256(body + timestamp, secretKey). The signature is sent as x-waitstate-signature. The control plane verifies before accepting.

Policy auth (JWT)

On init, the SDK exchanges your keys for a JWT via POST /v1/auth/token. The JWT is used for GET /v1/policy/{orgId} reads and auto-refreshes 2 minutes before expiry.

Management auth

Dashboard API calls use session-based auth (cookie). Programmatic management uses a bearer token.

Site Sharding

By default, the control plane routes all pulses from the same organization to a single aggregator. If you run multiple sites (e.g. staging, production, or separate apps) within one org, you can isolate them with siteId.

Pass siteId when creating the SDK instance. Each unique siteId gets its own aggregator with independent health tracking, reflex evaluation, and usage accounting. Sites are created automatically on the first pulse. No manual setup required. You can view and manage your sites in the dashboard.

• If omitted, siteId defaults to your orgId (one aggregator per org).
• Billing is still per-org. Monthly usage is tracked by orgId regardless of how many sites you have.
• Each site gets its own policy. A latency spike on staging won't throttle production.
• The number of sites is capped per plan: Hobby allows 1, Pro allows 10, Enterprise is unlimited.

Fail-Open & Safe Mode

WaitState is designed to never block traffic due to its own failures. But unlimited traffic during a prolonged outage is also dangerous. The lease mechanism provides a safety net.

Fail-open guarantees

• Control plane unreachable (short-term): SDK uses the last cached policy. Gate decisions continue normally.
• Never synced: If no policy was ever fetched (bootstrap), the default policy allows everything (globalMaxWeight: Infinity).
• Pulse fails: SDK retries on next interval. Telemetry counters are preserved and re-sent on the next successful pulse.
• Auth fails: SDK starts pulsing anyway with the default interval. Init errors go to onError.
• No reflex rules: All traffic is allowed.
• Unknown tag: gate() returns allow if the weight is under the global max.
• Kill signal: SDK stops pulsing, resets to fail-open default, and resumes after 24 hours.
• Monthly cap exceeded: Control plane returns status: cap_exceeded. SDK fails open (globalMaxWeight: Infinity) and backs off to 5-minute pulse intervals. When the new month starts, normal policy resumes automatically.

Lease & safe mode

Each policy includes a leaseDurationSeconds field. This is the maximum time the SDK trusts its cached policy without hearing from the control plane. If no successful pulse or policy response arrives within the lease window, the SDK enters safe mode.

Safe mode behavior

The safeModeStrategy constructor option controls what happens when the lease expires:

In all strategies:

• gate() returns reason: lease_expired for all calls (both allowed and denied).
• A [WAITSTATE-FATAL] log message fires once when safe mode activates.
• When the SDK successfully syncs again, normal policy-based gating resumes.

Why not just fail-open forever?

Pure fail-open means a prolonged control plane outage removes WaitState's intelligence layer entirely. Safe mode provides a hard floor: your API keeps serving traffic, but at a rate that won't overwhelm your backend. Your existing rate limiters and circuit breakers still apply either way.

Bootstrap grace period

The lease clock only starts after the first successful sync. During bootstrap (before the SDK has ever reached the control plane), gate() is fully fail-open. This prevents false safe-mode activations during cold starts or deployment rollouts.

Telemetry & Metrics

Every SDK and the agent expose the same telemetry methods. These feed into the pulse payload so the reflex engine can react to backend health. Without telemetry, reflex rules on latency and errors evaluate against zero.

Built-in metrics

All SDKs provide methods for reporting latency and errors. Method names follow each language's conventions (reportLatency in JS, report_latency in Rust/Python) but the semantics and aggregation behavior are identical.

// Timer pattern (recommended)
const stop = ws.startTimer('search');
const result = await doSearch(query);
stop(); // reports elapsed ms as latency

// Direct reporting
ws.reportLatency(42.5, 'search');  // ms
ws.reportError('search');

Custom metrics: report(metric, value, tag?)

Report a custom metric value. Each metric is aggregated as min/max/sum/count per pulse window, giving you average, minimum, and maximum values in the control plane. Create reflex rules on any custom metric name to trigger automated responses.

// Report a custom metric (min/max/sum/count aggregated per pulse)
ws.report('queue_depth', 87, 'search');
ws.report('cache_hit_rate', 0.92, 'search');

// Without a tag, defaults to '__default__'
ws.report('active_connections', 142);

Custom metric reflex rule

Custom metrics work with the same reflex rule engine as latency and errors. The reflex engine evaluates the metric's average (sum/count) against your threshold.

// Block search traffic when queue depth exceeds 100
{
  "tagName": "search",
  "metric": "queue_depth",
  "operator": "gt",
  "threshold": 100,
  "action": "block",
  "actionValue": null,
  "enabled": true,
  "priority": 1
}

Plan limits

Metrics reported via report() always flow through the pipeline. The plan limit controls how many distinct custom metric names can be used in reflex rules. Excess metrics in the data pipeline are silently trimmed (alphabetical order, kept first N).

Use Cases

WaitState works anywhere you need to shed traffic intelligently under pressure: GraphQL APIs, AI gateways, e-commerce, multi-tenant SaaS, fintech, gaming, IoT, and more. Each use case includes integration code, reflex rules, and a walkthrough of what happens under load.

See all use cases with integration examples →

JavaScript / TypeScript SDK

The official JS/TS SDK. Zero dependencies. All SDKs share the same gate(tag, weight) interface and pulse/policy protocol.

Install

npm install @waitstate/sdk

Constructor

const ws = new WaitState({
  publishKey: process.env.WAITSTATE_PUBLISH_KEY,
  secretKey: process.env.WAITSTATE_SECRET_KEY,
  siteId: 'site-prod',            // optional, shard key (defaults to orgId)
  instanceId: 'web-01',           // optional, defaults to randomUUID()
  pulseInterval: 5000,            // optional, ms between pulses (server can override)
  safeModeStrategy: 'open',         // optional, 'open' | 'fixed_rps' | 'last_policy'
  safeModeMaxRps: 50,               // optional, max req/sec in safe mode (default: 50)
  baseUrl: 'https://api.waitstate.io',  // optional
  onError: (err) => console.error('[waitstate]', err),
});

gate(tag?, weight?)

Synchronous. Returns a GateResult. Never throws.

// Tag-based gating with weight
const d1 = ws.gate('enterprise', 10);  // high-priority traffic
const d2 = ws.gate('free', 1);         // low-priority traffic
const d3 = ws.gate();                  // no tag, weight defaults to 1

// Check the reason for denial
if (!decision.allowed) {
  switch (decision.reason) {
    case 'tag_blocked':   // this tag is explicitly blocked by policy
    case 'over_weight':   // weight exceeds global max
    case 'global_block':  // all traffic blocked
    case 'kill_signal':   // emergency kill from control plane
    case 'lease_expired': // control plane lease expired, safe mode (safeModeMaxRps req/s)
      break;
  }
}

GateResult

// Allowed
{ "allowed": true, "reason": "allowed" }

// Denied
{ "allowed": false, "reason": "tag_blocked" }
{ "allowed": false, "reason": "over_weight" }
{ "allowed": false, "reason": "global_block" }
{ "allowed": false, "reason": "kill_signal" }

// Safe mode (lease expired, behavior depends on safeModeStrategy)
{ "allowed": true,  "reason": "lease_expired" }
{ "allowed": false, "reason": "lease_expired" }

Telemetry & custom metrics

The JS SDK exposes reportLatency(), reportError(), startTimer(), and report() for custom metrics. These are platform-wide features available in every SDK and the agent. See Telemetry & Metrics for full documentation, naming rules, and plan limits.

shutdown()

Async. Stops the pulse timer, clears the auth refresh timer, and sends one final pulse to flush pending telemetry.

// Flush pending pulses on graceful shutdown
process.on('SIGTERM', async () => {
  await ws.shutdown();
  process.exit(0);
});

Advanced exports

For low-level use, the SDK also exports individual components:

• gate(policy, tag?, weight?) -standalone pure function, takes a BouncerPolicy directly
• PolicyCache -in-memory policy store (get(), update(), reset())
• TelemetryCollector -accumulates gate metrics between pulses
• signPulse(body, timestamp, secretKey) -returns HMAC-SHA256 hex digest
• createSignedHeaders(body, publishKey, secretKey) -returns signed header object
• AuthManager -manages JWT token lifecycle
• WaitStateError -error class with status, code, message

Example: Express middleware

import express from 'express';
import { WaitState } from '@waitstate/sdk';

const app = express();
const ws = new WaitState({
  publishKey: process.env.WAITSTATE_PUBLISH_KEY,
  secretKey: process.env.WAITSTATE_SECRET_KEY,
});

app.use((req, res, next) => {
  const tag = req.user?.plan ?? 'free';
  const weight = tag === 'enterprise' ? 10 : tag === 'pro' ? 5 : 1;
  const decision = ws.gate(tag, weight);

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

  // Track latency and errors for the reflex engine
  const stop = ws.startTimer(tag);
  res.on('finish', () => {
    stop();
    if (res.statusCode >= 500) ws.reportError(tag);
  });
  next();
});

Framework middleware

Drop-in middleware for popular frameworks. Each is a separate subpath export with zero runtime dependencies on the framework — types are structural.

import express from 'express';
import { WaitState } from '@waitstate/sdk';
import { createMiddleware } from '@waitstate/sdk/express';

const app = express();
const ws = new WaitState({
  publishKey: process.env.WAITSTATE_PUBLISH_KEY,
  secretKey: process.env.WAITSTATE_SECRET_KEY,
});

app.use(createMiddleware({ waitstate: ws }));

import Fastify from 'fastify';
import { WaitState } from '@waitstate/sdk';
import { createPlugin } from '@waitstate/sdk/fastify';

const app = Fastify();
const ws = new WaitState({
  publishKey: process.env.WAITSTATE_PUBLISH_KEY,
  secretKey: process.env.WAITSTATE_SECRET_KEY,
});

createPlugin({ waitstate: ws })(app);

import { Hono } from 'hono';
import { WaitState } from '@waitstate/sdk';
import { createMiddleware } from '@waitstate/sdk/hono';

const app = new Hono();
const ws = new WaitState({
  publishKey: process.env.WAITSTATE_PUBLISH_KEY,
  secretKey: process.env.WAITSTATE_SECRET_KEY,
});

app.use('*', createMiddleware({ waitstate: ws }));

import { WaitState } from '@waitstate/sdk';
import { withGate } from '@waitstate/sdk/nextjs';

const ws = new WaitState({
  publishKey: process.env.WAITSTATE_PUBLISH_KEY,
  secretKey: process.env.WAITSTATE_SECRET_KEY,
});

export const GET = withGate({ waitstate: ws }, async (req) => {
  return Response.json({ ok: true });
});

Middleware options

All middleware accept the same options:

createMiddleware({
  waitstate: ws,
  tagFrom: 'x-waitstate-tag',         // header name, or (req) => string
  weightFrom: 'x-waitstate-weight',   // header name, or (req) => number
  retryAfter: 60,                     // Retry-After header value (seconds)
  onDenied: (req, res, result) => {   // custom deny handler
    res.statusCode = 429;
    res.end('Too many requests');
  },
});

Each middleware automatically reports latency (on response) and errors (on 5xx) to the reflex engine.

Gotchas

Rust SDK

The Rust SDK (waitstate-rs) provides the same gate(tag, weight) interface with lock-free, zero-allocation gate checks. Built for high-throughput services where microsecond-level overhead matters.

Install

cargo add waitstate

Methods

Internals

• Policy stored in ArcSwap for lock-free reads on the gate path.
• Per-tag counters use DashMap with AtomicU64 for contention-free telemetry accumulation.
• Background tasks (pulse every 20s, sync every 30s) run on Tokio and never block the gate call.
• HMAC-SHA256 signing via hmac/sha2 crates. JWT auth for policy reads.
• Same fail-open and safe-mode guarantees as the JS SDK. If the lease expires, gate() throttles to 50 req/sec.

Agent (Kubernetes DaemonSet)

The WaitState Agent is a standalone Rust binary that runs as a Kubernetes DaemonSet sidecar. Instead of embedding the SDK in every service, you deploy the agent once per node and call it over localhost.

Routes

How it works

The agent wraps the Rust SDK internally. It collects metrics from all pods on the node via /coprocess, aggregates them, and sends a single pulse to the control plane on behalf of every service on that node. This means:

• Your services don't need the WaitState SDK as a dependency. Just POST to localhost:9000/gate.
• Metrics from all pods on the node are bundled into one pulse, giving the reflex engine a node-level view of health.
• Gate checks are still sub-millisecond (localhost HTTP call + in-memory policy lookup in the agent).
• Works with any language. If your service can make an HTTP call, it can use WaitState.

When to use the agent vs. the SDK

Edge SDK (WASM)

The Edge SDK is the Rust core compiled to WebAssembly. It provides the same gate(tag, weight) interface for edge runtimes where Node.js APIs aren't available.

Install

npm install @waitstate/edge

Exported functions

The Edge SDK is lower-level than the Node.js SDK. You manage the pulse/policy lifecycle yourself (typically via a Durable Object or KV cache). The gate() function is a pure, synchronous check against a policy you provide.

Python SDK

Native extension compiled from the Rust core via UniFFI. The same lock-free gate engine, exposed as a Python package with framework middleware for FastAPI, Flask, and Django.

Install

pip install waitstate

Basic usage

import os
from waitstate import WaitstateClient, WaitstateConfig

client = WaitstateClient(WaitstateConfig(
    publish_key=os.environ["WAITSTATE_PUBLISH_KEY"],
    secret_key=os.environ["WAITSTATE_SECRET_KEY"],
))

result = client.gate("search", 1.0)
if result.allowed:
    # proceed with request
    pass

Framework middleware

import os
from fastapi import FastAPI, Depends, Request
from waitstate import WaitstateClient, WaitstateConfig
from waitstate.middleware.fastapi import create_dependency, create_response_hook

app = FastAPI()
client = WaitstateClient(WaitstateConfig(
    publish_key=os.environ["WAITSTATE_PUBLISH_KEY"],
    secret_key=os.environ["WAITSTATE_SECRET_KEY"],
))

gate = create_dependency(client)
app.middleware("http")(create_response_hook(client))

@app.get("/search")
async def search(request: Request, _=Depends(gate)):
    return {"results": []}

from flask import Flask
from waitstate import WaitstateClient, WaitstateConfig
from waitstate.middleware.flask import init_app

app = Flask(__name__)
client = WaitstateClient(WaitstateConfig(
    publish_key="ws_pub_xxx",
    secret_key="ws_sec_xxx",
))

init_app(app, client)

@app.route("/search")
def search():
    return {"results": []}

from waitstate import WaitstateClient, WaitstateConfig

WAITSTATE_CLIENT = WaitstateClient(WaitstateConfig(
    publish_key="ws_pub_xxx",
    secret_key="ws_sec_xxx",
))

MIDDLEWARE = [
    "waitstate.middleware.django.WaitStateMiddleware",
    # ...
]

Agent mode

If you're using the agent sidecar, the Python SDK can talk to it over localhost instead of running the full Rust client in-process:

from waitstate import WaitstateClient, WaitstateConfig

# Agent mode: no keys needed, talks to local sidecar
client = WaitstateClient(WaitstateConfig(
    publish_key="",
    secret_key="",
    agent_url="http://localhost:9000",
))

Custom metrics

The Python SDK supports custom metrics via report(metric, value, tag). Same naming rules and plan limits as the JS and Rust SDKs.

Go SDK

Java SDK

C# / .NET SDK

Ruby SDK

Elixir SDK

PHP SDK

API Reference

The control plane exposes these endpoints. The SDK handles pulse and policy automatically. Management endpoints are for dashboard or CI use.

SDK endpoints (handled by SDK)

Management endpoints

Example: Create API key pair

curl -X POST https://api.waitstate.io/v1/api-keys \
  -H "Authorization: Bearer <management-token>" \
  -H "Content-Type: application/json" \
  -d '{ "environment": "live" }'

{
  "id": "key_xxx",
  "publishKey": "ws_pub_xxx",
  "secretKey": "ws_sec_xxx",
  "environment": "live"
}

Glossary

Canonical definitions for terms used across WaitState SDKs, the control plane, and this documentation.