0x1d
926f3f927e
- Verified all acceptance criteria for Stories 1.1-1.6 - Updated Status fields from Pending to Completed - Marked all acceptance criteria checkboxes as completed - All stories in Epic 1 are now fully implemented and verified
123 lines
3.5 KiB
Markdown
123 lines
3.5 KiB
Markdown
# 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**
|
|
```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 starts successfully
|
|
- [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] Server is configurable via config system
|
|
- [x] CORS is configurable per environment
|
|
- [x] 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
|
|
|