---
name: inter-service-communication
description: Inter-service communication patterns for GoodGo microservices including gRPC, GraphQL, service-to-service authentication, protocol selection, and client patterns. Use when implementing service-to-service calls, choosing communication protocols, or building service clients.
---

# Inter-Service Communication Patterns

## When to Use This Skill

Use this skill when:
- Implementing service-to-service communication
- Choosing between REST, gRPC, or GraphQL protocols
- Setting up gRPC services and clients
- Implementing GraphQL services and resolvers
- Implementing service-to-service authentication
- Building resilient service clients with circuit breakers
- Managing connection pooling for service clients
- Implementing request/response interceptors
- Handling service discovery for internal calls
- Optimizing inter-service communication performance

## Core Concepts

### Communication Protocol Options

**HTTP/REST:**
- Human-readable, easy to debug
- Browser-compatible
- Standard HTTP semantics
- JSON payloads
- Good for external APIs

**gRPC:**
- Binary protocol (Protocol Buffers)
- High performance, low latency
- Streaming support
- Strong typing with .proto files
- HTTP/2 based

**GraphQL:**
- Flexible query language
- Single endpoint
- Client-controlled data fetching
- Strong typing with schema

### Protocol Selection Guidelines

Choose protocol based on use case, performance requirements, team expertise, and ecosystem needs.

#### Protocol Selection Decision Tree

```mermaid
flowchart TD
    Start([Need Inter-Service Communication]) --> CheckExternal{External/Public API?}
    
    CheckExternal -->|Yes| UseREST[Use REST]
    CheckExternal -->|No| CheckPerformance{High Performance<br/>Required?}
    
    CheckPerformance -->|Yes| CheckStreaming{Need Streaming?}
    CheckPerformance -->|No| CheckFlexible{Need Flexible<br/>Queries?}
    
    CheckStreaming -->|Yes| UseGRPC[Use gRPC]
    CheckStreaming -->|No| CheckLowLatency{Ultra Low<br/>Latency?}
    
    CheckLowLatency -->|Yes| UseGRPC
    CheckLowLatency -->|No| UseREST
    
    CheckFlexible -->|Yes| UseGraphQL[Use GraphQL]
    CheckFlexible -->|No| UseREST
    
    UseREST --> RESTDesc["REST: External APIs<br/>Browser clients<br/>Simple CRUD"]
    UseGRPC --> GRPCDesc["gRPC: Internal services<br/>High performance<br/>Streaming support"]
    UseGraphQL --> GraphQLDesc["GraphQL: Complex queries<br/>Mobile apps<br/>Flexible data"]
    
    style UseREST fill:#e1f5ff
    style UseGRPC fill:#fff4e1
    style UseGraphQL fill:#e8f5e9
```

## Key Patterns

### Service-to-Service Call Flow

The following diagram illustrates the complete flow of a service-to-service call, including authentication, interceptors, and error handling:

```mermaid
sequenceDiagram
    participant ClientService as Client Service
    participant ClientLib as Service Client<br/>(HTTP/gRPC/GraphQL)
    participant Interceptor as Request<br/>Interceptor
    participant Auth as Auth<br/>Middleware
    participant TargetService as Target Service
    participant Logger as Logger
    participant Metrics as Metrics
    
    ClientService->>ClientLib: Make request
    ClientLib->>Interceptor: Add correlation ID<br/>Add service auth header<br/>Add request ID
    Interceptor->>Logger: Log request start
    Interceptor->>Metrics: Track request start
    Interceptor->>TargetService: HTTP/gRPC/GraphQL Request<br/>(with headers)
    
    TargetService->>Auth: Validate x-service-auth
    alt Invalid Auth
        Auth-->>TargetService: 403 Forbidden
        TargetService-->>ClientLib: Error Response
        ClientLib->>Logger: Log error
        ClientLib->>Metrics: Track failure
        ClientLib-->>ClientService: ServiceError
    else Valid Auth
        Auth->>TargetService: Authenticated
        TargetService->>TargetService: Process request
        TargetService-->>ClientLib: Success Response
        ClientLib->>Logger: Log success<br/>(with correlation ID)
        ClientLib->>Metrics: Track success<br/>(duration, status)
        ClientLib-->>ClientService: Response Data
    end
```

### HTTP/REST Service Client

