@veducio/keja 0.0.0-stage → 0.3.0

package/src/project/config.ts

@@ -0,0 +1,450 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { projectError } from "../errors/framework-errors.ts";
+import { freshImportUrl } from "./reload-graph.ts";
+
+const configBrand = "keja.config";
+
+const defaultConfig = {
+  versioning: "keja.versioning.ts",
+  public_path: "src/public",
+  service_path: "src/service",
+};
+
+export type ArgusSettings = {
+  url: string;
+  env: string;
+  username: string | null;
+  password: string | null;
+  public: string | null;
+  service: string | null;
+};
+
+export type ArgusConfigInput = {
+  enabled: boolean;
+  url?: string;
+  env?: string;
+  username?: string;
+  password?: string;
+  public?: string;
+  service?: string;
+};
+
+export type ArgusConfig =
+  | { enabled: false }
+  | ({ enabled: true } & ArgusSettings);
+
+export type DatabaseConfigInput = {
+  enabled: boolean;
+  migrations?: string;
+};
+
+export type DatabaseConfig =
+  | { enabled: false }
+  | { enabled: true; migrations: string };
+
+export type VaultSettings = {
+  address: string;
+  token: string;
+  namespace: string | null;
+  mount: string;
+  transit_key: string | null;
+  transit_mount: string;
+  grant_max_exp: number;
+};
+
+export type VaultConfigInput = {
+  enabled: boolean;
+  address?: string;
+  token?: string;
+  namespace?: string;
+  mount?: string;
+  transit_key?: string;
+  transit_mount?: string;
+  grant_max_exp?: number;
+};
+
+export type VaultConfig =
+  | { enabled: false }
+  | ({ enabled: true } & VaultSettings);
+
+export type KejaConfigInput = {
+  name?: string;
+  versioning?: string;
+  public_path?: string;
+  service_path?: string;
+  argus?: ArgusConfigInput;
+  db?: DatabaseConfigInput;
+  vault?: VaultConfigInput;
+};
+
+export type KejaConfig = {
+  name: string | null;
+  versioning: string;
+  public_path: string;
+  service_path: string;
+  argus: ArgusConfig;
+  database: DatabaseConfig;
+  vault: VaultConfig;
+};
+
+export function defineConfig(input: KejaConfigInput = {}) {
+  const config: KejaConfig = {
+    name: optionalText(input.name, "name", "service name"),
+    versioning: configPath(
+      input.versioning,
+      defaultConfig.versioning,
+      "versioning",
+    ),
+    public_path: configPath(
+      input.public_path,
+      defaultConfig.public_path,
+      "public_path",
+    ),
+    service_path: configPath(
+      input.service_path,
+      defaultConfig.service_path,
+      "service_path",
+    ),
+    argus: configArgus(input.argus),
+    database: configDatabase(input.db),
+    vault: configVault(input.vault),
+  };
+  return Object.assign(config, { [configBrand]: true as const });
+}
+
+export function isConfig(value: unknown): value is KejaConfig {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    configBrand in value &&
+    (value as Record<string, unknown>)[configBrand] === true &&
+    hasPath(value, "versioning") &&
+    hasPath(value, "public_path") &&
+    hasPath(value, "service_path") &&
+    hasName(value) &&
+    hasArgus(value) &&
+    hasDatabase(value) &&
+    hasVault(value)
+  );
+}
+
+export type ProjectPaths = {
+  config: string | null;
+  versioning: string;
+  public: string;
+  service: string;
+};
+
+export type LoadedConfig = ProjectPaths & {
+  name: string | null;
+  argus: ArgusConfig;
+  database: DatabaseConfig;
+  vault: VaultConfig;
+};
+
+export function resolveProjectPaths(root: string, config: KejaConfig) {
+  return {
+    versioning: path.resolve(root, config.versioning),
+    public: path.resolve(root, config.public_path),
+    service: path.resolve(root, config.service_path),
+  };
+}
+
+export async function loadConfig(
+  root: string,
+  generation?: string,
+): Promise<LoadedConfig> {
+  const file = path.join(root, "keja.config.ts");
+  if (!existsSync(file)) {
+    return loadedConfig(root, null, defineConfig());
+  }
+  const href = generation
+    ? freshImportUrl(file, generation)
+    : pathToFileURL(file).href;
+  const loaded = await import(href);
+  if (!isConfig(loaded.default)) {
+    throw projectError(
+      "invalidConfigFile",
+      `${file} must default-export defineConfig(...)`,
+    );
+  }
+  return loadedConfig(root, file, loaded.default);
+}
+
+function configPath(value: unknown, fallback: string, field: string) {
+  if (value === undefined) {
+    return fallback;
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts ${field} must be a non-empty path`,
+    );
+  }
+  return value.trim();
+}
+
+function loadedConfig(
+  root: string,
+  file: string | null,
+  config: KejaConfig,
+): LoadedConfig {
+  return {
+    config: file,
+    ...resolveProjectPaths(root, config),
+    name: config.name,
+    argus: config.argus,
+    database: resolvedDatabase(root, config.database),
+    vault: config.vault,
+  };
+}
+
+function resolvedDatabase(
+  root: string,
+  database: DatabaseConfig,
+): DatabaseConfig {
+  if (!database.enabled) {
+    return database;
+  }
+  return {
+    enabled: true,
+    migrations: path.resolve(root, database.migrations),
+  };
+}
+
+function configDatabase(
+  value: DatabaseConfigInput | undefined,
+): DatabaseConfig {
+  if (value === undefined) {
+    return { enabled: false };
+  }
+  if (!isEnabledObject(value)) {
+    throw projectError(
+      "invalidConfigFile",
+      "keja.config.ts db must be an object with enabled",
+    );
+  }
+  if (!value.enabled) {
+    return { enabled: false };
+  }
+  return {
+    enabled: true,
+    migrations: configPath(value.migrations, "migrations", "db.migrations"),
+  };
+}
+
+function configArgus(value: ArgusConfigInput | undefined): ArgusConfig {
+  if (value === undefined) {
+    return { enabled: false };
+  }
+  if (!isEnabledObject(value)) {
+    throw projectError(
+      "invalidConfigFile",
+      "keja.config.ts argus must be an object with enabled",
+    );
+  }
+  if (!value.enabled) {
+    return { enabled: false };
+  }
+  const username = optionalText(value.username, "argus.username", "username");
+  const password = optionalText(value.password, "argus.password", "password");
+  if ((username === null) !== (password === null)) {
+    throw projectError(
+      "invalidConfigFile",
+      "keja.config.ts argus.username and argus.password must both be set",
+    );
+  }
+  return {
+    enabled: true,
+    url: absoluteHttpUrl(value.url, "argus.url"),
+    env: requiredText(value.env, "argus.env", "environment name"),
+    username,
+    password,
+    public: optionalText(value.public, "argus.public", "service name"),
+    service: optionalText(value.service, "argus.service", "service name"),
+  };
+}
+
+function configVault(value: VaultConfigInput | undefined): VaultConfig {
+  if (value === undefined) {
+    return { enabled: false };
+  }
+  if (!isEnabledObject(value)) {
+    throw projectError(
+      "invalidConfigFile",
+      "keja.config.ts vault must be an object with enabled",
+    );
+  }
+  if (!value.enabled) {
+    return { enabled: false };
+  }
+  const namespace =
+    value.namespace ?? configEnv("VAULT_NAMESPACE") ?? undefined;
+  return {
+    enabled: true,
+    address: absoluteHttpUrl(
+      value.address ?? configEnv("VAULT_ADDR") ?? undefined,
+      "vault.address",
+    ),
+    token: requiredText(
+      value.token ?? configEnv("VAULT_TOKEN") ?? undefined,
+      "vault.token",
+      "token",
+    ),
+    namespace: optionalText(namespace, "vault.namespace", "namespace"),
+    mount: vaultMount(value.mount ?? configEnv("VAULT_KV_MOUNT") ?? "secret"),
+    transit_key:
+      value.transit_key === undefined
+        ? null
+        : vaultName(value.transit_key, "vault.transit_key"),
+    transit_mount: vaultName(
+      value.transit_mount ?? "transit",
+      "vault.transit_mount",
+    ),
+    grant_max_exp: grantMaxExp(value.grant_max_exp),
+  };
+}
+
+function isEnabledObject(value: unknown): value is { enabled: boolean } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { enabled?: unknown }).enabled === "boolean"
+  );
+}
+
+function absoluteHttpUrl(value: unknown, field: string) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts ${field} must be an absolute http or https URL`,
+    );
+  }
+  try {
+    const url = new URL(value.trim());
+    if (url.protocol === "http:" || url.protocol === "https:") {
+      return url.href.replace(/\/$/, "");
+    }
+  } catch {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts ${field} must be an absolute http or https URL`,
+    );
+  }
+  throw projectError(
+    "invalidConfigFile",
+    `keja.config.ts ${field} must be an absolute http or https URL`,
+  );
+}
+
+function vaultMount(value: string) {
+  return vaultName(value, "vault.mount");
+}
+
+function vaultName(value: string, field: string) {
+  const name = value.trim().replace(/^\/+|\/+$/g, "");
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts ${field} must be a name`,
+    );
+  }
+  return name;
+}
+
+function grantMaxExp(value: number | undefined) {
+  if (value === undefined) {
+    return 900;
+  }
+  if (
+    typeof value !== "number" ||
+    !Number.isInteger(value) ||
+    value < 1 ||
+    value > 86400
+  ) {
+    throw projectError(
+      "invalidConfigFile",
+      "keja.config.ts vault.grant_max_exp must be a whole number of seconds from 1 to 86400",
+    );
+  }
+  return value;
+}
+
+function configEnv(name: string) {
+  const runtime = globalThis as {
+    Bun?: { env?: Record<string, string | undefined> };
+  };
+  const value = runtime.Bun?.env?.[name] ?? process.env[name];
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function requiredText(value: unknown, field: string, label: string) {
+  const text = optionalText(value, field, label);
+  if (text === null) {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts ${field} must be a non-empty ${label}`,
+    );
+  }
+  return text;
+}
+
+function optionalText(value: unknown, field: string, label: string) {
+  if (value === undefined) {
+    return null;
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts ${field} must be a non-empty ${label}`,
+    );
+  }
+  return value.trim();
+}
+
+function hasName(value: object) {
+  const name = (value as KejaConfig).name;
+  return name === null || typeof name === "string";
+}
+
+function hasArgus(value: object) {
+  const argus = (value as KejaConfig).argus;
+  return (
+    typeof argus === "object" &&
+    argus !== null &&
+    (argus.enabled === false ||
+      (argus.enabled === true &&
+        typeof argus.url === "string" &&
+        typeof argus.env === "string"))
+  );
+}
+
+function hasVault(value: object) {
+  const vault = (value as KejaConfig).vault;
+  return (
+    typeof vault === "object" &&
+    vault !== null &&
+    (vault.enabled === false ||
+      (vault.enabled === true &&
+        typeof vault.address === "string" &&
+        typeof vault.token === "string" &&
+        typeof vault.mount === "string"))
+  );
+}
+
+function hasDatabase(value: object) {
+  const database = (value as KejaConfig).database;
+  return (
+    typeof database === "object" &&
+    database !== null &&
+    (database.enabled === false ||
+      (database.enabled === true && typeof database.migrations === "string"))
+  );
+}
+
+function hasPath(value: object, key: keyof KejaConfig) {
+  return typeof (value as KejaConfig)[key] === "string";
+}

