@pramen/server 0.0.13 → 0.0.15

package/src/runtime/queue.ts

@@ -0,0 +1,155 @@
+// ctx.queue — Cloudflare Queues producer facade, the same shape as ctx.mail / ctx.files:
+// an adapter seam (CloudflareQueueAdapter / MemoryQueueAdapter) behind a thin `Queue`
+// facade, built from the environment. Handlers enqueue onto a native Cloudflare Queue
+// without touching the producer binding directly:
+//
+//   await ctx.queue.send("jobs", { kind: "resize", id });
+//   await ctx.queue.sendBatch("jobs", [{ body: a }, { body: b, delaySeconds: 30 }]);
+//
+// This is distinct from `ctx.tasks` (the transactional outbox). `ctx.tasks.enqueue`
+// is atomic with the mutation's DB write (commit-or-rollback together) and drained
+// in-process. `ctx.queue` is a native Cloudflare Queue: NOT transactional with the
+// write (the message is sent regardless of whether the mutation later rolls back),
+// but higher-throughput, with platform-native batching/retry/DLQ and a consumer that
+// can run in a *different* Worker. Reach for ctx.tasks when the side-effect must commit
+// with the data; reach for ctx.queue for decoupled, high-volume fan-out.
+//
+// On Cloudflare the transport is the Queues producer binding (declared in oblaka.ts as
+// `new Queue({ binding: "both", ... })`). Off-platform / unconfigured, sending to a queue
+// that isn't bound FAILS CLOSED (throws) rather than silently dropping the message —
+// mirroring how ctx.mail fails closed without a transport.
+
+/** Cloudflare Queues content type for a sent message. Omitted ⇒ the platform default
+ * (v8 structured clone). Use "json" for cross-runtime / external consumers. */
+export type QueueContentType = "text" | "bytes" | "json" | "v8";
+
+/** Per-message send options (mirrors the Cloudflare Queues producer API). */
+export interface QueueSendOptions {
+  /** Defer delivery by N seconds (the consumer won't see the message until then). */
+  delaySeconds?: number;
+  /** How the body is serialized on the wire. Omitted ⇒ platform default (v8). */
+  contentType?: QueueContentType;
+}
+
+/** One message in a `sendBatch` — a body plus its own per-message options. */
+export interface QueueSendRequest {
+  body: unknown;
+  delaySeconds?: number;
+  contentType?: QueueContentType;
+}
+
+/** Batch-level send options. */
+export interface QueueBatchOptions {
+  /** Default delay applied to every message in the batch (per-message overrides win). */
+  delaySeconds?: number;
+}
+
+/** The Cloudflare Queues producer binding shape (what `env.<QUEUE>` exposes). A binding
+ * is recognized as a queue producer iff it has BOTH `send` and `sendBatch` (which
+ * distinguishes it from the email `send`-only binding, KV, R2, D1, …). */
+export interface QueueProducerBinding {
+  send(body: unknown, options?: QueueSendOptions): Promise<void>;
+  sendBatch(messages: Iterable<QueueSendRequest>, options?: QueueBatchOptions): Promise<void>;
+}
+
+/** The transport seam — one per backend (Cloudflare Queues, an in-memory capture, …). */
+export interface QueueAdapter {
+  send(queue: string, body: unknown, options?: QueueSendOptions): Promise<void>;
+  sendBatch(queue: string, messages: readonly QueueSendRequest[], options?: QueueBatchOptions): Promise<void>;
+}
+
+/** The `ctx.queue` facade: validates, then delegates to the adapter for a named queue. */
+export class Queue {
+  constructor(private readonly adapter: QueueAdapter) {}
+
+  /** Enqueue a single message onto `queue`. `body` is serialized by the platform. */
+  async send(queue: string, body: unknown, options?: QueueSendOptions): Promise<void> {
+    assertQueueName(queue);
+    if (body === undefined) throw new Error("ctx.queue.send: `body` is required");
+    await this.adapter.send(queue, body, options);
+  }
+
+  /** Enqueue many messages onto `queue` in one call (cheaper than N sends). */
+  async sendBatch(queue: string, messages: readonly QueueSendRequest[], options?: QueueBatchOptions): Promise<void> {
+    assertQueueName(queue);
+    if (!Array.isArray(messages) || messages.length === 0) {
+      throw new Error("ctx.queue.sendBatch: `messages` must be a non-empty array");
+    }
+    for (const m of messages) {
+      if (!m || m.body === undefined) throw new Error("ctx.queue.sendBatch: every message needs a `body`");
+    }
+    await this.adapter.sendBatch(queue, messages, options);
+  }
+}
+
+function assertQueueName(queue: string): void {
+  if (typeof queue !== "string" || queue.length === 0) {
+    throw new Error("ctx.queue: a queue name is required (the oblaka `Queue` name)");
+  }
+}
+
+/** Cloudflare Queues transport. Constructed with the producer bindings discovered from
+ * the environment, keyed by binding name. Sending to a name with no bound queue throws
+ * a clear error (fail-closed) — a missing binding is a config error, not a silent drop. */
+export class CloudflareQueueAdapter implements QueueAdapter {
+  constructor(private readonly bindings: Readonly<Record<string, QueueProducerBinding>>) {}
+
+  private bindingFor(queue: string): QueueProducerBinding {
+    const b = this.bindings[queue];
+    if (!b) {
+      const known = Object.keys(this.bindings);
+      const avail = known.length ? known.join(", ") : "none";
+      throw new Error(
+        `ctx.queue: no queue binding '${queue}' — declare it in oblaka.ts ` +
+          `(new Queue({ name: '${queue}', binding: 'both' })). Bound queues: ${avail}.`,
+      );
+    }
+    return b;
+  }
+
+  async send(queue: string, body: unknown, options?: QueueSendOptions): Promise<void> {
+    await this.bindingFor(queue).send(body, options);
+  }
+
+  async sendBatch(queue: string, messages: readonly QueueSendRequest[], options?: QueueBatchOptions): Promise<void> {
+    await this.bindingFor(queue).sendBatch(messages, options);
+  }
+}
+
+/** In-memory transport: captures sent messages instead of delivering them. For unit
+ * tests (assert on `.sent`) and pure off-platform use. */
+export class MemoryQueueAdapter implements QueueAdapter {
+  readonly sent: Array<{ queue: string; body: unknown; options?: QueueSendOptions | QueueBatchOptions }> = [];
+  async send(queue: string, body: unknown, options?: QueueSendOptions): Promise<void> {
+    this.sent.push({ queue, body, options });
+  }
+  async sendBatch(queue: string, messages: readonly QueueSendRequest[], options?: QueueBatchOptions): Promise<void> {
+    for (const m of messages) this.sent.push({ queue, body: m.body, options: { ...options, ...m } });
+  }
+}
+
+/** Discover the Cloudflare Queues producer bindings in an environment: any value that
+ * exposes BOTH `send` and `sendBatch` functions (which excludes the email `send`-only
+ * binding, KV, R2, D1, the DO namespace, …). Returns name → binding. */
+export function discoverQueueBindings(env: Readonly<Record<string, unknown>>): Record<string, QueueProducerBinding> {
+  const out: Record<string, QueueProducerBinding> = {};
+  for (const [name, value] of Object.entries(env)) {
+    if (
+      value &&
+      typeof value === "object" &&
+      typeof (value as { send?: unknown }).send === "function" &&
+      typeof (value as { sendBatch?: unknown }).sendBatch === "function"
+    ) {
+      out[name] = value as QueueProducerBinding;
+    }
+  }
+  return out;
+}
+
+/** Build `ctx.queue` from the environment: a Cloudflare adapter over the discovered
+ * producer bindings. Sending to an undeclared queue fails closed (the adapter throws).
+ * There is no silent capture fallback — declare the `Queue` binding and it exists in
+ * dev (lopata) and miniflare too. */
+export function createQueue(env: Readonly<Record<string, unknown>>): Queue {
+  return new Queue(new CloudflareQueueAdapter(discoverQueueBindings(env)));
+}

