RCC Server Module


📚 Detailed Architecture Documentation: ARCHITECTURE.md

Overview

The RCC Server Module is a powerful HTTP server component designed for the RCC (Router-Controlled Computing) framework. It provides client input proxy response capabilities with intelligent virtual model routing, middleware support, and comprehensive monitoring features.

Features

$3

- HTTP Server: High-performance Express.js-based HTTP server with security middleware
- Virtual Model Routing: Intelligent request routing based on Claude Code Router rules
- Middleware Support: Extensible middleware system for request processing
- WebSocket Support: Real-time bidirectional communication
- Load Balancing: Multiple strategies (round-robin, weighted, least-connections)
- Monitoring: Comprehensive metrics and health checking
- Configuration Management: Flexible configuration system

$3

- Model Capability Detection: Automatic capability matching for virtual models
- Intelligent Routing: Rule-based routing with priority and condition evaluation
- Health Monitoring: Real-time health checks and system metrics
- Error Handling: Comprehensive error handling and recovery
- Performance Metrics: Request tracking and performance analytics
- Pipeline Integration: Seamless integration with Pipeline Scheduler for request processing
- Configuration Management: Dynamic configuration integration with virtual model mapping
- Fallback Processing: Automatic fallback to direct processing when pipeline fails

Installation

``bash
npm install rcc-server
`

Peer Dependencies

This module requires the following RCC modules:

`bash
npm install rcc-basemodule rcc-pipeline rcc-errorhandling rcc-configuration rcc-virtual-model-rules rcc-underconstruction
`

Quick Start

$3

`typescript
import { ServerModule } from 'rcc-server';

// Create server instance
const server = new ServerModule();

// Initialize with configuration
await server.initialize({
port: 3000,
host: 'localhost',
cors: {
origin: ['http://localhost:3000'],
credentials: true
},
compression: true,
helmet: true,
rateLimit: {
windowMs: 60000,
max: 100
},
timeout: 30000,
bodyLimit: '10mb'
});

// Start the server
await server.start();

console.log('Server is running on http://localhost:3000');
`

$3

`typescript
import { VirtualModelConfig } from 'rcc-server';

const modelConfig: VirtualModelConfig = {
id: 'qwen-turbo',
name: 'Qwen Turbo',
provider: 'qwen',
endpoint: 'https://chat.qwen.ai/api/v1/chat/completions',
model: 'qwen-turbo',
capabilities: ['chat', 'streaming', 'tools'],
maxTokens: 4000,
temperature: 0.7,
topP: 1.0,
priority: 8,
enabled: true,
routingRules: [
{
id: 'chat-rule',
name: 'Chat requests',
condition: 'path:/api/chat',
weight: 1.0,
enabled: true,
priority: 5,
modelId: 'qwen-turbo'
}
]
};

await server.registerVirtualModel(modelConfig);
`

$3

`typescript
import { RouteConfig } from 'rcc-server';

const routeConfig: RouteConfig = {
id: 'chat-endpoint',
path: '/api/chat',
method: 'POST',
handler: 'chatHandler',
middleware: ['auth', 'rateLimit'],
virtualModel: 'qwen-turbo',
authRequired: true
};

await server.registerRoute(routeConfig);
`

Pipeline Integration

The RCC Server Module provides seamless integration with the Pipeline Scheduler for advanced request processing capabilities. This integration enables sophisticated request routing, load balancing, and error handling through a unified pipeline architecture.

$3

`typescript
import { ServerModule } from 'rcc-server';
import { PipelineScheduler } from 'rcc-pipeline';
import { PipelineSystemConfig } from 'rcc-pipeline';

// Create server instance
const server = new ServerModule();

// Configure server
const serverConfig = {
port: 3000,
host: 'localhost',
// ... other server configuration
};

server.configure(serverConfig);
await server.initialize();
await server.start();

// Create pipeline scheduler configuration
const pipelineConfig: PipelineSystemConfig = {
pipelines: [
{
id: 'qwen-turbo-pipeline',
name: 'Qwen Turbo Pipeline',
type: 'ai-model',
enabled: true,
priority: 1,
weight: 3,
maxConcurrentRequests: 20,
timeout: 45000,
config: {
model: 'qwen-turbo',
provider: 'qwen',
maxTokens: 2000,
temperature: 0.7,
topP: 0.9
}
}
],
loadBalancer: {
strategy: 'weighted',
healthCheckInterval: 15000
},
scheduler: {
defaultTimeout: 45000,
maxRetries: 5,
retryDelay: 2000
}
};

