0
# Runtime Libraries
1

2
The jsii runtime system enables execution of jsii assemblies across different programming languages. It consists of a JavaScript runtime host, kernel for assembly execution, and language-specific client implementations for Python, Java, .NET, and Go.
3

4
## Capabilities
5

6
### JavaScript Runtime Host
7

8
The main runtime host that manages kernel processes and provides IO communication for jsii API exchanges.
9

10
```typescript { .api }
11
/**
12
 * Main runtime host for kernel communication
13
 */
14
class KernelHost {
15
  /**
16
   * Start the kernel host process
17
   * @returns Promise that resolves when host is ready
18
   */
19
  run(): Promise<void>;
20

21
  /**
22
   * Stop the kernel host and cleanup resources
23
   * @returns Promise that resolves when cleanup is complete
24
   */
25
  close(): Promise<void>;
26
}
27

28
/**
29
 * IO provider interface for jsii API exchanges
30
 */
31
interface IInputOutput {
32
  /**
33
   * Read input from the communication channel
34
   * @returns Input message or exit signal
35
   */
36
  read(): Input | Exit;
37

38
  /**
39
   * Write output to the communication channel
40
   * @param output Output message to write
41
   */
42
  write(output: Output): void;
43
}
44

45
/**
46
 * Standard implementation using synchronous stdio
47
 */
48
class InputOutput implements IInputOutput {
49
  /**
50
   * Create new InputOutput instance
51
   * @param stdio Optional custom stdio implementation
52
   */
53
  constructor(stdio?: SyncStdio);
54

55
  read(): Input | Exit;
56
  write(output: Output): void;
57
}
58

59
/**
60
 * Synchronous stdio operations
61
 */
62
class SyncStdio {
63
  /**
64
   * Read line from stdin synchronously
65
   */
66
  readLine(): string | null;
67

68
  /**
69
   * Write line to stdout
70
   */
71
  writeLine(line: string): void;
72

73
  /**
74
   * Write line to stderr
75
   */
76
  writeErrorLine(line: string): void;
77
}
78
```
79

80
### Kernel Execution Engine
81

82
The core execution kernel that loads jsii assemblies and handles method invocations across language boundaries.
83

84
```typescript { .api }
85
/**
86
 * Main jsii kernel for loading and executing assemblies
87
 */
88
class Kernel {
89
  /**
90
   * Create new kernel instance
91
   * @param callbackHandler Handler for callback requests
92
   */
93
  constructor(callbackHandler?: (callback: api.Callback) => any);
94

95
  /**
96
   * Load a jsii assembly into the kernel
97
   * @param request Assembly load request
98
   * @returns Load response with assembly information
99
   */
100
  load(request: api.LoadRequest): api.LoadResponse;
101

102
  /**
103
   * Create an instance of a jsii class
104
   * @param request Object creation request
105
   * @returns Object reference for the created instance
106
   */
107
  create(request: api.CreateRequest): api.CreateResponse;
108

109
  /**
110
   * Delete an object reference
111
   * @param request Object deletion request
112
   * @returns Deletion confirmation
113
   */
114
  del(request: api.DelRequest): api.DelResponse;
115

116
  /**
117
   * Get property value from an object
118
   * @param request Property access request
119
   * @returns Property value
120
   */
121
  get(request: api.GetRequest): api.GetResponse;
122

123
  /**
124
   * Get static property value from a class
125
   * @param request Static property access request  
126
   * @returns Property value
127
   */
128
  sget(request: api.StaticGetRequest): api.GetResponse;
129

130
  /**
131
   * Set property value on an object
132
   * @param request Property assignment request
133
   * @returns Assignment confirmation
134
   */
135
  set(request: api.SetRequest): api.SetResponse;
136

137
  /**
138
   * Set static property value on a class
139
   * @param request Static property assignment request
140
   * @returns Assignment confirmation  
141
   */
142
  sset(request: api.StaticSetRequest): api.SetResponse;
143

144
  /**
145
   * Invoke method on an object
146
   * @param request Method invocation request
147
   * @returns Method result
148
   */
149
  invoke(request: api.InvokeRequest): api.GetResponse;
150

151
  /**
152
   * Invoke static method on a class
153
   * @param request Static method invocation request
154
   * @returns Method result
155
   */
156
  sinvoke(request: api.StaticInvokeRequest): api.GetResponse;
157

158
  /**
159
   * Execute arbitrary script in the kernel
160
   * @param request Script execution request
161
   * @returns Script result
162
   */
163
  invokeBinScript(request: api.InvokeScriptRequest): api.InvokeScriptResponse;
164

165
  /**
166
   * Get available bin script commands
167
   * @param request Script command request
168
   * @returns Available commands
169
   */
170
  getBinScriptCommand(request: api.GetScriptCommandRequest): api.GetScriptCommandResponse;
171
}
172
```
173

