diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 33fe767..b144a65 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -7,18 +7,23 @@ concurrency: group: ${{ github.ref }} cancel-in-progress: true +permissions: + contents: read + id-token: write # npm trusted publishing (OIDC) + jobs: publish-npm: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v7 - - uses: actions/setup-node@v2 + # Trusted publishing needs npm >= 11.5.1; Node 24 bundles it. + - uses: actions/setup-node@v7 with: - node-version: '18.x' + node-version: '24.x' registry-url: 'https://registry.npmjs.org' - - run: npm install + - run: npm ci - run: npm run test - run: npm run build - run: npm publish --access=public diff --git a/README.MD b/README.MD index 03ef329..d0973be 100644 --- a/README.MD +++ b/README.MD @@ -48,6 +48,27 @@ part of the filesystem that survives `stop()`/`start()` — everything else image on restart, and the sandbox's idle timeout has the same effect as an explicit `stop()`. +Stream output while a command runs — the last event carries the exit code: + +```typescript +for await (const event of sb.execStream( + "bash", + "-c", + "pip install --break-system-packages requests", + { timeout: "5m" }, +)) { + if (event.type === "stdout") process.stdout.write(event.data); + else if (event.type === "stderr") process.stderr.write(event.data); + else console.log("exit code", event.returncode); +} +``` + +`exec()` and `execStream()` also take an `AbortSignal` (`{ signal }`). Aborting +makes the pending call or loop throw the signal's reason. Neither aborting nor +leaving an `execStream()` loop early (`break`, `return` or an exception) stops +the command: it keeps running in the sandbox until it exits or reaches its +`timeout` (60 seconds by default). + Auto-terminate with `try`/`finally`: ```typescript diff --git a/RELEASE.MD b/RELEASE.MD index fef70f7..1d542ad 100644 --- a/RELEASE.MD +++ b/RELEASE.MD @@ -6,7 +6,12 @@ This document describes the release process for the `deepinfra` package. Before release, make sure to do the following steps: - [ ] Update the `package.json` version number. You can use `npm version --allow-same-version --no-git-tag-version version_number` to update the version number. -- [ ] Create a new release on GitHub with the same version number. +- [ ] Create a new release on GitHub with the same version number. This runs `.github/workflows/deploy.yml`, which publishes to npm. + +## npm authentication +The publish job signs in to npm with [trusted publishing](https://docs.npmjs.com/trusted-publishers). On npmjs.com, open the package's Settings, then Trusted publishing, and add GitHub Actions with organization `deepinfra`, repository `deepinfra-node` and workflow filename `deploy.yml`, with `npm publish` allowed. A new entry expires unless it publishes within 2 days, so add it right before a release. + +Without a trusted publisher the job falls back to the `NPM_TOKEN` repository secret. diff --git a/examples/sandbox-quickstart.ts b/examples/sandbox-quickstart.ts index 5db717e..baf2162 100644 --- a/examples/sandbox-quickstart.ts +++ b/examples/sandbox-quickstart.ts @@ -1,5 +1,5 @@ /** - * Sandbox quickstart: create, exec, file round-trip, terminate. + * Sandbox quickstart: create, exec, streamed exec, file round-trip, terminate. * * Needs DEEPINFRA_API_KEY in the environment. Run with: * npx ts-node -r tsconfig-paths/register examples/sandbox-quickstart.ts @@ -21,6 +21,13 @@ async function main(): Promise { const sum = await sb.runPython("print(sum(range(101)))"); console.log("sum 0..100 =", sum.check().stdout.trim()); + const countdown = "for i in 3 2 1; do echo $i; sleep 1; done"; + for await (const event of sb.execStream("bash", "-c", countdown)) { + if (event.type === "stdout") { + process.stdout.write(event.data); + } + } + await sb.fs.write("/workspace/hello.txt", "hello from the host\n"); const readBack = await sb.fs.read("/workspace/hello.txt"); console.log("read back:", readBack.toString("utf8").trim()); diff --git a/package-lock.json b/package-lock.json index 3b3cded..4f5b52d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "deepinfra", - "version": "2.1.0", + "version": "2.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "deepinfra", - "version": "2.1.0", + "version": "2.2.0", "license": "MIT", "dependencies": { "axios": "^1.20.0", diff --git a/package.json b/package.json index bc22fb5..3979c32 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "deepinfra", - "version": "2.1.0", + "version": "2.2.0", "description": "Official API wrapper for DeepInfra", "main": "dist/index.js", "types": "dist/index.d.ts", @@ -32,7 +32,8 @@ "deepinfra", "api", "wrapper", - "typesript", + "sandbox", + "typescript", "large language model", "deep learning", "machine learning", diff --git a/src/lib/http/deepinfra-client.ts b/src/lib/http/deepinfra-client.ts index b3a86af..7923d4f 100644 --- a/src/lib/http/deepinfra-client.ts +++ b/src/lib/http/deepinfra-client.ts @@ -98,13 +98,18 @@ export class DeepInfraClient { /** * Issue a streaming request; error statuses throw before returning. * Streaming requests are never retried (exec is not idempotent). + * Aborting `signal` cancels the request and errors the response stream. */ - async stream(spec: RequestSpec): Promise> { + async stream( + spec: RequestSpec, + signal?: AbortSignal, + ): Promise> { let response: AxiosResponse; try { response = await this.http().request({ ...this.requestConfig(spec), responseType: "stream", + signal, }); } catch (error) { if (!axios.isAxiosError(error)) { diff --git a/src/lib/sandbox/index.ts b/src/lib/sandbox/index.ts index b603b5f..b2614bc 100644 --- a/src/lib/sandbox/index.ts +++ b/src/lib/sandbox/index.ts @@ -3,6 +3,7 @@ export { SandboxFS } from "@/lib/sandbox/sandbox-fs"; export type { SandboxInfo, SandboxState } from "@/lib/sandbox/sandbox-info"; export type { SandboxPlan } from "@/lib/sandbox/sandbox-plan"; export { ExecResult } from "@/lib/sandbox/exec-result"; +export type { ExecEvent } from "@/lib/sandbox/streaming"; export type { ExecOptions, WaitOptions, diff --git a/src/lib/sandbox/sandbox-options.ts b/src/lib/sandbox/sandbox-options.ts index 94a7d5a..f03344c 100644 --- a/src/lib/sandbox/sandbox-options.ts +++ b/src/lib/sandbox/sandbox-options.ts @@ -3,6 +3,12 @@ import { Duration } from "@/lib/sandbox/duration"; export interface ExecOptions { timeout?: Duration; + /** + * Stop waiting for the command: the pending call or loop throws the + * signal's reason. The command keeps running in the sandbox until it exits + * or times out. Once the exit status has arrived, aborting has no effect. + */ + signal?: AbortSignal; } export interface WaitOptions { diff --git a/src/lib/sandbox/sandbox.ts b/src/lib/sandbox/sandbox.ts index 2f67179..d0a6b29 100644 --- a/src/lib/sandbox/sandbox.ts +++ b/src/lib/sandbox/sandbox.ts @@ -22,7 +22,12 @@ import { WaitOptions, CreateOptions, } from "@/lib/sandbox/sandbox-options"; -import { foldExecEvents, iterNdjson } from "@/lib/sandbox/streaming"; +import { + ExecEvent, + foldExecEvents, + iterNdjson, + toExecEvents, +} from "@/lib/sandbox/streaming"; import { Duration, parseDuration } from "@/lib/sandbox/duration"; import { tagsMatch } from "@/lib/sandbox/tags"; import { SANDBOXES, idPath } from "@/lib/sandbox/paths"; @@ -219,15 +224,26 @@ export class Sandbox { /** Run a command and return its aggregated stdout/stderr/returncode. */ exec(cmd: string, ...args: string[]): Promise; exec(cmd: string, ...args: [...string[], ExecOptions]): Promise; - async exec( + exec(cmd: string, ...args: Array): Promise { + return foldExecEvents(this.execEvents([cmd, ...args])); + } + + /** + * Run a command and yield its output while it runs; the last event is its + * exit status. The command starts when iteration starts. Leaving the loop + * early stops the reading, not the command, which runs until it exits or + * reaches its timeout. + */ + execStream(cmd: string, ...args: string[]): AsyncGenerator; + execStream( + cmd: string, + ...args: [...string[], ExecOptions] + ): AsyncGenerator; + execStream( cmd: string, ...args: Array - ): Promise { - const { command, options } = splitExecArgs([cmd, ...args]); - const response = await this._client.stream( - this.execSpec(command, options.timeout), - ); - return foldExecEvents(iterNdjson(response.data)); + ): AsyncGenerator { + return this.execEvents([cmd, ...args]); } /** @@ -242,6 +258,37 @@ export class Sandbox { // -- internals -- + private async *execEvents( + args: Array, + ): AsyncGenerator { + const { command, options } = splitExecArgs(args); + const { signal } = options; + let exited = false; + try { + const response = await this._client.stream( + this.execSpec(command, options.timeout), + signal, + ); + for await (const event of toExecEvents(iterNdjson(response.data))) { + if (event.type === "exit") { + exited = true; + } + yield event; + } + } catch (error) { + // An abort surfaces as a transport error; rethrow the caller's reason. + if (signal?.aborted) { + // After the exit event the command has finished, and the abort only + // cut off the end of the response. + if (exited) { + return; + } + throw signal.reason ?? error; + } + throw error; + } + } + private async waitForState( target: SandboxState, timeoutSeconds: number, diff --git a/src/lib/sandbox/streaming.ts b/src/lib/sandbox/streaming.ts index 2548bb4..2e6398f 100644 --- a/src/lib/sandbox/streaming.ts +++ b/src/lib/sandbox/streaming.ts @@ -85,33 +85,54 @@ function mapStreamError(err: unknown): APIConnectionError { return new APIConnectionError("Connection error"); } -/** Accumulate exec-stream events into an ExecResult. */ -export async function foldExecEvents( +/** A chunk of a running command's output, or its exit status (always the last event). */ +export type ExecEvent = + | { type: "stdout"; data: string } + | { type: "stderr"; data: string } + | { type: "exit"; returncode: number }; + +const NO_RETURN_CODE = "Exec stream ended without a return code"; + +/** Type the raw exec stream; an error line or a missing return code throws. */ +export async function* toExecEvents( events: AsyncIterable, -): Promise { - const stdout: string[] = []; - const stderr: string[] = []; - let returncode: number | undefined; +): AsyncGenerator { + let exited = false; for await (const event of events) { if ("error" in event) { throw new SandboxExecError(String(event.error)); } if ("stdout" in event) { - stdout.push(String(event.stdout)); + yield { type: "stdout", data: String(event.stdout) }; } if ("stderr" in event) { - stderr.push(String(event.stderr)); + yield { type: "stderr", data: String(event.stderr) }; } if ("returncode" in event) { - returncode = Number(event.returncode); + exited = true; + yield { type: "exit", returncode: Number(event.returncode) }; + } + } + if (!exited) { + throw new SandboxExecError(NO_RETURN_CODE); + } +} + +/** Accumulate exec events into an ExecResult. */ +export async function foldExecEvents( + events: AsyncIterable, +): Promise { + const output = { stdout: "", stderr: "" }; + let returncode: number | undefined; + for await (const event of events) { + if (event.type === "exit") { + returncode = event.returncode; + } else { + output[event.type] += event.data; } } if (returncode === undefined) { - throw new SandboxExecError("Exec stream ended without a return code"); + throw new SandboxExecError(NO_RETURN_CODE); } - return new ExecResult({ - stdout: stdout.join(""), - stderr: stderr.join(""), - returncode, - }); + return new ExecResult({ ...output, returncode }); } diff --git a/test/sandbox/sandbox.spec.ts b/test/sandbox/sandbox.spec.ts index a8c0dfd..4eb853b 100644 --- a/test/sandbox/sandbox.spec.ts +++ b/test/sandbox/sandbox.spec.ts @@ -1,4 +1,4 @@ -import { Readable } from "node:stream"; +import { PassThrough, Readable } from "node:stream"; import { inspect } from "node:util"; const requestMock = jest.fn(); @@ -42,6 +42,10 @@ function streamResponse(status: number, lines: string[]) { }; } +function openStreamResponse(body: Readable) { + return { status: 200, statusText: "", data: body, headers: {}, config: {} }; +} + function testSandbox( overrides: Partial = {}, client: DeepInfraClient, @@ -222,6 +226,101 @@ describe("Sandbox", () => { await expect(sb.exec("true")).rejects.toThrow(ConflictError); }); + it("execStream() yields each chunk as it arrives, then the exit status", async () => { + const body = new PassThrough(); + requestMock.mockResolvedValueOnce(openStreamResponse(body)); + + const sb = testSandbox({}, client); + const events = sb.execStream("make", "-j4", { timeout: "5m" }); + + body.write('{"stdout":"compiling\\n"}\n'); + expect(await events.next()).toEqual({ + done: false, + value: { type: "stdout", data: "compiling\n" }, + }); + expect(body.writableEnded).toBe(false); + + body.end('{"stderr":"warning\\n"}\n{"returncode":2}\n'); + expect((await events.next()).value).toEqual({ + type: "stderr", + data: "warning\n", + }); + expect((await events.next()).value).toEqual({ + type: "exit", + returncode: 2, + }); + expect((await events.next()).done).toBe(true); + + const call = requestMock.mock.calls[0][0]; + expect(call.responseType).toBe("stream"); + expect(call.url).toBe("https://api.deepinfra.com/v1/sandboxes/sb_1/exec"); + expect(call.data).toEqual({ + command: ["make", "-j4"], + timeout_seconds: 300, + }); + }); + + it("execStream() rejects with the signal's reason when aborted mid-stream", async () => { + const body = new PassThrough(); + requestMock.mockResolvedValueOnce(openStreamResponse(body)); + const controller = new AbortController(); + + const sb = testSandbox({}, client); + const events = sb.execStream("sleep", "60", { signal: controller.signal }); + body.write('{"stdout":"started"}\n'); + await events.next(); + + controller.abort(); + body.destroy(new Error("canceled")); // what axios does to the body on abort + + await expect(events.next()).rejects.toBe(controller.signal.reason); + expect(requestMock.mock.calls[0][0].signal).toBe(controller.signal); + }); + + it("execStream() ends normally when aborted after the exit event", async () => { + const body = new PassThrough(); + requestMock.mockResolvedValueOnce(openStreamResponse(body)); + const controller = new AbortController(); + + const sb = testSandbox({}, client); + const events = sb.execStream("true", { signal: controller.signal }); + body.write('{"returncode":0}\n'); + expect((await events.next()).value).toEqual({ + type: "exit", + returncode: 0, + }); + + controller.abort(); + body.destroy(new Error("canceled")); // what axios does to the body on abort + + expect(await events.next()).toEqual({ done: true, value: undefined }); + }); + + it("exec() rejects with the signal's reason when aborted before a response", async () => { + const controller = new AbortController(); + controller.abort(); + requestMock.mockRejectedValueOnce(new Error("canceled")); + + const sb = testSandbox({}, client); + await expect(sb.exec("true", { signal: controller.signal })).rejects.toBe( + controller.signal.reason, + ); + }); + + it("leaving an execStream() loop early closes the response stream", async () => { + const body = new PassThrough(); + requestMock.mockResolvedValueOnce(openStreamResponse(body)); + body.write('{"stdout":"y\\n"}\n'); + + const sb = testSandbox({}, client); + for await (const event of sb.execStream("yes")) { + expect(event.type).toBe("stdout"); + break; + } + + expect(body.destroyed).toBe(true); + }); + it("runPython() sugars to exec('python3', '-c', code)", async () => { requestMock.mockResolvedValueOnce( streamResponse(200, ['{"stdout":"42"}\n{"returncode":0}\n']), diff --git a/test/sandbox/streaming.spec.ts b/test/sandbox/streaming.spec.ts index 441c4eb..2d9cdf9 100644 --- a/test/sandbox/streaming.spec.ts +++ b/test/sandbox/streaming.spec.ts @@ -1,5 +1,10 @@ import { Readable } from "node:stream"; -import { foldExecEvents, iterNdjson } from "@/lib/sandbox/streaming"; +import { + ExecEvent, + foldExecEvents, + iterNdjson, + toExecEvents, +} from "@/lib/sandbox/streaming"; import { SandboxExecError } from "@/lib/errors"; function streamOf(chunks: string[]): Readable { @@ -57,13 +62,42 @@ describe("iterNdjson", () => { }); }); +describe("toExecEvents", () => { + it("types output chunks and ends with the exit event", async () => { + const wire = [{ stdout: "a" }, { stderr: "x" }, { returncode: 3 }]; + expect(await collect(toExecEvents(fromArray(wire)))).toEqual([ + { type: "stdout", data: "a" }, + { type: "stderr", data: "x" }, + { type: "exit", returncode: 3 }, + ]); + }); + + it("throws SandboxExecError on an {error} event, after the output before it", async () => { + const events = toExecEvents( + fromArray([{ stdout: "partial" }, { error: "boom" }]), + ); + expect((await events.next()).value).toEqual({ + type: "stdout", + data: "partial", + }); + const error = await events.next().catch((error_) => error_); + expect(error).toBeInstanceOf(SandboxExecError); + expect(error.message).toBe("boom"); + }); + + it("throws SandboxExecError when the stream ends without a return code", async () => { + const events = toExecEvents(fromArray([{ stdout: "no end" }])); + await expect(collect(events)).rejects.toThrow(/without a return code/); + }); +}); + describe("foldExecEvents", () => { it("accumulates interleaved stdout/stderr and captures the return code", async () => { - const events = [ - { stdout: "a" }, - { stderr: "x" }, - { stdout: "b" }, - { returncode: 0 }, + const events: ExecEvent[] = [ + { type: "stdout", data: "a" }, + { type: "stderr", data: "x" }, + { type: "stdout", data: "b" }, + { type: "exit", returncode: 0 }, ]; const result = await foldExecEvents(fromArray(events)); expect(result.stdout).toBe("ab"); @@ -71,19 +105,12 @@ describe("foldExecEvents", () => { expect(result.returncode).toBe(0); }); - it("throws SandboxExecError on an {error} event", async () => { - const events = [{ stdout: "partial" }, { error: "boom" }]; + it("throws SandboxExecError when the events end without an exit", async () => { + const events: ExecEvent[] = [{ type: "stdout", data: "no end" }]; await expect(foldExecEvents(fromArray(events))).rejects.toThrow( SandboxExecError, ); }); - - it("throws SandboxExecError when the stream ends without a return code", async () => { - const events = [{ stdout: "no end" }]; - await expect(foldExecEvents(fromArray(events))).rejects.toThrow( - /without a return code/, - ); - }); }); async function* fromArray(items: T[]): AsyncGenerator { diff --git a/tsconfig.json b/tsconfig.json index 839749f..dd3e8e9 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -32,6 +32,7 @@ ], "exclude": [ "**/misc.ts", + "**/__mocks__", "node_modules", "dist", "**/*.spec.ts",