@toshicloud/sdk 0.4.0 → 0.5.1

package/dist/errors.js

@@ -1,3 +1,5 @@
+import { BinaryReader, WireType } from "@bufbuild/protobuf/wire";
+import { ConnectError } from "@connectrpc/connect";
 /** A command that ended non-zero, or was cancelled before it had a status (errors.go:9-26). */
 export class ExitError extends Error {
     /** The execution the exit belongs to. */
@@ -75,3 +77,209 @@ function describe(cause) {
     }
     return "the stream ended";
 }
+/** The reasons a call is refused for a product. */
+export const ProductReason = {
+    /**
+     * The product is off for the workspace; the code is FailedPrecondition, and
+     * `cause` says which input turned it off.
+     */
+    Unavailable: "PRODUCT_UNAVAILABLE",
+};
+/** The inputs that turn a product off. */
+export const ProductCause = {
+    /** The deployment's build does not include the product. */
+    Build: "build",
+    /** The deployment's config turns the product off. */
+    Operator: "operator",
+    /** The workspace's plan leaves the product out. */
+    Plan: "plan",
+    /** The workspace's settings turn the product off. */
+    Workspace: "workspace",
+};
+const productReasons = new Set(Object.values(ProductReason));
+/** The reasons the API names on a refusal that is not a product's. */
+export const RefusalReason = {
+    /** The Windows VM takes no display input; the code is FailedPrecondition. */
+    DisplayInputNotEnabled: "DISPLAY_INPUT_NOT_ENABLED",
+    /** The image already has a build running; the code is FailedPrecondition. */
+    ImageBuildInProgress: "IMAGE_BUILD_IN_PROGRESS",
+    /** The registry of the revision's image could not say whether it serves the digest; the code is FailedPrecondition. */
+    ImageCheckFailed: "IMAGE_CHECK_FAILED",
+    /** A workload or a service revision still uses the image; the code is FailedPrecondition. */
+    ImageInUse: "IMAGE_IN_USE",
+    /** Another live image of the workspace has the name; the code is AlreadyExists. */
+    ImageNameTaken: "IMAGE_NAME_TAKEN",
+    /** A workspace image named by a job, a sandbox or a service revision has no ready version; the code is FailedPrecondition. */
+    ImageNotReady: "IMAGE_NOT_READY",
+    /** The revision's registry answered that it does not serve the image digest; the code is FailedPrecondition. */
+    ImageNotServed: "IMAGE_NOT_SERVED",
+    /** The call would remove the caller's last identity; the code is FailedPrecondition. */
+    LastIdentity: "LAST_IDENTITY",
+    /** The call would remove the workspace's last member; the code is FailedPrecondition. */
+    LastMember: "LAST_MEMBER",
+    /** The call would leave the workspace without an owner; the code is FailedPrecondition. */
+    LastOwner: "LAST_OWNER",
+    /** A role change names a permission the caller does not hold where the role applies; the code is PermissionDenied. */
+    PermissionMissing: "PERMISSION_MISSING",
+    /** The workspace's plan does not include images; the code is FailedPrecondition. */
+    PlanExcludesImages: "PLAN_EXCLUDES_IMAGES",
+    /** A Windows job Toshi licenses opens no display session; the code is FailedPrecondition. */
+    ToshiLicensedWindows: "TOSHI_LICENSED_WINDOWS",
+};
+const refusalReasons = new Set(Object.values(RefusalReason));
+// The ErrorInfo domain of the API's refusals.
+const errorInfoDomain = "toshi.run";
+/**
+ * The API's refusal of a call for a product that is off for the workspace.
+ * Every call the client makes throws it in place of the ConnectError, wait,
+ * watch and execute included. It is a ConnectError, so `instanceof
+ * ConnectError` and `code` read as before; test for it with
+ * {@link isProductError}.
+ */
+export class ProductError extends ConnectError {
+    /** The product's ID, such as `runners`. */
+    product;
+    reason;
+    /** The input that turned the product off, the refusal's `cause` metadata: `build`, `operator`, `plan` or `workspace`. */
+    productCause;
+    /** How far a product the deployment turns off has wound down: `no_new_work`, `draining` or `stopped`; empty otherwise. */
+    state;
+    constructor(err, reason, metadata) {
+        super(err.rawMessage, err.code, err.metadata, undefined, err);
+        // ConnectError's instanceof accepts a subclass only by this name.
+        this.name = "ConnectError";
+        this.details = err.details;
+        this.product = metadata.get("product") ?? "";
+        this.reason = reason;
+        this.productCause = (metadata.get("cause") ?? "");
+        this.state = metadata.get("state") ?? "";
+    }
+    // ConnectError's own check would accept any ConnectError.
+    static [Symbol.hasInstance](v) {
+        return Function.prototype[Symbol.hasInstance].call(ProductError, v);
+    }
+}
+/** Reports whether err is a product's refusal. */
+export function isProductError(err) {
+    return err instanceof ProductError;
+}
+/**
+ * The API's refusal that names a reason: an image still in use, a plan
+ * without images, a last identity, a rollback whose revision's image is gone,
+ * and the rest of {@link RefusalReason}. Every call the client makes throws
+ * it in place of the ConnectError. It is a ConnectError, so `instanceof
+ * ConnectError` and `code` read as before; test for it with
+ * {@link isRefusalError}.
+ */
+export class RefusalError extends ConnectError {
+    reason;
+    constructor(err, reason) {
+        super(err.rawMessage, err.code, err.metadata, undefined, err);
+        // ConnectError's instanceof accepts a subclass only by this name.
+        this.name = "ConnectError";
+        this.details = err.details;
+        this.reason = reason;
+    }
+    // ConnectError's own check would accept any ConnectError.
+    static [Symbol.hasInstance](v) {
+        return Function.prototype[Symbol.hasInstance].call(RefusalError, v);
+    }
+}
+/** Reports whether err is a refusal that names a reason this module knows. */
+export function isRefusalError(err) {
+    return err instanceof RefusalError;
+}
+/** err as a ProductError when it is a product's refusal, and err unchanged otherwise. */
+export function asProductError(err) {
+    if (!(err instanceof ConnectError) || err instanceof ProductError) {
+        return err;
+    }
+    for (const detail of err.details) {
+        if (!("type" in detail) || detail.type !== "google.rpc.ErrorInfo") {
+            continue;
+        }
+        const info = decodeErrorInfo(detail.value);
+        if (info === undefined || info.domain !== errorInfoDomain || !productReasons.has(info.reason)) {
+            continue;
+        }
+        return new ProductError(err, info.reason, info.metadata);
+    }
+    return err;
+}
+/** err as a RefusalError when it is a refusal that names a reason this module knows, and err unchanged otherwise. */
+export function asRefusalError(err) {
+    if (!(err instanceof ConnectError) || err instanceof RefusalError) {
+        return err;
+    }
+    for (const detail of err.details) {
+        if (!("type" in detail) || detail.type !== "google.rpc.ErrorInfo") {
+            continue;
+        }
+        const info = decodeErrorInfo(detail.value);
+        if (info === undefined || info.domain !== errorInfoDomain || !refusalReasons.has(info.reason)) {
+            continue;
+        }
+        return new RefusalError(err, info.reason);
+    }
+    return err;
+}
+/** err as one of this module's typed errors when the API's ErrorInfo detail names a reason it knows, and err unchanged otherwise. */
+export function asTypedError(err) {
+    return asRefusalError(asProductError(err));
+}
+/**
+ * Reads a google.rpc.ErrorInfo message: reason (1), domain (2) and metadata
+ * (3), a map of strings. It reads the wire format itself, so the SDK needs no
+ * package for the googleapis types.
+ */
+function decodeErrorInfo(bytes) {
+    const info = { reason: "", domain: "", metadata: new Map() };
+    try {
+        const reader = new BinaryReader(bytes);
+        while (reader.pos < reader.len) {
+            const [field, wireType] = reader.tag();
+            if (wireType !== WireType.LengthDelimited) {
+                reader.skip(wireType);
+                continue;
+            }
+            switch (field) {
+                case 1:
+                    info.reason = reader.string();
+                    break;
+                case 2:
+                    info.domain = reader.string();
+                    break;
+                case 3: {
+                    const [key, value] = decodeMapEntry(reader.bytes());
+                    info.metadata.set(key, value);
+                    break;
+                }
+                default:
+                    reader.skip(wireType);
+            }
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return info;
+}
+/** Reads one entry of a map<string, string>: key (1), value (2). */
+function decodeMapEntry(bytes) {
+    let key = "";
+    let value = "";
+    const reader = new BinaryReader(bytes);
+    while (reader.pos < reader.len) {
+        const [field, wireType] = reader.tag();
+        if (wireType === WireType.LengthDelimited && field === 1) {
+            key = reader.string();
+        }
+        else if (wireType === WireType.LengthDelimited && field === 2) {
+            value = reader.string();
+        }
+        else {
+            reader.skip(wireType);
+        }
+    }
+    return [key, value];
+}

package/dist/gen/toshi/permission_pb.d.ts

@@ -0,0 +1,244 @@
+import type { GenExtension, GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { FieldOptions, MethodOptions } from "@bufbuild/protobuf/wkt";
+import type { Message } from "@bufbuild/protobuf";
+/**
+ * Describes the file toshi/permission.proto.
+ */
+export declare const file_toshi_permission: GenFile;
+/**
+ * Audit is the audit event a call records.
+ *
+ * @generated from message toshi.Audit
+ */
+export type Audit = Message<"toshi.Audit"> & {
+    /**
+     * action is "<noun>.<verb>" with the verb in the past tense. Unset, it is
+     * the method's name: CreateSandbox records "sandbox.created". The build
+     * fails a method whose verb it cannot put in the past tense, or whose name
+     * gives the action this field names. "none" records nothing, for a call
+     * no Workspace API caller makes, such as a workload's upload.
+     *
+     * @generated from field: string action = 1;
+     */
+    action: string;
+    /**
+     * target is what the call acts on, as "<kind>:<source>", or "none". Unset,
+     * the kind is the action's noun and the source the response's id for a
+     * call that creates (Create, Reserve, Open) and the request's id
+     * otherwise: "id" or "<kind>_id", or for a create "<kind>.id" of the
+     * response. A source is a request field path, such as "job_id" or
+     * "start.sandbox_id", a response field path after "response.", such as
+     * "response.endpoint.id", "workspace" for the call's workspace, or
+     * "project" for the project the call resolved.
+     *
+     * @generated from field: string target = 2;
+     */
+    target: string;
+};
+/**
+ * Audit is the audit event a call records.
+ *
+ * @generated from message toshi.Audit
+ */
+export type AuditJson = {
+    /**
+     * action is "<noun>.<verb>" with the verb in the past tense. Unset, it is
+     * the method's name: CreateSandbox records "sandbox.created". The build
+     * fails a method whose verb it cannot put in the past tense, or whose name
+     * gives the action this field names. "none" records nothing, for a call
+     * no Workspace API caller makes, such as a workload's upload.
+     *
+     * @generated from field: string action = 1;
+     */
+    action?: string;
+    /**
+     * target is what the call acts on, as "<kind>:<source>", or "none". Unset,
+     * the kind is the action's noun and the source the response's id for a
+     * call that creates (Create, Reserve, Open) and the request's id
+     * otherwise: "id" or "<kind>_id", or for a create "<kind>.id" of the
+     * response. A source is a request field path, such as "job_id" or
+     * "start.sandbox_id", a response field path after "response.", such as
+     * "response.endpoint.id", "workspace" for the call's workspace, or
+     * "project" for the project the call resolved.
+     *
+     * @generated from field: string target = 2;
+     */
+    target?: string;
+};
+/**
+ * Describes the message toshi.Audit.
+ * Use `create(AuditSchema)` to create a new message.
+ */
+export declare const AuditSchema: GenMessage<Audit, {
+    jsonType: AuditJson;
+}>;
+/**
+ * MCP is how a call appears as a tool of the MCP server: each hint that is
+ * set replaces the one the generator's rules give, and exclude leaves the
+ * call out of the tool list.
+ *
+ * @generated from message toshi.MCP
+ */
+export type MCP = Message<"toshi.MCP"> & {
+    /**
+     * read_only is the tool's readOnlyHint: the call changes nothing.
+     *
+     * @generated from field: optional bool read_only = 1;
+     */
+    readOnly?: boolean | undefined;
+    /**
+     * destructive is the tool's destructiveHint: the call may end or remove
+     * something it cannot bring back.
+     *
+     * @generated from field: optional bool destructive = 2;
+     */
+    destructive?: boolean | undefined;
+    /**
+     * idempotent is the tool's idempotentHint: a second call with the same
+     * input changes nothing more.
+     *
+     * @generated from field: optional bool idempotent = 3;
+     */
+    idempotent?: boolean | undefined;
+    /**
+     * open_world is the tool's openWorldHint: the call reaches past the
+     * workspace, such as a workload that reaches what its network policy
+     * allows.
+     *
+     * @generated from field: optional bool open_world = 4;
+     */
+    openWorld?: boolean | undefined;
+    /**
+     * exclude leaves the call out, for a call that makes no sense as a tool,
+     * such as one only a workload's own token may make.
+     *
+     * @generated from field: bool exclude = 5;
+     */
+    exclude: boolean;
+};
+/**
+ * MCP is how a call appears as a tool of the MCP server: each hint that is
+ * set replaces the one the generator's rules give, and exclude leaves the
+ * call out of the tool list.
+ *
+ * @generated from message toshi.MCP
+ */
+export type MCPJson = {
+    /**
+     * read_only is the tool's readOnlyHint: the call changes nothing.
+     *
+     * @generated from field: optional bool read_only = 1;
+     */
+    readOnly?: boolean;
+    /**
+     * destructive is the tool's destructiveHint: the call may end or remove
+     * something it cannot bring back.
+     *
+     * @generated from field: optional bool destructive = 2;
+     */
+    destructive?: boolean;
+    /**
+     * idempotent is the tool's idempotentHint: a second call with the same
+     * input changes nothing more.
+     *
+     * @generated from field: optional bool idempotent = 3;
+     */
+    idempotent?: boolean;
+    /**
+     * open_world is the tool's openWorldHint: the call reaches past the
+     * workspace, such as a workload that reaches what its network policy
+     * allows.
+     *
+     * @generated from field: optional bool open_world = 4;
+     */
+    openWorld?: boolean;
+    /**
+     * exclude leaves the call out, for a call that makes no sense as a tool,
+     * such as one only a workload's own token may make.
+     *
+     * @generated from field: bool exclude = 5;
+     */
+    exclude?: boolean;
+};
+/**
+ * Describes the message toshi.MCP.
+ * Use `create(MCPSchema)` to create a new message.
+ */
+export declare const MCPSchema: GenMessage<MCP, {
+    jsonType: MCPJson;
+}>;
+/**
+ * permission names what a caller needs to make the call: an area and a
+ * level. "<area>.read" sees what the area holds and "<area>.write" changes
+ * it, where the area is a product, such as "sandboxes", or a part of the
+ * workspace, such as "secrets". A call that needs more than its area's
+ * level names a permission of its own, such as "debug.connect" for the key
+ * into a host job's debug session.
+ *
+ * Every Workspace API method carries it, and a method without it fails the
+ * build: the control plane's check table and the permissions page are
+ * generated from it. A workspace that is suspended keeps the calls whose
+ * level is "read".
+ *
+ * @generated from extension: string permission = 51000;
+ */
+export declare const permission: GenExtension<MethodOptions, string>;
+/**
+ * scope names what a call acts in: "workspace", the default when the
+ * option is absent, or "project" or "environment" for a call that names a
+ * project or an environment of the workspace, or a resource that belongs
+ * to one. A token limited to a project, or to one of its environments,
+ * makes only the calls whose scope is "project" or "environment".
+ *
+ * A method whose request has a project or environment field (project,
+ * project_id, environment, environment_id) names its scope, and the build
+ * checks it against that field: "environment" when the request has an
+ * environment field, "project" when it has only a project field, or
+ * "workspace" when the field is not where the call acts, such as the
+ * project a new token is limited to.
+ *
+ * @generated from extension: string scope = 51001;
+ */
+export declare const scope: GenExtension<MethodOptions, string>;
+/**
+ * audit names the audit event a call records when its action or target
+ * is not the one its name gives. Every call that changes something
+ * records one event: on the Workspace API a call whose permission's level
+ * is not "read", on the operator API a call whose verb is not a read
+ * (Get, List, Watch, Wait, Summarise, Suggest, Export, Discover). A read
+ * whose option names an action records one too.
+ *
+ * @generated from extension: toshi.Audit audit = 51002;
+ */
+export declare const audit: GenExtension<MethodOptions, Audit>;
+/**
+ * by_field marks an update call that needs no permission of its own: each
+ * field its mask names needs its field group's permission, the field's
+ * field_permission or, for a field without one, the method's permission.
+ * The caller needs at least one of them to make the call, and the
+ * handler checks each field the mask names before it writes; a mask that
+ * names nothing needs any one.
+ *
+ * @generated from extension: bool by_field = 51004;
+ */
+export declare const by_field: GenExtension<MethodOptions, boolean>;
+/**
+ * mcp sets how the call appears as a tool of the MCP server, where the
+ * rules its generator applies give the wrong answer. Without it a call
+ * whose permission's level is "read" is read-only and idempotent, a call
+ * whose name begins with Delete, Cancel, Revoke, Remove, Stop or Rollback
+ * is destructive, and no call reaches outside the workspace.
+ *
+ * @generated from extension: toshi.MCP mcp = 51005;
+ */
+export declare const mcp: GenExtension<MethodOptions, MCP>;
+/**
+ * field_permission names what a caller needs to change the field through
+ * the mask of an update call marked by_field: a field group of its own,
+ * such as "billing.write" for a workspace's spending limits. A field
+ * without it needs the method's permission. The build checks the name's
+ * shape, and the permissions page lists the field groups.
+ *
+ * @generated from extension: string field_permission = 51003;
+ */
+export declare const field_permission: GenExtension<FieldOptions, string>;

package/dist/gen/toshi/permission_pb.js

@@ -0,0 +1,94 @@
+// @generated by protoc-gen-es v2.16.0 with parameter "target=ts,json_types=true,import_extension=js"
+// @generated from file toshi/permission.proto (package toshi, syntax proto3)
+/* eslint-disable */
+import { extDesc, fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
+import { file_google_protobuf_descriptor } from "@bufbuild/protobuf/wkt";
+/**
+ * Describes the file toshi/permission.proto.
+ */
+export const file_toshi_permission = /*@__PURE__*/ fileDesc("ChZ0b3NoaS9wZXJtaXNzaW9uLnByb3RvEgV0b3NoaSInCgVBdWRpdBIOCgZhY3Rpb24YASABKAkSDgoGdGFyZ2V0GAIgASgJIrYBCgNNQ1ASFgoJcmVhZF9vbmx5GAEgASgISACIAQESGAoLZGVzdHJ1Y3RpdmUYAiABKAhIAYgBARIXCgppZGVtcG90ZW50GAMgASgISAKIAQESFwoKb3Blbl93b3JsZBgEIAEoCEgDiAEBEg8KB2V4Y2x1ZGUYBSABKAhCDAoKX3JlYWRfb25seUIOCgxfZGVzdHJ1Y3RpdmVCDQoLX2lkZW1wb3RlbnRCDQoLX29wZW5fd29ybGQ6QAoKcGVybWlzc2lvbhIeLmdvb2dsZS5wcm90b2J1Zi5NZXRob2RPcHRpb25zGLiOAyABKAlSCnBlcm1pc3Npb246NgoFc2NvcGUSHi5nb29nbGUucHJvdG9idWYuTWV0aG9kT3B0aW9ucxi5jgMgASgJUgVzY29wZTpECgVhdWRpdBIeLmdvb2dsZS5wcm90b2J1Zi5NZXRob2RPcHRpb25zGLqOAyABKAsyDC50b3NoaS5BdWRpdFIFYXVkaXQ6OwoIYnlfZmllbGQSHi5nb29nbGUucHJvdG9idWYuTWV0aG9kT3B0aW9ucxi8jgMgASgIUgdieUZpZWxkOj4KA21jcBIeLmdvb2dsZS5wcm90b2J1Zi5NZXRob2RPcHRpb25zGL2OAyABKAsyCi50b3NoaS5NQ1BSA21jcDpKChBmaWVsZF9wZXJtaXNzaW9uEh0uZ29vZ2xlLnByb3RvYnVmLkZpZWxkT3B0aW9ucxi7jgMgASgJUg9maWVsZFBlcm1pc3Npb25CHlocZ28udG9zaGljbG91ZC5pby9hcGkvdG9zaGlwYmIGcHJvdG8z", [file_google_protobuf_descriptor]);
+/**
+ * Describes the message toshi.Audit.
+ * Use `create(AuditSchema)` to create a new message.
+ */
+export const AuditSchema = /*@__PURE__*/ messageDesc(file_toshi_permission, 0);
+/**
+ * Describes the message toshi.MCP.
+ * Use `create(MCPSchema)` to create a new message.
+ */
+export const MCPSchema = /*@__PURE__*/ messageDesc(file_toshi_permission, 1);
+/**
+ * permission names what a caller needs to make the call: an area and a
+ * level. "<area>.read" sees what the area holds and "<area>.write" changes
+ * it, where the area is a product, such as "sandboxes", or a part of the
+ * workspace, such as "secrets". A call that needs more than its area's
+ * level names a permission of its own, such as "debug.connect" for the key
+ * into a host job's debug session.
+ *
+ * Every Workspace API method carries it, and a method without it fails the
+ * build: the control plane's check table and the permissions page are
+ * generated from it. A workspace that is suspended keeps the calls whose
+ * level is "read".
+ *
+ * @generated from extension: string permission = 51000;
+ */
+export const permission = /*@__PURE__*/ extDesc(file_toshi_permission, 0);
+/**
+ * scope names what a call acts in: "workspace", the default when the
+ * option is absent, or "project" or "environment" for a call that names a
+ * project or an environment of the workspace, or a resource that belongs
+ * to one. A token limited to a project, or to one of its environments,
+ * makes only the calls whose scope is "project" or "environment".
+ *
+ * A method whose request has a project or environment field (project,
+ * project_id, environment, environment_id) names its scope, and the build
+ * checks it against that field: "environment" when the request has an
+ * environment field, "project" when it has only a project field, or
+ * "workspace" when the field is not where the call acts, such as the
+ * project a new token is limited to.
+ *
+ * @generated from extension: string scope = 51001;
+ */
+export const scope = /*@__PURE__*/ extDesc(file_toshi_permission, 1);
+/**
+ * audit names the audit event a call records when its action or target
+ * is not the one its name gives. Every call that changes something
+ * records one event: on the Workspace API a call whose permission's level
+ * is not "read", on the operator API a call whose verb is not a read
+ * (Get, List, Watch, Wait, Summarise, Suggest, Export, Discover). A read
+ * whose option names an action records one too.
+ *
+ * @generated from extension: toshi.Audit audit = 51002;
+ */
+export const audit = /*@__PURE__*/ extDesc(file_toshi_permission, 2);
+/**
+ * by_field marks an update call that needs no permission of its own: each
+ * field its mask names needs its field group's permission, the field's
+ * field_permission or, for a field without one, the method's permission.
+ * The caller needs at least one of them to make the call, and the
+ * handler checks each field the mask names before it writes; a mask that
+ * names nothing needs any one.
+ *
+ * @generated from extension: bool by_field = 51004;
+ */
+export const by_field = /*@__PURE__*/ extDesc(file_toshi_permission, 3);
+/**
+ * mcp sets how the call appears as a tool of the MCP server, where the
+ * rules its generator applies give the wrong answer. Without it a call
+ * whose permission's level is "read" is read-only and idempotent, a call
+ * whose name begins with Delete, Cancel, Revoke, Remove, Stop or Rollback
+ * is destructive, and no call reaches outside the workspace.
+ *
+ * @generated from extension: toshi.MCP mcp = 51005;
+ */
+export const mcp = /*@__PURE__*/ extDesc(file_toshi_permission, 4);
+/**
+ * field_permission names what a caller needs to change the field through
+ * the mask of an update call marked by_field: a field group of its own,
+ * such as "billing.write" for a workspace's spending limits. A field
+ * without it needs the method's permission. The build checks the name's
+ * shape, and the permissions page lists the field groups.
+ *
+ * @generated from extension: string field_permission = 51003;
+ */
+export const field_permission = /*@__PURE__*/ extDesc(file_toshi_permission, 5);