moeralib 0.15.2 → 0.15.4

package/lib/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/naming/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.shorten = exports.resolve = exports.expand = exports.parseNodeName = exports.DEV_NAMING_SERVER = exports.MAIN_NAMING_SERVER = exports.MoeraNamingConnectionError = exports.MoeraNamingApiError = exports.MoeraNamingError = exports.MoeraNaming = void 0;
+exports.validateNamingSchema = exports.shorten = exports.resolve = exports.expand = exports.parseNodeName = exports.DEV_NAMING_SERVER = exports.MAIN_NAMING_SERVER = exports.MoeraNamingConnectionError = exports.MoeraNamingApiError = exports.MoeraNamingError = exports.MoeraNaming = void 0;
 var naming_1 = require("./naming");
 Object.defineProperty(exports, "MoeraNaming", { enumerable: true, get: function () { return naming_1.MoeraNaming; } });
 Object.defineProperty(exports, "MoeraNamingError", { enumerable: true, get: function () { return naming_1.MoeraNamingError; } });
@@ -12,3 +12,5 @@ Object.defineProperty(exports, "parseNodeName", { enumerable: true, get: functio
 Object.defineProperty(exports, "expand", { enumerable: true, get: function () { return naming_1.expand; } });
 Object.defineProperty(exports, "resolve", { enumerable: true, get: function () { return naming_1.resolve; } });
 Object.defineProperty(exports, "shorten", { enumerable: true, get: function () { return naming_1.shorten; } });
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "validateNamingSchema", { enumerable: true, get: function () { return validate_1.validateSchema; } });

package/lib/naming/naming.js

@@ -13,28 +13,60 @@ exports.resolve = exports.expand = exports.shorten = exports.parseNodeName = exp
 const json_rpc_2_0_1 = require("json-rpc-2.0");
 const schema_1 = require("../schema");
 const validate_1 = require("./validate");
+/**
+ * Main Moera naming server.
+ */
 exports.MAIN_NAMING_SERVER = "https://naming.moera.org/moera-naming";
+/**
+ * Moera developers' naming server.
+ */
 exports.DEV_NAMING_SERVER = "https://naming-dev.moera.org/moera-naming";
+/**
+ * Generic naming server error.
+ */
 class MoeraNamingError extends Error {
+    /**
+     * @param {string} method - API method name
+     * @param {string} message - error message
+     */
     constructor(method, message) {
         super(method + ": Naming server error: " + message);
     }
 }
 exports.MoeraNamingError = MoeraNamingError;
+/**
+ * Naming server returned an error response.
+ */
 class MoeraNamingApiError extends MoeraNamingError {
+    /**
+     * @param {string} method - API method name
+     * @param {ErrorResult} result - server response
+     */
     constructor(method, result) {
         super(method, result.error.message);
         this.errorCode = result.error.code;
     }
 }
 exports.MoeraNamingApiError = MoeraNamingApiError;
+/**
+ * Naming server connection error.
+ */
 class MoeraNamingConnectionError extends Error {
+    /**
+     * @param {string} message - error message
+     */
     constructor(message) {
         super("Naming server connection error: " + message);
     }
 }
 exports.MoeraNamingConnectionError = MoeraNamingConnectionError;
+/**
+ * Naming API interface.
+ */
 class MoeraNaming {
+    /**
+     * @param {string} server - the naming server URL
+     */
     constructor(server = exports.MAIN_NAMING_SERVER) {
         this.rpcClient = new json_rpc_2_0_1.JSONRPCClient((request_1, _a) => __awaiter(this, [request_1, _a], void 0, function* (request, [method, schema]) {
             let response;
@@ -107,46 +139,125 @@ class MoeraNaming {
             this.rpcClient.receive(data);
         }));
     }
+    /**
+     * Register or update the name. See Architecture Overview for the `detailed description
+     * {@link https://moera.org/overview/naming.html} of the algorithm.
+     *
+     * @param {string} name - the name to be registered/updated
+     * @param {number} generation - the name generation to be registered/updated
+     * @param {string | null} updatingKey - the public key for verifying signatures of further updates of the name. May
+     *     be ``null`` if the current generation of the name is updated – the current key is preserved in this case.
+     * @param {string | null} nodeUri - URI of the REST API endpoint of the node to which the name is assigned. May be
+     *     ``null`` - the current URI is preserved in this case.
+     * @param {string | null} signingKey - the public key of the name owner. May be ``null`` – the current key is
+     *     preserved in this case.
+     * @param {number | null} validFrom - the moment in time the owner's key is valid from. May be ``null`` if
+     *     ``signingKey`` is also ``null``.
+     * @param {string | null} previousDigest - the unique identifier as reported by a naming server of the current state
+     *     of the name. Used to detect the situations when the name was changed by someone else between sending
+     *     the request and processing it. May be ``null`` if the name was never registered before.
+     * @param {string | null} signature - the signature, if required, ``null`` otherwise
+     * @return {Promise<string>} identifier of the operation that was created
+    */
     put(name_1, generation_1) {
         return __awaiter(this, arguments, void 0, function* (name, generation, updatingKey = null, nodeUri = null, signingKey = null, validFrom = null, previousDigest = null, signature = null) {
             return yield this.rpcClient.request("put", { name, generation, updatingKey, nodeUri, signingKey, validFrom, previousDigest, signature }, ["put", "string"]);
         });
     }
+    /**
+     * Get the current status of the operation.
+     *
+     * @param {string} operationId
+     * @return {Promise<OperationStatusInfo |null>} the operation status or ``null``, if the operation ID is unknown
+     */
     getStatus(operationId) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield this.rpcClient.request("getStatus", { operationId }, ["getStatus", "OperationStatusInfo"]);
         });
     }
