FluxCore Dynamics Documentation

Everything you need to master photonic design

DocumentationWebSocket API

Quick Start

5-minute quickstart Account setup Your first design

WebSocket API

Real-time bidirectional communication for live updates

Real-Time

15 min readLast updated: January 2025WebSocket, Real-Time, Streaming

Socket.IO

Native WS

Connection

wss://ws.fluxcore.io

FluxCore supports both native WebSocket and Socket.IO protocols. Socket.IO is recommended for automatic reconnection and fallback support.

Socket.IO (Recommended)

import { io } from 'socket.io-client';

const socket = io('wss://ws.fluxcore.io', {
  auth: {
    token: 'YOUR_API_KEY'
  },
  transports: ['websocket'],
  reconnection: true,
  reconnectionDelay: 1000
});

socket.on('connect', () => {
  console.log('Connected!');
});

Native WebSocket

const ws = new WebSocket(
  'wss://ws.fluxcore.io/v1'
);

ws.onopen = () => {
  // Authenticate
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'YOUR_API_KEY'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

Event Channels

Simulation Channel

Stream real-time simulation updates including field data, metrics, and status changes.

// Subscribe to simulation updates
socket.emit('simulation:subscribe', {
  circuitId: 'cir_abc123'
});

// Receive live field updates (60 FPS)
socket.on('simulation:field', (data) => {
  // data.step - Current simulation step
  // data.time - Simulation time
  // data.field - Field array (Float32Array)
  // data.shape - Field dimensions [nx, ny, nz]
  updateVisualization(data.field, data.shape);
});

// Receive performance metrics
socket.on('simulation:metrics', (metrics) => {
  // metrics.insertionLoss - dB
  // metrics.couplingEfficiency - 0-1
  // metrics.groupDelay - seconds
  updateMetricsDisplay(metrics);
});

// Simulation state changes
socket.on('simulation:status', (status) => {
  // status: 'running' | 'paused' | 'completed' | 'error'
  console.log('Simulation status:', status);
});

// Control simulation
socket.emit('simulation:control', {
  action: 'pause'  // 'start' | 'pause' | 'resume' | 'stop' | 'step'
});

Performance Tip

Field data is sent as binary ArrayBuffer for efficiency. Use DataView or typed arrays to process the data on the client side.

Collaboration Channel

Real-time collaboration events for multi-user editing, presence, and synchronization.

// Join a circuit room for collaboration
socket.emit('circuit:join', {
  circuitId: 'cir_abc123'
});

// User presence events
socket.on('presence:join', (user) => {
  // user.id, user.name, user.color, user.cursor
  addCollaborator(user);
});

socket.on('presence:leave', (userId) => {
  removeCollaborator(userId);
});

// Cursor position updates (throttled to 30 FPS)
socket.on('cursor:move', (data) => {
  // data.userId, data.x, data.y, data.selection
  updateCursor(data.userId, data.x, data.y);
});

// Broadcast your cursor position
socket.emit('cursor:move', {
  x: cursorX,
  y: cursorY,
  selection: selectedComponents
});

// Component changes (CRDT-based)
socket.on('circuit:change', (change) => {
  // change.type: 'add' | 'update' | 'delete'
  // change.component: Component data
  // change.userId: Who made the change
  applyChange(change);
});

// Broadcast your changes
socket.emit('circuit:change', {
  type: 'update',
  component: {
    id: 'comp_123',
    parameters: { radius: 12.0 }
  }
});

Notifications Channel

Receive notifications for comments, mentions, job completions, and system events.

// Subscribe to notifications
socket.emit('notifications:subscribe');

// Receive notifications
socket.on('notification', (notification) => {
  switch (notification.type) {
    case 'comment':
      // Someone commented on your design
      showNotification(`${notification.user} commented: ${notification.preview}`);
      break;

    case 'mention':
      // You were @mentioned
      showNotification(`${notification.user} mentioned you`);
      break;

    case 'simulation_complete':
      // Simulation job finished
      showNotification('Simulation completed!', notification.resultUrl);
      break;

    case 'share':
      // Someone shared a design with you
      showNotification(`${notification.user} shared "${notification.designName}"`);
      break;
  }
});

// Mark notification as read
socket.emit('notification:read', { id: notification.id });

Error Handling & Reconnection

// Connection error handling
socket.on('connect_error', (error) => {
  if (error.message === 'authentication_failed') {
    // Refresh token and reconnect
    refreshToken().then(() => socket.connect());
  } else {
    console.error('Connection error:', error);
  }
});

// Disconnection handling
socket.on('disconnect', (reason) => {
  if (reason === 'io server disconnect') {
    // Server initiated disconnect, reconnect manually
    socket.connect();
  }
  // else: automatic reconnection will be attempted
});

// Custom reconnection strategy
const socket = io('wss://ws.fluxcore.io', {
  reconnection: true,
  reconnectionAttempts: 10,
  reconnectionDelay: 1000,
  reconnectionDelayMax: 30000,
  randomizationFactor: 0.5
});

// Track reconnection attempts
socket.io.on('reconnect_attempt', (attempt) => {
  console.log(`Reconnection attempt ${attempt}`);
  showReconnectingIndicator();
});

socket.io.on('reconnect', () => {
  console.log('Reconnected!');
  hideReconnectingIndicator();
  // Re-subscribe to channels
  resubscribeToChannels();
});

Connection States

connected - Active connection
connecting - Establishing connection
disconnected - No connection

Error Codes

authentication_failed - Invalid token
rate_limited - Too many messages
subscription_failed - Channel error
permission_denied - No access

Rate Limits

WebSocket connections have the following rate limits to ensure fair usage.

Event Type	Limit	Window
cursor:move	30 messages	1 second
circuit:change	100 messages	1 second
simulation:control	10 messages	1 second
All messages	1000 messages	1 minute