@highstate/backend 0.9.15 → 0.9.18

package/src/common/test/tracer.ts

@@ -0,0 +1,359 @@
+import { PassThrough } from "stream"
+import { basename } from "node:path"
+import pino, { levels } from "pino"
+import { test as baseTest, type RunnerTask } from "vitest"
+import { isPromise, omit } from "remeda"
+import * as md from "ts-markdown-builder"
+import { ReproducibleClockProvider, type ClockProvider } from "../clock"
+import { ReproducibleRandomProvider, type RandomProvider } from "../random"
+import { renderTraceEntry } from "./render"
+
+export interface TraceEntry {
+  readonly id: number
+  title?: string
+  render(): string
+}
+
+export function linkTraceEntry(entry: TraceEntry): string {
+  const anchorId = `#trace-${entry.id}`
+
+  if (entry.title) {
+    return md.link(anchorId, `${entry.id}. ${entry.title}`)
+  }
+
+  return md.link(anchorId, entry.id.toString())
+}
+
+export type TestPhase = "arrange" | "act" | "assert"
+
+class CallTraceEntry implements TraceEntry {
+  resolvedEntry?: TraceEntry
+  result?: unknown
+  error?: unknown
+
+  constructor(
+    readonly id: number,
+    private readonly serviceName: string,
+    private readonly methodName: string,
+    private readonly args: unknown[],
+    result?: unknown,
+    error?: unknown,
+  ) {
+    this.result = result
+    this.error = error
+  }
+
+  get title(): string {
+    return `${this.serviceName}.${this.methodName}`
+  }
+
+  render(): string {
+    if (this.resolvedEntry) {
+      // deferred completion - show promise link with ➡️
+      return renderTraceEntry({
+        icon: "➡️",
+        title: this.title,
+        fields: {
+          args: {
+            value: this.args,
+            alwaysRender: true,
+          },
+          result: {
+            value: `${md.code("Promise")}, resolved at ${linkTraceEntry(this.resolvedEntry)}`,
+            raw: true,
+          },
+        },
+      })
+    }
+
+    return renderTraceEntry({
+      icon: "✅",
+      title: this.title,
+      fields: {
+        args: {
+          value: this.args,
+          alwaysRender: true,
+        },
+        result: {
+          value: this.result,
+        },
+        error: {
+          value: this.error,
+        },
+      },
+    })
+  }
+}
+
+class CallResultEntry implements TraceEntry {
+  constructor(
+    readonly id: number,
+    private readonly callEntry: TraceEntry,
+    private readonly result?: unknown,
+    private readonly error?: unknown,
+  ) {}
+
+  render(): string {
+    return renderTraceEntry({
+      icon: "↩️",
+      title: linkTraceEntry(this.callEntry),
+      fields: {
+        result: {
+          value: this.result,
+        },
+        error: {
+          value: this.error,
+        },
+      },
+    })
+  }
+}
+
+const logLevelIcons: Record<string, string> = {
+  error: "❌",
+  warn: "⚠️",
+  info: "ℹ️",
+  debug: "🔍",
+  trace: "🔬",
+}
+
+class LogTraceEntry implements TraceEntry {
+  constructor(
+    readonly id: number,
+    private readonly level: string,
+    private readonly message: string,
+    private readonly data?: Record<string, unknown>,
+    private readonly error?: unknown,
+  ) {}
+
+  render(): string {
+    return renderTraceEntry({
+      icon: logLevelIcons[this.level] ?? "ℹ️",
+      title: this.level,
+      code: this.message,
+      fields: {
+        data: {
+          value: this.data,
+        },
+        error: {
+          value: this.error,
+        },
+      },
+    })
+  }
+}
+
+export class TestTracer {
+  private readonly traces: Record<TestPhase, TraceEntry[]> = {
+    arrange: [],
+    act: [],
+    assert: [],
+  }
+
+  private _entryCount = 0
+  private _currentPhase: TestPhase = "arrange"
+
+  setPhase(phase: TestPhase) {
+    this._currentPhase = phase
+  }
+
+  readonly logger = pino({ level: "debug" }, this.createLogStream())
+
+  createServiceMock<TService extends object>(name: string, impl: Partial<TService> = {}): TService {
+    return new Proxy(impl as TService, {
+      get: (target, prop) => {
+        // we assume that all get calls via the proxy are method calls
+
+        return this.createServiceMethodMock(
+          name,
+          prop as string,
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+          target[prop as keyof TService] as Function,
+        )
+      },
+    })
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  private createServiceMethodMock(serviceName: string, name: string, base: Function = () => {}) {
+    return new Proxy(base, {
+      apply: (target, thisArg, args) => {
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+          const result = target.apply(thisArg, args)
+
+          if (!isPromise(result)) {
+            // record synchronous call
+            this.addEntry(new CallTraceEntry(this.nextEntryId(), serviceName, name, args, result))
+
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            return result
+          }
+
+          // create async call trace entry
+          const callEntry = new CallTraceEntry(this.nextEntryId(), serviceName, name, args)
+          this.addEntry(callEntry)
+
+          // wrap the promise to track resolution
+          const wrappedPromise = (result as Promise<unknown>).then(
+            (resolvedValue: unknown) => {
+              if (this.nextEntryId() === callEntry.id + 1) {
+                // immediate completion (no other traces added in between)
+
+                callEntry.result = resolvedValue
+                return resolvedValue
+              }
+
+              // deferred completion - create a separate result entry
+              const resultEntry = new CallResultEntry(this.nextEntryId(), callEntry, resolvedValue)
+
+              this.addEntry(resultEntry)
+              callEntry.resolvedEntry = resultEntry
+
+              return resolvedValue
+            },
+            (rejectedError: unknown) => {
+              if (this.nextEntryId() === callEntry.id + 1) {
+                // immediate error (no other traces added in between)
+
+                callEntry.error = rejectedError
+                throw rejectedError
+              }
+
+              // deferred error - create a separate result entry
+              const resultEntry = new CallResultEntry(
+                this.nextEntryId(),
+                callEntry,
+                undefined,
+                rejectedError,
+              )
+
+              this.addEntry(resultEntry)
+              callEntry.resolvedEntry = resultEntry
+
+              throw rejectedError
+            },
+          )
+
+          return wrappedPromise
+        } catch (error) {
+          // record synchronous error
+          const callEntry = new CallTraceEntry(
+            this.nextEntryId(),
+            serviceName,
+            name,
+            args,
+            undefined,
+            error,
+          )
+
+          this.addEntry(callEntry)
+        }
+      },
+    })
+  }
+
+  nextEntryId(): number {
+    return this._entryCount + 1
+  }
+
+  addEntry(entry: TraceEntry) {
+    this._entryCount += 1
+    this.traces[this._currentPhase].push(entry)
+  }
+
+  private createLogStream() {
+    const stream = new PassThrough()
+
+    stream.on("data", data => {
+      const { level, msg, error, ...other } = JSON.parse(String(data)) as {
+        msg: string
+        level: number
+        error?: string
+      }
+
+      const levelLabel = levels.labels[level]
+      const logEntry = new LogTraceEntry(
+        this.nextEntryId(),
+        levelLabel,
+        msg,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        omit(other as any, ["time", "pid", "hostname"]),
+        error,
+      )
+
+      this.addEntry(logEntry)
+    })
+
+    return stream
+  }
+
+  render(): string {
+    const blocks = Object.entries(this.traces).flatMap(([phase, traces]) => {
+      if (traces.length === 0) {
+        return []
+      }
+
+      return [
+        `## ${phase}\n`,
+        ...traces.map(trace => {
+          const anchorId = `trace-${trace.id}`
+
+          return `### <a id="${anchorId}"></a> ${trace.id}. ${trace.render()}`
+        }),
+      ]
+    })
+
+    return md.joinBlocks(blocks)
+  }
+}
+
+export type TestBaseFixtures = {
+  tracer: TestTracer
+  clock: ClockProvider
+  random: RandomProvider
+}
+
+function camelCaseToKebabCase(str: string): string {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase()
+}
+
+function getFullName(test: RunnerTask): string {
+  let result = camelCaseToKebabCase(test.name)
+
+  while (test.suite) {
+    test = test.suite
+    result = `${camelCaseToKebabCase(test.name)}/${result}`
+  }
+
+  return result.replaceAll(" ", "-")
+}
+
+export const test = baseTest.extend<TestBaseFixtures>({
+  tracer: async ({ task, expect }, use) => {
+    const tracer = new TestTracer()
+
+    await use(tracer)
+
+    const fileName = basename(task.file.name).replace(/\.test\.ts$/, "")
+    const taskName = getFullName(task)
+    const rendered = tracer.render()
+
+    await expect(rendered).toMatchFileSnapshot(`./__traces__/${fileName}/${taskName}.md`)
+  },
+
+  random: async ({ task }, use) => {
+    const random = new ReproducibleRandomProvider(Buffer.from(task.id))
+
+    await use(random)
+  },
+
+  // eslint-disable-next-line no-empty-pattern
+  clock: async ({}, use) => {
+    const clock = new ReproducibleClockProvider()
+
+    await use(clock)
+  },
+})
+
+export const testBase = test

