@highstate/backend 0.9.15 → 0.9.18

package/src/shared/models/project/state.ts

@@ -0,0 +1,449 @@
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { z } from "zod"
+import { objectMetaSchema, userObjectMetaSchema } from "@highstate/contract"
+
+export const instanceOperationStatusEnumSchema = z.enum([
+  // transient statuses
+  "updating",
+  "processing-triggers",
+  "previewing",
+  "destroying",
+  "refreshing",
+  "pending",
+  "cancelling",
+
+  // stable statuses
+  "created",
+  "error",
+])
+
+export const instanceOperationStatusSchema = z.object({
+  /**
+   * The enum representing the current status of the instance from the operation perspective.
+   */
+  status: instanceOperationStatusEnumSchema,
+
+  /**
+   * The ID of the latest operation that this instance is associated with.
+   */
+  latestOperationId: z.string(),
+
+  /**
+   * The IDs of the instances that this instance depends on at the moment of latest operation.
+   */
+  dependencyIds: z.array(z.string()),
+
+  /**
+   * The some human-readable message describing the current status.
+   * Typically used to show the error message if the status is "error".
+   */
+  message: z.string().optional(),
+
+  /**
+   * The current count of the Pulumi resources being managed by this instance.
+   */
+  currentResourceCount: z.number().optional(),
+
+  /**
+   * The total count of the Pulumi resources that this instance is expected to manage.
+   */
+  totalResourceCount: z.number().optional(),
+
+  /**
+   * The calculated instance CRC32 input hash at the moment of latest operation completion.
+   *
+   * This hash covers:
+   * - the instance's configuration (name, args, secret hashes);
+   * - the component definition hash;
+   * - the unit's source hash (if applicable);
+   * - the input hashes and output hashes of all input instances.
+   */
+  inputHash: z.number().optional(),
+
+  /**
+   * The random 32-bit nonce used in input hash calculation.
+   *
+   * It is changed every time the instance secrets are updated,
+   * to invalidate the input hash and force running the instance again.
+   */
+  inputHashNonce: z.number().optional(),
+
+  /**
+   * The sha256 of the output produced by the instance at the moment of latest operation completion.
+   *
+   * Does not depend on anything except the instance's output.
+   */
+  outputHash: z.string().optional(),
+
+  /**
+   * The calculated sha256 dependency output hash at the moment of latest operation completion.
+   *
+   * This hash is calculated as combination of output hashes of all input instances and nothing else.
+   *
+   * The primary use case of this hash is to "short-circuit" execution:
+   * if the outputs of input instances have not changed, dependent instances can skip execution,
+   * even if their input hashes changed due to upstream config changes.
+   * This prevents unnecessary re-execution of the entire dependency graph when only non-output-affecting inputs are modified.
+   */
+  dependencyOutputHash: z.string().optional(),
+
+  /**
+   * The arguments of the instances at the moment of latest operation start.
+   */
+  args: z.record(z.string(), z.unknown()).optional(),
+})
+
+export const instanceEvaludationStatusEnumSchema = z.enum([
+  // transient statuses
+  "evaluating",
+
+  // stable statuses
+  "evaluated",
+  "error",
+])
+
+export const instanceEvaluationStatusSchema = z.object({
+  /**
+   * The enum representing the current status of the instance from the evaluation perspective.
+   *
+   * The stable status when instance is not evaludated is forbidden.
+   */
+  status: instanceEvaludationStatusEnumSchema,
+
+  /**
+   * The message describing the evaluation status.
+   * Typically used to show the error message if the status is "error".
+   */
+  message: z.string().optional(),
+})
+
+export enum WellKnownInstanceCustomStatus {
+  /**
+   * The instance is in a healthy state.
+   */
+  Healthy = "healthy",
+
+  /**
+   * The instance is in a degraded state.
+   */
+  Degraded = "degraded",
+
+  /**
+   * The instance is in a down state/completely broken.
+   */
+  Down = "down",
+
+  /**
+   * The instance is in a warning state.
+   */
+  Warning = "warning",
+
+  /**
+   * The instance is progressing with some external sync operation,
+   * such as a deployment or a data migration.
+   */
+  Progressing = "progressing",
+
+  /**
+   * The instance is in an error state.
+   */
+  Error = "error",
+}
+
+export const instanceCustomStatusSchema = z.object({
+  /**
+   * The name of the instance's extra status.
+   *
+   * Must be unique within the instance state.
+   */
+  name: z.string(),
+
+  /**
+   * The enum value of the instance's extra status.
+   *
+   * May be on of the `WellKnownExtraInstanceStatus` values or a custom value.
+   */
+  status: z.string(),
+
+  /**
+   * The title of the instance's extra status.
+   */
+  title: z.string(),
+
+  /**
+   * The `iconify` icon representing the instance's extra status.
+   *
+   * If not provided and status is a well-known value, the icon will be derived from the status.
+   */
+  icon: z.string().optional(),
+
+  /**
+   * The HEX color of the status badge.
+   *
+   * If not provided and status is a well-known value, the color will be derived from the status.
+   */
+  color: z.string().optional(),
+
+  /**
+   * The message describing the instance's extra status.
+   *
+   * Can be used to provide additional context or information about the status.
+   *
+   * The message will be displayed in the 800x600 ANSI terminal in the UI,
+   * so differenet TUI elements should be drawn within this area.
+   */
+  message: z.string().optional(),
+
+  /**
+   * The order of the status in the list of statuses.
+   *
+   * Must be in the range from `0` to `100`, lower values are displayed first.
+   *
+   * If not provided, the default is `50`.
+   */
+  order: z.number().min(0).max(100).optional(),
+})
+
+export const instanceStatusFieldValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.array(z.string()),
+])
+
+export const instanceStatusFieldSchema = z.object({
+  name: z.string(),
+  meta: objectMetaSchema,
+
+  complementaryTo: z.string().optional(),
+
+  value: instanceStatusFieldValueSchema.optional(),
+})
+
+export const unitInstanceStatusFieldSchema = instanceStatusFieldSchema.omit({ meta: true }).extend({
+  meta: userObjectMetaSchema,
+})
+
+export const instanceStateExtraSchema = z.object({
+  /**
+   * The status fields reported by the unit or attached via the API.
+   *
+   * Do not confuse with `customStatuses`.
+   *
+   * These fields are used to store additional information about the instance,
+   * such as URLs, display names, and other metadata.
+   */
+  statusFields: z.array(instanceStatusFieldSchema).optional(),
+
+  /**
+   * The extra statuses of the instance reported by the unit or attached via the API.
+   *
+   * Do not confuse with `statusFields.
+   */
+  customStatuses: z.array(instanceCustomStatusSchema).optional(),
+
+  /**
+   * The IDs of the pages that are owned by this instance.
+   *
+   * The keys are the local page names, and the values are the page IDs.
+   */
+  pageIds: z.record(z.string(), z.string()).optional(),
+
+  /**
+   * The IDs of the terminals that are owned by this instance.
+   *
+   * The keys are the local terminal names, and the values are the terminal IDs.
+   */
+  terminalIds: z.record(z.string(), z.string()).optional(),
+
+  /**
+   * The IDs of the triggers that are owned by this instance.
+   *
+   * The keys are the local trigger names, and the values are the trigger IDs.
+   */
+  triggerIds: z.record(z.string(), z.string()).optional(),
+
+  /**
+   * The IDs of the artifacts that this instance exports via outputs.
+   *
+   * The keys are the output keys, and the values are the artifact IDs.
+   *
+   * These artifacts can be both: produced by this instance or reexported from input instances.
+   */
+  exportedArtifactIds: z.record(z.string(), z.array(z.string())).optional(),
+
+  /**
+   * The IDs of the secrets that this instance exports via outputs.
+   *
+   * The keys are the output keys, and the values are the secret IDs.
+   *
+   * These secrets can be both: produced by this instance or reexported from input instances.
+   */
+  exportedSecretIds: z.record(z.string(), z.string().array()).optional(),
+
+  /**
+   * The IDs of the worker registrations that are owned by this instance.
+   *
+   * The keys are the unit worker names, and the values are the registration IDs.
+   */
+  workerRegistrationIds: z.record(z.string(), z.string()).optional(),
+})
+
+export const instanceStateSchema = z.object({
+  /**
+   * The unique identifier of the instance.
+   * The format is `{componentType}:{instanceName}`, so each instance must have a unique name within its component type.
+   */
+  id: z.string(),
+
+  /**
+   * The ID of the parent instance, if this instance is a child of another composite instance.
+   */
+  parentId: z.string().optional(),
+
+  /**
+   * The names of the secrets that has values in this instance.
+   */
+  secretNames: z.array(z.string()).optional(),
+
+  /**
+   * The current status of the instance from the operation perspective.
+   *
+   * This status persists in the storage only when the operation is completed.
+   *
+   * If the operation was interrupted, the status will be "error" with corresponding error message.
+   *
+   * If the instance was not created or was successfully destroyed, the whole "operationStatus" field will be undefined.
+   */
+  operationStatus: instanceOperationStatusSchema.optional(),
+
+  /**
+   * The current status of the instance from the evaluation perspective.
+   *
+   * Only applies to composite instances, will always be `undefined` for unit instances.
+   */
+  evaluationStatus: instanceEvaluationStatusSchema.optional(),
+
+  /**
+   * The extra components of the instance.
+   *
+   * Applies to both unit and composite instances.
+   */
+  extra: instanceStateExtraSchema.optional(),
+})
+
+export type InstanceStatusFieldValue = z.infer<typeof instanceStatusFieldValueSchema>
+export type InstanceStatusField = z.infer<typeof instanceStatusFieldSchema>
+export type UnitInstanceStatusField = z.infer<typeof unitInstanceStatusFieldSchema>
+
+export type InstanceOperationStatus = z.infer<typeof instanceOperationStatusSchema>
+export type InstanceOperataionStatusEnum = z.infer<typeof instanceOperationStatusEnumSchema>
+
+export type InstanceEvaluationStatus = z.infer<typeof instanceEvaluationStatusSchema>
+export type InstanceEvaluationStatusEnum = z.infer<typeof instanceEvaludationStatusEnumSchema>
+
+export type InstanceCustomStatus = z.infer<typeof instanceCustomStatusSchema>
+
+export type InstanceState = z.infer<typeof instanceStateSchema>
+
+export type NullableRecord<T extends Record<string, any>> = {
+  [K in keyof T]: T[K] | null
+}
+
+export const instanceStateExtraPath = z.object({
+  statusFields: z.array(instanceStatusFieldSchema).optional().nullable(),
+  customStatuses: z.array(instanceCustomStatusSchema).optional().nullable(),
+  pageIds: z.record(z.string(), z.string()).optional().nullable(),
+  terminalIds: z.record(z.string(), z.string()).optional().nullable(),
+  triggerIds: z.record(z.string(), z.string()).optional().nullable(),
+  exportedArtifactIds: z.record(z.string(), z.array(z.string())).optional().nullable(),
+  exportedSecretIds: z.record(z.string(), z.string().array()).optional().nullable(),
+  workerRegistrationIds: z.record(z.string(), z.string()).optional().nullable(),
+})
+
+export const instanceStatePatchSchema = z.object({
+  id: z.string(),
+  parentId: z.string().nullish(),
+  secretNames: z.array(z.string()).nullish(),
+  operationStatus: instanceOperationStatusSchema.partial().nullish(),
+  evaluationStatus: instanceEvaluationStatusSchema.partial().nullish(),
+  extra: instanceStateExtraPath.nullish(),
+})
+
+export type InstanceStatePatch = z.infer<typeof instanceStatePatchSchema>
+
+export function applyStatePatch(
+  existingState: InstanceState | null | undefined,
+  patch: InstanceStatePatch,
+): InstanceState {
+  const state: any = existingState ? { ...existingState } : { id: patch.id }
+
+  const anyPatch = patch as any
+
+  // merge the patch with the existing state with 2-level deep merge
+  // (merge objects nested in the state, but replace objects inside these nested objects)
+  for (const key of Object.keys(patch)) {
+    if (typeof anyPatch[key] === "undefined") {
+      // ignore undefined values
+      continue
+    }
+
+    if (
+      typeof anyPatch[key] !== "object" ||
+      anyPatch[key] === null ||
+      Array.isArray(anyPatch[key])
+    ) {
+      // if the value is not an object, just replace it
+      // transform null to undefined
+      state[key] = anyPatch[key] === null ? undefined : anyPatch[key]
+      continue
+    }
+
+    // if the value is an object, merge it with the existing state
+    const existingValue = state[key] ? { ...state[key] } : {}
+
+    for (const subKey of Object.keys(anyPatch[key])) {
+      existingValue[subKey] = anyPatch[key][subKey]
+    }
+
+    state[key] = existingValue
+  }
+
+  return state as InstanceState
+}
+
+export function isStateEmpty(state: InstanceState): boolean {
+  return (
+    !state.operationStatus &&
+    !state.evaluationStatus &&
+    (!state.extra || Object.keys(state.extra).length === 0) &&
+    (!state.secretNames || state.secretNames.length === 0)
+  )
+}
+
+export function isTransientOperationStatus(status: InstanceOperataionStatusEnum): boolean {
+  return status !== "created" && status !== "error"
+}
+
+export function isStableOperationStatus(status: InstanceOperataionStatusEnum): boolean {
+  return status === "created" || status === "error"
+}
+
+export const instanceStateEventSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("patched"),
+    patch: instanceStatePatchSchema,
+  }),
+  z.object({
+    type: z.literal("updated"),
+    state: instanceStateSchema,
+  }),
+  z.object({
+    type: z.literal("deleted"),
+    instanceId: z.string(),
+  }),
+])

