0x1d
38a251968c
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
148 lines
5.2 KiB
Markdown
148 lines
5.2 KiB
Markdown
# 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
|
|
|