@qlever-llc/trellis 0.10.22 → 0.11.0-rc.1

package/src/client_connect.ts

@@ -49,7 +49,12 @@ import {
   type TrellisOpts,
 } from "./trellis.js";
 import { TransportError } from "./errors/index.js";
-import { AsyncResult, Result, UnexpectedError } from "@qlever-llc/result";
+import {
+  AsyncResult,
+  BaseError,
+  Result,
+  UnexpectedError,
+} from "@qlever-llc/result";
 import { type StaticDecode, Type } from "typebox";
 import { Value } from "typebox/value";
 import {
@@ -62,6 +67,7 @@ import {
   observeNatsTrellisConnection,
   type TrellisConnection,
 } from "./connection.js";
+import { recordTrellisDuration } from "./telemetry/mod.js";
 
 type ClientContract<
   TApi extends TrellisAPI = TrellisAPI,
@@ -116,13 +122,19 @@ function createConnectedClient(args: {
 
 function clientConnectResult<T>(
   promise: Promise<T>,
-): AsyncResult<T, TransportError | UnexpectedError> {
+): AsyncResult<T, TransportError | UnexpectedError | ClientAuthHandledError> {
   return AsyncResult.from(
     promise.then(
-      (value): Result<T, TransportError | UnexpectedError> => Result.ok(value),
-      (cause): Result<T, TransportError | UnexpectedError> =>
+      (value): Result<
+        T,
+        TransportError | UnexpectedError | ClientAuthHandledError
+      > => Result.ok(value),
+      (
+        cause,
+      ): Result<T, TransportError | UnexpectedError | ClientAuthHandledError> =>
         Result.err(
-          cause instanceof TransportError
+          cause instanceof TransportError ||
+            cause instanceof ClientAuthHandledError
             ? cause
             : new UnexpectedError({ cause }),
         ),
@@ -166,13 +178,27 @@ export type ClientAuthContinuation =
   | { status: "handled" }
   | void;
 
+export type ClientAuthHandledErrorData = {
+  id: string;
+  type: "ClientAuthHandledError";
+  message: string;
+  context?: Record<string, unknown>;
+  traceId?: string;
+};
+
 /**
  * Error raised when client authentication was delegated to caller-owned routing.
  */
-export class ClientAuthHandledError extends Error {
+export class ClientAuthHandledError
+  extends BaseError<ClientAuthHandledErrorData> {
+  override readonly name = "ClientAuthHandledError" as const;
+
   constructor() {
     super("Client authentication was handled by the caller");
-    this.name = "ClientAuthHandledError";
+  }
+
+  override toSerializable(): ClientAuthHandledErrorData {
+    return this.baseSerializable() as ClientAuthHandledErrorData;
   }
 }
 
@@ -532,6 +558,7 @@ async function bindClientFlow(args: {
   flowId: string;
   sig: string;
 }): Promise<void> {
+  const startedAt = performance.now();
   const response = await fetch(
     `${args.trellisUrl}/auth/flow/${encodeURIComponent(args.flowId)}/bind`,
     {
@@ -596,6 +623,15 @@ async function bindClientFlow(args: {
       },
     });
   }
+  recordTrellisDuration(
+    "trellis.connect.duration",
+    performance.now() - startedAt,
+    {
+      phase: "bootstrap",
+      participantKind: "client",
+      outcome: "ok",
+    },
+  );
 }
 
 async function fetchClientBootstrap(args: {
@@ -604,6 +640,7 @@ async function fetchClientBootstrap(args: {
   bootstrapSig: string;
   iat: number;
 }): Promise<ClientBootstrapAttemptResponse> {
+  const startedAt = performance.now();
   const response = await fetch(`${args.trellisUrl}/bootstrap/client`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -639,12 +676,39 @@ async function fetchClientBootstrap(args: {
   }
 
   if (Value.Check(ClientBootstrapReadySchema, payload)) {
+    recordTrellisDuration(
+      "trellis.connect.duration",
+      performance.now() - startedAt,
+      {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+      },
+    );
     return payload;
   }
   if (Value.Check(ClientBootstrapAuthRequiredSchema, payload)) {
+    recordTrellisDuration(
+      "trellis.connect.duration",
+      performance.now() - startedAt,
+      {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+      },
+    );
     return payload;
   }
   if (Value.Check(ClientBootstrapNotReadySchema, payload)) {
+    recordTrellisDuration(
+      "trellis.connect.duration",
+      performance.now() - startedAt,
+      {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+      },
+    );
     return payload;
   }
 
@@ -678,6 +742,7 @@ async function fetchClientBootstrapWithRetry(args: {
   offsetState: ClockOffsetState;
 }): Promise<ClientBootstrapResponse> {
   for (let attempt = 0; attempt < 2; attempt += 1) {
+    const attemptStartedAt = performance.now();
     const requestStartedAtMs = args.deps.now();
     const iat = correctedIatSeconds(
       requestStartedAtMs,
@@ -690,6 +755,15 @@ async function fetchClientBootstrapWithRetry(args: {
       bootstrapSig: await args.identity.bootstrapSig(iat),
     });
     const responseReceivedAtMs = args.deps.now();
+    recordTrellisDuration(
+      "trellis.connect.duration",
+      performance.now() - attemptStartedAt,
+      {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+      },
+    );
 
     updateClockOffsetFromServer({
       offsetState: args.offsetState,
@@ -941,6 +1015,7 @@ async function buildSessionKeyLoginUrl(args: {
 }): Promise<
   { status: "bound" } | { status: "flow_started"; loginUrl: string }
 > {
+  const startedAt = performance.now();
   const context = authRequestContextRecord(args.context);
   let response = await fetch(`${args.trellisUrl}/auth/requests`, {
     method: "POST",
@@ -955,6 +1030,15 @@ async function buildSessionKeyLoginUrl(args: {
     }),
   });
   if (await authStartNeedsManifest(response)) {
+    recordTrellisDuration(
+      "trellis.connect.duration",
+      performance.now() - startedAt,
+      {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+      },
+    );
     response = await fetch(`${args.trellisUrl}/auth/requests`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -991,6 +1075,15 @@ async function buildSessionKeyLoginUrl(args: {
     (payload as { status?: unknown }).status === "flow_started" &&
     typeof (payload as { loginUrl?: unknown }).loginUrl === "string"
   ) {
+    recordTrellisDuration(
+      "trellis.connect.duration",
+      performance.now() - startedAt,
+      {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+      },
+    );
     return {
       status: "flow_started",
       loginUrl: (payload as { loginUrl: string }).loginUrl,
@@ -1000,6 +1093,15 @@ async function buildSessionKeyLoginUrl(args: {
     payload && typeof payload === "object" &&
     (payload as { status?: unknown }).status === "bound"
   ) {
+    recordTrellisDuration(
+      "trellis.connect.duration",
+      performance.now() - startedAt,
+      {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+      },
+    );
     return { status: "bound" };
   }
   throw createTransportError({
@@ -1039,6 +1141,7 @@ export async function connectClientWithDeps<
   args: ClientConnectArgsFor<TContract>,
   deps: ClientConnectDeps,
 ): Promise<Trellis<TrellisAPI, "client", RuntimeStateStores>> {
+  const totalStartedAt = performance.now();
   const trellisUrl = normalizeTrellisUrl(args.trellisUrl);
   const identity = await resolveClientIdentity(args.auth);
   const currentUrl = args.auth?.mode === "session_key"
@@ -1082,6 +1185,7 @@ export async function connectClientWithDeps<
     }
   }
 
+  const initialBootstrapStartedAt = performance.now();
   const initialBootstrap = await fetchClientBootstrapWithRetry({
     trellisUrl,
     sessionKey: identity.sessionKey,
@@ -1089,11 +1193,30 @@ export async function connectClientWithDeps<
     deps,
     offsetState,
   });
+  recordTrellisDuration(
+    "trellis.connect.duration",
+    performance.now() - initialBootstrapStartedAt,
+    {
+      phase: "bootstrap",
+      participantKind: "client",
+      outcome: "ok",
+    },
+  );
 
+  const authStartedAt = performance.now();
   const bootstrap = needsReauth(initialBootstrap) ||
       !bootstrapTargetsRequestedContract(initialBootstrap, args)
     ? await resolveAuthRequired(args, identity, currentUrl, deps, offsetState)
     : initialBootstrap;
+  recordTrellisDuration(
+    "trellis.connect.duration",
+    performance.now() - authStartedAt,
+    {
+      phase: "auth_resolution",
+      participantKind: "client",
+      outcome: "ok",
+    },
+  );
 
   if (bootstrap.status !== "ready") {
     if (bootstrap.status === "not_ready") {
@@ -1189,6 +1312,7 @@ export async function connectClientWithDeps<
   });
   let nc: NatsConnection;
   try {
+    const natsStartedAt = performance.now();
     nc = await transport.connect({
       servers: selectClientRuntimeTransportServers(
         bootstrap.connectInfo.transports,
@@ -1197,6 +1321,15 @@ export async function connectClientWithDeps<
       inboxPrefix: bootstrap.connectInfo.transport.inboxPrefix,
       authenticator: runtimeAuth.authenticators,
     });
+    recordTrellisDuration(
+      "trellis.connect.duration",
+      performance.now() - natsStartedAt,
+      {
+        phase: "nats_connect",
+        participantKind: "client",
+        outcome: "ok",
+      },
+    );
   } catch (error) {
     runtimeAuth.stop();
     throw createTransportError({
@@ -1241,7 +1374,7 @@ export async function connectClientWithDeps<
     TrellisAPI
   >["state"];
 
-  return createConnectedClient({
+  const client = createConnectedClient({
     name: clientOpts.name ?? "client",
     nc,
     connection,
@@ -1257,6 +1390,16 @@ export async function connectClientWithDeps<
       onSessionNotFound: handleSessionNotFound,
     },
   });
+  recordTrellisDuration(
+    "trellis.connect.duration",
+    performance.now() - totalStartedAt,
+    {
+      phase: "total",
+      participantKind: "client",
+      outcome: "ok",
+    },
+  );
+  return client;
 }
 
 async function resolveAuthRequired<
@@ -1315,40 +1458,82 @@ async function resolveAuthRequired<
     });
 
   if (authStart.status === "bound") {
-    return await fetchClientBootstrapWithRetry({
+    const bootstrapStartedAt = performance.now();
+    const bootstrap = await fetchClientBootstrapWithRetry({
       trellisUrl: normalizeTrellisUrl(args.trellisUrl),
       sessionKey: identity.sessionKey,
       identity,
       deps,
       offsetState,
     });
+    recordTrellisDuration(
+      "trellis.connect.duration",
+      performance.now() - bootstrapStartedAt,
+      {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+      },
+    );
+    return bootstrap;
   }
 
   const loginUrl = authStart.loginUrl;
 
+  const continuationStartedAt = performance.now();
   const continuation = await args.onAuthRequired?.({
     loginUrl,
     sessionKey: identity.sessionKey,
     mode: identity.mode,
   });
+  recordTrellisDuration(
+    "trellis.connect.duration",
+    performance.now() - continuationStartedAt,
+    {
+      phase: "bootstrap",
+      participantKind: "client",
+      outcome: "ok",
+    },
+  );
   if (continuation && continuation.status === "handled") {
     throw new ClientAuthHandledError();
   }
 
   if (continuation && continuation.status === "bound") {
+    const bindStartedAt = performance.now();
     await bindClientFlow({
       trellisUrl: normalizeTrellisUrl(args.trellisUrl),
       sessionKey: identity.sessionKey,
       flowId: continuation.flowId,
       sig: await identity.bindFlowSig(continuation.flowId),
     });
-    return await fetchClientBootstrapWithRetry({
+    recordTrellisDuration(
+      "trellis.connect.duration",
+      performance.now() - bindStartedAt,
+      {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+      },
+    );
+    const bootstrapStartedAt = performance.now();
+    const bootstrap = await fetchClientBootstrapWithRetry({
       trellisUrl: normalizeTrellisUrl(args.trellisUrl),
       sessionKey: identity.sessionKey,
       identity,
       deps,
       offsetState,
     });
+    recordTrellisDuration(
+      "trellis.connect.duration",
+      performance.now() - bootstrapStartedAt,
+      {
+        phase: "bootstrap",
+        participantKind: "client",
+        outcome: "ok",
+      },
+    );
+    return bootstrap;
   }
 
   if (isBrowserRuntime()) {
@@ -1370,11 +1555,14 @@ export class TrellisClient {
     ConnectedTrellisClient<
       TContract & { API: { trellis: ApiForClientContract<TContract> } }
     >,
-    TransportError | UnexpectedError
+    TransportError | UnexpectedError | ClientAuthHandledError
   >;
   static connect(
     args: TrellisClientConnectArgs,
-  ): AsyncResult<unknown, TransportError | UnexpectedError> {
+  ): AsyncResult<
+    unknown,
+    TransportError | UnexpectedError | ClientAuthHandledError
+  > {
     return clientConnectResult(connectClientWithDeps(args, defaultDeps));
   }
 }

package/src/codec.ts

@@ -6,7 +6,17 @@ import {
 import { Result } from "@qlever-llc/result";
 import type { StaticDecode, TSchema } from "typebox";
 import { EncodeError, ParseError, Value } from "typebox/value";
-import { UnexpectedError, ValidationError } from "./errors/index.js";
+import {
+  SchemaValidationError,
+  UnexpectedError,
+  ValidationError,
+} from "./errors/index.js";
+import type { SchemaValidationIssue } from "./errors/SchemaValidationError.js";
+import type { TLocalizedValidationError } from "typebox/error";
+import type {
+  TrellisValidationExtension,
+  TrellisValidationIssueHint,
+} from "./contract_support/mod.js";
 
 export type JsonValue =
   | string
@@ -18,6 +28,164 @@ export type JsonValue =
     [key: string]: JsonValue;
   };
 
+const X_TRELLIS_VALIDATION = "x-trellis-validation";
+
+function readTrellisValidationExtension(
+  schema: unknown,
+): TrellisValidationExtension | undefined {
+  if (schema === null || schema === undefined || typeof schema !== "object") {
+    return undefined;
+  }
+  const ext = (schema as Record<string, unknown>)[X_TRELLIS_VALIDATION];
+  if (ext === null || ext === undefined || typeof ext !== "object") {
+    return undefined;
+  }
+  return ext as TrellisValidationExtension;
+}
+
+function resolveSchemaNode(
+  root: unknown,
+  schemaPath: string,
+): unknown | undefined {
+  if (!schemaPath.startsWith("#/")) {
+    if (schemaPath === "#") return root;
+    return undefined;
+  }
+  const parts = schemaPath.slice(2).split("/").map(decodeURIComponent);
+  let current = root;
+  for (const part of parts) {
+    if (
+      current === null || current === undefined || typeof current !== "object"
+    ) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+function resolveRequiredErrorNode(
+  root: unknown,
+  error: TLocalizedValidationError,
+): unknown | undefined {
+  const params = error.params as Record<string, unknown> | undefined;
+  const missingProperty = (
+    params?.missingProperty ??
+      (params?.requiredProperties as string[] | undefined)?.[0]
+  ) as string | undefined;
+  if (!missingProperty) return undefined;
+
+  const objNode = resolveSchemaNode(root, error.schemaPath);
+  if (!objNode || typeof objNode !== "object") return undefined;
+
+  const properties = (objNode as Record<string, unknown>).properties;
+  if (!properties || typeof properties !== "object") return undefined;
+
+  return (properties as Record<string, unknown>)[missingProperty];
+}
+
+const ALLOWED_HINT_KEYWORDS = new Set([
+  "required",
+  "minItems",
+  "maxItems",
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "pattern",
+  "format",
+  "enum",
+  "const",
+]);
+
+function keywordAllowsHint(keyword: string): boolean {
+  return ALLOWED_HINT_KEYWORDS.has(keyword);
+}
+
+function typeboxIssueToPath(error: TLocalizedValidationError): string {
+  if (error.keyword === "required") {
+    const params = error.params as Record<string, unknown> | undefined;
+    const missingProperty = (
+      params?.missingProperty ??
+        (params?.requiredProperties as string[] | undefined)?.[0]
+    ) as string | undefined;
+    if (missingProperty) {
+      return error.instancePath
+        ? `${error.instancePath}/${missingProperty}`
+        : `/${missingProperty}`;
+    }
+  }
+  return error.instancePath || error.schemaPath;
+}
+
+function collectValidationIssues(
+  root: unknown,
+  errors: Iterable<TLocalizedValidationError>,
+): {
+  annotated: SchemaValidationIssue[];
+  unannotated: TLocalizedValidationError[];
+} {
+  const annotated: SchemaValidationIssue[] = [];
+  const unannotated: TLocalizedValidationError[] = [];
+
+  for (const error of [...errors]) {
+    const schemaNode = error.keyword === "required"
+      ? resolveRequiredErrorNode(root, error)
+      : resolveSchemaNode(root, error.schemaPath);
+
+    const extension = schemaNode !== undefined
+      ? readTrellisValidationExtension(schemaNode)
+      : undefined;
+
+    if (
+      extension !== undefined &&
+      keywordAllowsHint(error.keyword) &&
+      extension.issues?.[error.keyword] !== undefined
+    ) {
+      const hint = extension.issues[error.keyword]!;
+      if (hint.code !== undefined) {
+        annotated.push({
+          path: typeboxIssueToPath(error),
+          schemaPath: error.schemaPath,
+          keyword: error.keyword,
+          code: hint.code,
+          message: hint.message || error.message,
+          label: hint.label ?? extension.label,
+          note: hint.note ?? extension.note,
+          i18nKey: hint.i18nKey,
+          severity: hint.severity ?? "error",
+          params: error.params as Record<string, unknown>,
+        });
+        continue;
+      }
+    }
+
+    unannotated.push(error);
+  }
+
+  return { annotated, unannotated };
+}
+
+function buildValidationError(
+  schema: unknown,
+  data: unknown,
+  errors: Iterable<TLocalizedValidationError>,
+  cause: ParseError | EncodeError,
+): SchemaValidationError | ValidationError {
+  const { annotated, unannotated } = collectValidationIssues(schema, errors);
+  if (annotated.length > 0 && unannotated.length === 0) {
+    return new SchemaValidationError({ issues: annotated, cause });
+  }
+  return new ValidationError({
+    errors: unannotated.length > 0
+      ? unannotated
+      : annotated.map((i) => ({ path: i.path, message: i.message })),
+    cause,
+  });
+}
+
 function parseWithSchema(schema: TSchema, data: JsonValue): unknown {
   return Value.Parse(schema, data);
 }
@@ -29,13 +197,16 @@ function encodeWithSchema(schema: TSchema, data: unknown): string {
 export function parse<T extends TSchema>(
   schema: T,
   data: JsonValue,
-): Result<StaticDecode<T>, ValidationError | UnexpectedError> {
+): Result<
+  StaticDecode<T>,
+  SchemaValidationError | ValidationError | UnexpectedError
+> {
   try {
     return Result.ok(parseWithSchema(schema, data) as StaticDecode<T>);
   } catch (cause) {
     if (cause instanceof ParseError) {
       const errors = Value.Errors(schema, data);
-      return Result.err(new ValidationError({ errors, cause }));
+      return Result.err(buildValidationError(schema, data, errors, cause));
     }
     return Result.err(new UnexpectedError({ cause }));
   }
@@ -44,7 +215,10 @@ export function parse<T extends TSchema>(
 export function parseSchema<S extends SchemaLike>(
   schema: S,
   data: JsonValue,
-): Result<InferSchemaType<S>, ValidationError | UnexpectedError> {
+): Result<
+  InferSchemaType<S>,
+  SchemaValidationError | ValidationError | UnexpectedError
+> {
   const raw = unwrapSchema(schema);
   try {
     return Result.ok(
@@ -53,23 +227,24 @@ export function parseSchema<S extends SchemaLike>(
   } catch (cause) {
     if (cause instanceof ParseError) {
       const errors = Value.Errors(raw as TSchema, data);
-      return Result.err(new ValidationError({ errors, cause }));
+      return Result.err(buildValidationError(raw, data, errors, cause));
     }
     return Result.err(new UnexpectedError({ cause }));
   }
 }
 
+/** Parses unknown JSON-compatible data with an arbitrary Trellis schema. */
 export function parseUnknownSchema(
   schema: SchemaLike,
   data: JsonValue,
-): Result<unknown, ValidationError | UnexpectedError> {
+): Result<unknown, SchemaValidationError | ValidationError | UnexpectedError> {
   const raw = unwrapSchema(schema);
   try {
     return Result.ok(parseWithSchema(raw as TSchema, data));
   } catch (cause) {
     if (cause instanceof ParseError) {
       const errors = Value.Errors(raw as TSchema, data);
-      return Result.err(new ValidationError({ errors, cause }));
+      return Result.err(buildValidationError(raw, data, errors, cause));
     }
     return Result.err(new UnexpectedError({ cause }));
   }
@@ -78,13 +253,13 @@ export function parseUnknownSchema(
 export function encode<T extends TSchema>(
   schema: T,
   data: unknown,
-): Result<string, ValidationError | UnexpectedError> {
+): Result<string, SchemaValidationError | ValidationError | UnexpectedError> {
   try {
     return Result.ok(encodeWithSchema(schema, data));
   } catch (cause) {
     if (cause instanceof EncodeError) {
       const errors = Value.Errors(schema, data);
-      return Result.err(new ValidationError({ errors, cause }));
+      return Result.err(buildValidationError(schema, data, errors, cause));
     }
     return Result.err(new UnexpectedError({ cause }));
   }
@@ -93,14 +268,14 @@ export function encode<T extends TSchema>(
 export function encodeSchema(
   schema: SchemaLike,
   data: unknown,
-): Result<string, ValidationError | UnexpectedError> {
+): Result<string, SchemaValidationError | ValidationError | UnexpectedError> {
   const raw = unwrapSchema(schema);
   try {
     return Result.ok(encodeWithSchema(raw as TSchema, data));
   } catch (cause) {
     if (cause instanceof EncodeError) {
       const errors = Value.Errors(raw as TSchema, data);
-      return Result.err(new ValidationError({ errors, cause }));
+      return Result.err(buildValidationError(raw, data, errors, cause));
     }
     return Result.err(new UnexpectedError({ cause }));
   }