package/src/common/tree.ts

@@ -0,0 +1,33 @@
+export type TreeNode = {
+  text: string
+  children: TreeNode[]
+}
+
+/**
+ * Renders a tree structure similar to the Linux tree command output.
+ * Uses box-drawing characters to create visual hierarchy.
+ */
+export function renderTree(node: TreeNode): string {
+  const lines: string[] = []
+
+  function renderNode(node: TreeNode, prefix: string = "", isLast: boolean = true): void {
+    // Add current node
+    lines.push(prefix + (isLast ? "└── " : "├── ") + node.text)
+
+    // Add children
+    const childPrefix = prefix + (isLast ? "    " : "│   ")
+    node.children.forEach((child, index) => {
+      const isLastChild = index === node.children.length - 1
+      renderNode(child, childPrefix, isLastChild)
+    })
+  }
+
+  // Start with root node (no prefix)
+  lines.push(node.text)
+  node.children.forEach((child, index) => {
+    const isLastChild = index === node.children.length - 1
+    renderNode(child, "", isLastChild)
+  })
+
+  return lines.join("\n")
+}

package/src/common/utils.ts

@@ -34,13 +34,25 @@ export function isAbortError(error: unknown): boolean {
   return error instanceof Error && error.name === "AbortError"
 }
 
