tensorlake 0.5.34 → 0.5.36

package/dist/index.d.cts

@@ -97,6 +97,11 @@ interface CreateSandboxOptions {
     snapshotId?: string;
     /** Optional name for the sandbox. Named sandboxes support suspend/resume. When absent the sandbox is ephemeral. */
     name?: string;
+    /**
+     * Local cloud-init file path or HTTP(S) URL for the sandbox. Supported for
+     * fresh sandboxes and filesystem-only snapshot restores.
+     */
+    cloudInit?: string | URL;
 }
 interface UpdateSandboxOptions {
     /** New name for the sandbox. Naming an ephemeral sandbox enables suspend/resume. */

package/dist/index.d.ts

@@ -97,6 +97,11 @@ interface CreateSandboxOptions {
     snapshotId?: string;
     /** Optional name for the sandbox. Named sandboxes support suspend/resume. When absent the sandbox is ephemeral. */
     name?: string;
+    /**
+     * Local cloud-init file path or HTTP(S) URL for the sandbox. Supported for
+     * fresh sandboxes and filesystem-only snapshot restores.
+     */
+    cloudInit?: string | URL;
 }
 interface UpdateSandboxOptions {
     /** New name for the sandbox. Naming an ephemeral sandbox enables suspend/resume. */

package/dist/index.js

@@ -19,7 +19,7 @@ var SDK_VERSION, API_URL, API_KEY, NAMESPACE, SANDBOX_PROXY_URL, DEFAULT_HTTP_TI
 var init_defaults = __esm({
   "src/defaults.ts"() {
     "use strict";
-    SDK_VERSION = "0.5.34";
+    SDK_VERSION = "0.5.36";
     API_URL = process.env.TENSORLAKE_API_URL ?? "https://api.tensorlake.ai";
     API_KEY = process.env.TENSORLAKE_API_KEY ?? void 0;
     NAMESPACE = process.env.INDEXIFY_NAMESPACE ?? "default";
@@ -139,6 +139,56 @@ var init_errors = __esm({
   }
 });
 
+// src/sdk-timings.ts
+function sdkTimingsEnabled() {
+  const value = process.env[SDK_TIMINGS_ENV_VAR];
+  return value === "1" || value === "true" || value === "yes";
+}
+function sdkTimingPayloadsEnabled() {
+  const value = process.env[SDK_TIMING_PAYLOADS_ENV_VAR];
+  return value === "1" || value === "true" || value === "yes";
+}
+function nowMs() {
+  return performance.now();
+}
+function logSdkTiming(op, phase, startedAt, fields = {}) {
+  if (!sdkTimingsEnabled()) return;
+  logSdkTimingEvent(op, phase, {
+    ...fields,
+    duration_ms: Math.round((nowMs() - startedAt) * 100) / 100
+  });
+}
+function logSdkTimingEvent(op, phase, fields = {}) {
+  if (!sdkTimingsEnabled()) return;
+  const parts = [
+    "[tensorlake:sdk-timing]",
+    `op=${op}`,
+    `phase=${phase}`
+  ];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value == null) continue;
+    parts.push(`${key}=${formatSdkTimingValue(value)}`);
+  }
+  console.error(parts.join(" "));
+}
+function formatSdkTimingValue(value) {
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (/^[A-Za-z0-9_./:@-]+$/.test(value)) {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+var SDK_TIMINGS_ENV_VAR, SDK_TIMING_PAYLOADS_ENV_VAR;
+var init_sdk_timings = __esm({
+  "src/sdk-timings.ts"() {
+    "use strict";
+    SDK_TIMINGS_ENV_VAR = "TENSORLAKE_SDK_TIMINGS";
+    SDK_TIMING_PAYLOADS_ENV_VAR = "TENSORLAKE_SDK_TIMING_PAYLOADS";
+  }
+});
+
 // src/http.ts
 import {
   Agent,
@@ -164,6 +214,10 @@ function normalizeRequestBody(body) {
   }
   return body;
 }
+function stripPathPayload(path2) {
+  const queryStart = path2.search(/[?#]/);
+  return queryStart === -1 ? path2 : path2.slice(0, queryStart);
+}
 function throwMappedError(status, body, path2) {
   let message = body;
   try {
@@ -213,6 +267,7 @@ var init_http = __esm({
     "use strict";
     init_defaults();
     init_errors();
+    init_sdk_timings();
     REQUEST_TIMEOUT_HEADER = "X-Tensorlake-Request-Timeout-Ms";
     setGlobalDispatcher(
       new Agent({
@@ -339,9 +394,18 @@ var init_http = __esm({
         const { traceparent, traceId } = _HttpClient.makeTraceparent();
         headers["traceparent"] = traceparent;
         let lastError;
+        const operationStart = nowMs();
+        const timingPath = sdkTimingPayloadsEnabled() ? path2 : stripPathPayload(path2);
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
           if (attempt > 0) {
             const delay = this.retryBackoffMs * Math.pow(2, attempt - 1);
+            logSdkTimingEvent("http.request", "retry_sleep_start", {
+              method,
+              path: timingPath,
+              attempt,
+              delay_ms: delay,
+              server_trace_id: traceId
+            });
             await sleep(delay);
           }
           this.abortController = new AbortController();
@@ -351,6 +415,7 @@ var init_http = __esm({
             this.abortController?.abort();
           }, this.timeoutMs);
           const combinedSignal = signal ? anySignal([signal, this.abortController.signal]) : this.abortController.signal;
+          const attemptStart = nowMs();
           try {
             const response = await undiciFetch(url, {
               method,
@@ -359,15 +424,45 @@ var init_http = __esm({
               signal: combinedSignal
             });
             if (timeoutId != null) clearTimeout(timeoutId);
-            if (response.ok) return { response, traceId };
+            logSdkTiming("http.request", "headers", attemptStart, {
+              method,
+              path: timingPath,
+              status: response.status,
+              attempt,
+              server_trace_id: traceId
+            });
+            if (response.ok) {
+              logSdkTiming("http.request", "complete", operationStart, {
+                method,
+                path: timingPath,
+                status: response.status,
+                attempts: attempt + 1,
+                server_trace_id: traceId
+              });
+              return { response, traceId };
+            }
             if (retryableStatusCodes.has(response.status) && attempt < this.maxRetries) {
               lastError = new RemoteAPIError(
                 response.status,
                 await response.text().catch(() => "")
               );
+              logSdkTimingEvent("http.request", "retryable_status", {
+                method,
+                path: timingPath,
+                status: response.status,
+                attempt,
+                server_trace_id: traceId
+              });
               continue;
             }
             if (allowHttpErrors || allowedErrorStatusCodes.has(response.status)) {
+              logSdkTiming("http.request", "complete", operationStart, {
+                method,
+                path: timingPath,
+                status: response.status,
+                attempts: attempt + 1,
+                server_trace_id: traceId
+              });
               return { response, traceId };
             }
             const errorBody = await response.text().catch(() => "");
@@ -383,6 +478,13 @@ var init_http = __esm({
               });
             }
             lastError = err instanceof Error ? err : new Error(String(err));
+            logSdkTiming("http.request", "error", attemptStart, {
+              method,
+              path: timingPath,
+              attempt,
+              server_trace_id: traceId,
+              error: timedOut ? `request timed out after ${this.timeoutMs}ms` : describeError(err)
+            });
             if (attempt >= this.maxRetries) {
               const detail = timedOut ? `request timed out after ${this.timeoutMs}ms` : describeError(err);
               throw new SandboxConnectionError(detail, { cause: err });
@@ -3097,6 +3199,7 @@ var init_sandbox = __esm({
     init_models();
     init_tunnel();
     init_sse();
+    init_sdk_timings();
     init_url();
     DEFAULT_PROCESS_USER = "tl-user";
     SandboxProxyConnection = class {
@@ -3124,7 +3227,12 @@ var init_sandbox = __esm({
         if (this.resolvePromise != null) {
           return this.resolvePromise;
         }
-        this.resolvePromise = this.resolveProxyInfo(this.sandbox._getLifecycleIdentifier()).then((info) => {
+        const identifier = this.sandbox._getLifecycleIdentifier();
+        const resolveStart = nowMs();
+        logSdkTimingEvent("sandbox.proxy", "resolve_start", {
+          sandbox_id: identifier
+        });
+        this.resolvePromise = this.resolveProxyInfo(identifier).then((info) => {
           this.resolveProxyInfo = void 0;
           this.sandbox.traceId = info.traceId;
           this.sandbox._setLifecycleIdentifier(info.sandboxId);
@@ -3134,6 +3242,12 @@ var init_sandbox = __esm({
           const nextHttp = this.configureProxy(proxyUrl, info.sandboxId, this.routingHint);
           this.http.close();
           this.http = nextHttp;
+          logSdkTiming("sandbox.proxy", "resolve_complete", resolveStart, {
+            sandbox_id: info.sandboxId,
+            server_trace_id: info.traceId,
+            routing_hint: this.routingHint,
+            ingress_endpoint: info.ingressEndpoint
+          });
         }).finally(() => {
           this.resolvePromise = null;
         });
@@ -3594,6 +3708,7 @@ var init_sandbox = __esm({
        * the process, streams output, and delivers the exit code over one connection.
        */
       async run(command, options) {
+        const opStart = nowMs();
         const body = { command };
         if (options?.args) body.args = options.args;
         if (options?.env) body.env = options.env;
@@ -3601,15 +3716,28 @@ var init_sandbox = __esm({
         if (options?.timeout != null) body.timeout = options.timeout;
         const user = processUserPayload(options?.user);
         body.user = user;
+        logSdkTimingEvent("sandbox.run", "start", {
+          sandbox_id: this.sandboxId,
+          command: sdkTimingPayloadsEnabled() ? command : void 0,
+          command_length: command.length
+        });
+        const requestStart = nowMs();
         const sseStream = await this.http.requestStream(
           "POST",
           "/api/v1/processes/run",
           { json: body }
         );
         const traceId = sseStream.traceId;
+        logSdkTiming("sandbox.run", "stream_headers", requestStart, {
+          sandbox_id: this.sandboxId,
+          server_trace_id: traceId,
+          command: sdkTimingPayloadsEnabled() ? command : void 0,
+          command_length: command.length
+        });
         const stdoutLines = [];
         const stderrLines = [];
         let exitCode = -1;
+        const streamStart = nowMs();
         for await (const raw of parseSSEStream(sseStream)) {
           if (typeof raw.line === "string") {
             if (raw.stream === "stderr") {
@@ -3625,6 +3753,20 @@ var init_sandbox = __esm({
             }
           }
         }
+        logSdkTiming("sandbox.run", "stream_complete", streamStart, {
+          sandbox_id: this.sandboxId,
+          server_trace_id: traceId,
+          command: sdkTimingPayloadsEnabled() ? command : void 0,
+          command_length: command.length,
+          exit_code: exitCode
+        });
+        logSdkTiming("sandbox.run", "complete", opStart, {
+          sandbox_id: this.sandboxId,
+          server_trace_id: traceId,
+          command: sdkTimingPayloadsEnabled() ? command : void 0,
+          command_length: command.length,
+          exit_code: exitCode
+        });
         return Object.assign(
           { exitCode, stdout: stdoutLines.join("\n"), stderr: stderrLines.join("\n") },
           { traceId }
@@ -3972,6 +4114,50 @@ var client_exports = {};
 __export(client_exports, {
   SandboxClient: () => SandboxClient
 });
+import { readFile } from "fs/promises";
+function cloudInitIncludeData(source) {
+  const isWindowsPath = /^[A-Za-z]:[\\/]/.test(source);
+  try {
+    const url = new URL(source);
+    if ((url.protocol === "http:" || url.protocol === "https:") && url.hostname.length > 0) {
+      return Buffer.from(`#include
+${url.toString()}
+`, "utf8");
+    }
+    if (!isWindowsPath) {
+      throw new SandboxError(
+        "cloud-init URL must be an absolute HTTP(S) URL with a host"
+      );
+    }
+  } catch (error) {
+    if (error instanceof SandboxError) throw error;
+    if (!isWindowsPath && /^[A-Za-z][A-Za-z0-9+.-]*:/.test(source)) {
+      throw new SandboxError(
+        "cloud-init URL must be an absolute HTTP(S) URL with a host"
+      );
+    }
+  }
+  return void 0;
+}
+async function readCloudInitBase64(cloudInit) {
+  if (cloudInit == null) return void 0;
+  const sourceText = cloudInit instanceof URL ? cloudInit.toString() : cloudInit;
+  const includeData = cloudInitIncludeData(sourceText);
+  const data = includeData ?? await readFile(sourceText).catch((error) => {
+    throw new SandboxError(
+      `failed to read cloud-init file ${JSON.stringify(sourceText)}: ${error}`
+    );
+  });
+  if (data.length === 0) {
+    throw new SandboxError("cloud-init user data must not be empty");
+  }
+  if (data.length > MAX_CLOUD_INIT_USER_DATA_BYTES) {
+    throw new SandboxError(
+      `cloud-init user data exceeds ${MAX_CLOUD_INIT_USER_DATA_BYTES} byte limit`
+    );
+  }
+  return data.toString("base64");
+}
 function resolveRequestTimeoutMs(options) {
   if (options?.requestTimeout != null) {
     return secondsToMillis4(options.requestTimeout);
@@ -4049,7 +4235,7 @@ function validateUserPort(port) {
 function dedupeAndSortPorts(ports) {
   return [...new Set(ports)].sort((a, b) => a - b);
 }
-var CREATE_SANDBOX_RETRYABLE_STATUS_CODES, CREATE_SANDBOX_ALLOWED_ERROR_STATUS_CODES, COPY_SANDBOX_ALLOWED_ERROR_STATUS_CODES, SandboxClient, RESERVED_SANDBOX_MANAGEMENT_PORT;
+var CREATE_SANDBOX_RETRYABLE_STATUS_CODES, CREATE_SANDBOX_ALLOWED_ERROR_STATUS_CODES, COPY_SANDBOX_ALLOWED_ERROR_STATUS_CODES, MAX_CLOUD_INIT_USER_DATA_BYTES, SandboxClient, RESERVED_SANDBOX_MANAGEMENT_PORT;
 var init_client = __esm({
   "src/client.ts"() {
     "use strict";
@@ -4058,10 +4244,12 @@ var init_client = __esm({
     init_http();
     init_models();
     init_sandbox();
+    init_sdk_timings();
     init_url();
     CREATE_SANDBOX_RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([502, 503]);
     CREATE_SANDBOX_ALLOWED_ERROR_STATUS_CODES = /* @__PURE__ */ new Set([504]);
     COPY_SANDBOX_ALLOWED_ERROR_STATUS_CODES = /* @__PURE__ */ new Set([422, 504]);
+    MAX_CLOUD_INIT_USER_DATA_BYTES = 16 * 1024;
     SandboxClient = class _SandboxClient {
       http;
       apiUrl;
@@ -4152,6 +4340,7 @@ var init_client = __esm({
       // --- Sandbox CRUD ---
       /** Create a new sandbox. Returns immediately; the sandbox may still be starting. Use `createAndConnect()` for a blocking, ready-to-use handle. */
       async create(options) {
+        const cloudInitBase64 = await readCloudInitBase64(options?.cloudInit);
         const body = {
           resources: {
             cpus: options?.cpus ?? 1,
@@ -4164,6 +4353,7 @@ var init_client = __esm({
         if (options?.entrypoint != null) body.entrypoint = options.entrypoint;
         if (options?.snapshotId != null) body.snapshot_id = options.snapshotId;
         if (options?.name != null) body.name = options.name;
+        if (cloudInitBase64 != null) body.cloud_init_base64 = cloudInitBase64;
         if (options?.allowInternetAccess === false || options?.allowOut != null || options?.denyOut != null) {
           body.network = {
             allow_internet_access: options?.allowInternetAccess ?? true,
@@ -4581,9 +4771,24 @@ var init_client = __esm({
        * @throws {SandboxError} If the sandbox terminates during startup or the timeout elapses.
        */
       async createAndConnect(options) {
+        if (options?.poolId != null && options?.cloudInit != null) {
+          throw new SandboxError("cloud-init cannot be used with poolId");
+        }
+        const opStart = nowMs();
         const requestTimeout = options?.requestTimeout ?? options?.startupTimeout ?? this.requestTimeoutMs / 1e3;
         const requestClient = this.withRequestTimeout(requestTimeout);
+        logSdkTimingEvent("sandbox.create", "start", {
+          request_timeout_s: requestTimeout,
+          image: options?.image,
+          pool_id: options?.poolId
+        });
+        const createStart = nowMs();
         const result = options?.poolId != null ? await requestClient.claim(options.poolId) : await requestClient.create(options);
+        logSdkTiming("sandbox.create", options?.poolId != null ? "claim_response" : "create_response", createStart, {
+          sandbox_id: result.sandboxId,
+          status: result.status,
+          server_trace_id: result.traceId
+        });
         const requestedName = options?.poolId != null ? null : options?.name ?? null;
         const finishConnect = (routingHint, name, ingressEndpoint) => {
           const sandbox = requestClient.connect(
@@ -4596,6 +4801,13 @@ var init_client = __esm({
           sandbox.traceId = result.traceId;
           sandbox._setLifecycleIdentifier(result.sandboxId);
           sandbox._setName(name ?? requestedName);
+          logSdkTiming("sandbox.create", "complete", opStart, {
+            sandbox_id: result.sandboxId,
+            status: "running" /* RUNNING */,
+            server_trace_id: result.traceId,
+            routing_hint: routingHint,
+            ingress_endpoint: ingressEndpoint
+          });
           return sandbox;
         };
         if (result.status === "running" /* RUNNING */) {
@@ -4620,7 +4832,13 @@ var init_client = __esm({
         }
         const deadline = Date.now() + secondsToMillis4(requestTimeout);
         while (Date.now() < deadline) {
+          const pollStart = nowMs();
           const info = await requestClient.get(result.sandboxId);
+          logSdkTiming("sandbox.create", "poll_response", pollStart, {
+            sandbox_id: result.sandboxId,
+            status: info.status,
+            server_trace_id: info.traceId
+          });
           if (info.status === "running" /* RUNNING */) {
             return finishConnect(info.routingHint, info.name, info.ingressEndpoint);
           }