@highstate/backend 0.9.15 → 0.9.16

package/src/shared/models/base.ts

@@ -0,0 +1,151 @@
+import { z } from "zod"
+
+export const userObjectMetaSchema = z.object({
+  /**
+   * Human-readable name of the object.
+   *
+   * Used in UI components for better user experience.
+   */
+  title: z.string().optional(),
+
+  /**
+   * The title used globally for the object.
+   *
+   * For example, the title of an instance secret is "Password" which is okay
+   * to display in the instance secret list, but when the secret is displayed in a
+   * global secret list the name should be more descriptive, like "Proxmox Password".
+   */
+  globalTitle: z.string().optional(),
+
+  /**
+   * Description of the object.
+   *
+   * Provides additional context for users and developers.
+   */
+  description: z.string().optional(),
+
+  /**
+   * The color of the object.
+   *
+   * Used in UI components to visually distinguish objects.
+   */
+  color: z.string().optional(),
+
+  /**
+   * Primary icon identifier.
+   *
+   * Should reference a iconify icon name, like "mdi:server" or "gg:remote".
+   */
+  icon: z.string().optional(),
+
+  /**
+   * The color of the primary icon.
+   */
+  iconColor: z.string().optional(),
+
+  /**
+   * The secondary icon identifier.
+   *
+   * Used to provide additional context or actions related to the object.
+   *
+   * Should reference a iconify icon name, like "mdi:edit" or "mdi:delete".
+   */
+  secondaryIcon: z.string().optional(),
+
+  /**
+   * The color of the secondary icon.
+   */
+  secondaryIconColor: z.string().optional(),
+})
+
+export const objectMetaSchema = userObjectMetaSchema.extend({
+  /**
+   * Creation timestamp in milliseconds.
+   *
+   * Managed automatically by the system.
+   */
+  createdAt: z.number().optional(),
+
+  /**
+   * Last update timestamp in milliseconds.
+   *
+   * Managed automatically by the system.
+   */
+  updatedAt: z.number().optional(),
+
+  /**
+   * The optional version of the document to support optimistic concurrency control.
+   *
+   * Managed automatically by the system.
+   */
+  version: z.number().optional(),
+})
+
+export type UserObjectMeta = z.infer<typeof userObjectMetaSchema>
+export type ObjectMeta = z.infer<typeof objectMetaSchema>
+
+export function hasObjectMeta(value: unknown): value is { meta: ObjectMeta } {
+  return typeof value === "object" && value !== null && "meta" in value
+}
+
+export const collectionQuerySchema = z.object({
+  /**
+   * The search string to filter documents by display name, description, or other text fields.
+   *
+   * Not implemented yet.
+   */
+  search: z.string().optional(),
+
+  /**
+   * The skip count for pagination.
+   *
+   * Cannot be used with `cursor`.
+   */
+  skip: z.number().int().nonnegative().optional(),
+
+  /**
+   * The sorting order for the results.
+   *
+   * By default, "asc" is used.
+   */
+  sort: z.enum(["asc", "desc"]).default("asc"),
+
+  /**
+   * The ID of the document to start the query from.
+   *
+   * If "asc" sorting is used, this will return results after this ID.
+   * Otherwise, it will return results before this ID.
+   *
+   * Cannot be used with `skip`.
+   */
+  cursor: z.string().optional(),
+
+  /**
+   * The count of documents to return.
+   *
+   * Defaults to 20 if not specified.
+   * Maximum value is 100.
+   */
+  count: z.number().int().nonnegative().max(100).optional(),
+})
+
+export type CollectionQuery = z.infer<typeof collectionQuerySchema>
+
+export type CollectionQueryResult<T> = {
+  /**
+   * The list of objects matching the query.
+   */
+  items: T[]
+
+  /**
+   * The total number of documents matching the query.
+   */
+  total: number
+
+  /**
+   * The cursor for the next page of results.
+   *
+   * If undefined, there are no more results.
+   */
+  nextCursor?: string
+}

package/src/shared/models/errors.ts

@@ -0,0 +1,5 @@
+export class AccessError extends Error {
+  constructor(message: string) {
+    super(message)
+  }
+}

package/src/shared/models/index.ts

@@ -0,0 +1,4 @@
+export * from "./base"
+export * from "./backend"
+export * from "./project"
+export * from "./errors"

package/src/shared/models/project/api-key.ts

