@veilway/sdk 0.3.5-alpha → 0.3.7-alpha

package/dist/src/index.d.ts

@@ -15,6 +15,8 @@ export type Upstream = Schemas["Upstream"];
 export type UpstreamPreview = Schemas["UpstreamPreview"];
 export type UpstreamPreviewRequest = Schemas["UpstreamPreviewRequest"];
 export type UpstreamConfirmed = Schemas["UpstreamConfirmed"];
+export type UpstreamChoice = Schemas["UpstreamChoice"];
+export type UpstreamChosen = Schemas["UpstreamChosen"];
 export type UpstreamRemoved = Schemas["UpstreamRemoved"];
 export type InboundInfo = Schemas["InboundInfo"];
 export type Problem = Schemas["Problem"];
@@ -109,6 +111,8 @@ export declare class Client {
         move?: boolean;
         hosts?: boolean;
     }): Promise<UpstreamConfirmed>;
+    /** Changes what the config chooses on an upstream: `profile`, `failover`, `transport` and `exit`. A field that is left out stays and null is automatic. Only an exit change keeps the running tunnel (`live`). The link, keys, allow, allow_private and via cannot be changed this way. */
+    chooseUpstream(tag: string, choice: UpstreamChoice): Promise<UpstreamChosen>;
     /** Asks the upstream to connect again now: every wait it was in starts over. */
     retryUpstream(tag: string): Promise<{
         tag: string;

package/dist/src/index.js

@@ -75,6 +75,8 @@ export class Client {
     removeUpstream(tag) { return this.json("DELETE", "/v1/upstreams/" + encodeURIComponent(tag)); }
     /** Confirms the move of the provider's endpoint and the new refresh hosts that `listUpstreams` reports as pending. Without options both are confirmed; with them a field that is left out is false. The answer says what had been waiting. */
     confirmUpstream(tag, options = {}) { return this.json("POST", "/v1/upstreams/" + encodeURIComponent(tag) + "/confirm", {}, options); }
+    /** Changes what the config chooses on an upstream: `profile`, `failover`, `transport` and `exit`. A field that is left out stays and null is automatic. Only an exit change keeps the running tunnel (`live`). The link, keys, allow, allow_private and via cannot be changed this way. */
+    chooseUpstream(tag, choice) { return this.json("PATCH", "/v1/upstreams/" + encodeURIComponent(tag), {}, choice); }
     /** Asks the upstream to connect again now: every wait it was in starts over. */
     retryUpstream(tag) { return this.json("POST", "/v1/upstreams/" + encodeURIComponent(tag) + "/retry"); }
     /** 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. */

package/dist/src/schema.d.ts

@@ -140,7 +140,8 @@ export interface paths {
         delete: operations["relayDelete"];
         options?: never;
         head?: never;
-        patch?: never;
+        /** The same call with PATCH, which is how the choice on an upstream is changed. */
+        patch: operations["relayPatch"];
         trace?: never;
     };
     "/v1/openapi.json": {
@@ -293,7 +294,8 @@ export interface paths {
         delete: operations["removeUpstream"];
         options?: never;
         head?: never;
-        patch?: never;
+        /** Changes what the config chooses on an upstream: the profile (null: every profile in turn), failover to the other profiles, the transport (null: automatic) and the exit of the provider. A field that is left out stays. It goes through the same checks and the same apply as a config document, at the revision that runs now (read again once if it moved), and is written to the config file. When only the exit changed the running tunnel is kept and asked for the other exit, and nothing leaves through the old one meanwhile (live: true). The link, the keys, allow, allow_private and via are never changed by it. */
+        patch: operations["chooseUpstream"];
         trace?: never;
     };
     "/v1/upstreams/{tag}/confirm": {
@@ -551,6 +553,18 @@ export interface components {
         };
         Exit: {
             backend: components["schemas"]["Backend"];
+            /** @description The address and port of the server the outbound talks to now, which is the one its name resolved to. Null for another exit and before the name resolved. */
+            endpoint: string | null;
+            /**
+             * Format: uint64
+             * @description The flows open through the WireGuard outbound's own stack, TCP and UDP. Null for every other exit.
+             */
+            flows: number | null;
+            /**
+             * Format: uint64
+             * @description Seconds since the last handshake with the server. Null for another exit and before the first handshake.
+             */
+            handshake_secs: number | null;
             /**
              * Format: uint64
              * @description Seconds since the interface went down. Null while `interface_up` is not false.
@@ -584,6 +598,20 @@ export interface components {
             name: string;
             /** @description The tag of the outbound of a netstack backend. */
             outbound: string | null;
+            /** @description Why the WireGuard outbound is down. Null while `outbound_up` is not false. */
+            outbound_down_reason: string | null;
+            /**
+             * Format: uint64
+             * @description Seconds since the WireGuard outbound went down. Null while `outbound_up` is not false.
+             */
+            outbound_down_secs: number | null;
+            /**
+             * Format: uint64
+             * @description How often the WireGuard outbound switched between working and down.
+             */
+            outbound_flips: number;
+            /** @description For an exit through a WireGuard outbound: whether the outbound works. It is false only while it is down: the server has not answered a handshake for 20 seconds or a datagram could not be sent to it. An outbound with no handshake in the last 180 seconds and nothing unanswered is idle and counts as up. While it is false the exit does not work, devices without a choice of exit leave through `routing.fallback`, and nothing leaves around it. Null for every other exit. */
+            outbound_up: boolean | null;
             tag: string;
             traffic: components["schemas"]["Traffic"];
             /** @description Whether the SOCKS5 proxy of the exit relays UDP as far as the node knows. Null for an exit without one. */
@@ -649,6 +677,15 @@ export interface components {
         InboundTransport: {
             /** @description False for a transport the config switched off: it does not listen. */
             enabled: boolean;
+            /**
+             * Format: int64
+             * @description Unix seconds: when the node found the new key (at a start, a reload or when the certificate file was read again). The node does not refuse the certificate.
+             */
+            key_changed_at: number | null;
+            /** @description Only on a `tls` transport that is listening: the SHA-256 of the key's SubjectPublicKeyInfo of its certificate, in standard base64, the pin a link or a profile carries for it. */
+            pin: string | null;
+            /** @description Only when the node found that the pin is not the one it served before, for 30 days after: the pin that was served before. A link or a profile that pins it fails until it is paired or refreshed again. */
+            previous_pin: string | null;
             rating: components["schemas"]["Rating"];
             transport: components["schemas"]["Transport"];
         };
@@ -664,10 +701,30 @@ export interface components {
             /** Format: uint64 */
             missed: number;
         };
+        /** @description What the user's speed limits did since the node started. */
+        Limited: {
+            /** Format: uint64 */
+            down_packets: number;
+            /**
+             * Format: uint64
+             * @description Milliseconds that TCP streams of the user waited for the limit, added up over streams and both directions.
+             */
+            paced_ms: number;
+            /**
+             * Format: uint64
+             * @description Packets dropped for being over the rate: UDP, pings and TCP that does not leave through a netstack exit. TCP that does is slowed down, never dropped.
+             */
+            up_packets: number;
+        };
         /** @description One node link. It holds no key and no secret. */
         Link: {
             /** Format: uint */
             candidate_index: number | null;
+            /**
+             * Format: uint64
+             * @description On the exit half: packets this node forwarded from the link into another link, which happens only for a link with allow_chain. Zero otherwise.
+             */
+            chained: number;
             /** @description On the exit half: why this node cut the link off. Null for a link that may run. */
             denied: components["schemas"]["Denied"] | null;
             /**
@@ -721,7 +778,7 @@ export interface components {
         /** @description Which side of a managed link this node is. */
         LinkManage: "peer" | "by_peer";
         LinkRole: "listener" | "dialler";
-        LinkState: "up" | "connecting" | "unreachable" | "refused" | "ended";
+        LinkState: "up" | "connecting" | "unreachable" | "refused" | "pin_mismatch" | "ended";
         Links: {
             links: components["schemas"]["Link"][];
         };
@@ -789,7 +846,7 @@ export interface components {
         OutboundStats: {
             /** Format: uint64 */
             down_bytes_per_sec: number;
-            /** @description Why an `xray` outbound cannot carry a flow now, in words: the add-on is not installed or not running, Xray ended and starts again, or the name of its server does not resolve to an address the node may dial. Every exit through it is down with the same reason. Null while it carries, and for an outbound that is not `xray`. */
+            /** @description Why an `xray` outbound cannot carry a flow now, in words: the add-on is not installed or not running, Xray ended and starts again, or the name of its server does not resolve to an address the node may dial. For a `wireguard` outbound: its server has not answered a handshake for 20 seconds, a datagram could not be sent to it, or its name or address is refused. Every exit through it is down with the same reason. Null while it carries, and for an outbound that is neither. */
             down_reason: string | null;
             /**
              * Format: uint64
@@ -968,22 +1025,24 @@ export interface components {
             generation: number;
             revision: string;
         };
-        /** @description A certificate the node made for a `tls` listener, with the key it keeps. */
+        /** @description The certificate of a `tls` listener, with the pin of its key. */
         SelfSigned: {
             /** @description The listen address, as the config writes it. */
             listen: string;
             /**
              * Format: int64
-             * @description Unix seconds, 80 to 100 days after `not_before`, drawn per certificate. Clients do not check it.
+             * @description Unix seconds. For a self-signed certificate 80 to 100 days after `not_before`, drawn per certificate, and clients do not check it.
              */
             not_after: number;
             /**
              * Format: int64
-             * @description Unix seconds. The node makes the certificate anew with the same key 20 days before `not_after`.
+             * @description Unix seconds. For a self-signed certificate the node makes it anew with the same key 20 days before `not_after`.
              */
             not_before: number;
-            /** @description The SHA-256 of the key's SubjectPublicKeyInfo, in standard base64: the pin a profile's candidate carries with `self_signed`. It stays the same when the certificate is made anew. */
+            /** @description The SHA-256 of the key's SubjectPublicKeyInfo, in standard base64: the pin a profile's or a link's candidate carries. For a self-signed certificate it stays the same when the certificate is made anew. */
             pin: string;
+            /** @description True for a certificate the node made itself: the candidate that pins it is marked `self_signed`, and the pin is its only check. False for a certificate from the config's `cert` file: the chain is checked as well and the candidate is not marked `self_signed`. */
+            self_signed: boolean;
         };
         /** @description A device with a live session on one inbound. The address the device connects from is not part of it. */
         Session: {
@@ -1065,7 +1124,7 @@ export interface components {
         };
         Status: {
             addons: components["schemas"]["Addons"];
-            /** @description The self-signed certificates the node made for its `tls` transports with `"self_signed": true`, one for each listen address. Empty for a node that has none. */
+            /** @description The certificate of every `tls` transport, one for each listen address, with its pin: the ones the node made for transports with `"self_signed": true` (`self_signed` true), and the ones read from the `cert` file of the others (`self_signed` false: a chain from an authority, the pin is the second condition). Empty for a node that has none. */
             certificates: components["schemas"]["SelfSigned"][];
             /** Format: uint */
             exits: number;
@@ -1509,9 +1568,19 @@ export interface components {
         };
         /** @description What the node is doing for one upstream. Nothing in it is a key, a secret, a token or the link. */
         Upstream: {
+            choice: components["schemas"]["UpstreamChoiceState"];
+            /**
+             * Format: uint64
+             * @description Seconds the tunnel has been connected. Null while it is not.
+             */
+            connected_secs: number | null;
             counters: components["schemas"]["UpstreamCounters"];
+            /** @description What the tunnel itself says: connecting, reconnecting, connected, stopped:<reason> (quota, expired, disabled or node-stopping) or failed. Null while no tunnel exists. */
+            engine_state: string | null;
             /** @description The exit of the provider in use, and the exits it offers. */
             exit: string | null;
+            /** @description The exits the provider offers, at most 16, once the control channel is open. */
+            exits: components["schemas"]["UpstreamExitState"][];
             /**
              * Format: int64
              * @description When the document stops being current and when it was last refreshed, in Unix seconds.
@@ -1530,7 +1599,11 @@ export interface components {
             pending_move: string | null;
             /** @description The profile in use, and the transport it is connected over. */
             profile: string | null;
+            /** @description Every profile of the document held, in the order they are tried, and whether each is usable. */
+            profiles: components["schemas"]["UpstreamProfileState"][];
             provider: string | null;
+            /** @description The same notices with the severity the provider gave them. */
+            provider_notices: components["schemas"]["UpstreamNotice"][];
             quota: components["schemas"]["UpstreamQuota"] | null;
             /** @description Plain words for why the state is what it is. Empty while it is up. */
             reason: string;
@@ -1548,6 +1621,35 @@ export interface components {
             state_secs: number;
             tag: string;
             transport: components["schemas"]["Transport"] | null;
+            /** @description The types of transport the profile in use lists. */
+            transports: components["schemas"]["Transport"][];
+        };
+        /** @description What to choose on an upstream. A field that is left out stays as it is, and null is automatic. The change goes through the same checks and the same apply as a config document does, and is written to the config file. Only the exit is taken on the running tunnel; any other field makes the tunnel again. */
+        UpstreamChoice: {
+            /** @description The tag of the provider's exit to leave through. Null: the provider's default. */
+            exit?: string | null;
+            /** @description Whether the other profiles are tried when the named one cannot be used. Null is false. */
+            failover?: boolean | null;
+            /** @description The profile of the provider's document to use. Null: every profile is tried in the document's order, starting with the last one that carried. */
+            profile?: string | null;
+            /** @description The type of transport to connect over: udp, udp-obfs, tls, ws, ws-plain, fronted or fronted-shaped. Null: the engine picks from every transport of the profile. */
+            transport?: string | null;
+        };
+        /** @description What the config chooses on an upstream: null is automatic. */
+        UpstreamChoiceState: {
+            /** @description The exit of the provider that is asked for now, which may be one the operator just switched to. */
+            exit: string | null;
+            failover: boolean;
+            profile: string | null;
+            transport: string | null;
+        };
+        /** @description What a choice on an upstream came to: the config now in force, and whether only the exit changed, so that the tunnel was kept and asked for the other exit. */
+        UpstreamChosen: {
+            /** Format: uint64 */
+            generation: number;
+            live: boolean;
+            revision: string;
+            tag: string;
         };
         /** @description A class of transports the operator allows an upstream to use, as the client engine ranks them from strongest to weakest. `cover` is always allowed. */
         UpstreamClass: "cover" | "no_cover" | "exposed" | "plain";
@@ -1603,6 +1705,23 @@ export interface components {
             name: string;
             tag: string;
         };
+        /** @description An exit the provider offers, with its name as plain text. */
+        UpstreamExitState: {
+            all_protocols: boolean;
+            /** @description Two uppercase letters. */
+            country: string | null;
+            name: string;
+            /** @description This node's device has this exit selected at the provider. */
+            selected: boolean;
+            tag: string;
+        };
+        /** @description A notice of the provider, as plain text. */
+        UpstreamNotice: {
+            severity: components["schemas"]["UpstreamSeverity"];
+            text: string;
+        };
+        /** @enum {string} */
+        UpstreamPeriod: "none" | "daily" | "weekly" | "monthly";
         /** @description The answer to a preview: the document the provider sent, verified under the key of the link, as the operator reads it before saying yes. Fetching it took a place at the provider. The place is given back when the preview is declined or runs out, and made permanent by the config that names the same link and device within `expires_in_secs`. */
         UpstreamPreview: {
             /**
@@ -1673,11 +1792,29 @@ export interface components {
             /** @description In the provider's order. */
             transports: components["schemas"]["Transport"][];
         };
+        /** @description A profile of the provider's document and whether this node can use it now. Never an address. */
+        UpstreamProfileState: {
+            id: string;
+            name: string;
+            /** @description Plain words for why not. Empty when it is usable. */
+            reason: string;
+            usable: boolean;
+        };
         /** @description What the provider says an account has used and has. A quota of 0 is none. */
         UpstreamQuota: {
+            /** Format: int64 */
+            account_expires_at?: number | null;
+            /** Format: uint64 */
+            down_bytes?: number | null;
+            /** @description What the provider's control channel says besides, once it is open: how often the quota starts over, when the period began and the account ends (Unix seconds), and the bytes of the device's own traffic, up and down. */
+            period?: components["schemas"]["UpstreamPeriod"] | null;
+            /** Format: int64 */
+            period_start?: number | null;
             /** Format: uint64 */
             quota_bytes: number;
             /** Format: uint64 */
+            up_bytes?: number | null;
+            /** Format: uint64 */
             used_bytes: number;
         };
         /** @description What a removal did. `confirmed` says whether the provider took the word that the device left; when it did not, the place stays until the provider removes it. The upstream is not run again by a config that still names it. */
@@ -1690,6 +1827,8 @@ export interface components {
             tag: string;
         };
         /** @enum {string} */
+        UpstreamSeverity: "information" | "warning";
+        /** @enum {string} */
         UpstreamStatus: "fetching" | "connecting" | "up" | "down";
         Upstreams: {
             upstreams: components["schemas"]["Upstream"][];
@@ -1707,6 +1846,7 @@ export interface components {
             dns_set: string | null;
             enabled: boolean;
             expires_at: string | null;
+            limited: components["schemas"]["Limited"];
             name: string;
             /**
              * Format: int64
@@ -1716,6 +1856,13 @@ export interface components {
             /** Format: uint64 */
             quota_bytes: number | null;
             quota_period: components["schemas"]["QuotaPeriod"] | null;
+            /** Format: uint64 */
+            speed_down: number | null;
+            /**
+             * Format: uint64
+             * @description The most the user sends and receives through this node, in bytes per second. Null for no limit.
+             */
+            speed_up: number | null;
             traffic: components["schemas"]["Traffic"];
             /**
              * Format: uint64
@@ -2521,6 +2668,87 @@ export interface operations {
             };
         };
     };
+    relayPatch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                tag: string;
+                path: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": Record<string, never>;
+            };
+        };
+        responses: {
+            /** @description The answer. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": unknown;
+                };
+            };
+            /** @description not_managed: the link does not have manage peer on this node. Node 1's own, with the header veilway-relay: node1. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description no_such_link: the running config has no enabled node link of that tag. not_allowed_through_link: the route or the method is not on the list of routes a managed node serves. Node 1's own, with the header veilway-relay: node1. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description The answer of the other node itself: the relay keeps its own time, 30 seconds and 75 for the preview of an upstream. */
+            408: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description peer_refused: the other node reset the connection, because it does not serve management or has no control API. answer_too_large: the answer is over 8 MiB. bad_answer: the answer is not HTTP/1.1 with a length, or the connection ended before it was whole, and a change it was sent may still have been made: read its revision. Node 1's own, with the header veilway-relay: node1; any other 502 is the other node's own answer, with none of it. */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description link_down: the link is not up, answered at once with nothing sent, and details name its state, since when and what the dialler's last attempt came to. busy: four connections of the link are open, or the node relays as many requests as it takes at once, and none was freed in 5 seconds. Node 1's own answers carry the header veilway-relay: node1; any other 503 is the other node's own, with none of it. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description peer_silent: no answer to the connection within 10 seconds, or none within the request's time. A change the other node was sent may still have been made. Node 1's own, with the header veilway-relay: node1. */
+            504: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+        };
+    };
     openapi: {
         parameters: {
             query?: never;
@@ -2963,6 +3191,104 @@ export interface operations {
             };
         };
     };
+    chooseUpstream: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                tag: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["UpstreamChoice"];
+            };
+        };
+        responses: {
+            /** @description The answer. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["UpstreamChosen"];
+                };
+            };
+            /** @description The body is not one JSON document, or could not be read to its end. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description The running config has no upstream of that tag. Nothing was changed. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description The body was not read within 30 seconds. Nothing was changed: once the node has begun to apply the choice, the answer waits for it and is never this one. */
+            408: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description The running config changed twice while the choice was made. Nothing was changed. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description The body is larger than 4 MiB. */
+            413: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description The body was not sent as application/json. */
+            415: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description The body is not what a choice takes, or the config with the choice does not validate (the problems name the fields), or the node could not prepare it. Nothing was changed. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description The node already serves as many connections, or as many event streams, as it takes at once. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+        };
+    };
     confirmUpstream: {
         parameters: {
             query?: never;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@veilway/sdk",
-	"version": "0.3.5-alpha",
+	"version": "0.3.7-alpha",
 	"description": "Typed client for the Veilway control API",
 	"license": "Apache-2.0",
 	"repository": {