Add service-scoped feed endpoint

Author: clementbiron

src/collection-api/routes/feed.js

@@ -6,6 +6,7 @@ import { COMMIT_MESSAGE_PREFIXES } from '../../archivist/recorder/repositories/g
 import { toISODateWithoutMilliseconds } from '../../archivist/utils/date.js';
 
 import versionsRepository, { storageConfig } from './versionsRepository.js';
+import { findServiceCaseInsensitive } from './utils.js';
 
 const TAG_AUTHORITY = 'opentermsarchive.org,2026';
 const FEED_AUTHOR_NAME = 'OTA-Bot';
@@ -108,13 +109,14 @@ function render(document) {
 }
 
 /**
- * @returns {express.Router} The router instance
+ * @param   {object}         services The services to be exposed by the API
+ * @returns {express.Router}          The router instance
  * @swagger
  * tags:
  *   name: Feeds
  *   description: Atom feeds of version changes
  */
-export default function feedRouter() {
+export default function feedRouter(services) {
   const router = express.Router();
 
   /**
@@ -145,5 +147,48 @@ export default function feedRouter() {
     sendAtom(res, render(document));
   });
 
+  /**
+   * @swagger
+   * /feed/{serviceId}:
+   *   get:
+   *     summary: Atom feed of the latest version changes scoped to a single service.
+   *     tags: [Feeds]
+   *     produces:
+   *       - application/atom+xml
+   *     parameters:
+   *       - in: path
+   *         name: serviceId
+   *         description: The ID of the service. Case-insensitive.
+   *         schema:
+   *           type: string
+   *         required: true
+   *     responses:
+   *       200:
+   *         description: An Atom 1.0 feed listing the latest version records for the given service, newest first.
+   *         content:
+   *           application/atom+xml:
+   *             schema:
+   *               type: string
+   *       404:
+   *         description: No service matching the provided ID is found.
+   */
+  router.get('/feed/:serviceId', async (req, res) => {
+    const service = findServiceCaseInsensitive(services, req.params.serviceId);
+
+    if (!service) {
+      return res.status(404).send('Service not found');
+    }
+
+    const collection = await getCollection();
+    const baseUrl = buildAbsoluteBaseUrl(req);
+    const selfHref = `${baseUrl}/feed/${encodeURIComponent(service.id)}`;
+    const feedId = `tag:${TAG_AUTHORITY}:feed:${collection.metadata?.id}:${service.id}`;
+
+    const versions = await versionsRepository.findRecent(DEFAULT_LIMIT, { serviceId: service.id });
+    const document = buildFeedDocument({ collection, selfHref, feedId, versions, baseUrl });
+
+    return sendAtom(res, render(document));
+  });
+
   return router;
 }

src/collection-api/routes/feed.test.js

@@ -228,4 +228,120 @@ describe('Feed API', () => {
       });
     });
   });
