@archipelagolab/lobi 1.0.0

package/src/matrix/client/file-sync-store.ts

@@ -0,0 +1,289 @@
+import { readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  Category,
+  MemoryStore,
+  SyncAccumulator,
+  type ISyncData,
+  type IRooms,
+  type ISyncResponse,
+  type IStoredClientOpts,
+} from "@archipelagolab/lobi-js-sdk/lib/lobi.js";
+import { writeJsonFileAtomically } from "openclaw/plugin-sdk/json-store";
+import { isRecord } from "../../record-shared.js";
+import { createAsyncLock } from "../async-lock.js";
+import { LogService } from "../sdk/logger.js";
+import { claimCurrentTokenStorageState } from "./storage.js";
+
+const STORE_VERSION = 1;
+const PERSIST_DEBOUNCE_MS = 250;
+
+type PersistedMatrixSyncStore = {
+  version: number;
+  savedSync: ISyncData | null;
+  clientOptions?: IStoredClientOpts;
+  cleanShutdown?: boolean;
+};
+
+function normalizeRoomsData(value: unknown): IRooms | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  return {
+    [Category.Join]: isRecord(value[Category.Join]) ? (value[Category.Join] as IRooms["join"]) : {},
+    [Category.Invite]: isRecord(value[Category.Invite])
+      ? (value[Category.Invite] as IRooms["invite"])
+      : {},
+    [Category.Leave]: isRecord(value[Category.Leave])
+      ? (value[Category.Leave] as IRooms["leave"])
+      : {},
+    [Category.Knock]: isRecord(value[Category.Knock])
+      ? (value[Category.Knock] as IRooms["knock"])
+      : {},
+  };
+}
+
+function toPersistedSyncData(value: unknown): ISyncData | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  if (typeof value.nextBatch === "string" && value.nextBatch.trim()) {
+    const roomsData = normalizeRoomsData(value.roomsData);
+    if (!Array.isArray(value.accountData) || !roomsData) {
+      return null;
+    }
+    return {
+      nextBatch: value.nextBatch,
+      accountData: value.accountData,
+      roomsData,
+    };
+  }
+
+  // Older Matrix state files stored the raw /sync-shaped payload directly.
+  if (typeof value.next_batch === "string" && value.next_batch.trim()) {
+    const roomsData = normalizeRoomsData(value.rooms);
+    if (!roomsData) {
+      return null;
+    }
+    return {
+      nextBatch: value.next_batch,
+      accountData:
+        isRecord(value.account_data) && Array.isArray(value.account_data.events)
+          ? value.account_data.events
+          : [],
+      roomsData,
+    };
+  }
+
+  return null;
+}
+
+function readPersistedStore(raw: string): PersistedMatrixSyncStore | null {
+  try {
+    const parsed = JSON.parse(raw) as {
+      version?: unknown;
+      savedSync?: unknown;
+      clientOptions?: unknown;
+      cleanShutdown?: unknown;
+    };
+    const savedSync = toPersistedSyncData(parsed.savedSync);
+    if (parsed.version === STORE_VERSION) {
+      return {
+        version: STORE_VERSION,
+        savedSync,
+        clientOptions: isRecord(parsed.clientOptions)
+          ? (parsed.clientOptions as IStoredClientOpts)
+          : undefined,
+        cleanShutdown: parsed.cleanShutdown === true,
+      };
+    }
+
+    // Backward-compat: prior Matrix state files stored the raw sync blob at the
+    // top level without versioning or wrapped metadata.
+    return {
+      version: STORE_VERSION,
+      savedSync: toPersistedSyncData(parsed),
+      cleanShutdown: false,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function cloneJson<T>(value: T): T {
+  return structuredClone(value);
+}
+
+function syncDataToSyncResponse(syncData: ISyncData): ISyncResponse {
+  return {
+    next_batch: syncData.nextBatch,
+    rooms: syncData.roomsData,
+    account_data: {
+      events: syncData.accountData,
+    },
+  };
+}
+
+export class FileBackedMatrixSyncStore extends MemoryStore {
+  private readonly persistLock = createAsyncLock();
+  private readonly accumulator = new SyncAccumulator();
+  private savedSync: ISyncData | null = null;
+  private savedClientOptions: IStoredClientOpts | undefined;
+  private readonly hadSavedSyncOnLoad: boolean;
+  private readonly hadCleanShutdownOnLoad: boolean;
+  private cleanShutdown = false;
+  private dirty = false;
+  private persistTimer: NodeJS.Timeout | null = null;
+  private persistPromise: Promise<void> | null = null;
+
+  constructor(private readonly storagePath: string) {
+    super();
+
+    let restoredSavedSync: ISyncData | null = null;
+    let restoredClientOptions: IStoredClientOpts | undefined;
+    let restoredCleanShutdown = false;
+    try {
+      const raw = readFileSync(this.storagePath, "utf8");
+      const persisted = readPersistedStore(raw);
+      restoredSavedSync = persisted?.savedSync ?? null;
+      restoredClientOptions = persisted?.clientOptions;
+      restoredCleanShutdown = persisted?.cleanShutdown === true;
+    } catch {
+      // Missing or unreadable sync cache should not block startup.
+    }
+
+    this.savedSync = restoredSavedSync;
+    this.savedClientOptions = restoredClientOptions;
+    this.hadSavedSyncOnLoad = restoredSavedSync !== null;
+    this.hadCleanShutdownOnLoad = this.hadSavedSyncOnLoad && restoredCleanShutdown;
+    this.cleanShutdown = this.hadCleanShutdownOnLoad;
+
+    if (this.savedSync) {
+      this.accumulator.accumulate(syncDataToSyncResponse(this.savedSync), true);
+      super.setSyncToken(this.savedSync.nextBatch);
+    }
+    if (this.savedClientOptions) {
+      void super.storeClientOptions(this.savedClientOptions);
+    }
+  }
+
+  hasSavedSync(): boolean {
+    return this.hadSavedSyncOnLoad;
+  }
+
+  hasSavedSyncFromCleanShutdown(): boolean {
+    return this.hadCleanShutdownOnLoad;
+  }
+
+  override getSavedSync(): Promise<ISyncData | null> {
+    return Promise.resolve(this.savedSync ? cloneJson(this.savedSync) : null);
+  }
+
+  override getSavedSyncToken(): Promise<string | null> {
+    return Promise.resolve(this.savedSync?.nextBatch ?? null);
+  }
+
+  override setSyncData(syncData: ISyncResponse): Promise<void> {
+    this.accumulator.accumulate(syncData);
+    this.savedSync = this.accumulator.getJSON();
+    this.markDirtyAndSchedulePersist();
+    return Promise.resolve();
+  }
+
+  override getClientOptions() {
+    return Promise.resolve(
+      this.savedClientOptions ? cloneJson(this.savedClientOptions) : undefined,
+    );
+  }
+
+  override storeClientOptions(options: IStoredClientOpts) {
+    this.savedClientOptions = cloneJson(options);
+    void super.storeClientOptions(options);
+    this.markDirtyAndSchedulePersist();
+    return Promise.resolve();
+  }
+
+  override save(force = false) {
+    if (force) {
+      return this.flush();
+    }
+    return Promise.resolve();
+  }
+
+  override wantsSave(): boolean {
+    // We persist directly from setSyncData/storeClientOptions so the SDK's
+    // periodic save hook stays disabled. Shutdown uses flush() for a final sync.
+    return false;
+  }
+
+  override async deleteAllData(): Promise<void> {
+    if (this.persistTimer) {
+      clearTimeout(this.persistTimer);
+      this.persistTimer = null;
+    }
+    this.dirty = false;
+    await this.persistPromise?.catch(() => undefined);
+    await super.deleteAllData();
+    this.savedSync = null;
+    this.savedClientOptions = undefined;
+    this.cleanShutdown = false;
+    await fs.rm(this.storagePath, { force: true }).catch(() => undefined);
+  }
+
+  markCleanShutdown(): void {
+    this.cleanShutdown = true;
+    this.dirty = true;
+  }
+
+  async flush(): Promise<void> {
+    if (this.persistTimer) {
+      clearTimeout(this.persistTimer);
+      this.persistTimer = null;
+    }
+    while (this.dirty || this.persistPromise) {
+      if (this.dirty && !this.persistPromise) {
+        this.persistPromise = this.persist().finally(() => {
+          this.persistPromise = null;
+        });
+      }
+      await this.persistPromise;
+    }
+  }
+
+  private markDirtyAndSchedulePersist(): void {
+    this.cleanShutdown = false;
+    this.dirty = true;
+    if (this.persistTimer) {
+      return;
+    }
+    this.persistTimer = setTimeout(() => {
+      this.persistTimer = null;
+      void this.flush().catch((err) => {
+        LogService.warn("MatrixFileSyncStore", "Failed to persist Matrix sync store:", err);
+      });
+    }, PERSIST_DEBOUNCE_MS);
+    this.persistTimer.unref?.();
+  }
+
+  private async persist(): Promise<void> {
+    this.dirty = false;
+    const payload: PersistedMatrixSyncStore = {
+      version: STORE_VERSION,
+      savedSync: this.savedSync ? cloneJson(this.savedSync) : null,
+      cleanShutdown: this.cleanShutdown,
+      ...(this.savedClientOptions ? { clientOptions: cloneJson(this.savedClientOptions) } : {}),
+    };
+    try {
+      await this.persistLock(async () => {
+        await writeJsonFileAtomically(this.storagePath, payload);
+        claimCurrentTokenStorageState({
+          rootDir: path.dirname(this.storagePath),
+        });
+      });
+    } catch (err) {
+      this.dirty = true;
+      throw err;
+    }
+  }
+}

package/src/matrix/client/logging.ts

@@ -0,0 +1,123 @@
+import { logger as matrixJsSdkRootLogger } from "@archipelagolab/lobi-js-sdk/lib/logger.js";
+import { ConsoleLogger, LogService, setMatrixConsoleLogging } from "../sdk/logger.js";
+
+let matrixSdkLoggingConfigured = false;
+let matrixSdkLogMode: "default" | "quiet" = "default";
+const matrixSdkBaseLogger = new ConsoleLogger();
+const matrixSdkSilentMethodFactory = () => () => {};
+let matrixSdkRootMethodFactory: unknown;
+let matrixSdkRootLoggerInitialized = false;
+
+type MatrixJsSdkLogger = {
+  trace: (...messageOrObject: unknown[]) => void;
+  debug: (...messageOrObject: unknown[]) => void;
+  info: (...messageOrObject: unknown[]) => void;
+  warn: (...messageOrObject: unknown[]) => void;
+  error: (...messageOrObject: unknown[]) => void;
+  getChild: (namespace: string) => MatrixJsSdkLogger;
+};
+
+function shouldSuppressMatrixHttpNotFound(module: string, messageOrObject: unknown[]): boolean {
+  if (!module.includes("MatrixHttpClient")) {
+    return false;
+  }
+  return messageOrObject.some((entry) => {
+    if (!entry || typeof entry !== "object") {
+      return false;
+    }
+    return (entry as { errcode?: string }).errcode === "M_NOT_FOUND";
+  });
+}
+
+export function ensureMatrixSdkLoggingConfigured(): void {
+  if (!matrixSdkLoggingConfigured) {
+    matrixSdkLoggingConfigured = true;
+  }
+  applyMatrixSdkLogger();
+}
+
+export function setMatrixSdkLogMode(mode: "default" | "quiet"): void {
+  matrixSdkLogMode = mode;
+  if (!matrixSdkLoggingConfigured) {
+    return;
+  }
+  applyMatrixSdkLogger();
+}
+
+export function setMatrixSdkConsoleLogging(enabled: boolean): void {
+  setMatrixConsoleLogging(enabled);
+}
+
+export function createMatrixJsSdkClientLogger(prefix = "matrix"): MatrixJsSdkLogger {
+  return createMatrixJsSdkLoggerInstance(prefix);
+}
+
+function applyMatrixJsSdkRootLoggerMode(): void {
+  const rootLogger = matrixJsSdkRootLogger as {
+    methodFactory?: unknown;
+    rebuild?: () => void;
+  };
+  if (!matrixSdkRootLoggerInitialized) {
+    matrixSdkRootMethodFactory = rootLogger.methodFactory;
+    matrixSdkRootLoggerInitialized = true;
+  }
+  rootLogger.methodFactory =
+    matrixSdkLogMode === "quiet" ? matrixSdkSilentMethodFactory : matrixSdkRootMethodFactory;
+  rootLogger.rebuild?.();
+}
+
+function applyMatrixSdkLogger(): void {
+  applyMatrixJsSdkRootLoggerMode();
+  if (matrixSdkLogMode === "quiet") {
+    LogService.setLogger({
+      trace: () => {},
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+    });
+    return;
+  }
+
+  LogService.setLogger({
+    trace: (module, ...messageOrObject) => matrixSdkBaseLogger.trace(module, ...messageOrObject),
+    debug: (module, ...messageOrObject) => matrixSdkBaseLogger.debug(module, ...messageOrObject),
+    info: (module, ...messageOrObject) => matrixSdkBaseLogger.info(module, ...messageOrObject),
+    warn: (module, ...messageOrObject) => matrixSdkBaseLogger.warn(module, ...messageOrObject),
+    error: (module, ...messageOrObject) => {
+      if (shouldSuppressMatrixHttpNotFound(module, messageOrObject)) {
+        return;
+      }
+      matrixSdkBaseLogger.error(module, ...messageOrObject);
+    },
+  });
+}
+
+function createMatrixJsSdkLoggerInstance(prefix: string): MatrixJsSdkLogger {
+  const log = (method: keyof ConsoleLogger, ...messageOrObject: unknown[]): void => {
+    if (matrixSdkLogMode === "quiet") {
+      return;
+    }
+    (matrixSdkBaseLogger[method] as (module: string, ...args: unknown[]) => void)(
+      prefix,
+      ...messageOrObject,
+    );
+  };
+
+  return {
+    trace: (...messageOrObject) => log("trace", ...messageOrObject),
+    debug: (...messageOrObject) => log("debug", ...messageOrObject),
+    info: (...messageOrObject) => log("info", ...messageOrObject),
+    warn: (...messageOrObject) => log("warn", ...messageOrObject),
+    error: (...messageOrObject) => {
+      if (shouldSuppressMatrixHttpNotFound(prefix, messageOrObject)) {
+        return;
+      }
+      log("error", ...messageOrObject);
+    },
+    getChild: (namespace: string) => {
+      const nextNamespace = namespace.trim();
+      return createMatrixJsSdkLoggerInstance(nextNamespace ? `${prefix}.${nextNamespace}` : prefix);
+    },
+  };
+}

package/src/matrix/client/migration-snapshot.runtime.ts

@@ -0,0 +1 @@
+export { maybeCreateMatrixMigrationSnapshot } from "../../migration-snapshot-backup.js";

package/src/matrix/client/private-network-host.ts

@@ -0,0 +1,56 @@
+import net from "node:net";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+
+function normalizeHost(host: string): string {
+  const normalized = normalizeLowercaseStringOrEmpty(host).replace(/\.+$/, "");
+  return normalized.startsWith("[") && normalized.endsWith("]")
+    ? normalized.slice(1, -1)
+    : normalized;
+}
+
+function isPrivateIpv4(host: string): boolean {
+  const parts = host.split(".").map((part) => Number(part));
+  if (
+    parts.length !== 4 ||
+    parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)
+  ) {
+    return false;
+  }
+  const [a, b] = parts;
+  return (
+    a === 10 ||
+    a === 127 ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) ||
+    (a === 169 && b === 254) ||
+    (a === 100 && b >= 64 && b <= 127)
+  );
+}
+
+function isPrivateIpv6(host: string): boolean {
+  if (host === "::1") {
+    return true;
+  }
+  if (host === "::" || host.startsWith("ff")) {
+    return false;
+  }
+  return host.startsWith("fc") || host.startsWith("fd") || host.startsWith("fe80:");
+}
+
+export function isPrivateOrLoopbackHost(host: string): boolean {
+  const normalized = normalizeHost(host);
+  if (!normalized) {
+    return false;
+  }
+  if (normalized === "localhost") {
+    return true;
+  }
+  const family = net.isIP(normalized);
+  if (family === 4) {
+    return isPrivateIpv4(normalized);
+  }
+  if (family === 6) {
+    return isPrivateIpv6(normalized);
+  }
+  return false;
+}

package/src/matrix/client/runtime.ts

@@ -0,0 +1,4 @@
+export function isBunRuntime(): boolean {
+  const versions = process.versions as { bun?: string };
+  return typeof versions.bun === "string";
+}