wldx-admin-cli 1.1.0 → 1.2.0

package/src/transfer/plan.mjs

@@ -0,0 +1,153 @@
+// The plan of a config import: every object of the export against the target PBX. new (not there), same, differs
+// (there and different: overwritten only when chosen) or blocked (cannot be written, with the reason), with warnings
+// that do not stop it (a sound or music on hold class missing on the target, a queue member who is not a user there,
+// a value outside the PBX). The target's own objects are made portable the same way, so both sides compare by name.
+import {keyOf, refsOf, splitKey, toPortable} from './refs.mjs';
+
+// JSON with sorted keys and numbers as strings: two objects compare equal whatever the order of their fields.
+const stable = (v) =>
+  v && typeof v === 'object'
+    ? Array.isArray(v)
+      ? `[${v.map(stable).join(',')}]`
+      : `{${Object.keys(v)
+          .sort()
+          .map((k) => `${JSON.stringify(k)}:${stable(v[k])}`)
+          .join(',')}}`
+    : JSON.stringify(typeof v === 'number' ? String(v) : v); // the PBX answers 0 or "0" for the same value
+
+const OUTSIDE_NAMES = {sounds: 'sound', moh: 'music on hold', phonebooks: 'phonebook'};
+
+// portable: the export ({kinds, soft, outside, external, unresolved, bound}); target: readKinds of the target;
+// checks: {serial, host, licenses: {type: free}, sounds, moh, phonebooks} (a list not given is not checked).
+export function makePlan(portable, target, {serial, host, licenses, sounds, moh, phonebooks}) {
+  const targetPortable = toPortable(target, {serial, host});
+  const theirs = new Map();
+  const ids = {};
+  const twice = new Set(); // names that two objects of a kind share on the target: ambiguous
+  for (const [kind, list] of Object.entries(target)) {
+    if (!Array.isArray(list)) continue;
+    for (const o of list) {
+      const key = keyOf(kind, o.name);
+      if (Object.hasOwn(ids, key)) twice.add(key);
+      ids[key] = {
+        id: o.id,
+        ...(o.dn ? {dn: o.dn} : {}),
+        name: o.name,
+        ...(kind === 'trunks-sip' && typeof o.data?.name === 'string' ? {login: o.data.name} : {}),
+      };
+    }
+  }
+  for (const [kind, list] of Object.entries(targetPortable.kinds))
+    for (const o of list) theirs.set(keyOf(kind, o.name), o.data);
+
+  const items = [];
+  const bound = new Set((portable.bound ?? []).map((b) => keyOf(b.kind, b.name)));
+  for (const [kind, list] of Object.entries(portable.kinds)) {
+    const counts = new Map();
+    for (const o of list) counts.set(o.name, (counts.get(o.name) ?? 0) + 1);
+    for (const o of list) {
+      const key = keyOf(kind, o.name);
+      const it = {
+        key,
+        kind,
+        name: o.name,
+        data: o.data,
+        warnings: [],
+        needs: [...new Set(refsOf(o.data).map((r) => keyOf(r.kind, r.name)))].filter((k) => k !== key),
+      };
+      if (twice.has(key)) Object.assign(it, {state: 'blocked', reason: `two objects named ${o.name} on ${host}`});
+      else if (counts.get(o.name) > 1)
+        Object.assign(it, {state: 'blocked', reason: `two objects named ${o.name} in the export`});
+      else if (bound.has(key)) Object.assign(it, {state: 'blocked', reason: 'bound to the source PBX'});
+      else if (target[kind] && !Array.isArray(target[kind]))
+        Object.assign(it, {state: 'blocked', reason: `${kind} cannot be read on ${host}: ${target[kind].error}`});
+      else if (!theirs.has(key)) it.state = 'new';
+      else if (kind === 'users' && theirs.get(key).name !== o.data.name)
+        Object.assign(it, {state: 'blocked', reason: `extension ${o.name} is ${theirs.get(key).name} on ${host}`});
+      else it.state = stable(theirs.get(key)) === stable(o.data) ? 'same' : 'differs';
+      items.push(it);
+    }
+  }
+
+  // New users take a license of their type each; beyond the free ones they cannot be made.
+  if (licenses) {
+    const free = {...licenses};
+    for (const it of items.filter((i) => i.kind === 'users' && i.state === 'new')) {
+      const type = it.data.licenseType;
+      if (!type) continue;
+      if ((free[type] ?? 0) <= 0) Object.assign(it, {state: 'blocked', reason: `no free ${type} license on ${host}`});
+      else free[type] -= 1;
+    }
+  }
+
+  // A reference must be in the export (and writable) or on the target; repeated until nothing changes, so a block
+  // travels up the chain.
+  const byKey = new Map(items.map((i) => [i.key, i]));
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const it of items) {
+      if (it.state === 'blocked') continue;
+      for (const need of it.needs) {
+        const mine = byKey.get(need);
+        // on the target already, or in the export and writable
+        if (Object.hasOwn(ids, need) || (mine && mine.state !== 'blocked')) continue;
+        const why = mine ? `${need} is blocked: ${mine.reason}` : `neither in the export nor on ${host}`;
+        Object.assign(it, {state: 'blocked', reason: `needs ${need}: ${why}`});
+        changed = true;
+        break;
+      }
+    }
+  }
+
+  // Warnings, {type, value, path?, text}: values outside the transfer missing on the target (sound, moh, phonebook;
+  // not-checked when the target's list was not read), queue members who are not users there (member), values outside
+  // the PBX (external), references to nothing on the source (unresolved).
+  const has = {sounds, moh, phonebooks};
+  const TYPE = {sounds: 'sound', moh: 'moh', phonebooks: 'phonebook'};
+  const warn = (key, w) => byKey.get(key)?.warnings.push(w);
+  for (const x of portable.outside ?? []) {
+    const list = has[x.kind];
+    const w = {type: TYPE[x.kind], value: x.value, path: x.path};
+    if (!list)
+      warn(x.from, {
+        ...w,
+        type: 'not-checked',
+        text: `${OUTSIDE_NAMES[x.kind]} ${x.value} (${x.path}) was not checked on ${host}`,
+      });
+    else if (!list.map(String).includes(String(x.value)))
+      warn(x.from, {...w, text: `${OUTSIDE_NAMES[x.kind]} ${x.value} is not on ${host} (${x.path})`});
+  }
+  for (const [from, keys] of Object.entries(portable.soft ?? {})) {
+    for (const k of keys) {
+      const mine = byKey.get(k);
+      if (Object.hasOwn(ids, k) || (mine && mine.state !== 'blocked')) continue;
+      const value = splitKey(k).name;
+      if (!Array.isArray(target.users))
+        warn(from, {
+          type: 'not-checked',
+          value,
+          text: `the user ${value} was not checked on ${host} (its users were not read)`,
+        });
+      else warn(from, {type: 'member', value, text: `${value} is not a user on ${host} (nor a user of the export)`});
+    }
+  }
+  for (const x of portable.external ?? [])
+    warn(keyOf(x.kind, x.name), {
+      type: 'external',
+      value: x.what,
+      path: x.path,
+      text: `${x.path} is outside the PBX (${x.what}), kept as it is: check it works for ${host}`,
+    });
+  for (const x of portable.unresolved ?? [])
+    warn(keyOf(x.kind, x.name), {
+      type: 'unresolved',
+      value: x.value,
+      path: x.path,
+      text: `${x.path} = ${x.value} pointed at nothing on the source, kept as it is`,
+    });
+
+  const counts = {new: 0, same: 0, differs: 0, blocked: 0};
+  for (const it of items) counts[it.state] += 1;
+  const welcomeMails = items.filter((i) => i.kind === 'users' && i.state === 'new' && i.data.email).length;
+  return {host, items, counts, welcomeMails, target: ids};
+}