-const abortMessagePatterns = ["Operation aborted", "Command was killed with SIGINT"]
+const abortMessagePatterns = [
+  "Operation aborted",
+  "This operation was aborted",
+  "Command was killed with SIGINT",
+]
 
 export function isAbortErrorLike(error: unknown): boolean {
+  if (isAbortError(error)) {
+    return true
+  }
+
   if (error instanceof Error) {
     return abortMessagePatterns.some(pattern => error.message.includes(pattern))
   }
 
+  if (typeof error === "string") {
+    return abortMessagePatterns.some(pattern => error.includes(pattern))
+  }
+
   return false
 }
 
@@ -61,3 +73,30 @@ export function errorToString(error: unknown): string {
 
   return JSON.stringify(error)
 }
+
+export function valueToString(value: unknown): string {
+  if (typeof value === "string") {
+    return value
+  }
+
+  return JSON.stringify(value)
+}
+
+export function stringToValue(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return value
+  }
+}
+
+export function waitForAbort(signal: AbortSignal): Promise<void> {
+  return new Promise(resolve => {
+    if (signal.aborted) {
+      resolve()
+      return
+    }
+
+    signal.addEventListener("abort", () => resolve(), { once: true })
+  })
+}

package/src/config.ts

@@ -1,28 +1,32 @@
 import { z } from "zod"
 import { libraryBackendConfig } from "./library"
 import { projectBackendConfig } from "./project"
-import { secretBackendConfig } from "./secret"
 import { terminalBackendConfig } from "./terminal"
 import { runnerBackendConfig } from "./runner"
