endia 0.0.0-stage → 0.0.2

package/dist/routes.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The paths of the API's routes, each built from its parts with every name escaped. One place builds them, so that a route group
+ * cannot misspell a path or forget to escape a name.
+ */
+export declare const Routes: {
+    readonly version: "/v1/version";
+    readonly info: "/v1/info";
+    readonly hostStats: "/v1/host/stats";
+    readonly systemDf: "/v1/system/df";
+    readonly systemPrune: "/v1/system/prune";
+    readonly builderPrune: "/v1/builder/prune";
+    readonly images: "/v1/images";
+    readonly build: "/v1/images/build";
+    readonly baseImport: "/v1/bases/import";
+    readonly basePrepare: "/v1/bases/prepare";
+    readonly clients: "/v1/clients";
+    readonly operations: "/v1/operations";
+    readonly fleets: "/v1/fleets";
+    readonly machines: "/v1/machines";
+    readonly volumes: "/v1/volumes";
+    readonly image: (reference: string) => string;
+    readonly tag: (target: string) => string;
+    readonly operation: (id: string) => string;
+    readonly operationLog: (id: string) => string;
+    readonly operationCancel: (id: string) => string;
+    readonly fleet: (name: string) => string;
+    readonly fleetLogs: (name: string) => string;
+    readonly fleetStop: (name: string) => string;
+    readonly fleetStart: (name: string) => string;
+    readonly fleetRestart: (name: string) => string;
+    readonly fleetPurpose: (name: string) => string;
+    readonly machine: (name: string) => string;
+    readonly machineStart: (name: string) => string;
+    readonly machineStop: (name: string) => string;
+    readonly machineRestart: (name: string) => string;
+    readonly machineLogs: (name: string) => string;
+    readonly machinePurpose: (name: string) => string;
+    readonly machineStats: (name: string) => string;
+    readonly machineExec: (name: string) => string;
+    readonly machineArchive: (name: string, path: string) => string;
+    readonly processes: (machine: string) => string;
+    readonly process: (machine: string, processId: number) => string;
+    readonly processWait: (machine: string, processId: number) => string;
+    readonly processStop: (machine: string, processId: number) => string;
+    readonly processLogs: (machine: string, processId: number) => string;
+    readonly desktop: (machine: string, action: DesktopAction) => string;
+    readonly exec: (id: string) => string;
+    readonly execStart: (id: string) => string;
+    readonly execResize: (id: string) => string;
+    readonly client: (name: string) => string;
+    readonly volume: (name: string) => string;
+};
+/** The last part of each desktop route's path, after `/v1/machines/{name}/desktop/`. */
+export type DesktopAction = "launch" | "screenshot" | "inspect" | "wait" | "invoke" | "click" | "set-value" | "keys" | "pointer" | "windows" | "tray" | "tray/click" | "uac";
+/** The media types of the bodies the client sends and reads. */
+export declare const MediaTypes: {
+    readonly json: "application/json";
+    readonly tar: "application/x-tar";
+};
+/** The headers the API defines beyond HTTP's own. */
+export declare const Headers: {
+    readonly idempotencyKey: "Idempotency-Key";
+    /** A HEAD answer's error, as Base64 of the error's JSON, because a HEAD answer has no body. */
+    readonly error: "X-EastIndia-Error";
+    /** A path's description on the archive routes, as Base64 of its JSON. */
+    readonly pathStat: "X-EastIndia-Path-Stat";
+    readonly screenshotWidth: "X-EastIndia-Width";
+    readonly screenshotHeight: "X-EastIndia-Height";
+    readonly screenshotSession: "X-EastIndia-Session";
+    readonly screenshotTaken: "X-EastIndia-Taken";
+};

package/dist/routes.js

