@alineo-labs/sandbox 0.4.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { BashSession, CheckpointInfo, CommandError, CredentialBinding, CredentialBroker, CredentialBroker as CredentialBroker$1, CredentialResolver, DiagnosticEvent, DiagnosticLog, EnvironmentRecord, EnvironmentRecord as EnvironmentRecord$1, EnvironmentRecord as EnvironmentRecord$2, ExecCodeOptions, ExecConnectionError, ExecHandle, ExecOptions, ExecResult, FileInfo, IStorageAdapter, IStorageAdapter as IStorageAdapter$1, InteractiveExecHandle, LedgerEntry, LedgerEvent, ListSandboxOptions, ListSandboxOptions as ListSandboxOptions$1, Metrics, PendingInteractiveExec, SandboxDetails, SandboxDetails as SandboxDetails$1, SandboxError, SandboxHandle, SandboxHandle as SandboxHandle$1, SandboxHooks, SandboxStatus, StepTimeoutError } from "@alineo-labs/core";
2
2
  import { CodeLanguage, CredentialProxyConfig, NetworkPolicy, NetworkPolicy as NetworkPolicy$1, NetworkRule } from "@alineo-labs/opensandbox";
3
3
  import { OpenSandboxCredentialBroker } from "@alineo-labs/vault";
4
+ import { LedgerEnvelope } from "@alineo-labs/schema/types";
4
5
  //#region src/types.d.ts
5
6
  /**
6
7
  * Client-side SDK error carrying an HTTP-style status code, thrown for
@@ -27,6 +28,18 @@ interface SandboxClientOptions {
27
28
  * `new PostgresAdapter(connectionString)` from `@alineo-labs/postgres` for production.
28
29
  */
29
30
  adapter: IStorageAdapter$1;
31
+ /**
32
+ * Receives a `LedgerEnvelope` for every event any sandbox from this client emits, beside
33
+ * the ledger write.
34
+ *
35
+ * Synchronous and must not throw — it runs on the write path of a sandbox operation, so an
36
+ * async sink would become backpressure and a throwing one would fail the very operation
37
+ * being recorded. A sink that needs IO buffers internally and flushes on its own schedule.
38
+ *
39
+ * @internal The ledger is the system of record and a sink is an export path; the public
40
+ * shape of this belongs with the work that owns export.
41
+ */
42
+ sink?: (envelope: LedgerEnvelope) => void;
30
43
  /**
31
44
  * Maximum number of sandboxes that may be active simultaneously.
32
45
  * When at capacity, `sandbox()` awaits until a slot is free.
@@ -280,6 +293,7 @@ export declare class Environment {
280
293
  export declare class Sandbox {
281
294
  private readonly _control;
282
295
  private readonly _adapter;
296
+ private readonly _sink;
283
297
  private readonly _credentialBroker;
284
298
  private readonly _maxConcurrency;
285
299
  private readonly _useServerProxy;
@@ -288,6 +302,15 @@ export declare class Sandbox {
288
302
  private _connectPromise;
289
303
  private _adapterClosed;
290
304
  private readonly _envBuilds;
305
+ /**
306
+ * The five `sandbox.created` writes below do not go through `SandboxCore.emit()` — the
307
+ * handle does not exist yet when they happen. This is their shared funnel, so a sink is
308
+ * attached to all five or none, rather than to four of them.
309
+ *
310
+ * The sink runs before the append for the same reason it does in `emit()`: an exporter
311
+ * must not delay, or fail, the write it is exporting.
312
+ */
313
+ private _append;
291
314
  constructor(options: SandboxClientOptions);
292
315
  /** Lazily initialises the adapter on first use. Concurrent callers share the same promise. */
293
316
  private _ensureConnected;
