@foss.global/forgefixtures 0.2.0

package/ts/interfaces.gitlabseed.ts

@@ -0,0 +1,135 @@
+export type TGitlabVisibility = 'public' | 'internal' | 'private';
+
+export interface IGitlabSeedFile {
+  path: string;
+  content: string;
+}
+
+export interface IGitlabSeedUser {
+  username: string;
+  name?: string;
+}
+
+export interface IGitlabSeedGroup {
+  /** Group path segment. The full path is `<parent>/<path>`. */
+  path: string;
+  /** Full path of an earlier group in the spec, making this a subgroup. */
+  parent?: string;
+  visibility: TGitlabVisibility;
+  members?: Array<{ username: string; accessLevel: TGitlabAccessLevel }>;
+}
+
+/** GitLab access levels by name: guest 10, reporter 20, developer 30, maintainer 40, owner 50. */
+export type TGitlabAccessLevel = 'guest' | 'reporter' | 'developer' | 'maintainer' | 'owner';
+
+export interface IGitlabSeedIssue {
+  kind: 'issue';
+  /** Spec-local identifier used to find this issue in the manifest. */
+  key: string;
+  title: string;
+  description?: string;
+  /** Existing user who opens the issue (through the administrator's sudo). */
+  author: string;
+  issueType?: 'issue' | 'incident';
+  confidential?: boolean;
+  state: 'opened' | 'closed';
+  /** Applied by the administrator, so they are not dropped for authors without planning rights. */
+  labels?: string[];
+  milestone?: string;
+  assignees?: string[];
+  notes?: Array<{ author: string; body: string }>;
+}
+
+export interface IGitlabSeedMergeRequest {
+  kind: 'mergeRequest';
+  key: string;
+  title: string;
+  description?: string;
+  author: string;
+  /** Branch in the same project. */
+  sourceBranch: string;
+  targetBranch: string;
+  state: 'opened' | 'closed';
+  labels?: string[];
+}
+
+export interface IGitlabSeedProject {
+  /** Full path of a seeded group, or a seeded username for a personal project. */
+  namespace: string;
+  path: string;
+  visibility: TGitlabVisibility;
+  description?: string;
+  members?: Array<{ username: string; accessLevel: TGitlabAccessLevel }>;
+  /** Committed to `main` after initialisation with a README. */
+  files?: IGitlabSeedFile[];
+  /** Each branch is created by one commit of its files on top of `from` (default `main`). */
+  branches?: Array<{ name: string; from?: string; files: [IGitlabSeedFile, ...IGitlabSeedFile[]] }>;
+  tags?: Array<{ name: string; ref: string; message?: string }>;
+  labels?: Array<{ name: string; color: string; description?: string }>;
+  /** Closed milestones are closed after the items: GitLab ignores a closed milestone assigned through the API. */
+  milestones?: Array<{ title: string; description?: string; state?: 'active' | 'closed' }>;
+  /** Issues and merge requests have separate IID sequences; within each kind they are created in order. */
+  issuesAndMergeRequests?: Array<IGitlabSeedIssue | IGitlabSeedMergeRequest>;
+  releases?: Array<{ tagName: string; ref: string; name: string; description?: string }>;
+}
+
+export interface IGitlabSeedSpec {
+  users: IGitlabSeedUser[];
+  groups: IGitlabSeedGroup[];
+  projects: IGitlabSeedProject[];
+  /** Deleted after everything else (without hard delete); GitLab moves their contributions to its ghost user. */
+  deleteUsers?: string[];
+}
+
+export interface IGitlabSeedManifestAuthor {
+  id: number;
+  username: string;
+}
+
+/** What GitLab itself reported after seeding, read back once all mutations finished. */
+export interface IGitlabSeedManifest {
+  baseUrl: string;
+  version: string;
+  users: Array<{ username: string; id: number; deleted: boolean }>;
+  groups: Array<{ fullPath: string; id: number; parentId: number | null; visibility: TGitlabVisibility }>;
+  projects: IGitlabSeedManifestProject[];
+}
+
+export interface IGitlabSeedManifestProject {
+  pathWithNamespace: string;
+  id: number;
+  namespaceId: number;
+  namespaceKind: 'group' | 'user';
+  visibility: TGitlabVisibility;
+  defaultBranch: string;
+  webUrl: string;
+  httpUrlToRepo: string;
+  branches: Array<{ name: string; commitSha: string }>;
+  tags: Array<{ name: string; commitSha: string }>;
+  labels: Array<{ name: string; id: number }>;
+  milestones: Array<{ title: string; id: number; iid: number; state: 'active' | 'closed' }>;
+  issues: Array<{
+    key: string;
+    id: number;
+    iid: number;
+    state: 'opened' | 'closed';
+    issueType: string;
+    confidential: boolean;
+    author: IGitlabSeedManifestAuthor;
+    labels: string[];
+    milestone: string | null;
+    assignees: string[];
+    notes: Array<{ id: number; author: IGitlabSeedManifestAuthor }>;
+  }>;
+  mergeRequests: Array<{
+    key: string;
+    id: number;
+    iid: number;
+    state: 'opened' | 'closed';
+    author: IGitlabSeedManifestAuthor;
+    sourceBranch: string;
+    targetBranch: string;
+    sha: string;
+  }>;
+  releases: Array<{ tagName: string; name: string }>;
+}

