@qlever-llc/trellis 0.10.9 → 0.10.11

package/src/sdk/_generated/state/types.ts

@@ -3,42 +3,246 @@ import type { RpcHandlerFn } from "../../../index.js";
 import type { API } from "./api.js";
 
 export const CONTRACT_ID = "trellis.state@v1" as const;
-export const CONTRACT_DIGEST = "XfWDYLTBlYFjDqMPBEXrTBccZbFvHp0MnqscehdRKT4" as const;
+export const CONTRACT_DIGEST =
+  "XfWDYLTBlYFjDqMPBEXrTBccZbFvHp0MnqscehdRKT4" as const;
 
-export type StateAdminDeleteInput = ({ contractDigest: string; contractId: string; expectedRevision?: string; key?: string; scope: "userApp"; store: string; user: { id: string; origin: string; userId?: string; }; } | { contractDigest: string; contractId: string; deviceId: string; expectedRevision?: string; key?: string; scope: "deviceApp"; store: string; });
-export type StateAdminDeleteOutput = { deleted: boolean; };
+export type StateAdminDeleteInput = {
+  contractDigest: string;
+  contractId: string;
+  expectedRevision?: string;
+  key?: string;
+  scope: "userApp";
+  store: string;
+  user: { id: string; origin: string; userId?: string };
+} | {
+  contractDigest: string;
+  contractId: string;
+  deviceId: string;
+  expectedRevision?: string;
+  key?: string;
+  scope: "deviceApp";
+  store: string;
+};
+export type StateAdminDeleteOutput = { deleted: boolean };
 
-export type StateAdminGetInput = ({ contractDigest: string; contractId: string; key?: string; scope: "userApp"; store: string; user: { id: string; origin: string; userId?: string; }; } | { contractDigest: string; contractId: string; deviceId: string; key?: string; scope: "deviceApp"; store: string; });
-export type StateAdminGetOutput = ({ found: false; } | { entry: { expiresAt?: string; key?: string; revision: string; updatedAt: string; value: unknown; }; found: true; } | { currentStateVersion: string; entry: { expiresAt?: string; key?: string; revision: string; updatedAt: string; value: unknown; }; migrationRequired: true; stateVersion: string; writerContractDigest: string; });
+export type StateAdminGetInput = {
+  contractDigest: string;
+  contractId: string;
+  key?: string;
+  scope: "userApp";
+  store: string;
+  user: { id: string; origin: string; userId?: string };
+} | {
+  contractDigest: string;
+  contractId: string;
+  deviceId: string;
+  key?: string;
+  scope: "deviceApp";
+  store: string;
+};
+export type StateAdminGetOutput = { found: false } | {
+  entry: {
+    expiresAt?: string;
+    key?: string;
+    revision: string;
+    updatedAt: string;
+    value: unknown;
+  };
+  found: true;
+} | {
+  currentStateVersion: string;
+  entry: {
+    expiresAt?: string;
+    key?: string;
+    revision: string;
+    updatedAt: string;
+    value: unknown;
+  };
+  migrationRequired: true;
+  stateVersion: string;
+  writerContractDigest: string;
+};
 
