@ixo/oracle-runtime-workers 0.2.0

package/src/sqlite/vacuum-policy.ts

@@ -0,0 +1,77 @@
+/**
+ * When the user object may rebuild its working copy without free pages.
+ *
+ * `VACUUM` (via `DoSqliteDatabase.compact`) holds the transaction lock for
+ * the whole rewrite and transiently doubles the file in DO storage, so it
+ * only runs on a quiet object with a file that is actually worth it. The
+ * predicate is pure so the thresholds are testable; the object supplies the
+ * numbers from its alarm tick.
+ */
+
+/** No turn for this long before the object counts as quiet. */
+export const VACUUM_IDLE_MS = 10 * 60_000;
+/** Files below this are cheap enough to leave alone. */
+export const VACUUM_MIN_FILE_BYTES = 4 * 1024 * 1024;
+/** Free-page share that makes the rewrite worth its cost. */
+export const VACUUM_MIN_FREE_SHARE = 0.2;
+/** At most one rebuild per object per this interval. */
+export const VACUUM_MIN_INTERVAL_MS = 6 * 60 * 60_000;
+/** DO SQLite storage cap; the rewrite needs 2× the file below it. */
+export const DO_STORAGE_CAP_BYTES = 10 * 1024 * 1024 * 1024;
+
+export interface VacuumPolicyInput {
+  now: number;
+  lastAccessAt: number;
+  lastVacuumAt: number | undefined;
+  /** Unflushed changes pending for the owner store. */
+  dirty: boolean;
+  /** An owner-store flush is reading the file right now. */
+  exporting: boolean;
+  fileBytes: number;
+  pageCount: number;
+  freelistCount: number;
+}
+
+export type VacuumVerdict =
+  | { vacuum: true; freeShare: number }
+  | { vacuum: false; reason: string; freeShare: number };
+
+export function shouldVacuum(input: VacuumPolicyInput): VacuumVerdict {
+  const freeShare =
+    input.pageCount > 0 ? input.freelistCount / input.pageCount : 0;
+  const no = (reason: string): VacuumVerdict => ({
+    vacuum: false,
+    reason,
+    freeShare,
+  });
+  if (input.exporting) return no('owner-store flush in progress');
+  if (input.dirty) return no('working copy dirty (flush first)');
+  if (input.now - input.lastAccessAt < VACUUM_IDLE_MS)
+    return no('object active within the idle window');
+  if (input.fileBytes < VACUUM_MIN_FILE_BYTES) return no('file too small');
+  if (freeShare <= VACUUM_MIN_FREE_SHARE)
+    return no('free share below threshold');
+  if (
+    input.lastVacuumAt !== undefined &&
+    input.now - input.lastVacuumAt < VACUUM_MIN_INTERVAL_MS
+  )
+    return no('vacuumed recently');
+  if (input.fileBytes * 2 >= DO_STORAGE_CAP_BYTES * 0.9)
+    return no('not enough storage headroom for the rewrite');
+  return { vacuum: true, freeShare };
+}
+
+/**
+ * Whether the numbers say a rebuild is wanted at all (ignoring quiet-time
+ * and interval gates) — used to re-arm the alarm for a later check.
+ */
+export function vacuumWanted(input: VacuumPolicyInput): boolean {
+  const verdict = shouldVacuum({
+    ...input,
+    dirty: false,
+    exporting: false,
+    lastAccessAt: input.now - VACUUM_IDLE_MS,
+    lastVacuumAt: undefined,
+  });
+  return verdict.vacuum;
+}

package/src/sqlite/wa-sqlite-loader.ts

