@qlever-llc/trellis 0.8.3 → 0.9.0-rc.10

package/src/env.ts

@@ -0,0 +1 @@
+export { getEnv } from "./telemetry/env.js";

package/src/errors/AuthError.ts

@@ -0,0 +1,82 @@
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.js";
+
+export const AuthErrorDataSchema = Type.Object({
+  id: Type.String(),
+  type: Type.Literal("AuthError"),
+  message: Type.String(),
+  reason: Type.Union([
+    Type.Literal("invalid_request"),
+    Type.Literal("missing_session_key"),
+    Type.Literal("missing_proof"),
+    Type.Literal("session_not_found"),
+    Type.Literal("session_expired"),
+    Type.Literal("invalid_signature"),
+    Type.Literal("user_not_found"),
+    Type.Literal("user_already_exists"),
+    Type.Literal("username_taken"),
+    Type.Literal("identity_already_exists"),
+    Type.Literal("identity_not_found"),
+    Type.Literal("user_inactive"),
+    Type.Literal("unknown_device"),
+    Type.Literal("device_deployment_not_found"),
+    Type.Literal("device_deployment_disabled"),
+    Type.Literal("device_activation_revoked"),
+    Type.Literal("unknown_service"),
+    Type.Literal("service_disabled"),
+    Type.Literal("iat_out_of_range"),
+    Type.Literal("invalid_binding_token"),
+    Type.Literal("session_corrupted"),
+    Type.Literal("session_already_bound"),
+    Type.Literal("authtoken_already_used"),
+    Type.Literal("oauth_session_key_mismatch"),
+    Type.Literal("reply_subject_mismatch"),
+    Type.Literal("insufficient_permissions"),
+    Type.Literal("reauth_required"),
+    Type.Literal("forbidden"),
+    Type.Literal("last_admin_required"),
+    Type.Literal("missing_flow_id"),
+    Type.Literal("device_activation_flow_not_found"),
+    Type.Literal("device_activation_flow_expired"),
+    Type.Literal("device_activation_rejected"),
+    Type.Literal("device_identity_key_mismatch"),
+    Type.Literal("invalid_device_qr_mac"),
+  ]),
+  context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  traceId: Type.Optional(Type.String()),
+});
+export type AuthErrorData = Static<typeof AuthErrorDataSchema>;
+
+/**
+ * Error for authentication and authorization failures.
+ */
+export class AuthError extends TrellisError<AuthErrorData> {
+  override readonly name = "AuthError" as const;
+  readonly reason: AuthErrorData["reason"];
+
+  constructor(
+    options: ErrorOptions & {
+      reason: AuthErrorData["reason"];
+      message?: string;
+      context?: Record<string, unknown>;
+      id?: string;
+    },
+  ) {
+    const { reason, message, ...baseOptions } = options;
+    super(message ?? `Auth failed: ${reason}`, baseOptions);
+    this.reason = reason;
+  }
+
+  /**
+   * Serializes error to a plain object.
+   *
+   * @returns Plain object representation of the error
+   */
+  override toSerializable(): AuthErrorData {
+    return {
+      ...this.baseSerializable(),
+      type: this.name,
+      reason: this.reason,
+    } as AuthErrorData;
+  }
+}

package/src/errors/KVError.ts

@@ -0,0 +1,47 @@
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.js";
+
+export const KVErrorDataSchema = Type.Object({
+  id: Type.String(),
+  type: Type.Literal("KVError"),
+  message: Type.String(),
+  operation: Type.Optional(Type.String()),
+  context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  traceId: Type.Optional(Type.String()),
+});
+export type KVErrorData = Static<typeof KVErrorDataSchema>;
+
+/**
+ * Error for KV storage operations.
+ * Used when key-value store operations fail.
+ */
+export class KVError extends TrellisError<KVErrorData> {
+  override readonly name = "KVError" as const;
+  readonly operation?: string;
+
+  constructor(
+    options: ErrorOptions & {
+      operation?: string;
+      context?: Record<string, unknown>;
+      id?: string;
+    },
+  ) {
+    const { operation, ...baseOptions } = options;
+    const msg = `KV ${operation || ""} failed`;
+    super(msg, baseOptions);
+    this.operation = operation;
+  }
+
+  /**
+   * Serializes error to a plain object.
+   *
+   * @returns Plain object representation of the error
+   */
+  override toSerializable(): KVErrorData {
+    return {
+      ...this.baseSerializable(),
+      type: this.name,
+      operation: this.operation,
+    } as KVErrorData;
+  }
+}

package/src/errors/RemoteError.ts

