@foss.global/forgefixtures 0.2.0

package/ts/classes.giteaseed.ts

@@ -0,0 +1,486 @@
+import * as plugins from './plugins.js';
+import * as responses from './responses.js';
+import type { GiteaFixture } from './classes.giteafixture.js';
+import type { ForgeFixtureHttpClient } from './classes.httpclient.js';
+import type {
+  IGiteaSeedFile,
+  IGiteaSeedIssue,
+  IGiteaSeedManifest,
+  IGiteaSeedManifestAuthor,
+  IGiteaSeedManifestRepository,
+  IGiteaSeedPullRequest,
+  IGiteaSeedRepository,
+  IGiteaSeedSpec,
+  TGiteaVisibility,
+} from './interfaces.giteaseed.js';
+
+const defaultBranch = 'main';
+const lfsMediaType = 'application/vnd.git-lfs+json';
+const namePattern = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,38}$/;
+const colorPattern = /^#[0-9a-f]{6}$/;
+
+interface ISeededIssueRef {
+  key: string;
+  kind: 'issue' | 'pullRequest';
+  number: number;
+}
+
+interface ISeededRepositoryRefs {
+  spec: IGiteaSeedRepository;
+  labels: Map<string, number>;
+  milestones: Map<string, { id: number; state: 'open' | 'closed' }>;
+  tags: Array<{ name: string; commitSha: string }>;
+  items: ISeededIssueRef[];
+  releases: Array<{ tagName: string; id: number; draft: boolean; prerelease: boolean }>;
+  lfsObjects: Array<{ path: string; oid: string; size: number }>;
+}
+
+const segment = (valueArg: string) => encodeURIComponent(valueArg);
+
+/** Rejects inconsistent specs before the first mutation. */
+export const validateGiteaSeedSpec = (specArg: IGiteaSeedSpec): void => {
+  const fail = (messageArg: string): never => {
+    throw new TypeError(`Invalid Gitea seed spec: ${messageArg}`);
+  };
+  const unique = (valuesArg: string[], whatArg: string) => {
+    const seen = new Set<string>();
+    for (const value of valuesArg) {
+      if (seen.has(value.toLowerCase())) fail(`duplicate ${whatArg} "${value}"`);
+      seen.add(value.toLowerCase());
+    }
+  };
+  const users = new Set(specArg.users.map((userArg) => userArg.username));
+  const organizations = new Set(specArg.organizations.map((organizationArg) => organizationArg.name));
+  for (const name of [...users, ...organizations]) if (!namePattern.test(name)) fail(`malformed name "${name}"`);
+  unique([...users, ...organizations], 'user or organization');
+  for (const username of specArg.deleteUsers ?? []) if (!users.has(username)) fail(`cannot delete unknown user "${username}"`);
+  unique(specArg.repositories.map((repositoryArg) => `${repositoryArg.owner}/${repositoryArg.name}`), 'repository');
+  const deleted = new Set(specArg.deleteUsers ?? []);
+  for (const repository of specArg.repositories) {
+    const where = `${repository.owner}/${repository.name}`;
+    if (!namePattern.test(repository.name)) fail(`malformed repository name "${where}"`);
+    if (!users.has(repository.owner) && !organizations.has(repository.owner)) fail(`${where} has an unknown owner`);
+    if (deleted.has(repository.owner)) fail(`${where} is owned by a user scheduled for deletion`);
+    const knownUser = (usernameArg: string) => {
+      if (!users.has(usernameArg)) fail(`${where} references unknown user "${usernameArg}"`);
+    };
+    for (const collaborator of repository.collaborators ?? []) knownUser(collaborator.username);
+    const lfsPaths = (repository.lfsObjects ?? []).map((fileArg) => fileArg.path);
+    const filePaths = [...(repository.files ?? []).map((fileArg) => fileArg.path), ...lfsPaths];
+    unique(filePaths, `${where} file`);
+    if (filePaths.includes('README.md')) fail(`${where} cannot seed README.md; auto-initialisation creates it`);
+    if (lfsPaths.length > 0 && filePaths.includes('.gitattributes')) fail(`${where} cannot combine LFS objects with its own .gitattributes`);
+    const branches = new Set([defaultBranch]);
+    for (const branch of repository.branches ?? []) {
+      if (branches.has(branch.name)) fail(`${where} declares branch "${branch.name}" twice`);
+      if (!branches.has(branch.from ?? defaultBranch)) fail(`${where} branch "${branch.name}" starts from an undeclared branch`);
+      branches.add(branch.name);
+    }
+    const labels = new Set((repository.labels ?? []).map((labelArg) => {
+      if (!colorPattern.test(labelArg.color)) fail(`${where} label "${labelArg.name}" needs a lowercase #rrggbb color`);
+      return labelArg.name;
+    }));
+    unique([...labels], `${where} label`);
+    const milestones = new Set((repository.milestones ?? []).map((milestoneArg) => milestoneArg.title));
+    unique([...milestones], `${where} milestone`);
+    unique((repository.tags ?? []).map((tagArg) => tagArg.name), `${where} tag`);
+    unique((repository.issuesAndPullRequests ?? []).map((itemArg) => itemArg.key), `${where} issue key`);
+    for (const item of repository.issuesAndPullRequests ?? []) {
+      knownUser(item.author);
+      for (const label of item.labels ?? []) if (!labels.has(label)) fail(`${where} ${item.key} uses unknown label "${label}"`);
+      if (item.kind === 'issue') {
+        if (item.milestone !== undefined && !milestones.has(item.milestone)) fail(`${where} ${item.key} uses an unknown milestone`);
+        for (const assignee of item.assignees ?? []) knownUser(assignee);
+        for (const comment of item.comments ?? []) knownUser(comment.author);
+      } else if (!branches.has(item.head) || !branches.has(item.base) || item.head === item.base) {
+        fail(`${where} ${item.key} needs two distinct declared branches`);
+      }
+    }
+  }
+};
+
+/**
+ * Seeds a running {@link GiteaFixture} through Gitea's documented REST and
+ * Git LFS APIs, then reads everything back into a ground-truth manifest.
+ */
+export class GiteaSeedBuilder {
+  readonly #fixture: GiteaFixture;
+
+  constructor(fixtureArg: GiteaFixture) {
+    this.#fixture = fixtureArg;
+  }
+
+  public async apply(specArg: IGiteaSeedSpec): Promise<IGiteaSeedManifest> {
+    validateGiteaSeedSpec(specArg);
+    const runtime = this.#fixture.runtime;
+    const http = this.#fixture.http;
+    const users = new Map<string, number>();
+    for (const user of specArg.users) {
+      const created = await this.#api(http, 'POST', '/api/v1/admin/users', [201], {
+        json: {
+          username: user.username,
+          email: `${user.username.toLowerCase()}@example.com`,
+          password: plugins.crypto.randomBytes(24).toString('base64url'),
+          must_change_password: false,
+          ...(user.fullName === undefined ? {} : { full_name: user.fullName }),
+          visibility: user.visibility ?? 'public',
+        },
+      });
+      users.set(user.username, responses.integer(responses.field(created, 'id', 'created user'), 'user id'));
+    }
+    const organizations: IGiteaSeedManifest['organizations'] = [];
+    for (const organization of specArg.organizations) {
+      const created = await this.#api(http, 'POST', '/api/v1/orgs', [201], {
+        json: { username: organization.name, visibility: organization.visibility },
+      });
+      organizations.push({
+        name: organization.name,
+        id: responses.integer(responses.field(created, 'id', 'created organization'), 'organization id'),
+        visibility: this.#visibility(responses.field(created, 'visibility', 'created organization')),
+      });
+    }
+    const organizationNames = new Set(specArg.organizations.map((organizationArg) => organizationArg.name));
+    const seeded: ISeededRepositoryRefs[] = [];
+    for (const repository of specArg.repositories) {
+      seeded.push(await this.#seedRepository(http, repository, organizationNames.has(repository.owner)));
+    }
+    for (const username of specArg.deleteUsers ?? []) {
+      await this.#api(http, 'DELETE', `/api/v1/admin/users/${segment(username)}`, [204]);
+    }
+    const deleted = new Set(specArg.deleteUsers ?? []);
+    const repositories: IGiteaSeedManifestRepository[] = [];
+    for (const refs of seeded) repositories.push(await this.#readBack(http, refs));
+    return {
+      baseUrl: runtime.baseUrl,
+      version: runtime.version,
+      users: [...users].map(([username, id]) => ({ username, id, deleted: deleted.has(username) })),
+      organizations,
+      repositories,
+    };
+  }
+
+  async #seedRepository(
+    httpArg: ForgeFixtureHttpClient,
+    specArg: IGiteaSeedRepository,
+    ownedByOrganizationArg: boolean,
+  ): Promise<ISeededRepositoryRefs> {
+    const repoPath = `/api/v1/repos/${segment(specArg.owner)}/${segment(specArg.name)}`;
+    await this.#api(
+      httpArg, 'POST',
+      ownedByOrganizationArg ? `/api/v1/orgs/${segment(specArg.owner)}/repos` : `/api/v1/admin/users/${segment(specArg.owner)}/repos`,
+      [201],
+      {
+        json: {
+          name: specArg.name, private: specArg.private, description: specArg.description ?? '',
+          auto_init: true, default_branch: defaultBranch, readme: 'Default',
+        },
+      },
+    );
+    for (const collaborator of specArg.collaborators ?? []) {
+      await this.#api(httpArg, 'PUT', `${repoPath}/collaborators/${segment(collaborator.username)}`, [204], {
+        json: { permission: collaborator.permission },
+      });
+    }
+    const refs: ISeededRepositoryRefs = {
+      spec: specArg, labels: new Map(), milestones: new Map(), tags: [], items: [], releases: [], lfsObjects: [],
+    };
+    for (const lfsObject of specArg.lfsObjects ?? []) {
+      refs.lfsObjects.push({ path: lfsObject.path, ...await this.#uploadLfsObject(httpArg, specArg, lfsObject.content) });
+    }
+    const defaultFiles: IGiteaSeedFile[] = [...(specArg.files ?? [])];
+    if (refs.lfsObjects.length > 0) {
+      defaultFiles.push({
+        path: '.gitattributes',
+        content: refs.lfsObjects.map((objectArg) => `${objectArg.path} filter=lfs diff=lfs merge=lfs -text\n`).join(''),
+      });
+      for (const object of refs.lfsObjects) {
+        defaultFiles.push({
+          path: object.path,
+          content: `version https://git-lfs.github.com/spec/v1\noid sha256:${object.oid}\nsize ${object.size}\n`,
+        });
+      }
+    }
+    if (defaultFiles.length > 0) {
+      await this.#commitFiles(httpArg, repoPath, defaultFiles, { branch: defaultBranch }, 'Seed default branch files');
+    }
+    for (const branch of specArg.branches ?? []) {
+      await this.#commitFiles(httpArg, repoPath, branch.files, {
+        branch: branch.from ?? defaultBranch, new_branch: branch.name,
+      }, `Seed branch ${branch.name}`);
+    }
+    for (const label of specArg.labels ?? []) {
+      const created = await this.#api(httpArg, 'POST', `${repoPath}/labels`, [201], {
+        json: { name: label.name, color: label.color, description: label.description ?? '' },
+      });
+      refs.labels.set(label.name, responses.integer(responses.field(created, 'id', 'created label'), 'label id'));
+    }
+    for (const milestone of specArg.milestones ?? []) {
+      const created = await this.#api(httpArg, 'POST', `${repoPath}/milestones`, [201], {
+        json: { title: milestone.title, description: milestone.description ?? '', state: milestone.state ?? 'open' },
+      });
+      refs.milestones.set(milestone.title, {
+        id: responses.integer(responses.field(created, 'id', 'created milestone'), 'milestone id'),
+        state: this.#state(responses.field(created, 'state', 'created milestone')),
+      });
+    }
+    for (const tag of specArg.tags ?? []) {
+      const created = await this.#api(httpArg, 'POST', `${repoPath}/tags`, [200, 201], {
+        json: { tag_name: tag.name, target: tag.target, message: tag.message ?? '' },
+      });
+      refs.tags.push({ name: tag.name, commitSha: this.#tagCommitSha(created) });
+    }
+    for (const item of specArg.issuesAndPullRequests ?? []) {
+      refs.items.push(item.kind === 'issue'
+        ? await this.#seedIssue(httpArg, repoPath, refs, item)
+        : await this.#seedPullRequest(httpArg, repoPath, refs, item));
+    }
+    for (const release of specArg.releases ?? []) {
+      const created = await this.#api(httpArg, 'POST', `${repoPath}/releases`, [201], {
+        json: {
+          tag_name: release.tagName, target_commitish: release.target, name: release.name, body: release.body ?? '',
+          draft: release.draft ?? false, prerelease: release.prerelease ?? false,
+        },
+      });
+      refs.releases.push({
+        tagName: release.tagName,
+        id: responses.integer(responses.field(created, 'id', 'created release'), 'release id'),
+        draft: responses.boolean(responses.field(created, 'draft', 'created release'), 'release draft'),
+        prerelease: responses.boolean(responses.field(created, 'prerelease', 'created release'), 'release prerelease'),
+      });
+    }
+    return refs;
+  }
+
+  async #seedIssue(
+    httpArg: ForgeFixtureHttpClient,
+    repoPathArg: string,
+    refsArg: ISeededRepositoryRefs,
+    issueArg: IGiteaSeedIssue,
+  ): Promise<ISeededIssueRef> {
+    const created = await this.#api(httpArg, 'POST', `${repoPathArg}/issues`, [201], {
+      sudo: issueArg.author, json: { title: issueArg.title, body: issueArg.body ?? '' },
+    });
+    const number = responses.integer(responses.field(created, 'number', 'created issue'), 'issue number');
+    const issuePath = `${repoPathArg}/issues/${number}`;
+    for (const comment of issueArg.comments ?? []) {
+      await this.#api(httpArg, 'POST', `${issuePath}/comments`, [201], { sudo: comment.author, json: { body: comment.body } });
+    }
+    await this.#applyLabels(httpArg, issuePath, refsArg, issueArg.labels);
+    const edit: Record<string, unknown> = {};
+    if (issueArg.milestone !== undefined) edit.milestone = refsArg.milestones.get(issueArg.milestone)!.id;
+    if (issueArg.assignees !== undefined) edit.assignees = issueArg.assignees;
+    if (issueArg.state === 'closed') edit.state = 'closed';
+    if (Object.keys(edit).length > 0) await this.#api(httpArg, 'PATCH', issuePath, [201], { json: edit });
+    return { key: issueArg.key, kind: 'issue', number };
+  }
+
+  async #seedPullRequest(
+    httpArg: ForgeFixtureHttpClient,
+    repoPathArg: string,
+    refsArg: ISeededRepositoryRefs,
+    pullArg: IGiteaSeedPullRequest,
+  ): Promise<ISeededIssueRef> {
+    const created = await this.#api(httpArg, 'POST', `${repoPathArg}/pulls`, [201], {
+      sudo: pullArg.author, json: { title: pullArg.title, body: pullArg.body ?? '', head: pullArg.head, base: pullArg.base },
+    });
+    const number = responses.integer(responses.field(created, 'number', 'created pull request'), 'pull request number');
+    await this.#applyLabels(httpArg, `${repoPathArg}/issues/${number}`, refsArg, pullArg.labels);
+    if (pullArg.state === 'closed') {
+      await this.#api(httpArg, 'PATCH', `${repoPathArg}/pulls/${number}`, [201], { json: { state: 'closed' } });
+    }
+    return { key: pullArg.key, kind: 'pullRequest', number };
+  }
+
+  async #applyLabels(
+    httpArg: ForgeFixtureHttpClient,
+    issuePathArg: string,
+    refsArg: ISeededRepositoryRefs,
+    labelsArg: string[] | undefined,
+  ): Promise<void> {
+    if (!labelsArg || labelsArg.length === 0) return;
+    await this.#api(httpArg, 'POST', `${issuePathArg}/labels`, [200], {
+      json: { labels: labelsArg.map((labelArg) => refsArg.labels.get(labelArg)!) },
+    });
+  }
+
+  async #commitFiles(
+    httpArg: ForgeFixtureHttpClient,
+    repoPathArg: string,
+    filesArg: IGiteaSeedFile[],
+    branchArg: { branch: string; new_branch?: string },
+    messageArg: string,
+  ): Promise<void> {
+    await this.#api(httpArg, 'POST', `${repoPathArg}/contents`, [201], {
+      json: {
+        ...branchArg,
+        message: messageArg,
+        files: filesArg.map((fileArg) => ({
+          operation: 'create',
+          path: fileArg.path,
+          content: Buffer.from(fileArg.content, 'utf8').toString('base64'),
+        })),
+      },
+    });
+  }
+
+  /** Uploads one object through the Git LFS batch API using the administrator's token as password. */
+  async #uploadLfsObject(
+    httpArg: ForgeFixtureHttpClient,
+    repositoryArg: IGiteaSeedRepository,
+    contentArg: string,
+  ): Promise<{ oid: string; size: number }> {
+    const content = Buffer.from(contentArg, 'utf8');
+    const oid = plugins.crypto.createHash('sha256').update(content).digest('hex');
+    const size = content.byteLength;
+    const runtime = this.#fixture.runtime;
+    const basic = `Basic ${Buffer.from(`${runtime.admin.username}:${runtime.admin.token}`).toString('base64')}`;
+    const batch = await httpArg.requestJson({
+      method: 'POST',
+      url: `/${segment(repositoryArg.owner)}/${segment(repositoryArg.name)}.git/info/lfs/objects/batch`,
+      headers: { accept: lfsMediaType, 'content-type': lfsMediaType, authorization: basic },
+      body: Buffer.from(JSON.stringify({ operation: 'upload', transfers: ['basic'], objects: [{ oid, size }] })),
+      expectedStatus: [200],
+    });
+    const objects = responses.array(responses.field(batch, 'objects', 'LFS batch response'), 'LFS batch objects');
+    if (objects.length !== 1) throw new Error('The LFS batch response does not describe exactly one object.');
+    const object = responses.record(objects[0], 'LFS batch object');
+    if (object.oid !== oid || object.size !== size || object.error !== undefined) {
+      throw new Error(`The LFS batch refused object ${oid}.`);
+    }
+    const actions = object.actions === undefined ? {} : responses.record(object.actions, 'LFS actions');
+    const actionHeaders = (actionArg: Record<string, unknown>): Record<string, string> => {
+      const headers: Record<string, string> = {};
+      if (actionArg.header === undefined) return headers;
+      for (const [name, value] of Object.entries(responses.record(actionArg.header, 'LFS action header'))) {
+        headers[name] = responses.text(value, `LFS action header ${name}`);
+      }
+      return headers;
+    };
+    if (actions.upload !== undefined) {
+      const upload = responses.record(actions.upload, 'LFS upload action');
+      await httpArg.request({
+        method: 'PUT', url: responses.text(upload.href, 'LFS upload href'),
+        headers: { ...actionHeaders(upload), 'content-type': 'application/octet-stream' },
+        body: content, expectedStatus: [200],
+      });
+    }
+    if (actions.verify !== undefined) {
+      const verify = responses.record(actions.verify, 'LFS verify action');
+      await httpArg.request({
+        method: 'POST', url: responses.text(verify.href, 'LFS verify href'),
+        headers: { ...actionHeaders(verify), accept: lfsMediaType, 'content-type': lfsMediaType },
+        body: Buffer.from(JSON.stringify({ oid, size })), expectedStatus: [200],
+      });
+    }
+    return { oid, size };
+  }
+
+  async #readBack(httpArg: ForgeFixtureHttpClient, refsArg: ISeededRepositoryRefs): Promise<IGiteaSeedManifestRepository> {
+    const specArg = refsArg.spec;
+    const repoPath = `/api/v1/repos/${segment(specArg.owner)}/${segment(specArg.name)}`;
+    const repository = responses.record(await this.#api(httpArg, 'GET', repoPath, [200]), 'repository');
+    const owner = responses.record(repository.owner, 'repository owner');
+    const branches: IGiteaSeedManifestRepository['branches'] = [];
+    for (const name of [defaultBranch, ...(specArg.branches ?? []).map((branchArg) => branchArg.name)]) {
+      const branch = await this.#api(httpArg, 'GET', `${repoPath}/branches/${segment(name)}`, [200]);
+      branches.push({ name, commitSha: responses.text(responses.field(responses.field(branch, 'commit', 'branch'), 'id', 'branch commit'), 'branch commit id') });
+    }
+    const issues: IGiteaSeedManifestRepository['issues'] = [];
+    const pullRequests: IGiteaSeedManifestRepository['pullRequests'] = [];
+    for (const item of refsArg.items) {
+      if (item.kind === 'issue') {
+        const issue = responses.record(await this.#api(httpArg, 'GET', `${repoPath}/issues/${item.number}`, [200]), 'issue');
+        const comments = responses.array(await this.#api(httpArg, 'GET', `${repoPath}/issues/${item.number}/comments`, [200]), 'comments');
+        const milestone = issue.milestone === null || issue.milestone === undefined
+          ? null
+          : responses.text(responses.field(issue.milestone, 'title', 'issue milestone'), 'milestone title');
+        issues.push({
+          key: item.key,
+          id: responses.integer(issue.id, 'issue id'),
+          number: responses.integer(issue.number, 'issue number'),
+          state: this.#state(issue.state),
+          author: this.#author(issue.user),
+          labels: responses.array(issue.labels ?? [], 'issue labels')
+            .map((labelArg) => responses.text(responses.field(labelArg, 'name', 'issue label'), 'label name')),
+          milestone,
+          assignees: responses.array(issue.assignees ?? [], 'issue assignees').map((assigneeArg) => this.#author(assigneeArg).login),
+          comments: comments.map((commentArg) => ({
+            id: responses.integer(responses.field(commentArg, 'id', 'comment'), 'comment id'),
+            author: this.#author(responses.field(commentArg, 'user', 'comment')),
+          })),
+        });
+      } else {
+        const pull = responses.record(await this.#api(httpArg, 'GET', `${repoPath}/pulls/${item.number}`, [200]), 'pull request');
+        const head = responses.record(pull.head, 'pull request head');
+        const base = responses.record(pull.base, 'pull request base');
+        pullRequests.push({
+          key: item.key,
+          id: responses.integer(pull.id, 'pull request id'),
+          number: responses.integer(pull.number, 'pull request number'),
+          state: this.#state(pull.state),
+          author: this.#author(pull.user),
+          head: responses.text(head.ref, 'pull request head ref'),
+          base: responses.text(base.ref, 'pull request base ref'),
+          headSha: responses.text(head.sha, 'pull request head sha'),
+        });
+      }
+    }
+    return {
+      owner: specArg.owner,
+      name: specArg.name,
+      fullName: responses.text(repository.full_name, 'repository full name'),
+      id: responses.integer(repository.id, 'repository id'),
+      ownerId: responses.integer(owner.id, 'repository owner id'),
+      private: responses.boolean(repository.private, 'repository private'),
+      internal: responses.boolean(repository.internal, 'repository internal'),
+      defaultBranch: responses.text(repository.default_branch, 'repository default branch'),
+      htmlUrl: responses.text(repository.html_url, 'repository html url'),
+      cloneUrl: responses.text(repository.clone_url, 'repository clone url'),
+      branches,
+      tags: refsArg.tags,
+      labels: [...refsArg.labels].map(([name, id]) => ({ name, id })),
+      milestones: [...refsArg.milestones].map(([title, milestone]) => ({ title, ...milestone })),
+      issues,
+      pullRequests,
+      releases: refsArg.releases,
+      lfsObjects: refsArg.lfsObjects,
+    };
+  }
+
+  /** Tag responses carry the target commit as `commit.sha`. */
+  #tagCommitSha(tagArg: unknown): string {
+    return responses.text(responses.field(responses.field(tagArg, 'commit', 'tag'), 'sha', 'tag commit'), 'tag commit sha');
+  }
+
+  #author(userArg: unknown): IGiteaSeedManifestAuthor {
+    const user = responses.record(userArg, 'user');
+    return { id: responses.integer(user.id, 'user id'), login: responses.text(user.login, 'user login') };
+  }
+
+  #state(valueArg: unknown): 'open' | 'closed' {
+    if (valueArg !== 'open' && valueArg !== 'closed') throw new Error('Expected state to be open or closed.');
+    return valueArg;
+  }
+
+  #visibility(valueArg: unknown): TGiteaVisibility {
+    if (valueArg !== 'public' && valueArg !== 'limited' && valueArg !== 'private') {
+      throw new Error('Expected visibility to be public, limited or private.');
+    }
+    return valueArg;
+  }
+
+  async #api(
+    httpArg: ForgeFixtureHttpClient,
+    methodArg: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+    pathArg: string,
+    expectedStatusArg: number[],
+    optionsArg: { json?: unknown; sudo?: string } = {},
+  ): Promise<unknown> {
+    const headers: Record<string, string> = { authorization: `token ${this.#fixture.runtime.admin.token}` };
+    if (optionsArg.sudo !== undefined) headers.sudo = optionsArg.sudo;
+    return httpArg.requestJson({
+      method: methodArg, url: pathArg, headers, expectedStatus: expectedStatusArg,
+      ...(optionsArg.json === undefined ? {} : { json: optionsArg.json }),
+    });
+  }
+}