endia 0.0.0-stage → 0.0.2

package/dist/transport/api-connection.js

@@ -0,0 +1,396 @@
+import { randomUUID } from "node:crypto";
+import http, {} from "node:http";
+import https from "node:https";
+import net from "node:net";
+import { setTimeout as delay } from "node:timers/promises";
+import WebSocket from "ws";
+import { EastIndiaApiError, EastIndiaConnectionError } from "../errors.js";
+import { Headers, MediaTypes } from "../routes.js";
+import { classifyConnectionFailure } from "./connection-failures.js";
+import { readJsonLines } from "./json-lines.js";
+import { describeServiceAddress } from "./service-address.js";
+/**
+ * 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 class ApiConnection {
+    settings;
+    agent;
+    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) {
+        this.settings = settings;
+        this.addressText = describeServiceAddress(settings.address);
+        this.agent = ApiConnection.createAgent(settings);
+    }
+    /**
+     * 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.
+     */
+    async read(path, signal) {
+        return parseJson(await this.send({ method: "GET", path, signal }, { keyed: false, timed: true }));
+    }
+    /**
+     * 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.
+     */
+    async change(exchange, timed = true) {
+        return parseJson(await this.send(exchange, { keyed: true, timed }));
+    }
+    /**
+     * 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.
+     */
+    async changeWithoutAnswer(exchange) {
+        await this.send(exchange, { keyed: true, timed: true });
+    }
+    /**
+     * 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.
+     */
+    async sendOnce(exchange) {
+        return parseJson(await this.send(exchange, { keyed: false, timed: false }));
+    }
+    /**
+     * 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) {
+        return this.send(exchange, { keyed: false, timed: true });
+    }
+    /**
+     * 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.
+     */
+    async head(path, signal) {
+        return (await this.send({ method: "HEAD", path, signal }, { keyed: false, timed: true })).headers;
+    }
+    /**
+     * 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.
+     */
+    async openStream(exchange) {
+        const response = await this.dispatch(exchange, undefined, exchange.signal);
+        if (exchange.signal !== undefined) {
+            const signal = exchange.signal;
+            const stop = () => {
+                response.destroy(signal.reason instanceof Error ? signal.reason : undefined);
+            };
+            signal.addEventListener("abort", stop, { once: true });
+            response.once("close", () => {
+                signal.removeEventListener("abort", stop);
+            });
+        }
+        return response;
+    }
+    /**
+     * 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.
+     */
+    async *readLines(path, signal) {
+        yield* readJsonLines(await this.openStream({ method: "GET", path, signal }));
+    }
+    /**
+     * 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, signal) {
+        signal?.throwIfAborted();
+        const socket = this.createWebSocket(path);
+        return new Promise((resolve, reject) => {
+            const abort = () => {
+                socket.terminate();
+                reject(signal?.reason);
+            };
+            signal?.addEventListener("abort", abort, { once: true });
+            const settle = () => {
+                signal?.removeEventListener("abort", abort);
+                socket.removeAllListeners("open").removeAllListeners("unexpected-response").removeAllListeners("error");
+            };
+            socket.once("open", () => {
+                settle();
+                resolve(socket);
+            });
+            // A refused upgrade is answered like any other refusal, with the error as its body. The ws package hands that answer to this
+            // listener and leaves the upgrade request open, so the listener reads the body and then destroys the request.
+            socket.once("unexpected-response", (request, response) => {
+                settle();
+                readAll(response).then((body) => {
+                    reject(new EastIndiaApiError(response.statusCode ?? 0, readError({ status: response.statusCode ?? 0, headers: response.headers, body })));
+                }, (error) => {
+                    reject(this.connectionError(error));
+                }).finally(() => {
+                    request.destroy();
+                });
+            });
+            socket.once("error", (error) => {
+                settle();
+                reject(this.connectionError(error));
+            });
+        });
+    }
+    /** Closes the connections kept open for later requests. A request sent afterwards opens a new one. */
+    close() {
+        this.agent.destroy();
+    }
+    async send(exchange, sending) {
+        if (!sending.keyed) {
+            return this.sendAttempt(exchange, undefined, sending.timed);
+        }
+        // Every attempt of one changing request carries the same key, so that the service does the work once.
+        const key = randomUUID().replaceAll("-", "");
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.sendAttempt(exchange, key, sending.timed);
+            }
+            catch (error) {
+                if (!(error instanceof EastIndiaConnectionError) || error.failure !== "unreachable" || attempt >= this.settings.requestRetries) {
+                    throw error;
+                }
+                await delay(this.settings.requestRetryDelayMilliseconds, undefined, { signal: exchange.signal });
+            }
+        }
+    }
+    // One attempt, read to the end of its answer. The client's time limit covers both the reply and the reading of its body; when it
+    // passes, the request is abandoned and reported as timedOut, while the caller's own signal rejects with the caller's reason.
+    async sendAttempt(exchange, key, timed) {
+        const limit = timed ? AbortSignal.timeout(this.settings.requestTimeoutMilliseconds) : undefined;
+        const signal = combine(exchange.signal, limit);
+        try {
+            const response = await this.dispatch(exchange, key, signal);
+            const body = await readAll(response, signal).catch((error) => {
+                throw signal?.aborted === true ? error : this.connectionError(error);
+            });
+            return { status: response.statusCode ?? 0, headers: response.headers, body };
+        }
+        catch (error) {
+            if (limit?.aborted === true && exchange.signal?.aborted !== true) {
+                throw new EastIndiaConnectionError(this.addressText, "timedOut", error);
+            }
+            throw error;
+        }
+    }
+    // Sends the request and gives the answer once its headers have arrived. A refusal is read to its end and thrown as
+    // EastIndiaApiError; an error before any answer is thrown as EastIndiaConnectionError, unless the signal ended the request.
+    dispatch(exchange, key, signal) {
+        signal?.throwIfAborted();
+        return new Promise((resolve, reject) => {
+            const request = this.createRequest(exchange, key);
+            const abort = () => {
+                request.destroy(signal?.reason instanceof Error ? signal.reason : undefined);
+                reject(signal?.reason);
+            };
+            signal?.addEventListener("abort", abort, { once: true });
+            request.once("response", (response) => {
+                signal?.removeEventListener("abort", abort);
+                const status = response.statusCode ?? 0;
+                if (status < 400) {
+                    resolve(response);
+                    return;
+                }
+                readAll(response, signal).then((body) => {
+                    reject(new EastIndiaApiError(status, readError({ status, headers: response.headers, body })));
+                }, (error) => {
+                    reject(signal?.aborted === true ? signal.reason : this.connectionError(error));
+                });
+            });
+            request.once("error", (error) => {
+                signal?.removeEventListener("abort", abort);
+                reject(signal?.aborted === true ? signal.reason : this.connectionError(error));
+            });
+            this.writeBody(request, exchange.body);
+        });
+    }
+    createRequest(exchange, key) {
+        const headers = {};
+        if (key !== undefined) {
+            headers[Headers.idempotencyKey] = key;
+        }
+        if (exchange.body !== undefined) {
+            headers["Content-Type"] = exchange.body.contentType;
+            const length = "bytes" in exchange.body ? exchange.body.bytes.byteLength : exchange.body.length;
+            if (length !== undefined) {
+                headers["Content-Length"] = String(length);
+            }
+        }
+        const address = this.settings.address;
+        const options = { method: exchange.method, path: exchange.path, headers, agent: this.agent };
+        return address.kind === "https"
+            ? https.request({ ...options, host: address.hostname, port: address.port })
+            : http.request({ ...options, socketPath: address.path, host: "localhost" });
+    }
+    writeBody(request, body) {
+        if (body === undefined) {
+            request.end();
+            return;
+        }
+        if ("bytes" in body) {
+            request.end(body.bytes);
+            return;
+        }
+        const stream = body.open();
+        stream.once("error", (error) => request.destroy(error));
+        stream.pipe(request);
+    }
+    createWebSocket(path) {
+        const address = this.settings.address;
+        if (address.kind === "socket") {
+            return new WebSocket(`ws://localhost${path}`, { createConnection: () => net.connect(address.path) });
+        }
+        const tls = this.settings.tls;
+        const host = address.hostname.includes(":") ? `[${address.hostname}]` : address.hostname;
+        return new WebSocket(`wss://${host}:${String(address.port)}${path}`, { ca: tls?.ca, cert: tls?.cert, key: tls?.key });
+    }
+    connectionError(error) {
+        return error instanceof EastIndiaConnectionError
+            ? error
+            : new EastIndiaConnectionError(this.addressText, classifyConnectionFailure(error, this.settings.address.kind === "socket"), error);
+    }
+    static createAgent(settings) {
+        if (settings.address.kind === "socket") {
+            return new http.Agent({ keepAlive: true });
+        }
+        if (settings.tls === undefined) {
+            throw new Error("A connection over HTTPS needs the certificate files: ca, cert and key.");
+        }
+        return new https.Agent({ keepAlive: true, ca: settings.tls.ca, cert: settings.tls.cert, key: settings.tls.key });
+    }
+}
+/**
+ * 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 function jsonBody(value) {
+    return { contentType: MediaTypes.json, bytes: Buffer.from(JSON.stringify(value), "utf8") };
+}
+/**
+ * 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 function tarBody(archive) {
+    return archive instanceof Uint8Array ? { contentType: MediaTypes.tar, bytes: archive } : { contentType: MediaTypes.tar, open: archive };
+}
+/**
+ * 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 function readError(answer) {
+    const fromBody = tryParseError(answer.body.toString("utf8"));
+    if (fromBody !== null) {
+        return fromBody;
+    }
+    const header = answer.headers[Headers.error.toLowerCase()];
+    return typeof header === "string" ? tryParseError(Buffer.from(header, "base64").toString("utf8")) : 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 function readHeaderJson(headers, name) {
+    const text = headers[name.toLowerCase()];
+    if (typeof text !== "string") {
+        return undefined;
+    }
+    try {
+        return JSON.parse(Buffer.from(text, "base64").toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function tryParseError(text) {
+    try {
+        const value = JSON.parse(text);
+        return typeof value === "object" && value !== null && "code" in value && "message" in value ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function parseJson(answer) {
+    if (answer.body.length === 0) {
+        throw new Error(`The service answered ${String(answer.status)} without the JSON body the route promises.`);
+    }
+    return JSON.parse(answer.body.toString("utf8"));
+}
+/**
+ * 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 async function readAll(stream, signal) {
+    const chunks = [];
+    const stop = () => {
+        stream.destroy(signal?.reason instanceof Error ? signal.reason : undefined);
+    };
+    signal?.addEventListener("abort", stop, { once: true });
+    try {
+        for await (const chunk of stream) {
+            chunks.push(chunk);
+        }
+    }
+    catch (error) {
+        throw signal?.aborted === true ? signal.reason : error;
+    }
+    finally {
+        signal?.removeEventListener("abort", stop);
+    }
+    return Buffer.concat(chunks);
+}
+function combine(first, second) {
+    return first === undefined ? second : second === undefined ? first : AbortSignal.any([first, second]);
+}

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

@@ -0,0 +1,14 @@
+import type { ConnectionFailure } from "../errors.js";
+/**
+ * Decides why a request got no answer, from the error Node reported while sending it.
+ *
+ * A server certificate this client refused carries one of OpenSSL's verification codes. A client certificate the service refused
+ * ends the handshake with a TLS alert, whose OpenSSL code and message name the alert; under TLS 1.3 the alert arrives on the first
+ * read, after the request has been written, and is still named. A refused named pipe is an access error. Anything else is a
+ * connection that never reached the service.
+ *
+ * @param error - The error Node reported.
+ * @param overSocket - Whether the request went to a local socket, such as the named pipe, rather than over HTTPS.
+ * @returns The reason no answer came.
+ */
+export declare function classifyConnectionFailure(error: unknown, overSocket: boolean): ConnectionFailure;

