@archipelagolab/lobi 1.0.0

package/src/matrix/client-bootstrap.ts

@@ -0,0 +1,164 @@
+import { getMatrixRuntime } from "../runtime.js";
+import type { CoreConfig } from "../types.js";
+import { getActiveMatrixClient } from "./active-client.js";
+import { isBunRuntime } from "./client/runtime.js";
+import type { MatrixClient } from "./sdk.js";
+
+type ResolvedRuntimeMatrixClient = {
+  client: MatrixClient;
+  stopOnDone: boolean;
+  cleanup?: (mode: ResolvedRuntimeMatrixClientStopMode) => Promise<void>;
+};
+
+type MatrixRuntimeClientReadiness = "none" | "prepared" | "started";
+type ResolvedRuntimeMatrixClientStopMode = "stop" | "persist";
+
+type MatrixResolvedClientHook = (
+  client: MatrixClient,
+  context: { preparedByDefault: boolean },
+) => Promise<void> | void;
+
+type MatrixSharedClientRuntimeDeps = Pick<
+  typeof import("./client.js"),
+  "acquireSharedMatrixClient" | "resolveMatrixAuthContext"
+> &
+  Pick<typeof import("./client/shared.js"), "releaseSharedClientInstance">;
+
+let matrixSharedClientRuntimeDepsPromise: Promise<MatrixSharedClientRuntimeDeps> | undefined;
+
+async function loadMatrixSharedClientRuntimeDeps(): Promise<MatrixSharedClientRuntimeDeps> {
+  matrixSharedClientRuntimeDepsPromise ??= Promise.all([
+    import("./client.js"),
+    import("./client/shared.js"),
+  ]).then(([clientModule, sharedModule]) => ({
+    acquireSharedMatrixClient: clientModule.acquireSharedMatrixClient,
+    resolveMatrixAuthContext: clientModule.resolveMatrixAuthContext,
+    releaseSharedClientInstance: sharedModule.releaseSharedClientInstance,
+  }));
+  return await matrixSharedClientRuntimeDepsPromise;
+}
+
+async function ensureResolvedClientReadiness(params: {
+  client: MatrixClient;
+  readiness?: MatrixRuntimeClientReadiness;
+  preparedByDefault: boolean;
+}): Promise<void> {
+  if (params.readiness === "started") {
+    await params.client.start();
+    return;
+  }
+  if (params.readiness === "prepared" || (!params.readiness && params.preparedByDefault)) {
+    await params.client.prepareForOneOff();
+  }
+}
+
+function ensureMatrixNodeRuntime() {
+  if (isBunRuntime()) {
+    throw new Error("Matrix support requires Node (bun runtime not supported)");
+  }
+}
+
+async function resolveRuntimeMatrixClient(opts: {
+  client?: MatrixClient;
+  cfg?: CoreConfig;
+  timeoutMs?: number;
+  accountId?: string | null;
+  onResolved?: MatrixResolvedClientHook;
+}): Promise<ResolvedRuntimeMatrixClient> {
+  ensureMatrixNodeRuntime();
+  if (opts.client) {
+    await opts.onResolved?.(opts.client, { preparedByDefault: false });
+    return { client: opts.client, stopOnDone: false };
+  }
+
+  const cfg = opts.cfg ?? (getMatrixRuntime().config.loadConfig() as CoreConfig);
+  const { acquireSharedMatrixClient, releaseSharedClientInstance, resolveMatrixAuthContext } =
+    await loadMatrixSharedClientRuntimeDeps();
+  const authContext = resolveMatrixAuthContext({
+    cfg,
+    accountId: opts.accountId,
+  });
+  const active = getActiveMatrixClient(authContext.accountId);
+  if (active) {
+    await opts.onResolved?.(active, { preparedByDefault: false });
+    return { client: active, stopOnDone: false };
+  }
+  const client = await acquireSharedMatrixClient({
+    cfg,
+    timeoutMs: opts.timeoutMs,
+    accountId: authContext.accountId,
+    startClient: false,
+  });
+  try {
+    await opts.onResolved?.(client, { preparedByDefault: true });
+  } catch (err) {
+    await releaseSharedClientInstance(client, "stop");
+    throw err;
+  }
+  return {
+    client,
+    stopOnDone: true,
+    cleanup: async (mode) => {
+      await releaseSharedClientInstance(client, mode);
+    },
+  };
+}
+
+export async function resolveRuntimeMatrixClientWithReadiness(opts: {
+  client?: MatrixClient;
+  cfg?: CoreConfig;
+  timeoutMs?: number;
+  accountId?: string | null;
+  readiness?: MatrixRuntimeClientReadiness;
+}): Promise<ResolvedRuntimeMatrixClient> {
+  return await resolveRuntimeMatrixClient({
+    client: opts.client,
+    cfg: opts.cfg,
+    timeoutMs: opts.timeoutMs,
+    accountId: opts.accountId,
+    onResolved: async (client, context) => {
+      await ensureResolvedClientReadiness({
+        client,
+        readiness: opts.readiness,
+        preparedByDefault: context.preparedByDefault,
+      });
+    },
+  });
+}
+
+export async function stopResolvedRuntimeMatrixClient(
+  resolved: ResolvedRuntimeMatrixClient,
+  mode: ResolvedRuntimeMatrixClientStopMode = "stop",
+): Promise<void> {
+  if (!resolved.stopOnDone) {
+    return;
+  }
+  if (resolved.cleanup) {
+    await resolved.cleanup(mode);
+    return;
+  }
+  if (mode === "persist") {
+    await resolved.client.stopAndPersist();
+    return;
+  }
+  resolved.client.stop();
+}
+
+export async function withResolvedRuntimeMatrixClient<T>(
+  opts: {
+    client?: MatrixClient;
+    cfg?: CoreConfig;
+    timeoutMs?: number;
+    accountId?: string | null;
+    readiness?: MatrixRuntimeClientReadiness;
+  },
+  run: (client: MatrixClient) => Promise<T>,
+  stopMode: ResolvedRuntimeMatrixClientStopMode = "stop",
+): Promise<T> {
+  const resolved = await resolveRuntimeMatrixClientWithReadiness(opts);
+  try {
+    return await run(resolved.client);
+  } finally {
+    await stopResolvedRuntimeMatrixClient(resolved, stopMode);
+  }
+}

