solid-objects 0.14.6 → 0.14.7

package/docs/cloudflare.md

@@ -0,0 +1,155 @@
+# Cloudflare Durable Objects
+
+Import actor definitions from `solid-objects/core` to share them between Node
+and Workers. On Cloudflare, import `createRuntime`, `durableObjects`,
+`createDurableObjectsHost`, and `createDurableObjectsSessionHost` from
+`solid-objects/cloudflare`.
+
+The [runnable example](../examples/cloudflare/README.md) includes both Durable
+Object classes, Wrangler bindings, migrations, and a public shopping cart.
+
+## Configure the hosts
+
+```typescript
+import { createRuntime, durableObjects, withRuntime } from "solid-objects/cloudflare"
+
+const runtime = createRuntime({
+  backend: durableObjects({ namespace: env.ACTORS, sessions: env.SESSIONS }),
+})
+
+const counter = runtime.ref(Counter, "counter-1")
+const count = await counter.with({ authorizationContext: subject }).increment()
+await withRuntime(
+  runtime,
+  () => Counter.ref("counter-1").with({ authorizationContext: subject }).count,
+)
+```
+
+Define the actor host once with `createDurableObjectsHost({ actors, configure })`.
+`configure(env)` returns a `CloudflareConfiguration` with the same backend
+bindings, authorization policies, and an `effects` map of named handlers. A
+handler receives the existing effect arguments and `EffectContext` with its
+stable delivery ID. Definitions and configuration stay inside the deployment;
+they are not transmitted through RPC.
+
+Use `runtime.ref()` or request-scoped `withRuntime()` in Worker handlers.
+`Actor.ref()` within actor operations and lifecycle callbacks retains its
+runtime across awaits. The backend does not set a global default runtime.
+
+The host supplies storage and scheduling, so there is no `install()` or
+`run()` step. Configure both exported classes using `new_sqlite_classes` and
+enable `nodejs_compat` for async context propagation. Library schema migrations
+run synchronously on activation and use a separate migration ledger.
+
+## Guarantees and recovery
+
+An actor type plus its string-normalized ID routes to one Durable Object.
+Operations and getters enter its ordered durable mailbox. Snapshots read one
+committed state image without entering the mailbox. A retryable head blocks
+later turns, and permanent failures pause that actor until operator recovery.
+
+State, results, effects, outbound messages, reminders, and the next alarm commit
+together. Actor code executes outside that short transaction. Destruction and
+restart generations fence stale commits. State migrations and read-only
+projection checks use the same implementation as the SQL runtime.
+
+Delivery is at least once. An effect can reach its external service before the
+acknowledgement is stored. Deduplicate using `EffectContext.id`. `sendTo()` stores
+an outbound intent in the source object and deduplicates acceptance in the
+destination. This is eventual delivery, not a cross-object transaction.
+Actors cannot synchronously call or wait on other actors.
+
+One alarm covers the next due mailbox turn, retry, reminder, outbox delivery,
+subscription expiry, or retention deadline. Persistent retry state supplements
+Cloudflare's finite automatic alarm retries. Idle objects have no recurring
+polling loop. Completed records default to 30 days of retention; dead letters
+remain available for inspection. Idempotency receipts expire with their messages,
+so callers must not rely on deduplication after the retention window.
+
+An invocation timeout after acceptance raises `SyncTimeout` with a recoverable
+`messageReference`. If RPC fails before an acceptance response arrives,
+`EnqueueOutcomeUnknown.details` contains `actorType`, `actorId`, and `requestId`:
+
+```typescript
+const message = await runtime.lookupMessage({
+  ...error.details,
+  authorizationContext: subject,
+})
+if (message) await message.wait({ authorizationContext: subject })
+```
+
+A missing lookup is not proof that an outstanding enqueue cannot still arrive.
+Look up again, or retry the application operation with its original explicit
+idempotency key. Lookup requires query authorization for `__lookupMessage__`;
+an existing message also requires authorization for its original operation.
+
+Use `runtime.actorAdministration({ actorType, actorId, authorizationContext })`
+for `deadLetters()`, `retryDeadLetter(id)`, `reminders()`, and
+`resumeReminder({ name, runAt })`. Inspection is bounded to 1,000 records per
+call. These operations call `authorizeAdministration` with resource
+`actor:` followed by the canonical JSON identity tuple.
+
+## Realtime sessions
+
+The application authenticates its HTTP upgrade before calling
+`runtime.openWebSocket({ sessionId, expiresAt })`. Forward the returned response
+to the browser. `sessionId` must be an opaque application session reference,
+not a bearer credential or serialized user object. Never forward client-supplied
+`X-Solid-Session-*` headers to the session namespace.
+
+The session host's `resolveAuthorizationContext({ sessionId, environment })`
+loads current authorization data and returns JSON, or `null` when access has
+expired or been revoked. It runs when opening the connection, subscribing, and
+delivering events. Actor policies still authorize subscriptions and each named
+personalized payload. Authentication remains application-owned.
+
+One hibernating WebSocket multiplexes up to 100 actors by default. Configure
+`maxSubscriptions` on the session host to change that limit. The browser client,
+version-1 envelopes, value versus invalidation projections, personalized
+payloads, and revision fences use the existing protocol.
+
+The handshake uses Fetch because WebSocket upgrades cannot travel through
+ordinary RPC. Actor-to-session events use RPC. Durable registrations survive
+hibernation; disconnect and expiry trigger registration cleanup. Reconnects
+replay current committed projections, not every event missed while offline.
+
+## Capability boundaries
+
+| Surface                                                            | Cloudflare backend                     |
+| ------------------------------------------------------------------ | -------------------------------------- |
+| Actor operations, getters, snapshots, state migrations             | Supported                              |
+| Durable sends, results, retries, rejection, destruction            | Supported                              |
+| Effects, reminders, cross-actor `sendTo()`                         | Supported                              |
+| Browser subscriptions and personalized payloads                    | Supported through session hosts        |
+| Actor-scoped dead letters and reminder administration              | Supported                              |
+| `commitAction`, shared application SQL transactions                | Unsupported                            |
+| Global repository, reconciliation, process controls, SQL dashboard | Unsupported                            |
+| Process-local `runtime.realtime.connect()` / server `ref.live`     | Unsupported; use browser subscriptions |
+| SQL-to-Durable-Objects data migration                              | Not provided                           |
+
+Unsupported runtime facilities raise `UnsupportedCapability`; staging a commit
+action permanently fails that turn before any state or intent commits.
+Application and effect code must run within Workers' APIs and execution limits.
+Arbitrary JavaScript is cooperative; caller timeout does not preempt it.
+Eviction may discard private fields, and does not guarantee `onDeactivate()`.
+
+State defaults to a 1 MiB limit. Encoded records, including indexed copies of
+fields, must also fit Cloudflare's 2 MB SQLite row limit. Oversized records raise
+`PayloadTooLarge`; increasing a configured payload limit cannot bypass the
+[platform limits](https://developers.cloudflare.com/durable-objects/platform/limits/).
+
+Cloudflare hosting is JavaScript-specific. It does not change Ruby's SQL backend
+or the guarantees of the existing SQL drivers.
+
+## Validate and release
+
+`pnpm run test:cloudflare` runs the Workers integration suite. `pnpm run check`
+type-checks the separate Workers target alongside Node; `pnpm run check:cloudflare`
+checks the example bundle and its imports. Keep backend schema changes additive.
+Once an actor persists a newer state version, rollback to older actor code may
+be unsafe; test that rollback against the stored version before deploying it.
+
+Before calling this backend stable, run a deployed soak in a disposable
+namespace covering alarms without traffic, eviction/restart recovery,
+hibernation, and slow external effects. Local Workers tests do not establish
+Cloudflare production failover behavior.

package/docs/parity.md

@@ -40,6 +40,10 @@ such boundary between a gem and its dependents.
 
 ## Runtime and correctness
 
+SQL waiters read results and status from one statement. Ruby already checks
+completion and returns the result from the same loaded message; no Ruby change
+is needed for the JavaScript stale-result race fix.
+
 | Capability                                                                                                    | Status  | TypeScript shape or remaining work                                                                                                                                                                                                                                                                                                     |
 | ------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Actor registry, durable identity, JSON state, and adjacent state migrations                                   | Native  | Ordinary classes, static actor types, inferred state, explicit migrations, and isolated runtime context across every actor-instance callback.                                                                                                                                                                                          |
@@ -180,6 +184,21 @@ and Rails to Node) ran in solid-objects-ruby#49; the one disagreement it
 found (the optional `arguments` default) is fixed and pinned by the shared
 fixture.
 
