tessl/npm-scramjet--runner

Runtime environment for sequence execution and communication with Transform Hub host.

—

Pending

Overview

Eval results

Files

Runner Execution

Name: tessl/npm-scramjet--runner
Author: tessl

The Runner class is the core execution engine that manages the complete lifecycle of data transformation sequences, including initialization, execution, monitoring, and cleanup.

Core Imports

import { Runner } from "@scramjet/runner";

Capabilities

Runner Class

Core runtime environment for sequence code that communicates with Host and manages data transfer, health monitoring, and control message handling.

/**
 * Runtime environment for sequence code.
 * Communicates with Host with data transferred to/from Sequence, health info,
 * reacts to control messages such as stopping etc.
 */
class Runner<X extends AppConfig> implements IComponent {
  constructor(
    sequencePath: string,
    hostClient: IHostClient,
    instanceId: string,
    sequenceInfo: SequenceInfo,
    runnerConnectInfo: RunnerConnectInfo
  );
  
  /** Logger instance for the runner */
  logger: IObjectLogger;
  
  /** Application context for sequences (throws if accessed before initialization) */
  readonly context: RunnerAppContext<X, any>;
  
  /** Handshake promise resolver for host communication */
  handshakeResolver?: { res: Function; rej: Function };
  
  /** Output stream reference with topic information */
  instanceOutput?: Readable & HasTopicInformation | void;
}

Usage Note:

The Runner class is typically instantiated by the Scramjet Transform Hub infrastructure rather than directly by user code. The HostClient and other dependencies are provided by the runtime environment.

Main Execution

Primary execution method that handles the complete sequence lifecycle.

/**
 * Main execution method that initializes connection, loads sequence, and runs it
 * @returns Promise that resolves when sequence completes or rejects on error
 */
main(): Promise<void>;

Pre-execution Setup

Initializes host connection and prepares execution environment.

/**
 * Pre-execution setup including host connection, stream initialization, and handshake
 * @returns Promise resolving to app configuration and arguments
 */
premain(): Promise<{ appConfig: AppConfig; args: any }>;

Control Message Handling

Processes control messages from the Host for managing sequence execution.

/**
 * Handle control messages from Host (monitoring rate, kill, stop, pong, events)
 * @param message - Encoded control message with code and data
 */
controlStreamHandler(message: EncodedControlMessage): Promise<void>;

/**
 * Set up control message parsing from host control stream
 */
defineControlStream(): void;

Monitoring and Health

Health monitoring and reporting functionality.

/**
 * Handle monitoring rate configuration from Host
 * @param data - Monitoring rate configuration
 */
handleMonitoringRequest(data: MonitoringRateMessageData): Promise<void>;

/**
 * Send handshake message to Host with runner information
 */
sendHandshakeMessage(): void;

/**
 * Wait for handshake acknowledgment from Host
 * @returns Promise resolving to handshake acknowledgment data
 */
waitForHandshakeResponse(): Promise<HandshakeAcknowledgeMessageData>;

/**
 * Send PANG message to Host with input/output requirements
 * @param args - PANG message data with requirements and content types
 */
sendPang(args: PangMessageData): void;

Lifecycle Management

Methods for handling sequence lifecycle events and cleanup.

/**
 * Handle kill request from Host - terminates sequence immediately
 */
handleKillRequest(): Promise<void>;

/**
 * Handle stop request from Host - graceful sequence termination
 * @param data - Stop sequence configuration including timeout and keepalive options
 */
addStopHandlerRequest(data: StopSequenceMessageData): Promise<void>;

/**
 * Handle Host disconnection and attempt reconnection
 */
handleDisconnect(): Promise<void>;

/**
 * Clean up resources and return exit code
 * @returns Promise resolving to exit code
 */
cleanup(): Promise<number>;

Stream Configuration

Stream setup and content type handling.

/**
 * Configure input stream content type and set up data mapping
 * @param headers - Headers containing content-type information
 */
setInputContentType(headers: any): Promise<void>;

Sequence Loading and Execution

Methods for loading and executing sequence code.

/**
 * Load sequence from file system
 * @returns Array of application interfaces representing the sequence
 */
getSequence(): ApplicationInterface[];

/**
 * Execute sequence functions in order with proper stream handling
 * @param sequence - Array of sequence functions to execute
 * @param args - Arguments to pass to sequence functions
 */
runSequence(sequence: any[], args?: any[]): Promise<void>;

Application Context Initialization

Initialize the application context for sequences.

/**
 * Initialize app context with configuration and API clients
 * @param config - Application configuration
 */
initAppContext(config: X): void;

Supporting Types

interface MonitoringRateMessageData {
  monitoringRate: number;
}

interface StopSequenceMessageData {
  timeout: number;
  canCallKeepalive: boolean;
}

interface HandshakeAcknowledgeMessageData {
  [key: string]: any;
}

interface ApplicationInterface {
  requires?: string;
  contentType?: string;
  (...args: any[]): any;
}

interface HasTopicInformation {
  topic?: string;
  contentType?: string;
}

enum InstanceStatus {
  STARTING = "starting",
  RUNNING = "running",
  STOPPING = "stopping",
  COMPLETED = "completed",
  ERRORED = "errored",
  KILLING = "killing"
}

enum RunnerExitCode {
  STOPPED = 0,
  KILLED = 1,
  SEQUENCE_FAILED_ON_START = 2,
  SEQUENCE_FAILED_DURING_EXECUTION = 3,
  UNCAUGHT_EXCEPTION = 4,
  CLEANUP_FAILED = 5,
  INVALID_ENV_VARS = 6,
  INVALID_SEQUENCE_PATH = 7
}

Install with Tessl CLI