Web_BLS_ProjectConsole/openspec/specs/command/design.md

Command Capability Design

Context

This design document describes the technical implementation of the command capability for the BLS Project Console, which allows users to send console commands to Redis queues for other programs to read and execute.

Goals / Non-Goals

Goals

• Implement command sending to Redis queues
• Provide command validation and error handling
• Maintain a history of sent commands
• Handle command responses from Redis
• Ensure high performance and reliability

Non-Goals

• Command execution or processing
• Complex command syntax highlighting
• Advanced command editing capabilities

Decisions

Decision: Redis Queue Implementation

• What: Use Redis List as the queue data structure
• Why: Redis Lists provide efficient push/pop operations with O(1) time complexity, making them ideal for message queues
• Alternatives considered:
  • Redis Streams: More advanced but overkill for our use case
  • Redis Pub/Sub: No persistence, so commands would be lost if the receiving program is down

Decision: Command History Storage

• What: Store command history in memory with a configurable maximum size
• Why: In-memory storage provides fast access times and avoids the complexity of database management
• Alternatives considered:
  • Database storage: Adds complexity and latency
  • File system: Not suitable for real-time access

Decision: Command Validation

• What: Implement basic command validation on both frontend and backend
• Why: Frontend validation provides immediate feedback to users, while backend validation ensures data integrity
• Alternatives considered:
  • Only frontend validation: Less secure, as users could bypass it
  • Only backend validation: Less responsive, as users would have to wait for server response

Architecture

Frontend Architecture

CommandView Component
├── CommandForm Component
├── CommandHistory Component
└── CommandService

Backend Architecture

Command Routes
├── Command Service
│   ├── Redis Client
│   └── Command Manager
└── Command History Manager

Implementation Details

Redis Connection

• Use the redis npm package to connect to Redis
• Implement automatic reconnection with exponential backoff
• Handle connection errors gracefully

Command Sending

1. User enters a command in the frontend form
2. Frontend validates the command (not empty, no invalid characters)
3. Frontend sends a POST request to /api/commands with the command content
4. Backend validates the command again
5. Backend generates a unique command ID
6. Backend adds the command to the Redis queue using LPUSH
7. Backend stores the command in the in-memory command history
8. Backend sends a success response to the frontend

Command Validation

• Frontend validation:
  • Check that the command is not empty
  • Check that the command does not contain invalid characters (e.g., null bytes)
  • Limit command length to 1024 characters
• Backend validation:
  • Same checks as frontend
  • Additional server-side validation if needed

Command History

• Store command history in an array in memory
• Implement a circular buffer to limit memory usage
• Default maximum command count: 1000
• Configurable via environment variable
• Include command ID, content, timestamp, and status

Command Response Handling

1. Receiving program reads the command from the Redis queue
2. Receiving program executes the command
3. Receiving program writes the response to a separate Redis queue
4. Backend listens for responses on the response queue using BLPOP
5. When a response is received, backend updates the command status in the history
6. Backend notifies the frontend of the response via Server-Sent Events (SSE)

Risks / Trade-offs

Risk: Redis Connection Failure

• Risk: If Redis connection is lost, commands won't be sent
• Mitigation: Implement automatic reconnection with exponential backoff, and notify users when connection is lost

Risk: Command Loss

• Risk: Commands could be lost if Redis goes down
• Mitigation: Implement Redis persistence (RDB or AOF) to ensure commands are not lost

Risk: Command Response Timeout

• Risk: Commands could take too long to execute, causing the UI to hang
• Mitigation: Implement a timeout mechanism for command responses, and show a loading indicator to users

Migration Plan

No migration is required as this is a new feature.

Open Questions

• What is the expected maximum command frequency per minute?
• Should we add support for command templates or macros?
• Should we implement command scheduling for future execution?