Real-time Events

// Create a WebSocket subscription to a specific machine by ID
const subscription = client.subscribe('machine-id');
 
// Listen for successful connection to the machine's event channel
subscription.on('connect', () => {
  console.log('Connected');
});
 
// Handle disconnection events for cleanup or UI updates
subscription.on('disconnect', () => {
  console.log('Disconnected');
});
 
// Unsubscribe when done to release the WebSocket connection
subscription.unsubscribe();

// Listen for machine status changes (online/offline transitions)
subscription.on('status', (event) => {
  console.log(event.status); // 'online' | 'offline'
  console.log(event.timestamp); // ISO 8601 timestamp of the status change
});

// Stream command output as it is produced on the machine
subscription.on('output', (event) => {
  console.log(event.type); // 'stdout' for standard output, 'stderr' for errors
  console.log(event.data); // The actual output text chunk
  console.log(event.commandId); // ID of the command that produced this output
});

// Receive periodic system metrics updates from the machine
subscription.on('metrics', (event) => {
  console.log(event.cpu.usage); // CPU usage percentage (0-100)
  console.log(event.memory.used); // Memory used in bytes
  console.log(event.disk.used); // Disk space used in bytes
});

// Watch for file system changes on the machine
subscription.on('file', (event) => {
  console.log(event.type); // 'created' | 'modified' | 'deleted'
  console.log(event.path); // Absolute path to the changed file
});

// Subscribe to events from multiple machines at once
const subscription = client.subscribeMany([
  'machine-1',
  'machine-2',
]);
 
// Each event includes the machineId so you can distinguish sources
subscription.on('status', (event) => {
  console.log(event.machineId, event.status);
});

import { useRealtime } from '@cmdop/react';
 
// React component that displays live machine status using the useRealtime hook
function StatusMonitor({ machineId }) {
  // useRealtime manages the WebSocket subscription lifecycle automatically
  const { status, metrics, connected } = useRealtime(machineId);
 
  return (
    <div>
      <p>Connected: {connected ? 'Yes' : 'No'}</p>
      <p>Status: {status}</p>
      {/* Safely access nested metrics with optional chaining */}
      <p>CPU: {metrics?.cpu.usage}%</p>
    </div>
  );
}

// Configure reconnection behavior for resilient subscriptions
const subscription = client.subscribe('machine-id', {
  reconnect: true, // Enable automatic reconnection on disconnect
  reconnectDelay: 1000, // Wait 1 second between reconnection attempts
  maxReconnectAttempts: 10, // Give up after 10 failed attempts
});

// Handle subscription errors (network failures, auth issues, etc.)
subscription.on('error', (error) => {
  console.error('Subscription error:', error);
});
 
// Track reconnection attempts for logging or UI feedback
subscription.on('reconnecting', (attempt) => {
  console.log(`Reconnecting (attempt ${attempt})...`);
});

// Subscribe only to specific event channels instead of all events
const subscription = client.subscribe('machine-id', {
  channels: ['status', 'metrics'], // Only receive status and metrics events
});

// Listen for real-time presence changes as users join/leave
subscription.on('presence', (event) => {
  console.log('Users viewing:', event.users);
});
 
// Query the current presence snapshot on demand
const presence = await subscription.presence();
console.log(presence.users); // Array of currently connected users