@qlever-llc/trellis 0.10.17 → 0.19.0-rc.1

package/src/jobs.ts

@@ -1,4 +1,4 @@
-import { AsyncResult, type BaseError, Result } from "@qlever-llc/result";
+import { AsyncResult, BaseError, Result } from "@qlever-llc/result";
 import { UnexpectedError } from "./errors/index.js";
 import { type StaticDecode, Type } from "typebox";
 
@@ -41,6 +41,8 @@ export type JobState =
   | "failed"
   | "cancelled"
   | "expired"
+  | "skipped"
+  | "stale"
   | "dead"
   | "dismissed";
 
@@ -50,6 +52,116 @@ export type JobIdentity = {
   id: string;
 };
 
+export type JobNotEnqueuedReason =
+  | "active-limit"
+  | "queue-depth"
+  | "stale-blocked"
+  | "coalesced";
+
+export type JobNotEnqueuedErrorData = {
+  id: string;
+  type: "JobNotEnqueuedError";
+  message: string;
+  reason: JobNotEnqueuedReason;
+  key: string;
+  active: number;
+  queued: number;
+  limit: number;
+  existingJobId?: string;
+  context?: Record<string, unknown>;
+  traceId?: string;
+};
+
+/** Error returned when keyed job admission does not create a new job. */
+export class JobNotEnqueuedError extends BaseError<JobNotEnqueuedErrorData> {
+  override readonly name = "JobNotEnqueuedError" as const;
+  readonly reason: JobNotEnqueuedReason;
+  readonly key: string;
+  readonly active: number;
+  readonly queued: number;
+  readonly limit: number;
+  readonly existingJobId?: string;
+
+  constructor(
+    options: ErrorOptions & {
+      reason: JobNotEnqueuedReason;
+      key: string;
+      active: number;
+      queued: number;
+      limit: number;
+      existingJobId?: string;
+      message?: string;
+      context?: Record<string, unknown>;
+      id?: string;
+      traceId?: string;
+    },
+  ) {
+    const {
+      reason,
+      key,
+      active,
+      queued,
+      limit,
+      existingJobId,
+      message,
+      ...baseOptions
+    } = options;
+    super(
+      message ?? `Job was not enqueued for key '${key}': ${reason}`,
+      baseOptions,
+    );
+    this.reason = reason;
+    this.key = key;
+    this.active = active;
+    this.queued = queued;
+    this.limit = limit;
+    this.existingJobId = existingJobId;
+  }
+
+  /** Serializes the admission error for transport or logging. */
+  override toSerializable(): JobNotEnqueuedErrorData {
+    const base = this.baseSerializable();
+    return {
+      id: base.id,
+      type: this.name,
+      message: base.message,
+      reason: this.reason,
+      key: this.key,
+      active: this.active,
+      queued: this.queued,
+      limit: this.limit,
+      ...(this.existingJobId !== undefined
+        ? { existingJobId: this.existingJobId }
+        : {}),
+      ...(base.context !== undefined ? { context: base.context } : {}),
+      ...(base.traceId !== undefined ? { traceId: base.traceId } : {}),
+    };
+  }
+}
+
+export type JobSubmitOutcome<TPayload, TResult> =
+  | { kind: "accepted"; ref: JobRef<TPayload, TResult>; key?: string }
+  | {
+    kind: "rejected";
+    key: string;
+    reason: "active-limit" | "queue-depth" | "stale-blocked";
+    active: number;
+    queued: number;
+    limit: number;
+  }
+  | {
+    kind: "coalesced";
+    key: string;
+    existing: JobIdentity;
+    reason: string;
+  }
+  | {
+    kind: "replaced";
+    key: string;
+    replaced: JobIdentity;
+    ref: JobRef<TPayload, TResult>;
+  };
+
 export type JobSnapshot<TPayload, TResult> = {
   id: string;
   service: string;
@@ -81,6 +193,8 @@ export type TerminalJob<TPayload, TResult> = JobSnapshot<TPayload, TResult> & {
     | "failed"
     | "cancelled"
     | "expired"
+    | "skipped"
+    | "stale"
     | "dead"
     | "dismissed";
 };
@@ -269,6 +383,9 @@ export class JobQueue<TPayload, TResult> {
       job: ActiveJob<TPayload, TResult>,
     ) => Promise<Result<TResult, BaseError>>,
   ) => void;