package/dist/transport/connection-failures.js

@@ -0,0 +1,57 @@
+/**
+ * The error codes Node gives when this client refuses the server's certificate: OpenSSL's verification results, and Node's own code
+ * for a certificate that does not name the address. Any of them means the server is not the EastIndia service the client trusts.
+ */
+const ServerCertificateRefusals = new Set([
+    "CERT_HAS_EXPIRED",
+    "CERT_NOT_YET_VALID",
+    "CERT_REJECTED",
+    "CERT_REVOKED",
+    "CERT_SIGNATURE_FAILURE",
+    "CERT_UNTRUSTED",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "ERR_TLS_CERT_ALTNAME_INVALID",
+    "HOSTNAME_MISMATCH",
+    "INVALID_CA",
+    "INVALID_PURPOSE",
+    "PATH_LENGTH_EXCEEDED",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_DECRYPT_CERT_SIGNATURE",
+    "UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY",
+    "UNABLE_TO_GET_ISSUER_CERT",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+]);
+/** The error codes Windows gives, through Node, when it refuses to open a named pipe for the calling account. */
+const PipeRefusals = new Set(["EACCES", "EPERM"]);
+/**
+ * Decides why a request got no answer, from the error Node reported while sending it.
+ *
+ * A server certificate this client refused carries one of OpenSSL's verification codes. A client certificate the service refused
+ * ends the handshake with a TLS alert, whose OpenSSL code and message name the alert; under TLS 1.3 the alert arrives on the first
+ * read, after the request has been written, and is still named. A refused named pipe is an access error. Anything else is a
+ * connection that never reached the service.
+ *
+ * @param error - The error Node reported.
+ * @param overSocket - Whether the request went to a local socket, such as the named pipe, rather than over HTTPS.
+ * @returns The reason no answer came.
+ */
+export function classifyConnectionFailure(error, overSocket) {
+    const code = codeOf(error);
+    if (ServerCertificateRefusals.has(code)) {
+        return "serverNotTrusted";
+    }
+    if (code.includes("ALERT") || messageOf(error).toLowerCase().includes("alert")) {
+        return "certificateRefused";
+    }
+    if (overSocket && PipeRefusals.has(code)) {
+        return "pipeRefused";
+    }
+    return "unreachable";
+}
+function codeOf(error) {
+    return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : "";
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : "";
+}

