Merge pull request #925 from kaitranntt/kai/feat/cliproxy-routing-guidance

feat(cliproxy): add routing guidance and strategy controls

tests/unit/cliproxy/management-api-client.test.ts

@@ -90,6 +90,54 @@ describe('management-api-client', () => {
       });
     });
 
+    describe('routing strategy helpers', () => {
+      it('reads the routing strategy from the management endpoint', async () => {
+        const client = new ManagementApiClient(config);
+        const originalFetch = global.fetch;
+        const fetchMock = mock(() =>
+          Promise.resolve(
+            new Response(JSON.stringify({ strategy: 'fill-first' }), {
+              status: 200,
+              headers: { 'Content-Type': 'application/json' },
+            })
+          )
+        );
+        global.fetch = fetchMock as typeof global.fetch;
+
+        const strategy = await client.getRoutingStrategy();
+
+        expect(strategy).toBe('fill-first');
+        expect(fetchMock).toHaveBeenCalled();
+        global.fetch = originalFetch;
+      });
+
+      it('writes the routing strategy using the expected payload shape', async () => {
+        const client = new ManagementApiClient(config);
+        const originalFetch = global.fetch;
+        const fetchMock = mock(() =>
+          Promise.resolve(
+            new Response(JSON.stringify({ ok: true }), {
+              status: 200,
+              headers: { 'Content-Type': 'application/json' },
+            })
+          )
+        );
+        global.fetch = fetchMock as typeof global.fetch;
+
+        const strategy = await client.putRoutingStrategy('round-robin');
+
+        expect(strategy).toBe('round-robin');
+        expect(fetchMock).toHaveBeenCalledWith(
+          'http://localhost:8317/routing/strategy',
+          expect.objectContaining({
+            method: 'PUT',
+            body: JSON.stringify({ value: 'round-robin' }),
+          })
+        );
+        global.fetch = originalFetch;
+      });
+    });
+
     describe('error code mapping', () => {
       it('should map ENOTFOUND to DNS_FAILED', () => {
         const error = new Error('getaddrinfo ENOTFOUND example.com') as NodeJS.ErrnoException;

tests/unit/cliproxy/routing-strategy.test.ts

@@ -0,0 +1,127 @@
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+describe('cliproxy routing strategy service', () => {
+  let tempHome = '';
+  let originalCcsHome: string | undefined;
+  let setGlobalConfigDir: (dir: string | undefined) => void;
+  let routingTarget = {
+    host: '127.0.0.1',
+    port: 8317,
+    protocol: 'http' as const,
+    isRemote: false,
+  };
+  let responseFactory: (() => Promise<Response>) | null = null;
+
+  beforeEach(async () => {
+    originalCcsHome = process.env.CCS_HOME;
+    tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-routing-strategy-'));
+    process.env.CCS_HOME = tempHome;
+
+    ({ setGlobalConfigDir } = await import('../../../src/utils/config-manager'));
+    setGlobalConfigDir(path.join(tempHome, '.ccs'));
+  });
+
+  afterEach(() => {
+    mock.restore();
+    setGlobalConfigDir(undefined);
+
+    if (originalCcsHome !== undefined) {
+      process.env.CCS_HOME = originalCcsHome;
+    } else {
+      delete process.env.CCS_HOME;
+    }
+
+    if (tempHome && fs.existsSync(tempHome)) {
+      fs.rmSync(tempHome, { recursive: true, force: true });
+    }
+  });
+
+  async function loadRoutingModule() {
+    mock.module('../../../src/cliproxy/routing-strategy-http', () => ({
+      getCliproxyRoutingTarget: () => routingTarget,
+      fetchCliproxyRoutingResponse: () => {
+        if (!responseFactory) {
+          throw new Error('routing unavailable');
+        }
+        return responseFactory();
+      },
+      getRoutingErrorMessage: async (response: Response, fallback: string) => {
+        const body = (await response.json().catch(() => null)) as { error?: string } | null;
+        return body?.error || fallback;
+      },
+    }));
+
+    return import(`../../../src/cliproxy/routing-strategy?test=${Date.now()}-${Math.random()}`);
+  }
+
+  it('normalizes canonical and shorthand strategy values', async () => {
+    const mod = await loadRoutingModule();
+
+    expect(mod.normalizeCliproxyRoutingStrategy('round-robin')).toBe('round-robin');
+    expect(mod.normalizeCliproxyRoutingStrategy('RR')).toBe('round-robin');
+    expect(mod.normalizeCliproxyRoutingStrategy('fillfirst')).toBe('fill-first');
+    expect(mod.normalizeCliproxyRoutingStrategy('ff')).toBe('fill-first');
+    expect(mod.normalizeCliproxyRoutingStrategy('nope')).toBeNull();
+  });
+
+  it('falls back to the saved local default when live CLIProxy is unavailable', async () => {
+    const { mutateUnifiedConfig } = await import('../../../src/config/unified-config-loader');
+    mutateUnifiedConfig((config) => {
+      if (config.cliproxy) {
+        config.cliproxy.routing = { strategy: 'fill-first' };
+      }
+    });
+
+    const mod = await loadRoutingModule();
+    const state = await mod.readCliproxyRoutingState();
+
+    expect(state.strategy).toBe('fill-first');
+    expect(state.source).toBe('config');
+    expect(state.target).toBe('local');
+    expect(state.reachable).toBe(false);
+  });
+
+  it('persists the local startup default even when the live proxy is down', async () => {
+    const mod = await loadRoutingModule();
+    const result = await mod.applyCliproxyRoutingStrategy('fill-first');
+
+    expect(result.applied).toBe('config-only');
+    expect(result.strategy).toBe('fill-first');
+
+    const configPath = path.join(tempHome, '.ccs', 'cliproxy', 'config.yaml');
+    const configContent = fs.readFileSync(configPath, 'utf8');
+    expect(configContent).toContain('routing:');
+    expect(configContent).toContain('strategy: fill-first');
+  });
+
+  it('reads and writes remote strategy without mutating the local default', async () => {
+    routingTarget = {
+      host: 'remote.example.com',
+      port: 8080,
+      protocol: 'http',
+      isRemote: true,
+    };
+
+    let methodCount = 0;
+    responseFactory = async () => {
+      methodCount += 1;
+      return new Response(JSON.stringify({ strategy: 'fill-first' }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    };
+
+    const mod = await loadRoutingModule();
+    const readState = await mod.readCliproxyRoutingState();
+    const writeState = await mod.applyCliproxyRoutingStrategy('fill-first');
+
+    expect(readState.strategy).toBe('fill-first');
+    expect(readState.target).toBe('remote');
+    expect(writeState.applied).toBe('live');
+    expect(mod.getConfiguredCliproxyRoutingStrategy()).toBe('round-robin');
+    expect(methodCount).toBe(2);
+  });
+});

tests/unit/commands/cliproxy-routing-subcommand.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
+
+describe('cliproxy routing command dispatch', () => {
+  let calls: string[] = [];
+
+  beforeEach(() => {
+    calls = [];
+
+    mock.module('../../../src/commands/cliproxy/routing-subcommand', () => ({
+      handleRoutingStatus: async () => {
+        calls.push('status');
+      },
+      handleRoutingExplain: async () => {
+        calls.push('explain');
+      },
+      handleRoutingSet: async (args: string[]) => {
+        calls.push(`set:${args.join(' ')}`);
+      },
+    }));
+  });
+
+  afterEach(() => {
+    mock.restore();
+  });
+
+  async function loadHandleCliproxyCommand() {
+    const mod = await import(`../../../src/commands/cliproxy/index?test=${Date.now()}-${Math.random()}`);
+    return mod.handleCliproxyCommand;
+  }
+
+  it('shows routing status by default', async () => {
+    const handleCliproxyCommand = await loadHandleCliproxyCommand();
+    await handleCliproxyCommand(['routing']);
+    expect(calls).toEqual(['status']);
+  });
+
+  it('shows the routing explainer', async () => {
+    const handleCliproxyCommand = await loadHandleCliproxyCommand();
+    await handleCliproxyCommand(['routing', 'explain']);
+    expect(calls).toEqual(['explain']);
+  });
+
+  it('passes the explicit strategy to set', async () => {
+    const handleCliproxyCommand = await loadHandleCliproxyCommand();
+    await handleCliproxyCommand(['routing', 'set', 'fill-first']);
+    expect(calls).toEqual(['set:fill-first']);
+  });
+});

tests/unit/web-server/cliproxy-routing-routes.test.ts

@@ -0,0 +1,106 @@
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
+import express from 'express';
+import type { Server } from 'http';
+
+describe('cliproxy routing routes', () => {
+  let server: Server;
+  let baseUrl = '';
+  let readStateMock: ReturnType<typeof mock>;
+  let applyStrategyMock: ReturnType<typeof mock>;
+
+  beforeEach(async () => {
+    readStateMock = mock(async () => ({
+      strategy: 'round-robin',
+      source: 'live',
+      target: 'local',
+      reachable: true,
+    }));
+    applyStrategyMock = mock(async () => ({
+      strategy: 'fill-first',
+      source: 'live',
+      target: 'local',
+      reachable: true,
+      applied: 'live-and-config',
+    }));
+
+    mock.module('../../../src/cliproxy/routing-strategy', () => ({
+      readCliproxyRoutingState: readStateMock,
+      applyCliproxyRoutingStrategy: applyStrategyMock,
+      normalizeCliproxyRoutingStrategy: (value: unknown) => {
+        if (value === 'round-robin' || value === 'fill-first') {
+          return value;
+        }
+        return null;
+      },
+    }));
+
+    const { default: routingRoutes } = await import(
+      `../../../src/web-server/routes/cliproxy-routing-routes?test=${Date.now()}-${Math.random()}`
+    );
+
+    const app = express();
+    app.use(express.json());
+    app.use('/api/cliproxy', routingRoutes);
+
+    server = await new Promise<Server>((resolve, reject) => {
+      const instance = app.listen(0, '127.0.0.1');
+      instance.once('error', reject);
+      instance.once('listening', () => resolve(instance));
+    });
+
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+      throw new Error('Unable to resolve test server port');
+    }
+    baseUrl = `http://127.0.0.1:${address.port}`;
+  });
+
+  afterEach(async () => {
+    mock.restore();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  it('returns the current routing state', async () => {
+    const response = await fetch(`${baseUrl}/api/cliproxy/routing/strategy`);
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({
+      strategy: 'round-robin',
+      source: 'live',
+      target: 'local',
+      reachable: true,
+    });
+    expect(readStateMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects invalid routing values', async () => {
+    const response = await fetch(`${baseUrl}/api/cliproxy/routing/strategy`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value: 'auto' }),
+    });
+
+    expect(response.status).toBe(400);
+    expect(await response.json()).toEqual({
+      error: 'Invalid strategy. Use: round-robin or fill-first',
+    });
+    expect(applyStrategyMock).not.toHaveBeenCalled();
+  });
+
+  it('applies a valid routing strategy', async () => {
+    const response = await fetch(`${baseUrl}/api/cliproxy/routing/strategy`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value: 'fill-first' }),
+    });
+
+    expect(response.status).toBe(200);
+    expect(applyStrategyMock).toHaveBeenCalledWith('fill-first');
+    expect(await response.json()).toEqual({
+      strategy: 'fill-first',
+      source: 'live',
+      target: 'local',
+      reachable: true,
+      applied: 'live-and-config',
+    });
+  });
+});