package/ts/interfaces.ts

@@ -0,0 +1,94 @@
+export type TForgeFixtureKind = 'gitea' | 'gitlab';
+
+/** A published forge image, pinned by its multi-architecture index digest. */
+export interface IForgeFixtureImage {
+  /** Upstream release the image is expected to report through its version API. */
+  version: string;
+  /** Human-readable tag, retained as evidence only. The digest is what gets pulled. */
+  tag: string;
+  /** Complete `repository@sha256:<index digest>` reference, pulled and verified exactly. */
+  repoDigest: string;
+}
+
+/** Options shared by every fixture lifecycle. */
+export interface IForgeFixtureLifecycleOptions {
+  /**
+   * Docker Engine socket. Omit to use `@apiclient.xyz/docker` resolution
+   * (`DOCKER_HOST`, then `/var/run/docker.sock`).
+   */
+  dockerSocketPath?: string;
+  /**
+   * Upper bound for this lifecycle. Once exceeded, any later reaper run may
+   * remove its resources even if the owning process is still alive.
+   */
+  maxLifetimeMs?: number;
+  /** Deadline for pulling the pinned image, including its digest verification. */
+  pullTimeoutMs?: number;
+  /** Deadline from container start until the forge answers as ready. */
+  startupTimeoutMs?: number;
+}
+
+/** Ownership evidence written into the labels of every Docker resource of one lifecycle. */
+export interface IForgeFixtureOwner {
+  lifecycleId: string;
+  kind: TForgeFixtureKind;
+  /** systemd machine id (`/etc/machine-id`); distinguishes hosts that share a host name. */
+  machineId: string;
+  hostname: string;
+  bootId: string;
+  /** PID namespace of the owner (`pid:[<inode>]`); PIDs are only comparable inside it. */
+  pidNamespace: string;
+  pid: number;
+  /** Process start time in clock ticks since boot, guarding against PID reuse. */
+  processStartTicks: string;
+  createdAt: string;
+  expiresAt: string;
+}
+
+export type TForgeFixtureReapReason = 'owner-exited' | 'owner-rebooted' | 'expired';
+
+export interface IForgeFixtureReapReport {
+  removedContainers: string[];
+  removedNetworks: string[];
+  removedVolumes: string[];
+  /** Lifecycles removed, with the reason each was considered stale. */
+  reapedLifecycles: Array<{ lifecycleId: string; reason: TForgeFixtureReapReason }>;
+  /** Managed resources whose ownership labels could not be interpreted. They are never removed. */
+  unrecognizedResources: Array<{ type: 'container' | 'network' | 'volume'; id: string }>;
+}
+
+/** Material a test needs to talk to a started fixture over verified TLS. */
+export interface IForgeFixtureEndpoint {
+  /** HTTPS instance root without trailing slash, for example `https://127.0.0.1:41234`. */
+  baseUrl: string;
+  /** PEM of the lifecycle-local certificate authority that issued the endpoint certificate. */
+  caCertificatePem: string;
+}
+
+export interface IGiteaFixtureRuntime extends IForgeFixtureEndpoint {
+  kind: 'gitea';
+  lifecycleId: string;
+  /** Version reported by `/api/v1/version`, verified against the image pin. */
+  version: string;
+  image: IForgeFixtureImage;
+  /** Site administrator created at bootstrap. Its password is random and never retained. */
+  admin: {
+    username: string;
+    /** Access token with scope `all`. */
+    token: string;
+  };
+}
+
+export interface IGitlabFixtureRuntime extends IForgeFixtureEndpoint {
+  kind: 'gitlab';
+  lifecycleId: string;
+  /** Version reported by `/api/v4/version`, verified against the image pin. */
+  version: string;
+  image: IForgeFixtureImage;
+  /** The built-in `root` administrator. Its password is generated by GitLab and never read. */
+  admin: {
+    username: string;
+    /** Personal access token with scopes `api` and `sudo`. */
+    token: string;
+  };
+}