@@ -0,0 +1,111 @@
+import {
+  Result,
+  type UnexpectedError,
+  type UnexpectedErrorData,
+} from "@qlever-llc/result";
+import Type, { type Static } from "typebox";
+import { ParseError, Value } from "typebox/value";
+import type { AuthErrorData } from "./AuthError.js";
+import type { KVErrorData } from "./KVError.js";
+import type { StoreErrorData } from "./StoreError.js";
+import type { TrellisErrorData } from "../models/trellis/TrellisError.js";
+import { TrellisErrorDataSchema } from "../models/trellis/TrellisError.js";
+import type { TransportErrorData } from "./TransportError.js";
+import type { TransferErrorData } from "./TransferError.js";
+import { TrellisError } from "./TrellisError.js";
+import { ValidationError } from "./ValidationError.js";
+import type { ValidationErrorData } from "./ValidationError.js";
+
+export const RemoteErrorDataSchema = Type.Object({
+  id: Type.String(),
+  type: Type.Literal("RemoteError"),
+  message: Type.String(),
+  remoteError: Type.Any(),
+  context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  traceId: Type.Optional(Type.String()),
+});
+export type RemoteErrorData = Static<typeof RemoteErrorDataSchema>;
+
+export type TransportableTrellisErrorData =
+  | UnexpectedErrorData
+  | AuthErrorData
+  | ValidationErrorData
+  | KVErrorData
+  | StoreErrorData
+  | TransportErrorData
+  | TransferErrorData
+  | TrellisErrorData;
+
+/**
+ * Error for wrapping errors received from remote Trellis services.
+ * This is the only error type with parseJSON/parseObject methods for deserializing remote errors.
+ */
+export class RemoteError extends TrellisError<RemoteErrorData> {
+  override readonly name = "RemoteError" as const;
+  readonly remoteError: TransportableTrellisErrorData;
+
+  constructor(
+    options: ErrorOptions & {
+      error: TransportableTrellisErrorData;
+      context?: Record<string, unknown>;
+      id?: string;
+    },
+  ) {
+    const { error, ...baseOptions } = options;
+    super(`Remote error: ${error.message}`, baseOptions);
+    this.remoteError = error;
+  }
+
+  /**
+   * Serializes error to a plain object.
+   *
+   * @returns Plain object representation of the error
+   */
+  override toSerializable(): RemoteErrorData {
+    return {
+      ...this.baseSerializable(),
+      type: this.name,
+      remoteError: this.remoteError,
+    } as RemoteErrorData;
+  }
+
+  /**
+   * Parses and validates a plain object as TrellisErrorData.
+   * Use this to deserialize errors received from remote services.
+   *
+   * @param obj - Plain object to validate
+   * @returns Result containing validated TrellisError or a ValidationError or UnexpectedError
+   */
+  static parse(
+    data: unknown,
+  ): Result<TransportableTrellisErrorData, ValidationError | UnexpectedError> {
+    return Result.try(() => typeof data === "string" ? JSON.parse(data) : data)
+      .andThen(
+        (
+          obj: unknown,
+        ): Result<
+          TransportableTrellisErrorData,
+          ValidationError | UnexpectedError
+        > => {
+          const parseResult = Result.try(() =>
+            Value.Parse(TrellisErrorDataSchema, obj)
+          );
+          if (parseResult.isErr()) {
+            const cause = parseResult.error.cause;
+            if (cause instanceof ParseError) {
+              const errors = Value.Errors(TrellisErrorDataSchema, obj);
+              return Result.err(new ValidationError({ errors, cause }));
+            }
+            return Result.err(parseResult.error);
+          }
+          return Result.ok(parseResult.take() as TransportableTrellisErrorData);
+        },
+      );
+  }
+
+  /**
+   * Alias for parse() - parses JSON string or object as TrellisErrorData.
+   * @see parse
+   */
+  static parseJSON = RemoteError.parse;
+}

package/src/errors/StoreError.ts

@@ -0,0 +1,43 @@
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.js";
+
+export const StoreErrorDataSchema = Type.Object({
+  id: Type.String(),
+  type: Type.Literal("StoreError"),
+  message: Type.String(),
+  operation: Type.Optional(Type.String()),
+  context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  traceId: Type.Optional(Type.String()),
+});
+
+export type StoreErrorData = Static<typeof StoreErrorDataSchema>;
+
+export class StoreError extends TrellisError<StoreErrorData> {
+  override readonly name = "StoreError" as const;
+  readonly operation?: string;
+
+  constructor(
+    options: ErrorOptions & {
+      operation?: string;
+      context?: Record<string, unknown>;
+      id?: string;
+    },
+  ) {
+    const { operation, ...baseOptions } = options;
+    const message = `Store ${operation || ""} failed`;
+    super(message, baseOptions);
+    this.operation = operation;
+  }
+
+  override toSerializable(): StoreErrorData {
+    const base = this.baseSerializable();
+    return {
+      id: base.id,
+      type: this.name,
+      message: base.message,
+      ...(this.operation !== undefined ? { operation: this.operation } : {}),
+      ...(base.context !== undefined ? { context: base.context } : {}),
+      ...(base.traceId !== undefined ? { traceId: base.traceId } : {}),
+    };
+  }
+}