-export type StateAdminListInput = ({ contractDigest: string; contractId: string; limit: number; offset?: number; prefix?: string; scope: "userApp"; store: string; user: { id: string; origin: string; userId?: string; }; } | { contractDigest: string; contractId: string; deviceId: string; limit: number; offset?: number; prefix?: string; scope: "deviceApp"; store: string; });
-export type StateAdminListOutput = { count: number; entries: Array<({ expiresAt?: string; key?: string; revision: string; updatedAt: string; value: unknown; } | { currentStateVersion: string; entry: { expiresAt?: string; key?: string; revision: string; updatedAt: string; value: unknown; }; migrationRequired: true; stateVersion: string; writerContractDigest: string; })>; limit: number; nextOffset?: number; offset: number; };
+export type StateAdminListInput = {
+  contractDigest: string;
+  contractId: string;
+  limit: number;
+  offset?: number;
+  prefix?: string;
+  scope: "userApp";
+  store: string;
+  user: { id: string; origin: string; userId?: string };
+} | {
+  contractDigest: string;
+  contractId: string;
+  deviceId: string;
+  limit: number;
+  offset?: number;
+  prefix?: string;
+  scope: "deviceApp";
+  store: string;
+};
+export type StateAdminListOutput = {
+  count: number;
+  entries: Array<
+    ({
+      expiresAt?: string;
+      key?: string;
+      revision: string;
+      updatedAt: string;
+      value: unknown;
+    } | {
+      currentStateVersion: string;
+      entry: {
+        expiresAt?: string;
+        key?: string;
+        revision: string;
+        updatedAt: string;
+        value: unknown;
+      };
+      migrationRequired: true;
+      stateVersion: string;
+      writerContractDigest: string;
+    })
+  >;
+  limit: number;
+  nextOffset?: number;
+  offset: number;
+};
 
-export type StateDeleteInput = { expectedRevision?: string; key?: string; store: string; };
-export type StateDeleteOutput = { deleted: boolean; };
+export type StateDeleteInput = {
+  expectedRevision?: string;
+  key?: string;
+  store: string;
+};
+export type StateDeleteOutput = { deleted: boolean };
 
-export type StateGetInput = { key?: string; store: string; };
-export type StateGetOutput = ({ found: false; } | { entry: { expiresAt?: string; key?: string; revision: string; updatedAt: string; value: unknown; }; found: true; } | { currentStateVersion: string; entry: { expiresAt?: string; key?: string; revision: string; updatedAt: string; value: unknown; }; migrationRequired: true; stateVersion: string; writerContractDigest: string; });
+export type StateGetInput = { key?: string; store: string };
+export type StateGetOutput = { found: false } | {
+  entry: {
+    expiresAt?: string;
+    key?: string;
+    revision: string;
+    updatedAt: string;
+    value: unknown;
+  };
+  found: true;
+} | {
+  currentStateVersion: string;
+  entry: {
+    expiresAt?: string;
+    key?: string;
+    revision: string;
+    updatedAt: string;
+    value: unknown;
+  };
+  migrationRequired: true;
+  stateVersion: string;
+  writerContractDigest: string;
+};
 
-export type StateListInput = { limit: number; offset?: number; prefix?: string; store: string; };
-export type StateListOutput = { count: number; entries: Array<({ expiresAt?: string; key?: string; revision: string; updatedAt: string; value: unknown; } | { currentStateVersion: string; entry: { expiresAt?: string; key?: string; revision: string; updatedAt: string; value: unknown; }; migrationRequired: true; stateVersion: string; writerContractDigest: string; })>; limit: number; nextOffset?: number; offset: number; };
+export type StateListInput = {
+  limit: number;
+  offset?: number;
+  prefix?: string;
+  store: string;
+};
+export type StateListOutput = {
+  count: number;
+  entries: Array<
+    ({
+      expiresAt?: string;
+      key?: string;
+      revision: string;
+      updatedAt: string;
+      value: unknown;
+    } | {
+      currentStateVersion: string;
+      entry: {
+        expiresAt?: string;
+        key?: string;
+        revision: string;
+        updatedAt: string;
+        value: unknown;
+      };
+      migrationRequired: true;
+      stateVersion: string;
+      writerContractDigest: string;
+    })
+  >;
+  limit: number;
+  nextOffset?: number;
+  offset: number;
+};
 
