solid-objects 0.12.1 → 0.13.1

package/examples/failure-recovery/demo.ts

@@ -0,0 +1,233 @@
+import assert from "node:assert/strict"
+import { existsSync } from "node:fs"
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { fork, type ChildProcess } from "node:child_process"
+import { createRuntime, type ActorReference, type MessageReference } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+import { RecoveryCounter } from "./actor.ts"
+
+interface WorkerMessage {
+  event: string
+  attempt?: number
+  processed?: number
+}
+
+interface SerializationEvent {
+  event: "start" | "finish"
+  messageId: string
+  at: number
+}
+
+interface ExternalEffectEvent {
+  messageId: string
+  attempt: number
+  processId: number
+}
+
+const directory = await mkdtemp(join(tmpdir(), "solid-objects-recovery-"))
+const databasePath = join(directory, "state.sqlite3")
+const runtime = createRuntime({
+  database: sqlite({ path: databasePath, timeoutMilliseconds: 2_000, lockRetryAttempts: 20 }),
+  leaseDurationMilliseconds: 250,
+  leaseRenewalIntervalMilliseconds: 50,
+  processHeartbeatIntervalMilliseconds: 75,
+  processAliveThresholdMilliseconds: 300,
+  workerCount: 1,
+  effectWorkerCount: 0,
+  reminderSchedulerCount: 0,
+  retentionIntervalMilliseconds: 0,
+  deadProcessCleanupIntervalMilliseconds: 0,
+  authorizeMessage: () => true,
+  authorizeQuery: () => true,
+  authorizeAdministration: () => true,
+})
+
+try {
+  runtime.register(RecoveryCounter)
+  await runtime.install()
+  const serialization = await proveSerialization()
+  const crash = await proveCrashRecovery()
+  const fencing = await proveFencing()
+  process.stdout.write(`${JSON.stringify({ serialization, crash, fencing }, null, 2)}\n`)
+} finally {
+  await runtime.close()
+  await rm(directory, { recursive: true })
+}
+
+assert.equal(existsSync(directory), false)
+
+async function proveSerialization(): Promise<{ finalState: number; overlap: false }> {
+  const controlDirectory = join(directory, "serialization")
+  await mkdir(controlDirectory)
+  const reference = runtime.ref(RecoveryCounter, "serialized")
+  const messages = await Promise.all([
+    reference.send.serialize({ controlDirectory }),
+    reference.send.serialize({ controlDirectory }),
+  ])
+  const workers = [spawnWorker(), spawnWorker()]
+  await Promise.all(workers.map(({ finished }) => finished))
+  await Promise.all(messages.map((message) => message.result()))
+  const events = await readJsonLines(
+    join(controlDirectory, "serialization.jsonl"),
+    parseSerializationEvent,
+  )
+  assert.equal(events.length, 4)
+  const starts = events.filter((event) => event.event === "start")
+  const finishes = events.filter((event) => event.event === "finish")
+  assert.equal(starts.length, 2)
+  assert.equal(finishes.length, 2)
+  assert(Number(starts[1]?.at) >= Number(finishes[0]?.at))
+  const snapshot = await reference.snapshot()
+  assert.equal(snapshot.count, 2)
+  return { finalState: snapshot.count, overlap: false }
+}
+
+async function proveCrashRecovery(): Promise<{
+  attempts: number
+  finalState: number
+  repeatedEffects: number
+}> {
+  const controlDirectory = join(directory, "crash")
+  await mkdir(controlDirectory)
+  const reference = runtime.ref(RecoveryCounter, "crash")
+  const message = await reference.send.recover({ controlDirectory })
+  const firstWorker = spawnWorker()
+  await firstWorker.waitFor((entry) => entry.event === "operation.started" && entry.attempt === 1)
+  firstWorker.child.kill("SIGKILL")
+  await firstWorker.finished.catch(() => undefined)
+  await wait(350)
+  const recoveryWorker = spawnWorker()
+  await recoveryWorker.finished
+  await message.result()
+  return recoveryResult({ reference, message, controlDirectory })
+}
+
+async function proveFencing(): Promise<{
+  attempts: number
+  finalState: number
+  repeatedEffects: number
+}> {
+  const controlDirectory = join(directory, "fencing")
+  await mkdir(controlDirectory)
+  const reference = runtime.ref(RecoveryCounter, "fencing")
+  const message = await reference.send.recover({ controlDirectory })
+  const staleWorker = spawnWorker()
+  await staleWorker.waitFor((entry) => entry.event === "operation.started" && entry.attempt === 1)
+  staleWorker.child.kill("SIGSTOP")
+  await wait(350)
+  const recoveryWorker = spawnWorker()
+  await recoveryWorker.finished
+  await message.result()
+  staleWorker.child.kill("SIGCONT")
+  await writeFile(join(controlDirectory, "release-first-attempt"), "")
+  await staleWorker.waitFor((entry) => entry.event === "solid_objects.activation.lost")
+  await staleWorker.finished
+  return recoveryResult({ reference, message, controlDirectory })
+}
+
+async function recoveryResult(options: {
+  reference: ActorReference<RecoveryCounter>
+  message: MessageReference
+  controlDirectory: string
+}): Promise<{ attempts: number; finalState: number; repeatedEffects: number }> {
+  const stored = await runtime.repository.findMessage(options.message.id)
+  const attempts = Number(stored?.attempt_count)
+  const snapshot = await options.reference.snapshot()
+  const effects = await readJsonLines(
+    join(options.controlDirectory, "external-effects.jsonl"),
+    parseExternalEffectEvent,
+  )
+  assert.equal(attempts, 2)
+  assert.equal(snapshot.count, 1)
+  assert.equal(effects.length, 2)
+  return { attempts, finalState: snapshot.count, repeatedEffects: effects.length }
+}
+
+function spawnWorker(): {
+  child: ChildProcess
+  finished: Promise<void>
+  waitFor(predicate: (message: WorkerMessage) => boolean): Promise<WorkerMessage>
+} {
+  const child = fork(fileURLToPath(new URL("./worker.ts", import.meta.url)), [databasePath], {
+    cwd: fileURLToPath(new URL("../..", import.meta.url)),
+    stdio: ["ignore", "pipe", "pipe", "ipc"],
+  })
+  const messages: WorkerMessage[] = []
+  const listeners = new Set<(message: WorkerMessage) => void>()
+  let stderr = ""
+  child.stderr?.on("data", (chunk) => {
+    stderr += chunk
+  })
+  child.on("message", (message: WorkerMessage) => {
+    messages.push(message)
+    for (const listener of listeners) listener(message)
+  })
+  const finished = new Promise<void>((resolvePromise, reject) => {
+    child.once("error", reject)
+    child.once("exit", (code, signal) => {
+      if (code === 0) {
+        resolvePromise()
+        return
+      }
+      reject(new Error(`worker exited with code ${code} and signal ${signal}\n${stderr}`))
+    })
+  })
+  return {
+    child,
+    finished,
+    waitFor: (predicate) => {
+      const existing = messages.find(predicate)
+      if (existing) return Promise.resolve(existing)
+      return new Promise((resolvePromise) => {
+        const listener = (message: WorkerMessage) => {
+          if (!predicate(message)) return
+          listeners.delete(listener)
+          resolvePromise(message)
+        }
+        listeners.add(listener)
+      })
+    },
+  }
+}
+
+async function readJsonLines<Value>(
+  path: string,
+  parse: (line: string) => Value,
+): Promise<Value[]> {
+  return (await readFile(path, "utf8")).trim().split("\n").filter(Boolean).map(parse)
+}
+
+function parseSerializationEvent(line: string): SerializationEvent {
+  const event = JSON.parse(line) as Partial<SerializationEvent>
+  if (
+    (event.event !== "start" && event.event !== "finish") ||
+    typeof event.messageId !== "string" ||
+    typeof event.at !== "number"
+  ) {
+    throw new TypeError("invalid serialization event")
+  }
+  return { event: event.event, messageId: event.messageId, at: event.at }
+}
+
+function parseExternalEffectEvent(line: string): ExternalEffectEvent {
+  const event = JSON.parse(line) as Partial<ExternalEffectEvent>
+  if (
+    typeof event.messageId !== "string" ||
+    typeof event.attempt !== "number" ||
+    typeof event.processId !== "number"
+  ) {
+    throw new TypeError("invalid external effect event")
+  }
+  return {
+    messageId: event.messageId,
+    attempt: event.attempt,
+    processId: event.processId,
+  }
+}
+
+async function wait(milliseconds: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds))
+}

