toolz/goplt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
da7a4e3703b6523ba7487544263f68ce960c2969
goplt/docs/content/stories/epic5/5.7-grpc-services.md
0x1d 38a251968c docs: Align documentation with true microservices architecture 
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
2025-11-06 08:54:19 +01:00

4.0 KiB
Raw Blame History

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

  • Streaming RPCs work correctly
  • gRPC-Gateway provides HTTP access to gRPC services
  • Advanced error handling works across services
  • gRPC middleware provides observability
  • Health check service integrates with Consul
  • All services support advanced gRPC features

Related ADRs

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

# 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