-export type StatePutInput = { expectedRevision?: (string | null); key?: string; store: string; ttlMs?: number; value: unknown; };
-export type StatePutOutput = ({ applied: true; entry: { expiresAt?: string; key?: string; revision: string; updatedAt: string; value: unknown; }; } | { applied: false; entry?: ({ expiresAt?: string; key?: string; revision: string; updatedAt: string; value: unknown; } | { currentStateVersion: string; entry: { expiresAt?: string; key?: string; revision: string; updatedAt: string; value: unknown; }; migrationRequired: true; stateVersion: string; writerContractDigest: string; }); found: boolean; });
+export type StatePutInput = {
+  expectedRevision?: string | null;
+  key?: string;
+  store: string;
+  ttlMs?: number;
+  value: unknown;
+};
+export type StatePutOutput = {
+  applied: true;
+  entry: {
+    expiresAt?: string;
+    key?: string;
+    revision: string;
+    updatedAt: string;
+    value: unknown;
+  };
+} | {
+  applied: false;
+  entry?: {
+    expiresAt?: string;
+    key?: string;
+    revision: string;
+    updatedAt: string;
+    value: unknown;
+  } | {
+    currentStateVersion: string;
+    entry: {
+      expiresAt?: string;
+      key?: string;
+      revision: string;
+      updatedAt: string;
+      value: unknown;
+    };
+    migrationRequired: true;
+    stateVersion: string;
+    writerContractDigest: string;
+  };
+  found: boolean;
+};
 
 export interface RpcMap {
-  "State.Admin.Delete": { input: StateAdminDeleteInput; output: StateAdminDeleteOutput; };
-  "State.Admin.Get": { input: StateAdminGetInput; output: StateAdminGetOutput; };
-  "State.Admin.List": { input: StateAdminListInput; output: StateAdminListOutput; };
-  "State.Delete": { input: StateDeleteInput; output: StateDeleteOutput; };
-  "State.Get": { input: StateGetInput; output: StateGetOutput; };
-  "State.List": { input: StateListInput; output: StateListOutput; };
-  "State.Put": { input: StatePutInput; output: StatePutOutput; };
+  "State.Admin.Delete": {
+    input: StateAdminDeleteInput;
+    output: StateAdminDeleteOutput;
+  };
+  "State.Admin.Get": { input: StateAdminGetInput; output: StateAdminGetOutput };
+  "State.Admin.List": {
+    input: StateAdminListInput;
+    output: StateAdminListOutput;
+  };
+  "State.Delete": { input: StateDeleteInput; output: StateDeleteOutput };
+  "State.Get": { input: StateGetInput; output: StateGetOutput };
+  "State.List": { input: StateListInput; output: StateListOutput };
+  "State.Put": { input: StatePutInput; output: StatePutOutput };
 }
 
-export type StateAdminDeleteHandler = RpcHandlerFn<typeof API.owned, "State.Admin.Delete">;
-export type StateAdminGetHandler = RpcHandlerFn<typeof API.owned, "State.Admin.Get">;
-export type StateAdminListHandler = RpcHandlerFn<typeof API.owned, "State.Admin.List">;
+export type StateAdminDeleteHandler = RpcHandlerFn<
+  typeof API.owned,
+  "State.Admin.Delete"
+>;
+export type StateAdminGetHandler = RpcHandlerFn<
+  typeof API.owned,
+  "State.Admin.Get"
+>;
+export type StateAdminListHandler = RpcHandlerFn<
+  typeof API.owned,
+  "State.Admin.List"
+>;
 export type StateDeleteHandler = RpcHandlerFn<typeof API.owned, "State.Delete">;
 export type StateGetHandler = RpcHandlerFn<typeof API.owned, "State.Get">;
 export type StateListHandler = RpcHandlerFn<typeof API.owned, "State.List">;
@@ -52,4 +256,3 @@ export interface FeedMap {
 
 export interface SubjectMap {
 }
-

package/src/server/health.ts

@@ -104,6 +104,25 @@ function summarizeHealthChecks(
   return `${failedCount} check${failedCount === 1 ? "" : "s"} failing`;
 }
 
+function annotateServiceHealthCheck(
+  result: HealthCheckResult,
+  metadata: { service: string; contractId: string; contractDigest: string },
+): HealthCheckResult {
+  if (result.status !== "failed") {
+    return result;
+  }
+
+  return {
+    ...result,
+    info: {
+      ...(result.info ?? {}),
+      service: metadata.service,
+      contractId: metadata.contractId,
+      contractDigest: metadata.contractDigest,
+    },
+  };
+}
+
 function normalizeLegacyHealthCheck(
   check: HealthCheckFn,
 ): ServiceHealthCheckFn {
@@ -114,6 +133,10 @@ function normalizeLegacyHealthCheck(
         status: "failed",
         error: result.error.message,
         summary: result.error.message,
+        info: {
+          errorType: result.error.name,
+          errorId: result.error.id,
+        },
       };
     }
 
@@ -206,6 +229,9 @@ export async function runServiceHealthCheck(
       status: "failed",
       error: message,
       summary: message,
+      info: {
+        errorType: error instanceof Error ? error.name : typeof error,
+      },
       latencyMs,
     };
   }
