goplt/docs/content/stories/epic1/1.7-service-client-interfaces.md

Story 1.7: Service Client Interfaces

Metadata

• Story ID: 1.7
• Title: Service Client Interfaces
• Epic: 1 - Core Kernel & Infrastructure
• Status: In Progress
• Priority: High
• Estimated Time: 4-6 hours
• Dependencies: 1.1

Goal

Create service client interfaces for all core services to enable microservices communication. All inter-service communication will go through these interfaces.

Description

This story defines service client interfaces for all core services (Auth, Identity, Authz, Audit) and creates a service client factory that can create gRPC (primary) or HTTP (fallback) clients. Service clients use Consul for service discovery.

Deliverables

1. Service Client Interfaces (pkg/services/)

Define interfaces for all core services:

• AuthServiceClient in pkg/services/auth.go:

  • Login(ctx, email, password) (*TokenResponse, error)
  • RefreshToken(ctx, refreshToken) (*TokenResponse, error)
  • ValidateToken(ctx, token) (*TokenClaims, error)

• IdentityServiceClient in pkg/services/identity.go:

  • GetUser(ctx, id) (*User, error)
  • GetUserByEmail(ctx, email) (*User, error)
  • CreateUser(ctx, user) (*User, error)
  • UpdateUser(ctx, id, user) (*User, error)
  • DeleteUser(ctx, id) error
  • VerifyEmail(ctx, token) error
  • RequestPasswordReset(ctx, email) error
  • ResetPassword(ctx, token, newPassword) error

• AuthzServiceClient in pkg/services/authz.go:

  • Authorize(ctx, userID, permission) error
  • HasPermission(ctx, userID, permission) (bool, error)
  • GetUserPermissions(ctx, userID) ([]Permission, error)

• AuditServiceClient in pkg/services/audit.go:

  • Record(ctx, action) error
  • Query(ctx, filters) ([]AuditLog, error)

2. Service Client Factory (internal/services/factory.go)

• NewServiceClient(serviceName string, registry ServiceRegistry) (ServiceClient, error)
• Support for gRPC clients (primary)
• Support for HTTP clients (fallback)
• Service discovery integration via Consul
• Connection pooling and lifecycle management

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

• gRPC client implementations for each service
• Service discovery integration
• Connection management
• Retry and circuit breaker support

4. HTTP Client Implementation (internal/services/http/client/)

• HTTP client implementations for each service (fallback)
• Service discovery integration
• Request/response handling
• Retry support

5. Configuration

• Service client configuration in config/default.yaml:
  • Protocol selection (gRPC/HTTP)
  • Service discovery settings
  • Connection pool settings
  • Retry and timeout configuration

Implementation Steps

1. Define Service Client Interfaces

   • Create pkg/services/auth.go
   • Create pkg/services/identity.go
   • Create pkg/services/authz.go
   • Create pkg/services/audit.go

2. Create Service Client Factory

   • Create internal/services/factory.go
   • Implement client creation logic
   • Integrate with service registry (Consul)

3. Implement gRPC Clients

   • Create internal/services/grpc/client/
   • Implement clients for each service
   • Add service discovery integration

4. Implement HTTP Clients (Fallback)

   • Create internal/services/http/client/
   • Implement clients for each service
   • Add service discovery integration

5. Add Configuration

   • Update config/default.yaml
   • Add service client configuration

6. Test Service Clients

   • Test client creation
   • Test service discovery
   • Test gRPC and HTTP clients

Acceptance Criteria

• Service client interfaces are defined for all core services
• Service factory creates gRPC clients
• Service factory creates HTTP clients (fallback)
• Service clients use Consul for service discovery
• Service clients are injectable via DI
• Configuration supports protocol selection
• All inter-service communication goes through service clients
• Service clients handle connection pooling and lifecycle

Related ADRs

• ADR-0030: Service Communication Strategy
• ADR-0033: Service Discovery Implementation

Implementation Notes

• gRPC is the primary protocol, HTTP is fallback
• All clients use Consul for service discovery
• Service clients should handle retries and circuit breakers
• Connection pooling is important for performance
• Service clients should be stateless and thread-safe

Testing

# Test service client interfaces
go test ./pkg/services/...

# Test service client factory
go test ./internal/services/...

# Test with Consul
docker-compose up consul
go test ./internal/services/... -tags=integration

Files to Create/Modify

• pkg/services/auth.go - AuthServiceClient interface
• pkg/services/identity.go - IdentityServiceClient interface
• pkg/services/authz.go - AuthzServiceClient interface
• pkg/services/audit.go - AuditServiceClient interface
• internal/services/factory.go - Service client factory
• internal/services/grpc/client/ - gRPC client implementations
• internal/services/http/client/ - HTTP client implementations
• config/default.yaml - Add service client configuration