package/src/project/load.test.ts

@@ -0,0 +1,60 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { defineRoute, response } from "../route/define.ts";
+import { collectRouteFiles, routesFromModule } from "./load.ts";
+
+describe("collectRouteFiles", () => {
+  it("keeps route modules nested several directories deep", async () => {
+    const root = mkdtempSync(path.join(tmpdir(), "keja-routes-"));
+    const publicDirectory = path.join(root, "public");
+    mkdirSync(path.join(publicDirectory, "orgs", "teams"), {
+      recursive: true,
+    });
+    writeFileSync(path.join(publicDirectory, "_middleware.ts"), "");
+    writeFileSync(path.join(publicDirectory, "orgs", "_middleware.ts"), "");
+    writeFileSync(
+      path.join(publicDirectory, "orgs", "teams", "members.ts"),
+      "",
+    );
+    writeFileSync(
+      path.join(publicDirectory, "orgs", "teams", "members.test.ts"),
+      "",
+    );
+
+    await expect(collectRouteFiles(publicDirectory)).resolves.toEqual([
+      "orgs/teams/members.ts",
+    ]);
+  });
+});
+
+describe("routesFromModule", () => {
+  it("reads a default route and named routes from one module", () => {
+    const ready = route("get", "/ready");
+    const list = route("get", "/jobs");
+    const create = route("post", "/jobs");
+    expect(
+      routesFromModule({
+        default: ready,
+        list,
+        create,
+        schema: z.object({ name: z.string() }),
+      }).map((item) => `${item.method} ${item.path}`),
+    ).toEqual(["get /ready", "get /jobs", "post /jobs"]);
+    expect(routesFromModule({ schema: z.string() })).toEqual([]);
+  });
+});
+
+function route(method: "get" | "post", routePath: string) {
+  return defineRoute({
+    method,
+    path: routePath,
+    version: "v1",
+    responses: {
+      Ok: response({ code: 200, json: z.object({ ok: z.literal(true) }) }),
+    },
+    handler: ({ respond }) => respond.Ok({ ok: true }),
+  });
+}

