Scripts Module
This file defines the Scripts
class, which manages the CLI scripts server in the @sodacore/core
library. It discovers script controllers and their commands, starts a TCP server for CLI connections, handles incoming requests, and manages command execution and authentication.
Features
- Script Discovery: Scans all registered modules for script controllers and their commands.
- TCP Server: Starts a TCP server (using Bun) to handle CLI script connections.
- Command Routing: Maps incoming commands to their corresponding controller methods.
- Authentication: Ensures only authenticated sockets can execute commands (except internal commands).
- Connection Management: Tracks active connections and handles connection lifecycle events.
- Error Handling: Handles invalid packets, unknown commands, and execution errors gracefully.
Usage
import Scripts from './module/scripts';
const scripts = new Scripts(config);
await scripts.init();
await scripts.start();
// ... later
await scripts.stop();
API
Properties
- shouldStart:
boolean
Indicates whether the CLI server should be started. - server:
TCPSocketListener<IScriptSocketData> | undefined
The TCP server instance. - connections:
Map<symbol, Socket<IScriptSocketData>>
Map of active socket connections. - commands:
Record<string, { module: any, key: string }>
Map of available script commands and their handlers.
Methods
async init(): Promise<void>
Scans all modules in the Registry
for script controllers and their commands. Populates the commands
map and determines if the CLI server should be started based on configuration.
async start(): Promise<void>
Starts the CLI scripts TCP server if enabled. Handles connection events (open
, close
, data
, drain
, error
) and manages socket state.
async stop(): Promise<void>
Stops the CLI scripts TCP server and cleans up resources.
hasScripts(): boolean
Returns whether the CLI server should be started.
getCommands(): string[]
Returns a list of all registered script command names.
private async handle(socket: Socket<IScriptSocketData>, data: string): Promise<void>
Handles incoming data from a socket:
- Parses the packet.
- Validates the command and authentication.
- Executes the corresponding command method with a new
ScriptContext
. - Handles and responds to errors or command results.
How It Works
Initialization:
- Scans all modules for script controllers and their methods.
- Registers commands in the
commands
map using the formatnamespace:method
.
Server Startup:
- Starts a TCP server on the configured port and hostname.
- Handles new connections, disconnections, incoming data, and errors.
Command Handling:
- Parses incoming packets and routes commands to the appropriate controller method.
- Ensures only authenticated sockets can execute commands (except internal commands prefixed with
_:
). - Sends responses or error messages back to the client.
Notes
- Script controllers and methods must be registered using the appropriate decorators to be discovered.
- The server uses Bun's TCP server API for high-performance networking.
- Error handling is robust, ensuring clients receive meaningful feedback on failures.
- The
ScriptContext
object is passed to each command method, providing access to logging, session, and prompt helpers.