tapimo 0.15.1 → 0.18.0

package/src/cloudflare.ts

@@ -5,6 +5,7 @@
 import { DurableObject as CloudflareDurableObject } from 'cloudflare:workers'
 
 import * as Db from './db/Db.js'
+import * as RateLimit from './internal/RateLimit.js'
 import * as Routes from './internal/routes/index.js'
 import * as Metrics from './Metrics.js'
 import * as Store from './internal/Store.js'
@@ -12,6 +13,88 @@ import * as Store from './internal/Store.js'
 type State = ConstructorParameters<typeof CloudflareDurableObject>[0]
 type Environment = ConstructorParameters<typeof CloudflareDurableObject>[1]
 
+/** Idle time after which a principal's object deletes its storage; a return recreates it cold. */
+const quotaIdleMs = 24 * 60 * 60 * 1_000
+
+/**
+ * Durable Object holding one principal's fixed-window counters, one row per
+ * quota. Each row tracks its current window; a newer window replaces it and
+ * an older one is ignored, so rows stay bounded. An idle alarm deletes the
+ * object's storage so one-off callers, such as public IPs, leave nothing behind.
+ */
+export class RateLimiter extends CloudflareDurableObject {
+  /** Scheduled idle deletion; unknown until first read after construction. */
+  #alarmAt: number | null | undefined
+  #cold = true
+  #context: State
+  #tableReady = false
+
+  constructor(ctx: State, env: Environment) {
+    super(ctx, env as never)
+    this.#context = ctx
+    void ctx.blockConcurrencyWhile(async () => this.#ensureTable())
+  }
+
+  /** Counts one request in its window and reports whether this call constructed the object. */
+  async consume(
+    options: RateLimit.durableObject.Stub.ConsumeOptions,
+  ): Promise<RateLimit.durableObject.Outcome> {
+    const cold = this.#cold
+    this.#cold = false
+    // Only the idle alarm drops the table after construction.
+    if (!this.#tableReady) this.#ensureTable()
+    // One statement: start the window, continue it, or ignore a stale one.
+    const row = this.#context.storage.sql
+      .exec<{ count: number }>(
+        `INSERT INTO counters (quota, bucket, count) VALUES (?1, ?2, 1)
+         ON CONFLICT (quota) DO UPDATE SET
+           count = CASE WHEN excluded.bucket > counters.bucket THEN 1 WHEN excluded.bucket = counters.bucket THEN counters.count + 1 ELSE counters.count END,
+           bucket = MAX(counters.bucket, excluded.bucket)
+         RETURNING count`,
+        options.quota,
+        options.bucket,
+      )
+      .one()
+    // The increment has committed, so a failure here must not fail the RPC:
+    // the caller's retry would count the request twice.
+    await this.#extendIdle().catch(() => {
+      this.#alarmAt = undefined
+    })
+    return { cold, count: row.count }
+  }
+
+  /** Deletes the storage of an object nothing has consumed for the idle window. */
+  async alarm(): Promise<void> {
+    // The alarm, not a consume, paid for constructing this instance.
+    this.#cold = false
+    await this.#context.storage.deleteAll()
+    this.#alarmAt = null
+    this.#tableReady = false
+  }
+
+  #ensureTable() {
+    this.#context.storage.sql.exec(
+      'CREATE TABLE IF NOT EXISTS counters (quota TEXT PRIMARY KEY, bucket INTEGER NOT NULL, count INTEGER NOT NULL)',
+    )
+    this.#tableReady = true
+  }
+
+  // The alarm is only pushed once it is within half the window, so a busy
+  // object writes it twice a day. Never set from the constructor: a wake for
+  // the alarm would otherwise push it out before the handler ran.
+  async #extendIdle() {
+    const { storage } = this.#context
+    const now = Date.now()
+    const current = this.#alarmAt === undefined ? await storage.getAlarm() : this.#alarmAt
+    if (current !== null && current - now > quotaIdleMs / 2) {
+      this.#alarmAt = current
+      return
+    }
+    this.#alarmAt = now + quotaIdleMs
+    await storage.setAlarm(this.#alarmAt)
+  }
+}
+
 /** Durable Object class that exposes a Tempo API store over Cloudflare RPC. */
 export class DurableObject extends CloudflareDurableObject {
   #store: Store.Store
@@ -51,6 +134,33 @@ export class DurableObject extends CloudflareDurableObject {
     return Store.increment(this.#store, key, options)
   }
 
+  /** Blocks a Routes provider quota inside this object. */
+  async routesQuotaBlock(options: Routes.Quota.block.Options) {
+    await Routes.Quota.block(this.#store, options)
+  }
+
+  /** Checks a Routes provider quota inside this object. */
+  async routesQuotaCheck(options: Routes.Quota.check.Options) {
+    try {
+      await Routes.Quota.check(this.#store, options)
+      return true
+    } catch (cause) {
+      if (cause instanceof Routes.Provider.ProviderRateLimitError) return false
+      throw cause
+    }
+  }
+
+  /** Reserves capacity from a Routes provider quota inside this object. */
+  async routesQuotaConsume(options: Routes.Quota.consume.Options) {
+    try {
+      await Routes.Quota.consume(this.#store, options)
+      return true
+    } catch (cause) {
+      if (cause instanceof Routes.Provider.ProviderRateLimitError) return false
+      throw cause
+    }
+  }
+
   /** Lists keys. */
   async list(options?: Parameters<Store.Store['list']>[0]) {
     return this.#store.list(options)
@@ -88,6 +198,8 @@ type RoutesSourceRegisterOptions = RoutesSourceConfiguration & {
 }
 
 type RoutesSourceSyncOptions = RoutesSourceConfiguration & {
+  /** Revision read before loading the route snapshot; omitted by older callers during deployment. */
+  revision?: string | undefined
   routes: readonly RoutesSourceRoute[]
 }
 
@@ -137,29 +249,37 @@ export class RoutesSourceObserver<
     const route = this.context.storage.sql
       .exec<RoutesSourceRouteRow>('SELECT id, address FROM routes WHERE id = ?', options.route.id)
       .toArray()[0]
-    this.context.storage.transactionSync(() => {
-      this.context.storage.sql.exec(
-        'INSERT OR REPLACE INTO configuration (id, value) VALUES (1, ?)',
-        configuration,
-      )
-      this.context.storage.sql.exec(
-        'INSERT OR REPLACE INTO routes (id, address) VALUES (?, ?)',
-        options.route.id,
-        options.route.address.toLowerCase(),
-      )
-      if (!route || route.address.toLowerCase() !== options.route.address.toLowerCase())
-        this.context.storage.sql.exec(
-          'INSERT OR IGNORE INTO backfills (id) VALUES (?)',
-          options.route.id,
-        )
-    })
+    const changed = !route || route.address.toLowerCase() !== options.route.address.toLowerCase()
+    const configured = this.#configuration() === configuration
+    // Unguarded by revision: a late retry can re-add a removed route until the next sync reconciles it.
+    if (changed || !configured)
+      this.context.storage.transactionSync(() => {
+        if (!configured)
+          this.context.storage.sql.exec(
+            'INSERT OR REPLACE INTO configuration (id, value) VALUES (1, ?)',
+            configuration,
+          )
+        if (changed) {
+          this.context.storage.sql.exec(
+            'INSERT OR REPLACE INTO routes (id, address) VALUES (?, ?)',
+            options.route.id,
+            options.route.address.toLowerCase(),
+          )
+          this.context.storage.sql.exec(
+            'INSERT OR IGNORE INTO backfills (id) VALUES (?)',
+            options.route.id,
+          )
+        }
+        this.#advanceRevision()
+      })
     await this.#ensureAlarm()
   }
 
-  /** Replaces the active routes from the database and repairs alarm scheduling. */
-  async sync(options: RoutesSourceSyncOptions): Promise<void> {
+  /** Applies changed routes and repairs alarm scheduling; returns false when the snapshot is stale. */
+  async sync(options: RoutesSourceSyncOptions): Promise<boolean> {
+    if (options.revision !== undefined && options.revision !== this.getRevision()) return false
     const configuration = serializeRoutesSourceConfiguration(options)
-    const existing = new Map(
+    const existing = new Map<string, string>(
       this.context.storage.sql
         .exec<RoutesSourceRouteRow>('SELECT id, address FROM routes ORDER BY id')
         .toArray()
@@ -168,27 +288,48 @@ export class RoutesSourceObserver<
     const changed = options.routes.filter(
       (route) => existing.get(route.id) !== route.address.toLowerCase(),
     )
-    this.context.storage.transactionSync(() => {
-      this.context.storage.sql.exec(
-        'INSERT OR REPLACE INTO configuration (id, value) VALUES (1, ?)',
-        configuration,
-      )
-      this.context.storage.sql.exec('DELETE FROM routes')
-      for (const route of options.routes)
-        this.context.storage.sql.exec(
-          'INSERT INTO routes (id, address) VALUES (?, ?)',
-          route.id,
-          route.address.toLowerCase(),
-        )
-      this.context.storage.sql.exec('DELETE FROM backfills WHERE id NOT IN (SELECT id FROM routes)')
-      for (const route of changed)
-        this.context.storage.sql.exec('INSERT OR IGNORE INTO backfills (id) VALUES (?)', route.id)
-    })
+    const incoming = new Set(options.routes.map((route) => route.id))
+    const removed = [...existing.keys()].filter((id) => !incoming.has(id))
+    const configured = this.#configuration() === configuration
+    if (changed.length > 0 || removed.length > 0 || !configured)
+      this.context.storage.transactionSync(() => {
+        if (!configured)
+          this.context.storage.sql.exec(
+            'INSERT OR REPLACE INTO configuration (id, value) VALUES (1, ?)',
+            configuration,
+          )
+        for (const id of removed) {
+          this.context.storage.sql.exec('DELETE FROM routes WHERE id = ?', id)
+          this.context.storage.sql.exec('DELETE FROM backfills WHERE id = ?', id)
+        }
+        // Delete changed addresses first so valid address swaps do not violate the unique constraint.
+        for (const route of changed)
+          this.context.storage.sql.exec('DELETE FROM routes WHERE id = ?', route.id)
+        for (const route of changed) {
+          this.context.storage.sql.exec(
+            'INSERT INTO routes (id, address) VALUES (?, ?)',
+            route.id,
+            route.address.toLowerCase(),
+          )
+          this.context.storage.sql.exec('INSERT OR IGNORE INTO backfills (id) VALUES (?)', route.id)
+        }
+        this.#advanceRevision()
+      })
     if (options.routes.length === 0) {
       await this.context.storage.deleteAlarm()
-      return
+      return true
     }
     await this.#ensureAlarm()
+    return true
+  }
+
+  /** Reads the persisted revision used to reject obsolete route snapshots. */
+  getRevision(): string {
+    return (
+      this.context.storage.sql
+        .exec<RoutesSourceStateRow>("SELECT value FROM state WHERE key = 'routes_revision'")
+        .toArray()[0]?.value ?? ''
+    )
   }
 
   /** Scans confirmed source blocks and persists newly observed deposits. */
@@ -316,6 +457,13 @@ export class RoutesSourceObserver<
       .toArray()[0]?.value
   }
 
+  #advanceRevision(): void {
+    this.context.storage.sql.exec(
+      "INSERT OR REPLACE INTO state (key, value) VALUES ('routes_revision', ?)",
+      crypto.randomUUID(),
+    )
+  }
+
   async #ensureAlarm(): Promise<void> {
     if ((await this.context.storage.getAlarm()) === null)
       await this.context.storage.setAlarm(Date.now())