package/examples/failure-recovery/worker.ts

@@ -0,0 +1,46 @@
+import { createRuntime } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+import { RecoveryCounter } from "./actor.ts"
+
+const databasePath = requiredArgument(2)
+const runtime = createRuntime({
+  database: sqlite({ path: databasePath, timeoutMilliseconds: 2_000, lockRetryAttempts: 20 }),
+  pollingIntervalMilliseconds: 10,
+  leaseDurationMilliseconds: 250,
+  leaseRenewalIntervalMilliseconds: 50,
+  processHeartbeatIntervalMilliseconds: 75,
+  processAliveThresholdMilliseconds: 300,
+  workerCount: 1,
+  effectWorkerCount: 0,
+  reminderSchedulerCount: 0,
+  retentionIntervalMilliseconds: 0,
+  deadProcessCleanupIntervalMilliseconds: 0,
+  authorizeMessage: () => true,
+  authorizeQuery: () => true,
+  authorizeAdministration: () => true,
+  instrumentation: ({ name, attributes }) => {
+    process.send?.({ event: name, attributes })
+  },
+})
+
+runtime.register(RecoveryCounter)
+await runtime.install()
+const worker = runtime.worker()
+
+try {
+  let processed = 0
+  for (let attempt = 0; attempt < 200 && processed === 0; attempt += 1) {
+    processed = await worker.runOnce({ activationRetention: "release" })
+    if (processed === 0) await new Promise((resolve) => setTimeout(resolve, 10))
+  }
+  process.send?.({ event: "worker.finished", processed })
+} finally {
+  await worker.stop()
+  await runtime.close()
+}
+
+function requiredArgument(index: number): string {
+  const value = process.argv[index]
+  if (!value) throw new TypeError(`argument ${index - 1} is required`)
+  return value
+}

