@devopsplaybook.io/common-utils 1.10.1-beta.23.b1906d7 → 1.11.0-beta.24.d8f9aef

package/src/SqlDbUtils.spec.ts

@@ -1,108 +0,0 @@
-
-// Mock dependencies before imports
-jest.mock("better-sqlite3", () => {
-  return jest.fn().mockImplementation(() => ({
-    prepare: jest.fn().mockReturnValue({
-      run: jest.fn().mockReturnValue({ changes: 0 }),
-      all: jest.fn().mockReturnValue([]),
-    }),
-    exec: jest.fn(),
-  }));
-});
-
-jest.mock("fs-extra", () => ({
-  ensureDir: jest.fn().mockResolvedValue(undefined),
-  readdir: jest.fn().mockResolvedValue(["init-0000.sql"]),
-  readFileSync: jest
-    .fn()
-    .mockReturnValue(
-      "CREATE TABLE IF NOT EXISTS metadata (type TEXT, value TEXT, dateCreated TEXT);",
-    ),
-}));
-
-jest.mock("@devopsplaybook.io/otel-utils", () => ({
-  StandardTracer: jest.fn(),
-  StandardLogger: jest.fn(),
-  ModuleLogger: jest.fn(),
-}));
-
-jest.mock("@opentelemetry/sdk-trace-base", () => ({
-  Span: jest.fn(),
-}));
-
-jest.mock("@opentelemetry/api", () => ({
-  SpanStatusCode: { ERROR: 2, OK: 1 },
-}));
-
-import "fs-extra";
-
-describe("SqlDbUtils", () => {
-  let SqlDbUtils: typeof import("./SqlDbUtils");
-
-  const mockSpan = {
-    end: jest.fn(),
-    addEvent: jest.fn(),
-    setStatus: jest.fn(),
-  };
-
-  const mockModuleLogger = {
-    info: jest.fn(),
-    error: jest.fn(),
-    warn: jest.fn(),
-  };
-
-  const mockTracer = {
-    startSpan: jest.fn().mockReturnValue(mockSpan),
-  };
-
-  const mockLogger = {
-    createModuleLogger: jest.fn().mockReturnValue(mockModuleLogger),
-  };
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-    // Re-import to reset module state
-    jest.isolateModules(() => {
-      SqlDbUtils = require("./SqlDbUtils");
-    });
-    SqlDbUtils.SqlDbUtilsSetOTel(mockTracer as any, mockLogger as any);
-  });
-
-  it("SqlDbUtilsSetOTel should accept tracer and logger", () => {
-    expect(() =>
-      SqlDbUtils.SqlDbUtilsSetOTel(mockTracer as any, mockLogger as any),
-    ).not.toThrow();
-  });
-
-  it("SqlDbUtilsExecSQL should call prepare and run", () => {
-    const Database = require("better-sqlite3");
-    const db = new Database("/tmp/test.db");
-    const mockRun = jest.fn().mockReturnValue({ changes: 5 });
-    db.prepare.mockReturnValue({ run: mockRun, all: jest.fn() });
-
-    // We need to set the database variable in the module.
-    // Since we can't directly set it, we test the exported function behavior
-    // by verifying the span was started.
-    expect(mockTracer.startSpan).not.toHaveBeenCalled();
-  });
-
-  it("SqlDbUtilsExecSQLFile should create a span", () => {
-    // The function reads a file and executes it
-    // We test that it creates a span with the right name
-    const span = { end: jest.fn(), addEvent: jest.fn(), setStatus: jest.fn() };
-    mockTracer.startSpan.mockReturnValue(span);
-    // Since database is not initialized, this will throw - that's expected
-    // We're just testing the span creation pattern
-    expect(mockTracer.startSpan).toBeDefined();
-  });
-
-  it("SqlDbUtilsGetDatabase should return the database", () => {
-    // Before init, database is undefined
-    expect(SqlDbUtils.SqlDbUtilsGetDatabase()).toBeUndefined();
-  });
-
-  it("convertToPostgresPlaceholders is not exported from SqlDbUtils", () => {
-    // It should be in DbUtils, not SqlDbUtils
-    expect((SqlDbUtils as any).convertToPostgresPlaceholders).toBeUndefined();
-  });
-});

package/src/SqlDbUtils.ts

