endia 0.0.0-stage → 0.0.2

package/dist/contract/status.d.ts

@@ -0,0 +1,151 @@
+import type { Timestamp } from "./common.js";
+/** The service's version, as `endia version` prints it. */
+export interface VersionInfo {
+    readonly version: string;
+    readonly apiVersion: string;
+    readonly gitCommit: string;
+    readonly built: Timestamp;
+    readonly os: string;
+    readonly arch: string;
+    /** The version of the guest service the service installs in new machines, or null when it has none. */
+    readonly guestServiceVersion?: string | null;
+}
+/** The host's description, the configuration in effect and what needs attention, as `endia info` prints them. */
+export interface SystemInfo {
+    readonly name: string;
+    readonly serverVersion: string;
+    readonly operatingSystem: string;
+    readonly osVersion: string;
+    readonly architecture: string;
+    readonly logicalProcessors: number;
+    readonly memoryTotalBytes: number;
+    readonly storageRoot: string;
+    readonly imageFolder: string;
+    readonly machines: number;
+    readonly machinesRunning: number;
+    readonly machinesExited: number;
+    readonly images: number;
+    readonly fleets: number;
+    readonly volumes: number;
+    readonly hyperV: HyperVStatus;
+    /** The service's configuration in effect. */
+    readonly config: HostConfigurationView;
+    readonly warnings: readonly string[];
+}
+/** Whether Hyper-V can run machines, and the switch that gives them the internet. */
+export interface HyperVStatus {
+    readonly ready: boolean;
+    readonly reason?: string | null;
+    readonly internetSwitch: string;
+    readonly internetSwitchPresent: boolean;
+}
+/** The host's configuration as `endia info` answers it: each key of `config\policy.json` with the value in effect, under the key's camel-case name. The service fills it from its configuration, and the members, their order and their nullability are the wire. This type holds no logic and no defaults, so every member is required. */
+export interface HostConfigurationView {
+    /** The `imageFolder` key in effect: the absolute path of the image folder, or null when it is not set. */
+    readonly imageFolder: string | null;
+    /** The `listenAddress` key in effect. */
+    readonly listenAddress: string;
+    /** The `listenPort` key in effect. */
+    readonly listenPort: number;
+    /** The `resourcePrefix` key in effect. */
+    readonly resourcePrefix: string;
+    /** The `internetSwitch` key in effect. */
+    readonly internetSwitch: string;
+    /** The `hostReserveMiB` key in effect. */
+    readonly hostReserveMiB: number;
+    /** The `minFreeDiskGiB` key in effect. */
+    readonly minFreeDiskGiB: number;
+    /** The `builderMemoryMiB` key in effect. */
+    readonly builderMemoryMiB: number;
+    /** The `builderProcessorCount` key in effect. */
+    readonly builderProcessorCount: number;
+    /** The `basePrepareDiskGiB` key in effect. */
+    readonly basePrepareDiskGiB: number;
+    /** The `basePrepareTimeoutSeconds` key in effect. */
+    readonly basePrepareTimeoutSeconds: number;
+    /** The `guestProgramsFolder` key in effect, or null when it is not set. */
+    readonly guestProgramsFolder: string | null;
+    /** The `machineMemoryMiB` key in effect. */
+    readonly machineMemoryMiB: number;
+    /** The `machineMemoryFloorMiB` key in effect. */
+    readonly machineMemoryFloorMiB: number;
+    /** The `machineMemoryCeilingMiB` key in effect. */
+    readonly machineMemoryCeilingMiB: number;
+    /** The `machineProcessorCount` key in effect. */
+    readonly machineProcessorCount: number;
+    /** The `maxLayerDepth` key in effect. */
+    readonly maxLayerDepth: number;
+    /** The `maxParallelBoots` key in effect. */
+    readonly maxParallelBoots: number;
+    /** The `guestConnectTimeoutSeconds` key in effect. */
+    readonly guestConnectTimeoutSeconds: number;
+    /** The `guestReadyTimeoutSeconds` key in effect. */
+    readonly guestReadyTimeoutSeconds: number;
+    /** The `desktopReadyTimeoutSeconds` key in effect. */
+    readonly desktopReadyTimeoutSeconds: number;
+    /** The `setupTimeoutSeconds` key in effect. */
+    readonly setupTimeoutSeconds: number;
+    /** The `stopTimeoutSeconds` key in effect. */
+    readonly stopTimeoutSeconds: number;
+    /** The `buildStepTimeoutSeconds` key in effect. */
+    readonly buildStepTimeoutSeconds: number;
+    /** The `restartTimeoutSeconds` key in effect. */
+    readonly restartTimeoutSeconds: number;
+    /** The `desktopActionTimeoutSeconds` key in effect. */
+    readonly desktopActionTimeoutSeconds: number;
+    /** The `uacSettleSeconds` key in effect. */
+    readonly uacSettleSeconds: number;
+    /** The `restartDelayInitialMilliseconds` key in effect. */
+    readonly restartDelayInitialMilliseconds: number;
+    /** The `restartDelayMaxSeconds` key in effect. */
+    readonly restartDelayMaxSeconds: number;
+    /** The `restartResetAfterSeconds` key in effect. */
+    readonly restartResetAfterSeconds: number;
+    /** The `defaultAddressPools` key in effect, or null when it is not set. */
+    readonly defaultAddressPools: readonly AddressPoolView[] | null;
+    /** The `volumeSizeGiB` key in effect. */
+    readonly volumeSizeGiB: number;
+    /** The `machineLogMaxBytes` key in effect. */
+    readonly machineLogMaxBytes: number;
+    /** The `statsIntervalSeconds` key in effect. */
+    readonly statsIntervalSeconds: number;
+    /** The `operationRetentionDays` key in effect. */
+    readonly operationRetentionDays: number;
+    /** The `idempotencyRetentionHours` key in effect. */
+    readonly idempotencyRetentionHours: number;
+    /** The `serviceLogRetentionDays` key in effect. */
+    readonly serviceLogRetentionDays: number;
+    /** The `retentionSweepMinutes` key in effect. */
+    readonly retentionSweepMinutes: number;
+    /** The `maxContextBytes` key in effect. */
+    readonly maxContextBytes: number;
+    /** The `clientCertificateValidityDays` key in effect. */
+    readonly clientCertificateValidityDays: number;
+    /** The `evaluationWarningDays` key in effect. */
+    readonly evaluationWarningDays: number;
+    /** The `hyperVAccessFolder` key in effect, or null when it is not set. */
+    readonly hyperVAccessFolder: string | null;
+    /** The `hyperVEndpoint` key in effect, or null when it is not set. */
+    readonly hyperVEndpoint: string | null;
+    /** The `hostPathMap` key in effect, or null when it is not set. */
+    readonly hostPathMap: string | null;
+    /** The `guestRelay` key in effect, or null when it is not set. */
+    readonly guestRelay: string | null;
+    /** The `hyperVRequestTimeoutSeconds` key in effect. */
+    readonly hyperVRequestTimeoutSeconds: number;
+    /** The `hyperVJobTimeoutSeconds` key in effect. */
+    readonly hyperVJobTimeoutSeconds: number;
+    /** The `turnOffTimeoutSeconds` key in effect. */
+    readonly turnOffTimeoutSeconds: number;
+    /** The `sshReadyTimeoutSeconds` key in effect. */
+    readonly sshReadyTimeoutSeconds: number;
+    /** The `statsReadTimeoutSeconds` key in effect. */
+    readonly statsReadTimeoutSeconds: number;
+}
+/** One entry of the `defaultAddressPools` key as `HostConfigurationView` writes it: a range of IPv4 addresses and the prefix length of the subnets cut from it. */
+export interface AddressPoolView {
+    /** The range in CIDR form, for example `10.231.0.0/16`. */
+    readonly base: string;
+    /** The prefix length of each subnet cut from the range, for example `24`. */
+    readonly size: number;
+}

