@highstate/backend-api 0.27.0 → 0.29.0

package/src/shared/error-handling.test.ts

@@ -0,0 +1,138 @@
+import { Code, ConnectError } from "@connectrpc/connect"
+import { BadRequestSchema, ErrorInfoSchema } from "@highstate/api/v1"
+import {
+  BackendError,
+  BackendErrorCategory,
+  InvalidOperationPlanError,
+  InvalidPageSizeError,
+  PermissionDeniedError,
+} from "@highstate/backend/shared"
+import { describe, expect, it, vi } from "vitest"
+import { createErrorHandlingInterceptor } from "./error-handling"
+
+describe("createErrorHandlingInterceptor", () => {
+  it("maps backend errors to structured details", async () => {
+    const logger = { error: vi.fn() }
+    const interceptor = createErrorHandlingInterceptor({ logger } as never)
+    const handler = interceptor(async () => {
+      throw new InvalidPageSizeError(-1)
+    })
+
+    try {
+      await handler({
+        method: { name: "ListOperations" },
+        header: new Headers({ "x-request-id": "request-1" }),
+      } as never)
+      expect.fail("Expected handler to throw")
+    } catch (error) {
+      expect(error).toBeInstanceOf(ConnectError)
+      const connectError = error as ConnectError
+      expect(connectError.code).toBe(Code.InvalidArgument)
+      expect(connectError.findDetails(ErrorInfoSchema)[0]?.reason).toBe("PAGE_SIZE_INVALID")
+      expect(connectError.findDetails(BadRequestSchema)[0]?.fieldViolations[0]?.field).toBe(
+        "page_size",
+      )
+      expect(logger.error).not.toHaveBeenCalled()
+    }
+  })
+
+  it("exposes operation planning validation errors", async () => {
+    const logger = { error: vi.fn() }
+    const interceptor = createErrorHandlingInterceptor({ logger } as never)
+    const handler = interceptor(async () => {
+      throw new InvalidOperationPlanError(
+        "Operation options are invalid: ghost options are supported only for updates",
+      )
+    })
+
+    const result = (await handler({
+      method: { name: "PlanOperation" },
+      header: new Headers(),
+    } as never).catch(error => error as ConnectError)) as ConnectError
+
+    expect(result.code).toBe(Code.InvalidArgument)
+    expect(result.rawMessage).toBe(
+      "Operation options are invalid: ghost options are supported only for updates",
+    )
+    expect(result.findDetails(ErrorInfoSchema)[0]?.reason).toBe("OPERATION_PLAN_INVALID")
+    expect(logger.error).not.toHaveBeenCalled()
+  })
+
+  it("sanitizes and logs unexpected errors once", async () => {
+    const logger = { error: vi.fn() }
+    const interceptor = createErrorHandlingInterceptor({ logger } as never)
+    const handler = interceptor(async () => {
+      throw new Error("sensitive internal path")
+    })
+
+    await expect(
+      handler({ method: { name: "GetProject" }, header: new Headers() } as never),
+    ).rejects.toMatchObject({ code: Code.Internal, rawMessage: "An unexpected error occurred" })
+    expect(logger.error).toHaveBeenCalledOnce()
+  })
+
+  it("preserves cancellation without domain details", async () => {
+    const logger = { error: vi.fn() }
+    const cancellation = new ConnectError("Canceled", Code.Canceled)
+    const interceptor = createErrorHandlingInterceptor({ logger } as never)
+    const handler = interceptor(async () => {
+      throw cancellation
+    })
+
+    await expect(
+      handler({ method: { name: "Connect" }, header: new Headers() } as never),
+    ).rejects.toBe(cancellation)
+    expect(logger.error).not.toHaveBeenCalled()
+  })
+
+  it("preserves unauthenticated and permission-denied classifications without secret metadata", async () => {
+    for (const error of [
+      new BackendErrorForTest("Authentication required", BackendErrorCategory.Unauthenticated),
+      new PermissionDeniedError("project.get"),
+    ]) {
+      const interceptor = createErrorHandlingInterceptor({ logger: { error: vi.fn() } } as never)
+      const handler = interceptor(async () => {
+        throw error
+      })
+
+      await expect(
+        handler({ method: { name: "GetProject" }, header: new Headers() } as never),
+      ).rejects.toMatchObject({
+        code:
+          error.category === BackendErrorCategory.Unauthenticated
+            ? Code.Unauthenticated
+            : Code.PermissionDenied,
+      })
+    }
+
+    const secret = new BackendErrorForTest(
+      "Authentication failed",
+      BackendErrorCategory.Unauthenticated,
+      {
+        token: "plaintext-token",
+        safe: "value",
+      },
+    )
+    const interceptor = createErrorHandlingInterceptor({ logger: { error: vi.fn() } } as never)
+    const handler = interceptor(async () => {
+      throw secret
+    })
+    const result = (await handler({
+      method: { name: "GetProject" },
+      header: new Headers(),
+    } as never).catch(error => error as ConnectError)) as ConnectError
+
+    expect(result.findDetails(ErrorInfoSchema)[0]?.metadata).toEqual({ safe: "value" })
+    expect(result.rawMessage).not.toContain("plaintext-token")
+  })
+})
+
+class BackendErrorForTest extends BackendError {
+  constructor(
+    message: string,
+    category: BackendErrorCategory,
+    metadata: Record<string, string> = {},
+  ) {
+    super(message, { category, reason: "AUTHENTICATION_FAILED", metadata })
+  }
+}