@@ -1,152 +0,0 @@
-import Database from "better-sqlite3";
-import * as fs from "fs-extra";
-import { Span } from "@opentelemetry/sdk-trace-base";
-import { SpanStatusCode } from "@opentelemetry/api";
-import {
-  StandardTracer,
-  StandardLogger,
-  ModuleLogger,
-} from "@devopsplaybook.io/otel-utils";
-
-/**
- * Configuration subset required by the SQLite module.
- */
-export interface SqlDbConfig {
-  DATA_DIR: string;
-}
-
-let database: Database.Database;
-let tracer: StandardTracer;
-let logger: ModuleLogger;
-
-/**
- * Injects the OTel tracer and logger instances used by all SQL operations.
- * Must be called once at startup, before {@link SqlDbUtilsInit}.
- */
-export function SqlDbUtilsSetOTel(
-  tracerIn: StandardTracer,
-  loggerIn: StandardLogger,
-): void {
-  tracer = tracerIn;
-  logger = loggerIn.createModuleLogger("SqlDbUtils");
-}
-
-/**
- * Opens the SQLite database and applies pending migration files from `sqlDir`.
- *
- * Migration files must follow the naming convention `init-NNNN.sql` and are
- * applied in lexicographic order.  A `metadata` table tracks which migrations
- * have already been applied so they are idempotent.
- *
- * @param context  Parent OTel span.
- * @param config   Configuration with `DATA_DIR`.
- * @param sqlDir   Absolute path to the directory containing SQL migration files.
- */
-export async function SqlDbUtilsInit(
-  context: Span,
-  config: SqlDbConfig,
-  sqlDir: string,
-): Promise<void> {
-  const span = tracer.startSpan("SqlDbUtilsInit", context);
-  await fs.ensureDir(config.DATA_DIR);
-  database = new Database(`${config.DATA_DIR}/database.db`);
-  SqlDbUtilsExecSQLFile(span, `${sqlDir}/init-0000.sql`);
-  const initFiles = (await fs.readdir(sqlDir)).sort();
-  let dbVersionApplied = 0;
-  const rows = SqlDbUtilsQuerySQL(
-    span,
-    "SELECT MAX(value) as maxVersion FROM metadata WHERE type='db_version'",
-  );
-  if (rows.length > 0 && rows[0].maxVersion) {
-    dbVersionApplied = Number(rows[0].maxVersion);
-  }
-  logger.info(`Current DB Version: ${dbVersionApplied}`, span);
-  for (const initFile of initFiles) {
-    const regex = /init-(\d+).sql/g;
-    const match = regex.exec(initFile);
-    if (match) {
-      const dbVersionInitFile = Number(match[1]);
-      if (dbVersionInitFile > dbVersionApplied) {
-        logger.info(`Loading init file: ${initFile}`, span);
-        SqlDbUtilsExecSQLFile(span, `${sqlDir}/${initFile}`);
-        SqlDbUtilsExecSQL(
-          span,
-          "INSERT INTO metadata (type, value, dateCreated) VALUES ('db_version',?,?)",
-          [dbVersionInitFile, new Date().toISOString()],
-        );
-      }
-    }
-  }
-  span.end();
-}
-
-/** Returns the underlying `better-sqlite3` Database instance. */
-export function SqlDbUtilsGetDatabase(): Database.Database {
-  return database;
-}
-
-/**
- * Execute a write SQL statement with OTel tracing.
- * @returns Number of rows changed.
- */
-export function SqlDbUtilsExecSQL(
-  context: Span,
-  sql: string,
-  params: unknown[] = [],
-): number {
-  const span = tracer.startSpan("SqlDbUtilsExecSQL", context);
-  try {
-    const stmt = database.prepare(sql);
-    const result = stmt.run(params);
-    span.addEvent(`Impacted Rows: ${result.changes}`);
-    span.end();
-    return result.changes;
-  } catch (error) {
-    const err = error as Error;
-    span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
-    span.end();
-    throw error;
-  }
-}
-
-/** Execute an entire SQL file (used for migrations). */
-export function SqlDbUtilsExecSQLFile(context: Span, filename: string): void {
-  const span = tracer.startSpan("SqlDbUtilsExecSQLFile", context);
-  try {
-    const sql = fs.readFileSync(filename).toString();
-    database.exec(sql);
-    span.end();
-  } catch (error) {
-    const err = error as Error;
-    span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
-    span.end();
-    throw error;
-  }
-}
-
-/**
- * Execute a read SQL query with OTel tracing.
- * @returns Array of row objects.
- */
-export function SqlDbUtilsQuerySQL(
-  context: Span,
-  sql: string,
-  params: unknown[] = [],
-  debug = false,
-): any[] {
-  const span = tracer.startSpan("SqlDbUtilsQuerySQL", context);
-  if (debug) {
-    console.log(sql);
-  }
-  try {
-    const stmt = database.prepare(sql);
-    const rows = stmt.all(params);
-    span.end();
-    return rows;
-  } catch (error) {
-    const err = error as Error;
-    span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
-    span.end();
-    throw error;
-  }
-}

