@voyantjs/workflows-orchestrator-node 0.107.5 → 0.107.7

package/src/dashboard-sse.ts

@@ -0,0 +1,150 @@
+import type { ServerResponse } from "node:http"
+import type { ChunkBus, ChunkEvent } from "./dashboard-chunks.js"
+import type { SnapshotRunStore } from "./snapshot-run-store.js"
+import type { StoreEvent, StoreStream } from "./store-stream.js"
+
+function unrefTimer(timer: ReturnType<typeof setInterval>): void {
+  if (
+    typeof timer === "object" &&
+    timer !== null &&
+    "unref" in timer &&
+    typeof timer.unref === "function"
+  ) {
+    timer.unref()
+  }
+}
+
+export function handleSseStream(
+  res: ServerResponse,
+  stream: StoreStream,
+  chunkBus?: ChunkBus,
+): void {
+  res.writeHead(200, {
+    "content-type": "text/event-stream",
+    "cache-control": "no-store",
+    connection: "keep-alive",
+    "access-control-allow-origin": "*",
+  })
+  res.write("retry: 3000\n\n")
+
+  const writeEvent = (event: StoreEvent): void => {
+    try {
+      res.write(`event: ${event.kind}\ndata: ${JSON.stringify(event)}\n\n`)
+    } catch {
+      // Ignore write errors on closed sockets.
+    }
+  }
+
+  const writeChunk = (event: ChunkEvent): void => {
+    try {
+      res.write(`event: stream.chunk\ndata: ${JSON.stringify(event)}\n\n`)
+    } catch {
+      // Ignore write errors on closed sockets.
+    }
+  }
+
+  const unsubscribeStore = stream.subscribe(writeEvent)
+  const unsubscribeChunk = chunkBus ? chunkBus.subscribe(writeChunk) : () => {}
+  const ping = setInterval(() => {
+    try {
+      res.write(`: ping ${Date.now()}\n\n`)
+    } catch {
+      // Ignore write errors on closed sockets.
+    }
+  }, 25_000)
+  unrefTimer(ping)
+
+  res.on("close", () => {
+    clearInterval(ping)
+    unsubscribeStore()
+    unsubscribeChunk()
+  })
+}
+
+const TERMINAL_STATUSES = new Set([
+  "completed",
+  "failed",
+  "cancelled",
+  "compensated",
+  "compensation_failed",
+])
+
+export function handleRunSseStream(
+  res: ServerResponse,
+  runId: string,
+  stream: StoreStream,
+  chunkBus: ChunkBus | undefined,
+  store: SnapshotRunStore,
+): void {
+  res.writeHead(200, {
+    "content-type": "text/event-stream",
+    "cache-control": "no-store",
+    connection: "keep-alive",
+    "access-control-allow-origin": "*",
+  })
+  res.write("retry: 3000\n\n")
+
+  let closed = false
+  const close = (): void => {
+    if (closed) return
+    closed = true
+    try {
+      res.end()
+    } catch {
+      // Ignore close failures.
+    }
+  }
+
+  const writeEvent = (kind: string, data: unknown): void => {
+    if (closed) return
+    try {
+      res.write(`event: ${kind}\ndata: ${JSON.stringify(data)}\n\n`)
+    } catch {
+      // Ignore write errors on closed sockets.
+    }
+  }
+
+  void store.get(runId).then((run) => {
+    if (run) {
+      writeEvent("hello", { run })
+      if (TERMINAL_STATUSES.has(run.status)) close()
+    } else {
+      writeEvent("hello", { run: null })
+    }
+  })
+
+  const unsubscribeStore = stream.subscribe((event) => {
+    if (event.kind === "added" || event.kind === "updated") {
+      if (event.run.id !== runId) return
+      writeEvent(event.kind, event)
+      if (TERMINAL_STATUSES.has(event.run.status)) close()
+    } else if (event.kind === "removed") {
+      if (event.runId !== runId) return
+      writeEvent(event.kind, event)
+      close()
+    }
+  })
+
+  const unsubscribeChunk = chunkBus
+    ? chunkBus.subscribe((event) => {
+        if (event.runId !== runId) return
+        writeEvent("stream.chunk", event)
+      })
+    : () => {}
+
+  const ping = setInterval(() => {
+    try {
+      res.write(`: ping ${Date.now()}\n\n`)
+    } catch {
+      // Ignore write errors on closed sockets.
+    }
+  }, 25_000)
+  unrefTimer(ping)
+
+  res.on("close", () => {
+    closed = true
+    clearInterval(ping)
+    unsubscribeStore()
+    unsubscribeChunk()
+  })
+}

