@foss.global/forgefixtures 0.2.0

package/ts/classes.gitlabseed.ts

@@ -0,0 +1,502 @@
+import * as plugins from './plugins.js';
+import * as responses from './responses.js';
+import type { GitlabFixture } from './classes.gitlabfixture.js';
+import type { ForgeFixtureHttpClient } from './classes.httpclient.js';
+import type {
+  IGitlabSeedFile,
+  IGitlabSeedIssue,
+  IGitlabSeedManifest,
+  IGitlabSeedManifestAuthor,
+  IGitlabSeedManifestProject,
+  IGitlabSeedMergeRequest,
+  IGitlabSeedProject,
+  IGitlabSeedSpec,
+  TGitlabAccessLevel,
+  TGitlabVisibility,
+} from './interfaces.gitlabseed.js';
+
+const defaultBranch = 'main';
+const pathPattern = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,254}$/;
+const colorPattern = /^#[0-9a-f]{6}$/;
+const accessLevels: Record<TGitlabAccessLevel, number> = { guest: 10, reporter: 20, developer: 30, maintainer: 40, owner: 50 };
+const userDeletionTimeoutMs = 5 * 60 * 1000;
+const projectAccessTimeoutMs = 2 * 60 * 1000;
+
+interface ISeededItemRef {
+  key: string;
+  kind: 'issue' | 'mergeRequest';
+  iid: number;
+}
+
+interface ISeededProjectRefs {
+  spec: IGitlabSeedProject;
+  id: number;
+  labels: Map<string, number>;
+  milestones: Map<string, { id: number; iid: number; state: 'active' | 'closed' }>;
+  tags: Array<{ name: string; commitSha: string }>;
+  items: ISeededItemRef[];
+  releases: Array<{ tagName: string; name: string }>;
+  /** Users already seen to have access to the project. */
+  accessibleTo: Set<string>;
+}
+
+const sleep = (msArg: number) => new Promise<void>((resolveArg) => setTimeout(resolveArg, msArg));
+
+/** Rejects inconsistent specs before the first mutation. */
+export const validateGitlabSeedSpec = (specArg: IGitlabSeedSpec): void => {
+  const fail = (messageArg: string): never => {
+    throw new TypeError(`Invalid GitLab 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));
+  for (const username of users) if (!pathPattern.test(username) || username.toLowerCase() === 'root') fail(`malformed or reserved username "${username}"`);
+  const groups = new Set<string>();
+  for (const group of specArg.groups) {
+    if (!pathPattern.test(group.path)) fail(`malformed group path "${group.path}"`);
+    if (group.parent !== undefined && !groups.has(group.parent)) fail(`group "${group.path}" names a parent that is not declared before it`);
+    const fullPath = group.parent === undefined ? group.path : `${group.parent}/${group.path}`;
+    if (groups.has(fullPath)) fail(`duplicate group "${fullPath}"`);
+    groups.add(fullPath);
+    for (const member of group.members ?? []) if (!users.has(member.username)) fail(`group "${fullPath}" references unknown user "${member.username}"`);
+  }
+  unique([...users, ...[...groups].filter((pathArg) => !pathArg.includes('/'))], 'top-level namespace');
+  const deleted = new Set(specArg.deleteUsers ?? []);
+  for (const username of deleted) if (!users.has(username)) fail(`cannot delete unknown user "${username}"`);
+  unique(specArg.projects.map((projectArg) => `${projectArg.namespace}/${projectArg.path}`), 'project');
+  for (const project of specArg.projects) {
+    const where = `${project.namespace}/${project.path}`;
+    if (!pathPattern.test(project.path)) fail(`malformed project path "${where}"`);
+    if (!groups.has(project.namespace) && !users.has(project.namespace)) fail(`${where} has an unknown namespace`);
+    if (deleted.has(project.namespace)) fail(`${where} belongs to a user scheduled for deletion`);
+    const knownUser = (usernameArg: string) => {
+      if (!users.has(usernameArg)) fail(`${where} references unknown user "${usernameArg}"`);
+    };
+    for (const member of project.members ?? []) knownUser(member.username);
+    const filePaths = (project.files ?? []).map((fileArg) => fileArg.path);
+    unique(filePaths, `${where} file`);
+    if (filePaths.includes('README.md')) fail(`${where} cannot seed README.md; initialisation creates it`);
+    const branches = new Set([defaultBranch]);
+    for (const branch of project.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((project.labels ?? []).map((labelArg) => {
+      if (!colorPattern.test(labelArg.color)) fail(`${where} label "${labelArg.name}" needs a lowercase #rrggbb color`);
+      if (labelArg.name.includes(',')) fail(`${where} label "${labelArg.name}" cannot contain a comma`);
+      return labelArg.name;
+    }));
+    unique([...labels], `${where} label`);
+    const milestones = new Set((project.milestones ?? []).map((milestoneArg) => milestoneArg.title));
+    unique([...milestones], `${where} milestone`);
+    unique((project.tags ?? []).map((tagArg) => tagArg.name), `${where} tag`);
+    unique((project.issuesAndMergeRequests ?? []).map((itemArg) => itemArg.key), `${where} item key`);
+    for (const item of project.issuesAndMergeRequests ?? []) {
+      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 note of item.notes ?? []) knownUser(note.author);
+      } else if (!branches.has(item.sourceBranch) || !branches.has(item.targetBranch) || item.sourceBranch === item.targetBranch) {
+        fail(`${where} ${item.key} needs two distinct declared branches`);
+      }
+    }
+  }
+};
+
+/**
+ * Seeds a running {@link GitlabFixture} through GitLab's documented REST API,
+ * then reads everything back into a ground-truth manifest.
+ */
+export class GitlabSeedBuilder {
+  readonly #fixture: GitlabFixture;
+
+  constructor(fixtureArg: GitlabFixture) {
+    this.#fixture = fixtureArg;
+  }
+
+  public async apply(specArg: IGitlabSeedSpec): Promise<IGitlabSeedManifest> {
+    validateGitlabSeedSpec(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/v4/users', [201], {
+        json: {
+          username: user.username,
+          name: user.name ?? user.username,
+          email: `${user.username.toLowerCase()}@example.com`,
+          password: plugins.crypto.randomBytes(24).toString('base64url'),
+          skip_confirmation: true,
+        },
+      });
+      users.set(user.username, responses.integer(responses.field(created, 'id', 'created user'), 'user id'));
+    }
+    const groups = new Map<string, number>();
+    const manifestGroups: IGitlabSeedManifest['groups'] = [];
+    for (const group of specArg.groups) {
+      const parentId = group.parent === undefined ? null : groups.get(group.parent)!;
+      const created = responses.record(await this.#api(http, 'POST', '/api/v4/groups', [201], {
+        json: { name: group.path, path: group.path, visibility: group.visibility, ...(parentId === null ? {} : { parent_id: parentId }) },
+      }), 'created group');
+      const id = responses.integer(created.id, 'group id');
+      const fullPath = responses.text(created.full_path, 'group full path');
+      groups.set(fullPath, id);
+      for (const member of group.members ?? []) {
+        await this.#api(http, 'POST', `/api/v4/groups/${id}/members`, [201], {
+          json: { user_id: users.get(member.username)!, access_level: accessLevels[member.accessLevel] },
+        });
+      }
+      manifestGroups.push({
+        fullPath, id,
+        parentId: created.parent_id === null ? null : responses.integer(created.parent_id, 'group parent id'),
+        visibility: this.#visibility(created.visibility),
+      });
+    }
+    const seeded: ISeededProjectRefs[] = [];
+    for (const project of specArg.projects) seeded.push(await this.#seedProject(http, project, groups, users));
+    for (const username of specArg.deleteUsers ?? []) await this.#deleteUser(http, users.get(username)!);
+    const deleted = new Set(specArg.deleteUsers ?? []);
+    const projects: IGitlabSeedManifestProject[] = [];
+    for (const refs of seeded) projects.push(await this.#readBack(http, refs));
+    return {
+      baseUrl: runtime.baseUrl,
+      version: runtime.version,
+      users: [...users].map(([username, id]) => ({ username, id, deleted: deleted.has(username) })),
+      groups: manifestGroups,
+      projects,
+    };
+  }
+
+  async #seedProject(
+    httpArg: ForgeFixtureHttpClient,
+    specArg: IGitlabSeedProject,
+    groupsArg: Map<string, number>,
+    usersArg: Map<string, number>,
+  ): Promise<ISeededProjectRefs> {
+    const body = {
+      name: specArg.path, path: specArg.path, visibility: specArg.visibility, description: specArg.description ?? '',
+      initialize_with_readme: true, default_branch: defaultBranch,
+    };
+    const groupId = groupsArg.get(specArg.namespace);
+    const created = groupId !== undefined
+      ? await this.#api(httpArg, 'POST', '/api/v4/projects', [201], { json: { ...body, namespace_id: groupId } })
+      : await this.#api(httpArg, 'POST', `/api/v4/projects/user/${usersArg.get(specArg.namespace)!}`, [201], { json: body });
+    const id = responses.integer(responses.field(created, 'id', 'created project'), 'project id');
+    const projectPath = `/api/v4/projects/${id}`;
+    const refs: ISeededProjectRefs = {
+      spec: specArg, id, labels: new Map(), milestones: new Map(), tags: [], items: [], releases: [], accessibleTo: new Set(),
+    };
+    for (const member of specArg.members ?? []) {
+      await this.#api(httpArg, 'POST', `${projectPath}/members`, [201], {
+        json: { user_id: usersArg.get(member.username)!, access_level: accessLevels[member.accessLevel] },
+      });
+    }
+    if ((specArg.files ?? []).length > 0) {
+      await this.#commitFiles(httpArg, projectPath, specArg.files!, { branch: defaultBranch }, 'Seed default branch files');
+    }
+    for (const branch of specArg.branches ?? []) {
+      await this.#commitFiles(httpArg, projectPath, branch.files, {
+        branch: branch.name, start_branch: branch.from ?? defaultBranch,
+      }, `Seed branch ${branch.name}`);
+    }
+    for (const label of specArg.labels ?? []) {
+      const createdLabel = await this.#api(httpArg, 'POST', `${projectPath}/labels`, [201], {
+        json: { name: label.name, color: label.color, description: label.description ?? '' },
+      });
+      refs.labels.set(label.name, responses.integer(responses.field(createdLabel, 'id', 'created label'), 'label id'));
+    }
+    // Milestones are closed only after the items: GitLab silently ignores a closed
+    // milestone assigned through the API (its milestone finder defaults to active).
+    for (const milestone of specArg.milestones ?? []) {
+      const createdMilestone = responses.record(await this.#api(httpArg, 'POST', `${projectPath}/milestones`, [201], {
+        json: { title: milestone.title, description: milestone.description ?? '' },
+      }), 'created milestone');
+      refs.milestones.set(milestone.title, {
+        id: responses.integer(createdMilestone.id, 'milestone id'),
+        iid: responses.integer(createdMilestone.iid, 'milestone iid'),
+        state: this.#milestoneState(createdMilestone.state),
+      });
+    }
+    for (const tag of specArg.tags ?? []) {
+      const createdTag = await this.#api(httpArg, 'POST', `${projectPath}/repository/tags`, [201], {
+        json: { tag_name: tag.name, ref: tag.ref, ...(tag.message === undefined ? {} : { message: tag.message }) },
+      });
+      refs.tags.push({
+        name: tag.name,
+        commitSha: responses.text(responses.field(responses.field(createdTag, 'commit', 'tag'), 'id', 'tag commit'), 'tag commit id'),
+      });
+    }
+    for (const item of specArg.issuesAndMergeRequests ?? []) {
+      refs.items.push(item.kind === 'issue'
+        ? await this.#seedIssue(httpArg, projectPath, refs, usersArg, item)
+        : await this.#seedMergeRequest(httpArg, projectPath, refs, item));
+    }
+    for (const milestone of (specArg.milestones ?? []).filter((milestoneArg) => milestoneArg.state === 'closed')) {
+      const ref = refs.milestones.get(milestone.title)!;
+      const closed = await this.#api(httpArg, 'PUT', `${projectPath}/milestones/${ref.id}`, [200], { json: { state_event: 'close' } });
+      ref.state = this.#milestoneState(responses.field(closed, 'state', 'closed milestone'));
+    }
+    for (const release of specArg.releases ?? []) {
+      await this.#api(httpArg, 'POST', `${projectPath}/releases`, [201], {
+        json: { tag_name: release.tagName, ref: release.ref, name: release.name, description: release.description ?? '' },
+      });
+      refs.releases.push({ tagName: release.tagName, name: release.name });
+    }
+    return refs;
+  }
+
+  async #seedIssue(
+    httpArg: ForgeFixtureHttpClient,
+    projectPathArg: string,
+    refsArg: ISeededProjectRefs,
+    usersArg: Map<string, number>,
+    issueArg: IGitlabSeedIssue,
+  ): Promise<ISeededItemRef> {
+    await this.#awaitProjectAccess(httpArg, refsArg, issueArg.author);
+    const created = await this.#api(httpArg, 'POST', `${projectPathArg}/issues`, [201], {
+      sudo: issueArg.author,
+      json: {
+        title: issueArg.title, description: issueArg.description ?? '',
+        issue_type: issueArg.issueType ?? 'issue', confidential: issueArg.confidential ?? false,
+      },
+    });
+    const iid = responses.integer(responses.field(created, 'iid', 'created issue'), 'issue iid');
+    const issuePath = `${projectPathArg}/issues/${iid}`;
+    for (const note of issueArg.notes ?? []) {
+      await this.#awaitProjectAccess(httpArg, refsArg, note.author);
+      await this.#api(httpArg, 'POST', `${issuePath}/notes`, [201], { sudo: note.author, json: { body: note.body } });
+    }
+    const edit: Record<string, unknown> = {};
+    if (issueArg.labels !== undefined) edit.labels = issueArg.labels.join(',');
+    if (issueArg.milestone !== undefined) edit.milestone_id = refsArg.milestones.get(issueArg.milestone)!.id;
+    if (issueArg.assignees !== undefined) edit.assignee_ids = issueArg.assignees.map((usernameArg) => usersArg.get(usernameArg)!);
+    if (issueArg.state === 'closed') edit.state_event = 'close';
+    if (Object.keys(edit).length > 0) {
+      const updated = await this.#api(httpArg, 'PUT', issuePath, [200], { json: edit });
+      this.#assertApplied(`issue ${issueArg.key}`, updated, issueArg);
+    }
+    return { key: issueArg.key, kind: 'issue', iid };
+  }
+
+  async #seedMergeRequest(
+    httpArg: ForgeFixtureHttpClient,
+    projectPathArg: string,
+    refsArg: ISeededProjectRefs,
+    mergeRequestArg: IGitlabSeedMergeRequest,
+  ): Promise<ISeededItemRef> {
+    await this.#awaitProjectAccess(httpArg, refsArg, mergeRequestArg.author);
+    const created = await this.#api(httpArg, 'POST', `${projectPathArg}/merge_requests`, [201], {
+      sudo: mergeRequestArg.author,
+      json: {
+        title: mergeRequestArg.title, description: mergeRequestArg.description ?? '',
+        source_branch: mergeRequestArg.sourceBranch, target_branch: mergeRequestArg.targetBranch,
+      },
+    });
+    const iid = responses.integer(responses.field(created, 'iid', 'created merge request'), 'merge request iid');
+    const edit: Record<string, unknown> = {};
+    if (mergeRequestArg.labels !== undefined) edit.labels = mergeRequestArg.labels.join(',');
+    if (mergeRequestArg.state === 'closed') edit.state_event = 'close';
+    if (Object.keys(edit).length > 0) {
+      const updated = await this.#api(httpArg, 'PUT', `${projectPathArg}/merge_requests/${iid}`, [200], { json: edit });
+      this.#assertApplied(`merge request ${mergeRequestArg.key}`, updated, mergeRequestArg);
+    }
+    return { key: mergeRequestArg.key, kind: 'mergeRequest', iid };
+  }
+
+  async #commitFiles(
+    httpArg: ForgeFixtureHttpClient,
+    projectPathArg: string,
+    filesArg: IGitlabSeedFile[],
+    branchArg: { branch: string; start_branch?: string },
+    messageArg: string,
+  ): Promise<void> {
+    await this.#api(httpArg, 'POST', `${projectPathArg}/repository/commits`, [201], {
+      json: {
+        ...branchArg,
+        commit_message: messageArg,
+        actions: filesArg.map((fileArg) => ({ action: 'create', file_path: fileArg.path, content: fileArg.content })),
+      },
+    });
+  }
+
+  /**
+   * GitLab grants the members of a group access to a project created in it
+   * from a background job (`AuthorizedProjectUpdate::ProjectRecalculateWorker`),
+   * so a group member may not see a new project yet. Waits until the user,
+   * acting through sudo, can read the project.
+   */
+  async #awaitProjectAccess(httpArg: ForgeFixtureHttpClient, refsArg: ISeededProjectRefs, usernameArg: string): Promise<void> {
+    if (refsArg.accessibleTo.has(usernameArg)) return;
+    const deadline = Date.now() + projectAccessTimeoutMs;
+    while (true) {
+      const response = await httpArg.request({
+        method: 'GET', url: `/api/v4/projects/${refsArg.id}`, headers: this.#headers(usernameArg), expectedStatus: [200, 404],
+      });
+      if (response.status === 200) {
+        refsArg.accessibleTo.add(usernameArg);
+        return;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `${usernameArg} cannot see ${refsArg.spec.namespace}/${refsArg.spec.path} after ${projectAccessTimeoutMs} ms; check the seed memberships.`,
+        );
+      }
+      await sleep(500);
+    }
+  }
+
+  /** User deletion runs in the background; wait until the user is gone and its content moved to the ghost user. */
+  async #deleteUser(httpArg: ForgeFixtureHttpClient, userIdArg: number): Promise<void> {
+    await this.#api(httpArg, 'DELETE', `/api/v4/users/${userIdArg}`, [204]);
+    const deadline = Date.now() + userDeletionTimeoutMs;
+    while (Date.now() < deadline) {
+      const response = await httpArg.request({
+        method: 'GET', url: `/api/v4/users/${userIdArg}`, headers: this.#headers(), expectedStatus: [200, 404],
+      });
+      if (response.status === 404) return;
+      await sleep(1_000);
+    }
+    throw new Error(`GitLab did not finish deleting user ${userIdArg} within ${userDeletionTimeoutMs} ms.`);
+  }
+
+  async #readBack(httpArg: ForgeFixtureHttpClient, refsArg: ISeededProjectRefs): Promise<IGitlabSeedManifestProject> {
+    const specArg = refsArg.spec;
+    const projectPath = `/api/v4/projects/${refsArg.id}`;
+    const project = responses.record(await this.#api(httpArg, 'GET', projectPath, [200]), 'project');
+    const namespace = responses.record(project.namespace, 'project namespace');
+    const branches: IGitlabSeedManifestProject['branches'] = [];
+    for (const name of [defaultBranch, ...(specArg.branches ?? []).map((branchArg) => branchArg.name)]) {
+      const branch = await this.#api(httpArg, 'GET', `${projectPath}/repository/branches/${encodeURIComponent(name)}`, [200]);
+      branches.push({ name, commitSha: responses.text(responses.field(responses.field(branch, 'commit', 'branch'), 'id', 'branch commit'), 'branch commit id') });
+    }
+    const issues: IGitlabSeedManifestProject['issues'] = [];
+    const mergeRequests: IGitlabSeedManifestProject['mergeRequests'] = [];
+    for (const item of refsArg.items) {
+      if (item.kind === 'issue') {
+        const issue = responses.record(await this.#api(httpArg, 'GET', `${projectPath}/issues/${item.iid}`, [200]), 'issue');
+        const notes = responses.array(await this.#api(httpArg, 'GET', `${projectPath}/issues/${item.iid}/notes`, [200], {
+          query: { sort: 'asc', order_by: 'created_at', per_page: '100' },
+        }), 'notes').map((noteArg) => responses.record(noteArg, 'note')).filter((noteArg) => noteArg.system === false);
+        issues.push({
+          key: item.key,
+          id: responses.integer(issue.id, 'issue id'),
+          iid: responses.integer(issue.iid, 'issue iid'),
+          state: this.#itemState(issue.state),
+          issueType: responses.text(issue.issue_type, 'issue type'),
+          confidential: responses.boolean(issue.confidential, 'issue confidential'),
+          author: this.#author(issue.author),
+          labels: responses.array(issue.labels, 'issue labels').map((labelArg) => responses.text(labelArg, 'label name')),
+          milestone: issue.milestone === null || issue.milestone === undefined
+            ? null
+            : responses.text(responses.field(issue.milestone, 'title', 'issue milestone'), 'milestone title'),
+          assignees: responses.array(issue.assignees ?? [], 'issue assignees').map((assigneeArg) => this.#author(assigneeArg).username),
+          notes: notes.map((noteArg) => ({ id: responses.integer(noteArg.id, 'note id'), author: this.#author(noteArg.author) })),
+        });
+      } else {
+        const mergeRequest = responses.record(await this.#api(httpArg, 'GET', `${projectPath}/merge_requests/${item.iid}`, [200]), 'merge request');
+        mergeRequests.push({
+          key: item.key,
+          id: responses.integer(mergeRequest.id, 'merge request id'),
+          iid: responses.integer(mergeRequest.iid, 'merge request iid'),
+          state: this.#itemState(mergeRequest.state),
+          author: this.#author(mergeRequest.author),
+          sourceBranch: responses.text(mergeRequest.source_branch, 'merge request source branch'),
+          targetBranch: responses.text(mergeRequest.target_branch, 'merge request target branch'),
+          sha: responses.text(mergeRequest.sha, 'merge request sha'),
+        });
+      }
+    }
+    const namespaceKind = namespace.kind;
+    if (namespaceKind !== 'group' && namespaceKind !== 'user') throw new Error('Expected a group or user namespace.');
+    return {
+      pathWithNamespace: responses.text(project.path_with_namespace, 'project path'),
+      id: refsArg.id,
+      namespaceId: responses.integer(namespace.id, 'namespace id'),
+      namespaceKind,
+      visibility: this.#visibility(project.visibility),
+      defaultBranch: responses.text(project.default_branch, 'project default branch'),
+      webUrl: responses.text(project.web_url, 'project web url'),
+      httpUrlToRepo: responses.text(project.http_url_to_repo, 'project clone url'),
+      branches,
+      tags: refsArg.tags,
+      labels: [...refsArg.labels].map(([name, id]) => ({ name, id })),
+      milestones: [...refsArg.milestones].map(([title, milestone]) => ({ title, ...milestone })),
+      issues,
+      mergeRequests,
+      releases: refsArg.releases,
+    };
+  }
+
+  /** GitLab answers 200 even when it drops an attribute it refuses; seeding must not continue on a false premise. */
+  #assertApplied(whatArg: string, updatedArg: unknown, specArg: IGitlabSeedIssue | IGitlabSeedMergeRequest): void {
+    const updated = responses.record(updatedArg, whatArg);
+    const sorted = (valuesArg: string[]) => [...valuesArg].sort().join(',');
+    const dropped: string[] = [];
+    if (this.#itemState(updated.state) !== specArg.state) dropped.push('state');
+    if (specArg.labels !== undefined
+      && sorted(responses.array(updated.labels, 'labels').map((labelArg) => responses.text(labelArg, 'label'))) !== sorted(specArg.labels)) {
+      dropped.push('labels');
+    }
+    if (specArg.kind === 'issue') {
+      const milestone = updated.milestone === null || updated.milestone === undefined
+        ? undefined
+        : responses.text(responses.field(updated.milestone, 'title', 'milestone'), 'milestone title');
+      if (milestone !== specArg.milestone) dropped.push('milestone');
+      if (specArg.assignees !== undefined
+        && sorted(responses.array(updated.assignees, 'assignees').map((userArg) => this.#author(userArg).username)) !== sorted(specArg.assignees)) {
+        dropped.push('assignees');
+      }
+    }
+    if (dropped.length > 0) throw new Error(`GitLab did not apply the ${dropped.join(', ')} of ${whatArg}.`);
+  }
+
+  #author(userArg: unknown): IGitlabSeedManifestAuthor {
+    const user = responses.record(userArg, 'user');
+    return { id: responses.integer(user.id, 'user id'), username: responses.text(user.username, 'user username') };
+  }
+
+  #itemState(valueArg: unknown): 'opened' | 'closed' {
+    if (valueArg !== 'opened' && valueArg !== 'closed') throw new Error('Expected state to be opened or closed.');
+    return valueArg;
+  }
+
+  #milestoneState(valueArg: unknown): 'active' | 'closed' {
+    if (valueArg !== 'active' && valueArg !== 'closed') throw new Error('Expected milestone state to be active or closed.');
+    return valueArg;
+  }
+
+  #visibility(valueArg: unknown): TGitlabVisibility {
+    if (valueArg !== 'public' && valueArg !== 'internal' && valueArg !== 'private') {
+      throw new Error('Expected visibility to be public, internal or private.');
+    }
+    return valueArg;
+  }
+
+  #headers(sudoArg?: string): Record<string, string> {
+    const headers: Record<string, string> = { 'private-token': this.#fixture.runtime.admin.token };
+    if (sudoArg !== undefined) headers.sudo = sudoArg;
+    return headers;
+  }
+
+  async #api(
+    httpArg: ForgeFixtureHttpClient,
+    methodArg: 'GET' | 'POST' | 'PUT' | 'DELETE',
+    pathArg: string,
+    expectedStatusArg: number[],
+    optionsArg: { json?: unknown; sudo?: string; query?: Record<string, string> } = {},
+  ): Promise<unknown> {
+    return httpArg.requestJson({
+      method: methodArg, url: pathArg, headers: this.#headers(optionsArg.sudo), expectedStatus: expectedStatusArg,
+      ...(optionsArg.json === undefined ? {} : { json: optionsArg.json }),
+      ...(optionsArg.query === undefined ? {} : { query: optionsArg.query }),
+    });
+  }
+}