@@ -350,16 +376,28 @@ export class ServiceHealth {
   }
 
   async checks(): Promise<HealthCheckResult[]> {
-    return await Promise.all(
+    const results = await Promise.all(
       Array.from(this.#checks.entries()).map(([name, check]) =>
         runServiceHealthCheck(name, check)
       ),
     );
+    return results.map((result) =>
+      annotateServiceHealthCheck(result, {
+        service: this.serviceName,
+        contractId: this.contractId,
+        contractDigest: this.contractDigest,
+      })
+    );
   }
 
   async response(): Promise<HealthResponse> {
-    const checks = Object.fromEntries(this.#checks.entries());
-    return await runAllServiceHealthChecks(this.serviceName, checks);
+    const results = await this.checks();
+    return {
+      status: summarizeHealthStatus(results),
+      service: this.serviceName,
+      timestamp: new Date().toISOString(),
+      checks: results,
+    };
   }
 
   async heartbeat(): Promise<Omit<HealthHeartbeat, "header">> {

package/src/server/service.ts

@@ -77,7 +77,10 @@ import type {
   RpcHandlerContext,
   RpcHandlerErrorOf,
 } from "../trellis.js";
-import { createTrellisInternal } from "../trellis.js";
+import {
+  annotateHandlerBoundaryError,
+  createTrellisInternal,
+} from "../trellis.js";
 import type {
   NatsConnectFn,
   NatsConnectOpts,
@@ -956,6 +959,22 @@ type ContractJobName<
   >,
 > = keyof ContractJobsOf<TContract> & string;
 
+type ContractEventName<
+  TContract extends ServiceContract<
+    TrellisAPI,
+    TrellisAPI | undefined,
+    ContractJobsMetadata
+  >,
+> = ServiceEventName<ContractTrellisApi<TContract>>;
+
+type ContractFeedName<
+  TContract extends ServiceContract<
+    TrellisAPI,
+    TrellisAPI | undefined,
+    ContractJobsMetadata
+  >,
+> = keyof ContractOwnedApi<TContract>["feeds"] & string;
+
 type ContractOperationName<
   TContract extends ServiceContract<
     TrellisAPI,
@@ -991,6 +1010,7 @@ export type JobArgs<
     ContractKvMetadata
   >,
   TJob extends ContractJobName<TContract>,
+  TDeps = undefined,
 > = {
   job: PublicActiveJob<
     ContractJobPayload<TContract, TJob>,
@@ -1001,7 +1021,7 @@ export type JobArgs<
     ContractKvOf<TContract>,
     ContractJobsOf<TContract>
   >;
-};
+} & WithDeps<TDeps>;
 
 /** Result returned by a typed Trellis service job handler. */
 export type JobResult<
@@ -1014,6 +1034,9 @@ export type JobResult<
   TJob extends ContractJobName<TContract>,
 > = Result<ContractJobResult<TContract, TJob>, BaseError>;
 
+type WithDeps<TDeps> = [TDeps] extends [undefined] ? {} : { deps: TDeps };
+
+/** Typed RPC handler function for an extracted Trellis service handler. */
 export type RpcHandler<
   TContract extends ServiceContract<
     TrellisAPI,
@@ -1022,6 +1045,7 @@ export type RpcHandler<
     ContractKvMetadata
   >,
   M extends RpcMethodName<ContractOwnedApi<TContract>>,
+  TDeps = undefined,
 > = ({
   input,
   context,
@@ -1034,7 +1058,7 @@ export type RpcHandler<
     ContractKvOf<TContract>,
     ContractJobsOf<TContract>
   >;
-}) =>
+} & WithDeps<TDeps>) =>
   | Promise<
     Result<
       RpcMethodOutput<ContractOwnedApi<TContract>, M>,
@@ -1046,6 +1070,55 @@ export type RpcHandler<
     RpcHandlerErrorOf<ContractOwnedApi<TContract>, M>
   >;
 
+/** Typed event listener function for an extracted Trellis service listener. */
+export type ServiceEventHandler<
+  TContract extends ServiceContract<
+    TrellisAPI,
+    TrellisAPI | undefined,
+    ContractJobsMetadata,
+    ContractKvMetadata
+  >,
+  E extends ContractEventName<TContract>,
+  TDeps = undefined,
+> = (
+  args: {
+    event: ServiceEventOf<ContractTrellisApi<TContract>, E>;
+    context: EventListenerContext;
+    client: Trellis<
+      ContractTrellisApi<TContract>,
+      ContractKvOf<TContract>,
+      ContractJobsOf<TContract>
+    >;
+  } & WithDeps<TDeps>,
+) => MaybeAsync<void, BaseError>;
+
+/** Typed feed handler function for an extracted Trellis service handler. */
+export type FeedHandler<
+  TContract extends ServiceContract<
+    TrellisAPI,
+    TrellisAPI | undefined,
+    ContractJobsMetadata,
+    ContractKvMetadata
+  >,
+  F extends ContractFeedName<TContract>,
+  TDeps = undefined,
+> = (
+  context: {
+    input: FeedInputOf<ContractOwnedApi<TContract>, F>;
+    caller: unknown;
+    signal: AbortSignal;
+    emit(
+      event: FeedEventOf<ContractOwnedApi<TContract>, F>,
+    ): AsyncResult<void, ValidationError | UnexpectedError>;
+    client: Trellis<
+      ContractTrellisApi<TContract>,
+      ContractKvOf<TContract>,
+      ContractJobsOf<TContract>
+    >;
+  } & WithDeps<TDeps>,
+) => unknown | Promise<unknown>;
+
+/** Typed job handler function for an extracted Trellis service job handler. */
 export type JobHandler<
   TContract extends ServiceContract<
     TrellisAPI,
@@ -1054,8 +1127,12 @@ export type JobHandler<
     ContractKvMetadata
   >,
   TJob extends ContractJobName<TContract>,
-> = (args: JobArgs<TContract, TJob>) => Promise<JobResult<TContract, TJob>>;
+  TDeps = undefined,
+> = (args: JobArgs<TContract, TJob, TDeps>) => Promise<
+  JobResult<TContract, TJob>
+>;
 
+/** Typed operation handler function for an extracted Trellis service handler. */
 export type OperationHandler<
   TContract extends ServiceContract<
     TrellisAPI,
@@ -1064,6 +1141,7 @@ export type OperationHandler<
     ContractKvMetadata
   >,
   O extends ContractOperationName<TContract>,
+  TDeps = undefined,
 > = (
   args:
     & OperationHandlerContext<
@@ -1078,9 +1156,20 @@ export type OperationHandler<
         ContractKvOf<TContract>,
         ContractJobsOf<TContract>
       >;
-    },
+    }
+    & WithDeps<TDeps>,
 ) => unknown | Promise<unknown>;
 
