@monster-orange/den 0.0.0 → 0.1.0

package/src/pillars/perf/k6.config.js

@@ -0,0 +1,112 @@
+/**
+ * k6 Configuration
+ * Base configuration for performance tests
+ */
+
+export const options = {
+  // VUs (Virtual Users)
+  vus: 10,
+  duration: "30s",
+
+  // Thresholds - Define SLAs
+  thresholds: {
+    // 95% of requests should be below 500ms
+    http_req_duration: ["p(95)<500"],
+
+    // Error rate should be less than 1%
+    http_req_failed: ["rate<0.01"],
+
+    // 90% of requests should be below 300ms
+    "http_req_duration{name:health}": ["p(90)<300"],
+  },
+
+  // Stages for ramping VUs
+  stages: [
+    { duration: "30s", target: 20 }, // Ramp up to 20 users
+    { duration: "1m", target: 20 }, // Stay at 20 users
+    { duration: "30s", target: 0 }, // Ramp down to 0 users
+  ],
+
+  // Tags - For organizing metrics
+  tags: {
+    test_type: "load",
+  },
+
+  // Summaries
+  summaryTrendStats: ["avg", "min", "med", "max", "p(90)", "p(95)", "p(99)"],
+
+  // HTTP settings
+  http: {
+    timeout: "30s",
+  },
+
+  // Rate limiting
+  // rps: 100, // Max requests per second
+
+  // Scenarios - Advanced load patterns
+  scenarios: {
+    // Constant load
+    constant_load: {
+      executor: "constant-vus",
+      vus: 10,
+      duration: "1m",
+      tags: { scenario: "constant" },
+    },
+
+    // Ramping load
+    ramping_load: {
+      executor: "ramping-vus",
+      startVUs: 0,
+      stages: [
+        { duration: "30s", target: 50 },
+        { duration: "1m", target: 50 },
+        { duration: "30s", target: 0 },
+      ],
+      tags: { scenario: "ramping" },
+    },
+
+    // Per-VU iterations
+    // per_vu_iterations: {
+    //   executor: 'per-vu-iterations',
+    //   vus: 10,
+    //   iterations: 100,
+    //   maxDuration: '5m',
+    //   tags: { scenario: 'iterations' },
+    // },
+
+    // Constant arrival rate
+    // constant_arrival_rate: {
+    //   executor: 'constant-arrival-rate',
+    //   rate: 100, // 100 iterations per timeUnit
+    //   timeUnit: '1s',
+    //   duration: '1m',
+    //   preAllocatedVUs: 50,
+    //   maxVUs: 100,
+    //   tags: { scenario: 'arrival' },
+    // },
+  },
+};
+
+/**
+ * Load environment configuration
+ */
+export function getEnvironment() {
+  const env = __ENV.E2E_ENVIRONMENT || "local";
+  const configPath = `./config/environments/${env}.json`;
+
+  // In k6, we need to read config from environment variables
+  // since k6 doesn't support direct file reading in init context
+  return {
+    name: env,
+    baseUrl: __ENV.API_BASE_URL || "http://localhost:3000",
+    apiTimeout: parseInt(__ENV.API_TIMEOUT || "30000", 10),
+  };
+}
+
+/**
+ * Get authentication token
+ * Note: In real tests, you'd get this via OAuth flow or from ENV
+ */
+export function getAuthToken() {
+  return __ENV.AUTH_TOKEN || "";
+}

package/src/pillars/perf/run.ts