@@ -0,0 +1,123 @@
+/**
+ * Instantiates wa-sqlite (SQLite compiled to WebAssembly) on workerd.
+ *
+ * Why this file exists:
+ * - workerd disallows runtime wasm compilation (`WebAssembly.compile`,
+ *   `new WebAssembly.Module(bytes)`, `instantiateStreaming`). The Emscripten
+ *   factory in `wa-sqlite/dist/wa-sqlite.mjs` would normally fetch + compile
+ *   `wa-sqlite.wasm`; instead we import the `.wasm` as a build-time
+ *   `CompiledWasm` module (a ready `WebAssembly.Module`) and hand it to the
+ *   factory through its `instantiateWasm(imports, receiveInstance)` hook,
+ *   which only needs the synchronous `new WebAssembly.Instance(module, imports)`.
+ * - We use the SYNC build (`wa-sqlite.mjs`, not the Asyncify `-async` build):
+ *   Durable Object storage (`ctx.storage.sql.exec`) is synchronous, so the VFS
+ *   can be fully synchronous — faster and far simpler than Asyncify.
+ *
+ * Contract verified against `wa-sqlite@1.0.0`:
+ * - `dist/wa-sqlite.mjs` default export: `(moduleArg?) => Promise<Module>`.
+ *   If `moduleArg.instantiateWasm` is set it is called as
+ *   `instantiateWasm(imports, receiveInstance)` and must return the exports.
+ *   Without `moduleArg.locateFile` the factory evaluates
+ *   `new URL('wa-sqlite.wasm', import.meta.url)` eagerly — we set `locateFile`
+ *   to skip that (it's never fetched anyway).
+ * - `src/sqlite-api.js` `Factory(module)` builds the JS API; `vfs_register`
+ *   delegates to `module.registerVFS(vfs, makeDefault)` which throws when a VFS
+ *   name is already registered (there is no unregister), hence the registry
+ *   below.
+ *
+ * One Emscripten module instance is cached per isolate. Many Durable Objects in
+ * the same isolate share it; each DO registers its own VFS (named after the DO
+ * id) so different objects open different databases on the same instance.
+ */
+import './wasm.d';
+import * as SQLite from 'wa-sqlite';
+import SQLiteESMFactory from 'wa-sqlite/dist/wa-sqlite.mjs';
+import wasmModule from 'wa-sqlite/dist/wa-sqlite.wasm';
+
+/** The subset of the Emscripten module surface this runtime relies on. */
+export interface WaSqliteModule {
+  /** Current wasm heap view (re-created by Emscripten when memory grows). */
+  HEAPU8: Uint8Array;
+  registerVFS(vfs: SQLiteVFS, makeDefault?: boolean): number;
+}
+
+export interface SqliteRuntime {
+  sqlite3: SQLiteAPI;
+  module: WaSqliteModule;
+}
+
+interface ModuleFactoryArgs {
+  locateFile(path: string, scriptDirectory: string): string;
+  instantiateWasm(
+    imports: WebAssembly.Imports,
+    receiveInstance: (instance: WebAssembly.Instance) => void,
+  ): WebAssembly.Exports;
+}
+
+let runtimePromise: Promise<SqliteRuntime> | undefined;
+
+/**
+ * Returns the per-isolate SQLite runtime, instantiating it on first use.
+ * Safe to call concurrently; all callers share one promise.
+ */
+export function loadSqlite(): Promise<SqliteRuntime> {
+  runtimePromise ??= instantiate().catch((error: unknown) => {
+    // Let a later call retry instead of caching a rejected promise forever.
+    runtimePromise = undefined;
+    throw error;
+  });
+  return runtimePromise;
+}
+
+async function instantiate(): Promise<SqliteRuntime> {
+  const args: ModuleFactoryArgs = {
+    locateFile: (path) => path,
+    instantiateWasm: (imports, receiveInstance) => {
+      const instance = new WebAssembly.Instance(wasmModule, imports);
+      receiveInstance(instance);
+      return instance.exports;
+    },
+  };
+  const module: WaSqliteModule = await SQLiteESMFactory(args);
+  const sqlite3 = SQLite.Factory(module);
+  return { sqlite3, module };
+}
+
+/**
+ * VFS objects registered on the shared module, keyed by VFS name. SQLite has
+ * no "unregister" in the wa-sqlite glue, so a Durable Object that is evicted
+ * and re-created in the same isolate re-uses (and re-binds) its VFS object
+ * rather than registering a second one under the same name.
+ */
+const vfsRegistry = new Map<string, SQLiteVFS>();
+
+/**
+ * Register `create()`'s VFS under `name` unless one is already registered, in
+ * which case the existing object is returned and `create` is not called.
+ */
+export function getOrRegisterVfs<V extends SQLiteVFS>(
+  runtime: SqliteRuntime,
+  name: string,
+  create: () => V,
+  isInstance: (vfs: SQLiteVFS) => vfs is V,
+): V {
+  const existing = vfsRegistry.get(name);
+  if (existing !== undefined) {
+    if (!isInstance(existing)) {
+      throw new Error(
+        `VFS '${name}' is registered with a different implementation`,
+      );
+    }
+    return existing;
+  }
+  const vfs = create();
+  runtime.sqlite3.vfs_register(vfs, false);
+  vfsRegistry.set(name, vfs);
+  return vfs;
+}
+
+/** SQLite library version string of the loaded build (e.g. `3.45.1`). */
+export async function sqliteVersion(): Promise<string> {
+  const { sqlite3 } = await loadSqlite();
+  return sqlite3.libversion();
+}

