@veilway/sdk 0.0.0-stage → 0.2.6-alpha

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @veilway/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed client for the control API of a Veilway node. The node serves the API on a unix socket, so the client takes a `fetch` function and a base URL and leaves the choice of how to reach the socket to you. It has no runtime dependencies.
+
+## Use
+
+```ts
+import {Agent, fetch as undiciFetch} from "undici";
+import {Client, VeilwayError, type Fetch} from "@veilway/sdk";
+
+const dispatcher = new Agent({connect: {socketPath: "/run/veilway/control.sock"}});
+const fetch: Fetch = (url, init) => undiciFetch(url, {...init, dispatcher}) as unknown as ReturnType<Fetch>;
+const client = new Client(fetch, "http://veilway");
+console.log(await client.status());
+const running = await client.getConfig();
+try {
+	await client.applyConfig({...running.document, log: {level: "debug"}}, running.revision);
+} catch (e) {
+	if (e instanceof VeilwayError) console.log(e.status, e.code, e.message, e.details);
+}
+const stop = new AbortController();
+for await (const event of client.events(stop.signal)) {
+	if (event.event === "user_cut_off") console.log(event.data.user);
+}
+```
+
+Every failure from the node is thrown as `VeilwayError` with `status`, `code`, `message` and `details`. A stale revision on `applyConfig` has the code `stale_revision`, and its first detail holds the revision that runs now.
+
+`events` yields `{id, event, data}`, ends when the node closes the stream or the signal aborts, and tells a slow reader how many events it missed with a `lagged` event (which has no id). Event names the client does not know are skipped.
+
+The config document in `getConfig` has every secret replaced by `"<redacted>"`. Pass it back as it is and the node keeps the real values.
+
+## Commands
+
+Everything runs in Docker with the image `node:22`.
+
+```
+docker run --rm -v "$PWD/../..:/w" -v veilway-sdk-nm:/w/packages/sdk/node_modules -w /w/packages/sdk node:22 sh -c "npm ci && npm run generate"
+docker run --rm -v "$PWD/../..:/w" -v veilway-sdk-nm:/w/packages/sdk/node_modules -w /w/packages/sdk node:22 sh -c "npm ci && npm run check"
+```
+
+- `npm run generate` writes `src/schema.ts` from `crates/veilway-api/openapi.json`. Run it after the Rust tests rewrite that file.
+- `npm run check` generates into a temporary file, fails if it differs from `src/schema.ts`, then type-checks.
+- `npm test` compiles and runs the tests. The ones that talk to a node need `VEILWAY_API_SOCKET` and are skipped without it. The parser test needs no node.
+
+## Test against a running node
+
+The test starts nothing. `test/live.sh` starts a node from a release binary with a throwaway config and keys, runs `npm test` against its socket and stops the node. Run it in a container that has both node 22 and a `veilway` binary that matches its libc, with `VEILWAY_BIN` set to the binary. Without the script, start a node with `veilway run --api /path/to.sock` and set `VEILWAY_API_SOCKET` to that path.

package/dist/src/index.d.ts

