feat(#650): delete-contacts action

src/fn/delete-contacts.js

@@ -0,0 +1,64 @@
+const minimist = require('minimist');
+const path = require('path');
+
+const environment = require('../lib/environment');
+const pouch = require('../lib/db');
+const { info } = require('../lib/log');
+
+const HierarchyOperations = require('../lib/hierarchy-operations');
+
+module.exports = {
+  requiresInstance: true,
+  execute: () => {
+    const args = parseExtraArgs(environment.pathToProject, environment.extraArgs);
+    const db = pouch();
+    const options = {
+      docDirectoryPath: args.docDirectoryPath,
+      force: args.force,
+      disableUsers: args.disableUsers,
+    };
+    return HierarchyOperations(db, options).delete(args.sourceIds);
+  }
+};
+
+// Parses extraArgs and asserts if required parameters are not present
+const parseExtraArgs = (projectDir, extraArgs = []) => {
+  const args = minimist(extraArgs, { boolean: true });
+
+  const sourceIds = (args.ids || args.id || '')
+    .split(',')
+    .filter(id => id);
+
+  if (sourceIds.length === 0) {
+    usage();
+    throw Error('Action "delete-contacts" is missing required list of contacts to be deleted');
+  }
+
+  return {
+    sourceIds,
+    disableUsers: !!args['disable-users'],
+    docDirectoryPath: path.resolve(projectDir, args.docDirectoryPath || 'json_docs'),
+    force: !!args.force,
+  };
+};
+
+const bold = text => `\x1b[1m${text}\x1b[0m`;
+const usage = () => {
+  info(`
+${bold('cht-conf\'s delete-contacts action')}
+When combined with 'upload-docs' this action recursively deletes a contact and all of their descendant contacts and data. ${bold('This operation is permanent. It cannot be undone.')}
+
+${bold('USAGE')}
+cht --local delete-contacts -- --ids=<id1>,<id2>
+
+${bold('OPTIONS')}
+--ids=<id1>,<id2>
+  A comma delimited list of ids of contacts to be deleted.
+
+--disable-users
+  When flag is present, users at any deleted place will be permanently disabled.
+
+--docDirectoryPath=<path to stage docs>
+  Specifies the folder used to store the documents representing the changes in hierarchy.
+`);
+};

src/fn/merge-contacts.js

@@ -13,6 +13,7 @@ module.exports = {
     const args = parseExtraArgs(environment.pathToProject, environment.extraArgs);
     const db = pouch();
     const options = {
+      disableUsers: args.disableUsers,
       docDirectoryPath: args.docDirectoryPath,
       force: args.force,
     };
@@ -41,6 +42,7 @@ const parseExtraArgs = (projectDir, extraArgs = []) => {
   return {
     destinationId: args.destination,
     sourceIds,
+    disableUsers: !!args['disable-users'],
     docDirectoryPath: path.resolve(projectDir, args.docDirectoryPath || 'json_docs'),
     force: !!args.force,
   };
@@ -63,6 +65,9 @@ ${bold('OPTIONS')}
 --sources=<source_id1>,<source_id2>
   A comma delimited list of IDs of contacts which will be deleted. The hierarchy of contacts and reports under it will be moved to be under the destination contact.
 
+--disable-users
+  When flag is present, users at any deleted place will be permanently disabled.
+
 --docDirectoryPath=<path to stage docs>
   Specifies the folder used to store the documents representing the changes in hierarchy.
 `);

src/fn/upload-docs.js

@@ -1,19 +1,22 @@
 const path = require('path');
 const minimist = require('minimist');
-const userPrompt = require('../lib/user-prompt');
+const semver = require('semver');
 
+const api = require('../lib/api');
 const environment = require('../lib/environment');
 const fs = require('../lib/sync-fs');
+const { getValidApiVersion } = require('../lib/get-api-version');
 const log = require('../lib/log');
 const pouch = require('../lib/db');
 const progressBar = require('../lib/progress-bar');
+const userPrompt = require('../lib/user-prompt');
 
 const { info, trace, warn } = log;
 
 const FILE_EXTENSION = '.doc.json';
 const INITIAL_BATCH_SIZE = 100;
 
-const execute = async () => {
+async function execute() {
   const args = minimist(environment.extraArgs || [], { boolean: true });
 
   const docDir = path.resolve(environment.pathToProject, args.docDirectoryPath || 'json_docs');
@@ -22,22 +25,23 @@ const execute = async () => {
     return Promise.resolve();
   }
 
-  const filesToUpload = fs.recurseFiles(docDir).filter(name => name.endsWith(FILE_EXTENSION));
-  const docIdErrors = getErrorsWhereDocIdDiffersFromFilename(filesToUpload);
-  if (docIdErrors.length > 0) {
-    throw new Error(`upload-docs: ${docIdErrors.join('\n')}`);
-  }
-
-  const totalCount = filesToUpload.length;
+  const filenamesToUpload = fs.recurseFiles(docDir).filter(name => name.endsWith(FILE_EXTENSION));
+  const totalCount = filenamesToUpload.length;
   if (totalCount === 0) {
     return; // nothing to upload
   }
 
-  warn(`This operation will permanently write ${totalCount} docs.  Are you sure you want to continue?`);
-  if (!userPrompt.keyInYN()) {
-    throw new Error('User aborted execution.');
+  const analysis = analyseFiles(filenamesToUpload);
+  const errors = analysis.map(result => result.error).filter(Boolean);
+  if (errors.length > 0) {
+    throw new Error(`upload-docs: ${errors.join('\n')}`);
   }
 
+  warnAndPrompt(`This operation will permanently write ${totalCount} docs.  Are you sure you want to continue?`);
+
+  const deletedDocIds = analysis.map(result => result.delete).filter(Boolean);
+  await handleUsersAtDeletedFacilities(deletedDocIds);
+
   const results = { ok:[], failed:{} };
   const progress = log.level > log.LEVEL_ERROR ? progressBar.init(totalCount, '{{n}}/{{N}} docs ', ' {{%}} {{m}}:{{s}}') : null;
   const processNextBatch = async (docFiles, batchSize) => {
@@ -93,20 +97,107 @@ const execute = async () => {
     }
   };
 
-  return processNextBatch(filesToUpload, INITIAL_BATCH_SIZE);
-};
+  return processNextBatch(filenamesToUpload, INITIAL_BATCH_SIZE);
+}
+
+function warnAndPrompt(warningMessage) {
+  warn(warningMessage);
+  if (!userPrompt.keyInYN()) {
+    throw new Error('User aborted execution.');
+  }
+}
 
-const getErrorsWhereDocIdDiffersFromFilename = filePaths =>
-  filePaths
+function analyseFiles(filePaths) {
+  return filePaths
     .map(filePath => {
       const json = fs.readJson(filePath);
       const idFromFilename = path.basename(filePath, FILE_EXTENSION);
 
       if (json._id !== idFromFilename) {
-        return `File '${filePath}' sets _id:'${json._id}' but the file's expected _id is '${idFromFilename}'.`;
+        return { error: `File '${filePath}' sets _id:'${json._id}' but the file's expected _id is '${idFromFilename}'.` };
+      }
+
+      if (json._deleted && json.disableUsers) {
+        return { delete: json._id };
       }
     })