package/dist/contract/status.js

@@ -0,0 +1 @@
+export {};

package/dist/contract/volumes.d.ts

@@ -0,0 +1,22 @@
+import type { Timestamp } from "./common.js";
+/** One named volume as `endia volume ls` and `endia volume inspect` show it: its disk, its size, the fleet that created it and the machine it is attached to. */
+export interface VolumeDetail {
+    /** The volume's name. */
+    readonly name: string;
+    /** The driver, always `local`. */
+    readonly driver: string;
+    /** The full path of the volume's disk on the host. */
+    readonly mountpoint: string;
+    /** The volume's labels from the Compose model. */
+    readonly labels: Readonly<Record<string, string>>;
+    /** The most bytes the disk may grow to. */
+    readonly sizeBytes: number;
+    /** The size of the disk's file now, in bytes, or null when the file cannot be read. */
+    readonly usedBytes: number | null;
+    /** The name of the fleet whose `compose up` created the volume. */
+    readonly fleet: string;
+    /** The name of the machine the volume is attached to, or null when it is attached to none. */
+    readonly attachedTo: string | null;
+    /** When the volume was created. */
+    readonly created: Timestamp;
+}

package/dist/contract/volumes.js

@@ -0,0 +1 @@
+export {};

package/dist/eastindia-client.d.ts