@@ -0,0 +1,73 @@
+/**
+ * The paths of the API's routes, each built from its parts with every name escaped. One place builds them, so that a route group
+ * cannot misspell a path or forget to escape a name.
+ */
+export const Routes = {
+    version: "/v1/version",
+    info: "/v1/info",
+    hostStats: "/v1/host/stats",
+    systemDf: "/v1/system/df",
+    systemPrune: "/v1/system/prune",
+    builderPrune: "/v1/builder/prune",
+    images: "/v1/images",
+    build: "/v1/images/build",
+    baseImport: "/v1/bases/import",
+    basePrepare: "/v1/bases/prepare",
+    clients: "/v1/clients",
+    operations: "/v1/operations",
+    fleets: "/v1/fleets",
+    machines: "/v1/machines",
+    volumes: "/v1/volumes",
+    // An image reference may hold "/", and the route takes the rest of the path, so each part is escaped on its own.
+    image: (reference) => `/v1/images/${escapeEachPart(reference)}`,
+    tag: (target) => `/v1/images/tags/${escapeEachPart(target)}`,
+    operation: (id) => `/v1/operations/${encodeURIComponent(id)}`,
+    operationLog: (id) => `${Routes.operation(id)}/log`,
+    operationCancel: (id) => `${Routes.operation(id)}/cancel`,
+    fleet: (name) => `/v1/fleets/${encodeURIComponent(name)}`,
+    fleetLogs: (name) => `${Routes.fleet(name)}/logs`,
+    fleetStop: (name) => `${Routes.fleet(name)}/stop`,
+    fleetStart: (name) => `${Routes.fleet(name)}/start`,
+    fleetRestart: (name) => `${Routes.fleet(name)}/restart`,
+    fleetPurpose: (name) => `${Routes.fleet(name)}/purpose`,
+    machine: (name) => `/v1/machines/${encodeURIComponent(name)}`,
+    machineStart: (name) => `${Routes.machine(name)}/start`,
+    machineStop: (name) => `${Routes.machine(name)}/stop`,
+    machineRestart: (name) => `${Routes.machine(name)}/restart`,
+    machineLogs: (name) => `${Routes.machine(name)}/logs`,
+    machinePurpose: (name) => `${Routes.machine(name)}/purpose`,
+    machineStats: (name) => `${Routes.machine(name)}/stats`,
+    machineExec: (name) => `${Routes.machine(name)}/exec`,
+    machineArchive: (name, path) => `${Routes.machine(name)}/archive?path=${encodeURIComponent(path)}`,
+    processes: (machine) => `${Routes.machine(machine)}/processes`,
+    process: (machine, processId) => `${Routes.processes(machine)}/${String(processId)}`,
+    processWait: (machine, processId) => `${Routes.process(machine, processId)}/wait`,
+    processStop: (machine, processId) => `${Routes.process(machine, processId)}/stop`,
+    processLogs: (machine, processId) => `${Routes.process(machine, processId)}/logs`,
+    desktop: (machine, action) => `${Routes.machine(machine)}/desktop/${action}`,
+    exec: (id) => `/v1/execs/${encodeURIComponent(id)}`,
+    execStart: (id) => `${Routes.exec(id)}/start`,
+    execResize: (id) => `${Routes.exec(id)}/resize`,
+    client: (name) => `/v1/clients/${encodeURIComponent(name)}`,
+    volume: (name) => `/v1/volumes/${encodeURIComponent(name)}`,
+};
+/** The media types of the bodies the client sends and reads. */
+export const MediaTypes = {
+    json: "application/json",
+    tar: "application/x-tar",
+};
+/** The headers the API defines beyond HTTP's own. */
+export const Headers = {
+    idempotencyKey: "Idempotency-Key",
+    /** A HEAD answer's error, as Base64 of the error's JSON, because a HEAD answer has no body. */
+    error: "X-EastIndia-Error",
+    /** A path's description on the archive routes, as Base64 of its JSON. */
+    pathStat: "X-EastIndia-Path-Stat",
+    screenshotWidth: "X-EastIndia-Width",
+    screenshotHeight: "X-EastIndia-Height",
+    screenshotSession: "X-EastIndia-Session",
+    screenshotTaken: "X-EastIndia-Taken",
+};
+function escapeEachPart(reference) {
+    return reference.split("/").map(encodeURIComponent).join("/");
+}

package/dist/transport/api-connection.d.ts