@@ -0,0 +1,93 @@
+import type { components } from "./schema.js";
+type Schemas = components["schemas"];
+export type { components, paths, operations } from "./schema.js";
+export type Status = Schemas["Status"];
+export type Applied = Schemas["Applied"];
+export type Difference = Schemas["Difference"];
+export type Validation = Schemas["Validation"];
+export type User = Schemas["User"];
+export type Stats = Schemas["Stats"];
+export type Replay = Schemas["Replay"];
+export type Session = Schemas["Session"];
+export type Exit = Schemas["Exit"];
+export type Link = Schemas["Link"];
+export type InboundInfo = Schemas["InboundInfo"];
+export type Problem = Schemas["Problem"];
+/** A config v1 document. The generated schema calls it an object nobody can fill in, so the client takes any object and the node does the checking. */
+export type ConfigDocument = Record<string, unknown>;
+export type RunningConfig = Omit<Schemas["Running"], "document"> & {
+    document: ConfigDocument;
+};
+/** The data of each event on the stream, by the name of the event. */
+export interface EventData {
+    config_applied: Schemas["ConfigApplied"];
+    config_refused: Schemas["ConfigRefused"];
+    user_cut_off: Schemas["UserCutOff"];
+    user_restored: Schemas["UserRestored"];
+    usage_reset: Schemas["UsageReset"];
+    exit_udp_changed: Schemas["ExitUdpChanged"];
+    stats: Schemas["Stats"];
+    lagged: Schemas["Lagged"];
+}
+/** One event of the stream. `id` is empty for `lagged`, which has none. */
+export type NodeEvent = {
+    [K in keyof EventData]: {
+        id: string | undefined;
+        event: K;
+        data: EventData[K];
+    };
+}[keyof EventData];
+/** The part of a fetch response the client uses, so the fetch of undici, the global one and a test double all fit. */
+export interface FetchResponse {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+    body: ReadableStream<Uint8Array> | null;
+}
+export type Fetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<FetchResponse>;
+/** Every answer that is not a success, and an answer the client could not read. */
+export declare class VeilwayError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: Problem[];
+    constructor(status: number, code: string, message: string, details?: Problem[]);
+}
+export declare class Client {
+    private readonly fetch;
+    private readonly base;
+    /** `base` is only the start of every URL, for example "http://veilway": over a unix socket the host is never looked up, the `fetch` decides where the bytes go. */
+    constructor(fetch: Fetch, base: string);
+    private send;
+    private json;
+    status(): Promise<Status>;
+    /** The running config with every secret replaced by "<redacted>", and the revision to give `applyConfig`. */
+    getConfig(): Promise<RunningConfig>;
+    /** Puts a document in force. `revision` is the one of the config the change was made on. A stale one throws a `stale_revision` error whose details hold the revision that runs. */
+    applyConfig(document: ConfigDocument, revision: string): Promise<Applied>;
+    validateConfig(document: ConfigDocument): Promise<Validation>;
+    diffConfig(document: ConfigDocument): Promise<Difference>;
+    listUsers(): Promise<User[]>;
+    getUser(name: string): Promise<User>;
+    /** Starts the user's quota count over, which lets a user who was out of quota connect again at once. With `totals` the user's `traffic` goes back to zero as well. The answer is the user as `getUser` gives them, and the same call again changes nothing more. */
+    resetUsage(name: string, options?: {
+        totals?: boolean;
+    }): Promise<User>;
+    /** Empties the replay memory of the obfuscated transports and sets its floor and limit to the node's clock plus 60 seconds. Every client is refused for those 60 seconds, and a proof that was accepted with a timestamp above the new floor can be used once more. A node that has run no obfuscated transport throws `replay_absent`. The answer is the replay memory after the reset. */
+    resetReplay(): Promise<Replay>;
+    stats(): Promise<Stats>;
+    listSessions(): Promise<Session[]>;
+    listExits(): Promise<Exit[]>;
+    /** Every inbound with its WireGuard public key, the public half of its node transport key, and the rating of each transport. No private key. */
+    listInbounds(): Promise<InboundInfo[]>;
+    /** Every enabled node link with its state and its counters. */
+    listLinks(): Promise<Link[]>;
+    /** The event stream. It ends when the node closes it or when `signal` aborts, and throws when the node refuses it or sends something that is not an event. Event names this client does not know are skipped. */
+    events(signal?: AbortSignal): AsyncGenerator<NodeEvent, void, undefined>;
+}

package/dist/src/index.js