@@ -0,0 +1,62 @@
+import { z } from "zod"
+import { objectMetaSchema } from "../base"
+
+export const instanceActionSchema = z.enum(["read", "write"])
+export const serviceAccountActionSchema = z.enum(["full"])
+
+export const projectAccessScope = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("instance"),
+    actions: instanceActionSchema.array(),
+    instanceIds: z.string().array(),
+  }),
+  z.object({
+    type: z.literal("service-account"),
+    actions: serviceAccountActionSchema.array(),
+    serviceAccountIds: z.string().array(),
+  }),
+])
+
+export const projectApiKeySchema = z.object({
+  id: z.string().ulid(),
+  meta: objectMetaSchema,
+
+  /**
+   * The 256-bit random token used to authenticate API requests.
+   */
+  token: z.string(),
+
+  scopes: z.array(projectAccessScope),
+})
+
+export type InstanceAction = z.infer<typeof instanceActionSchema>
+export type ProjectAccessScope = z.infer<typeof projectAccessScope>
+export type ProjectApiKey = z.infer<typeof projectApiKeySchema>
+
+function hasAll<T>(array: T[], values: T[]): boolean {
+  return values.every(value => array.includes(value))
+}
+
+export function validateInstanceAccess(
+  apiKey: ProjectApiKey,
+  actions: InstanceAction[],
+  instanceIds: string[],
+): boolean {
+  return apiKey.scopes
+    .filter(scope => scope.type === "instance")
+    .some(scope => hasAll(scope.actions, actions) && hasAll(scope.instanceIds, instanceIds))
+}
+
+type ActionDescriptionMap<TType extends ProjectAccessScope["type"] = ProjectAccessScope["type"]> = {
+  [K in TType]: Record<(ProjectAccessScope & { type: K })["actions"][number], string>
+}
+
+export const projectAccessActionDescriptions: ActionDescriptionMap = {
+  "service-account": {
+    full: "Full access to the service account and all resources owned by it and granted to it.",
+  },
+  instance: {
+    read: "Read access to the instance, including its state all resources owned by it.",
+    write: "Write access to the instance, including its state and all resources owned by it.",
+  },
+}

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

@@ -0,0 +1,113 @@
+import { z } from "zod"
+import {
+  HighstateSignature,
+  type File,
+  type FileContent,
+  type FileMeta,
+  type UnitArtifact,
+} from "@highstate/contract"
+import { objectMetaSchema, userObjectMetaSchema } from "../base"
+
+export const artifactUsageSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("instance"),
+    instanceId: z.string(),
+  }),
+  z.object({
+    type: z.literal("terminal"),
+    terminalId: z.string(),
+  }),
+  z.object({
+    type: z.literal("service-account"),
+    serviceAccountId: z.string(),
+  }),
+])
+
+export type ArtifactUsage = z.infer<typeof artifactUsageSchema>
+
+export function compareArtifactUsage(a: ArtifactUsage, b: ArtifactUsage): boolean {
+  if (a.type === "instance" && b.type === "instance") {
+    return a.instanceId === b.instanceId
+  }
+
+  if (a.type === "terminal" && b.type === "terminal") {
+    return a.terminalId === b.terminalId
+  }
+
+  if (a.type === "service-account" && b.type === "service-account") {
+    return a.serviceAccountId === b.serviceAccountId
+  }
+
+  return false
+}
+
+/**
+ * File metadata schema.
+ */
+export const fileMetaSchema = z.object({
+  name: z.string(),
+  size: z.number().optional(),
+  isBinary: z.boolean().optional(),
+  mode: z.number().optional(),
+}) satisfies z.ZodType<FileMeta>
+
+/**
+ * Complete artifact schema for database storage.
+ * Contains all artifact information.
+ */
+export const artifactSchema = z.object({
+  /**
+   * The UUIDv7 of the artifact generated when the artifact with unique content is first stored.
+   */
+  id: z.string().uuid(),
+
+  meta: objectMetaSchema,
+
+  /**
+   * The SHA-256 hash of the artifact content before encryption.
+   */
+  hash: z.string(),
+
+  /**
+   * The list of usages of this artifact.
+   *
+   * When became empty, the artifact is garbage collected.
+   */
+  usages: artifactUsageSchema.array(),
+
+  /**
+   * The size of the unencrypted artifact archive in bytes.
+   */
+  size: z.number(),
+
+  /**
+   * The size of each chunk of the artifact which independently encrypted.
+   */
+  chunkSize: z.number(),
+})
+
+export type Artifact = z.infer<typeof artifactSchema>
+
+/**
+ * Artifact schema for unit API.
+ */
+export const unitArtifactSchema = z.object({
+  hash: z.string(),
+  meta: userObjectMetaSchema.optional(),
+}) satisfies z.ZodType<UnitArtifact>
+
+export const fileContentSchema = z.union([
+  z.object({
+    type: z.literal("embedded"),
+    value: z.string(),
+  }),
+  z.object({
+    type: z.literal("artifact"),
+    [HighstateSignature.Artifact]: unitArtifactSchema,
+  }),
+]) satisfies z.ZodType<FileContent>
+
+export const fileSchema = z.object({
+  meta: fileMetaSchema,
+  content: fileContentSchema,
+}) satisfies z.ZodType<File>

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

