endia 0.0.0-stage → 0.0.2

package/dist/groups/operations.js

@@ -0,0 +1,174 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { EastIndiaApiError } from "../errors.js";
+import { Routes } from "../routes.js";
+import { QueryText } from "../transport/query-text.js";
+/** The states after which an operation never changes again. */
+const FinalStates = new Set(["succeeded", "failed", "cancelled", "interrupted"]);
+/**
+ * The pause before a followed log is read again when it ended while the operation had not yet finished, as when the connection
+ * broke. It keeps a service that keeps closing the stream from being asked again at once, over and over.
+ */
+const FollowAgainDelayMilliseconds = 1000;
+/**
+ * Says whether an operation has finished: succeeded, failed, been cancelled or been interrupted.
+ *
+ * @param operation - The operation as last read.
+ * @returns True when its state never changes again.
+ */
+export function isFinished(operation) {
+    return FinalStates.has(operation.state);
+}
+/**
+ * The operation routes: list, inspect, read the log, cancel; and handles that follow one operation to its end. Every route that
+ * starts work returns an `OperationHandle` built here.
+ */
+export class OperationsClient {
+    connection;
+    /** @internal */
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Lists every kept operation, newest first: `endia operation ls`.
+     *
+     * @param options - `filters` such as `{ state: ["running"], kind: ["build"] }`.
+     * @returns The operations.
+     */
+    list(options = {}) {
+        return this.connection.read(Routes.operations + new QueryText().addJson("filters", options.filters).toString(), options.signal);
+    }
+    /**
+     * Reads one operation: `endia operation inspect`.
+     *
+     * @param id - The operation ID or a unique prefix of it.
+     * @param signal - Cancels the request.
+     * @returns The operation.
+     */
+    inspect(id, signal) {
+        return this.connection.read(Routes.operation(id), signal);
+    }
+    /**
+     * Opens an operation's log, the lines the command prints as the CLI prints them: `endia operation logs`.
+     *
+     * @param id - The operation ID or a unique prefix of it.
+     * @param options - With `follow`, the stream stays open until the operation finishes.
+     * @returns The log as UTF-8 text.
+     */
+    async logs(id, options = {}) {
+        const query = new QueryText().add("follow", options.follow ?? false).add("tail", options.tail);
+        const stream = await this.connection.openStream({ method: "GET", path: Routes.operationLog(id) + query.toString(), signal: options.signal });
+        return stream.setEncoding("utf8");
+    }
+    /**
+     * Asks the service to cancel an operation: `endia operation cancel`. A build or import cleans up as on failure; a fleet or machine
+     * operation stops before its next machine step; a prune stops before its next deletion.
+     *
+     * @param id - The operation ID or a unique prefix of it.
+     * @param signal - Cancels the request.
+     * @returns The operation in `cancelling`, or unchanged when it had already finished.
+     */
+    cancel(id, signal) {
+        return this.connection.change({ method: "POST", path: Routes.operationCancel(id), signal });
+    }
+    /**
+     * Wraps an operation that was read elsewhere, such as one another program started, in a handle that follows it and waits for its
+     * end.
+     *
+     * @param operation - The operation as last read.
+     * @returns The handle.
+     */
+    handle(operation) {
+        return new OperationHandle(this, operation);
+    }
+}
+/**
+ * Work the service has accepted and carries out in the background: a build, an import, a fleet or machine change, or a prune. The
+ * handle follows that work: it reads the operation's state, follows its log, cancels it, and waits for it to finish.
+ *
+ * @typeParam TResult - The result the operation gives when it succeeds, such as `BuildResult`.
+ */
+export class OperationHandle {
+    operations;
+    /** The operation as the service answered when it accepted the work. */
+    accepted;
+    /** @internal */
+    constructor(operations, accepted) {
+        this.operations = operations;
+        this.accepted = accepted;
+    }
+    /** The operation ID: 32 lower-case hexadecimal digits. */
+    get id() {
+        return this.accepted.id;
+    }
+    /**
+     * Reads the operation as it stands now.
+     *
+     * @param signal - Cancels the request.
+     * @returns The operation.
+     */
+    inspect(signal) {
+        return this.operations.inspect(this.id, signal);
+    }
+    /**
+     * Opens the operation's log.
+     *
+     * @param options - With `follow`, the stream stays open until the operation finishes.
+     * @returns The log as UTF-8 text.
+     */
+    logs(options = {}) {
+        return this.operations.logs(this.id, options);
+    }
+    /**
+     * Asks the service to cancel the operation. The operation then ends `cancelled`, which `wait` reports.
+     *
+     * @param signal - Cancels the request.
+     * @returns The operation in `cancelling`, or unchanged when it had already finished.
+     */
+    cancel(signal) {
+        return this.operations.cancel(this.id, signal);
+    }
+    /**
+     * Waits until the operation finishes, whatever its outcome, by following its log to the end as the CLI does.
+     *
+     * When the followed log ends before the operation has finished, as when the connection breaks, the log is opened again after a
+     * pause. The log only grows, so the text `onLog` has already received is skipped and each piece reaches it once.
+     *
+     * @param options - `onLog` receives the log as it is written.
+     * @returns The finished operation, in `succeeded`, `failed`, `cancelled` or `interrupted`.
+     */
+    async wait(options = {}) {
+        let delivered = 0;
+        for (;;) {
+            const log = await this.logs({ follow: true, signal: options.signal });
+            let read = 0;
+            for await (const text of log) {
+                const unseen = text.slice(Math.max(0, delivered - read));
+                read += text.length;
+                delivered += unseen.length;
+                if (unseen.length > 0) {
+                    options.onLog?.(unseen);
+                }
+            }
+            const operation = await this.inspect(options.signal);
+            if (isFinished(operation)) {
+                return operation;
+            }
+            await delay(FollowAgainDelayMilliseconds, undefined, { signal: options.signal });
+        }
+    }
+    /**
+     * Waits until the operation finishes and gives its result.
+     *
+     * @param options - `onLog` receives the log as it is written.
+     * @returns The result of the succeeded operation.
+     * @throws EastIndiaApiError when the operation failed, was cancelled or was interrupted; its `code` is the operation's error code,
+     * such as `BUILD_FAILED`, and its `operation` is the finished operation.
+     */
+    async result(options = {}) {
+        const operation = await this.wait(options);
+        if (operation.state !== "succeeded") {
+            throw EastIndiaApiError.fromOperation(operation);
+        }
+        return operation.result;
+    }
+}

