@alineo-labs/sandbox 0.3.0 → 0.4.1

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,7 +1,6 @@
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
-
5
4
  //#region src/types.d.ts
6
5
  /**
7
6
  * Client-side SDK error carrying an HTTP-style status code, thrown for
@@ -11,7 +10,7 @@ import { OpenSandboxCredentialBroker } from "@alineo-labs/vault";
11
10
  * `OpenSandboxError` from `@alineo-labs/opensandbox`, which is never rethrown as a
12
11
  * `SandboxClientError`.
13
12
  */
14
- declare class SandboxClientError extends Error {
13
+ export declare class SandboxClientError extends Error {
15
14
  readonly status: number;
16
15
  constructor(message: string, status: number);
17
16
  }
@@ -229,13 +228,13 @@ interface EnvironmentSandboxOptions {
229
228
  * }
230
229
  * ```
231
230
  */
232
- declare class Environment {
231
+ export declare class Environment {
233
232
  /** The environment name, as passed to `client.environment()`. */
234
233
  readonly name: string;
235
234
  private readonly opts;
236
235
  private readonly client;
237
- constructor(/** The environment name, as passed to `client.environment()`. */
238
-
236
+ constructor(
237
+ /** The environment name, as passed to `client.environment()`. */
239
238
  name: string, opts: EnvironmentOptions, client: Sandbox);
240
239
  /**
241
240
  * Return a sandbox pre-configured with this environment.
@@ -278,7 +277,7 @@ declare class Environment {
278
277
  * await sb.close();
279
278
  * ```
280
279
  */
281
- declare class Sandbox {
280
+ export declare class Sandbox {
282
281
  private readonly _control;
283
282
  private readonly _adapter;
284
283
  private readonly _credentialBroker;
@@ -409,6 +408,14 @@ declare class Sandbox {
409
408
  }, runId?: string, opts?: {
410
409
  networkPolicy?: NetworkPolicy$1;
411
410
  credentialProxy?: boolean;
411
+ /**
412
+ * Environment for the restored sandbox — normally omitted (a snapshot already carries
413
+ * its container env). Use it only for `OPENSANDBOX_EGRESS_*` sidecar vars, which are
414
+ * process-scoped and must be re-supplied on every restore (the sidecar is not
415
+ * snapshotted): the server routes those to the sidecar and drops them from the
416
+ * container.
417
+ */
418
+ env?: Record<string, string>;
412
419
  /** Resource scope for the restored sandbox — see `SandboxOptions.resourceId`. Unlike
413
420
  * `resume()`, `restoreSnapshot()` has no prior ledger session of its own to inherit
414
421
  * from (the snapshot may have come from anywhere), so this must be passed explicitly. */
@@ -428,9 +435,13 @@ declare class Sandbox {
428
435
  * ```
429
436
  */
430
437
  readonly sandboxes: {
431
- /** List all sandbox records across all names, newest first. */list: (opts?: ListSandboxOptions$1) => Promise<SandboxDetails$1[]>; /** List sandbox records for a specific name, newest first. */
432
- listByName: (name: string, opts?: ListSandboxOptions$1) => Promise<SandboxDetails$1[]>; /** Return details for a single sandbox record. Returns `null` if not found. */
433
- get: (name: string, sandboxId: string) => Promise<SandboxDetails$1 | null>; /** Delete all ledger events for a sandbox. */
438
+ /** List all sandbox records across all names, newest first. */
439
+ list: (opts?: ListSandboxOptions$1) => Promise<SandboxDetails$1[]>;
440
+ /** List sandbox records for a specific name, newest first. */
441
+ listByName: (name: string, opts?: ListSandboxOptions$1) => Promise<SandboxDetails$1[]>;
442
+ /** Return details for a single sandbox record. Returns `null` if not found. */
443
+ get: (name: string, sandboxId: string) => Promise<SandboxDetails$1 | null>;
444
+ /** Delete all ledger events for a sandbox. */
434
445
  delete: (name: string, sandboxId: string) => Promise<void>;
435
446
  };
436
447
  /**
@@ -470,7 +481,9 @@ declare class Sandbox {
470
481
  * ```
471
482
  */
472
483
  readonly environments: {
473
- /** Return all environment records, newest first. */list: () => Promise<EnvironmentRecord$1[]>; /** Remove the ledger record for a named environment. Does not delete the server-side snapshot. */
484
+ /** Return all environment records, newest first. */
485
+ list: () => Promise<EnvironmentRecord$1[]>;
486
+ /** Remove the ledger record for a named environment. Does not delete the server-side snapshot. */
474
487
  delete: (name: string) => Promise<void>;
475
488
  };
476
489
  _envInfo(name: string): Promise<EnvironmentRecord$1 | null>;
@@ -489,4 +502,4 @@ declare class Sandbox {
489
502
  private _releaseSlot;
490
503
  }
491
504
  //#endregion
492
- export { BashSession, type CheckpointInfo, CodeLanguage, CommandError, type CredentialBinding, type CredentialBroker, type CredentialProxyConfig, type DiagnosticEvent, type DiagnosticLog, Environment, type EnvironmentOptions, type EnvironmentRecord, type EnvironmentSandboxOptions, type ExecCodeOptions, ExecConnectionError, type ExecHandle, type ExecOptions, type ExecResult, type FileInfo, type IStorageAdapter, type InteractiveExecHandle, type LedgerEntry, LedgerEvent, type ListSandboxOptions, type Metrics, type NetworkPolicy, type NetworkRule, OpenSandboxCredentialBroker, type PendingInteractiveExec, type ResumeOptions, Sandbox, SandboxClientError, type SandboxClientOptions, type SandboxDetails, SandboxError, SandboxHandle, type SandboxOptions, SandboxStatus, StepTimeoutError };
505
+ export { BashSession, type CheckpointInfo, CodeLanguage, CommandError, type CredentialBinding, type CredentialBroker, type CredentialProxyConfig, type DiagnosticEvent, type DiagnosticLog, type EnvironmentOptions, type EnvironmentRecord, type EnvironmentSandboxOptions, type ExecCodeOptions, ExecConnectionError, type ExecHandle, type ExecOptions, type ExecResult, type FileInfo, type IStorageAdapter, type InteractiveExecHandle, type LedgerEntry, LedgerEvent, type ListSandboxOptions, type Metrics, type NetworkPolicy, type NetworkRule, OpenSandboxCredentialBroker, type PendingInteractiveExec, type ResumeOptions, type SandboxClientOptions, type SandboxDetails, SandboxError, SandboxHandle, type SandboxOptions, SandboxStatus, StepTimeoutError };
package/dist/index.mjs CHANGED
@@ -1,5 +1,5 @@
1
- import { BashSession, CommandError, ExecConnectionError, LedgerEvent, LedgerEvent as LedgerEvent$1, SandboxError, SandboxHandle, SandboxHandle as SandboxHandle$1, SandboxStatus, StepTimeoutError, reconstructBoundCredentials, resolveBoundCredential } from "@alineo-labs/core";
2
- import { CodeLanguage, ControlClient, SandboxState, SnapshotState } from "@alineo-labs/opensandbox";
1
+ import { BashSession, CommandError, ExecConnectionError, LedgerEvent, LedgerEvent as LedgerEvent$1, SandboxError, SandboxHandle, SandboxHandle as SandboxHandle$1, SandboxStatus, StepTimeoutError, reconstructBoundCredentials, reconstructEgressRules, resolveBoundCredential } from "@alineo-labs/core";
2
+ import { CodeLanguage, ControlClient, SandboxState, SnapshotState, isValidEgressTarget } from "@alineo-labs/opensandbox";
3
3
  import { OpenSandboxCredentialBroker, OpenSandboxCredentialBroker as OpenSandboxCredentialBroker$1 } from "@alineo-labs/vault";
4
4
  //#region src/types.ts
5
5
  /**
@@ -83,6 +83,14 @@ var Environment = class {
83
83
  //#endregion
84
84
  //#region src/client.ts
85
85
  /**
86
+ * Reject a `networkPolicy` with a malformed `target` before it reaches the server — a fast
87
+ * local error instead of a round-trip. `undefined` policies pass through untouched.
88
+ */
89
+ function assertValidNetworkPolicy(policy) {
90
+ if (!policy) return;
91
+ for (const rule of policy.egress ?? []) if (!isValidEgressTarget(rule.target)) throw new SandboxClientError(`Invalid networkPolicy egress target ${JSON.stringify(rule.target)} — expected an FQDN, a "*."-prefixed wildcard domain, a bare IP address, or a CIDR block.`, 400);
92
+ }
93
+ /**
86
94
  * Main entry point for the sandbox client. Manages sandbox lifecycle and session history.
87
95
  *
88
96
  * @example
@@ -153,6 +161,7 @@ var Sandbox = class {
153
161
  * ```
154
162
  */
155
163
  async sandbox(opts) {
164
+ assertValidNetworkPolicy(opts.networkPolicy);
156
165
  await this._ensureConnected();
157
166
  await this._acquireSlot();
158
167
  const image = typeof opts.image === "string" ? { uri: opts.image } : opts.image;
@@ -260,8 +269,16 @@ var Sandbox = class {
260
269
  const runId = createdPayload?.runId ?? crypto.randomUUID();
261
270
  const resourceId = createdPayload?.resourceId;
262
271
  const teamId = createdPayload?.teamId;
263
- const networkPolicy = createdPayload?.networkPolicy;
272
+ const originalNetworkPolicy = createdPayload?.networkPolicy;
264
273
  const credentialProxy = createdPayload?.credentialProxy;
274
+ const replayedEgress = originalNetworkPolicy ? reconstructEgressRules(entries) : {
275
+ apply: [],
276
+ remove: []
277
+ };
278
+ const networkPolicy = originalNetworkPolicy ? {
279
+ ...originalNetworkPolicy,
280
+ egress: [...replayedEgress.apply, ...(originalNetworkPolicy.egress ?? []).filter((r) => !replayedEgress.apply.some((rr) => rr.target === r.target) && !replayedEgress.remove.includes(r.target))]
281
+ } : void 0;
265
282
  const boundCredentials = reconstructBoundCredentials(entries);
266
283
  const replayCache = /* @__PURE__ */ new Map();
267
284
  const pendingStdout = /* @__PURE__ */ new Map();
@@ -421,12 +438,14 @@ var Sandbox = class {
421
438
  * ```
422
439
  */
423
440
  async restoreSnapshot(snapshotId, name, resources, runId, opts) {
441
+ assertValidNetworkPolicy(opts?.networkPolicy);
424
442
  await this._ensureConnected();
425
443
  await this._acquireSlot();
426
444
  try {
427
445
  const finalRunId = runId ?? crypto.randomUUID();
428
446
  const newId = (await this._control.createSandbox({
429
447
  snapshotId,
448
+ env: opts?.env,
430
449
  resourceLimits: resources,
431
450
  metadata: { runId: finalRunId },
432
451
  networkPolicy: opts?.networkPolicy,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alineo-labs/sandbox",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -29,14 +29,14 @@
29
29
  "test:watch": "vitest"
30
30
  },
31
31
  "dependencies": {
32
- "@alineo-labs/core": "0.3.0",
33
- "@alineo-labs/opensandbox": "0.2.0",
34
- "@alineo-labs/vault": "0.2.0"
32
+ "@alineo-labs/core": "0.4.1",
33
+ "@alineo-labs/opensandbox": "0.3.0",
34
+ "@alineo-labs/vault": "0.3.1"
35
35
  },
36
36
  "devDependencies": {
37
- "bun-types": "1.3.14",
38
- "tsdown": "0.22.3",
37
+ "bun-types": "1.4.2",
38
+ "tsdown": "0.23.0",
39
39
  "typescript": "6.0.3",
40
- "vitest": "4.1.9"
40
+ "vitest": "5.0.0"
41
41
  }
42
42
  }