@highstate/backend 0.7.2 → 0.7.3

package/src/shared/state.ts

@@ -0,0 +1,262 @@
+import { omit } from "remeda"
+import { z } from "zod"
+
+export const instanceStatusSchema = z.enum([
+  "not_created",
+  "updating",
+  "previewing",
+  "destroying",
+  "refreshing",
+  "created",
+  "error",
+  "pending",
+  "unknown",
+])
+
+export const instanceStatusFieldSchema = z.object({
+  name: z.string(),
+  value: z.string().optional(),
+  displayName: z.string().optional(),
+  sensitive: z.boolean().optional(),
+  url: z.string().optional(),
+  complementaryTo: z.string().optional(),
+})
+
+export const instanceFileMetaSchema = z.object({
+  name: z.string(),
+  contentType: z.string(),
+  size: z.number(),
+  isBinary: z.boolean().optional(),
+})
+
+export const instanceFileSchema = z.object({
+  meta: instanceFileMetaSchema,
+  content: z.string(),
+})
+
+export const instancePageBlockSchema = z.union([
+  z.object({
+    type: z.literal("markdown"),
+    content: z.string(),
+  }),
+  z.object({
+    type: z.literal("qr"),
+    content: z.string(),
+    showContent: z.coerce.boolean(),
+    language: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal("file"),
+    fileMeta: instanceFileMetaSchema,
+  }),
+])
+
+export const instancePageMetaSchema = z.object({
+  name: z.string(),
+  title: z.string(),
+})
+
+export const instancePageSchema = z.object({
+  ...instancePageMetaSchema.shape,
+  content: z.array(instancePageBlockSchema),
+})
+
+export const instanceTerminalMetaSchema = z.object({
+  name: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
+})
+
+export const instanceTerminalFileSchema = z.object({
+  content: z.string().optional(),
+  isBinary: z.boolean().optional(),
+  mode: z.number().optional(),
+})
+
+export const instanceTerminalSchema = z.object({
+  ...instanceTerminalMetaSchema.shape,
+  image: z.string(),
+  command: z.string().array(),
+  cwd: z.string().optional(),
+  env: z.record(z.string()).optional(),
+  files: z.record(instanceTerminalFileSchema).optional(),
+})
+
+export const instanceTriggerSpecSchema = z.union([
+  z.object({
+    type: z.literal("before-destroy"),
+  }),
+  z.object({
+    type: z.literal("schedule"),
+    schedule: z.string(),
+  }),
+])
+
+export const instanceTriggerSchema = z.object({
+  name: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
+  spec: instanceTriggerSpecSchema,
+})
+
+export const instanceTriggerInvocationSchema = z.object({
+  name: z.string(),
+})
+
+export const instanceStateSchema = z.object({
+  id: z.string(),
+  parentId: z.string().nullable().default(null),
+  status: instanceStatusSchema,
+  dependencyIds: z.array(z.string()).default(() => []),
+
+  latestOperationId: z.string().nullable().default(null),
+
+  currentResourceCount: z.number().nullable().default(null),
+  totalResourceCount: z.number().nullable().default(null),
+  inputHash: z.string().nullable().default(null),
+  outputHash: z.string().nullable().default(null),
+
+  error: z.string().nullable().default(null),
+  evaluationError: z.string().nullable().default(null),
+
+  statusFields: z.array(instanceStatusFieldSchema).default(() => []),
+  files: z.array(instanceFileMetaSchema).default(() => []),
+  pages: z.array(instancePageMetaSchema).default(() => []),
+  terminals: z.array(instanceTerminalMetaSchema).default(() => []),
+  triggers: z.array(instanceTriggerSchema).default(() => []),
+})
+
+export const instanceStateUpdateSchema = z
+  .object({
+    ...instanceStateSchema.shape,
+
+    // secrets updated by the unit
+    secrets: z.record(z.string()).nullable(),
+
+    // log line emitted by the unit
+    logLine: z.string().nullable(),
+  })
+  .partial()
+
+export type InstanceStatusField = z.infer<typeof instanceStatusFieldSchema>
+export type InstanceTerminal = z.infer<typeof instanceTerminalSchema>
+
+export type InstanceStatus = z.infer<typeof instanceStatusSchema>
+export type InstanceState = z.infer<typeof instanceStateSchema>
+
+export type InstanceStateUpdate = z.infer<typeof instanceStateUpdateSchema>
+
+export type InstancePageBlock = z.infer<typeof instancePageBlockSchema>
+export type InstancePageMeta = z.infer<typeof instancePageMetaSchema>
+export type InstanceFileMeta = z.infer<typeof instanceFileMetaSchema>
+
+export type InstanceTriggerSpec = z.infer<typeof instanceTriggerSpecSchema>
+export type InstanceTrigger = z.infer<typeof instanceTriggerSchema>
+export type InstanceTriggerInvocation = z.infer<typeof instanceTriggerInvocationSchema>
+
+export function createInstanceState(
+  id: string,
+  status: InstanceStatus = "not_created",
+  fields: Partial<InstanceState> = {},
+): InstanceState {
+  return {
+    id,
+    parentId: null,
+    dependencyIds: [],
+    status: status,
+
+    latestOperationId: null,
+
+    currentResourceCount: null,
+    totalResourceCount: null,
+    inputHash: null,
+    outputHash: null,
+
+    error: null,
+    evaluationError: null,
+
+    statusFields: [],
+    files: [],
+    pages: [],
+    terminals: [],
+    triggers: [],
+
+    ...fields,
+  }
+}
+
+export function applyPartialInstanceState(
+  states: Map<string, InstanceState>,
+  patch: Partial<InstanceState>,
+): InstanceState {
+  if (!patch.id) {
+    throw new Error("The ID of the instance state is required.")
+  }
+
+  let state = states.get(patch.id) ?? createInstanceState(patch.id, "unknown")
+  state = { ...state, ...patch }
+
+  states.set(state.id, state)
+  return state
+}
+
+export function createInstanceStatePatch(update: InstanceStateUpdate): Partial<InstanceState> {
+  return omit(update, ["secrets", "logLine"])
+}
+
+/**
+ * Builds a map where instance id -> instance state ids that directly depend on the instance.
+ *
+ * @param instanceStates The instance states to build the map from.
+ */
+export function buildDependentInstanceStateMap(
+  instanceStates: Map<string, InstanceState>,
+): Map<string, string[]> {
+  const dependentMap = new Map<string, string[]>()
+
+  for (const state of instanceStates.values()) {
+    for (const dependency of state.dependencyIds) {
+      let dependents = dependentMap.get(dependency)
+      if (!dependents) {
+        dependents = []
+        dependentMap.set(dependency, dependents)
+      }
+
+      dependents.push(state.id)
+    }
+  }
+
+  return dependentMap
+}
+
+/**
+ * Gets all instance ids that depend on the given instance id (including recursively).
+ * The instance id itself is not included in the result.
+ *
+ * @param dependentMap The dependent map.
+ * @param instanceId The instance id to get all dependent instance ids.
+ */
+export function getAllDependentInstanceIds(
+  dependentMap: Map<string, string[]>,
+  instanceId: string,
+): string[] {
+  const result = new Set<string>()
+  const visited = new Set<string>()
+
+  const traverse = (id: string) => {
+    if (visited.has(id)) return
+    visited.add(id)
+
+    const dependents = dependentMap.get(id)
+    if (!dependents) return
+
+    for (const dependent of dependents) {
+      result.add(dependent)
+      traverse(dependent)
+    }
+  }
+
+  traverse(instanceId)
+
+  return Array.from(result)
+}