+
+  describe('GET /feed/:serviceId', () => {
+    const SERVICE = 'service_without_history';
+    const OTHER_SERVICE = 'service_with_history';
+    const TERMS = 'Terms of Service';
+
+    let repository;
+
+    before(async function () {
+      this.timeout(5000);
+      repository = RepositoryFactory.create(storageConfig);
+      await repository.initialize();
+
+      await repository.save(new Version({
+        serviceId: SERVICE,
+        termsType: TERMS,
+        content: 'c1',
+        fetchDate: new Date('2024-01-01T00:00:00Z'),
+        snapshotIds: ['s1'],
+      }));
+      await repository.save(new Version({
+        serviceId: SERVICE,
+        termsType: TERMS,
+        content: 'c2',
+        fetchDate: new Date('2024-02-01T00:00:00Z'),
+        snapshotIds: ['s2'],
+      }));
+      await repository.save(new Version({
+        serviceId: OTHER_SERVICE,
+        termsType: TERMS,
+        content: 'c3',
+        fetchDate: new Date('2024-03-01T00:00:00Z'),
+        snapshotIds: ['s3'],
+      }));
+    });
+
+    after(() => repository.removeAll());
+
+    context('when the service exists and has versions', () => {
+      let response;
+
+      before(async () => {
+        response = await request.get(`${basePath}/v1/feed/${encodeURIComponent(SERVICE)}`);
+      });
+
+      it('responds with 200', () => {
+        expect(response.status).to.equal(200);
+      });
+
+      it('responds with Content-Type application/atom+xml', () => {
+        expect(response.headers['content-type']).to.match(/^application\/atom\+xml/);
+      });
+
+      it('includes only entries for that service', () => {
+        const serviceTerms = [...response.text.matchAll(/scheme="tag:opentermsarchive.org,2026:scheme:service"[^/]*term="([^"]+)"/g)]
+          .concat([...response.text.matchAll(/term="([^"]+)"[^/]*scheme="tag:opentermsarchive.org,2026:scheme:service"/g)])
+          .map(match => match[1]);
+
+        expect(serviceTerms).to.not.be.empty;
+
+        for (const term of serviceTerms) {
+          expect(term).to.equal(SERVICE);
+        }
+      });
+
+      it('has a feed id including the service id', () => {
+        expect(extractTag(response.text, 'id')).to.equal(`tag:opentermsarchive.org,2026:feed:test:${SERVICE}`);
+      });
+
+      it('has a self link pointing to the service-scoped feed endpoint', () => {
+        const href = response.text.match(/<link[^>]*rel="self"[^>]*href="([^"]+)"/)[1];
+
+        expect(href).to.match(new RegExp(`/feed/${SERVICE}$`));
+      });
+    });
+
+    context('when the service exists but has no versions', () => {
+      let response;
+
+      before(async () => {
+        response = await request.get(`${basePath}/v1/feed/${encodeURIComponent('service_with_filters_history')}`);
+      });
+
+      it('responds with 200', () => {
+        expect(response.status).to.equal(200);
+      });
+
+      it('returns an empty feed (no entries)', () => {
+        expect(response.text).to.not.include('<entry>');
+      });
+    });
+
+    context('when the service does not exist', () => {
+      let response;
+
+      before(async () => {
+        response = await request.get(`${basePath}/v1/feed/DoesNotExist`);
+      });
+
+      it('responds with 404', () => {
+        expect(response.status).to.equal(404);
+      });
+    });
+
+    context('when the serviceId uses different casing', () => {
+      let response;
+
+      before(async () => {
+        response = await request.get(`${basePath}/v1/feed/${encodeURIComponent(SERVICE.toUpperCase())}`);
+      });
+
+      it('still resolves to the service (case-insensitive)', () => {
+        expect(response.status).to.equal(200);
+      });
+    });
+  });
 });

src/collection-api/routes/index.js

@@ -38,7 +38,7 @@ export default async function apiRouter(basePath) {
   router.use(await metadataRouter(collection, services));
   router.use(servicesRouter(services));
   router.use(versionsRouter);
-  router.use(feedRouter());
+  router.use(feedRouter(services));
 
   return router;
 }

src/collection-api/routes/services.js

@@ -1,5 +1,7 @@
 import express from 'express';
 
+import { findServiceCaseInsensitive } from './utils.js';
+
 /**
  * @param   {object}         services The services to be exposed by the API
  * @returns {express.Router}          The router instance
@@ -130,8 +132,7 @@ export default function servicesRouter(services) {
    *         description: No service matching the provided ID is found.
    */
   router.get('/service/:serviceId', (req, res) => {
-    const matchedServiceID = Object.keys(services).find(key => key.toLowerCase() === req.params.serviceId?.toLowerCase());
-    const service = services[matchedServiceID];
+    const service = findServiceCaseInsensitive(services, req.params.serviceId);
 
     if (!service) {
       res.status(404).send('Service not found');

src/collection-api/routes/utils.js

@@ -0,0 +1,5 @@
+export function findServiceCaseInsensitive(services, serviceId) {
+  const matched = Object.keys(services).find(key => key.toLowerCase() === serviceId?.toLowerCase());
+
+  return matched ? services[matched] : null;
+}