@sandbox-kit/sandbox 0.0.0-stage → 0.1.1

package/dist/client/sandbox.js

@@ -0,0 +1,160 @@
+// Sandbox handle runtime behavior is handwritten. Lifecycle methods dispatch
+// through optional Backend capabilities.
+import { SandboxState, } from "#contracts/sandbox_data_contracts.js";
+import { ErrorKind, sandboxError, unsupported, withContext, } from "#client/errors.js";
+import { awaitWithSignal, clone, operationOptions, operationSignal, publicTimeoutOptions, } from "#client/operation.js";
+export const sandboxConstructorToken = Symbol("sandbox-kit.Sandbox");
+export class Sandbox {
+    #backend;
+    #owner;
+    #timeout;
+    #info;
+    #closed = false;
+    #tail = Promise.resolve();
+    constructor(token, init) {
+        if (token !== sandboxConstructorToken)
+            throw new TypeError("Sandbox handles are created by Client");
+        this.#backend = init.backend;
+        this.#owner = init.owner;
+        this.#info = clone(init.info);
+        this.#timeout = init.timeout;
+    }
+    get id() {
+        return this.#info.id;
+    }
+    get providerName() {
+        return this.#info.provider;
+    }
+    info() {
+        return clone(this.#info);
+    }
+    capabilities() {
+        if (this.#closed || this.#owner.isClosed() || this.#info.terminal)
+            return [];
+        return this.#backend.capabilities?.(clone(this.#info)) ?? [];
+    }
+    supports(capability) {
+        return this.capabilities().includes(capability);
+    }
+    async refresh(options = {}) {
+        return this.#serialized("refresh", options, this.#timeout, async (signal) => {
+            const method = this.#backend.refresh;
+            if (!method)
+                unsupported(this.providerName, "refresh");
+            const info = await awaitWithSignal(() => method.call(this.#backend, this.id, operationOptions(options, signal)), signal);
+            this.#info = clone({ ...info, provider: this.providerName });
+            return this.info();
+        });
+    }
+    async start(options = {}) {
+        return this.#update("start", this.#backend.start, publicTimeoutOptions(options), options);
+    }
+    async stop(options = {}) {
+        const { force, ...call } = options;
+        return this.#update("stop", this.#backend.stop, {
+            ...publicTimeoutOptions(call),
+            ...(force === undefined ? {} : { force }),
+        }, call);
+    }
+    async pause(options = {}) {
+        return this.#update("pause", this.#backend.pause, publicTimeoutOptions(options), options);
+    }
+    async terminate(options = {}) {
+        const { wait, ...call } = options;
+        const request = {
+            ...publicTimeoutOptions(call),
+            ...(wait === undefined ? {} : { wait }),
+        };
+        return this.#serialized("terminate", call, call.timeout ?? this.#timeout, async (signal) => {
+            const method = this.#backend.terminate;
+            if (!method)
+                unsupported(this.providerName, "terminate");
+            const result = await awaitWithSignal(() => method.call(this.#backend, this.id, clone(request), operationOptions(call, signal)), signal);
+            this.#info = {
+                ...this.#info,
+                state: SandboxState.Terminated,
+                terminal: true,
+            };
+            return result;
+        });
+    }
+    async archive(options = {}) {
+        return this.#update("archive", this.#backend.archive, publicTimeoutOptions(options), options);
+    }
+    async delete(options = {}) {
+        const { wait, ...call } = options;
+        return this.#update("delete", this.#backend.delete, {
+            ...publicTimeoutOptions(call),
+            ...(wait === undefined ? {} : { wait }),
+        }, call);
+    }
+    async close(options = {}) {
+        if (this.#closed)
+            return;
+        await this.#serialized("close", options, this.#timeout, async (signal) => {
+            const close = this.#backend.closeSandbox;
+            if (close)
+                await awaitWithSignal(() => close.call(this.#backend, this.id, operationOptions(options, signal)), signal);
+            this.#closed = true;
+        });
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    async #update(operation, method, request, options) {
+        return this.#serialized(operation, options, options.timeout ?? this.#timeout, async (signal) => {
+            if (!method)
+                unsupported(this.providerName, operation);
+            const info = await awaitWithSignal(() => method.call(this.#backend, this.id, clone(request), operationOptions(options, signal)), signal);
+            this.#info = clone({ ...info, provider: this.providerName });
+            return this.info();
+        });
+    }
+    async #serialized(operation, options, timeout, body) {
+        this.#ensureOpen(operation);
+        const releaseClient = this.#owner.begin(operation);
+        const previous = this.#tail;
+        let unlock;
+        this.#tail = new Promise((resolve) => {
+            unlock = resolve;
+        });
+        let acquired = false;
+        let scoped;
+        try {
+            scoped = operationSignal(options, timeout);
+            await awaitWithSignal(() => previous, scoped.signal);
+            acquired = true;
+            this.#ensureOpen(operation);
+            return await body(scoped.signal);
+        }
+        catch (error) {
+            throw withContext(error, this.providerName, operation);
+        }
+        finally {
+            scoped?.dispose();
+            if (acquired)
+                unlock();
+            else
+                void previous.then(unlock, unlock);
+            releaseClient();
+        }
+    }
+    #ensureOpen(operation) {
+        if (this.#closed || this.#owner.isClosed())
+            throw sandboxError({
+                kind: ErrorKind.FailedPrecondition,
+                provider: this.providerName,
+                operation,
+                field: "sandbox",
+                message: "sandbox-kit: sandbox handle is closed",
+            });
+        if (operation !== "close" && this.#info.terminal)
+            throw sandboxError({
+                kind: ErrorKind.FailedPrecondition,
+                provider: this.providerName,
+                operation,
+                field: "sandbox",
+                message: "sandbox-kit: sandbox lifecycle is terminal",
+            });
+    }
+}

