omgkit 2.13.0 → 2.15.0

package/plugin/skills/microservices/circuit-breaker-patterns/SKILL.md

@@ -0,0 +1,246 @@
+# Circuit Breaker Patterns
+
+Resilience patterns with Resilience4j, Polly, bulkheads, timeouts, retries, and fallback strategies.
+
+## Overview
+
+Circuit breakers prevent cascade failures in distributed systems by detecting failures and temporarily stopping requests to failing services.
+
+## Key Patterns
+
+### Circuit Breaker States
+- **Closed**: Normal operation, requests pass through
+- **Open**: Failure threshold exceeded, requests fail fast
+- **Half-Open**: Testing if service recovered
+
+### Related Patterns
+- **Retry**: Attempt failed operations again
+- **Timeout**: Limit operation duration
+- **Bulkhead**: Isolate failures to prevent spread
+- **Fallback**: Provide alternative when primary fails
+
+## Resilience4j Implementation
+
+### Circuit Breaker
+```java
+// Configuration
+CircuitBreakerConfig config = CircuitBreakerConfig.custom()
+    .failureRateThreshold(50)                 // Open if 50% fail
+    .waitDurationInOpenState(Duration.ofSeconds(30))
+    .permittedNumberOfCallsInHalfOpenState(3)
+    .slidingWindowType(SlidingWindowType.COUNT_BASED)
+    .slidingWindowSize(10)
+    .build();
+
+CircuitBreaker circuitBreaker = CircuitBreaker.of("userService", config);
+
+// Usage
+Supplier<User> decoratedSupplier = CircuitBreaker
+    .decorateSupplier(circuitBreaker, () -> userService.getUser(userId));
+
+Try<User> result = Try.ofSupplier(decoratedSupplier)
+    .recover(CallNotPermittedException.class, e -> getCachedUser(userId));
+```
+
+### Retry with Backoff
+```java
+RetryConfig retryConfig = RetryConfig.custom()
+    .maxAttempts(3)
+    .waitDuration(Duration.ofMillis(500))
+    .exponentialBackoff(2, Duration.ofSeconds(10))
+    .retryOnException(e -> e instanceof TransientException)
+    .build();
+
+Retry retry = Retry.of("userService", retryConfig);
+
+Supplier<User> retryingSupplier = Retry
+    .decorateSupplier(retry, () -> userService.getUser(userId));
+```
+
+### Bulkhead
+```java
+// Thread pool bulkhead
+ThreadPoolBulkheadConfig bulkheadConfig = ThreadPoolBulkheadConfig.custom()
+    .maxThreadPoolSize(10)
+    .coreThreadPoolSize(5)
+    .queueCapacity(20)
+    .build();
+
+ThreadPoolBulkhead bulkhead = ThreadPoolBulkhead.of("userService", bulkheadConfig);
+
+CompletionStage<User> result = bulkhead.executeSupplier(
+    () -> userService.getUser(userId)
+);
+```
+
+### Combined Resilience
+```java
+// Combine patterns
+Supplier<User> resilientSupplier = Decorators
+    .ofSupplier(() -> userService.getUser(userId))
+    .withRetry(retry)
+    .withCircuitBreaker(circuitBreaker)
+    .withBulkhead(bulkhead)
+    .withFallback(Arrays.asList(
+        CallNotPermittedException.class,
+        BulkheadFullException.class
+    ), e -> getCachedUser(userId))
+    .decorate();
+```
+
+## Node.js Implementation (opossum)
+
+### Basic Circuit Breaker
+```javascript
+const CircuitBreaker = require('opossum');
+
+const options = {
+  timeout: 3000,           // 3 seconds
+  errorThresholdPercentage: 50,
+  resetTimeout: 30000,     // 30 seconds
+  volumeThreshold: 5,      // Minimum calls before calculating
+};
+
+const breaker = new CircuitBreaker(callExternalService, options);
+
+// Events
+breaker.on('success', (result) => console.log('Success:', result));
+breaker.on('timeout', () => console.log('Timeout'));
+breaker.on('reject', () => console.log('Rejected - circuit open'));
+breaker.on('open', () => console.log('Circuit opened'));
+breaker.on('halfOpen', () => console.log('Circuit half-open'));
+breaker.on('close', () => console.log('Circuit closed'));
+breaker.on('fallback', (result) => console.log('Fallback:', result));
+
+// Fallback
+breaker.fallback(() => ({ cached: true, data: getCachedData() }));
+
+// Usage
+const result = await breaker.fire(requestParams);
+```
+
+### Health Check Integration
+```javascript
+const breaker = new CircuitBreaker(callService, options);
+
+// Health endpoint
+app.get('/health', (req, res) => {
+  const health = {
+    status: breaker.opened ? 'degraded' : 'healthy',
+    circuitBreaker: {
+      state: breaker.opened ? 'open' : (breaker.halfOpen ? 'half-open' : 'closed'),
+      stats: breaker.stats
+    }
+  };
+  res.json(health);
+});
+```
+
+## Configuration Guidelines
+
+### Circuit Breaker Tuning
+```yaml
+# Conservative (for critical services)
+failure_threshold: 25%
+sliding_window: 20 calls
+wait_in_open: 60 seconds
+half_open_calls: 3
+
+# Aggressive (for non-critical services)
+failure_threshold: 50%
+sliding_window: 10 calls
+wait_in_open: 30 seconds
+half_open_calls: 5
+```
+
+### Retry Configuration
+```yaml
+# Idempotent operations (safe to retry)
+max_attempts: 3
+initial_delay: 100ms
+multiplier: 2
+max_delay: 5s
+jitter: 0.1
+
+# Non-idempotent (use with caution)
+max_attempts: 1
+# Or use retry only for specific errors
+```
+
+### Timeout Guidelines
+```yaml
+# Timeouts should be:
+# - Shorter than user patience (< 5s for UI)
+# - Longer than P99 latency
+# - Account for downstream timeouts
+
+http_client: 5s
+database: 10s
+external_api: 15s
+batch_operations: 60s
+```
+
+## Best Practices
+
+1. **Fail Fast**: Don't wait for timeouts when circuit is open
+2. **Graceful Degradation**: Always have fallbacks
+3. **Monitor Circuit State**: Alert on open circuits
+4. **Tune Thresholds**: Based on actual failure patterns
+5. **Test Failure Modes**: Chaos engineering
+
+## Fallback Strategies
+
+### Cached Response
+```javascript
+async function getUser(userId) {
+  try {
+    return await userService.getUser(userId);
+  } catch (error) {
+    return await cache.get(`user:${userId}`);
+  }
+}
+```
+
+### Default Value
+```javascript
+async function getRecommendations(userId) {
+  try {
+    return await recommendationService.get(userId);
+  } catch (error) {
+    return getDefaultRecommendations();
+  }
+}
+```
+
+### Degraded Service
+```javascript
+async function getProductDetails(productId) {
+  try {
+    return await getFullDetails(productId);
+  } catch (error) {
+    // Return basic info from database
+    return await getBasicDetails(productId);
+  }
+}
+```
+
+## Anti-Patterns
+
+- Circuit breaker without fallback
+- Same timeout as downstream service
+- Not resetting circuit after deployment
+- Ignoring circuit breaker metrics
+- Retrying non-idempotent operations
+
+## When to Use
+
+- Calling external/third-party services
+- Microservice-to-microservice communication
+- Operations that can fail transiently
+- When graceful degradation is acceptable
+
+## When NOT to Use
+
+- Local operations that won't fail externally
+- When all-or-nothing is required
+- Very fast operations where overhead matters

