Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 21 additions & 0 deletions README.MD
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 6 additions & 1 deletion RELEASE.MD
Original file line number Diff line number Diff line change
Expand Up @@ -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.



Expand Down
9 changes: 8 additions & 1 deletion examples/sandbox-quickstart.ts
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -21,6 +21,13 @@ async function main(): Promise<void> {
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());
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 3 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down Expand Up @@ -32,7 +32,8 @@
"deepinfra",
"api",
"wrapper",
"typesript",
"sandbox",
"typescript",
"large language model",
"deep learning",
"machine learning",
Expand Down
7 changes: 6 additions & 1 deletion src/lib/http/deepinfra-client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<AxiosResponse<Readable>> {
async stream(
spec: RequestSpec,
signal?: AbortSignal,
): Promise<AxiosResponse<Readable>> {
let response: AxiosResponse<Readable>;
try {
response = await this.http().request<Readable>({
...this.requestConfig(spec),
responseType: "stream",
signal,
});
} catch (error) {
if (!axios.isAxiosError(error)) {
Expand Down
1 change: 1 addition & 0 deletions src/lib/sandbox/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
6 changes: 6 additions & 0 deletions src/lib/sandbox/sandbox-options.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
63 changes: 55 additions & 8 deletions src/lib/sandbox/sandbox.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -219,15 +224,26 @@ export class Sandbox {
/** Run a command and return its aggregated stdout/stderr/returncode. */
exec(cmd: string, ...args: string[]): Promise<ExecResult>;
exec(cmd: string, ...args: [...string[], ExecOptions]): Promise<ExecResult>;
async exec(
exec(cmd: string, ...args: Array<string | ExecOptions>): Promise<ExecResult> {
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<ExecEvent>;
execStream(
cmd: string,
...args: [...string[], ExecOptions]
): AsyncGenerator<ExecEvent>;
execStream(
cmd: string,
...args: Array<string | ExecOptions>
): Promise<ExecResult> {
const { command, options } = splitExecArgs([cmd, ...args]);
const response = await this._client.stream(
this.execSpec(command, options.timeout),
);
return foldExecEvents(iterNdjson(response.data));
): AsyncGenerator<ExecEvent> {
return this.execEvents([cmd, ...args]);
}

/**
Expand All @@ -242,6 +258,37 @@ export class Sandbox {

// -- internals --

private async *execEvents(
args: Array<string | ExecOptions>,
): AsyncGenerator<ExecEvent> {
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,
Expand Down
51 changes: 36 additions & 15 deletions src/lib/sandbox/streaming.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<NdjsonEvent>,
): Promise<ExecResult> {
const stdout: string[] = [];
const stderr: string[] = [];
let returncode: number | undefined;
): AsyncGenerator<ExecEvent> {
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<ExecEvent>,
): Promise<ExecResult> {
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 });
}
Loading
Loading