@archipelagolab/lobi 1.0.0

package/src/matrix/client/shared.test.ts

@@ -0,0 +1,344 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { MatrixAuth } from "./types.js";
+
+const resolveMatrixAuthMock = vi.hoisted(() => vi.fn());
+const resolveMatrixAuthContextMock = vi.hoisted(() => vi.fn());
+const createMatrixClientMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./config.js", () => ({
+  resolveMatrixAuth: resolveMatrixAuthMock,
+  resolveMatrixAuthContext: resolveMatrixAuthContextMock,
+}));
+
+vi.mock("./create-client.js", () => ({
+  createMatrixClient: createMatrixClientMock,
+}));
+
+let acquireSharedMatrixClient: typeof import("./shared.js").acquireSharedMatrixClient;
+let releaseSharedClientInstance: typeof import("./shared.js").releaseSharedClientInstance;
+let resolveSharedMatrixClient: typeof import("./shared.js").resolveSharedMatrixClient;
+let stopSharedClient: typeof import("./shared.js").stopSharedClient;
+let stopSharedClientForAccount: typeof import("./shared.js").stopSharedClientForAccount;
+let stopSharedClientInstance: typeof import("./shared.js").stopSharedClientInstance;
+
+function authFor(accountId: string): MatrixAuth {
+  return {
+    accountId,
+    homeserver: "https://matrix.example.org",
+    userId: `@${accountId}:example.org`,
+    accessToken: `token-${accountId}`,
+    password: "secret", // pragma: allowlist secret
+    deviceId: `${accountId.toUpperCase()}-DEVICE`,
+    deviceName: `${accountId} device`,
+    initialSyncLimit: undefined,
+    encryption: false,
+  };
+}
+
+function createMockClient(name: string) {
+  const client = {
+    name,
+    start: vi.fn(async () => undefined),
+    stop: vi.fn(() => undefined),
+    getJoinedRooms: vi.fn(async () => [] as string[]),
+    crypto: undefined,
+  };
+  return client;
+}
+
+function primeAccountClientMocks(params?: {
+  mainAuth?: MatrixAuth;
+  opsAuth?: MatrixAuth;
+  mainClient?: ReturnType<typeof createMockClient>;
+  opsClient?: ReturnType<typeof createMockClient>;
+}) {
+  const mainAuth = params?.mainAuth ?? authFor("main");
+  const opsAuth = params?.opsAuth ?? authFor("ops");
+  const mainClient = params?.mainClient ?? createMockClient("main");
+  const opsClient = params?.opsClient ?? createMockClient("ops");
+
+  resolveMatrixAuthMock.mockImplementation(async ({ accountId }: { accountId?: string }) =>
+    accountId === "ops" ? opsAuth : mainAuth,
+  );
+  createMatrixClientMock.mockImplementation(async ({ accountId }: { accountId?: string }) => {
+    if (accountId === "ops") {
+      return opsClient;
+    }
+    return mainClient;
+  });
+
+  return { mainAuth, opsAuth, mainClient, opsClient };
+}
+
+describe("resolveSharedMatrixClient", () => {
+  beforeAll(async () => {
+    ({
+      acquireSharedMatrixClient,
+      releaseSharedClientInstance,
+      resolveSharedMatrixClient,
+      stopSharedClient,
+      stopSharedClientForAccount,
+      stopSharedClientInstance,
+    } = await import("./shared.js"));
+  });
+
+  beforeEach(() => {
+    resolveMatrixAuthMock.mockReset();
+    resolveMatrixAuthContextMock.mockReset();
+    createMatrixClientMock.mockReset();
+    resolveMatrixAuthContextMock.mockImplementation(
+      ({ accountId }: { accountId?: string | null } = {}) => ({
+        cfg: undefined,
+        env: undefined,
+        accountId: accountId ?? "default",
+        resolved: {},
+      }),
+    );
+  });
+
+  afterEach(() => {
+    stopSharedClient();
+    vi.clearAllMocks();
+  });
+
+  it("keeps account clients isolated when resolves are interleaved", async () => {
+    const { mainClient, opsClient } = primeAccountClientMocks();
+
+    const firstMain = await resolveSharedMatrixClient({ accountId: "main", startClient: false });
+    const firstPoe = await resolveSharedMatrixClient({ accountId: "ops", startClient: false });
+    const secondMain = await resolveSharedMatrixClient({ accountId: "main" });
+
+    expect(firstMain).toBe(mainClient);
+    expect(firstPoe).toBe(opsClient);
+    expect(secondMain).toBe(mainClient);
+    expect(createMatrixClientMock).toHaveBeenCalledTimes(2);
+    expect(mainClient.start).toHaveBeenCalledTimes(1);
+    expect(opsClient.start).toHaveBeenCalledTimes(0);
+  });
+
+  it("stops only the targeted account client", async () => {
+    const { mainAuth, mainClient, opsClient } = primeAccountClientMocks();
+
+    await resolveSharedMatrixClient({ accountId: "main", startClient: false });
+    await resolveSharedMatrixClient({ accountId: "ops", startClient: false });
+
+    stopSharedClientForAccount(mainAuth);
+
+    expect(mainClient.stop).toHaveBeenCalledTimes(1);
+    expect(opsClient.stop).toHaveBeenCalledTimes(0);
+
+    stopSharedClient();
+
+    expect(opsClient.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it("drops stopped shared clients by instance so the next resolve recreates them", async () => {
+    const mainAuth = authFor("main");
+    const firstMainClient = createMockClient("main-first");
+    const secondMainClient = createMockClient("main-second");
+
+    resolveMatrixAuthMock.mockResolvedValue(mainAuth);
+    createMatrixClientMock
+      .mockResolvedValueOnce(firstMainClient)
+      .mockResolvedValueOnce(secondMainClient);
+
+    const first = await resolveSharedMatrixClient({ accountId: "main", startClient: false });
+    stopSharedClientInstance(first as unknown as import("../sdk.js").MatrixClient);
+    const second = await resolveSharedMatrixClient({ accountId: "main", startClient: false });
+
+    expect(first).toBe(firstMainClient);
+    expect(second).toBe(secondMainClient);
+    expect(firstMainClient.stop).toHaveBeenCalledTimes(1);
+    expect(createMatrixClientMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("reuses the effective implicit account instead of keying it as default", async () => {
+    const poeAuth = authFor("ops");
+    const poeClient = createMockClient("ops");
+
+    resolveMatrixAuthContextMock.mockReturnValue({
+      cfg: undefined,
+      env: undefined,
+      accountId: "ops",
+      resolved: {},
+    });
+    resolveMatrixAuthMock.mockResolvedValue(poeAuth);
+    createMatrixClientMock.mockResolvedValue(poeClient);
+
+    const first = await resolveSharedMatrixClient({ startClient: false });
+    const second = await resolveSharedMatrixClient({ startClient: false });
+
+    expect(first).toBe(poeClient);
+    expect(second).toBe(poeClient);
+    expect(resolveMatrixAuthMock).toHaveBeenCalledWith({
+      cfg: undefined,
+      env: undefined,
+      accountId: "ops",
+    });
+    expect(createMatrixClientMock).toHaveBeenCalledTimes(1);
+    expect(createMatrixClientMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        accountId: "ops",
+      }),
+    );
+  });
+
+  it("honors startClient false even when the caller acquires a shared lease", async () => {
+    const mainAuth = authFor("main");
+    const mainClient = createMockClient("main");
+
+    resolveMatrixAuthMock.mockResolvedValue(mainAuth);
+    createMatrixClientMock.mockResolvedValue(mainClient);
+
+    const client = await acquireSharedMatrixClient({ accountId: "main", startClient: false });
+
+    expect(client).toBe(mainClient);
+    expect(mainClient.start).not.toHaveBeenCalled();
+  });
+
+  it("keeps shared clients alive until the last one-off lease releases", async () => {
+    const mainAuth = authFor("main");
+    const mainClient = {
+      ...createMockClient("main"),
+      stopAndPersist: vi.fn(async () => undefined),
+    };
+
+    resolveMatrixAuthMock.mockResolvedValue(mainAuth);
+    createMatrixClientMock.mockResolvedValue(mainClient);
+
+    const first = await acquireSharedMatrixClient({ accountId: "main", startClient: false });
+    const second = await acquireSharedMatrixClient({ accountId: "main", startClient: false });
+
+    expect(first).toBe(mainClient);
+    expect(second).toBe(mainClient);
+
+    expect(
+      await releaseSharedClientInstance(mainClient as unknown as import("../sdk.js").MatrixClient),
+    ).toBe(false);
+    expect(mainClient.stop).not.toHaveBeenCalled();
+
+    expect(
+      await releaseSharedClientInstance(mainClient as unknown as import("../sdk.js").MatrixClient),
+    ).toBe(true);
+    expect(mainClient.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects mismatched explicit account ids when auth is already resolved", async () => {
+    await expect(
+      resolveSharedMatrixClient({
+        auth: authFor("ops"),
+        accountId: "main",
+        startClient: false,
+      }),
+    ).rejects.toThrow("Matrix shared client account mismatch");
+  });
+
+  it("lets a later waiter abort while shared startup continues for the owner", async () => {
+    const mainAuth = authFor("main");
+    let resolveStartup: (() => void) | undefined;
+    const mainClient = {
+      ...createMockClient("main"),
+      start: vi.fn(
+        async () =>
+          await new Promise<void>((resolve) => {
+            resolveStartup = resolve;
+          }),
+      ),
+    };
+
+    resolveMatrixAuthMock.mockResolvedValue(mainAuth);
+    createMatrixClientMock.mockResolvedValue(mainClient);
+
+    const ownerPromise = resolveSharedMatrixClient({ accountId: "main" });
+    await vi.waitFor(() => {
+      expect(mainClient.start).toHaveBeenCalledTimes(1);
+      expect(resolveStartup).toEqual(expect.any(Function));
+    });
+
+    const abortController = new AbortController();
+    const canceledWaiter = resolveSharedMatrixClient({
+      accountId: "main",
+      abortSignal: abortController.signal,
+    });
+    abortController.abort();
+
+    await expect(canceledWaiter).rejects.toMatchObject({
+      message: "Matrix startup aborted",
+      name: "AbortError",
+    });
+
+    resolveStartup?.();
+    await expect(ownerPromise).resolves.toBe(mainClient);
+  });
+
+  it("keeps the shared startup lock while an aborted waiter exits early", async () => {
+    const mainAuth = authFor("main");
+    let resolveStartup: (() => void) | undefined;
+    const mainClient = {
+      ...createMockClient("main"),
+      start: vi.fn(
+        async () =>
+          await new Promise<void>((resolve) => {
+            resolveStartup = resolve;
+          }),
+      ),
+    };
+
+    resolveMatrixAuthMock.mockResolvedValue(mainAuth);
+    createMatrixClientMock.mockResolvedValue(mainClient);
+
+    const ownerPromise = resolveSharedMatrixClient({ accountId: "main" });
+    await vi.waitFor(() => {
+      expect(mainClient.start).toHaveBeenCalledTimes(1);
+      expect(resolveStartup).toEqual(expect.any(Function));
+    });
+
+    const abortController = new AbortController();
+    const abortedWaiter = resolveSharedMatrixClient({
+      accountId: "main",
+      abortSignal: abortController.signal,
+    });
+    abortController.abort();
+    await expect(abortedWaiter).rejects.toMatchObject({
+      message: "Matrix startup aborted",
+      name: "AbortError",
+    });
+
+    const followerPromise = resolveSharedMatrixClient({ accountId: "main" });
+    expect(mainClient.start).toHaveBeenCalledTimes(1);
+
+    resolveStartup?.();
+    await expect(ownerPromise).resolves.toBe(mainClient);
+    await expect(followerPromise).resolves.toBe(mainClient);
+    expect(mainClient.start).toHaveBeenCalledTimes(1);
+  });
+
+  it("recreates the shared client when dispatcherPolicy changes", async () => {
+    const firstAuth = {
+      ...authFor("main"),
+      dispatcherPolicy: {
+        mode: "explicit-proxy" as const,
+        proxyUrl: "http://127.0.0.1:7890",
+      },
+    };
+    const secondAuth = {
+      ...authFor("main"),
+      dispatcherPolicy: {
+        mode: "explicit-proxy" as const,
+        proxyUrl: "http://127.0.0.1:7891",
+      },
+    };
+    const firstClient = createMockClient("main-first");
+    const secondClient = createMockClient("main-second");
+
+    resolveMatrixAuthMock.mockResolvedValueOnce(firstAuth).mockResolvedValueOnce(secondAuth);
+    createMatrixClientMock.mockResolvedValueOnce(firstClient).mockResolvedValueOnce(secondClient);
+
+    const first = await resolveSharedMatrixClient({ accountId: "main", startClient: false });
+    const second = await resolveSharedMatrixClient({ accountId: "main", startClient: false });
+
+    expect(first).toBe(firstClient);
+    expect(second).toBe(secondClient);
+    expect(createMatrixClientMock).toHaveBeenCalledTimes(2);
+  });
+});

package/src/matrix/client/shared.ts

@@ -0,0 +1,306 @@
+import { normalizeOptionalAccountId } from "openclaw/plugin-sdk/account-id";
+import type { CoreConfig } from "../../types.js";
+import type { MatrixClient } from "../sdk.js";
+import { LogService } from "../sdk/logger.js";
+import { awaitMatrixStartupWithAbort } from "../startup-abort.js";
+import { resolveMatrixAuth, resolveMatrixAuthContext } from "./config.js";
+import type { MatrixAuth } from "./types.js";
+
+type MatrixCreateClientDeps = {
+  createMatrixClient: typeof import("./create-client.js").createMatrixClient;
+};
+
+let matrixCreateClientDepsPromise: Promise<MatrixCreateClientDeps> | undefined;
+
+async function loadMatrixCreateClientDeps(): Promise<MatrixCreateClientDeps> {
+  matrixCreateClientDepsPromise ??= import("./create-client.js").then((runtime) => ({
+    createMatrixClient: runtime.createMatrixClient,
+  }));
+  return await matrixCreateClientDepsPromise;
+}
+
+type SharedMatrixClientState = {
+  client: MatrixClient;
+  key: string;
+  started: boolean;
+  cryptoReady: boolean;
+  startPromise: Promise<void> | null;
+  leases: number;
+};
+
+const sharedClientStates = new Map<string, SharedMatrixClientState>();
+const sharedClientPromises = new Map<string, Promise<SharedMatrixClientState>>();
+
+function serializeDispatcherPolicyKey(auth: MatrixAuth): string {
+  return JSON.stringify(auth.dispatcherPolicy ?? null);
+}
+
+function buildSharedClientKey(auth: MatrixAuth): string {
+  return [
+    auth.homeserver,
+    auth.userId,
+    auth.accessToken,
+    auth.encryption ? "e2ee" : "plain",
+    auth.allowPrivateNetwork ? "private-net" : "strict-net",
+    serializeDispatcherPolicyKey(auth),
+    auth.accountId,
+  ].join("|");
+}
+
+async function createSharedMatrixClient(params: {
+  auth: MatrixAuth;
+  timeoutMs?: number;
+}): Promise<SharedMatrixClientState> {
+  const { createMatrixClient } = await loadMatrixCreateClientDeps();
+  const client = await createMatrixClient({
+    homeserver: params.auth.homeserver,
+    userId: params.auth.userId,
+    accessToken: params.auth.accessToken,
+    password: params.auth.password,
+    deviceId: params.auth.deviceId,
+    encryption: params.auth.encryption,
+    localTimeoutMs: params.timeoutMs,
+    initialSyncLimit: params.auth.initialSyncLimit,
+    accountId: params.auth.accountId,
+    allowPrivateNetwork: params.auth.allowPrivateNetwork,
+    ssrfPolicy: params.auth.ssrfPolicy,
+    dispatcherPolicy: params.auth.dispatcherPolicy,
+  });
+  return {
+    client,
+    key: buildSharedClientKey(params.auth),
+    started: false,
+    cryptoReady: false,
+    startPromise: null,
+    leases: 0,
+  };
+}
+
+function findSharedClientStateByInstance(client: MatrixClient): SharedMatrixClientState | null {
+  for (const state of sharedClientStates.values()) {
+    if (state.client === client) {
+      return state;
+    }
+  }
+  return null;
+}
+
+function deleteSharedClientState(state: SharedMatrixClientState): void {
+  sharedClientStates.delete(state.key);
+  sharedClientPromises.delete(state.key);
+}
+
+async function ensureSharedClientStarted(params: {
+  state: SharedMatrixClientState;
+  encryption?: boolean;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  const waitForStart = async (startPromise: Promise<void>) => {
+    await awaitMatrixStartupWithAbort(startPromise, params.abortSignal);
+  };
+
+  if (params.state.started) {
+    return;
+  }
+  if (params.state.startPromise) {
+    await waitForStart(params.state.startPromise);
+    return;
+  }
+
+  const startPromise = (async () => {
+    const client = params.state.client;
+
+    // Initialize crypto if enabled
+    if (params.encryption && !params.state.cryptoReady) {
+      try {
+        const joinedRooms = await client.getJoinedRooms();
+        if (client.crypto) {
+          await client.crypto.prepare(joinedRooms);
+          params.state.cryptoReady = true;
+        }
+      } catch (err) {
+        LogService.warn("MatrixClientLite", "Failed to prepare crypto:", err);
+      }
+    }
+
+    await client.start({ abortSignal: params.abortSignal });
+    params.state.started = true;
+  })();
+  // Keep the shared startup lock until the underlying start fully settles, even
+  // if one waiter aborts early while another caller still owns the startup.
+  const guardedStart = startPromise.finally(() => {
+    if (params.state.startPromise === guardedStart) {
+      params.state.startPromise = null;
+    }
+  });
+  params.state.startPromise = guardedStart;
+
+  await waitForStart(guardedStart);
+}
+
+async function resolveSharedMatrixClientState(
+  params: {
+    cfg?: CoreConfig;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    auth?: MatrixAuth;
+    startClient?: boolean;
+    accountId?: string | null;
+    abortSignal?: AbortSignal;
+  } = {},
+): Promise<SharedMatrixClientState> {
+  const requestedAccountId = normalizeOptionalAccountId(params.accountId);
+  if (params.auth && requestedAccountId && requestedAccountId !== params.auth.accountId) {
+    throw new Error(
+      `Matrix shared client account mismatch: requested ${requestedAccountId}, auth resolved ${params.auth.accountId}`,
+    );
+  }
+  const authContext = params.auth
+    ? null
+    : resolveMatrixAuthContext({
+        cfg: params.cfg,
+        env: params.env,
+        accountId: params.accountId,
+      });
+  const auth =
+    params.auth ??
+    (await resolveMatrixAuth({
+      cfg: authContext?.cfg ?? params.cfg,
+      env: authContext?.env ?? params.env,
+      accountId: authContext?.accountId,
+    }));
+  const key = buildSharedClientKey(auth);
+  const shouldStart = params.startClient !== false;
+
+  const existingState = sharedClientStates.get(key);
+  if (existingState) {
+    if (shouldStart) {
+      await ensureSharedClientStarted({
+        state: existingState,
+        encryption: auth.encryption,
+        abortSignal: params.abortSignal,
+      });
+    }
+    return existingState;
+  }
+
+  const existingPromise = sharedClientPromises.get(key);
+  if (existingPromise) {
+    const pending = await existingPromise;
+    if (shouldStart) {
+      await ensureSharedClientStarted({
+        state: pending,
+        encryption: auth.encryption,
+        abortSignal: params.abortSignal,
+      });
+    }
+    return pending;
+  }
+
+  const creationPromise = createSharedMatrixClient({
+    auth,
+    timeoutMs: params.timeoutMs,
+  });
+  sharedClientPromises.set(key, creationPromise);
+
+  try {
+    const created = await creationPromise;
+    sharedClientStates.set(key, created);
+    if (shouldStart) {
+      await ensureSharedClientStarted({
+        state: created,
+        encryption: auth.encryption,
+        abortSignal: params.abortSignal,
+      });
+    }
+    return created;
+  } finally {
+    sharedClientPromises.delete(key);
+  }
+}
+
+export async function resolveSharedMatrixClient(
+  params: {
+    cfg?: CoreConfig;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    auth?: MatrixAuth;
+    startClient?: boolean;
+    accountId?: string | null;
+    abortSignal?: AbortSignal;
+  } = {},
+): Promise<MatrixClient> {
+  const state = await resolveSharedMatrixClientState(params);
+  return state.client;
+}
+
+export async function acquireSharedMatrixClient(
+  params: {
+    cfg?: CoreConfig;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    auth?: MatrixAuth;
+    startClient?: boolean;
+    accountId?: string | null;
+    abortSignal?: AbortSignal;
+  } = {},
+): Promise<MatrixClient> {
+  const state = await resolveSharedMatrixClientState(params);
+  state.leases += 1;
+  return state.client;
+}
+
+export function stopSharedClient(): void {
+  for (const state of sharedClientStates.values()) {
+    state.client.stop();
+  }
+  sharedClientStates.clear();
+  sharedClientPromises.clear();
+}
+
+export function stopSharedClientForAccount(auth: MatrixAuth): void {
+  const key = buildSharedClientKey(auth);
+  const state = sharedClientStates.get(key);
+  if (!state) {
+    return;
+  }
+  state.client.stop();
+  deleteSharedClientState(state);
+}
+
+export function removeSharedClientInstance(client: MatrixClient): boolean {
+  const state = findSharedClientStateByInstance(client);
+  if (!state) {
+    return false;
+  }
+  deleteSharedClientState(state);
+  return true;
+}
+
+export function stopSharedClientInstance(client: MatrixClient): void {
+  if (!removeSharedClientInstance(client)) {
+    return;
+  }
+  client.stop();
+}
+
+export async function releaseSharedClientInstance(
+  client: MatrixClient,
+  mode: "stop" | "persist" = "stop",
+): Promise<boolean> {
+  const state = findSharedClientStateByInstance(client);
+  if (!state) {
+    return false;
+  }
+  state.leases = Math.max(0, state.leases - 1);
+  if (state.leases > 0) {
+    return false;
+  }
+  deleteSharedClientState(state);
+  if (mode === "persist") {
+    await client.stopAndPersist();
+  } else {
+    client.stop();
+  }
+  return true;
+}