@hivehub/rulebook 5.5.2 → 5.8.0

package/templates/services/RABBITMQ.md

@@ -1,286 +0,0 @@
-<!-- RABBITMQ:START -->
-# RabbitMQ Message Queue Instructions
-
-**CRITICAL**: Use RabbitMQ for reliable message queuing, pub/sub messaging, and task distribution with multiple exchange types.
-
-## Core Features
-
-### Connection
-```typescript
-// Using amqplib
-import amqp from 'amqplib'
-
-const connection = await amqp.connect(process.env.RABBITMQ_URL || 'amqp://localhost:5672')
-const channel = await connection.createChannel()
-
-// Connection with options
-const connection = await amqp.connect({
-  protocol: 'amqp',
-  hostname: process.env.RABBITMQ_HOST || 'localhost',
-  port: parseInt(process.env.RABBITMQ_PORT || '5672'),
-  username: process.env.RABBITMQ_USER || 'guest',
-  password: process.env.RABBITMQ_PASSWORD || 'guest',
-  vhost: process.env.RABBITMQ_VHOST || '/',
-})
-```
-
-### Basic Operations
-```typescript
-// Declare queue
-await channel.assertQueue('tasks', {
-  durable: true, // Survive broker restart
-})
-
-// Send message
-channel.sendToQueue('tasks', Buffer.from(JSON.stringify({ task: 'process' })), {
-  persistent: true, // Survive broker restart
-})
-
-// Consume messages
-await channel.consume('tasks', (msg) => {
-  if (msg) {
-    const content = JSON.parse(msg.content.toString())
-    console.log('Received:', content)
-    
-    // Process message
-    processTask(content)
-    
-    // Acknowledge
-    channel.ack(msg)
-  }
-}, {
-  noAck: false, // Manual acknowledgment
-})
-```
-
-### Exchange Types
-```typescript
-// Direct exchange
-await channel.assertExchange('logs', 'direct', { durable: true })
-await channel.bindQueue('queue', 'logs', 'error')
-await channel.publish('logs', 'error', Buffer.from('Error message'))
-
-// Topic exchange
-await channel.assertExchange('events', 'topic', { durable: true })
-await channel.bindQueue('queue', 'events', 'user.*.created')
-await channel.publish('events', 'user.123.created', Buffer.from(JSON.stringify(data)))
-
-// Fanout exchange (broadcast)
-await channel.assertExchange('notifications', 'fanout', { durable: true })
-await channel.bindQueue('queue1', 'notifications', '')
-await channel.bindQueue('queue2', 'notifications', '')
-await channel.publish('notifications', '', Buffer.from('Broadcast message'))
-
-// Headers exchange
-await channel.assertExchange('headers_exchange', 'headers', { durable: true })
-await channel.bindQueue('queue', 'headers_exchange', '', {
-  'x-match': 'all',
-  type: 'notification',
-  priority: 'high',
-})
-await channel.publish('headers_exchange', '', Buffer.from('Message'), {
-  headers: { type: 'notification', priority: 'high' },
-})
-```
-
-## Common Patterns
-
-### Work Queue (Task Distribution)
-```typescript
-// Producer
-async function publishTask(task: any) {
-  await channel.assertQueue('tasks', { durable: true })
-  channel.sendToQueue('tasks', Buffer.from(JSON.stringify(task)), {
-    persistent: true,
-  })
-}
-
-// Consumer
-async function consumeTasks() {
-  await channel.assertQueue('tasks', { durable: true })
-  channel.prefetch(1) // Process one message at a time
-  
-  await channel.consume('tasks', async (msg) => {
-    if (msg) {
-      try {
-        const task = JSON.parse(msg.content.toString())
-        await processTask(task)
-        channel.ack(msg)
-      } catch (error) {
-        // Reject and requeue
-        channel.nack(msg, false, true)
-      }
-    }
-  })
-}
-```
-
-### Pub/Sub
-```typescript
-// Publisher
-async function publishEvent(eventType: string, data: any) {
-  await channel.assertExchange('events', 'topic', { durable: true })
-  channel.publish('events', eventType, Buffer.from(JSON.stringify(data)), {
-    persistent: true,
-  })
-}
-
-// Subscriber
-async function subscribeToEvents(routingKey: string, handler: (data: any) => void) {
-  await channel.assertExchange('events', 'topic', { durable: true })
-  const queue = await channel.assertQueue('', { exclusive: true })
-  await channel.bindQueue(queue.queue, 'events', routingKey)
-  
-  await channel.consume(queue.queue, (msg) => {
-    if (msg) {
-      const data = JSON.parse(msg.content.toString())
-      handler(data)
-      channel.ack(msg)
-    }
-  })
-}
-```
-
-### RPC Pattern
-```typescript
-// RPC Server
-async function setupRPCServer() {
-  await channel.assertQueue('rpc_queue', { durable: false })
-  channel.prefetch(1)
-  
-  await channel.consume('rpc_queue', async (msg) => {
-    if (msg) {
-      const request = JSON.parse(msg.content.toString())
-      const response = await processRequest(request)
-      
-      channel.sendToQueue(
-        msg.properties.replyTo,
-        Buffer.from(JSON.stringify(response)),
-        {
-          correlationId: msg.properties.correlationId,
-        }
-      )
-      
-      channel.ack(msg)
-    }
-  })
-}
-
-// RPC Client
-async function rpcCall(request: any): Promise<any> {
-  const queue = await channel.assertQueue('', { exclusive: true })
-  const correlationId = generateUuid()
-  
-  return new Promise((resolve, reject) => {
-    const timeout = setTimeout(() => {
-      channel.deleteQueue(queue.queue)
-      reject(new Error('RPC timeout'))
-    }, 10000)
-    
-    channel.consume(queue.queue, (msg) => {
-      if (msg && msg.properties.correlationId === correlationId) {
-        clearTimeout(timeout)
-        const response = JSON.parse(msg.content.toString())
-        channel.deleteQueue(queue.queue)
-        resolve(response)
-      }
-    }, { noAck: true })
-    
-    channel.sendToQueue('rpc_queue', Buffer.from(JSON.stringify(request)), {
-      correlationId,
-      replyTo: queue.queue,
-    })
-  })
-}
-```
-
-## Best Practices
-
-✅ **DO:**
-- Use durable queues and exchanges for important messages
-- Set message persistence for critical messages
-- Use manual acknowledgment (noAck: false)
-- Implement proper error handling
-- Use prefetch to control message distribution
-- Monitor queue lengths
-- Use dead letter exchanges for failed messages
-- Implement connection retry logic
-- Use appropriate exchange types
-- Set message TTL when needed
-
-❌ **DON'T:**
-- Skip acknowledgment (lose messages on crash)
-- Use auto-ack for critical messages
-- Ignore connection errors
-- Hardcode connection strings
-- Store large messages (use external storage)
-- Skip error handling
-- Ignore queue monitoring
-- Use non-durable queues for important data
-- Skip message persistence
-- Ignore memory limits
-
-## Configuration
-
-### Environment Variables
-```bash
-RABBITMQ_URL=amqp://localhost:5672
-RABBITMQ_URL=amqp://user:password@host:5672/vhost
-RABBITMQ_HOST=localhost
-RABBITMQ_PORT=5672
-RABBITMQ_USER=guest
-RABBITMQ_PASSWORD=guest
-RABBITMQ_VHOST=/
-```
-
-### Docker Compose
-```yaml
-services:
-  rabbitmq:
-    image: rabbitmq:3-management-alpine
-    ports:
-      - "5672:5672"   # AMQP
-      - "15672:15672" # Management UI
-    environment:
-      RABBITMQ_DEFAULT_USER: admin
-      RABBITMQ_DEFAULT_PASS: securepassword
-    volumes:
-      - rabbitmq_data:/var/lib/rabbitmq
-    healthcheck:
-      test: ["CMD", "rabbitmq-diagnostics", "ping"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-volumes:
-  rabbitmq_data:
-```
-
-## Integration with Development
-
-### Testing
-```typescript
-// Use test connection
-const testConnection = await amqp.connect('amqp://localhost:5673') // Different port
-
-// Clean up after tests
-afterEach(async () => {
-  // Delete test queues/exchanges or use separate vhost
-})
-```
-
-### Health Checks
-```typescript
-async function checkRabbitMQHealth(): Promise<boolean> {
-  try {
-    const connection = await amqp.connect(process.env.RABBITMQ_URL)
-    await connection.close()
-    return true
-  } catch {
-    return false
-  }
-}
-```
-
-<!-- RABBITMQ:END -->
-

