dcrouter/readme.opsserver.md

DCRouter OpsServer Implementation Plan

Command to reread CLAUDE.md: cat /home/philkunz/.claude/CLAUDE.md

Overview

This document outlines the implementation plan for adding a TypedRequest-based API to the DCRouter OpsServer, following the patterns established in the cloudly project. The goal is to create a type-safe, reactive management dashboard with real-time statistics and monitoring capabilities.

Architecture Overview

The implementation follows a clear separation of concerns:

• Backend: TypedRequest handlers in OpsServer
• Frontend: Reactive web components with Smartstate
• Communication: Type-safe requests via TypedRequest pattern
• State Management: Centralized state with reactive updates

Implementation Phases

Phase 1: Interface Definition ✓

Create TypeScript interfaces for all API operations:

Directory Structure ✓

ts_interfaces/
  plugins.ts         # TypedRequest interfaces import
  data/              # Data type definitions
    auth.ts          # IIdentity interface
    stats.ts         # Server, Email, DNS, Security types
    index.ts         # Exports
  requests/          # Request interfaces
    admin.ts         # Authentication requests
    config.ts        # Configuration management  
    logs.ts          # Log retrieval with IVirtualStream
    stats.ts         # Statistics endpoints
    index.ts         # Exports

Key Interfaces Defined ✓

• Server Statistics

  • IReq_GetServerStatistics - Server metrics with history

• Email Operations

  • IReq_GetEmailStatistics - Email delivery stats
  • IReq_GetQueueStatus - Queue monitoring

• DNS Management

  • IReq_GetDnsStatistics - DNS query metrics

• Rate Limiting

  • IReq_GetRateLimitStatus - Rate limit info

• Security Metrics

  • IReq_GetSecurityMetrics - Security stats and trends
  • IReq_GetActiveConnections - Connection monitoring

• Logging

  • IReq_GetRecentLogs - Paginated log retrieval
  • IReq_GetLogStream - Real-time log streaming with IVirtualStream

• Configuration

  • IReq_GetConfiguration - Read config
  • IReq_UpdateConfiguration - Update config

• Authentication

  • IReq_AdminLoginWithUsernameAndPassword - Admin login
  • IReq_AdminLogout - Logout
  • IReq_VerifyIdentity - Token verification

• Health Check

  • IReq_GetHealthStatus - Service health monitoring

Phase 2: Backend Implementation ✓

2.1 Enhance OpsServer (ts/opsserver/classes.opsserver.ts) ✓

• Add TypedRouter initialization
• Use TypedServer's built-in typedrouter
• CORS is already handled by TypedServer
• Add handler registration method

// Example structure following cloudly pattern
public typedrouter = new plugins.typedrequest.TypedRouter();

constructor(private dcRouterRef: DcRouter) {
  // Add our typedrouter to the dcRouter's main typedrouter
  this.dcRouterRef.typedrouter.addTypedRouter(this.typedrouter);
}

public async start() {
  // TypedServer already has a built-in typedrouter at /typedrequest
  this.server = new plugins.typedserver.utilityservers.UtilityWebsiteServer({
    domain: 'localhost',
    feedMetadata: null,
    serveDir: paths.distServe,
  });
  
  // The server's typedrouter is automatically available
  // Add the main dcRouter typedrouter to the server's typedrouter
  this.server.typedrouter.addTypedRouter(this.dcRouterRef.typedrouter);
  
  this.setupHandlers();
  await this.server.start(3000);
}

Note: TypedServer automatically provides the /typedrequest endpoint with its built-in typedrouter. We just need to add our routers to it using the addTypedRouter() method.

Hierarchical TypedRouter Structure

Following cloudly's pattern, we'll use a hierarchical router structure:

TypedServer (built-in typedrouter at /typedrequest)
  └── DcRouter.typedrouter (main router)
      └── OpsServer.typedrouter (ops-specific handlers)
          ├── StatsHandler.typedrouter
          ├── ConfigHandler.typedrouter
          └── SecurityHandler.typedrouter

This allows clean separation of concerns while keeping all handlers accessible through the single /typedrequest endpoint.

2.2 Create Handler Classes ✓

Create modular handlers in ts/opsserver/handlers/:

• stats.handler.ts - Server and performance statistics
• security.handler.ts - Security and reputation metrics
• config.handler.ts - Configuration management
• logs.handler.ts - Log retrieval and streaming
• admin.handler.ts - Authentication and session management

Each handler should:

• Have its own typedrouter that gets added to OpsServer's router
• Access the main DCRouter instance
• Register handlers using TypedHandler instances
• Format responses according to interfaces
• Handle errors gracefully

Example handler structure:

export class StatsHandler {
  public typedrouter = new plugins.typedrequest.TypedRouter();
  
  constructor(private opsServerRef: OpsServer) {
    // Add this handler's router to the parent
    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
    this.registerHandlers();
  }
  
