Routes

This page documents the API route modules in fusion/api/routes/.

runs.py - Simulation Runs

Location:: fusion/api/routes/runs.py
Prefix:: /api/runs
Tag:: runs

Provides CRUD operations for simulation runs and real-time streaming.

Endpoints

POST /api/runs

Create and start a new simulation run.

# Request body
{
    "run_id": "my_simulation",       # Optional custom ID
    "name": "Test Run",              # Optional display name
    "template": "minimal.ini",       # Config template name
    "config_overrides": {            # Optional INI overrides
        "general_settings": {
            "num_requests": "1000"
        }
    }
}

# Response (201 Created)
{
    "id": "abc123def456",
    "name": "Test Run",
    "status": "PENDING",
    "template": "minimal.ini",
    "created_at": "2024-01-15T10:30:00Z",
    ...
}

GET /api/runs

List all runs with optional filtering and pagination.

Query parameters:

status - Filter by status (comma-separated: RUNNING,COMPLETED)
limit - Maximum results (default: 50, max: 100)
offset - Pagination offset (default: 0)

GET /api/runs/{run_id}

Get details for a specific run including progress information.

DELETE /api/runs/{run_id}

Cancel a running job (sends SIGTERM to process group) or delete a completed run.

GET /api/runs/{run_id}/logs

Stream log output via Server-Sent Events.

Query parameters:

from_start - Whether to send existing log content (default: true)

Event format:

event: log
data: {"line": "INFO: Starting simulation..."}

event: log
data: {"line": "INFO: Processing request 1/1000"}

event: done
data: {}

GET /api/runs/{run_id}/progress

Stream progress updates via Server-Sent Events.

Event format:

event: progress
data: {"current_erlang": 300.0, "total_erlangs": 3, "current_iteration": 1, "total_iterations": 2}

event: done
data: {}

configs.py - Configuration Templates

Location:: fusion/api/routes/configs.py
Prefix:: /api/configs
Tag:: configs

Provides access to INI configuration templates.

Endpoints

GET /api/configs/templates

List available configuration templates from fusion/configs/templates/.

# Response
{
    "templates": [
        {
            "name": "minimal.ini",
            "path": "fusion/configs/templates/minimal.ini",
            "description": "Minimal configuration for quick tests"
        },
        ...
    ]
}

GET /api/configs/templates/{name}

Get the content of a specific template.

# Response
{
    "name": "minimal.ini",
    "content": "[general_settings]\nnetwork = NSFNet\n..."
}

topology.py - Network Topology

Location:: fusion/api/routes/topology.py
Prefix:: /api/topology
Tag:: topology

Provides network topology data for visualization.

Endpoints

GET /api/topology

List available topologies.

# Response
{
    "topologies": ["NSFNet", "USbackbone60", "COST239", ...]
}

GET /api/topology/{name}

Get topology data with computed node positions.

# Response
{
    "name": "NSFNet",
    "nodes": [
        {"id": 0, "label": "0", "x": 100.5, "y": 200.3},
        {"id": 1, "label": "1", "x": 150.2, "y": 180.7},
        ...
    ],
    "links": [
        {"source": 0, "target": 1, "weight": 1.0},
        {"source": 0, "target": 2, "weight": 1.0},
        ...
    ],
    "metadata": {
        "num_nodes": 14,
        "num_links": 21
    }
}

Node positions are computed using a spring layout algorithm (NetworkX) and cached.

codebase.py - Codebase Explorer

Location:: fusion/api/routes/codebase.py
Prefix:: /api/codebase
Tag:: codebase

Provides codebase browsing and search functionality.

Endpoints

GET /api/codebase/tree

Get the directory tree structure for the FUSION codebase.

Query parameters:

path - Subdirectory to start from (default: project root)
depth - Maximum recursion depth (default: 3)

# Response
{
    "name": "fusion",
    "type": "directory",
    "children": [
        {
            "name": "core",
            "type": "directory",
            "children": [...]
        },
        {
            "name": "__init__.py",
            "type": "file",
            "size": 1234
        },
        ...
    ]
}

GET /api/codebase/file

Get the content of a specific file.

Query parameters:

path - File path relative to project root (required)

# Response
{
    "path": "fusion/core/simulation.py",
    "content": "\"\"\"Simulation engine...",
    "language": "python",
    "size": 15000
}

GET /api/codebase/search

Search for files by name pattern.

Query parameters:

query - Search pattern (required)
limit - Maximum results (default: 20)

# Response
{
    "results": [
        {"path": "fusion/core/simulation.py", "type": "file"},
        {"path": "fusion/sim/simulation_engine.py", "type": "file"},
        ...
    ],
    "total": 5
}

GET /api/codebase/modules

Get high-level module descriptions for the architecture view.

# Response
{
    "modules": [
        {
            "name": "core",
            "description": "Simulation engine and orchestrator",
            "path": "fusion/core",
            "key_files": ["simulation.py", "orchestrator.py"]
        },
        ...
    ]
}

artifacts.py - Run Artifacts

Location:: fusion/api/routes/artifacts.py
Prefix:: /api
Tag:: artifacts

Provides access to simulation output files.

Endpoints

GET /api/runs/{run_id}/artifacts

List output files for a completed run.

# Response
{
    "artifacts": [
        {
            "name": "erlang_results.json",
            "path": "data/output/NSFNet/my_run/erlang_results.json",
            "size": 4096,
            "modified": "2024-01-15T10:45:00Z"
        },
        ...
    ]
}

GET /api/runs/{run_id}/artifacts/{path:path}

Download a specific artifact file. Returns the file with appropriate MIME type.

system.py - System Endpoints

Location:: fusion/api/routes/system.py
Prefix:: /api
Tag:: system

System-level endpoints for health checks and monitoring.

Endpoints

GET /api/health

Health check endpoint for monitoring and load balancers.

# Response
{
    "status": "healthy",
    "version": "1.0.0",
    "database": "connected"
}