package/dist/groups/processes.d.ts

@@ -0,0 +1,77 @@
+import type { Timestamp } from "../contract/common.js";
+import type { ProcessDetail, ProcessLogLine, ProcessStopResult, ProcessSummary, ProcessWaitResult } from "../contract/processes.js";
+/** Which process a request means, beyond its ID. */
+export interface ProcessIdentity {
+    /**
+     * The time the process must have started, copied from the answer that named the process, such as the `started` member of a
+     * detached exec's answer. Windows reuses process IDs, so the time tells the process apart from a later one with the same ID.
+     * When the process with the ID started at another time, the service refuses the request with `NOT_FOUND`. When `started` is
+     * undefined, the request means whichever process has the ID.
+     */
+    readonly started?: Timestamp;
+    readonly signal?: AbortSignal;
+}
+/**
+ * The process routes of a running machine: list, inspect, wait, stop and read the output of a program started detached. A request
+ * names a process by its Windows process ID, which a detached exec and a desktop launch return.
+ */
+export declare class ProcessesClient {
+    private readonly connection;
+    /**
+     * Lists the machine's processes: `endia process ls`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param signal - Cancels the request.
+     * @returns The processes.
+     */
+    list(machine: string, signal?: AbortSignal): Promise<ProcessSummary[]>;
+    /**
+     * Reads one process: `endia process inspect`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param processId - The Windows process ID.
+     * @param options - The process's start time.
+     * @returns The process, with its exit code once it has ended.
+     */
+    inspect(machine: string, processId: number, options?: ProcessIdentity): Promise<ProcessDetail>;
+    /**
+     * Waits until a process ends: `endia process wait`. The service answers only when the process has ended or the time-out has
+     * passed, so the client's own time limit does not apply.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param processId - The Windows process ID.
+     * @param options - `timeout` is the longest wait in seconds; without it the wait has no limit. When the time-out passes first, the
+     * service refuses the request with `TIMEOUT`, and the process keeps running.
+     * @returns The exit code in full, such as 3010; null when EastIndia did not start the process on the machine's current boot, because
+     * only then does it know the exit code.
+     */
+    wait(machine: string, processId: number, options?: ProcessIdentity & {
+        readonly timeout?: number;
+    }): Promise<ProcessWaitResult>;
+    /**
+     * Ends a process as `docker stop` ends a container: `endia process stop`. The service first asks the process to close, by
+     * sending a close message to each of its top-level windows, or a `CTRL_BREAK` event to a console process without windows. When the
+     * process has not ended within the time-out, the service ends it with exit code 1.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param processId - The Windows process ID.
+     * @param options - `timeout` is the time in seconds the process has to close, 10 when undefined; 0 ends it at once.
+     * @returns How the process ended, and its exit code when known.
+     */
+    stop(machine: string, processId: number, options?: ProcessIdentity & {
+        readonly timeout?: number;
+    }): Promise<ProcessStopResult>;
+    /**
+     * Reads the output a detached program wrote: `endia process logs`. Only a program started detached on the machine's current
+     * boot has its output kept; for any other process the service refuses the request with `NOT_FOUND`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param processId - The Windows process ID.
+     * @param options - `follow` keeps reading new lines until the process ends.
+     * @returns The lines, each naming its stream, as they arrive.
+     */
+    logs(machine: string, processId: number, options?: {
+        readonly follow?: boolean;
+        readonly signal?: AbortSignal;
+    }): AsyncGenerator<ProcessLogLine, void, undefined>;
+}