// Create and integrate pipeline scheduler
const pipelineScheduler = new PipelineScheduler(pipelineConfig);
await server.setPipelineScheduler(pipelineScheduler);

// Register virtual models
await server.registerVirtualModel({
id: 'qwen-turbo-virtual',
name: 'Qwen Turbo Virtual Model',
provider: 'qwen',
model: 'qwen-turbo',
capabilities: ['text-generation', 'chat'],
maxTokens: 2000,
temperature: 0.7,
enabled: true
});
`

$3

The server automatically integrates with the Configuration module to provide dynamic virtual model mapping and pipeline generation:

`typescript
// The server automatically initializes ConfigurationToPipelineModule
// which provides:
// - Virtual model mapping from configuration
// - Pipeline table generation
// - Dynamic pipeline assembly
// - Configuration validation

// Check integration status
const status = server.getStatus();
console.log('Pipeline Integration:', {
enabled: status.pipelineIntegration.enabled,
schedulerAvailable: status.pipelineIntegration.schedulerAvailable,
processingMethod: status.pipelineIntegration.processingMethod,
fallbackEnabled: status.pipelineIntegration.fallbackEnabled
});
`

$3

1. Request Reception: Server receives HTTP request
2. Virtual Model Routing: Request is routed to appropriate virtual model
3. Pipeline Execution: Request is processed through Pipeline Scheduler
4. Fallback Handling: If pipeline fails, falls back to direct processing
5. Response Generation: Response is formatted and returned to client

`typescript
// Example request processing
const request = {
id: 'test-request',
method: 'POST',
path: '/api/chat',
headers: {
'Content-Type': 'application/json'
},
body: {
messages: [
{ role: 'user', content: 'Hello!' }
]
},
timestamp: Date.now(),
virtualModel: 'qwen-turbo-virtual'
};

// Process request (automatically uses pipeline if available)
const response = await server.handleRequest(request);

// Response includes processing metadata
console.log('Response:', {
status: response.status,
processingMethod: response.headers['X-Processing-Method'],
virtualModel: response.headers['X-Virtual-Model'],
pipelineId: response.headers['X-Pipeline-Id'],
executionId: response.headers['X-Execution-Id'],
processingTime: response.processingTime
});
`

$3

The system provides comprehensive error handling with automatic fallback:

`typescript
// Pipeline execution errors are automatically handled
try {
const response = await server.handleRequest(request);

if (response.headers['X-Processing-Method'] === 'direct') {
// Request was processed via fallback
console.log('Fallback reason:', response.headers['X-Fallback-Reason']);
}
} catch (error) {
// Handle critical errors
console.error('Request failed:', error);
}
`

$3

Monitor pipeline integration performance:

`typescript
// Get detailed integration status
const integrationConfig = server.getPipelineIntegrationConfig();
console.log('Pipeline Integration Config:', {
enabled: integrationConfig.enabled,
defaultTimeout: integrationConfig.defaultTimeout,
maxRetries: integrationConfig.maxRetries,
fallbackToDirect: integrationConfig.fallbackToDirect
});

// Monitor overall system health
const health = await server.getHealth();
console.log('System Health:', {
status: health.status,
pipelineIntegration: health.checks.pipeline_integration,
schedulerHealth: health.checks.pipeline_scheduler
});
`

API Documentation

$3

The main class that provides all server functionality.

#### Methods

##### initialize(config: ServerConfig): Promise
Initialize the server with configuration.

##### start(): Promise
Start the HTTP server.

##### stop(): Promise
Stop the HTTP server.

##### handleRequest(request: ClientRequest): Promise
Handle a client request and return a response.

##### registerVirtualModel(model: VirtualModelConfig): Promise
Register a virtual model for request routing.

##### registerRoute(route: RouteConfig): Promise
Register a custom route.

##### getStatus(): ServerStatus
Get current server status.

##### getHealth(): Promise
Get detailed health information.

$3

Configuration for virtual models:

`typescript
interface VirtualModelConfig {
id: string; // Unique identifier
name: string; // Human-readable name
provider: string; // Provider name (e.g., 'qwen', 'openai')
endpoint: string; // API endpoint URL
apiKey?: string; // Optional API key
model: string; // Model name
capabilities: string[]; // Supported capabilities
maxTokens: number; // Maximum token limit
temperature: number; // Temperature parameter
topP: number; // Top-p parameter
priority: number; // Load balancing priority (1-10)
enabled: boolean; // Whether model is enabled
routingRules: RoutingRule[]; // Routing rules
}
`

$3

Request object format:

`typescript
interface ClientRequest {
id: string; // Unique request ID
method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
path: string; // Request path
headers: Record; // Request headers
body?: any; // Request body
query?: Record; // Query parameters
timestamp: number; // Request timestamp
clientId?: string; // Optional client ID
virtualModel?: string; // Optional virtual model override
}
`

Configuration

$3

Complete server configuration:

`typescript
interface ServerConfig {
port: number; // Server port
host: string; // Server host
cors: { // CORS configuration
origin: string | string[];
credentials: boolean;
};
compression: boolean; // Enable compression
helmet: boolean; // Enable security headers
rateLimit: { // Rate limiting
windowMs: number;
max: number;
};
timeout: number; // Request timeout (ms)
bodyLimit: string; // Request body size limit
}
`

Routing Rules and Virtual Model Mapping

The server uses routing rules to determine which virtual model should handle each request. When no specific model is requested, the system evaluates all enabled models against their routing rules and selects the first matching candidate.

$3


`typescript
const model = {
id: 'chat-model',
name: 'Chat Model',
provider: 'openai',
endpoint: 'https://api.openai.com/v1/chat',
capabilities: ['chat', 'streaming'],
// ... other config
};

