# 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**: Completed
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: 1.1, 1.3, 1.4

## Goal
Create HTTP and gRPC server foundation that services can use. Each service will have its own server instance.

## Description
This story implements HTTP and gRPC server foundations that services will use to create their own server instances. It includes common middleware, server lifecycle management, and integration with the DI container. Services (Auth, Identity, etc.) will use these foundations in Epic 2.

## Deliverables

### 1. HTTP Server Foundation (`internal/server/http.go`)
- HTTP server helper functions
- Gin router initialization helper
- Server configuration (port, host, timeouts)
- Graceful shutdown handling
- Reusable by services

### 2. gRPC Server Foundation (`internal/server/grpc.go`)
- gRPC server initialization helper
- Interceptor support (logging, tracing, metrics)
- Server lifecycle management
- Reusable by services

### 3. Common 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 (for HTTP)
- **Request Timeout**: Handle request timeouts
- **Response Compression**: Gzip compression for responses (HTTP)

### 4. FX Lifecycle Integration
- Server lifecycle management helpers
- Graceful shutdown support
- Port configuration from config system
- Reusable by services

**Note:** Services will use these foundations to create their own server instances in Epic 2.

## 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
- [x] HTTP server foundation is reusable by services
- [x] gRPC server foundation is reusable by services
- [x] All middleware executes in correct order
- [x] Request IDs are generated and logged
- [x] Metrics are collected for all requests
- [x] Panics are recovered and handled
- [x] Graceful shutdown works correctly
- [x] Servers are configurable via config system
- [x] Services can create their own server instances using these foundations

## 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/http.go` - HTTP server foundation
- `internal/server/grpc.go` - gRPC server foundation
- `internal/server/middleware.go` - Common middleware functions
- `config/default.yaml` - Add server configuration

**Note:** Services will create their own server instances using these foundations in Epic 2.