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

Install Dependencies
```
go get github.com/gin-gonic/gin
```
Create HTTP Server
- Create internal/server/server.go
- Initialize Gin router
- Configure server settings
Implement Middleware
- Request ID middleware
- Logging middleware
- Panic recovery middleware
- Metrics middleware
- CORS middleware
- Timeout middleware
- Compression middleware
Register Core Routes
- Health endpoints
- Metrics endpoint
Integrate with FX
- Add lifecycle hooks
- Handle graceful shutdown
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

ADR-0006: HTTP Framework

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

# 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

3.5 KiB Raw Blame History