@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/sqlite/user-kv-store.ts

@@ -0,0 +1,317 @@
+/**
+ * `user_kv` table access in the USER'S OWN SQLite database — the Workers
+ * implementation of `ctx.kv` (`UserKvSurface`). Rows live in the owner file,
+ * so plugin state written here survives the object being evicted and
+ * restored from the owner copy, and leaves with the file when it is exported
+ * or deleted.
+ *
+ *   user_kv(namespace, key, value, bytes, idle_ttl_ms, expires_at, touched_seq)
+ *
+ * `value` is JSON text; `bytes` the row's UTF-8 size — namespace, key and
+ * value together (`userKvRowBytes`) — the unit of the store-wide byte cap
+ * (`USER_KV_LIMITS` in `core/user-kv.ts`). Every write checks the caps
+ * inside its own transaction. `expires_at` (ms epoch) is null for entries written
+ * without an idle TTL. `touched_seq` is a store-wide counter bumped on every
+ * read and write of a row: the least-recently-used entry of a namespace is
+ * its lowest `touched_seq`. A counter rather than a timestamp keeps the order
+ * total when several touches land in the same millisecond.
+ */
+import {
+  assertUserKvName,
+  assertUserKvOptions,
+  assertUserKvValueSize,
+  decodeUserKvValue,
+  encodeUserKvValue,
+  resolveUserKvLimits,
+  userKvOverflow,
+  userKvRowBytes,
+  userKvValueBytes,
+  type UserKvLimits,
+  type UserKvUsage,
+} from '../core/user-kv';
+import type { UserKvSurface, UserKvWriteOptions } from '../plugin-api/types';
+import type { DoSqliteDatabase } from './database';
+
+type KvRow = {
+  value: string;
+  idle_ttl_ms: number | bigint | null;
+  expires_at: number | bigint | null;
+};
+
+type CountRow = { n: number | bigint };
+type TotalsRow = { n: number | bigint; b: number | bigint };
+
+const NEXT_SEQ = `(SELECT COALESCE(MAX(touched_seq), 0) + 1 FROM user_kv)`;
+
+export class SqliteUserKv implements UserKvSurface {
+  private setupPromise: Promise<void> | undefined;
+  private readonly now: () => number;
+  private readonly limits: Readonly<UserKvLimits>;
+
+  /**
+   * `limits` overrides the hard caps for tests; the host constructs the
+   * store without it, so the caps in force are `USER_KV_LIMITS`.
+   */
+  constructor(
+    private readonly db: DoSqliteDatabase,
+    options: { now?: () => number; limits?: Partial<UserKvLimits> } = {},
+  ) {
+    this.now = options.now ?? Date.now;
+    this.limits = resolveUserKvLimits(options.limits);
+  }
+
+  /**
+   * Create the table + indexes, or bring a table from an older build up to
+   * the current shape. Idempotent, cached like `TasksStore`.
+   */
+  setup(): Promise<void> {
+    this.setupPromise ??= this.doSetup().catch((error: unknown) => {
+      this.setupPromise = undefined;
+      throw error;
+    });
+    return this.setupPromise;
+  }
+
+  private async doSetup(): Promise<void> {
+    await this.db.run(`
+      CREATE TABLE IF NOT EXISTS user_kv (
+        namespace TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value TEXT NOT NULL,
+        bytes INTEGER NOT NULL,
+        idle_ttl_ms INTEGER,
+        expires_at INTEGER,
+        touched_seq INTEGER NOT NULL,
+        PRIMARY KEY (namespace, key)
+      )`);
+    await this.addBytesColumn();
+    await this.db.run(
+      `CREATE INDEX IF NOT EXISTS idx_user_kv_recency ON user_kv(namespace, touched_seq)`,
+    );
+    // Every touch computes MAX(touched_seq) over the whole table.
+    await this.db.run(
+      `CREATE INDEX IF NOT EXISTS idx_user_kv_seq ON user_kv(touched_seq)`,
+    );
+    // Covers the store-wide COUNT(*) + SUM(bytes) of the cap check, so it
+    // reads the index rather than every value.
+    await this.db.run(
+      `CREATE INDEX IF NOT EXISTS idx_user_kv_bytes ON user_kv(bytes)`,
+    );
+    // The store-wide sweep of expired rows before a write is refused.
+    await this.db.run(
+      `CREATE INDEX IF NOT EXISTS idx_user_kv_expiry ON user_kv(expires_at)`,
+    );
+  }
+
+  /**
+   * A table created before the caps has no `bytes`: add it and fill it from
+   * the stored names and JSON in one transaction, so a column that exists is always
+   * filled. SQLite only adds a NOT NULL column with a default; every write
+   * sets it explicitly.
+   */
+  private async addBytesColumn(): Promise<void> {
+    const columns = await this.db.exec<{ name: string }>(
+      `PRAGMA table_info(user_kv)`,
+    );
+    if (columns.some((column) => column.name === 'bytes')) return;
+    await this.db.transaction(async () => {
+      await this.db.run(
+        `ALTER TABLE user_kv ADD COLUMN bytes INTEGER NOT NULL DEFAULT 0`,
+      );
+      await this.db.run(
+        `UPDATE user_kv SET bytes = length(CAST(namespace AS BLOB))
+           + length(CAST(key AS BLOB)) + length(CAST(value AS BLOB))`,
+      );
+    });
+  }
+
+  async get(namespace: string, key: string): Promise<unknown> {
+    assertUserKvName('namespace', namespace);
+    assertUserKvName('key', key);
+    await this.setup();
+    return this.db.transaction(async () => {
+      const json = await this.touch(namespace, key);
+      return json === undefined ? undefined : decodeUserKvValue(json);
+    });
+  }
+
+  async set(
+    namespace: string,
+    key: string,
+    value: unknown,
+    options: UserKvWriteOptions = {},
+  ): Promise<void> {
+    const json = encodeUserKvValue(value);
+    await this.update(namespace, key, () => decodeUserKvValue(json), options);
+  }
+
+  async update(
+    namespace: string,
+    key: string,
+    fn: (current: unknown) => unknown,
+    options: UserKvWriteOptions = {},
+  ): Promise<unknown> {
+    assertUserKvName('namespace', namespace);
+    assertUserKvName('key', key);
+    assertUserKvOptions(options);
+    await this.setup();
+    return this.db.transaction(async () => {
+      const current = await this.touch(namespace, key);
+      const next = fn(
+        current === undefined ? undefined : decodeUserKvValue(current),
+      );
+      if (next === undefined) {
+        await this.db.run(
+          `DELETE FROM user_kv WHERE namespace = ? AND key = ?`,
+          [namespace, key],
+        );
+        if (options.maxEntries !== undefined) {
+          await this.trim(namespace, options.maxEntries);
+        }
+        return undefined;
+      }
+      const json = encodeUserKvValue(next);
+      const valueBytes = assertUserKvValueSize(namespace, json, this.limits);
+      const ttl = options.idleTtlMs ?? null;
+      await this.db.run(
+        `INSERT INTO user_kv (namespace, key, value, bytes, idle_ttl_ms, expires_at, touched_seq)
+         VALUES (?, ?, ?, ?, ?, ?, ${NEXT_SEQ})
+         ON CONFLICT (namespace, key) DO UPDATE SET
+           value = excluded.value,
+           bytes = excluded.bytes,
+           idle_ttl_ms = excluded.idle_ttl_ms,
+           expires_at = excluded.expires_at,
+           touched_seq = excluded.touched_seq`,
+        [
+          namespace,
+          key,
+          json,
+          userKvRowBytes(namespace, key, valueBytes),
+          ttl,
+          ttl === null ? null : this.now() + ttl,
+        ],
+      );
+      if (options.maxEntries !== undefined) {
+        await this.trim(namespace, options.maxEntries);
+      }
+      // `touch` deleted an expired row, so `current` is the live row this
+      // write replaced, if any. Namespace and key are the same, so the row
+      // grew exactly when its value did.
+      await this.enforceCaps(namespace, {
+        entries: current === undefined,
+        bytes:
+          valueBytes > (current === undefined ? 0 : userKvValueBytes(current)),
+      });
+      return decodeUserKvValue(json);
+    });
+  }
+
+  async delete(namespace: string, key: string): Promise<void> {
+    assertUserKvName('namespace', namespace);
+    assertUserKvName('key', key);
+    await this.setup();
+    await this.db.run(`DELETE FROM user_kv WHERE namespace = ? AND key = ?`, [
+      namespace,
+      key,
+    ]);
+  }
+
+  /**
+   * The live row's JSON, marked most recently used with its idle deadline
+   * slid; an expired row is deleted and reads as absent. Runs inside the
+   * caller's transaction.
+   */
+  private async touch(
+    namespace: string,
+    key: string,
+  ): Promise<string | undefined> {
+    const row = await this.db.get<KvRow>(
+      `SELECT value, idle_ttl_ms, expires_at FROM user_kv WHERE namespace = ? AND key = ?`,
+      [namespace, key],
+    );
+    if (!row) return undefined;
+    const now = this.now();
+    if (row.expires_at !== null && Number(row.expires_at) <= now) {
+      await this.db.run(`DELETE FROM user_kv WHERE namespace = ? AND key = ?`, [
+        namespace,
+        key,
+      ]);
+      return undefined;
+    }
+    const ttl = row.idle_ttl_ms === null ? null : Number(row.idle_ttl_ms);
+    await this.db.run(
+      `UPDATE user_kv SET expires_at = ?, touched_seq = ${NEXT_SEQ}
+       WHERE namespace = ? AND key = ?`,
+      [ttl === null ? null : now + ttl, namespace, key],
+    );
+    return row.value;
+  }
+
+  /**
+   * Throw `UserKvLimitError` — rolling the caller's transaction back,
+   * so the write and anything it evicted are undone — when the write broke a
+   * hard cap. Before refusing, expired rows of every namespace are swept and
+   * the store measured again, so rows nobody can read any more never block
+   * a write. Only the measures the write `grew` are checked
+   * (`userKvOverflow`). Runs inside the caller's transaction, after the write.
+   */
+  private async enforceCaps(
+    namespace: string,
+    grew: { entries: boolean; bytes: boolean },
+  ): Promise<void> {
+    if (!grew.entries && !grew.bytes) return;
+    let overflow = userKvOverflow(
+      namespace,
+      await this.usage(namespace),
+      grew,
+      this.limits,
+    );
+    if (!overflow) return;
+    const swept = await this.db.run(
+      `DELETE FROM user_kv WHERE expires_at IS NOT NULL AND expires_at <= ?`,
+      [this.now()],
+    );
+    if (swept.changes > 0) {
+      overflow = userKvOverflow(
+        namespace,
+        await this.usage(namespace),
+        grew,
+        this.limits,
+      );
+    }
+    if (overflow) throw overflow;
+  }
+
+  /**
+   * Rows of the namespace (`idx_user_kv_recency`) and rows + row bytes of
+   * the store (covering `idx_user_kv_bytes`), expired rows included.
+   */
+  private async usage(namespace: string): Promise<UserKvUsage> {
+    const ns = await this.db.get<CountRow>(
+      `SELECT COUNT(*) AS n FROM user_kv WHERE namespace = ?`,
+      [namespace],
+    );
+    const totals = await this.db.get<TotalsRow>(
+      `SELECT COUNT(*) AS n, COALESCE(SUM(bytes), 0) AS b FROM user_kv`,
+    );
+    return {
+      namespaceEntries: Number(ns?.n ?? 0),
+      totalEntries: Number(totals?.n ?? 0),
+      totalBytes: Number(totals?.b ?? 0),
+    };
+  }
+
+  /** Drop the namespace's expired rows, then the least recently used beyond `maxEntries`. */
+  private async trim(namespace: string, maxEntries: number): Promise<void> {
+    await this.db.run(
+      `DELETE FROM user_kv WHERE namespace = ? AND expires_at IS NOT NULL AND expires_at <= ?`,
+      [namespace, this.now()],
+    );
+    await this.db.run(
+      `DELETE FROM user_kv WHERE namespace = ? AND key IN (
+         SELECT key FROM user_kv WHERE namespace = ?
+         ORDER BY touched_seq DESC LIMIT -1 OFFSET ?)`,
+      [namespace, namespace, maxEntries],
+    );
+  }
+}