+  readonly #submit: (
+    payload: TPayload,
+  ) => AsyncResult<JobSubmitOutcome<TPayload, TResult>, BaseError>;
 
   constructor(impl: {
     create: (
@@ -279,9 +396,15 @@ export class JobQueue<TPayload, TResult> {
         job: ActiveJob<TPayload, TResult>,
       ) => Promise<Result<TResult, BaseError>>,
     ) => void;
+    submit?: (
+      payload: TPayload,
+    ) => AsyncResult<JobSubmitOutcome<TPayload, TResult>, BaseError>;
   }) {
     this.#create = impl.create;
     this.#handle = impl.handle;
+    this.#submit = impl.submit ??
+      ((payload) =>
+        impl.create(payload).map((ref) => ({ kind: "accepted", ref })));
   }
 
   create(payload: TPayload): AsyncResult<JobRef<TPayload, TResult>, BaseError> {
@@ -292,6 +415,20 @@ export class JobQueue<TPayload, TResult> {
     }
   }
 
+  /**
+   * Submits a job using queue policy outcomes for keyed queues.
+   * Unkeyed queues accept and return a new job reference.
+   */
+  submit(
+    payload: TPayload,
+  ): AsyncResult<JobSubmitOutcome<TPayload, TResult>, BaseError> {
+    try {
+      return this.#submit(payload);
+    } catch (cause) {
+      return AsyncResult.err(toUnexpectedError(cause));
+    }
+  }
+
   handle(
     handler: (
       job: ActiveJob<TPayload, TResult>,

package/src/sdk/_generated/auth/api.ts

@@ -1,12 +1,15 @@
 // Generated from ./generated/contracts/manifests/trellis.auth@v1.json
 import { OWNED_API } from "./owned_api.js";
+import { OWNED_API as HealthApi } from "../health/mod.js";
 
 export { OWNED_API };
 
 export type UsedApi = {
   rpc: {};
   operations: {};
-  events: {};
+  events: {
+    readonly "Health.Heartbeat": typeof HealthApi.events["Health.Heartbeat"];
+  };
   feeds: {};
   subjects: {};
 };
@@ -14,7 +17,11 @@ export type UsedApi = {
 export const USED_API: UsedApi = {
   rpc: {},
   operations: {},
-  events: {},
+  events: {
+    get "Health.Heartbeat"() {
+      return HealthApi.events["Health.Heartbeat"];
+    },
+  },
   feeds: {},
   subjects: {},
 };

package/src/sdk/_generated/auth/client.ts

@@ -33,6 +33,7 @@ import type {
 } from "../../../index.js";
 import type { API, Api } from "./api.js";
 import type * as Types from "./types.js";
+import type * as HealthSdk from "../health/mod.js";
 
 type WithDeps<TDeps> = [TDeps] extends [undefined] ? {} : { deps: TDeps };
 
@@ -416,14 +417,12 @@ export interface TrellisAuthClient {
     readonly auth: {
       connectionsClosed: {
         publish(
-          event: Omit<Types.AuthConnectionsClosedEvent, "header">,
+          event: Types.AuthConnectionsClosedEvent,
         ): AsyncResult<void, ValidationError | UnexpectedError>;
         prepare(
-          event: Omit<Types.AuthConnectionsClosedEvent, "header">,
+          event: Types.AuthConnectionsClosedEvent,
         ): Result<
-          PreparedTrellisEvent<
-            Omit<Types.AuthConnectionsClosedEvent, "header">
-          >,
+          PreparedTrellisEvent<Types.AuthConnectionsClosedEvent>,
           ValidationError | UnexpectedError
         >;
         listen(
@@ -434,14 +433,12 @@ export interface TrellisAuthClient {
       };
       connectionsKicked: {
         publish(
-          event: Omit<Types.AuthConnectionsKickedEvent, "header">,
+          event: Types.AuthConnectionsKickedEvent,
         ): AsyncResult<void, ValidationError | UnexpectedError>;
         prepare(
-          event: Omit<Types.AuthConnectionsKickedEvent, "header">,
+          event: Types.AuthConnectionsKickedEvent,
         ): Result<
-          PreparedTrellisEvent<
-            Omit<Types.AuthConnectionsKickedEvent, "header">
-          >,
+          PreparedTrellisEvent<Types.AuthConnectionsKickedEvent>,
           ValidationError | UnexpectedError
         >;
         listen(
@@ -452,14 +449,12 @@ export interface TrellisAuthClient {
       };
       connectionsOpened: {
         publish(
-          event: Omit<Types.AuthConnectionsOpenedEvent, "header">,
+          event: Types.AuthConnectionsOpenedEvent,
         ): AsyncResult<void, ValidationError | UnexpectedError>;
         prepare(
-          event: Omit<Types.AuthConnectionsOpenedEvent, "header">,
+          event: Types.AuthConnectionsOpenedEvent,
         ): Result<
-          PreparedTrellisEvent<
-            Omit<Types.AuthConnectionsOpenedEvent, "header">
-          >,
+          PreparedTrellisEvent<Types.AuthConnectionsOpenedEvent>,
           ValidationError | UnexpectedError
         >;
         listen(
@@ -470,14 +465,12 @@ export interface TrellisAuthClient {
       };
       deviceUserAuthoritiesApproved: {
         publish(
-          event: Omit<Types.AuthDeviceUserAuthoritiesApprovedEvent, "header">,
+          event: Types.AuthDeviceUserAuthoritiesApprovedEvent,
         ): AsyncResult<void, ValidationError | UnexpectedError>;
         prepare(
-          event: Omit<Types.AuthDeviceUserAuthoritiesApprovedEvent, "header">,
+          event: Types.AuthDeviceUserAuthoritiesApprovedEvent,
         ): Result<
-          PreparedTrellisEvent<
-            Omit<Types.AuthDeviceUserAuthoritiesApprovedEvent, "header">
-          >,
+          PreparedTrellisEvent<Types.AuthDeviceUserAuthoritiesApprovedEvent>,
           ValidationError | UnexpectedError
         >;
         listen(
@@ -488,14 +481,12 @@ export interface TrellisAuthClient {
       };
       deviceUserAuthoritiesRequested: {
         publish(
-          event: Omit<Types.AuthDeviceUserAuthoritiesRequestedEvent, "header">,
+          event: Types.AuthDeviceUserAuthoritiesRequestedEvent,
         ): AsyncResult<void, ValidationError | UnexpectedError>;
         prepare(
-          event: Omit<Types.AuthDeviceUserAuthoritiesRequestedEvent, "header">,
+          event: Types.AuthDeviceUserAuthoritiesRequestedEvent,
         ): Result<
-          PreparedTrellisEvent<
-            Omit<Types.AuthDeviceUserAuthoritiesRequestedEvent, "header">
-          >,
+          PreparedTrellisEvent<Types.AuthDeviceUserAuthoritiesRequestedEvent>,
           ValidationError | UnexpectedError
         >;
         listen(
@@ -506,14 +497,12 @@ export interface TrellisAuthClient {
       };
       deviceUserAuthoritiesResolved: {
         publish(
-          event: Omit<Types.AuthDeviceUserAuthoritiesResolvedEvent, "header">,
+          event: Types.AuthDeviceUserAuthoritiesResolvedEvent,
         ): AsyncResult<void, ValidationError | UnexpectedError>;
         prepare(
-          event: Omit<Types.AuthDeviceUserAuthoritiesResolvedEvent, "header">,
+          event: Types.AuthDeviceUserAuthoritiesResolvedEvent,
         ): Result<
-          PreparedTrellisEvent<
-            Omit<Types.AuthDeviceUserAuthoritiesResolvedEvent, "header">
-          >,
+          PreparedTrellisEvent<Types.AuthDeviceUserAuthoritiesResolvedEvent>,
           ValidationError | UnexpectedError
         >;
         listen(
@@ -524,19 +513,13 @@ export interface TrellisAuthClient {
       };
       deviceUserAuthoritiesReviewRequested: {
         publish(
-          event: Omit<
-            Types.AuthDeviceUserAuthoritiesReviewRequestedEvent,
-            "header"
-          >,
+          event: Types.AuthDeviceUserAuthoritiesReviewRequestedEvent,
         ): AsyncResult<void, ValidationError | UnexpectedError>;
         prepare(
-          event: Omit<
-            Types.AuthDeviceUserAuthoritiesReviewRequestedEvent,
-            "header"
-          >,
+          event: Types.AuthDeviceUserAuthoritiesReviewRequestedEvent,
         ): Result<
           PreparedTrellisEvent<
-            Omit<Types.AuthDeviceUserAuthoritiesReviewRequestedEvent, "header">
+            Types.AuthDeviceUserAuthoritiesReviewRequestedEvent
           >,
           ValidationError | UnexpectedError
         >;
@@ -550,12 +533,12 @@ export interface TrellisAuthClient {
       };
       sessionsRevoked: {
         publish(
-          event: Omit<Types.AuthSessionsRevokedEvent, "header">,
+          event: Types.AuthSessionsRevokedEvent,
         ): AsyncResult<void, ValidationError | UnexpectedError>;
         prepare(
-          event: Omit<Types.AuthSessionsRevokedEvent, "header">,
+          event: Types.AuthSessionsRevokedEvent,
         ): Result<
-          PreparedTrellisEvent<Omit<Types.AuthSessionsRevokedEvent, "header">>,
+          PreparedTrellisEvent<Types.AuthSessionsRevokedEvent>,
           ValidationError | UnexpectedError
         >;
         listen(
@@ -565,6 +548,24 @@ export interface TrellisAuthClient {
         ): AsyncResult<void, ValidationError | UnexpectedError>;
       };
     };
+    readonly health: {
+      heartbeat: {
+        publish(
+          event: HealthSdk.HealthHeartbeatEvent,
+        ): AsyncResult<void, ValidationError | UnexpectedError>;
+        prepare(
+          event: HealthSdk.HealthHeartbeatEvent,
+        ): Result<
+          PreparedTrellisEvent<HealthSdk.HealthHeartbeatEvent>,
+          ValidationError | UnexpectedError
+        >;
+        listen(
+          handler: EventCallback<HealthSdk.HealthHeartbeatEvent>,
+          subjectData?: Record<string, unknown>,
+          opts?: EventOpts,
+        ): AsyncResult<void, ValidationError | UnexpectedError>;
+      };
+    };
   };
   readonly feed: {};
   readonly operation: {
@@ -590,12 +591,12 @@ export interface ServiceEventSurface<TDeps> {
   readonly auth: {
     connectionsClosed: {
       publish(
-        event: Omit<Types.AuthConnectionsClosedEvent, "header">,
+        event: Types.AuthConnectionsClosedEvent,
       ): AsyncResult<void, ValidationError | UnexpectedError>;
       prepare(
-        event: Omit<Types.AuthConnectionsClosedEvent, "header">,
+        event: Types.AuthConnectionsClosedEvent,
       ): Result<
-        PreparedTrellisEvent<Omit<Types.AuthConnectionsClosedEvent, "header">>,
+        PreparedTrellisEvent<Types.AuthConnectionsClosedEvent>,
         ValidationError | UnexpectedError
       >;
       listen(
@@ -606,12 +607,12 @@ export interface ServiceEventSurface<TDeps> {
     };
     connectionsKicked: {
       publish(
-        event: Omit<Types.AuthConnectionsKickedEvent, "header">,
+        event: Types.AuthConnectionsKickedEvent,
       ): AsyncResult<void, ValidationError | UnexpectedError>;
       prepare(
-        event: Omit<Types.AuthConnectionsKickedEvent, "header">,
+        event: Types.AuthConnectionsKickedEvent,
       ): Result<
-        PreparedTrellisEvent<Omit<Types.AuthConnectionsKickedEvent, "header">>,
+        PreparedTrellisEvent<Types.AuthConnectionsKickedEvent>,
         ValidationError | UnexpectedError
       >;
       listen(
@@ -622,12 +623,12 @@ export interface ServiceEventSurface<TDeps> {
     };
     connectionsOpened: {
       publish(
-        event: Omit<Types.AuthConnectionsOpenedEvent, "header">,
+        event: Types.AuthConnectionsOpenedEvent,
       ): AsyncResult<void, ValidationError | UnexpectedError>;
       prepare(
-        event: Omit<Types.AuthConnectionsOpenedEvent, "header">,
+        event: Types.AuthConnectionsOpenedEvent,
       ): Result<
-        PreparedTrellisEvent<Omit<Types.AuthConnectionsOpenedEvent, "header">>,
+        PreparedTrellisEvent<Types.AuthConnectionsOpenedEvent>,
         ValidationError | UnexpectedError
       >;
       listen(
@@ -638,14 +639,12 @@ export interface ServiceEventSurface<TDeps> {
     };
     deviceUserAuthoritiesApproved: {
       publish(
-        event: Omit<Types.AuthDeviceUserAuthoritiesApprovedEvent, "header">,
+        event: Types.AuthDeviceUserAuthoritiesApprovedEvent,
       ): AsyncResult<void, ValidationError | UnexpectedError>;
       prepare(
-        event: Omit<Types.AuthDeviceUserAuthoritiesApprovedEvent, "header">,
+        event: Types.AuthDeviceUserAuthoritiesApprovedEvent,
       ): Result<
-        PreparedTrellisEvent<
-          Omit<Types.AuthDeviceUserAuthoritiesApprovedEvent, "header">
-        >,
+        PreparedTrellisEvent<Types.AuthDeviceUserAuthoritiesApprovedEvent>,
         ValidationError | UnexpectedError
       >;
       listen(
@@ -659,14 +658,12 @@ export interface ServiceEventSurface<TDeps> {
     };
     deviceUserAuthoritiesRequested: {
       publish(
-        event: Omit<Types.AuthDeviceUserAuthoritiesRequestedEvent, "header">,
+        event: Types.AuthDeviceUserAuthoritiesRequestedEvent,
       ): AsyncResult<void, ValidationError | UnexpectedError>;
       prepare(
-        event: Omit<Types.AuthDeviceUserAuthoritiesRequestedEvent, "header">,
+        event: Types.AuthDeviceUserAuthoritiesRequestedEvent,
       ): Result<
-        PreparedTrellisEvent<
-          Omit<Types.AuthDeviceUserAuthoritiesRequestedEvent, "header">
-        >,
+        PreparedTrellisEvent<Types.AuthDeviceUserAuthoritiesRequestedEvent>,
         ValidationError | UnexpectedError
       >;
       listen(
@@ -680,14 +677,12 @@ export interface ServiceEventSurface<TDeps> {
     };
     deviceUserAuthoritiesResolved: {
       publish(
-        event: Omit<Types.AuthDeviceUserAuthoritiesResolvedEvent, "header">,
+        event: Types.AuthDeviceUserAuthoritiesResolvedEvent,
       ): AsyncResult<void, ValidationError | UnexpectedError>;
       prepare(
-        event: Omit<Types.AuthDeviceUserAuthoritiesResolvedEvent, "header">,
+        event: Types.AuthDeviceUserAuthoritiesResolvedEvent,
       ): Result<
-        PreparedTrellisEvent<
-          Omit<Types.AuthDeviceUserAuthoritiesResolvedEvent, "header">
-        >,
+        PreparedTrellisEvent<Types.AuthDeviceUserAuthoritiesResolvedEvent>,
         ValidationError | UnexpectedError
       >;
       listen(
@@ -701,19 +696,13 @@ export interface ServiceEventSurface<TDeps> {
     };
     deviceUserAuthoritiesReviewRequested: {
       publish(
-        event: Omit<
-          Types.AuthDeviceUserAuthoritiesReviewRequestedEvent,
-          "header"
-        >,
+        event: Types.AuthDeviceUserAuthoritiesReviewRequestedEvent,
       ): AsyncResult<void, ValidationError | UnexpectedError>;
       prepare(
-        event: Omit<
-          Types.AuthDeviceUserAuthoritiesReviewRequestedEvent,
-          "header"
-        >,
+        event: Types.AuthDeviceUserAuthoritiesReviewRequestedEvent,
       ): Result<
         PreparedTrellisEvent<
-          Omit<Types.AuthDeviceUserAuthoritiesReviewRequestedEvent, "header">
+          Types.AuthDeviceUserAuthoritiesReviewRequestedEvent
         >,
         ValidationError | UnexpectedError
       >;
@@ -728,12 +717,12 @@ export interface ServiceEventSurface<TDeps> {
     };
     sessionsRevoked: {
       publish(
-        event: Omit<Types.AuthSessionsRevokedEvent, "header">,
+        event: Types.AuthSessionsRevokedEvent,
       ): AsyncResult<void, ValidationError | UnexpectedError>;
       prepare(
-        event: Omit<Types.AuthSessionsRevokedEvent, "header">,
+        event: Types.AuthSessionsRevokedEvent,
       ): Result<
-        PreparedTrellisEvent<Omit<Types.AuthSessionsRevokedEvent, "header">>,
+        PreparedTrellisEvent<Types.AuthSessionsRevokedEvent>,
         ValidationError | UnexpectedError
       >;
       listen(
@@ -743,6 +732,24 @@ export interface ServiceEventSurface<TDeps> {
       ): AsyncResult<void, ValidationError | UnexpectedError>;
     };
   };
+  readonly health: {
+    heartbeat: {
+      publish(
+        event: HealthSdk.HealthHeartbeatEvent,
+      ): AsyncResult<void, ValidationError | UnexpectedError>;
+      prepare(
+        event: HealthSdk.HealthHeartbeatEvent,
+      ): Result<
+        PreparedTrellisEvent<HealthSdk.HealthHeartbeatEvent>,
+        ValidationError | UnexpectedError
+      >;
+      listen(
+        handler: ServiceEventHandler<HealthSdk.HealthHeartbeatEvent, TDeps>,
+        subjectData?: Record<string, unknown>,
+        opts?: EventOpts,
+      ): AsyncResult<void, ValidationError | UnexpectedError>;
+    };
+  };
 }
 
 export interface ServiceHandle<TDeps = undefined> {