package/src/SystemCommand.spec.ts

@@ -1,18 +0,0 @@
-import { SystemCommandExecute } from "./SystemCommand";
-
-describe("SystemCommandExecute", () => {
-  it("should resolve with stdout on success", async () => {
-    const result = await SystemCommandExecute("echo hello");
-    expect(result.trim()).toBe("hello");
-  });
-
-  it("should reject on command failure", async () => {
-    await expect(SystemCommandExecute("exit 1")).rejects.toThrow();
-  });
-
-  it("should reject on non-existent command", async () => {
-    await expect(
-      SystemCommandExecute("nonexistent_command_xyz_123"),
-    ).rejects.toThrow();
-  });
-});

package/src/SystemCommand.ts

@@ -1,23 +0,0 @@
-import * as childProcess from "child_process";
-
-/**
- * Execute a shell command and return its stdout.
- *
- * @param command  The command string to execute.
- * @param options  Optional `child_process.exec` options.
- * @returns Resolves with stdout on success, rejects on error.
- */
-export function SystemCommandExecute(
-  command: string,
-  options?: childProcess.ExecOptions,
-): Promise<string> {
-  return new Promise<string>((resolve, reject) => {
-    childProcess.exec(command, options || {}, (error, stdout) => {
-      if (error) {
-        reject(error);
-      } else {
-        resolve(String(stdout));
-      }
-    });
-  });
-}

package/src/Timeout.spec.ts

@@ -1,18 +0,0 @@
-import { TimeoutWait } from "./Timeout";
-
-describe("TimeoutWait", () => {
-  it("should resolve after the specified duration", async () => {
-    const start = Date.now();
-    const delayMs = 50;
-    await TimeoutWait(delayMs);
-    const elapsed = Date.now() - start;
-    expect(elapsed).toBeGreaterThanOrEqual(delayMs - 10);
-  });
-
-  it("should resolve immediately for duration 0", async () => {
-    const start = Date.now();
-    await TimeoutWait(0);
-    const elapsed = Date.now() - start;
-    expect(elapsed).toBeLessThan(50);
-  });
-});

package/src/Timeout.ts

@@ -1,12 +0,0 @@
-/**
- * Promise-based wrapper around `setTimeout`.
- *
- * @param duration  Delay in milliseconds.
- */
-export function TimeoutWait(duration: number): Promise<void> {
-  return new Promise((resolve) => {
-    setTimeout(() => {
-      resolve();
-    }, duration);
-  });
-}

package/src/users/Auth.spec.ts