package/src/project/load.ts

@@ -0,0 +1,158 @@
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { projectError } from "../errors/framework-errors.ts";
+import { isRoute, type RouteDefinition } from "../route/define.ts";
+import {
+  type MiddlewareDefinition,
+  middlewareList,
+} from "../route/middleware.ts";
+import { isVersions, type VersionDefinition } from "../versioning/define.ts";
+import {
+  type ArgusConfig,
+  type DatabaseConfig,
+  loadConfig,
+  type ProjectPaths,
+  type VaultConfig,
+} from "./config.ts";
+import { beginProjectReload, freshImportUrl } from "./reload-graph.ts";
+
+export type LoadedProject = {
+  paths: ProjectPaths;
+  name: string | null;
+  argus: ArgusConfig;
+  vault: VaultConfig;
+  database: DatabaseConfig;
+  versions: VersionDefinition[];
+  publicRoutes: RouteDefinition[];
+  publicMiddleware: MiddlewareDefinition<object>[];
+  serviceRoutes: RouteDefinition[];
+  serviceMiddleware: MiddlewareDefinition<object>[];
+};
+
+export async function loadProject(
+  root: string,
+  options?: { generation?: string },
+): Promise<LoadedProject> {
+  const generation = options?.generation;
+  if (generation) {
+    beginProjectReload(root, generation);
+  }
+  const loaded = await loadConfig(root, generation);
+  const paths = loaded;
+  if (!existsSync(paths.versioning)) {
+    throw projectError("missingVersionFile", `Missing ${paths.versioning}`);
+  }
+  const versioning = await import(projectHref(paths.versioning, generation));
+  if (!isVersions(versioning.default)) {
+    throw projectError(
+      "invalidVersionFile",
+      `${paths.versioning} must default-export defineVersions(...)`,
+    );
+  }
+  const publicDirectory = paths.public;
+  const serviceDirectory = paths.service;
+  return {
+    paths,
+    name: loaded.name,
+    argus: loaded.argus,
+    vault: loaded.vault,
+    database: loaded.database,
+    versions: versioning.default.versions,
+    publicRoutes: await loadRoutes(publicDirectory, generation),
+    publicMiddleware: await loadServerMiddleware(publicDirectory, generation),
+    serviceRoutes: await loadRoutes(serviceDirectory, generation),
+    serviceMiddleware: await loadServerMiddleware(serviceDirectory, generation),
+  };
+}
+
+function projectHref(file: string, generation?: string) {
+  return generation
+    ? freshImportUrl(file, generation)
+    : pathToFileURL(file).href;
+}
+
+async function loadRoutes(directory: string, generation?: string) {
+  if (!existsSync(directory)) {
+    throw projectError("missingRouteDirectory", `Missing ${directory}`);
+  }
+  const routes: RouteDefinition[] = [];
+  for (const file of await collectRouteFiles(directory)) {
+    const loaded = await import(
+      projectHref(path.join(directory, file), generation)
+    );
+    const exported = routesFromModule(loaded);
+    if (exported.length === 0) {
+      throw projectError(
+        "invalidRouteFile",
+        `${file} must export defineRoute(...)`,
+      );
+    }
+    routes.push(...exported);
+  }
+  return routes;
+}
+
+async function loadServerMiddleware(directory: string, generation?: string) {
+  const file = path.join(directory, "_middleware.ts");
+  if (!existsSync(file)) {
+    return [];
+  }
+  const loaded = await import(projectHref(file, generation));
+  const exported = middlewareList(loaded.default);
+  if (!exported) {
+    throw projectError(
+      "invalidMiddlewareFile",
+      `${file} must default-export defineMiddleware(...)`,
+    );
+  }
+  return exported;
+}
+
+export function routesFromModule(module: object) {
+  const record = module as Record<string, unknown>;
+  const names = Object.keys(record).filter((name) => name !== "default");
+  const ordered = "default" in record ? ["default", ...names] : names;
+  const routes: RouteDefinition[] = [];
+  for (const name of ordered) {
+    const value = record[name];
+    if (isRoute(value)) {
+      routes.push(value);
+    }
+  }
+  return routes;
+}
+
+export async function collectRouteFiles(directory: string) {
+  const files = await walk(directory, "");
+  return files.filter(
+    (file) =>
+      file.endsWith(".ts") &&
+      !file.endsWith(".test.ts") &&
+      !isServerMiddlewareFile(file),
+  );
+}
+
+async function walk(directory: string, prefix: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...(await walk(path.join(directory, entry.name), relative)));
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(relative);
+    }
+  }
+  return files;
+}
+
+function isServerMiddlewareFile(file: string) {
+  const normalized = file.replaceAll("\\", "/");
+  return (
+    normalized === "_middleware.ts" || normalized.endsWith("/_middleware.ts")
+  );
+}