@@ -0,0 +1,118 @@
+import type { SystemInfo, VersionInfo } from "./contract/status.js";
+import { ArchivesClient } from "./groups/archives.js";
+import { BasesClient } from "./groups/bases.js";
+import { CertificatesClient } from "./groups/certificates.js";
+import { DesktopClient } from "./groups/desktop.js";
+import { ExecsClient } from "./groups/execs.js";
+import { FleetsClient } from "./groups/fleets.js";
+import { ImagesClient } from "./groups/images.js";
+import { MachinesClient } from "./groups/machines.js";
+import { OperationsClient } from "./groups/operations.js";
+import { ProcessesClient } from "./groups/processes.js";
+import { StatsClient } from "./groups/stats.js";
+import { SystemClient } from "./groups/system.js";
+import { VolumesClient } from "./groups/volumes.js";
+import type { TlsFiles } from "./transport/tls-files.js";
+/** Everything a client needs to reach one EastIndia service as one caller. */
+export interface ClientOptions {
+    /**
+     * The service's address, in one of the two forms `EASTINDIA_HOST` takes.
+     *
+     * - `tcp://<host>:<port>`: the client connects over HTTPS with mutual TLS.
+     * - `npipe:////./pipe/<name>`: the client connects through a named pipe on this Windows PC. The pipe needs no certificate,
+     *   because Windows checks which account opens it.
+     */
+    readonly host: string;
+    /** The certificate files as PEM text; required over TCP, unused on the named pipe. `readTlsFolder` reads them from a folder. */
+    readonly tls?: TlsFiles;
+    /**
+     * The time allowed for one request, in milliseconds; 100 seconds when undefined. It does not apply to an upload, a streamed
+     * answer such as a followed log, a wait the service answers only when it ends, or a request sent once.
+     */
+    readonly requestTimeoutMilliseconds?: number;
+    /** How many times a changing request is sent again after its connection failed before any reply; 2 when undefined. */
+    readonly requestRetries?: number;
+    /** The time between those attempts, in milliseconds; 1000 when undefined. */
+    readonly requestRetryDelayMilliseconds?: number;
+}
+/**
+ * The typed client of the EastIndia API. EastIndia is a Windows service that runs Hyper-V Windows machines for tests, as Docker runs
+ * containers. A caller creates one client, with `fromEnv` or with explicit options, and calls the route groups below.
+ *
+ * - `images` builds and keeps images; `bases` imports the images that have no parent.
+ * - `fleets` brings Compose projects up and down; `machines` and `volumes` show and control what fleets made.
+ * - `execs` runs programs in machines, and `archives` copies files into and out of them.
+ * - `processes` waits for and stops the programs in a machine; `desktop` operates the windows of the signed-in user's programs.
+ * - `operations` follows the long work the other groups start; `stats` and `system` read and reclaim the host's resources.
+ * - `certificates` issues and revokes client certificates, on the named pipe only.
+ *
+ * Every call reports a failure as one of two errors. `EastIndiaApiError` means the service answered and refused, with the API's error
+ * code; `EastIndiaConnectionError` means no answer came.
+ */
+export declare class EastIndiaClient {
+    private readonly connection;
+    /** The image routes: build, list, inspect, tag and remove. */
+    readonly images: ImagesClient;
+    /** The base routes: import and prepare. */
+    readonly bases: BasesClient;
+    /** The operation routes: list, inspect, read the log and cancel; and `handle`, which wraps an operation to wait for its end. */
+    readonly operations: OperationsClient;
+    /** The fleet routes: up and its dry run, down, stop, start, restart, list, inspect and logs. */
+    readonly fleets: FleetsClient;
+    /** The machine routes: list, inspect, start, stop, restart and logs. */
+    readonly machines: MachinesClient;
+    /** The named volume routes: list, inspect and remove. */
+    readonly volumes: VolumesClient;
+    /** The exec routes: run a program attached or detached. */
+    readonly execs: ExecsClient;
+    /** The archive routes: copy files into and out of a machine. */
+    readonly archives: ArchivesClient;
+    /** The process routes: list, inspect, wait, stop and logs. */
+    readonly processes: ProcessesClient;
+    /** The desktop routes: launch programs and operate their windows. */
+    readonly desktop: DesktopClient;
+    /** The readings of the machines and of the host. */
+    readonly stats: StatsClient;
+    /** The disk space routes: df and prune. */
+    readonly system: SystemClient;
+    /** The client certificate routes, which the service answers on its named pipe only. */
+    readonly certificates: CertificatesClient;
+    /**
+     * Creates a client. No request is sent until a route is called.
+     *
+     * @param options - The address, the certificate files and the retries.
+     * @throws Error when the address has neither form, or when an address over TCP comes without the certificate files.
+     */
+    constructor(options: ClientOptions);
+    /**
+     * Creates a client that connects as the `endia` CLI does. The address comes from the first of these that is set:
+     *
+     * 1. `EASTINDIA_HOST`, with the certificate files in `EASTINDIA_CERT_PATH`;
+     * 2. the context `EASTINDIA_CONTEXT` names;
+     * 3. the CLI's current context in `~/.eastindia`;
+     * 4. the CLI's built-in context: the named pipe on Windows, `tcp://127.0.0.1:7443` elsewhere.
+     *
+     * The retries are the CLI's `requestRetries` and `requestRetryDelayMilliseconds`.
+     *
+     * @param environment - The environment variables; the process's own when undefined.
+     * @returns The client.
+     * @throws Error when the CLI's settings are not valid, the context named does not exist, or a certificate file cannot be read.
+     */
+    static fromEnv(environment?: Readonly<Record<string, string | undefined>>): EastIndiaClient;
+    /**
+     * Reads the service's version: `endia version`.
+     *
+     * @param signal - Cancels the request.
+     * @returns The version.
+     */
+    version(signal?: AbortSignal): Promise<VersionInfo>;
+    /**
+     * Reads the host's description, the configuration in effect and what needs attention: `endia info`.
+     *
+     * @param signal - Cancels the request.
+     * @returns The description.
+     */
+    info(signal?: AbortSignal): Promise<SystemInfo>;
+    /** Closes the connections kept open for later requests. Each request sent after `close` opens a new connection. */
+    close(): void;
+}