-import { stateBackendConfig } from "./state"
-import { workspaceBackendConfig } from "./workspace"
+import { stateBackendConfig, stateManagerConfig } from "./state"
+import { artifactBackendConfig } from "./artifact"
+import { pubSubBackendConfig } from "./pubsub"
+import { lockBackendConfig } from "./lock"
+import { hotStateBackendConfig } from "./hotstate"
+import { workerBackendConfig, workerManagerConfig } from "./worker"
 
 const loggerConfig = z.object({
-  HIGHSTATE_BACKEND_LOGGER_NAME: z.string().default("highstate-backend"),
-
-  HIGHSTATE_BACKEND_LOGGER_LEVEL: z
-    .enum(["fatal", "error", "warn", "info", "debug", "trace"])
-    .default("info"),
+  HIGHSTATE_LOG_LEVEL: z.enum(["fatal", "error", "warn", "info", "debug", "trace"]).default("info"),
 })
 
 const configSchema = z.object({
+  ...hotStateBackendConfig.shape,
+  ...pubSubBackendConfig.shape,
+  ...lockBackendConfig.shape,
   ...libraryBackendConfig.shape,
   ...projectBackendConfig.shape,
-  ...secretBackendConfig.shape,
   ...stateBackendConfig.shape,
+  ...stateManagerConfig.shape,
   ...runnerBackendConfig.shape,
   ...terminalBackendConfig.shape,
-  ...workspaceBackendConfig.shape,
+  ...workerBackendConfig.shape,
+  ...workerManagerConfig.shape,
+  ...artifactBackendConfig.shape,
   ...loggerConfig.shape,
 })
 
@@ -36,5 +40,9 @@ export async function loadConfig(
     await import("dotenv/config")
   }
 
-  return configSchema.parse(env)
+  try {
+    return configSchema.parse(env)
+  } catch (error) {
+    throw new Error("Failed to parse backend configuration", { cause: error })
+  }
 }

package/src/hotstate/abstractions.ts

@@ -0,0 +1,48 @@
+import type { z } from "zod"
+
+export interface HotStateBackend {
+  /**
+   * Gets a value for a key.
+   */
+  get(key: string, schema: z.ZodType): Promise<unknown>
+
+  /**
+   * Checks if a key exists.
+   */
+  exists(key: string): Promise<boolean>
+
+  /**
+   * Sets a value for a key.
+   */
+  set(key: string, schema: z.ZodType, value: unknown): Promise<void>
+
+  /**
+   * Deletes a key.
+   */
+  delete(key: string): Promise<void>
+
+  /**
+   * Gets all key-value pairs from a hash set.
+   */
+  hgetall(key: string, schema: z.ZodType): Promise<Array<[string, unknown]>>
+
+  /**
+   * Checks if a field exists in a hash set.
+   */
+  hexists(key: string, field: string): Promise<boolean>
+
+  /**
+   * Sets a field in a hash set.
+   */
+  hset(key: string, field: string, schema: z.ZodType, value: unknown): Promise<void>
+
+  /**
+   * Gets a field from a hash set.
+   */
+  hget(key: string, field: string, schema: z.ZodType): Promise<unknown>
+
+  /**
+   * Deletes a field from a hash set.
+   */
+  hdel(key: string, field: string): Promise<void>
+}

package/src/hotstate/factory.ts

@@ -0,0 +1,17 @@
+import type { HotStateBackend } from "./abstractions"
+import { z } from "zod"
+import { MemoryHotStateBackend } from "./memory"
+
+export const hotStateBackendConfig = z.object({
+  HIGHSTATE_HOTSTATE_BACKEND_TYPE: z.enum(["memory"]).default("memory"),
+})
+
+export function createHotStateBackend(
+  config: z.infer<typeof hotStateBackendConfig>,
+): HotStateBackend {
+  switch (config.HIGHSTATE_HOTSTATE_BACKEND_TYPE) {
+    case "memory": {
+      return MemoryHotStateBackend.create()
+    }
+  }
+}

package/src/{secret → hotstate}/index.ts

@@ -1,2 +1,3 @@
 export * from "./abstractions"
 export * from "./factory"
+export * from "./manager"