@highstate/backend 0.9.18 → 0.9.19

package/src/shared/models/base.ts

@@ -1,41 +1,42 @@
 import type { ObjectMeta } from "@highstate/contract"
+import { constant, mapValues } from "remeda"
 import { z } from "zod"
 
 export function hasObjectMeta(value: unknown): value is { meta: ObjectMeta } {
   return typeof value === "object" && value !== null && "meta" in value
 }
 
+const sortBySchema = z.object({
+  key: z.string(),
+  order: z.enum(["asc", "desc"]),
+})
+
+export type GenericEntity = {
+  id: string
+  meta: ObjectMeta
+  createdAt?: Date
+}
+
 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.
+   * The sorting configuration for the results.
    *
-   * By default, "asc" is used.
+   * Can be a single sort field or an array of sort fields.
+   * Each sort field contains the key and order.
    */
-  sort: z.enum(["asc", "desc"]).default("asc"),
+  sortBy: z.array(sortBySchema).optional(),
 
   /**
-   * 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.
+   * The number of items to skip.
    *
-   * Cannot be used with `skip`.
+   * Defaults to 0 if not specified.
    */
-  cursor: z.string().optional(),
+  skip: z.number().int().nonnegative().default(0).optional(),
 
   /**
    * The count of documents to return.
@@ -43,14 +44,21 @@ export const collectionQuerySchema = z.object({
    * Defaults to 20 if not specified.
    * Maximum value is 100.
    */
-  count: z.number().int().nonnegative().max(100).optional(),
+  count: z.number().int().positive().max(100).default(20).optional(),
 })
 
 export type CollectionQuery = z.infer<typeof collectionQuerySchema>
 