package/dist/eastindia-client.js

@@ -0,0 +1,142 @@
+import { connectionFromEnvironment } from "./environment.js";
+import { ArchivesClient } from "./groups/archives.js";
+import { BasesClient } from "./groups/bases.js";
+import { CertificatesClient } from "./groups/certificates.js";
+import { DesktopClient } from "./groups/desktop.js";
+import { ExecsClient } from "./groups/execs.js";
+import { FleetsClient } from "./groups/fleets.js";
+import { ImagesClient } from "./groups/images.js";
+import { MachinesClient } from "./groups/machines.js";
+import { OperationsClient } from "./groups/operations.js";
+import { ProcessesClient } from "./groups/processes.js";
+import { StatsClient } from "./groups/stats.js";
+import { SystemClient } from "./groups/system.js";
+import { VolumesClient } from "./groups/volumes.js";
+import { Routes } from "./routes.js";
+import { ApiConnection } from "./transport/api-connection.js";
+import { parseServiceAddress } from "./transport/service-address.js";
+/** The time allowed for one request when the options give none: the CLI's own. */
+const DefaultRequestTimeoutMilliseconds = 100_000;
+/** The retries when the options give none: the defaults of the CLI's `requestRetries` and `requestRetryDelayMilliseconds`. */
+const DefaultRequestRetries = 2;
+const DefaultRequestRetryDelayMilliseconds = 1000;
+/**
+ * The typed client of the EastIndia API. EastIndia is a Windows service that runs Hyper-V Windows machines for tests, as Docker runs
+ * containers. A caller creates one client, with `fromEnv` or with explicit options, and calls the route groups below.
+ *
+ * - `images` builds and keeps images; `bases` imports the images that have no parent.
+ * - `fleets` brings Compose projects up and down; `machines` and `volumes` show and control what fleets made.
+ * - `execs` runs programs in machines, and `archives` copies files into and out of them.
+ * - `processes` waits for and stops the programs in a machine; `desktop` operates the windows of the signed-in user's programs.
+ * - `operations` follows the long work the other groups start; `stats` and `system` read and reclaim the host's resources.
+ * - `certificates` issues and revokes client certificates, on the named pipe only.
+ *
+ * Every call reports a failure as one of two errors. `EastIndiaApiError` means the service answered and refused, with the API's error
+ * code; `EastIndiaConnectionError` means no answer came.
+ */
+export class EastIndiaClient {
+    connection;
+    /** The image routes: build, list, inspect, tag and remove. */
+    images;
+    /** The base routes: import and prepare. */
+    bases;
+    /** The operation routes: list, inspect, read the log and cancel; and `handle`, which wraps an operation to wait for its end. */
+    operations;
+    /** The fleet routes: up and its dry run, down, stop, start, restart, list, inspect and logs. */
+    fleets;
+    /** The machine routes: list, inspect, start, stop, restart and logs. */
+    machines;
+    /** The named volume routes: list, inspect and remove. */
+    volumes;
+    /** The exec routes: run a program attached or detached. */
+    execs;
+    /** The archive routes: copy files into and out of a machine. */
+    archives;
+    /** The process routes: list, inspect, wait, stop and logs. */
+    processes;
+    /** The desktop routes: launch programs and operate their windows. */
+    desktop;
+    /** The readings of the machines and of the host. */
+    stats;
+    /** The disk space routes: df and prune. */
+    system;
+    /** The client certificate routes, which the service answers on its named pipe only. */
+    certificates;
+    /**
+     * Creates a client. No request is sent until a route is called.
+     *
+     * @param options - The address, the certificate files and the retries.
+     * @throws Error when the address has neither form, or when an address over TCP comes without the certificate files.
+     */
+    constructor(options) {
+        this.connection = EastIndiaClient.connect(parseServiceAddress(options.host, "host"), options);
+        this.operations = new OperationsClient(this.connection);
+        this.images = new ImagesClient(this.connection, this.operations);
+        this.bases = new BasesClient(this.connection, this.operations);
+        this.fleets = new FleetsClient(this.connection, this.operations);
+        this.machines = new MachinesClient(this.connection, this.operations);
+        this.volumes = new VolumesClient(this.connection);
+        this.execs = new ExecsClient(this.connection);
+        this.archives = new ArchivesClient(this.connection);
+        this.processes = new ProcessesClient(this.connection);
+        this.desktop = new DesktopClient(this.connection);
+        this.stats = new StatsClient(this.connection);
+        this.system = new SystemClient(this.connection, this.operations);
+        this.certificates = new CertificatesClient(this.connection);
+    }
+    /**
+     * Creates a client that connects as the `endia` CLI does. The address comes from the first of these that is set:
+     *
+     * 1. `EASTINDIA_HOST`, with the certificate files in `EASTINDIA_CERT_PATH`;
+     * 2. the context `EASTINDIA_CONTEXT` names;
+     * 3. the CLI's current context in `~/.eastindia`;
+     * 4. the CLI's built-in context: the named pipe on Windows, `tcp://127.0.0.1:7443` elsewhere.
+     *
+     * The retries are the CLI's `requestRetries` and `requestRetryDelayMilliseconds`.
+     *
+     * @param environment - The environment variables; the process's own when undefined.
+     * @returns The client.
+     * @throws Error when the CLI's settings are not valid, the context named does not exist, or a certificate file cannot be read.
+     */
+    static fromEnv(environment = process.env) {
+        const chosen = connectionFromEnvironment(environment);
+        return new EastIndiaClient({
+            host: chosen.host,
+            tls: chosen.tls,
+            requestRetries: chosen.requestRetries,
+            requestRetryDelayMilliseconds: chosen.requestRetryDelayMilliseconds,
+        });
+    }
+    /**
+     * Reads the service's version: `endia version`.
+     *
+     * @param signal - Cancels the request.
+     * @returns The version.
+     */
+    version(signal) {
+        return this.connection.read(Routes.version, signal);
+    }
+    /**
+     * Reads the host's description, the configuration in effect and what needs attention: `endia info`.
+     *
+     * @param signal - Cancels the request.
+     * @returns The description.
+     */
+    info(signal) {
+        return this.connection.read(Routes.info, signal);
+    }
+    /** Closes the connections kept open for later requests. Each request sent after `close` opens a new connection. */
+    close() {
+        this.connection.close();
+    }
+    /** @internal Opens the connection; tests reach a local socket through it, which `host` has no form for. */
+    static connect(address, options) {
+        return new ApiConnection({
+            address,
+            tls: options.tls,
+            requestTimeoutMilliseconds: options.requestTimeoutMilliseconds ?? DefaultRequestTimeoutMilliseconds,
+            requestRetries: options.requestRetries ?? DefaultRequestRetries,
+            requestRetryDelayMilliseconds: options.requestRetryDelayMilliseconds ?? DefaultRequestRetryDelayMilliseconds,
+        });
+    }
+}