package/dist/groups/processes.js

@@ -0,0 +1,75 @@
+import { Routes } from "../routes.js";
+import { QueryText } from "../transport/query-text.js";
+/**
+ * The process routes of a running machine: list, inspect, wait, stop and read the output of a program started detached. A request
+ * names a process by its Windows process ID, which a detached exec and a desktop launch return.
+ */
+export class ProcessesClient {
+    connection;
+    /** @internal */
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Lists the machine's processes: `endia process ls`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param signal - Cancels the request.
+     * @returns The processes.
+     */
+    list(machine, signal) {
+        return this.connection.read(Routes.processes(machine), signal);
+    }
+    /**
+     * Reads one process: `endia process inspect`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param processId - The Windows process ID.
+     * @param options - The process's start time.
+     * @returns The process, with its exit code once it has ended.
+     */
+    inspect(machine, processId, options = {}) {
+        return this.connection.read(Routes.process(machine, processId) + new QueryText().add("started", options.started).toString(), options.signal);
+    }
+    /**
+     * Waits until a process ends: `endia process wait`. The service answers only when the process has ended or the time-out has
+     * passed, so the client's own time limit does not apply.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param processId - The Windows process ID.
+     * @param options - `timeout` is the longest wait in seconds; without it the wait has no limit. When the time-out passes first, the
+     * service refuses the request with `TIMEOUT`, and the process keeps running.
+     * @returns The exit code in full, such as 3010; null when EastIndia did not start the process on the machine's current boot, because
+     * only then does it know the exit code.
+     */
+    wait(machine, processId, options = {}) {
+        const query = new QueryText().add("timeout", options.timeout).add("started", options.started);
+        return this.connection.change({ method: "POST", path: Routes.processWait(machine, processId) + query.toString(), signal: options.signal }, false);
+    }
+    /**
+     * Ends a process as `docker stop` ends a container: `endia process stop`. The service first asks the process to close, by
+     * sending a close message to each of its top-level windows, or a `CTRL_BREAK` event to a console process without windows. When the
+     * process has not ended within the time-out, the service ends it with exit code 1.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param processId - The Windows process ID.
+     * @param options - `timeout` is the time in seconds the process has to close, 10 when undefined; 0 ends it at once.
+     * @returns How the process ended, and its exit code when known.
+     */
+    stop(machine, processId, options = {}) {
+        const query = new QueryText().add("t", options.timeout).add("started", options.started);
+        return this.connection.change({ method: "POST", path: Routes.processStop(machine, processId) + query.toString(), signal: options.signal }, false);
+    }
+    /**
+     * Reads the output a detached program wrote: `endia process logs`. Only a program started detached on the machine's current
+     * boot has its output kept; for any other process the service refuses the request with `NOT_FOUND`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param processId - The Windows process ID.
+     * @param options - `follow` keeps reading new lines until the process ends.
+     * @returns The lines, each naming its stream, as they arrive.
+     */
+    logs(machine, processId, options = {}) {
+        return this.connection.readLines(Routes.processLogs(machine, processId) + new QueryText().addFlag("follow", options.follow).toString(), options.signal);
+    }
+}