package/examples/sqlite-quickstart.ts

@@ -0,0 +1,109 @@
+import assert from "node:assert/strict"
+import { existsSync } from "node:fs"
+import { mkdtemp, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { Actor, createRuntime } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+
+class Counter extends Actor {
+  static override readonly actorType = "QuickstartCounter"
+
+  count = 0
+
+  increment(): number {
+    this.count += 1
+    return this.count
+  }
+
+  async pause({ milliseconds }: { milliseconds: number }): Promise<{
+    startedAt: number
+    finishedAt: number
+  }> {
+    const startedAt = performance.now()
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds))
+    return { startedAt, finishedAt: performance.now() }
+  }
+}
+
+export async function runQuickstart(
+  options: {
+    signal?: AbortSignal
+    write?: (value: string) => void
+  } = {},
+): Promise<void> {
+  const directory = await mkdtemp(join(tmpdir(), "solid-objects-quickstart-"))
+  const databasePath = join(directory, "state.sqlite3")
+  const runtime = createRuntime({
+    database: sqlite({ path: databasePath }),
+    workerCount: 2,
+    effectWorkerCount: 0,
+    reminderSchedulerCount: 0,
+    retentionIntervalMilliseconds: 0,
+    deadProcessCleanupIntervalMilliseconds: 0,
+    authorizeMessage: () => true,
+    authorizeQuery: () => true,
+  })
+  const shutdown = new AbortController()
+  const abort = () => shutdown.abort(options.signal?.reason)
+  options.signal?.addEventListener("abort", abort, { once: true })
+  let running: Promise<void> | undefined
+  let sameIdentityFinalState = 0
+  let independentIdentitiesOverlapped = false
+
+  try {
+    runtime.register(Counter)
+    await runtime.install()
+    running = runtime.run(shutdown.signal)
+
+    const counter = runtime.ref(Counter, "room-1")
+    const results = await Promise.all(Array.from({ length: 25 }, () => counter.increment()))
+    assert.deepEqual(
+      [...results].sort((left, right) => left - right),
+      Array.from({ length: 25 }, (_value, index) => index + 1),
+    )
+    sameIdentityFinalState = await counter.count
+    assert.equal(sameIdentityFinalState, 25)
+
+    const pauses = await Promise.all([
+      runtime.ref(Counter, "room-2").send.pause({ milliseconds: 100 }),
+      runtime.ref(Counter, "room-3").send.pause({ milliseconds: 100 }),
+    ])
+    const windows = await Promise.all(
+      pauses.map((message) => message.wait({ timeoutMilliseconds: 5_000 })),
+    )
+    const firstWindow = windows[0]
+    const secondWindow = windows[1]
+    if (!firstWindow || !secondWindow) throw new Error("two execution windows are required")
+    independentIdentitiesOverlapped =
+      firstWindow.startedAt < secondWindow.finishedAt &&
+      secondWindow.startedAt < firstWindow.finishedAt
+    assert.equal(independentIdentitiesOverlapped, true)
+  } finally {
+    shutdown.abort()
+    await running
+    await runtime.close()
+    options.signal?.removeEventListener("abort", abort)
+    await rm(directory, { recursive: true })
+  }
+
+  assert.equal(existsSync(directory), false)
+  const write = options.write ?? ((value: string) => process.stdout.write(value))
+  write(
+    `${JSON.stringify(
+      {
+        sameIdentityCalls: 25,
+        sameIdentityFinalState,
+        independentIdentitiesOverlapped,
+        temporaryStateRemoved: true,
+      },
+      null,
+      2,
+    )}\n`,
+  )
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  await runQuickstart()
+}