package/plugin/skills/microservices/contract-testing/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: contract-testing
+description: Consumer-driven contract testing with Pact, schema validation, provider verification, and CI/CD integration.
+---
+
+# Contract Testing
+
+Consumer-driven contract testing with Pact, schema validation, provider verification, and CI/CD integration.
+
+## Overview
+
+Contract testing ensures services can communicate correctly by verifying that providers meet consumer expectations without requiring full integration tests.
+
+## Key Concepts
+
+### Consumer-Driven Contracts
+- **Consumer**: Service that calls another service
+- **Provider**: Service being called
+- **Contract**: Expected interactions defined by consumer
+- **Pact**: Contract file containing interactions
+
+### Contract Types
+- **Consumer Contracts**: What consumer expects
+- **Provider Contracts**: What provider guarantees
+- **Bidirectional**: Both sides define expectations
+
+## Pact Implementation
+
+### Consumer Test (JavaScript)
+```javascript
+const { Pact } = require('@pact-foundation/pact');
+
+const provider = new Pact({
+  consumer: 'OrderService',
+  provider: 'UserService',
+  port: 1234,
+});
+
+describe('User Service Contract', () => {
+  beforeAll(() => provider.setup());
+  afterAll(() => provider.finalize());
+  afterEach(() => provider.verify());
+
+  describe('get user by id', () => {
+    beforeEach(() => {
+      return provider.addInteraction({
+        state: 'user with id 123 exists',
+        uponReceiving: 'a request for user 123',
+        withRequest: {
+          method: 'GET',
+          path: '/users/123',
+          headers: {
+            Accept: 'application/json',
+          },
+        },
+        willRespondWith: {
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: {
+            id: '123',
+            name: Matchers.string('John Doe'),
+            email: Matchers.email(),
+            createdAt: Matchers.iso8601DateTime(),
+          },
+        },
+      });
+    });
+
+    it('returns user details', async () => {
+      const user = await userClient.getUser('123');
+      expect(user.id).toBe('123');
+      expect(user.name).toBeDefined();
+    });
+  });
+});
+```
+
+### Provider Verification (JavaScript)
+```javascript
+const { Verifier } = require('@pact-foundation/pact');
+
+describe('User Service Provider Verification', () => {
+  it('validates the expectations of OrderService', async () => {
+    const verifier = new Verifier({
+      provider: 'UserService',
+      providerBaseUrl: 'http://localhost:8080',
+      pactBrokerUrl: 'https://pact-broker.example.com',
+      publishVerificationResult: true,
+      providerVersion: process.env.GIT_SHA,
+      stateHandlers: {
+        'user with id 123 exists': async () => {
+          await createTestUser({ id: '123', name: 'John Doe' });
+        },
+        'no users exist': async () => {
+          await clearAllUsers();
+        },
+      },
+    });
+
+    await verifier.verifyProvider();
+  });
+});
+```
+
+### Pact Matchers
+```javascript
+const { Matchers } = require('@pact-foundation/pact');
+
+// Type matchers
+Matchers.string('example')      // Any string
+Matchers.integer(123)           // Any integer
+Matchers.decimal(12.34)         // Any decimal
+Matchers.boolean(true)          // Any boolean
+
+// Format matchers
+Matchers.email()                // Valid email
+Matchers.uuid()                 // Valid UUID
+Matchers.iso8601DateTime()      // ISO 8601 datetime
+Matchers.ipv4Address()          // IPv4 address
+
+// Collection matchers
+Matchers.eachLike({             // Array with items like...
+  id: Matchers.integer(),
+  name: Matchers.string()
+}, { min: 1 })
+
+// Regex matcher
+Matchers.term({
+  matcher: '^[A-Z]{2}[0-9]{4}$',
+  generate: 'AB1234'
+})
+```
+
+## Pact Broker
+
+### Publishing Contracts
+```bash
+# Publish pact files to broker
+pact-broker publish ./pacts \
+  --consumer-app-version=$GIT_SHA \
+  --branch=$GIT_BRANCH \
+  --broker-base-url=https://pact-broker.example.com \
+  --broker-token=$PACT_BROKER_TOKEN
+```
+
+### Can-I-Deploy Check
+```bash
+# Check if safe to deploy
+pact-broker can-i-deploy \
+  --pacticipant=OrderService \
+  --version=$GIT_SHA \
+  --to-environment=production \
+  --broker-base-url=https://pact-broker.example.com
+```
+
+### Webhooks
+```json
+{
+  "description": "Trigger provider verification on contract change",
+  "events": [
+    { "name": "contract_content_changed" }
+  ],
+  "request": {
+    "method": "POST",
+    "url": "https://ci.example.com/trigger",
+    "headers": {
+      "Content-Type": "application/json"
+    },
+    "body": {
+      "provider": "${pactbroker.providerName}",
+      "consumer": "${pactbroker.consumerName}",
+      "pactUrl": "${pactbroker.pactUrl}"
+    }
+  }
+}
+```
+
+## CI/CD Integration
+
+### Consumer Pipeline
+```yaml
+# GitHub Actions - Consumer
+name: Consumer Contract Tests
+
+on: [push]
+
+jobs:
+  contract-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Run contract tests
+        run: npm run test:contract
+
+      - name: Publish contracts
+        run: |
+          pact-broker publish ./pacts \
+            --consumer-app-version=${{ github.sha }} \
+            --branch=${{ github.ref_name }} \
+            --broker-base-url=${{ secrets.PACT_BROKER_URL }} \
+            --broker-token=${{ secrets.PACT_BROKER_TOKEN }}
+
+      - name: Can I deploy?
+        run: |
+          pact-broker can-i-deploy \
+            --pacticipant=OrderService \
+            --version=${{ github.sha }} \
+            --to-environment=staging
+```
+
+### Provider Pipeline
+```yaml
+# GitHub Actions - Provider
+name: Provider Verification
+
+on:
+  push:
+  repository_dispatch:
+    types: [pact_changed]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Start provider
+        run: docker-compose up -d
+
+      - name: Verify contracts
+        run: npm run test:pact:verify
+        env:
+          PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          PROVIDER_VERSION: ${{ github.sha }}
+```
+
+## Best Practices
+
+1. **Consumer First**: Let consumers define expectations
+2. **Minimal Contracts**: Only test what consumer needs
+3. **State Management**: Proper provider state setup
+4. **Version Everything**: Use git SHA for versions
+5. **Automate Can-I-Deploy**: Gate deployments on verification
+
+## Contract Design Guidelines
+
+### What to Include
+- Request path and method
+- Required headers
+- Request body structure
+- Response status codes
+- Response body structure
+
+### What to Avoid
+- Implementation details
+- Exact values (use matchers)
+- Optional fields unless needed
+- Authentication details
+
+## Anti-Patterns
+
+- Testing every field exhaustively
+- Coupling to specific values
+- Ignoring provider states
+- Skipping can-i-deploy checks
+- Not versioning contracts
+
+## When to Use
+
+- Microservices with multiple consumers
+- Independent team deployments
+- APIs with breaking change risk
+- Contract evolution tracking
+
+## When NOT to Use
+
+- Single consumer APIs
+- Rapidly prototyping
+- Internal implementation details
+- UI testing