motia 0.5.11-beta.120-011950 → 0.5.11-beta.120-356715

package/dist/dot-files/.cursor/rules/production-deployment.mdc

@@ -0,0 +1,668 @@
+---
+description: Production deployment patterns and DevOps best practices for Motia applications
+globs: 
+alwaysApply: false
+---
+# Production Deployment Patterns
+
+Deploy robust, scalable Motia applications to production environments with confidence.
+
+## Environment Configuration
+
+### Environment Variables
+
+```bash
+# .env.example
+# Application
+NODE_ENV=production
+PORT=3000
+APP_NAME=my-motia-app
+
+# Authentication
+JWT_SECRET=your-super-secure-jwt-secret-here
+JWT_EXPIRES_IN=15m
+REFRESH_TOKEN_EXPIRES_IN=30d
+BCRYPT_ROUNDS=12
+
+# Database
+DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
+REDIS_URL=redis://localhost:6379
+
+# External Services
+OPENAI_API_KEY=sk-...
+SENDGRID_API_KEY=SG...
+AWS_ACCESS_KEY_ID=AKIA...
+AWS_SECRET_ACCESS_KEY=...
+AWS_S3_BUCKET=my-app-storage
+AWS_REGION=us-east-1
+
+# Monitoring
+SENTRY_DSN=https://...@sentry.io/...
+LOG_LEVEL=info
+
+# Rate Limiting
+RATE_LIMIT_WINDOW_MS=900000
+RATE_LIMIT_MAX_REQUESTS=100
+```
+
+### Configuration Management
+
+```typescript
+// config/environment.ts
+import { z } from 'zod'
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'staging', 'production']).default('development'),
+  PORT: z.coerce.number().default(3000),
+  APP_NAME: z.string().default('motia-app'),
+  
+  // Authentication
+  JWT_SECRET: z.string().min(32),
+  JWT_EXPIRES_IN: z.string().default('15m'),
+  REFRESH_TOKEN_EXPIRES_IN: z.string().default('30d'),
+  BCRYPT_ROUNDS: z.coerce.number().default(12),
+  
+  // Database
+  DATABASE_URL: z.string().url().optional(),
+  REDIS_URL: z.string().url().optional(),
+  
+  // External Services
+  OPENAI_API_KEY: z.string().optional(),
+  SENDGRID_API_KEY: z.string().optional(),
+  
+  // AWS
+  AWS_ACCESS_KEY_ID: z.string().optional(),
+  AWS_SECRET_ACCESS_KEY: z.string().optional(),
+  AWS_S3_BUCKET: z.string().optional(),
+  AWS_REGION: z.string().default('us-east-1'),
+  
+  // Monitoring
+  SENTRY_DSN: z.string().url().optional(),
+  LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug']).default('info'),
+  
+  // Rate Limiting
+  RATE_LIMIT_WINDOW_MS: z.coerce.number().default(900000),
+  RATE_LIMIT_MAX_REQUESTS: z.coerce.number().default(100)
+})
+
+export type Environment = z.infer<typeof envSchema>
+
+export const env = envSchema.parse(process.env)
+
+export const isDevelopment = env.NODE_ENV === 'development'
+export const isProduction = env.NODE_ENV === 'production'
+export const isStaging = env.NODE_ENV === 'staging'
+```
+
+## Docker Configuration
+
+```dockerfile
+# Dockerfile
+FROM node:18-alpine AS base
+
+# Install Python for multi-language support
+RUN apk add --no-cache python3 py3-pip build-base
+
+# Install pnpm
+RUN npm install -g pnpm
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json pnpm-lock.yaml ./
+COPY requirements.txt ./
+
+# Install dependencies
+RUN pnpm install --frozen-lockfile --production
+RUN pip3 install -r requirements.txt
+
+# Copy source code
+COPY . .
+
+# Build if necessary
+RUN pnpm build || true
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs
+RUN adduser -S motia -u 1001
+
+# Change ownership
+RUN chown -R motia:nodejs /app
+USER motia
+
+# Expose port
+EXPOSE 3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD curl -f http://localhost:3000/health || exit 1
+
+# Start application
+CMD ["pnpm", "start"]
+```
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_URL=postgresql://postgres:password@db:5432/motia_prod
+      - REDIS_URL=redis://redis:6379
+    depends_on:
+      - db
+      - redis
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  db:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_DB: motia_prod
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: password
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    command: redis-server --appendonly yes
+    volumes:
+      - redis_data:/data
+    ports:
+      - "6379:6379"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+volumes:
+  postgres_data:
+  redis_data:
+```
+
+## Health Checks & Monitoring
+
+```typescript
+// steps/monitoring/health-check.step.ts
+import { ApiRouteConfig, Handlers } from 'motia'
+import { z } from 'zod'
+
+export const config: ApiRouteConfig = {
+  type: 'api',
+  name: 'HealthCheck',
+  description: 'Application health check endpoint',
+  method: 'GET',
+  path: '/health',
+  responseSchema: {
+    200: z.object({
+      status: z.string(),
+      timestamp: z.string(),
+      uptime: z.number(),
+      version: z.string(),
+      environment: z.string(),
+      services: z.record(z.object({
+        status: z.enum(['healthy', 'unhealthy', 'degraded']),
+        responseTime: z.number().optional(),
+        error: z.string().optional()
+      }))
+    }),
+    503: z.object({
+      status: z.string(),
+      error: z.string()
+    })
+  },
+  emits: [],
+  flows: ['monitoring']
+}
+
+export const handler: Handlers['HealthCheck'] = async (req, { logger, state }) => {
+  try {
+    const startTime = Date.now()
+    const services: Record<string, any> = {}
+    
+    // Check database connectivity
+    try {
+      const dbStart = Date.now()
+      await state.get('health', 'db-check')
+      services.database = {
+        status: 'healthy',
+        responseTime: Date.now() - dbStart
+      }
+    } catch (error) {
+      services.database = {
+        status: 'unhealthy',
+        error: error.message
+      }
+    }
+    
+    // Check Redis connectivity
+    try {
+      const redisStart = Date.now()
+      await checkRedisHealth()
+      services.redis = {
+        status: 'healthy',
+        responseTime: Date.now() - redisStart
+      }
+    } catch (error) {
+      services.redis = {
+        status: 'unhealthy',
+        error: error.message
+      }
+    }
+    
+    // Check external services
+    services.openai = await checkOpenAIHealth()
+    services.email = await checkEmailServiceHealth()
+    
+    const allHealthy = Object.values(services).every(
+      (service: any) => service.status === 'healthy'
+    )
+    
+    const healthStatus = {
+      status: allHealthy ? 'healthy' : 'degraded',
+      timestamp: new Date().toISOString(),
+      uptime: process.uptime(),
+      version: process.env.npm_package_version || '1.0.0',
+      environment: process.env.NODE_ENV || 'unknown',
+      services
+    }
+    
+    if (!allHealthy) {
+      logger.warn('Health check showing degraded status', { services })
+    }
+    
+    return {
+      status: allHealthy ? 200 : 503,
+      body: healthStatus
+    }
+  } catch (error) {
+    logger.error('Health check failed', { error: error.message })
+    return {
+      status: 503,
+      body: {
+        status: 'unhealthy',
+        error: error.message
+      }
+    }
+  }
+}
+
+async function checkRedisHealth(): Promise<void> {
+  // Implement Redis health check
+  // Could use ioredis client to ping Redis
+}
+
+async function checkOpenAIHealth() {
+  try {
+    // Simple OpenAI API check
+    const response = await fetch('https://api.openai.com/v1/models', {
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
+      },
+      signal: AbortSignal.timeout(5000)
+    })
+    
+    return {
+      status: response.ok ? 'healthy' : 'unhealthy',
+      responseTime: Date.now()
+    }
+  } catch {
+    return { status: 'unhealthy', error: 'OpenAI API unavailable' }
+  }
+}
+
+async function checkEmailServiceHealth() {
+  // Implement email service health check
+  return { status: 'healthy' }
+}
+```
+
+## Production State Configuration
+
+```yaml
+# config.yml
+state:
+  adapter: redis
+  host: ${REDIS_HOST:-localhost}
+  port: ${REDIS_PORT:-6379}
+  password: ${REDIS_PASSWORD}
+  db: ${REDIS_DB:-0}
+  ttl: ${STATE_TTL:-3600}
+  keyPrefix: ${APP_NAME:-motia}:state:
+
+# Logging configuration
+logging:
+  level: ${LOG_LEVEL:-info}
+  format: json
+  destination: stdout
+  
+# Security settings  
+security:
+  rateLimit:
+    windowMs: ${RATE_LIMIT_WINDOW_MS:-900000}
+    max: ${RATE_LIMIT_MAX_REQUESTS:-100}
+  cors:
+    origin: ${CORS_ORIGIN:-*}
+    credentials: true
+  helmet:
+    contentSecurityPolicy: true
+    hsts: true
+```
+
+## CI/CD Pipeline
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy to Production
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  NODE_VERSION: '18'
+  PYTHON_VERSION: '3.11'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: test_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+          
+      redis:
+        image: redis:7
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'pnpm'
+          
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: 'pip'
+          
+      - name: Install dependencies
+        run: |
+          npm install -g pnpm
+          pnpm install
+          pip install -r requirements.txt
+          
+      - name: Run linting
+        run: |
+          pnpm lint
+          
+      - name: Run tests
+        env:
+          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test_db
+          REDIS_URL: redis://localhost:6379
+          JWT_SECRET: test-secret-key-for-testing-only
+        run: |
+          pnpm test
+          
+      - name: Build application
+        run: |
+          pnpm build
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: test
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Deploy to production
+        env:
+          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+          PRODUCTION_HOST: ${{ secrets.PRODUCTION_HOST }}
+        run: |
+          # Deploy using your preferred method
+          # This could be Docker deployment, Kubernetes, or cloud services
+          echo "Deploying to production..."
+```
+
+## Performance Optimization
+
+```typescript
+// steps/middleware/performance.ts
+import { ApiMiddleware } from 'motia'
+import compression from 'compression'
+import helmet from 'helmet'
+
+// Compression middleware
+export const compressionMiddleware: ApiMiddleware = async (req, ctx, next) => {
+  // Add compression for responses > 1KB
+  const response = await next()
+  
+  if (response.body && typeof response.body === 'object') {
+    const bodySize = JSON.stringify(response.body).length
+    if (bodySize > 1024) {
+      response.headers = {
+        ...response.headers,
+        'Content-Encoding': 'gzip'
+      }
+    }
+  }
+  
+  return response
+}
+
+// Security headers middleware
+export const securityMiddleware: ApiMiddleware = async (req, ctx, next) => {
+  const response = await next()
+  
+  return {
+    ...response,
+    headers: {
+      ...response.headers,
+      'X-Content-Type-Options': 'nosniff',
+      'X-Frame-Options': 'DENY',
+      'X-XSS-Protection': '1; mode=block',
+      'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
+      'Referrer-Policy': 'strict-origin-when-cross-origin'
+    }
+  }
+}
+
+// Request timing middleware
+export const timingMiddleware: ApiMiddleware = async (req, ctx, next) => {
+  const start = Date.now()
+  
+  const response = await next()
+  
+  const duration = Date.now() - start
+  
+  ctx.logger.info('Request completed', {
+    method: req.method || 'unknown',
+    path: req.path,
+    duration,
+    status: response.status
+  })
+  
+  return {
+    ...response,
+    headers: {
+      ...response.headers,
+      'X-Response-Time': `${duration}ms`
+    }
+  }
+}
+```
+
+## Error Handling & Logging
+
+```typescript
+// steps/middleware/error-handling.ts
+import { ApiMiddleware } from 'motia'
+import { env } from '../config/environment'
+
+export const errorHandlingMiddleware: ApiMiddleware = async (req, ctx, next) => {
+  try {
+    return await next()
+  } catch (error) {
+    ctx.logger.error('Unhandled error in API route', {
+      error: error.message,
+      stack: error.stack,
+      method: req.method,
+      path: req.path,
+      userId: req.user?.userId
+    })
+    
+    // Don't expose internal errors in production
+    const message = env.NODE_ENV === 'production' 
+      ? 'Internal server error'
+      : error.message
+    
+    return {
+      status: 500,
+      body: { error: message }
+    }
+  }
+}
+```
+
+## Monitoring & Alerting
+
+```typescript
+// steps/cron/system-monitoring.step.ts
+import { CronConfig, Handlers } from 'motia'
+
+export const config: CronConfig = {
+  type: 'cron',
+  name: 'SystemMonitoring',
+  description: 'Monitor system metrics and send alerts',
+  cron: '*/5 * * * *', // Every 5 minutes
+  emits: ['alert.system', 'metrics.collected'],
+  flows: ['monitoring']
+}
+
+export const handler: Handlers['SystemMonitoring'] = async ({ emit, logger, state }) => {
+  try {
+    const metrics = await collectSystemMetrics()
+    
+    // Store metrics
+    await state.set('metrics', new Date().toISOString(), metrics)
+    
+    // Check thresholds and send alerts
+    const alerts = checkAlertThresholds(metrics)
+    
+    for (const alert of alerts) {
+      await emit({
+        topic: 'alert.system',
+        data: {
+          severity: alert.severity,
+          metric: alert.metric,
+          value: alert.value,
+          threshold: alert.threshold,
+          timestamp: new Date().toISOString()
+        }
+      })
+    }
+    
+    await emit({
+      topic: 'metrics.collected',
+      data: metrics
+    })
+    
+    logger.info('System metrics collected', { 
+      alertCount: alerts.length,
+      metrics: Object.keys(metrics)
+    })
+    
+  } catch (error) {
+    logger.error('System monitoring failed', { error: error.message })
+  }
+}
+
+async function collectSystemMetrics() {
+  return {
+    memory: {
+      used: process.memoryUsage().heapUsed,
+      total: process.memoryUsage().heapTotal,
+      percentage: (process.memoryUsage().heapUsed / process.memoryUsage().heapTotal) * 100
+    },
+    cpu: {
+      usage: process.cpuUsage()
+    },
+    uptime: process.uptime(),
+    activeConnections: await getActiveConnectionCount(),
+    responseTime: await measureAverageResponseTime()
+  }
+}
+
+function checkAlertThresholds(metrics: any) {
+  const alerts = []
+  
+  if (metrics.memory.percentage > 85) {
+    alerts.push({
+      severity: 'warning',
+      metric: 'memory_usage',
+      value: metrics.memory.percentage,
+      threshold: 85
+    })
+  }
+  
+  if (metrics.memory.percentage > 95) {
+    alerts.push({
+      severity: 'critical', 
+      metric: 'memory_usage',
+      value: metrics.memory.percentage,
+      threshold: 95
+    })
+  }
+  
+  return alerts
+}
+```
+
+This production deployment setup provides:
+- Comprehensive environment configuration
+- Docker containerization
+- Health checks and monitoring
+- CI/CD pipeline
+- Performance optimization
+- Security best practices
+- Error handling and logging
+- System monitoring and alerting