package/dist/groups/stats.d.ts

@@ -0,0 +1,29 @@
+import type { HostStats, MachineStats } from "../contract/stats.js";
+/** Whether a readings route keeps sending readings or sends one. */
+export interface StatsOptions {
+    /**
+     * Whether the service keeps sending a new reading at its configured interval until the caller stops iterating. When false or
+     * undefined, the service sends one reading and ends the stream.
+     */
+    readonly stream?: boolean;
+    readonly signal?: AbortSignal;
+}
+/** The readings routes: a machine's processor, memory, network and disk use, and the host's: `endia stats`. */
+export declare class StatsClient {
+    private readonly connection;
+    /**
+     * Reads a machine's readings: `endia stats MACHINE`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param options - `stream` keeps reading; one reading by default.
+     * @returns The readings, as they arrive.
+     */
+    machine(machine: string, options?: StatsOptions): AsyncGenerator<MachineStats, void, undefined>;
+    /**
+     * Reads the host's readings: `endia stats --host`.
+     *
+     * @param options - `stream` keeps reading; one reading by default.
+     * @returns The readings, as they arrive.
+     */
+    host(options?: StatsOptions): AsyncGenerator<HostStats, void, undefined>;
+}

package/dist/groups/stats.js

@@ -0,0 +1,33 @@
+import { Routes } from "../routes.js";
+import { QueryText } from "../transport/query-text.js";
+/** The readings routes: a machine's processor, memory, network and disk use, and the host's: `endia stats`. */
+export class StatsClient {
+    connection;
+    /** @internal */
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Reads a machine's readings: `endia stats MACHINE`.
+     *
+     * @param machine - The machine name or a unique prefix of its ID.
+     * @param options - `stream` keeps reading; one reading by default.
+     * @returns The readings, as they arrive.
+     */
+    machine(machine, options = {}) {
+        return this.connection.readLines(Routes.machineStats(machine) + streamQuery(options), options.signal);
+    }
+    /**
+     * Reads the host's readings: `endia stats --host`.
+     *
+     * @param options - `stream` keeps reading; one reading by default.
+     * @returns The readings, as they arrive.
+     */
+    host(options = {}) {
+        return this.connection.readLines(Routes.hostStats + streamQuery(options), options.signal);
+    }
+}
+// A readings route without the stream parameter streams, as Docker's does, so the client always sends the parameter, false included.
+function streamQuery(options) {
+    return new QueryText().add("stream", options.stream ?? false).toString();
+}

package/dist/groups/system.d.ts

