@opentermsarchive/engine 14.1.0 → 15.0.0

package/src/archivist/recorder/repositories/interface.js

@@ -69,6 +69,15 @@ class RepositoryInterface {
     throw new Error(`#findById method is not implemented in ${this.constructor.name}`);
   }
 
+  /**
+   * Find the metadata of the record that matches the given record ID, without loading its content
+   * @param   {string}          recordId - Record ID of the record to find
+   * @returns {Promise<Record>}          Promise that will be resolved with the found record (without content) or null if none match the given ID
+   */
+  async findMetadataById(recordId) {
+    throw new Error(`#findMetadataById method is not implemented in ${this.constructor.name}`);
+  }
+
   /**
    * Find all records, in descending chronological order (newest first; opposite of #iterate)
    * For performance reasons, the content of the records will not be loaded by default. Use #loadRecordContent to load the content of individual records
@@ -99,6 +108,20 @@ class RepositoryInterface {
     throw new Error(`#findByService method is not implemented in ${this.constructor.name}`);
   }
 
+  /**
+   * Get the IDs locating a version within the history of its terms: the first (oldest) and last (newest) versions, as well as the immediately previous (older) and next (newer) ones
+   * These IDs are computed from a single deterministic chronological order (by fetch date, with the record ID as a stable tiebreaker), so navigating prev/next always round-trips
+   * @param   {string}                                                                 serviceId                          - Service ID of the version
+   * @param   {string}                                                                 termsType                          - Terms type of the version
+   * @param   {string}                                                                 versionId                          - ID of the version to locate within its terms history
+   * @param   {object}                                                                 [options]                          - Query options
+   * @param   {boolean}                                                                [options.includeTechnicalUpgrades] - When false, exclude technical upgrade records from the sequence. Default: true
+   * @returns {Promise<{first: ?string, prev: ?string, next: ?string, last: ?string}>}                                    Promise resolved with the related version IDs, each null when there is none
+   */
+  async getNavigationIds(serviceId, termsType, versionId, options = {}) {
+    throw new Error(`#getNavigationIds method is not implemented in ${this.constructor.name}`);
+  }
+
   /**
    * Find all records for a specific service and terms type, in descending chronological order
    * For performance reasons, the content of the records will not be loaded by default. Use #loadRecordContent to load the content of individual records
@@ -152,6 +175,17 @@ class RepositoryInterface {
   async loadRecordContent(record) {
     throw new Error(`#loadRecordContent method is not implemented in ${this.constructor.name}`);
   }
+
+  /**
+   * Get the number of lines added and deleted by a record, relative to the previous state of the same terms
+   * This is an optional capability: backends that retain diffs (Git) override it, while backends that store full snapshots (MongoDB) inherit this default and report the statistics as unavailable
+   * @param   {string}                                            recordId - Record ID to get diff stats for
+   * @returns {Promise<{additions: ?number, deletions: ?number}>}          Promise resolved with the number of added and deleted lines, each null when the backend cannot provide them
+   */
+  // eslint-disable-next-line class-methods-use-this, no-unused-vars
+  getDiffStats(recordId) {
+    return { additions: null, deletions: null };
+  }
 }
 
 export default RepositoryInterface;

package/src/archivist/recorder/repositories/mongo/index.js

@@ -88,6 +88,19 @@ export default class MongoRepository extends RepositoryInterface {
     return this.#toDomain(mongoDocument);
   }
 