package/src/matrix/client-resolver.test-helpers.ts

@@ -0,0 +1,147 @@
+import { expect, vi, type Mock } from "vitest";
+import type { MatrixClient } from "./sdk.js";
+
+type MatrixClientResolverMocks = {
+  loadConfigMock: Mock<() => unknown>;
+  getMatrixRuntimeMock: Mock<() => unknown>;
+  getActiveMatrixClientMock: Mock<(...args: unknown[]) => MatrixClient | null>;
+  acquireSharedMatrixClientMock: Mock<(...args: unknown[]) => Promise<MatrixClient>>;
+  releaseSharedClientInstanceMock: Mock<(...args: unknown[]) => Promise<boolean>>;
+  isBunRuntimeMock: Mock<() => boolean>;
+  resolveMatrixAuthContextMock: Mock<
+    (params: { cfg: unknown; accountId?: string | null }) => unknown
+  >;
+};
+
+export const matrixClientResolverMocks: MatrixClientResolverMocks = {
+  loadConfigMock: vi.fn(() => ({})),
+  getMatrixRuntimeMock: vi.fn(),
+  getActiveMatrixClientMock: vi.fn(),
+  acquireSharedMatrixClientMock: vi.fn(),
+  releaseSharedClientInstanceMock: vi.fn(),
+  isBunRuntimeMock: vi.fn(() => false),
+  resolveMatrixAuthContextMock: vi.fn(),
+};
+
+export function createMockMatrixClient(): MatrixClient {
+  return {
+    prepareForOneOff: vi.fn(async () => undefined),
+    start: vi.fn(async () => undefined),
+    stop: vi.fn(() => undefined),
+    stopAndPersist: vi.fn(async () => undefined),
+  } as unknown as MatrixClient;
+}
+
+export function primeMatrixClientResolverMocks(params?: {
+  cfg?: unknown;
+  accountId?: string;
+  resolved?: Record<string, unknown>;
+  auth?: Record<string, unknown>;
+  client?: MatrixClient;
+}): MatrixClient {
+  const {
+    loadConfigMock,
+    getMatrixRuntimeMock,
+    getActiveMatrixClientMock,
+    acquireSharedMatrixClientMock,
+    releaseSharedClientInstanceMock,
+    isBunRuntimeMock,
+    resolveMatrixAuthContextMock,
+  } = matrixClientResolverMocks;
+
+  const cfg = params?.cfg ?? {};
+  const accountId = params?.accountId ?? "default";
+  const defaultResolved = {
+    homeserver: "https://matrix.example.org",
+    userId: "@bot:example.org",
+    accessToken: "token",
+    password: undefined,
+    deviceId: "DEVICE123",
+    encryption: false,
+  };
+  const client = params?.client ?? createMockMatrixClient();
+
+  vi.clearAllMocks();
+  loadConfigMock.mockReturnValue(cfg);
+  getMatrixRuntimeMock.mockReturnValue({
+    config: {
+      loadConfig: loadConfigMock,
+    },
+  });
+  getActiveMatrixClientMock.mockReturnValue(null);
+  isBunRuntimeMock.mockReturnValue(false);
+  releaseSharedClientInstanceMock.mockReset().mockResolvedValue(true);
+  resolveMatrixAuthContextMock.mockImplementation(
+    ({
+      cfg: explicitCfg,
+      accountId: explicitAccountId,
+    }: {
+      cfg: unknown;
+      accountId?: string | null;
+    }) => ({
+      cfg: explicitCfg,
+      env: process.env,
+      accountId: explicitAccountId ?? accountId,
+      resolved: {
+        ...defaultResolved,
+        ...params?.resolved,
+      },
+    }),
+  );
+  acquireSharedMatrixClientMock.mockResolvedValue(client);
+
+  return client;
+}
+
+export async function expectOneOffSharedMatrixClient(params?: {
+  cfg?: unknown;
+  accountId?: string;
+  timeoutMs?: number;
+  prepareForOneOffCalls?: number;
+  startCalls?: number;
+  releaseMode?: "persist" | "stop";
+}) {
+  const {
+    getActiveMatrixClientMock,
+    acquireSharedMatrixClientMock,
+    releaseSharedClientInstanceMock,
+  } = matrixClientResolverMocks;
+  const accountId = params?.accountId ?? "default";
+  const prepareForOneOffCalls = params?.prepareForOneOffCalls ?? 1;
+  const startCalls = params?.startCalls ?? 0;
+  const releaseMode = params?.releaseMode ?? "stop";
+
+  expect(getActiveMatrixClientMock).toHaveBeenCalledWith(accountId);
+  expect(acquireSharedMatrixClientMock).toHaveBeenCalledTimes(1);
+  expect(acquireSharedMatrixClientMock).toHaveBeenCalledWith({
+    cfg: params?.cfg ?? {},
+    timeoutMs: params?.timeoutMs,
+    accountId,
+    startClient: false,
+  });
+
+  const sharedClient = await acquireSharedMatrixClientMock.mock.results[0]?.value;
+  expect(sharedClient.prepareForOneOff).toHaveBeenCalledTimes(prepareForOneOffCalls);
+  expect(sharedClient.start).toHaveBeenCalledTimes(startCalls);
+  expect(releaseSharedClientInstanceMock).toHaveBeenCalledWith(sharedClient, releaseMode);
+
+  return sharedClient;
+}
+
+export function expectExplicitMatrixClientConfig(params: { cfg: unknown; accountId?: string }) {
+  const { getMatrixRuntimeMock, resolveMatrixAuthContextMock, acquireSharedMatrixClientMock } =
+    matrixClientResolverMocks;
+  const accountId = params.accountId ?? "default";
+
+  expect(getMatrixRuntimeMock).not.toHaveBeenCalled();
+  expect(resolveMatrixAuthContextMock).toHaveBeenCalledWith({
+    cfg: params.cfg,
+    accountId,
+  });
+  expect(acquireSharedMatrixClientMock).toHaveBeenCalledWith({
+    cfg: params.cfg,
+    timeoutMs: undefined,
+    accountId,
+    startClient: false,
+  });
+}