fix(config): coalesce rapid rebuildCache calls to eliminate O(n²) load (#391)

Closes #388.

## Problem
Every config mutation (`saveProvider`, `saveAlias`, `deleteKey`,
`setSetting`, etc.) immediately awaited `rebuildCache()`, which issues
~6–8 DB queries and reloads the `QuotaScheduler`. A bulk import of 20
aliases therefore triggered 20 full cache rebuilds and 20 scheduler
reloads — `O(n²)` load.

## Solution
Introduced lightweight write coalescing inside `ConfigService`:

1. **Pending-writes counter** — incremented on every mutation.
2. **Deferred `rebuildCache()`** — if pending writes exist, schedule a
single rebuild for 100ms later instead of running immediately. The timer
is reset on every new mutation so only the final call in a burst hits
the DB.
3. **Promise deduplication** — an in-flight rebuild is tracked so
duplicate callers wait on the same promise.
4. **Explicit `flush()`** — for tests or callers that need immediate
consistency.

## Changes
- `packages/backend/src/services/config-service.ts`
- Add `pendingWrites`, `coalesceTimer`, `rebuildPromise`, `COALESCE_MS`
- Convert mutation methods from `await this.rebuildCache()` to
fire-and-forget scheduling
  - Rename original rebuild logic to `doRebuild()`
- Add `executeRebuild()` for synchronous callers (`initialize`,
`migrateLegacyTargetGroups`)
  - Add public `flush()`
- `packages/backend/src/services/__tests__/config-service.test.ts`
*(new)*
  - Tests that rapid mutations coalesce to a single rebuild
  - Tests that `flush()` forces an immediate rebuild
  - Tests that the timer eventually fires after mutations

## Backwards compatibility
All existing callers continue to work — the mutation shape is unchanged
(`async saveProvider(...)` still returns `Promise<void>`). The only
observable difference is that bulk writes complete faster and the cache
is eventually consistent within ~100ms.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

packages/backend/src/services/__tests__/config-service.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+
+vi.mock('../quota/quota-scheduler', () => ({
+  QuotaScheduler: {
+    getInstance: vi.fn(() => ({
+      getCheckerIds: vi.fn(() => []),
+      reload: vi.fn(),
+    })),
+  },
+}));
+
+import { ConfigService } from '../config-service';
+
+function createMockRepo() {
+  return {
+    saveProvider: vi.fn(),
+    deleteProvider: vi.fn(),
+    saveAlias: vi.fn(),
+    deleteAlias: vi.fn(),
+    deleteAllAliases: vi.fn(() => Promise.resolve(0)),
+    saveKey: vi.fn(),
+    deleteKey: vi.fn(),
+    saveUserQuota: vi.fn(),
+    deleteUserQuota: vi.fn(),
+    saveMcpServer: vi.fn(),
+    deleteMcpServer: vi.fn(),
+    setSetting: vi.fn(),
+    setSettingsBulk: vi.fn(),
+    getAllProviders: vi.fn(() => Promise.resolve({})),
+    getAllAliases: vi.fn(() => Promise.resolve({})),
+    getAllKeys: vi.fn(() => Promise.resolve({})),
+    getAllUserQuotas: vi.fn(() => Promise.resolve({})),
+    getAllMcpServers: vi.fn(() => Promise.resolve({})),
+    getFailoverPolicy: vi.fn(() => Promise.resolve({ enabled: false })),
+    getCooldownPolicy: vi.fn(() => Promise.resolve({ enabled: false })),
+    getAllSettings: vi.fn(() => Promise.resolve({})),
+  };
+}
+
+describe('ConfigService write coalescing', () => {
+  let service: ConfigService;
+  let mockRepo: ReturnType<typeof createMockRepo>;
+  let rebuildCount: number;
+
+  beforeEach(() => {
+    ConfigService.resetInstance();
+    rebuildCount = 0;
+    mockRepo = createMockRepo();
+
+    service = new ConfigService(mockRepo as any);
+
+    // Spy on doRebuild to count actual database-level rebuilds
+    const original = (service as any).doRebuild.bind(service);
+    (service as any).doRebuild = async () => {
+      rebuildCount++;
+      // Still call original so the cache is populated and flush() works
+      await original();
+    };
+  });
+
+  afterEach(() => {
+    ConfigService.resetInstance();
+    vi.useRealTimers();
+  });
+
+  it('coalesces multiple rapid mutations into a single rebuild', async () => {
+    vi.useFakeTimers();
+
+    await service.saveProvider('p1', {} as any);
+    await service.saveProvider('p2', {} as any);
+    await service.saveAlias('a1', {} as any);
+
+    expect(rebuildCount).toBe(0);
+
+    await vi.advanceTimersByTimeAsync(150);
+
+    expect(rebuildCount).toBe(1);
+
+    vi.useRealTimers();
+  });
+
+  it('flush forces immediate rebuild', async () => {
+    vi.useFakeTimers();
+
+    await service.saveProvider('p1', {} as any);
+    expect(rebuildCount).toBe(0);
+
+    await service.flush();
+    expect(rebuildCount).toBe(1);
+
+    vi.useRealTimers();
+  });
+
+  it('timer eventually fires and rebuilds after mutations', async () => {
+    vi.useFakeTimers();
+
+    await service.saveProvider('p1', {} as any);
+    expect(rebuildCount).toBe(0);
+
+    await vi.advanceTimersByTimeAsync(150);
+    expect(rebuildCount).toBe(1);
+
+    // A subsequent mutation triggers a new rebuild cycle
+    await service.saveAlias('a1', {} as any);
+    expect(rebuildCount).toBe(1);
+
+    await vi.advanceTimersByTimeAsync(150);
+    expect(rebuildCount).toBe(2);
+
+    vi.useRealTimers();
+  });
+});

packages/backend/src/services/config-service.ts

@@ -29,6 +29,15 @@ export class ConfigService {
   private cache: PlexusConfig | null = null;
   private repo: ConfigRepository;
 
+  /** Number of writes issued since the last rebuild; used for coalescing. */
+  private pendingWrites = 0;
+  /** Active timer for a deferred rebuild. */
+  private coalesceTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Promise for an in-flight rebuild so parallel callers can wait on it. */
+  private rebuildPromise: Promise<void> | null = null;
+  /** Delay (ms) before a coalesced rebuild fires. */
+  private readonly COALESCE_MS = 100;
+
   constructor(repo?: ConfigRepository) {
     this.repo = repo ?? new ConfigRepository();
   }
@@ -63,7 +72,7 @@ export class ConfigService {
    * Must be called once during startup, after DB is initialized.
    */
   async initialize(): Promise<void> {
-    await this.rebuildCache();
+    await this.executeRebuild();
     logger.debug('ConfigService initialized from database');
   }
 
@@ -80,7 +89,7 @@ export class ConfigService {
       logger.info(
         `Migrated ${migrated.length} legacy aliases to target groups: ${migrated.join(', ')}`
       );
-      await this.rebuildCache();
+      await this.executeRebuild();
     }
     return migrated;
   }
@@ -107,78 +116,91 @@ export class ConfigService {
 
   async saveProvider(slug: string, config: ProviderConfig): Promise<void> {
     await this.repo.saveProvider(slug, config);
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
   }
 
   async deleteProvider(slug: string, cascade: boolean = true): Promise<void> {
     await this.repo.deleteProvider(slug, cascade);
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
   }
 
   // ─── Alias CRUD ──────────────────────────────────────────────────
 
   async saveAlias(slug: string, config: ModelConfig): Promise<void> {
     await this.repo.saveAlias(slug, config);
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
   }
 
   async deleteAlias(slug: string): Promise<void> {
     await this.repo.deleteAlias(slug);
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
   }
 
   async deleteAllAliases(): Promise<number> {
     const count = await this.repo.deleteAllAliases();
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
     return count;
   }
 
   // ─── Key CRUD ────────────────────────────────────────────────────
 
   async saveKey(name: string, config: KeyConfig): Promise<void> {
     await this.repo.saveKey(name, config);
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
   }
 
   async deleteKey(name: string): Promise<void> {
     await this.repo.deleteKey(name);
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
   }
 
   // ─── User Quota CRUD ─────────────────────────────────────────────
 
   async saveUserQuota(name: string, quota: QuotaDefinition): Promise<void> {
     await this.repo.saveUserQuota(name, quota);
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
   }
 
   async deleteUserQuota(name: string): Promise<void> {
     await this.repo.deleteUserQuota(name);
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
   }
 
   // ─── MCP Server CRUD ─────────────────────────────────────────────
 
   async saveMcpServer(name: string, config: McpServerConfig): Promise<void> {
     await this.repo.saveMcpServer(name, config);
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
   }
 
   async deleteMcpServer(name: string): Promise<void> {
     await this.repo.deleteMcpServer(name);
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
   }
 
   // ─── Settings ─────────────────────────────────────────────────────
 
   async setSetting(key: string, value: unknown): Promise<void> {
     await this.repo.setSetting(key, value);
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
   }
 
   async setSettingsBulk(entries: Record<string, unknown>): Promise<void> {
     await this.repo.setSettingsBulk(entries);
-    await this.rebuildCache();
+    this.pendingWrites++;
+    this.rebuildCache();
   }
 
   async getSetting<T>(key: string, defaultValue: T): Promise<T> {
@@ -268,12 +290,83 @@ export class ConfigService {
     };
   }
 
+  // ─── Write Coalescing & Cache Flush ─────────────────────────────
+
+  /**
+   * Force an immediate, synchronous cache rebuild.
+   * Cancels any pending coalesced rebuild and waits for an in-flight one.
+   * Useful in tests or operations that need immediate consistency.
+   */
+  async flush(): Promise<void> {
+    if (this.coalesceTimer) {
+      clearTimeout(this.coalesceTimer);
+      this.coalesceTimer = null;
+    }
+    if (this.rebuildPromise) {
+      await this.rebuildPromise;
+    }
+    this.pendingWrites = 0;
+    await this.executeRebuild();
+  }
+
   // ─── Internal ────────────────────────────────────────────────────
 
   /**
-   * Rebuild the in-memory cache from the database.
+   * Schedule a cache rebuild, coalescing rapid successive calls.
+   * If pending writes are present the rebuild is deferred; only the
+   * final call in a burst actually hits the database.
+   */
+  private rebuildCache(): void {
+    if (this.coalesceTimer) {
+      clearTimeout(this.coalesceTimer);
+      this.coalesceTimer = null;
+    }
+
+    if (this.pendingWrites > 0) {
+      this.coalesceTimer = setTimeout(() => {
+        this.pendingWrites = 0;
+        this.rebuildCache();
+      }, this.COALESCE_MS);
+      return;
+    }
+
+    if (this.rebuildPromise) {
+      this.coalesceTimer = setTimeout(() => this.rebuildCache(), this.COALESCE_MS);
+      return;
+    }
+
+    const promise = this.executeRebuild();
+    this.rebuildPromise = promise;
+    promise.finally(() => {
+      if (this.rebuildPromise === promise) {
+        this.rebuildPromise = null;
+      }
+    });
+  }
+
+  /**
+   * Execute the actual cache rebuild. Guarantees that only one rebuild
+   * runs concurrently; duplicate callers receive the in-flight promise.
+   */
+  private async executeRebuild(): Promise<void> {
+    if (this.rebuildPromise) {
+      return this.rebuildPromise;
+    }
+    const promise = this.doRebuild();
+    this.rebuildPromise = promise;
+    try {
+      await promise;
+    } finally {
+      if (this.rebuildPromise === promise) {
+        this.rebuildPromise = null;
+      }
+    }
+  }
+
+  /**
+   * Core rebuild logic — loads the full config graph from the database.
    */
-  private async rebuildCache(): Promise<void> {
+  private async doRebuild(): Promise<void> {
     const providers = await this.repo.getAllProviders();
     const models = await this.repo.getAllAliases();
     const keys = await this.repo.getAllKeys();