package/src/dashboard-static.ts

@@ -0,0 +1,88 @@
+import { readFile, stat } from "node:fs/promises"
+import { extname, join, resolve as resolvePath } from "node:path"
+
+export function createStaticReader(rootDir: string): (path: string) => Promise<Uint8Array | null> {
+  const root = resolvePath(rootDir)
+  return async (path: string) => {
+    const absolute = resolvePath(root, path)
+    if (!absolute.startsWith(`${root}/`) && absolute !== root) return null
+    try {
+      return await readFile(absolute)
+    } catch {
+      return null
+    }
+  }
+}
+
+export async function findDashboardDir(startFrom: string): Promise<string | undefined> {
+  const candidates = [
+    join(startFrom, "apps/workflows-local-dashboard/dist"),
+    join(startFrom, "../local-dashboard/dist"),
+    join(startFrom, "../../apps/workflows-local-dashboard/dist"),
+    join(startFrom, "../../../apps/workflows-local-dashboard/dist"),
+  ]
+  for (const candidate of candidates) {
+    try {
+      const entry = await stat(join(candidate, "index.html"))
+      if (entry.isFile()) return candidate
+    } catch {
+      // Continue scanning candidate locations.
+    }
+  }
+  return undefined
+}
+
+export async function assertReadableFile(path: string, label: string): Promise<void> {
+  let info: Awaited<ReturnType<typeof stat>>
+  try {
+    info = await stat(path)
+  } catch (err) {
+    throw new Error(`voyant workflows selfhost: ${label} not found at "${path}"`, { cause: err })
+  }
+  if (!info.isFile()) {
+    throw new Error(`voyant workflows selfhost: ${label} must be a file (got "${path}")`)
+  }
+}
+
+export async function assertReadableDirectory(path: string, label: string): Promise<void> {
+  let info: Awaited<ReturnType<typeof stat>>
+  try {
+    info = await stat(path)
+  } catch (err) {
+    throw new Error(`voyant workflows selfhost: ${label} not found at "${path}"`, { cause: err })
+  }
+  if (!info.isDirectory()) {
+    throw new Error(`voyant workflows selfhost: ${label} must be a directory (got "${path}")`)
+  }
+}
+
+export function mimeFor(path: string): string {
+  const ext = extname(path).toLowerCase()
+  switch (ext) {
+    case ".html":
+      return "text/html; charset=utf-8"
+    case ".js":
+    case ".mjs":
+      return "application/javascript; charset=utf-8"
+    case ".css":
+      return "text/css; charset=utf-8"
+    case ".json":
+      return "application/json; charset=utf-8"
+    case ".svg":
+      return "image/svg+xml"
+    case ".png":
+      return "image/png"
+    case ".map":
+      return "application/json"
+    default:
+      return "application/octet-stream"
+  }
+}
+
+export function urlPath(raw: string): string {
+  try {
+    return new URL(raw, "http://local").pathname
+  } catch {
+    return raw
+  }
+}

package/src/dashboard-types.ts

