feat(ts_interfaces): add TypedRequest interfaces for admin and configuration requests
fix(dependencies): include @api.global/typedrequest-interfaces in package.json chore(docs): create OpsServer implementation plan in readme.opsserver.md
This commit is contained in:
Juergen Kunz
308
readme.opsserver.md
Normal file
308
readme.opsserver.md
Normal file
@ -0,0 +1,308 @@
|
||||
# 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**
|
||||
- [x] `IReq_GetServerStatistics` - Server metrics with history
|
||||
|
||||
- **Email Operations**
|
||||
- [x] `IReq_GetEmailStatistics` - Email delivery stats
|
||||
- [x] `IReq_GetQueueStatus` - Queue monitoring
|
||||
|
||||
- **DNS Management**
|
||||
- [x] `IReq_GetDnsStatistics` - DNS query metrics
|
||||
|
||||
- **Rate Limiting**
|
||||
- [x] `IReq_GetRateLimitStatus` - Rate limit info
|
||||
|
||||
- **Security Metrics**
|
||||
- [x] `IReq_GetSecurityMetrics` - Security stats and trends
|
||||
- [x] `IReq_GetActiveConnections` - Connection monitoring
|
||||
|
||||
- **Logging**
|
||||
- [x] `IReq_GetRecentLogs` - Paginated log retrieval
|
||||
- [x] `IReq_GetLogStream` - Real-time log streaming with IVirtualStream
|
||||
|
||||
- **Configuration**
|
||||
- [x] `IReq_GetConfiguration` - Read config
|
||||
- [x] `IReq_UpdateConfiguration` - Update config
|
||||
|
||||
- **Authentication**
|
||||
- [x] `IReq_AdminLoginWithUsernameAndPassword` - Admin login
|
||||
- [x] `IReq_AdminLogout` - Logout
|
||||
- [x] `IReq_VerifyIdentity` - Token verification
|
||||
|
||||
- **Health Check**
|
||||
- [x] `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
|
||||
|
||||
```typescript
|
||||
// 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
|
||||
- [ ] `email.handler.ts` - Email-related operations
|
||||
- [ ] `dns.handler.ts` - DNS management statistics
|
||||
- [ ] `security.handler.ts` - Security and reputation metrics
|
||||
- [ ] `config.handler.ts` - Configuration 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:
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
// 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 (if required)
|
||||
- [ ] Simple token-based authentication
|
||||
- [ ] Login component
|
||||
- [ ] Protected route handling
|
||||
- [ ] Session management
|
||||
|
||||
#### 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
|
||||
|
||||
### Next Steps
|
||||
- Phase 2: Backend Implementation - Enhance OpsServer and create handlers
|
||||
- Phase 3: Frontend State Management - Set up Smartstate
|
||||
- Phase 4: Frontend Integration - Create API clients and update dashboard
|
||||
|
||||
---
|
||||
|
||||
*This plan is a living document. Update it as implementation progresses.*
|
||||
Reference in New Issue
Block a user