package/ts/classes.httpclient.ts

@@ -0,0 +1,156 @@
+import * as plugins from './plugins.js';
+
+export type TForgeFixtureHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+export interface IForgeFixtureHttpRequest {
+  method: TForgeFixtureHttpMethod;
+  /** Path below the base URL (starting with `/`), or an absolute URL on the exact same origin. */
+  url: string;
+  query?: Record<string, string>;
+  /** Request headers, including credentials. Never included in errors. */
+  headers?: Record<string, string>;
+  /** JSON request body. Mutually exclusive with `body`. */
+  json?: unknown;
+  /** Raw request body. Mutually exclusive with `json`. */
+  body?: Uint8Array;
+  expectedStatus: readonly number[];
+  timeoutMs?: number;
+  maxResponseBytes?: number;
+}
+
+export interface IForgeFixtureHttpResponse {
+  status: number;
+  headers: plugins.http.IncomingHttpHeaders;
+  body: Buffer;
+}
+
+export interface IForgeFixtureHttpClientOptions {
+  /** HTTPS origin, optionally with a path prefix, without credentials. */
+  baseUrl: string;
+  /** The only certificate authority this client trusts. */
+  caCertificatePem: string;
+  requestTimeoutMs?: number;
+  maxResponseBytes?: number;
+}
+
+export class ForgeFixtureHttpError extends Error {
+  public readonly status: number;
+  public readonly method: string;
+  public readonly path: string;
+
+  constructor(methodArg: string, pathArg: string, statusArg: number, bodyExcerptArg: string) {
+    super(`${methodArg} ${pathArg} answered ${statusArg}: ${bodyExcerptArg}`);
+    this.name = 'ForgeFixtureHttpError';
+    this.status = statusArg;
+    this.method = methodArg;
+    this.path = pathArg;
+  }
+}
+
+/**
+ * HTTPS client scoped to one fixture: it trusts only the fixture CA, talks only
+ * to the fixture origin, never follows redirects, and bounds time and body size.
+ * It changes no process-global TLS state.
+ */
+export class ForgeFixtureHttpClient {
+  readonly #baseUrl: URL;
+  readonly #agent: plugins.https.Agent;
+  readonly #requestTimeoutMs: number;
+  readonly #maxResponseBytes: number;
+
+  constructor(optionsArg: IForgeFixtureHttpClientOptions) {
+    const baseUrl = new URL(optionsArg.baseUrl);
+    if (baseUrl.protocol !== 'https:' || baseUrl.username || baseUrl.password || baseUrl.search || baseUrl.hash) {
+      throw new TypeError('The fixture base URL must be a credential-free HTTPS URL.');
+    }
+    this.#baseUrl = new URL(baseUrl.href.endsWith('/') ? baseUrl.href : `${baseUrl.href}/`);
+    this.#agent = new plugins.https.Agent({ ca: [optionsArg.caCertificatePem], keepAlive: true, maxSockets: 8 });
+    this.#requestTimeoutMs = optionsArg.requestTimeoutMs ?? 60_000;
+    this.#maxResponseBytes = optionsArg.maxResponseBytes ?? 16 * 1024 * 1024;
+  }
+
+  public get baseUrl(): string {
+    return this.#baseUrl.href.replace(/\/$/, '');
+  }
+
+  /** Resolves a request target and refuses anything outside the fixture origin. */
+  public resolve(urlArg: string, queryArg?: Record<string, string>): URL {
+    const url = /^https?:\/\//.test(urlArg)
+      ? new URL(urlArg)
+      : new URL(urlArg.replace(/^\//, ''), this.#baseUrl);
+    if (url.origin !== this.#baseUrl.origin || url.username || url.password) {
+      throw new Error(`Refusing a request outside the fixture origin: ${url.origin}`);
+    }
+    for (const [key, value] of Object.entries(queryArg ?? {})) url.searchParams.set(key, value);
+    return url;
+  }
+
+  public async request(requestArg: IForgeFixtureHttpRequest): Promise<IForgeFixtureHttpResponse> {
+    if (requestArg.json !== undefined && requestArg.body !== undefined) {
+      throw new TypeError('A fixture request cannot carry both json and body.');
+    }
+    const url = this.resolve(requestArg.url, requestArg.query);
+    const payload = requestArg.json !== undefined
+      ? Buffer.from(JSON.stringify(requestArg.json))
+      : requestArg.body === undefined ? undefined : Buffer.from(requestArg.body);
+    const headers: Record<string, string> = { accept: 'application/json' };
+    for (const [name, value] of Object.entries(requestArg.headers ?? {})) headers[name.toLowerCase()] = value;
+    if (requestArg.json !== undefined) headers['content-type'] = 'application/json';
+    // A caller-requested transfer coding (for example Git LFS upload actions) replaces Content-Length.
+    if (payload !== undefined && headers['transfer-encoding'] === undefined) {
+      headers['content-length'] = String(payload.byteLength);
+    }
+    const timeoutMs = requestArg.timeoutMs ?? this.#requestTimeoutMs;
+    const maxResponseBytes = requestArg.maxResponseBytes ?? this.#maxResponseBytes;
+
+    const response = await new Promise<IForgeFixtureHttpResponse>((resolveArg, rejectArg) => {
+      const request = plugins.https.request(url, {
+        method: requestArg.method,
+        headers,
+        agent: this.#agent,
+        signal: AbortSignal.timeout(timeoutMs),
+      }, (responseArg) => {
+        const chunks: Buffer[] = [];
+        let size = 0;
+        responseArg.on('data', (chunkArg: Buffer) => {
+          size += chunkArg.byteLength;
+          if (size > maxResponseBytes) {
+            responseArg.destroy(new Error(`${requestArg.method} ${url.pathname} exceeded ${maxResponseBytes} response bytes.`));
+            return;
+          }
+          chunks.push(chunkArg);
+        });
+        responseArg.once('error', rejectArg);
+        responseArg.once('end', () => resolveArg({
+          status: responseArg.statusCode ?? 0,
+          headers: responseArg.headers,
+          body: Buffer.concat(chunks),
+        }));
+      });
+      request.once('error', rejectArg);
+      request.end(payload);
+    });
+    if (!requestArg.expectedStatus.includes(response.status)) {
+      throw new ForgeFixtureHttpError(
+        requestArg.method, url.pathname, response.status, response.body.subarray(0, 512).toString('utf8'),
+      );
+    }
+    return response;
+  }
+
+  /** Performs a request and parses its JSON body. An empty body yields `null`. */
+  public async requestJson(requestArg: IForgeFixtureHttpRequest): Promise<unknown> {
+    const response = await this.request(requestArg);
+    if (response.body.byteLength === 0) return null;
+    const contentType = response.headers['content-type']?.split(';')[0]?.trim().toLowerCase();
+    if (contentType !== 'application/json' && contentType !== 'application/vnd.git-lfs+json') {
+      throw new Error(`${requestArg.method} ${requestArg.url} answered ${contentType ?? 'no content type'} instead of JSON.`);
+    }
+    return JSON.parse(response.body.toString('utf8')) as unknown;
+  }
+
+  /** Destroys pooled connections. The client is unusable afterwards. */
+  public close(): void {
+    this.#agent.destroy();
+  }
+}