+    /**
+     * Get current information about the given generation of the name.
+     *
+     * @param {string} name
+     * @param {number} generation
+     * @return {Promise<RegisteredNameInfo>} the information or ``null``, if the name/generation is not found
+     */
     getCurrent(name, generation) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield this.rpcClient.request("getCurrent", { name, generation }, ["getCurrent", "RegisteredNameInfo"]);
         });
     }
+    /**
+     * Get past information about the given generation of the name.
+     *
+     * @param {string} name
+     * @param {number} generation
+     * @param {number} at - the moment in time the information is related to
+     * @return {Promise<RegisteredNameInfo | null>} the information or ``null``, if the name/generation did not exist at
+     *     the given moment
+     */
     getPast(name, generation, at) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield this.rpcClient.request("getPast", { name, generation, at }, ["getPast", "RegisteredNameInfo"]);
         });
     }
+    /**
+     * Check if the given name is available for registration.
+     *
+     * @param {string} name
+     * @param {number} generation
+     * @return {Promise<boolean>} ``true``, if the name is free, ``false`` otherwise
+     */
     isFree(name, generation) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield this.rpcClient.request("isFree", { name, generation }, ["isFree", "boolean"]);
         });
     }
+    /**
+     * Find a name that is close to the given name.
+     *
+     * @param {string} name
+     * @return {Promise<RegisteredNameInfo | null>} information about the name or ``null``, if no name found that is
+     *     close enough
+     */
     getSimilar(name) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield this.rpcClient.request("getSimilar", { name }, ["getSimilar", "RegisteredNameInfo"]);
         });
     }
+    /**
+     * Get the whole history of signing keys for the given name.
+     *
+     * @param {string} name
+     * @param {number} generation
+     * @return {Promise<SigningKeyInfo[]>} the keys
+     */
     getAllKeys(name, generation) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield this.rpcClient.request("getAllKeys", { name, generation }, ["getAllKeys", "SigningKeyInfoArray"]);
         });
     }
