@sap/cds-dk 4.4.2 → 4.5.0

package/lib/client/params.js

@@ -0,0 +1,435 @@
+const Logger = require('./helper/logging');
+const { escapeRegex } = require('./helper/string_helper');
+
+
+// PARAM BASE TYPES
+
+const TokenStorage = Object.freeze({
+    plain: 0,
+    keyring: 1
+});
+
+const Persistence = Object.freeze({
+    none: 0,
+    setting: 1,
+    auth: 2
+});
+
+const ObfuscationLevel = Object.freeze({
+    none: 0,    // Keep this at zero always!
+    full: 1,
+    partial: 2  // Allows a few start and end characters displayed in DEBUG output; only use with string-type params
+});
+const DISCLOSURE_LENGTH = 3;
+
+/**
+ * Parameters hold a name and a value and can only be set to compatible values.
+ */
+class Param {
+    /**
+     * Constructor.
+     * @param name the name
+     * @param val the initial value
+     * @param options constructor options
+     */
+    constructor(name,
+                val,
+                options = {}) {
+
+        this.persist = Persistence.none;
+        this.obfuscate = ObfuscationLevel.none;
+        this.abbreviate = false;
+        this.internal = false;
+        this.allowedValues = null;
+
+        this.name = name;
+        this._val = val;
+        this.options = options;
+        Object.entries(options).forEach(([key, val]) => this[key] = val);
+    }
+
+    /**
+     * Get the name of the main param (as opposed to an alias).
+     */
+    get mainName() {
+        return this.name;
+    }
+
+    /**
+     * Using Proxy to achieve aliasing by routing all but certain properties through to main param.
+     * @param name the alias name
+     */
+    newAlias(name) {
+        return new Proxy(this, {
+            get(param, prop, alias) {
+                switch (prop) {
+                    case 'clone':
+                        return (val) => (val ? param.clone(val) : param).newAlias(alias.name);
+                    case 'name':
+                        return name;
+                    default:
+                        return param[prop];
+                }
+            }
+        });
+    }
+
+    /**
+     * Set value.
+     * @param newVal the new value
+     */
+    set val(newVal) {
+        this.validate(newVal);
+        this._val = newVal;
+    }
+
+    /**
+     * Get value.
+     */
+    get val() {
+        return this._val;
+    }
+
+    /**
+     * Validate the param value.
+     * @param val the value in question
+     * @private
+     */
+    validate(val) {
+        if (val === undefined) {
+            return; // Allow `undefined` always.
+        }
+        let expectedType = typeof this.val;
+        if (expectedType === 'undefined' && this.allowedValues) {
+            expectedType = typeof this.allowedValues[0];
+        }
+        if (typeof val !== expectedType) {
+            throw new Error(`Failed to set '${(this.name)}' = ${JSON.stringify(val)}: expected value of type ${expectedType}`);
+        }
+        if (this.allowedValues && !(this.allowedValues).includes(val)) {
+            throw new Error(`Failed to set '${(this.name)}' = ${JSON.stringify(val)}: expected one of ${JSON.stringify(this.allowedValues)}`);
+        }
+    }
+
+    /**
+     * Transform the value to make it suitable for output, i.e. return:
+     * - `undefined` for internal params (making them hidden)
+     * - `'...'` for (parts of) obfuscated or (when debug output is off) abbreviated params
+     * - `this.val` for all others
+     */
+    format() {
+        return this.internal
+            ? undefined
+            : this.obfuscate === ObfuscationLevel.none && (!this.abbreviate || process.env.DEBUG)
+                ? this.val
+                : this.obfuscate === ObfuscationLevel.partial && process.env.DEBUG && typeof this.val === 'string'
+                    ? this.val.substr(0, DISCLOSURE_LENGTH) + '...' + this.val.substr(-DISCLOSURE_LENGTH)
+                    : '...';
+    }
+
+    /**
+     * Return a new instance of this class with the same properties as the current object.
+     * @param val used as value if given
+     */
+    clone(val = this.val) {
+        this.validate(val);
+        return new Param(this.name, val, this.options);
+    }
+
+    /**
+     * Prevent this being changed.
+     */
+    freeze() {
+        Object.freeze(this._val);
+        Object.freeze(this);
+        return this;
+    }
+}
+
+// type ParamType<P> = P extends Param<infer U> ? U : never;
+
+
+// CONCRETE PARAMS
+
+/**
+ * The known params and their default values, restricted to those needed by the app as a whole.
+ */
+class BasicParams {
+    constructor() {
+        // NON-PERSISTED PARAMS
+        // - general
+        this.projectFolder          = new Param('projectFolder',          '');
+        this.directory              = this.projectFolder.newAlias('directory');
+
+        // - auth-related
+        this.passcode               = new Param('passcode',               '', { obfuscate: ObfuscationLevel.partial });
+        this.tokenStorage           = new Param('tokenStorage', undefined, { allowedValues: ['plain', 'keyring'] });
+        this.plain                  = new Param('plain',                  false, { internal: true }); // for backward compatibility - ignored
+        this.renewLogin             = new Param('renewLogin',             false);
+        this.username               = new Param('username',               '');
+        this.password               = new Param('password',               '', { obfuscate: ObfuscationLevel.full });
+        this.clientid               = new Param('clientid',               '');
+        this.clientsecret           = new Param('clientsecret',           '', { obfuscate: ObfuscationLevel.partial });
+
+        // PERSISTED PARAMS (SETTINGS)
+        this.appUrl                 = new Param('appUrl',                 '', { persist: Persistence.setting });
+        this.to                     = this.appUrl.newAlias('to');
+        this.url                    = this.appUrl.newAlias('url');
+        this.subdomain              = new Param('subdomain',              '', { persist: Persistence.setting });
+        this.passcodeUrl            = new Param('passcodeUrl',            '', { persist: Persistence.setting, abbreviate: true });
+        this.passcode_url           = this.passcodeUrl.newAlias('passcode_url');
+        this.tokenUrl               = new Param('tokenUrl',               '', { persist: Persistence.setting, abbreviate: true })
+
+        // PERSISTED AUTH PARAMS
+        this.token                  = new Param('token',                  '', { persist: Persistence.auth, obfuscate: ObfuscationLevel.partial });
+        this.tokenExpirationDate    = new Param('tokenExpirationDate',    Number.MAX_SAFE_INTEGER, { persist: Persistence.auth });
+        this.refreshToken           = new Param('refreshToken',           '', { persist: Persistence.auth, obfuscate: ObfuscationLevel.partial });
+
+        // INTERNAL PARAMS (HIDDEN FROM USER, COMPUTED)
+        this.reqAuth                = new Param('reqAuth',                null, { obfuscate: ObfuscationLevel.full, internal: true });
+        this.clearOtherTokenStorage = new Param('clearOtherTokenStorage', false, { internal: true });
+    }
+}
+
+/**
+ * All known params including those needed for specific commands.
+ */
+class AllParams extends BasicParams {
+    constructor() {
+        super();
+
+        // `extend` PARAMS
+        this.force                  = new Param('force',                  false);
+        this.templates              = new Param('templates',              false);
+
+        // `activate` PARAMS
+        this.undeploy               = new Param('undeploy',               false);
+        this.wsdl                   = new Param('wsdl',                   false);
+
+        // `logout` PARAMS
+        this.deleteSettings         = new Param('deleteSettings',         false);
+        this["delete-settings"]      = this.deleteSettings.newAlias('delete-settings');
+        this.clearInvalid           = new Param('clearInvalid',           false);
+        this["clear-invalid"]        = this.clearInvalid.newAlias('clear-invalid');
+    }
+}
+
+const ParamDefs = Object.freeze(new AllParams());
+
+// PARAM COLLECTIONS
+
+function collect(values, param) {
+    return Object.assign(values, {[param.name]: param.val});
+}
+
+/**
+ * A bundle of params with values. There are no requirements on the number of params contained.
+ */
+class ParamCollection {
+    constructor(paramValues = {}) {
+        this.params = {};
+        this.isFrozen = false;
+
+        for (const [name, val] of Object.entries(paramValues)) {
+            if (val != null) {
+                this.set(name, val);
+            }
+        }
+    }
+
+    /**
+     * Throw error if this is frozen.
+     * @private
+     */
+    checkFrozen() {
+        if (this.isFrozen) {
+            throw new Error('cannot modify read-only parameter collection');
+        }
+    }
+
+    /**
+     * Create a new frozen `ParamCollection`.
+     * @param paramValues the param values to set
+     */
+    static frozen(paramValues = {}) {
+        const paramCollection = new ParamCollection(paramValues);
+        paramCollection.freeze();
+        return paramCollection;
+    }
+
+    /**
+     * Get the name of a main param (as opposed to an alias).
+     * @param name the param in question
+     */
+    static mainName(name) {
+        const paramDef = ParamDefs[name];
+        if (!paramDef) {
+            throw new Error(`Unknown parameter: '${name}'`);
+        }
+        return paramDef.mainName;
+    }
+
+    /**
+     * Whether this includes the given param.
+     * @param name the param in question
+     */
+    has(name) {
+        return name in this.params;
+    }
+
+    /**
+     * Return the value of the given param.
+     * @param name the param in question
+     */
+    get(name) {
+        const param = this.getParam(name);
+        return param && param.val;
+    }
+
+    /**
+     * Return the `Param` object for the given param.
+     * @param name the param in question
+     */
+    getParam(name) {
+        return this.params[name] || ParamDefs[name];
+    }
+
+    /**
+     * Set a value for the given param. Will add the param to this collection unless already included.
+     * @param name the param in question
+     * @param val the value to set
+     */
+    set(name, val) {
+        this.checkFrozen();
+        const mainName = ParamCollection.mainName(name);
+        if (this.has(mainName)) {
+            this.getParam(name).val = val;
+        } else {
+            this.params[mainName] = ParamDefs[mainName].clone(val);
+        }
+        if (mainName !== name) {
+            Logger.debug(`Migrated setting '${name}' to new key '${mainName}'`);
+        }
+    }
+
+    /**
+     * Delete the given param from this collection.
+     * @param name the param in question
+     */
+    delete(name) {
+        this.checkFrozen();
+        delete this.params[name];
+    }
+
+    /**
+     * Prevent this collection and all included params from being changed.
+     */
+    freeze() {
+        this.toArray().forEach(param => param.freeze());
+        this.isFrozen = true;
+        return this;
+    }
+
+    /**
+     * Add all params contained in another collection to this.
+     * @param params the other `ParamCollection`
+     */
+    merge(params) {
+        this.checkFrozen();
+        for (const param of params) {
+            this.set(param.name, param.val);
+        }
+    }
+
+    /**
+     * Iterate through all contained param objects.
+     */
+    *[Symbol.iterator]() {
+        for (const param of Object.values(this.params)) {
+            yield param;
+        }
+    }
+
+    /**
+     * Return a new array from all contained param objects.
+     */
+    toArray() {
+        return Array.from(this);
+    }
+
+    /**
+     * Get the number of contained params.
+     */
+    get size() {
+        return Object.keys(this.params).length;
+    }
+
+    /**
+     * Return a new `ParamCollection` containing clones of all params contained in this collection.
+     */
+    clone() {
+        const clonedParams = this.toArray()
+            .map(param => param.clone())
+            .reduce(collect, {});
+        return new ParamCollection(clonedParams);
+    }
+
+    /**
+     * Return an object mapping each of the contained params' names to its corresponding value.
+     * @param persistence the type of persistence to filter for (omit to disable filtering)
+     */
+    toValueMap(persistence) {
+        return this.toArray()
+            .filter(param => param.persist === persistence || persistence === undefined)
+            .reduce(collect, {});
+    }
+
+    /**
+     * Return an object mapping each of the contained params' names to its corresponding value.
+     * Used by `JSON.stringify`.
+     */
+    toJSON() {
+        return this.toValueMap();
+    }
+
+    /**
+     * Format this as a string. Omits `undefined` values.
+     * @param actualValues whether to include all actual param values, irrespective of any transformations normally
+     * applied (e.g. value obfuscations)
+     */
+    format(actualValues = false) {
+        return this.toArray()
+            .reduce((result, param) => {
+                const val = actualValues ? param.val : param.format();
+                if (val !== undefined) {
+                    result += `${param.name}: ${JSON.stringify(val)}, `;
+                }
+                return result;
+            }, '{ ')
+            .replace(/(,|(?<={)) $/, ' }');
+    }
+
+    /**
+     * Replace all occurrences of values of those params that are to be obfuscated with their (partly) obfuscated versions.
+     * Replacement applies only to values of query parameters.
+     * @param url the URL whose query parameters to replace
+     */
+    obfuscateQueryParams(url) {
+        function reqParam(value) {
+            return new RegExp(`(?<==)${escapeRegex(value)}(?=&|$)`, 'g');
+        }
+        return this.toArray()
+            .filter(param => param.obfuscate)
+            .reduce((result, param) => result.replace(reqParam(param.val), param.format()), url);
+    }
+
+}
+ParamCollection.prototype.toString = ParamCollection.prototype.format;
+
+module.exports = {
+    Param,
+    ParamCollection,
+    Persistence,
+    TokenStorage,
+    ObfuscationLevel
+}