moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-platform-railway/modules/networking-domains.md

@@ -0,0 +1,338 @@
+# Networking and Domains Module
+
+Purpose: Private networking configuration, custom domain setup, multi-region deployment, and auto-scaling patterns for Railway applications.
+
+---
+
+## Private Networking
+
+### Internal Service Communication
+
+Railway automatically provisions private domains for inter-service communication:
+- Format: service-name.railway.internal
+- Port: Application's exposed port
+- Protocol: HTTP or TCP
+
+Environment Variable Access:
+```typescript
+// Your service's private domain
+const myDomain = process.env.RAILWAY_PRIVATE_DOMAIN
+// Other service's private domain (set via variable reference)
+const apiDomain = process.env.API_RAILWAY_PRIVATE_DOMAIN
+```
+
+Service Discovery Pattern:
+```typescript
+interface ServiceConfig {
+  name: string
+  port: number
+  healthPath?: string
+}
+
+class ServiceRegistry {
+  private services: Map<string, string> = new Map()
+
+  register(config: ServiceConfig): void {
+    const envKey = `${config.name.toUpperCase().replace(/-/g, '_')}_RAILWAY_PRIVATE_DOMAIN`
+    const domain = process.env[envKey]
+    if (domain) {
+      this.services.set(config.name, `http://${domain}:${config.port}`)
+    }
+  }
+
+  getUrl(serviceName: string): string | undefined {
+    return this.services.get(serviceName)
+  }
+
+  async checkHealth(serviceName: string, healthPath = '/health'): Promise<boolean> {
+    const url = this.getUrl(serviceName)
+    if (!url) return false
+    try {
+      const response = await fetch(`${url}${healthPath}`)
+      return response.ok
+    } catch {
+      return false
+    }
+  }
+}
+
+const registry = new ServiceRegistry()
+registry.register({ name: 'api', port: 3000, healthPath: '/health' })
+registry.register({ name: 'worker', port: 3001 })
+```
+
+---
+
+## Custom Domains
+
+### Domain Configuration Steps
+
+1. Add Domain in Railway Dashboard:
+   - Navigate to service settings
+   - Add custom domain
+   - Copy provided DNS records
+
+2. Configure DNS Records:
+   - CNAME record for subdomains: www.example.com -> railway.app
+   - A record for apex domains: example.com -> Railway IP
+
+3. SSL Certificate:
+   - Automatic provisioning via Let's Encrypt
+   - Usually completes within minutes
+   - Supports wildcard certificates for subdomains
+
+### Multiple Domains
+
+railway.toml configuration:
+```toml
+[deploy]
+healthcheckPath = "/health"
+
+# Primary domain serves all traffic
+# Additional domains configured in dashboard
+```
+
+Domain Routing in Application:
+```typescript
+app.use((req, res, next) => {
+  const host = req.hostname
+
+  if (host === 'api.example.com') {
+    // API-specific middleware
+    return apiRouter(req, res, next)
+  }
+
+  if (host === 'admin.example.com') {
+    // Admin-specific middleware
+    return adminRouter(req, res, next)
+  }
+
+  // Default handling
+  next()
+})
+```
+
+---
+
+## Multi-Region Deployment
+
+### Available Regions
+
+- us-west1: Oregon, USA
+- us-east4: Virginia, USA
+- europe-west4: Netherlands, Europe
+- asia-southeast1: Singapore, Asia
+
+### Region-Specific Deployment
+
+Command Line:
+```bash
+railway up --region us-west1
+railway up --region europe-west4
+```
+
+railway.toml Configuration:
+```toml
+[[deploy.regions]]
+name = "us-west1"
+replicas = 3
+
+[[deploy.regions]]
+name = "europe-west4"
+replicas = 2
+
+[[deploy.regions]]
+name = "asia-southeast1"
+replicas = 2
+```
+
+### Geo-Routing Pattern
+
+```typescript
+import geoip from 'geoip-lite'
+
+const regionEndpoints = {
+  'NA': 'https://us-west1.api.example.com',
+  'EU': 'https://europe-west4.api.example.com',
+  'AS': 'https://asia-southeast1.api.example.com'
+}
+
+function getRegionForIP(ip: string): string {
+  const geo = geoip.lookup(ip)
+  if (!geo) return 'NA'
+
+  const continent = geo.continent
+  if (['EU', 'AF'].includes(continent)) return 'EU'
+  if (['AS', 'OC'].includes(continent)) return 'AS'
+  return 'NA'
+}
+
+app.get('/api/region', (req, res) => {
+  const clientIP = req.ip || req.connection.remoteAddress
+  const region = getRegionForIP(clientIP)
+  res.json({ region, endpoint: regionEndpoints[region] })
+})
+```
+
+### Database Read Replicas
+
+```typescript
+import { Pool } from 'pg'
+
+const primaryPool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 10
+})
+
+const replicaPool = new Pool({
+  connectionString: process.env.DATABASE_REPLICA_URL,
+  max: 20
+})
+
+async function query(sql: string, params?: any[], forceWrite = false) {
+  const isRead = sql.trim().toLowerCase().startsWith('select')
+  const pool = (isRead && !forceWrite) ? replicaPool : primaryPool
+  return pool.query(sql, params)
+}
+
+// Usage
+const users = await query('SELECT * FROM users WHERE active = true')
+const result = await query('INSERT INTO logs (message) VALUES ($1)', ['action'], true)
+```
+
+---
+
+## Auto-Scaling
+
+### Resource-Based Scaling
+
+```toml
+[deploy.scaling]
+minReplicas = 2
+maxReplicas = 10
+targetCPUUtilization = 70
+targetMemoryUtilization = 80
+```
+
+Scale-Up Triggers:
+- CPU usage exceeds targetCPUUtilization
+- Memory usage exceeds targetMemoryUtilization
+- New replica spawned within 30-60 seconds
+
+Scale-Down Behavior:
+- Gradual reduction when metrics normalize
+- Respects minReplicas floor
+- Cooldown period prevents rapid oscillation
+
+### Request-Based Scaling
+
+```toml
+[deploy.scaling]
+minReplicas = 1
+maxReplicas = 20
+targetRequestsPerSecond = 100
+scaleDownDelaySeconds = 300
+```
+
+Request Metrics:
+- Based on incoming HTTP requests
+- More responsive than resource-based scaling
+- Ideal for bursty traffic patterns
+
+### Application Metrics Export
+
+```typescript
+import { register, Counter, Histogram, collectDefaultMetrics } from 'prom-client'
+
+collectDefaultMetrics()
+
+const httpRequests = new Counter({
+  name: 'http_requests_total',
+  help: 'Total HTTP requests',
+  labelNames: ['method', 'path', 'status']
+})
+
+const httpDuration = new Histogram({
+  name: 'http_request_duration_seconds',
+  help: 'HTTP request duration',
+  labelNames: ['method', 'path'],
+  buckets: [0.01, 0.05, 0.1, 0.5, 1, 5]
+})
+
+// Middleware to track metrics
+app.use((req, res, next) => {
+  const start = Date.now()
+  res.on('finish', () => {
+    const duration = (Date.now() - start) / 1000
+    httpRequests.inc({ method: req.method, path: req.path, status: res.statusCode })
+    httpDuration.observe({ method: req.method, path: req.path }, duration)
+  })
+  next()
+})
+
+// Metrics endpoint
+app.get('/metrics', async (req, res) => {
+  res.set('Content-Type', register.contentType)
+  res.end(await register.metrics())
+})
+```
+
+---
+
+## Load Balancing
+
+Railway Load Balancer Features:
+- Automatic distribution across replicas
+- Health-based routing
+- Sticky sessions via cookies (optional)
+- WebSocket support
+
+Sticky Session Configuration:
+```typescript
+import session from 'express-session'
+
+app.use(session({
+  secret: process.env.SESSION_SECRET,
+  resave: false,
+  saveUninitialized: false,
+  cookie: {
+    secure: process.env.NODE_ENV === 'production',
+    maxAge: 24 * 60 * 60 * 1000 // 24 hours
+  }
+}))
+```
+
+WebSocket Connection:
+```typescript
+import { WebSocketServer } from 'ws'
+import { createServer } from 'http'
+
+const server = createServer(app)
+const wss = new WebSocketServer({ server })
+
+wss.on('connection', (ws, req) => {
+  console.log('Client connected from:', req.socket.remoteAddress)
+
+  ws.on('message', (message) => {
+    // Handle message
+  })
+
+  ws.on('close', () => {
+    console.log('Client disconnected')
+  })
+})
+
+server.listen(process.env.PORT || 3000)
+```
+
+---
+
+## Works Well With
+
+- modules/docker-deployment.md: Container configuration
+- modules/multi-service.md: Service architecture
+- moai-platform-vercel: Edge deployment for frontend
+
+---
+
+Version: 1.0.0 | Updated: 2025-12-30

moai_adk/templates/.claude/skills/moai-platform-railway/modules/volumes-storage.md

@@ -0,0 +1,353 @@
+# Volumes and Storage Module
+
+Purpose: Persistent volume configuration, storage patterns, and data management for stateful Railway applications.
+
+---
+
+## Volume Configuration
+
+Basic Volume Definition:
+```toml
+[deploy]
+startCommand = "npm start"
+
+[[volumes]]
+mountPath = "/app/data"
+name = "app-data"
+size = "10Gi"
+```
+
+Multiple Volumes:
+```toml
+[[volumes]]
+mountPath = "/app/data"
+name = "app-data"
+size = "10Gi"
+
+[[volumes]]
+mountPath = "/app/uploads"
+name = "user-uploads"
+size = "50Gi"
+
+[[volumes]]
+mountPath = "/app/cache"
+name = "cache-storage"
+size = "5Gi"
+```
+
+Volume Size Options:
+- 1Gi to 100Gi for standard workloads
+- Size can be increased but not decreased
+- Cost scales with provisioned size
+
+---
+
+## Storage Patterns
+
+### File Storage Service
+
+```typescript
+import { join } from 'path'
+import { existsSync, mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'fs'
+import { readdir, stat } from 'fs/promises'
+
+const VOLUME_PATH = process.env.RAILWAY_VOLUME_MOUNT_PATH || '/app/data'
+
+class PersistentStorage {
+  private basePath: string
+
+  constructor(subdir?: string) {
+    this.basePath = subdir ? join(VOLUME_PATH, subdir) : VOLUME_PATH
+    if (!existsSync(this.basePath)) {
+      mkdirSync(this.basePath, { recursive: true })
+    }
+  }
+
+  write(filename: string, data: Buffer | string): void {
+    const filepath = join(this.basePath, filename)
+    writeFileSync(filepath, data)
+  }
+
+  read(filename: string): Buffer {
+    const filepath = join(this.basePath, filename)
+    return readFileSync(filepath)
+  }
+
+  exists(filename: string): boolean {
+    return existsSync(join(this.basePath, filename))
+  }
+
+  delete(filename: string): void {
+    const filepath = join(this.basePath, filename)
+    if (existsSync(filepath)) {
+      unlinkSync(filepath)
+    }
+  }
+
+  async list(): Promise<string[]> {
+    return readdir(this.basePath)
+  }
+
+  async getSize(filename: string): Promise<number> {
+    const stats = await stat(join(this.basePath, filename))
+    return stats.size
+  }
+}
+
+export const storage = new PersistentStorage()
+export const uploadsStorage = new PersistentStorage('uploads')
+export const cacheStorage = new PersistentStorage('cache')
+```
+
+### Upload Handler
+
+```typescript
+import multer from 'multer'
+import { v4 as uuid } from 'uuid'
+import path from 'path'
+
+const UPLOAD_PATH = process.env.RAILWAY_VOLUME_MOUNT_PATH
+  ? `${process.env.RAILWAY_VOLUME_MOUNT_PATH}/uploads`
+  : '/app/uploads'
+
+const storage = multer.diskStorage({
+  destination: (req, file, cb) => {
+    cb(null, UPLOAD_PATH)
+  },
+  filename: (req, file, cb) => {
+    const ext = path.extname(file.originalname)
+    cb(null, `${uuid()}${ext}`)
+  }
+})
+
+const upload = multer({
+  storage,
+  limits: { fileSize: 10 * 1024 * 1024 }, // 10MB
+  fileFilter: (req, file, cb) => {
+    const allowed = ['image/jpeg', 'image/png', 'image/gif', 'application/pdf']
+    cb(null, allowed.includes(file.mimetype))
+  }
+})
+
+// Route handler
+app.post('/upload', upload.single('file'), (req, res) => {
+  if (!req.file) {
+    return res.status(400).json({ error: 'No file uploaded' })
+  }
+  res.json({
+    filename: req.file.filename,
+    size: req.file.size,
+    mimetype: req.file.mimetype
+  })
+})
+```
+
+### SQLite on Persistent Volume
+
+```typescript
+import Database from 'better-sqlite3'
+import { join } from 'path'
+
+const DB_PATH = process.env.RAILWAY_VOLUME_MOUNT_PATH
+  ? join(process.env.RAILWAY_VOLUME_MOUNT_PATH, 'app.db')
+  : '/app/data/app.db'
+
+const db = new Database(DB_PATH, {
+  verbose: process.env.NODE_ENV === 'development' ? console.log : undefined
+})
+
+// Enable WAL mode for better concurrent access
+db.pragma('journal_mode = WAL')
+db.pragma('synchronous = NORMAL')
+db.pragma('cache_size = -64000') // 64MB cache
+
+// Initialize schema
+db.exec(`
+  CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    email TEXT UNIQUE NOT NULL,
+    name TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  )
+`)
+
+export { db }
+```
+
+---
+
+## Cache Storage Patterns
+
+### Disk-Based Cache
+
+```typescript
+import { join } from 'path'
+import { existsSync, writeFileSync, readFileSync, statSync, unlinkSync } from 'fs'
+import { createHash } from 'crypto'
+
+const CACHE_PATH = process.env.RAILWAY_VOLUME_MOUNT_PATH
+  ? `${process.env.RAILWAY_VOLUME_MOUNT_PATH}/cache`
+  : '/app/cache'
+
+interface CacheEntry<T> {
+  data: T
+  expiresAt: number
+}
+
+class DiskCache {
+  private path: string
+
+  constructor() {
+    this.path = CACHE_PATH
+  }
+
+  private getFilePath(key: string): string {
+    const hash = createHash('md5').update(key).digest('hex')
+    return join(this.path, `${hash}.json`)
+  }
+
+  set<T>(key: string, data: T, ttlSeconds: number = 3600): void {
+    const entry: CacheEntry<T> = {
+      data,
+      expiresAt: Date.now() + ttlSeconds * 1000
+    }
+    writeFileSync(this.getFilePath(key), JSON.stringify(entry))
+  }
+
+  get<T>(key: string): T | null {
+    const filepath = this.getFilePath(key)
+    if (!existsSync(filepath)) return null
+
+    const entry: CacheEntry<T> = JSON.parse(readFileSync(filepath, 'utf-8'))
+    if (Date.now() > entry.expiresAt) {
+      unlinkSync(filepath)
+      return null
+    }
+    return entry.data
+  }
+
+  delete(key: string): void {
+    const filepath = this.getFilePath(key)
+    if (existsSync(filepath)) {
+      unlinkSync(filepath)
+    }
+  }
+}
+
+export const cache = new DiskCache()
+```
+
+---
+
+## Data Backup Patterns
+
+### Scheduled Backup Script
+
+```typescript
+import { exec } from 'child_process'
+import { promisify } from 'util'
+import { createReadStream } from 'fs'
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'
+
+const execAsync = promisify(exec)
+
+const s3 = new S3Client({
+  region: process.env.AWS_REGION,
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!
+  }
+})
+
+async function backupVolume(): Promise<void> {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const backupName = `backup-${timestamp}.tar.gz`
+  const volumePath = process.env.RAILWAY_VOLUME_MOUNT_PATH || '/app/data'
+  const tempPath = `/tmp/${backupName}`
+
+  // Create compressed archive
+  await execAsync(`tar -czf ${tempPath} -C ${volumePath} .`)
+
+  // Upload to S3
+  await s3.send(new PutObjectCommand({
+    Bucket: process.env.BACKUP_BUCKET!,
+    Key: `railway-backups/${backupName}`,
+    Body: createReadStream(tempPath)
+  }))
+
+  // Cleanup
+  await execAsync(`rm ${tempPath}`)
+  console.log(`Backup completed: ${backupName}`)
+}
+
+// Run backup
+backupVolume().catch(console.error)
+```
+
+### Restore Script
+
+```typescript
+import { exec } from 'child_process'
+import { promisify } from 'util'
+import { createWriteStream } from 'fs'
+import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3'
+import { Readable } from 'stream'
+
+const execAsync = promisify(exec)
+
+async function restoreVolume(backupKey: string): Promise<void> {
+  const volumePath = process.env.RAILWAY_VOLUME_MOUNT_PATH || '/app/data'
+  const tempPath = '/tmp/restore.tar.gz'
+
+  // Download from S3
+  const response = await s3.send(new GetObjectCommand({
+    Bucket: process.env.BACKUP_BUCKET!,
+    Key: backupKey
+  }))
+
+  // Write to temp file
+  const stream = response.Body as Readable
+  const writeStream = createWriteStream(tempPath)
+  await new Promise((resolve, reject) => {
+    stream.pipe(writeStream).on('finish', resolve).on('error', reject)
+  })
+
+  // Extract to volume
+  await execAsync(`tar -xzf ${tempPath} -C ${volumePath}`)
+
+  // Cleanup
+  await execAsync(`rm ${tempPath}`)
+  console.log(`Restore completed from: ${backupKey}`)
+}
+```
+
+---
+
+## Volume Considerations
+
+Replica Limitations:
+- Volumes are tied to a single replica
+- numReplicas must be 1 when using volumes
+- For multi-replica deployments, use external storage (S3, R2)
+
+Performance Characteristics:
+- SSD-backed storage
+- Low latency for local reads/writes
+- Size can be increased dynamically
+- Data persists across deployments
+
+Volume vs External Storage Decision:
+- Use volumes for: SQLite, local caches, temporary processing
+- Use external storage for: User uploads, shared assets, large files
+
+---
+
+## Works Well With
+
+- modules/docker-deployment.md: Container configuration
+- modules/multi-service.md: Shared storage patterns
+- moai-domain-database: Database storage patterns
+
+---
+
+Version: 1.0.0 | Updated: 2025-12-30