package/src/sqlite/wasm.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `.wasm` imports are `CompiledWasm` modules on workerd (wrangler's default
+ * module rule and the Workers vitest pool both apply it). The import yields a
+ * ready `WebAssembly.Module`, so no runtime compilation happens — which is
+ * required, because workerd forbids `WebAssembly.compile` / `new Module(bytes)`.
+ */
+declare module '*.wasm' {
+  const wasmModule: WebAssembly.Module;
+  export default wasmModule;
+}

package/src/tasks/schedule.ts

@@ -0,0 +1,174 @@
+/**
+ * Pure scheduling math for the tasks subsystem — next-fire computation for
+ * the three trigger kinds (`once` / `cron` / `interval`), schedule
+ * validation, run previews and the consecutive-failure backoff curve.
+ *
+ * Everything here is a pure function of its inputs so it can be unit-tested
+ * without a Durable Object; the scheduler (`scheduler.ts`) supplies the
+ * clock.
+ */
+import { CronExpressionParser } from 'cron-parser';
+import type { OracleTaskSchedule } from '../plugin-api/types';
+
+/** Consecutive failed runs before a recurring task is stopped as `failed`. */
+export const MAX_CONSECUTIVE_FAILURES = 3;
+
+/** First-retry delay after a failed run; doubles per consecutive failure. */
+export const FAILURE_BACKOFF_BASE_MS = 60_000;
+
+/** Backoff ceiling — a retry is never pushed further out than this. */
+export const FAILURE_BACKOFF_MAX_MS = 60 * 60_000;
+
+/** Default for `TASKS_MAX_PER_USER` (live = active or paused tasks). */
+export const DEFAULT_MAX_TASKS_PER_USER = 50;
+
+/** Default for `TASKS_MIN_CRON_INTERVAL_SEC` (applies to `interval` too). */
+export const DEFAULT_MIN_CRON_INTERVAL_SEC = 300;
+
+/**
+ * Next fire time (ms epoch) strictly after `fromMs`, or null when the
+ * schedule has none (one-shot in the past, unparseable cron, bad interval).
+ */
+export function computeNextRunAtMs(
+  schedule: OracleTaskSchedule,
+  fromMs: number,
+): number | null {
+  switch (schedule.kind) {
+    case 'once': {
+      const at = Date.parse(schedule.at);
+      if (Number.isNaN(at)) return null;
+      return at > fromMs ? at : null;
+    }
+    case 'cron': {
+      try {
+        return CronExpressionParser.parse(schedule.cron, {
+          currentDate: new Date(fromMs),
+          ...(schedule.timezone ? { tz: schedule.timezone } : {}),
+        })
+          .next()
+          .toDate()
+          .getTime();
+      } catch {
+        return null;
+      }
+    }
+    case 'interval': {
+      if (
+        !Number.isInteger(schedule.everySeconds) ||
+        schedule.everySeconds <= 0
+      ) {
+        return null;
+      }
+      return fromMs + schedule.everySeconds * 1000;
+    }
+  }
+}
+
+/** The next `count` fire times as ISO strings (fewer when the schedule ends). */
+export function previewRuns(
+  schedule: OracleTaskSchedule,
+  count: number,
+  fromMs: number,
+): string[] {
+  const runs: string[] = [];
+  let cursor = fromMs;
+  for (let i = 0; i < count; i++) {
+    const next = computeNextRunAtMs(schedule, cursor);
+    if (next === null || next <= cursor) break;
+    runs.push(new Date(next).toISOString());
+    cursor = next;
+  }
+  return runs;
+}
+
+/**
+ * Milliseconds between two consecutive fires of a cron pattern, or null when
+ * the pattern does not parse. Drives the minimum-frequency check.
+ */
+export function cronIntervalMs(cron: string, timezone?: string): number | null {
+  try {
+    const it = CronExpressionParser.parse(cron, {
+      ...(timezone ? { tz: timezone } : {}),
+    });
+    const a = it.next().toDate().getTime();
+    const b = it.next().toDate().getTime();
+    return b - a;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Human-readable problems with a schedule; empty = valid. The minimum
+ * interval floor applies to cron patterns AND `interval` schedules — a
+ * one-shot only needs to be in the future.
+ */
+export function validateSchedule(
+  schedule: OracleTaskSchedule,
+  minIntervalSec: number,
+  fromMs = Date.now(),
+): string[] {
+  const problems: string[] = [];
+  switch (schedule.kind) {
+    case 'once': {
+      const at = Date.parse(schedule.at);
+      if (Number.isNaN(at)) {
+        problems.push(`"${schedule.at}" is not a valid ISO timestamp.`);
+      } else if (at <= fromMs) {
+        problems.push(
+          `The one-shot time ${schedule.at} is in the past — pick a future time.`,
+        );
+      }
+      break;
+    }
+    case 'cron': {
+      const interval = cronIntervalMs(schedule.cron, schedule.timezone);
+      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.`,
+        );
+      }
+      break;
+    }
+    case 'interval': {
+      if (
+        !Number.isInteger(schedule.everySeconds) ||
+        schedule.everySeconds <= 0
+      ) {
+        problems.push('everySeconds must be a positive integer.');
+      } else if (schedule.everySeconds < minIntervalSec) {
+        problems.push(
+          `An interval of ${schedule.everySeconds}s is below the minimum of ${minIntervalSec}s between runs.`,
+        );
+      }
+      break;
+    }
+  }
+  return problems;
+}
+
+/**
+ * Delay before the next attempt after `consecutiveFailures` failed runs in a
+ * row: base × 2^(n−1), capped. The scheduler takes the LATER of this and the
+ * schedule's own next fire, so backoff can only push runs out, never pull
+ * them in.
+ */
+export function backoffDelayMs(consecutiveFailures: number): number {
+  if (consecutiveFailures <= 0) return 0;
+  const exp = Math.min(consecutiveFailures - 1, 30);
+  return Math.min(FAILURE_BACKOFF_BASE_MS * 2 ** exp, FAILURE_BACKOFF_MAX_MS);
+}
+
+/** One-line human summary of a schedule (tool responses, log lines). */
+export function summarizeSchedule(schedule: OracleTaskSchedule): string {
+  switch (schedule.kind) {
+    case 'once':
+      return `once at ${schedule.at}`;
+    case 'cron':
+      return `cron \`${schedule.cron}\`${schedule.timezone ? ` (${schedule.timezone})` : ''}`;
+    case 'interval':
+      return `every ${schedule.everySeconds}s`;
+  }
+}