package/ts/ownership.ts

@@ -0,0 +1,160 @@
+import * as plugins from './plugins.js';
+import { forgeFixtureLabels } from './constants.js';
+import type { IForgeFixtureOwner, TForgeFixtureKind, TForgeFixtureReapReason } from './interfaces.js';
+
+export interface IForgeFixtureProcessIdentity {
+  machineId: string;
+  hostname: string;
+  bootId: string;
+  pidNamespace: string;
+  pid: number;
+  processStartTicks: string;
+}
+
+const machineIdPattern = /^[0-9a-f]{32}$/;
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const decimalPattern = /^[0-9]{1,20}$/;
+const pidNamespacePattern = /^pid:\[[0-9]{1,20}\]$/;
+
+const isErrnoException = (errorArg: unknown): errorArg is NodeJS.ErrnoException =>
+  errorArg instanceof Error && 'code' in errorArg;
+
+/**
+ * Reads field 22 (`starttime`) of `/proc/<pid>/stat`. Returns `undefined` when
+ * the process does not exist. The command name may contain spaces and
+ * parentheses, so fields are counted after its closing parenthesis.
+ */
+export const readProcessStartTicks = async (pidArg: number): Promise<string | undefined> => {
+  let stat: string;
+  try {
+    stat = await plugins.fs.promises.readFile(`/proc/${pidArg}/stat`, 'utf8');
+  } catch (error) {
+    if (isErrnoException(error) && error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+  const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+  // fields[0] is field 3 (state), so field 22 is fields[19].
+  const startTicks = fields[19];
+  if (startTicks === undefined || !decimalPattern.test(startTicks)) {
+    throw new Error(`Process ${pidArg} has a malformed /proc stat record.`);
+  }
+  return startTicks;
+};
+
+/**
+ * Stands in for the machine ID of a process whose system has no valid
+ * `/etc/machine-id`, as in many container images. It is fixed for the life of
+ * the process and never matches another process, so every other owner is
+ * foreign to this one, and this owner is foreign to every other process: both
+ * sides judge each other by expiry only.
+ */
+const processLocalMachineId = plugins.crypto.randomBytes(16).toString('hex');
+
+const readMachineId = async (): Promise<string> => {
+  let machineId: string;
+  try {
+    machineId = (await plugins.fs.promises.readFile('/etc/machine-id', 'utf8')).trim();
+  } catch (error) {
+    if (isErrnoException(error) && error.code === 'ENOENT') return processLocalMachineId;
+    throw error;
+  }
+  return machineIdPattern.test(machineId) ? machineId : processLocalMachineId;
+};
+
+export const readCurrentProcessIdentity = async (): Promise<IForgeFixtureProcessIdentity> => {
+  const machineId = await readMachineId();
+  const bootId = (await plugins.fs.promises.readFile('/proc/sys/kernel/random/boot_id', 'utf8')).trim();
+  if (!uuidPattern.test(bootId)) throw new Error('The kernel boot id is malformed.');
+  const processStartTicks = await readProcessStartTicks(process.pid);
+  if (processStartTicks === undefined) throw new Error('The current process has no /proc stat record.');
+  const pidNamespace = await plugins.fs.promises.readlink('/proc/self/ns/pid');
+  if (!pidNamespacePattern.test(pidNamespace)) throw new Error('The current PID namespace identity is malformed.');
+  return { machineId, hostname: plugins.os.hostname(), bootId, pidNamespace, pid: process.pid, processStartTicks };
+};
+
+export const createForgeFixtureOwner = async (
+  kindArg: TForgeFixtureKind,
+  maxLifetimeMsArg: number,
+): Promise<IForgeFixtureOwner> => {
+  if (!Number.isSafeInteger(maxLifetimeMsArg) || maxLifetimeMsArg < 60_000) {
+    throw new TypeError('maxLifetimeMs must be an integer of at least 60000.');
+  }
+  const identity = await readCurrentProcessIdentity();
+  const createdAt = new Date();
+  return {
+    lifecycleId: plugins.crypto.randomUUID(),
+    kind: kindArg,
+    ...identity,
+    createdAt: createdAt.toISOString(),
+    expiresAt: new Date(createdAt.getTime() + maxLifetimeMsArg).toISOString(),
+  };
+};
+
+/** Labels carried by every Docker resource of one lifecycle. */
+export const forgeFixtureOwnerLabels = (ownerArg: IForgeFixtureOwner): Record<string, string> => ({
+  [forgeFixtureLabels.managed]: 'true',
+  [forgeFixtureLabels.lifecycleId]: ownerArg.lifecycleId,
+  [forgeFixtureLabels.kind]: ownerArg.kind,
+  [forgeFixtureLabels.machineId]: ownerArg.machineId,
+  [forgeFixtureLabels.hostname]: ownerArg.hostname,
+  [forgeFixtureLabels.bootId]: ownerArg.bootId,
+  [forgeFixtureLabels.pidNamespace]: ownerArg.pidNamespace,
+  [forgeFixtureLabels.pid]: String(ownerArg.pid),
+  [forgeFixtureLabels.processStartTicks]: ownerArg.processStartTicks,
+  [forgeFixtureLabels.createdAt]: ownerArg.createdAt,
+  [forgeFixtureLabels.expiresAt]: ownerArg.expiresAt,
+});
+
+const isIsoTimestamp = (valueArg: string | undefined): valueArg is string =>
+  valueArg !== undefined && !Number.isNaN(Date.parse(valueArg)) && new Date(valueArg).toISOString() === valueArg;
+
+/** Parses ownership labels; returns `undefined` for anything this package did not write. */
+export const parseForgeFixtureOwnerLabels = (
+  labelsArg: Record<string, string> | undefined,
+): IForgeFixtureOwner | undefined => {
+  if (!labelsArg || labelsArg[forgeFixtureLabels.managed] !== 'true') return undefined;
+  const lifecycleId = labelsArg[forgeFixtureLabels.lifecycleId];
+  const kind = labelsArg[forgeFixtureLabels.kind];
+  const machineId = labelsArg[forgeFixtureLabels.machineId];
+  const hostname = labelsArg[forgeFixtureLabels.hostname];
+  const bootId = labelsArg[forgeFixtureLabels.bootId];
+  const pidNamespace = labelsArg[forgeFixtureLabels.pidNamespace];
+  const pid = labelsArg[forgeFixtureLabels.pid];
+  const processStartTicks = labelsArg[forgeFixtureLabels.processStartTicks];
+  const createdAt = labelsArg[forgeFixtureLabels.createdAt];
+  const expiresAt = labelsArg[forgeFixtureLabels.expiresAt];
+  if (
+    lifecycleId === undefined || !uuidPattern.test(lifecycleId)
+    || (kind !== 'gitea' && kind !== 'gitlab')
+    || machineId === undefined || !machineIdPattern.test(machineId)
+    || !hostname
+    || bootId === undefined || !uuidPattern.test(bootId)
+    || pidNamespace === undefined || !pidNamespacePattern.test(pidNamespace)
+    || pid === undefined || !decimalPattern.test(pid) || !Number.isSafeInteger(Number(pid))
+    || processStartTicks === undefined || !decimalPattern.test(processStartTicks)
+    || !isIsoTimestamp(createdAt) || !isIsoTimestamp(expiresAt)
+  ) return undefined;
+  return {
+    lifecycleId, kind, machineId, hostname, bootId, pidNamespace, pid: Number(pid), processStartTicks, createdAt, expiresAt,
+  };
+};
+
+/**
+ * Decides whether a lifecycle is stale. A PID identifies a process only inside
+ * its PID namespace: host-network containers sharing the Docker socket share
+ * hostname and boot id but not PIDs, and machines sharing a remote daemon can
+ * share a host name. Owners on another machine (machine id or host name) or in
+ * another PID namespace are therefore judged by expiry only.
+ */
+export const classifyForgeFixtureOwner = async (
+  ownerArg: IForgeFixtureOwner,
+  currentArg: IForgeFixtureProcessIdentity,
+  nowArg: Date,
+): Promise<TForgeFixtureReapReason | 'alive'> => {
+  if (Date.parse(ownerArg.expiresAt) <= nowArg.getTime()) return 'expired';
+  if (ownerArg.machineId !== currentArg.machineId || ownerArg.hostname !== currentArg.hostname) return 'alive';
+  if (ownerArg.bootId !== currentArg.bootId) return 'owner-rebooted';
+  if (ownerArg.pidNamespace !== currentArg.pidNamespace) return 'alive';
+  const startTicks = await readProcessStartTicks(ownerArg.pid);
+  return startTicks === ownerArg.processStartTicks ? 'alive' : 'owner-exited';
+};

package/ts/plugins.ts

@@ -0,0 +1,23 @@
+// Polyfill required by @peculiar/x509 (through tsyringe). This import must precede its evaluation.
+import 'reflect-metadata';
+
+// Node native scope
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as https from 'node:https';
+import * as net from 'node:net';
+import * as os from 'node:os';
+import * as tls from 'node:tls';
+
+export { crypto, fs, http, https, net, os, tls };
+
+// @apiclient.xyz scope
+import * as docker from '@apiclient.xyz/docker';
+
+export { docker };
+
+// third-party scope
+import * as x509 from '@peculiar/x509';
+
+export { x509 };

package/ts/responses.ts

@@ -0,0 +1,33 @@
+/** Narrow readers for forge JSON responses. Each throws with the field it expected. */
+
+export const record = (valueArg: unknown, whatArg: string): Record<string, unknown> => {
+  if (typeof valueArg !== 'object' || valueArg === null || Array.isArray(valueArg)) {
+    throw new Error(`Expected ${whatArg} to be an object.`);
+  }
+  return valueArg as Record<string, unknown>;
+};
+
+export const array = (valueArg: unknown, whatArg: string): unknown[] => {
+  if (!Array.isArray(valueArg)) throw new Error(`Expected ${whatArg} to be an array.`);
+  return valueArg;
+};
+
+export const integer = (valueArg: unknown, whatArg: string): number => {
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg)) {
+    throw new Error(`Expected ${whatArg} to be a safe integer.`);
+  }
+  return valueArg;
+};
+
+export const text = (valueArg: unknown, whatArg: string): string => {
+  if (typeof valueArg !== 'string') throw new Error(`Expected ${whatArg} to be a string.`);
+  return valueArg;
+};
+
+export const boolean = (valueArg: unknown, whatArg: string): boolean => {
+  if (typeof valueArg !== 'boolean') throw new Error(`Expected ${whatArg} to be a boolean.`);
+  return valueArg;
+};
+
+export const field = (valueArg: unknown, keyArg: string, whatArg: string): unknown =>
+  record(valueArg, whatArg)[keyArg];