-    .filter(err => err);
+    .filter(Boolean);
+}
+
+async function handleUsersAtDeletedFacilities(deletedDocIds) {
+  await assertCoreVersion();
+
+  const affectedUsers = await getAffectedUsers(deletedDocIds);
+  const usernames = affectedUsers.map(userDoc => userDoc.username).join(', ');
+  if (affectedUsers.length === 0) {
+    trace('No users found needing an update.');
+    return;
+  }
+
+  warnAndPrompt(`This operation will update permissions for ${affectedUsers.length} user accounts: ${usernames}. Are you sure you want to continue?`);
+  await updateAffectedUsers(affectedUsers);
+}
+
+async function assertCoreVersion() {
+  const actualCoreVersion = await getValidApiVersion();
+  if (semver.lt(actualCoreVersion, '4.7.0-dev')) {
+    throw Error(`CHT Core Version 4.7.0 or newer is required to use --disable-users options. Version is ${actualCoreVersion}.`);
+  }
+
+  trace(`Core version is ${actualCoreVersion}. Proceeding to disable users.`);
+}
+
+async function getAffectedUsers(deletedDocIds) {
+  const toPostApiFormat = (apiResponse) => {
+    const places = Array.isArray(apiResponse.place) ? apiResponse.place.filter(Boolean) : [apiResponse.place];
+    const placeIds = places.map(place => place?._id);
+    return {
+      _id: apiResponse.id,
+      _rev: apiResponse.rev,
+      username: apiResponse.username,
+      place: placeIds,
+    };
+  };
+
+  const knownUserDocs = {};
+  for (const facilityId of deletedDocIds) {
+    const fetchedUserInfos = await api().getUsersAtPlace(facilityId);
+    for (const fetchedUserInfo of fetchedUserInfos) {
+      const userDoc = knownUserDocs[fetchedUserInfo.username] || toPostApiFormat(fetchedUserInfo);
+      removePlace(userDoc, facilityId);
+      knownUserDocs[userDoc.username] = userDoc;
+    }
+  }
+
+  return Object.values(knownUserDocs);
+}
+
+function removePlace(userDoc, placeId) {
+  if (Array.isArray(userDoc.place)) {
+    userDoc.place = userDoc.place
+      .filter(id => id !== placeId);
+  } else {
+    delete userDoc.place;
+  }
+}
+
+async function updateAffectedUsers(affectedUsers) {
+  let disabledUsers = 0, updatedUsers = 0;
+  for (const userDoc of affectedUsers) {
+    const shouldDisable = !userDoc.place || userDoc.place?.length === 0;
+    if (shouldDisable) {
+      trace(`Disabling ${userDoc.username}`);
+      await api().disableUser(userDoc.username);
+      disabledUsers++;
+    } else {
+      trace(`Updating ${userDoc.username}`);
+      await api().updateUser(userDoc);
+      updatedUsers++;
+    }
+  }
+
+  info(`${disabledUsers} users disabled. ${updatedUsers} users updated.`);
+}
 
 module.exports = {
   requiresInstance: true,

src/lib/api.js

@@ -39,6 +39,7 @@ const request = {
   get: _request('get'),
   post: _request('post'),
   put: _request('put'),
+  delete: _request('delete'),
 };
 
 const logDeprecatedTransitions = (settings) => {
@@ -98,6 +99,29 @@ const api = {
       .then(() => updateAppSettings(content));
   },
 
+  async getUsersAtPlace(facilityId) {
+    const result = await request.get({
+      uri: `${environment.instanceUrl}/api/v2/users?facility_id=${facilityId}`,
+      json: true,
+    });
+
+    return result || [];
+  },
+
+  disableUser(username) {
+    return request.delete({
+      uri: `${environment.instanceUrl}/api/v1/users/${username}`,
+    });
+  },
+
+  updateUser(userDoc) {
+    return request.post({
+      uri: `${environment.instanceUrl}/api/v1/users/${userDoc.username}`,
+      json: true,
+      body: userDoc,
+    });
+  },
+
   createUser(userData) {
     return request.post({
       uri: `${environment.instanceUrl}/api/v1/users`,

src/lib/hierarchy-operations/delete-hierarchy.js

@@ -0,0 +1,46 @@
+const DataSource = require('./hierarchy-data-source');
+const JsDocs = require('./jsdocFolder');
+const lineageConstraints = require('./lineage-constraints');
+const { trace, info } = require('../log');
+
+const prettyPrintDocument = doc => `'${doc.name}' (${doc._id})`;
+async function deleteHierarchy(db, options, sourceIds) {
+  JsDocs.prepareFolder(options);
+
+  const sourceDocs = await DataSource.getContactsByIds(db, sourceIds);
+  const constraints = await lineageConstraints(db, options);
+  for (const sourceId of sourceIds) {
+    const sourceDoc = sourceDocs[sourceId];
+    trace(`Deleting descendants and reports under: ${prettyPrintDocument(sourceDoc)}`);
+    const descendantsAndSelf = await DataSource.getContactWithDescendants(db, sourceId);
+
+    let affectedReportCount = 0;
+    for (const descendant of descendantsAndSelf) {
+      const toDeleteUsers = options.disableUsers && constraints.isPlace(descendant);
+      JsDocs.deleteDoc(options, descendant, toDeleteUsers);
+      affectedReportCount += await deleteReportsForContact(db, options, descendant);
+    }
+
+    const affectedContactCount = descendantsAndSelf.length;
+
+    info(`Staged updates to delete ${prettyPrintDocument(sourceDoc)}. ${affectedContactCount.length} contact(s) and ${affectedReportCount} report(s).`);
+  }
+}
+
+async function deleteReportsForContact(db, options, contact) {
+  let skip = 0;
+  let reportBatch;
+  do {
+    reportBatch = await DataSource.getReportsForContacts(db, [], contact._id, skip);
+
+    for (const report of reportBatch) {
+      JsDocs.deleteDoc(options, report);
+    }
+
+    skip += reportBatch.length;
+  } while (reportBatch.length >= DataSource.BATCH_SIZE);
+
+  return skip;
+}
+
+module.exports = deleteHierarchy;

src/lib/hierarchy-operations/index.js

@@ -1,10 +1,10 @@
+const DataSource = require('./hierarchy-data-source');
+const deleteHierarchy = require('./delete-hierarchy');
+const JsDocs = require('./jsdocFolder');
 const lineageManipulation = require('./lineage-manipulation');
 const LineageConstraints = require('./lineage-constraints');
 const { trace, info } = require('../log');
 
-const JsDocs = require('./jsdocFolder');
-const DataSource = require('./hierarchy-data-source');
-
 async function moveHierarchy(db, options, sourceIds, destinationId) {
   JsDocs.prepareFolder(options);
   trace(`Fetching contact details: ${destinationId}`);
@@ -30,11 +30,8 @@ async function moveHierarchy(db, options, sourceIds, destinationId) {
     await constraints.assertNoPrimaryContactViolations(sourceDoc, destinationDoc, descendantsAndSelf);
 
     if (options.merge) {
-      JsDocs.writeDoc(options, {
-        _id: sourceDoc._id,
-        _rev: sourceDoc._rev,
-        _deleted: true,
-      });
+      const toDeleteUsers = options.disableUsers && constraints.isPlace(sourceDoc);
+      JsDocs.deleteDoc(options, sourceDoc, toDeleteUsers);
     }
 
     const prettyPrintDocument = doc => `'${doc.name}' (${doc._id})`;
@@ -176,11 +173,11 @@ function replaceLineageInContacts(moveContext) {
     .filter(Boolean);
 }
 
-module.exports = (db, options) => {
+module.exports = (db, options = {}) => {
   return {
     HIERARCHY_ROOT: DataSource.HIERARCHY_ROOT,
     move: (sourceIds, destinationId) => moveHierarchy(db, { ...options, merge: false }, sourceIds, destinationId),
     merge: (sourceIds, destinationId) => moveHierarchy(db, { ...options, merge: true }, sourceIds, destinationId),
+    delete: async (sourceIds) => deleteHierarchy(db, options, sourceIds),
   };
 };
-