Control Tower Core

Centralized, runtime-agnostic library for real-time collaboration and synchronization.

Installation

npm install @principal-ai/control-tower-core

Quick Start

import {
  ServerBuilder,
  DefaultRoomManager,
  DefaultLockManager,
  MockTransportAdapter
} from '@principal-ai/control-tower-core';

// Create a server with default implementations
const server = new ServerBuilder()
  .withTransport(new MockTransportAdapter())
  .withRoomManager(new DefaultRoomManager())
  .withLockManager(new DefaultLockManager())
  .build();

await server.start(8080);
console.log('Server started on port 8080');

Features

• Room Management: Create, join, and manage collaborative rooms
• Lock Management: File/directory locking with queue support
• Real-time Events: Event broadcasting and history
• Extensible: Abstract interfaces for custom implementations
• TypeScript: Full type safety with generated declarations
• Experimental APIs: Opt-in broadcast features for rapid prototyping (see Experimental Features)

API Reference

ServerBuilder

The main entry point for creating servers:

const server = new ServerBuilder()
  .withTransport(transportAdapter)
  .withRoomManager(roomManager)
  .withLockManager(lockManager)
  .withAuth(authAdapter) // optional
  .withStorage(storageAdapter) // optional
  .withDefaultRoomConfig({
    maxUsers: 50,
    maxHistory: 100,
    permissions: ['read', 'write']
  })
  .build();

Default Implementations

• DefaultRoomManager: In-memory room management
• DefaultLockManager: In-memory locking with queue support
• MockTransportAdapter: Mock transport for testing

Custom Implementations

Implement the abstract interfaces to create custom adapters:

import { RoomManager } from '@principal-ai/control-tower-core';

class CustomRoomManager extends RoomManager {
  async createRoom(id: string, config: RoomConfig): Promise<Room> {
    // Your implementation
  }
  // ... implement other methods
}

Experimental Features

⚠️ For Development Use Only

Control Tower Core provides experimental broadcast APIs for rapid prototyping and internal tooling. These APIs allow broadcasting messages beyond room boundaries.

Enabling Experimental Features

import { ServerBuilder } from '@principal-ai/control-tower-core';

const server = new ServerBuilder()
  .withTransport(transportAdapter)
  .withRoomManager(roomManager)
  .withLockManager(lockManager)
  .withExperimentalFeatures({
    enableBroadcast: true  // Enable experimental broadcast APIs
  })
  .build();

Using Experimental Broadcast

// Broadcast to all connected clients
await server.experimental.broadcast({
  type: 'system:announcement',
  data: { message: 'Server maintenance in 5 minutes' }
});

// Broadcast to authenticated users only
await server.experimental.broadcastAuthenticated({
  type: 'presence:user_online',
  data: { userId: 'alice' }
});

// Broadcast with custom filtering
await server.experimental.broadcastWhere(
  (client) => client.userId.startsWith('admin_'),
  { type: 'admin:alert', data: { ... } }
);

// Send to specific users
await server.experimental.sendToUsers(
  ['user1', 'user2'],
  { type: 'notification:mention', data: { ... } }
);

Important Notes

• Experimental APIs may change or be removed without major version bumps
• Not recommended for production applications
• Use for prototyping, then submit a feature request to graduate to stable API
• See full documentation for details

Testing

Control Tower Core provides comprehensive test utilities for building reliable applications.

MockTransportAdapter

The MockTransportAdapter provides test helpers for simulating client-server interactions:

import { MockTransportAdapter } from '@principal-ai/control-tower-core';

const transport = new MockTransportAdapter();

// Simulate a client connection
await transport.simulateConnection('client-id', {
  authenticated: true,
  userId: 'user-123',
  metadata: { deviceType: 'desktop' }
});

// Simulate client messages
await transport.simulateClientMessage('client-id', 'join_room', {
  roomId: 'room-1'
});

// Simulate incoming server messages (for client tests)
transport.simulateIncomingMessage({
  type: 'room_joined',
  payload: { roomId: 'room-1', state: { ... } }
});

// Track connection attempts (useful for reconnection tests)
const attempts = transport.getConnectionAttempts();
transport.resetConnectionAttempts();

// Get messages sent to specific clients
const messages = transport.getSentMessages('client-id');

Running Tests

# Run all tests
bun test

# Run specific test file
bun test tests/BaseServer.test.ts

# Run with coverage
bun test --coverage

Documentation

• Experimental Broadcast APIs
• Feature Request Template
• Architecture Design
• Changelog

License

MIT