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

package/src/codec.ts

@@ -0,0 +1,107 @@
+import {
+  type InferSchemaType,
+  type SchemaLike,
+  unwrapSchema,
+} from "./contracts.js";
+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";
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | {
+    [key: string]: JsonValue;
+  };
+
+function parseWithSchema(schema: TSchema, data: JsonValue): unknown {
+  return Value.Parse(schema, data);
+}
+
+function encodeWithSchema(schema: TSchema, data: unknown): string {
+  return JSON.stringify(Value.Encode(schema, data));
+}
+
+export function parse<T extends TSchema>(
+  schema: T,
+  data: JsonValue,
+): Result<StaticDecode<T>, 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(new UnexpectedError({ cause }));
+  }
+}
+
+export function parseSchema<S extends SchemaLike>(
+  schema: S,
+  data: JsonValue,
+): Result<InferSchemaType<S>, ValidationError | UnexpectedError> {
+  const raw = unwrapSchema(schema);
+  try {
+    return Result.ok(
+      parseWithSchema(raw as TSchema, data) as InferSchemaType<S>,
+    );
+  } catch (cause) {
+    if (cause instanceof ParseError) {
+      const errors = Value.Errors(raw as TSchema, data);
+      return Result.err(new ValidationError({ errors, cause }));
+    }
+    return Result.err(new UnexpectedError({ cause }));
+  }
+}
+
+export function parseUnknownSchema(
+  schema: SchemaLike,
+  data: JsonValue,
+): Result<unknown, 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(new UnexpectedError({ cause }));
+  }
+}
+
+export function encode<T extends TSchema>(
+  schema: T,
+  data: unknown,
+): Result<string, 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(new UnexpectedError({ cause }));
+  }
+}
+
+export function encodeSchema(
+  schema: SchemaLike,
+  data: unknown,
+): Result<string, 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(new UnexpectedError({ cause }));
+  }
+}

package/src/connection.ts

