@auersperg/flare 0.0.0-stage → 0.3.1

package/dist/sdk/cloudflare.js

@@ -0,0 +1,391 @@
+import { DurableObject, WorkerEntrypoint } from "cloudflare:workers";
+import {
+  flatten,
+  validate
+} from "./server.js";
+import {
+  FlareError,
+  errorCode
+} from "./protocol.js";
+import { exportData, restoreData, emptyData } from "./backup.js";
+import { database } from "./database.js";
+import { applySchema, schemaContract } from "./schema.js";
+import { boundedJson, LIMITS } from "./protocol.js";
+function authorize(mode, auth, internal = false) {
+  if (mode === "internal" && !internal)
+    throw new FlareError("UNAUTHORIZED", "Internal function");
+  if (auth && (!auth.subject || !auth.issuer || !Number.isFinite(auth.expiresAt) || auth.expiresAt <= Date.now()))
+    throw new FlareError("AUTH_EXPIRED", "Authorization expired");
+  if (mode === "required" && !auth)
+    throw new FlareError("UNAUTHORIZED", "Authentication required");
+}
+export function createFacet(app) {
+  const functions = flatten(app.functions);
+  const contract = schemaContract(app.schema);
+  return class AppFacet extends DurableObject {
+    tail = Promise.resolve();
+    constructor(ctx, env) {
+      super(ctx, env);
+      ctx.blockConcurrencyWhile(async () => {
+        await applySchema(ctx.storage, app.schema);
+        ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS _flared_revision (id INTEGER PRIMARY KEY CHECK(id=1), value INTEGER NOT NULL)");
+        ctx.storage.sql.exec("INSERT OR IGNORE INTO _flared_revision VALUES (1,0)");
+        ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS _flared_outbox (id TEXT PRIMARY KEY, release TEXT NOT NULL, path TEXT NOT NULL, args TEXT NOT NULL, auth TEXT NOT NULL, dueAt INTEGER NOT NULL,internal INTEGER NOT NULL DEFAULT 0)");
+        ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS _flared_changes (name TEXT PRIMARY KEY,revision INTEGER NOT NULL)");
+        ctx.storage.sql.exec("CREATE INDEX IF NOT EXISTS outbox_pending ON _flared_outbox(dueAt,id)");
+      });
+    }
+    serial(fn) {
+      const result = this.tail.then(fn);
+      this.tail = result.catch(() => {
+        return;
+      });
+      return result;
+    }
+    revision() {
+      return Number(this.ctx.storage.sql.exec("SELECT value FROM _flared_revision WHERE id=1").one().value);
+    }
+    snapshot() {
+      return this.serial(async () => ({
+        revision: this.revision(),
+        changes: Object.fromEntries(this.ctx.storage.sql.exec("SELECT * FROM _flared_changes").toArray().map((row) => [String(row.name), Number(row.revision)]))
+      }));
+    }
+    async invoke(call) {
+      try {
+        return { ok: true, value: await this.execute(call) };
+      } catch (error) {
+        return {
+          ok: false,
+          code: errorCode(error)
+        };
+      }
+    }
+    async administrative(operation, input) {
+      try {
+        const work = {
+          inspect: () => this.inspect(input),
+          edit: () => this.edit(input),
+          "backup-export": () => this.serial(async () => exportData(this.ctx.storage, app.schema)),
+          "backup-empty": () => this.serial(async () => emptyData(this.ctx.storage, app.schema)),
+          "backup-restore": () => this.serial(() => restoreData(this.ctx.storage, app.schema, input.id, input.snapshot))
+        };
+        if (!Object.hasOwn(work, operation))
+          throw new FlareError("INVALID_OPERATION", "Unknown administrative capability");
+        return { ok: true, value: await work[operation]() };
+      } catch (error) {
+        return {
+          ok: false,
+          code: errorCode(error)
+        };
+      }
+    }
+    execute(call) {
+      return this.serial(async () => {
+        const fn = functions[call.path];
+        if (!fn || fn.kind !== call.kind || call.kind === "action")
+          throw new FlareError("FUNCTION_NOT_FOUND", "Data function not found");
+        authorize(fn.auth, call.auth, call.internal);
+        const args = await validate(fn.input, call.args);
+        if (call.kind === "query") {
+          return this.ctx.storage.transaction(async () => {
+            const tables = new Set;
+            const capability = database(this.ctx.storage.sql, app.schema, false, tables);
+            try {
+              const result = await validate(fn.output, await fn.handler({ db: capability.db, auth: call.auth }, args), true);
+              await capability.finish();
+              return { result, revision: this.revision(), tables: [...tables] };
+            } finally {
+              capability.revoke();
+            }
+          });
+        }
+        let result = null;
+        const changed = new Set;
+        await this.ctx.storage.transaction(async () => {
+          let active = true;
+          const scheduled = [];
+          const jobs = Object.freeze({
+            cancel: (id) => {
+              const pending = (async () => {
+                if (!active)
+                  throw new FlareError("CAPABILITY_EXPIRED", "Mutation invocation ended");
+                if (scheduled.length >= 100)
+                  throw new FlareError("LIMIT_EXCEEDED", "Maximum 100 job operations per mutation");
+                return this.cancelPending(id);
+              })();
+              scheduled.push(pending);
+              pending.catch(() => {
+                return;
+              });
+              return pending;
+            },
+            schedule: (path, jobArgs, options = {}) => {
+              const pending = (async () => {
+                if (!active)
+                  throw new FlareError("CAPABILITY_EXPIRED", "Mutation invocation ended");
+                if (scheduled.length >= 100)
+                  throw new FlareError("LIMIT_EXCEEDED", "Maximum 100 jobs per mutation");
+                const target = functions[path];
+                if (!target || target.kind !== "action")
+                  throw new FlareError("FUNCTION_NOT_FOUND", "Scheduled action not found");
+                const delay = options.delaySeconds ?? 0;
+                if (!Number.isFinite(delay) || delay < 0 || delay > 31536000)
+                  throw new FlareError("INVALID_INPUT", "Invalid job delay");
+                const input = await validate(target.input, jobArgs);
+                if (!active)
+                  throw new FlareError("CAPABILITY_EXPIRED", "Mutation invocation ended");
+                const id = crypto.randomUUID();
+                this.ctx.storage.sql.exec("INSERT INTO _flared_outbox (id,release,path,args,auth,dueAt) VALUES (?,?,?,?,?,?)", id, this.env.RELEASE_ID, path, JSON.stringify(input), JSON.stringify(call.auth), Date.now() + Math.ceil(delay * 1000));
+                if (target.auth === "internal")
+                  this.ctx.storage.sql.exec("UPDATE _flared_outbox SET internal=1,auth='null' WHERE id=?", id);
+                return id;
+              })();
+              scheduled.push(pending);
+              pending.catch(() => {
+                return;
+              });
+              return pending;
+            }
+          });
+          const capability = database(this.ctx.storage.sql, app.schema, true, new Set, changed);
+          try {
+            result = await validate(fn.output, await fn.handler({ db: capability.db, auth: call.auth, jobs }, args), true);
+            await capability.finish();
+            const settled = await Promise.allSettled(scheduled);
+            const failed = settled.find((result) => result.status === "rejected");
+            if (failed?.status === "rejected")
+              throw failed.reason;
+          } finally {
+            active = false;
+            capability.revoke();
+            await Promise.allSettled(scheduled);
+          }
+          this.commitRevision(changed);
+        });
+        await this.ctx.storage.sync();
+        return { result, revision: this.revision(), tables: [...changed] };
+      });
+    }
+    commitRevision(changed) {
+      this.ctx.storage.sql.exec("UPDATE _flared_revision SET value=value+1 WHERE id=1");
+      for (const name of changed)
+        this.ctx.storage.sql.exec("INSERT INTO _flared_changes VALUES (?,?) ON CONFLICT(name) DO UPDATE SET revision=excluded.revision", name, this.revision());
+    }
+    pendingJobs(limit = 100) {
+      return this.serial(async () => {
+        if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+          throw new FlareError("INVALID_INPUT", "Invalid outbox page size");
+        return this.ctx.storage.sql.exec("SELECT * FROM _flared_outbox ORDER BY dueAt,id LIMIT ?", limit).toArray().map((row) => ({
+          id: String(row.id),
+          release: String(row.release),
+          path: String(row.path),
+          args: JSON.parse(String(row.args)),
+          auth: JSON.parse(String(row.auth)),
+          dueAt: Number(row.dueAt),
+          internal: Number(row.internal) === 1
+        }));
+      });
+    }
+    cancelPending(id) {
+      if (typeof id !== "string" || !/^[a-z0-9_-]{1,128}$/.test(id))
+        throw new FlareError("INVALID_INPUT", "Invalid job ID");
+      return this.ctx.storage.sql.exec("DELETE FROM _flared_outbox WHERE id=? RETURNING id", id).toArray().length === 1;
+    }
+    cancelJob(id) {
+      return this.serial(async () => {
+        const cancelled = this.cancelPending(id);
+        await this.ctx.storage.sync();
+        return cancelled;
+      });
+    }
+    pendingJobReferences() {
+      return this.serial(async () => {
+        const paths = this.ctx.storage.sql.exec("SELECT DISTINCT path FROM _flared_outbox ORDER BY path LIMIT 201").toArray().map((row) => String(row.path));
+        const releases = this.ctx.storage.sql.exec("SELECT DISTINCT release FROM _flared_outbox ORDER BY release LIMIT 1001").toArray().map((row) => String(row.release));
+        return {
+          paths: paths.slice(0, 200),
+          releases: releases.slice(0, 1000),
+          truncated: paths.length > 200 || releases.length > 1000
+        };
+      });
+    }
+    validateJob(path, args) {
+      return this.serial(async () => {
+        const target = functions[path];
+        if (!target || target.kind !== "action")
+          throw new FlareError("FUNCTION_NOT_FOUND", "Scheduled action not found");
+        await validate(target.input, args);
+      });
+    }
+    enqueueJob(job) {
+      return this.serial(async () => {
+        const target = functions[job.path];
+        if (!target || target.kind !== "action")
+          throw new FlareError("FUNCTION_NOT_FOUND", "Scheduled action not found");
+        const args = await validate(target.input, job.args);
+        this.ctx.storage.sql.exec("INSERT OR IGNORE INTO _flared_outbox (id,release,path,args,auth,dueAt,internal) VALUES (?,?,?,?,?,?,1)", job.id, this.env.RELEASE_ID, job.path, JSON.stringify(args), "null", job.dueAt);
+        await this.ctx.storage.sync();
+      });
+    }
+    markJobsSent(ids) {
+      return this.serial(async () => {
+        if (!Array.isArray(ids) || ids.length > 100 || ids.some((id) => typeof id !== "string" || !/^[a-z0-9_-]{1,128}$/.test(id)))
+          throw new FlareError("INVALID_INPUT", "Invalid outbox IDs");
+        if (ids.length)
+          this.ctx.storage.transactionSync(() => {
+            this.ctx.storage.sql.exec(`DELETE FROM _flared_outbox WHERE id IN (${ids.map(() => "?").join(",")})`, ...ids);
+          });
+        await this.ctx.storage.sync();
+      });
+    }
+    inspect(input = {}) {
+      return this.serial(async () => {
+        if (!input.table)
+          return {
+            revision: this.revision(),
+            tables: Object.entries(contract).map(([name, definition]) => ({
+              name,
+              document: definition.document,
+              indexes: definition.indexes,
+              columns: this.columns(name)
+            }))
+          };
+        const capability = database(this.ctx.storage.sql, app.schema, false);
+        try {
+          const result = await capability.db.query(input.table).paginate({ limit: input.limit ?? 50, cursor: input.cursor });
+          await capability.finish();
+          return {
+            revision: this.revision(),
+            columns: this.columns(input.table),
+            rows: result.page,
+            next: result.continueCursor
+          };
+        } finally {
+          capability.revoke();
+        }
+      });
+    }
+    columns(name) {
+      const definition = contract[name];
+      if (!definition)
+        throw new FlareError("INVALID_TABLE", "Unknown table");
+      return [
+        { name: "_id", type: "TEXT", pk: 1, notnull: 1, dflt_value: null },
+        {
+          name: "_creationTime",
+          type: "REAL",
+          pk: 0,
+          notnull: 1,
+          dflt_value: null,
+          readonly: true
+        },
+        ...Object.entries(definition.document.properties).map(([field, value]) => ({
+          name: field,
+          type: value.type === "boolean" ? "BOOLEAN" : ["integer", "number"].includes(value.type) ? "REAL" : value.type === "string" ? "TEXT" : "JSON",
+          pk: 0,
+          notnull: Number((definition.document.required ?? []).includes(field)),
+          dflt_value: value.default === undefined ? null : JSON.stringify(value.default),
+          schema: value
+        }))
+      ];
+    }
+    edit(input) {
+      return this.serial(async () => {
+        boundedJson(input, LIMITS.inputBytes);
+        let rows = [];
+        const changed = new Set;
+        await this.ctx.storage.transaction(async () => {
+          if (input.expectedRevision !== this.revision())
+            throw new FlareError("CONFLICT", "Data changed; reload before editing");
+          const capability = database(this.ctx.storage.sql, app.schema, true, new Set, changed);
+          try {
+            if (input.operation === "insert") {
+              const id = await capability.db.insert(input.table, input.values ?? {});
+              rows = [await capability.db.get(input.table, id)];
+            } else if (input.key && input.operation === "update") {
+              await capability.db.patch(input.table, input.key, input.values ?? {});
+              rows = [await capability.db.get(input.table, input.key)];
+            } else if (input.key && input.operation === "delete") {
+              const row = await capability.db.get(input.table, input.key);
+              await capability.db.delete(input.table, input.key);
+              rows = [row];
+            } else
+              throw new FlareError("INVALID_INPUT", "Invalid edit");
+            await capability.finish();
+            boundedJson(rows, LIMITS.outputBytes);
+          } finally {
+            capability.revoke();
+          }
+          this.commitRevision(changed);
+        });
+        await this.ctx.storage.sync();
+        return { rows, revision: this.revision() };
+      });
+    }
+  };
+}
+async function rpcData(response) {
+  const result = await response;
+  try {
+    const value = structuredClone(result);
+    boundedJson(value, LIMITS.outputBytes);
+    return value;
+  } finally {
+    if (result && typeof result === "object") {
+      const dispose = result[Symbol.dispose];
+      dispose?.call(result);
+    }
+  }
+}
+export function createAction(app) {
+  const functions = flatten(app.functions);
+  return class Action extends WorkerEntrypoint {
+    async invoke(call) {
+      try {
+        return { ok: true, value: await this.execute(call) };
+      } catch (e) {
+        return {
+          ok: false,
+          code: errorCode(e)
+        };
+      }
+    }
+    async execute(call) {
+      const fn = functions[call.path];
+      if (!fn || fn.kind !== "action" || call.kind !== "action")
+        throw new FlareError("FUNCTION_NOT_FOUND", "Action not found");
+      authorize(fn.auth, call.auth, call.internal);
+      const args = await validate(fn.input, call.args);
+      const capability = this.env.CAPABILITY;
+      const context = {
+        auth: call.auth,
+        schedules: {
+          set: (input) => rpcData(capability.scheduleCommand("set", input)),
+          cancel: (name) => rpcData(capability.scheduleCommand("cancel", { name })),
+          list: () => rpcData(capability.scheduleCommand("list", {}))
+        },
+        runQuery: (ref, input) => {
+          if (ref.kind !== "query")
+            throw new FlareError("INVALID_KIND", "Expected query");
+          return rpcData(capability.runQuery(ref.path, input, call.auth));
+        },
+        runMutation: (ref, input) => {
+          if (ref.kind !== "mutation")
+            throw new FlareError("INVALID_KIND", "Expected mutation");
+          return rpcData(capability.runMutation(ref.path, input, call.auth));
+        },
+        secrets: { get: (name) => capability.secret(name) },
+        files: {
+          upload: (body, type, options) => capability.upload(body, type, options),
+          download: (id) => capability.download(id),
+          generateUploadUrl: (input) => rpcData(capability.fileCommand("reserve", input)),
+          getDownloadUrl: (id) => rpcData(capability.fileCommand("download", { id })),
+          delete: (id) => rpcData(capability.fileCommand("delete", { id })),
+          list: (input = {}) => rpcData(capability.fileCommand("list", input))
+        }
+      };
+      return validate(fn.output, await fn.handler(context, args), true);
+    }
+  };
+}