package/dist/client/types.d.ts

@@ -0,0 +1,63 @@
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import { ConfigSchema, type APIKeyCredentials as WireAPIKeyCredentials, type AuthConfig, type BearerTokenCredentials as WireBearerTokenCredentials, type OAuthCredentials as WireOAuthCredentials, type TokenPairCredentials as WireTokenPairCredentials } from "@sandbox-kit/contracts/client";
+import type { ArchiveOptions, CreateOptions, CreateResult, DeleteOptions, ExitResult, LifecycleCapability, PauseOptions, SandboxInfo, StartOptions, StopOptions, TerminateOptions } from "#contracts/sandbox_data_contracts.js";
+import type { DurationFieldsToMs } from "#internal/duration_ms.js";
+import type { RemapFields } from "#internal/input_remap.js";
+import type { FlattenOneof } from "#internal/oneof_input.js";
+import type { StripProto } from "#internal/strip_proto.js";
+/** Public credential shapes (no protobuf `$typeName` / getters). */
+export type APIKeyCredentials = StripProto<WireAPIKeyCredentials>;
+export type TokenPairCredentials = StripProto<WireTokenPairCredentials>;
+export type BearerTokenCredentials = StripProto<WireBearerTokenCredentials>;
+export type OAuthCredentials = StripProto<WireOAuthCredentials>;
+export type Scope = StripProto<import("@sandbox-kit/contracts/client").Scope>;
+/** Public auth: set exactly one credential variant (no protobuf `{ case, value }`). */
+export type AuthInput = FlattenOneof<NonNullable<AuthConfig["credentials"]>>;
+/**
+ * Public client settings (ms timeout, flat auth).
+ * Prefer {@link ClientConfig} at construction (`Config` plus `provider`).
+ */
+export type Config = DurationFieldsToMs<RemapFields<StripProto<MessageInitShape<typeof ConfigSchema>>, {
+    auth: AuthInput;
+}>>;
+export interface OperationOptions {
+    readonly signal?: AbortSignal;
+    /** Operation deadline in milliseconds. */
+    readonly timeout?: number;
+}
+/** Public stop options: Kit call options plus optional force. */
+export type StopCallOptions = OperationOptions & {
+    readonly force?: boolean;
+};
+/** Public terminate options: Kit call options plus optional wait. */
+export type TerminateCallOptions = OperationOptions & {
+    readonly wait?: boolean;
+};
+/** Public delete options: Kit call options plus optional wait. */
+export type DeleteCallOptions = OperationOptions & {
+    readonly wait?: boolean;
+};
+export interface Backend {
+    readonly name: string;
+    create?(request: CreateOptions, options: OperationOptions): Promise<CreateResult>;
+    attach?(id: string, options: OperationOptions): Promise<SandboxInfo>;
+    refresh?(id: string, options: OperationOptions): Promise<SandboxInfo>;
+    start?(id: string, request: StartOptions, options: OperationOptions): Promise<SandboxInfo>;
+    stop?(id: string, request: StopOptions, options: OperationOptions): Promise<SandboxInfo>;
+    pause?(id: string, request: PauseOptions, options: OperationOptions): Promise<SandboxInfo>;
+    terminate?(id: string, request: TerminateOptions, options: OperationOptions): Promise<ExitResult>;
+    archive?(id: string, request: ArchiveOptions, options: OperationOptions): Promise<SandboxInfo>;
+    delete?(id: string, request: DeleteOptions, options: OperationOptions): Promise<SandboxInfo>;
+    close(options: OperationOptions): Promise<void>;
+    closeSandbox?(id: string, options: OperationOptions): Promise<void>;
+    capabilities?(info: SandboxInfo): readonly LifecycleCapability[];
+}
+export interface Provider {
+    readonly name: string;
+    /** Receives public {@link Config}. */
+    initialize(config: Config): Backend;
+}
+/** Provider selection stays handwritten and is never part of the portable Config message. */
+export type ClientConfig = Config & {
+    readonly provider: Provider;
+};

