Hooks Reference: Server and Client Lifecycle Callbacks

const stelar = new StelarServer({
  port: 3000,
  hooks: {
    onRateLimitExceeded: ({ clientId }) => {
      console.warn('Spammer detected:', clientId);
      return false; // Warn but do NOT disconnect
    },
  },
});

onRateLimitExceeded: ({ clientId, event, protocol }) => {
  metrics.increment('rate_limit.exceeded', { protocol });
  if (event === 'typing') return false; // Never disconnect for typing spam
}

onMaxConnectionsReached: ({ activeConnections, max, ip }) => {
  alertOps(`Server at capacity: ${activeConnections}/${max}. Rejected: ${ip}`);
}

onPayloadTooLarge: ({ clientId, event, size, max }) => {
  console.warn(`Oversized payload from ${clientId}: ${size} bytes (limit ${max})`);
}

onClientJoinRoom: ({ clientId, room, metadata }) => {
  const role = metadata.get('role');
  if (room.startsWith('admin-') && role !== 'admin') {
    return false; // Block non-admins from admin rooms
  }
  if (room.startsWith('vip-') && !metadata.get('isPremium')) {
    return false; // Block non-premium from VIP rooms
  }
}

onBeforeBroadcast: ({ event, data }) => {
  if (event === 'system-debug' && process.env.NODE_ENV === 'production') {
    return false; // Never broadcast debug events in production
  }
}

onBeforeEmit: ({ event, data }) => {
  if (event === 'debug' && !isDev) return false; // No debug in production
  console.debug('→', event, data);
}

onStateChange: ({ from, to }) => {
  if (to === 'reconnecting') showOfflineBanner();
  if (to === 'connected')    hideOfflineBanner();
  analytics.track('connection_state_change', { from, to });
}

onReconnectDelay: ({ attempt, defaultDelay }) => {
  // During business hours: reconnect fast
  const hour = new Date().getHours();
  if (hour >= 9 && hour <= 18) return 500;
  return defaultDelay; // Off-hours: normal exponential backoff
}

const stelar = new StelarServer({
  port: 3000,
  maxConnections: 5000,
  rateLimit: { maxPoints: 100, windowMs: 1000 },

  hooks: {
    // Access control for admin rooms
    onClientJoinRoom: ({ clientId, room, metadata }) => {
      const role = metadata.get('role');
      if (room.startsWith('admin-') && role !== 'admin') {
        console.warn(`[ACCESS DENIED] ${clientId} tried to join ${room}`);
        return false;
      }
    },

    // Warn on rate limit, auto-ban repeat offenders
    onRateLimitExceeded: ({ clientId, event, protocol }) => {
      const count = incrementAbuse(clientId);
      console.warn(`[RATE LIMIT] ${clientId} on "${event}" (offense #${count})`);

      if (count >= 10) {
        banlist.add(clientId);
        return; // Disconnect on 10th offense
      }
      return false; // Warn only for first 9 offenses
    },

    // Metrics on connection/disconnection
    onClientConnect: ({ clientId, ip, protocol }) => {
      metrics.gauge('active_connections', stelar.getStats().activeConnections);
      console.log(`[+] ${clientId} (${protocol}) from ${ip}`);
    },

    onClientDisconnect: ({ clientId, rooms }) => {
      metrics.gauge('active_connections', stelar.getStats().activeConnections);
      console.log(`[-] ${clientId} left ${rooms.size} room(s)`);
    },

    // Alert when server approaches capacity
    onMaxConnectionsReached: ({ activeConnections, max, ip }) => {
      notifyOps(`Server full (${activeConnections}/${max}). Rejected: ${ip}`);
    },

    // Log oversized payloads
    onPayloadTooLarge: ({ clientId, event, size, max }) => {
      console.warn(`[PAYLOAD] ${clientId} sent ${size} bytes on "${event}" (limit ${max})`);
    },

    // Intercept certain broadcasts
    onBeforeBroadcast: ({ event }) => {
      if (event === 'internal-debug') return false;
    },
  },
});

const client = new StelarClient('wss://app.example.com', {
  hooks: {
    // UI feedback on state changes
    onStateChange: ({ from, to }) => {
      console.log(`State: ${from} → ${to}`);
      updateStatusIndicator(to);

      if (to === 'reconnecting') showReconnectingOverlay();
      if (to === 'connected')    hideReconnectingOverlay();
    },

    // Track all received messages
    onMessage: ({ event, data, isBinary }) => {
      metrics.increment('messages.received');
      if (isBinary) metrics.increment('messages.binary');
    },

    // Suppress debug events in production
    onBeforeEmit: ({ event }) => {
      if (event.startsWith('debug:') && !isDev) return false;
    },

    // Adaptive reconnection delay based on time of day
    onReconnectDelay: ({ attempt, defaultDelay }) => {
      const hour = new Date().getHours();
      return (hour >= 9 && hour <= 18) ? 500 : defaultDelay;
    },

    // Notify user that messages are pending
    onMessageQueued: ({ event, queueSize }) => {
      if (queueSize === 1) showPendingBadge();
    },

    // Hide badge once messages are sent
    onQueueDrained: ({ count }) => {
      hidePendingBadge();
      console.log(`Flushed ${count} pending message(s)`);
    },

    // Report errors
    onError: ({ error, context }) => {
      errorReporter.capture(error, { context, user: getUser() });
    },
  },
});

stelar.updateConfig({
  hooks: {
    onRateLimitExceeded: ({ clientId }) => {
      // Replace the original hook — now auto-bans instead of warning
      banUser(clientId);
      return false;
    },
  },
});
// Note: updateConfig merges hooks — existing hooks not in the update are preserved

client.updateOptions({
  hooks: {
    onBeforeEmit: ({ event }) => {
      // After feature flag change: start suppressing analytics events
      if (event.startsWith('analytics:')) return false;
    },
  },
});