  private registerHandlers() {
    this.typedrouter.addTypedHandler(
      new plugins.typedrequest.TypedHandler<IReq_GetServerStatistics>(
        'getServerStatistics',
        async (dataArg, toolsArg) => {
          const stats = await this.collectServerStats();
          return stats;
        }
      )
    );
  }
}

Phase 3: Frontend State Management

3.1 Set up Smartstate (ts_web/appstate.ts)

• Initialize Smartstate instance
• Create state parts with appropriate persistence
• Define initial state structures

// State structure example
interface IStatsState {
  serverStats: IRes_ServerStatistics | null;
  emailStats: IRes_EmailStatistics | null;
  dnsStats: IRes_DnsStatistics | null;
  lastUpdated: number;
  isLoading: boolean;
  error: string | null;
}

3.2 State Parts to Create

• statsState - Runtime statistics (soft persistence)
• configState - Configuration data (soft persistence)
• uiState - UI preferences (persistent)
• loginState - Authentication state (persistent) if needed

Phase 4: Frontend Integration

4.1 API Client Setup (ts_web/api/clients.ts)

• Create TypedRequest instances for each endpoint
• Configure base URL handling
• Add error interceptors
• Implement retry logic

4.2 Create Actions (ts_web/state/actions.ts)

• fetchAllStatsAction - Batch fetch all statistics
• refreshServerStatsAction - Update server stats only
• refreshEmailStatsAction - Update email stats only
• setAutoRefreshAction - Toggle auto-refresh
• Error handling actions

4.3 Update Dashboard Component (ts_web/elements/ops-dashboard.ts)

• Subscribe to state changes
• Implement reactive UI updates
• Add refresh controls
• Create sub-components for different stat types
• Implement auto-refresh timer

Phase 5: Component Structure

Create modular components in ts_web/elements/components/:

• server-stats.ts - Server statistics display
• email-stats.ts - Email metrics visualization
• dns-stats.ts - DNS statistics
• rate-limit-display.ts - Rate limiting status
• security-metrics.ts - Security dashboard
• log-viewer.ts - Real-time log display

Phase 6: Optional Enhancements

6.1 Authentication ✓ (Implemented)

• JWT-based authentication using @push.rocks/smartjwt
• Guards for identity validation and admin access
• Login/logout endpoints following cloudly pattern
• Login component (frontend)
• Protected route handling (frontend)
• Session persistence (frontend)

6.2 Real-time Updates (future)

• WebSocket integration for live stats
• Push notifications for critical events
• Event streaming for logs

Technical Stack

Dependencies to Use

• @api.global/typedserver - Server with built-in typedrouter at /typedrequest
• @api.global/typedrequest - TypedRouter and TypedHandler classes
• @design.estate/dees-domtools - Frontend TypedRequest client
• @push.rocks/smartstate - State management
• @design.estate/dees-element - Web components
• @design.estate/dees-catalog - UI components

Existing Dependencies to Leverage

• Current DCRouter instance and statistics
• Existing error handling patterns
• Logger infrastructure
• Security modules

Development Workflow

1. Start with interfaces - Define all types first
2. Implement one handler - Start with server stats
3. Create minimal frontend - Test with one endpoint
4. Iterate - Add more handlers and UI components
5. Polish - Add error handling, loading states, etc.

Testing Strategy

• Unit tests for handlers
• Integration tests for API endpoints
• Frontend component tests
• End-to-end testing with real DCRouter instance

Success Criteria

• Type-safe communication between frontend and backend
• Real-time statistics display
• Responsive and reactive UI
• Clean, maintainable code structure
• Consistent with cloudly patterns
• Easy to extend with new features

Notes

• Follow existing code conventions in the project
• Use pnpm for all package management
• Ensure all tests pass before marking complete
• Document any deviations from the plan

---

Progress Status

Completed ✓

• Phase 1: Interface Definition - All TypedRequest interfaces created following cloudly pattern

  • Created proper TypedRequest interfaces with method, request, and response properties
  • Used IVirtualStream for log streaming
  • Added @api.global/typedrequest-interfaces dependency
  • All interfaces compile successfully

• Phase 2: Backend Implementation - TypedRouter integration and handlers

  • Enhanced OpsServer with hierarchical TypedRouter structure
  • Created all handler classes with proper TypedHandler registration
  • Implemented mock data responses for all endpoints
  • Fixed all TypeScript compilation errors
  • VirtualStream used for log streaming with Uint8Array encoding
  • JWT Authentication - Following cloudly pattern:
    • Added @push.rocks/smartjwt and @push.rocks/smartguard dependencies
    • Updated IIdentity interface to match cloudly structure
    • Implemented JWT-based authentication with RSA keypairs
    • Created validIdentityGuard and adminIdentityGuard
    • Added guard helpers for protecting endpoints
    • Full test coverage for JWT authentication flows

Next Steps

• Phase 3: Frontend State Management - Set up Smartstate
• Phase 4: Frontend Integration - Create API clients and update dashboard
• Phase 5: Create modular UI components

---

This plan is a living document. Update it as implementation progresses.