@@ -0,0 +1,45 @@
+import { z } from "zod"
+
+export const metaSchema = z.object({
+  displayName: z.string().optional(),
+  description: z.string().optional(),
+  color: z.string().optional(),
+})
+
+export const entitySchema = z.object({
+  type: z.string(),
+  schema: z.any(), // TSchema from TypeBox
+  meta: metaSchema,
+  definitionHash: z.string(),
+})
+
+export const componentMetaSchema = metaSchema.extend({
+  primaryIcon: z.string().optional(),
+  primaryIconColor: z.string().optional(),
+  secondaryIcon: z.string().optional(),
+  secondaryIconColor: z.string().optional(),
+  category: z.string().optional(),
+  defaultNamePrefix: z.string().optional(),
+})
+
+export const componentArgumentSchema = z.object({
+  schema: z.any(), // ArgumentValueSchema from TypeBox
+  required: z.boolean(),
+  meta: componentMetaSchema,
+})
+
+export const componentInputSchema = z.object({
+  type: z.string(),
+  required: z.boolean(),
+  multiple: z.boolean(),
+  meta: componentMetaSchema,
+})
+
+export const componentModelSchema = z.object({
+  type: z.string(),
+  args: z.record(componentArgumentSchema),
+  inputs: z.record(componentInputSchema),
+  outputs: z.record(componentInputSchema),
+  meta: componentMetaSchema,
+  definitionHash: z.string(),
+})

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

@@ -0,0 +1,14 @@
+export * from "./instance"
+export * from "./state"
+export * from "./operation"
+export * from "./terminal"
+export * from "./page"
+export * from "./artifact"
+export * from "./trigger"
+export * from "./unlock-method"
+export * from "./secret"
+export * from "./lock"
+export * from "./component"
+export * from "./service-account"
+export * from "./worker"
+export * from "./api-key"

package/src/shared/{project.ts → models/project/instance.ts}

@@ -38,11 +38,23 @@ export const instanceModelSchema = z.object({
 export const compositeInstanceSchema = z.object({
   instance: instanceModelSchema,
   children: z.array(instanceModelSchema),
+  childCompositeInstanceIds: z.array(z.string()).optional(),
   inputHash: z.string().optional(),
 })
 
 export type CompositeInstance = z.infer<typeof compositeInstanceSchema>
 
+export const compositeInstanceEventSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("updated"),
+    instance: compositeInstanceSchema,
+  }),
+  z.object({
+    type: z.literal("deleted"),
+    instanceId: z.string(),
+  }),
+])
+
 export const hubModelPatchSchema = z.object({
   position: positionSchema.optional(),
   inputs: z.array(instanceInputSchema).optional(),

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

@@ -0,0 +1,91 @@
+import { z } from "zod"
+import { objectMetaSchema } from "../base"
+
+export const instanceLockSpecSchema = z.union([
+  z.object({
+    type: z.literal("operation"),
+
+    /**
+     * The operation ID. Will be used to fetch the operation and detect whether it is still running or lost.
+     */
+    operationId: z.string(),
+  }),
+  z.object({
+    type: z.literal("evaluation"),
+
+    /**
+     * The internal evaluation ID that is used to detect lost evaluations and restart them.
+     */
+    evaluationId: z.string(),
+  }),
+  z.object({
+    type: z.literal("custom"),
+
+    /**
+     * The ID of the party that holds the lock.
+     *
+     * Each locker must only manage the locks it has created.
+     */
+    lockerId: z.string(),
+
+    /**
+     * The ID of the lock provided by the locker.
+     *
+     * Must be unique across all locks in the locker system.
+     */
+    lockId: z.string(),
+
+    /**
+     * The optional payload provided by the locker.
+     *
+     * Can be used to store additional information about the lock,
+     * like the ID of the lock in the locker system,
+     * or any other metadata that is relevant to the lock.
+     */
+    payload: z.record(z.string()).optional(),
+  }),
+])
+
+export const instanceLockSchema = z.object({
+  id: z.string(),
+  meta: objectMetaSchema,
+  spec: instanceLockSpecSchema,
+})
+
+export type InstanceLock = z.infer<typeof instanceLockSchema>
+export type InstanceLockSpec = z.infer<typeof instanceLockSpecSchema>
+
+/**
+ * Compares two instance lock specifications for equality.
+ *
+ * @param a The first instance lock specification to compare.
+ * @param b The second instance lock specification to compare.
+ *
+ * @returns True if both specifications are of the same type and have matching identifiers, false otherwise.
+ */
+export function compareInstanceLockSpecs(a: InstanceLockSpec, b: InstanceLockSpec): boolean {
+  if (a.type === "operation" && b.type === "operation") {
+    return a.operationId === b.operationId
+  }
+
+  if (a.type === "evaluation" && b.type === "evaluation") {
+    return a.evaluationId === b.evaluationId
+  }
+
+  if (a.type === "custom" && b.type === "custom") {
+    return a.lockerId === b.lockerId && a.lockId === b.lockId
+  }
+
+  return false
+}
+
+export const instanceLockEventSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("locked"),
+    locks: z.array(instanceLockSchema),
+  }),
+  z.object({
+    type: z.literal("unlocked"),
+    instanceIds: z.array(z.string()),
+  }),
+])

