0x1d
38a251968c
Transform all documentation from modular monolith to true microservices
architecture where core services are independently deployable.
Key Changes:
- Core Kernel: Infrastructure only (no business logic)
- Core Services: Auth, Identity, Authz, Audit as separate microservices
- Each service has own entry point (cmd/{service}/)
- Each service has own gRPC server and database schema
- Services register with Consul for service discovery
- API Gateway: Moved from Epic 8 to Epic 1 as core infrastructure
- Single entry point for all external traffic
- Handles routing, JWT validation, rate limiting, CORS
- Service Discovery: Consul as primary mechanism (ADR-0033)
- Database Pattern: Per-service connections with schema isolation
Documentation Updates:
- Updated all 9 architecture documents
- Updated 4 ADRs and created 2 new ADRs (API Gateway, Service Discovery)
- Rewrote Epic 1: Core Kernel & Infrastructure (infrastructure only)
- Rewrote Epic 2: Core Services (Auth, Identity, Authz, Audit as services)
- Updated Epic 3-8 stories for service architecture
- Updated plan.md, playbook.md, requirements.md, index.md
- Updated all epic READMEs and story files
New ADRs:
- ADR-0032: API Gateway Strategy
- ADR-0033: Service Discovery Implementation (Consul)
New Stories:
- Epic 1.7: Service Client Interfaces
- Epic 1.8: API Gateway Implementation
117 lines
4.0 KiB
Markdown
117 lines
4.0 KiB
Markdown
# Story 5.7: Advanced gRPC Features
|
|
|
|
## Metadata
|
|
- **Story ID**: 5.7
|
|
- **Title**: Advanced gRPC Features
|
|
- **Epic**: 5 - Infrastructure Adapters
|
|
- **Status**: Pending
|
|
- **Priority**: Medium
|
|
- **Estimated Time**: 6-8 hours
|
|
- **Dependencies**: 1.7, 2.1, 2.2, 2.3, 2.5
|
|
|
|
## Goal
|
|
Enhance gRPC implementation with advanced features including streaming RPCs, gRPC-Gateway for HTTP access, advanced error handling, and gRPC middleware. Basic gRPC service definitions and clients are already implemented in Epic 1 and Epic 2.
|
|
|
|
## Description
|
|
This story enhances the gRPC implementation that was established in Epic 1 (Service Client Interfaces) and Epic 2 (each service implements its own gRPC server). It adds advanced features like streaming RPCs, gRPC-Gateway integration for HTTP access, advanced error handling, and gRPC middleware for observability.
|
|
|
|
## Deliverables
|
|
|
|
### 1. Streaming RPC Support
|
|
- Add streaming RPC definitions to existing proto files
|
|
- Server-side streaming implementations
|
|
- Client-side streaming implementations
|
|
- Bidirectional streaming support
|
|
- Example: Stream audit logs, stream user events
|
|
|
|
### 2. gRPC-Gateway Integration
|
|
- HTTP to gRPC gateway for REST API access
|
|
- Generate REST endpoints from gRPC services
|
|
- Support for both gRPC and HTTP on same service
|
|
- Gateway configuration
|
|
|
|
### 3. Advanced Error Handling
|
|
- Structured error responses
|
|
- gRPC status codes mapping
|
|
- Error details and metadata
|
|
- Error propagation across services
|
|
|
|
### 4. gRPC Middleware
|
|
- Logging middleware
|
|
- Metrics middleware
|
|
- Tracing middleware (OpenTelemetry)
|
|
- Authentication middleware
|
|
- Rate limiting middleware
|
|
|
|
### 5. gRPC Health Check Service
|
|
- Standard gRPC health check protocol
|
|
- Per-service health status
|
|
- Integration with Consul health checks
|
|
|
|
**Note:** Basic gRPC service definitions (`api/proto/*.proto`), gRPC servers (in each service), and gRPC clients (implementing service client interfaces) are already implemented in Epic 1 and Epic 2.
|
|
|
|
## Implementation Steps
|
|
|
|
1. **Add Streaming RPCs**
|
|
- Update existing proto files with streaming RPCs
|
|
- Implement streaming handlers in services
|
|
- Update clients to support streaming
|
|
|
|
2. **Implement gRPC-Gateway**
|
|
- Install gRPC-Gateway
|
|
- Generate gateway code from proto files
|
|
- Configure gateway endpoints
|
|
|
|
3. **Enhance Error Handling**
|
|
- Implement structured error responses
|
|
- Add error details and metadata
|
|
- Update error propagation
|
|
|
|
4. **Add gRPC Middleware**
|
|
- Create middleware chain
|
|
- Add logging, metrics, tracing middleware
|
|
- Integrate with existing observability
|
|
|
|
5. **Implement Health Check Service**
|
|
- Add gRPC health check service
|
|
- Integrate with Consul health checks
|
|
|
|
## Acceptance Criteria
|
|
- [x] Streaming RPCs work correctly
|
|
- [x] gRPC-Gateway provides HTTP access to gRPC services
|
|
- [x] Advanced error handling works across services
|
|
- [x] gRPC middleware provides observability
|
|
- [x] Health check service integrates with Consul
|
|
- [x] All services support advanced gRPC features
|
|
|
|
## Related ADRs
|
|
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
|
|
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
|
|
- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
|
|
|
|
## Implementation Notes
|
|
- Basic gRPC is already implemented in Epic 1 and Epic 2
|
|
- Focus on advanced features: streaming, gateway, middleware
|
|
- Maintain backward compatibility with existing gRPC services
|
|
- Add OpenTelemetry instrumentation to middleware
|
|
|
|
## Testing
|
|
```bash
|
|
# Test streaming RPCs
|
|
go test ./services/*/internal/api/... -run Streaming
|
|
|
|
# Test gRPC-Gateway
|
|
curl http://localhost:8080/api/v1/users/123
|
|
|
|
# Test health check service
|
|
grpcurl -plaintext localhost:8081 grpc.health.v1.Health/Check
|
|
```
|
|
|
|
## Files to Create/Modify
|
|
- `api/proto/*.proto` - Add streaming RPCs to existing proto files
|
|
- `internal/server/grpc/middleware.go` - gRPC middleware
|
|
- `internal/server/grpc/gateway.go` - gRPC-Gateway integration
|
|
- `internal/server/grpc/health.go` - Health check service
|
|
- `Makefile` - Add gateway generation target
|
|
|