@lenso/limits 0.0.0-stage → 0.2.0

package/dist/postgres.d.ts

@@ -0,0 +1,211 @@
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+import { type CounterKind, type LimitStore, type Lease } from "./contracts";
+export declare const postgresLimitSchema: {
+    counters: import("drizzle-orm/pg-core").PgTableWithColumns<{
+        name: "lenso_limit_counters";
+        schema: undefined;
+        columns: {
+            scope: import("drizzle-orm/pg-core").PgColumn<{
+                name: "scope";
+                tableName: "lenso_limit_counters";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            kind: import("drizzle-orm/pg-core").PgColumn<{
+                name: "kind";
+                tableName: "lenso_limit_counters";
+                dataType: "string";
+                columnType: "PgText";
+                data: CounterKind;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                $type: CounterKind;
+            }>;
+            capacity: import("drizzle-orm/pg-core").PgColumn<{
+                name: "capacity";
+                tableName: "lenso_limit_counters";
+                dataType: "number";
+                columnType: "PgBigInt53";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            periodMs: import("drizzle-orm/pg-core").PgColumn<{
+                name: "period_ms";
+                tableName: "lenso_limit_counters";
+                dataType: "number";
+                columnType: "PgBigInt53";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            windowStart: import("drizzle-orm/pg-core").PgColumn<{
+                name: "window_start";
+                tableName: "lenso_limit_counters";
+                dataType: "number";
+                columnType: "PgBigInt53";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            used: import("drizzle-orm/pg-core").PgColumn<{
+                name: "used";
+                tableName: "lenso_limit_counters";
+                dataType: "number";
+                columnType: "PgBigInt53";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            lastNow: import("drizzle-orm/pg-core").PgColumn<{
+                name: "last_now";
+                tableName: "lenso_limit_counters";
+                dataType: "number";
+                columnType: "PgBigInt53";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+        };
+        dialect: 'pg';
+    }>;
+    concurrencyBuckets: import("drizzle-orm/pg-core").PgTableWithColumns<{
+        name: "lenso_limit_concurrency";
+        schema: undefined;
+        columns: {
+            scope: import("drizzle-orm/pg-core").PgColumn<{
+                name: "scope";
+                tableName: "lenso_limit_concurrency";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: true;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            capacity: import("drizzle-orm/pg-core").PgColumn<{
+                name: "capacity";
+                tableName: "lenso_limit_concurrency";
+                dataType: "number";
+                columnType: "PgBigInt53";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            lastNow: import("drizzle-orm/pg-core").PgColumn<{
+                name: "last_now";
+                tableName: "lenso_limit_concurrency";
+                dataType: "number";
+                columnType: "PgBigInt53";
+                data: number;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            leases: import("drizzle-orm/pg-core").PgColumn<{
+                name: "leases";
+                tableName: "lenso_limit_concurrency";
+                dataType: "json";
+                columnType: "PgJsonb";
+                data: Lease[];
+                driverParam: unknown;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                $type: Lease[];
+            }>;
+        };
+        dialect: 'pg';
+    }>;
+};
+/** Borrows the database; schema creation and connection lifetime belong to the caller. */
+export declare function createPostgresLimitStore<TResult extends PgQueryResultHKT = PgQueryResultHKT, TSchema extends Record<string, unknown> = Record<string, unknown>>(db: PgDatabase<TResult, TSchema>): LimitStore;

package/dist/postgres.js

@@ -0,0 +1,128 @@
+import {
+  LimitError2,
+  maxDurationMs,
+  positiveInteger,
+  scopeKey,
+  validateConsume,
+  validateAcquire,
+  validateToken,
+  validateKind,
+  consumeState,
+  liveState,
+  acquireState,
+  renewState
+} from "./index-bz4qnpx8.js";
+
+// src/postgres.ts
+import { and, eq, sql } from "drizzle-orm";
+import { check, jsonb, pgTable, primaryKey, text, bigint } from "drizzle-orm/pg-core";
+var counters = pgTable("lenso_limit_counters", {
+  scope: text("scope").notNull(),
+  kind: text("kind").$type().notNull(),
+  capacity: bigint("capacity", { mode: "number" }).notNull(),
+  periodMs: bigint("period_ms", { mode: "number" }).notNull(),
+  windowStart: bigint("window_start", { mode: "number" }).notNull(),
+  used: bigint("used", { mode: "number" }).notNull(),
+  lastNow: bigint("last_now", { mode: "number" }).notNull()
+}, (t) => [
+  primaryKey({ columns: [t.scope, t.kind], name: "lenso_limit_counters_pk" }),
+  check("lenso_limit_counter_kind", sql`${t.kind} IN ('rate', 'quota')`),
+  check("lenso_limit_counter_capacity", sql`${t.capacity} BETWEEN 1 AND 2147483647`),
+  check("lenso_limit_counter_period", sql`${t.periodMs} BETWEEN 1 AND 31622400000`),
+  check("lenso_limit_counter_used", sql`${t.used} BETWEEN 0 AND ${t.capacity}`),
+  check("lenso_limit_counter_clock", sql`${t.windowStart} >= 0 AND ${t.lastNow} >= 0`)
+]);
+var concurrencyBuckets = pgTable("lenso_limit_concurrency", {
+  scope: text("scope").primaryKey().notNull(),
+  capacity: bigint("capacity", { mode: "number" }).notNull(),
+  lastNow: bigint("last_now", { mode: "number" }).notNull(),
+  leases: jsonb("leases").$type().notNull()
+}, (t) => [
+  check("lenso_limit_lease_capacity", sql`${t.capacity} BETWEEN 1 AND 2147483647`),
+  check("lenso_limit_lease_clock", sql`${t.lastNow} >= 0`)
+]);
+var postgresLimitSchema = { counters, concurrencyBuckets };
+var dbNow = sql`floor(extract(epoch from clock_timestamp()) * 1000)::bigint`;
+var serializedJson = (value) => sql`${JSON.stringify(value)}::text::jsonb`;
+function createPostgresLimitStore(db) {
+  async function now(tx) {
+    const [row] = await tx.select({ now: dbNow }).from(sql`(SELECT 1) AS clock_source`);
+    return Number(row.now);
+  }
+  return {
+    async consume(kind, input) {
+      validateKind(kind);
+      validateConsume(input);
+      const key = scopeKey(input.scope);
+      return db.transaction(async (tx) => {
+        await tx.insert(counters).values({
+          scope: key,
+          kind,
+          capacity: input.capacity,
+          periodMs: input.periodMs,
+          windowStart: 0,
+          used: 0,
+          lastNow: 0
+        }).onConflictDoNothing();
+        const [previous] = await tx.select().from(counters).where(and(eq(counters.scope, key), eq(counters.kind, kind))).for("update");
+        if (!previous)
+          throw new LimitError2("backend-failure");
+        const clock = await now(tx);
+        const { state, result } = consumeState(previous, input, clock);
+        await tx.update(counters).set(state).where(and(eq(counters.scope, key), eq(counters.kind, kind)));
+        return result;
+      });
+    },
+    async acquire(input, token) {
+      validateAcquire(input);
+      validateToken(token);
+      const key = scopeKey(input.scope);
+      return db.transaction(async (tx) => {
+        await tx.insert(concurrencyBuckets).values({
+          scope: key,
+          capacity: input.capacity,
+          lastNow: 0,
+          leases: serializedJson([])
+        }).onConflictDoNothing();
+        const [previous] = await tx.select().from(concurrencyBuckets).where(eq(concurrencyBuckets.scope, key)).for("update");
+        if (!previous)
+          throw new LimitError2("backend-failure");
+        const clock = await now(tx);
+        const state = liveState(previous, input.capacity, clock);
+        const result = acquireState(state, input, token);
+        await tx.update(concurrencyBuckets).set({ ...state, leases: serializedJson(state.leases) }).where(eq(concurrencyBuckets.scope, key));
+        return result;
+      });
+    },
+    async renew(scope, token, ttlMs) {
+      const key = scopeKey(scope);
+      validateToken(token);
+      positiveInteger(ttlMs, maxDurationMs);
+      return db.transaction(async (tx) => {
+        const [previous] = await tx.select().from(concurrencyBuckets).where(eq(concurrencyBuckets.scope, key)).for("update");
+        if (!previous)
+          return null;
+        const state = liveState(previous, previous.capacity, await now(tx));
+        const lease = renewState(state, scope, token, ttlMs);
+        await tx.update(concurrencyBuckets).set({ ...state, leases: serializedJson(state.leases) }).where(eq(concurrencyBuckets.scope, key));
+        return lease;
+      });
+    },
+    async release(scope, token) {
+      const key = scopeKey(scope);
+      validateToken(token);
+      await db.transaction(async (tx) => {
+        const [previous] = await tx.select().from(concurrencyBuckets).where(eq(concurrencyBuckets.scope, key)).for("update");
+        if (!previous)
+          return;
+        const state = liveState(previous, previous.capacity, await now(tx));
+        state.leases = state.leases.filter((lease) => lease.token !== token);
+        await tx.update(concurrencyBuckets).set({ ...state, leases: serializedJson(state.leases) }).where(eq(concurrencyBuckets.scope, key));
+      });
+    }
+  };
+}
+export {
+  createPostgresLimitStore,
+  postgresLimitSchema
+};

package/dist/service.d.ts

@@ -0,0 +1,27 @@
+import type { Logger } from "@lenso/core/plugin";
+import { type Acquisition, type AcquireInput, type ConsumeInput, type Decision, type Lease, type LimitConfig, type LimitStore } from "./contracts";
+export interface LeaseRunOptions {
+    readonly signal?: AbortSignal;
+    /** The wrapper owns renewal only when explicitly requested, and stops it in finally. */
+    readonly renewEveryMs?: number;
+}
+export interface LeaseExecution {
+    readonly signal: AbortSignal;
+    /** Null is possible only with explicitly configured fail-open admission. */
+    readonly lease: Lease | null;
+}
+export interface Limits {
+    consumeRate(input: ConsumeInput): Promise<Decision>;
+    consumeQuota(input: ConsumeInput): Promise<Decision>;
+    acquire(input: AcquireInput): Promise<Acquisition>;
+    renew(lease: Lease, ttlMs: number): Promise<Lease | null>;
+    release(lease: Lease): Promise<void>;
+    withLease<T>(input: AcquireInput, execute: (context: LeaseExecution) => Promise<T>, options?: LeaseRunOptions): Promise<T>;
+    /** Stops admission, aborts/drains wrappers, and releases this service's leases, not the store. */
+    close(): Promise<void>;
+}
+export declare function createLimits(options: {
+    readonly store: LimitStore;
+    readonly config: LimitConfig;
+    readonly logger?: Logger;
+}): Limits;