package/src/shared/{operation.ts → models/project/operation.ts}

@@ -1,4 +1,5 @@
 import { z } from "zod"
+import { objectMetaSchema } from "../base"
 
 export const operationTypeSchema = z.enum(["update", "preview", "destroy", "recreate", "refresh"])
 
@@ -8,6 +9,7 @@ export const operationStatusSchema = z.enum([
   "completed",
   "failed",
   "cancelled",
+  "failing",
 ])
 
 export const operationOptionsSchema = z.object({
@@ -81,18 +83,20 @@ export const operationOptionsSchema = z.object({
   refresh: z.boolean().default(false),
 })
 
-export const projectOperationRequestSchema = z.object({
+export const operationRequestSchema = z.object({
   projectId: z.string(),
   type: operationTypeSchema,
   instanceIds: z.array(z.string()),
   options: operationOptionsSchema.partial().optional(),
 })
 
-export const projectOperationSchema = z.object({
+export const operationSchema = z.object({
   id: z.string().uuid(),
+  meta: objectMetaSchema,
   status: operationStatusSchema,
 
-  projectId: z.string(),
+  error: z.string().nullable(),
+
   type: operationTypeSchema,
 
   requestedInstanceIds: z.array(z.string()),
@@ -100,19 +104,36 @@ export const projectOperationSchema = z.object({
   instanceIdsToUpdate: z.array(z.string()).default(() => []),
   instanceIdsToDestroy: z.array(z.string()).default(() => []),
 
-  options: operationOptionsSchema.default(() => ({})),
+  options: operationOptionsSchema,
 
-  error: z.string().nullable(),
   startedAt: z.number(),
   completedAt: z.number().nullable(),
 })
 
 export type OperationType = z.infer<typeof operationTypeSchema>
 export type OperationStatus = z.infer<typeof operationStatusSchema>
-export type ProjectOperation = z.infer<typeof projectOperationSchema>
-export type ProjectOperationRequest = z.infer<typeof projectOperationRequestSchema>
+export type Operation = z.infer<typeof operationSchema>
+export type OperationRequest = z.infer<typeof operationRequestSchema>
 export type OperationOptions = z.infer<typeof operationOptionsSchema>
 
 export function isFinalOperationStatus(status: OperationStatus): boolean {
   return status === "completed" || status === "failed" || status === "cancelled"
 }
+
+export const operationLogEntrySchema = z.tuple([
+  z.string().uuid(), // UUIDv7
+  z.string(), // The log message
+])
+
+export type OperationLogEntry = z.infer<typeof operationLogEntrySchema>
+
+export const operationEventSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("updated"),
+    operation: operationSchema,
+  }),
+  z.object({
+    type: z.literal("deleted"),
+    operationId: z.string(),
+  }),
+])

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

@@ -0,0 +1,57 @@
+import { z } from "zod"
+import { objectMetaSchema, userObjectMetaSchema } from "../base"
+import { fileSchema } from "./artifact"
+
+/**
+ * Page block schema for database storage and unit API.
+ */
+export const pageBlockSchema = 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(),
+  }),
+  fileSchema.extend({
+    type: z.literal("file"),
+  }),
+])
+
+export type PageBlock = z.infer<typeof pageBlockSchema>
+
+/**
+ * Page info for frontend display.
+ * Contains only basic information visible to the frontend.
+ */
+export const pageSchema = z.object({
+  id: z.string(),
+  instanceId: z.string().optional(),
+  meta: objectMetaSchema,
+})
+
+export type Page = z.infer<typeof pageSchema>
+
+/**
+ * The content of a page separated from the page info.
+ */
+export const pageContentSchema = z.object({
+  id: z.string(),
+  content: z.array(pageBlockSchema),
+})
+
+export type PageContent = z.infer<typeof pageContentSchema>
+
+/**
+ * Page schema for unit API.
+ * This is what units provide - excludes id, instanceId and some fields from meta since those are set by the system.
+ */
+export const unitPageSchema = pageContentSchema.omit({ id: true }).extend({
+  name: z.string(),
+  meta: userObjectMetaSchema,
+})
+
+export type UnitPage = z.infer<typeof unitPageSchema>