```typescript
// Base service client with circuit breaker and interceptors
import { ServiceClient } from '../../core/clients/service-client';

const notificationClient = new ServiceClient({
  baseURL: process.env.NOTIFICATION_SERVICE_URL || 'http://notification-service:5003',
  serviceName: 'notification-service',
  timeout: 5000,
  enableCircuitBreaker: true,
});

// Usage
await notificationClient.post('/api/v1/notifications', {
  userId,
  message,
});
```

### gRPC Service

```typescript
// gRPC server implementation
import { UserGrpcServer } from './user.grpc.service';

const grpcServer = new UserGrpcServer(userService);
grpcServer.start(50051);

// gRPC client
import { GrpcClient } from '../../core/clients/grpc-client';

const userGrpcClient = new GrpcClient({
  protoPath: './proto/user_service.proto',
  packageName: 'goodgo.user.v1',
  serviceName: 'UserService',
  serverUrl: 'localhost:50051',
});

const user = await userGrpcClient.call('getUser', { user_id: '123' });
```

### GraphQL Service

```typescript
// GraphQL client
import { GraphQLServiceClient } from '../../core/clients/graphql-client';

const userGraphQLClient = new GraphQLServiceClient({
  endpoint: 'http://user-service:5002/graphql',
});

const GET_USER_QUERY = `
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      email
      name
    }
  }
`;

const user = await userGraphQLClient.query(GET_USER_QUERY, { id: '123' });
```

### Service-to-Service Authentication

The authentication flow ensures secure communication between services:

```mermaid
sequenceDiagram
    participant ClientService as Client Service
    participant ServiceClient as Service Client
    participant Env as Environment<br/>Variables
    participant TargetService as Target Service
    participant AuthMiddleware as Auth<br/>Middleware
    
    ClientService->>ServiceClient: Create client instance
    ServiceClient->>Env: Read INTERNAL_API_KEY
    Env-->>ServiceClient: API Key
    
    ClientService->>ServiceClient: Make request
    ServiceClient->>ServiceClient: Auto-add x-service-auth<br/>header with API key
    
    ServiceClient->>TargetService: HTTP Request<br/>(x-service-auth: token)
    
    TargetService->>AuthMiddleware: Extract x-service-auth
    AuthMiddleware->>AuthMiddleware: Compare with<br/>INTERNAL_API_KEY
    
    alt Token Matches
        AuthMiddleware->>TargetService: Auth Success
        TargetService->>TargetService: Process request
        TargetService-->>ServiceClient: 200 OK + Data
    else Token Mismatch
        AuthMiddleware->>TargetService: Auth Failed
        TargetService-->>ServiceClient: 403 Forbidden<br/>(INVALID_SERVICE_AUTH)
        ServiceClient->>ServiceClient: Throw ServiceError
        ServiceClient-->>ClientService: Error Response
    end
```

#### Implementation

```typescript
// Internal auth middleware
import { internalAuthMiddleware } from '../../middlewares/internal-auth.middleware';

router.use('/internal', internalAuthMiddleware);

// Client automatically adds auth header
const client = new ServiceClient({
  baseURL: 'http://service:5000',
  serviceName: 'service',
});
// X-Service-Auth header is added automatically
```

## Best Practices

### Protocol Selection

- **REST**: External APIs, browser clients, simple CRUD
- **gRPC**: Internal services, high performance, streaming
- **GraphQL**: Complex queries, mobile apps, flexible data

### Performance

- Use connection pooling
- Enable HTTP keep-alive
- Set appropriate timeouts
- Implement circuit breakers

### Security

- Always authenticate internal calls
- Use TLS/mTLS
- Store secrets securely
- Implement rate limiting

### Observability

- Log with correlation IDs
- Track metrics (duration, success rate)
- Add distributed tracing
- Monitor service health

## Testing

```typescript
// Mock service client
const mockClient = createMockServiceClient();
mockClient.get.mockResolvedValue({ id: '123' });
```

## Resources

- [gRPC Documentation](https://grpc.io/docs/)
- [GraphQL Documentation](https://graphql.org/learn/)
- [Protocol Buffers](https://developers.google.com/protocol-buffers)
- [Resilience Patterns](./resilience-patterns.md)
- [Security](./security.md)
- Skill Source: `.cursor/skills/inter-service-communication/SKILL.md`