@@ -0,0 +1,466 @@
+import type { NatsConnection } from "@nats-io/nats-core";
+import { logger as noopLogger, type LoggerLike } from "./globals.js";
+
+/** Identifies the Trellis runtime that owns a connection. */
+export type TrellisConnectionKind = "client" | "device" | "service";
+
+/** Framework-neutral lifecycle phase for an observed Trellis transport. */
+export type TrellisConnectionPhase =
+  | "connected"
+  | "disconnected"
+  | "reconnecting"
+  | "error"
+  | "closed";
+
+/** Diagnostic metadata copied from the underlying transport without exposing raw handles. */
+export type TrellisConnectionTransportMetadata = {
+  readonly name?: string;
+  readonly event?: string;
+  readonly server?: string;
+  readonly data?: unknown;
+  readonly error?: unknown;
+};
+
+/** Current framework-neutral connection status. */
+export type TrellisConnectionStatus = {
+  readonly kind: TrellisConnectionKind;
+  readonly phase: TrellisConnectionPhase;
+  readonly observedAt: Date;
+  readonly transport?: TrellisConnectionTransportMetadata;
+};
+
+/** Receives connection status changes. */
+export type TrellisConnectionStatusListener = (
+  status: TrellisConnectionStatus,
+) => void;
+
+/** Narrow transport shape used by Trellis connection lifecycle observation. */
+export type TrellisConnectionStatusTransport = {
+  status?: () => AsyncIterable<unknown>;
+  closed: () => Promise<void | Error>;
+  close: () => Promise<void>;
+  isClosed?: () => boolean;
+  getServer?: () => string | undefined;
+};
+
+/** Options for constructing a manually controlled Trellis connection lifecycle. */
+export type TrellisConnectionOptions = {
+  kind: TrellisConnectionKind;
+  initialStatus?: TrellisConnectionStatus;
+  close?: () => Promise<void>;
+  stopObserving?: () => void;
+  log?: LoggerLike | false;
+};
+
+/** Options for observing a transport-backed Trellis connection lifecycle. */
+export type ObserveTrellisConnectionOptions = {
+  kind: TrellisConnectionKind;
+  transport: TrellisConnectionStatusTransport;
+  transportName?: string;
+  log?: LoggerLike | false;
+  lifecycleLog?: TrellisConnectionLifecycleLogOptions;
+};
+
+/** Options for observing a NATS-backed Trellis connection lifecycle. */
+export type ObserveNatsTrellisConnectionOptions = {
+  kind: TrellisConnectionKind;
+  nc: NatsConnection;
+  log?: LoggerLike | false;
+  lifecycleLog?: TrellisConnectionLifecycleLogOptions;
+};
+
+/** Options for logging transport lifecycle events with Trellis runtime context. */
+export type TrellisConnectionLifecycleLogOptions = {
+  log: LoggerLike;
+  context: Record<string, unknown>;
+};
+
+/**
+ * Framework-neutral Trellis connection lifecycle handle.
+ *
+ * The class stores the latest transport-neutral status, delivers it immediately
+ * to subscribers, and owns lifecycle cleanup without exposing raw transport
+ * handles to framework adapters.
+ */
+export class TrellisConnection {
+  #status: TrellisConnectionStatus;
+  #listeners = new Set<TrellisConnectionStatusListener>();
+  #closeTransport: () => Promise<void>;
+  #stopObserving: () => void;
+  #log: LoggerLike;
+  #stopped = false;
+
+  /** Creates a Trellis connection lifecycle handle. */
+  constructor(options: TrellisConnectionOptions) {
+    this.#status = options.initialStatus ??
+      createStatus(options.kind, "connected");
+    this.#closeTransport = options.close ?? (async () => {});
+    this.#stopObserving = options.stopObserving ?? (() => {});
+    this.#log = options.log === false ? noopLogger : options.log ?? noopLogger;
+  }
+
+  /** Returns the latest observed connection status. */
+  get status(): TrellisConnectionStatus {
+    return this.#status;
+  }
+
+  /**
+   * Subscribes to status changes and immediately delivers the current status.
+   *
+   * The returned function removes the listener. Calling it more than once is
+   * safe.
+   */
+  subscribe(listener: TrellisConnectionStatusListener): () => void {
+    this.#listeners.add(listener);
+    listener(this.#status);
+
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  }
+
+  /** Stops status observation without closing the underlying transport. */
+  stopObserving(): void {
+    if (this.#stopped) {
+      return;
+    }
+
+    this.#stopped = true;
+    this.#stopObserving();
+  }
+
+  /** Closes the underlying transport and publishes a terminal closed status. */
+  async close(): Promise<void> {
+    this.stopObserving();
+    try {
+      await this.#closeTransport();
+      this.setStatus(createStatus(this.#status.kind, "closed"));
+    } catch (error) {
+      this.setStatus(createStatus(this.#status.kind, "error", { error }));
+      throw error;
+    }
+  }
+
+  /** Publishes a new status to all active listeners. */
+  setStatus(status: TrellisConnectionStatus): void {
+    if (
+      this.#stopped && status.phase !== "closed" && status.phase !== "error"
+    ) {
+      return;
+    }
+
+    this.#status = status;
+    this.#log.debug(
+      {
+        kind: status.kind,
+        phase: status.phase,
+        transport: status.transport,
+      },
+      "Trellis connection status changed",
+    );
+
+    for (const listener of this.#listeners) {
+      listener(status);
+    }
+  }
+}
+
+/** Observes a narrow transport status stream as a Trellis connection lifecycle. */
+export function observeTrellisConnection(
+  options: ObserveTrellisConnectionOptions,
+): TrellisConnection {
+  let stopped = false;
+  const connection = new TrellisConnection({
+    kind: options.kind,
+    close: () => options.transport.close(),
+    stopObserving: () => {
+      stopped = true;
+    },
+    log: options.log,
+  });
+
+  const baseTransport = createTransportMetadata(
+    options.transport,
+    options.transportName,
+  );
+
+  const statusStream = options.transport.status;
+  if (typeof statusStream === "function") {
+    void (async () => {
+      try {
+        for await (const event of statusStream.call(options.transport)) {
+          if (stopped) {
+            return;
+          }
+
+          const status = statusFromTransportEvent(
+            options.kind,
+            event,
+            baseTransport,
+          );
+          if (status) {
+            logTransportLifecycleEvent(options, event);
+            connection.setStatus(status);
+          }
+        }
+      } catch (error) {
+        if (!stopped) {
+          logTransportStatusWatcherFailure(options, error);
+          connection.setStatus(createStatus(options.kind, "error", {
+            ...baseTransport,
+            error,
+          }));
+        }
+      }
+    })();
+  }
+
+  void options.transport.closed().then((closedError) => {
+    if (stopped) {
+      return;
+    }
+
+    if (closedError instanceof Error) {
+      logTransportClosed(options, closedError);
+      connection.setStatus(createStatus(options.kind, "error", {
+        ...baseTransport,
+        error: closedError,
+      }));
+      return;
+    }
+
+    logTransportClosed(options);
+    connection.setStatus(createStatus(options.kind, "closed", baseTransport));
+  });
+
+  return connection;
+}
+
+/** Observes a NATS connection without exposing the raw NATS handle publicly. */
+export function observeNatsTrellisConnection(
+  options: ObserveNatsTrellisConnectionOptions,
+): TrellisConnection {
+  return observeTrellisConnection({
+    kind: options.kind,
+    transport: options.nc,
+    transportName: "nats",
+    log: options.log,
+    lifecycleLog: options.lifecycleLog,
+  });
+}
+
+function lifecycleLabel(kind: TrellisConnectionKind): string {
+  switch (kind) {
+    case "client":
+      return "Client";
+    case "device":
+      return "Device";
+    case "service":
+      return "Service";
+  }
+}
+
+function normalizeTransportError(error: Error): Record<string, unknown> {
+  const record = error as Error & {
+    operation?: unknown;
+    subject?: unknown;
+    queue?: unknown;
+  };
+
+  return {
+    name: error.name,
+    message: error.message,
+    ...(typeof record.operation === "string"
+      ? { operation: record.operation }
+      : {}),
+    ...(typeof record.subject === "string" ? { subject: record.subject } : {}),
+    ...(typeof record.queue === "string" ? { queue: record.queue } : {}),
+  };
+}
+
+function normalizeTransportStatus(status: unknown): Record<string, unknown> {
+  if (!status || typeof status !== "object") {
+    return { status };
+  }
+
+  const record = status as Record<string, unknown>;
+  return {
+    ...(typeof record.type === "string" ? { type: record.type } : {}),
+    ...(record.error instanceof Error
+      ? { error: normalizeTransportError(record.error) }
+      : {}),
+    ...(typeof record.data === "string" ? { data: record.data } : {}),
+    ...(record.data && typeof record.data === "object"
+      ? { data: record.data }
+      : {}),
+  };
+}
+
+function getNatsLifecycleLog(kind: TrellisConnectionKind, event: unknown): {
+  level: "info" | "warn" | "error";
+  message: string;
+} | null {
+  if (!event || typeof event !== "object") {
+    return null;
+  }
+
+  const label = lifecycleLabel(kind);
+  switch ((event as { type?: unknown }).type) {
+    case "disconnect":
+      return { level: "warn", message: `${label} disconnected from NATS` };
+    case "reconnecting":
+      return { level: "warn", message: `${label} attempting NATS reconnect` };
+    case "forceReconnect":
+      return { level: "warn", message: `${label} forcing NATS reconnect` };
+    case "reconnect":
+      return { level: "info", message: `${label} reconnected to NATS` };
+    case "staleConnection":
+      return {
+        level: "warn",
+        message: `${label} NATS connection became stale`,
+      };
+    case "error":
+      return { level: "error", message: `${label} NATS error` };
+    default:
+      return null;
+  }
+}
+
+function logTransportLifecycleEvent(
+  options: ObserveTrellisConnectionOptions,
+  event: unknown,
+): void {
+  if (!options.lifecycleLog) {
+    return;
+  }
+
+  const lifecycleLog = getNatsLifecycleLog(options.kind, event);
+  if (!lifecycleLog) {
+    return;
+  }
+
+  options.lifecycleLog.log[lifecycleLog.level](
+    {
+      ...options.lifecycleLog.context,
+      connection: normalizeTransportStatus(event),
+    },
+    lifecycleLog.message,
+  );
+}
+
+function logTransportStatusWatcherFailure(
+  options: ObserveTrellisConnectionOptions,
+  error: unknown,
+): void {
+  if (!options.lifecycleLog) {
+    return;
+  }
+
+  options.lifecycleLog.log.warn(
+    { ...options.lifecycleLog.context, error },
+    `${lifecycleLabel(options.kind)} NATS status watcher failed`,
+  );
+}
+
+function logTransportClosed(
+  options: ObserveTrellisConnectionOptions,
+  error?: Error,
+): void {
+  if (!options.lifecycleLog) {
+    return;
+  }
+
+  const label = lifecycleLabel(options.kind);
+  if (error) {
+    options.lifecycleLog.log.error(
+      { ...options.lifecycleLog.context, error },
+      `${label} NATS connection closed with error`,
+    );
+    return;
+  }
+
+  options.lifecycleLog.log.warn(
+    options.lifecycleLog.context,
+    `${label} NATS connection closed`,
+  );
+}
+
+function createStatus(
+  kind: TrellisConnectionKind,
+  phase: TrellisConnectionPhase,
+  transport?: TrellisConnectionTransportMetadata,
+): TrellisConnectionStatus {
+  return {
+    kind,
+    phase,
+    observedAt: new Date(),
+    ...(transport ? { transport } : {}),
+  };
+}
+
+function createTransportMetadata(
+  transport: TrellisConnectionStatusTransport,
+  name?: string,
+): TrellisConnectionTransportMetadata {
+  return {
+    ...(name ? { name } : {}),
+    ...(typeof transport.getServer === "function"
+      ? { server: transport.getServer() }
+      : {}),
+  };
+}
+
+function statusFromTransportEvent(
+  kind: TrellisConnectionKind,
+  event: unknown,
+  baseTransport: TrellisConnectionTransportMetadata,
+): TrellisConnectionStatus | null {
+  const transportEvent = normalizeTransportEvent(event);
+  if (!transportEvent.type) {
+    return null;
+  }
+
+  const transport = {
+    ...baseTransport,
+    event: transportEvent.type,
+    ...(transportEvent.data === undefined ? {} : { data: transportEvent.data }),
+    ...(transportEvent.error === undefined
+      ? {}
+      : { error: transportEvent.error }),
+  };
+
+  switch (transportEvent.type) {
+    case "disconnect":
+    case "disconnected":
+      return createStatus(kind, "disconnected", transport);
+    case "reconnecting":
+    case "forceReconnect":
+    case "staleConnection":
+      return createStatus(kind, "reconnecting", transport);
+    case "reconnect":
+      return createStatus(kind, "connected", transport);
+    case "error":
+      return createStatus(kind, "error", transport);
+    case "closed":
+      return createStatus(kind, "closed", transport);
+    default:
+      return null;
+  }
+}
+
+function normalizeTransportEvent(event: unknown): {
+  type?: string;
+  data?: unknown;
+  error?: unknown;
+} {
+  if (!event || typeof event !== "object") {
+    return {};
+  }
+
+  const record = event as Record<string, unknown>;
+  return {
+    ...(typeof record.type === "string" ? { type: record.type } : {}),
+    ...("data" in record ? { data: record.data } : {}),
+    ...("error" in record ? { error: record.error } : {}),
+  };
+}

package/src/contract.ts

@@ -0,0 +1,84 @@
+import {
+  type ContractApiViews,
+  type ContractDependencyUse,
+  type ContractExports,
+  type ContractJobsMetadata,
+  type ContractModule,
+  type ContractState,
+  type ContractStateKind,
+  type ContractStateMetadata,
+  type ContractStateStore,
+  type ContractUseFn,
+  type DefineContractInput,
+  type DefinedContract as BaseDefinedContract,
+  type EmptyApi,
+  type SdkContractModule,
+  type TrellisApiLike,
+  type TrellisContractV1,
+  type UseSpec,
+} from "./contract_support/mod.js";
+
+// Keep this module browser-safe.
+//
+// `js/apps/*` and other callers build contracts from `@qlever-llc/trellis/contracts`, and those
+// apps need to build inside a clean OCI build stage. If this file reaches into
+// `../server/*`, Vite pulls Deno-only NATS transports into browser bundles and the
+// container build stops being reproducible. Server-specific helpers therefore live
+// in `@qlever-llc/trellis/service` and are wired explicitly by service code.
+export type DefinedContract<
+  TOwnedApi extends {
+    rpc: Record<string, unknown>;
+    operations: Record<string, unknown>;
+    events: Record<string, unknown>;
+    feeds?: Record<string, unknown>;
+    subjects: Record<string, unknown>;
+  },
+  TUsedApi extends {
+    rpc: Record<string, unknown>;
+    operations: Record<string, unknown>;
+    events: Record<string, unknown>;
+    feeds?: Record<string, unknown>;
+    subjects: Record<string, unknown>;
+  },
+  TTrellisApi extends {
+    rpc: Record<string, unknown>;
+    operations: Record<string, unknown>;
+    events: Record<string, unknown>;
+    feeds?: Record<string, unknown>;
+    subjects: Record<string, unknown>;
+  },
+  TContractId extends string = string,
+  TJobs extends ContractJobsMetadata = {},
+  TState extends ContractStateMetadata = {},
+> = BaseDefinedContract<
+  TOwnedApi,
+  TUsedApi,
+  TTrellisApi,
+  TContractId,
+  TJobs,
+  TState
+>;
+
+export {
+  defineAgentContract,
+  defineAppContract,
+  defineDeviceContract,
+  defineServiceContract,
+} from "./contract_support/mod.js";
+
+export type {
+  ContractApiViews,
+  ContractDependencyUse,
+  ContractExports,
+  ContractModule,
+  ContractState,
+  ContractStateKind,
+  ContractStateStore,
+  ContractUseFn,
+  DefineContractInput,
+  EmptyApi,
+  SdkContractModule,
+  TrellisApiLike,
+  TrellisContractV1,
+  UseSpec,
+};