feat(#10706): add bulk operation framework and contact hierarchy delete

api/src/controllers/bulk-operations.js

@@ -0,0 +1,79 @@
+const service = require('../services/bulk-operations');
+const serverUtils = require('../server-utils');
+const auth = require('../auth');
+
+module.exports = {
+  v1: {
+    /**
+     * @openapi
+     * /api/v1/bulk-operations/{id}:
+     *   get:
+     *     summary: Get the status of a bulk operation
+     *     operationId: v1BulkOperationIdGet
+     *     description: >
+     *       Returns the log document for a bulk operation, including the per-action status and the
+     *       count of changes applied so far. Used to poll the progress of an operation that was
+     *       started through one of the bulk endpoints.
+     *     tags: [Bulk]
+     *     x-since: 5.3.0
+     *     parameters:
+     *       - in: path
+     *         name: id
+     *         required: true
+     *         schema:
+     *           type: string
+     *         description: The id of the bulk operation, as returned when it was started.
+     *     responses:
+     *       '200':
+     *         description: The bulk operation log
+     *         content:
+     *           application/json:
+     *             schema:
+     *               type: object
+     *               properties:
+     *                 _id:
+     *                   type: string
+     *                   description: The bulk operation id.
+     *                 start_date:
+     *                   type: string
+     *                   format: date-time
+     *                   description: When the operation was started.
+     *                 actions:
+     *                   type: object
+     *                   description: Per-action status, keyed by action id.
+     *                   additionalProperties:
+     *                     type: object
+     *                     properties:
+     *                       status:
+     *                         type: string
+     *                         enum: [queued, completed, failed]
+     *                       action:
+     *                         type: string
+     *                         enum: [archive, set-contact, delete-user]
+     *                       updated_date:
+     *                         type: string
+     *                         format: date-time
+     *                       total_changes_count:
+     *                         type: integer
+     *                       failed_operations:
+     *                         type: array
+     *                         description: The operations that failed, present only when status is failed.
+     *                         items:
+     *                           type: object
+     *       '401':
+     *         $ref: '#/components/responses/Unauthorized'
+     *       '403':
+     *         $ref: '#/components/responses/Forbidden'
+     *       '404':
+     *         $ref: '#/components/responses/NotFound'
+     */
+    get: serverUtils.doOrError(async (req, res) => {
+      await auth.assertPermissions(req, { isOnline: true });
+      const log = await service.getLog(req.params.id);
+      if (!log) {
+        return serverUtils.error({ status: 404, message: 'Bulk operation not found' }, req, res);
+      }
+      res.json(log);
+    })
+  }
+};

api/src/controllers/person.js

@@ -2,6 +2,7 @@ const { Person, Qualifier } = require('@medic/cht-datasource');
 const ctx = require('../services/data-context');
 const serverUtils = require('../server-utils');
 const auth = require('../auth');
+const deleteContactService = require('../services/delete-contact');
 
 const getPerson = ctx.bind(Person.v1.get);
 const getPersonWithLineage = ctx.bind(Person.v1.getWithLineage);
@@ -208,5 +209,48 @@ module.exports = {
       const updatedPersonDoc = await updatePerson(updatePersonInput);
       return res.json(updatedPersonDoc);
     }),
+
+    /**
+     * @openapi
+     * /api/v1/person/{id}:
+     *   delete:
+     *     summary: Delete a person
+     *     operationId: v1PersonIdDelete
+     *     description: >
+     *       Queues an asynchronous bulk operation that removes the person and the reports they are the
+     *       subject of, clears any dangling primary-contact references, and (with delete_users=true)
+     *       removes linked user accounts. Returns a summary of the changes and the bulk operation id
+     *       to poll.
+     *     tags: [Person]
+     *     x-since: 5.3.0
+     *     x-permissions:
+     *       hasAll: [can_delete_contact_hierarchy, can_delete_users]
+     *     parameters:
+     *       - in: path
+     *         name: id
+     *         required: true
+     *         schema:
+     *           type: string
+     *         description: The id of the person to delete
+     *       - $ref: '#/components/parameters/deleteUsers'
+     *       - $ref: '#/components/parameters/dryRun'
+     *     responses:
+     *       '202':
+     *         $ref: '#/components/responses/BulkOperationQueued'
+     *       '200':
+     *         $ref: '#/components/responses/BulkOperationDryRun'
+     *       '400':
+     *         $ref: '#/components/responses/BadRequest'
+     *       '401':
+     *         $ref: '#/components/responses/Unauthorized'
+     *       '403':
+     *         $ref: '#/components/responses/Forbidden'
+     *       '404':
+     *         $ref: '#/components/responses/NotFound'
+     */
+    delete: deleteContactService.handleDelete({
+      get: (uuid) => getPerson(Qualifier.byUuid(uuid)),
+      type: 'Person',
+    }),
   },
 };