package/dist/sdk/database.d.ts

@@ -0,0 +1,39 @@
+import { type Schema, type TableDefinition, type Value, type Input, type Doc, type NativeSql } from "./schema.js";
+export interface Range<D> {
+    eq<K extends keyof D & string>(field: K, value: D[K]): Range<D>;
+    gt<K extends keyof D & string>(field: K, value: D[K]): Range<D>;
+    gte<K extends keyof D & string>(field: K, value: D[K]): Range<D>;
+    lt<K extends keyof D & string>(field: K, value: D[K]): Range<D>;
+    lte<K extends keyof D & string>(field: K, value: D[K]): Range<D>;
+}
+export interface Page<D> {
+    page: D[];
+    continueCursor: string | null;
+    isDone: boolean;
+}
+export interface Query<T extends TableDefinition> {
+    withIndex(index: keyof T["indexes"] & string, range?: (q: Range<Value<T>>) => Range<Value<T>>): Query<T>;
+    order(direction: "asc" | "desc"): Query<T>;
+    take(limit: number): Promise<Doc<T>[]>;
+    first(): Promise<Doc<T> | null>;
+    paginate(options: {
+        limit: number;
+        cursor?: string | null;
+    }): Promise<Page<Doc<T>>>;
+}
+export interface ReadDatabase<S extends Schema = Schema> {
+    get<K extends keyof S & string>(table: K, id: string): Promise<Doc<S[K]> | null>;
+    query<K extends keyof S & string>(table: K): Query<S[K]>;
+}
+export interface WriteDatabase<S extends Schema = Schema> extends ReadDatabase<S> {
+    insert<K extends keyof S & string>(table: K, value: Input<S[K]>): Promise<string>;
+    patch<K extends keyof S & string>(table: K, id: string, value: Partial<Input<S[K]>>): Promise<void>;
+    replace<K extends keyof S & string>(table: K, id: string, value: Input<S[K]>): Promise<void>;
+    delete<K extends keyof S & string>(table: K, id: string): Promise<void>;
+}
+/** Storage never escapes this closure. Each invocation has a revocable capability. */
+export declare function database<S extends Schema>(sql: NativeSql, schema: S, writable: boolean, touched?: Set<string>, changed?: Set<string>): {
+    db: ReadDatabase<S> & WriteDatabase<S>;
+    finish(): Promise<void>;
+    revoke(): void;
+};