Skip to content

Latest commit

 

History

History
269 lines (217 loc) · 8.03 KB

api-reference.md

File metadata and controls

269 lines (217 loc) · 8.03 KB

API Reference

Complete API reference for Reflow components and systems.

Core APIs

Graph API

Actor API

Network API

Messaging API

Runtime APIs

JavaScript/Deno Runtime

Python Runtime

WebAssembly Runtime

Component APIs

Standard Library

Data Operations

Flow Control

Configuration Reference

Runtime Configuration

[runtime]
thread_pool_size = 8      # Number of worker threads
log_level = "info"        # Logging level: trace, debug, info, warn, error
hot_reload = false        # Enable hot reloading in development

[memory]
max_heap_size = "1GB"     # Maximum heap size
gc_frequency = 100        # Garbage collection frequency

Network Configuration

[network]
max_connections = 1000    # Maximum concurrent connections
timeout_ms = 5000        # Connection timeout in milliseconds
buffer_size = 8192       # Message buffer size

[websocket]
enable = true            # Enable WebSocket support
port = 8080             # WebSocket port
max_frame_size = 65536  # Maximum frame size

Script Configuration

[scripts.deno]
enable = true
allow_net = false        # Network access permission
allow_read = true        # File read permission
allow_write = false      # File write permission

[scripts.python]
enable = true
virtual_env = "venv"     # Virtual environment path
requirements = "requirements.txt"

[scripts.wasm]
enable = true
max_memory = "64MB"      # Maximum WASM memory
stack_size = "1MB"       # Stack size

Error Codes

Runtime Errors

  • E001 - Actor initialization failed
  • E002 - Message routing error
  • E003 - Network connection failed
  • E004 - Script execution error
  • E005 - Memory allocation failed

Graph Errors

  • G001 - Invalid graph structure
  • G002 - Cycle detected in graph
  • G003 - Port type mismatch
  • G004 - Orphaned node detected
  • G005 - Invalid connection

Component Errors

  • C001 - Component not found
  • C002 - Invalid component configuration
  • C003 - Component lifecycle error
  • C004 - Port compatibility error
  • C005 - Component execution timeout

Type Definitions

Core Types

// Graph types
pub struct Graph {
    pub name: String,
    pub directed: bool,
    pub metadata: HashMap<String, Value>,
}

pub struct GraphNode {
    pub id: String,
    pub component: String,
    pub metadata: HashMap<String, Value>,
}

pub struct GraphConnection {
    pub from_node: String,
    pub from_port: String,
    pub to_node: String,
    pub to_port: String,
    pub metadata: Option<HashMap<String, Value>>,
}

// Message types
pub enum Message {
    Null,
    Boolean(bool),
    Integer(i64),
    Float(f64),
    String(String),
    Array(Vec<Message>),
    Object(HashMap<String, Message>),
    Binary(Vec<u8>),
}

// Actor types
pub trait Actor: Send + Sync {
    fn process(&mut self, inputs: HashMap<String, Message>) -> Result<HashMap<String, Message>, ActorError>;
    fn get_input_ports(&self) -> Vec<PortDefinition>;
    fn get_output_ports(&self) -> Vec<PortDefinition>;
}

Configuration Types

pub struct RuntimeConfig {
    pub thread_pool_size: usize,
    pub log_level: String,
    pub hot_reload: bool,
}

pub struct NetworkConfig {
    pub max_connections: usize,
    pub timeout_ms: u64,
    pub buffer_size: usize,
}

pub struct ScriptConfig {
    pub runtime: ScriptRuntime,
    pub source: String,
    pub entry_point: String,
    pub permissions: ScriptPermissions,
}

WebAssembly Exports

Graph Management

// Create and manage graphs
const graph = new Graph("MyGraph", true, {});
graph.addNode("node1", "Component", {});
graph.addConnection("node1", "out", "node2", "in", {});

// Graph analysis
const validation = graph.validate();
const cycles = graph.detectCycles();
const layout = graph.calculateLayout();

Network Operations

// Network management
const network = new Network();
network.addActor("processor", processorActor);
network.connect("source", "output", "processor", "input");
await network.start();

Message Handling

// Message creation and handling
const message = Message.fromJson({"key": "value"});
const result = await actor.process({"input": message});

Environment Variables

Runtime Environment

  • REFLOW_LOG_LEVEL - Override logging level
  • REFLOW_THREAD_POOL_SIZE - Override thread pool size
  • REFLOW_CONFIG_PATH - Configuration file path

Development Environment

  • REFLOW_DEV_MODE - Enable development features
  • REFLOW_HOT_RELOAD - Enable hot reloading
  • REFLOW_DEBUG_ACTORS - Enable actor debugging

Production Environment

  • REFLOW_PRODUCTION - Enable production optimizations
  • REFLOW_METRICS_ENDPOINT - Metrics collection endpoint
  • REFLOW_HEALTH_CHECK_PORT - Health check port

Performance Considerations

Memory Management

  • Use memory pooling for frequently allocated objects
  • Configure appropriate garbage collection settings
  • Monitor memory usage with built-in profiling tools

Concurrency

  • Balance thread pool size with available CPU cores
  • Use async operations for I/O bound tasks
  • Implement backpressure for high-throughput scenarios

Optimization

  • Enable compiler optimizations for production builds
  • Use profile-guided optimization when available
  • Monitor performance metrics and bottlenecks

Next Steps