@ebowwa/sandbox 0.1.1

package/src/core/index.ts

@@ -0,0 +1,123 @@
+/**
+ * Core Primitives
+ *
+ * Composable building blocks for sandboxed execution.
+ * Each primitive can be used independently or combined.
+ */
+
+// Types - Foundation
+export type {
+  Language,
+  LanguageCapabilities,
+  PermissionLevel,
+  Permissions,
+  FileSystemPermission,
+  NetworkPermission,
+  EnvironmentPermission,
+  ProcessPermission,
+  Limits,
+  Cell,
+  ExecutionContext,
+  ExecutionOptions,
+  ExecutionResult,
+  ExecutionError,
+  ExecutionMetrics,
+  DisplayOutput,
+  Compiler,
+  CompileOptions,
+  Runtime,
+  Kernel,
+  CompletionResult,
+  InspectResult,
+  Notebook,
+  NotebookMetadata,
+  NotebookRunOptions,
+  NotebookResult,
+  Session,
+  PolyglotCell,
+  LanguageBridge,
+  Sandbox,
+  SandboxOptions,
+  SessionOptions,
+  NotebookOptions,
+} from "./types.js";
+
+// Type utilities
+export {
+  permissionsFromLevel,
+  parseMemory,
+  parseTime,
+} from "./types.js";
+
+// Compiler - Transforms source to executable
+export type {
+  CompileResult,
+  ImportDefinition,
+  CompilerOptions,
+  ICompiler,
+} from "./compiler.js";
+
+export {
+  BaseCompiler,
+  WasmCompiler,
+  CompilerRegistry,
+  defaultCompilerRegistry,
+} from "./compiler.js";
+
+// Runtime - Executes compiled code
+export type {
+  RuntimeOptions,
+  ExecutionRequest,
+  IRuntime,
+  RuntimeCapabilities,
+} from "./runtime.js";
+
+export {
+  Wasm2WasmRuntime,
+  NativeWasmRuntime,
+  RuntimeRegistry,
+  defaultRuntimeRegistry,
+} from "./runtime.js";
+
+// Permissions - Access control
+export type {
+  PermissionChecker as PermissionCheckerType,
+} from "./permissions.js";
+
+export {
+  PermissionChecker,
+  PermissionBuilder,
+  createPermissions,
+  mergePermissions,
+  impliesPermission,
+  upgradePermissions,
+} from "./permissions.js";
+
+// Limits - Resource constraints
+export type {
+  ParsedLimits,
+} from "./limits.js";
+
+export {
+  DEFAULT_LIMITS,
+  LimitsParser,
+  LimitsEnforcer,
+  LimitsBuilder,
+  mergeLimits,
+} from "./limits.js";
+
+// Cell - Executable unit
+export type {
+  CellMetadata,
+  CellState,
+  ExecutableCell,
+} from "./cell.js";
+
+export {
+  CellBuilder,
+  CellExecutor,
+  CellRegistry,
+  createCell,
+  createCellsFromMarkdown,
+  cellsToMarkdown,
+} from "./cell.js";

package/src/core/limits.ts