package/src/shared/models/project/terminal.ts

@@ -0,0 +1,98 @@
+import { z } from "zod"
+import { fileSchema, objectMetaSchema, userObjectMetaSchema } from "@highstate/contract"
+
+const metaFields = {
+  title: true,
+  globalTitle: true,
+  description: true,
+  icon: true,
+  iconColor: true,
+} as const
+
+const requiredMetaFields = {
+  title: true,
+  description: true,
+} as const
+
+/**
+ * The basic information about a terminal.
+ * The spec of the terminal is stored separately and defined in `terminalSpecSchema`.
+ */
+export const terminalSchema = z.object({
+  id: z.string().uuid(), // UUIDv7
+
+  meta: objectMetaSchema
+    .pick({
+      ...metaFields,
+      createdAt: true,
+      updatedAt: true,
+    })
+    .required(requiredMetaFields),
+
+  /**
+   * The ID of the instance produced the terminal if applicable.
+   */
+  instanceId: z.string().optional(),
+})
+
+export type Terminal = z.infer<typeof terminalSchema>
+
+/**
+ * Contains all the information needed to run a terminal,
+ * including the image, command, working directory, environment variables, and files.
+ */
+export const terminalSpecSchema = z.object({
+  image: z.string(),
+  command: z.string().array(),
+  cwd: z.string().optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  files: z.record(z.string(), fileSchema).optional(),
+})
+
+export type TerminalSpec = z.infer<typeof terminalSpecSchema>
+
+/**
+ * Terminal schema for unit API.
+ */
+export const unitTerminalSchema = z.object({
+  name: z.string(),
+  meta: userObjectMetaSchema.pick(metaFields).required(requiredMetaFields),
+  spec: terminalSpecSchema,
+})
+
+export type UnitTerminal = z.infer<typeof unitTerminalSchema>
+
+/**
+ * Terminal session schema for database storage and frontend display.
+ * Contains all terminal session information.
+ */
+export const terminalSessionSchema = z.object({
+  id: z.uuidv7(),
+
+  meta: objectMetaSchema
+    .pick({ ...metaFields, createdAt: true, updatedAt: true })
+    .required(requiredMetaFields)
+    .extend({
+      /**
+       * The time when the session was finished.
+       */
+      finishedAt: z.number().optional(),
+    }),
+
+  /**
+   * The ID of the project this session belongs to.
+   */
+  projectId: z.string(),
+
+  /**
+   * References the terminal this session is based on.
+   */
+  terminalId: z.string(),
+
+  /**
+   * References the instance produced the terminal if applicable.
+   */
+  instanceId: z.string().optional(),
+})
+
+export type TerminalSession = z.infer<typeof terminalSessionSchema>