+    /**
+     * Get the list of all registered names at the given moment. The list is returned in pages, one per call.
+     *
+     * @param {number} at - the moment in time the information is related to
+     * @param {number} page - number of the page to be returned (starting from 0)
+     * @param {number} size - size of the page
+     * @return {Promise<RegisteredNameInfo[]>}
+     */
     getAll(at, page, size) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield this.rpcClient.request("getAll", { at, page, size }, ["getAll", "RegisteredNameInfoArray"]);
         });
     }
+    /**
+     * Get the list of all names registered after the given moment. The list is returned in pages, one per call.
+     *
+     * @param {number} at - the moment in time the information is related to
+     * @param {number} page - number of the page to be returned (starting from 0)
+     * @param {number} size - size of the page
+     * @return {Promise<RegisteredNameInfo[]>}
+     */
     getAllNewer(at, page, size) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield this.rpcClient.request("getAllNewer", { at, page, size }, ["getAllNewer", "RegisteredNameInfoArray"]);
@@ -154,6 +265,15 @@ class MoeraNaming {
     }
 }
 exports.MoeraNaming = MoeraNaming;
+/**
+ * Parse a node name and return its name and generation parts.
+ *
+ * If the node name does not include a generation, generation 0 is returned. If name syntax is invalid, ``Error``
+ * is thrown.
+ *
+ * @param {string} nodeName - the node name to be parsed
+ * @return {[string, number]} [name, generation]
+ */
 function parseNodeName(nodeName) {
     let name = nodeName;
     let generation = 0;
@@ -192,6 +312,13 @@ function expand(nodeName) {
     return `${name}_${gen}`;
 }
 exports.expand = expand;
+/**
+ * Shortcut function to resolve a node name and get the node URI.
+ *
+ * @param name {string} - the node name
+ * @param namingServer {string} - a naming server to be used
+ * @return {Promise<string | null>} the node URI, or ``null`` if the name does not exist
+ */
 function resolve(name_1) {
     return __awaiter(this, arguments, void 0, function* (name, namingServer = exports.MAIN_NAMING_SERVER) {
         var _a, _b;

package/lib/node/caller.js

@@ -12,36 +12,62 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Caller = exports.moeraRoot = exports.MoeraCallError = exports.MoeraNodeConnectionError = exports.MoeraNodeApiError = exports.MoeraNodeError = void 0;
+exports.Caller = exports.moeraRoot = exports.MoeraNodeCallError = exports.MoeraNodeConnectionError = exports.MoeraNodeApiError = exports.MoeraNodeError = void 0;
 const lodash_clonedeep_1 = __importDefault(require("lodash.clonedeep"));
 const validate_1 = require("./validate");
 const util_1 = require("../util");
 const schema_1 = require("../schema");
+/**
+ * Generic node error.
+ */
 class MoeraNodeError extends Error {
+    /**
+     * @param {string} name - request name
+     * @param {string} message - error message
+     */
     constructor(name, message) {
         super(name + ": Node error: " + message);
     }
 }
 exports.MoeraNodeError = MoeraNodeError;
+/**
+ * Node returned an error response.
+ */
 class MoeraNodeApiError extends MoeraNodeError {
+    /**
+     * @param {string} name - request name
+     * @param {Result} result - node response
+     */
     constructor(name, result) {
         super(name, result.message);
         this.errorCode = result.errorCode;
     }
 }
 exports.MoeraNodeApiError = MoeraNodeApiError;
+/**
+ * Error while connecting the node.
+ */
 class MoeraNodeConnectionError extends Error {
+    /**
+     * @param {string} message - error message
+     */
     constructor(message) {
         super("Node connection error: " + message);
     }
 }
 exports.MoeraNodeConnectionError = MoeraNodeConnectionError;
-class MoeraCallError extends Error {
+/**
+ * Missing context of the call (authentication parameters or node URL).
+ */
+class MoeraNodeCallError extends Error {
+    /**
+     * @param {string} message - error message
+     */
     constructor(message) {
         super(message);
     }
 }
-exports.MoeraCallError = MoeraCallError;
+exports.MoeraNodeCallError = MoeraNodeCallError;
 function encodeBody(decoded, format) {
     var _a;
     if (decoded == null) {
@@ -116,6 +142,12 @@ function decodeBodies(name, data) {
     }
     return decoded;
 }
+/**
+ * Convert partial node URL to a standardized form.
+ *
+ * @param {string} url - partial URL
+ * @return {string} standard URL
+ */
 function moeraRoot(url) {
     if (!url.startsWith("http:") && !url.startsWith("https:")) {
         url = "https://" + url;
@@ -134,6 +166,9 @@ function moeraRoot(url) {
 exports.moeraRoot = moeraRoot;
 class Caller {
     constructor() {
+        /**
+         * API endpoint URL of the node.
+         */
         this.root = null;
         this._rootSecret = null;
         this._token = null;
@@ -141,36 +176,93 @@ class Caller {
         this._carteSource = null;
         this._authMethod = "none";
     }
+    /**
+     * Set node URL.
+     *
+     * @param {string} url
+     */
     nodeUrl(url) {
         this.root = moeraRoot(url);
     }
+    /**
+     * Set root secret for authentication.
+     *
+     * @param {string} secret
+     */
     rootSecret(secret) {
         this._rootSecret = secret;
     }
+    /**
+     * Set admin token for authentication.
+     *
+     * @param {string} token
+     */
     token(token) {
         this._token = token;
     }
+    /**
+     * Set carte for authentication.
+     *
+     * @param {string} carte
+     */
     carte(carte) {
         this._carte = carte;
     }
+    /**
+     * Set a source of cartes for authentication.
+     * @param {CarteSource} carteSource
+     */
     carteSource(carteSource) {
         this._carteSource = carteSource;
     }
+    /**
+     * Select authentication method for the following requests.
+     *
+     * @param {NodeAuth} authMethod
+     */
     authMethod(authMethod) {
         this._authMethod = authMethod;
     }
+    /**
+     * Switch off authentication for the following requests.
+     */
     noAuth() {
         this.authMethod("none");
     }
+    /**
+     * Select carte authentication for the following requests.
+     */
     auth() {
         this.authMethod("peer");
     }
+    /**
+     * Select admin token authentication for the following requests.
+     */
     authAdmin() {
         this.authMethod("admin");
     }
+    /**
+     * Select root admin secret authentication for the following requests.
+     */
     authRootAdmin() {
         this.authMethod("root-admin");
     }
+    /**
+     * Generic method for making node API requests.
+     *
+     * @param {string} name - request name (for error messages)
+     * @param {string} location - request path
+     * @param {Partial<Record<string, string | number | boolean | null>> | null} params - query parameters, mapping
+     *     name to value, ``null`` values are skipped
+     * @param {string} method - request method (one of 'GET', 'POST', 'PUT', 'DELETE'), the default is 'GET'
+     * @param {Structure | Structure[] | Buffer | null} body - request body
+     * @param {string | null} contentType - content-type of the request body, when it is not a JSON structure
+     * @param {boolean} auth - `true` (default) to authenticate the request, `false` otherwise
+     * @param {string} schema - JSON schema to validate the response
+     * @param {boolean} bodies - `true` to decode `Body` structures in the response, `false` (default) otherwise
+     * @param {boolean} srcBodies - `true` to encode `Body` structures in the request, `false` (default) otherwise
+     * @return {Promise<any>}
+     */
     call(name_1, location_1, _a) {
         return __awaiter(this, arguments, void 0, function* (name, location, { params = null, method = "GET", body = null, contentType = null, auth = true, schema, bodies = false, srcBodies = false }) {
             let bodyEncoded = null;
@@ -195,18 +287,18 @@ class Caller {
                             bearer = "carte:" + this._carte;
                         }
                         else {
-                            throw new MoeraCallError("Carte is not set");
+                            throw new MoeraNodeCallError("Carte is not set");
                         }
                         break;
                     case "admin":
                         if (this._token == null) {
-                            throw new MoeraCallError("Token is not set");
+                            throw new MoeraNodeCallError("Token is not set");
                         }
                         bearer = "token:" + this._token;
                         break;
                     case "root-admin":
                         if (this._rootSecret == null) {
-                            throw new MoeraCallError("Root secret is not set");
+                            throw new MoeraNodeCallError("Root secret is not set");
                         }
                         bearer = "secret:" + this._rootSecret;
                         break;
@@ -216,7 +308,7 @@ class Caller {
                 headers["Authorization"] = `Bearer ${bearer}`;
             }
             if (this.root == null) {
-                throw new MoeraCallError("Node URL is not set");
+                throw new MoeraNodeCallError("Node URL is not set");
             }
             let url = (0, util_1.urlWithParameters)(this.root + "/api" + location, params);
             let response;

package/lib/node/cartes.js

@@ -10,7 +10,13 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MoeraCarteSource = exports.MoeraCartesError = void 0;
+/**
+ * Error obtaining valid cartes.
+ */
 class MoeraCartesError extends Error {
+    /**
+     * @param {string} message - error message
+     */
     constructor(message) {
         super(message);
     }
@@ -19,16 +25,30 @@ exports.MoeraCartesError = MoeraCartesError;
 function isAdminCarte(carte) {
     return carte.permissions == null || carte.permissions.includes("other");
 }
+/**
+ * Class that gets cartes from the given node, caches them and supplies them for authentication.
+ */
 class MoeraCarteSource {
+    /**
+     * @param {MoeraNode} node node to get cartes from
+     */
     constructor(node) {
         this.cartes = [];
         this.node = node;
     }
+    /**
+     * Force renewing the cached list of cartes.
+     */
     renew() {
         return __awaiter(this, void 0, void 0, function* () {
             this.cartes = (yield this.node.getCartes()).cartes;
         });
     }
+    /**
+     * Get a valid carte. Use one of the cached ones, if possible.
+     *
+     * @return {Promise<string>} the carte
+     */
     getCarte() {
         return __awaiter(this, void 0, void 0, function* () {
             for (const renewed of [false, true]) {

package/lib/node/index.js

@@ -1,13 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MoeraCartesError = exports.MoeraCarteSource = exports.moeraRoot = exports.MoeraNodeConnectionError = exports.MoeraNodeApiError = exports.MoeraNodeError = exports.MoeraNode = void 0;
+exports.validateNodeSchema = exports.MoeraCartesError = exports.MoeraCarteSource = exports.moeraRoot = exports.MoeraNodeCallError = exports.MoeraNodeConnectionError = exports.MoeraNodeApiError = exports.MoeraNodeError = exports.MoeraNode = void 0;
 var node_1 = require("./node");
 Object.defineProperty(exports, "MoeraNode", { enumerable: true, get: function () { return node_1.MoeraNode; } });
 var caller_1 = require("./caller");
 Object.defineProperty(exports, "MoeraNodeError", { enumerable: true, get: function () { return caller_1.MoeraNodeError; } });
 Object.defineProperty(exports, "MoeraNodeApiError", { enumerable: true, get: function () { return caller_1.MoeraNodeApiError; } });
 Object.defineProperty(exports, "MoeraNodeConnectionError", { enumerable: true, get: function () { return caller_1.MoeraNodeConnectionError; } });
+Object.defineProperty(exports, "MoeraNodeCallError", { enumerable: true, get: function () { return caller_1.MoeraNodeCallError; } });
 Object.defineProperty(exports, "moeraRoot", { enumerable: true, get: function () { return caller_1.moeraRoot; } });
 var cartes_1 = require("./cartes");
 Object.defineProperty(exports, "MoeraCarteSource", { enumerable: true, get: function () { return cartes_1.MoeraCarteSource; } });
 Object.defineProperty(exports, "MoeraCartesError", { enumerable: true, get: function () { return cartes_1.MoeraCartesError; } });
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "validateNodeSchema", { enumerable: true, get: function () { return validate_1.validateSchema; } });