@gjermundgaraba/clankerbox-sdk 0.4.1 → 0.12.1

package/dist/client-BVzrg2pq.d.mts

@@ -0,0 +1,289 @@
+import { Context, Duration, Effect, Schema } from "effect";
+import { HttpClient } from "effect/http";
+//#region src/errors.d.ts
+declare const Invalid_base: Schema.Class<Invalid, Schema.TaggedStruct<"Invalid", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The request is malformed: a bad ID or name, an undeclared field, a value out of range. */
+declare class Invalid extends Invalid_base {
+  get retryable(): boolean;
+}
+declare const NotFound_base: Schema.Class<NotFound, Schema.TaggedStruct<"NotFound", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The machine or checkpoint doesn't exist. A `delete` that meets it is done. */
+declare class NotFound extends NotFound_base {
+  get retryable(): boolean;
+}
+declare const ConflictKind: Schema.Literals<readonly ["exists", "busy"]>;
+type ConflictKind = typeof ConflictKind.Type;
+declare const Conflict_base: Schema.Class<Conflict, Schema.TaggedStruct<"Conflict", {
+  readonly message: Schema.String;
+  readonly kind: Schema.Literals<readonly ["exists", "busy"]>;
+}>, import("effect/Cause").YieldableError>;
+/** The name is taken (`exists`), or another action holds the resource (`busy`). */
+declare class Conflict extends Conflict_base {
+  get retryable(): boolean;
+}
+declare const Precondition_base: Schema.Class<Precondition, Schema.TaggedStruct<"Precondition", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The resource's state doesn't allow the action, or no host offers the requested base. */
+declare class Precondition extends Precondition_base {
+  get retryable(): boolean;
+}
+declare const Capacity_base: Schema.Class<Capacity, Schema.TaggedStruct<"Capacity", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The host has no room now; room can free up, so a later call may succeed. */
+declare class Capacity extends Capacity_base {
+  get retryable(): boolean;
+}
+declare const Unavailable_base: Schema.Class<Unavailable, Schema.TaggedStruct<"Unavailable", {
+  readonly message: Schema.String;
+  readonly access: Schema.Literals<("read" | "write")[]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The client couldn't reach the host, or lost its reply. Only the client library produces
+ * it. `access` is the access of the action that met it: a mutation's request may have
+ * reached the host and run, so it is never retryable.
+ */
+declare class Unavailable extends Unavailable_base {
+  get retryable(): boolean;
+}
+declare const Internal_base: Schema.Class<Internal, Schema.TaggedStruct<"Internal", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class Internal extends Internal_base {
+  get retryable(): boolean;
+}
+/** What a host answers with; every action group declares these. */
+declare const hostErrors: readonly [typeof Invalid, typeof NotFound, typeof Conflict, typeof Precondition, typeof Capacity, typeof Internal];
+type HostError = InstanceType<(typeof hostErrors)[number]>;
+/** What a call through the client library fails with. */
+type ClankerboxError = HostError | Unavailable;
+/** The tag a host records on a failed action: always one of the errors it answers with. */
+declare const HostErrorTag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
+type HostErrorTag = typeof HostErrorTag.Type;
+/** The tag of any error a call through the client library can fail with. */
+declare const ErrorTag: Schema.Literals<readonly [...("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[], "Unavailable"]>;
+type ErrorTag = typeof ErrorTag.Type;
+//#endregion
+//#region src/resources.d.ts
+declare const Runtime: Schema.Literals<readonly ["smolvm", "tart", "boat"]>;
+type Runtime = typeof Runtime.Type;
+/** The mutations that record themselves on a resource's `action`. */
+declare const ActionName: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
+type ActionName = typeof ActionName.Type;
+/**
+ * A resource's last action: `running` while it holds the row, `failed` with its error
+ * after a native failure, `done` after a success. The next action replaces it.
+ */
+declare const ActionRecord: Schema.Struct<{
+  readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
+  readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
+  readonly error: Schema.optionalKey<Schema.Struct<{
+    readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
+    readonly message: Schema.String;
+  }>>;
+}>;
+type ActionRecord = typeof ActionRecord.Type;
+/** Where a machine's guest port 22 is reached. */
+declare const SshEndpoint: Schema.Struct<{
+  readonly host: Schema.String;
+  readonly port: Schema.Int;
+}>;
+type SshEndpoint = typeof SshEndpoint.Type;
+declare const Machine: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly runtime: Schema.Literals<readonly ["smolvm", "tart", "boat"]>;
+  readonly createdAt: Schema.DateTimeUtcFromString;
+  readonly base: Schema.String;
+  /** The label the client passed at create, normally its profile's name. */
+  readonly profile: Schema.optionalKey<Schema.String>;
+  readonly cpu: Schema.Int;
+  readonly ramMib: Schema.Int;
+  readonly diskGib: Schema.Int;
+  /**
+   * Read from the runtime, never stored: `missing` when the runtime doesn't have the machine,
+   * `unknown` when it couldn't be read.
+   */
+  readonly state: Schema.Literals<readonly ["running", "stopped", "missing", "unknown"]>;
+  readonly action: Schema.Struct<{
+    readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
+    readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
+    readonly error: Schema.optionalKey<Schema.Struct<{
+      readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
+      readonly message: Schema.String;
+    }>>;
+  }>;
+  readonly ssh: Schema.optionalKey<Schema.Struct<{
+    readonly host: Schema.String;
+    readonly port: Schema.Int;
+  }>>;
+  /** The guest's SSH host public key, as `<type> <base64>`. */
+  readonly hostKey: Schema.optionalKey<Schema.String>;
+}>;
+type Machine = typeof Machine.Type;
+declare const Checkpoint: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly createdAt: Schema.DateTimeUtcFromString;
+  /** The ID of the machine it was captured from. */
+  readonly machine: Schema.String;
+  /** What it holds, by runtime: `ram` (RAM and disks) on smolvm, `disk` on Tart and boat. */
+  readonly kind: Schema.Literals<readonly ["ram", "disk"]>;
+  readonly base: Schema.String;
+  readonly profile: Schema.optionalKey<Schema.String>;
+  readonly cpu: Schema.Int;
+  readonly ramMib: Schema.Int;
+  readonly diskGib: Schema.Int;
+  readonly action: Schema.Struct<{
+    readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
+    readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
+    readonly error: Schema.optionalKey<Schema.Struct<{
+      readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
+      readonly message: Schema.String;
+    }>>;
+  }>;
+}>;
+type Checkpoint = typeof Checkpoint.Type;
+/** The SDK's version, which is also the version of the clankerbox binaries it ships with. */
+declare const version: string;
+/** A version's major.minor: releases that share it speak the same API. */
+declare const release: (of: string) => string;
+declare const Host: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly runtime: Schema.Literals<readonly ["smolvm", "tart", "boat"]>;
+  /** The clankerbox version the host runs. */
+  readonly version: Schema.String;
+  /** The runtime's version; for boat, its API version. */
+  readonly runtimeVersion: Schema.String;
+  readonly bases: Schema.$Array<Schema.String>;
+}>;
+type Host = typeof Host.Type;
+/** A setup script and how long it may run. Nothing logs the script: it can carry secrets. */
+declare const Setup: Schema.Struct<{
+  readonly script: Schema.String;
+  readonly timeoutSeconds: Schema.Int;
+}>;
+type Setup = typeof Setup.Type;
+/**
+ * What a new machine is made from: a base, its sizes, an optional setup script with its
+ * timeout, and an optional `profile` label. A profile file fills these in; the host never
+ * sees the profile itself.
+ */
+declare const MachineSpec: Schema.Struct<{
+  base: Schema.String;
+  cpu: Schema.Int;
+  ramMib: Schema.Int;
+  diskGib: Schema.Int;
+  setup: Schema.optionalKey<Schema.Struct<{
+    readonly script: Schema.String;
+    readonly timeoutSeconds: Schema.Int;
+  }>>;
+  profile: Schema.optionalKey<Schema.String>;
+}>;
+type MachineSpec = typeof MachineSpec.Type;
+/**
+ * `machine.create`'s input: the spec and the new machine's full ID. The host checks that the ID
+ * names it, so a create never lands under another host's ID.
+ */
+declare const CreateRequest: Schema.Struct<{
+  readonly base: Schema.String;
+  readonly cpu: Schema.Int;
+  readonly ramMib: Schema.Int;
+  readonly diskGib: Schema.Int;
+  readonly setup: Schema.optionalKey<Schema.Struct<{
+    readonly script: Schema.String;
+    readonly timeoutSeconds: Schema.Int;
+  }>>;
+  readonly profile: Schema.optionalKey<Schema.String>;
+  readonly id: Schema.String;
+}>;
+type CreateRequest = typeof CreateRequest.Type;
+/**
+ * A profile file: a client-side file that fills in a create request. `setup.path` is a script
+ * file or a recipe directory, relative to the profile file, and comes with its timeout: the
+ * profile's author sets it, and there is no default. `host` places the create on that host
+ * instead of by base.
+ */
+declare const Profile: Schema.Struct<{
+  readonly base: Schema.String;
+  readonly cpu: Schema.Int;
+  readonly ramMib: Schema.Int;
+  readonly diskGib: Schema.Int;
+  readonly setup: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.String;
+    readonly timeoutSeconds: Schema.Int;
+  }>>;
+  readonly host: Schema.optionalKey<Schema.String>;
+}>;
+type Profile = typeof Profile.Type;
+declare namespace client_d_exports {
+  export { Client, CreateOptions, Gathered, HostEntry, Interface, Options, Unreachable, make };
+}
+/** One host a client talks to. `id` is the host part of every ID it holds. */
+declare const HostEntry: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly url: Schema.String;
+}>;
+type HostEntry = typeof HostEntry.Type;
+/** A host that didn't answer a fan-out, and why. */
+interface Unreachable {
+  readonly host: string;
+  readonly error: ClankerboxError;
+}
+/** What a fan-out gathered: every reachable host's answers, and the hosts that didn't answer. */
+interface Gathered<A> {
+  readonly answers: ReadonlyArray<A>;
+  readonly unreachable: ReadonlyArray<Unreachable>;
+}
+interface Options {
+  /**
+   * How long to wait for a mutation's reply, unbounded by default: a create with a long setup
+   * runs for as long as it takes. It only stops the wait, and a mutation that outlasts it fails
+   * like a lost reply.
+   */
+  readonly timeout?: Duration.Duration | undefined;
+  /**
+   * How long to wait for a read's reply, `readTimeout` (10 s) by default. A fan-out bounds each
+   * host's request on its own, so a host that doesn't answer in time is named among the
+   * unreachable.
+   */
+  readonly readTimeout?: Duration.Duration | undefined;
+}
+interface CreateOptions {
+  /** The host to create on, normally a profile's `host`. A full ID in `target` wins over it. */
+  readonly host?: string | undefined;
+}
+interface Interface {
+  /** Every host, with its bases. */
+  readonly hosts: Effect.Effect<Gathered<Host>>;
+  readonly machines: Effect.Effect<Gathered<Machine>>;
+  readonly checkpoints: Effect.Effect<Gathered<Checkpoint>>;
+  readonly machine: (id: string) => Effect.Effect<Machine, ClankerboxError>;
+  readonly checkpoint: (id: string) => Effect.Effect<Checkpoint, ClankerboxError>;
+  /**
+   * Creates a machine. `target` is a full ID, which names its host, or a name: then the
+   * options' host, or else the first host in the list that offers the spec's base.
+   */
+  readonly create: (target: string, spec: MachineSpec, options?: CreateOptions) => Effect.Effect<Machine, ClankerboxError>;
+  readonly start: (id: string) => Effect.Effect<Machine, ClankerboxError>;
+  readonly stop: (id: string) => Effect.Effect<Machine, ClankerboxError>;
+  readonly delete: (id: string) => Effect.Effect<void, ClankerboxError>;
+  /** Copies a machine to a new name on its host. */
+  readonly fork: (machine: string, name: string) => Effect.Effect<Machine, ClankerboxError>;
+  /** Creates a machine named `name` from a checkpoint, on the checkpoint's host. */
+  readonly restore: (checkpoint: string, name: string) => Effect.Effect<Machine, ClankerboxError>;
+  readonly capture: (machine: string, name: string) => Effect.Effect<Checkpoint, ClankerboxError>;
+  readonly deleteCheckpoint: (id: string) => Effect.Effect<void, ClankerboxError>;
+}
+declare const Client_base: Context.ServiceClass<Client, "@gjermundgaraba/clankerbox-sdk/Client", Interface>;
+declare class Client extends Client_base {}
+/**
+ * Builds a client over `hosts`, in placement order. Making it sends nothing. An empty list
+ * is Invalid, and so is a malformed entry or a host ID that appears twice: IDs route by it.
+ */
+declare const make: (hosts: ReadonlyArray<HostEntry>, options?: Options) => Effect.Effect<Interface, Invalid, HttpClient.HttpClient>;
+//#endregion
+export { hostErrors as A, HostError as C, NotFound as D, Invalid as E, Precondition as O, ErrorTag as S, Internal as T, version as _, ActionName as a, Conflict as b, CreateRequest as c, MachineSpec as d, Profile as f, release as g, SshEndpoint as h, client_d_exports as i, Unavailable as k, Host as l, Setup as m, HostEntry as n, ActionRecord as o, Runtime as p, Options as r, Checkpoint as s, Client as t, Machine as u, Capacity as v, HostErrorTag as w, ConflictKind as x, ClankerboxError as y };