@@ -0,0 +1,33 @@
+import type { DiskUsage, PruneResult } from "../contract/space.js";
+import type { OperationHandle } from "./operations.js";
+/** The disk space routes: what images, machines and volumes take, and the prune that deletes what nothing uses. */
+export declare class SystemClient {
+    private readonly connection;
+    private readonly operations;
+    /**
+     * Reads what images, machines, volumes and the build cache take on disk, and the free space: `endia system df`.
+     *
+     * @param signal - Cancels the request.
+     * @returns The disk use.
+     */
+    diskUsage(signal?: AbortSignal): Promise<DiskUsage>;
+    /**
+     * Deletes what nothing uses: `endia system prune`. It deletes, in this order:
+     * 1. every machine in state `exited` or `created`;
+     * 2. every image with no tag, no children and no machine;
+     * 3. the unused build cache, the entries that `images.pruneBuildCache` deletes;
+     * 4. the finished operations older than the service's retention;
+     * 5. the host objects whose owner no longer exists.
+     *
+     * It deletes what every caller of the service made, not only this caller's.
+     *
+     * @param options - `all` deletes every image that no machine uses and no image is built on, tagged or not. `volumes` is Docker's
+     * option for anonymous volumes; EastIndia has none, so it deletes nothing more.
+     * @returns The prune's operation; its result names what was deleted.
+     */
+    prune(options?: {
+        readonly all?: boolean;
+        readonly volumes?: boolean;
+        readonly signal?: AbortSignal;
+    }): Promise<OperationHandle<PruneResult>>;
+}

package/dist/groups/system.js

@@ -0,0 +1,40 @@
+import { Routes } from "../routes.js";
+import { QueryText } from "../transport/query-text.js";
+/** The disk space routes: what images, machines and volumes take, and the prune that deletes what nothing uses. */
+export class SystemClient {
+    connection;
+    operations;
+    /** @internal */
+    constructor(connection, operations) {
+        this.connection = connection;
+        this.operations = operations;
+    }
+    /**
+     * Reads what images, machines, volumes and the build cache take on disk, and the free space: `endia system df`.
+     *
+     * @param signal - Cancels the request.
+     * @returns The disk use.
+     */
+    diskUsage(signal) {
+        return this.connection.read(Routes.systemDf, signal);
+    }
+    /**
+     * Deletes what nothing uses: `endia system prune`. It deletes, in this order:
+     * 1. every machine in state `exited` or `created`;
+     * 2. every image with no tag, no children and no machine;
+     * 3. the unused build cache, the entries that `images.pruneBuildCache` deletes;
+     * 4. the finished operations older than the service's retention;
+     * 5. the host objects whose owner no longer exists.
+     *
+     * It deletes what every caller of the service made, not only this caller's.
+     *
+     * @param options - `all` deletes every image that no machine uses and no image is built on, tagged or not. `volumes` is Docker's
+     * option for anonymous volumes; EastIndia has none, so it deletes nothing more.
+     * @returns The prune's operation; its result names what was deleted.
+     */
+    async prune(options = {}) {
+        const query = new QueryText().addFlag("all", options.all).addFlag("volumes", options.volumes);
+        const accepted = await this.connection.change({ method: "POST", path: Routes.systemPrune + query.toString(), signal: options.signal });
+        return this.operations.handle(accepted);
+    }
+}

package/dist/groups/volumes.d.ts