api/src/controllers/place.js

@@ -2,6 +2,7 @@ const { Place, Qualifier } = require('@medic/cht-datasource');
 const ctx = require('../services/data-context');
 const serverUtils = require('../server-utils');
 const auth = require('../auth');
+const deleteContactService = require('../services/delete-contact');
 
 const getPlace = ctx.bind(Place.v1.get);
 const getPlaceWithLineage = ctx.bind(Place.v1.getWithLineage);
@@ -214,6 +215,49 @@ module.exports = {
       };
       const updatedPlaceDoc = await update(updatePlaceInput);
       return res.json(updatedPlaceDoc);
+    }),
+
+    /**
+     * @openapi
+     * /api/v1/place/{id}:
+     *   delete:
+     *     summary: Delete a place and its hierarchy
+     *     operationId: v1PlaceIdDelete
+     *     description: >
+     *       Queues an asynchronous bulk operation that removes the place, every descendant contact,
+     *       and the reports they are the subject of, clears any dangling primary-contact references,
+     *       and (with delete_users=true) removes linked user accounts. Returns a summary of the
+     *       changes and the bulk operation id to poll.
+     *     tags: [Place]
+     *     x-since: 5.3.0
+     *     x-permissions:
+     *       hasAll: [can_delete_contact_hierarchy, can_delete_users]
+     *     parameters:
+     *       - in: path
+     *         name: id
+     *         required: true
+     *         schema:
+     *           type: string
+     *         description: The id of the place to delete
+     *       - $ref: '#/components/parameters/deleteUsers'
+     *       - $ref: '#/components/parameters/dryRun'
+     *     responses:
+     *       '202':
+     *         $ref: '#/components/responses/BulkOperationQueued'
+     *       '200':
+     *         $ref: '#/components/responses/BulkOperationDryRun'
+     *       '400':
+     *         $ref: '#/components/responses/BadRequest'
+     *       '401':
+     *         $ref: '#/components/responses/Unauthorized'
+     *       '403':
+     *         $ref: '#/components/responses/Forbidden'
+     *       '404':
+     *         $ref: '#/components/responses/NotFound'
+     */
+    delete: deleteContactService.handleDelete({
+      get: (uuid) => getPlace(Qualifier.byUuid(uuid)),
+      type: 'Place',
     })
   }
 };

api/src/routing.js

@@ -46,6 +46,7 @@ const { people, places } = require('@medic/contacts')(config, db, dataContext);
 const upgrade = require('./controllers/upgrade');
 const settings = require('./controllers/settings');
 const bulkDocs = require('./controllers/bulk-docs');
+const bulkOperations = require('./controllers/bulk-operations');
 const monitoring = require('./controllers/monitoring');
 const africasTalking = require('./controllers/africas-talking');
 const rapidPro = require('./controllers/rapidpro');