package/src/shared/models/project/trigger.ts

@@ -0,0 +1,56 @@
+import { z } from "zod"
+import { objectMetaSchema, userObjectMetaSchema } from "@highstate/contract"
+
+/**
+ * Trigger specification schema.
+ */
+export const triggerSpecSchema = z.union([
+  z.object({
+    type: z.literal("before-destroy"),
+  }),
+  z.object({
+    type: z.literal("schedule"),
+    schedule: z.string(),
+  }),
+])
+
+export type TriggerSpec = z.infer<typeof triggerSpecSchema>
+
+/**
+ * Trigger info for frontend display.
+ * Contains only basic information visible to the frontend.
+ */
+export const triggerSchema = z.object({
+  id: z.string(),
+  instanceId: z.string(),
+  meta: objectMetaSchema,
+  spec: triggerSpecSchema,
+})
+
+export type Trigger = z.infer<typeof triggerSchema>
+
+/**
+ * Trigger schema for unit API.
+ * This is what units provide - excludes id since it's set by the system.
+ */
+export const unitTriggerSchema = triggerSchema
+  .omit({ id: true, instanceId: true, meta: true })
+  .extend({
+    name: z.string(),
+    meta: userObjectMetaSchema.optional(),
+  })
+  .extend({
+    name: z.string(),
+    meta: userObjectMetaSchema.optional(),
+  })
+
+export type UnitTrigger = z.infer<typeof unitTriggerSchema>
+
+/**
+ * Trigger invocation schema.
+ */
+export const triggerInvocationSchema = z.object({
+  name: z.string(),
+})
+
+export type TriggerInvocation = z.infer<typeof triggerInvocationSchema>

package/src/shared/models/project/unlock-method.ts

@@ -0,0 +1,38 @@
+import { z } from "zod"
+import { objectMetaSchema } from "@highstate/contract"
+
+export const unlockMethodType = z.enum(["password", "passkey"])
+
+/**
+ * Complete unlock method schema for database storage.
+ * Contains all unlock method information including encryption details.
+ */
+export const unlockMethodSchema = z.object({
+  id: z.uuidv7(),
+
+  /**
+   * Metadata for the unlock method.
+   */
+  meta: objectMetaSchema,
+
+  /**
+   * The type of unlock method (password or passkey).
+   */
+  type: unlockMethodType,
+
+  /**
+   * The encrypted identity used to decrypt the master key.
+   */
+  encryptedIdentity: z.string(),
+
+  /**
+   * The recipient of the unlock method to use to encrypt the master key for this unlock method.
+   */
+  recipient: z.string(),
+})
+
+export const inputUnlockMethodSchema = unlockMethodSchema.omit({ id: true })
+
+export type InputUnlockMethod = z.infer<typeof inputUnlockMethodSchema>
+export type UnlockMethod = z.infer<typeof unlockMethodSchema>
+export type UnlockMethodType = z.infer<typeof unlockMethodType>