feat: implement Express server with configuration, middleware, and routing

- Set up the main entry point for the application with Express
- Add application configuration management
- Implement error handling middleware with custom error classes
- Introduce security features using Helmet and CORS
- Create basic routing with health check and API versioning endpoints
- Add structured logging using Winston
- Include integration tests for server setup and error handling

Author: angoca

src/config/app.ts

@@ -0,0 +1,22 @@
+/**
+ * Application configuration
+ */
+
+export interface AppConfig {
+  port: number;
+  env: string;
+  apiVersion: string;
+  corsOrigin: string | string[];
+}
+
+/**
+ * Get application configuration from environment variables
+ */
+export function getAppConfig(): AppConfig {
+  return {
+    port: parseInt(process.env.PORT || '3000', 10),
+    env: process.env.NODE_ENV || 'development',
+    apiVersion: process.env.API_VERSION || 'v1',
+    corsOrigin: process.env.CORS_ORIGIN || '*',
+  };
+}

src/index.ts

@@ -3,5 +3,128 @@
  * Main entry point for the application
  */
 
-// This file will be implemented in later tasks
-// Placeholder to ensure TypeScript compilation works
+import express, { Express, Request, Response, NextFunction } from 'express';
+import cors from 'cors';
+import helmet from 'helmet';
+import { getAppConfig } from './config/app';
+import { errorHandler, notFoundHandler, ApiError } from './middleware/errorHandler';
+import { logger } from './utils/logger';
+import routes from './routes';
+
+/**
+ * Create and configure Express application
+ */
+function createApp(): Express {
+  const app = express();
+  const config = getAppConfig();
+
+  // Trust proxy (for rate limiting behind reverse proxy)
+  app.set('trust proxy', 1);
+
+  // Security middleware
+  app.use(
+    helmet({
+      contentSecurityPolicy: {
+        directives: {
+          defaultSrc: ["'self'"],
+          styleSrc: ["'self'", "'unsafe-inline'"],
+          scriptSrc: ["'self'"],
+          imgSrc: ["'self'", 'data:', 'https:'],
+        },
+      },
+    })
+  );
+
+  // CORS configuration
+  app.use(
+    cors({
+      origin: config.corsOrigin,
+      methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+      allowedHeaders: ['Content-Type', 'Authorization', 'User-Agent'],
+      exposedHeaders: ['X-RateLimit-Limit', 'X-RateLimit-Remaining', 'X-RateLimit-Reset'],
+    })
+  );
+
+  // Body parsing middleware
+  app.use(express.json({ limit: '10mb' }));
+  app.use(express.urlencoded({ extended: true, limit: '10mb' }));
+
+  // Handle JSON parsing errors
+  app.use(
+    (
+      err: Error & { status?: number; type?: string },
+      req: Request,
+      res: Response,
+      next: NextFunction
+    ) => {
+      if (err instanceof SyntaxError && err.type === 'entity.parse.failed') {
+        const apiError = new ApiError(400, 'Invalid JSON in request body');
+        return errorHandler(apiError, req, res, next);
+      }
+      next(err);
+    }
+  );
+
+  // Request logging middleware
+  app.use((req: Request, _res: Response, next: NextFunction) => {
+    logger.info('Incoming request', {
+      method: req.method,
+      path: req.path,
+      ip: req.ip,
+      userAgent: req.get('User-Agent'),
+    });
+    next();
+  });
+
+  // Routes
+  app.use('/', routes);
+
+  // 404 handler (must be after all routes)
+  app.use(notFoundHandler);
+
+  // Error handler (must be last)
+  app.use(errorHandler);
+
+  return app;
+}
+
+/**
+ * Start the server
+ */
+function startServer(): void {
+  const app = createApp();
+  const config = getAppConfig();
+
+  const server = app.listen(config.port, () => {
+    logger.info('Server started', {
+      port: config.port,
+      env: config.env,
+      apiVersion: config.apiVersion,
+    });
+  });
+
+  // Graceful shutdown
+  process.on('SIGTERM', () => {
+    logger.info('SIGTERM received, shutting down gracefully');
+    server.close(() => {
+      logger.info('Server closed');
+      process.exit(0);
+    });
+  });
+
+  process.on('SIGINT', () => {
+    logger.info('SIGINT received, shutting down gracefully');
+    server.close(() => {
+      logger.info('Server closed');
+      process.exit(0);
+    });
+  });
+}
+
+// Start server if this file is run directly
+if (require.main === module) {
+  startServer();
+}
+
+// Export app factory for testing
+export default createApp;

src/middleware/errorHandler.ts

