Add service and terms type scoped feed endpoint

Author: clementbiron

src/collection-api/routes/feed.js

@@ -190,5 +190,60 @@ export default function feedRouter(services) {
     return sendAtom(res, render(document));
   });
 
+  /**
+   * @swagger
+   * /feed/{serviceId}/{termsType}:
+   *   get:
+   *     summary: Atom feed of the latest version changes scoped to a service and terms type.
+   *     tags: [Feeds]
+   *     produces:
+   *       - application/atom+xml
+   *     parameters:
+   *       - in: path
+   *         name: serviceId
+   *         description: The ID of the service. Case-insensitive.
+   *         schema:
+   *           type: string
+   *         required: true
+   *       - in: path
+   *         name: termsType
+   *         description: The terms type declared by the service (e.g. "Terms of Service", "Privacy Policy").
+   *         schema:
+   *           type: string
+   *         required: true
+   *     responses:
+   *       200:
+   *         description: An Atom 1.0 feed listing the latest version records for the given service and terms type, newest first.
+   *         content:
+   *           application/atom+xml:
+   *             schema:
+   *               type: string
+   *       404:
+   *         description: Either the service ID does not match any service or the terms type is not declared by that service.
+   */
+  router.get('/feed/:serviceId/:termsType', async (req, res) => {
+    const service = findServiceCaseInsensitive(services, req.params.serviceId);
+
+    if (!service) {
+      return res.status(404).send('Service not found');
+    }
+
+    const { termsType } = req.params;
+
+    if (!service.getTermsTypes().includes(termsType)) {
+      return res.status(404).send('Terms type not found for this service');
+    }
+
+    const collection = await getCollection();
+    const baseUrl = buildAbsoluteBaseUrl(req);
+    const selfHref = `${baseUrl}/feed/${encodeURIComponent(service.id)}/${encodeURIComponent(termsType)}`;
+    const feedId = `tag:${TAG_AUTHORITY}:feed:${collection.metadata?.id}:${service.id}:${termsType}`;
+
+    const versions = await versionsRepository.findRecent(DEFAULT_LIMIT, { serviceId: service.id, termsType });
+    const document = buildFeedDocument({ collection, selfHref, feedId, versions, baseUrl });
+
+    return sendAtom(res, render(document));
+  });
+
   return router;
 }

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

@@ -344,4 +344,143 @@ describe('Feed API', () => {
       });
     });
   });
+
+  describe('XML escaping and URL encoding', () => {
+    const SERVICE = 'Service B!';
+    const TERMS = 'Privacy Policy';
+    const FETCH_DATE = new Date('2024-05-15T10:00:00Z');
+
+    let response;
+    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: 'content with & and <tags>',
+        fetchDate: FETCH_DATE,
+        snapshotIds: ['s_escape'],
+      }));
+
+      response = await request.get(`${basePath}/v1/feed/${encodeURIComponent(SERVICE)}/${encodeURIComponent(TERMS)}`);
+    });
+
+    after(() => repository.removeAll());
+
+    it('responds with 200', () => {
+      expect(response.status).to.equal(200);
+    });
+
+    it('URL-encodes spaces and special characters in the self link href', () => {
+      const href = response.text.match(/<link[^>]*rel="self"[^>]*href="([^"]+)"/)[1];
+
+      expect(href).to.include('Service%20B!');
+      expect(href).to.include('Privacy%20Policy');
+      expect(href).to.not.include('Service B!');
+    });
+
+    it('URL-encodes spaces and special characters in entry alternate links', () => {
+      const href = response.text.match(/<link[^>]*rel="alternate"[^>]*href="([^"]+)"/)[1];
+
+      expect(href).to.include('Service%20B!');
+      expect(href).to.include('Privacy%20Policy');
+    });
+  });
+
+  describe('GET /feed/:serviceId/:termsType', () => {
+    const SERVICE = 'service_without_history';
+    const TERMS = 'Terms of Service';
+    const UNKNOWN_TERMS = 'Imprint';
+
+    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: 'first',
+        fetchDate: new Date('2024-01-01T00:00:00Z'),
+        snapshotIds: ['s1'],
+      }));
+      await repository.save(new Version({
+        serviceId: SERVICE,
+        termsType: TERMS,
+        content: 'updated',
+        fetchDate: new Date('2024-02-01T00:00:00Z'),
+        snapshotIds: ['s2'],
+      }));
+    });
+
+    after(() => repository.removeAll());
+
+    context('when the service and terms type match', () => {
+      let response;
+
+      before(async () => {
+        response = await request.get(`${basePath}/v1/feed/${encodeURIComponent(SERVICE)}/${encodeURIComponent(TERMS)}`);
+      });
+
+      it('responds with 200', () => {
+        expect(response.status).to.equal(200);
+      });
+
+      it('includes entries for the combination', () => {
+        const entries = response.text.match(/<entry>/g) || [];
+
+        expect(entries.length).to.be.at.least(1);
+      });
+
+      it('entries only have the expected terms type', () => {
+        const termsTypeTerms = [...response.text.matchAll(/<category[^/]*scheme="tag:opentermsarchive.org,2026:scheme:terms-type"[^/]*term="([^"]+)"/g)]
+          .concat([...response.text.matchAll(/<category[^/]*term="([^"]+)"[^/]*scheme="tag:opentermsarchive.org,2026:scheme:terms-type"/g)])
+          .map(match => match[1]);
+
+        for (const term of termsTypeTerms) {
+          expect(term).to.equal(TERMS);
+        }
+      });
+
+      it('has a feed id that includes both service and terms type', () => {
+        expect(extractTag(response.text, 'id')).to.equal(`tag:opentermsarchive.org,2026:feed:test:${SERVICE}:${TERMS}`);
+      });
+
+      it('has a self link pointing to the combination endpoint', () => {
+        const href = response.text.match(/<link[^>]*rel="self"[^>]*href="([^"]+)"/)[1];
+
+        expect(href).to.match(new RegExp(`/feed/${SERVICE}/${encodeURIComponent(TERMS)}$`));
+      });
+    });
+
+    context('when the service exists but does not declare the terms type', () => {
+      let response;
+
+      before(async () => {
+        response = await request.get(`${basePath}/v1/feed/${encodeURIComponent(SERVICE)}/${encodeURIComponent(UNKNOWN_TERMS)}`);
+      });
+
+      it('responds with 404', () => {
+        expect(response.status).to.equal(404);
+      });
+    });
+
+    context('when the service does not exist', () => {
+      let response;
+
+      before(async () => {
+        response = await request.get(`${basePath}/v1/feed/DoesNotExist/${encodeURIComponent(TERMS)}`);
+      });
+
+      it('responds with 404', () => {
+        expect(response.status).to.equal(404);
+      });
+    });
+  });
 });