halt-rate 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AtomicStore, R as RedisClientLike, E as EvaluateInput, D as Decision, P as Policy } from './limiter-HCt8ADZ2.js';
-export { a as Algorithm, I as InMemoryStore, K as KeyStrategy, b as RateLimiter, c as RateLimiterOptions, S as Store, i as isAtomicStore, n as normalizePolicy, t as toHeaders } from './limiter-HCt8ADZ2.js';
+import { A as AtomicStore, R as RedisClientLike, E as EvaluateInput, D as Decision, P as Policy, T as TelemetryHooks, Q as Quota, a as Penalty } from './limiter-DqVVE0Kl.js';
+export { b as Algorithm, C as CompositeTelemetry, I as InMemoryStore, K as KeyStrategy, L as LoggingTelemetry, M as MetricsTelemetry, c as PENALTY_LENIENT, d as PENALTY_MODERATE, e as PENALTY_STRICT, f as PenaltyConfig, g as PenaltyManager, h as QUOTA_ENTERPRISE_MONTHLY, i as QUOTA_FREE_DAILY, j as QUOTA_FREE_MONTHLY, k as QUOTA_PRO_DAILY, l as QUOTA_PRO_MONTHLY, m as QuotaManager, n as QuotaPeriod, o as RateLimiter, p as RateLimiterOptions, S as Store, q as isAtomicStore, r as normalizePolicy, t as toHeaders } from './limiter-DqVVE0Kl.js';
 
 /**
  * Redis storage backend for Halt — production-grade, atomic rate limiting.
@@ -130,4 +130,175 @@ declare namespace extractors {
   export { extractors_HEALTH_CHECK_PATHS as HEALTH_CHECK_PATHS, extractors_extractApiKey as extractApiKey, extractors_extractIp as extractIp, extractors_extractPath as extractPath, extractors_extractUserId as extractUserId, extractors_isHealthCheck as isHealthCheck, extractors_isPrivateIp as isPrivateIp };
 }
 
-export { AtomicStore, Decision, EvaluateInput, type FailMode, Policy, RedisClientLike, RedisStore, type RedisStoreOptions, extractors, index as presets };
+/**
+ * Dynamic limits — change policies at runtime without restarting.
+ *
+ * `PolicyRegistry` holds named policies you can mutate live. Use it as the
+ * limiter's `policy` via `registry.resolver(selector)`:
+ *
+ *   const registry = new PolicyRegistry([presets.PUBLIC_API]);
+ *   const limiter = new RateLimiter({
+ *     store,
+ *     policy: registry.resolver((req) => 'public_api'),
+ *   });
+ *   // later, no restart:
+ *   registry.update('public_api', { limit: 500 });
+ *
+ * For limits stored in Redis/DB/config (and shared across a fleet), use
+ * `cachedPolicyResolver` with a loader that reads that shared state.
+ */
+
+declare class PolicyRegistry {
+    private policies;
+    constructor(initial?: Policy[]);
+    /** Add or replace a policy (keyed by `policy.name`). */
+    register(policy: Policy): this;
+    get(name: string): Policy | undefined;
+    has(name: string): boolean;
+    /** Mutate fields of an existing policy at runtime (e.g. `{ limit: 500 }`). */
+    update(name: string, patch: Partial<Omit<Policy, 'name'>>): Policy;
+    remove(name: string): boolean;
+    list(): Policy[];
+    /**
+     * Build a resolver for the limiter's `policy` option.
+     * @param selector maps a request to a registered policy name.
+     */
+    resolver(selector: (request: any) => string): (request: any) => Policy;
+}
+interface CachedPolicyResolverOptions {
+    /** Cache entry lifetime in ms (default 5000). */
+    ttlMs?: number;
+    /** Cache key for a request (default: the loaded policy is shared under one key). */
+    key?: (request: any) => string;
+}
+/**
+ * Wrap a (possibly async) loader with a per-key TTL cache. The loader reads your
+ * source of truth (Redis/DB/config), so limits propagate across a fleet and
+ * refresh live — without restarting. Use the returned function as `policy`.
+ */
+declare function cachedPolicyResolver(loader: (request: any) => Policy | Promise<Policy>, options?: CachedPolicyResolverOptions): (request: any) => Promise<Policy>;
+
+/**
+ * In-process statistics collector for rate-limit observability.
+ *
+ * Implements `TelemetryHooks`, so you plug it into a RateLimiter (and optionally
+ * QuotaManager / PenaltyManager) and it aggregates everything in memory. Call
+ * `snapshot()` to expose a `/halt/stats` endpoint or log periodically.
+ *
+ * It is per-process by design — for a fleet, run it on each instance and roll up
+ * across instances with the OpenTelemetry adapter (see observability/otel). Memory
+ * is bounded: the tracked-key table is capped and the smallest counters are evicted.
+ *
+ *   const stats = new StatsCollector();
+ *   const limiter = new RateLimiter({ store, policy, telemetry: stats });
+ *   app.get('/halt/stats', (_req, res) => res.json(stats.snapshot()));
+ */
+
+interface StatsCollectorOptions {
+    /** How many top limited keys `snapshot()` returns (default 20). */
+    topN?: number;
+    /** Max distinct keys tracked for the top-N table before eviction (default 10000). */
+    maxTrackedKeys?: number;
+}
+interface Tally {
+    allowed: number;
+    blocked: number;
+}
+interface EndpointTally extends Tally {
+    cost: number;
+}
+interface StatsSnapshot {
+    allowedTotal: number;
+    blockedTotal: number;
+    /** Per-policy allowed/blocked counts. */
+    byPolicy: Record<string, Tally>;
+    /** Per-endpoint allowed/blocked counts and consumed cost. */
+    byEndpoint: Record<string, EndpointTally>;
+    /** Highest-blocked keys (users / API keys / IPs), descending. */
+    topLimitedKeys: Array<{
+        key: string;
+        blocked: number;
+    }>;
+    /** Consumed cost per plan (allowed requests only). */
+    costByPlan: Record<string, number>;
+    /** Count of quota-exceeded events (from QuotaManager telemetry). */
+    quotaExceeded: number;
+    /** Count of penalties applied (from PenaltyManager telemetry). */
+    penaltiesApplied: number;
+    /** Count of recorded violations (from PenaltyManager telemetry). */
+    violations: number;
+    /** Number of distinct keys currently tracked for top-N. */
+    trackedKeys: number;
+}
+declare class StatsCollector implements TelemetryHooks {
+    private topN;
+    private maxTrackedKeys;
+    private allowedTotal;
+    private blockedTotal;
+    private byPolicy;
+    private byEndpoint;
+    private limitedKeys;
+    private costByPlan;
+    private quotaExceededCount;
+    private penaltiesAppliedCount;
+    private violationsCount;
+    constructor(options?: StatsCollectorOptions);
+    onAllowed(_key: string, _decision: Decision, metadata?: Record<string, any>): void;
+    onBlocked(key: string, _decision: Decision, metadata?: Record<string, any>): void;
+    onQuotaExceeded(_identifier: string, _quota: Quota): void;
+    onPenaltyApplied(_identifier: string, _penalty: Penalty): void;
+    onViolation(_identifier: string, _penalty: Penalty, _severity: number): void;
+    /** Point-in-time view of the aggregated stats. */
+    snapshot(): StatsSnapshot;
+    /** Clear all counters (e.g. after exporting). */
+    reset(): void;
+    private policyTally;
+    private endpointTally;
+    private trackLimitedKey;
+    /** Evict the lowest-count tracked key to keep memory bounded. */
+    private evictSmallest;
+}
+
+/**
+ * OpenTelemetry metrics adapter for Halt.
+ *
+ * Implements `TelemetryHooks` over the OTel metrics API. You inject a Meter, so
+ * Halt keeps no hard dependency on `@opentelemetry/api`:
+ *
+ *   import { metrics } from '@opentelemetry/api';
+ *   import { OpenTelemetryMetrics } from 'halt-rate';
+ *
+ *   const telemetry = new OpenTelemetryMetrics(metrics.getMeter('halt'));
+ *   const limiter = new RateLimiter({ store, policy, telemetry });
+ *
+ * Request spans are already covered by the limiter's `otelTracer` option; this
+ * adapter adds counters for dashboards/alerts. Roll up across instances with your
+ * OTel collector.
+ */
+
+/** Minimal structural types satisfied by `@opentelemetry/api` (no hard dep). */
+interface OTelCounterLike {
+    add(value: number, attributes?: Record<string, string | number | boolean>): void;
+}
+interface OTelMeterLike {
+    createCounter(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): OTelCounterLike;
+}
+declare class OpenTelemetryMetrics implements TelemetryHooks {
+    private requests;
+    private blocked;
+    private cost;
+    private quotaExceededCounter;
+    private penaltyAppliedCounter;
+    private violationsCounter;
+    constructor(meter: OTelMeterLike);
+    onAllowed(_key: string, _decision: Decision, metadata?: Record<string, any>): void;
+    onBlocked(_key: string, _decision: Decision, metadata?: Record<string, any>): void;
+    onQuotaExceeded(_identifier: string, quota: Quota): void;
+    onPenaltyApplied(_identifier: string, _penalty: Penalty): void;
+    onViolation(_identifier: string, _penalty: Penalty, severity: number): void;
+}
+
+export { AtomicStore, type CachedPolicyResolverOptions, Decision, EvaluateInput, type FailMode, type OTelCounterLike, type OTelMeterLike, OpenTelemetryMetrics, Penalty, Policy, PolicyRegistry, Quota, RedisClientLike, RedisStore, type RedisStoreOptions, StatsCollector, type StatsCollectorOptions, type StatsSnapshot, TelemetryHooks, cachedPolicyResolver, extractors, index as presets };