feat: add rate limiting, concurrency control, and timeout utilities with IP filtering support

apps/e2e/demo-e2e-guard/e2e/browser/guard-browser.pw.spec.ts

@@ -0,0 +1,128 @@
+/**
+ * Playwright Browser E2E Tests for Guard
+ *
+ * Tests that guard errors are properly returned when requests come from
+ * a browser client via raw HTTP JSON-RPC calls to the MCP endpoint.
+ *
+ * Uses Playwright's `request` API fixture for HTTP testing (no DOM needed).
+ */
+import { test, expect, type APIRequestContext } from '@playwright/test';
+
+const MCP_ENDPOINT = '/mcp';
+
+/**
+ * Initialize an MCP session and return the session ID from the response header.
+ */
+async function initializeSession(request: APIRequestContext) {
+  const response = await request.post(MCP_ENDPOINT, {
+    data: {
+      jsonrpc: '2.0',
+      id: 'init-1',
+      method: 'initialize',
+      params: {
+        protocolVersion: '2025-03-26',
+        capabilities: {},
+        clientInfo: { name: 'playwright-test', version: '1.0.0' },
+      },
+    },
+    headers: { 'Content-Type': 'application/json' },
+  });
+
+  expect(response.ok()).toBe(true);
+  const body = await response.json();
+  expect(body.error).toBeUndefined();
+
+  const sessionId = response.headers()['mcp-session-id'];
+  expect(sessionId).toBeTruthy();
+  return { response, sessionId };
+}
+
+/**
+ * Call a tool via raw JSON-RPC POST.
+ */
+async function callTool(
+  request: APIRequestContext,
+  sessionId: string,
+  toolName: string,
+  args: Record<string, unknown>,
+  id: string | number = 'call-1',
+) {
+  return request.post(MCP_ENDPOINT, {
+    data: {
+      jsonrpc: '2.0',
+      id,
+      method: 'tools/call',
+      params: { name: toolName, arguments: args },
+    },
+    headers: {
+      'Content-Type': 'application/json',
+      'mcp-session-id': sessionId,
+    },
+  });
+}
+
+async function warmUpRateLimited(request: APIRequestContext, sessionId: string, count: number, idPrefix = 'call') {
+  for (let i = 0; i < count; i++) {
+    const response = await callTool(request, sessionId, 'rate-limited', { message: `req-${i}` }, `${idPrefix}-${i}`);
+    expect(response.status()).toBe(200);
+    const body = await response.json();
+    expect(body.result?.isError).not.toBe(true);
+  }
+}
+
+test.describe('Guard Browser E2E', () => {
+  test('should call tool successfully via browser HTTP', async ({ request }) => {
+    const { sessionId } = await initializeSession(request);
+    expect(sessionId).toBeTruthy();
+
+    const response = await callTool(request, sessionId, 'unguarded', { value: 'browser-test' });
+    expect(response.status()).toBe(200);
+
+    const body = await response.json();
+    expect(body.result).toBeDefined();
+    expect(body.result.isError).not.toBe(true);
+  });
+
+  test('should receive rate limit error after exceeding limit', async ({ request }) => {
+    const { sessionId } = await initializeSession(request);
+
+    // Send 3 requests (within limit)
+    await warmUpRateLimited(request, sessionId, 3);
+
+    // 4th request should trigger rate limit
+    const response = await callTool(request, sessionId, 'rate-limited', { message: 'over-limit' }, 'call-blocked');
+    expect(response.status()).toBe(200);
+    const body = await response.json();
+
+    // Rate limit errors surface as isError: true in the tool result
+    expect(body.result?.isError).toBe(true);
+    const content = JSON.stringify(body.result?.content ?? []);
+    expect(content.toLowerCase()).toMatch(/rate.limit|retry|too.many/i);
+  });
+
+  test('should receive timeout error for slow execution', async ({ request }) => {
+    const { sessionId } = await initializeSession(request);
+
+    // timeout-tool has 500ms timeout, 1000ms delay exceeds it
+    const response = await callTool(request, sessionId, 'timeout-tool', { delayMs: 1000 }, 'call-timeout');
+    expect(response.status()).toBe(200);
+    const body = await response.json();
+
+    expect(body.result?.isError).toBe(true);
+    const content = JSON.stringify(body.result?.content ?? []);
+    expect(content.toLowerCase()).toMatch(/timeout|timed.out/i);
+  });
+
+  test('should call multiple tools and maintain rate limit state via HTTP', async ({ request }) => {
+    const { sessionId } = await initializeSession(request);
+
+    // Call rate-limited tool 3 times (within limit)
+    await warmUpRateLimited(request, sessionId, 3);
+
+    // 4th call should hit the per-tool rate limit
+    const response = await callTool(request, sessionId, 'rate-limited', { message: 'over' }, 'call-blocked');
+    expect(response.status()).toBe(200); // MCP returns 200 with error in body
+    const body = await response.json();
+    expect(body.result?.isError).toBe(true);
+  });
+});

apps/e2e/demo-e2e-guard/e2e/guard-cli.e2e.spec.ts