+  async findMetadataById(recordId) {
+    if (!ObjectId.isValid(recordId)) {
+      return null;
+    }
+
+    const document = await this.collection.findOne(
+      { _id: ObjectId.createFromHexString(recordId) },
+      { projection: { content: 0 } },
+    );
+
+    return document ? this.#toDomain(document, { deferContentLoading: true }) : null;
+  }
+
   async findAll({ limit, offset, includeTechnicalUpgrades = true } = {}) {
     const filter = includeTechnicalUpgrades ? {} : { isTechnicalUpgrade: { $ne: true } };
     let query = this.collection.find(filter).project({ content: 0 }).sort({ fetchDate: -1 });
@@ -146,6 +159,46 @@ export default class MongoRepository extends RepositoryInterface {
       .map(mongoDocument => this.#toDomain(mongoDocument, { deferContentLoading: true })));
   }
 
+  async getNavigationIds(serviceId, termsType, versionId, { includeTechnicalUpgrades = true } = {}) {
+    const empty = { first: null, prev: null, next: null, last: null };
+
+    if (!ObjectId.isValid(versionId)) {
+      return empty;
+    }
+
+    const _id = ObjectId.createFromHexString(versionId);
+    const filter = { serviceId, termsType };
+
+    if (!includeTechnicalUpgrades) {
+      filter.isTechnicalUpgrade = { $ne: true };
+    }
+
+    const current = await this.collection.findOne({ ...filter, _id }, { projection: { fetchDate: 1 } });
+
+    if (!current) {
+      return empty;
+    }
+
+    const { fetchDate } = current;
+    const idOnly = { projection: { _id: 1 } };
+
+    // Deterministic total order (fetchDate, then _id) ascending; prev is the greatest record strictly before the current one, next the least strictly after.
+    // Using _id as a tiebreaker makes prev and next well-defined even for versions sharing the same fetch date, so navigation always round-trips.
+    const [ oldest, newest, previous, next ] = await Promise.all([
+      this.collection.find(filter, idOnly).sort({ fetchDate: 1, _id: 1 }).limit(1).next(),
+      this.collection.find(filter, idOnly).sort({ fetchDate: -1, _id: -1 }).limit(1).next(),
+      this.collection.find({ ...filter, $or: [{ fetchDate: { $lt: fetchDate } }, { fetchDate, _id: { $lt: _id } }] }, idOnly).sort({ fetchDate: -1, _id: -1 }).limit(1).next(),
+      this.collection.find({ ...filter, $or: [{ fetchDate: { $gt: fetchDate } }, { fetchDate, _id: { $gt: _id } }] }, idOnly).sort({ fetchDate: 1, _id: 1 }).limit(1).next(),
+    ]);
+
+    return {
+      first: oldest?._id?.toString() || null,
+      last: newest?._id?.toString() || null,
+      prev: previous?._id?.toString() || null,
+      next: next?._id?.toString() || null,
+    };
+  }
+
   count(serviceId, termsType) {
     const filter = {};
 

package/src/archivist/recorder/repositories/mongo/index.test.js

@@ -988,6 +988,177 @@ describe('MongoRepository', () => {
       });
     });
 
+    describe('#getNavigationIds', () => {
+      let firstVersion;
+      let middleVersion;
+      let lastVersion;
+
+      before(async () => {
+        firstVersion = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: 'first content',
+          fetchDate: FETCH_DATE_EARLIER,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        middleVersion = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: 'middle content',
+          fetchDate: FETCH_DATE,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        lastVersion = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: 'last content',
+          fetchDate: FETCH_DATE_LATER,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+      });
+
+      after(() => subject.removeAll());
+
+      context('for the oldest version', () => {
+        let navigationIds;
+
+        before(async () => { navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, firstVersion.id); });
+
+        it('has no previous version', () => expect(navigationIds.prev).to.be.null);
+        it('points to the next version', () => expect(navigationIds.next).to.equal(middleVersion.id));
+        it('points to itself as first', () => expect(navigationIds.first).to.equal(firstVersion.id));
+        it('points to the newest version as last', () => expect(navigationIds.last).to.equal(lastVersion.id));
+      });
+
+      context('for a middle version', () => {
+        let navigationIds;
+
+        before(async () => { navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, middleVersion.id); });
+
+        it('points to the previous version', () => expect(navigationIds.prev).to.equal(firstVersion.id));
+        it('points to the next version', () => expect(navigationIds.next).to.equal(lastVersion.id));
+        it('points to the oldest version as first', () => expect(navigationIds.first).to.equal(firstVersion.id));
+        it('points to the newest version as last', () => expect(navigationIds.last).to.equal(lastVersion.id));
+      });
+
+      context('for the newest version', () => {
+        let navigationIds;
+
+        before(async () => { navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, lastVersion.id); });
+
+        it('points to the previous version', () => expect(navigationIds.prev).to.equal(middleVersion.id));
+        it('has no next version', () => expect(navigationIds.next).to.be.null);
+        it('points to itself as last', () => expect(navigationIds.last).to.equal(lastVersion.id));
+      });
+
+      context('when the version does not exist', () => {
+        it('returns only null IDs', async () => {
+          expect(await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, 'ffffffffffffffffffffffff')).to.deep.equal({ first: null, prev: null, next: null, last: null });
+        });
+      });
+
+      context('when a technical upgrade is recorded out of chronological order', () => {
+        // A technical upgrade re-renders an old snapshot: it carries an OLD fetch date but is inserted last.
+        // The navigation IDs are derived from a single chronological order, so prev/next stay exact inverses.
+        const TECHNICAL_UPGRADE_DATE = new Date('2000-01-01T09:00:00.000Z'); // between firstVersion (06:00) and middleVersion (12:00)
+        let technicalUpgrade;
+
+        before(async () => {
+          technicalUpgrade = await subject.save(new Version({
+            serviceId: SERVICE_PROVIDER_ID,
+            termsType: TERMS_TYPE,
+            content: 'technical upgrade content',
+            fetchDate: TECHNICAL_UPGRADE_DATE,
+            isTechnicalUpgrade: true,
+            snapshotIds: [SNAPSHOT_ID],
+          }));
+        });
+
+        it('orders it by its fetch date, not its insertion order', async () => {
+          const navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, technicalUpgrade.id);
+
+          expect(navigationIds.prev).to.equal(firstVersion.id);
+          expect(navigationIds.next).to.equal(middleVersion.id);
+        });
+
+        it('keeps prev and next as exact inverses (round-trips)', async () => {
+          const fromFirst = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, firstVersion.id);
+
+          expect(fromFirst.next).to.equal(technicalUpgrade.id);
+
+          const backFromUpgrade = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, fromFirst.next);
+
+          expect(backFromUpgrade.prev).to.equal(firstVersion.id);
+        });
+
+        it('can exclude technical upgrades from the sequence', async () => {
+          const navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, firstVersion.id, { includeTechnicalUpgrades: false });
+
+          expect(navigationIds.next).to.equal(middleVersion.id);
+        });
+      });
+    });
+
+    describe('#getNavigationIds with versions sharing the same fetch date', () => {
+      // Distinct versions can share a fetch date; the _id tiebreaker must keep the order deterministic so prev/next still round-trip.
+      let ids;
+
+      before(async () => {
+        ids = [];
+        for (const content of [ 'tie A', 'tie B', 'tie C' ]) {
+          ids.push((await subject.save(new Version({ serviceId: SERVICE_PROVIDER_ID, termsType: TERMS_TYPE, content, fetchDate: FETCH_DATE, snapshotIds: [SNAPSHOT_ID] }))).id);
+        }
+      });
+
+      after(() => subject.removeAll());
+
+      it('round-trips next then prev for every version', async () => {
+        for (const id of ids) {
+          const navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, id);
+
+          if (navigationIds.next) {
+            expect((await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, navigationIds.next)).prev).to.equal(id);
+          }
+        }
+      });
+
+      it('exposes all three versions as a single ordered chain', async () => {
+        const head = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, ids[0]);
+        const walked = new Set([head.first]);
+        let cursor = head.first;
+
+        while (cursor) {
+          walked.add(cursor);
+          cursor = (await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, cursor)).next;
+        }
+
+        expect(walked).to.have.lengthOf(ids.length);
+      });
+    });
+
+    describe('#getDiffStats', () => {
+      // Diff statistics are an optional repository capability; MongoDB stores full snapshots rather than diffs, so it inherits the interface default that reports them as unavailable.
+      let versionId;
+
+      before(async () => {
+        ({ id: versionId } = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: CONTENT,
+          fetchDate: FETCH_DATE,
+          snapshotIds: [SNAPSHOT_ID],
+        })));
+      });
+
+      after(() => subject.removeAll());
+
+      it('reports additions and deletions as unavailable', async () => {
+        expect(await subject.getDiffStats(versionId)).to.deep.equal({ additions: null, deletions: null });
+      });
+    });
+
     describe('#findLatest', () => {
       context('when there are records for the given service', () => {
         let lastSnapshotId;

package/src/collection-api/middlewares/errors.js

@@ -2,5 +2,5 @@ import logger from '../logger.js';
 
 export default function errorsMiddleware(err, req, res, next) {
   logger.error(err.stack);
-  res.status(500).json({ error: err.message });
+  res.status(500).json({ error: 'Internal Server Error' }); // Never echo internal error details: they can expose server internals such as filesystem paths
 }

package/src/collection-api/routes/index.js

@@ -38,6 +38,7 @@ export default async function apiRouter(basePath) {
   const collection = await getCollection();
   const versionsStorageConfig = config.get('@opentermsarchive/engine.recorder.versions.storage');
   const versionsRepository = await RepositoryFactory.create(versionsStorageConfig).initialize();
+  const snapshotsRepository = await RepositoryFactory.create(config.get('@opentermsarchive/engine.recorder.snapshots.storage')).initialize();
   const feedConfig = config.get('@opentermsarchive/engine.collection-api.feed');
 
   if (!collection.metadata?.id) {
@@ -50,7 +51,7 @@ export default async function apiRouter(basePath) {
 
   router.use(await metadataRouter(collection, services));
   router.use(servicesRouter(services));
-  router.use(versionsRouter(versionsRepository));
+  router.use(versionsRouter(versionsRepository, snapshotsRepository));
   router.use(feedRouter(services, versionsRepository, versionsStorageConfig.type, feedConfig.limit, feedConfig.versionUrlTemplate));
 
   return router;

package/src/collection-api/routes/services.js

@@ -9,6 +9,24 @@ import express from 'express';
  *   description: Services API
  * components:
  *   schemas:
+ *     ServiceListItem:
+ *       type: object
+ *       properties:
+ *         id:
+ *           type: string
+ *           description: The ID of the service.
+ *         name:
+ *           type: string
+ *           description: The name of the service.
+ *         terms:
+ *           type: array
+ *           description: The declared terms types for this service.
+ *           items:
+ *             type: object
+ *             properties:
+ *               type:
+ *                 type: string
+ *                 description: The type of terms.
  *     Service:
  *       type: object
  *       description: Definition of a service and the agreements its provider sets forth. While the information is the same, the format differs from the JSON declaration files that are designed for readability by contributors.
@@ -51,6 +69,19 @@ import express from 'express';
  *                       description: The names of filters to apply to the content.
  *                       items:
  *                         type: string
+ *     ErrorResponse:
+ *       type: object
+ *       properties:
+ *         error:
+ *           type: string
+ *           description: Error message.
+ *   responses:
+ *     NotFoundError:
+ *       description: Resource not found.
+ *       content:
+ *         application/json:
+ *           schema:
+ *             $ref: '#/components/schemas/ErrorResponse'
  */
 export default function servicesRouter(services) {
   const router = express.Router();
@@ -71,23 +102,7 @@ export default function servicesRouter(services) {
    *             schema:
    *               type: array
    *               items:
-   *                 type: object
-   *                 properties:
-   *                   id:
-   *                     type: string
-   *                     description: The ID of the service.
-   *                   name:
-   *                     type: string
-   *                     description: The name of the service.
-   *                   terms:
-   *                     type: array
-   *                     description: The declared terms types for this service.
-   *                     items:
-   *                       type: object
-   *                       properties:
-   *                         type:
-   *                           type: string
-   *                           description: The type of terms.
+   *                 $ref: '#/components/schemas/ServiceListItem'
    */
   router.get('/services', (req, res) => {
     res.status(200).json(Object.values(services).map(service => ({
@@ -127,15 +142,13 @@ export default function servicesRouter(services) {
    *             schema:
    *               $ref: '#/components/schemas/Service'
    *       404:
-   *         description: No service matching the provided ID is found.
+   *         $ref: '#/components/responses/NotFoundError'
    */
   router.get('/service/:serviceId', (req, res) => {
     const service = Object.hasOwn(services, req.params.serviceId) ? services[req.params.serviceId] : null;
 
     if (!service) {
-      res.status(404).send('Service not found');
-
-      return;
+      return res.status(404).json({ error: 'Service not found' });
     }
 
     res.status(200).json({