@opentermsarchive/engine 16.0.1 → 16.1.0

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

@@ -4,15 +4,16 @@ import GitRepository from './git/index.js';
 import MongoRepository from './mongo/index.js';
 
 export default class RepositoryFactory {
-  static create(params) {
+  static create(params, { readOnly = false } = {}) {
     switch (params.type) {
     case 'git':
       return new GitRepository({
         ...params.git,
         path: path.resolve(process.cwd(), params.git.path),
+        readOnly,
       });
     case 'mongo':
-      return new MongoRepository(params.mongo);
+      return new MongoRepository({ ...params.mongo, readOnly });
     default:
       throw new Error(`Unknown storage repository configuration for type '${params.type}'`);
     }

package/src/archivist/recorder/repositories/git/dataMapper.js

@@ -67,7 +67,8 @@ export function toDomain(commit) {
   }
 
   const [relativeFilePath] = modifiedFilesInCommit;
-  const snapshotIdsMatch = body.match(/\b[0-9a-f]{5,40}\b/g);
+  const bodyWithoutTrailers = Object.keys(trailers).length ? body.split(/\n\n+/).slice(0, -1).join('\n\n') : body; // Trailers, when present, are the last section of the body; their values, such as the hexadecimal segments of a run ID, must not be read as snapshot IDs
+  const snapshotIdsMatch = bodyWithoutTrailers.match(/\b[0-9a-f]{5,40}\b/g);
 
   const [ termsType, documentId ] = path.basename(relativeFilePath, path.extname(relativeFilePath)).split(TERMS_TYPE_AND_DOCUMENT_ID_SEPARATOR);
 

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

@@ -8,42 +8,38 @@ import path from 'path';
 
 import mime from 'mime';
 
+import Git from '../../../../git/index.js';
+import { isPlainPathSegment } from '../../../../git/pathSegment.js';
 import RepositoryInterface from '../interface.js';
 
 import * as DataMapper from './dataMapper.js';
-import Git from './git.js';
 
 const fs = fsApi.promises;
 
 const RECORD_ID_REGEXP = /^[0-9a-f]{7,40}$/i; // Git commit SHA 7 (abbreviated) to 40 (full) hexadecimal characters. Prevent value such as `--output=…` to be parsed as a command-line option
 
-const CONTROL_CHARACTERS_REGEXP = /\p{Cc}/u; // Matches any Unicode "control" character: the C0 range (U+0000 to U+001F), DEL (U+007F) and the C1 range (U+0080 to U+009F), i.e. 65 non-printable characters including NUL. The `u` flag is required for the `\p{...}` property escape to be recognised, otherwise the pattern would match the literal text `p{Cc}`. Legitimate service IDs, terms types and document IDs never contain these, and NUL in particular can truncate a value once it reaches git or the filesystem, so any segment holding one is rejected.
-
-// Keeps hostile values from reaching git, where a pathspec that resolves outside the repository (such as `../foo/*`) aborts with an error that exposes the repository location.
-function isPlainPathSegment(segment) {
-  return segment.length > 0
-    && segment !== '.'
-    && segment !== '..'
-    && !segment.includes('/')
-    && !segment.includes('\\')
-    && !CONTROL_CHARACTERS_REGEXP.test(segment);
-}
-
 function canMatchRecordFilePath(...pathSegments) {
   // A non-string segment means "not provided" (`undefined`, or `false` for an absent document ID) and constrains nothing
   return pathSegments.every(segment => typeof segment !== 'string' || isPlainPathSegment(segment));
 }
 
 export default class GitRepository extends RepositoryInterface {
-  constructor({ path, author, publish, snapshotIdentiferTemplate }) {
+  constructor({ path, author, publish, snapshotIdentiferTemplate, readOnly = false }) {
     super();
     this.path = path;
     this.needsPublication = publish;
+    this.readOnly = readOnly; // Readers share the repository with the tracker, so they must never touch the working tree nor the commit-graph: both race the tracker, and the commit-graph write then fails with `commit-graph.lock: File exists`
     this.git = new Git({ path: this.path, author });
     this.snapshotIdentiferTemplate = snapshotIdentiferTemplate;
   }
 
   async initialize() {
+    if (this.readOnly) {
+      this.git.open();
+
+      return this;
+    }
+
     await this.git.initialize();
     await this.git.cleanUp(); // Drop all uncommitted changes and remove all leftover files that may be present if the process was killed aggressively
     await this.git.writeCommitGraph(); // Create or replace the commit graph with a new one to ensure it's fully consistent
@@ -52,6 +48,8 @@ export default class GitRepository extends RepositoryInterface {
   }
 
   async save(record) {
+    this.#assertWritable('save records');
+
     const { serviceId, termsType, documentId, fetchDate } = record;
 
     if (record.isFirstRecord === undefined || record.isFirstRecord === null) {
@@ -75,6 +73,10 @@ export default class GitRepository extends RepositoryInterface {
   }
 
   async finalize() {
+    if (this.readOnly) {
+      return;
+    }
+
     if (this.needsPublication) {
       await this.git.pushChanges();
     }
@@ -214,31 +216,20 @@ export default class GitRepository extends RepositoryInterface {
     }
   }
 
-  removeAll() {
-    return this.git.destroyHistory();
+  async removeAll() {
+    this.#assertWritable('remove records');
+
+    await this.git.destroyHistory();
   }
 
   async loadRecordContent(record) {
     const relativeFilePath = DataMapper.generateFilePath(record.serviceId, record.termsType, record.documentId, record.mimeType);
 
-    if (record.mimeType != mime.getType('pdf')) {
-      record.content = await this.git.show(`${record.id}:${relativeFilePath}`);
+    const objectPath = `${record.id}:${relativeFilePath}`;
 
-      return;
-    }
-
-    // In case of PDF files, `git show` cannot be used as it converts PDF binary into strings that do not retain the original binary representation
-    // It is impossible to restore the original binary data from the resulting string
-    let pdfBuffer;
-
-    try {
-      await this.git.restore(relativeFilePath, record.id); // Temporarily restore the PDF file to a specific commit
-      pdfBuffer = await fs.readFile(`${this.path}/${relativeFilePath}`); // …read the content
-    } finally {
-      await this.git.restore(relativeFilePath, 'HEAD'); // …and finally restore the file to its most recent state
-    }
-
-    record.content = pdfBuffer;
+    record.content = record.mimeType == mime.getType('pdf')
+      ? await this.git.showBuffer(objectPath) // Binary content is read straight from the object database, so nothing is ever written to the working tree shared with the tracker
+      : await this.git.show(objectPath);
   }
 
   getDiffStats(recordId) {
@@ -308,6 +299,12 @@ export default class GitRepository extends RepositoryInterface {
     return this.git.isTracked(`${this.path}/${DataMapper.generateFilePath(serviceId, termsType, documentId)}`);
   }
 
+  #assertWritable(operation) {
+    if (this.readOnly) {
+      throw new Error(`Cannot ${operation} in read-only repository ${this.path}`);
+    }
+  }
+
   async #toDomain(commit, { deferContentLoading } = {}) {
     if (!commit) {
       return null;

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

@@ -2,18 +2,21 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
-import { expect } from 'chai';
+import { expect, use } from 'chai';
+import chaiAsPromised from 'chai-as-promised';
 import config from 'config';
 import mime from 'mime';
 
+import Git from '../../../../git/index.js';
 import Snapshot from '../../snapshot.js';
 import Version from '../../version.js';
 
 import { TERMS_TYPE_AND_DOCUMENT_ID_SEPARATOR, SNAPSHOT_ID_MARKER, COMMIT_MESSAGE_PREFIXES } from './dataMapper.js';
-import Git from './git.js';
 
 import GitRepository from './index.js';
 
+use(chaiAsPromised);
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 const RECORDER_PATH = path.resolve(__dirname, '../../../../..', config.get('@opentermsarchive/engine.recorder.versions.storage.git.path'));
@@ -395,6 +398,28 @@ describe('GitRepository', () => {
         expect(record.metadata).to.deep.equal(METADATA);
       });
 
+      context('when a metadata value contains hexadecimal segments', () => {
+        let recordWithRunId;
+
+        before(async () => {
+          const { id: recordId } = await subject.save(new Version({
+            serviceId: SERVICE_PROVIDER_ID,
+            termsType: TERMS_TYPE,
+            content: `${CONTENT} (updated)`,
+            fetchDate: FETCH_DATE_LATER,
+            snapshotIds: [SNAPSHOT_ID],
+            mimeType: HTML_MIME_TYPE,
+            metadata: { ...METADATA, 'x-run-id': 'ota-run-189e7be3-60ef-40c7-ac28-81a44288e105' },
+          }));
+
+          recordWithRunId = await subject.findById(recordId);
+        });
+
+        it('returns only the snapshot ID', () => {
+          expect(recordWithRunId.snapshotIds).to.deep.equal([SNAPSHOT_ID]);
+        });
+      });
+
       context('when requested record does not exist', () => {
         it('returns null', async () => {
           expect(await subject.findById('inexistantID')).to.equal(null);
@@ -2063,4 +2088,75 @@ describe('GitRepository', () => {
       });
     });
   });
+
+  context('when read-only', () => {
+    const UNTRACKED_FILE_PATH = `${RECORDER_PATH}/untracked-file.md`;
+    const COMMIT_GRAPH_PATH = `${RECORDER_PATH}/.git/objects/info/commit-graph`;
+
+    let writer;
+    let record;
+
+    before(async () => {
+      writer = new GitRepository({
+        ...config.get('@opentermsarchive/engine.recorder.versions.storage.git'),
+        path: RECORDER_PATH,
+      });
+
+      await writer.git.initialize(); // Bypass GitRepository#initialize, which writes the commit-graph, to check that the read-only repository does not write it either
+      fs.rmSync(COMMIT_GRAPH_PATH, { force: true });
+
+      record = await writer.save(new Version({
+        serviceId: SERVICE_PROVIDER_ID,
+        termsType: TERMS_TYPE,
+        content: CONTENT,
+        fetchDate: FETCH_DATE,
+        snapshotIds: [SNAPSHOT_ID],
+      }));
+
+      fs.writeFileSync(UNTRACKED_FILE_PATH, CONTENT);
+
+      subject = new GitRepository({
+        ...config.get('@opentermsarchive/engine.recorder.versions.storage.git'),
+        path: RECORDER_PATH,
+        readOnly: true,
+      });
+
+      await subject.initialize();
+      await subject.finalize();
+    });
+
+    after(() => writer.removeAll());
+
+    it('reads the records', async () => {
+      const records = await subject.findAll();
+
+      expect(records.map(({ id }) => id)).to.deep.equal([record.id]);
+    });
+
+    it('leaves uncommitted changes untouched', () => {
+      expect(fs.existsSync(UNTRACKED_FILE_PATH)).to.be.true;
+    });
+
+    it('does not write the commit-graph', () => {
+      expect(fs.existsSync(COMMIT_GRAPH_PATH)).to.be.false;
+    });
+
+    it('rejects saving records', async () => {
+      await expect(subject.save(record)).to.be.rejectedWith(Error, /read-only/);
+    });
+
+    it('rejects removing records', async () => {
+      await expect(subject.removeAll()).to.be.rejectedWith(Error, /read-only/);
+    });
+
+    it('rejects opening a missing repository', async () => {
+      const missingRepository = new GitRepository({
+        ...config.get('@opentermsarchive/engine.recorder.versions.storage.git'),
+        path: `${RECORDER_PATH}-missing`,
+        readOnly: true,
+      });
+
+      await expect(missingRepository.initialize()).to.be.rejectedWith(Error, /does not exist/);
+    });
+  });
 });

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

@@ -10,12 +10,13 @@ import RepositoryInterface from '../interface.js';
 import * as DataMapper from './dataMapper.js';
 
 export default class MongoRepository extends RepositoryInterface {
-  constructor({ database: databaseName, collection: collectionName, connectionURI }) {
+  constructor({ database: databaseName, collection: collectionName, connectionURI, readOnly = false }) {
     super();
 
     this.client = new MongoClient(connectionURI);
     this.databaseName = databaseName;
     this.collectionName = collectionName;
+    this.readOnly = readOnly;
   }
 
   async initialize() {
@@ -34,6 +35,8 @@ export default class MongoRepository extends RepositoryInterface {
   }
 
   async save(record) {
+    this.#assertWritable('save records');
+
     const { serviceId, termsType, documentId } = record;
 
     if (record.isFirstRecord === undefined || record.isFirstRecord === null) {
@@ -223,8 +226,16 @@ export default class MongoRepository extends RepositoryInterface {
     }
   }
 
-  removeAll() {
-    return this.collection.deleteMany();
+  async removeAll() {
+    this.#assertWritable('remove records');
+
+    await this.collection.deleteMany();
+  }
+
+  #assertWritable(operation) {
+    if (this.readOnly) {
+      throw new Error(`Cannot ${operation} in read-only repository ${this.databaseName}.${this.collectionName}`);
+    }
   }
 
   async loadRecordContent(record) {

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

@@ -2,7 +2,8 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
-import { expect } from 'chai';
+import { expect, use } from 'chai';
+import chaiAsPromised from 'chai-as-promised';
 import config from 'config';
 import mime from 'mime';
 import { MongoClient, ObjectId } from 'mongodb';
@@ -12,6 +13,8 @@ import Version from '../../version.js';
 
 import MongoRepository from './index.js';
 
+use(chaiAsPromised);
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 const { connectionURI } = config.get('@opentermsarchive/engine.recorder.snapshots.storage.mongo');
@@ -1944,4 +1947,27 @@ describe('MongoRepository', () => {
       });
     });
   });
+
+  context('when read-only', () => {
+    before(() => {
+      subject = new MongoRepository({
+        ...config.get('@opentermsarchive/engine.recorder.versions.storage.mongo'),
+        readOnly: true,
+      });
+    });
+
+    it('rejects saving records', async () => {
+      await expect(subject.save(new Version({
+        serviceId: SERVICE_PROVIDER_ID,
+        termsType: TERMS_TYPE,
+        content: CONTENT,
+        fetchDate: FETCH_DATE,
+        snapshotIds: [SNAPSHOT_ID],
+      }))).to.be.rejectedWith(Error, /read-only/);
+    });
+
+    it('rejects removing records', async () => {
+      await expect(subject.removeAll()).to.be.rejectedWith(Error, /read-only/);
+    });
+  });
 });

package/src/archivist/services/index.js

@@ -2,8 +2,10 @@ import fs from 'fs/promises';
 import path from 'path';
 import { pathToFileURL } from 'url';
 
+import async from 'async';
 import config from 'config';
 
+import Git from '../../git/index.js';
 import * as exposedFilters from '../extract/exposedFilters.js';
 
 import Service from './service.js';
@@ -13,6 +15,8 @@ import Terms from './terms.js';
 export const DECLARATIONS_PATH = './declarations';
 const declarationsPath = path.resolve(process.cwd(), config.get('@opentermsarchive/engine.collectionPath'), DECLARATIONS_PATH);
 
+const MAX_PARALLEL_DECLARATIONS_READS = 5; // Reading declarations at a commit spawns one git process per service; left unbounded, a large collection would exhaust the file descriptors or processes allowed to the engine
+
 const JSON_EXT = '.json';
 const JS_EXT = '.js';
 const HISTORY_SUFFIX = '.history';
@@ -106,10 +110,11 @@ function createWrappedFilter(baseFunction, filterName, filterParams) {
     return;
   }
 
-  if (filterParams || exposedFilters[filterName]) { // Built-in filters always receive their parameters before the context, even when none are declared
+  if (filterParams !== undefined || exposedFilters[filterName]) { // Built-in filters always receive their parameters before the context, even when none are declared
     const wrappedFilter = (webPageDOM, context) => baseFunction(webPageDOM, filterParams, context);
 
     Object.defineProperty(wrappedFilter, 'name', { value: filterName });
+    Object.defineProperty(wrappedFilter, 'declaration', { value: filterParams === undefined ? filterName : { [filterName]: filterParams } }); // Keep the declared form, as the parameters are otherwise only reachable through the closure
 
     return wrappedFilter;
   }
@@ -145,6 +150,45 @@ export function getServiceFilters(serviceFilters, declaredFilters) {
 export async function getDeclaredServicesIds() {
   const fileNames = await fs.readdir(declarationsPath);
 
+  return declaredServicesIdsFromFileNames(fileNames);
+}
+
+export function getDeclarationsCommit() { // Resolves to null when the declarations are not versioned with Git
+  return Git.getHeadSha(declarationsPath);
+}
+
+// Returns the [{ serviceId, termsType }] declared at the given commit of the declarations repository.
+// Reads through git so the answer reflects the declarations exactly as they were at that commit, not as they are on disk; used by crash recovery to derive the coverage of a run that referenced this commit.
+export async function getDeclaredTermsAtCommit(commit) {
+  const fileNames = await Git.listFilesAtCommit(declarationsPath, commit);
+  const serviceIds = declaredServicesIdsFromFileNames(fileNames);
+
+  return declaredTermsOf(serviceIds, async serviceId => {
+    const rawDeclaration = await Git.readFileAtCommit(declarationsPath, commit, `${serviceId}${JSON_EXT}`);
+
+    try {
+      return JSON.parse(rawDeclaration);
+    } catch (error) {
+      throw new Error(`The "${serviceId}" service declaration at commit ${commit} is malformed and cannot be parsed`);
+    }
+  });
+}
+
+export async function getDeclaredTerms() { // Working-tree counterpart of getDeclaredTermsAtCommit; used as approximation when a declarations commit is not reachable anymore
+  return declaredTermsOf(await getDeclaredServicesIds(), loadServiceDeclaration);
+}
+
+async function declaredTermsOf(serviceIds, loadDeclaration) {
+  const declaredTermsPerService = await async.mapLimit(serviceIds, MAX_PARALLEL_DECLARATIONS_READS, async serviceId => {
+    const declaration = await loadDeclaration(serviceId);
+
+    return Object.keys(declaration.terms ?? {}).map(termsType => ({ serviceId, termsType }));
+  });
+
+  return declaredTermsPerService.flat(); // Flattened in serviceIds order to keep the result deterministic regardless of read completion order
+}
+
+function declaredServicesIdsFromFileNames(fileNames) {
   return fileNames
     .filter(fileName => fileName.endsWith(JSON_EXT) && !fileName.includes(`${HISTORY_SUFFIX}${JSON_EXT}`))
     .map(fileName => path.basename(fileName, JSON_EXT));

package/src/archivist/services/index.test.js

@@ -2,10 +2,12 @@ import fs from 'fs/promises';
 import path from 'path';
 
 import { expect, use } from 'chai';
+import config from 'config';
 import sinon from 'sinon';
 import sinonChai from 'sinon-chai';
 
 import expectedServices from '../../../test/fixtures/services.js';
+import Git, { GitObjectNotFoundError } from '../../git/index.js';
 import createWebPageDOM from '../extract/dom.js';
 import * as exposedFilters from '../extract/exposedFilters.js';
 
@@ -13,7 +15,7 @@ import Service from './service.js';
 import SourceDocument from './sourceDocument.js';
 import Terms from './terms.js';
 
-import { getDeclaredServicesIds, loadServiceDeclaration, loadServiceFilters, getServiceFilters, createSourceDocuments, createServiceFromDeclaration, load, loadWithHistory } from './index.js';
+import { getDeclaredServicesIds, getDeclaredTermsAtCommit, loadServiceDeclaration, loadServiceFilters, getServiceFilters, createSourceDocuments, createServiceFromDeclaration, load, loadWithHistory } from './index.js';
 
 use(sinonChai);
 
@@ -151,6 +153,36 @@ describe('Services', () => {
     });
   });
 
+  describe('#getDeclaredTermsAtCommit', () => {
+    const declarationsPath = path.resolve(process.cwd(), config.get('@opentermsarchive/engine.collectionPath'), './declarations');
+
+    afterEach(() => sinon.restore());
+
+    it('returns the terms declared at the given commit, whatever the working tree contains', async function () {
+      this.timeout(10000);
+
+      const commit = await Git.getHeadSha(declarationsPath); // The test declarations are committed in the engine repository itself, so its HEAD reflects them exactly
+      const expected = Object.entries(expectedServices).flatMap(([ serviceId, service ]) => service.getTermsTypes().map(termsType => ({ serviceId, termsType })));
+
+      sinon.stub(fs, 'readdir').resolves(['uncommitted-service.json']); // Make the working tree differ from the commit: it must not be read
+      sinon.stub(fs, 'readFile').resolves(JSON.stringify({ name: 'Uncommitted service', terms: { Imprint: {} } }));
+
+      expect(await getDeclaredTermsAtCommit(commit)).to.have.deep.members(expected);
+    });
+
+    it('throws a GitObjectNotFoundError for an unknown commit', async () => {
+      try {
+        await getDeclaredTermsAtCommit('deadbeefdeadbeefdeadbeefdeadbeefdeadbeef');
+      } catch (error) {
+        expect(error).to.be.an.instanceOf(GitObjectNotFoundError);
+
+        return;
+      }
+
+      expect.fail('No error was thrown');
+    });
+  });
+
   describe('#loadServiceDeclaration', () => {
     let readFile;
 
@@ -310,6 +342,19 @@ describe('Services', () => {
       expect(result[0](null, 'context')).to.equal('foo');
     });
 
+    it('keeps the declared form of filters declared with parameters', () => {
+      const [filter] = getServiceFilters({ paramFilter: (dom, param) => param }, [{ paramFilter: [ 'foo', 'bar' ] }]);
+
+      expect(filter.declaration).to.deep.equal({ paramFilter: [ 'foo', 'bar' ] });
+    });
+
+    it('keeps the name as the declared form of exposed filters declared by string name', () => {
+      const [filterName] = Object.keys(exposedFilters);
+      const [filter] = getServiceFilters({}, [filterName]);
+
+      expect(filter.declaration).to.equal(filterName);
+    });
+
     describe('parameters passed to filters', () => {
       let serviceLoadedFilters;
       let passedDOM;
@@ -348,6 +393,12 @@ describe('Services', () => {
           testParameterPassing({ param1: 'param1', param2: 'param2' });
         });
       });
+
+      context('as a falsy value', () => {
+        it('passes parameters correctly', () => {
+          testParameterPassing(false);
+        });
+      });
     });
   });
 

package/src/archivist/services/sourceDocument.js

@@ -40,8 +40,14 @@ export default class SourceDocument {
   }
 
   clearContent() {
-    this.content = null;
+    this.content = null; // Only the potentially large content is cleared: the MIME type is read after the extraction, to record the tracking results
+  }
+
+  resetObservations() {
+    // mimeType and snapshotId are observations of a single tracking attempt, but they are stored on declaration objects that live for the whole process: without this reset, a failed fetch would expose the previous run's values as if they belonged to the failed attempt.
+    // The proper pattern would be for the fetch and extract pipeline to return its observations instead of mutating the declarations, letting consumers build their records from run-scoped data; this reset contains that debt rather than fixing it.
     this.mimeType = null;
+    this.snapshotId = null;
   }
 
   static extractCssSelectorsFromProperty(property) {
@@ -83,7 +89,7 @@ export default class SourceDocument {
       fetch: this.location,
       select: this.contentSelectors,
       remove: this.insignificantContentSelectors,
-      filter: this.filters ? this.filters.map(filter => filter.name) : undefined,
+      filter: this.filters ? this.filters.map(filter => filter.declaration ?? filter.name) : undefined, // Filters declared with parameters carry their declared form, so that a change of parameters is persisted
       executeClientScripts: this.executeClientScripts,
     };
   }

package/src/archivist/services/sourceDocument.test.js

@@ -214,6 +214,29 @@ describe('SourceDocument', () => {
     });
   });
 
+  describe('#clearContent', () => {
+    it('clears the content but keeps the MIME type', () => {
+      const sourceDocument = new SourceDocument({ location: URL, content: '<html></html>', mimeType: 'text/html' });
+
+      sourceDocument.clearContent();
+
+      expect(sourceDocument.content).to.be.null;
+      expect(sourceDocument.mimeType).to.equal('text/html');
+    });
+  });
+
+  describe('#resetObservations', () => {
+    it('clears the MIME type and the snapshot ID observed by a previous tracking', () => {
+      const sourceDocument = new SourceDocument({ location: URL, mimeType: 'text/html' });
+
+      sourceDocument.snapshotId = 'abc123';
+      sourceDocument.resetObservations();
+
+      expect(sourceDocument.mimeType).to.be.null;
+      expect(sourceDocument.snapshotId).to.be.null;
+    });
+  });
+
   describe('#toPersistence', () => {
     it('converts basic source document declarations into JSON representation', () => {
       const result = new SourceDocument({
@@ -275,5 +298,19 @@ describe('SourceDocument', () => {
 
       expect(result).to.deep.equal(expectedResult);
     });
+
+    it('converts filters declared with parameters to their declared form', () => {
+      const filterWithParameters = () => {};
+
+      Object.defineProperty(filterWithParameters, 'declaration', { value: { removeQueryParams: ['utm_source'] } });
+
+      const result = new SourceDocument({
+        location: URL,
+        contentSelectors: 'body',
+        filters: [ filterWithParameters, function filterSomething() {} ],
+      }).toPersistence();
+
+      expect(result.filter).to.deep.equal([{ removeQueryParams: ['utm_source'] }, 'filterSomething' ]);
+    });
   });
 });

package/src/archivist/tracking-results/errors.js

@@ -0,0 +1,5 @@
+/* eslint-disable max-classes-per-file */ // Grouping the module's error types here is the point of an errors module
+
+export class MissingCollectionIdError extends Error {} // The collection metadata does not provide the id that identifies the collection in every persisted run; tracking-results cannot record without it
+
+export class UnreadableRunError extends Error {} // The persisted run.json cannot be read as a valid Run (corrupted JSON, incompatible schema from another engine version): recovery is impossible by construction, unlike infrastructure failures for which a retry is meaningful