package/dist/transport/json-lines.d.ts

@@ -0,0 +1,10 @@
+import type { Readable } from "node:stream";
+/**
+ * Reads a stream of JSON objects, one per line (`application/x-ndjson`), which is how the service answers its log and readings
+ * routes. The generator yields each object as soon as its line arrives. Blank lines are skipped. Stopping the iteration early destroys the stream, which
+ * ends the request.
+ *
+ * @param stream - The answer's body.
+ * @returns The objects, in the order the lines arrive.
+ */
+export declare function readJsonLines<T>(stream: Readable): AsyncGenerator<T, void, undefined>;

package/dist/transport/json-lines.js

@@ -0,0 +1,23 @@
+import { createInterface } from "node:readline";
+/**
+ * Reads a stream of JSON objects, one per line (`application/x-ndjson`), which is how the service answers its log and readings
+ * routes. The generator yields each object as soon as its line arrives. Blank lines are skipped. Stopping the iteration early destroys the stream, which
+ * ends the request.
+ *
+ * @param stream - The answer's body.
+ * @returns The objects, in the order the lines arrive.
+ */
+export async function* readJsonLines(stream) {
+    const lines = createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of lines) {
+            if (line.length > 0) {
+                yield JSON.parse(line);
+            }
+        }
+    }
+    finally {
+        lines.close();
+        stream.destroy();
+    }
+}

