@vercel/sandbox 0.0.5 → 0.0.7

package/src/{client/client.ts → api-client/api-client.ts}

@@ -1,21 +1,38 @@
 import FormData from "form-data";
-import { APIClient, parseOrThrow, type RequestParams } from "./base-client";
+import {
+  BaseClient,
+  parseOrThrow,
+  type Parsed,
+  type RequestParams,
+} from "./base-client";
 import {
   Command,
+  CommandFinished,
   CreatedCommand,
   CreatedSandbox,
   LogLine,
+  StoppedSandbox,
   WrittenFile,
 } from "./validators";
 import { Readable } from "stream";
 import { APIError } from "./api-error";
-import { createDeferredGenerator } from "../utils/deferred-generator";
+import { LRUCache } from "lru-cache";
 import { VERSION } from "../version";
 import { z } from "zod";
 import jsonlines from "jsonlines";
 import os from "os";
-
-export class SandboxClient extends APIClient {
+import ms from "ms";
+
+/**
+ * Allows to track the logs hits for a command un a to maximum of items and
+ * TTL so that we don't incur in memory leaks in a log running process.
+ */
+const logHits = new LRUCache<string, boolean>({
+  ttl: ms("45m"),
+  max: 1000,
+});
+
+export class APIClient extends BaseClient {
   private teamId: string;
 
   constructor(params: { host?: string; teamId: string; token: string }) {
@@ -41,10 +58,11 @@ export class SandboxClient extends APIClient {
   }
 
   async createSandbox(params: {
-    ports: number[];
+    ports?: number[];
     projectId: string;
-    source: { type: "git"; url: string };
+    source?: { type: "git"; url: string } | { type: "tarball"; url: string };
     timeout?: number;
+    resources?: { vcpus: number };
   }) {
     return parseOrThrow(
       CreatedSandbox,
@@ -55,6 +73,7 @@ export class SandboxClient extends APIClient {
           ports: params.ports,
           source: params.source,
           timeout: params.timeout,
+          resources: params.resources,
         }),
       }),
     );
@@ -81,17 +100,44 @@ export class SandboxClient extends APIClient {
     );
   }
 
+  async getCommand(params: {
+    sandboxId: string;
+    cmdId: string;
+    wait: true;
+  }): Promise<Parsed<z.infer<typeof CommandFinished>>>;
+  async getCommand(params: {
+    sandboxId: string;
+    cmdId: string;
+    wait?: boolean;
+  }): Promise<Parsed<z.infer<typeof Command>>>;
   async getCommand(params: {
     sandboxId: string;
     cmdId: string;
     wait?: boolean;
   }) {
+    return params.wait
+      ? parseOrThrow(
+          CommandFinished,
+          await this.request(
+            `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
+            { query: { wait: "true" } },
+          ),
+        )
+      : parseOrThrow(
+          Command,
+          await this.request(
+            `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
+          ),
+        );
+  }
+
+  async mkDir(params: { sandboxId: string; path: string; cwd?: string }) {
     return parseOrThrow(
-      Command,
-      await this.request(
-        `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
-        { query: { wait: params.wait ? "true" : undefined } },
-      ),
+      WrittenFile,
+      await this.request(`/v1/sandboxes/${params.sandboxId}/fs/mkdir`, {
+        method: "POST",
+        body: JSON.stringify({ path: params.path, cwd: params.cwd }),
+      }),
     );
   }
 
@@ -135,54 +181,45 @@ export class SandboxClient extends APIClient {
     return response.body;
   }
 
-  getLogs(params: { sandboxId: string; cmdId: string }) {
-    const deferred = createDeferredGenerator<z.infer<typeof LogLine>, void>();
-
-    (async () => {
-      const response = await this.request(
-        `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}/logs`,
-        { method: "GET" },
-      );
-
-      if (response.headers.get("content-type") !== "application/x-ndjson") {
-        throw new APIError(response, {
-          message: "Expected a stream of logs",
-        });
-      }
-
-      const parser = jsonlines.parse();
-      response.body.pipe(parser);
-
-      parser.on("data", (data) => {
-        const parsed = LogLine.safeParse(data);
-        if (parsed.success) {
-          deferred.next({
-            value: parsed.data,
-            done: false,
-          });
-        } else {
-          deferred.next({
-            value: Promise.reject(parsed.error),
-            done: false,
-          });
-        }
+  async *getLogs(params: {
+    sandboxId: string;
+    cmdId: string;
+  }): AsyncIterable<z.infer<typeof LogLine>> {
+    const url = `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}/logs`;
+    const response = await this.request(url, { method: "GET" });
+    if (response.headers.get("content-type") !== "application/x-ndjson") {
+      throw new APIError(response, {
+        message: "Expected a stream of logs",
       });
+    }
 
-      parser.on("error", (err) => {
-        deferred.next({
-          value: Promise.reject(err),
-          done: false,
-        });
-      });
+    /**
+     * Currently, once we consume logs in the backend we cannot read them
+     * again. This logic writes a warning when the endpoint for a command
+     * logs is consumed more than once to alert the user about this.
+     *
+     * This is a temporary solution, we should be able to handle this in
+     * the backend in the future.
+     */
+    if (logHits.get(url)) {
+      console.warn(
+        `Multiple consumers for logs of command \`${params.cmdId}\`. This may lead to unexpected behavior.`,
+      );
+    }
 
