@daghis/teamcity-mcp 0.1.2

package/src/middleware/error.test.ts

@@ -0,0 +1,274 @@
+/**
+ * Error handling middleware tests
+ */
+import { z } from 'zod';
+
+import {
+  MCPAuthError,
+  MCPNotFoundError,
+  MCPToolError,
+  MCPValidationError,
+  asyncHandler,
+  formatError,
+  retry,
+  safeJsonParse,
+} from './error';
+
+describe('Error Classes', () => {
+  describe('MCPToolError', () => {
+    it('should create error with default values', () => {
+      const error = new MCPToolError('Test error');
+      expect(error.message).toBe('Test error');
+      expect(error.code).toBe('TOOL_ERROR');
+      expect(error.statusCode).toBe(500);
+      expect(error.name).toBe('MCPToolError');
+      expect(error.data).toBeUndefined();
+    });
+
+    it('should create error with custom values', () => {
+      const testData = { detail: 'Custom data' };
+      const error = new MCPToolError('Custom error', 'CUSTOM_CODE', 400, testData);
+      expect(error.message).toBe('Custom error');
+      expect(error.code).toBe('CUSTOM_CODE');
+      expect(error.statusCode).toBe(400);
+      expect(error.data).toEqual(testData);
+    });
+
+    it('should capture stack trace', () => {
+      const error = new MCPToolError('Test error');
+      expect(error.stack).toBeDefined();
+    });
+  });
+
+  describe('MCPValidationError', () => {
+    it('should create validation error', () => {
+      const zodError = new z.ZodError([
+        {
+          code: 'invalid_type',
+          expected: 'string',
+          received: 'number',
+          path: ['field'],
+          message: 'Expected string',
+        },
+      ]);
+
+      const error = new MCPValidationError('Validation failed', zodError);
+      expect(error.message).toBe('Validation failed');
+      expect(error.code).toBe('VALIDATION_ERROR');
+      expect(error.statusCode).toBe(400);
+      expect(error.name).toBe('MCPValidationError');
+      expect(error.data).toEqual(zodError.errors);
+    });
+  });
+
+  describe('MCPAuthError', () => {
+    it('should create auth error', () => {
+      const error = new MCPAuthError('Authentication failed');
+      expect(error.message).toBe('Authentication failed');
+      expect(error.code).toBe('AUTH_ERROR');
+      expect(error.statusCode).toBe(401);
+      expect(error.name).toBe('MCPAuthError');
+    });
+  });
+
+  describe('MCPNotFoundError', () => {
+    it('should create not found error', () => {
+      const error = new MCPNotFoundError('User');
+      expect(error.message).toBe('User not found');
+      expect(error.code).toBe('NOT_FOUND');
+      expect(error.statusCode).toBe(404);
+      expect(error.name).toBe('MCPNotFoundError');
+    });
+  });
+});
+
+describe('formatError', () => {
+  it('should format MCPToolError correctly', () => {
+    const error = new MCPToolError('Tool error', 'CUSTOM_CODE', 400, { key: 'value' });
+    const result = formatError(error);
+
+    expect(result).toEqual({
+      success: false,
+      error: {
+        message: 'Tool error',
+        code: 'CUSTOM_CODE',
+        data: { key: 'value' },
+      },
+    });
+  });
+
+  it('should format ZodError correctly', () => {
+    const zodError = new z.ZodError([
+      {
+        code: 'invalid_type',
+        expected: 'string',
+        received: 'number',
+        path: ['field'],
+        message: 'Expected string',
+      },
+    ]);
+
+    const result = formatError(zodError);
+
+    expect(result).toEqual({
+      success: false,
+      error: {
+        message: 'Validation failed',
+        code: 'VALIDATION_ERROR',
+        data: zodError.errors,
+      },
+    });
+  });
+
+  it('should format generic Error correctly', () => {
+    const error = new Error('Generic error');
+    const result = formatError(error);
+
+    expect(result).toEqual({
+      success: false,
+      error: {
+        message: 'Generic error',
+        code: 'INTERNAL_ERROR',
+      },
+    });
+  });
+
+  it('should format unknown error correctly', () => {
+    const result = formatError('string error');
+
+    expect(result).toEqual({
+      success: false,
+      error: {
+        message: 'An unknown error occurred',
+        code: 'UNKNOWN_ERROR',
+      },
+    });
+  });
+
+  it('should format null/undefined error correctly', () => {
+    expect(formatError(null)).toEqual({
+      success: false,
+      error: {
+        message: 'An unknown error occurred',
+        code: 'UNKNOWN_ERROR',
+      },
+    });
+
+    expect(formatError(undefined)).toEqual({
+      success: false,
+      error: {
+        message: 'An unknown error occurred',
+        code: 'UNKNOWN_ERROR',
+      },
+    });
+  });
+});
+
+describe('asyncHandler', () => {
+  it('should handle successful async function', async () => {
+    const handler = asyncHandler(async (...args: unknown[]) => {
+      const value = args[0] as number;
+      return value * 2;
+    });
+    const result = await handler(5);
+    expect(result).toBe(10);
+  });
+
+  it('should catch and re-throw errors', async () => {
+    const testError = new Error('Test error');
+    const handler = asyncHandler(async () => {
+      throw testError;
+    });
+
+    await expect(handler()).rejects.toThrow('Test error');
+  });
+
+  it('should handle non-Error throws', async () => {
+    const handler = asyncHandler(async () => {
+      throw new Error('String error');
+    });
+
+    await expect(handler()).rejects.toThrow('String error');
+  });
+});
+
+describe('safeJsonParse', () => {
+  it('should parse valid JSON', () => {
+    const result = safeJsonParse('{"key": "value"}');
+    expect(result).toEqual({ key: 'value' });
+  });
+
+  it('should return null for invalid JSON', () => {
+    const result = safeJsonParse('invalid json');
+    expect(result).toBeNull();
+  });
+
+  it('should return typed result', () => {
+    interface TestType {
+      name: string;
+      age: number;
+    }
+
+    const result = safeJsonParse<TestType>('{"name": "John", "age": 30}');
+    expect(result).toEqual({ name: 'John', age: 30 });
+  });
+});
+
+describe('retry', () => {
+  it('should succeed on first try', async () => {
+    const fn = jest.fn().mockResolvedValue('success');
+    const result = await retry(fn);
+
+    expect(result).toBe('success');
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should retry on failure and eventually succeed', async () => {
+    const fn = jest
+      .fn()
+      .mockRejectedValueOnce(new Error('First fail'))
+      .mockRejectedValueOnce(new Error('Second fail'))
+      .mockResolvedValue('success');
+
+    const result = await retry(fn, { retries: 3, delay: 10 });
+
+    expect(result).toBe('success');
+    expect(fn).toHaveBeenCalledTimes(3);
+  });
+
+  it('should throw last error after all retries', async () => {
+    const finalError = new Error('Final error');
+    const fn = jest.fn().mockRejectedValue(finalError);
+
+    await expect(retry(fn, { retries: 2, delay: 10 })).rejects.toThrow('Final error');
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('should use exponential backoff', async () => {
+    const fn = jest.fn().mockRejectedValue(new Error('Always fail'));
+    const startTime = Date.now();
+
+    try {
+      await retry(fn, { retries: 3, delay: 10, exponentialBackoff: true });
+    } catch (error) {
+      // Expected to fail
+    }
+
+    const elapsed = Date.now() - startTime;
+    // Should wait at least 10 + 20 = 30ms (exponential backoff)
+    expect(elapsed).toBeGreaterThanOrEqual(30);
+    expect(fn).toHaveBeenCalledTimes(3);
+  });
+
+  it('should use constant delay when exponentialBackoff is false', async () => {
+    const fn = jest.fn().mockRejectedValue(new Error('Always fail'));
+
+    try {
+      await retry(fn, { retries: 3, delay: 10, exponentialBackoff: false });
+    } catch (error) {
+      // Expected to fail
+    }
+
+    expect(fn).toHaveBeenCalledTimes(3);
+  });
+});

package/src/middleware/error.ts

@@ -0,0 +1,314 @@
+/**
+ * Error handling middleware for MCP server
+ */
+import { z } from 'zod';
+
+import { error as logError } from '@/utils/logger';
+
+/**
+ * Custom error class for MCP tool errors
+ */
+export class MCPToolError extends Error {
+  constructor(
+    message: string,
+    public code: string = 'TOOL_ERROR',
+    public statusCode: number = 500,
+    public data?: unknown
+  ) {
+    super(message);
+    this.name = 'MCPToolError';
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Custom error class for validation errors
+ */
+export class MCPValidationError extends MCPToolError {
+  constructor(
+    message: string,
+    public errors?: z.ZodError
+  ) {
+    super(message, 'VALIDATION_ERROR', 400, errors?.errors);
+    this.name = 'MCPValidationError';
+  }
+}
+
+/**
+ * Custom error class for authentication errors
+ */
+export class MCPAuthError extends MCPToolError {
+  constructor(message: string) {
+    super(message, 'AUTH_ERROR', 401);
+    this.name = 'MCPAuthError';
+  }
+}
+
+/**
+ * Custom error class for not found errors
+ */
+export class MCPNotFoundError extends MCPToolError {
+  constructor(resource: string) {
+    super(`${resource} not found`, 'NOT_FOUND', 404);
+    this.name = 'MCPNotFoundError';
+  }
+}
+
+/**
+ * Custom error class for TeamCity API errors
+ */
+export class MCPTeamCityError extends MCPToolError {
+  public readonly teamCityCode?: string;
+  public readonly requestId?: string;
+
+  constructor(
+    message: string,
+    statusCode: number = 500,
+    teamCityCode?: string,
+    requestId?: string
+  ) {
+    super(message, 'TEAMCITY_ERROR', statusCode, { teamCityCode, requestId });
+    this.name = 'MCPTeamCityError';
+    this.teamCityCode = teamCityCode;
+    this.requestId = requestId;
+  }
+}
+
+/**
+ * Custom error class for configuration errors
+ */
+export class MCPConfigError extends MCPToolError {
+  constructor(
+    message: string,
+    public readonly configPath?: string
+  ) {
+    super(message, 'CONFIG_ERROR', 500, { configPath });
+    this.name = 'MCPConfigError';
+  }
+}
+
+/**
+ * Custom error class for timeout errors
+ */
+export class MCPTimeoutError extends MCPToolError {
+  constructor(operation: string, timeout: number) {
+    super(`Operation '${operation}' timed out after ${timeout}ms`, 'TIMEOUT_ERROR', 408, {
+      operation,
+      timeout,
+    });
+    this.name = 'MCPTimeoutError';
+  }
+}
+
+/**
+ * Custom error class for rate limiting errors
+ */
+export class MCPRateLimitError extends MCPToolError {
+  constructor(public readonly retryAfter?: number) {
+    super('Rate limit exceeded', 'RATE_LIMIT_ERROR', 429, { retryAfter });
+    this.name = 'MCPRateLimitError';
+  }
+}
+
+/**
+ * Error response formatter
+ */
+export interface ErrorResponse {
+  error: {
+    message: string;
+    code: string;
+    data?: unknown;
+  };
+  success: false;
+}
+
+/**
+ * Format error for MCP response with enhanced logging
+ */
+export function formatError(
+  err: unknown,
+  context?: { requestId?: string; operation?: string }
+): ErrorResponse {
+  // Log error details for debugging
+  if (err instanceof MCPToolError) {
+    logError('MCP Tool Error', err, {
+      code: err.code,
+      statusCode: err.statusCode,
+      data: err.data,
+      ...context,
+    });
+
+    return {
+      success: false,
+      error: {
+        message: err.message,
+        code: err.code,
+        data: err.data,
+      },
+    };
+  }
+
+  if (err instanceof z.ZodError) {
+    logError('Validation Error', err, {
+      errors: err.errors,
+      ...context,
+    });
+
+    return {
+      success: false,
+      error: {
+        message: 'Validation failed',
+        code: 'VALIDATION_ERROR',
+        data: err.errors,
+      },
+    };
+  }
+
+  if (err instanceof Error) {
+    logError('Internal Error', err, context);
+
+    return {
+      success: false,
+      error: {
+        message: process.env['NODE_ENV'] === 'production' ? 'Internal server error' : err.message,
+        code: 'INTERNAL_ERROR',
+      },
+    };
+  }
+
+  logError('Unknown Error', new Error(String(err)), context);
+
+  return {
+    success: false,
+    error: {
+      message: 'An unknown error occurred',
+      code: 'UNKNOWN_ERROR',
+    },
+  };
+}
+
+/**
+ * Global error handler for uncaught errors
+ */
+export function setupGlobalErrorHandlers(): void {
+  process.on('uncaughtException', (err: Error) => {
+    logError('Uncaught Exception', err);
+    // Give time for logs to flush
+    setTimeout(() => process.exit(1), 100);
+  });
+
+  process.on('unhandledRejection', (reason: unknown, promise: Promise<unknown>) => {
+    logError('Unhandled Rejection', undefined, { reason, promise });
+    // Don't exit on unhandled rejection in development
+    if (process.env['NODE_ENV'] === 'production') {
+      setTimeout(() => process.exit(1), 100);
+    }
+  });
+}
+
+/**
+ * Wrap async handler to catch errors with enhanced context
+ */
+export function asyncHandler<T>(
+  handler: (...args: unknown[]) => Promise<T>,
+  operationName?: string
+): (...args: unknown[]) => Promise<T> {
+  return async (...args: unknown[]): Promise<T> => {
+    const context = {
+      operation: operationName ?? handler.name ?? 'anonymous',
+      args: process.env['NODE_ENV'] !== 'production' ? args : undefined,
+    };
+
+    try {
+      return await handler(...args);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      logError('Async handler error', error, context);
+      throw err;
+    }
+  };
+}
+
+/**
+ * Safe JSON parse with error handling and validation
+ */
+export function safeJsonParse<T = unknown>(
+  json: string,
+  validator?: (data: unknown) => data is T
+): T | null {
+  try {
+    const parsed = JSON.parse(json) as unknown;
+
+    if (validator && !validator(parsed)) {
+      logError('JSON validation failed', new Error('Parsed JSON does not match expected schema'), {
+        json: json.substring(0, 200) + (json.length > 200 ? '...' : ''),
+      });
+      return null;
+    }
+
+    return parsed as T;
+  } catch (err) {
+    logError('JSON parse error', err instanceof Error ? err : new Error(String(err)), {
+      json: json.substring(0, 200) + (json.length > 200 ? '...' : ''),
+    });
+    return null;
+  }
+}
+
+/**
+ * Enhanced retry helper for flaky operations with better error handling
+ */
+export async function retry<T>(
+  fn: () => Promise<T>,
+  options: {
+    retries?: number;
+    delay?: number;
+    exponentialBackoff?: boolean;
+    shouldRetry?: (error: unknown) => boolean;
+    operationName?: string;
+  } = {}
+): Promise<T> {
+  const {
+    retries = 3,
+    delay = 1000,
+    exponentialBackoff = true,
+    shouldRetry = () => true,
+    operationName = 'unknown',
+  } = options;
+
+  let lastError: unknown;
+
+  // Intentional sequential retries; each iteration awaits the previous attempt
+  /* eslint-disable no-await-in-loop */
+  for (let i = 0; i < retries; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+
+      const isLastAttempt = i === retries - 1;
+      const shouldRetryThis = shouldRetry(err);
+
+      if (isLastAttempt || !shouldRetryThis) {
+        logError(
+          `Retry operation '${operationName}' failed`,
+          err instanceof Error ? err : new Error(String(err)),
+          { attempt: i + 1, totalAttempts: retries, willRetry: false }
+        );
+        break;
+      }
+
+      logError(
+        `Retry operation '${operationName}' failed, retrying`,
+        err instanceof Error ? err : new Error(String(err)),
+        { attempt: i + 1, totalAttempts: retries, willRetry: true }
+      );
+
+      const waitTime = exponentialBackoff ? delay * Math.pow(2, i) : delay;
+      await new Promise((resolve) => setTimeout(resolve, waitTime));
+    }
+  }
+
+  throw lastError;
+}
+/* eslint-enable no-await-in-loop */