@@ -476,6 +477,8 @@ app.get('/api/v1/monitoring', deprecation.deprecate('/api/v2/monitoring'), monit
 app.get('/api/v2/monitoring', monitoring.getV2);
 app.get('/api/v1/impact', impact.v1.get);
 
+app.get('/api/v1/bulk-operations/:id', bulkOperations.v1.get);
+
 app.post('/api/v1/upgrade', jsonParser, upgrade.upgrade);
 app.post('/api/v1/upgrade/stage', jsonParser, upgrade.stage);
 app.post('/api/v1/upgrade/complete', jsonParser, upgrade.complete);
@@ -659,6 +662,7 @@ app.get('/api/v1/place', place.v1.getAll);
 app.get('/api/v1/place/:uuid', place.v1.get);
 app.postJson('/api/v1/place', place.v1.create);
 app.putJson('/api/v1/place/:uuid', place.v1.update);
+app.delete('/api/v1/place/:uuid', place.v1.delete);
 
 /**
  * @openapi
@@ -734,6 +738,7 @@ app.get('/api/v1/person', person.v1.getAll);
 app.get('/api/v1/person/:uuid', person.v1.get);
 app.postJson('/api/v1/person', person.v1.create);
 app.putJson('/api/v1/person/:uuid', person.v1.update);
+app.delete('/api/v1/person/:uuid', person.v1.delete);
 
 app.get('/api/v1/contact/uuid', contact.v1.getUuids);
 app.postJson('/api/v1/contact/summary', contact.v1.getSummaries);

api/src/services/bulk-operations.js

@@ -0,0 +1,95 @@
+const { v7: uuid } = require('uuid');
+const db = require('../db');
+const { BULK_OPERATIONS } = require('@medic/constants');
+
+const { LOG_ID_PREFIX, ACTION_ID_PREFIX, OPERATIONS_ATTACHMENT, STATUSES } = BULK_OPERATIONS;
+const OPERATIONS_CONTENT_TYPE = 'application/json';
+
+const getOperationUuid = (operationId) => operationId.slice(LOG_ID_PREFIX.length);
+const generateOperationId = () => `${LOG_ID_PREFIX}${uuid()}`;
+const generateActionId = (operationId) => `${ACTION_ID_PREFIX}${getOperationUuid(operationId)}:${uuid()}`;
+
+// Params live in an attachment so advancing the cursor as Sentinel batches does not rewrite them.
+const encodeOperations = (operations) => ({
+  content_type: OPERATIONS_CONTENT_TYPE,
+  data: Buffer.from(JSON.stringify(operations)).toString('base64'),
+});
+
+const buildActionDoc = (operationId, action, operations) => ({
+  _id: generateActionId(operationId),
+  bulk_operation_id: operationId,
+  action,
+  cursor: 0,
+  total: operations.length,
+  _attachments: {
+    [OPERATIONS_ATTACHMENT]: encodeOperations(operations),
+  },
+});
+
+const buildLogAction = (action, totalChangesCount, date) => ({
+  status: STATUSES.QUEUED,
+  action,
+  updated_date: date,
+  total_changes_count: totalChangesCount,
+});
+
+const buildBulkOperation = (actionOperations, date) => {
+  const operationId = generateOperationId();
+  const actions = actionOperations.map(({ action, operations }) => buildActionDoc(operationId, action, operations));
+
+  const logActions = {};
+  actions.forEach((actionDoc) => {
+    logActions[actionDoc._id] = buildLogAction(actionDoc.action, actionDoc.total, date);
+  });
+
+  const log = {
+    _id: operationId,
+    start_date: date,
+    actions: logActions,
+  };
+
+  return { log, actions };
+};
+
+// Guards against returning the other kinds of log doc that share the medic-logs database.
+const getLog = async (id) => {
+  if (!id?.startsWith(LOG_ID_PREFIX)) {
+    return null;
+  }
+
+  try {
+    const log = await db.medicLogs.get(id);
+    delete log._rev;
+    return log;
+  } catch (err) {
+    if (err.status === 404) {
+      return null;
+    }
+    throw err;
+  }
+};
+
+/**
+ * Queues a bulk operation: writes the log document to medic-logs (the status record the polling
+ * endpoint reads) and one action document per action type to medic-sentinel (what the Sentinel
+ * listener processes). The log is written first so it exists before the listener picks up an action.
+ * Action groups with no operations are skipped.
+ * @param {Object[]} actionOperations - one group per action type
+ * @param {string} actionOperations[].action - the action type (`archive`, `set-contact`, `delete-user`)
+ * @param {Object[]} actionOperations[].operations - the per-item params for that action
+ * @returns {Promise<string>} the bulk operation id
+ */
+const queue = async (actionOperations) => {
+  const nonEmpty = actionOperations.filter(({ operations }) => operations.length);
+  const { log, actions } = buildBulkOperation(nonEmpty, new Date());
+
+  await db.medicLogs.put(log);
+  await db.sentinel.bulkDocs(actions);
+
+  return log._id;
+};
+
+module.exports = {
+  getLog,
+  queue,
+};