-      parser.on("end", () => {
-        deferred.next({
-          value: undefined,
-          done: true,
-        });
-      });
-    })();
+    logHits.set(url, true);
+    for await (const chunk of response.body.pipe(jsonlines.parse())) {
+      yield LogLine.parse(chunk);
+    }
+  }
 
-    return deferred.generator();
+  async stopSandbox(params: {
+    sandboxId: string;
+  }): Promise<Parsed<z.infer<typeof StoppedSandbox>>> {
+    const url = `/v1/sandboxes/${params.sandboxId}/stop`;
+    return parseOrThrow(
+      StoppedSandbox,
+      await this.request(url, { method: "POST" }),
+    );
   }
 }

package/src/{client → api-client}/base-client.ts

@@ -18,7 +18,7 @@ export interface RequestParams extends RequestInit {
  * we can pass query parameters as an object, support retries, debugging
  * and automatic authorization.
  */
-export class APIClient {
+export class BaseClient {
   protected token?: string;
   private fetch: ReturnType<typeof withRetry<RequestInit>>;
   private debug: boolean;

package/src/api-client/index.ts

@@ -0,0 +1 @@
+export { APIClient } from "./api-client";

package/src/{client → api-client}/validators.ts

@@ -17,12 +17,20 @@ export const Command = z.object({
   name: z.string(),
 });
 
-export const FinishedCommand = z.object({
+export const CommandFinished = z.object({
+  args: z.array(z.string()),
   cmdId: z.string(),
+  cwd: z.string(),
+  exitCode: z.number(),
+  name: z.string(),
 });
 
 export const WrittenFile = z.object({});
 
+export const StoppedSandbox = z.object({
+  sandboxId: z.string(),
+});
+
 export const LogLine = z.object({
   stream: z.enum(["stdout", "stderr"]),
   data: z.string(),

package/src/command.test.ts

@@ -0,0 +1,51 @@
+import { it, expect, vi } from "vitest";
+import { Sandbox } from "./sandbox";
+
+it("warns when there is more than one logs consumer", async () => {
+  const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation(() => true);
+
+  const sandbox = await Sandbox.create({
+    projectId: process.env.VERCEL_PROJECT_ID!,
+    teamId: process.env.VERCEL_TEAM_ID!,
+    token: process.env.VERCEL_TOKEN!,
+  });
+
+  const cmd = await sandbox.runCommand({
+    cmd: "echo",
+    args: ["Hello World!"],
+    stdout: process.stdout,
+  });
+
+  expect(await cmd.stdout()).toEqual("");
+  expect(stdoutSpy).toHaveBeenCalledWith("Hello World!\n");
+  expect(warnSpy).toHaveBeenCalledWith(
+    expect.stringMatching(
+      /Multiple consumers for logs of command `[^`]+`\.\sThis may lead to unexpected behavior\./,
+    ),
+  );
+
+  await sandbox.stop();
+});
+
+it("does not warn when there is only one logs consumer", async () => {
+  const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+  const sandbox = await Sandbox.create({
+    projectId: process.env.VERCEL_PROJECT_ID!,
+    teamId: process.env.VERCEL_TEAM_ID!,
+    token: process.env.VERCEL_TOKEN!,
+  });
+
+  const cmd = await sandbox.runCommand({
+    cmd: "echo",
+    args: ["Hello World!"],
+  });
+
+  expect(await cmd.stdout()).toEqual("Hello World!\n");
+  expect(warnSpy).not.toHaveBeenCalled();
+
+  await sandbox.stop();
+});

package/src/command.ts

@@ -0,0 +1,176 @@
+import { APIClient } from "./api-client";
+
+/**
+ * A command executed in a Sandbox.
+ *
+ * You can {@link wait} on commands to access their {@link CommandFinished.exitCode}, and
+ * iterate over their output with {@link logs}.
+ *
+ * @see {@link Sandbox.runCommand} to start a command.
+ *
+ * @hideconstructor
+ */
+export class Command {
+  /**
+   * @internal
+   * @private
+   */
+  protected client: APIClient;
+
+  /**
+   * ID of the sandbox this command is running in.
+   */
+  private sandboxId: string;
+
+  /**
+   * ID of the command execution.
+   */
+  public cmdId: string;
+
+  /**
+   * @param params - Object containing the client, sandbox ID, and command ID.
+   * @param params.client - API client used to interact with the backend.
+   * @param params.sandboxId - The ID of the sandbox where the command is running.
+   * @param params.cmdId - The ID of the command execution.
+   */
+  constructor({
+    client,
+    sandboxId,
+    cmdId,
+  }: {
+    client: APIClient;
+    sandboxId: string;
+    cmdId: string;
+  }) {
+    this.client = client;
+    this.sandboxId = sandboxId;
+    this.cmdId = cmdId;
+  }
+
+  /**
+   * Iterate over the output of this command.
+   *
+   * ```
+   * for await (const log of cmd.logs()) {
+   *   if (log.stream === "stdout") {
+   *     process.stdout.write(log.data);
+   *   } else {
+   *     process.stderr.write(log.data);
+   *   }
+   * }
+   * ```
+   *
+   * @returns An async iterable of log entries from the command output.
+   *
+   * @see {@link Command.stdout}, {@link Command.stderr}, and {@link Command.output}
+   * to access output as a string.
+   */
+  logs() {
+    return this.client.getLogs({
+      sandboxId: this.sandboxId,
+      cmdId: this.cmdId,
+    });
+  }
+
+  /**
+   * Wait for a command to exit and populate its exit code.
+   *
+   * ```
+   * await cmd.wait()
+   * if (cmd.exitCode != 0) {
+   *   console.error("Something went wrong...")
+   * }
+   * ```
+   *
+   * @returns A {@link CommandFinished} instance with populated exit code.
+   */
+  async wait() {
+    const command = await this.client.getCommand({
+      sandboxId: this.sandboxId,
+      cmdId: this.cmdId,
+      wait: true,
+    });
+
+    return new CommandFinished({
+      client: this.client,
+      sandboxId: this.sandboxId,
+      cmdId: command.json.cmdId,
+      exitCode: command.json.exitCode,
+    });
+  }
+
+  /**
+   * Get the output of `stdout`, `stderr`, or both as a string.
+   *
+   * NOTE: This may throw string conversion errors if the command does
+   * not output valid Unicode.
+   *
+   * @param stream - The output stream to read: "stdout", "stderr", or "both".
+   * @returns The output of the specified stream(s) as a string.
+   */
+  async output(stream: "stdout" | "stderr" | "both" = "both") {
+    let data = "";
+    for await (const log of this.logs()) {
+      if (stream === "both" || log.stream === stream) {
+        data += log.data;
+      }
+    }
+    return data;
+  }
+
+  /**
+   * Get the output of `stdout` as a string.
+   *
+   * NOTE: This may throw string conversion errors if the command does
+   * not output valid Unicode.
+   *
+   * @returns The standard output of the command.
+   */
+  async stdout() {
+    return this.output("stdout");
+  }
+
+  /**
+   * Get the output of `stderr` as a string.
+   *
+   * NOTE: This may throw string conversion errors if the command does
+   * not output valid Unicode.
+   *
+   * @returns The standard error output of the command.
+   */
+  async stderr() {
+    return this.output("stderr");
+  }
+}
+
+/**
+ * A command that has finished executing.
+ *
+ * Contains the exit code of the command.
+ *
+ * @hideconstructor
+ */
+export class CommandFinished extends Command {
+  /**
+   * The exit code of the command, if available. This is set after
+   * {@link wait} has returned.
+   */
+  public exitCode: number;
+
+  /**
+   * @param params - Object containing client, sandbox ID, command ID, and exit code.
+   * @param params.client - API client used to interact with the backend.
+   * @param params.sandboxId - The ID of the sandbox where the command ran.
+   * @param params.cmdId - The ID of the command execution.
+   * @param params.exitCode - The exit code of the completed command.
+   */
+  constructor(params: {
+    client: APIClient;
+    sandboxId: string;
+    cmdId: string;
+    exitCode: number;
+  }) {
+    super({ ...params });
+    this.exitCode = params.exitCode;
+  }
+}

package/src/index.ts

@@ -1 +1,2 @@
-export { SDK, Sandbox, Command } from "./create-sandbox";
+export { Sandbox } from "./sandbox";
+export { Command, CommandFinished } from "./command";