flowfram-runtime

Distributed runtime execution engine for FlowFRAM simulations.

Installation

# Global installation (recommended for CLI usage)
npm install -g flowfram-runtime

# Or with yarn
yarn global add flowfram-runtime

# Or with pnpm
pnpm add -g flowfram-runtime

Usage

CLI

# Start with default settings (port 3001)
flowfram-runtime

# Start on custom port
flowfram-runtime --port 8080

# Show help
flowfram-runtime --help

# Show version
flowfram-runtime --version

Environment Variables

PORT=3001              # Server port
HOST=0.0.0.0           # Server host
LOG_LEVEL=info         # Logging level (debug, info, warn, error)
RUNTIME_DATA_DIR=./data # Directory for persisted flows

Features

• REST API for flow deployment, stop, and inject operations
• Batch execution mode for programmatic experiment validation
• Server-Sent Events (SSE) for real-time event streaming
• 35+ node types implemented
• MQTT In/Out with external broker support
• HTTP Request node
• Database nodes: PostgreSQL, MySQL, MSSQL
• State persistence (survives restarts)
• Multi-tenant isolation
• Automatic flow restoration on startup

Docker

# Build and run with Docker Compose
docker-compose up -d

# With MQTT broker (optional)
docker-compose --profile mqtt up -d

# View logs
docker-compose logs -f runtime-service

# Stop
docker-compose down

Docker Build Only

# Build image
docker build -t flowfram-runtime .

# Run container
docker run -d -p 3001:3001 --name flowfram-runtime flowfram-runtime

API Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /deploy | Deploy a flow | | POST | /stop | Stop a running flow | | POST | /flows/:flowId/stop | Stop a specific flow | | POST | /inject | Execute an inject node | | POST | /batch-run | Execute N iterations (for experiments) | | POST | /config | Update runtime configuration | | POST | /context/clear | Clear runtime context | | POST | /setInstantiation | Set instantiation mode | | GET | /status | Get runtime status | | GET | /flows | List deployed flows | | GET | /events?flowId=xxx | SSE event stream | | GET | /health | Health check |

Configuration

Environment variables:

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3001 | Server port | | RUNTIME_DATA_DIR | ./data | Directory for persisted flows |

Supported Nodes

| Category | Nodes | |----------|-------| | Core | inject, debug, function, change, switch, template, delay | | Network | http-request, mqtt-in, mqtt-out | | Database | postgresql, mysql, mssql | | Parser | json, csv, csv-parse, xml, html | | Sequence | split, join, sort, batch | | Function | range, rbe, trigger | | Control | catch, status, complete | | FRAM | resonance, resonance-indicator, coupling-matrix | | Output | chart-output, table-output | | Visual | comment |

Architecture

┌─────────────────────────────────────────────────────────┐
│  Runtime Service (Port 3001)                            │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Express REST API                                 │  │
│  │  - POST /deploy, /stop, /inject, /batch-run       │  │
│  │  - GET /status, /flows, /events, /health           │  │
│  └───────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────┐  │
│  │  ServerFlowRuntime                                │  │
│  │  - Node execution engine (35+ types)              │  │
│  │  - Message routing                                │  │
│  │  - Context management                             │  │
│  └───────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Persistence Layer                                │  │
│  │  - Saves deployed flows to disk                   │  │
│  │  - Restores flows on startup                      │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

License

MIT