package/dist/transport/query-text.d.ts

@@ -0,0 +1,49 @@
+import type { Filters } from "../contract/common.js";
+/** A value a query parameter takes: text, a number, or a boolean written `true` or `false`. */
+type QueryValue = string | number | boolean;
+/**
+ * Builds a route's query string as the API reads it. A parameter whose value is undefined is left out, so that the service applies
+ * its default; the service refuses a parameter it does not know, so nothing else is ever added.
+ */
+export declare class QueryText {
+    private readonly parameters;
+    /**
+     * Adds one parameter, unless its value is undefined.
+     *
+     * @param name - The parameter's name, as the API spells it.
+     * @param value - The value; undefined leaves the parameter out.
+     * @returns This query.
+     */
+    add(name: string, value: QueryValue | undefined): this;
+    /**
+     * Adds a boolean parameter only when it is true: false is every route's default for its boolean parameters.
+     *
+     * @param name - The parameter's name.
+     * @param value - The value; false or undefined leaves the parameter out.
+     * @returns This query.
+     */
+    addFlag(name: string, value: boolean | undefined): this;
+    /**
+     * Adds a list, which the API reads as the parameter repeated once per value.
+     *
+     * @param name - The parameter's name.
+     * @param values - The values; none leaves the parameter out.
+     * @returns This query.
+     */
+    addEach(name: string, values: readonly string[] | undefined): this;
+    /**
+     * Adds an object the API reads as URL-encoded JSON, such as `filters`, `buildargs` or `labels`.
+     *
+     * @param name - The parameter's name.
+     * @param value - The object; undefined or an object without members leaves the parameter out.
+     * @returns This query.
+     */
+    addJson(name: string, value: Filters | Readonly<Record<string, string>> | undefined): this;
+    /**
+     * Writes the query.
+     *
+     * @returns The query with its leading `?`, or an empty string when it has no parameter.
+     */
+    toString(): string;
+}
+export {};