+export function collectionQueryResult<TSchema extends z.ZodType>(schema: TSchema) {
+  return z.object({
+    items: z.array(schema),
+    total: z.number().int().nonnegative(),
+  })
+}
+
 export type CollectionQueryResult<T> = {
   /**
-   * The list of objects matching the query.
+   * The list of objects matching the query and restricted by pagination.
    */
   items: T[]
 
@@ -58,11 +66,17 @@ export type CollectionQueryResult<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
+/**
+ * Creates a selection object using the provided schema.
+ *
+ * It can be used in zod pick or prisma select.
+ *
+ * @param schema The Zod schema to create the selection object from.
+ */
+export function forSchema<TSchema extends z.ZodObject>(
+  schema: TSchema,
+): { [K in keyof TSchema["shape"]]: true } {
+  return mapValues(schema.shape, constant(true)) as { [K in keyof TSchema["shape"]]: true }
 }

package/src/shared/models/errors.ts

@@ -1,5 +1,86 @@
-export class AccessError extends Error {
+export class BackendError extends Error {
+  constructor(message: string, cause?: unknown) {
+    super(message, { cause })
+    this.name = "BackendError"
+  }
+}
+
+export class AccessError extends BackendError {
   constructor(message: string) {
     super(message)
+    this.name = "AccessError"
+  }
+}
+
+export class ProjectLockedError extends AccessError {
+  constructor(projectId: string) {
+    super(`The project with ID "${projectId}" is locked, decryption is not possible.`)
+  }
+}
+
+export class ProjectNotFoundError extends BackendError {
+  constructor(projectId: string) {
+    super(`Project with ID "${projectId}" not found.`)
+    this.name = "ProjectNotFoundError"
+  }
+}
+
+export class CannotDeleteLastUnlockMethodError extends BackendError {
+  constructor(projectId: string) {
+    super(`Refused to delete the last unlock method for project "${projectId}".`)
+    this.name = "CannotDeleteLastUnlockMethodError"
+  }
+}
+
+export class InstanceNotFoundError extends BackendError {
+  constructor(projectId: string, instanceId: string) {
+    super(`Instance with ID "${instanceId}" not found in project "${projectId}".`)
+    this.name = "InstanceNotFoundError"
+  }
+}
+
+export class InvalidInstanceKindError extends BackendError {
+  constructor(projectId: string, instanceId: string, expectedKind: string, actualKind: string) {
+    super(
+      `Instance "${instanceId}" in project "${projectId}" has kind "${actualKind}", but expected "${expectedKind}".`,
+    )
+    this.name = "InvalidInstanceKindError"
+  }
+}
+
+export class OperationNotFoundError extends BackendError {
+  constructor(projectId: string, operationId: string) {
+    super(`Operation with ID "${operationId}" not found in project "${projectId}".`)
+    this.name = "OperationNotFoundError"
+  }
+}
+
+export class InstanceLockLostError extends BackendError {
+  constructor(projectId: string, instanceIds: string[], token: string) {
+    super(
+      `Instance lock lost for instances [${instanceIds.join(", ")}] in project "${projectId}" with token "${token}".`,
+    )
+    this.name = "InstanceLockLostError"
+  }
+}
+
+export class InstanceStateNotFoundError extends BackendError {
+  constructor(projectId: string, instanceId: string) {
+    super(`State for instance with ID "${instanceId}" not found in project "${projectId}".`)
+    this.name = "InstanceStateNotFoundError"
+  }
+}
+
+export class InstanceLockedError extends BackendError {
+  constructor(projectId: string, instanceId: string) {
+    super(`Instance with ID "${instanceId}" in project "${projectId}" is locked.`)
+    this.name = "InstanceLockedError"
+  }
+}
+
+export class WorkerVersionNotFoundError extends BackendError {
+  constructor(projectId: string, workerVersionId: string) {
+    super(`Worker version with ID "${workerVersionId}" not found in project "${projectId}".`)
+    this.name = "WorkerVersionNotFoundError"
   }
 }

package/src/shared/models/index.ts

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

package/src/shared/models/prisma.ts

@@ -0,0 +1,36 @@
+import type * as contract from "@highstate/contract"
+import type * as shared from "../../shared"
+
+declare global {
+  namespace PrismaJson {
+    type LibrarySpec = shared.LibrarySpec
+    type CommonObjectMeta = contract.CommonObjectMeta
+
+    type PulumiBackendSpec = shared.PulumiBackendSpec
+
+    type ProjectModelStorageSpec = shared.ProjectModelStorageSpec
+
+    type InstanceId = contract.InstanceId
+    type NullableInstanceId = contract.InstanceId | null
+    type InstanceIds = contract.InstanceId[]
+    type InstanceModel = contract.InstanceModel
+
+    type InstanceArgs = Record<string, unknown>
+    type InstanceResolvedInputs = Record<string, contract.InstanceInput[]>
+    type UnlockMethodMeta = shared.UnlockMethodMeta
+    type ProjectUnlockSuite = shared.ProjectUnlockSuite
+
+    type InstanceStatusFields = contract.InstanceStatusField[]
+
+    type OperationMeta = shared.OperationMeta
+    type OperationOptions = shared.OperationOptions
+    type OperationPhase = shared.OperationPhase
+
+    type WorkerUnitRegistrationParams = Record<string, unknown>
+
+    type ServiceAccountMeta = contract.ServiceAccountMeta
+
+    type ApiKeyMeta = shared.ApiKeyMeta
+    type InstanceArtifactIds = Record<string, string[]>
+  }
+}

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

@@ -1,65 +1,43 @@
-import { z } from "zod"
-import { objectMetaSchema } from "@highstate/contract"
-
-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.uuidv7(),
-  meta: objectMetaSchema,
-
-  /**
-   * The 256-bit random token used to authenticate API requests.
-   */
-  token: z.string(),
-
-  /**
-   * The scopes granted to this API key.
-   */
-  scopes: z.array(projectAccessScope),
+import {
+  commonObjectMetaSchema,
+  objectMetaSchema,
+  serviceAccountMetaSchema,
+  z,
+} from "@highstate/contract"
+import { collectionQuerySchema } from "../base"
+import type { ServiceAccount } from "../../../database"
+
+export const apiKeyMetaSchema = objectMetaSchema
+  .pick({
+    title: true,
+    description: true,
+  })
+  .required({ title: true })
+
+export type ApiKeyMeta = z.infer<typeof apiKeyMetaSchema>
+
+export const apiKeyOutputSchema = z.object({
+  id: z.cuid2(),
+  meta: commonObjectMetaSchema,
+  serviceAccountId: z.cuid2(),
+  serviceAccountMeta: serviceAccountMetaSchema.nullable(),
+  createdAt: z.date(),
 })
 
-export type InstanceAction = z.infer<typeof instanceActionSchema>
-export type ProjectAccessScope = z.infer<typeof projectAccessScope>
-export type ProjectApiKey = z.infer<typeof projectApiKeySchema>
+export type ApiKeyOutput = z.infer<typeof apiKeyOutputSchema>
 
-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))
-}
+export const apiKeyQuerySchema = collectionQuerySchema.extend({
+  serviceAccountId: z.string().optional(),
+})
 
-type ActionDescriptionMap<TType extends ProjectAccessScope["type"] = ProjectAccessScope["type"]> = {
-  [K in TType]: Record<(ProjectAccessScope & { type: K })["actions"][number], string>
-}
+export type ApiKeyQuery = z.infer<typeof apiKeyQuerySchema>
 