package/dist/environment.d.ts

@@ -0,0 +1,52 @@
+import type { TlsFiles } from "./transport/tls-files.js";
+/** What `EastIndiaClient.fromEnv` connects with, as the `endia` CLI would choose it. */
+export interface EnvironmentConnection {
+    /** The address, `tcp://<host>:<port>` or `npipe:////./pipe/<name>`. */
+    readonly host: string;
+    /** The certificate files, read for an address over TCP; undefined for a named pipe. */
+    readonly tls: TlsFiles | undefined;
+    /** The CLI's `requestRetries`. */
+    readonly requestRetries: number;
+    /** The CLI's `requestRetryDelayMilliseconds`. */
+    readonly requestRetryDelayMilliseconds: number;
+}
+/** The environment variables the CLI reads to choose its connection, and the folder that holds its settings and contexts. */
+export declare const EnvironmentVariables: {
+    /** The address, which wins over every context. */
+    readonly host: "EASTINDIA_HOST";
+    /** The folder of `ca.pem`, `cert.pem` and `key.pem` for the address in `EASTINDIA_HOST`. */
+    readonly certPath: "EASTINDIA_CERT_PATH";
+    /** The context to use instead of the current one. */
+    readonly context: "EASTINDIA_CONTEXT";
+    /** The configuration folder instead of `.eastindia` in the home folder. */
+    readonly config: "EASTINDIA_CONFIG";
+};
+/**
+ * Chooses the connection as the `endia` CLI chooses it when it is given neither `--host` nor `--context`:
+ *
+ * 1. `EASTINDIA_HOST`, with the certificate files in `EASTINDIA_CERT_PATH`, or else in the configuration folder;
+ * 2. otherwise the context `EASTINDIA_CONTEXT` names;
+ * 3. otherwise `currentContext` in `config.json`;
+ * 4. otherwise the built-in context `default`: the named pipe on Windows, `tcp://127.0.0.1:7443` elsewhere with the certificate files
+ *    in the configuration folder.
+ *
+ * The configuration folder is `EASTINDIA_CONFIG`, or else `.eastindia` in the home folder. A stored context lives where the CLI
+ * stores it, in Docker's layout: `contexts/meta/<SHA-256 of the name>/meta.json`, and the certificate files in
+ * `contexts/tls/<SHA-256 of the name>/eastindia/`.
+ *
+ * @param environment - The environment variables.
+ * @param home - The home folder.
+ * @param windows - Whether this computer runs Windows, which decides the built-in context's address.
+ * @returns The connection.
+ * @throws Error when `config.json` holds an unknown key or a value out of range, when the context named does not exist, or when a
+ * certificate file cannot be read; the message names the file or the context.
+ */
+export declare function connectionFromEnvironment(environment: Readonly<Record<string, string | undefined>>, home?: string, windows?: boolean): EnvironmentConnection;
+/**
+ * Reads the three certificate files of a folder: `ca.pem`, `cert.pem` and `key.pem`.
+ *
+ * @param folder - The folder.
+ * @returns The files' text.
+ * @throws Error naming the file that is missing or cannot be read.
+ */
+export declare function readTlsFolder(folder: string): TlsFiles;

