REST API

REST API — Ruflo V2 Swarm Coordination API

Comprehensive REST API layer for the Ruflo swarm coordination system, providing authentication, database access, Claude AI client integration, and full swarm lifecycle management via Express.js endpoints.

Purpose

Serves as the primary HTTP interface for managing swarms, agents, tasks, and metrics. Combines four core services: AuthService (JWT + API key auth), DatabaseService (multi-engine persistence), ClaudeAPIClient (AI model integration), and SwarmApi (coordination endpoints).

Source Location

/tmp/ruflo/v2/src/api/

Core Services

AuthService (auth-service.ts)

Handles authentication and role-based access control.

User Roles:

• admin -- Full system access (all 14 permissions)
• operator -- Manage swarms and agents (12 permissions)
• developer -- Create and monitor tasks (7 permissions)
• viewer -- Read-only access (5 permissions)
• service -- Service-to-service authentication (api.access only)

Permissions System:

• swarm.create, swarm.read, swarm.update, swarm.delete, swarm.scale
• agent.spawn, agent.read, agent.terminate
• task.create, task.read, task.cancel
• metrics.read, system.admin, api.access

Authentication Methods:

• JWT tokens with configurable expiry (default: 24h)
• API keys with HMAC-SHA256 hashing and constant-time comparison
• Session management with client info tracking (user agent, IP, device)
• Rate limiting: max 5 failed attempts, 15-minute lockout

Commands:

POST /auth/login          -- Authenticate with email + password
POST /auth/api-key        -- Authenticate with API key
POST /auth/verify         -- Verify JWT token
POST /auth/users          -- Create new user (admin only)
POST /auth/api-keys       -- Generate API key for user
DELETE /auth/api-keys/:id -- Revoke API key
DELETE /auth/sessions/:id -- Invalidate session

DatabaseService (database-service.ts)

Multi-engine database abstraction supporting SQLite, MySQL, and PostgreSQL.

Record Types:

• SwarmRecord -- Swarm instances with topology, strategy, and status
• AgentRecord -- Agent lifecycle with capabilities and metadata
• TaskRecord -- Task orchestration with priority and strategy
• MetricRecord -- Time-series metrics for monitoring
• EventRecord -- Audit trail with severity levels

Configuration:

{
  type: 'sqlite' | 'mysql' | 'postgresql',
  database: string,
  host?: string,
  port?: number,
  poolSize?: number,
  timeout?: number,
  retryAttempts?: number
}

ClaudeAPIClient (claude-client.ts)

Direct integration with the Claude API featuring circuit breaker pattern, health checks, and streaming support.

Supported Models:

• claude-3-opus-20240229
• claude-3-sonnet-20240229
• claude-3-haiku-20240307
• claude-2.1, claude-2.0, claude-instant-1.2

Features:

• Streaming via SSE (Server-Sent Events)
• Circuit breaker with configurable threshold and reset timeout
• Retry with exponential backoff and jitter
• Structured error hierarchy: ClaudeRateLimitError, ClaudeTimeoutError, ClaudeNetworkError, ClaudeAuthenticationError, ClaudeValidationError

SwarmApi (swarm-api.ts)

Express router providing RESTful endpoints for swarm coordination.

Endpoints:

POST   /swarms                -- Create swarm (topology: hierarchical|mesh|ring|star)
GET    /swarms                -- List all swarms
GET    /swarms/:id            -- Get swarm details
DELETE /swarms/:id            -- Destroy swarm
POST   /swarms/:id/agents     -- Spawn agent in swarm
GET    /swarms/:id/agents     -- List agents
POST   /swarms/:id/tasks      -- Orchestrate task
GET    /swarms/:id/tasks      -- List tasks
GET    /swarms/:id/metrics    -- Get swarm metrics

Configuration:

{
  rateLimit: { windowMs: number, maxRequests: number },
  authentication: { enabled: boolean, apiKeys?: string[], jwtSecret?: string },
  cors: { origins: string[], methods: string[] },
  swagger: { enabled: boolean, title: string, version: string }
}

Error Handling

All endpoints return structured JSON errors:

{
  "error": "Human-readable message",
  "code": "VALIDATION_ERROR | SWARM_ERROR | AUTH_ERROR",
  "details": {}
}

HTTP status mapping: 400 (ValidationError), 401 (AuthenticationError), 409 (SwarmError), 500 (internal).

Implementation Details

• Express.js middleware chain: logging, body validation, auth, route handler, error handler
• Request logging captures method, path, IP, and User-Agent
• All API keys stored as HMAC-SHA256 hashes, never plaintext
• Session cleanup runs periodically to remove expired entries
• Database supports automatic migration on initialization