+/** Typed health info function for an extracted bound service health handler. */
+export type HealthInfoHandler<TDeps = undefined> = (
+  args: WithDeps<TDeps>,
+) => ServiceHealthInfo | undefined | Promise<ServiceHealthInfo | undefined>;
+
+/** Typed health check function for an extracted bound service health handler. */
+export type HealthCheckHandler<TDeps = undefined> = (
+  args: WithDeps<TDeps>,
+) => ServiceHealthCheck | Promise<ServiceHealthCheck>;
+
 export type JobQueue<
   TPayload,
   TResult,
@@ -1326,19 +1415,10 @@ type BoundJobsFacadeOf<
 };
 
 type BoundServiceHealth<TDeps> = Omit<ServiceHealth, "add" | "setInfo"> & {
-  setInfo(
-    info:
-      | ServiceHealthInfo
-      | ((args: { deps: TDeps }) =>
-        | ServiceHealthInfo
-        | undefined
-        | Promise<ServiceHealthInfo | undefined>),
-  ): void;
+  setInfo(info: ServiceHealthInfo | HealthInfoHandler<TDeps>): void;
   add(
     name: string,
-    check: (args: { deps: TDeps }) =>
-      | ServiceHealthCheck
-      | Promise<ServiceHealthCheck>,
+    check: HealthCheckHandler<TDeps>,
   ): () => void;
 };
 