package/dist/transport/query-text.js

@@ -0,0 +1,62 @@
+/**
+ * Builds a route's query string as the API reads it. A parameter whose value is undefined is left out, so that the service applies
+ * its default; the service refuses a parameter it does not know, so nothing else is ever added.
+ */
+export class QueryText {
+    parameters = new URLSearchParams();
+    /**
+     * Adds one parameter, unless its value is undefined.
+     *
+     * @param name - The parameter's name, as the API spells it.
+     * @param value - The value; undefined leaves the parameter out.
+     * @returns This query.
+     */
+    add(name, value) {
+        if (value !== undefined) {
+            this.parameters.append(name, String(value));
+        }
+        return this;
+    }
+    /**
+     * Adds a boolean parameter only when it is true: false is every route's default for its boolean parameters.
+     *
+     * @param name - The parameter's name.
+     * @param value - The value; false or undefined leaves the parameter out.
+     * @returns This query.
+     */
+    addFlag(name, value) {
+        return value === true ? this.add(name, true) : this;
+    }
+    /**
+     * Adds a list, which the API reads as the parameter repeated once per value.
+     *
+     * @param name - The parameter's name.
+     * @param values - The values; none leaves the parameter out.
+     * @returns This query.
+     */
+    addEach(name, values) {
+        for (const value of values ?? []) {
+            this.add(name, value);
+        }
+        return this;
+    }
+    /**
+     * Adds an object the API reads as URL-encoded JSON, such as `filters`, `buildargs` or `labels`.
+     *
+     * @param name - The parameter's name.
+     * @param value - The object; undefined or an object without members leaves the parameter out.
+     * @returns This query.
+     */
+    addJson(name, value) {
+        return value === undefined || Object.keys(value).length === 0 ? this : this.add(name, JSON.stringify(value));
+    }
+    /**
+     * Writes the query.
+     *
+     * @returns The query with its leading `?`, or an empty string when it has no parameter.
+     */
+    toString() {
+        const text = this.parameters.toString();
+        return text === "" ? "" : `?${text}`;
+    }
+}

package/dist/transport/service-address.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Where the client sends its requests: a host and port reached over HTTPS with mutual TLS, or a local socket, which on Windows is
+ * the service's named pipe and needs no certificate. The `endia` CLI writes the same two places as `tcp://<host>:<port>` and
+ * `npipe:////./pipe/<name>`, and `parseServiceAddress` reads those forms.
+ */
+export type ServiceAddress = {
+    readonly kind: "https";
+    readonly hostname: string;
+    readonly port: number;
+} | {
+    readonly kind: "socket";
+    readonly path: string;
+};
+/**
+ * Reads an address in the forms the CLI and `EASTINDIA_HOST` take: `tcp://<host>:<port>`, over which TLS is always used and always
+ * verified, or `npipe:////./pipe/<name>`, a named pipe on this PC.
+ *
+ * @param host - The address, for example `tcp://host.docker.internal:7443` or `npipe:////./pipe/eastindia_engine`.
+ * @param setting - Where the address came from, which the error message names, for example `EASTINDIA_HOST`.
+ * @returns Where the client connects.
+ * @throws Error when the address has neither form.
+ */
+export declare function parseServiceAddress(host: string, setting: string): ServiceAddress;
+/**
+ * Names an address as messages name it: the host and port, or the socket's path.
+ *
+ * @param address - The address.
+ * @returns For example `host.docker.internal:7443` or `\\.\pipe\eastindia_engine`.
+ */
+export declare function describeServiceAddress(address: ServiceAddress): string;