Merge branch '269-support-requesting-a-partial-update-from-the-events-log-endpoint' into 'devel'

Resolve "Support requesting a partial update from the events log endpoint"

Closes #269

See merge request wgp/dougal/software!47

lib/www/server/api/index.js

@@ -181,6 +181,9 @@ app.map({
 		post: [ mw.auth.access.write, mw.event.post ],
 		put: [ mw.auth.access.write, mw.event.put ],
 		delete: [ mw.auth.access.write, mw.event.delete ],
+		'changes/:since': {
+			get: [ mw.event.changes ]
+		},
 		// TODO Rename -/:sequence → sequence/:sequence
 		'-/:sequence/': { // NOTE: We need to avoid conflict with the next endpoint ☹
 			get: [ mw.event.sequence.get ],

lib/www/server/api/middleware/event/changes.js

@@ -0,0 +1,14 @@
+
+const { event } = require('../../../lib/db');
+
+const json = async function (req, res, next) {
+	try {
+		const response = await event.changes(req.params.project, req.params.since, req.query);
+		res.status(200).send(response);
+		next();
+	} catch (err) {
+		next(err);
+	}
+};
+
+module.exports = json;

lib/www/server/api/middleware/event/index.js

@@ -6,5 +6,6 @@ module.exports = {
 	post: require('./post'),
 	put: require('./put'),
 	patch: require('./patch'),
-	delete: require('./delete')
+	delete: require('./delete'),
+	changes: require('./changes')
 }

lib/www/server/lib/db/event/changes.js

@@ -0,0 +1,61 @@
+const { setSurvey } = require('../connection');
+const { replaceMarkers } = require('../../utils');
+
+function parseValidity (row) {
+	if (row.validity) {
+		const rx = /^(.)("([\d :.+-]+)")?,("([\d :.+-]+)")?([\]\)])$/;
+		const m = row.validity.match(rx);
+		row.validity = [ m[1], m[3], m[5], m[6] ];
+	}
+	return row;
+}
+
+function transform (row) {
+	if (row.validity[2]) {
+		return {
+			uid: row.uid,
+			id: row.id,
+			is_deleted: true
+		}
+	} else {
+		row.is_deleted = false;
+		row.has_edits = row.id != row.uid;
+		row.modified_on = row.validity[1];
+		delete row.uid;
+		delete row.validity;
+		return row;
+	}
+}
+
+function unique (rows) {
+	const o = {};
+	rows.forEach(row => o[row.id] = row);
+	return Object.values(o);
+}
+
+/**
+ * Get the event change history from a given epoch (ts0),
+ * for all events.
+ */
+async function changes (projectId, ts0, opts = {}) {
+
+	if (!projectId || !ts0) {
+		throw {status: 400, message: "Invalid request" };
+		return;
+	}
+
+	const client = await setSurvey(projectId);
+
+	const text = `
+		SELECT *
+		FROM event_log_changes($1);
+	`;
+
+	const res = await client.query(text, [ts0]);
+	client.release();
+	return opts.unique
+		? unique(res.rows.map(i => transform(replaceMarkers(parseValidity(i)))))
+		: res.rows.map(i => transform(replaceMarkers(parseValidity(i))));
+}
+
+module.exports = changes;

lib/www/server/lib/db/event/index.js

@@ -5,5 +5,6 @@ module.exports = {
 	post: require('./post'),
 	put: require('./put'),
 	patch: require('./patch'),
-	del: require('./delete')
+	del: require('./delete'),
+	changes: require('./changes')
 }

lib/www/server/spec/openapi.yaml

@@ -180,6 +180,16 @@ components:
             required: true
             example: 14707
 
+        Since:
+            description: Starting epoch
+            name: since
+            in: path
+            schema:
+                type: string
+                format: date-time
+            required: true
+            example: 1970-01-01T00:00:00Z
+
         QueryLimit:
             description: Maximum number of results to return
             name: limit
@@ -206,6 +216,16 @@ components:
                 pattern: "(([^\\s,;:]+)(\\s*[,;:\\s]\\s*)?)+"
             example: "line,point,tstamp"
 
+        Unique:
+            description: |
+                Return unique results. Any value at all represents `true`.
+            name: unique
+            in: query
+            schema:
+                type: string
+                pattern: ".+"
+            example: "t"
+
 
     schemas:
         Duration:
@@ -602,14 +622,26 @@ components:
                                 Flag to indicate that this event is read-only. It cannot be edited by the user or deleted. Typically this concerns system-generated events such as QC results or midnight shots.
                     additionalProperties: true
 
+        EventIDAbstract:
+            type: object
+            properties:
+                id:
+                    type: number
+                    description: Event ID.
+
+
+        EventUIDAbstract:
+            type: object
+            properties:
+                uid:
+                    type: number
+                    description: Event instance unique ID. When an event is modified, the new entry acquires a different `uid` while keeping the same `id` as the original event.
+
+
         EventAbstract:
             allOf:
                 -
-                    type: object
-                    properties:
-                        id:
-                            type: number
-                            description: Event ID.
+                    $ref: "#/components/schemas/EventIDAbstract"
                 -
                     $ref: "#/components/schemas/EventNew"
 
@@ -659,6 +691,47 @@ components:
                                 * The third element is either an ISO-8601 timestamp or `null`. The latter indicates +∞. These are the events returned by endpoints that do not concern themselves with event history.
                                 * The fourth element is one of `]` or `)`. As before, it indicates either an open or closed interval.
 
+        EventChangesIsDeletedAbstract:
+            type: object
+            properties:
+                is_deleted:
+                    type: boolean
+                    description: >
+                        Flag to indicate whether this event or event instance (depending on the presence of a `uid` attribute) has been deleted.
+
+
+        EventChangesModified:
+            description: An event modification.
+            allOf:
+                -
+                    $ref: "#/components/schemas/EventAbstract"
+                -
+                    $ref: "#/components/schemas/EventChangesIsDeletedAbstract"
+
+        EventChangesDeleted:
+            description: |
+                Identification of a deleted event or event instance.
+
+                **Note:** the details of the deleted event are not included, only its `id` and `uid`.
+            allOf:
+                -
+                    $ref: "#/components/schemas/EventIDAbstract"
+                -
+                    $ref: "#/components/schemas/EventUIDAbstract"
+                -
+                    $ref: "#/components/schemas/EventChangesIsDeletedAbstract"
+
+        EventChanges:
+            description: List of event changes since the given epoch.
+            type: array
+            items:
+                anyOf:
+                    -
+                        $ref: "#/components/schemas/EventChangesDeleted"
+                    -
+                        $ref: "#/components/schemas/EventChangesModified"
+
+
         SeisExportEntryFSP:
             type: object
             properties:
@@ -1382,6 +1455,31 @@ paths:
                     $ref: "#/components/responses/401"
 
 
+    /project/{project}/changes/{since}:
+        get:
+            summary: Get event change history since epoch.
+            tags: [ "log" ]
+            security:
+                - BearerAuthGuest: []
+                - CookieAuthGuest: []
+            parameters:
+                - $ref: "#/components/parameters/Project"
+                - $ref: "#/components/parameters/Since"
+                - $ref: "#/components/parameters/Unique"
+            responses:
+                "200":
+                    description: List of project event changes. If `unique` is given, only the latest version of each event will be returned, otherwise the entire modification history is given, potentially including the same event `id` multiple times.
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items:
+                                    $ref: "#/components/schemas/EventChanges"
+
+                "401":
+                    $ref: "#/components/responses/401"
+
+
     /project/{project}/label:
         get:
             summary: Get project labels.