package/dist/environment.js

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+/** The environment variables the CLI reads to choose its connection, and the folder that holds its settings and contexts. */
+export const EnvironmentVariables = {
+    /** The address, which wins over every context. */
+    host: "EASTINDIA_HOST",
+    /** The folder of `ca.pem`, `cert.pem` and `key.pem` for the address in `EASTINDIA_HOST`. */
+    certPath: "EASTINDIA_CERT_PATH",
+    /** The context to use instead of the current one. */
+    context: "EASTINDIA_CONTEXT",
+    /** The configuration folder instead of `.eastindia` in the home folder. */
+    config: "EASTINDIA_CONFIG",
+};
+/** The configuration folder's name in the home folder, as Docker's is `.docker`. */
+const ConfigFolderName = ".eastindia";
+/** The settings file in the configuration folder. */
+const SettingsFileName = "config.json";
+/** The name of the built-in context, which no file stores. */
+const DefaultContext = "default";
+/** The built-in context's address on Windows: the installed service's named pipe. */
+const DefaultPipeHost = "npipe:////./pipe/eastindia_engine";
+/** The built-in context's address elsewhere: the service's port on this computer. */
+const DefaultTcpHost = "tcp://127.0.0.1:7443";
+/** The key under which a context's `meta.json` names its endpoint, as Docker's is `docker`. */
+const EndpointKey = "eastindia";
+/** The defaults of the settings that `config.json` may leave out, and their ranges. */
+const RequestRetries = { default: 2, minimum: 0, maximum: 10 };
+const RequestRetryDelayMilliseconds = { default: 1000, minimum: 100, maximum: 2147483647 };
+/**
+ * Chooses the connection as the `endia` CLI chooses it when it is given neither `--host` nor `--context`:
+ *
+ * 1. `EASTINDIA_HOST`, with the certificate files in `EASTINDIA_CERT_PATH`, or else in the configuration folder;
+ * 2. otherwise the context `EASTINDIA_CONTEXT` names;
+ * 3. otherwise `currentContext` in `config.json`;
+ * 4. otherwise the built-in context `default`: the named pipe on Windows, `tcp://127.0.0.1:7443` elsewhere with the certificate files
+ *    in the configuration folder.
+ *
+ * The configuration folder is `EASTINDIA_CONFIG`, or else `.eastindia` in the home folder. A stored context lives where the CLI
+ * stores it, in Docker's layout: `contexts/meta/<SHA-256 of the name>/meta.json`, and the certificate files in
+ * `contexts/tls/<SHA-256 of the name>/eastindia/`.
+ *
+ * @param environment - The environment variables.
+ * @param home - The home folder.
+ * @param windows - Whether this computer runs Windows, which decides the built-in context's address.
+ * @returns The connection.
+ * @throws Error when `config.json` holds an unknown key or a value out of range, when the context named does not exist, or when a
+ * certificate file cannot be read; the message names the file or the context.
+ */
+export function connectionFromEnvironment(environment, home = homedir(), windows = process.platform === "win32") {
+    const configFolder = path.resolve(environment[EnvironmentVariables.config] ?? path.join(home, ConfigFolderName));
+    const settings = readSettings(path.join(configFolder, SettingsFileName));
+    const chosen = chooseContext(environment, settings, configFolder, windows);
+    return {
+        host: chosen.host,
+        tls: chosen.host.startsWith("tcp://") ? readTlsFolder(chosen.certificateFolder) : undefined,
+        requestRetries: settings.requestRetries,
+        requestRetryDelayMilliseconds: settings.requestRetryDelayMilliseconds,
+    };
+}
+/**
+ * Reads the three certificate files of a folder: `ca.pem`, `cert.pem` and `key.pem`.
+ *
+ * @param folder - The folder.
+ * @returns The files' text.
+ * @throws Error naming the file that is missing or cannot be read.
+ */
+export function readTlsFolder(folder) {
+    const read = (name) => {
+        const file = path.join(folder, name);
+        try {
+            return readFileSync(file, "utf8");
+        }
+        catch (error) {
+            throw new Error(`Cannot read ${name} at ${file}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    };
+    return { ca: read("ca.pem"), cert: read("cert.pem"), key: read("key.pem") };
+}
+function chooseContext(environment, settings, configFolder, windows) {
+    const host = environment[EnvironmentVariables.host];
+    if (host !== undefined) {
+        return { host, certificateFolder: environment[EnvironmentVariables.certPath] ?? configFolder };
+    }
+    const name = environment[EnvironmentVariables.context] ?? settings.currentContext ?? DefaultContext;
+    if (name === DefaultContext) {
+        return { host: windows ? DefaultPipeHost : DefaultTcpHost, certificateFolder: configFolder };
+    }
+    // Docker names a context's folders by the SHA-256 of its name, so that any name is a valid folder name.
+    const folderName = createHash("sha256").update(name, "utf8").digest("hex");
+    const metaFile = path.join(configFolder, "contexts", "meta", folderName, "meta.json");
+    if (!existsSync(metaFile)) {
+        throw new Error(`Context "${name}" does not exist: ${metaFile} is missing.`);
+    }
+    const meta = JSON.parse(readFileSync(metaFile, "utf8"));
+    const endpoint = meta.Endpoints?.[EndpointKey]?.Host;
+    if (endpoint === undefined) {
+        throw new Error(`${metaFile} names no ${EndpointKey} endpoint.`);
+    }
+    return { host: endpoint, certificateFolder: path.join(configFolder, "contexts", "tls", folderName, EndpointKey) };
+}
+// Reads config.json as the CLI reads it: an unknown key, or a value of the wrong type or out of range, is refused and named.
+function readSettings(file) {
+    if (!existsSync(file)) {
+        return { currentContext: undefined, requestRetries: RequestRetries.default, requestRetryDelayMilliseconds: RequestRetryDelayMilliseconds.default };
+    }
+    const keys = JSON.parse(readFileSync(file, "utf8"));
+    for (const key of Object.keys(keys)) {
+        if (!["currentContext", "requestRetries", "requestRetryDelayMilliseconds"].includes(key)) {
+            throw new Error(`${file} holds the unknown key '${key}'.`);
+        }
+    }
+    const currentContext = keys["currentContext"];
+    if (currentContext !== undefined && currentContext !== null && typeof currentContext !== "string") {
+        throw new Error(`${file}: 'currentContext' must be a string.`);
+    }
+    return {
+        currentContext: currentContext ?? undefined,
+        requestRetries: integerSetting(file, keys, "requestRetries", RequestRetries),
+        requestRetryDelayMilliseconds: integerSetting(file, keys, "requestRetryDelayMilliseconds", RequestRetryDelayMilliseconds),
+    };
+}
+function integerSetting(file, keys, key, range) {
+    const value = keys[key];
+    if (value === undefined) {
+        return range.default;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < range.minimum || value > range.maximum) {
+        throw new Error(`${file}: '${key}' must be an integer from ${String(range.minimum)} to ${String(range.maximum)}.`);
+    }
+    return value;
+}