@sylix/coworker 2.0.11 → 2.0.12

package/dist/skills/defaults/backend-development/microservices.md

@@ -0,0 +1,284 @@
+---
+name: microservices
+description: Design and implement microservices architectures with patterns for service decomposition, communication, and orchestration.
+---
+
+# Microservices Architecture — CoWorker Edition
+
+Build scalable, maintainable distributed systems using proven microservices patterns.
+
+## When to Use This Skill
+
+- Decomposing a monolith into services
+- Designing new distributed systems
+- Choosing communication patterns between services
+- Implementing service discovery and orchestration
+- Handling distributed transactions
+
+## Core Principles
+
+### 1. Service Decomposition
+
+**When to split a service:**
+- Different scaling requirements
+- Distinct domain boundaries
+- Independent deployment cycles
+- Different technology needs
+
+**How to decompose:**
+- Start with business capabilities
+- Identify bounded contexts (DDD)
+- Define clear API contracts
+- Extract incrementally
+
+```python
+# Bad: Too granular - chat system split into 20 services
+# user-service, message-service, read-service, typing-service,
+# presence-service, notification-service, etc.
+
+# Good: Decompose by business capability
+# user-service, conversation-service, notification-service
+```
+
+### 2. Communication Patterns
+
+#### Synchronous (REST/gRPC)
+
+```python
+# FastAPI service
+from fastapi import HTTPException
+
+class OrderService:
+    def __init__(self, http_client):
+        self.http = http_client
+    
+    async def get_order_with_user(self, order_id: str):
+        order = await self.get_order(order_id)
+        if not order:
+            raise HTTPException(404, "Order not found")
+        
+        # Sync call to user service
+        user = await self.http.get(
+            f"http://user-service/api/users/{order.user_id}"
+        )
+        order.user = user
+        return order
+```
+
+#### Asynchronous (Message Queues)
+
+```python
+import aio_pika
+
+class OrderService:
+    async def create_order(self, order_data: dict):
+        # Create order locally
+        order = await self.save_order(order_data)
+        
+        # Publish event asynchronously
+        await self.channel.default_exchange.publish(
+            aio_pika.Message(
+                body=json.dumps({
+                    "event": "order.created",
+                    "order_id": order.id,
+                    "user_id": order.user_id
+                }).encode()
+            ),
+            routing_key="order.events"
+        )
+        
+        return order
+```
+
+### 3. Service Discovery
+
+```yaml
+# Kubernetes service (k8s)
+apiVersion: v1
+kind: Service
+metadata:
+  name: user-service
+spec:
+  selector:
+    app: user-service
+  ports:
+    - port: 80
+      targetPort: 8080
+---
+apiVersion: v1
+kind: Endpoints
+metadata:
+  name: user-service
+subsets:
+  - addresses:
+      - ip: 10.1.0.5
+    ports:
+      - port: 8080
+```
+
+### 4. Circuit Breaker Pattern
+
+```python
+from circuitbreaker import circuit
+
+class UserServiceClient:
+    @circuit(failure_threshold=5, recovery_timeout=30)
+    async def get_user(self, user_id: str):
+        response = await self.http.get(
+            f"http://user-service/api/users/{user_id}",
+            timeout=5
+        )
+        if response.status == 503:
+            raise ServiceUnavailable()
+        return response.json()
+
+# Fallback when circuit is open
+async def get_user_safe(user_id: str):
+    try:
+        return await user_client.get_user(user_id)
+    except CircuitOpenError:
+        # Return cached data or default
+        return await cache.get(f"user:{user_id}")
+```
+
+### 5. Distributed Tracing
+
+```python
+from opentelemetry import trace
+
+tracer = trace.get_tracer(__name__)
+
+class OrderService:
+    async def process_order(self, order_id: str):
+        with tracer.start_as_current_span("process_order") as span:
+            span.set_attribute("order.id", order_id)
+            
+            # This span automatically includes parent context
+            user = await self.get_user(order_id)
+            
+            with tracer.start_as_current_span("process_payment"):
+                await self.payment_service.charge(user, order_id)
+            
+            return {"status": "processed"}
+```
+
+## Service Mesh
+
+### Istio Configuration
+
+```yaml
+apiVersion: networking.istio.io/v1beta1
+kind: VirtualService
+metadata:
+  name: order-service
+spec:
+  hosts:
+    - order-service
+  http:
+    - match:
+        - headers:
+            x-canary:
+              exact: "true"
+      route:
+        - destination:
+            host: order-service
+            subset: v2
+          weight: 10
+    - route:
+        - destination:
+            host: order-service
+            subset: v1
+          weight: 90
+---
+apiVersion: networking.istio.io/v1beta1
+kind: DestinationRule
+metadata:
+  name: order-service
+spec:
+  host: order-service
+  trafficPolicy:
+    connectionPool:
+      tcp:
+        maxConnections: 100
+      http:
+        h2UpgradePolicy: UPGRADE
+        http2MaxRequests: 1000
+    circuitBreaker:
+      consecutive5xxErrors: 5
+      interval: 30s
+      baseEjectionTime: 60s
+```
+
+## Saga Pattern
+
+### Choreography
+
+```python
+# Order Service - publishes events
+async def create_order(order_data):
+    order = await save_order({**order_data, status: "PENDING"})
+    
+    await publisher.publish("order.created", {
+        "order_id": order.id,
+        "items": order.items
+    })
+    
+    return order
+
+# Inventory Service - listens and reacts
+async def on_order_created(event):
+    if not reserve_inventory(event.items):
+        await publisher.publish("order.failed", {
+            "order_id": event.order_id,
+            "reason": "inventory_unavailable"
+        })
+    else:
+        await publisher.publish("inventory.reserved", {
+            "order_id": event.order_id
+        })
+```
+
+### Orchestration
+
+```python
+class OrderSagaOrchestrator:
+    def __init__(self):
+        self.steps = [
+            ReserveInventoryStep(),
+            ProcessPaymentStep(),
+            CreateShippingLabelStep(),
+            NotifyCustomerStep()
+        ]
+    
+    async def execute(self, order_data):
+        saga = SagaContext(order_id=generate_id())
+        
+        for step in self.steps:
+            try:
+                await step.execute(saga)
+            except StepFailed as e:
+                await self.compensate(saga, e.step)
+                raise OrderFailed(e.reason)
+        
+        return saga.order
+```
+
+## Best Practices
+
+1. **API Design** - Well-defined contracts, versioning, documentation
+2. **Single Responsibility** - Each service does one thing well
+3. **Loose Coupling** - Services share only contracts, not databases
+4. **Observability** - Distributed tracing, logging, metrics
+5. **Resilience** - Circuit breakers, retries, timeouts
+6. **Configuration** - Externalize config, use config maps/secrets
+7. **Security** - mTLS between services, API gateways, rate limiting
+
+## Common Pitfalls
+
+- Distributed monolith (services too tightly coupled)
+- Shared databases (breaks independence)
+- Lack of observability
+- No circuit breakers
+- Synchronous everywhere (cascading failures)
+- Ignoring failure modes
+- Over-decomposition (too many services)