package/dist/client/types.js

@@ -0,0 +1,3 @@
+// Public client / provider / backend contracts are handwritten facades over
+// portable protobuf config and create/lifecycle option types.
+import { ConfigSchema, } from "@sandbox-kit/contracts/client";

package/dist/client/validation.d.ts

@@ -0,0 +1,9 @@
+import type { CreateOptions } from "#contracts/sandbox_data_contracts.js";
+import type { Config } from "#client/types.js";
+/**
+ * Rejects public {@link CreateOptions} the shared contract cannot represent.
+ * Materializes wire form privately for Protovalidate. Provider-specific checks
+ * remain in each provider adapter.
+ */
+export declare function validateCreateOptions(value: CreateOptions, provider?: string, operation?: string): void;
+export declare function validateConfig(value: Config, provider?: string, operation?: string): void;

package/dist/client/validation.js

@@ -0,0 +1,221 @@
+// Shared create/config validation is Protovalidate on materialized wire
+// messages; secure_endpoint stays handwritten.
+import { create, } from "@bufbuild/protobuf";
+import { pathToString } from "@bufbuild/protobuf/reflect";
+import { durationFromMs } from "@bufbuild/protobuf/wkt";
+import { createValidator } from "@bufbuild/protovalidate";
+import { ConfigSchema, } from "@sandbox-kit/contracts/client";
+import { CreateOptionsSchema, } from "@sandbox-kit/contracts/sandbox";
+import { materializeDurationFields } from "#internal/duration_ms.js";
+import { metadataObjectFromMap } from "#metadata/metadata_object.js";
+import { ErrorKind, sandboxError } from "#client/errors.js";
+const contractValidator = createValidator({ failFast: true });
+const stableRuleIDs = {
+    "enum.defined_only": "known_enum",
+    "duration.gte": "minimum",
+    "oneof.required": "exactly_one",
+    auth_credentials_required: "exactly_one",
+    cpu_limit: "limit",
+    memory_limit: "limit",
+    cpu_requires_positive: "requires_positive",
+    memory_requires_positive: "requires_positive",
+    restricted_requires_allowlist: "requires_any",
+    block_all_forbids_network: "forbids",
+    allow_all_forbids_allowlists: "forbids",
+    after_requires_duration: "requires_any",
+    after_forbids_duration: "forbids",
+};
+function validationError(input) {
+    throw sandboxError({
+        kind: ErrorKind.InvalidArgument,
+        provider: input.provider,
+        operation: input.operation,
+        field: input.field,
+        rule: input.rule,
+        message: "sandbox-kit: " + input.message,
+    });
+}
+function validSecureEndpoint(value) {
+    try {
+        const url = new URL(value);
+        if (!url.hostname || url.username || url.password || url.hash)
+            return false;
+        if (url.protocol === "https:")
+            return true;
+        if (url.protocol !== "http:")
+            return false;
+        const host = url.hostname.toLowerCase();
+        return (host === "localhost" ||
+            host === "[::1]" ||
+            host === "::1" ||
+            /^127(?:\.[0-9]{1,3}){3}$/.test(host));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Rejects public {@link CreateOptions} the shared contract cannot represent.
+ * Materializes wire form privately for Protovalidate. Provider-specific checks
+ * remain in each provider adapter.
+ */
+export function validateCreateOptions(value, provider = "", operation = "create") {
+    const message = materializeCreateOptions(value);
+    const result = contractValidator.validate(CreateOptionsSchema, message);
+    reportValidationResult(result, provider, operation);
+}
+function messageFieldHint(ruleID) {
+    switch (ruleID) {
+        case "cpu_limit":
+        case "cpu_requires_positive":
+            return "resources.cpu_limit_cores";
+        case "memory_limit":
+        case "memory_requires_positive":
+            return "resources.memory_limit_mib";
+        case "restricted_requires_allowlist":
+            return "network.outbound_cidrs,outbound_domains";
+        case "block_all_forbids_network":
+            return "network.outbound_cidrs,outbound_domains,private_network,linked_sandbox,inbound_cidrs,ports";
+        case "allow_all_forbids_allowlists":
+            return "network.outbound_cidrs,outbound_domains";
+        case "after_requires_duration":
+        case "after_forbids_duration":
+            return "after";
+        case "oneof.required":
+            return "tcp_port,command";
+        case "auth_credentials_required":
+            return "api_key,token_pair,bearer_token,oauth_refresh";
+        case "exactly_one":
+            return "client_secret,jwt_key";
+        default:
+            return "";
+    }
+}
+export function validateConfig(value, provider = "", operation = "create") {
+    const message = materializeClientConfig(value);
+    const result = contractValidator.validate(ConfigSchema, message);
+    reportValidationResult(result, provider, operation);
+    if (message.endpoint !== undefined &&
+        !validSecureEndpoint(message.endpoint)) {
+        validationError({
+            provider,
+            operation,
+            field: "endpoint",
+            rule: "secure_endpoint",
+            message: "must use HTTPS except for loopback HTTP development endpoints",
+        });
+    }
+}
+function reportValidationResult(result, provider, operation) {
+    if (result.kind === "valid")
+        return;
+    if (result.kind === "error") {
+        throw sandboxError({
+            kind: ErrorKind.InvalidArgument,
+            provider,
+            operation,
+            field: "",
+            message: "sandbox-kit: invalid configuration",
+        }, result.error);
+    }
+    const violation = result.violations[0];
+    const ruleID = violation.ruleId;
+    let field = pathToString(violation.field);
+    const rule = stableRuleIDs[ruleID] ?? ruleID;
+    if (!field) {
+        field = messageFieldHint(ruleID);
+    }
+    validationError({
+        provider,
+        operation,
+        field,
+        rule,
+        message: violation.message || "invalid configuration",
+    });
+}
+/** Materializes a plain client config into the generated protobuf message. */
+function materializeClientConfig(input) {
+    const { auth, timeout, ...rest } = input;
+    return create(ConfigSchema, {
+        ...rest,
+        ...(timeout === undefined ? {} : { timeout: durationFromMs(timeout) }),
+        ...(auth === undefined
+            ? {}
+            : { auth: { credentials: authCredentials(auth) } }),
+    });
+}
+/** Materializes plain create options into the generated protobuf message. */
+function materializeCreateOptions(input) {
+    const { source, readiness, providerOptions, network, ...rest } = input;
+    const withDurations = materializeDurationFields(rest);
+    return create(CreateOptionsSchema, {
+        ...withDurations,
+        ...(network === undefined
+            ? {}
+            : { network: materializeNetworkConfig(network) }),
+        ...(source === undefined ? {} : { source: { kind: sourceKind(source) } }),
+        ...(readiness === undefined
+            ? {}
+            : { readiness: { check: readinessCheck(readiness) } }),
+        ...(providerOptions === undefined
+            ? {}
+            : { providerOptions: metadataObjectFromMap(providerOptions) }),
+    });
+}
+/** Wrap public string-array allowlists into wire StringAllowlist messages. */
+function materializeNetworkConfig(network) {
+    const { outboundCidrs, outboundDomains, inboundCidrs, ...rest } = network;
+    return {
+        ...rest,
+        ...(outboundCidrs === undefined
+            ? {}
+            : { outboundCidrs: { entries: outboundCidrs } }),
+        ...(outboundDomains === undefined
+            ? {}
+            : { outboundDomains: { entries: outboundDomains } }),
+        ...(inboundCidrs === undefined
+            ? {}
+            : { inboundCidrs: { entries: inboundCidrs } }),
+    };
+}
+function authCredentials(auth) {
+    if (auth.apiKey !== undefined)
+        return { case: "apiKey", value: auth.apiKey };
+    if (auth.tokenPair !== undefined)
+        return {
+            case: "tokenPair",
+            value: auth.tokenPair,
+        };
+    if (auth.bearerToken !== undefined)
+        return {
+            case: "bearerToken",
+            value: auth.bearerToken,
+        };
+    if (auth.oauthRefresh !== undefined)
+        return {
+            case: "oauthRefresh",
+            value: auth.oauthRefresh,
+        };
+    return { case: undefined };
+}
+function sourceKind(source) {
+    if (source.providerDefault !== undefined)
+        return {
+            case: "providerDefault",
+            value: {},
+        };
+    if (source.image !== undefined)
+        return { case: "image", value: source.image };
+    if (source.snapshot !== undefined)
+        return { case: "snapshot", value: source.snapshot };
+    if (source.warmPool !== undefined)
+        return { case: "warmPool", value: source.warmPool };
+    return { case: undefined };
+}
+function readinessCheck(readiness) {
+    if (readiness.tcpPort !== undefined)
+        return { case: "tcpPort", value: readiness.tcpPort };
+    if (readiness.command !== undefined)
+        return { case: "command", value: readiness.command };
+    return { case: undefined };
+}

package/dist/contracts/config_paths.d.ts

@@ -0,0 +1,44 @@
+/** Canonical path "auth". */
+export declare const ConfigFieldAuth: "auth";
+/** Canonical path "auth.api_key". */
+export declare const ConfigFieldAuthApiKey: "auth.api_key";
+/** Canonical path "auth.api_key.key". */
+export declare const ConfigFieldAuthApiKeyKey: "auth.api_key.key";
+/** Canonical path "auth.token_pair". */
+export declare const ConfigFieldAuthTokenPair: "auth.token_pair";
+/** Canonical path "auth.token_pair.id". */
+export declare const ConfigFieldAuthTokenPairId: "auth.token_pair.id";
+/** Canonical path "auth.token_pair.secret". */
+export declare const ConfigFieldAuthTokenPairSecret: "auth.token_pair.secret";
+/** Canonical path "auth.bearer_token". */
+export declare const ConfigFieldAuthBearerToken: "auth.bearer_token";
+/** Canonical path "auth.bearer_token.token". */
+export declare const ConfigFieldAuthBearerTokenToken: "auth.bearer_token.token";
+/** Canonical path "auth.oauth_refresh". */
+export declare const ConfigFieldAuthOauthRefresh: "auth.oauth_refresh";
+/** Canonical path "auth.oauth_refresh.refresh_token". */
+export declare const ConfigFieldAuthOauthRefreshRefreshToken: "auth.oauth_refresh.refresh_token";
+/** Canonical path "auth.oauth_refresh.client_id". */
+export declare const ConfigFieldAuthOauthRefreshClientId: "auth.oauth_refresh.client_id";
+/** Canonical path "auth.oauth_refresh.client_secret". */
+export declare const ConfigFieldAuthOauthRefreshClientSecret: "auth.oauth_refresh.client_secret";
+/** Canonical path "auth.oauth_refresh.jwt_key". */
+export declare const ConfigFieldAuthOauthRefreshJwtKey: "auth.oauth_refresh.jwt_key";
+/** Canonical path "endpoint". */
+export declare const ConfigFieldEndpoint: "endpoint";
+/** Canonical path "region". */
+export declare const ConfigFieldRegion: "region";
+/** Canonical path "scope". */
+export declare const ConfigFieldScope: "scope";
+/** Canonical path "scope.app_name". */
+export declare const ConfigFieldScopeAppName: "scope.app_name";
+/** Canonical path "scope.environment". */
+export declare const ConfigFieldScopeEnvironment: "scope.environment";
+/** Canonical path "scope.organization_id". */
+export declare const ConfigFieldScopeOrganizationId: "scope.organization_id";
+/** Canonical path "scope.project_id". */
+export declare const ConfigFieldScopeProjectId: "scope.project_id";
+/** Canonical path "timeout". */
+export declare const ConfigFieldTimeout: "timeout";
+/** Canonical path "provider". */
+export declare const ConfigFieldProvider: "provider";

package/dist/contracts/config_paths.js

@@ -0,0 +1,50 @@
+// Config field-path constants identify client settings in errors.
+// Values are canonical protobuf paths (snake_case), matching Go.
+//
+// Example:
+//
+//   console.log(ConfigFieldEndpoint); // endpoint
+/** Canonical path "auth". */
+export const ConfigFieldAuth = "auth";
+/** Canonical path "auth.api_key". */
+export const ConfigFieldAuthApiKey = "auth.api_key";
+/** Canonical path "auth.api_key.key". */
+export const ConfigFieldAuthApiKeyKey = "auth.api_key.key";
+/** Canonical path "auth.token_pair". */
+export const ConfigFieldAuthTokenPair = "auth.token_pair";
+/** Canonical path "auth.token_pair.id". */
+export const ConfigFieldAuthTokenPairId = "auth.token_pair.id";
+/** Canonical path "auth.token_pair.secret". */
+export const ConfigFieldAuthTokenPairSecret = "auth.token_pair.secret";
+/** Canonical path "auth.bearer_token". */
+export const ConfigFieldAuthBearerToken = "auth.bearer_token";
+/** Canonical path "auth.bearer_token.token". */
+export const ConfigFieldAuthBearerTokenToken = "auth.bearer_token.token";
+/** Canonical path "auth.oauth_refresh". */
+export const ConfigFieldAuthOauthRefresh = "auth.oauth_refresh";
+/** Canonical path "auth.oauth_refresh.refresh_token". */
+export const ConfigFieldAuthOauthRefreshRefreshToken = "auth.oauth_refresh.refresh_token";
+/** Canonical path "auth.oauth_refresh.client_id". */
+export const ConfigFieldAuthOauthRefreshClientId = "auth.oauth_refresh.client_id";
+/** Canonical path "auth.oauth_refresh.client_secret". */
+export const ConfigFieldAuthOauthRefreshClientSecret = "auth.oauth_refresh.client_secret";
+/** Canonical path "auth.oauth_refresh.jwt_key". */
+export const ConfigFieldAuthOauthRefreshJwtKey = "auth.oauth_refresh.jwt_key";
+/** Canonical path "endpoint". */
+export const ConfigFieldEndpoint = "endpoint";
+/** Canonical path "region". */
+export const ConfigFieldRegion = "region";
+/** Canonical path "scope". */
+export const ConfigFieldScope = "scope";
+/** Canonical path "scope.app_name". */
+export const ConfigFieldScopeAppName = "scope.app_name";
+/** Canonical path "scope.environment". */
+export const ConfigFieldScopeEnvironment = "scope.environment";
+/** Canonical path "scope.organization_id". */
+export const ConfigFieldScopeOrganizationId = "scope.organization_id";
+/** Canonical path "scope.project_id". */
+export const ConfigFieldScopeProjectId = "scope.project_id";
+/** Canonical path "timeout". */
+export const ConfigFieldTimeout = "timeout";
+/** Canonical path "provider". */
+export const ConfigFieldProvider = "provider";