@@ -0,0 +1,88 @@
+/**
+ * Error handling middleware
+ */
+
+import { Request, Response, NextFunction } from 'express';
+import { logger } from '../utils/logger';
+
+/**
+ * Custom error class for API errors
+ */
+export class ApiError extends Error {
+  statusCode: number;
+  isOperational: boolean;
+
+  constructor(statusCode: number, message: string, isOperational = true) {
+    super(message);
+    this.statusCode = statusCode;
+    this.isOperational = isOperational;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Error handler middleware
+ * Handles all errors and sends appropriate responses
+ */
+export function errorHandler(
+  err: Error | ApiError,
+  req: Request,
+  res: Response,
+  _next: NextFunction
+): void {
+  // Log error
+  logger.error('Error occurred', {
+    error: err.message,
+    stack: err.stack,
+    path: req.path,
+    method: req.method,
+    ip: req.ip,
+  });
+
+  // Handle known API errors
+  if (err instanceof ApiError && err.isOperational) {
+    res.status(err.statusCode).json({
+      error: getErrorName(err.statusCode),
+      message: err.message,
+      statusCode: err.statusCode,
+    });
+    return;
+  }
+
+  // Handle unknown errors
+  const statusCode = (err as ApiError).statusCode || 500;
+  const message = process.env.NODE_ENV === 'production' ? 'Internal server error' : err.message;
+
+  res.status(statusCode).json({
+    error: getErrorName(statusCode),
+    message,
+    statusCode,
+    ...(process.env.NODE_ENV !== 'production' && { stack: err.stack }),
+  });
+}
+
+/**
+ * 404 Not Found handler
+ */
+export function notFoundHandler(req: Request, _res: Response, next: NextFunction): void {
+  const error = new ApiError(404, `Route ${req.method} ${req.path} not found`);
+  next(error);
+}
+
+/**
+ * Get error name from status code
+ */
+function getErrorName(statusCode: number): string {
+  const errorNames: Record<number, string> = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+  };
+
+  return errorNames[statusCode] || 'Error';
+}

src/routes/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Main routes index
+ */
+
+import { Router } from 'express';
+import { getAppConfig } from '../config/app';
+
+const router = Router();
+const { apiVersion } = getAppConfig();
+
+/**
+ * API version info endpoint
+ */
+router.get(`/api/${apiVersion}`, (_req, res) => {
+  res.json({
+    name: 'OSM Notes API',
+    version: process.env.npm_package_version || '0.1.0',
+    apiVersion,
+    status: 'operational',
+  });
+});
+
+/**
+ * Health check route (will be moved to separate file later)
+ */
+router.get('/health', (_req, res) => {
+  res.json({
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+  });
+});
+
+export default router;

src/utils/logger.ts

@@ -0,0 +1,25 @@
+/**
+ * Structured logging utility using Winston
+ * Placeholder implementation - will be fully implemented in Task 2.2
+ */
+
+import winston from 'winston';
+
+/**
+ * Logger instance
+ * Full configuration will be added in Task 2.2
+ */
+export const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.errors({ stack: true }),
+    winston.format.json()
+  ),
+  defaultMeta: { service: 'osm-notes-api' },
+  transports: [
+    new winston.transports.Console({
+      format: winston.format.combine(winston.format.colorize(), winston.format.simple()),
+    }),
+  ],
+});

tests/integration/server.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Integration tests for Express server setup
+ */
+
+import request from 'supertest';
+import { Express } from 'express';
+
+describe('Express Server Setup', () => {
+  let app: Express;
+
+  beforeAll(async () => {
+    // Import app after all modules are loaded
+    const { default: createApp } = await import('../../src/index');
+    app = createApp();
+  });
+
+  describe('Basic Server Configuration', () => {
+    it('should start server and respond to requests', async () => {
+      const response = await request(app).get('/health');
+      expect(response.status).toBeDefined();
+    });
+
+    it('should have CORS enabled', async () => {
+      const response = await request(app).options('/health').set('Origin', 'http://example.com');
+
+      expect(response.headers['access-control-allow-origin']).toBeDefined();
+    });
+
+    it('should have security headers (Helmet)', async () => {
+      const response = await request(app).get('/health');
+
+      expect(response.headers['x-content-type-options']).toBe('nosniff');
+      expect(response.headers['x-frame-options']).toBeDefined();
+    });
+
+    it('should parse JSON body', async () => {
+      // Test JSON parsing by checking that invalid JSON returns 400
+      const response = await request(app)
+        .post('/api/v1')
+        .send('invalid json')
+        .set('Content-Type', 'application/json');
+
+      // Should handle invalid JSON gracefully (either 400 or 404)
+      expect([400, 404]).toContain(response.status);
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should handle 404 errors', async () => {
+      const response = await request(app).get('/nonexistent');
+
+      expect(response.status).toBe(404);
+      expect(response.body).toHaveProperty('error');
+    });
+
+    it('should handle errors with proper format', async () => {
+      const response = await request(app).get('/nonexistent');
+
+      expect(response.body).toHaveProperty('error');
+      expect(response.body).toHaveProperty('message');
+    });
+  });
+
+  describe('API Versioning', () => {
+    it('should have /api/v1 prefix', async () => {
+      // This will be implemented when routes are added
+      const response = await request(app).get('/api/v1');
+
+      // Should not be 404 if versioning is set up correctly
+      expect(response.status).toBeDefined();
+    });
+  });
+});