goplt/docs/content/stories/epic1/1.5-http-server.md

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 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

   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

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