halt-rate 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -31,7 +31,8 @@ function normalizePolicy(policy) {
     cost: policy.cost ?? 1,
     blockDuration: policy.blockDuration ?? void 0,
     keyExtractor: policy.keyExtractor ?? void 0,
-    exemptions: policy.exemptions ?? []
+    exemptions: policy.exemptions ?? [],
+    plan: policy.plan ?? void 0
   };
   if (normalized.limit <= 0) {
     throw new Error("limit must be positive");
@@ -402,6 +403,25 @@ var RateLimiter = class {
     this.algorithmCache = /* @__PURE__ */ new Map();
     this.otelTracer = options.otelTracer;
     this.metricsRecorder = options.metricsRecorder;
+    this.telemetry = options.telemetry;
+  }
+  /** Fan a finished decision out to the telemetry hooks with rich metadata. */
+  emitTelemetry(request, key, decision, policy, cost) {
+    if (!this.telemetry) return;
+    const metadata = {
+      policy: policy.name,
+      algorithm: policy.algorithm,
+      keyStrategy: policy.keyStrategy,
+      endpoint: extractPath(request) ?? void 0,
+      cost,
+      plan: policy.plan
+    };
+    this.telemetry.onCheck?.(key, decision, metadata);
+    if (decision.allowed) {
+      this.telemetry.onAllowed?.(key, decision, metadata);
+    } else {
+      this.telemetry.onBlocked?.(key, decision, metadata);
+    }
   }
   /**
    * Check if request is allowed under rate limit.
@@ -460,6 +480,7 @@ var RateLimiter = class {
         1
       );
       span2?.end?.();
+      this.emitTelemetry(request, key, decision2, policy, requestCost);
       return decision2;
     }
     const store = this.store;
@@ -543,6 +564,7 @@ var RateLimiter = class {
       this.metricsRecorder?.("halt.request.blocked", { policy: policy.name }, 1);
     }
     span?.end?.();
+    this.emitTelemetry(request, key, decision, policy, requestCost);
     return decision;
   }
   /**
@@ -1006,6 +1028,7 @@ var GENEROUS_API = {
 };
 var PLAN_FREE = {
   name: "free_plan",
+  plan: "free",
   limit: 100,
   window: 3600,
   // 100 requests per hour
@@ -1015,6 +1038,7 @@ var PLAN_FREE = {
 };
 var PLAN_STARTER = {
   name: "starter_plan",
+  plan: "starter",
   limit: 500,
   window: 3600,
   // 500 requests per hour
@@ -1024,6 +1048,7 @@ var PLAN_STARTER = {
 };
 var PLAN_PRO = {
   name: "pro_plan",
+  plan: "pro",
   limit: 2e3,
   window: 3600,
   // 2000 requests per hour
@@ -1033,6 +1058,7 @@ var PLAN_PRO = {
 };
 var PLAN_BUSINESS = {
   name: "business_plan",
+  plan: "business",
   limit: 5e3,
   window: 3600,
   // 5000 requests per hour
@@ -1042,6 +1068,7 @@ var PLAN_BUSINESS = {
 };
 var PLAN_ENTERPRISE = {
   name: "enterprise_plan",
+  plan: "enterprise",
   limit: 2e4,
   window: 3600,
   // 20000 requests per hour
@@ -1066,6 +1093,524 @@ function getPlanPolicy(planName) {
   return PLAN_TIERS[normalized];
 }
 
-export { Algorithm, InMemoryStore, KeyStrategy, RateLimiter, RedisStore, extractors_exports as extractors, isAtomicStore, normalizePolicy, presets_exports as presets, toHeaders };
+// src/core/quota.ts
+var QuotaPeriod = /* @__PURE__ */ ((QuotaPeriod2) => {
+  QuotaPeriod2["HOURLY"] = "hourly";
+  QuotaPeriod2["DAILY"] = "daily";
+  QuotaPeriod2["MONTHLY"] = "monthly";
+  QuotaPeriod2["YEARLY"] = "yearly";
+  return QuotaPeriod2;
+})(QuotaPeriod || {});
+var QuotaManager = class {
+  constructor(store, telemetry) {
+    this.store = store;
+    this.telemetry = telemetry;
+  }
+  getQuotaKey(identifier, quotaName) {
+    return `halt:quota:${quotaName}:${identifier}`;
+  }
+  calculateResetTime(period) {
+    const now = /* @__PURE__ */ new Date();
+    switch (period) {
+      case "hourly" /* HOURLY */:
+        const nextHour = new Date(now);
+        nextHour.setHours(now.getHours() + 1, 0, 0, 0);
+        return Math.floor(nextHour.getTime() / 1e3);
+      case "daily" /* DAILY */:
+        const nextDay = new Date(now);
+        nextDay.setDate(now.getDate() + 1);
+        nextDay.setHours(0, 0, 0, 0);
+        return Math.floor(nextDay.getTime() / 1e3);
+      case "monthly" /* MONTHLY */:
+        const nextMonth = new Date(now);
+        if (now.getMonth() === 11) {
+          nextMonth.setFullYear(now.getFullYear() + 1, 0, 1);
+        } else {
+          nextMonth.setMonth(now.getMonth() + 1, 1);
+        }
+        nextMonth.setHours(0, 0, 0, 0);
+        return Math.floor(nextMonth.getTime() / 1e3);
+      case "yearly" /* YEARLY */:
+        const nextYear = new Date(now);
+        nextYear.setFullYear(now.getFullYear() + 1, 0, 1);
+        nextYear.setHours(0, 0, 0, 0);
+        return Math.floor(nextYear.getTime() / 1e3);
+      default:
+        throw new Error(`Invalid quota period: ${period}`);
+    }
+  }
+  async getQuota(identifier, quota) {
+    const key = this.getQuotaKey(identifier, quota.name);
+    const stored = await this.store.get(key);
+    if (!stored) {
+      return {
+        name: quota.name,
+        limit: quota.limit,
+        period: quota.period,
+        currentUsage: 0,
+        resetAt: this.calculateResetTime(quota.period)
+      };
+    }
+    const currentQuota = {
+      name: stored.name || quota.name,
+      limit: stored.limit || quota.limit,
+      period: stored.period || quota.period,
+      currentUsage: stored.currentUsage || 0,
+      resetAt: stored.resetAt
+    };
+    const now = Math.floor(Date.now() / 1e3);
+    if (currentQuota.resetAt && now >= currentQuota.resetAt) {
+      currentQuota.currentUsage = 0;
+      currentQuota.resetAt = this.calculateResetTime(currentQuota.period);
+    }
+    return currentQuota;
+  }
+  async checkQuota(identifier, quota, cost = 1) {
+    const currentQuota = await this.getQuota(identifier, quota);
+    const allowed = (currentQuota.currentUsage || 0) + cost <= currentQuota.limit;
+    this.telemetry?.onQuotaCheck?.(identifier, currentQuota, allowed);
+    if (!allowed) {
+      this.telemetry?.onQuotaExceeded?.(identifier, currentQuota);
+    }
+    return { allowed, quota: currentQuota };
+  }
+  async consumeQuota(identifier, quota, cost = 1) {
+    const currentQuota = await this.getQuota(identifier, quota);
+    currentQuota.currentUsage = (currentQuota.currentUsage || 0) + cost;
+    const key = this.getQuotaKey(identifier, quota.name);
+    const ttl = (currentQuota.resetAt || 0) - Math.floor(Date.now() / 1e3) + 3600;
+    await this.store.set(key, currentQuota, ttl);
+    return currentQuota;
+  }
+  async resetQuota(identifier, quota) {
+    const key = this.getQuotaKey(identifier, quota.name);
+    await this.store.delete(key);
+  }
+  remaining(quota) {
+    return Math.max(0, quota.limit - (quota.currentUsage || 0));
+  }
+  isExceeded(quota) {
+    return (quota.currentUsage || 0) >= quota.limit;
+  }
+};
+var QUOTA_FREE_MONTHLY = {
+  name: "free_monthly_requests",
+  limit: 1e4,
+  period: "monthly" /* MONTHLY */
+};
+var QUOTA_PRO_MONTHLY = {
+  name: "pro_monthly_requests",
+  limit: 1e5,
+  period: "monthly" /* MONTHLY */
+};
+var QUOTA_ENTERPRISE_MONTHLY = {
+  name: "enterprise_monthly_requests",
+  limit: 1e6,
+  period: "monthly" /* MONTHLY */
+};
+var QUOTA_FREE_DAILY = {
+  name: "free_daily_requests",
+  limit: 500,
+  period: "daily" /* DAILY */
+};
+var QUOTA_PRO_DAILY = {
+  name: "pro_daily_requests",
+  limit: 5e3,
+  period: "daily" /* DAILY */
+};
+
+// src/core/penalty.ts
+var PenaltyManager = class {
+  constructor(store, config, telemetry) {
+    this.store = store;
+    this.telemetry = telemetry;
+    this.config = {
+      threshold: config?.threshold ?? 10,
+      duration: config?.duration ?? 3600,
+      multiplier: config?.multiplier ?? 0.5,
+      decayRate: config?.decayRate ?? 1
+    };
+  }
+  getPenaltyKey(identifier) {
+    return `halt:penalty:${identifier}`;
+  }
+  async getPenalty(identifier) {
+    const key = this.getPenaltyKey(identifier);
+    const stored = await this.store.get(key);
+    if (!stored) {
+      return {
+        abuseScore: 0,
+        penaltyUntil: null,
+        violations: 0,
+        lastViolation: null
+      };
+    }
+    const penalty = {
+      abuseScore: stored.abuseScore || 0,
+      penaltyUntil: stored.penaltyUntil || null,
+      violations: stored.violations || 0,
+      lastViolation: stored.lastViolation || null
+    };
+    if (penalty.lastViolation) {
+      const hoursElapsed = (Date.now() / 1e3 - penalty.lastViolation) / 3600;
+      const decay = hoursElapsed * this.config.decayRate;
+      penalty.abuseScore = Math.max(0, penalty.abuseScore - decay);
+    }
+    return penalty;
+  }
+  async recordViolation(identifier, severity = 1) {
+    const penalty = await this.getPenalty(identifier);
+    penalty.abuseScore += severity;
+    penalty.violations += 1;
+    penalty.lastViolation = Math.floor(Date.now() / 1e3);
+    let penaltyTriggered = false;
+    if (penalty.abuseScore >= this.config.threshold && !this.isActive(penalty)) {
+      penalty.penaltyUntil = Math.floor(Date.now() / 1e3) + this.config.duration;
+      penaltyTriggered = true;
+    }
+    await this.savePenalty(identifier, penalty);
+    this.telemetry?.onViolation?.(identifier, penalty, severity);
+    if (penaltyTriggered) {
+      this.telemetry?.onPenaltyApplied?.(identifier, penalty);
+    }
+    return penalty;
+  }
+  async applyPenalty(identifier, duration) {
+    const penalty = await this.getPenalty(identifier);
+    penalty.penaltyUntil = Math.floor(Date.now() / 1e3) + (duration ?? this.config.duration);
+    await this.savePenalty(identifier, penalty);
+    this.telemetry?.onPenaltyApplied?.(identifier, penalty);
+    return penalty;
+  }
+  async clearPenalty(identifier) {
+    const key = this.getPenaltyKey(identifier);
+    await this.store.delete(key);
+  }
+  getRateLimitMultiplier(penalty) {
+    if (this.isActive(penalty)) {
+      return this.config.multiplier;
+    }
+    return 1;
+  }
+  isActive(penalty) {
+    if (!penalty.penaltyUntil) {
+      return false;
+    }
+    return Math.floor(Date.now() / 1e3) < penalty.penaltyUntil;
+  }
+  timeRemaining(penalty) {
+    if (!this.isActive(penalty)) {
+      return 0;
+    }
+    return (penalty.penaltyUntil || 0) - Math.floor(Date.now() / 1e3);
+  }
+  async savePenalty(identifier, penalty) {
+    const key = this.getPenaltyKey(identifier);
+    const ttl = 7 * 24 * 3600;
+    await this.store.set(key, penalty, ttl);
+  }
+};
+var PENALTY_LENIENT = {
+  threshold: 20,
+  duration: 1800,
+  // 30 minutes
+  multiplier: 0.75,
+  decayRate: 2
+};
+var PENALTY_MODERATE = {
+  threshold: 10,
+  duration: 3600,
+  // 1 hour
+  multiplier: 0.5,
+  decayRate: 1
+};
+var PENALTY_STRICT = {
+  threshold: 5,
+  duration: 7200,
+  // 2 hours
+  multiplier: 0.25,
+  decayRate: 0.5
+};
+
+// src/core/telemetry.ts
+var LoggingTelemetry = class {
+  constructor(logger = console) {
+    this.logger = logger;
+  }
+  onCheck(key, decision, metadata) {
+    this.logger.debug(
+      `Rate limit check: key=${key}, allowed=${decision.allowed}, remaining=${decision.remaining}, metadata=${JSON.stringify(metadata)}`
+    );
+  }
+  onAllowed(key, decision, _metadata) {
+    this.logger.info(`Request allowed: key=${key}, remaining=${decision.remaining}`);
+  }
+  onBlocked(key, decision, metadata) {
+    this.logger.warn(
+      `Request blocked: key=${key}, retry_after=${decision.retryAfter}s, metadata=${JSON.stringify(metadata)}`
+    );
+  }
+  onQuotaCheck(identifier, quota, allowed) {
+    this.logger.debug(
+      `Quota check: identifier=${identifier}, quota=${quota.name}, allowed=${allowed}, remaining=${quota.limit - (quota.currentUsage || 0)}`
+    );
+  }
+  onQuotaExceeded(identifier, quota) {
+    this.logger.warn(
+      `Quota exceeded: identifier=${identifier}, quota=${quota.name}, limit=${quota.limit}, reset_at=${quota.resetAt}`
+    );
+  }
+  onPenaltyApplied(identifier, penalty) {
+    this.logger.warn(
+      `Penalty applied: identifier=${identifier}, abuse_score=${penalty.abuseScore}, penalty_until=${penalty.penaltyUntil}`
+    );
+  }
+  onViolation(identifier, penalty, severity) {
+    this.logger.info(
+      `Violation recorded: identifier=${identifier}, severity=${severity}, abuse_score=${penalty.abuseScore}, violations=${penalty.violations}`
+    );
+  }
+};
+var MetricsTelemetry = class {
+  constructor(metricsClient) {
+    this.metricsClient = metricsClient;
+  }
+  onCheck(_key, _decision, metadata) {
+    this.metricsClient.increment("halt.checks.total", this.getTags(metadata));
+  }
+  onAllowed(_key, decision, metadata) {
+    this.metricsClient.increment("halt.requests.allowed", this.getTags(metadata));
+    this.metricsClient.gauge("halt.remaining", decision.remaining, this.getTags(metadata));
+  }
+  onBlocked(_key, _decision, metadata) {
+    this.metricsClient.increment("halt.requests.blocked", this.getTags(metadata));
+  }
+  onQuotaCheck(_identifier, quota, _allowed) {
+    const tags = { quota: quota.name, period: quota.period };
+    this.metricsClient.increment("halt.quota.checks", tags);
+    this.metricsClient.gauge(
+      "halt.quota.remaining",
+      quota.limit - (quota.currentUsage || 0),
+      tags
+    );
+  }
+  onQuotaExceeded(_identifier, quota) {
+    const tags = { quota: quota.name, period: quota.period };
+    this.metricsClient.increment("halt.quota.exceeded", tags);
+  }
+  onPenaltyApplied(_identifier, penalty) {
+    this.metricsClient.increment("halt.penalties.applied");
+    this.metricsClient.gauge("halt.penalties.abuse_score", penalty.abuseScore);
+  }
+  onViolation(_identifier, _penalty, severity) {
+    this.metricsClient.increment("halt.violations.total");
+    this.metricsClient.histogram("halt.violations.severity", severity);
+  }
+  getTags(metadata) {
+    if (!metadata) {
+      return {};
+    }
+    return {
+      policy: metadata.policy,
+      algorithm: metadata.algorithm
+    };
+  }
+};
+var CompositeTelemetry = class {
+  constructor(hooks) {
+    this.hooks = hooks;
+  }
+  onCheck(key, decision, metadata) {
+    this.hooks.forEach((hook) => hook.onCheck?.(key, decision, metadata));
+  }
+  onAllowed(key, decision, metadata) {
+    this.hooks.forEach((hook) => hook.onAllowed?.(key, decision, metadata));
+  }
+  onBlocked(key, decision, metadata) {
+    this.hooks.forEach((hook) => hook.onBlocked?.(key, decision, metadata));
+  }
+  onQuotaCheck(identifier, quota, allowed) {
+    this.hooks.forEach((hook) => hook.onQuotaCheck?.(identifier, quota, allowed));
+  }
+  onQuotaExceeded(identifier, quota) {
+    this.hooks.forEach((hook) => hook.onQuotaExceeded?.(identifier, quota));
+  }
+  onPenaltyApplied(identifier, penalty) {
+    this.hooks.forEach((hook) => hook.onPenaltyApplied?.(identifier, penalty));
+  }
+  onViolation(identifier, penalty, severity) {
+    this.hooks.forEach((hook) => hook.onViolation?.(identifier, penalty, severity));
+  }
+};
+
+// src/core/stats.ts
+var StatsCollector = class {
+  constructor(options = {}) {
+    this.allowedTotal = 0;
+    this.blockedTotal = 0;
+    this.byPolicy = /* @__PURE__ */ new Map();
+    this.byEndpoint = /* @__PURE__ */ new Map();
+    this.limitedKeys = /* @__PURE__ */ new Map();
+    this.costByPlan = /* @__PURE__ */ new Map();
+    this.quotaExceededCount = 0;
+    this.penaltiesAppliedCount = 0;
+    this.violationsCount = 0;
+    this.topN = options.topN ?? 20;
+    this.maxTrackedKeys = options.maxTrackedKeys ?? 1e4;
+  }
+  onAllowed(_key, _decision, metadata) {
+    this.allowedTotal++;
+    const cost = Number(metadata?.cost ?? 1);
+    this.policyTally(metadata).allowed++;
+    const endpoint = metadata?.endpoint;
+    if (endpoint) {
+      const e = this.endpointTally(endpoint);
+      e.allowed++;
+      e.cost += cost;
+    }
+    const plan = metadata?.plan ?? metadata?.policy ?? "unknown";
+    this.costByPlan.set(plan, (this.costByPlan.get(plan) ?? 0) + cost);
+  }
+  onBlocked(key, _decision, metadata) {
+    this.blockedTotal++;
+    this.policyTally(metadata).blocked++;
+    const endpoint = metadata?.endpoint;
+    if (endpoint) {
+      this.endpointTally(endpoint).blocked++;
+    }
+    if (key) this.trackLimitedKey(key);
+  }
+  onQuotaExceeded(_identifier, _quota) {
+    this.quotaExceededCount++;
+  }
+  onPenaltyApplied(_identifier, _penalty) {
+    this.penaltiesAppliedCount++;
+  }
+  onViolation(_identifier, _penalty, _severity) {
+    this.violationsCount++;
+  }
+  /** Point-in-time view of the aggregated stats. */
+  snapshot() {
+    const topLimitedKeys = [...this.limitedKeys.entries()].sort((a, b) => b[1] - a[1]).slice(0, this.topN).map(([key, blocked]) => ({ key, blocked }));
+    return {
+      allowedTotal: this.allowedTotal,
+      blockedTotal: this.blockedTotal,
+      byPolicy: mapToObject(this.byPolicy),
+      byEndpoint: mapToObject(this.byEndpoint),
+      topLimitedKeys,
+      costByPlan: mapToObject(this.costByPlan),
+      quotaExceeded: this.quotaExceededCount,
+      penaltiesApplied: this.penaltiesAppliedCount,
+      violations: this.violationsCount,
+      trackedKeys: this.limitedKeys.size
+    };
+  }
+  /** Clear all counters (e.g. after exporting). */
+  reset() {
+    this.allowedTotal = 0;
+    this.blockedTotal = 0;
+    this.byPolicy.clear();
+    this.byEndpoint.clear();
+    this.limitedKeys.clear();
+    this.costByPlan.clear();
+    this.quotaExceededCount = 0;
+    this.penaltiesAppliedCount = 0;
+    this.violationsCount = 0;
+  }
+  policyTally(metadata) {
+    const policy = metadata?.policy ?? "unknown";
+    let t = this.byPolicy.get(policy);
+    if (!t) {
+      t = { allowed: 0, blocked: 0 };
+      this.byPolicy.set(policy, t);
+    }
+    return t;
+  }
+  endpointTally(endpoint) {
+    let e = this.byEndpoint.get(endpoint);
+    if (!e) {
+      e = { allowed: 0, blocked: 0, cost: 0 };
+      this.byEndpoint.set(endpoint, e);
+    }
+    return e;
+  }
+  trackLimitedKey(key) {
+    const current = this.limitedKeys.get(key);
+    if (current !== void 0) {
+      this.limitedKeys.set(key, current + 1);
+      return;
+    }
+    if (this.limitedKeys.size >= this.maxTrackedKeys) {
+      this.evictSmallest();
+    }
+    this.limitedKeys.set(key, 1);
+  }
+  /** Evict the lowest-count tracked key to keep memory bounded. */
+  evictSmallest() {
+    let minKey;
+    let minVal = Infinity;
+    for (const [k, v] of this.limitedKeys) {
+      if (v < minVal) {
+        minVal = v;
+        minKey = k;
+      }
+    }
+    if (minKey !== void 0) this.limitedKeys.delete(minKey);
+  }
+};
+function mapToObject(map) {
+  const out = {};
+  for (const [k, v] of map) out[k] = v;
+  return out;
+}
+
+// src/observability/otel.ts
+var OpenTelemetryMetrics = class {
+  constructor(meter) {
+    this.requests = meter.createCounter("halt.requests", {
+      description: "Total rate-limit checks"
+    });
+    this.blocked = meter.createCounter("halt.blocked", {
+      description: "Rate-limited (blocked) requests"
+    });
+    this.cost = meter.createCounter("halt.cost", {
+      description: "Consumed request cost (weighted endpoints)"
+    });
+    this.quotaExceededCounter = meter.createCounter("halt.quota.exceeded", {
+      description: "Quota-exceeded events"
+    });
+    this.penaltyAppliedCounter = meter.createCounter("halt.penalty.applied", {
+      description: "Penalties applied (abuse controls)"
+    });
+    this.violationsCounter = meter.createCounter("halt.violations", {
+      description: "Recorded abuse violations"
+    });
+  }
+  onAllowed(_key, _decision, metadata) {
+    const policy = String(metadata?.policy ?? "unknown");
+    this.requests.add(1, { policy, allowed: "true" });
+    const endpoint = metadata?.endpoint;
+    const plan = String(metadata?.plan ?? metadata?.policy ?? "unknown");
+    const cost = Number(metadata?.cost ?? 1);
+    this.cost.add(cost, endpoint ? { endpoint: String(endpoint), plan } : { plan });
+  }
+  onBlocked(_key, _decision, metadata) {
+    const policy = String(metadata?.policy ?? "unknown");
+    this.requests.add(1, { policy, allowed: "false" });
+    const endpoint = metadata?.endpoint;
+    this.blocked.add(1, endpoint ? { policy, endpoint: String(endpoint) } : { policy });
+  }
+  onQuotaExceeded(_identifier, quota) {
+    this.quotaExceededCounter.add(1, { quota: quota.name });
+  }
+  onPenaltyApplied(_identifier, _penalty) {
+    this.penaltyAppliedCounter.add(1);
+  }
+  onViolation(_identifier, _penalty, severity) {
+    this.violationsCounter.add(1, { severity });
+  }
+};
+
+export { Algorithm, CompositeTelemetry, InMemoryStore, KeyStrategy, LoggingTelemetry, MetricsTelemetry, OpenTelemetryMetrics, PENALTY_LENIENT, PENALTY_MODERATE, PENALTY_STRICT, PenaltyManager, QUOTA_ENTERPRISE_MONTHLY, QUOTA_FREE_DAILY, QUOTA_FREE_MONTHLY, QUOTA_PRO_DAILY, QUOTA_PRO_MONTHLY, QuotaManager, QuotaPeriod, RateLimiter, RedisStore, StatsCollector, extractors_exports as extractors, isAtomicStore, normalizePolicy, presets_exports as presets, toHeaders };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map