package/templates/services/REDIS.md

@@ -1,292 +0,0 @@
-<!-- REDIS:START -->
-# Redis Cache Instructions
-
-**CRITICAL**: Use Redis for high-performance caching, session storage, pub/sub messaging, and real-time features.
-
-## Core Features
-
-### Connection
-```typescript
-// Using redis (Node.js)
-import { createClient } from 'redis'
-
-const client = createClient({
-  url: process.env.REDIS_URL || 'redis://localhost:6379',
-  socket: {
-    reconnectStrategy: (retries) => {
-      if (retries > 10) {
-        return new Error('Too many reconnection attempts')
-      }
-      return Math.min(retries * 100, 3000)
-    },
-  },
-})
-
-await client.connect()
-
-// Using ioredis
-import Redis from 'ioredis'
-
-const redis = new Redis({
-  host: process.env.REDIS_HOST || 'localhost',
-  port: parseInt(process.env.REDIS_PORT || '6379'),
-  password: process.env.REDIS_PASSWORD,
-  retryStrategy: (times) => Math.min(times * 50, 2000),
-  maxRetriesPerRequest: 3,
-})
-```
-
-### Basic Operations
-```typescript
-// String operations
-await client.set('user:1', JSON.stringify({ name: 'John', email: 'john@example.com' }))
-await client.set('user:1', 'value', { EX: 3600 }) // Expire in 1 hour
-const user = await client.get('user:1')
-await client.del('user:1')
-
-// Multiple operations
-await client.mSet({
-  'key1': 'value1',
-  'key2': 'value2',
-})
-const values = await client.mGet(['key1', 'key2'])
-
-// Increment/Decrement
-await client.incr('counter')
-await client.incrBy('counter', 5)
-await client.decr('counter')
-```
-
-### Data Structures
-```typescript
-// Lists
-await client.lPush('tasks', 'task1', 'task2')
-await client.rPush('tasks', 'task3')
-const task = await client.lPop('tasks')
-const tasks = await client.lRange('tasks', 0, -1)
-
-// Sets
-await client.sAdd('tags', 'javascript', 'typescript', 'nodejs')
-const tags = await client.sMembers('tags')
-const exists = await client.sIsMember('tags', 'javascript')
-await client.sRem('tags', 'javascript')
-
-// Sorted Sets
-await client.zAdd('leaderboard', {
-  score: 100,
-  value: 'player1',
-})
-const topPlayers = await client.zRange('leaderboard', 0, 9, { REV: true })
-
-// Hashes
-await client.hSet('user:1', {
-  name: 'John',
-  email: 'john@example.com',
-  age: '30',
-})
-const user = await client.hGetAll('user:1')
-await client.hIncrBy('user:1', 'age', 1)
-```
-
-### Advanced Features
-```typescript
-// Pub/Sub
-const publisher = client.duplicate()
-await publisher.connect()
-
-const subscriber = client.duplicate()
-await subscriber.connect()
-
-await subscriber.subscribe('notifications', (message) => {
-  console.log('Received:', message)
-})
-
-await publisher.publish('notifications', JSON.stringify({ type: 'alert', message: 'Hello' }))
-
-// Streams
-await client.xAdd('events', '*', {
-  type: 'user_login',
-  userId: '123',
-  timestamp: Date.now().toString(),
-})
-
-const events = await client.xRead({
-  key: 'events',
-  id: '0',
-}, {
-  COUNT: 10,
-  BLOCK: 1000,
-})
-
-// Transactions
-const multi = client.multi()
-multi.set('key1', 'value1')
-multi.set('key2', 'value2')
-multi.incr('counter')
-await multi.exec()
-```
-
-## Common Patterns
-
-### Caching
-```typescript
-async function getCachedUser(userId: string) {
-  const cached = await client.get(`user:${userId}`)
-  if (cached) {
-    return JSON.parse(cached)
-  }
-  
-  const user = await fetchUserFromDatabase(userId)
-  await client.set(`user:${userId}`, JSON.stringify(user), { EX: 3600 })
-  return user
-}
-
-// Cache with tags (for invalidation)
-async function cacheWithTags(key: string, value: any, tags: string[], ttl: number) {
-  await client.set(key, JSON.stringify(value), { EX: ttl })
-  for (const tag of tags) {
-    await client.sAdd(`tag:${tag}`, key)
-  }
-}
-
-async function invalidateByTag(tag: string) {
-  const keys = await client.sMembers(`tag:${tag}`)
-  if (keys.length > 0) {
-    await client.del(...keys)
-  }
-  await client.del(`tag:${tag}`)
-}
-```
-
-### Rate Limiting
-```typescript
-async function checkRateLimit(userId: string, limit: number, window: number): Promise<boolean> {
-  const key = `ratelimit:${userId}`
-  const current = await client.incr(key)
-  
-  if (current === 1) {
-    await client.expire(key, window)
-  }
-  
-  return current <= limit
-}
-```
-
-### Session Storage
-```typescript
-async function setSession(sessionId: string, data: any, ttl: number) {
-  await client.set(`session:${sessionId}`, JSON.stringify(data), { EX: ttl })
-}
-
-async function getSession(sessionId: string) {
-  const data = await client.get(`session:${sessionId}`)
-  return data ? JSON.parse(data) : null
-}
-
-async function deleteSession(sessionId: string) {
-  await client.del(`session:${sessionId}`)
-}
-```
-
-### Distributed Locks
-```typescript
-async function acquireLock(key: string, ttl: number): Promise<boolean> {
-  const result = await client.set(key, 'locked', {
-    EX: ttl,
-    NX: true, // Only set if not exists
-  })
-  return result === 'OK'
-}
-
-async function releaseLock(key: string) {
-  await client.del(key)
-}
-```
-
-## Best Practices
-
-✅ **DO:**
-- Use connection pooling
-- Set appropriate TTL for cached data
-- Use pipelining for multiple operations
-- Use transactions (MULTI/EXEC) for atomic operations
-- Monitor memory usage
-- Use appropriate data structures (hash for objects, set for unique values)
-- Implement cache invalidation strategies
-- Use Redis Cluster for high availability
-- Enable persistence (RDB or AOF) for production
-- Use Redis Sentinel for failover
-
-❌ **DON'T:**
-- Store large values (> 100KB, use compression or external storage)
-- Use Redis as primary database (it's a cache)
-- Skip error handling
-- Ignore memory limits
-- Hardcode connection strings
-- Use KEYS command in production (use SCAN instead)
-- Store sensitive data without encryption
-- Skip connection retry logic
-- Ignore eviction policies
-- Use blocking operations without timeouts
-
-## Configuration
-
-### Environment Variables
-```bash
-REDIS_URL=redis://localhost:6379
-REDIS_URL=redis://:password@host:6379
-REDIS_URL=rediss://host:6380  # SSL
-REDIS_HOST=localhost
-REDIS_PORT=6379
-REDIS_PASSWORD=securepassword
-```
-
-### Docker Compose
-```yaml
-services:
-  redis:
-    image: redis:7-alpine
-    ports:
-      - "6379:6379"
-    command: redis-server --requirepass securepassword --appendonly yes
-    volumes:
-      - redis_data:/data
-    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-volumes:
-  redis_data:
-```
-
-## Integration with Development
-
-### Testing
-```typescript
-// Use test Redis instance
-const testClient = createClient({
-  url: 'redis://localhost:6380', // Different port for tests
-})
-
-// Clean up after tests
-afterEach(async () => {
-  await testClient.flushDb()
-})
-```
-
-### Health Checks
-```typescript
-async function checkRedisHealth(): Promise<boolean> {
-  try {
-    await client.ping()
-    return true
-  } catch {
-    return false
-  }
-}
-```
-
-<!-- REDIS:END -->
-