@@ -0,0 +1,40 @@
+/**
+ * E2E Tests for Guard — CLI/Bin Mode
+ *
+ * Guards are intentionally disabled in CLI mode (cliMode flag skips
+ * guard manager initialization). These tests verify that tools work
+ * correctly without guard enforcement — a valuable smoke test for
+ * the CLI execution path.
+ */
+import { ensureBuild, runCli } from './helpers/exec-cli';
+
+describe('Guard CLI E2E', () => {
+  beforeAll(async () => {
+    await ensureBuild();
+  }, 120000);
+
+  it('should execute rate-limited tool via CLI without rate limiting', () => {
+    const { stdout, exitCode } = runCli(['rate-limited', '--message', 'hello-cli']);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('hello-cli');
+  });
+
+  it('should execute timeout tool via CLI without timeout enforcement', () => {
+    // In CLI mode, no timeout guard is applied, so a 100ms delay always succeeds
+    const { stdout, exitCode } = runCli(['timeout-tool', '--delay-ms', '100']);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('done');
+  });
+
+  it('should list all guard tools via CLI help', () => {
+    const { stdout, exitCode } = runCli(['--help']);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('rate-limited');
+    expect(stdout).toContain('concurrency-mutex');
+    expect(stdout).toContain('concurrency-queued');
+    expect(stdout).toContain('timeout-tool');
+    expect(stdout).toContain('combined-guard');
+    expect(stdout).toContain('unguarded');
+    expect(stdout).toContain('slow-tool');
+  });
+});

apps/e2e/demo-e2e-guard/e2e/guard-combined.e2e.spec.ts

@@ -0,0 +1,108 @@
+/**
+ * E2E Tests for Guard — Combined Guards
+ *
+ * Tests that multiple guard types work together on a single tool:
+ * - Rate limit + concurrency + timeout on combined-guard tool
+ * - Each guard enforces independently
+ */
+import { test, expect } from '@frontmcp/testing';
+
+test.describe('Guard Combined — All Pass', () => {
+  test.use({
+    server: 'apps/e2e/demo-e2e-guard/src/main.ts',
+    project: 'demo-e2e-guard',
+    publicMode: true,
+  });
+
+  test('should succeed when all guards pass', async ({ mcp }) => {
+    const result = await mcp.tools.call('combined-guard', { delayMs: 100 });
+    expect(result).toBeSuccessful();
+    expect(result).toHaveTextContent('done');
+  });
+});
+
+test.describe('Guard Combined — Rate Limit', () => {
+  test.use({
+    server: 'apps/e2e/demo-e2e-guard/src/main.ts',
+    project: 'demo-e2e-guard',
+    publicMode: true,
+  });
+
+  test('should enforce rate limit on combined tool', async ({ mcp }) => {
+    // combined-guard allows 5 requests per 5 seconds
+    for (let i = 0; i < 5; i++) {
+      const result = await mcp.tools.call('combined-guard', { delayMs: 0 });
+      expect(result).toBeSuccessful();
+    }
+
+    // 6th request should be rate-limited
+    const result = await mcp.tools.call('combined-guard', { delayMs: 0 });
+    expect(result).toBeError();
+  });
+});
+
+test.describe('Guard Combined — Concurrency', () => {
+  test.use({
+    server: 'apps/e2e/demo-e2e-guard/src/main.ts',
+    project: 'demo-e2e-guard',
+    publicMode: true,
+  });
+
+  test('should enforce concurrency limit on combined tool', async ({ server }) => {
+    // combined-guard: maxConcurrent: 2, queueTimeoutMs: 1000
+    const client1 = await server.createClient();
+    const client2 = await server.createClient();
+    const client3 = await server.createClient();
+
+    try {
+      // Launch 3 parallel calls with 1500ms delay each
+      // Max concurrent is 2, so 3rd must queue
+      // Queue timeout is 1000ms, but first calls take 1500ms → 3rd should timeout
+      const results = await Promise.allSettled([
+        client1.tools.call('combined-guard', { delayMs: 1500 }),
+        client2.tools.call('combined-guard', { delayMs: 1500 }),
+        // Small delay to ensure first two get the slots
+        (async () => {
+          await new Promise<void>((r) => setTimeout(r, 100));
+          return client3.tools.call('combined-guard', { delayMs: 100 });
+        })(),
+      ]);
+
+      // First two should succeed
+      expect(results[0].status).toBe('fulfilled');
+      expect(results[1].status).toBe('fulfilled');
+      if (results[0].status === 'fulfilled') {
+        expect(results[0].value).toBeSuccessful();
+      }
+      if (results[1].status === 'fulfilled') {
+        expect(results[1].value).toBeSuccessful();
+      }
+
+      // Third should have an error (queue timeout)
+      if (results[2].status === 'fulfilled') {
+        expect(results[2].value).toBeError();
+      }
+      // If rejected at transport level, that's also acceptable
+    } finally {
+      await client1.disconnect();
+      await client2.disconnect();
+      await client3.disconnect();
+    }
+  });
+});
+
+test.describe('Guard Combined — Timeout', () => {
+  test.use({
+    server: 'apps/e2e/demo-e2e-guard/src/main.ts',
+    project: 'demo-e2e-guard',
+    publicMode: true,
+  });
+
+  test('should enforce timeout on combined tool', async ({ mcp }) => {
+    // combined-guard has 2000ms timeout, 3000ms delay exceeds it
+    const result = await mcp.tools.call('combined-guard', { delayMs: 3000 });
+    expect(result).toBeError();
+    const text = JSON.stringify(result);
+    expect(text.toLowerCase()).toMatch(/timeout|timed.out/i);
+  });
+});