goplt/docs/content/stories/epic1/1.7-service-abstraction-layer.md

Story 1.7: Service Client Interfaces

Metadata

• Story ID: 1.7
• Title: Service Client Interfaces
• Epic: 1 - Core Kernel & Infrastructure
• Status: Pending
• Priority: High
• Estimated Time: 4-6 hours
• Dependencies: 1.1, 1.2, 2.1, 2.2

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 implements the foundation for microservices architecture by creating service client interfaces for all core services. These interfaces will be implemented as gRPC clients (primary) or HTTP clients (fallback), ensuring all services communicate via network calls.

Deliverables

1. Service Client Interfaces (pkg/services/)

Define service client interfaces for all core services:

• IdentityServiceClient - User and identity operations
• AuthServiceClient - Authentication operations
• AuthzServiceClient - Authorization operations
• PermissionServiceClient - Permission resolution
• AuditServiceClient - Audit logging
• CacheServiceClient - Cache operations (if needed)
• EventBusClient - Event publishing (already abstracted)

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

Factory pattern for creating service clients:

• Create gRPC clients (primary)
• Create HTTP clients (fallback)
• Support service registry integration
• Handle client lifecycle and connection pooling

3. Configuration

• Service client configuration in config/default.yaml:

  services:
    default_protocol: grpc  # grpc, http
    registry:
      type: consul  # consul, kubernetes, etcd
      consul:
        address: localhost:8500
  

5. DI Integration

• Provider functions for service clients
• Register in DI container
• Support service client injection

Implementation Steps

1. Define Service Client Interfaces

   • Create pkg/services/identity.go
   • Create pkg/services/auth.go
   • Create pkg/services/authz.go
   • Define all interface methods
   • Design for network calls (context, timeouts, errors)

2. Create Service Factory

   • Create internal/services/factory.go
   • Implement gRPC client creation
   • Implement HTTP client creation (fallback)
   • Support service registry integration

3. Add Configuration

   • Add service configuration
   • Support protocol selection (gRPC/HTTP)
   • Service registry configuration

4. Update Core Services

   • Services expose gRPC servers
   • Services use service clients for inter-service calls
   • No direct in-process calls between services

Acceptance Criteria

• Service client interfaces are defined for all core services
• Service factory creates gRPC clients
• Service factory creates HTTP clients (fallback)
• Service clients are injectable via DI
• Configuration supports protocol selection
• Service clients are testable and mockable
• All inter-service communication goes through service clients

Related ADRs

• ADR-0029: Microservices Architecture
• ADR-0030: Service Communication Strategy

Implementation Notes

• Interfaces should match existing service methods
• Use context for all operations
• Support cancellation and timeouts
• Design for network calls (retries, circuit breakers)
• gRPC will be implemented in Epic 5, but interfaces are defined here

Testing

# Test service clients
go test ./internal/services/...

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

Files to Create/Modify

• pkg/services/identity.go - Identity service client interface
• pkg/services/auth.go - Auth service client interface
• pkg/services/authz.go - Authz service client interface
• internal/services/factory.go - Service client factory
• internal/di/providers.go - Add service client providers
• config/default.yaml - Add service configuration