toolz/goplt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ace9678f6cef87765f5b15d1a9bbf4b84ac0e637
goplt/docs/content/stories/epic5/5.7-grpc-services.md

4.6 KiB
Raw Blame History

Story 5.7: gRPC Service Definitions and Clients

Metadata

  • Story ID: 5.7
  • Title: gRPC Service Definitions and Clients
  • Epic: 5 - Infrastructure Adapters
  • Status: Pending
  • Priority: Medium
  • Estimated Time: 8-10 hours
  • Dependencies: 1.7, 3.5

Goal

Implement gRPC service definitions and clients to enable microservices communication, allowing modules to be extracted as independent services.

Description

This story implements gRPC service definitions for core services and gRPC clients that implement the service client interfaces. This enables modules to communicate with services over the network when deployed as microservices.

Deliverables

1. gRPC Service Definitions (api/proto/)

  • Define Protocol Buffer files for core services:
    • identity.proto - Identity service
    • auth.proto - Authentication service
    • authz.proto - Authorization service
    • permission.proto - Permission service
    • audit.proto - Audit service
  • Use protobuf v3
  • Include proper message definitions
  • Include service definitions

2. gRPC Server Implementations (internal/services/grpc/server/)

  • Implement gRPC servers for each service:
    • identity_server.go - Identity gRPC server
    • auth_server.go - Auth gRPC server
    • authz_server.go - Authz gRPC server
  • Server implementations wrap existing services
  • Error handling and validation
  • Request/response conversion

3. gRPC Client Implementations (internal/services/grpc/client/)

  • Implement gRPC clients that satisfy service client interfaces:
    • grpc_identity_client.go - Identity gRPC client
    • grpc_auth_client.go - Auth gRPC client
    • grpc_authz_client.go - Authz gRPC client
  • Connection pooling
  • Retry logic
  • Circuit breaker support
  • Timeout handling

4. gRPC Server Setup

  • gRPC server initialization
  • Service registration
  • Health check service
  • Reflection service (development)
  • Integration with HTTP server (gRPC-Gateway optional)

5. Code Generation

  • Makefile target for protobuf generation
  • Generate Go code from .proto files
  • Generate gRPC server and client stubs

6. Configuration

  • gRPC configuration in config/default.yaml: 
    grpc:
  enabled: false  # Enable gRPC server
  port: 9090
  reflection: true  # Enable reflection (dev)

7. Integration

  • Integrate with service factory
  • Support switching between local and gRPC clients
  • Service registry integration for gRPC services

Implementation Steps

  1. Install Dependencies

    go get google.golang.org/grpc
go get google.golang.org/protobuf
go install google.golang.org/protobuf/cmd/protoc-gen-go
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc

  2. Define Protocol Buffers

    • Create api/proto/ directory
    • Define .proto files for each service
    • Define messages and services

  3. Generate gRPC Code

    • Create Makefile target
    • Generate Go code from protobuf

  4. Implement gRPC Servers

    • Create server implementations
    • Wrap existing services
    • Handle errors and validation

  5. Implement gRPC Clients

    • Create client implementations
    • Implement service client interfaces
    • Add connection management

  6. Integrate with Service Factory

    • Update factory to support gRPC clients
    • Add gRPC server startup

Acceptance Criteria

  • gRPC service definitions are created
  • gRPC servers are implemented
  • gRPC clients implement service interfaces
  • Service factory can create gRPC clients
  • gRPC services can be enabled via configuration
  • Code generation works
  • gRPC clients work with service registry

Related ADRs

Implementation Notes

  • Use protobuf v3
  • Support both unary and streaming RPCs
  • Implement proper error handling
  • Add OpenTelemetry instrumentation
  • Support service versioning

Testing

# Generate protobuf code
make generate-proto

# Test gRPC servers
go test ./internal/services/grpc/server/...

# Test gRPC clients
go test ./internal/services/grpc/client/...

Files to Create/Modify

  • api/proto/identity.proto - Identity service definition
  • api/proto/auth.proto - Auth service definition
  • api/proto/authz.proto - Authz service definition
  • internal/services/grpc/server/ - gRPC server implementations
  • internal/services/grpc/client/ - gRPC client implementations
  • internal/services/factory.go - Add gRPC client support
  • Makefile - Add protobuf generation
  • config/default.yaml - Add gRPC configuration