-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.",
-  },
+export function toApiKeyOutput(
+  apiKey: Omit<ApiKeyOutput, "serviceAccountMeta">,
+  serviceAccount?: Pick<ServiceAccount, "meta"> | null,
+): ApiKeyOutput {
+  return {
+    ...apiKey,
+    serviceAccountMeta: serviceAccount?.meta ?? null,
+  }
 }

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

@@ -1,83 +1,23 @@
+import { commonObjectMetaSchema } from "@highstate/contract"
 import { z } from "zod"
-import { type FileMeta } from "@highstate/contract"
-import { objectMetaSchema } from "@highstate/contract"
+import { collectionQuerySchema } 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.uuidv7(),
-
-  meta: objectMetaSchema,
-
-  /**
-   * The SHA-256 hash of the artifact content before encryption.
-   */
+export const artifactOutputSchema = z.object({
+  id: z.cuid2(),
   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(),
+  meta: commonObjectMetaSchema,
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+
+export type ArtifactOutput = z.infer<typeof artifactOutputSchema>
 
-  /**
-   * The size of each chunk of the artifact which independently encrypted.
-   */
-  chunkSize: z.number(),
+export const artifactQuerySchema = collectionQuerySchema.extend({
+  stateId: z.string().optional(),
+  serviceAccountId: z.string().optional(),
+  terminalId: z.string().optional(),
+  pageId: z.string().optional(),
 })
 
-export type Artifact = z.infer<typeof artifactSchema>
+export type ArtifactQuery = z.infer<typeof artifactQuerySchema>

package/src/shared/models/project/custom-status.ts

@@ -0,0 +1,12 @@
+import { commonObjectMetaSchema } from "@highstate/contract"
+import { z } from "zod"
+
+export const instanceCustomStatusInputSchema = z.object({
+  name: z.string(),
+  meta: commonObjectMetaSchema,
+  value: z.string(),
+  message: z.string().optional(),
+  order: z.number().min(0).max(100).optional(),
+})
+
+export type InstanceCustomStatusInput = z.infer<typeof instanceCustomStatusInputSchema>

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

@@ -1,13 +1,14 @@
+export * from "./api-key"
+export * from "./artifact"
+export * from "./custom-status"
+export * from "./lock"
 export * from "./model"
-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 "./service-account"
+export * from "./state"
+export * from "./terminal"
+export * from "./trigger"
+export * from "./unlock-method"
 export * from "./worker"
-export * from "./api-key"

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

@@ -1,91 +1,23 @@
+import { commonObjectMetaSchema } from "@highstate/contract"
 import { z } from "zod"
-import { instanceIdSchema, objectMetaSchema } from "@highstate/contract"
 
-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(), z.string()).optional(),
-  }),
-])
-
-export const instanceLockSchema = z.object({
-  id: instanceIdSchema,
-  meta: objectMetaSchema,
-  spec: instanceLockSpecSchema,
+export const instanceLockOutputSchema = z.object({
+  stateId: z.cuid2(),
+  meta: commonObjectMetaSchema,
+  acquiredAt: z.date(),
 })
 
-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 type InstanceLockOutput = z.infer<typeof instanceLockOutputSchema>
 
 export const instanceLockEventSchema = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("locked"),
-    locks: z.array(instanceLockSchema),
+    locks: instanceLockOutputSchema.array(),
   }),
   z.object({
     type: z.literal("unlocked"),
-    instanceIds: z.array(z.string()),
+    stateIds: z.array(z.string()),
   }),
 ])
+
+export type InstanceLockEvent = z.infer<typeof instanceLockEventSchema>

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

@@ -1,14 +1,32 @@
-import { hubModelSchema, instanceIdSchema, instanceModelSchema } from "@highstate/contract"
+import {
+  type HubModel,
+  hubModelSchema,
+  type InstanceModel,
+  instanceIdSchema,
+  instanceModelSchema,
+} from "@highstate/contract"
 import { z } from "zod"
 
 export const projectModelEventSchema = z.object({
   updatedInstances: instanceModelSchema.array().optional(),
   updatedHubs: hubModelSchema.array().optional(),
   updatedVirtualInstances: instanceModelSchema.array().optional(),
+  updatedGhostInstances: instanceModelSchema.array().optional(),
 
   deletedInstanceIds: instanceIdSchema.array().optional(),
   deletedHubIds: z.string().array().optional(),
   deletedVirtualInstanceIds: instanceIdSchema.array().optional(),
+  deletedGhostInstanceIds: instanceIdSchema.array().optional(),
 })
 
 export type ProjectNodeEvent = z.infer<typeof projectModelEventSchema>
+
+export type ProjectModel = {
+  instances: InstanceModel[]
+  hubs: HubModel[]
+}
+
+export type FullProjectModel = ProjectModel & {
+  virtualInstances: InstanceModel[]
+  ghostInstances: InstanceModel[]
+}