package/src/tasks/schedule.ts

@@ -7,7 +7,11 @@
  * without a Durable Object; the scheduler (`scheduler.ts`) supplies the
  * clock.
  */
-import { CronExpressionParser } from 'cron-parser';
+import {
+  CronExpression,
+  CronExpressionParser,
+  CronFieldCollection,
+} from 'cron-parser';
 import type { OracleTaskSchedule } from '../plugin-api/types';
 
 /** Consecutive failed runs before a recurring task is stopped as `failed`. */
@@ -81,21 +85,201 @@ export function previewRuns(
   return runs;
 }
 
+const DAY_MS = 86_400_000;
+/** Calendar span searched for the two closest firing days (covers a leap year). */
+const FIRING_DAY_SCAN_DAYS = 4 * 366;
+/** How far ahead UTC-offset changes of the task's timezone are looked for. */
+const OFFSET_CHANGE_LOOKAHEAD_DAYS = 366;
 /**
- * Milliseconds between two consecutive fires of a cron pattern, or null when
- * the pattern does not parse. Drives the minimum-frequency check.
+ * Fires examined around one UTC-offset change. A pattern that fires more
+ * often than this in three days is already below any practical floor on its
+ * wall-clock gaps; the cap only bounds the work for tiny operator floors.
  */
