Crate iron_control_api

Crate iron_control_api 

Source
Expand description

REST API and WebSocket server for Iron Runtime dashboard.

Provides HTTP/REST endpoints and WebSocket connections for real-time communication between the Rust runtime and web-based management dashboard. Handles authentication, authorization, and structured API responses.

§Purpose

This crate implements the control plane API for Iron Runtime:

  • REST endpoints for agent management, analytics, and configuration
  • WebSocket connections for real-time event streaming
  • JWT-based authentication and RBAC authorization
  • Structured error responses and request validation
  • CORS support for browser-based dashboards

§Architecture

The API follows a layered architecture:

  1. Transport Layer: Axum web framework with HTTP/1.1, HTTP/2, and WebSocket support
  2. Authentication Layer: JWT validation, token auth, and user sessions
  3. Authorization Layer: Role-based access control (RBAC)
  4. Route Layer: RESTful endpoints organized by resource domain
  5. State Layer: Shared access to runtime state via StateManager

All layers use async/await with Tokio runtime for concurrent request handling.

§Key Types

  • ApiServer - Main server managing lifecycle and routing
  • ApiState - Shared state accessible to all handlers
  • jwt_auth - JWT token validation and claims
  • rbac - Role-based access control
  • error - Structured API error responses

§Public API

§Server Setup

use iron_control_api::ApiServer;
use iron_runtime_state::StateManager;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
  let state_manager = Arc::new(StateManager::new());
  let server = ApiServer::new(state_manager, 8080);

  // Blocks until server shutdown
  server.start().await?;
  Ok(())
}

§REST Endpoints

§Agent Management

GET  /api/agents/:id/status   - Get agent status
POST /api/agents/:id/stop     - Stop agent
GET  /api/agents/:id/metrics  - Get agent metrics

§Analytics & Usage

GET /api/analytics           - Get aggregated stats
GET /api/usage               - Get usage metrics

§Budget & Limits

GET  /api/budget             - Get budget status
POST /api/budget/reserve     - Reserve budget
GET  /api/limits             - Get rate limits

§Configuration

GET /api/providers           - List LLM providers
GET /api/keys                - List API keys
GET /api/tokens              - List tokens

§Authentication

POST /api/auth/login         - User login
POST /api/auth/refresh       - Refresh JWT token
GET  /api/auth/verify        - Verify token

§Health & Status

GET /api/health              - Health check

§WebSocket Events

WS /ws                       - Real-time event stream

Events streamed to connected clients:

  • Agent state changes (started, stopped, failed)
  • Budget threshold alerts
  • PII detection events
  • Request completion/failure

§Feature Flags

  • enabled - Enable API server (disabled for runtime-only builds)

§Authentication

The API supports multiple authentication mechanisms:

§JWT Tokens (User Sessions)

Authorization: Bearer <jwt_token>

Used for dashboard user sessions. Tokens include user ID and role claims.

§API Tokens (Service Auth)

X-API-Token: at_550e8400-e29b-41d4-a716-446655440000

Used for programmatic API access. Tokens scoped to specific resources.

§IC Tokens (Internal Auth)

X-IC-Token: ic_550e8400-e29b-41d4-a716-446655440000

Used for runtime-to-runtime communication.

§Authorization

RBAC enforces role-based permissions:

  • Admin: Full access to all endpoints
  • User: Read access to own resources, limited write
  • Viewer: Read-only access to non-sensitive data

§Error Handling

All errors return structured JSON:

{
  "error": "Budget exceeded",
  "code": "BUDGET_EXCEEDED",
  "details": {
    "spent": 105.50,
    "limit": 100.00
  }
}

HTTP status codes follow REST conventions:

  • 200: Success
  • 400: Bad request (validation error)
  • 401: Unauthorized (missing/invalid auth)
  • 403: Forbidden (insufficient permissions)
  • 404: Not found
  • 500: Internal server error

Modules§

error
Custom error types and JSON error responses for API
ic_token
Protocol 005: Budget Control Protocol
ip_token
IP Token (Iron Provider Token) encryption
jwt_auth
JWT authentication middleware
middleware
Middleware modules for Iron Control API
rate_limiter
In-memory rate limiter for login endpoint
rbac
RBAC (Role-Based Access Control) module
routes
REST API route handlers
token_auth
API Token authentication middleware
user_auth
User authentication and password verification

Structs§

ApiServer
API server
ApiState
API server state