174
### Kernel API
175

176
Complete API interface definitions for kernel communication protocols and data structures.
177

178
```typescript { .api }
179
namespace api {
180
  /**
181
   * Request to load an assembly into the kernel
182
   */
183
  interface LoadRequest {
184
    /** Assembly name */
185
    name: string;
186
    /** Assembly version */
187
    version: string;
188
    /** Optional tarball path for assembly */
189
    tarball?: string;
190
  }
191

192
  /**
193
   * Response from assembly loading
194
   */
195
  interface LoadResponse {
196
    /** Loaded assembly name */
197
    assembly: string;
198
    /** Assembly types */
199
    types: number;
200
  }
201

202
  /**
203
   * Request to create object instance
204
   */
205
  interface CreateRequest {
206
    /** Fully qualified class name */
207
    fqn: string;
208
    /** Constructor arguments */
209
    args?: any[];
210
    /** Method/property overrides */
211
    overrides?: Override[];
212
    /** Interface implementations */
213
    interfaces?: string[];
214
  }
215

216
  /**
217
   * Response with object reference
218
   */
219
  type CreateResponse = ObjRef;
220

221
  /**
222
   * Request to delete object
223
   */
224
  interface DelRequest {
225
    /** Object reference to delete */
226
    objref: ObjRef;
227
  }
228

229
  /**
230
   * Delete confirmation response
231
   */
232
  interface DelResponse {
233
    /** Success confirmation */
234
    deleted: boolean;
235
  }
236

237
  /**
238
   * Request to get property value
239
   */
240
  interface GetRequest {
241
    /** Object reference */
242
    objref: ObjRef;
243
    /** Property name */
244
    property: string;
245
  }
246

247
  /**
248
   * Request to get static property
249
   */
250
  interface StaticGetRequest {
251
    /** Fully qualified class name */
252
    fqn: string;
253
    /** Static property name */
254
    property: string;
255
  }
256

257
  /**
258
   * Property value response
259
   */
260
  interface GetResponse {
261
    /** Property value */
262
    value?: any;
263
  }
264

265
  /**
266
   * Request to set property value
267
   */
268
  interface SetRequest {
269
    /** Object reference */
270
    objref: ObjRef;
271
    /** Property name */
272
    property: string;
273
    /** New property value */
274
    value?: any;
275
  }
276

277
  /**
278
   * Request to set static property
279
   */
280
  interface StaticSetRequest {
281
    /** Fully qualified class name */
282
    fqn: string;
283
    /** Static property name */
284
    property: string;
285
    /** New property value */
286
    value?: any;
287
  }
288

289
  /**
290
   * Set property confirmation response
291
   */
292
  interface SetResponse {}
293

294
  /**
295
   * Request to invoke method
296
   */
297
  interface InvokeRequest {
298
    /** Object reference */
299
    objref: ObjRef;
300
    /** Method name */
301
    method: string;
302
    /** Method arguments */
303
    args?: any[];
304
  }
305

306
  /**
307
   * Request to invoke static method
308
   */
309
  interface StaticInvokeRequest {
310
    /** Fully qualified class name */
311
    fqn: string;
312
    /** Static method name */  
313
    method: string;
314
    /** Method arguments */
315
    args?: any[];
316
  }
317

318
  /**
319
   * Hello message from kernel
320
   */
321
  interface HelloResponse {
322
    /** Kernel hello message */
323
    hello: string;
324
  }
325

326
  /**
327
   * Script execution request
328
   */
329
  interface InvokeScriptRequest {
330
    /** Script command */
331
    command: string;
332
    /** Script arguments */
333
    args: string[];
334
  }
335

336
  /**
337
   * Script execution response
338
   */
339
  interface InvokeScriptResponse {
340
    /** Exit code */
341
    exit?: number;
342
    /** Script output */
343
    stdout?: string;
344
    /** Script errors */
345
    stderr?: string;
346
  }
347

348
  /**
349
   * Get script command request
350
   */
351
  interface GetScriptCommandRequest {
352
    /** Command name */
353
    command: string;
354
  }
355

356
  /**
357
   * Script command information response  
358
   */
359
  interface GetScriptCommandResponse {
360
    /** Command executable path */
361
    command?: string;
362
  }
363
}
364
```
365

