agental-sdk 0.2.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/dist/client.d.ts +20 -1
- package/dist/client.js +26 -0
- package/dist/index.d.ts +1 -1
- package/dist/openapi.d.ts +28 -28
- package/dist/sandbox.d.ts +31 -3
- package/dist/sandbox.js +23 -1
- package/dist/template.d.ts +11 -1
- package/dist/template.js +14 -0
- package/dist/types.d.ts +10 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -112,6 +112,7 @@ await sandbox.stop({ keepMemory: true }); // or keep its memory too, at 10%: sta
|
|
|
112
112
|
await sandbox.start(); // waits until it is running, also when it has to be brought back from storage
|
|
113
113
|
|
|
114
114
|
const copy = await sandbox.fork(); // a new sandbox with the same disk
|
|
115
|
+
const live = await sandbox.fork({ memory: true }); // or one that goes on from where it was, every process running on (Firecracker boxes only)
|
|
115
116
|
|
|
116
117
|
const snapshot = await sandbox.snapshot("before-upgrade");
|
|
117
118
|
await sandbox.restore(snapshot.id); // roll the disk back
|
package/dist/client.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { Http, type AgentalOptions } from "./http.js";
|
|
2
2
|
import { Email, Sandbox, type CreateOptions } from "./sandbox.js";
|
|
3
3
|
import { Templates } from "./template.js";
|
|
4
|
-
import type { AccountEmail, AccountExport, ApiKey, ApiKeyUsage, Billing, Burst, Catalog, HostRoute, Invite, Me, Member, Organization, Region, AutoReload, Checkout, DataRetention, CreateApiKey, CreatedApiKey, MetricsAtMoment, Policy, Prices, RunningOverTime, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, Size, Snapshot, Team, TeamRole, Telemetry, TelemetryTest, RunsOnRepository, RunsOnRepositories, Usage, Webhook } from "./types.js";
|
|
4
|
+
import type { AccountEmail, AccountExport, ApiKey, ApiKeyUsage, Billing, Burst, Catalog, HostRoute, Invite, Me, Member, Organization, Region, AutoReload, Checkout, DataRetention, CreateApiKey, CreatedApiKey, MetricsAtMoment, Policy, Prices, RunningOverTime, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, Size, Snapshot, Team, TeamRole, Telemetry, TelemetryTest, RunsOnRepository, RunsOnRepositories, Usage, Webhook, EgressAccount } from "./types.js";
|
|
5
5
|
/** What a list of sandboxes is narrowed to. Each field left out narrows nothing; a list of values is any of them. */
|
|
6
6
|
export interface SandboxFilter {
|
|
7
7
|
/** Tags every sandbox has. */
|
|
@@ -335,6 +335,25 @@ export declare class Agental {
|
|
|
335
335
|
* defaultBudgetMicros. It answers with the account's burst as it stands now.
|
|
336
336
|
*/
|
|
337
337
|
setBurstBudget(budgetMicros: number | null): Promise<Burst>;
|
|
338
|
+
/**
|
|
339
|
+
* Whether the account may send sandboxes out through residential addresses, and what it
|
|
340
|
+
* still needs: plan (Fleet or larger), card (one saved), use_case (setEgressUseCase()).
|
|
341
|
+
* With what a GB costs, what it has spent this month, its budget, and why its residential
|
|
342
|
+
* connections are refused now, if they are. Amounts are millionths of a US dollar.
|
|
343
|
+
*/
|
|
344
|
+
egress(): Promise<EgressAccount>;
|
|
345
|
+
/**
|
|
346
|
+
* Tells us what the account's sandboxes will use residential addresses for, in a few
|
|
347
|
+
* sentences (20 to 2,000 characters): said once for the whole account. Sent again, it
|
|
348
|
+
* replaces what was sent. An owner's key only. Only where policy() says residentialEgress.
|
|
349
|
+
*/
|
|
350
|
+
setEgressUseCase(useCase: string): Promise<EgressAccount>;
|
|
351
|
+
/**
|
|
352
|
+
* Sets the most the account's residential traffic costs in a month, in millionths of a US
|
|
353
|
+
* dollar: 0 refuses all of it. null gives it the default again, defaultBudgetMicros. An
|
|
354
|
+
* owner's key only. Only where policy() says residentialEgress.
|
|
355
|
+
*/
|
|
356
|
+
setEgressBudget(budgetMicros: number | null): Promise<EgressAccount>;
|
|
338
357
|
/**
|
|
339
358
|
* Running time and what it comes to at the list price, by sandbox, by key, by day and by hour, and the mail of the same
|
|
340
359
|
* window. With apiKeyId, one key or several, only the sandboxes those keys made, "console" standing for those made in
|
package/dist/client.js
CHANGED
|
@@ -126,6 +126,7 @@ class Sandboxes {
|
|
|
126
126
|
...(options.snapshotId !== undefined ? { snapshotId: options.snapshotId } : {}),
|
|
127
127
|
...(options.ttlSeconds !== undefined ? { ttlSeconds: options.ttlSeconds } : {}),
|
|
128
128
|
...(options.network ? { network: options.network } : {}),
|
|
129
|
+
...(options.egress ? { egress: options.egress } : {}),
|
|
129
130
|
...(options.sshKeys !== undefined ? { sshKeys: options.sshKeys } : {}),
|
|
130
131
|
...(options.tags !== undefined ? { tags: options.tags } : {}),
|
|
131
132
|
...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
|
|
@@ -454,6 +455,31 @@ export class Agental {
|
|
|
454
455
|
async setBurstBudget(budgetMicros) {
|
|
455
456
|
return (await this.http.json({ method: "PUT", path: "/v1/burst/budget", body: { budgetMicros }, replay: true })).body;
|
|
456
457
|
}
|
|
458
|
+
/**
|
|
459
|
+
* Whether the account may send sandboxes out through residential addresses, and what it
|
|
460
|
+
* still needs: plan (Fleet or larger), card (one saved), use_case (setEgressUseCase()).
|
|
461
|
+
* With what a GB costs, what it has spent this month, its budget, and why its residential
|
|
462
|
+
* connections are refused now, if they are. Amounts are millionths of a US dollar.
|
|
463
|
+
*/
|
|
464
|
+
async egress() {
|
|
465
|
+
return (await this.http.json({ method: "GET", path: "/v1/egress", replay: true })).body;
|
|
466
|
+
}
|
|
467
|
+
/**
|
|
468
|
+
* Tells us what the account's sandboxes will use residential addresses for, in a few
|
|
469
|
+
* sentences (20 to 2,000 characters): said once for the whole account. Sent again, it
|
|
470
|
+
* replaces what was sent. An owner's key only. Only where policy() says residentialEgress.
|
|
471
|
+
*/
|
|
472
|
+
async setEgressUseCase(useCase) {
|
|
473
|
+
return (await this.http.json({ method: "PUT", path: "/v1/egress/use-case", body: { useCase }, replay: true })).body;
|
|
474
|
+
}
|
|
475
|
+
/**
|
|
476
|
+
* Sets the most the account's residential traffic costs in a month, in millionths of a US
|
|
477
|
+
* dollar: 0 refuses all of it. null gives it the default again, defaultBudgetMicros. An
|
|
478
|
+
* owner's key only. Only where policy() says residentialEgress.
|
|
479
|
+
*/
|
|
480
|
+
async setEgressBudget(budgetMicros) {
|
|
481
|
+
return (await this.http.json({ method: "PUT", path: "/v1/egress/budget", body: { budgetMicros }, replay: true })).body;
|
|
482
|
+
}
|
|
457
483
|
/**
|
|
458
484
|
* Running time and what it comes to at the list price, by sandbox, by key, by day and by hour, and the mail of the same
|
|
459
485
|
* window. With apiKeyId, one key or several, only the sandboxes those keys made, "console" standing for those made in
|
package/dist/index.d.ts
CHANGED
|
@@ -6,5 +6,5 @@ export { Browser, Commands, Desktop, Email, Files, Sandbox, Schedules, Ssh } fro
|
|
|
6
6
|
export { Secrets, Template, Templates } from "./template.js";
|
|
7
7
|
export type { TemplateChanges } from "./template.js";
|
|
8
8
|
export type { BurstOptions, CommandLine, CreateOptions, DesktopButton, ExecEvent, ExecOptions, SandboxChanges, ScreenshotOptions, SendEmailOptions, StartOptions, StopOptions, WaitOptions } from "./sandbox.js";
|
|
9
|
-
export type { AccountEmail, ApiKey, ApiKeyAction, ApiKeyPreset, ApiKeyUsage, Billing, BrowserState, Burst, BurstFee, BurstQuote, Catalog, Region, AutoReload, Checkout, Command, CreateSchedule, CreateApiKey, CreatedApiKey, DesktopLink, DesktopScreenshot, DesktopState, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, HiddenVariable, HostRoute, Invite, Me, Member, Organization, MetricsAtMoment, MetricsReading, NetworkRule, Operation, PlainVariable, Plan, Policy, Prices, RunningOverTime, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, SandboxMetrics, SandboxNetwork, SandboxNetworkDetail, SandboxOwnNetwork, SandboxStatus, SandboxTemplate, SandboxUsage, Schedule, ScheduleRun, SecretVariable, SendEmail, SetAutoStop, Size, Snapshot, SshKey, SshState, UpdateSchedule, Team, TeamRole, Telemetry, DataRetention, AccountExport, TelemetryTest, RunsOnRepository, RunsOnRepositories, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateStart, TemplateSsh, Usage, Webhook, WebhookDelivery, } from "./types.js";
|
|
9
|
+
export type { AccountEmail, ApiKey, ApiKeyAction, ApiKeyPreset, ApiKeyUsage, Billing, BrowserState, Burst, BurstFee, BurstQuote, Catalog, Region, AutoReload, Checkout, Command, CreateSchedule, CreateApiKey, CreatedApiKey, DesktopLink, DesktopScreenshot, DesktopState, Egress, EgressAccount, EgressInput, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, HiddenVariable, HostRoute, Invite, Me, Member, Organization, MetricsAtMoment, MetricsReading, NetworkRule, Operation, PlainVariable, Plan, Policy, Prices, RunningOverTime, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, SandboxMetrics, SandboxNetwork, SandboxNetworkDetail, SandboxOwnNetwork, SandboxStatus, SandboxTemplate, SandboxUsage, Schedule, ScheduleRun, SecretVariable, SendEmail, SetAutoStop, Size, Snapshot, SshKey, SshState, UpdateSchedule, Team, TeamRole, Telemetry, DataRetention, AccountExport, TelemetryTest, RunsOnRepository, RunsOnRepositories, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateStart, TemplateSsh, Usage, Webhook, WebhookDelivery, } from "./types.js";
|
|
10
10
|
export { verifyWebhook } from "./webhooks.js";
|
package/dist/openapi.d.ts
CHANGED
|
@@ -2763,7 +2763,7 @@ export interface paths {
|
|
|
2763
2763
|
patch?: never;
|
|
2764
2764
|
trace?: never;
|
|
2765
2765
|
};
|
|
2766
|
-
"/v1/egress/
|
|
2766
|
+
"/v1/egress/use-case": {
|
|
2767
2767
|
parameters: {
|
|
2768
2768
|
query?: never;
|
|
2769
2769
|
header?: never;
|
|
@@ -2771,8 +2771,8 @@ export interface paths {
|
|
|
2771
2771
|
cookie?: never;
|
|
2772
2772
|
};
|
|
2773
2773
|
get?: never;
|
|
2774
|
-
/** @description Tells us the account's
|
|
2775
|
-
put: operations["
|
|
2774
|
+
/** @description Tells us what the account's sandboxes will use residential addresses for, in place of what it said before. It is said once for the whole account, covers all its sandboxes and templates, and we may refuse residential egress on it. With a plan of Fleet or larger and a card saved, the account may then turn it on for its sandboxes. */
|
|
2775
|
+
put: operations["setEgressUseCase"];
|
|
2776
2776
|
post?: never;
|
|
2777
2777
|
delete?: never;
|
|
2778
2778
|
options?: never;
|
|
@@ -2880,7 +2880,7 @@ export interface components {
|
|
|
2880
2880
|
*/
|
|
2881
2881
|
feeMicros?: number;
|
|
2882
2882
|
/**
|
|
2883
|
-
* @description
|
|
2883
|
+
* @description On a 429 burst refusal: seconds until the same start costs no burst fee, as the meter falls. Null where waiting would not do: on running_limit_reached, or for a start larger than the plan's whole free burst. On a 503 admission_unavailable: 1. Also sent as Retry-After.
|
|
2884
2884
|
* @example 240
|
|
2885
2885
|
*/
|
|
2886
2886
|
retryAfterSeconds?: number | null;
|
|
@@ -5492,18 +5492,16 @@ export interface components {
|
|
|
5492
5492
|
offered: boolean;
|
|
5493
5493
|
/** @description Whether a sandbox of this account may go out residential now: offered, nothing missing, and not refused. */
|
|
5494
5494
|
enabled: boolean;
|
|
5495
|
-
/** @description What the account still needs: plan, to be on Fleet ($100 a month) or a larger plan; card, a card saved;
|
|
5496
|
-
missing: ("plan" | "card" | "
|
|
5495
|
+
/** @description What the account still needs: plan, to be on Fleet ($100 a month) or a larger plan; card, a card saved; use_case, what its sandboxes will use residential addresses for, with PUT /v1/egress/use-case. */
|
|
5496
|
+
missing: ("plan" | "card" | "use_case")[];
|
|
5497
5497
|
/** @description Set when we refused the account residential egress: its sandboxes' residential traffic is refused until we lift it. */
|
|
5498
5498
|
refused: {
|
|
5499
5499
|
reason: string;
|
|
5500
5500
|
at: string;
|
|
5501
5501
|
} | null;
|
|
5502
|
-
/** @description What the account told us of
|
|
5503
|
-
|
|
5504
|
-
|
|
5505
|
-
website: string;
|
|
5506
|
-
intendedUse: string;
|
|
5502
|
+
/** @description What the account told us its sandboxes will use residential addresses for, once for all of them, or null. */
|
|
5503
|
+
useCase: {
|
|
5504
|
+
text: string;
|
|
5507
5505
|
submittedAt: string;
|
|
5508
5506
|
} | null;
|
|
5509
5507
|
/** @description What a GB of residential traffic costs, both directions counted, in millionths of a US dollar: 3000000 is $3. */
|
|
@@ -5521,23 +5519,12 @@ export interface components {
|
|
|
5521
5519
|
*/
|
|
5522
5520
|
blocked: "refused" | "out_of_credit" | "budget_reached" | "plan" | null;
|
|
5523
5521
|
};
|
|
5524
|
-
|
|
5525
|
-
/**
|
|
5526
|
-
* @description The company's legal name.
|
|
5527
|
-
* @example Example Labs Ltd
|
|
5528
|
-
*/
|
|
5529
|
-
company: string;
|
|
5530
|
-
/**
|
|
5531
|
-
* Format: uri
|
|
5532
|
-
* @description Its website.
|
|
5533
|
-
* @example https://example.com
|
|
5534
|
-
*/
|
|
5535
|
-
website: string;
|
|
5522
|
+
EgressUseCase: {
|
|
5536
5523
|
/**
|
|
5537
5524
|
* @description What its sandboxes will use residential addresses for, in a few sentences: the sites, and why they need it.
|
|
5538
5525
|
* @example Our agents test our customers' sign-up flows from the countries they sell in, behind Cloudflare Turnstile.
|
|
5539
5526
|
*/
|
|
5540
|
-
|
|
5527
|
+
useCase: string;
|
|
5541
5528
|
};
|
|
5542
5529
|
EgressBudget: {
|
|
5543
5530
|
/**
|
|
@@ -5901,6 +5888,17 @@ export interface operations {
|
|
|
5901
5888
|
"application/json": components["schemas"]["Error"];
|
|
5902
5889
|
};
|
|
5903
5890
|
};
|
|
5891
|
+
/** @description admission_unavailable: the create could not be written just now, and nothing was made or charged. Send the same request again, with the same Idempotency-Key, after Retry-After (1 second). */
|
|
5892
|
+
503: {
|
|
5893
|
+
headers: {
|
|
5894
|
+
/** @description Seconds to wait before sending it again: 1. */
|
|
5895
|
+
"Retry-After": string;
|
|
5896
|
+
[name: string]: unknown;
|
|
5897
|
+
};
|
|
5898
|
+
content: {
|
|
5899
|
+
"application/json": components["schemas"]["Error"];
|
|
5900
|
+
};
|
|
5901
|
+
};
|
|
5904
5902
|
};
|
|
5905
5903
|
};
|
|
5906
5904
|
summarizeSandboxes: {
|
|
@@ -7320,6 +7318,8 @@ export interface operations {
|
|
|
7320
7318
|
content: {
|
|
7321
7319
|
"application/json": {
|
|
7322
7320
|
name: string;
|
|
7321
|
+
/** @description true: the fork goes on from where the source was, with every process that ran in it running on and what they held in memory, instead of starting from a copy of its disk. It has its own address, machine id, SSH host key and random seed, and its processes still hold the source's environment, its token among them, until they end. A running source is paused while its memory is written, about a second for every 2 to 3 GiB; a source stopped with keepMemory gives the memory it kept and stays as it was. Only on sandboxes whose host offers it (501 driver_operation_unavailable elsewhere); a stopped source that kept no memory is 409 invalid_state. */
|
|
7322
|
+
memory?: boolean;
|
|
7323
7323
|
};
|
|
7324
7324
|
};
|
|
7325
7325
|
};
|
|
@@ -7333,7 +7333,7 @@ export interface operations {
|
|
|
7333
7333
|
"application/json": components["schemas"]["Sandbox"];
|
|
7334
7334
|
};
|
|
7335
7335
|
};
|
|
7336
|
-
/** @description Fork created and running: a new sandbox of the same size with a copy of what the source held, on the source's template, with the source's own secrets and addresses. It is held to that template's outbound rule as it is now, with those addresses on top, from its first boot. The source is left as it was. */
|
|
7336
|
+
/** @description Fork created and running: a new sandbox of the same size with a copy of what the source held, on the source's template, with the source's own secrets and addresses. It is held to that template's outbound rule as it is now, with those addresses on top, from its first boot. The source is left as it was. With memory, the fork's processes are the source's, running on. */
|
|
7337
7337
|
201: {
|
|
7338
7338
|
headers: {
|
|
7339
7339
|
[name: string]: unknown;
|
|
@@ -17909,7 +17909,7 @@ export interface operations {
|
|
|
17909
17909
|
};
|
|
17910
17910
|
};
|
|
17911
17911
|
};
|
|
17912
|
-
|
|
17912
|
+
setEgressUseCase: {
|
|
17913
17913
|
parameters: {
|
|
17914
17914
|
query?: never;
|
|
17915
17915
|
header?: never;
|
|
@@ -17918,7 +17918,7 @@ export interface operations {
|
|
|
17918
17918
|
};
|
|
17919
17919
|
requestBody: {
|
|
17920
17920
|
content: {
|
|
17921
|
-
"application/json": components["schemas"]["
|
|
17921
|
+
"application/json": components["schemas"]["EgressUseCase"];
|
|
17922
17922
|
};
|
|
17923
17923
|
};
|
|
17924
17924
|
responses: {
|
|
@@ -17931,7 +17931,7 @@ export interface operations {
|
|
|
17931
17931
|
"application/json": components["schemas"]["EgressAccount"];
|
|
17932
17932
|
};
|
|
17933
17933
|
};
|
|
17934
|
-
/** @description invalid_request:
|
|
17934
|
+
/** @description invalid_request: useCase is missing, shorter than 20 characters or longer than 2,000. The key belongs to no account. */
|
|
17935
17935
|
400: {
|
|
17936
17936
|
headers: {
|
|
17937
17937
|
[name: string]: unknown;
|
package/dist/sandbox.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { type Http } from "./http.js";
|
|
2
2
|
import { Secrets, type Template } from "./template.js";
|
|
3
|
-
import type { BrowserState, CreateSchedule, Schedule, ScheduleRun, UpdateSchedule, SshKey, SshState, Command, DesktopLink, DesktopScreenshot, DesktopState, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, HostRoute, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxMetrics, SandboxNetworkDetail, SandboxOwnNetwork, SandboxTemplate, SandboxUsage, SendEmail, SetAutoStop, Size, Snapshot } from "./types.js";
|
|
3
|
+
import type { BrowserState, CreateSchedule, Schedule, ScheduleRun, UpdateSchedule, SshKey, SshState, Command, DesktopLink, DesktopScreenshot, DesktopState, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, HostRoute, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxMetrics, SandboxNetworkDetail, SandboxOwnNetwork, SandboxTemplate, SandboxUsage, SendEmail, SetAutoStop, Size, Snapshot, Egress, EgressInput } from "./types.js";
|
|
4
4
|
/** A create answers when the machine is ready, usually in under a minute. The API says to allow it three. */
|
|
5
5
|
declare const CREATE_TIMEOUT_MS = 180000;
|
|
6
6
|
/** A list is the arguments exactly as given, with no shell. A string is a line of shell, run by `sh -c`. */
|
|
@@ -79,6 +79,14 @@ export interface CreateOptions extends BurstOptions {
|
|
|
79
79
|
* networkPolicy.
|
|
80
80
|
*/
|
|
81
81
|
network?: SandboxOwnNetwork;
|
|
82
|
+
/**
|
|
83
|
+
* Where its web traffic leaves, from its first boot: { via: "residential", country: "de" }
|
|
84
|
+
* sends its TCP to ports 80 and 443 out through a residential address in Germany, charged
|
|
85
|
+
* at $3 a GB from the account's credits. Left out, its template's; { via: "box" } leaves
|
|
86
|
+
* from its server whatever the template says. Residential asks that the account may use it:
|
|
87
|
+
* client.egress(). It takes a key with network.write. Only where policy() says residentialEgress.
|
|
88
|
+
*/
|
|
89
|
+
egress?: EgressInput;
|
|
82
90
|
/**
|
|
83
91
|
* OpenSSH public key lines let in as root as it is made, on top of the keys its template
|
|
84
92
|
* lets in. It turns nothing on: SSH is on as it is made only where its template says so,
|
|
@@ -522,6 +530,16 @@ export declare class Sandbox {
|
|
|
522
530
|
* affected. Only where policy() says networkPolicy.
|
|
523
531
|
*/
|
|
524
532
|
setNetwork(own: SandboxOwnNetwork): Promise<SandboxNetworkDetail>;
|
|
533
|
+
/** Where its web traffic leaves: from its server (box), or through a residential address in a country. */
|
|
534
|
+
egress(): Promise<Egress>;
|
|
535
|
+
/**
|
|
536
|
+
* Sets where its web traffic leaves, in place of what it had: { via: "box" }, or
|
|
537
|
+
* { via: "residential", country: "us", session: "rotating" }. New connections take it
|
|
538
|
+
* within seconds, without a restart, and connections already open are not moved.
|
|
539
|
+
* Residential asks that the account may use it: client.egress(). It takes a key with
|
|
540
|
+
* network.write. Only where policy() says residentialEgress.
|
|
541
|
+
*/
|
|
542
|
+
setEgress(egress: EgressInput): Promise<Egress>;
|
|
525
543
|
/**
|
|
526
544
|
* Runs a command and waits for it. A command that fails is still an answer: read
|
|
527
545
|
* exitCode. Every command starts fresh, as root in /root, so a cd or an export does not
|
|
@@ -564,8 +582,18 @@ export declare class Sandbox {
|
|
|
564
582
|
/**
|
|
565
583
|
* Copies it into a new sandbox, running, with the same disk. From then on the two share
|
|
566
584
|
* nothing. Nothing that was running here is started in the copy.
|
|
567
|
-
|
|
568
|
-
|
|
585
|
+
*
|
|
586
|
+
* With `memory: true` the copy goes on from where this one was instead: every process
|
|
587
|
+
* running on, with what it held in memory, under the copy's own address, machine id and SSH
|
|
588
|
+
* host key. Its processes still hold this sandbox's environment, its token among them, until
|
|
589
|
+
* they end. A running sandbox is paused while its memory is written, about a second for every
|
|
590
|
+
* 2 to 3 GiB; one stopped with `keepMemory` gives the memory it kept. Only on Firecracker
|
|
591
|
+
* boxes: elsewhere it throws `501 driver_operation_unavailable`, and for a stopped sandbox
|
|
592
|
+
* that kept no memory `409 invalid_state`. The copy is made in this sandbox's organization.
|
|
593
|
+
*/
|
|
594
|
+
fork(options?: Pick<CreateOptions, "name" | "idempotencyKey" | "timeoutMs" | "maxBurstFeeMicros" | "maxBurstWaitMs"> & {
|
|
595
|
+
memory?: boolean;
|
|
596
|
+
}): Promise<Sandbox>;
|
|
569
597
|
/** Destroys it and its disk for good. */
|
|
570
598
|
delete(): Promise<void>;
|
|
571
599
|
/** Keeps the sandbox as it is now, to roll back to or to make new sandboxes from. */
|
package/dist/sandbox.js
CHANGED
|
@@ -639,6 +639,20 @@ export class Sandbox {
|
|
|
639
639
|
this.info = { ...this.info, network: { outbound: detail.outbound, allow: detail.allow } };
|
|
640
640
|
return detail;
|
|
641
641
|
}
|
|
642
|
+
/** Where its web traffic leaves: from its server (box), or through a residential address in a country. */
|
|
643
|
+
async egress() {
|
|
644
|
+
return (await this.http.json({ method: "GET", path: `${this.path}/egress`, replay: true })).body;
|
|
645
|
+
}
|
|
646
|
+
/**
|
|
647
|
+
* Sets where its web traffic leaves, in place of what it had: { via: "box" }, or
|
|
648
|
+
* { via: "residential", country: "us", session: "rotating" }. New connections take it
|
|
649
|
+
* within seconds, without a restart, and connections already open are not moved.
|
|
650
|
+
* Residential asks that the account may use it: client.egress(). It takes a key with
|
|
651
|
+
* network.write. Only where policy() says residentialEgress.
|
|
652
|
+
*/
|
|
653
|
+
async setEgress(egress) {
|
|
654
|
+
return (await this.http.json({ method: "PUT", path: `${this.path}/egress`, body: egress, replay: true })).body;
|
|
655
|
+
}
|
|
642
656
|
/**
|
|
643
657
|
* Runs a command and waits for it. A command that fails is still an answer: read
|
|
644
658
|
* exitCode. Every command starts fresh, as root in /root, so a cd or an export does not
|
|
@@ -783,9 +797,17 @@ export class Sandbox {
|
|
|
783
797
|
/**
|
|
784
798
|
* Copies it into a new sandbox, running, with the same disk. From then on the two share
|
|
785
799
|
* nothing. Nothing that was running here is started in the copy.
|
|
800
|
+
*
|
|
801
|
+
* With `memory: true` the copy goes on from where this one was instead: every process
|
|
802
|
+
* running on, with what it held in memory, under the copy's own address, machine id and SSH
|
|
803
|
+
* host key. Its processes still hold this sandbox's environment, its token among them, until
|
|
804
|
+
* they end. A running sandbox is paused while its memory is written, about a second for every
|
|
805
|
+
* 2 to 3 GiB; one stopped with `keepMemory` gives the memory it kept. Only on Firecracker
|
|
806
|
+
* boxes: elsewhere it throws `501 driver_operation_unavailable`, and for a stopped sandbox
|
|
807
|
+
* that kept no memory `409 invalid_state`. The copy is made in this sandbox's organization.
|
|
786
808
|
*/
|
|
787
809
|
async fork(options = {}) {
|
|
788
|
-
const { info, burstFeeMicros } = await makeSandbox(this.http, `${this.path}/fork`, { name: options.name ?? made("sbx") }, options.idempotencyKey ?? made("sdk"), options.timeoutMs ?? CREATE_TIMEOUT_MS, options);
|
|
810
|
+
const { info, burstFeeMicros } = await makeSandbox(this.http, `${this.path}/fork`, { name: options.name ?? made("sbx"), ...(options.memory === true ? { memory: true } : {}) }, options.idempotencyKey ?? made("sdk"), options.timeoutMs ?? CREATE_TIMEOUT_MS, options);
|
|
789
811
|
return new Sandbox(this.http, info, burstFeeMicros);
|
|
790
812
|
}
|
|
791
813
|
/** Destroys it and its disk for good. */
|
package/dist/template.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type Http } from "./http.js";
|
|
2
|
-
import type { HiddenVariable, NetworkRule, PlainVariable, SecretVariable, Size, SshKey, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateSsh, TemplateStart } from "./types.js";
|
|
2
|
+
import type { HiddenVariable, NetworkRule, PlainVariable, SecretVariable, Size, SshKey, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateSsh, TemplateStart, Egress, EgressInput } from "./types.js";
|
|
3
3
|
/**
|
|
4
4
|
* Secrets: a template's, or a sandbox's own. Variables are in the environment of every
|
|
5
5
|
* command run in a sandbox, and files are written into its work folder before each one.
|
|
@@ -130,6 +130,16 @@ export declare class Template {
|
|
|
130
130
|
* when it next starts, or now when apply() names it. Only where policy() says networkPolicy.
|
|
131
131
|
*/
|
|
132
132
|
setNetwork(rule: NetworkRule): Promise<TemplateNetwork>;
|
|
133
|
+
/** Where the web traffic of a sandbox made from it leaves. One that was never set is box: from its server. */
|
|
134
|
+
egress(): Promise<Egress>;
|
|
135
|
+
/**
|
|
136
|
+
* Sets where the web traffic of a sandbox made from it from now on leaves: { via: "box" },
|
|
137
|
+
* or { via: "residential", country: "de" }. A sandbox already made keeps its own, and one
|
|
138
|
+
* made with egress of its own has that. Residential asks that the account may use it:
|
|
139
|
+
* client.egress(). It takes a key with network.write. Only where policy() says
|
|
140
|
+
* residentialEgress.
|
|
141
|
+
*/
|
|
142
|
+
setEgress(egress: EgressInput): Promise<Egress>;
|
|
133
143
|
/** What a sandbox made from it is given for SSH as it is made: whether SSH is turned on, and the keys let in. */
|
|
134
144
|
ssh(): Promise<TemplateSsh>;
|
|
135
145
|
/**
|
package/dist/template.js
CHANGED
|
@@ -172,6 +172,20 @@ export class Template {
|
|
|
172
172
|
this.info = { ...this.info, network: set };
|
|
173
173
|
return set;
|
|
174
174
|
}
|
|
175
|
+
/** Where the web traffic of a sandbox made from it leaves. One that was never set is box: from its server. */
|
|
176
|
+
async egress() {
|
|
177
|
+
return (await this.http.json({ method: "GET", path: `${this.path}/egress`, replay: true })).body;
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* Sets where the web traffic of a sandbox made from it from now on leaves: { via: "box" },
|
|
181
|
+
* or { via: "residential", country: "de" }. A sandbox already made keeps its own, and one
|
|
182
|
+
* made with egress of its own has that. Residential asks that the account may use it:
|
|
183
|
+
* client.egress(). It takes a key with network.write. Only where policy() says
|
|
184
|
+
* residentialEgress.
|
|
185
|
+
*/
|
|
186
|
+
async setEgress(egress) {
|
|
187
|
+
return (await this.http.json({ method: "PUT", path: `${this.path}/egress`, body: egress, replay: true })).body;
|
|
188
|
+
}
|
|
175
189
|
/** What a sandbox made from it is given for SSH as it is made: whether SSH is turned on, and the keys let in. */
|
|
176
190
|
async ssh() {
|
|
177
191
|
return (await this.http.json({ method: "GET", path: `${this.path}/ssh`, replay: true })).body;
|
package/dist/types.d.ts
CHANGED
|
@@ -49,6 +49,16 @@ export type SandboxOwnNetwork = Schemas["SandboxOwnNetworkInput"];
|
|
|
49
49
|
export type TemplateNetwork = Schemas["TemplateNetwork"];
|
|
50
50
|
/** A rule to hold a template's sandboxes to: open, blocked, or allowlist with the IPv4 addresses and ranges in allow. */
|
|
51
51
|
export type NetworkRule = Schemas["TemplateNetworkInput"];
|
|
52
|
+
/** Where a sandbox's web traffic leaves: from its server (box), or through a residential address in a country. */
|
|
53
|
+
export type Egress = Schemas["Egress"];
|
|
54
|
+
/**
|
|
55
|
+
* Where to send a sandbox's web traffic out: { via: "box" }, or { via: "residential",
|
|
56
|
+
* country: "de", session?: "sticky" | "rotating" }. Residential is charged at $3 a GB, both
|
|
57
|
+
* directions counted, and only ports 80 and 443 over TCP go through it.
|
|
58
|
+
*/
|
|
59
|
+
export type EgressInput = Schemas["EgressInput"];
|
|
60
|
+
/** Whether the account may send sandboxes out residential, what it still needs, and what it has spent and may spend this month. */
|
|
61
|
+
export type EgressAccount = Schemas["EgressAccount"];
|
|
52
62
|
export type Size = SandboxInfo["size"];
|
|
53
63
|
/** What a command ended with. A command that failed is still an answer: read exitCode. */
|
|
54
64
|
export type ExecResult = Schemas["ExecResult"];
|
package/dist/version.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** This package's version, as package.json says it. A test holds the two to the same. */
|
|
2
|
-
export declare const VERSION = "0.
|
|
2
|
+
export declare const VERSION = "0.3.0";
|
package/dist/version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** This package's version, as package.json says it. A test holds the two to the same. */
|
|
2
|
-
export const VERSION = "0.
|
|
2
|
+
export const VERSION = "0.3.0";
|
package/package.json
CHANGED