-export function cronIntervalMs(cron: string, timezone?: string): number | null {
+const MAX_FIRES_PER_OFFSET_WINDOW = 3_000;
+/**
+ * How far around an offset change fires are examined when the pattern's
+ * shortest gap is longer (weekly and rarer patterns): a gap of more than a
+ * week minus the shift is not a frequency any floor is about.
+ */
+const MAX_OFFSET_WINDOW_REACH_MS = 7 * DAY_MS;
+
+/** A timezone's UTC offset (ms) at `atMs`. Throws a RangeError for an unknown zone. */
+function utcOffsetMs(format: Intl.DateTimeFormat, atMs: number): number {
+  const parts: Record<string, number> = {};
+  for (const part of format.formatToParts(new Date(atMs))) {
+    if (part.type !== 'literal') parts[part.type] = Number(part.value);
+  }
+  const wallClock = Date.UTC(
+    parts.year ?? 0,
+    (parts.month ?? 1) - 1,
+    parts.day ?? 1,
+    (parts.hour ?? 0) % 24,
+    parts.minute ?? 0,
+    parts.second ?? 0,
+  );
+  return wallClock - Math.floor(atMs / 1000) * 1000;
+}
+
+/**
+ * The fewest calendar days between two consecutive days the pattern's
+ * date fields (day of month, month, day of week) select, over
+ * `FIRING_DAY_SCAN_DAYS` from `fromMs`; Infinity when fewer than two match.
+ */
+function closestFiringDays(
+  fields: CronFieldCollection,
+  fromMs: number,
+): number {
+  if (
+    fields.dayOfMonth.isWildcard &&
+    fields.month.isWildcard &&
+    fields.dayOfWeek.isWildcard
+  ) {
+    return 1;
+  }
+  const days = CronExpression.fieldsToExpression(
+    CronFieldCollection.from(fields, { second: [0], minute: [0], hour: [0] }),
+    { currentDate: new Date(fromMs), tz: 'UTC' },
+  );
+  const end = fromMs + FIRING_DAY_SCAN_DAYS * DAY_MS;
+  let closest = Number.POSITIVE_INFINITY;
+  let previous: number | undefined;
+  while (days.hasNext()) {
+    const day = days.next().getTime();
+    if (day > end) break;
+    if (previous !== undefined)
+      closest = Math.min(closest, Math.round((day - previous) / DAY_MS));
+    if (closest === 1) break;
+    previous = day;
+  }
+  return closest;
+}
+
+/**
+ * The shortest gap (ms) between consecutive fires of a cron pattern in
+ * `timezone` (the runtime's zone when absent), or null when the pattern or
+ * the timezone does not parse. Drives the minimum-frequency check, so it
+ * covers every pair of consecutive fires, not just the next two:
+ *
+ *   - within a day: the closest two of the pattern's times of day;
+ *   - across midnight: last time of one firing day → first time of the next
+ *     firing day, for the two closest firing days (weekday lists, month ends
+ *     and leap days included);
+ *   - across a UTC-offset change of `timezone` in the coming year: the real
+ *     elapsed time between the fires around it (a 01:00 / 04:00 pattern is
+ *     2 hours apart on the day the clocks go forward).
+ *
+ * Infinity when the pattern fires at most once in the scanned span. A gap
+ * below `floorMs` ends the search early (that is all the caller needs).
+ */
+export function cronIntervalMs(
+  cron: string,
+  timezone?: string,
+  fromMs = Date.now(),
+  floorMs = 0,
+  examined?: { fires: number },
+): number | null {
+  let fields: CronFieldCollection;
+  let offsetFormat: Intl.DateTimeFormat | undefined;
   try {
-    const it = CronExpressionParser.parse(cron, {
-      ...(timezone ? { tz: timezone } : {}),
-    });
-    const a = it.next().toDate().getTime();
-    const b = it.next().toDate().getTime();
-    return b - a;
+    fields = CronExpressionParser.parse(cron, {
+      currentDate: new Date(fromMs),
+      tz: 'UTC',
+    }).fields;
+    if (timezone) {
+      offsetFormat = new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: 'numeric',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: 'numeric',
+        second: 'numeric',
+      });
+    }
   } catch {
     return null;
   }
