# Story 1.5: HTTP Server Foundation with Middleware Stack

## Metadata
- **Story ID**: 1.5
- **Title**: HTTP Server Foundation with Middleware Stack
- **Epic**: 1 - Core Kernel & Infrastructure
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: 1.1, 1.3, 1.4

## Goal
Create a production-ready HTTP server with comprehensive middleware for security, observability, and error handling.

## Description
This story implements a complete HTTP server using Gin with a comprehensive middleware stack including request ID generation, structured logging, panic recovery, metrics collection, CORS, and graceful shutdown.

## Deliverables

### 1. HTTP Server (`internal/server/server.go`)
- Gin router initialization
- Server configuration (port, host, timeouts)
- Graceful shutdown handling

### 2. Comprehensive Middleware Stack
- **Request ID Generator**: Unique ID per request
- **Structured Logging**: Log all requests with context
- **Panic Recovery**: Recover panics → error bus
- **Prometheus Metrics**: Collect request metrics
- **CORS Support**: Configurable CORS headers
- **Request Timeout**: Handle request timeouts
- **Response Compression**: Gzip compression for responses

### 3. Core Route Registration
- `GET /healthz` - Liveness probe
- `GET /ready` - Readiness probe
- `GET /metrics` - Prometheus metrics

### 4. FX Lifecycle Integration
- HTTP server starts on `OnStart` hook
- Graceful shutdown on `OnStop` hook (drains connections)
- Port configuration from config system

### 5. Integration
- Integration with main application entry point
- Integration with all middleware systems

## Implementation Steps

1. **Install Dependencies**
   ```bash
   go get github.com/gin-gonic/gin
   ```

2. **Create HTTP Server**
   - Create `internal/server/server.go`
   - Initialize Gin router
   - Configure server settings

3. **Implement Middleware**
   - Request ID middleware
   - Logging middleware
   - Panic recovery middleware
   - Metrics middleware
   - CORS middleware
   - Timeout middleware
   - Compression middleware

4. **Register Core Routes**
   - Health endpoints
   - Metrics endpoint

5. **Integrate with FX**
   - Add lifecycle hooks
   - Handle graceful shutdown

6. **Test Server**
   - Verify server starts
   - Test all endpoints
   - Test graceful shutdown

## Acceptance Criteria
- [ ] HTTP server starts successfully
- [ ] All middleware executes in correct order
- [ ] Request IDs are generated and logged
- [ ] Metrics are collected for all requests
- [ ] Panics are recovered and handled
- [ ] Graceful shutdown works correctly
- [ ] Server is configurable via config system
- [ ] CORS is configurable per environment
- [ ] All core endpoints work correctly

## Related ADRs
- [ADR-0006: HTTP Framework](../../adr/0006-http-framework.md)

## Implementation Notes
- Use Gin for HTTP routing
- Middleware order is important
- Support graceful shutdown with connection draining
- CORS should be configurable per environment
- Consider adding rate limiting in future (Epic 6)

## Testing
```bash
# Test server startup
go run cmd/platform/main.go

# Test endpoints
curl http://localhost:8080/healthz
curl http://localhost:8080/ready
curl http://localhost:8080/metrics

# Test graceful shutdown
# Send SIGTERM and verify graceful shutdown
```

## Files to Create/Modify
- `internal/server/server.go` - HTTP server
- `internal/server/middleware.go` - Middleware functions
- `internal/di/providers.go` - Add server provider
- `config/default.yaml` - Add server configuration