package/src/errors/TransferError.ts

@@ -0,0 +1,43 @@
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.js";
+
+export const TransferErrorDataSchema = Type.Object({
+  id: Type.String(),
+  type: Type.Literal("TransferError"),
+  message: Type.String(),
+  operation: Type.Optional(Type.String()),
+  context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  traceId: Type.Optional(Type.String()),
+});
+
+export type TransferErrorData = Static<typeof TransferErrorDataSchema>;
+
+export class TransferError extends TrellisError<TransferErrorData> {
+  override readonly name = "TransferError" as const;
+  readonly operation?: string;
+
+  constructor(
+    options: ErrorOptions & {
+      operation?: string;
+      context?: Record<string, unknown>;
+      id?: string;
+    },
+  ) {
+    const { operation, ...baseOptions } = options;
+    const message = `Transfer ${operation || "operation"} failed`;
+    super(message, baseOptions);
+    this.operation = operation;
+  }
+
+  override toSerializable(): TransferErrorData {
+    const base = this.baseSerializable();
+    return {
+      id: base.id,
+      type: this.name,
+      message: base.message,
+      ...(this.operation !== undefined ? { operation: this.operation } : {}),
+      ...(base.context !== undefined ? { context: base.context } : {}),
+      ...(base.traceId !== undefined ? { traceId: base.traceId } : {}),
+    };
+  }
+}

package/src/errors/TransportError.ts

@@ -0,0 +1,48 @@
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.js";
+
+export const TransportErrorDataSchema = Type.Object({
+  id: Type.String(),
+  type: Type.Literal("TransportError"),
+  message: Type.String(),
+  code: Type.String(),
+  hint: Type.String(),
+  context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  traceId: Type.Optional(Type.String()),
+});
+
+export type TransportErrorData = Static<typeof TransportErrorDataSchema>;
+
+/**
+ * Error for Trellis runtime transport failures.
+ */
+export class TransportError extends TrellisError<TransportErrorData> {
+  override readonly name = "TransportError" as const;
+  readonly code: string;
+  readonly hint: string;
+
+  constructor(
+    options: ErrorOptions & {
+      code: string;
+      message: string;
+      hint: string;
+      context?: Record<string, unknown>;
+      id?: string;
+      traceId?: string;
+    },
+  ) {
+    const { code, message, hint, ...baseOptions } = options;
+    super(message, baseOptions);
+    this.code = code;
+    this.hint = hint;
+  }
+
+  override toSerializable(): TransportErrorData {
+    return {
+      ...this.baseSerializable(),
+      type: this.name,
+      code: this.code,
+      hint: this.hint,
+    };
+  }
+}

package/src/errors/TrellisError.ts

@@ -0,0 +1,20 @@
+/**
+ * Base class for all Trellis-specific errors.
+ * Extends BaseError and relies on the traceId getter being configured via initTracing.
+ */
+import { BaseError, type BaseErrorSchema } from "@qlever-llc/result";
+
+/**
+ * Abstract base class for Trellis errors.
+ * Trellis errors automatically include traceId when initTracing() has been called
+ * and a span is active in the current context.
+ *
+ * The traceId integration is configured by the tracing module's initTracing() function,
+ * which sets up BaseError.traceIdGetter to retrieve the traceId from the active span.
+ */
+export abstract class TrellisError<
+  TData extends BaseErrorSchema = BaseErrorSchema,
+> extends BaseError<TData> {
+  // TrellisError inherits getTraceId() from BaseError which uses the static traceIdGetter.
+  // The traceIdGetter is configured by initTracing() in the tracing module.
+}

package/src/errors/ValidationError.ts