366
### Serialization Protocol
367

368
Object serialization and wire format for cross-language communication.
369

370
```typescript { .api }
371
/**
372
 * Token constants for object serialization
373
 */
374
const TOKEN_REF = "$jsii.byref";
375
const TOKEN_INTERFACES = "$jsii.interfaces";
376
const TOKEN_DATE = "$jsii.date";
377
const TOKEN_ENUM = "$jsii.enum";
378
const TOKEN_MAP = "$jsii.map";
379
const TOKEN_STRUCT = "$jsii.struct";
380

381
/**
382
 * Object reference with serialization token
383
 */
384
interface ObjRef {
385
  /** Reference token */
386
  [TOKEN_REF]: string;
387
  /** Implemented interfaces */
388
  [TOKEN_INTERFACES]?: string[];
389
}
390

391
/**
392
 * Serialized date object for cross-language transfer
393
 */
394
interface WireDate {
395
  /** Date token */
396
  [TOKEN_DATE]: string;
397
}
398

399
/**
400
 * Serialized enum value
401
 */
402
interface WireEnum {
403
  /** Enum token */
404
  [TOKEN_ENUM]: string;
405
}
406

407
/**
408
 * Serialized map object
409
 */
410
interface WireMap {
411
  /** Map token */
412
  [TOKEN_MAP]: { [key: string]: any };
413
}
414

415
/**
416
 * Serialized struct (data-only interface)
417
 */
418
interface WireStruct {
419
  /** Struct token */  
420
  [TOKEN_STRUCT]: string;
421
  /** Struct data */
422
  [key: string]: any;
423
}
424
```
425

426
### Override System
427

428
Method and property override system for inheritance and interface implementation.
429

430
```typescript { .api }
431
/**
432
 * Method or property override definition
433
 */
434
type Override = MethodOverride | PropertyOverride;
435

436
/**
437
 * Method override specification  
438
 */
439
interface MethodOverride {
440
  /** Method name to override */
441
  method: string;
442
  /** Callback cookie for identification */
443
  cookie?: string;
444
}
445

446
/**
447
 * Property override specification
448
 */
449
interface PropertyOverride {
450
  /** Property name to override */
451
  property: string;
452
  /** Callback cookie for identification */
453
  cookie?: string;
454
}
455

456
/**
457
 * Callback request structure for overrides
458
 */
459
interface Callback {
460
  /** Callback identifier */
461
  cbid: string;
462
  /** Callback cookie */
463
  cookie?: string;
464
  /** Callback result */
465
  result?: any;
466
  /** Callback error */
467
  err?: string;
468
}
469
```
470

471
### Error Handling
472

473
Error types and exception handling for kernel operations.
474