package/src/shared/error-handling.ts

@@ -1,27 +1,140 @@
+import type { GenMessage } from "@bufbuild/protobuf/codegenv2"
 import type { Services } from "@highstate/backend"
-import { AccessError } from "@highstate/backend/shared"
+import { create, type Message } from "@bufbuild/protobuf"
+import { durationFromMs } from "@bufbuild/protobuf/wkt"
+import { Code, ConnectError, type Interceptor } from "@connectrpc/connect"
+import {
+  BadRequestSchema,
+  ErrorInfoSchema,
+  PreconditionFailureSchema,
+  RequestInfoSchema,
+  RetryInfoSchema,
+} from "@highstate/api/v1"
+import { BackendError, BackendErrorCategory } from "@highstate/backend/shared"
 import { isAbortError } from "abort-controller-x"
-import { type CallContext, ServerError, type ServerMiddlewareCall, Status } from "nice-grpc-common"
 
-export function createErrorHandlingMiddleware(services: Services) {
-  return async function* errorHandlingMiddleware<TRequest, TResponse>(
-    call: ServerMiddlewareCall<TRequest, TResponse>,
-    context: CallContext,
-  ) {
+const sensitiveMetadataKey = /credential|token|secret|encrypted|cause|stack|path/i
+
+type OutgoingDetail = { desc: GenMessage<Message>; value: Message }
+
+/**
+ * Creates the interceptor that translates backend failures into API errors.
+ *
+ * @param services The backend services used for error logging.
+ * @returns An interceptor that translates backend failures into API errors.
+ */
+export function createErrorHandlingInterceptor(services: Services): Interceptor {
+  return next => async request => {
     try {
-      return yield* call.next(call.request, context)
+      return await next(request)
     } catch (error) {
-      if (error instanceof ServerError || isAbortError(error)) {
+      if (isAbortError(error) || (error instanceof ConnectError && error.code === Code.Canceled)) {
         throw error
       }
 
-      if (error instanceof AccessError) {
-        services.logger.info({ error }, "access denied")
-        throw new ServerError(Status.UNAUTHENTICATED, "Access denied")
+      if (error instanceof BackendError) {
+        const code = categoryToCode(error.category)
+        if (code === Code.Internal) {
+          services.logger.error({ error, method: request.method.name }, "unexpected backend error")
+          throw new ConnectError("An unexpected error occurred", Code.Internal)
+        }
+
+        throw new ConnectError(error.message, code, undefined, backendErrorDetails(error, request))
+      }
+
+      if (error instanceof ConnectError) {
+        throw error
       }
 
-      services.logger.error({ error }, "unexpected error")
-      throw new ServerError(Status.INTERNAL, "An unexpected error occurred")
+      services.logger.error({ error, method: request.method.name }, "unexpected error")
+      throw new ConnectError("An unexpected error occurred", Code.Internal)
     }
   }
 }
+
+function backendErrorDetails(
+  error: BackendError,
+  request: Parameters<Parameters<Interceptor>[0]>[0],
+): OutgoingDetail[] {
+  const details: OutgoingDetail[] = [
+    {
+      desc: ErrorInfoSchema,
+      value: create(ErrorInfoSchema, {
+        reason: error.reason,
+        domain: "highstate.io",
+        metadata: Object.fromEntries(
+          Object.entries(error.metadata).filter(([key]) => !sensitiveMetadataKey.test(key)),
+        ),
+      }),
+    },
+  ]
+
+  if (error.fieldViolations.length > 0) {
+    details.push({
+      desc: BadRequestSchema,
+      value: create(BadRequestSchema, {
+        fieldViolations: error.fieldViolations.map(violation => ({
+          field: toProtobufPath(violation.field),
+          reason: violation.reason,
+          description: violation.description,
+        })),
+      }),
+    })
+  }
+
+  if (error.preconditionViolations.length > 0) {
+    details.push({
+      desc: PreconditionFailureSchema,
+      value: create(PreconditionFailureSchema, {
+        violations: error.preconditionViolations.map(violation => ({ ...violation })),
+      }),
+    })
+  }
+
+  if (error.retry && Number.isFinite(error.retry.delayMs) && error.retry.delayMs >= 0) {
+    details.push({
+      desc: RetryInfoSchema,
+      value: create(RetryInfoSchema, { retryDelay: durationFromMs(error.retry.delayMs) }),
+    })
+  }
+
+  const requestId = request.header.get("x-request-id")?.trim()
+  if (requestId) {
+    details.push({
+      desc: RequestInfoSchema,
+      value: create(RequestInfoSchema, { requestId }),
+    })
+  }
+
+  return details
+}
+
+function toProtobufPath(path: string): string {
+  return path
+    .split(".")
+    .map(segment => segment.replace(/[A-Z]/g, character => `_${character.toLowerCase()}`))
+    .join(".")
+}
+
+function categoryToCode(category: BackendErrorCategory): Code {
+  switch (category) {
+    case BackendErrorCategory.InvalidArgument:
+      return Code.InvalidArgument
+    case BackendErrorCategory.Unauthenticated:
+      return Code.Unauthenticated
+    case BackendErrorCategory.PermissionDenied:
+      return Code.PermissionDenied
+    case BackendErrorCategory.NotFound:
+      return Code.NotFound
+    case BackendErrorCategory.AlreadyExists:
+      return Code.AlreadyExists
+    case BackendErrorCategory.FailedPrecondition:
+      return Code.FailedPrecondition
+    case BackendErrorCategory.Aborted:
+      return Code.Aborted
+    case BackendErrorCategory.Unavailable:
+      return Code.Unavailable
+    case BackendErrorCategory.Internal:
+      return Code.Internal
+  }
+}

package/src/shared/field-mask.test.ts

@@ -0,0 +1,37 @@
+import { create } from "@bufbuild/protobuf"
+import { FieldMaskSchema } from "@bufbuild/protobuf/wkt"
+import { ConnectError } from "@connectrpc/connect"
+import { BadRequestSchema, InstanceSchema } from "@highstate/api/v1"
+import { describe, expect, it } from "vitest"
+import { validateUpdateMask } from "./field-mask"
+
+const mutablePaths = new Set(["arguments", "position", "position.x", "position.y"])
+
+describe("validateUpdateMask", () => {
+  it("normalizes JSON and TypeScript field names to Protobuf paths", () => {
+    const paths = validateUpdateMask(
+      create(FieldMaskSchema, { paths: ["position.x", "arguments"] }),
+      InstanceSchema,
+      mutablePaths,
+    )
+
+    expect(paths).toEqual(["position.x", "arguments"])
+  })
+
+  it.each([
+    { paths: [] },
+    { paths: ["*"] },
+    { paths: ["id"] },
+    { paths: ["inputs.values"] },
+    { paths: ["arguments.value"] },
+  ])("rejects invalid paths %j", ({ paths }) => {
+    try {
+      validateUpdateMask(create(FieldMaskSchema, { paths }), InstanceSchema, mutablePaths)
+      expect.fail("Expected update mask validation to fail")
+    } catch (error) {
+      expect(error).toBeInstanceOf(ConnectError)
+      const connectError = error as ConnectError
+      expect(connectError.findDetails(BadRequestSchema)).toHaveLength(1)
+    }
+  })
+})

package/src/shared/field-mask.ts

@@ -0,0 +1,81 @@
+import type { Message } from "@bufbuild/protobuf"
+import type { GenMessage } from "@bufbuild/protobuf/codegenv2"
+import type { FieldMask } from "@bufbuild/protobuf/wkt"
+import { Code, type ConnectError } from "@connectrpc/connect"
+import { createApiError } from "./api-error"
+
+/**
+ * Validates and normalizes a request update mask.
+ *
+ * @param mask The update mask to validate.
+ * @param schema The protobuf schema used to normalize field names.
+ * @param mutablePaths The set of fields that may be updated.
+ * @returns The normalized mutable field paths.
+ */
+export function validateUpdateMask<T extends Message>(
+  mask: FieldMask | undefined,
+  schema: GenMessage<T>,
+  mutablePaths: ReadonlySet<string>,
+): string[] {
+  if (!mask || mask.paths.length === 0) {
+    throw fieldMaskError("update_mask", "REQUIRED", "The update mask must not be empty")
+  }
+
+  const paths = new Set<string>()
+  for (const path of mask.paths) {
+    const normalized = normalizePath(schema, path)
+    if (!mutablePaths.has(normalized)) {
+      throw fieldMaskError(
+        `update_mask.paths`,
+        "IMMUTABLE_OR_UNKNOWN",
+        `The path "${path}" is unknown, immutable, output-only, or traverses a collection`,
+      )
+    }
+    paths.add(normalized)
+  }
+
+  return [...paths]
+}
+
+function normalizePath<T extends Message>(schema: GenMessage<T>, path: string): string {
+  if (!path || path === "*") return path
+
+  let descriptor = schema
+  const normalized: string[] = []
+  const segments = path.split(".")
+
+  for (const [index, segment] of segments.entries()) {
+    const field = descriptor.fields.find(
+      candidate =>
+        candidate.name === segment ||
+        candidate.localName === segment ||
+        candidate.jsonName === segment,
+    )
+    if (!field) return path
+
+    normalized.push(field.name)
+    if (index === segments.length - 1) break
+    if (field.fieldKind !== "message" || !field.message) return path
+
+    descriptor = field.message as GenMessage<T>
+  }
+
+  return normalized.join(".")
+}
+
+/**
+ * Creates an API error describing an invalid update-mask field.
+ *
+ * @param field The field containing the violation.
+ * @param reason The reason the field is invalid.
+ * @param description The human-readable explanation of the violation.
+ * @returns The API error describing the invalid field.
+ */
+export function fieldMaskError(field: string, reason: string, description: string): ConnectError {
+  return createApiError({
+    message: "Invalid update mask",
+    code: Code.InvalidArgument,
+    reason: "UPDATE_MASK_INVALID",
+    fieldViolations: [{ field, reason, description }],
+  })
+}

package/src/shared/index.ts

@@ -1,3 +1,8 @@
+export * from "./api-error"
 export * from "./authentication"
+export * from "./authorization-header"
+export * from "./conversion"
 export * from "./error-handling"
+export * from "./field-mask"
+export * from "./serialization"
 export * from "./validation"

package/src/shared/serialization.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest"
+import { toJsonObject } from "./serialization"
+
+describe("toJsonObject", () => {
+  it("normalizes dates and removes undefined values", () => {
+    expect(
+      toJsonObject({
+        createdAt: new Date("2026-08-22T12:00:00.000Z"),
+        omitted: undefined,
+        nested: [{ value: 1 }],
+      }),
+    ).toEqual({
+      createdAt: "2026-08-22T12:00:00.000Z",
+      nested: [{ value: 1 }],
+    })
+  })
+})

package/src/shared/serialization.ts

@@ -0,0 +1,35 @@
+import type { JsonObject } from "@bufbuild/protobuf"
+
+/**
+ * Converts a structured value into a protobuf JSON object.
+ *
+ * @param value The structured value to convert.
+ * @returns The corresponding protobuf JSON object.
+ */
+export function toJsonObject(value: object): JsonObject {
+  return normalizeJsonValue(value) as JsonObject
+}
+
+function normalizeJsonValue(value: unknown): unknown {
+  if (value instanceof Date) {
+    return value.toISOString()
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(normalizeJsonValue)
+  }
+
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).flatMap(([key, entry]) => {
+        if (entry === undefined) {
+          return []
+        }
+
+        return [[key, normalizeJsonValue(entry)]]
+      }),
+    )
+  }
+
+  return value
+}

package/src/shared/validation.ts

@@ -1,6 +1,15 @@
 import type { z } from "zod"
-import { ServerError, Status } from "nice-grpc-common"
+import { Code } from "@connectrpc/connect"
+import { createApiError } from "./api-error"
 
+/**
+ * Parses and validates a named request argument.
+ *
+ * @param request The request containing the argument.
+ * @param argumentName The name of the argument to validate.
+ * @param schema The schema used to validate the argument.
+ * @returns The validated argument value.
+ */
 export function parseArgument<
   TRequest,
   TArgumentName extends string & keyof TRequest,
@@ -8,11 +17,42 @@ export function parseArgument<
 >(request: TRequest, argumentName: TArgumentName, schema: TSchema): z.infer<TSchema> {
   const result = schema.safeParse(request[argumentName])
   if (!result.success) {
-    throw new ServerError(
-      Status.INVALID_ARGUMENT,
-      `Invalid argument "${argumentName}": ${result.error.message}`,
-    )
+    throw validationError(`Invalid argument "${argumentName}"`, argumentName, result.error)
   }
 
   return result.data
 }
+
+/**
+ * Parses and validates an arbitrary value.
+ *
+ * @param value The value to validate.
+ * @param name The name used in validation errors.
+ * @param schema The schema used to validate the value.
+ * @returns The validated value.
+ */
+export function parseValue<TSchema extends z.ZodType>(
+  value: unknown,
+  name: string,
+  schema: TSchema,
+): z.infer<TSchema> {
+  const result = schema.safeParse(value)
+  if (!result.success) {
+    throw validationError(`Invalid ${name}`, name, result.error)
+  }
+
+  return result.data
+}
+
+function validationError(message: string, field: string, error: z.ZodError) {
+  return createApiError({
+    message,
+    code: Code.InvalidArgument,
+    reason: "REQUEST_INVALID",
+    fieldViolations: error.issues.map(issue => ({
+      field: [field, ...issue.path.map(String)].join("."),
+      reason: issue.code.toUpperCase(),
+      description: issue.message,
+    })),
+  })
+}

package/src/handlers/instance.ts

@@ -1,44 +0,0 @@
-import type { InstanceServiceImplementation } from "@highstate/api/instance.v1"
-import type { Services } from "@highstate/backend"
-import { instanceCustomStatusInputSchema } from "@highstate/backend/shared"
-import { z } from "@highstate/contract"
-import { authenticate, parseArgument } from "../shared"
-
-export function createInstanceService(services: Services): InstanceServiceImplementation {
-  return {
-    async updateCustomStatus(request, context) {
-      const [projectId, apiKey] = await authenticate(services, context)
-
-      // TODO: validate instance access
-
-      const stateId = parseArgument(request, "stateId", z.cuid2())
-      const customStatus = parseArgument(request, "status", instanceCustomStatusInputSchema)
-
-      await services.instanceStateService.updateCustomStatus(
-        projectId,
-        stateId,
-        apiKey.serviceAccountId,
-        customStatus,
-      )
-
-      return {}
-    },
-
-    async removeCustomStatus(request, context) {
-      const [projectId, apiKey] = await authenticate(services, context)
-
-      // TODO: validate instance access
-
-      const stateId = parseArgument(request, "stateId", z.cuid2())
-
-      await services.instanceStateService.removeCustomStatus(
-        projectId,
-        stateId,
-        apiKey.serviceAccountId,
-        request.statusName,
-      )
-
-      return {}
-    },
-  }
-}