Skip to content

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

typescript
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

  1. Initialization:

    • Scans all modules for script controllers and their methods.
    • Registers commands in the commands map using the format namespace:method.
  2. Server Startup:

    • Starts a TCP server on the configured port and hostname.
    • Handles new connections, disconnections, incoming data, and errors.
  3. 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.

Released under the Apache-2.0 License.