package/src/project/reload-graph.test.ts

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { freshImportUrl, resolveProjectImport } from "./reload-graph.ts";
+
+describe("project reload imports", () => {
+  const root = path.resolve("keja-app");
+  const route = path.join(root, "src", "public", "posts.ts");
+
+  it("adds a generation to a project file import", () => {
+    expect(freshImportUrl(route, "4")).toBe(`keja:${route}?keja=4`);
+  });
+
+  it("follows a relative import out of the route directory", () => {
+    const resolved = resolveProjectImport({
+      importer: `keja:${route}`,
+      specifier: "../data.ts",
+      projectRoot: root,
+      generation: "4",
+    });
+    const file = path.join(root, "src", "data.ts");
+    expect(resolved).toEqual({
+      path: `${file}?keja=4`,
+      namespace: "keja",
+      file,
+      outside: false,
+    });
+  });
+
+  it("follows the next file imported by that dependency", () => {
+    const data = path.join(root, "src", "data.ts");
+    const resolved = resolveProjectImport({
+      importer: `keja:${data}?keja=4`,
+      specifier: "./schema.ts",
+      projectRoot: root,
+      generation: "4",
+    });
+    const file = path.join(root, "src", "schema.ts");
+    expect(resolved?.path).toBe(`${file}?keja=4`);
+    expect(resolved?.file).toBe(file);
+  });
+
+  it("leaves package imports cached", () => {
+    expect(
+      resolveProjectImport({
+        importer: `keja:${route}`,
+        specifier: "@veducio/keja",
+        projectRoot: root,
+        generation: "4",
+      }),
+    ).toBeNull();
+  });
+});