+
+  // Wall-clock gaps: the pattern's times of day, then the step between days.
+  const times: number[] = [];
+  for (const hour of fields.hour.values)
+    for (const minute of fields.minute.values)
+      for (const second of fields.second.values)
+        times.push((hour * 3600 + minute * 60 + second) * 1000);
+  times.sort((a, b) => a - b);
+  let shortest = Number.POSITIVE_INFINITY;
+  for (let i = 1; i < times.length; i += 1)
+    shortest = Math.min(shortest, times[i]! - times[i - 1]!);
+  let firingDays: number;
+  try {
+    firingDays = closestFiringDays(fields, fromMs);
+  } catch {
+    return null;
+  }
+  if (Number.isFinite(firingDays) && times.length > 0) {
+    shortest = Math.min(
+      shortest,
+      firingDays * DAY_MS - (times[times.length - 1]! - times[0]!),
+    );
+  }
+  if (!offsetFormat || shortest < floorMs) return shortest;
+
+  // Real elapsed time around each UTC-offset change in the coming year.
+  const format = offsetFormat;
+  let previousOffset = utcOffsetMs(format, fromMs);
+  for (let day = 1; day <= OFFSET_CHANGE_LOOKAHEAD_DAYS; day += 1) {
+    const dayMs = fromMs + day * DAY_MS;
+    const offset = utcOffsetMs(format, dayMs);
+    if (offset === previousOffset) continue;
+    const shift = Math.abs(offset - previousOffset);
+    previousOffset = offset;
+    // The change instant, to the minute, between the two daily samples.
+    let before = dayMs - DAY_MS;
+    let after = dayMs;
+    while (after - before > 60_000) {
+      const mid = before + Math.floor((after - before) / 2);
+      if (utcOffsetMs(format, mid) === offset) after = mid;
+      else before = mid;
+    }
+    // Only a pair of fires that straddles the change can come closer than
+    // its clock gap, and by at most `shift`: a pair that could beat the
+    // gap found so far (or break the floor) is less than `reach` apart,
+    // so both of its fires lie within `reach` of the change. Fires the
+    // change moves (a time that does not exist that day) land within
+    // `shift` after it.
+    const reach =
+      Math.min(
+        shortest,
+        floorMs > 0 ? floorMs : Number.POSITIVE_INFINITY,
+        MAX_OFFSET_WINDOW_REACH_MS,
+      ) + shift;
+    const windowStart = after - reach;
+    const windowEnd = after + shift + reach;
+    try {
+      const fires = CronExpressionParser.parse(cron, {
+        currentDate: new Date(windowStart),
+        tz: timezone,
+      });
+      let previous: number | undefined;
+      for (let n = 0; n < MAX_FIRES_PER_OFFSET_WINDOW; n += 1) {
+        const fire = fires.next().getTime();
+        if (examined) examined.fires += 1;
+        // cron-parser can stop advancing next to a change that is not a
+        // whole hour (it returns the same fire again): the window ends there.
+        if (fire > windowEnd || (previous !== undefined && fire <= previous))
+          break;
+        if (previous !== undefined)
+          shortest = Math.min(shortest, fire - previous);
+        if (shortest < floorMs) return shortest;
+        previous = fire;
+      }
+    } catch {
+      // The pattern has no fire left after this window (cron-parser throws
+      // past its search horizon): nothing more to measure here.
+    }
+  }
+  return shortest;
 }
 
 /**
@@ -122,12 +306,17 @@ export function validateSchedule(
       break;
     }
     case 'cron': {
-      const interval = cronIntervalMs(schedule.cron, schedule.timezone);
+      const interval = cronIntervalMs(
+        schedule.cron,
+        schedule.timezone,
+        fromMs,
+        minIntervalSec * 1000,
+      );
       if (interval === null) {
         problems.push(`Cron pattern "${schedule.cron}" is not valid.`);
       } else if (interval < minIntervalSec * 1000) {
         problems.push(
-          `That cron schedule fires every ${Math.round(interval / 1000)}s — the minimum interval between runs is ${minIntervalSec}s. Pick a less frequent schedule.`,
+          `That cron schedule fires as little as ${Math.round(interval / 1000)}s apart — the minimum interval between runs is ${minIntervalSec}s. Pick a less frequent schedule.`,
         );
       }
       break;