@@ -0,0 +1,80 @@
+import type { TLocalizedValidationError } from "typebox/error";
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.js";
+
+export type ValidationErrorInput =
+  | TLocalizedValidationError
+  | { path: string; message: string };
+
+type NormalizedError = { schemaPath: string; message: string };
+
+function normalizeError(e: ValidationErrorInput): NormalizedError {
+  if ("schemaPath" in e) {
+    return { schemaPath: e.schemaPath, message: e.message ?? "Invalid value" };
+  }
+  return { schemaPath: e.path, message: e.message };
+}
+
+/**
+ * Schema for validation issue in ValidationError.
+ */
+export const ValidationIssueSchema = Type.Object({
+  path: Type.String(),
+  message: Type.String(),
+});
+export type ValidationIssue = Static<typeof ValidationIssueSchema>;
+
+/**
+ * Schema for ValidationError serialization.
+ */
+export const ValidationErrorDataSchema = Type.Object({
+  id: Type.String(),
+  type: Type.Literal("ValidationError"),
+  message: Type.String(),
+  issues: Type.Array(ValidationIssueSchema),
+  context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  traceId: Type.Optional(Type.String()),
+});
+export type ValidationErrorData = Static<typeof ValidationErrorDataSchema>;
+
+/**
+ * Error for data validation failures.
+ * Includes schema validation and missing required data.
+ */
+export class ValidationError extends TrellisError<ValidationErrorData> {
+  override readonly name = "ValidationError" as const;
+  readonly #normalizedErrors: Array<NormalizedError>;
+
+  constructor(
+    options: ErrorOptions & {
+      errors: Iterable<ValidationErrorInput>;
+      context?: Record<string, unknown>;
+      id?: string;
+    },
+  ) {
+    const { errors: rawErrors, ...baseOptions } = options;
+    const errors = [...rawErrors].map(normalizeError);
+    const msg = errors
+      .map((e) => `Validation failed. ${e.schemaPath}: ${e.message}.`)
+      .join("\n");
+    super(msg.length ? msg : "Data validation failed.", baseOptions);
+    this.#normalizedErrors = errors;
+  }
+
+  /**
+   * Serializes error to a plain object.
+   * Transforms internal errors array to issues array for serialization.
+   *
+   * @returns Plain object representation of the error
+   */
+  override toSerializable(): ValidationErrorData {
+    return {
+      ...this.baseSerializable(),
+      type: this.name,
+      issues: this.#normalizedErrors.map((e) => ({
+        path: e.schemaPath,
+        message: e.message,
+      })),
+    } as ValidationErrorData;
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,195 @@
+import "../_dnt.polyfills.js";
+import {
+  UnexpectedError,
+  type UnexpectedErrorData,
+  UnexpectedErrorDataSchema,
+} from "@qlever-llc/result";
+import { schema } from "../contract_support/mod.js";
+import { AuthError } from "./AuthError.js";
+import type { AuthErrorData } from "./AuthError.js";
+import { AuthErrorDataSchema } from "./AuthError.js";
+import { ValidationError } from "./ValidationError.js";
+import type { ValidationErrorData } from "./ValidationError.js";
+import { ValidationErrorDataSchema } from "./ValidationError.js";
+import { RemoteError } from "./RemoteError.js";
+import { KVError } from "./KVError.js";
+import type { KVErrorData } from "./KVError.js";
+import { KVErrorDataSchema } from "./KVError.js";
+import { StoreError } from "./StoreError.js";
+import type { StoreErrorData } from "./StoreError.js";
+import { StoreErrorDataSchema } from "./StoreError.js";
+import { TransportError } from "./TransportError.js";
+import type { TransportErrorData } from "./TransportError.js";
+import { TransportErrorDataSchema } from "./TransportError.js";
+import { TransferError } from "./TransferError.js";
+import type { TransferErrorData } from "./TransferError.js";
+import { TransferErrorDataSchema } from "./TransferError.js";
+
+type RuntimeRpcErrorDesc = {
+  type: string;
+  schema?: unknown;
+  fromSerializable(data: unknown): Error;
+};
+
+export { UnexpectedError } from "@qlever-llc/result";
+export { TrellisError } from "./TrellisError.js";
+export { AuthError } from "./AuthError.js";
+export { ValidationError } from "./ValidationError.js";
+export { RemoteError } from "./RemoteError.js";
+export { KVError } from "./KVError.js";
+export { StoreError } from "./StoreError.js";
+export { TransportError } from "./TransportError.js";
+export { TransferError } from "./TransferError.js";
+
+export { type AuthErrorData, AuthErrorDataSchema } from "./AuthError.js";
+export {
+  type ValidationErrorData,
+  ValidationErrorDataSchema,
+  type ValidationIssue,
+  ValidationIssueSchema,
+} from "./ValidationError.js";
+export { type RemoteErrorData, RemoteErrorDataSchema } from "./RemoteError.js";
+export { type KVErrorData, KVErrorDataSchema } from "./KVError.js";
+export { type StoreErrorData, StoreErrorDataSchema } from "./StoreError.js";
+export {
+  type TransportErrorData,
+  TransportErrorDataSchema,
+} from "./TransportError.js";
+export {
+  type TransferErrorData,
+  TransferErrorDataSchema,
+} from "./TransferError.js";
+
+/**
+ * Single source of truth for all Trellis errors.
+ * This object is used for compile-time type inference.
+ */
+const TRANSPORTABLE_TRELLIS_ERRORS = {
+  UnexpectedError,
+  TransportError,
+  AuthError,
+  ValidationError,
+  KVError,
+  StoreError,
+  TransferError,
+} as const;
+
+const TRELLIS_ERRORS = {
+  ...TRANSPORTABLE_TRELLIS_ERRORS,
+  RemoteError,
+} as const;
+
+/**
+ * Compile-time mapping from error names to their instance types.
+ * Derived from TRELLIS_ERRORS to ensure types stay in sync with runtime.
+ */
+export type TrellisErrorMap = {
+  [K in keyof typeof TRELLIS_ERRORS]: InstanceType<(typeof TRELLIS_ERRORS)[K]>;
+};
+
+export type TransportableTrellisErrorMap = {
+  [K in keyof typeof TRANSPORTABLE_TRELLIS_ERRORS]: InstanceType<
+    (typeof TRANSPORTABLE_TRELLIS_ERRORS)[K]
+  >;
+};
+
+export type TrellisErrorName = keyof TransportableTrellisErrorMap;
+export type TrellisErrorInstance = TrellisErrorMap[TrellisErrorName];
+export type MapErrorNamesToTypes<T extends readonly TrellisErrorName[]> = {
+  [K in keyof T]: T[K] extends TrellisErrorName
+    ? TransportableTrellisErrorMap[T[K]]
+    : never;
+}[number];
+
+export const BUILTIN_RPC_ERRORS = {
+  UnexpectedError: {
+    type: "UnexpectedError",
+    schema: schema<UnexpectedErrorData>(UnexpectedErrorDataSchema),
+    fromSerializable(data: UnexpectedErrorData) {
+      return new UnexpectedError({
+        id: data.id,
+        context: data.context,
+        traceId: data.traceId,
+      });
+    },
+  },
+  AuthError: {
+    type: "AuthError",
+    schema: schema<AuthErrorData>(AuthErrorDataSchema),
+    fromSerializable(data: AuthErrorData) {
+      return new AuthError({
+        reason: data.reason,
+        message: data.message,
+        id: data.id,
+        context: data.context,
+      });
+    },
+  },
+  TransportError: {
+    type: "TransportError",
+    schema: schema<TransportErrorData>(TransportErrorDataSchema),
+    fromSerializable(data: TransportErrorData) {
+      return new TransportError({
+        code: data.code,
+        message: data.message,
+        hint: data.hint,
+        id: data.id,
+        context: data.context,
+        traceId: data.traceId,
+      });
+    },
+  },
+  ValidationError: {
+    type: "ValidationError",
+    schema: schema<ValidationErrorData>(ValidationErrorDataSchema),
+    fromSerializable(data: ValidationErrorData) {
+      return new ValidationError({
+        errors: data.issues.map((issue) => ({
+          path: issue.path,
+          message: issue.message,
+        })),
+        id: data.id,
+        context: data.context,
+      });
+    },
+  },
+  KVError: {
+    type: "KVError",
+    schema: schema<KVErrorData>(KVErrorDataSchema),
+    fromSerializable(data: KVErrorData) {
+      return new KVError({
+        operation: data.operation,
+        id: data.id,
+        context: data.context,
+      });
+    },
+  },
+  StoreError: {
+    type: "StoreError",
+    schema: schema<StoreErrorData>(StoreErrorDataSchema),
+    fromSerializable(data: StoreErrorData) {
+      return new StoreError({
+        operation: data.operation,
+        id: data.id,
+        context: data.context,
+      });
+    },
+  },
+  TransferError: {
+    type: "TransferError",
+    schema: schema<TransferErrorData>(TransferErrorDataSchema),
+    fromSerializable(data: TransferErrorData) {
+      return new TransferError({
+        operation: data.operation,
+        id: data.id,
+        context: data.context,
+      });
+    },
+  },
+} as const satisfies Record<string, RuntimeRpcErrorDesc>;
+
+export function getBuiltinRpcError(
+  type: string,
+): RuntimeRpcErrorDesc | undefined {
+  return BUILTIN_RPC_ERRORS[type as keyof typeof BUILTIN_RPC_ERRORS];
+}