@@ -0,0 +1,36 @@
+import type { Filters } from "../contract/common.js";
+import type { VolumeDetail } from "../contract/volumes.js";
+/** The named volume routes: list, inspect and remove. A fleet creates its named volumes when it comes up. */
+export declare class VolumesClient {
+    private readonly connection;
+    /**
+     * Lists named volumes: `endia volume ls`.
+     *
+     * @param options - `filters` such as `{ label: ["team=qa"] }`.
+     * @returns The volumes.
+     */
+    list(options?: {
+        readonly filters?: Filters;
+        readonly signal?: AbortSignal;
+    }): Promise<VolumeDetail[]>;
+    /**
+     * Reads one named volume: `endia volume inspect`.
+     *
+     * @param name - The volume's name.
+     * @param signal - Cancels the request.
+     * @returns The volume.
+     */
+    inspect(name: string, signal?: AbortSignal): Promise<VolumeDetail>;
+    /**
+     * Deletes a named volume and its disk: `endia volume rm`.
+     *
+     * @param name - The volume's name.
+     * @param options - `force` is sent as `endia volume rm -f` sends it.
+     * @returns When the service has deleted the volume. A volume attached to a machine is refused with `RESOURCE_IN_USE`, with or
+     * without `force`.
+     */
+    remove(name: string, options?: {
+        readonly force?: boolean;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}

package/dist/groups/volumes.js

@@ -0,0 +1,40 @@
+import { Routes } from "../routes.js";
+import { QueryText } from "../transport/query-text.js";
+/** The named volume routes: list, inspect and remove. A fleet creates its named volumes when it comes up. */
+export class VolumesClient {
+    connection;
+    /** @internal */
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Lists named volumes: `endia volume ls`.
+     *
+     * @param options - `filters` such as `{ label: ["team=qa"] }`.
+     * @returns The volumes.
+     */
+    list(options = {}) {
+        return this.connection.read(Routes.volumes + new QueryText().addJson("filters", options.filters).toString(), options.signal);
+    }
+    /**
+     * Reads one named volume: `endia volume inspect`.
+     *
+     * @param name - The volume's name.
+     * @param signal - Cancels the request.
+     * @returns The volume.
+     */
+    inspect(name, signal) {
+        return this.connection.read(Routes.volume(name), signal);
+    }
+    /**
+     * Deletes a named volume and its disk: `endia volume rm`.
+     *
+     * @param name - The volume's name.
+     * @param options - `force` is sent as `endia volume rm -f` sends it.
+     * @returns When the service has deleted the volume. A volume attached to a machine is refused with `RESOURCE_IN_USE`, with or
+     * without `force`.
+     */
+    remove(name, options = {}) {
+        return this.connection.changeWithoutAnswer({ method: "DELETE", path: Routes.volume(name) + new QueryText().addFlag("force", options.force).toString(), signal: options.signal });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+export { EastIndiaClient, type ClientOptions } from "./eastindia-client.js";
+export { EastIndiaApiError, EastIndiaConnectionError, MachineFailedError, type ConnectionFailure } from "./errors.js";
+export { readTlsFolder } from "./environment.js";
+export { resolveComposeModel, type ComposeProjectOptions, type ResolvedComposeModel } from "./compose-model.js";
+export type { TlsFiles } from "./transport/tls-files.js";
+export { ArchivesClient, type MachineArchive } from "./groups/archives.js";
+export { BasesClient } from "./groups/bases.js";
+export { CertificatesClient } from "./groups/certificates.js";
+export { DesktopClient, type DesktopScreenshot } from "./groups/desktop.js";
+export { ExecsClient, type DetachedExec, type ExecResult, type RunOptions } from "./groups/execs.js";
+export { FleetsClient, type FleetArchive, type FleetServicesOptions, type FleetUpOptions, type FleetWaitOptions } from "./groups/fleets.js";
+export { ImagesClient, type ArchiveContext, type BuildOptions, type FolderContext } from "./groups/images.js";
+export { MachinesClient, type LogOptions } from "./groups/machines.js";
+export { isFinished, OperationHandle, OperationsClient, type OperationLogOptions, type OperationWaitOptions } from "./groups/operations.js";
+export { ProcessesClient, type ProcessIdentity } from "./groups/processes.js";
+export { StatsClient, type StatsOptions } from "./groups/stats.js";
+export { SystemClient } from "./groups/system.js";
+export { VolumesClient } from "./groups/volumes.js";
+export { MaxPurposeDetailBytes } from "./purposes.js";
+export { ExecSession } from "./exec/exec-session.js";
+export type { ComposeModel, ComposeService } from "./contract/compose.js";
+export type * from "./contract/archives.js";
+export type * from "./contract/bases.js";
+export type * from "./contract/clients.js";
+export type * from "./contract/common.js";
+export type * from "./contract/desktop.js";
+export type * from "./contract/execs.js";
+export type * from "./contract/fleets.js";
+export type * from "./contract/images.js";
+export type * from "./contract/machines.js";
+export type * from "./contract/operations.js";
+export type * from "./contract/processes.js";
+export type * from "./contract/purposes.js";
+export type * from "./contract/space.js";
+export type * from "./contract/stats.js";
+export type * from "./contract/status.js";
+export type * from "./contract/volumes.js";

package/dist/index.js

@@ -0,0 +1,20 @@
+// The public surface of the endia package: the client, its route groups and options, the errors, and the API's records.
+export { EastIndiaClient } from "./eastindia-client.js";
+export { EastIndiaApiError, EastIndiaConnectionError, MachineFailedError } from "./errors.js";
+export { readTlsFolder } from "./environment.js";
+export { resolveComposeModel } from "./compose-model.js";
+export { ArchivesClient } from "./groups/archives.js";
+export { BasesClient } from "./groups/bases.js";
+export { CertificatesClient } from "./groups/certificates.js";
+export { DesktopClient } from "./groups/desktop.js";
+export { ExecsClient } from "./groups/execs.js";
+export { FleetsClient } from "./groups/fleets.js";
+export { ImagesClient } from "./groups/images.js";
+export { MachinesClient } from "./groups/machines.js";
+export { isFinished, OperationHandle, OperationsClient } from "./groups/operations.js";
+export { ProcessesClient } from "./groups/processes.js";
+export { StatsClient } from "./groups/stats.js";
+export { SystemClient } from "./groups/system.js";
+export { VolumesClient } from "./groups/volumes.js";
+export { MaxPurposeDetailBytes } from "./purposes.js";
+export { ExecSession } from "./exec/exec-session.js";

package/dist/purposes.d.ts

@@ -0,0 +1,17 @@
+/** The most bytes a purpose's detail may take in UTF-8: 64 KiB. */
+export declare const MaxPurposeDetailBytes = 65536;
+/** The JSON of a purpose a caller sets: the body of `PUT .../purpose` and the content of `purpose.json` in the archive of `compose up`. */
+export interface PurposeBody {
+    readonly title: string;
+    /** Left out when the purpose has no detail. */
+    readonly detail?: string;
+}
+/**
+ * Checks a purpose a caller sets and gives its JSON. The service checks the other limits: a title of 1 to 200 characters.
+ *
+ * @param title - What the fleet or machine is being used for, in one line.
+ * @param detail - Markdown notes, or undefined for none.
+ * @returns The purpose's JSON; an undefined detail is left out of it.
+ * @throws Error when the title has a line break or the detail takes more than 65536 bytes in UTF-8. Nothing is sent then.
+ */
+export declare function purposeBody(title: string, detail: string | undefined): PurposeBody;

package/dist/purposes.js

@@ -0,0 +1,21 @@
+/** The most bytes a purpose's detail may take in UTF-8: 64 KiB. */
+export const MaxPurposeDetailBytes = 65536;
+/** Carriage return, line feed, next line, line separator and paragraph separator: each ends a line in some reader. */
+const LineBreak = /[\r\n\u0085\u2028\u2029]/u;
+/**
+ * Checks a purpose a caller sets and gives its JSON. The service checks the other limits: a title of 1 to 200 characters.
+ *
+ * @param title - What the fleet or machine is being used for, in one line.
+ * @param detail - Markdown notes, or undefined for none.
+ * @returns The purpose's JSON; an undefined detail is left out of it.
+ * @throws Error when the title has a line break or the detail takes more than 65536 bytes in UTF-8. Nothing is sent then.
+ */
+export function purposeBody(title, detail) {
+    if (LineBreak.test(title)) {
+        throw new Error("A purpose's title is one line; the title given has a line break.");
+    }
+    if (detail !== undefined && Buffer.byteLength(detail, "utf8") > MaxPurposeDetailBytes) {
+        throw new Error(`A purpose's detail takes at most ${String(MaxPurposeDetailBytes)} bytes in UTF-8.`);
+    }
+    return detail === undefined ? { title } : { title, detail };
+}