0
# Host Communication
1

2
The HostClient class manages network connections and data streams between the runner and the Scramjet Transform Hub host, providing multiple communication channels for different types of data.
3

4
## Core Imports
5

6
```typescript
7
import { HostClient } from "@scramjet/runner/src/host-client";
8
```
9

10
## Capabilities
11

12
### HostClient Class
13

14
Connects to Host and exposes streams per channel for comprehensive communication including data transfer, control messages, monitoring, and standard I/O.
15

16
```typescript { .api }
17
/**
18
 * Connects to Host and exposes streams per channel (stdin, monitor etc.)
19
 */
20
class HostClient implements IHostClient {
21
  constructor(instancesServerPort: number, instancesServerHost: string);
22
  
23
  /** Logger instance for host communication */
24
  logger: IObjectLogger;
25
  
26
  /** BPMux multiplexer for HTTP connections */
27
  bpmux: any;
28
  
29
  /** HTTP agent for API connections */
30
  agent?: Agent;
31
}
32
```
33

34
**Usage Example:**
35

36
```typescript
37
import { HostClient } from "@scramjet/runner/src/host-client";
38

39
// Create connection to host
40
const hostClient = new HostClient(3000, "localhost");
41

42
// Initialize connection with instance ID
43
await hostClient.init("instance-123");
44

45
// Use streams for communication
46
hostClient.inputStream.pipe(someProcessor);
47
someOutput.pipe(hostClient.outputStream);
48

49
// Clean disconnect
50
await hostClient.disconnect(false);
51
```
52

53
### Connection Management
54

55
Initialize and manage connections to the Transform Hub host.
56

57
```typescript { .api }
58
/**
59
 * Initialize connection to host with multiple streams
60
 * @param id - Instance identifier (36 bytes)
61
 * @returns Promise that resolves when all connections are established
62
 */
63
init(id: string): Promise<void>;
64

65
/**
66
 * Disconnect from host and clean up all streams
67
 * @param hard - Whether to force close streams without graceful shutdown
68
 * @returns Promise that resolves when disconnection is complete
69
 */
70
disconnect(hard: boolean): Promise<void>;
71

72
/**
73
 * Get HTTP agent for making API calls to host
74
 * @returns HTTP agent configured for host communication
75
 * @throws Error if agent is not initialized
76
 */
77
getAgent(): Agent;
78
```
79

80
### Stream Access
81

82
Access to various communication streams between runner and host.
83

84
```typescript { .api }
85
/**
86
 * Standard input stream from host to sequence
87
 */
88
readonly stdinStream: Readable;
89

90
/**
91
 * Standard output stream from sequence to host
92
 */
93
readonly stdoutStream: Writable;
94

95
/**
96
 * Standard error stream from sequence to host
97
 */
98
readonly stderrStream: Writable;
99

100
/**
101
 * Control message stream from host (JSON messages)
102
 */
103
readonly controlStream: Readable;
104

105
/**
106
 * Monitoring message stream to host (health, status updates)
107
 */
108
readonly monitorStream: Writable;
109

110
/**
111
 * Sequence input data stream from host
112
 */
113
readonly inputStream: Readable;
114

115
/**
116
 * Sequence output data stream to host
117
 */
118
readonly outputStream: Writable;
119

120
/**
121
 * Logging stream to host for structured logs
122
 */
123
readonly logStream: Writable;
124

125
/**
126
 * Package communication stream for API multiplexing
127
 */
128
readonly packageStream: Readable;
129
```
130

131
**Usage Example:**
132

133
```typescript
134
// Read control messages
135
StringStream
136
  .from(hostClient.controlStream)
137
  .JSONParse()
138
  .each(([code, data]) => {
139
    console.log("Control message:", code, data);
140
  });
141

142
// Send monitoring data
143
const monitoringData = [RunnerMessageCode.MONITORING, { healthy: true }];
144
hostClient.monitorStream.write(JSON.stringify(monitoringData) + "\r\n");
145

146
// Process input data
147
hostClient.inputStream
148
  .pipe(new PassThrough())
149
  .on('data', (chunk) => {
150
    console.log("Received data:", chunk.toString());
151
  });
152
```
153

154
## Supporting Types
155

156
```typescript { .api }
157
interface IHostClient {
158
  logger: IObjectLogger;
159
  
160
  init(id: string): Promise<void>;
161
  disconnect(hard: boolean): Promise<void>;
162
  getAgent(): Agent;
163
  
164
  readonly stdinStream: Readable;
165
  readonly stdoutStream: Writable;
166
  readonly stderrStream: Writable;
167
  readonly controlStream: Readable;
168
  readonly monitorStream: Writable;
169
  readonly inputStream: Readable;
170
  readonly outputStream: Writable;
171
  readonly logStream: Writable;
172
  readonly packageStream: Readable;
173
}
174

175
interface UpstreamStreamsConfig extends Array<Socket> {
176
  [index: number]: Socket;
177
}
178

179
enum CommunicationChannel {
180
  IN = 0,
181
  OUT = 1,
182
  CONTROL = 2,
183
  MONITORING = 3,
184
  STDIN = 4,
185
  STDOUT = 5,
186
  STDERR = 6,
187
  LOG = 7,
188
  PACKAGE = 8
189
}
190
```
191

192
## Communication Protocol
193

194
The HostClient uses a multi-stream protocol with dedicated channels:
195

196
1. **Data Streams** (IN/OUT): Sequence input and output data
197
2. **Control Stream**: JSON messages for sequence control (start, stop, kill)
198
3. **Monitoring Stream**: Health status and lifecycle messages
199
4. **Standard I/O**: stdin, stdout, stderr for sequence processes
200
5. **Logging Stream**: Structured logging output
201
6. **Package Stream**: HTTP API multiplexing via BPMux
202

203
All streams use TCP connections with binary protocol multiplexing for HTTP API calls. Control and monitoring messages use JSON format with CRLF line termination.