package/src/transfer/refs.mjs

@@ -0,0 +1,251 @@
+// References of a config transfer. toPortable() turns every value that points outside its object (an id, a name or
+// an LDAP dn of another object, the PBX itself, a secret, an object outside the PBX) into a marker, so the objects
+// mean the same on any PBX; fromPortable() turns the markers back into the values of the target PBX. A last scan
+// marks an object `bound` when the serial or the host of the source PBX is still in one of its strings.
+//
+//   {"$ref": "<kind>/<name>", "as": "id"|"name"|"dn"|"login", "number"?: true}   another object
+//   {"$self": "pbx"}                                                            the PBX (pbxid=<serial>,dc=wildix)
+//   {"$secret": "<path>"}                                                       a secret, never exported
+//   {"$external": "<what>", "value": …}                                         outside the PBX, kept as it is
+
+// The parameters of dialplan applications that point at objects, found live on WMS 7.11 (an empty rule per
+// application: the PBX names what it requires). `by` is the form the PBX uses first.
+const ID = 'id';
+const NAME = 'name';
+export const APP_REFS = {
+  Queue: {queueId: ['queues', ID], mohClass: ['moh']},
+  Timetable: {timetableId: ['timetables', ID], dialplan: ['dialplans', NAME]},
+  IVR: {ivrName: ['ivr', NAME]},
+  GotoIfSwitchIsOn: {switchId: ['switches', ID], dialplan: ['dialplans', NAME]},
+  GotoIf3SwitchIsOnOrBlinking: {
+    switchId: ['switches', ID],
+    dialplanOn: ['dialplans', NAME],
+    dialplanBlinking: ['dialplans', NAME],
+  },
+  FeaturePaging: {groupId: ['paging', ID]},
+  DialTrunk: {trunk: ['trunks-sip', NAME]},
+  DialHuntGroup: {huntGroup: ['trunk-groups', NAME]},
+  GotoIfUserStatus: {user: ['users', NAME, 'soft'], dialplan: ['dialplans', NAME]},
+  Goto: {dialplan: ['dialplans', NAME]},
+  GotoIf: {dialplan: ['dialplans', NAME]},
+  GotoIfBusyCongested: {dialplan: ['dialplans', NAME]},
+  VerifyCaller: {dialplan: ['dialplans', NAME]},
+  CorrectOutgoingNumber: {dialplan: ['dialplans', NAME]},
+  GotoIfGroupCount: {dialplan: ['dialplans', NAME]},
+  DialRemotePbx: {dialplan: ['dialplans', NAME]},
+  LookUpCidNameInPhonebook: {phonebookId: ['phonebooks']},
+  LookUpDestCidNameInPhonebook: {phonebookId: ['phonebooks']},
+  Playback: {filename: ['sounds']},
+};
+// Kinds a transfer does not carry: their values stay, and the plan checks the target has them.
+const OUTSIDE = new Set(['moh', 'sounds', 'phonebooks']);
+export const EXTERNAL = {VoiceBot: {botId: 'voicebot'}, DialRemotePbx: {pbx: 'remote-pbx'}};
+
+// Secret fields of a trunk ("key" alone is not one: it names a codec).
+const SECRET_KEY = /secret|password|passwd|^register$|apikey|token/i;
+const PBXID = /^pbxid=([^,]+),dc=wildix$/i;
+
+// Values that mean the same on every PBX: nothing, "all", a dialplan expression, a built-in (negative) id.
+const literal = (v) =>
+  v === undefined || v === null || v === '' || v === 'all' || /\$\{/.test(String(v)) || /^-\d+$/.test(String(v));
+
+export const keyOf = (kind, name) => `${kind}/${name}`;
+export function splitKey(key) {
+  const at = key.indexOf('/');
+  return {kind: key.slice(0, at), name: key.slice(at + 1)};
+}
+
+const isMarker = (v) =>
+  v &&
+  typeof v === 'object' &&
+  !Array.isArray(v) &&
+  ('$ref' in v || '$self' in v || '$secret' in v || '$external' in v);
+
+// Lookup tables of the objects of a snapshot, per kind: by id, dn, name and (trunks) login.
+function indexOf(snapshot) {
+  const idx = {};
+  for (const [kind, objects] of Object.entries(snapshot)) {
+    if (!Array.isArray(objects)) continue;
+    const t = {id: new Map(), dn: new Map(), name: new Map(), login: new Map()};
+    for (const o of objects) {
+      t.id.set(String(o.id), o.name);
+      if (o.dn) t.dn.set(String(o.dn).toLowerCase(), o.name);
+      t.name.set(String(o.name), o.name);
+      if (kind === 'trunks-sip' && o.data?.name) t.login.set(String(o.data.name), o.name);
+    }
+    idx[kind] = t;
+  }
+  return idx;
+}
+
+export function toPortable(snapshot, {serial, host}) {
+  const idx = indexOf(snapshot);
+  const out = {kinds: {}, errors: {}, needs: {}, soft: {}, bound: [], external: [], unresolved: [], outside: []};
+
+  for (const [kind, objects] of Object.entries(snapshot)) {
+    if (!Array.isArray(objects)) {
+      out.errors[kind] = objects?.error ?? 'not read';
+      continue;
+    }
+    out.kinds[kind] = objects.map((o) => {
+      const key = keyOf(kind, o.name);
+      const needs = new Set();
+      const soft = new Set();
+      const at = {kind, name: o.name};
+
+      // A value pointing at an object of `target`: a marker, or the value kept and noted.
+      const ref = (value, target, path, order = [ID, 'dn', NAME, 'login'], how) => {
+        if (literal(value)) return value;
+        // A soft reference (a user by extension) stays as it is: an extension means the same on any PBX.
+        if (how === 'soft') {
+          soft.add(keyOf(target, String(value)));
+          return value;
+        }
+        if (OUTSIDE.has(target)) {
+          out.outside.push({...at, path, kind: target, value: String(value), from: key});
+          return value;
+        }
+        const t = idx[target];
+        const s = String(value);
+        for (const as of order) {
+          const name = t?.[as]?.get(as === 'dn' ? s.toLowerCase() : s);
+          if (name === undefined) continue;
+          needs.add(keyOf(target, name));
+          return {$ref: keyOf(target, name), as, ...(typeof value === 'number' ? {number: true} : {})};
+        }
+        out.unresolved.push({...at, path, value: s});
+        return value;
+      };
+      const pathOf = (base, k) => (base ? `${base}.${k}` : k);
+      const data = structuredClone(o.data);
+
+      if (kind === 'dialplans') {
+        data.includedDialplans = (data.includedDialplans ?? []).map((x, i) => ({
+          ...x,
+          dialplanId: ref(x.dialplanId, 'dialplans', `includedDialplans[${i}].dialplanId`, [ID, NAME]),
+        }));
+        for (const [n, num] of (data.numbers ?? []).entries()) {
+          for (const [a, application] of (num.apps ?? []).entries()) {
+            const params = application.params;
+            if (!params || Array.isArray(params)) continue;
+            const base = `numbers[${n}].apps[${a}].params`;
+            for (const [p, [target, by, how]] of Object.entries(APP_REFS[application.name] ?? {})) {
+              if (!(p in params)) continue;
+              params[p] = ref(params[p], target, pathOf(base, p), by === ID ? [ID, NAME] : [NAME, ID, 'login'], how);
+            }
+            for (const [p, what] of Object.entries(EXTERNAL[application.name] ?? {})) {
+              if (literal(params[p])) continue;
+              out.external.push({...at, path: pathOf(base, p), what});
+              params[p] = {$external: what, value: params[p]};
+            }
+          }
+        }
+      }
+      if (kind === 'acl-groups') {
+        if (data.inherits?.dn)
+          data.inherits = {...data.inherits, dn: ref(data.inherits.dn, 'acl-groups', 'inherits.dn', ['dn'])};
+        data.rules = (data.rules ?? []).map((r, i) => ({
+          ...r,
+          group: ref(r.group, 'acl-groups', `rules[${i}].group`, ['dn']),
+        }));
+        // An admin rule about this PBX is about the target; one about another PBX (or when the serial is not known)
+        // stays as it is and is reported: giving a group admin rights on the target it did not have is not a guess.
+        data.adminRules = (data.adminRules ?? []).map((r, i) => {
+          const m = PBXID.exec(String(r.subject ?? ''));
+          if (!m) return r;
+          if (serial && m[1].toLowerCase() === String(serial).toLowerCase()) return {...r, subject: {$self: 'pbx'}};
+          out.unresolved.push({...at, path: `adminRules[${i}].subject`, value: String(r.subject)});
+          return r;
+        });
+      }
+      if (kind === 'users') {
+        if ('groupDn' in data) data.groupDn = ref(data.groupDn, 'acl-groups', 'groupDn', ['dn']);
+        for (const f of ['dialplan', 'faxDialplan']) if (f in data) data[f] = ref(data[f], 'dialplans', f, [NAME]);
+      }
+      if (kind === 'queues') {
+        if (data.settings && 'aclGroup' in data.settings)
+          data.settings.aclGroup = ref(data.settings.aclGroup, 'acl-groups', 'settings.aclGroup', ['dn', ID, NAME]);
+        for (const m of data.members ?? []) soft.add(keyOf('users', String(m).split(/[@,]/)[0]));
+      }
+      if (kind === 'trunk-groups') {
+        data.rules = (data.rules ?? []).map((r, i) => ({
+          ...r,
+          trunkName: ref(r.trunkName, 'trunks-sip', `rules[${i}].trunkName`, [NAME, 'login', ID]),
+        }));
+      }
+      if (kind === 'trunks-sip') {
+        if (data.settingsPbx && 'context' in data.settingsPbx)
+          data.settingsPbx.context = ref(data.settingsPbx.context, 'dialplans', 'settingsPbx.context', [NAME]);
+        hideSecrets(data, '');
+      }
+
+      out.needs[key] = [...needs].filter((k) => k !== key);
+      out.soft[key] = [...soft];
+      if (!out.soft[key].length) delete out.soft[key];
+      if (!out.needs[key].length) delete out.needs[key];
+      scan(data, '', (path, found) => out.bound.push({...at, path, found}), {serial, host});
+      return {name: o.name, data};
+    });
+  }
+  return out;
+}
+
+// Every non-empty secret of an object becomes {$secret: <its path>}.
+function hideSecrets(o, base) {
+  for (const [k, v] of Object.entries(o)) {
+    const path = Array.isArray(o) ? `${base}[${k}]` : base ? `${base}.${k}` : k;
+    if (SECRET_KEY.test(k) && typeof v === 'string' && v !== '') o[k] = {$secret: path};
+    else if (v && typeof v === 'object' && !isMarker(v)) hideSecrets(v, path);
+  }
+}
+
+// The safety scan: strings (outside markers) that still hold the source serial or host.
+function scan(v, path, hit, {serial, host}) {
+  if (typeof v === 'string') {
+    const s = v.toLowerCase();
+    if (serial && s.includes(String(serial).toLowerCase())) hit(path, 'serial');
+    else if (host && s.includes(String(host).toLowerCase())) hit(path, 'host');
+    return;
+  }
+  if (!v || typeof v !== 'object' || isMarker(v)) return;
+  for (const [k, x] of Array.isArray(v) ? v.entries() : Object.entries(v))
+    scan(x, Array.isArray(v) ? `${path}[${k}]` : path ? `${path}.${k}` : k, hit, {serial, host});
+}
+
+// Every $ref of an object, with where it is.
+export function refsOf(data, path = '', out = []) {
+  if (!data || typeof data !== 'object') return out;
+  if (!Array.isArray(data) && typeof data.$ref === 'string') {
+    out.push({...splitKey(data.$ref), path});
+    return out;
+  }
+  for (const [k, v] of Array.isArray(data) ? data.entries() : Object.entries(data))
+    refsOf(v, Array.isArray(data) ? `${path}[${k}]` : path ? `${path}.${k}` : k, out);
+  return out;
+}
+
+export class MissingValue extends Error {}
+
+// The markers of an object replaced by the values of the target: resolve({kind, name, as}) for a $ref,
+// resolve.self() for the PBX, resolve.secret(path) for a secret. A $ref or secret without a value throws MissingValue.
+export function fromPortable(kind, data, resolve) {
+  const walk = (v) => {
+    if (!v || typeof v !== 'object') return v;
+    if (Array.isArray(v)) return v.map(walk);
+    if (typeof v.$ref === 'string') {
+      const {kind: k, name} = splitKey(v.$ref);
+      const value = resolve({kind: k, name, as: v.as});
+      if (value === undefined) throw new MissingValue(`${kind}: ${v.$ref} is not on the target`);
+      return v.number ? Number(value) : value;
+    }
+    if ('$self' in v) return resolve.self();
+    if ('$secret' in v) {
+      const value = resolve.secret(v.$secret);
+      if (value === undefined) throw new MissingValue(`${kind}: the secret ${v.$secret} was not given`);
+      return value;
+    }
+    if ('$external' in v) return v.value;
+    return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)]));
+  };
+  return walk(data);
+}