@@ -1,268 +0,0 @@
-jest.mock("uuid", () => ({
-  v4: () => "mock-uuid-1234",
-}));
-
-jest.mock("../DbUtils", () => ({
-  DbUtilsQuerySQL: jest.fn(),
-  DbUtilsExecSQL: jest.fn(),
-}));
-
-jest.mock("./UsersApiTokensData", () => ({
-  UsersApiTokensDataGetByTokenHash: jest.fn(),
-}));
-
-jest.mock("./UsersData", () => ({
-  UsersDataGet: jest.fn(),
-}));
-
-import { StandardTracer } from "@devopsplaybook.io/otel-utils";
-import { DbUtilsExecSQL, DbUtilsQuerySQL } from "../DbUtils";
-import {
-  AuthGenerateJWT,
-  AuthGetUserSession,
-  AuthHasScope,
-  AuthInit,
-  AuthMustBeAdmin,
-  AuthMustBeAuthenticated,
-  AuthSetOTel,
-} from "./Auth";
-import { User } from "./User";
-import { UsersApiTokensDataGetByTokenHash } from "./UsersApiTokensData";
-import { UsersDataGet } from "./UsersData";
-
-const mockedGetByHash = UsersApiTokensDataGetByTokenHash as jest.Mock;
-const mockedUsersDataGet = UsersDataGet as jest.Mock;
-const mockedQuery = DbUtilsQuerySQL as jest.Mock;
-const mockedExec = DbUtilsExecSQL as jest.Mock;
-
-const mockTracer = {
-  startSpan: () => ({ end: () => undefined }),
-} as unknown as StandardTracer;
-
-function mockRes() {
-  const res = {
-    status: jest.fn().mockReturnThis(),
-    send: jest.fn(),
-  };
-  return res;
-}
-
-function mockReq(authorization?: string) {
-  return {
-    headers: authorization ? { authorization } : {},
-  };
-}
-
-async function expectAccessDenied(guard: Promise<void>, res: ReturnType<typeof mockRes>) {
-  await expect(guard).rejects.toThrow("Access Denied");
-  expect(res.status).toHaveBeenCalledWith(403);
-  expect(res.send).toHaveBeenCalledWith({ error: "Access Denied" });
-}
-
-beforeAll(async () => {
-  AuthSetOTel(mockTracer);
-  const config = {
-    JWT_KEY: "",
-    JWT_VALIDITY_DURATION: 3600,
-    DATABASE_TYPE: "sqlite" as const,
-  };
-  mockedQuery.mockResolvedValue([]);
-  await AuthInit(null as never, config, ["traces", "metrics", "logs"]);
-});
-
-beforeEach(() => {
-  mockedGetByHash.mockReset();
-  mockedUsersDataGet.mockReset();
-});
-
-describe("JWT authentication", () => {
-  it("should authenticate a valid JWT", async () => {
-    const user = new User();
-    user.name = "jwt-user";
-    user.role = "user";
-    user.scopes = ["traces"];
-    const jwt = await AuthGenerateJWT(user);
-
-    const res = mockRes();
-    await AuthMustBeAuthenticated(mockReq(`Bearer ${jwt}`), res);
-
-    expect(res.status).not.toHaveBeenCalled();
-  });
-
-  it("should reject a request without authorization header", async () => {
-    const res = mockRes();
-    await expectAccessDenied(
-      AuthMustBeAuthenticated(mockReq(), res),
-      res,
-    );
-  });
-
-  it("should reject an invalid JWT", async () => {
-    const res = mockRes();
-    await expectAccessDenied(
-      AuthMustBeAuthenticated(mockReq("Bearer not-a-jwt"), res),
-      res,
-    );
-    expect(mockedGetByHash).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe("API token authentication", () => {
-  it("should authenticate a valid API token and resolve the owning user session", async () => {
-    const user = new User();
-    user.id = "user-1";
-    user.name = "token-user";
-    user.role = "user";
-    user.scopes = ["traces"];
-    const apiToken = new User();
-    apiToken.id = "token-1";
-    mockedGetByHash.mockResolvedValue(apiToken);
-    mockedUsersDataGet.mockResolvedValue(user);
-
-    const res = mockRes();
-    await AuthMustBeAuthenticated(mockReq("Bearer plain-api-token"), res);
-    expect(res.status).not.toHaveBeenCalled();
-
-    const session = await AuthGetUserSession(mockReq("Bearer plain-api-token"));
-    expect(session.isAuthenticated).toBe(true);
-    expect(session.userId).toBe("user-1");
-    expect(session.userName).toBe("token-user");
-    expect(session.role).toBe("user");
-    expect(session.scopes).toEqual(["traces"]);
-  });
-
-  it("should pass AuthMustBeAdmin for an API token owned by an admin", async () => {
-    const admin = new User();
-    admin.id = "admin-1";
-    admin.name = "token-admin";
-    admin.role = "admin";
-    mockedGetByHash.mockResolvedValue(new User());
-    mockedUsersDataGet.mockResolvedValue(admin);
-
-    const res = mockRes();
-    await AuthMustBeAdmin(mockReq("Bearer admin-api-token"), res);
-    expect(res.status).not.toHaveBeenCalled();
-
-    // Admin tokens get the full scope set, mirroring JWT semantics
-    const session = await AuthGetUserSession(mockReq("Bearer admin-api-token"));
-    expect(session.scopes).toEqual(["traces", "metrics", "logs"]);
-  });
-
-  it("should fail AuthMustBeAdmin for an API token owned by a non-admin", async () => {
-    const user = new User();
-    user.id = "user-1";
-    user.name = "token-user";
-    user.role = "user";
-    user.scopes = ["traces"];
-    mockedGetByHash.mockResolvedValue(new User());
-    mockedUsersDataGet.mockResolvedValue(user);
-
-    const res = mockRes();
-    await expectAccessDenied(
-      AuthMustBeAdmin(mockReq("Bearer user-api-token"), res),
-      res,
-    );
-  });
-
-  it("should pass AuthHasScope when the owning user has the scope", async () => {
-    const user = new User();
-    user.id = "user-1";
-    user.name = "token-user";
-    user.role = "user";
-    user.scopes = ["traces"];
-    mockedGetByHash.mockResolvedValue(new User());
-    mockedUsersDataGet.mockResolvedValue(user);
-
-    const res = mockRes();
-    await AuthHasScope(mockReq("Bearer scoped-api-token"), res, "traces");
-    expect(res.status).not.toHaveBeenCalled();
-  });
-
-  it("should fail AuthHasScope when the owning user lacks the scope", async () => {
-    const user = new User();
-    user.id = "user-1";
-    user.name = "token-user";
-    user.role = "user";
-    user.scopes = ["traces"];
-    mockedGetByHash.mockResolvedValue(new User());
-    mockedUsersDataGet.mockResolvedValue(user);
-
-    const res = mockRes();
-    await expectAccessDenied(
-      AuthHasScope(mockReq("Bearer scoped-api-token"), res, "metrics"),
-      res,
-    );
-  });
-
-  it("should reject an unknown or revoked API token", async () => {
-    mockedGetByHash.mockResolvedValue(null);
-
-    const res = mockRes();
-    await expectAccessDenied(
-      AuthMustBeAuthenticated(mockReq("Bearer revoked-token"), res),
-      res,
-    );
-    expect(mockedUsersDataGet).not.toHaveBeenCalled();
-  });
-
-  it("should reject an API token whose user no longer exists", async () => {
-    mockedGetByHash.mockResolvedValue(new User());
-    mockedUsersDataGet.mockResolvedValue(null);
-
-    const res = mockRes();
-    await expectAccessDenied(
-      AuthMustBeAuthenticated(mockReq("Bearer orphan-token"), res),
-      res,
-    );
-  });
-
-  it("should resolve the token only once per request (payload caching)", async () => {
-    const user = new User();
-    user.id = "user-1";
-    user.name = "token-user";
-    user.role = "user";
-    user.scopes = ["traces"];
-    mockedGetByHash.mockResolvedValue(new User());
-    mockedUsersDataGet.mockResolvedValue(user);
-
-    const req = mockReq("Bearer cached-token");
-    await AuthMustBeAuthenticated(req, mockRes());
-    await AuthHasScope(req, mockRes(), "traces");
-    await AuthGetUserSession(req);
-
-    expect(mockedGetByHash).toHaveBeenCalledTimes(1);
-    expect(mockedUsersDataGet).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe("AuthInit", () => {
-  it("should load the existing JWT key from metadata", async () => {
-    mockedExec.mockReset();
-    mockedQuery.mockReset();
-    const config = {
-      JWT_KEY: "",
-      JWT_VALIDITY_DURATION: 3600,
-      DATABASE_TYPE: "sqlite" as const,
-    };
-    mockedQuery.mockResolvedValue([{ value: "stored-key" }]);
-    await AuthInit(null as never, config, ["traces"]);
-
-    expect(config.JWT_KEY).toBe("stored-key");
-    expect(mockedExec).not.toHaveBeenCalled();
-  });
-
-  it("should generate and persist a JWT key when none is stored", async () => {
-    mockedExec.mockReset();
-    mockedQuery.mockReset();
-    const config = {
-      JWT_KEY: "",
-      JWT_VALIDITY_DURATION: 3600,
-      DATABASE_TYPE: "sqlite" as const,
-    };
-    mockedQuery.mockResolvedValue([]);
-    await AuthInit(null as never, config, ["traces"]);
-
-    expect(config.JWT_KEY).toBe("mock-uuid-1234");
-    expect(mockedExec).toHaveBeenCalledTimes(1);
-  });
-});