+## JavaScript-only: Cloudflare hosting
+
+The experimental `solid-objects/cloudflare` backend hosts each actor identity
+in a SQLite-backed Durable Object. Portable actor definitions, turn evaluation,
+state migrations, and authorization are shared with the SQL runtime. Alarms
+drive durable mailbox/outbox recovery, and session Durable Objects host
+hibernating browser subscriptions.
+
+Ruby hosting on Cloudflare is **Not applicable**. This backend introduces no
+change to Ruby's SQL behavior or roadmap. Its JavaScript support is **Partial**
+until deployed failover and soak validation completes. Shared SQL transactions,
+commit actions, fleet administration, reconciliation, and the SQL dashboard
+are explicit unsupported capabilities. The [backend matrix](cloudflare.md#capability-boundaries)
+records these boundaries separately from SQL-runtime parity.
+
 ## Rails-specific surfaces
 
 Rails generators, Active Record models/controllers, Turbo rendering, and

package/docs/support.md

@@ -2,17 +2,18 @@
 
 ## Runtime support
 
-| Component       | Supported or tested range                                   |
-| --------------- | ----------------------------------------------------------- |
-| Node.js         | 24.4.0 or newer; CI runs 24.4.0 and 24.15.0                 |
-| TypeScript      | 5.9 or newer for TypeScript applications                    |
-| SQLite          | Node's built-in `node:sqlite` on the supported Node runtime |
-| PostgreSQL      | 14 or newer; CI runs 14 and 18                              |
-| MySQL           | 8.0 or newer with InnoDB; CI runs 8.0 and 8.4               |
-| Redis wake-up   | Optional; CI runs Redis 7                                   |
-| Browser client  | Chromium through Playwright                                 |
-| SQLite WASM     | `@sqlite.org/sqlite-wasm` 3.50 or newer; optional           |
-| Browser runtime | Chromium through Playwright; OPFS for persistent storage    |
+| Component          | Supported or tested range                                          |
+| ------------------ | ------------------------------------------------------------------ |
+| Node.js            | 24.4.0 or newer; CI runs 24.4.0 and 24.15.0                        |
+| TypeScript         | 5.9 or newer for TypeScript applications                           |
+| SQLite             | Node's built-in `node:sqlite` on the supported Node runtime        |
+| PostgreSQL         | 14 or newer; CI runs 14 and 18                                     |
+| MySQL              | 8.0 or newer with InnoDB; CI runs 8.0 and 8.4                      |
+| Redis wake-up      | Optional; CI runs Redis 7                                          |
+| Browser client     | Chromium through Playwright                                        |
+| SQLite WASM        | `@sqlite.org/sqlite-wasm` 3.50 or newer; optional                  |
+| Browser runtime    | Chromium through Playwright; OPFS for persistent storage           |
+| Cloudflare runtime | Experimental; Workers integration tests and Wrangler bundle checks |
 
 The package is ESM-only. PostgreSQL, MySQL, Redis, and SQLite WASM require
 their optional peer dependency. The Node SQLite adapter has no driver

package/examples/cloudflare/README.md

@@ -0,0 +1,49 @@
+# Cloudflare shopping cart
+
+This is an intentionally public shopping cart. Anyone can add or remove items
+from `ShoppingCart("demo-cart")`; destruction and administration remain denied.
+Replace the demo session resolver with your application's session lookup before
+using this example for private data.
+
+The example code is here:
+
+- [`shopping-cart.ts`](./shopping-cart.ts) — actor state, cart operations, and realtime observables
+- [`worker.ts`](./worker.ts) — Worker routes, authorization, and Durable Object hosts
+- [`wrangler.jsonc`](./wrangler.jsonc) — SQLite-backed Durable Object bindings and migrations
+- [`environment.d.ts`](./environment.d.ts) — generated Wrangler binding types
+
+From the repository root:
+
+```sh
+pnpm install
+pnpm run build
+pnpm run dev:cloudflare
+```
+
+In another terminal:
+
+```sh
+curl http://localhost:8787/cart
+curl -X POST http://localhost:8787/cart/items \
+  -H 'content-type: application/json' \
+  --data '{"sku":"book","name":"Solid Objects book","priceCents":2500,"quantity":1}'
+curl -X POST http://localhost:8787/cart/remove \
+  -H 'content-type: application/json' \
+  --data '{"sku":"book"}'
+curl -X POST http://localhost:8787/cart/clear-later
+```
+
+The last call schedules the cart to clear five seconds later. Stop the local
+server and start it again to verify persistence. Local state lives in
+Wrangler's `.wrangler` directory. Each actor identity has its own SQLite-backed
+Durable Object; browser connections use the separate `Sessions` class.
+
+Connect the existing `SolidObjectsBrowserClient` to `/events` and subscribe to
+`{ actorType: "ShoppingCart", actorId: "demo-cart" }`. The connection expires
+after one hour. Reconnect and resubscribe to obtain the current committed
+projection with `itemCount` and `totalCents`.
+
+`pnpm run check:cloudflare` validates the production bundle without uploading it.
+To deploy this example to your own account, run `fnox exec -- pnpm run deploy:cloudflare`.
+Wrangler creates the two SQLite-backed namespaces using the configuration's
+class migrations. No D1 database or external broker is required.

package/examples/cloudflare/environment.d.ts

@@ -0,0 +1,14 @@
+/* eslint-disable */
+// Generated by Wrangler by running `wrangler types --config=examples/cloudflare/wrangler.jsonc --include-runtime=false examples/cloudflare/environment.d.ts` (hash: 30c3823992a5154da09c838c96a8f2fb)
+interface __BaseEnv_Env {
+  ACTORS: DurableObjectNamespace<import("./worker").Actors>
+  SESSIONS: DurableObjectNamespace<import("./worker").Sessions>
+}
+declare namespace Cloudflare {
+  interface GlobalProps {
+    mainModule: typeof import("./worker")
+    durableNamespaces: "Actors" | "Sessions"
+  }
+  interface Env extends __BaseEnv_Env {}
+}
+interface Env extends __BaseEnv_Env {}

package/examples/cloudflare/shopping-cart.ts

@@ -0,0 +1,65 @@
+import { Actor, broadcastValue } from "solid-objects/core"
+
+interface CartItem {
+  name: string
+  priceCents: number
+  quantity: number
+}
+
+export class ShoppingCart extends Actor {
+  static override readonly actorType = "ShoppingCart"
+  items: Record<string, CartItem> = {}
+
+  addItem(input: { sku: string; name: string; priceCents: number; quantity?: number }): number {
+    if (
+      !input.sku ||
+      !input.name ||
+      !Number.isSafeInteger(input.priceCents) ||
+      input.priceCents < 0
+    )
+      throw new TypeError("sku, name, and a non-negative integer priceCents are required")
+    const quantity = input.quantity ?? 1
+    if (!Number.isSafeInteger(quantity) || quantity <= 0)
+      throw new TypeError("quantity must be a positive safe integer")
+    const existing = this.items[input.sku]
+    const combinedQuantity = (existing?.quantity ?? 0) + quantity
+    if (!Number.isSafeInteger(combinedQuantity))
+      throw new TypeError("combined quantity must be a positive safe integer")
+    this.items[input.sku] = {
+      name: input.name,
+      priceCents: input.priceCents,
+      quantity: combinedQuantity,
+    }
+    return this.totalCents
+  }
+
+  removeItem(input: { sku: string }): void {
+    delete this.items[input.sku]
+  }
+
+  clear(): void {
+    this.items = {}
+  }
+
+  clearLater(): void {
+    this.schedule({ at: new Date(Date.now() + 5_000), key: "clear" }).clear!()
+  }
+
+  get itemCount(): number {
+    return Object.values(this.items).reduce((total, item) => total + item.quantity, 0)
+  }
+
+  get totalCents(): number {
+    return Object.values(this.items).reduce(
+      (total, item) => total + item.priceCents * item.quantity,
+      0,
+    )
+  }
+
+  override observables() {
+    return {
+      itemCount: broadcastValue(this.itemCount),
+      totalCents: broadcastValue(this.totalCents),
+    }
+  }
+}

package/examples/cloudflare/worker.ts

@@ -0,0 +1,87 @@
+import {
+  createDurableObjectsHost,
+  createDurableObjectsSessionHost,
+  createRuntime,
+  durableObjects,
+  type CloudflareConfiguration,
+} from "solid-objects/cloudflare"
+import { ShoppingCart } from "./shopping-cart.js"
+
+function backend(environment: Env) {
+  return durableObjects({ namespace: environment.ACTORS, sessions: environment.SESSIONS })
+}
+
+function publicCart(input: {
+  actorType: string
+  actorId: string
+  authorizationContext: unknown
+}): boolean {
+  return (
+    input.actorType === "ShoppingCart" &&
+    input.actorId === "demo-cart" &&
+    input.authorizationContext === "public-demo"
+  )
+}
+
+export class Actors extends createDurableObjectsHost<Env>({
+  actors: [ShoppingCart],
+  configure: (environment): CloudflareConfiguration => ({
+    backend: backend(environment),
+    authorizeMessage: publicCart,
+    authorizeQuery: publicCart,
+    authorizeSubscription: publicCart,
+  }),
+}) {}
+
+export class Sessions extends createDurableObjectsSessionHost<Env>({
+  backend,
+  resolveAuthorizationContext: ({ sessionId }) =>
+    sessionId === "demo-cart" ? "public-demo" : null,
+}) {}
+
+export default {
+  async fetch(request: Request, environment: Env): Promise<Response> {
+    const url = new URL(request.url)
+    const runtime = createRuntime({ backend: backend(environment) })
+    const cartReference = runtime.ref(ShoppingCart, "demo-cart")
+    const cart = cartReference.with({ authorizationContext: "public-demo" })
+    const isWebSocketRequest =
+      url.pathname === "/events" && request.headers.get("Upgrade") === "websocket"
+    const origin = request.headers.get("Origin")
+    if (isWebSocketRequest && origin !== null && origin !== url.origin)
+      return new Response("Forbidden", { status: 403 })
+    if (isWebSocketRequest)
+      return runtime.openWebSocket({
+        sessionId: "demo-cart",
+        expiresAt: new Date(Date.now() + 3_600_000),
+      })
+    if (request.method === "GET" && url.pathname === "/cart")
+      return Response.json(
+        await runtime.snapshot(cartReference, { authorizationContext: "public-demo" }),
+      )
+    if (request.method === "POST" && url.pathname === "/cart/items") {
+      const item = (await request.json()) as {
+        sku: string
+        name: string
+        priceCents: number
+        quantity?: number
+      }
+      return Response.json({ totalCents: await cart.addItem(item) })
+    }
+    if (request.method === "POST" && url.pathname === "/cart/remove") {
+      const item = (await request.json()) as { sku: string }
+      await cart.removeItem(item)
+      return new Response(null, { status: 204 })
+    }
+    if (request.method === "POST" && url.pathname === "/cart/clear-later") {
+      await cart.clearLater()
+      return new Response(null, { status: 202 })
+    }
+    return new Response(
+      "GET /cart; POST /cart/items; POST /cart/remove; POST /cart/clear-later; WebSocket /events",
+      {
+        status: url.pathname === "/" ? 200 : 404,
+      },
+    )
+  },
+} satisfies ExportedHandler<Env>

package/examples/cloudflare/wrangler.jsonc

@@ -0,0 +1,15 @@
+{
+  "$schema": "../../node_modules/wrangler/config-schema.json",
+  "name": "solid-objects-shopping-cart",
+  "main": "worker.ts",
+  "compatibility_date": "2026-09-04",
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": {
+    "bindings": [
+      { "name": "ACTORS", "class_name": "Actors" },
+      { "name": "SESSIONS", "class_name": "Sessions" },
+    ],
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Actors", "Sessions"] }],
+  "observability": { "enabled": true },
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-objects",
-  "version": "0.14.6",
+  "version": "0.14.7",
   "description": "Race-free realtime state per application identity, backed by your SQL database",
   "type": "module",
   "license": "MIT",
@@ -38,6 +38,14 @@
     "MIT-LICENSE"
   ],
   "exports": {
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare/index.d.ts",
+      "import": "./dist/cloudflare/index.js"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
@@ -92,8 +100,12 @@
     }
   },
   "scripts": {
-    "build": "pnpm run clean && tsc -p tsconfig.build.json && tsc -p tsconfig.quickstart-build.json && node scripts/prepare-executable.mjs",
-    "check": "pnpm run check:parameters && pnpm run check:documentation && pnpm run check:browser-imports && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.examples.json --noEmit",
+    "test:cloudflare": "vitest run --config vitest.cloudflare.config.ts",
+    "dev:cloudflare": "wrangler dev --config examples/cloudflare/wrangler.jsonc",
+    "deploy:cloudflare": "wrangler deploy --config examples/cloudflare/wrangler.jsonc",
+    "check:cloudflare": "node scripts/check-cloudflare-imports.mjs && tsc -p tsconfig.cloudflare-example.json --noEmit && wrangler deploy --dry-run --config examples/cloudflare/wrangler.jsonc",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json && tsc -p tsconfig.cloudflare-build.json && tsc -p tsconfig.quickstart-build.json && node scripts/prepare-executable.mjs",
+    "check": "pnpm run check:parameters && pnpm run check:documentation && pnpm run check:browser-imports && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.examples.json --noEmit && tsc -p tsconfig.cloudflare.json --noEmit",
     "check:browser-imports": "node scripts/check-browser-imports.mjs",
     "check:documentation": "node scripts/check-documentation.mjs",
     "check:parameters": "node scripts/check-parameter-style.mjs",
@@ -117,6 +129,8 @@
     "prepack": "pnpm run build"
   },
   "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.1.4",
+    "@cloudflare/workers-types": "^5.20260904.1",
     "@playwright/test": "^1.62.1",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@types/node": "^24.0.0",
@@ -130,14 +144,15 @@
     "signal-polyfill": "^0.2.2",
     "typescript": "^5.9.0",
     "vitest": "^4.1.10",
+    "wrangler": "^4.129.0",
     "ws": "^8.21.3"
   },
   "peerDependencies": {
     "@sqlite.org/sqlite-wasm": ">=3.50.0-build1",
-    "signal-polyfill": ">=0.2.2",
     "mysql2": "^3.23.3",
     "pg": "^8.23.0",
-    "redis": "^6.2.1"
+    "redis": "^6.2.1",
+    "signal-polyfill": ">=0.2.2"
   },
   "peerDependenciesMeta": {
     "@sqlite.org/sqlite-wasm": {