@@ -351,7 +374,7 @@ export declare class Sandbox {
351
374
  * @param opts.runId Default run-correlation ID for any later `.fork()` call on the
352
375
  * returned `SandboxHandle`. `connect()` has no way to discover the sandbox's original
353
376
  * `runId` (no ledger lookup is attempted — the caller may be using a completely
354
- * different adapter than whatever originally created it, as `alineo fork` does when
377
+ * different adapter than whatever originally created it, as `alineo spawn` does when
355
378
  * self-attaching). Omit this and pass `runId` explicitly to `.fork()` itself instead.
356
379
  *
357
380
  * @example
package/dist/index.mjs CHANGED
@@ -113,6 +113,7 @@ function assertValidNetworkPolicy(policy) {
113
113
  var Sandbox = class {
114
114
  _control;
115
115
  _adapter;
116
+ _sink;
116
117
  _credentialBroker;
117
118
  _maxConcurrency;
118
119
  _useServerProxy;
@@ -121,12 +122,38 @@ var Sandbox = class {
121
122
  _connectPromise = null;
122
123
  _adapterClosed = false;
123
124
  _envBuilds = /* @__PURE__ */ new Map();
125
+ /**
126
+ * The five `sandbox.created` writes below do not go through `SandboxCore.emit()` — the
127
+ * handle does not exist yet when they happen. This is their shared funnel, so a sink is
128
+ * attached to all five or none, rather than to four of them.
129
+ *
130
+ * The sink runs before the append for the same reason it does in `emit()`: an exporter
131
+ * must not delay, or fail, the write it is exporting.
132
+ */
133
+ async _append(entry) {
134
+ if (this._sink) try {
135
+ this._sink({
136
+ v: 1,
137
+ ts: entry.ts,
138
+ type: entry.event,
139
+ ...typeof entry.payload?.runId === "string" ? { runId: entry.payload.runId } : {},
140
+ data: {
141
+ sandboxId: entry.sandboxId,
142
+ name: entry.name,
143
+ stepIndex: entry.stepIndex,
144
+ payload: entry.payload
145
+ }
146
+ });
147
+ } catch {}
148
+ await this._adapter.append(entry);
149
+ }
124
150
  constructor(options) {
125
151
  this._control = new ControlClient({
126
152
  baseUrl: options.baseUrl,
127
153
  apiKey: options.apiKey ?? ""
128
154
  });
129
155
  this._adapter = options.adapter;
156
+ this._sink = options.sink;
130
157
  this._maxConcurrency = options.maxConcurrency;
131
158
  this._useServerProxy = options.useServerProxy ?? false;
132
159
  this._credentialBroker = options.credentialBroker ?? new OpenSandboxCredentialBroker$1(this._control, this._useServerProxy);
@@ -189,7 +216,7 @@ var Sandbox = class {
189
216
  })).id;
190
217
  await this._waitForRunning(sandboxId);
191
218
  const name = opts.name ?? `sandbox-${sandboxId.slice(0, 8)}`;
192
- await this._adapter.append({
219
+ await this._append({
193
220
  ts: Date.now(),
194
221
  name,
195
222
  sandboxId,
@@ -208,6 +235,7 @@ var Sandbox = class {
208
235
  const sb = new SandboxHandle$1(sandboxId, name, {
209
236
  control: this._control,
210
237
  adapter: this._adapter,
238
+ sink: this._sink,
211
239
  credentialBroker: this._credentialBroker,
212
240
  hooks: opts.hooks,
213
241
  onClose: () => {
@@ -331,7 +359,7 @@ var Sandbox = class {
331
359
  credentialProxy: credentialProxy ? { enabled: true } : void 0
332
360
  })).id;
333
361
  await this._waitForRunning(newSessionId);
334
- await this._adapter.append({
362
+ await this._append({
335
363
  ts: Date.now(),
336
364
  name,
337
365
  sandboxId: newSessionId,
@@ -351,6 +379,7 @@ var Sandbox = class {
351
379
  const sb = new SandboxHandle$1(newSessionId, name, {
352
380
  control: this._control,
353
381
  adapter: this._adapter,
382
+ sink: this._sink,
354
383
  credentialBroker: this._credentialBroker,
355
384
  onClose: () => {
356
385
  this._releaseSlot();
@@ -385,7 +414,7 @@ var Sandbox = class {
385
414
  * @param opts.runId Default run-correlation ID for any later `.fork()` call on the
386
415
  * returned `SandboxHandle`. `connect()` has no way to discover the sandbox's original
387
416
  * `runId` (no ledger lookup is attempted — the caller may be using a completely
388
- * different adapter than whatever originally created it, as `alineo fork` does when
417
+ * different adapter than whatever originally created it, as `alineo spawn` does when
389
418
  * self-attaching). Omit this and pass `runId` explicitly to `.fork()` itself instead.
390
419
  *
391
420
  * @example
@@ -406,6 +435,7 @@ var Sandbox = class {
406
435
  const handle = new SandboxHandle$1(sandboxId, name, {
407
436
  control: this._control,
408
437
  adapter: this._adapter,
438
+ sink: this._sink,
409
439
  credentialBroker: this._credentialBroker,
410
440
  onClose: () => {
411
441
  this._releaseSlot();
@@ -455,7 +485,7 @@ var Sandbox = class {
455
485
  credentialProxy: opts?.credentialProxy ? { enabled: true } : void 0
456
486
  })).id;
457
487
  await this._waitForRunning(newId);
458
- await this._adapter.append({
488
+ await this._append({
459
489
  ts: Date.now(),
460
490
  name,
461
491
  sandboxId: newId,
@@ -474,6 +504,7 @@ var Sandbox = class {
474
504
  return new SandboxHandle$1(newId, name, {
475
505
  control: this._control,
476
506
  adapter: this._adapter,
507
+ sink: this._sink,
477
508
  credentialBroker: this._credentialBroker,
478
509
  onClose: () => {
479
510
  this._releaseSlot();
@@ -632,7 +663,7 @@ var Sandbox = class {
632
663
  const sessionName = `env-${envName}-${newId.slice(0, 8)}`;
633
664
  const resourceId = extra?.resourceId;
634
665
  const teamId = extra?.teamId;
635
- await this._adapter.append({
666
+ await this._append({
636
667
  ts: Date.now(),
637
668
  name: sessionName,
638
669
  sandboxId: newId,
@@ -650,6 +681,7 @@ var Sandbox = class {
650
681
  const sb = new SandboxHandle$1(newId, sessionName, {
651
682
  control: this._control,
652
683
  adapter: this._adapter,
684
+ sink: this._sink,
653
685
  credentialBroker: this._credentialBroker,
654
686
  hooks: extra?.hooks,
655
687
  onClose: () => {
@@ -681,7 +713,7 @@ var Sandbox = class {
681
713
  })).id;
682
714
  await this._waitForRunning(newId);
683
715
  const sessionName = `fork-${parentName}-${newId.slice(0, 8)}`;
684
- await this._adapter.append({
716
+ await this._append({
685
717
  ts: Date.now(),
686
718
  name: sessionName,
687
719
  sandboxId: newId,
@@ -701,6 +733,7 @@ var Sandbox = class {
701
733
  return new SandboxHandle$1(newId, sessionName, {
702
734
  control: this._control,
703
735
  adapter: this._adapter,
736
+ sink: this._sink,
704
737
  credentialBroker: this._credentialBroker,
705
738
  onClose: () => {
706
739
  this._releaseSlot();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alineo-labs/sandbox",
3
- "version": "0.4.2",
3
+ "version": "0.5.0",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -29,9 +29,10 @@
29
29
  "test:watch": "vitest"
30
30
  },
31
31
  "dependencies": {
32
- "@alineo-labs/core": "0.4.1",
33
- "@alineo-labs/opensandbox": "0.3.0",
34
- "@alineo-labs/vault": "0.3.1"
32
+ "@alineo-labs/core": "0.5.0",
33
+ "@alineo-labs/opensandbox": "0.3.2",
34
+ "@alineo-labs/schema": "0.2.0",
35
+ "@alineo-labs/vault": "0.3.3"
35
36
  },
36
37
  "devDependencies": {
37
38
  "bun-types": "1.4.2",