await server.registerVirtualModel(model);
`

$3

Virtual models can define routing rules to filter which requests they should handle:

`typescript
const model = {
// ... other config
routingRules: [
{
id: 'chat-only',
name: 'Chat Requests Only',
condition: 'path:/api/chat',
weight: 1.0,
enabled: true,
priority: 1
}
]
};
`

Monitoring and Metrics

$3

`typescript
const health = await server.getHealth();
console.log('Server health:', health.status);
console.log('Health checks:', health.checks);
`

$3

`typescript
const metrics = server.getMetrics();
console.log('Total requests:', metrics.length);
console.log('Average response time:',
metrics.reduce((sum, m) => sum + m.processingTime, 0) / metrics.length);
`

$3

`typescript
const status = server.getStatus();
console.log('Server status:', status.status);
console.log('Active connections:', status.connections);
console.log('Virtual models:', status.virtualModels);
`

Middleware System

$3

`typescript
import { MiddlewareConfig } from 'rcc-server';

const middleware: MiddlewareConfig = {
name: 'auth',
type: 'pre',
priority: 10,
enabled: true,
config: {
secretKey: 'your-secret-key'
}
};

await server.registerMiddleware(middleware);
`

$3

The server includes several built-in middleware:

- Security: Helmet.js for security headers
- CORS: Cross-origin resource sharing
- Compression: Response compression
- Body Parsing: Request body parsing
- Rate Limiting: Request rate limiting
- Request Logging: Detailed request logging

Error Handling

The server provides comprehensive error handling:

`typescript
try {
const response = await server.handleRequest(request);
console.log('Request successful:', response);
} catch (error) {
console.error('Request failed:', error);

// Error response includes:
// - Error details
// - Request ID for tracking
// - Processing time
// - HTTP status code
}
`

Development

$3

`bash


Install dependencies

npm install

Build the module

npm run build

Run type checking

npm run typecheck

Run linting

npm run lint

Run tests

npm test
`

$3

`bash


Run all tests

npm test

Run tests with coverage

npm run test:coverage

Run tests in watch mode

npm run test:watch
`

$3

Check the examples/ directory for complete usage examples:

- Basic Server - Basic server setup and configuration
- Virtual Model Setup - Virtual model registration and routing
- Custom Routes - Custom route registration and handling
- Middleware - Middleware system and custom middleware
- Pipeline Integration - Pipeline scheduler integration examples
- Complete Integration - Complete end-to-end integration example

Performance

The server module is optimized for performance:

- Non-blocking I/O: Built on Node.js and Express.js
- Connection Pooling: Efficient connection management
- Memory Management: Automatic garbage collection and cleanup
- Load Balancing: Intelligent request distribution
- Caching: Response caching where appropriate
- Compression: Automatic response compression

Security

The server includes several security features:

- Security Headers: Helmet.js for secure headers
- CORS: Configurable cross-origin resource sharing
- Rate Limiting: Prevent abuse and DoS attacks
- Input Validation: Request validation and sanitization
- Authentication: Optional authentication middleware
- HTTPS: SSL/TLS support (requires certificate)

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature`
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please open an issue on the GitHub Issues page.

Changelog

See CHANGELOG.md for a list of changes and version history.

Related Projects

- RCC Base Module - Core framework for modular development
- RCC Pipeline - Pipeline and workflow management
- RCC Configuration - Configuration management and validation
- RCC Virtual Model Rules - Virtual model routing and rule management
- RCC Error Handling - Error handling and recovery
- RCC Under Construction - Feature development tracking

---

Built with ❤️ by the RCC Development Team