package/src/shared/terminal.ts

@@ -0,0 +1,13 @@
+import { z } from "zod"
+
+export const terminalSessionSchema = z.object({
+  id: z.string().nanoid(),
+  projectId: z.string(),
+  instanceId: z.string(),
+  terminalName: z.string(),
+  terminalTitle: z.string(),
+  createdAt: z.coerce.date(),
+  finishedAt: z.coerce.date().optional(),
+})
+
+export type TerminalSession = z.infer<typeof terminalSessionSchema>

package/src/state/abstractions.ts

@@ -0,0 +1,222 @@
+import {
+  type CompositeInstance,
+  type InstanceState,
+  type ProjectOperation,
+  type TerminalSession,
+} from "../shared"
+
+export type LogEntry = [instanceId: string, line: string]
+export type TerminalHistoryEntry = [sessionId: string, entry: string]
+
+export interface StateBackend {
+  /**
+   * Gets the active operations which are not completed or failed.
+   */
+  getActiveOperations(signal?: AbortSignal): Promise<ProjectOperation[]>
+
+  /**
+   * Gets recent operations of the project.
+   * If `beforeOperationId` is provided, returns the operations before the specified operation ID.
+   * The page size is fixed to 10.
+   *
+   * @param projectId The ID of the project.
+   * @param beforeOperationId The ID of the operation to get the operations before.
+   */
+  getOperations(projectId: string, beforeOperationId?: string): Promise<ProjectOperation[]>
+
+  /**
+   * Gets the current (cached) instance states of the project.
+   * Actual states should be retrieved from the runner (and they are still may not be up-to-date).
+   *
+   * @param projectId The ID of the project.
+   */
+  getAllInstanceStates(projectId: string, signal?: AbortSignal): Promise<InstanceState[]>
+
+  /**
+   * Gets the current (cached) state of the instance.
+   *
+   * @param projectId The ID of the project.
+   * @param instanceId The ID of the instance.
+   */
+  getInstanceState(projectId: string, instanceId: string): Promise<InstanceState | null>
+
+  /**
+   * Gets the current (cached) state of the instances.
+   *
+   * @param projectId The ID of the project.
+   * @param instanceIds The IDs of the instances.
+   */
+  getInstanceStates(projectId: string, instanceIds: string[]): Promise<InstanceState[]>
+
+  /**
+   * Gets the affected instance states at the moment of the operation completion.
+   * The logs are not included.
+   *
+   * @param operationId The ID of the operation.
+   */
+  getAffectedInstanceStates(operationId: string): Promise<InstanceState[]>
+
+  /**
+   * Gets the full logs of the instance at the moment of the operation completion.
+   *
+   * @param operationId The ID of the operation.
+   * @param instanceId The ID of the instance.
+   */
+  getInstanceLogs(operationId: string, instanceId: string): Promise<string[]>
+
+  /**
+   * Puts the operation to the state.
+   * The operation must have a unique ID sortable chronologically.
+   * Also, the operation must have the project ID.
+   *
+   * @param operation The operation to put.
+   */
+  putOperation(operation: ProjectOperation): Promise<void>
+
+  /**
+   * Puts the instance states affected by the operation to the state.
+   *
+   * @param projectId The ID of the project.
+   * @param operationId The ID of the operation.
+   * @param states The instance states to put.
+   */
+  putAffectedInstanceStates(
+    projectId: string,
+    operationId: string,
+    states: InstanceState[],
+  ): Promise<void>
+
+  /**
+   * Puts the instance states of the project to the state.
+   *
+   * @param projectId The ID of the project.
+   * @param states The instance states to put.
+   */
+  putInstanceStates(projectId: string, states: InstanceState[]): Promise<void>
+
+  /**
+   * Appends the log lines to the instance logs.
+   *
+   * @param operationId The ID of the operation.
+   * @param logs The logs to append. Each log is a tuple of the instance ID and the log line.
+   */
+  appendInstanceLogs(operationId: string, logs: LogEntry[]): Promise<void>
+
+  /**
+   * Gets all the evaluated composite instances of the project.
+   *
+   * @param projectId The ID of the project.
+   */
+  getCompositeInstances(projectId: string, signal?: AbortSignal): Promise<CompositeInstance[]>
+
+  /**
+   * Gets the IDs of the composite instances which are children (level 2+) of the top-level composite instances.
+   *
+   * Used to track the evaluated composite instances and clear them when the top-level composite instances are cleared/changed.
+   *
+   * @param projectId The ID of the project.
+   * @param instanceIds The IDs of the top-level composite instances.
+   */
+  getTopLevelCompositeChildrenIds(
+    projectId: string,
+    instanceIds: string[],
+    signal?: AbortSignal,
+  ): Promise<Record<string, string[]>>
+
+  /**
+   * Puts the IDs of the composite instances which are children (level 2+) of the top-level composite instances.
+   *
+   * @param projectId The ID of the project.
+   * @param childrenIds The IDs of the composite instances (key is the top-level instance ID).
+   */
+  putTopLevelCompositeChildrenIds(
+    projectId: string,
+    childrenIds: Record<string, string[]>,
+  ): Promise<void>
+
+  /**
+   * Gets the evaluated composite instance of the project.
+   *
+   * @param projectId The ID of the project.
+   * @param instanceId The ID of the instance.
+   */
+  getCompositeInstance(projectId: string, instanceId: string): Promise<CompositeInstance | null>
+
+  /**
+   * Gets the input hash of the evaluated composite instance.
+   *
+   * @param projectId The ID of the project.
+   * @param instanceId The ID of the instance.
+   */
+  getCompositeInstanceInputHash(projectId: string, instanceId: string): Promise<string | null>
+
+  /**
+   * Puts the evaluated composite instances of the project to the state.
+   *
+   * @param projectId The ID of the project.
+   * @param instances The instances to put.
+   */
+  putCompositeInstances(projectId: string, instances: CompositeInstance[]): Promise<void>
+
+  /**
+   * Clears the evaluation state of the instance.
+   *
+   * @param projectId The ID of the project.
+   * @param instanceIds The IDs of the instances to clear.
+   */
+  clearCompositeInstances(projectId: string, instanceIds: string[]): Promise<void>
+
+  /**
+   * Gets all the terminal sessions of the instance.
+   *
+   * @param projectId The ID of the project.
+   * @param instanceId The ID of the instance.
+   */
+  getTerminalSessions(projectId: string, instanceId: string): Promise<TerminalSession[]>
+
+  /**
+   * Gets the IDs of all the active terminal sessions.
+   */
+  getActiveTerminalSessions(): Promise<TerminalSession[]>
+
+  /**
+   * Puts the IDs of the active terminal sessions.
+   */
+  putActiveTerminalSessions(sessions: TerminalSession[]): Promise<void>
+
+  /**
+   * Gets the terminal session.
+   *
+   * @param projectId The ID of the project.
+   * @param instanceId The ID of the instance.
+   * @param sessionId The ID of the session.
+   */
+  getTerminalSession(
+    projectId: string,
+    instanceId: string,
+    sessionId: string,
+  ): Promise<TerminalSession | null>
+
+  /**
+   * Puts the terminal sessions of the instance to the state.
+   *
+   * @param projectId The ID of the project.
+   * @param instanceId The ID of the instance.
+   * @param session The terminal session to put.
+   */
+  putTerminalSession(projectId: string, instanceId: string, session: TerminalSession): Promise<void>
+
+  /**
+   * Gets the history lines of the terminal session.
+   *
+   * @param sessionId The ID of the session.
+   */
+  getTerminalSessionHistory(sessionId: string): Promise<string[]>
+
+  /**
+   * Appends the history lines to the terminal sessions.
+   *
+   * @param entries The entries to append.
+   */
+  appendTerminalSessionHistory(entries: TerminalHistoryEntry[]): Promise<void>
+}

package/src/state/factory.ts

@@ -0,0 +1,22 @@
+import type { StateBackend } from "./abstractions"
+import type { Logger } from "pino"
+import type { LocalPulumiHost } from "../common"
+import { z } from "zod"
+import { LocalStateBackend, localStateBackendConfig } from "./local"
+
+export const stateBackendConfig = z.object({
+  HIGHSTATE_BACKEND_STATE_TYPE: z.enum(["local"]).default("local"),
+  ...localStateBackendConfig.shape,
+})
+
+export function createStateBackend(
+  config: z.infer<typeof stateBackendConfig>,
+  localPulumiHost: LocalPulumiHost,
+  logger: Logger,
+): Promise<StateBackend> {
+  switch (config.HIGHSTATE_BACKEND_STATE_TYPE) {
+    case "local": {
+      return LocalStateBackend.create(config, localPulumiHost, logger)
+    }
+  }
+}

package/src/state/index.ts

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