0
# Runner Execution
1

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

4
## Core Imports
5

6
```typescript
7
import { Runner } from "@scramjet/runner";
8
```
9

10
## Capabilities
11

12
### Runner Class
13

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

16
```typescript { .api }
17
/**
18
 * Runtime environment for sequence code.
19
 * Communicates with Host with data transferred to/from Sequence, health info,
20
 * reacts to control messages such as stopping etc.
21
 */
22
class Runner<X extends AppConfig> implements IComponent {
23
  constructor(
24
    sequencePath: string,
25
    hostClient: IHostClient,
26
    instanceId: string,
27
    sequenceInfo: SequenceInfo,
28
    runnerConnectInfo: RunnerConnectInfo
29
  );
30
  
31
  /** Logger instance for the runner */
32
  logger: IObjectLogger;
33
  
34
  /** Application context for sequences (throws if accessed before initialization) */
35
  readonly context: RunnerAppContext<X, any>;
36
  
37
  /** Handshake promise resolver for host communication */
38
  handshakeResolver?: { res: Function; rej: Function };
39
  
40
  /** Output stream reference with topic information */
41
  instanceOutput?: Readable & HasTopicInformation | void;
42
}
43
```
44

45
**Usage Note:**
46

47
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.
48

49
### Main Execution
50

51
Primary execution method that handles the complete sequence lifecycle.
52

53
```typescript { .api }
54
/**
55
 * Main execution method that initializes connection, loads sequence, and runs it
56
 * @returns Promise that resolves when sequence completes or rejects on error
57
 */
58
main(): Promise<void>;
59
```
60

61
### Pre-execution Setup
62

63
Initializes host connection and prepares execution environment.
64

65
```typescript { .api }
66
/**
67
 * Pre-execution setup including host connection, stream initialization, and handshake
68
 * @returns Promise resolving to app configuration and arguments
69
 */
70
premain(): Promise<{ appConfig: AppConfig; args: any }>;
71
```
72

73
### Control Message Handling
74

75
Processes control messages from the Host for managing sequence execution.
76

77
```typescript { .api }
78
/**
79
 * Handle control messages from Host (monitoring rate, kill, stop, pong, events)
80
 * @param message - Encoded control message with code and data
81
 */
82
controlStreamHandler(message: EncodedControlMessage): Promise<void>;
83

84
/**
85
 * Set up control message parsing from host control stream
86
 */
87
defineControlStream(): void;
88
```
89

90
### Monitoring and Health
91

92
Health monitoring and reporting functionality.
93

94
```typescript { .api }
95
/**
96
 * Handle monitoring rate configuration from Host
97
 * @param data - Monitoring rate configuration
98
 */
99
handleMonitoringRequest(data: MonitoringRateMessageData): Promise<void>;
100

101
/**
102
 * Send handshake message to Host with runner information
103
 */
104
sendHandshakeMessage(): void;
105

106
/**
107
 * Wait for handshake acknowledgment from Host
108
 * @returns Promise resolving to handshake acknowledgment data
109
 */
110
waitForHandshakeResponse(): Promise<HandshakeAcknowledgeMessageData>;
111

112
/**
113
 * Send PANG message to Host with input/output requirements
114
 * @param args - PANG message data with requirements and content types
115
 */
116
sendPang(args: PangMessageData): void;
117
```
118

119
### Lifecycle Management
120

121
Methods for handling sequence lifecycle events and cleanup.
122

123
```typescript { .api }
124
/**
125
 * Handle kill request from Host - terminates sequence immediately
126
 */
127
handleKillRequest(): Promise<void>;
128

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

135
/**
136
 * Handle Host disconnection and attempt reconnection
137
 */
138
handleDisconnect(): Promise<void>;
139

140
/**
141
 * Clean up resources and return exit code
142
 * @returns Promise resolving to exit code
143
 */
144
cleanup(): Promise<number>;
145
```
146

147
### Stream Configuration
148

149
Stream setup and content type handling.
150

151
```typescript { .api }
152
/**
153
 * Configure input stream content type and set up data mapping
154
 * @param headers - Headers containing content-type information
155
 */
156
setInputContentType(headers: any): Promise<void>;
157
```
158

159
### Sequence Loading and Execution
160

161
Methods for loading and executing sequence code.
162

163
```typescript { .api }
164
/**
165
 * Load sequence from file system
166
 * @returns Array of application interfaces representing the sequence
167
 */
168
getSequence(): ApplicationInterface[];
169

170
/**
171
 * Execute sequence functions in order with proper stream handling
172
 * @param sequence - Array of sequence functions to execute
173
 * @param args - Arguments to pass to sequence functions
174
 */
175
runSequence(sequence: any[], args?: any[]): Promise<void>;
176
```
177

178
### Application Context Initialization
179

180
Initialize the application context for sequences.
181

182
```typescript { .api }
183
/**
184
 * Initialize app context with configuration and API clients
185
 * @param config - Application configuration
186
 */
187
initAppContext(config: X): void;
188
```
189

190
## Supporting Types
191

192
```typescript { .api }
193
interface MonitoringRateMessageData {
194
  monitoringRate: number;
195
}
196

197
interface StopSequenceMessageData {
198
  timeout: number;
199
  canCallKeepalive: boolean;
200
}
201

202
interface HandshakeAcknowledgeMessageData {
203
  [key: string]: any;
204
}
205

206
interface ApplicationInterface {
207
  requires?: string;
208
  contentType?: string;
209
  (...args: any[]): any;
210
}
211

212
interface HasTopicInformation {
213
  topic?: string;
214
  contentType?: string;
215
}
216

217
enum InstanceStatus {
218
  STARTING = "starting",
219
  RUNNING = "running",
220
  STOPPING = "stopping",
221
  COMPLETED = "completed",
222
  ERRORED = "errored",
223
  KILLING = "killing"
224
}
225

226
enum RunnerExitCode {
227
  STOPPED = 0,
228
  KILLED = 1,
229
  SEQUENCE_FAILED_ON_START = 2,
230
  SEQUENCE_FAILED_DURING_EXECUTION = 3,
231
  UNCAUGHT_EXCEPTION = 4,
232
  CLEANUP_FAILED = 5,
233
  INVALID_ENV_VARS = 6,
234
  INVALID_SEQUENCE_PATH = 7
235
}
236
```