@highstate/backend 0.9.18 → 0.9.19

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

@@ -1,449 +1,142 @@
-/* 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 type { InstanceId } from "@highstate/contract"
+import type {
+  InstanceState as DatabaseInstanceState,
+  InstanceCustomStatus,
+  InstanceEvaluationState,
+  InstanceOperationState,
+  InstanceOperationStatus,
+} from "../../../database"
 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 instance state aggregate including all related states.
+ */
+export type InstanceState = DatabaseInstanceState & {
   /**
-   * The calculated instance CRC32 input hash at the moment of latest operation completion.
+   * The ID of the parent instance, if any.
    *
-   * 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.
+   * Not to be confused with `parentId` which is the surrogate ID of the parent state.
    */
-  inputHash: z.number().optional(),
+  parentInstanceId?: InstanceId | null
 
   /**
-   * 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.
+   * The names of the instance secrets which have values set.
    */
-  args: z.record(z.string(), z.unknown()).optional(),
-})
-
-export const instanceEvaludationStatusEnumSchema = z.enum([
-  // transient statuses
-  "evaluating",
+  secretNames?: string[]
 
-  // 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.
+   * The last operation state of the instance.
    */
-  status: instanceEvaludationStatusEnumSchema,
+  lastOperationState?: InstanceOperationState | null
 
   /**
-   * The message describing the evaluation status.
-   * Typically used to show the error message if the status is "error".
+   * The evaluation state of the instance.
    */
-  message: z.string().optional(),
-})
+  evaluationState?: InstanceEvaluationState | null
 
-export enum WellKnownInstanceCustomStatus {
   /**
-   * The instance is in a healthy state.
+   * The IDs of the terminals produced by this unit instance.
    */
-  Healthy = "healthy",
+  terminalIds?: string[]
 
   /**
-   * The instance is in a degraded state.
+   * The IDs of the pages produced by this unit instance.
    */
-  Degraded = "degraded",
+  pageIds?: string[]
 
   /**
-   * The instance is in a down state/completely broken.
+   * The IDs of the triggers produced by this unit instance.
    */
-  Down = "down",
+  triggerIds?: string[]
 
   /**
-   * The instance is in a warning state.
+   * The custom statuses attached to this instance.
    */
-  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",
+  customStatuses?: InstanceCustomStatus[]
 }
 
-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 instanceStateEventSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("updated"),
+    state: z.custom<InstanceState>(),
+  }),
+  z.object({
+    type: z.literal("patched"),
+    stateId: z.string(),
+    patch: z.custom<Partial<InstanceState>>(),
+  }),
+  z.object({
+    type: z.literal("deleted"),
+    stateId: 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
+/**
+ * Checks if the given instance state represents a "virtual ghost" instance.
+ *
+ * Note: The evaluation state must be loaded, otherwise this function will always return true.
+ *
+ * @param state The instance state to check.
+ * @returns True if the instance is a virtual ghost, false otherwise.
+ */
+export function isVirtualGhostInstance(
+  state: Pick<InstanceState, "status" | "source" | "evaluationState">,
+): boolean {
+  if (state.source !== "virtual") return false
+  if (state.status === "undeployed") return false
+
+  return !state.evaluationState
 }
 
-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)
-  )
+/**
+ * Checks if the given instance state represents a deployed instance.
+ *
+ * An instance is considered deployed if the state exists and its status is not "undeployed".
+ *
+ * @param state The instance state to check (can be undefined).
+ * @returns True if the instance is deployed, false otherwise.
+ */
+export function isInstanceDeployed(state: InstanceState | undefined): boolean {
+  return !!state && state.status !== "undeployed"
 }
 
-export function isTransientOperationStatus(status: InstanceOperataionStatusEnum): boolean {
-  return status !== "created" && status !== "error"
+export type {
+  InstanceEvaluationState,
+  InstanceEvaluationStatus,
+  InstanceOperationState,
+  InstanceOperationStatus,
+  InstanceStatus,
+} from "../../../database"
+
+export const finalInstanceOperationStatuses: InstanceOperationStatus[] = [
+  "destroyed",
+  "updated",
+  "cancelled",
+  "destroyed",
+  "failed",
+  "skipped",
+]
+
+/**
+ * Checks if an instance operation status exists and is final transient (not stable).
+ *
+ * @param status The instance operation status to check
+ * @returns True if the status is transient
+ */
+export function isTransientInstanceOperationStatus(status?: InstanceOperationStatus): boolean {
+  return !!status && !finalInstanceOperationStatuses.includes(status)
 }
 
-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,
-  }),
+export const workerUnitRegistrationEventSchema = z.discriminatedUnion("type", [
   z.object({
-    type: z.literal("updated"),
-    state: instanceStateSchema,
+    type: z.literal("registered"),
+    instanceId: z.string(),
+    params: z.record(z.string(), z.unknown()),
   }),
   z.object({
-    type: z.literal("deleted"),
+    type: z.literal("deregistered"),
     instanceId: z.string(),
   }),
 ])
+
+export type WorkerUnitRegistrationEvent = z.infer<typeof workerUnitRegistrationEventSchema>