@highstate/backend 0.7.2 → 0.7.3

package/src/state/local.ts

@@ -0,0 +1,605 @@
+import type { ClassicLevel } from "classic-level"
+import type { AbstractSublevel, AbstractValueIteratorOptions } from "abstract-level"
+import type { Logger } from "pino"
+import { resolve } from "node:path"
+import { z } from "zod"
+import { uuidv7 } from "uuidv7"
+import {
+  type ProjectOperation,
+  type InstanceState,
+  projectOperationSchema,
+  instanceStateSchema,
+  isFinalOperationStatus,
+  type TerminalSession,
+  terminalSessionSchema,
+  compositeInstanceSchema,
+  type CompositeInstance,
+} from "../shared"
+import { LocalPulumiHost } from "../common"
+import { type LogEntry, type StateBackend, type TerminalHistoryEntry } from "./abstractions"
+
+export const localStateBackendConfig = z.object({
+  HIGHSTATE_BACKEND_STATE_LOCAL_DIR: z.string().optional(),
+})
+
+type Sublevel<TValue = unknown> = AbstractSublevel<
+  ClassicLevel<string, unknown>,
+  string | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>,
+  string,
+  TValue
+>
+
+/**
+ * A state backend that stores the state in a local LevelDB database.
+ *
+ * It uses the following structure:
+ *
+ * - `activeOperations/{operationId}` - all active operations, denormalized from `projects/{projectId}/operations`;
+ * - `activeTerminalSessionIds` - the IDs of the active terminal sessions;
+ *
+ * - `projects/{projectId}/operations/{operationId}` - the operations of the project;
+ * - `projects/{projectId}/instanceStates/{instanceId}` - the latest states of the instances of the project;
+ * - `projects/{projectId}/compositeInstances/{instanceId}` - all evaluated composite instances of the project;
+ * - `projects/{projectId}/compositeInstanceInputHashes/{instanceId}` - the input hashes of the composite instances, can be fetched independently;
+ * - `projects/{projectId}/topLevelCompositeChildrenIds/{instanceId}` - the IDs of the composite children of the top-level composite instance;
+ * - `projects/{projectId}/instances/{instanceId}/terminalSessions/{sessionId}` - the terminal sessions of the instances;
+ *
+ * - `operations/{operationId}/instanceStates/{instanceID}` - the states of the instances affected by the operation (at the moment of the operation completion);
+ * - `operations/{operationId}/instances/{instanceID}/logs/{logId}` - the logs of the instances affected by the operation, logId is a UUIDv7;
+ *
+ * - `terminalSessions/{sessionId}/history/{lineId}` - the history lines of the terminal session, lineId is a UUIDv7;
+ */
+export class LocalStateBackend implements StateBackend {
+  constructor(
+    private readonly db: ClassicLevel<string, unknown>,
+    private readonly logger: Logger,
+  ) {
+    this.logger.debug({ msg: "initialized", dbLocation: db.location })
+  }
+
+  async getActiveOperations(): Promise<ProjectOperation[]> {
+    const sublevel = this.getActiveOperationsSublevel()
+
+    return this.getAllSublevelItems(sublevel, projectOperationSchema)
+  }
+
+  async getOperations(projectId: string, beforeOperationId?: string): Promise<ProjectOperation[]> {
+    const sublevel = this.getProjectOperationsSublevel(projectId)
+    const pageSize = 10
+
+    return await this.getAllSublevelItems(sublevel, projectOperationSchema, pageSize, {
+      lt: beforeOperationId,
+      reverse: true,
+    })
+  }
+
+  async getAllInstanceStates(projectId: string): Promise<InstanceState[]> {
+    const sublevel = this.getProjectInstanceStatesSublevel(projectId)
+
+    return await this.getAllSublevelItems(sublevel, instanceStateSchema)
+  }
+
+  async getInstanceState(projectId: string, instanceID: string): Promise<InstanceState | null> {
+    const sublevel = this.getProjectInstanceStatesSublevel(projectId)
+
+    return await this.getSublevelItem(sublevel, instanceStateSchema, instanceID)
+  }
+
+  async getInstanceStates(projectId: string, instanceIds: string[]): Promise<InstanceState[]> {
+    const sublevel = this.getProjectInstanceStatesSublevel(projectId)
+
+    return await this.getSublevelItems(sublevel, instanceStateSchema, instanceIds)
+  }
+
+  async getAffectedInstanceStates(operationId: string): Promise<InstanceState[]> {
+    const sublevel = this.getOperationInstanceStatesSublevel(operationId)
+
+    return await this.getAllSublevelItems(sublevel, instanceStateSchema)
+  }
+
+  async getInstanceLogs(operationId: string, instanceId: string): Promise<string[]> {
+    const sublevel = this.getOperationInstanceLogsSublevel(operationId, instanceId)
+
+    return await Array.fromAsync(sublevel.values())
+  }
+
+  async putOperation(operation: ProjectOperation): Promise<void> {
+    this.validateItem(projectOperationSchema, operation)
+
+    const operationsSublevel = this.getProjectOperationsSublevel(operation.projectId)
+    const activeOperationsSublevel = this.getActiveOperationsSublevel()
+
+    if (!isFinalOperationStatus(operation.status)) {
+      // if the operation is not completed or failed, it is active,
+      // so we put it to the active operations sublevel as well
+      await this.db.batch([
+        { type: "put", key: operation.id, value: operation, sublevel: operationsSublevel },
+        { type: "put", key: operation.id, value: operation, sublevel: activeOperationsSublevel },
+      ])
+    } else {
+      // otherwise, we put it only to the operations sublevel
+      // and ensure it is not in the active operations
+      await this.db.batch([
+        { type: "put", key: operation.id, value: operation, sublevel: operationsSublevel },
+        { type: "del", key: operation.id, sublevel: activeOperationsSublevel },
+      ])
+    }
+  }
+
+  async putAffectedInstanceStates(
+    projectId: string,
+    operationId: string,
+    states: InstanceState[],
+  ): Promise<void> {
+    this.validateArray(instanceStateSchema, states)
+
+    const operationInstanceStatesSublevel = this.getOperationInstanceStatesSublevel(operationId)
+    const projectInstanceStatesSublevel = this.getProjectInstanceStatesSublevel(projectId)
+
+    await this.db.batch(
+      // put the states to both the operation and project sublevels
+      // denormalization is cool
+      // this separation is also necessary because the instance states can be updated without operations
+      states.flatMap(state => [
+        {
+          // always put the state to the operation sublevel for history
+          type: "put",
+          key: state.id,
+          value: state,
+          sublevel: operationInstanceStatesSublevel,
+        },
+        {
+          type: state.status === "not_created" ? "del" : "put",
+          key: state.id,
+          value: state,
+          sublevel: projectInstanceStatesSublevel,
+        },
+      ]),
+    )
+  }
+
+  async putInstanceStates(projectId: string, states: InstanceState[]): Promise<void> {
+    this.validateArray(instanceStateSchema, states)
+
+    const sublevel = this.getProjectInstanceStatesSublevel(projectId)
+
+    await sublevel.batch(
+      // as i told before, we update the instance states without operations
+      // this method is used when upstream instance state changes are detected
+      states.map(state => ({
+        type: state.status === "not_created" ? "del" : "put",
+        key: state.id,
+        value: state,
+      })),
+    )
+  }
+
+  async appendInstanceLogs(operationId: string, logs: LogEntry[]): Promise<void> {
+    const sublevels = new Map<string, Sublevel<string>>()
+    for (const [instanceId] of logs) {
+      if (sublevels.has(instanceId)) {
+        continue
+      }
+
+      const sublevel = this.getOperationInstanceLogsSublevel(operationId, instanceId)
+      sublevels.set(instanceId, sublevel)
+    }
+
+    await this.db.batch(
+      logs.map(([instanceID, line]) => ({
+        type: "put",
+        key: uuidv7(),
+        value: line,
+        sublevel: sublevels.get(instanceID)!,
+      })),
+    )
+  }
+
+  async getCompositeInstances(
+    projectId: string,
+    signal?: AbortSignal,
+  ): Promise<CompositeInstance[]> {
+    const sublevel = this.getProjectCompositeInstancesSublevel(projectId)
+
+    return await this.getAllSublevelItems(
+      //
+      sublevel,
+      compositeInstanceSchema,
+      undefined,
+      { signal },
+    )
+  }
+
+  async getCompositeInstance(
+    projectId: string,
+    instanceId: string,
+  ): Promise<CompositeInstance | null> {
+    const sublevel = this.getProjectCompositeInstancesSublevel(projectId)
+
+    return this.getSublevelItem(sublevel, compositeInstanceSchema, instanceId)
+  }
+
+  async getCompositeInstanceInputHash(
+    projectId: string,
+    instanceId: string,
+  ): Promise<string | null> {
+    const sublevel = this.getProjectCompositeInstanceInputHashesSublevel(projectId)
+    const inputHash = await sublevel.get(instanceId)
+
+    return inputHash ?? null
+  }
+
+  async putCompositeInstances(projectId: string, instances: CompositeInstance[]): Promise<void> {
+    this.validateArray(compositeInstanceSchema, instances)
+
+    const sublevel = this.getProjectCompositeInstancesSublevel(projectId)
+    const inputHashesSublevel = this.getProjectCompositeInstanceInputHashesSublevel(projectId)
+
+    await this.db.batch(
+      instances.flatMap(instance => [
+        {
+          type: "put",
+          key: instance.instance.id,
+          value: compositeInstanceSchema.parse(instance),
+          sublevel: sublevel,
+        },
+      ]),
+    )
+  }
+
+  async clearCompositeInstances(projectId: string, instanceIds: string[]): Promise<void> {
+    const sublevel = this.getProjectCompositeInstancesSublevel(projectId)
+    const inputHashesSublevel = this.getProjectCompositeInstanceInputHashesSublevel(projectId)
+
+    await this.db.batch(
+      instanceIds.flatMap(instanceId => [
+        { type: "del", key: instanceId, sublevel },
+        { type: "del", key: instanceId, sublevel: inputHashesSublevel },
+      ]),
+    )
+  }
+
+  async getTopLevelCompositeChildrenIds(
+    projectId: string,
+    instanceIds: string[],
+  ): Promise<Record<string, string[]>> {
+    const sublevel = this.getProjectCompositeChildrenIdsSublevel(projectId)
+    const items = await sublevel.getMany(instanceIds)
+    const schema = z.array(z.string()).optional()
+
+    const result: Record<string, string[]> = {}
+    for (let i = 0; i < items.length; i++) {
+      const instanceId = instanceIds[i]
+      const childrenIds = schema.parse(items[i])
+
+      result[instanceId] = childrenIds ?? []
+    }
+
+    return result
+  }
+
+  async putTopLevelCompositeChildrenIds(
+    projectId: string,
+    childrenIds: Record<string, string[]>,
+  ): Promise<void> {
+    const sublevel = this.getProjectCompositeChildrenIdsSublevel(projectId)
+    const schema = z.array(z.string()).optional()
+
+    await sublevel.batch(
+      Object.entries(childrenIds).map(([instanceId, ids]) => ({
+        type: "put",
+        key: instanceId,
+        value: schema.parse(ids),
+      })),
+    )
+  }
+
+  async getActiveTerminalSessions(): Promise<TerminalSession[]> {
+    const data = await this.db.get("activeTerminalSessionIds", { valueEncoding: "json" })
+
+    return data ? z.array(terminalSessionSchema).parse(data) : []
+  }
+
+  putActiveTerminalSessions(sessions: TerminalSession[]): Promise<void> {
+    this.validateArray(terminalSessionSchema, sessions)
+
+    return this.db.put("activeTerminalSessionIds", sessions, { valueEncoding: "json" })
+  }
+
+  async getTerminalSession(
+    projectId: string,
+    instanceId: string,
+    sessionId: string,
+  ): Promise<TerminalSession | null> {
+    const sublevel = this.getTerminalSessionsSublevel(projectId, instanceId)
+
+    return await this.getSublevelItem(sublevel, terminalSessionSchema, sessionId)
+  }
+
+  async getTerminalSessions(projectId: string, instanceId: string): Promise<TerminalSession[]> {
+    const sublevel = this.getTerminalSessionsSublevel(projectId, instanceId)
+
+    return await this.getAllSublevelItems(sublevel, terminalSessionSchema)
+  }
+
+  async getLastTerminalSession(
+    projectId: string,
+    instanceId: string,
+    sessionId: string,
+  ): Promise<TerminalSession | null> {
+    const sublevel = this.getTerminalSessionsSublevel(projectId, instanceId)
+
+    return await this.getSublevelItem(sublevel, terminalSessionSchema, sessionId)
+  }
+
+  async putTerminalSession(
+    projectId: string,
+    instanceId: string,
+    session: TerminalSession,
+  ): Promise<void> {
+    this.validateItem(terminalSessionSchema, session)
+
+    const sublevel = this.getTerminalSessionsSublevel(projectId, instanceId)
+    await sublevel.put(session.id, session)
+  }
+
+  async getTerminalSessionHistory(sessionId: string): Promise<string[]> {
+    const sublevel = this.getTerminalSessionHistorySublevel(sessionId)
+
+    return await Array.fromAsync(sublevel.values())
+  }
+
+  async appendTerminalSessionHistory(lines: TerminalHistoryEntry[]): Promise<void> {
+    const sublevels = new Map<string, Sublevel<string>>()
+    for (const [sessionId] of lines) {
+      if (sublevels.has(sessionId)) {
+        continue
+      }
+
+      const sublevel = this.getTerminalSessionHistorySublevel(sessionId)
+      sublevels.set(sessionId, sublevel)
+    }
+
+    await this.db.batch(
+      lines.map(([sessionId, line]) => ({
+        type: "put",
+        key: uuidv7(),
+        value: line,
+        sublevel: sublevels.get(sessionId)!,
+      })),
+    )
+  }
+
+  private async getAllSublevelItems<TSchema extends z.ZodType>(
+    sublevel: Sublevel,
+    schema: TSchema,
+    limit?: number,
+    options?: AbstractValueIteratorOptions<string, unknown>,
+  ): Promise<z.infer<TSchema>[]> {
+    const result: z.infer<TSchema>[] = []
+    const iterator = options ? sublevel.iterator(options) : sublevel.iterator()
+    const invalidKeys: string[] = []
+
+    for await (const [key, value] of iterator) {
+      const parseResult = schema.safeParse(value)
+
+      if (!parseResult.success) {
+        this.logger.warn({
+          msg: "failed to parse item, it will be deleted",
+          error: parseResult.error,
+          sublevel: sublevel.prefix,
+          key,
+        })
+
+        invalidKeys.push(key)
+        continue
+      }
+
+      result.push(parseResult.data as z.infer<TSchema>)
+      if (limit && result.length >= limit) {
+        break
+      }
+    }
+
+    if (invalidKeys.length > 0) {
+      this.logger.info({
+        msg: "deleting invalid items",
+        sublevel: sublevel.prefix,
+        keyCount: invalidKeys.length,
+      })
+
+      await sublevel.batch(invalidKeys.map(key => ({ type: "del", key })))
+    }
+
+    return result
+  }
+
+  private async getSublevelItem<TSchema extends z.ZodType>(
+    sublevel: Sublevel,
+    schema: TSchema,
+    key: string,
+  ): Promise<z.infer<TSchema> | null> {
+    const value = await sublevel.get(key)
+
+    if (!value) {
+      return null
+    }
+
+    const parseResult = schema.safeParse(value)
+
+    if (!parseResult.success) {
+      this.logger.warn({
+        msg: "failed to parse item, it will be deleted",
+        error: parseResult.error,
+        sublevel: sublevel.prefix,
+        key,
+      })
+
+      await sublevel.del(key)
+      return null
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return parseResult.data as z.infer<TSchema>
+  }
+
+  private async getSublevelItems<TSchema extends z.ZodType>(
+    sublevel: Sublevel,
+    schema: TSchema,
+    keys: string[],
+  ): Promise<z.infer<TSchema>[]> {
+    const result: z.infer<TSchema>[] = []
+    const invalidKeys: string[] = []
+
+    for (const key of keys) {
+      const value = await sublevel.get(key)
+
+      if (!value) {
+        continue
+      }
+
+      const parseResult = schema.safeParse(value)
+
+      if (!parseResult.success) {
+        this.logger.warn({
+          msg: "failed to parse item, it will be deleted",
+          error: parseResult.error,
+          sublevel: sublevel.prefix,
+          key,
+        })
+
+        invalidKeys.push(key)
+        continue
+      }
+
+      result.push(parseResult.data as z.infer<TSchema>)
+    }
+
+    if (invalidKeys.length > 0) {
+      this.logger.info({
+        msg: "deleting invalid items",
+        sublevel: sublevel.prefix,
+        keyCount: invalidKeys.length,
+      })
+
+      await sublevel.batch(invalidKeys.map(key => ({ type: "del", key })))
+    }
+
+    return result
+  }
+
+  private validateItem<TSchema extends z.ZodType>(schema: TSchema, item: z.infer<TSchema>): void {
+    const parseResult = schema.safeParse(item)
+
+    if (!parseResult.success) {
+      this.logger.error({
+        msg: "failed to validate item",
+        error: parseResult.error,
+        item,
+      })
+
+      throw new Error(`Failed to validate item: ${parseResult.error.errors[0].message}`, {
+        cause: parseResult.error,
+      })
+    }
+  }
+
+  private validateArray<TSchema extends z.ZodType>(
+    schema: TSchema,
+    items: z.infer<TSchema>[],
+  ): void {
+    for (const item of items) {
+      this.validateItem(schema, item)
+    }
+  }
+
+  private getActiveOperationsSublevel(): Sublevel {
+    return this.getJsonSublevel("activeOperations")
+  }
+
+  private getProjectOperationsSublevel(projectId: string): Sublevel {
+    return this.getJsonSublevel(`projects/${projectId}/operations`)
+  }
+
+  private getProjectCompositeInstancesSublevel(projectId: string): Sublevel {
+    return this.getJsonSublevel(`projects/${projectId}/compositeInstances`)
+  }
+
+  private getProjectCompositeInstanceInputHashesSublevel(projectId: string): Sublevel<string> {
+    return this.getStringSublevel(`projects/${projectId}/compositeInstanceInputHashes`)
+  }
+
+  private getProjectCompositeChildrenIdsSublevel(projectId: string): Sublevel {
+    return this.getJsonSublevel(`projects/${projectId}/topLevelCompositeChildrenIds`)
+  }
+
+  private getProjectInstanceStatesSublevel(projectId: string): Sublevel {
+    return this.getJsonSublevel(`projects/${projectId}/instanceStates`)
+  }
+
+  private getOperationInstanceStatesSublevel(operationId: string): Sublevel {
+    return this.getJsonSublevel(`operations/${operationId}/instanceStates`)
+  }
+
+  private getOperationInstanceLogsSublevel(
+    operationId: string,
+    instanceId: string,
+  ): Sublevel<string> {
+    return this.getStringSublevel(`operations/${operationId}/instances/${instanceId}/logs`)
+  }
+
+  private getTerminalSessionsSublevel(projectId: string, instanceId: string): Sublevel {
+    return this.getJsonSublevel(`projects/${projectId}/instances/${instanceId}/terminalSessions`)
+  }
+
+  private getTerminalSessionHistorySublevel(sessionId: string): Sublevel<string> {
+    return this.getStringSublevel(`terminalSessions/${sessionId}/history`)
+  }
+
+  private getStringSublevel(path: string): Sublevel<string> {
+    return this.db.sublevel<string, string>(path, { valueEncoding: "utf8" })
+  }
+
+  private getJsonSublevel(path: string): Sublevel {
+    return this.db.sublevel<string, unknown>(path, { valueEncoding: "json" })
+  }
+
+  static async create(
+    config: z.infer<typeof localStateBackendConfig>,
+    localPulumiHost: LocalPulumiHost,
+    logger: Logger,
+  ): Promise<StateBackend> {
+    const childLogger = logger.child({ backend: "StateBackend", service: "LocalStateBackend" })
+
+    let location = config.HIGHSTATE_BACKEND_STATE_LOCAL_DIR
+    if (!location) {
+      const currentUser = await localPulumiHost.getCurrentUser()
+
+      if (!currentUser) {
+        throw new Error(
+          "The pulumi state is not specified, please run `pulumi login` or specify the state location manually before restarting the service",
+        )
+      }
+
+      if (!currentUser.url) {
+        throw new Error(
+          "The pulumi user does not have a URL, please specify the state location manually",
+        )
+      }
+
+      const path = currentUser.url.replace("file://", "").replace("~", process.env.HOME!)
+      location = resolve(path, ".pulumi", ".highstate")
+
+      childLogger.debug({
+        msg: "auto-detected state location",
+        pulumiStateUrl: currentUser.url,
+        location,
+      })
+    }
+
+    const { ClassicLevel } = await import("classic-level")
+    const db = new ClassicLevel<string, unknown>(location)
+
+    return new LocalStateBackend(db, childLogger)
+  }
+}

package/src/state/manager.ts

@@ -0,0 +1,33 @@
+import type { InstanceState } from "../shared"
+import EventEmitter, { on } from "node:events"
+
+export type StateEvents = Record<string, [Partial<InstanceState>]>
+
+export class StateManager {
+  private readonly stateEE = new EventEmitter<StateEvents>()
+
+  /**
+   * Watches for all instance state changes in the project.
+   *
+   * @param projectId The project ID to watch.
+   * @param signal The signal to abort the operation.
+   */
+  public async *watchInstanceStates(
+    projectId: string,
+    signal?: AbortSignal,
+  ): AsyncIterable<Partial<InstanceState>> {
+    for await (const [state] of on(this.stateEE, projectId, { signal })) {
+      yield state
+    }
+  }
+
+  /**
+   * Emits a state patch for the instance in the project.
+   *
+   * @param projectId The project ID to emit the state patch for.
+   * @param patch The state patch to emit.
+   */
+  public emitStatePatch(projectId: string, patch: Partial<InstanceState>): void {
+    this.stateEE.emit(projectId, patch)
+  }
+}