@@ -0,0 +1,136 @@
+/** The most one line of the event stream may hold before the client gives up on it. */
+const MAX_LINE = 1 << 20;
+const EVENTS = new Set(["config_applied", "config_refused", "user_cut_off", "user_restored", "usage_reset", "exit_udp_changed", "stats", "lagged"]);
+/** Every answer that is not a success, and an answer the client could not read. */
+export class VeilwayError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details = []) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = "VeilwayError";
+    }
+}
+export class Client {
+    fetch;
+    base;
+    /** `base` is only the start of every URL, for example "http://veilway": over a unix socket the host is never looked up, the `fetch` decides where the bytes go. */
+    constructor(fetch, base) {
+        this.fetch = fetch;
+        this.base = base;
+    }
+    async send(method, path, headers = {}, body, signal) {
+        const response = await this.fetch(this.base.replace(/\/+$/, "") + path, { method, headers: { accept: "application/json", ...headers }, body, signal });
+        if (response.status >= 200 && response.status < 300)
+            return response;
+        const text = await response.text().catch(() => "");
+        let failure;
+        try {
+            failure = JSON.parse(text).error;
+        }
+        catch { }
+        if (failure && typeof failure.code === "string" && typeof failure.message === "string")
+            throw new VeilwayError(response.status, failure.code, failure.message, Array.isArray(failure.details) ? failure.details : []);
+        throw new VeilwayError(response.status, "bad_response", "The node answered " + response.status + " with a body that is not an error document.");
+    }
+    async json(method, path, headers = {}, body) {
+        const response = await this.send(method, path, body ? { "content-type": "application/json", ...headers } : headers, body && JSON.stringify(body));
+        try {
+            return JSON.parse(await response.text());
+        }
+        catch {
+            throw new VeilwayError(response.status, "bad_response", "The node answered with a body that is not JSON.");
+        }
+    }
+    status() { return this.json("GET", "/v1/status"); }
+    /** The running config with every secret replaced by "<redacted>", and the revision to give `applyConfig`. */
+    getConfig() { return this.json("GET", "/v1/config"); }
+    /** Puts a document in force. `revision` is the one of the config the change was made on. A stale one throws a `stale_revision` error whose details hold the revision that runs. */
+    applyConfig(document, revision) { return this.json("PUT", "/v1/config", { "if-match": "\"" + revision.replace(/"/g, "") + "\"" }, document); }
+    validateConfig(document) { return this.json("POST", "/v1/config/validate", {}, document); }
+    diffConfig(document) { return this.json("POST", "/v1/config/diff", {}, document); }
+    async listUsers() { return (await this.json("GET", "/v1/users")).users; }
+    getUser(name) { return this.json("GET", "/v1/users/" + encodeURIComponent(name)); }
+    /** Starts the user's quota count over, which lets a user who was out of quota connect again at once. With `totals` the user's `traffic` goes back to zero as well. The answer is the user as `getUser` gives them, and the same call again changes nothing more. */
+    resetUsage(name, options = {}) { return this.json("POST", "/v1/users/" + encodeURIComponent(name) + "/usage/reset", {}, { totals: options.totals === true }); }
+    /** Empties the replay memory of the obfuscated transports and sets its floor and limit to the node's clock plus 60 seconds. Every client is refused for those 60 seconds, and a proof that was accepted with a timestamp above the new floor can be used once more. A node that has run no obfuscated transport throws `replay_absent`. The answer is the replay memory after the reset. */
+    resetReplay() { return this.json("POST", "/v1/replay/reset"); }
+    stats() { return this.json("GET", "/v1/stats"); }
+    async listSessions() { return (await this.json("GET", "/v1/sessions")).sessions; }
+    async listExits() { return (await this.json("GET", "/v1/exits")).exits; }
+    /** Every inbound with its WireGuard public key, the public half of its node transport key, and the rating of each transport. No private key. */
+    async listInbounds() { return (await this.json("GET", "/v1/inbounds")).inbounds; }
+    /** Every enabled node link with its state and its counters. */
+    async listLinks() { return (await this.json("GET", "/v1/links")).links; }
+    /** The event stream. It ends when the node closes it or when `signal` aborts, and throws when the node refuses it or sends something that is not an event. Event names this client does not know are skipped. */
+    async *events(signal) {
+        let reader;
+        try {
+            const response = await this.send("GET", "/v1/events", { accept: "text/event-stream" }, undefined, signal);
+            if (!response.body)
+                throw new VeilwayError(response.status, "bad_response", "The node answered the event stream without a body.");
+            reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let pending = "", id, event = "message", data = [], skipLf = false;
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                pending += decoder.decode(value, { stream: true });
+                if (skipLf && pending.startsWith("\n"))
+                    pending = pending.slice(1);
+                skipLf = false;
+                let cut;
+                while ((cut = /\r\n|\n|\r/.exec(pending))) {
+                    const line = pending.slice(0, cut.index);
+                    // A CR at the very end may be the first half of a CRLF whose LF has not arrived yet.
+                    if (cut[0] === "\r" && cut.index + 1 === pending.length)
+                        skipLf = true;
+                    pending = pending.slice(cut.index + cut[0].length);
+                    if (line === "") {
+                        const name = event, text = data.join("\n"), last = name === "lagged" ? undefined : id;
+                        event = "message";
+                        data = [];
+                        if (!EVENTS.has(name))
+                            continue;
+                        let parsed;
+                        try {
+                            parsed = JSON.parse(text);
+                        }
+                        catch {
+                            throw new VeilwayError(response.status, "bad_event", "An event of the stream holds no JSON.");
+                        }
+                        yield { id: last, event: name, data: parsed };
+                        continue;
+                    }
+                    if (line.startsWith(":"))
+                        continue;
+                    const colon = line.indexOf(":");
+                    const field = colon < 0 ? line : line.slice(0, colon);
+                    let value = colon < 0 ? "" : line.slice(colon + 1);
+                    if (value.startsWith(" "))
+                        value = value.slice(1);
+                    if (field === "id" && !value.includes("\0"))
+                        id = value;
+                    else if (field === "event")
+                        event = value;
+                    else if (field === "data")
+                        data.push(value);
+                }
+                if (pending.length > MAX_LINE)
+                    throw new VeilwayError(response.status, "bad_event", "A line of the event stream is longer than " + MAX_LINE + " bytes.");
+            }
+        }
+        catch (e) {
+            if (signal?.aborted)
+                return;
+            throw e;
+        }
+        finally {
+            await reader?.cancel().catch(() => { });
+        }
+    }
+}