@@ -0,0 +1,508 @@
+/**
+ * Limits Primitive
+ *
+ * Composable resource limits for sandbox execution.
+ * Enforces memory, time, CPU, and I/O constraints.
+ */
+
+import type { Limits } from "./types.js";
+
+/**
+ * Parsed limits in normalized units
+ */
+export interface ParsedLimits {
+  memoryBytes: number;
+  timeoutMs: number;
+  cpuTimeMs: number;
+  maxInstructions: number;
+  maxOutputBytes: number;
+  maxStackDepth: number;
+  network: {
+    maxBandwidthBytes: number;
+    maxConnections: number;
+  };
+  filesystem: {
+    maxFileBytes: number;
+    maxTotalBytes: number;
+    maxOpenFiles: number;
+  };
+}
+
+/**
+ * Default limits for different isolation levels
+ */
+export const DEFAULT_LIMITS: Record<string, ParsedLimits> = {
+  isolated: {
+    memoryBytes: 16 * 1024 * 1024, // 16MB
+    timeoutMs: 5000, // 5s
+    cpuTimeMs: 1000, // 1s CPU time
+    maxInstructions: 10_000_000,
+    maxOutputBytes: 1024 * 1024, // 1MB
+    maxStackDepth: 100,
+    network: {
+      maxBandwidthBytes: 0,
+      maxConnections: 0,
+    },
+    filesystem: {
+      maxFileBytes: 0,
+      maxTotalBytes: 0,
+      maxOpenFiles: 0,
+    },
+  },
+  readonly: {
+    memoryBytes: 64 * 1024 * 1024, // 64MB
+    timeoutMs: 30000, // 30s
+    cpuTimeMs: 5000, // 5s CPU time
+    maxInstructions: 100_000_000,
+    maxOutputBytes: 10 * 1024 * 1024, // 10MB
+    maxStackDepth: 500,
+    network: {
+      maxBandwidthBytes: 0,
+      maxConnections: 0,
+    },
+    filesystem: {
+      maxFileBytes: 10 * 1024 * 1024, // 10MB per file
+      maxTotalBytes: 100 * 1024 * 1024, // 100MB total
+      maxOpenFiles: 10,
+    },
+  },
+  network: {
+    memoryBytes: 128 * 1024 * 1024, // 128MB
+    timeoutMs: 60000, // 60s
+    cpuTimeMs: 10000, // 10s CPU time
+    maxInstructions: 500_000_000,
+    maxOutputBytes: 50 * 1024 * 1024, // 50MB
+    maxStackDepth: 1000,
+    network: {
+      maxBandwidthBytes: 10 * 1024 * 1024, // 10MB/s
+      maxConnections: 10,
+    },
+    filesystem: {
+      maxFileBytes: 10 * 1024 * 1024,
+      maxTotalBytes: 100 * 1024 * 1024,
+      maxOpenFiles: 20,
+    },
+  },
+  filesystem: {
+    memoryBytes: 256 * 1024 * 1024, // 256MB
+    timeoutMs: 120000, // 2min
+    cpuTimeMs: 30000, // 30s CPU time
+    maxInstructions: 1_000_000_000,
+    maxOutputBytes: 100 * 1024 * 1024, // 100MB
+    maxStackDepth: 2000,
+    network: {
+      maxBandwidthBytes: 50 * 1024 * 1024, // 50MB/s
+      maxConnections: 50,
+    },
+    filesystem: {
+      maxFileBytes: 100 * 1024 * 1024, // 100MB per file
+      maxTotalBytes: 1024 * 1024 * 1024, // 1GB total
+      maxOpenFiles: 100,
+    },
+  },
+  admin: {
+    memoryBytes: 1024 * 1024 * 1024, // 1GB
+    timeoutMs: 300000, // 5min
+    cpuTimeMs: 60000, // 1min CPU time
+    maxInstructions: 5_000_000_000,
+    maxOutputBytes: 500 * 1024 * 1024, // 500MB
+    maxStackDepth: 5000,
+    network: {
+      maxBandwidthBytes: 100 * 1024 * 1024, // 100MB/s
+      maxConnections: 100,
+    },
+    filesystem: {
+      maxFileBytes: 1024 * 1024 * 1024, // 1GB per file
+      maxTotalBytes: 10 * 1024 * 1024 * 1024, // 10GB total
+      maxOpenFiles: 500,
+    },
+  },
+  sudo: {
+    memoryBytes: 4 * 1024 * 1024 * 1024, // 4GB
+    timeoutMs: 600000, // 10min
+    cpuTimeMs: 300000, // 5min CPU time
+    maxInstructions: 10_000_000_000,
+    maxOutputBytes: 1024 * 1024 * 1024, // 1GB
+    maxStackDepth: 10000,
+    network: {
+      maxBandwidthBytes: 500 * 1024 * 1024, // 500MB/s
+      maxConnections: 500,
+    },
+    filesystem: {
+      maxFileBytes: 10 * 1024 * 1024 * 1024, // 10GB per file
+      maxTotalBytes: 100 * 1024 * 1024 * 1024, // 100GB total
+      maxOpenFiles: 1000,
+    },
+  },
+};
+
+/**
+ * Limits Parser
+ *
+ * Converts human-readable limits to normalized values.
+ */
+export class LimitsParser {
+  /**
+   * Parse limits object to normalized values
+   */
+  static parse(limits: Limits): ParsedLimits {
+    return {
+      memoryBytes: this.parseMemory(limits.memory),
+      timeoutMs: this.parseTime(limits.timeout),
+      cpuTimeMs: limits.cpuTime ?? 30000,
+      maxInstructions: limits.maxInstructions ?? 100_000_000,
+      maxOutputBytes: limits.maxOutputSize ?? 10 * 1024 * 1024,
+      maxStackDepth: limits.maxStackDepth ?? 1000,
+      network: {
+        maxBandwidthBytes: this.parseMemory(limits.network?.maxBandwidth),
+        maxConnections: limits.network?.maxConnections ?? 10,
+      },
+      filesystem: {
+        maxFileBytes: this.parseMemory(limits.filesystem?.maxFileSize),
+        maxTotalBytes: this.parseMemory(limits.filesystem?.maxTotalSize),
+        maxOpenFiles: limits.filesystem?.maxOpenFiles ?? 100,
+      },
+    };
+  }
+
+  /**
+   * Parse memory string/number to bytes
+   */
+  static parseMemory(mem: number | string | undefined): number {
+    if (mem === undefined) return 16 * 1024 * 1024; // 16MB default
+    if (typeof mem === "number") return mem;
+
+    const match = mem.match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb|tb)?$/i);
+    if (!match) return 16 * 1024 * 1024;
+
+    const [, num, unit] = match;
+    const multipliers: Record<string, number> = {
+      b: 1,
+      kb: 1024,
+      mb: 1024 ** 2,
+      gb: 1024 ** 3,
+      tb: 1024 ** 4,
+    };
+
+    return Math.floor(parseFloat(num) * (multipliers[unit?.toLowerCase() ?? "b"] ?? 1));
+  }
+
+  /**
+   * Parse time string/number to milliseconds
+   */
+  static parseTime(time: number | string | undefined): number {
+    if (time === undefined) return 30000; // 30s default
+    if (typeof time === "number") return time;
+
+    const match = time.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h)?$/i);
+    if (!match) return 30000;
+
+    const [, num, unit] = match;
+    const multipliers: Record<string, number> = {
+      ms: 1,
+      s: 1000,
+      m: 60000,
+      h: 3600000,
+    };
+
+    return Math.floor(parseFloat(num) * (multipliers[unit?.toLowerCase() ?? "ms"] ?? 1));
+  }
+
+  /**
+   * Format bytes to human-readable string
+   */
+  static formatMemory(bytes: number): string {
+    const units = ["b", "kb", "mb", "gb", "tb"];
+    let value = bytes;
+    let unitIndex = 0;
+
+    while (value >= 1024 && unitIndex < units.length - 1) {
+      value /= 1024;
+      unitIndex++;
+    }
+
+    return `${value.toFixed(1)}${units[unitIndex]}`;
+  }
+
+  /**
+   * Format milliseconds to human-readable string
+   */
+  static formatTime(ms: number): string {
+    if (ms < 1000) return `${ms}ms`;
+    if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+    if (ms < 3600000) return `${(ms / 60000).toFixed(1)}m`;
+    return `${(ms / 3600000).toFixed(1)}h`;
+  }
+}
+
+/**
+ * Limits Enforcer
+ *
+ * Tracks and enforces resource limits during execution.
+ */
+export class LimitsEnforcer {
+  private startTime = 0;
+  private instructionCount = 0;
+  private memoryUsed = 0;
+  private outputSize = 0;
+  private networkBytes = { in: 0, out: 0 };
+  private openFiles = 0;
+  private aborted = false;
+  private abortReason?: string;
+
+  constructor(private limits: ParsedLimits) {}
+
+  /**
+   * Start tracking
+   */
+  start(): void {
+    this.startTime = Date.now();
+    this.aborted = false;
+    this.abortReason = undefined;
+  }
+
+  /**
+   * Check if execution should continue
+   */
+  check(): { ok: boolean; reason?: string } {
+    if (this.aborted) {
+      return { ok: false, reason: this.abortReason };
+    }
+
+    // Check timeout
+    const elapsed = Date.now() - this.startTime;
+    if (elapsed > this.limits.timeoutMs) {
+      return { ok: false, reason: `Timeout exceeded: ${elapsed}ms > ${this.limits.timeoutMs}ms` };
+    }
+
+    return { ok: true };
+  }
+
+  /**
+   * Track memory allocation
+   */
+  trackMemory(bytes: number): { ok: boolean; reason?: string } {
+    this.memoryUsed += bytes;
+    if (this.memoryUsed > this.limits.memoryBytes) {
+      this.abort(`Memory limit exceeded: ${LimitsParser.formatMemory(this.memoryUsed)} > ${LimitsParser.formatMemory(this.limits.memoryBytes)}`);
+      return { ok: false, reason: this.abortReason };
+    }
+    return { ok: true };
+  }
+
+  /**
+   * Track instruction execution
+   */
+  trackInstructions(count: number): { ok: boolean; reason?: string } {
+    this.instructionCount += count;
+    if (this.instructionCount > this.limits.maxInstructions) {
+      this.abort(`Instruction limit exceeded: ${this.instructionCount} > ${this.limits.maxInstructions}`);
+      return { ok: false, reason: this.abortReason };
+    }
+    return { ok: true };
+  }
+
+  /**
+   * Track output size
+   */
+  trackOutput(bytes: number): { ok: boolean; reason?: string } {
+    this.outputSize += bytes;
+    if (this.outputSize > this.limits.maxOutputBytes) {
+      this.abort(`Output limit exceeded: ${LimitsParser.formatMemory(this.outputSize)} > ${LimitsParser.formatMemory(this.limits.maxOutputBytes)}`);
+      return { ok: false, reason: this.abortReason };
+    }
+    return { ok: true };
+  }
+
+  /**
+   * Track network usage
+   */
+  trackNetwork(direction: "in" | "out", bytes: number): { ok: boolean; reason?: string } {
+    this.networkBytes[direction] += bytes;
+    // Could add bandwidth tracking here
+    return { ok: true };
+  }
+
+  /**
+   * Track file open
+   */
+  trackFileOpen(): { ok: boolean; reason?: string } {
+    this.openFiles++;
+    if (this.openFiles > this.limits.filesystem.maxOpenFiles) {
+      this.openFiles--;
+      return { ok: false, reason: `Too many open files: ${this.openFiles} > ${this.limits.filesystem.maxOpenFiles}` };
+    }
+    return { ok: true };
+  }
+
+  /**
+   * Track file close
+   */
+  trackFileClose(): void {
+    this.openFiles = Math.max(0, this.openFiles - 1);
+  }
+
+  /**
+   * Get current usage stats
+   */
+  getUsage(): {
+    elapsed: number;
+    memory: number;
+    instructions: number;
+    output: number;
+    networkIn: number;
+    networkOut: number;
+    openFiles: number;
+  } {
+    return {
+      elapsed: Date.now() - this.startTime,
+      memory: this.memoryUsed,
+      instructions: this.instructionCount,
+      output: this.outputSize,
+      networkIn: this.networkBytes.in,
+      networkOut: this.networkBytes.out,
+      openFiles: this.openFiles,
+    };
+  }
+
+  /**
+   * Abort execution
+   */
+  abort(reason: string): void {
+    this.aborted = true;
+    this.abortReason = reason;
+  }
+
+  /**
+   * Check if aborted
+   */
+  isAborted(): boolean {
+    return this.aborted;
+  }
+
+  /**
+   * Get abort reason
+   */
+  getAbortReason(): string | undefined {
+    return this.abortReason;
+  }
+}
+
+/**
+ * Limits Builder
+ *
+ * Fluent API for building limits.
+ */
+export class LimitsBuilder {
+  private limits: Limits = {};
+
+  memory(bytes: number | string): this {
+    this.limits.memory = bytes;
+    return this;
+  }
+
+  timeout(ms: number | string): this {
+    this.limits.timeout = ms;
+    return this;
+  }
+
+  cpuTime(ms: number): this {
+    this.limits.cpuTime = ms;
+    return this;
+  }
+
+  instructions(max: number): this {
+    this.limits.maxInstructions = max;
+    return this;
+  }
+
+  outputSize(bytes: number): this {
+    this.limits.maxOutputSize = bytes;
+    return this;
+  }
+
+  stackDepth(max: number): this {
+    this.limits.maxStackDepth = max;
+    return this;
+  }
+
+  network(options: Limits["network"]): this {
+    this.limits.network = options;
+    return this;
+  }
+
+  filesystem(options: Limits["filesystem"]): this {
+    this.limits.filesystem = options;
+    return this;
+  }
+
+  build(): Limits {
+    return this.limits;
+  }
+
+  parse(): ParsedLimits {
+    return LimitsParser.parse(this.limits);
+  }
+}
+
+/**
+ * Merge limits (take minimums - most restrictive)
+ */
+export function mergeLimits(...limits: Limits[]): Limits {
+  const result: Limits = {};
+
+  // Memory - take minimum
+  const memories = limits
+    .map(l => l.memory)
+    .filter(Boolean);
+  if (memories.length > 0) {
+    const parsed = memories.map(m => LimitsParser.parseMemory(m));
+    result.memory = Math.min(...parsed);
+  }
+
+  // Timeout - take minimum
+  const timeouts = limits
+    .map(l => l.timeout)
+    .filter(Boolean);
+  if (timeouts.length > 0) {
+    const parsed = timeouts.map(t => LimitsParser.parseTime(t));
+    result.timeout = Math.min(...parsed);
+  }
+
+  // CPU time - take minimum
+  const cpuTimes = limits
+    .map(l => l.cpuTime)
+    .filter(Boolean) as number[];
+  if (cpuTimes.length > 0) {
+    result.cpuTime = Math.min(...cpuTimes);
+  }
+
+  // Instructions - take minimum
+  const instructions = limits
+    .map(l => l.maxInstructions)
+    .filter(Boolean) as number[];
+  if (instructions.length > 0) {
+    result.maxInstructions = Math.min(...instructions);
+  }
+
+  // Output size - take minimum
+  const outputSizes = limits
+    .map(l => l.maxOutputSize)
+    .filter(Boolean) as number[];
+  if (outputSizes.length > 0) {
+    result.maxOutputSize = Math.min(...outputSizes);
+  }
+
+  // Stack depth - take minimum
+  const stackDepths = limits
+    .map(l => l.maxStackDepth)
+    .filter(Boolean) as number[];
+  if (stackDepths.length > 0) {
+    result.maxStackDepth = Math.min(...stackDepths);
+  }
+
+  return result;
+}
+
+// Re-export parse functions from types
+export { parseMemory, parseTime } from "./types.js";