# 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