@@ -1741,6 +1821,8 @@ export async function createConnectedService<
       stream: args.server.stream,
       noResponderRetry: args.server.noResponderRetry,
       api: runtimeApi,
+      contractId: args.contractId,
+      contractDigest: args.contractDigest,
       connection,
       transferSupport: {
         openOperationTransfer: (transferArgs) =>
@@ -1760,6 +1842,8 @@ export async function createConnectedService<
       stream: args.server.stream,
       noResponderRetry: args.server.noResponderRetry,
       api: runtimeApi,
+      contractId: args.contractId,
+      contractDigest: args.contractDigest,
       eventConsumers: {
         metadata: args.contractEventConsumers,
         bindings: args.bindings.eventConsumers,
@@ -1932,6 +2016,14 @@ function toUnexpectedError(cause: unknown): UnexpectedError {
     : new UnexpectedError({ cause });
 }
 
+function serializeJobHandlerError(error: BaseError): string {
+  try {
+    return JSON.stringify(error.toSerializable());
+  } catch {
+    return error.message;
+  }
+}
+
 function okVoid(): Result<void, never> {
   return Result.ok(undefined);
 }
@@ -2326,6 +2418,8 @@ function createJobsFacade<
   TKv extends ContractKvMetadata = ContractKvMetadata,
 >(args: {
   serviceName: string;
+  contractId?: string;
+  contractDigest?: string;
   nc: NatsConnection;
   contractJobs: TJobs;
   client: Trellis<TTrellisApi, TKv, TJobs>;
@@ -2489,9 +2583,35 @@ function createJobsFacade<
                   },
                 );
 
-                const handled = (await handler(publicJob)).take();
+                const jobErrorContext = {
+                  jobType: queueType,
+                  requestId: job.context().requestId,
+                  service: args.serviceName,
+                  contractId: args.contractId,
+                  contractDigest: args.contractDigest,
+                  traceId: job.context().traceId,
+                };
+
+                let handled: unknown | Result<never, BaseError>;
+                try {
+                  handled = (await handler(publicJob)).take();
+                } catch (cause) {
+                  const annotatedError = annotateHandlerBoundaryError(
+                    cause,
+                    jobErrorContext,
+                  );
+                  throw InternalJobProcessError.failed(
+                    serializeJobHandlerError(annotatedError),
+                  );
+                }
                 if (isErr(handled)) {
-                  throw InternalJobProcessError.failed(handled.error.message);
+                  const annotatedError = annotateHandlerBoundaryError(
+                    handled.error,
+                    jobErrorContext,
+                  );
+                  throw InternalJobProcessError.failed(
+                    serializeJobHandlerError(annotatedError),
+                  );
                 }
                 return handled;
               },
@@ -2679,6 +2799,8 @@ export class TrellisService<
     this.#operationTransfer = operationTransfer;
     const jobs = createJobsFacade<TJobs, TTrellisApi, TKv>({
       serviceName: name,
+      contractId: health.contractId,
+      contractDigest: health.contractDigest,
       nc,
       contractJobs,
       client: handlerTrellis,