@@ -0,0 +1,106 @@
+import type { createServer } from "node:http"
+import type { ServiceResolver } from "@voyantjs/workflows/driver"
+import type { WaitpointInjection } from "@voyantjs/workflows-orchestrator"
+import type { ChunkBus } from "./dashboard-chunks.js"
+import type { SchedulerHandle } from "./scheduler.js"
+import type { ListFilter, SnapshotRunStore, StoredRun } from "./snapshot-run-store.js"
+
+export interface ServeDeps {
+  store: SnapshotRunStore
+  createServer: typeof createServer
+  shutdown?: () => void | Promise<void>
+  healthCheck?: () => Promise<HealthReport> | HealthReport
+  readinessCheck?: () => Promise<HealthReport> | HealthReport
+  collectMetrics?: () => Promise<string> | string
+  staticDir?: string
+  readStatic?: (path: string) => Promise<Uint8Array | null>
+  triggerRun?: (args: {
+    workflowId: string
+    input: unknown
+    runId?: string
+    tags?: string[]
+    triggeredByUserId?: string | null
+  }) => Promise<{ ok: true; saved: StoredRun } | { ok: false; message: string; exitCode: number }>
+  resumeRun?: (args: {
+    parentRunId: string
+    workflowId?: string
+    input?: unknown
+    resumeFromStep?: string
+    seedResults?: Record<string, unknown>
+    runId?: string
+    tags?: string[]
+    triggeredByUserId?: string | null
+  }) => Promise<
+    | { ok: true; saved: StoredRun; parentRunId: string; resumeFromStep: string }
+    | { ok: false; message: string; exitCode: number }
+  >
+  listWorkflows?: () => { id: string; description?: string }[]
+  injectWaitpoint?: (args: {
+    runId: string
+    injection: WaitpointInjection
+  }) => Promise<{ ok: true; saved: StoredRun } | { ok: false; message: string; exitCode: number }>
+  scheduler?: SchedulerHandle
+  listSchedules?: () => { workflowId: string; name?: string; nextAt: number; done: boolean }[]
+  cancelRun?: (args: {
+    runId: string
+  }) => Promise<{ ok: true; saved: StoredRun } | { ok: false; message: string; exitCode: number }>
+  chunkBus?: ChunkBus
+}
+
+export interface RequestHandlerDeps {
+  store: SnapshotRunStore
+  healthCheck?: ServeDeps["healthCheck"]
+  readinessCheck?: ServeDeps["readinessCheck"]
+  collectMetrics?: ServeDeps["collectMetrics"]
+  readStatic?: (path: string) => Promise<Uint8Array | null>
+  hasStaticDashboard?: boolean
+  triggerRun?: ServeDeps["triggerRun"]
+  resumeRun?: ServeDeps["resumeRun"]
+  listWorkflows?: ServeDeps["listWorkflows"]
+  injectWaitpoint?: ServeDeps["injectWaitpoint"]
+  listSchedules?: ServeDeps["listSchedules"]
+  cancelRun?: ServeDeps["cancelRun"]
+}
+
+export interface HandlerResponse {
+  status: number
+  headers: Record<string, string>
+  body: string | Uint8Array
+}
+
+export interface HealthReport {
+  ok: boolean
+  service?: string
+  checks?: Record<string, "ok" | "error">
+  details?: Record<string, unknown>
+}
+
+export interface MetricsSnapshot {
+  workflowsRegistered: number
+  schedulesRegistered: number
+  runsTotal: number
+  wakeupsTotal: number
+  runsByStatus: Record<string, number>
+  generatedAtMs: number
+}
+
+export interface ServeHandle {
+  close: () => Promise<void>
+  url: string
+}
+
+export interface NodeSelfHostServerOptions {
+  entryFile: string
+  port?: number
+  host?: string
+  staticDir?: string
+  cacheBustEntry?: boolean
+  services?: ServiceResolver
+  store?: SnapshotRunStore
+  databaseUrl?: string
+  wakeupPollIntervalMs?: number
+  wakeupLeaseMs?: number
+  wakeupLeaseOwner?: string
+}
+
+export type DashboardListFilter = ListFilter

package/src/node-selfhost-defaults.ts

@@ -0,0 +1,9 @@
+export const localTenantMeta = {
+  tenantId: "tnt_local",
+  projectId: "prj_local",
+  organizationId: "org_local",
+}
+
+export function createDefaultWakeupLeaseOwner(): string {
+  return `node-selfhost-${process.pid}-${Math.random().toString(36).slice(2, 8)}`
+}