withruntime 0.11.2 → 0.12.0

package/dist/freestyle/index.d.ts

@@ -1,14 +1,105 @@
 import type { Runtime } from "../client.js";
-import type { Sandbox } from "../sandbox.js";
-import { CompatibilityError, type ClientOptions } from "../compat/core.js";
+import type { Sandbox, Terminal } from "../sandbox.js";
+import type { Snapshot } from "../snapshots.js";
+import { CompatibilityError, type ClientOptions, type Refused, type RefusedAsync } from "../compat/core.js";
 export { CompatibilityError };
 export type VmState = "starting" | "running" | "pausing" | "paused" | "stopped";
+export interface FreestyleErrorBody {
+    code: string;
+    message: string;
+}
+/** What every failed Runtime call becomes, as Freestyle throws it for a
+ * non-2xx response: `code` is Runtime's error code in upper case
+ * (`NOT_FOUND`), `status` its HTTP status, and `cause` the RuntimeError. */
+export declare class FreestyleApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly path?: string;
+    constructor(status: number, body: FreestyleErrorBody, path?: string);
+}
+export interface FreestyleConnectionError {
+    name?: string;
+    message?: string;
+    code?: string;
+    errno?: string | number;
+    syscall?: string;
+    address?: string;
+    port?: number;
+}
+/** What a call that got no answer from Runtime becomes, as Freestyle 0.2.17
+ * throws a failed fetch: a TypeError whose `cause` is the RuntimeError
+ * ConnectionError and whose `errors` carry it as one entry. */
+export declare class FreestyleTransportError extends TypeError {
+    readonly errors: FreestyleConnectionError[];
+    constructor(cause: unknown, errors: FreestyleConnectionError[]);
+    toJSON(): {
+        name: string;
+        message: string;
+        errors: FreestyleConnectionError[];
+    };
+}
+export declare class FirewallRuleValidationError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export declare class TlsRuleValidationError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export declare class TlsForwardAuthValidationError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export declare const FirewallNamespace: Refused;
+export declare const FirewallRulesNamespace: Refused;
+export declare const validateFirewallEndpoint: Refused;
+export declare const validateFirewallRule: Refused;
+export declare const validateFirewallSpec: Refused;
+export declare const TlsNamespace: Refused;
+export declare const TlsRulesNamespace: Refused;
+export declare const TlsForwardAuthNamespace: Refused;
+export declare const hasTlsIdentity: Refused;
+export declare const resolveTlsProtocol: Refused;
+export declare const validateTlsDomain: Refused;
+export declare const validateTlsEndpoint: Refused;
+export declare const validateTlsForwardAuth: Refused;
+export declare const validateTlsMailRoute: Refused;
+export declare const validateTlsRule: Refused;
+export declare const validateTlsSpec: Refused;
+export declare const TunnelsNamespace: Refused;
+export declare const VpcNamespace: Refused;
+export declare const Vpc: Refused;
+export declare const VpcTunnelNamespace: Refused;
+export type FirewallProtocol = "tcp" | "udp" | "icmp";
+export interface FirewallEndpoint {
+    vmId?: string;
+    vpcId?: string;
+    tunnelId?: string;
+    cidr?: string;
+    public?: true;
+    port?: number;
+    protocol?: FirewallProtocol;
+}
 export interface FirewallRule {
     action: "allow";
-    source: Record<string, never>;
-    destination: {
-        public: true;
-    };
+    source: FirewallEndpoint;
+    destination: FirewallEndpoint;
+    description?: string;
+}
+export interface FirewallRuleData {
+    id: string;
+    action: "allow";
+    source: FirewallEndpoint;
+    destination: FirewallEndpoint;
+    description?: string | null;
+    dependencies: {
+        kind: string;
+        id: string;
+        slug?: string | null;
+        displayName?: string | null;
+    }[];
+    createdAt: string;
+    updatedAt: string;
 }
 export interface CreateVmOptions {
     snapshotId?: string | null;
@@ -27,14 +118,42 @@ export interface ExecOptions {
     env?: Record<string, string>;
     stdin?: string;
 }
+export interface FreestyleOptions extends ClientOptions {
+    teamId?: string;
+    stackAccessToken?: string;
+    identityAccessToken?: string;
+}
 export declare class Freestyle {
     readonly vms: VmsNamespace;
-    constructor(options?: ClientOptions);
+    readonly fetch: RefusedAsync;
+    constructor(options?: FreestyleOptions);
+    get firewall(): never;
+    get tls(): never;
+    get tunnels(): never;
+    get vpc(): never;
 }
-export declare class VmsNamespace {
+export declare class VmSnapshotsNamespace {
     private readonly runtime;
-    readonly snapshots: {
-        get: (id: string) => Promise<{
+    constructor(runtime: Runtime);
+    /** A snapshot by id or by its slug (Runtime's snapshot name). */
+    resolve(id: string): Promise<Snapshot>;
+    get(snapshotId: string): Promise<{
+        id: string;
+        sourceVmId: string;
+        slug: string | null;
+        displayName: string | null;
+        public: boolean;
+        createdAt: string;
+        updatedAt: string;
+        ttlSeconds: number | null;
+    }>;
+    delete(snapshotId: string): Promise<void>;
+    list(options?: {
+        sourceVmId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        snapshots: {
             id: string;
             sourceVmId: string;
             slug: string | null;
@@ -42,29 +161,31 @@ export declare class VmsNamespace {
             public: boolean;
             createdAt: string;
             updatedAt: string;
-            ttlSeconds: number;
-        }>;
-        delete: (id: string) => Promise<void>;
-        list: (options?: {
-            sourceVmId?: string;
-            limit?: number;
-            offset?: number;
-        }) => Promise<{
-            snapshots: {
-                id: string;
-                sourceVmId: string;
-                slug: string | null;
-                displayName: string | null;
-                public: boolean;
-                createdAt: string;
-                updatedAt: string;
-                ttlSeconds: number;
-            }[];
-            totalCount: number;
-        }>;
-    };
+            ttlSeconds: number | null;
+        }[];
+        totalCount: number;
+    }>;
+    /** Renames, relabels and re-times a snapshot: slug is its Runtime name,
+     * ttlSeconds whole days from now. */
+    update(snapshotId: string, options: {
+        slug?: string;
+        displayName?: string;
+        ttlSeconds?: number;
+    }): Promise<{
+        id: string;
+        sourceVmId: string;
+        slug: string | null;
+        displayName: string | null;
+        public: boolean;
+        createdAt: string;
+        updatedAt: string;
+        ttlSeconds: number | null;
+    }>;
+}
+export declare class VmsNamespace {
+    private readonly runtime;
+    readonly snapshots: VmSnapshotsNamespace;
     constructor(runtime: Runtime);
-    private resolveSnapshot;
     create(options: CreateVmOptions): Promise<{
         vm: Vm;
         vmId: string;
@@ -89,13 +210,15 @@ export declare class VmsNamespace {
         };
         firewallRules: {
             id: string;
+            action: "allow";
             source: {
                 vmId: string;
             };
-            action: "allow";
-            destination: {
-                public: true;
-            };
+            destination: FirewallEndpoint;
+            description: null;
+            dependencies: never[];
+            createdAt: string;
+            updatedAt: string;
         }[];
         tlsRules: never[];
     }>;
@@ -196,10 +319,118 @@ export declare class VmFilesystem {
         modified: string;
     }>;
 }
+export interface PtySessionInfo {
+    sessionId: number;
+    state: string;
+    createdUnix: number;
+    cols: number;
+    rows: number;
+    exitCode?: number | null;
+    linuxUser?: string | null;
+    slug?: string | null;
+}
+export interface PtyOpenOptions {
+    exec?: string;
+    cols?: number;
+    rows?: number;
+    linuxUser?: string;
+    slug?: string;
+}
+export type PtySessionSelector = number | string;
+export interface PtyAttachOptions {
+    session: PtySessionSelector;
+    linuxUser?: string;
+}
+export interface PtySessionEvents {
+    onData?: (data: Uint8Array) => void;
+    onExit?: (exitCode: number) => void;
+    onClose?: (info: {
+        wasClean: boolean;
+        code: number;
+        reason: string;
+    }) => void;
+    onError?: (err: unknown) => void;
+}
+/** A session's number: FNV-1a of its process id, 31 bits, never 0. */
+export declare function sessionNumber(processId: string): number;
+export declare class PtySession {
+    #private;
+    private readonly terminal;
+    private readonly sandbox;
+    private readonly processId;
+    readonly sessionId: number;
+    readonly slug: string | undefined;
+    readonly created: boolean;
+    constructor(terminal: Terminal, sandbox: Sandbox, processId: string, sessionId: number, slug: string | undefined, created: boolean, events: PtySessionEvents);
+    private readonly onError;
+    write(data: Uint8Array | string): void;
+    resize(options: {
+        cols: number;
+        rows: number;
+    }): void;
+    signal(sig: "sigint" | "sigkill"): void;
+    /** Closes the connection; the shell keeps running and attach() finds it. */
+    detach(): void;
+    get readyState(): number;
+}
+export declare class VmPty {
+    private readonly get;
+    constructor(get: () => Promise<Sandbox>);
+    private sessions;
+    private find;
+    private connect;
+    open(options?: PtyOpenOptions & PtySessionEvents): Promise<PtySession>;
+    attach(options: PtyAttachOptions & PtySessionEvents): Promise<PtySession>;
+    list(options?: {
+        linuxUser?: string;
+    }): Promise<{
+        sessions: PtySessionInfo[];
+    }>;
+    /** Ends a session's shell. An exited session stays in the list. */
+    close(session: PtySessionSelector, options?: {
+        linuxUser?: string;
+    }): Promise<{
+        sessionId: number;
+        exitCode: number | null | undefined;
+    } | {
+        sessionId: number;
+        exitCode?: undefined;
+    }>;
+}
+export declare class VmLinuxUserPty {
+    private readonly pty;
+    private readonly linuxUser;
+    constructor(pty: VmPty, linuxUser: string);
+    open(options?: Omit<PtyOpenOptions, "linuxUser"> & PtySessionEvents): Promise<PtySession>;
+    attach(options: Omit<PtyAttachOptions, "linuxUser"> & PtySessionEvents): Promise<PtySession>;
+    list(): Promise<{
+        sessions: PtySessionInfo[];
+    }>;
+    close(session: PtySessionSelector): Promise<{
+        sessionId: number;
+        exitCode: number | null | undefined;
+    } | {
+        sessionId: number;
+        exitCode?: undefined;
+    }>;
+}
+export declare class VmLinuxUser {
+    private readonly vm;
+    private readonly linuxUser;
+    readonly pty: VmLinuxUserPty;
+    constructor(vm: Vm, linuxUser: string);
+    exec(options: string | Omit<ExecOptions, "linuxUser">): Promise<{
+        stdout: string;
+        stderr: string;
+        statusCode: number | null;
+    }>;
+}
 export declare class Vm {
     private readonly runtime;
     readonly id: string;
     readonly fs: VmFilesystem;
+    readonly pty: VmPty;
+    readonly resize: RefusedAsync;
     constructor(runtime: Runtime, id: string);
     data(): Promise<{
         id: string;
@@ -259,6 +490,23 @@ export declare class Vm {
         updatedAt: string;
     }>;
     delete(): Promise<void>;
+    /** The VM's outbound rules, read back from its network settings. */
+    firewallRules(): Promise<{
+        rules: {
+            id: string;
+            action: "allow";
+            source: {
+                vmId: string;
+            };
+            destination: FirewallEndpoint;
+            description: null;
+            dependencies: never[];
+            createdAt: string;
+            updatedAt: string;
+        }[];
+        totalCount: number;
+    }>;
+    linuxUser(linuxUser: string): VmLinuxUser;
     update(options: {
         slug?: string;
         displayName?: string;
@@ -303,7 +551,7 @@ export declare class Vm {
             public: boolean;
             createdAt: string;
             updatedAt: string;
-            ttlSeconds: number;
+            ttlSeconds: number | null;
         };
     }>;
 }