package/package.json

@@ -1,10 +1,23 @@
 {
   "name": "solid-objects",
-  "version": "0.12.1",
-  "description": "Durable, addressable objects for Node.js",
+  "version": "0.13.1",
+  "description": "Race-free realtime state per application identity, backed by your SQL database",
   "type": "module",
   "license": "MIT",
   "author": "Lucas Carlson",
+  "keywords": [
+    "concurrency",
+    "durable-state",
+    "mysql",
+    "nodejs",
+    "postgresql",
+    "realtime",
+    "sqlite",
+    "state-management",
+    "typescript",
+    "actors",
+    "durable-objects"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cardmagic/solid-objects-js.git"
@@ -19,6 +32,7 @@
   "files": [
     "dist",
     "docs",
+    "examples",
     "README.md",
     "CHANGELOG.md",
     "MIT-LICENSE"
@@ -47,11 +61,15 @@
     "./browser": {
       "types": "./dist/browser/index.d.ts",
       "import": "./dist/browser/index.js"
+    },
+    "./web": {
+      "types": "./dist/web/index.d.ts",
+      "import": "./dist/web/index.js"
     }
   },
   "scripts": {
-    "build": "pnpm run clean && tsc -p tsconfig.build.json && node scripts/prepare-executable.mjs",
-    "check": "pnpm run check:parameters && pnpm run check:documentation && tsc -p tsconfig.json --noEmit",
+    "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 && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.examples.json --noEmit",
     "check:documentation": "node scripts/check-documentation.mjs",
     "check:parameters": "node scripts/check-parameter-style.mjs",
     "clean": "node scripts/clean.mjs",
@@ -62,8 +80,12 @@
     "test:coverage": "vitest run --coverage",
     "test:postgresql": "vitest run test/postgresql.test.ts",
     "test:mysql": "vitest run test/mysql.test.ts",
+    "test:package": "node scripts/release-artifact-smoke.mjs",
+    "test:recovery": "pnpm run build && node examples/failure-recovery/demo.ts",
     "test:redis": "vitest run test/redis-wake-up.test.ts",
     "test:watch": "vitest",
+    "benchmark": "pnpm run build && node benchmarks/run.ts",
+    "benchmark:idle": "pnpm run build && node benchmarks/idle.ts",
     "pack:check": "pnpm pack --dry-run && node scripts/check-package.mjs",
     "prepack": "pnpm run build"
   },