@@ -0,0 +1,185 @@
+import { type IncomingHttpHeaders, type IncomingMessage } from "node:http";
+import type { Readable } from "node:stream";
+import WebSocket from "ws";
+import type { ApiError } from "../contract/common.js";
+import { type ServiceAddress } from "./service-address.js";
+import type { TlsFiles } from "./tls-files.js";
+/** How the connection reaches the service and how patient it is. */
+export interface ConnectionSettings {
+    readonly address: ServiceAddress;
+    /** The certificate files; required over HTTPS, unused on a local socket. */
+    readonly tls: TlsFiles | undefined;
+    readonly requestTimeoutMilliseconds: number;
+    readonly requestRetries: number;
+    readonly requestRetryDelayMilliseconds: number;
+}
+/** A request body: bytes held in memory, or a stream opened afresh for each attempt, so that a retried request sends the same bytes. */
+export type RequestBody = {
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+} | {
+    readonly contentType: string;
+    readonly open: () => Readable;
+    readonly length?: number;
+};
+/** One request to the service. */
+export interface Exchange {
+    readonly method: "GET" | "HEAD" | "POST" | "PUT" | "DELETE";
+    /** The route's path with its query. */
+    readonly path: string;
+    readonly body?: RequestBody;
+    /** Cancels the request; the promise then rejects with the signal's reason. */
+    readonly signal?: AbortSignal | undefined;
+}
+/** A whole answer, read into memory. */
+export interface Answer {
+    readonly status: number;
+    readonly headers: IncomingHttpHeaders;
+    readonly body: Buffer;
+}
+/**
+ * The one connection the route groups share, over HTTPS with mutual TLS or over a local socket. Without it each group would repeat
+ * three rules that every request follows. A changing request carries an `Idempotency-Key`, and it is sent again with the same key
+ * when its connection fails before any reply. A refusal becomes a `EastIndiaApiError` with the service's error. A request that gets
+ * no answer becomes a `EastIndiaConnectionError` that says why.
+ *
+ * Over HTTPS the client presents the caller's certificate and accepts the server only when its certificate chains to `ca.pem`, is
+ * meant for server authentication and names the address: Node's TLS checks all three when `ca.pem` is the only authority given.
+ */
+export declare class ApiConnection {
+    private readonly settings;
+    private readonly agent;
+    private readonly addressText;
+    /**
+     * Opens the connection; no request is sent until a route group sends one.
+     *
+     * @param settings - The address, certificate files and patience.
+     * @throws Error when an HTTPS address comes without the certificate files.
+     */
+    constructor(settings: ConnectionSettings);
+    /**
+     * Reads a route's JSON answer. A read is sent once: it changes nothing, so a failed connection is reported rather than retried.
+     *
+     * @param path - The route's path with its query.
+     * @param signal - Cancels the request.
+     * @returns The parsed answer.
+     */
+    read<T>(path: string, signal?: AbortSignal): Promise<T>;
+    /**
+     * Sends a request that changes something and reads its JSON answer. It carries a new `Idempotency-Key`, and when its connection
+     * fails before any reply it is sent again with the same key, so that the service does the work once.
+     *
+     * @param exchange - The request.
+     * @param timed - Whether the client's time limit applies; false for an upload and for a wait the service answers only when it ends.
+     * @returns The parsed answer.
+     */
+    change<T>(exchange: Exchange, timed?: boolean): Promise<T>;
+    /**
+     * Sends a request that changes something and answers without a body, with the key and retries of `change`.
+     *
+     * @param exchange - The request.
+     * @returns When the service has answered with success.
+     */
+    changeWithoutAnswer(exchange: Exchange): Promise<void>;
+    /**
+     * Sends a request exactly once, without an `Idempotency-Key`, without a retry and without the client's time limit, and reads its
+     * JSON answer. A request whose body carries a password goes this way, because the service must never store it and a repeat could
+     * answer a prompt twice; so does a request whose answer carries a private key.
+     *
+     * @param exchange - The request.
+     * @returns The parsed answer.
+     */
+    sendOnce<T>(exchange: Exchange): Promise<T>;
+    /**
+     * Sends a request that changes nothing although it is a `POST`, such as a screenshot, without an `Idempotency-Key`, and gives the
+     * whole answer, for an answer that is not JSON.
+     *
+     * @param exchange - The request.
+     * @returns The answer.
+     */
+    sendWithoutKey(exchange: Exchange): Promise<Answer>;
+    /**
+     * Sends a request that has no body and whose answer has none, such as a HEAD, and gives the answer's headers.
+     *
+     * @param path - The route's path with its query.
+     * @param signal - Cancels the request.
+     * @returns The answer's headers.
+     */
+    head(path: string, signal?: AbortSignal): Promise<IncomingHttpHeaders>;
+    /**
+     * Sends a request whose answer is streamed, such as a followed log, and gives the answer once its headers have arrived. The client's
+     * time limit does not apply, because a followed stream stays open for as long as the service has more to send.
+     *
+     * @param exchange - The request.
+     * @returns The answer's body as it arrives; the caller reads it to its end or destroys it.
+     */
+    openStream(exchange: Exchange): Promise<IncomingMessage>;
+    /**
+     * Reads a route whose answer is a stream of JSON objects, one per line, such as a machine's log or its readings. The request is
+     * sent when the iteration starts, and stopping the iteration early ends it.
+     *
+     * @param path - The route's path with its query.
+     * @param signal - Ends the request.
+     * @returns The objects, as their lines arrive.
+     */
+    readLines<T>(path: string, signal?: AbortSignal): AsyncGenerator<T, void, undefined>;
+    /**
+     * Opens a route as a WebSocket, with the same certificate and the same server check as every other request.
+     *
+     * @param path - The route, such as `/v1/execs/{id}/start`.
+     * @param signal - Cancels the opening.
+     * @returns The open WebSocket; the caller closes it.
+     * @throws EastIndiaApiError when the service refuses the upgrade, with the error its answer carries.
+     * @throws EastIndiaConnectionError when no answer came.
+     */
+    openWebSocket(path: string, signal?: AbortSignal): Promise<WebSocket>;
+    /** Closes the connections kept open for later requests. A request sent afterwards opens a new one. */
+    close(): void;
+    private send;
+    private sendAttempt;
+    private dispatch;
+    private createRequest;
+    private writeBody;
+    private createWebSocket;
+    private connectionError;
+    private static createAgent;
+}
+/**
+ * Writes a JSON request body. Members whose value is undefined are left out, so that the service applies their defaults; the service
+ * refuses a member it does not know.
+ *
+ * @param value - The body.
+ * @returns The body as UTF-8 JSON.
+ */
+export declare function jsonBody(value: object): RequestBody;
+/**
+ * Writes a tar archive the caller packed as a request body.
+ *
+ * @param archive - The archive's bytes, or a function that opens it afresh, so that a retried request sends the same bytes.
+ * @returns The body, of type `application/x-tar`.
+ */
+export declare function tarBody(archive: Uint8Array | (() => Readable)): RequestBody;
+/**
+ * Reads the error of a refusal: the JSON body, or, for an answer without a body such as a HEAD's, the `X-EastIndia-Error` header,
+ * which holds the same JSON in Base64. Gives null when neither holds a readable error.
+ *
+ * @param answer - The refusal.
+ * @returns The error, or null.
+ */
+export declare function readError(answer: Answer): ApiError | null;
+/**
+ * Reads a JSON value that the API sends Base64-encoded in a header, such as `X-EastIndia-Path-Stat`.
+ *
+ * @param headers - The answer's headers.
+ * @param name - The header's name.
+ * @returns The value, or undefined when the header is absent or not Base64 of JSON.
+ */
+export declare function readHeaderJson(headers: IncomingHttpHeaders, name: string): unknown;
+/**
+ * Reads a body to its end.
+ *
+ * @param stream - The body.
+ * @param signal - Stops the reading; the promise then rejects with the signal's reason.
+ * @returns The bytes.
+ */
+export declare function readAll(stream: Readable, signal?: AbortSignal): Promise<Buffer>;