# 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
- [x] Service client interfaces are defined for all core services
- [x] Service factory creates gRPC clients
- [x] Service factory creates HTTP clients (fallback)
- [x] Service clients use Consul for service discovery
- [x] Service clients are injectable via DI
- [x] Configuration supports protocol selection
- [x] All inter-service communication goes through service clients
- [x] Service clients handle connection pooling and lifecycle

## Related ADRs
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)

## 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
```bash
# 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