475
```typescript { .api }
476
/**
477
 * Types of jsii errors
478
 */
479
enum JsiiErrorType {
480
  /** Internal jsii fault */
481
  JSII_FAULT = "@jsii/kernel.Fault", 
482
  /** Runtime execution error */
483
  RUNTIME_ERROR = "@jsii/kernel.RuntimeError"
484
}
485

486
/**
487
 * Base interface for jsii errors
488
 */
489
interface JsiiError {
490
  /** Error type discriminator */
491
  name: JsiiErrorType;
492
  /** Error message */
493
  message: string;
494
  /** Error stack trace */
495
  stack?: string;
496
}
497

498
/**
499
 * Fault error for kernel issues
500
 */
501
class JsiiFault extends Error implements JsiiError {
502
  readonly name = JsiiErrorType.JSII_FAULT;
503

504
  /**
505
   * Create new jsii fault
506
   * @param message Error message
507
   */
508
  constructor(message: string);
509
}
510

511
/**
512
 * Runtime error for execution issues
513
 */
514
class RuntimeError extends Error implements JsiiError {
515
  readonly name = JsiiErrorType.RUNTIME_ERROR;
516

517
  /**
518
   * Create new runtime error
519
   * @param message Error message  
520
   */
521
  constructor(message: string);
522
}
523
```
524

525
### Type Guards and Utilities
526

527
Helper functions for type checking and wire format validation.
528

529
```typescript { .api }
530
/**
531
 * Type guard for object references
532
 */
533
function isObjRef(value: any): value is ObjRef;
534

535
/**
536
 * Type guard for wire date objects
537
 */
538
function isWireDate(value: any): value is WireDate;
539

540
/**
541
 * Type guard for wire enum objects
542
 */
543
function isWireEnum(value: any): value is WireEnum;
544

545
/**
546
 * Type guard for wire map objects  
547
 */
548
function isWireMap(value: any): value is WireMap;
549

550
/**
551
 * Type guard for wire struct objects
552
 */
553
function isWireStruct(value: any): value is WireStruct;
554

555
/**
556
 * Type guard for method overrides
557
 */
558
function isMethodOverride(override: Override): override is MethodOverride;
559

560
/**
561
 * Type guard for property overrides  
562
 */
563
function isPropertyOverride(override: Override): override is PropertyOverride;
564
```
565

566
## Types
567

568
```typescript { .api }
569
/**
570
 * Input message types for kernel communication
571
 */
572
type Input = 
573
  | api.LoadRequest
574
  | api.CreateRequest
575
  | api.DelRequest
576
  | api.GetRequest
577
  | api.StaticGetRequest
578
  | api.SetRequest
579
  | api.StaticSetRequest
580
  | api.InvokeRequest
581
  | api.StaticInvokeRequest
582
  | api.InvokeScriptRequest
583
  | api.GetScriptCommandRequest;
584

585
/**
586
 * Output message types from kernel
587
 */
588
type Output =
589
  | api.HelloResponse
590
  | api.LoadResponse
591
  | api.CreateResponse
592
  | api.DelResponse
593
  | api.GetResponse
594
  | api.SetResponse
595
  | api.InvokeScriptResponse
596
  | api.GetScriptCommandResponse;
597

598
/**
599
 * Exit signal type
600
 */
601
interface Exit {
602
  /** Exit code */
603
  exit: number;
604
}
605
```
606

607
**Usage Examples:**
608

609
```typescript
610
// Setting up a kernel host
611
import { KernelHost, InputOutput } from '@jsii/runtime';
612

613
const host = new KernelHost();
614
const io = new InputOutput();
615

616
// Start the host
617
await host.run();
618

619
// Load an assembly
620
import { Kernel, api } from '@jsii/kernel';
621

622
const kernel = new Kernel();
623
const loadResponse = kernel.load({
624
  name: 'my-jsii-lib',
625
  version: '1.0.0'
626
});
627

628
// Create an object instance  
629
const objRef = kernel.create({
630
  fqn: 'my-jsii-lib.MyClass',
631
  args: ['constructor-arg']
632
});
633

634
// Call a method
635
const result = kernel.invoke({
636
  objref: objRef,
637
  method: 'myMethod',
638
  args: ['arg1', 'arg2']
639
});
640

641
// Clean up
642
kernel.del({ objref: objRef });
643
await host.close();
644
```