package/src/runtime/read-engine.ts

@@ -91,7 +91,12 @@ export function compileExpr(expr: SqlExpr, dialect: Dialect, params: unknown[] =
     case "false":
       return { sql: "0", params };
     case "cmp":
-      if (expr.value === null) return { sql: `${dialect.id(expr.col)} IS NULL`, params };
+      // A comparison against NULL is never TRUE in SQL (=, !=, <, > all yield NULL).
+      // Only the dedicated `null` node produces `IS NULL`; a `cmp` with a null operand
+      // matches nothing. (`eq()` already routes an equality-to-null to the `null` node,
+      // and the keyset comparator handles null order-keys explicitly — so no legitimate
+      // caller reaches here with a null value.)
+      if (expr.value === null) return { sql: "0", params };
       params.push(dialect.encode(expr.value));
       return { sql: `${dialect.id(expr.col)} ${expr.op} ${dialect.placeholder(params.length)}`, params };
     case "null":
@@ -145,7 +150,7 @@ export function evalExpr(expr: SqlExpr, row: Record<string, unknown>): boolean {
       return false;
     case "cmp": {
       const left = bind(row[expr.col]);
-      if (expr.value === null) return left === null || left === undefined;
+      if (expr.value === null) return false; // comparison against NULL is never true (use the `null` node for IS NULL)
       if (left === null || left === undefined) return false; // NULL compared to a value -> false
       const right = bind(expr.value);
       switch (expr.op) {

package/src/runtime/schema-diff.ts

@@ -1,56 +1,170 @@
-// Schema shape + diff — powers the CLI's `schema diff`. migrate() applies every
-// change on the next DO boot, additive AND destructive. A diff classifies each as
-// `destructive` (drop / type change — rebuilds the table and CAN lose data) or not
-// (add table/column — no data loss). A rename can't be detected from a shape diff;
-// it shows as drop+add unless declared with `renamedFrom` in the schema.
+// Schema shape + diff — powers the CLI's `schema diff`. The diff is a REPORTING tool; it
+// does not itself migrate. On the next DO boot migrate() applies ADDITIVE changes only
+// (new table -> CREATE TABLE; new column -> ALTER TABLE ADD COLUMN). DESTRUCTIVE changes
+// (drop column/table, type change, table rebuild) are SKIPPED unless the deploy sets
+// PRAMEN_ALLOW_DESTRUCTIVE=true — and when skipped the schema hash is left unwritten so a
+// later opt-in deploy retries. A rename can't be detected from a shape diff; it shows as
+// drop+add unless declared with `renamedFrom` in the schema.
+//
+// The shape records column type + the migration-relevant modifiers (notNull, unique,
+// primaryKey, generated, default, hidden) and the entity's partition, so the diff REPORTS
+// modifier and partition changes too. migrate() now RECONCILES modifier changes on an
+// existing column (a NOT NULL / DEFAULT / PRIMARY KEY change via a rebuild, a UNIQUE
+// change via a create/drop index), so a `change-column` is `appliesOnBoot: true`. It is
+// flagged `destructive` when it tightens a constraint (adds NOT NULL / UNIQUE / PRIMARY
+// KEY) — those apply only under PRAMEN_ALLOW_DESTRUCTIVE, or are skipped when the live
+// data conflicts (NULL rows / duplicates), leaving the hash unwritten. A partition MOVE
+// still CANNOT be enacted on boot (a partition is a separate Durable Object — it needs a
+// manual cross-DO data migration), so it stays `appliesOnBoot: false`.
 
 import type { FieldDef, SchemaDef } from "../sdk/schema";
+import { partitionOf } from "../sdk/schema";
 
-/** table -> column -> field type. The comparable surface of a schema. */
-export type SchemaShape = Record<string, Record<string, string>>;
+/** The comparable fingerprint of a single column: type + migration-relevant modifiers. */
+export interface ColumnShape {
+  type: string;
+  notNull?: boolean;
+  unique?: boolean;
+  primaryKey?: boolean;
+  generated?: boolean;
+  hidden?: boolean;
+  /** The literal or raw-SQL default, normalized to a string for comparison. */
+  default?: string;
+}
+
+/** The comparable fingerprint of a table: its partition + each column's shape. */
+export interface TableShape {
+  partition: string;
+  columns: Record<string, ColumnShape>;
+}
+
+/** table -> table shape. The comparable surface of a schema. */
+export type SchemaShape = Record<string, TableShape>;
+
+function columnShape(f: FieldDef): ColumnShape {
+  const c: ColumnShape = { type: f.type };
+  if (f.notNull) c.notNull = true;
+  if (f.unique) c.unique = true;
+  if (f.primaryKey) c.primaryKey = true;
+  if (f.generated) c.generated = true;
+  if (f.hidden) c.hidden = true;
+  if (f.defaultExpr !== undefined) c.default = `(${f.defaultExpr})`;
+  else if (f.default !== undefined) c.default = JSON.stringify(f.default);
+  return c;
+}
 
 export function schemaShape(schema: SchemaDef): SchemaShape {
   const out: SchemaShape = {};
   for (const [table, def] of Object.entries(schema)) {
-    const cols: Record<string, string> = {};
-    for (const [col, f] of Object.entries(def.fields)) cols[col] = (f as FieldDef).type;
-    out[table] = cols;
+    const columns: Record<string, ColumnShape> = {};
+    for (const [col, f] of Object.entries(def.fields)) columns[col] = columnShape(f as FieldDef);
+    out[table] = { partition: partitionOf(schema, table), columns };
   }
   return out;
 }
 
+/** The modifier fields compared for a `change-column` (everything but `type`). */
+const MODIFIER_KEYS: (keyof ColumnShape)[] = ["notNull", "unique", "primaryKey", "generated", "hidden", "default"];
+
+/** Does `next` tighten a constraint `prev` lacked (add NOT NULL / UNIQUE / PRIMARY KEY)?
+ * Such a change may require the destructive gate or be skipped when the live data
+ * conflicts (NULL rows / duplicates) — so the diff flags it `destructive`. */
+function tightensConstraint(prev: ColumnShape, next: ColumnShape): boolean {
+  return (!!next.notNull && !prev.notNull) || (!!next.unique && !prev.unique) || (!!next.primaryKey && !prev.primaryKey);
+}
+
+function modifierDiff(prev: ColumnShape, next: ColumnShape): string | null {
+  const parts: string[] = [];
+  for (const k of MODIFIER_KEYS) {
+    if (prev[k] !== next[k]) parts.push(`${k}: ${fmt(prev[k])} → ${fmt(next[k])}`);
+  }
+  return parts.length ? parts.join(", ") : null;
+}
+
+function fmt(v: unknown): string {
+  return v === undefined ? "—" : String(v);
+}
+
 export interface SchemaChange {
-  kind: "add-table" | "drop-table" | "add-column" | "drop-column" | "change-type";
+  kind: "add-table" | "drop-table" | "add-column" | "drop-column" | "change-type" | "change-column" | "move-partition";
   table: string;
   column?: string;
   detail?: string;
-  /** true = rebuilds the table and may lose data (drop / type change); false =
-   * additive, no data loss. All changes are auto-applied on the next DO boot. */
+  /** true = rebuilds the table and may lose data (drop / type change). false = additive
+   * OR a metadata-only change (modifier / partition move) — see `appliesOnBoot`. */
   destructive: boolean;
+  /** Whether migrate() enacts this change on the next DO boot. Additive changes are
+   * always applied; destructive changes (type/drop, or a constraint-tightening modifier
+   * change) apply only when the deploy sets PRAMEN_ALLOW_DESTRUCTIVE=true (and are
+   * skipped when the live data conflicts, leaving the hash unwritten). `false` here means
+   * the boot migrator will NEVER enact it — today only a partition MOVE (needs a manual
+   * cross-DO data migration). Reported for honesty. */
+  appliesOnBoot: boolean;
 }
 
 export function diffSchemaShape(prev: SchemaShape, next: SchemaShape): SchemaChange[] {
   const changes: SchemaChange[] = [];
 
   for (const table of Object.keys(next)) {
-    if (!(table in prev)) {
-      changes.push({ kind: "add-table", table, destructive: false });
+    const pt = prev[table];
+    if (!pt) {
+      changes.push({ kind: "add-table", table, destructive: false, appliesOnBoot: true });
       continue;
     }
-    for (const col of Object.keys(next[table]!)) {
-      if (!(col in prev[table]!)) {
-        changes.push({ kind: "add-column", table, column: col, destructive: false });
-      } else if (prev[table]![col] !== next[table]![col]) {
-        changes.push({ kind: "change-type", table, column: col, detail: `${prev[table]![col]} → ${next[table]![col]}`, destructive: true });
+    const nt = next[table]!;
+    if (pt.partition !== nt.partition) {
+      changes.push({
+        kind: "move-partition",
+        table,
+        detail: `${pt.partition} → ${nt.partition}`,
+        destructive: false,
+        // A partition is a separate Durable Object; boot migration can't move a table's
+        // data across DOs. Needs a manual data migration.
+        appliesOnBoot: false,
+      });
+    }
+    for (const col of Object.keys(nt.columns)) {
+      const pc = pt.columns[col];
+      const ncol = nt.columns[col]!;
+      if (!pc) {
+        changes.push({ kind: "add-column", table, column: col, destructive: false, appliesOnBoot: true });
+      } else if (pc.type !== ncol.type) {
+        changes.push({
+          kind: "change-type",
+          table,
+          column: col,
+          detail: `${pc.type} → ${ncol.type}`,
+          destructive: true,
+          // Applied only under PRAMEN_ALLOW_DESTRUCTIVE (a table rebuild). Report it as
+          // boot-applicable — the destructive-gating note explains the opt-in.
+          appliesOnBoot: true,
+        });
+      } else {
+        const md = modifierDiff(pc, ncol);
+        if (md) {
+          changes.push({
+            kind: "change-column",
+            table,
+            column: col,
+            detail: md,
+            // Tightening a constraint (add NOT NULL / UNIQUE / PRIMARY KEY) rebuilds/
+            // indexes and applies only under PRAMEN_ALLOW_DESTRUCTIVE (or is skipped when
+            // live data conflicts). Loosening or a DEFAULT change is additive.
+            destructive: tightensConstraint(pc, ncol),
+            // migrate() now reconciles modifier changes on an existing column on boot.
+            appliesOnBoot: true,
+          });
+        }
       }
     }
-    for (const col of Object.keys(prev[table]!)) {
-      if (!(col in next[table]!)) changes.push({ kind: "drop-column", table, column: col, destructive: true });
+    for (const col of Object.keys(pt.columns)) {
+      if (!(col in nt.columns))
+        changes.push({ kind: "drop-column", table, column: col, destructive: true, appliesOnBoot: true });
     }
   }
 
   for (const table of Object.keys(prev)) {
-    if (!(table in next)) changes.push({ kind: "drop-table", table, destructive: true });
+    if (!(table in next)) changes.push({ kind: "drop-table", table, destructive: true, appliesOnBoot: true });
   }
 
   return changes;

package/src/sdk/handlers.ts

@@ -5,6 +5,7 @@
 import type { Db } from "../runtime/db";
 import type { Kv } from "../runtime/kv";
 import type { Mail } from "../runtime/mail";
+import type { Queue } from "../runtime/queue";
 import type { Identity } from "./acl";
 import type { Files } from "./files";
 import type { SchemaDef } from "./schema";
@@ -36,6 +37,12 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
    * runs the matching `app.tasks` handler after commit, off the write path, with
    * retry. For notification email, webhooks, etc. — see `app.tasks`. */
   readonly tasks: Tasks;
+  /** Enqueue onto a native Cloudflare Queue: `ctx.queue.send("jobs", body)`. Unlike
+   * `ctx.tasks` (a transactional outbox, atomic with the mutation, drained in-process),
+   * a queue send is NOT transactional with the write but is higher-throughput, with
+   * platform-native batching/retry/DLQ and a consumer that may live in another Worker.
+   * Declare queues in oblaka.ts; consume them via `app.queues`. */
+  readonly queue: Queue;
 }
 
 /** The deferred-side-effects facade handed to handlers as `ctx.tasks`. */