@@ -0,0 +1,345 @@
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { parseArgs } from "util";
+import { resolveManifestBaseUrl } from "../../shared/service-url.js";
+import { getDistRoot } from "../../shared/paths.js";
+import type { Environment } from "../../shared/types/index.js";
+import { findManifest, resolveRepoPath } from "../smoke/discover.js";
+import { assertStorageAdminProbe } from "../smoke/admin-probe.js";
+import {
+  acquireFixture,
+  releaseFixturesForConsumer,
+} from "../smoke/fixture-manager.js";
+import { resolvePerformanceStorageFixture } from "../smoke/fixtures.js";
+import {
+  PERF_CURRENT_REPORT_DIR,
+  getPerfSummaryArtifactPath,
+} from "../../shared/perf/report-paths.js";
+import {
+  writeCurrentPerfRunReport,
+  resetCurrentPerfRunReport,
+} from "../../shared/perf/report-store.js";
+
+import { product } from "../../shared/product.js";
+export interface PerfRunModule {
+  repoName: string;
+  moduleName: string;
+}
+
+export interface RunPerfModulesOptions {
+  modules: PerfRunModule[];
+  environment: Environment;
+  baseUrl: string;
+  useLocalCheckout?: boolean;
+  env?: NodeJS.ProcessEnv;
+}
+
+function spawnK6Process(
+  testFile: string,
+  env: NodeJS.ProcessEnv,
+  summaryExportPath?: string,
+): Promise<{ success: boolean; exitCode: number }> {
+  const args = ["run"];
+  if (summaryExportPath) {
+    args.push("--summary-export", summaryExportPath);
+  }
+  args.push(testFile);
+  return new Promise((resolve) => {
+    const proc = spawn("k6", args, {
+      env,
+      stdio: "inherit",
+    });
+
+    proc.on("close", (code) => {
+      resolve({
+        success: code === 0,
+        exitCode: code ?? 1,
+      });
+    });
+
+    proc.on("error", (error) => {
+      console.error(`Failed to execute k6: ${error.message}`);
+      resolve({
+        success: false,
+        exitCode: 1,
+      });
+    });
+  });
+}
+
+function logPerfTeardownFailure(error: unknown): void {
+  if (error instanceof AggregateError) {
+    console.error("Performance storage fixture teardown failed:");
+    for (const [index, err] of error.errors.entries()) {
+      console.error(`  [${index + 1}/${error.errors.length}]`, err);
+    }
+    return;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Performance storage fixture teardown failed: ${message}`);
+}
+
+export async function runPerfModules(
+  options: RunPerfModulesOptions,
+): Promise<{ success: boolean; exitCode: number }> {
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    ...(options.env ?? {}),
+    E2E_ENVIRONMENT: options.environment,
+    BASE_URL: options.baseUrl,
+    BASE_API_URL: options.baseUrl,
+  };
+  const releases: Array<() => Promise<void>> = [];
+
+  let k6Outcome = { success: true, exitCode: 0 };
+  let caughtError: unknown = undefined;
+  let teardownFailed = false;
+  let disabledSkipCount = 0;
+  const completedModuleKeys: string[] = [];
+
+  // Den-root anchored: this child inherits its spawner's (arbitrary) cwd.
+  fs.mkdirSync(path.resolve(getDistRoot(), PERF_CURRENT_REPORT_DIR), {
+    recursive: true,
+  });
+  // Clear the prior run's report so a stale one is never served.
+  resetCurrentPerfRunReport();
+
+  try {
+    for (const moduleRef of options.modules) {
+      const discovered = findManifest(moduleRef.repoName);
+      if (!discovered) {
+        throw new Error(
+          `Performance repo "${moduleRef.repoName}" is not registered with ${product().cli}`,
+        );
+      }
+
+      const repoPath = resolveRepoPath(
+        discovered,
+        options.environment,
+        options.useLocalCheckout ?? false,
+      );
+      const moduleConfig =
+        discovered.manifest.performance?.[moduleRef.moduleName];
+      if (!moduleConfig) {
+        throw new Error(
+          `Performance module "${moduleRef.moduleName}" not found in ${moduleRef.repoName}/${product().manifestYml}`,
+        );
+      }
+
+      if (moduleConfig.enabled === false) {
+        console.warn(
+          `Skipping disabled performance module "${moduleRef.moduleName}" (${moduleRef.repoName})`,
+        );
+        disabledSkipCount += 1;
+        continue;
+      }
+
+      const moduleEnv = {
+        ...env,
+        PERF_TEST_ID: `${moduleRef.repoName}/${moduleRef.moduleName}`,
+        PERF_RUN_ID:
+          env.PERF_RUN_ID ??
+          `${moduleRef.repoName}-${moduleRef.moduleName}-${Date.now()}`,
+      };
+
+      if (moduleConfig.fixtures?.storage?.[options.environment]) {
+        const lifecycle = resolvePerformanceStorageFixture(
+          discovered.manifest,
+          moduleRef.moduleName,
+          options.environment,
+          moduleEnv,
+        );
+        if (lifecycle.adminProbePath) {
+          await assertStorageAdminProbe({
+            baseUrl: options.baseUrl,
+            adminProbePath: lifecycle.adminProbePath,
+            label: `${moduleRef.repoName} / ${moduleRef.moduleName} (${moduleConfig.service})`,
+            ...(lifecycle.adminProbe403Hint
+              ? { hintOn403: () => lifecycle.adminProbe403Hint! }
+              : {}),
+          });
+        }
+        const fixtureEnv = { ...moduleEnv, ...lifecycle.envVars };
+        const release = await acquireFixture({
+          fixtureKey: lifecycle.fixtureKey,
+          resolvedPayload: lifecycle.resolvedPayload as unknown as Record<
+            string,
+            unknown
+          >,
+          cwd: repoPath,
+          env: fixtureEnv,
+          setup: lifecycle.setup,
+          teardown: lifecycle.teardown,
+        });
+        releases.push(release);
+        Object.assign(moduleEnv, lifecycle.envVars);
+      }
+
+      const testFile = path.resolve(
+        repoPath,
+        moduleConfig.testDir,
+        moduleConfig.testMatch,
+      );
+      const moduleKey = `${moduleRef.repoName}/${moduleRef.moduleName}`;
+      // Absolute: k6 resolves relative paths against its inherited cwd.
+      const summaryPath = path.resolve(
+        getDistRoot(),
+        getPerfSummaryArtifactPath(moduleKey),
+      );
+      const result = await spawnK6Process(testFile, moduleEnv, summaryPath);
+      completedModuleKeys.push(moduleKey);
+      k6Outcome = result;
+      if (!result.success) {
+        break;
+      }
+    }
+
+    if (
+      disabledSkipCount === options.modules.length &&
+      options.modules.length > 0
+    ) {
+      throw new Error(
+        `All requested performance modules are disabled in manifest: ${options.modules
+          .map((m) => `${m.repoName}/${m.moduleName}`)
+          .join(", ")}`,
+      );
+    }
+  } catch (e) {
+    caughtError = e;
+  } finally {
+    try {
+      await releaseFixturesForConsumer(releases);
+    } catch (e) {
+      teardownFailed = true;
+      logPerfTeardownFailure(e);
+    }
+    console.log("  Storage fixture teardown completed.");
+  }
+
+  if (completedModuleKeys.length > 0) {
+    try {
+      writeCurrentPerfRunReport({
+        environment: options.environment,
+        modules: completedModuleKeys,
+        finishedAt: new Date().toISOString(),
+      });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      console.warn(`Failed to generate perf report: ${msg}`);
+    }
+  }
+
+  if (caughtError !== undefined) {
+    throw caughtError;
+  }
+  if (teardownFailed) {
+    return {
+      success: false,
+      exitCode: k6Outcome.success ? 1 : k6Outcome.exitCode,
+    };
+  }
+  return k6Outcome;
+}
+
+function cliArgs() {
+  return parseArgs({
+    options: {
+      env: { type: "string" },
+      repo: { type: "string", multiple: true },
+      module: { type: "string", multiple: true },
+      "base-url": { type: "string" },
+      "use-local-checkout": { type: "boolean" },
+    },
+  }).values;
+}
+
+/**
+ * Auto-resolve a base URL for perf runs from the manifest's
+ * `services.*.health.<env>` entry, falling back to
+ * `config/environments/<env>.json → baseUrls.api`.
+ */
+export function resolveBaseUrlFromManifest(
+  repoName: string,
+  moduleName: string,
+  environment: Environment,
+): string | null {
+  const discovered = findManifest(repoName);
+  if (!discovered) return null;
+
+  const moduleConfig = discovered.manifest.performance?.[moduleName];
+  if (!moduleConfig) return null;
+
+  const serviceName = moduleConfig.service ?? repoName;
+  const baseUrlKey = moduleConfig.baseUrlKey ?? "api";
+
+  const manifestUrl = resolveManifestBaseUrl({
+    manifest: discovered.manifest,
+    repoName,
+    serviceName,
+    environment,
+    baseUrlKey,
+  });
+  if (manifestUrl) return manifestUrl;
+
+  try {
+    const configPath = path.resolve(
+      `./config/environments/${environment}.json`,
+    );
+    const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    return config.baseUrls?.services?.[serviceName] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export async function main(): Promise<number> {
+  const values = cliArgs();
+  const repos = values.repo ?? [];
+  const moduleNames = values.module ?? [];
+  if (repos.length !== moduleNames.length || repos.length === 0) {
+    throw new Error(
+      "Performance runner requires matching --repo and --module arguments",
+    );
+  }
+
+  const environment = (values.env ??
+    process.env.E2E_ENVIRONMENT ??
+    "local") as Environment;
+
+  const baseUrl =
+    resolveBaseUrlFromManifest(repos[0], moduleNames[0], environment) ??
+    values["base-url"] ??
+    process.env.BASE_URL ??
+    process.env.BASE_API_URL;
+  if (!baseUrl) {
+    throw new Error(
+      "Could not determine base URL. Provide --base-url, set BASE_URL, " +
+        `or add a services.*.health.<env> entry in ${product().manifestYml}`,
+    );
+  }
+
+  const result = await runPerfModules({
+    modules: repos.map((repoName, index) => ({
+      repoName,
+      moduleName: moduleNames[index],
+    })),
+    environment,
+    baseUrl,
+    useLocalCheckout: values["use-local-checkout"] ?? false,
+    env: process.env,
+  });
+  return result.exitCode;
+}
+
+if (process.argv[1]?.endsWith("/run.ts")) {
+  main()
+    .then((exitCode) => {
+      process.exitCode = exitCode;
+    })
+    .catch((error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(message);
+      process.exitCode = 1;
+    });
+}

package/src/pillars/perf/scenarios/load-profile.js

@@ -0,0 +1,97 @@
+/**
+ * Load Test Scenarios
+ * Different load patterns for various testing needs
+ */
+
+/**
+ * Baseline Load Test
+ * Constant load to establish performance baseline
+ */
+export const baselineLoad = {
+  executor: "constant-vus",
+  vus: 10,
+  duration: "2m",
+  tags: { test_type: "baseline" },
+};
+
+/**
+ * Stress Test
+ * Gradually increase load to find breaking point
+ */
+export const stressTest = {
+  executor: "ramping-vus",
+  startVUs: 0,
+  stages: [
+    { duration: "2m", target: 50 }, // Ramp up to 50
+    { duration: "5m", target: 100 }, // Ramp up to 100
+    { duration: "2m", target: 200 }, // Ramp up to 200
+    { duration: "5m", target: 200 }, // Stay at 200
+    { duration: "2m", target: 0 }, // Ramp down
+  ],
+  tags: { test_type: "stress" },
+};
+
+/**
+ * Spike Test
+ * Sudden spike in traffic
+ */
+export const spikeTest = {
+  executor: "ramping-vus",
+  startVUs: 0,
+  stages: [
+    { duration: "30s", target: 10 }, // Normal load
+    { duration: "10s", target: 200 }, // Spike!
+    { duration: "1m", target: 200 }, // Sustain spike
+    { duration: "10s", target: 10 }, // Back to normal
+    { duration: "30s", target: 10 }, // Stay at normal
+    { duration: "10s", target: 0 }, // Ramp down
+  ],
+  tags: { test_type: "spike" },
+};
+
+/**
+ * Soak Test (Endurance Test)
+ * Sustained load over extended period
+ */
+export const soakTest = {
+  executor: "constant-vus",
+  vus: 50,
+  duration: "30m", // Run for 30 minutes
+  tags: { test_type: "soak" },
+};
+
+/**
+ * Breakpoint Test
+ * Incrementally increase load until system breaks
+ */
+export const breakpointTest = {
+  executor: "ramping-arrival-rate",
+  startRate: 10,
+  timeUnit: "1s",
+  preAllocatedVUs: 50,
+  maxVUs: 500,
+  stages: [
+    { duration: "1m", target: 10 },
+    { duration: "1m", target: 20 },
+    { duration: "1m", target: 40 },
+    { duration: "1m", target: 80 },
+    { duration: "1m", target: 160 },
+    { duration: "1m", target: 320 },
+  ],
+  tags: { test_type: "breakpoint" },
+};
+
+/**
+ * Peak Traffic Test
+ * Simulate peak business hours
+ */
+export const peakTrafficTest = {
+  executor: "ramping-vus",
+  startVUs: 0,
+  stages: [
+    { duration: "5m", target: 100 }, // Morning ramp up
+    { duration: "15m", target: 100 }, // Peak hours
+    { duration: "5m", target: 0 }, // Ramp down
+  ],
+  tags: { test_type: "peak" },
+};

package/src/pillars/perf/staging.ts

@@ -0,0 +1,73 @@
+import * as fs from "fs";
+import * as path from "path";
+
+export interface StagePerfTreeResult {
+  copiedFiles: number;
+  matchedTestFiles: number;
+}
+
+function normalizePath(value: string): string {
+  return value.split(path.sep).join("/");
+}
+
+function matchesTestPath(relativePath: string, testMatch: string): boolean {
+  const normalizedPath = normalizePath(relativePath);
+
+  if (normalizedPath === testMatch) {
+    return true;
+  }
+
+  if (testMatch.startsWith("**/*.")) {
+    return normalizedPath.endsWith(testMatch.slice("**/*".length));
+  }
+
+  if (testMatch.startsWith("**/")) {
+    const suffix = testMatch.slice(3);
+    return normalizedPath === suffix || normalizedPath.endsWith(`/${suffix}`);
+  }
+
+  if (!testMatch.includes("/")) {
+    return path.basename(normalizedPath) === testMatch;
+  }
+
+  return false;
+}
+
+export function stagePerfTree(
+  sourceDir: string,
+  destinationDir: string,
+  testMatch: string,
+): StagePerfTreeResult {
+  let copiedFiles = 0;
+  let matchedTestFiles = 0;
+
+  function copyRecursive(src: string, dst: string, relativeDir = ""): void {
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      const sourcePath = path.join(src, entry.name);
+      const destinationPath = path.join(dst, entry.name);
+      const relativePath = relativeDir
+        ? path.join(relativeDir, entry.name)
+        : entry.name;
+
+      if (entry.isDirectory()) {
+        fs.mkdirSync(destinationPath, { recursive: true });
+        copyRecursive(sourcePath, destinationPath, relativePath);
+        continue;
+      }
+
+      fs.copyFileSync(sourcePath, destinationPath);
+      copiedFiles += 1;
+      if (matchesTestPath(relativePath, testMatch)) {
+        matchedTestFiles += 1;
+      }
+    }
+  }
+
+  fs.mkdirSync(destinationDir, { recursive: true });
+  copyRecursive(sourceDir, destinationDir);
+
+  return {
+    copiedFiles,
+    matchedTestFiles,
+  };
+}