@highstate/backend-api 0.26.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highstate/backend-api",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "type": "module",
   "files": [
     "dist",
@@ -23,6 +23,7 @@
   },
   "scripts": {
     "build": "highstate build",
+    "test": "bun run --bun vitest run",
     "typecheck": "tsgo --noEmit --skipLibCheck",
     "biome": "biome check --write --unsafe --error-on-warnings",
     "biome:check": "biome check --error-on-warnings"
@@ -40,19 +41,20 @@
     }
   },
   "dependencies": {
-    "@bufbuild/protobuf": "^2.6.1",
-    "@highstate/api": "0.25.0",
-    "@highstate/backend": "0.25.0",
-    "@highstate/cli": "0.25.0",
-    "@highstate/contract": "0.25.0",
+    "@bufbuild/protobuf": "^2.14.0",
+    "@connectrpc/connect": "^2.1.2",
+    "@connectrpc/connect-node": "^2.1.2",
+    "@highstate/api": "0.27.0",
+    "@highstate/backend": "0.27.0",
+    "@highstate/cli": "0.27.0",
+    "@highstate/contract": "0.27.0",
     "abort-controller-x": "^0.4.3",
-    "nice-grpc": "^2.1.12",
-    "nice-grpc-common": "^2.0.2",
     "zod": "^4.0.5"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.2.0",
-    "@typescript/native-preview": "^7.0.0-dev.20250920.1"
+    "@biomejs/biome": "2.5.0",
+    "@typescript/native-preview": "^7.0.0-dev.20250920.1",
+    "vitest": "^3.2.4"
   },
   "repository": {
     "url": "https://github.com/highstate-io/highstate"

package/src/handlers/instance-state.ts

@@ -0,0 +1,96 @@
+import type { ServiceImpl } from "@connectrpc/connect"
+import type { InstanceStateService } from "@highstate/api/v1"
+import type { Services } from "@highstate/backend"
+import { instanceCustomStatusInputSchema } from "@highstate/backend/shared"
+import { z } from "@highstate/contract"
+import {
+  authenticateProject,
+  parseArgument,
+  toInstanceCustomStatus,
+  toInstanceState,
+} from "../shared"
+
+export function createInstanceStateService(
+  services: Services,
+): ServiceImpl<typeof InstanceStateService> {
+  return {
+    async listInstanceStates(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const page = await services.instanceStateService.getInstanceStates(
+        requestContext,
+        {
+          includeEvaluationState: request.includeEvaluationState,
+          includeLastOperationState: request.includeLastOperationState,
+          includeParentInstanceId: request.includeParentInstanceId,
+          includeExtra: request.includeExtra,
+          loadCustomStatuses: request.includeCustomStatuses,
+        },
+        { pageSize: request.pageSize, pageToken: request.pageToken },
+      )
+
+      return { states: page.items.map(toInstanceState), nextPageToken: page.nextPageToken }
+    },
+
+    async getInstanceState(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const stateId = parseArgument(request, "stateId", z.cuid2())
+      const state = await services.instanceStateService.getInstanceStateOrThrow(
+        requestContext,
+        stateId,
+        {
+          includeEvaluationState: request.includeEvaluationState,
+          includeLastOperationState: request.includeLastOperationState,
+          includeParentInstanceId: request.includeParentInstanceId,
+          includeExtra: request.includeExtra,
+          loadCustomStatuses: request.includeCustomStatuses,
+        },
+      )
+
+      return { state: toInstanceState(state) }
+    },
+
+    async updateCustomStatus(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const stateId = parseArgument(request, "stateId", z.cuid2())
+      const customStatus = parseArgument(request, "status", instanceCustomStatusInputSchema)
+
+      await services.instanceStateService.updateCustomStatus(
+        requestContext,
+        stateId,
+        requestContext.subject.serviceAccountId,
+        customStatus,
+      )
+
+      const state = await services.instanceStateService.getInstanceStateOrThrow(
+        requestContext,
+        stateId,
+        { loadCustomStatuses: true },
+      )
+      const status = state.customStatuses?.find(
+        value =>
+          value.name === customStatus.name &&
+          value.serviceAccountId === requestContext.subject.serviceAccountId,
+      )
+      if (!status) {
+        throw new Error("Updated custom status was not returned by the backend")
+      }
+
+      return { status: toInstanceCustomStatus(status) }
+    },
+
+    async removeCustomStatus(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const stateId = parseArgument(request, "stateId", z.cuid2())
+      const statusName = parseArgument(request, "statusName", z.string().min(1))
+
+      await services.instanceStateService.removeCustomStatus(
+        requestContext,
+        stateId,
+        requestContext.subject.serviceAccountId,
+        statusName,
+      )
+
+      return {}
+    },
+  }
+}

package/src/handlers/library.ts

@@ -0,0 +1,63 @@
+import type { ServiceImpl } from "@connectrpc/connect"
+import type { Services } from "@highstate/backend"
+import { ComponentKind, type LibraryService } from "@highstate/api/v1"
+import { ComponentNotFoundError } from "@highstate/backend/shared"
+import { z } from "@highstate/contract"
+import { authenticateProject, parseArgument, toComponent, toLibrary } from "../shared"
+
+export function createLibraryService(services: Services): ServiceImpl<typeof LibraryService> {
+  return {
+    async getLibrary(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const library = await services.libraryService.getLibraryModel(requestContext, context.signal)
+
+      return {
+        library: toLibrary({
+          components: { ...library.components },
+          entities: { ...library.entities },
+        }),
+      }
+    },
+
+    async listComponents(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const page = await services.libraryService.getComponents(
+        requestContext,
+        { pageSize: request.pageSize, pageToken: request.pageToken },
+        context.signal,
+      )
+
+      return {
+        components: page.items.map(component => ({
+          type: component.type,
+          kind: component.kind === "unit" ? ComponentKind.UNIT : ComponentKind.COMPOSITE,
+          meta: {
+            title: component.meta.title,
+            description: component.meta.description,
+            color: component.meta.color,
+            icon: component.meta.icon,
+            iconColor: component.meta.iconColor,
+            secondaryIcon: component.meta.secondaryIcon,
+            secondaryIconColor: component.meta.secondaryIconColor,
+            category: component.meta.category,
+            defaultNamePrefix: component.meta.defaultNamePrefix,
+          },
+        })),
+        nextPageToken: page.nextPageToken,
+      }
+    },
+
+    async getComponent(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const type = parseArgument(request, "type", z.string().min(1))
+      const library = await services.libraryService.getLibraryModel(requestContext, context.signal)
+      const component = library.components[type]
+
+      if (!component) {
+        throw new ComponentNotFoundError(requestContext.projectId, type)
+      }
+
+      return { component: toComponent(component) }
+    },
+  }
+}

package/src/handlers/operation.ts

@@ -0,0 +1,108 @@
+import type { ServiceImpl } from "@connectrpc/connect"
+import type { OperationService } from "@highstate/api/v1"
+import type { Services } from "@highstate/backend"
+import { operationLaunchInputSchema, operationPlanInputSchema } from "@highstate/backend/shared"
+import { instanceIdSchema, z } from "@highstate/contract"
+import {
+  authenticateProject,
+  fromOperationPhase,
+  fromOperationType,
+  parseValue,
+  toOperation,
+  toOperationLog,
+  toOperationPhase,
+} from "../shared"
+
+export function createOperationService(services: Services): ServiceImpl<typeof OperationService> {
+  return {
+    async planOperation(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const input = parseValue(
+        { ...request, projectId: requestContext.projectId, type: fromOperationType(request.type) },
+        "request",
+        operationPlanInputSchema,
+      )
+      const phases = await services.operationManager.plan(input)
+
+      return { phases: phases.map(toOperationPhase) }
+    },
+
+    async launchOperation(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const input = parseValue(
+        {
+          ...request,
+          projectId: requestContext.projectId,
+          type: fromOperationType(request.type),
+          plan: request.plan.length > 0 ? request.plan.map(fromOperationPhase) : undefined,
+        },
+        "request",
+        operationLaunchInputSchema,
+      )
+      const operation = await services.operationManager.launch(input)
+
+      return { operation: toOperation(operation) }
+    },
+
+    async getOperation(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const operationId = parseValue(request.operationId, "operationId", z.string().min(1))
+      const operation = await services.operationService.getOperationOrThrow(
+        requestContext,
+        operationId,
+      )
+
+      return { operation: toOperation(operation) }
+    },
+
+    async listOperations(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const page = await services.operationService.getOperations(requestContext, {
+        pageSize: request.pageSize,
+        pageToken: request.pageToken,
+      })
+
+      return { operations: page.items.map(toOperation), nextPageToken: page.nextPageToken }
+    },
+
+    async listOperationLogs(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const operationId = parseValue(request.operationId, "operationId", z.string().min(1))
+      const stateId = parseValue(request.stateId, "stateId", z.cuid2().optional())
+      await services.operationService.getOperationOrThrow(requestContext, operationId)
+
+      const page = await services.operationService.getOperationLogs(
+        requestContext,
+        operationId,
+        stateId,
+        { pageSize: request.pageSize, pageToken: request.pageToken },
+      )
+
+      return {
+        logs: page.items.map(log => toOperationLog(operationId, log)),
+        nextPageToken: page.nextPageToken,
+      }
+    },
+
+    async cancelOperation(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const operationId = parseValue(request.operationId, "operationId", z.string().min(1))
+      await services.operationService.getOperationOrThrow(requestContext, operationId)
+
+      services.operationManager.cancel(operationId)
+
+      return {}
+    },
+
+    async cancelInstanceOperation(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const operationId = parseValue(request.operationId, "operationId", z.string().min(1))
+      const instanceId = parseValue(request.instanceId, "instanceId", instanceIdSchema)
+      await services.operationService.getOperationOrThrow(requestContext, operationId)
+
+      services.operationManager.cancelInstance(operationId, instanceId)
+
+      return {}
+    },
+  }
+}

package/src/handlers/panel.ts

@@ -1,22 +1,23 @@
-import type { PanelServiceImplementation } from "@highstate/api/panel.v1"
+import type { ServiceImpl } from "@connectrpc/connect"
+import type { PanelService } from "@highstate/api/v1"
 import type { Services } from "@highstate/backend"
 import { panelInputSchema } from "@highstate/backend/shared"
 import { z } from "@highstate/contract"
-import { authenticate, parseArgument } from "../shared"
+import { authenticateProject, parseArgument } from "../shared"
 
-export function createPanelService(services: Services): PanelServiceImplementation {
+export function createPanelService(services: Services): ServiceImpl<typeof PanelService> {
   return {
     async setUnitPanels(request, context) {
-      const [projectId, apiKey] = await authenticate(services, context)
+      const requestContext = await authenticateProject(services, request, context)
       const workerVersionId = parseArgument(request, "workerVersionId", z.cuid2())
       const workerInstanceId = parseArgument(request, "workerInstanceId", z.cuid2())
       const stateId = parseArgument(request, "stateId", z.cuid2())
       const panels = parseArgument(request, "panels", z.array(panelInputSchema))
 
       const panelIds = await services.panelService.setUnitPanels(
-        projectId,
+        requestContext,
         stateId,
-        apiKey.id,
+        requestContext.subject.apiKeyId,
         workerVersionId,
         panels,
         workerInstanceId,

package/src/handlers/project-model.ts

@@ -0,0 +1,131 @@
+import type { ServiceImpl } from "@connectrpc/connect"
+import type { Services } from "@highstate/backend"
+import {
+  HubSchema,
+  InstanceSchema,
+  type ProjectModelService,
+  type UpdateHubRequest,
+  type UpdateInstanceRequest,
+} from "@highstate/api/v1"
+import { projectModelInstanceSchema } from "@highstate/backend/shared"
+import { hubModelSchema, instanceIdSchema, z } from "@highstate/contract"
+import {
+  authenticateProject,
+  fromHub,
+  fromInstance,
+  parseArgument,
+  parseValue,
+  toHub,
+  toHubPatch,
+  toInstance,
+  toInstancePatch,
+  toProjectModel,
+  validateUpdateMask,
+} from "../shared"
+
+type UpdateInstance = NonNullable<UpdateInstanceRequest["instance"]>
+type UpdateHub = NonNullable<UpdateHubRequest["hub"]>
+
+const instanceMutablePaths = new Set([
+  "arguments",
+  "inputs",
+  "hub_inputs",
+  "injection_inputs",
+  "position",
+  "position.x",
+  "position.y",
+])
+const hubMutablePaths = new Set([
+  "position",
+  "position.x",
+  "position.y",
+  "inputs",
+  "injection_inputs",
+])
+
+export function createProjectModelService(
+  services: Services,
+): ServiceImpl<typeof ProjectModelService> {
+  return {
+    async getProjectModel(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const [model] = await services.projectModelService.getProjectModel(requestContext, {
+        includeVirtualInstances: request.includeVirtualInstances,
+        includeGhostInstances: request.includeGhostInstances,
+      })
+
+      return { model: toProjectModel(model) }
+    },
+
+    async createNodes(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const instances = parseValue(
+        request.instances.map(fromInstance),
+        "instances",
+        projectModelInstanceSchema.array(),
+      )
+      const hubs = parseValue(request.hubs.map(fromHub), "hubs", hubModelSchema.array())
+
+      await services.projectService.createNodes(requestContext, instances, hubs)
+
+      return {}
+    },
+
+    async updateInstance(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const requestInstance = parseArgument(request, "instance", z.custom<UpdateInstance>())
+      const instanceId = parseArgument(requestInstance, "id", instanceIdSchema)
+      const paths = validateUpdateMask(request.updateMask, InstanceSchema, instanceMutablePaths)
+      const patch = toInstancePatch(requestInstance, paths)
+      const instance = await services.projectService.updateInstance(
+        requestContext,
+        instanceId,
+        patch,
+      )
+
+      return { instance: toInstance(instance) }
+    },
+
+    async renameInstance(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const instanceId = parseArgument(request, "instanceId", instanceIdSchema)
+      const newName = parseArgument(request, "newName", z.string().min(1))
+      const instance = await services.projectService.renameInstance(
+        requestContext,
+        instanceId,
+        newName,
+      )
+
+      return { instance: toInstance(instance) }
+    },
+
+    async deleteInstance(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const instanceId = parseArgument(request, "instanceId", instanceIdSchema)
+
+      await services.projectService.deleteInstance(requestContext, instanceId)
+
+      return {}
+    },
+
+    async updateHub(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const requestHub = parseArgument(request, "hub", z.custom<UpdateHub>())
+      const hubId = parseArgument(requestHub, "id", z.cuid2())
+      const paths = validateUpdateMask(request.updateMask, HubSchema, hubMutablePaths)
+      const patch = toHubPatch(requestHub, paths)
+      const hub = await services.projectService.updateHub(requestContext, hubId, patch)
+
+      return { hub: toHub(hub) }
+    },
+
+    async deleteHub(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const hubId = parseArgument(request, "hubId", z.cuid2())
+
+      await services.projectService.deleteHub(requestContext, hubId)
+
+      return {}
+    },
+  }
+}

package/src/handlers/project.ts

@@ -0,0 +1,46 @@
+import type { ServiceImpl } from "@connectrpc/connect"
+import type { ProjectService } from "@highstate/api/v1"
+import type { Services } from "@highstate/backend"
+import { authenticateBackend, authenticateProject, toProject } from "../shared"
+
+export function createProjectService(services: Services): ServiceImpl<typeof ProjectService> {
+  return {
+    async getProject(request, context) {
+      const requestContext = await authenticateProject(services, request, context)
+      const [project, unlockState] = await Promise.all([
+        services.projectService.getProjectOrThrowCore(requestContext.projectId),
+        services.projectUnlockService.getProjectUnlockStateCore(requestContext.projectId),
+      ])
+
+      return {
+        project: toProject(project),
+        isLocked: unlockState.type === "locked",
+      }
+    },
+
+    async listProjects(request, context) {
+      const requestContext = await authenticateBackend(services, context)
+      const result = await services.projectService.getProjects(requestContext, {
+        pageSize: request.pageSize,
+        pageToken: request.pageToken,
+      })
+      const projects = await Promise.all(
+        result.items.map(async project => {
+          const unlockState = await services.projectUnlockService.getProjectUnlockStateCore(
+            project.id,
+          )
+
+          return {
+            project: toProject(project),
+            isLocked: unlockState.type === "locked",
+          }
+        }),
+      )
+
+      return {
+        projects,
+        nextPageToken: result.nextPageToken,
+      }
+    },
+  }
+}

package/src/handlers/secret.ts

@@ -1,11 +1,12 @@
-import type { SecretServiceImplementation } from "@highstate/api/secret.v1"
+import type { ServiceImpl } from "@connectrpc/connect"
+import type { SecretService } from "@highstate/api/v1"
 import type { Services } from "@highstate/backend"
-import { authenticate } from "../shared"
+import { authenticateProject } from "../shared"
 
-export function createSecretService(services: Services): SecretServiceImplementation {
+export function createSecretService(services: Services): ServiceImpl<typeof SecretService> {
   return {
-    async getSecretContent(_request, context) {
-      const [_projectId] = await authenticate(services, context)
+    async getSecretContent(request, context) {
+      await authenticateProject(services, request, context)
 
       // TODO: validate secret access
 

package/src/handlers/worker.ts

@@ -1,31 +1,27 @@
-import type { WorkerServiceImplementation } from "@highstate/api/worker.v1"
+import type { ServiceImpl } from "@connectrpc/connect"
 import type { Services } from "@highstate/backend"
+import { create } from "@bufbuild/protobuf"
+import { ConnectResponseSchema, type WorkerService } from "@highstate/api/worker.v1"
+import { WorkerOwnershipError } from "@highstate/backend/shared"
 import { commonObjectMetaSchema, serviceAccountMetaSchema, z } from "@highstate/contract"
-import { authenticate, parseArgument } from "../shared"
+import { authenticateProject, parseArgument, toJsonObject } from "../shared"
 
-const workerMetaUpdatePayloadSchema = z.union([
-  commonObjectMetaSchema,
-  z.object({
-    workerMeta: commonObjectMetaSchema,
-    serviceAccountMeta: serviceAccountMetaSchema,
-  }),
-])
-
-export function createWorkerService(services: Services): WorkerServiceImplementation {
+export function createWorkerService(services: Services): ServiceImpl<typeof WorkerService> {
   return {
     async *connect(request, context) {
-      const [projectId, apiKey] = await authenticate(services, context)
+      const requestContext = await authenticateProject(services, request, context)
+      const { projectId } = requestContext
 
       const workerVersionId = parseArgument(request, "workerVersionId", z.cuid2())
       const workerInstanceId = parseArgument(request, "workerInstanceId", z.cuid2())
       const dataEndpoint = parseArgument(request, "dataEndpoint", z.string().min(1))
       const database = await services.database.forProject(projectId)
       const workerVersion = await database.workerVersion.findFirst({
-        where: { id: workerVersionId, apiKeyId: apiKey.id },
+        where: { id: workerVersionId, apiKeyId: requestContext.subject.apiKeyId },
         select: { id: true },
       })
       if (!workerVersion) {
-        throw new Error(`Worker version "${workerVersionId}" is not owned by the API key`)
+        throw new WorkerOwnershipError(projectId, workerVersionId)
       }
 
       services.workerManager.assertWorkerInstance(projectId, workerVersionId, workerInstanceId)
@@ -43,15 +39,15 @@ export function createWorkerService(services: Services): WorkerServiceImplementa
           select: { stateId: true, params: true },
         })
         for (const registration of existingRegistrations) {
-          yield {
+          yield create(ConnectResponseSchema, {
             event: {
-              $case: "unitRegistration",
+              case: "unitRegistration",
               value: {
                 stateId: registration.stateId,
-                params: registration.params,
+                params: toJsonObject(registration.params),
               },
             },
-          }
+          })
         }
         const registrationStream = await services.pubsubManager.subscribe([
           "worker-unit-registration",
@@ -60,19 +56,19 @@ export function createWorkerService(services: Services): WorkerServiceImplementa
         ])
         for await (const event of registrationStream) {
           if (event.type === "registered") {
-            yield {
+            yield create(ConnectResponseSchema, {
               event: {
-                $case: "unitRegistration",
-                value: { stateId: event.stateId, params: event.params },
+                case: "unitRegistration",
+                value: { stateId: event.stateId, params: toJsonObject(event.params) },
               },
-            }
+            })
           } else if (event.type === "deregistered") {
-            yield {
+            yield create(ConnectResponseSchema, {
               event: {
-                $case: "unitDeregistration",
+                case: "unitDeregistration",
                 value: { stateId: event.stateId },
               },
-            }
+            })
           }
         }
       } finally {
@@ -81,17 +77,18 @@ export function createWorkerService(services: Services): WorkerServiceImplementa
     },
 
     async updateWorkerVersionMeta(request, context) {
-      const [projectId] = await authenticate(services, context)
+      const requestContext = await authenticateProject(services, request, context)
 
       const workerVersionId = parseArgument(request, "workerVersionId", z.string())
-      const payload = parseArgument(request, "meta", workerMetaUpdatePayloadSchema)
-
-      const workerMeta = "workerMeta" in payload ? payload.workerMeta : payload
-      const serviceAccountMeta =
-        "serviceAccountMeta" in payload ? payload.serviceAccountMeta : undefined
+      const workerMeta = parseArgument(request, "workerMeta", commonObjectMetaSchema)
+      const serviceAccountMeta = parseArgument(
+        request,
+        "serviceAccountMeta",
+        serviceAccountMetaSchema.optional(),
+      )
 
       await services.workerService.updateWorkerVersionMeta(
-        projectId,
+        requestContext,
         workerVersionId,
         workerMeta,
         serviceAccountMeta,