@foss.global/forgefixtures 0.2.0

package/ts/classes.giteafixture.ts

@@ -0,0 +1,205 @@
+import * as plugins from './plugins.js';
+import { giteaFixtureImage } from './constants.js';
+import { ForgeFixtureContainerLifecycle } from './classes.containerlifecycle.js';
+import type { ForgeFixtureHttpClient } from './classes.httpclient.js';
+import type { IForgeFixtureLifecycleOptions, IForgeFixtureReapReport, IGiteaFixtureRuntime } from './interfaces.js';
+
+export interface IGiteaFixtureOptions extends IForgeFixtureLifecycleOptions {
+  /** Container memory limit; swap is disabled. Defaults to 512 MiB. */
+  memoryBytes?: number;
+  /** CPU limit in billionths of a CPU. Defaults to 2 CPUs. */
+  nanoCpus?: number;
+}
+
+export interface IGiteaAccessTokenRequest {
+  username: string;
+  /** Unique per user. */
+  tokenName: string;
+  /** Gitea scopes such as `all`, `public-only` or `read:repository`. */
+  scopes: string[];
+}
+
+const httpPort = 3000;
+const dataDirectory = '/var/lib/gitea';
+/** The configuration lives in the owned data volume, whose directories belong to the Gitea user. */
+const appIni = `${dataDirectory}/conf/app.ini`;
+const giteaBinary = '/usr/local/bin/gitea';
+const adminUsername = 'forgeadmin';
+const usernamePattern = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,38}$/;
+const scopePattern = /^(all|public-only|(read|write):[a-z]+)$/;
+const tokenPattern = /^[0-9a-f]{40}$/;
+const execTimeoutMs = 60_000;
+
+const sleep = (msArg: number) => new Promise<void>((resolveArg) => setTimeout(resolveArg, msArg));
+
+/**
+ * A disposable Gitea instance from the pinned rootless image, served over
+ * verified loopback TLS, with SQLite and all data in one owned named volume.
+ */
+export class GiteaFixture {
+  readonly #options: IGiteaFixtureOptions;
+  readonly #lifecycle: ForgeFixtureContainerLifecycle;
+  #runtime: IGiteaFixtureRuntime | undefined;
+  #starting: Promise<IGiteaFixtureRuntime> | undefined;
+
+  constructor(optionsArg: IGiteaFixtureOptions = {}) {
+    this.#options = { ...optionsArg };
+    this.#lifecycle = new ForgeFixtureContainerLifecycle('gitea', optionsArg, 120_000);
+  }
+
+  public get runtime(): IGiteaFixtureRuntime {
+    if (!this.#runtime) throw new Error('The Gitea fixture is not running.');
+    return this.#runtime;
+  }
+
+  /** HTTPS client scoped to this fixture's origin and CA. */
+  public get http(): ForgeFixtureHttpClient {
+    return this.#lifecycle.http;
+  }
+
+  /** Report of the stale-fixture reaper run that preceded this start. */
+  public get reapReport(): IForgeFixtureReapReport | undefined {
+    return this.#lifecycle.lastReapReport;
+  }
+
+  /**
+   * Starts the fixture and returns once Gitea answers with the pinned version
+   * and an admin token exists. A fixture starts at most once.
+   */
+  public start(): Promise<IGiteaFixtureRuntime> {
+    if (this.#starting) return Promise.reject(new Error('The Gitea fixture was already started.'));
+    this.#starting = this.#start();
+    return this.#starting;
+  }
+
+  async #start(): Promise<IGiteaFixtureRuntime> {
+    const endpoint = await this.#lifecycle.prepare();
+    try {
+      await this.#lifecycle.startContainer({
+        image: giteaFixtureImage,
+        user: '1000:1000',
+        command: [giteaBinary, '--config', appIni, 'web'],
+        env: {
+          GITEA_APP_INI: appIni,
+          GITEA__security__INSTALL_LOCK: 'true',
+          GITEA__security__SECRET_KEY: plugins.crypto.randomBytes(32).toString('hex'),
+          GITEA__server__ROOT_URL: `${endpoint.baseUrl}/`,
+          GITEA__server__DOMAIN: '127.0.0.1',
+          GITEA__server__SSH_DOMAIN: '127.0.0.1',
+          GITEA__server__HTTP_PORT: String(httpPort),
+          GITEA__server__LFS_START_SERVER: 'true',
+          GITEA__server__OFFLINE_MODE: 'true',
+          GITEA__service__DISABLE_REGISTRATION: 'true',
+          GITEA__database__DB_TYPE: 'sqlite3',
+          GITEA__log__LEVEL: 'Warn',
+        },
+        httpPort,
+        // Git hooks live in the data directory and must be executable, so it is an owned
+        // named volume (Docker mounts tmpfs noexec). It is removed with the lifecycle.
+        volumes: [{ purpose: 'data', target: dataDirectory }],
+        // Declared image volume, unused because the configuration lives in the data volume;
+        // mounted so Docker creates no anonymous volume for it.
+        tmpfsMounts: [{ target: '/etc/gitea', sizeBytes: 1024 * 1024 }],
+        memoryBytes: this.#options.memoryBytes ?? 512 * 1024 * 1024,
+        nanoCpus: this.#options.nanoCpus ?? 2_000_000_000,
+        pidsLimit: 512,
+        stopTimeoutSeconds: 10,
+      });
+      await this.#waitForHealth(Date.now() + this.#lifecycle.startupTimeoutMs);
+      const version = await this.#readVersion();
+      this.#lifecycle.assertNotStopping();
+      if (version !== giteaFixtureImage.version) {
+        throw new Error(`Gitea reports version ${version}; the pinned image is ${giteaFixtureImage.version}.`);
+      }
+      await this.#giteaCli([
+        'admin', 'user', 'create', '--username', adminUsername, '--email', `${adminUsername}@example.com`,
+        '--random-password', '--admin', '--must-change-password=false',
+      ], 'create the fixture administrator');
+      const token = await this.createAccessToken({ username: adminUsername, tokenName: 'forgefixtures-admin', scopes: ['all'] });
+      this.#lifecycle.assertNotStopping();
+      this.#runtime = {
+        kind: 'gitea',
+        lifecycleId: this.#lifecycle.lifecycleId,
+        baseUrl: endpoint.baseUrl,
+        caCertificatePem: endpoint.caCertificatePem,
+        version,
+        image: giteaFixtureImage,
+        admin: { username: adminUsername, token },
+      };
+      return this.#runtime;
+    } catch (error) {
+      const reported = this.#lifecycle.stopAwareError(error);
+      try {
+        await this.#lifecycle.stop();
+      } catch (cleanupError) {
+        throw new AggregateError([reported, cleanupError], 'The Gitea fixture failed to start and to clean up.');
+      }
+      throw reported;
+    }
+  }
+
+  /** Creates an access token through Gitea's supported admin CLI. The token is returned, never logged. */
+  public async createAccessToken(requestArg: IGiteaAccessTokenRequest): Promise<string> {
+    if (!usernamePattern.test(requestArg.username) || !/^[A-Za-z0-9_.-]{1,64}$/.test(requestArg.tokenName)
+      || requestArg.scopes.length === 0 || !requestArg.scopes.every((scopeArg) => scopePattern.test(scopeArg))) {
+      throw new TypeError('The access token request is malformed.');
+    }
+    const stdout = await this.#giteaCli([
+      'admin', 'user', 'generate-access-token', '--username', requestArg.username,
+      '--token-name', requestArg.tokenName, '--scopes', requestArg.scopes.join(','), '--raw',
+    ], `create an access token for ${requestArg.username}`);
+    const token = stdout.trim();
+    if (!tokenPattern.test(token)) throw new Error('Gitea returned an access token in an unexpected format.');
+    return token;
+  }
+
+  /**
+   * Removes every resource of this fixture. A start in progress is cancelled at
+   * its next checkpoint and awaited first, so nothing it created survives.
+   * Idempotent; retries incomplete cleanup.
+   */
+  public async stop(): Promise<void> {
+    this.#runtime = undefined;
+    this.#lifecycle.requestStop();
+    const starting = this.#starting;
+    if (starting) await starting.catch(() => undefined);
+    await this.#lifecycle.stop();
+  }
+
+  async #waitForHealth(deadlineArg: number): Promise<void> {
+    let lastFailure = 'no attempt';
+    while (Date.now() < deadlineArg) {
+      this.#lifecycle.assertNotStopping();
+      await this.#lifecycle.assertContainerRunning();
+      try {
+        const response = await this.#lifecycle.http.request({
+          method: 'GET', url: '/api/healthz', expectedStatus: [200, 503], timeoutMs: 5_000,
+        });
+        if (response.status === 200) return;
+        lastFailure = `status ${response.status}`;
+      } catch (error) {
+        lastFailure = error instanceof Error ? error.message : String(error);
+      }
+      await sleep(500);
+    }
+    throw new Error(
+      `Gitea did not become healthy within ${this.#lifecycle.startupTimeoutMs} ms (${lastFailure}). Last logs:\n${await this.#lifecycle.logsTail(40)}`,
+    );
+  }
+
+  async #readVersion(): Promise<string> {
+    const body = await this.#lifecycle.http.requestJson({ method: 'GET', url: '/api/v1/version', expectedStatus: [200] });
+    const version: unknown = typeof body === 'object' && body !== null ? Reflect.get(body, 'version') : undefined;
+    if (typeof version !== 'string') throw new Error('Gitea answered /api/v1/version without a version.');
+    return version;
+  }
+
+  /** Runs the Gitea CLI as the Gitea user. Output is returned but never included in errors. */
+  async #giteaCli(argsArg: string[], purposeArg: string): Promise<string> {
+    const result = await this.#lifecycle.exec([giteaBinary, '--config', appIni, ...argsArg], { timeoutMs: execTimeoutMs });
+    if (result.exitCode !== 0) {
+      throw new Error(`Gitea CLI failed to ${purposeArg} (exit ${result.exitCode}): ${result.stderr.slice(0, 1024)}`);
+    }
+    return result.stdout;
+  }
+}