@qlever-llc/trellis 0.10.13 → 0.10.15

package/src/server/service.ts

@@ -5,14 +5,13 @@ import {
   type NatsConnection,
   type Subscription,
 } from "@nats-io/nats-core";
+import type { KVError, StoreError } from "../errors/index.js";
+import { TypedKV } from "../kv.js";
 import {
-  type KVError,
-  type StoreError,
   type StoreWaitOptions,
-  TypedKV,
   TypedStore,
   TypedStoreEntry,
-} from "../index.js";
+} from "../store.js";
 import { sdk as trellisAuth } from "../sdk/auth.js";
 import {
   TrellisServiceRuntime,
@@ -745,7 +744,21 @@ async function fetchServiceBootstrapInfo(args: {
   }
 }
 
-export class StoreHandle {
+export abstract class StoreHandle {
+  abstract readonly binding: ResourceBindingStore;
+
+  abstract open(): AsyncResult<TypedStore, StoreError>;
+
+  /**
+   * Waits for a staged object to appear in the bound store and returns its entry.
+   */
+  abstract waitFor(
+    key: string,
+    options?: StoreWaitOptions,
+  ): AsyncResult<TypedStoreEntry, StoreError>;
+}
+
+class InternalStoreHandle extends StoreHandle {
   readonly binding: ResourceBindingStore;
   readonly #nc: NatsConnection;
 
@@ -754,6 +767,7 @@ export class StoreHandle {
     binding: ResourceBindingStore,
     token: typeof storeHandleConstructorToken,
   ) {
+    super();
     if (token !== storeHandleConstructorToken) {
       throw new TypeError(
         "StoreHandle instances are created by TrellisService",
@@ -1453,12 +1467,12 @@ export type BoundTrellisService<
     TrellisService<TOwnedApi, TTrellisApi, TJobs, TKv>,
     | "name"
     | "auth"
-    | "nc"
     | "kv"
     | "store"
     | "connection"
     | "createTransfer"
     | "completeOperation"
+    | "publishPrepared"
     | "wait"
     | "stop"
   >
@@ -1797,6 +1811,9 @@ export type TrellisServiceInternalConnectArgs<
   contractKv?: TKv;
 };
 
+/**
+ * @internal Shared by Trellis-owned service bootstrap paths.
+ */
 export async function createConnectedService<
   TOwnedApi extends TrellisAPI,
   TTrellisApi extends TrellisAPI,
@@ -1991,12 +2008,12 @@ export async function createConnectedService<
     stores: Object.fromEntries(
       Object.entries(args.bindings.store ?? {}).map(([alias, binding]) => [
         alias,
-        new StoreHandle(args.nc, binding, storeHandleConstructorToken),
+        new InternalStoreHandle(args.nc, binding, storeHandleConstructorToken),
       ]),
     ),
   });
 
-  const service = new TrellisService<TOwnedApi, TTrellisApi, TJobs, TKv>(
+  const service = Reflect.construct(TrellisService, [
     args.name,
     args.auth,
     args.nc,
@@ -2011,7 +2028,7 @@ export async function createConnectedService<
     stopHealthPublishing,
     connection,
     trellisServiceConstructorToken,
-  );
+  ]) as TrellisService<TOwnedApi, TTrellisApi, TJobs, TKv>;
   handlerResources = {
     kv: service.kv,
     store: service.store,
@@ -2757,6 +2774,143 @@ function createBoundJobsFacade<
   return boundJobs as BoundJobsFacadeOf<TJobs, TTrellisApi, TKv, TDeps>;
 }
 
+/**
+ * Connects a service with caller-supplied runtime dependencies for tests and
+ * Trellis-owned internals. This helper is intentionally not re-exported from
+ * public package subpaths.
+ *
+ * @internal
+ */
+export function connectTrellisServiceWithRuntimeDeps<
+  const TContract extends ServiceContract<
+    TrellisAPI,
+    TrellisAPI | undefined,
+    ContractJobsMetadata,
+    ContractKvMetadata
+  >,
+>(
+  args: TrellisServiceConnectArgs<TContract>,
+  deps: Partial<TrellisServiceRuntimeDeps>,
+): AsyncResult<
+  TrellisService<
+    ContractOwnedApi<TContract>,
+    ContractTrellisApi<TContract>,
+    ContractJobsOf<TContract>,
+    ContractKvOf<TContract>
+  >,
+  TransportError | UnexpectedError
+> {
+  return AsyncResult.from((async () => {
+    try {
+      type TOwnedApi = ContractOwnedApi<TContract>;
+      type TTrellisApi = ContractTrellisApi<TContract>;
+
+      const runtimeDeps = {
+        ...(await loadDefaultServiceRuntimeDeps()),
+        ...deps,
+      } satisfies TrellisServiceRuntimeDeps;
+      if (automaticTelemetryEnabled(args.telemetry)) {
+        runtimeDeps.initTelemetry?.(args.name);
+      }
+      const auth = await createAuth({ sessionKeySeed: args.sessionKeySeed });
+      const bootstrapLog = resolveServiceLogger(args.server?.log);
+      const bootstrap = await fetchServiceBootstrapInfo({
+        trellisUrl: args.trellisUrl,
+        serviceName: args.name,
+        contractId: args.contract.CONTRACT_ID,
+        contractDigest: args.contract.CONTRACT_DIGEST,
+        contract: args.contract.CONTRACT,
+        auth,
+        log: bootstrapLog,
+      });
+      const { authenticator: authTokenAuthenticator, inboxPrefix } = await auth
+        .natsConnectOptions({
+          contractDigest: args.contract.CONTRACT_DIGEST,
+        });
+
+      let nc: NatsConnection;
+      try {
+        nc = await runtimeDeps.connect({
+          servers: selectRuntimeTransportServers(
+            bootstrap.connectInfo.transports,
+          ),
+          maxReconnectAttempts: DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS,
+          waitOnFirstConnect: DEFAULT_SERVICE_RUNTIME_WAIT_ON_FIRST_CONNECT,
+          inboxPrefix,
+          authenticator: [
+            authTokenAuthenticator,
+            jwtAuthenticator(
+              bootstrap.connectInfo.transport.sentinel.jwt,
+              new TextEncoder().encode(
+                bootstrap.connectInfo.transport.sentinel.seed,
+              ),
+            ),
+          ],
+        });
+      } catch (cause) {
+        throw new TransportError({
+          code: "trellis.runtime.connect_failed",
+          message: "Trellis could not open the service runtime connection.",
+          hint:
+            "Retry the connection. If it keeps failing, check Trellis transport availability.",
+          cause,
+          context: {
+            trellisUrl: args.trellisUrl,
+            contractId: args.contract.CONTRACT_ID,
+            contractDigest: args.contract.CONTRACT_DIGEST,
+          },
+        });
+      }
+
+      try {
+        const server = args.contract.API.trellis
+          ? {
+            ...(args.server ?? {}),
+            api: args.contract.API.owned,
+            trellisApi: args.contract.API.trellis as TTrellisApi,
+          }
+          : {
+            ...(args.server ?? {}),
+            api: args.contract.API.owned,
+          };
+
+        return Result.ok(
+          await createConnectedService<
+            TOwnedApi,
+            TTrellisApi,
+            ContractJobsOf<TContract>,
+            ContractKvOf<TContract>
+          >({
+            name: args.name,
+            auth,
+            nc,
+            contractId: args.contract.CONTRACT_ID,
+            contractDigest: args.contract.CONTRACT_DIGEST,
+            contractJobs:
+              (args.contract[CONTRACT_JOBS_METADATA] ?? {}) as ContractJobsOf<
+                TContract
+              >,
+            contractKv:
+              (args.contract[CONTRACT_KV_METADATA] ?? {}) as ContractKvOf<
+                TContract
+              >,
+            contractEventConsumers: args.contract.CONTRACT.eventConsumers,
+            server,
+            bindings: bootstrap.binding.resources,
+          }),
+        );
+      } catch (cause) {
+        await closeFailedServiceBootstrapConnection(nc);
+        throw cause;
+      }
+    } catch (cause) {
+      return Result.err(
+        cause instanceof TransportError ? cause : toUnexpectedError(cause),
+      );
+    }
+  })());
+}
+
 export class TrellisService<
   TOwnedApi extends TrellisAPI = TrellisAPI,
   TTrellisApi extends TrellisAPI = TOwnedApi,
@@ -2765,8 +2919,8 @@ export class TrellisService<
 > {
   readonly name: string;
   readonly auth: SessionAuth;
-  readonly nc: NatsConnection;
   readonly #server: TrellisServiceRuntimeFor<TOwnedApi & TTrellisApi>;
+  readonly #nc: NatsConnection;
   readonly #handlerTrellis: Trellis<TTrellisApi, TKv, TJobs>;
   /** Event lifecycle surface for service startup listeners and publishers. */
   readonly event: ActiveEventFacade<TTrellisApi>;
@@ -2783,7 +2937,7 @@ export class TrellisService<
   #waitPromise?: Promise<void>;
   #stopPromise?: Promise<void>;
 
-  constructor(
+  private constructor(
     name: string,
     auth: SessionAuth,
     nc: NatsConnection,
@@ -2806,7 +2960,7 @@ export class TrellisService<
 
     this.name = name;
     this.auth = auth;
-    this.nc = nc;
+    this.#nc = nc;
     this.#server = server;
     Object.defineProperty(this, "server", {
       value: server,
@@ -2818,7 +2972,10 @@ export class TrellisService<
     this.store = Object.fromEntries(
       Object.entries(storeBindings).map((
         [alias, binding],
-      ) => [alias, new StoreHandle(nc, binding, storeHandleConstructorToken)]),
+      ) => [
+        alias,
+        new InternalStoreHandle(nc, binding, storeHandleConstructorToken),
+      ]),
     );
     this.#operationTransfer = operationTransfer;
     const jobs = createJobsFacade<TJobs, TTrellisApi, TKv>({
@@ -2854,7 +3011,6 @@ export class TrellisService<
     return {
       name: this.name,
       auth: this.auth,
-      nc: this.nc,
       event: this.#createBoundEventFacade(deps),
       kv: this.kv,
       store: this.store,
@@ -2865,12 +3021,20 @@ export class TrellisService<
       createTransfer: (args) => this.createTransfer(args),
       completeOperation: (operationId, output) =>
         this.completeOperation(operationId, output),
+      publishPrepared: (event) => this.publishPrepared(event),
       wait: () => this.wait(),
       stop: () => this.stop(),
       with: (nextDeps) => this.with(nextDeps),
     };
   }
 
+  /** Publishes a prepared event through the service runtime connection. */
+  publishPrepared(
+    event: PreparedTrellisEvent,
+  ): AsyncResult<void, UnexpectedError> {
+    return this.#handlerTrellis.publishPrepared(event);
+  }
+
   #createBoundHealth<TDeps>(deps: TDeps): BoundServiceHealth<TDeps> {
     const health = this.health;
     return {
@@ -3147,7 +3311,6 @@ export class TrellisService<
     >,
   >(
     args: TrellisServiceConnectArgs<TContract>,
-    deps?: Partial<TrellisServiceRuntimeDeps>,
   ): AsyncResult<
     TrellisService<
       ContractOwnedApi<TContract>,
@@ -3157,123 +3320,14 @@ export class TrellisService<
     >,
     TransportError | UnexpectedError
   > {
-    return AsyncResult.from((async () => {
-      try {
-        type TOwnedApi = ContractOwnedApi<TContract>;
-        type TTrellisApi = ContractTrellisApi<TContract>;
-
-        const runtimeDeps = {
-          ...(await loadDefaultServiceRuntimeDeps()),
-          ...deps,
-        } satisfies TrellisServiceRuntimeDeps;
-        if (automaticTelemetryEnabled(args.telemetry)) {
-          runtimeDeps.initTelemetry?.(args.name);
-        }
-        const auth = await createAuth({ sessionKeySeed: args.sessionKeySeed });
-        const bootstrapLog = resolveServiceLogger(args.server?.log);
-        const bootstrap = await fetchServiceBootstrapInfo({
-          trellisUrl: args.trellisUrl,
-          serviceName: args.name,
-          contractId: args.contract.CONTRACT_ID,
-          contractDigest: args.contract.CONTRACT_DIGEST,
-          contract: args.contract.CONTRACT,
-          auth,
-          log: bootstrapLog,
-        });
-        const { authenticator: authTokenAuthenticator, inboxPrefix } =
-          await auth
-            .natsConnectOptions({
-              contractDigest: args.contract.CONTRACT_DIGEST,
-            });
-
-        let nc: NatsConnection;
-        try {
-          nc = await runtimeDeps.connect({
-            servers: selectRuntimeTransportServers(
-              bootstrap.connectInfo.transports,
-            ),
-            maxReconnectAttempts: DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS,
-            waitOnFirstConnect: DEFAULT_SERVICE_RUNTIME_WAIT_ON_FIRST_CONNECT,
-            inboxPrefix,
-            authenticator: [
-              authTokenAuthenticator,
-              jwtAuthenticator(
-                bootstrap.connectInfo.transport.sentinel.jwt,
-                new TextEncoder().encode(
-                  bootstrap.connectInfo.transport.sentinel.seed,
-                ),
-              ),
-            ],
-          });
-        } catch (cause) {
-          throw new TransportError({
-            code: "trellis.runtime.connect_failed",
-            message: "Trellis could not open the service runtime connection.",
-            hint:
-              "Retry the connection. If it keeps failing, check Trellis transport availability.",
-            cause,
-            context: {
-              trellisUrl: args.trellisUrl,
-              contractId: args.contract.CONTRACT_ID,
-              contractDigest: args.contract.CONTRACT_DIGEST,
-            },
-          });
-        }
-
-        try {
-          const server = args.contract.API.trellis
-            ? {
-              ...(args.server ?? {}),
-              api: args.contract.API.owned,
-              trellisApi: args.contract.API.trellis as TTrellisApi,
-            }
-            : {
-              ...(args.server ?? {}),
-              api: args.contract.API.owned,
-            };
-
-          return Result.ok(
-            await createConnectedService<
-              TOwnedApi,
-              TTrellisApi,
-              ContractJobsOf<TContract>,
-              ContractKvOf<TContract>
-            >({
-              name: args.name,
-              auth,
-              nc,
-              contractId: args.contract.CONTRACT_ID,
-              contractDigest: args.contract.CONTRACT_DIGEST,
-              contractJobs:
-                (args.contract[CONTRACT_JOBS_METADATA] ?? {}) as ContractJobsOf<
-                  TContract
-                >,
-              contractKv:
-                (args.contract[CONTRACT_KV_METADATA] ?? {}) as ContractKvOf<
-                  TContract
-                >,
-              contractEventConsumers: args.contract.CONTRACT.eventConsumers,
-              server,
-              bindings: bootstrap.binding.resources,
-            }),
-          );
-        } catch (cause) {
-          await closeFailedServiceBootstrapConnection(nc);
-          throw cause;
-        }
-      } catch (cause) {
-        return Result.err(
-          cause instanceof TransportError ? cause : toUnexpectedError(cause),
-        );
-      }
-    })());
+    return connectTrellisServiceWithRuntimeDeps(args, {});
   }
 
   async wait(): Promise<void> {
     this.#waitPromise ??= (async () => {
       try {
         await this.#managedJobWorkers.start().orThrow();
-        const closed = await this.nc.closed();
+        const closed = await this.#nc.closed();
         if (closed instanceof Error) {
           throw closed;
         }
@@ -3299,6 +3353,12 @@ export class TrellisService<
             await this.#operationTransfer.stop();
           } finally {
             await this.#server.stop();
+            this.connection.setStatus({
+              kind: this.connection.status.kind,
+              phase: "closed",
+              observedAt: new Date(),
+              transport: { name: "nats" },
+            });
           }
         }
       }

package/src/server.ts

@@ -1799,12 +1799,12 @@ export class TrellisServiceRuntime extends Trellis<TrellisAPI, TrellisMode> {
 
   async stop(): Promise<void> {
     this.#stopPromise ??= (async () => {
-      if (this.natsConnection.isClosed()) {
+      if (this.nats.isClosed()) {
         return;
       }
 
       try {
-        await this.natsConnection.drain();
+        await this.nats.drain();
       } catch (cause) {
         if (
           !(cause instanceof Error) ||
@@ -1813,7 +1813,7 @@ export class TrellisServiceRuntime extends Trellis<TrellisAPI, TrellisMode> {
           throw cause;
         }
 
-        await this.natsConnection.closed().catch(() => undefined);
+        await this.nats.closed().catch(() => undefined);
       }
     })();
 

package/src/service/outbox_inbox.ts

@@ -1,4 +1,3 @@
-import type { NatsConnection } from "@nats-io/nats-core";
 import { type AsyncResult, type BaseError, isErr } from "@qlever-llc/result";
 import { type StaticDecode, Type } from "typebox";
 import type { PreparedTrellisEvent, Trellis } from "../trellis.js";
@@ -387,19 +386,6 @@ export type KvOutboxRecord = StaticDecode<typeof KvOutboxRecordSchema>;
 export class NatsKvOutboxRepository implements OutboxRepository {
   constructor(readonly kv: OutboxKvStore) {}
 
-  /** Opens or creates the KV bucket used for durable outbox records. */
-  static async open(
-    nats: NatsConnection,
-    bucket = "trellis_outbox",
-  ): Promise<NatsKvOutboxRepository> {
-    const opened = await TypedKV.open(nats, bucket, KvOutboxRecordSchema, {
-      history: 1,
-    });
-    const value = opened.take();
-    if (isErr(value)) throw value.error;
-    return new NatsKvOutboxRepository(value);
-  }
-
   async enqueue(event: PreparedTrellisEvent): Promise<OutboxMessage> {
     const now = new Date().toISOString();
     const record: KvOutboxRecord = {
@@ -500,20 +486,7 @@ export class NatsKvOutboxRepository implements OutboxRepository {
 
 /** Durable NATS KV inbox repository for event-id duplicate suppression. */
 export class NatsKvInboxRepository implements InboxRepository {
-  private constructor(readonly kv: TypedKV<typeof KvInboxRecordSchema>) {}
-
-  /** Opens or creates the KV bucket used for durable inbox records. */
-  static async open(
-    nats: NatsConnection,
-    bucket = "trellis_inbox",
-  ): Promise<NatsKvInboxRepository> {
-    const opened = await TypedKV.open(nats, bucket, KvInboxRecordSchema, {
-      history: 1,
-    });
-    const value = opened.take();
-    if (isErr(value)) throw value.error;
-    return new NatsKvInboxRepository(value);
-  }
+  constructor(readonly kv: TypedKV<typeof KvInboxRecordSchema>) {}
 
   async record(messageId: string, now: Date = new Date()): Promise<boolean> {
     // Durable NATS KV dedupe is useful for event handlers without SQL state, but

package/src/telemetry/env.ts

@@ -9,19 +9,22 @@ type ProcessLike = {
   env?: Record<string, string | undefined>;
 };
 
+type EnvironmentGlobalThis = typeof dntShim.dntGlobalThis & {
+  Deno?: DenoLike;
+  process?: ProcessLike;
+};
+
 // Shared telemetry code needs environment access without assuming Deno or Node.
 export function getEnv(key: string): string | undefined {
-  const deno = dntShim.dntGlobalThis as typeof dntShim.dntGlobalThis & { Deno?: DenoLike };
-  if (deno.Deno?.env?.get) {
+  const load = new Function("return globalThis") as () => EnvironmentGlobalThis;
+  const environmentGlobal = load();
+  if (environmentGlobal.Deno?.env?.get) {
     try {
-      return deno.Deno.env.get(key);
+      return environmentGlobal.Deno.env.get(key);
     } catch {
       return undefined;
     }
   }
 
-  const processGlobal = dntShim.dntGlobalThis as typeof dntShim.dntGlobalThis & {
-    process?: ProcessLike;
-  };
-  return processGlobal.process?.env?.[key];
+  return environmentGlobal.process?.env?.[key];
 }

package/src/trellis.ts

@@ -22,7 +22,6 @@ import {
   CONTRACT_JOBS_METADATA,
   CONTRACT_KV_METADATA,
   CONTRACT_STATE_METADATA,
-  type ContractEventConsumers,
   type ContractJobsMetadata,
   type ContractKvMetadata,
   type EventConsumerResourceBinding,
@@ -1117,10 +1116,28 @@ function createEventListenerContext(args: {
 }
 
 type RuntimeEventConsumers = {
-  metadata?: ContractEventConsumers;
+  metadata?: RuntimeEventConsumerGroups;
   bindings?: Record<string, EventConsumerResourceBinding>;
 };
 
+type RuntimeEventConsumerGroup = {
+  uses?: Readonly<Record<string, readonly string[]>>;
+  self?: readonly string[];
+};
+
+type RuntimeEventConsumerGroups = Readonly<
+  Record<string, RuntimeEventConsumerGroup>
+>;
+
+function eventConsumerGroupEvents(group: RuntimeEventConsumerGroup): string[] {
+  const events = new Set<string>();
+  for (const groupEvents of Object.values(group.uses ?? {})) {
+    for (const event of groupEvents) events.add(event);
+  }
+  for (const event of group.self ?? []) events.add(event);
+  return [...events].sort();
+}
+
 type TrellisInternalOpts<TA extends AnyTrellisAPI> = TrellisOpts<TA> & {
   eventConsumers?: RuntimeEventConsumers;
 };
@@ -1472,7 +1489,6 @@ export type ClientTrellis<
   readonly api: TA;
   readonly state: StateFacade<TState>;
   readonly connection: TrellisConnection;
-  readonly natsConnection: NatsConnection;
   readonly rpc: ActiveRpcFacade<TA>;
   readonly event: ActiveEventFacade<TA>;
   readonly feed: ActiveFeedFacade<TA>;
@@ -2077,13 +2093,6 @@ export class Trellis<
     this.operation = this.#createOperationFacade();
   }
 
-  /**
-   * Returns the underlying NATS connection.
-   */
-  get natsConnection(): NatsConnection {
-    return this.nats;
-  }
-
   #createStateFacade(state: TState | undefined): StateFacade<TState> {
     const stores = (state ?? {}) as RuntimeStateStores;
     const facade = Object.fromEntries(
@@ -4215,7 +4224,7 @@ export class Trellis<
     const bindings = this.#eventConsumers.bindings ?? {};
     const groups = Object.entries(metadata ?? {})
       .filter(([, group]) =>
-        group.events.some((entry) => entry.event === String(event))
+        eventConsumerGroupEvents(group).includes(String(event))
       )
       .map(([group]) => group);
 
@@ -4339,9 +4348,9 @@ export class Trellis<
   ): boolean {
     const metadata = this.#eventConsumers.metadata?.[group];
     if (!metadata) return false;
-    return metadata.events.every((entry) =>
+    return eventConsumerGroupEvents(metadata).every((event) =>
       loop.registrations.some((registration) =>
-        String(registration.event) === entry.event
+        String(registration.event) === event
       )
     );
   }