@veducio/keja 0.0.0-stage → 0.3.0

package/src/http/create-app.ts

@@ -0,0 +1,196 @@
+import { Scalar } from "@scalar/hono-api-reference";
+import { Hono } from "hono";
+import { frameworkError, projectError } from "../errors/framework-errors.ts";
+import type { RouteDefinition } from "../route/define.ts";
+import {
+  type MiddlewareDefinition,
+  runMiddleware,
+} from "../route/middleware.ts";
+import type { ServiceIdentity } from "../server/identity.ts";
+import {
+  resolveVersionToken,
+  type VersionDefinition,
+} from "../versioning/define.ts";
+import { selectRoute } from "../versioning/select.ts";
+import { createOpenApiDocument } from "./openapi.ts";
+
+export function createHttpApp(options: {
+  title: string;
+  versions: readonly VersionDefinition[];
+  routes: readonly RouteDefinition[];
+  middleware?: readonly MiddlewareDefinition<object>[];
+  server?: string | null;
+  identity?: ServiceIdentity;
+  postOnly?: boolean;
+}) {
+  validateRoutes(options.versions, options.routes, options.postOnly === true);
+  const document = createOpenApiDocument(
+    options.title,
+    options.routes,
+    options.server,
+  );
+  const app = new Hono();
+  app.get("/_health", (c) => c.json({ status: "ok" }));
+  if (options.identity) {
+    app.get("/_identity", (c) => c.json(options.identity));
+  }
+  app.get("/_openapi.json", (c) => c.json(document));
+  app.get(
+    "/docs",
+    Scalar({
+      url: "/_openapi.json",
+      hideClientButton: true,
+      showDeveloperTools: "never",
+    }),
+  );
+  app.all("/*", (c) =>
+    dispatch(
+      c.req.raw,
+      options.versions,
+      options.routes,
+      options.middleware ?? [],
+      options.postOnly === true,
+    ),
+  );
+  return app;
+}
+
+async function dispatch(
+  request: Request,
+  versions: readonly VersionDefinition[],
+  routes: readonly RouteDefinition[],
+  middleware: readonly MiddlewareDefinition<object>[],
+  postOnly: boolean,
+) {
+  if (postOnly && request.method !== "POST") {
+    return Response.json(frameworkError("methodNotAllowed"), { status: 405 });
+  }
+  const url = new URL(request.url);
+  const pathname = url.pathname;
+  const slash = pathname.indexOf("/", 1);
+  const token = slash === -1 ? pathname.slice(1) : pathname.slice(1, slash);
+  const remainder = slash === -1 ? "/" : pathname.slice(slash);
+  if (token.length === 0) {
+    return Response.json(frameworkError("notFound"), { status: 404 });
+  }
+  const requested = resolveVersionToken(token, versions);
+  if (!requested) {
+    return Response.json(frameworkError("unknownVersion"), { status: 404 });
+  }
+  const selected = selectRoute(
+    routes,
+    versions,
+    request.method,
+    remainder,
+    requested,
+  );
+  if (!selected) {
+    return Response.json(frameworkError("notFound"), { status: 404 });
+  }
+  return runMiddleware(
+    [
+      ...middleware.map((definition) => ({
+        definition,
+        allowFields: false,
+      })),
+      ...selected.route.middleware.map((definition) => ({
+        definition,
+        allowFields: true,
+      })),
+    ],
+    {
+      request,
+      version: requested.id,
+      params: selected.params,
+    },
+    async (fields) => {
+      const parsed = await parseRequest(
+        selected.route,
+        selected.params,
+        url,
+        request,
+      );
+      if (!parsed.ok) {
+        return Response.json(
+          frameworkError("invalidRequest", { issues: parsed.issues }),
+          { status: 400 },
+        );
+      }
+      return selected.route.handle({ ...parsed.input, fields });
+    },
+  );
+}
+
+async function parseRequest(
+  route: RouteDefinition,
+  params: Record<string, string>,
+  url: URL,
+  request: Request,
+) {
+  const input: {
+    params?: unknown;
+    query?: unknown;
+    body?: unknown;
+  } = {};
+  if (route.request.params) {
+    const parsed = route.request.params.safeParse(params);
+    if (!parsed.success) {
+      return { ok: false as const, issues: parsed.error.issues };
+    }
+    input.params = parsed.data;
+  }
+  if (route.request.query) {
+    const parsed = route.request.query.safeParse(
+      Object.fromEntries(url.searchParams),
+    );
+    if (!parsed.success) {
+      return { ok: false as const, issues: parsed.error.issues };
+    }
+    input.query = parsed.data;
+  }
+  if (route.request.body) {
+    let body: unknown;
+    try {
+      body = await request.json();
+    } catch {
+      return {
+        ok: false as const,
+        issues: [{ message: "Request body must be JSON" }],
+      };
+    }
+    const parsed = route.request.body.safeParse(body);
+    if (!parsed.success) {
+      return { ok: false as const, issues: parsed.error.issues };
+    }
+    input.body = parsed.data;
+  }
+  return { ok: true as const, input };
+}
+
+function validateRoutes(
+  versions: readonly VersionDefinition[],
+  routes: readonly RouteDefinition[],
+  postOnly: boolean,
+) {
+  const known = new Set(versions.map((version) => version.id));
+  const seen = new Set<string>();
+  for (const route of routes) {
+    if (postOnly && route.method !== "post") {
+      throw projectError(
+        "serviceMethod",
+        `${route.method.toUpperCase()} ${route.path} must use POST`,
+      );
+    }
+    if (!known.has(route.version)) {
+      throw projectError(
+        "unknownRouteVersion",
+        `${route.method.toUpperCase()} ${route.path} uses unknown version ${route.version}`,
+      );
+    }
+    const key = `${route.method} ${route.path} ${route.version}`;
+    if (seen.has(key)) {
+      throw projectError("duplicateRoute", `Duplicate route ${key}`);
+    }
+    seen.add(key);
+  }
+}

package/src/http/openapi.ts

@@ -0,0 +1,111 @@
+import { createRoute, OpenAPIHono } from "@hono/zod-openapi";
+import { type ZodType, z } from "zod";
+import type { RouteDefinition, RouteResponse } from "../route/define.ts";
+
+export function createOpenApiDocument(
+  title: string,
+  routes: readonly RouteDefinition[],
+  server?: string | null,
+) {
+  const spec = new OpenAPIHono();
+  for (const route of routes) {
+    spec.openapi(
+      createRoute({
+        method: route.method,
+        path: openApiPath(route.version, route.path),
+        request: openApiRequest(route) as never,
+        responses: openApiResponses(route.responses) as never,
+      }),
+      (c) => c.json({}, 200) as never,
+    );
+  }
+  return spec.getOpenAPIDocument({
+    openapi: "3.0.0",
+    info: {
+      title,
+      version: "0.1.0",
+    },
+    ...(server ? { servers: [{ url: server }] } : {}),
+  });
+}
+
+function openApiPath(version: string, path: string) {
+  const converted = path.replaceAll(/:([A-Za-z0-9_]+)/g, "{$1}");
+  return `/${version}${converted.startsWith("/") ? converted : `/${converted}`}`;
+}
+
+function openApiRequest(route: RouteDefinition) {
+  const request: {
+    params?: ZodType;
+    query?: ZodType;
+    body?: {
+      content: {
+        "application/json": {
+          schema: ZodType;
+        };
+      };
+      required: true;
+    };
+  } = {};
+  if (route.request.params) {
+    request.params = route.request.params;
+  }
+  if (route.request.query) {
+    request.query = route.request.query;
+  }
+  if (route.request.body) {
+    request.body = {
+      content: {
+        "application/json": {
+          schema: route.request.body,
+        },
+      },
+      required: true,
+    };
+  }
+  return request;
+}
+
+function openApiResponses(responses: readonly RouteResponse[]) {
+  const documented: Record<
+    number,
+    {
+      description: string;
+      content: {
+        "application/json": {
+          schema: ZodType;
+        };
+      };
+    }
+  > = {};
+  const grouped = new Map<number, RouteResponse[]>();
+  for (const defined of responses) {
+    grouped.set(defined.code, [...(grouped.get(defined.code) ?? []), defined]);
+  }
+  for (const [status, group] of grouped) {
+    documented[status] = {
+      description: group.map((defined) => defined.name).join(", "),
+      content: {
+        "application/json": {
+          schema: group.length === 1 ? group[0].schema : unionSchema(group),
+        },
+      },
+    };
+  }
+  if (Object.keys(documented).length === 0) {
+    documented[200] = {
+      description: "200",
+      content: {
+        "application/json": {
+          schema: z.object({}),
+        },
+      },
+    };
+  }
+  return documented;
+}
+
+function unionSchema(group: RouteResponse[]) {
+  const schemas = group.map((defined) => defined.schema);
+  return z.union(schemas as [ZodType, ZodType, ...ZodType[]]);
+}

package/src/process/slot.ts

@@ -0,0 +1,18 @@
+export function processValue<Value extends object>(
+  name: string,
+  create: () => Value,
+) {
+  const key = Symbol.for(`keja.${name}`);
+  const host = globalThis as Record<symbol, Value | undefined>;
+  const existing = host[key];
+  if (existing) {
+    return existing;
+  }
+  const created = create();
+  host[key] = created;
+  return created;
+}
+
+export function processBrand(name: string) {
+  return Symbol.for(`keja.${name}`);
+}

package/src/project/config.test.ts

@@ -0,0 +1,143 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { defineConfig, loadConfig, resolveProjectPaths } from "./config.ts";
+
+describe("defineConfig", () => {
+  it("uses the default project paths", () => {
+    expect(defineConfig()).toMatchObject({
+      versioning: "keja.versioning.ts",
+      public_path: "src/public",
+      service_path: "src/service",
+    });
+  });
+
+  it("keeps the paths that are set", () => {
+    expect(
+      defineConfig({
+        versioning: "config/versions.ts",
+        public_path: "routes/public",
+      }),
+    ).toMatchObject({
+      versioning: "config/versions.ts",
+      public_path: "routes/public",
+      service_path: "src/service",
+    });
+  });
+
+  it("keeps the database disabled until it is turned on", () => {
+    expect(defineConfig().database).toEqual({ enabled: false });
+    expect(defineConfig({ db: { enabled: false } }).database).toEqual({
+      enabled: false,
+    });
+    expect(defineConfig({ db: { enabled: true } }).database).toEqual({
+      enabled: true,
+      migrations: "migrations",
+    });
+    expect(
+      defineConfig({
+        db: { enabled: true, migrations: "db/migrations" },
+      }).database,
+    ).toEqual({
+      enabled: true,
+      migrations: "db/migrations",
+    });
+  });
+
+  it("rejects an empty path", () => {
+    expect(() => defineConfig({ service_path: "  " })).toThrow(
+      "keja.config.ts service_path must be a non-empty path",
+    );
+  });
+
+  it("keeps an optional Argus registry", () => {
+    expect(
+      defineConfig({
+        name: "billing",
+        argus: {
+          enabled: true,
+          url: "https://argus.veducio.com/",
+          env: "staging",
+          username: "argus",
+          password: "secret",
+          public: "billing",
+        },
+      }).argus,
+    ).toEqual({
+      enabled: true,
+      url: "https://argus.veducio.com",
+      env: "staging",
+      username: "argus",
+      password: "secret",
+      public: "billing",
+      service: null,
+    });
+    expect(defineConfig({ argus: { enabled: false } }).argus).toEqual({
+      enabled: false,
+    });
+    expect(() =>
+      defineConfig({
+        argus: { enabled: true, url: "argus.veducio.com", env: "staging" },
+      }),
+    ).toThrow("keja.config.ts argus.url must be an absolute http or https URL");
+  });
+
+  it("reads Vault settings from config", () => {
+    expect(
+      defineConfig({
+        vault: {
+          enabled: true,
+          address: "https://vault.example/",
+          token: "s.token",
+          namespace: "apps",
+          mount: "kv",
+        },
+      }).vault,
+    ).toEqual({
+      enabled: true,
+      address: "https://vault.example",
+      token: "s.token",
+      namespace: "apps",
+      mount: "kv",
+      transit_key: null,
+      transit_mount: "transit",
+      grant_max_exp: 900,
+    });
+    expect(defineConfig().vault).toEqual({ enabled: false });
+  });
+});
+
+describe("loadConfig", () => {
+  it("resolves the default paths from the project root", async () => {
+    const root = mkdtempSync(path.join(tmpdir(), "keja-config-"));
+    await expect(loadConfig(root)).resolves.toEqual({
+      config: null,
+      name: null,
+      argus: { enabled: false },
+      database: { enabled: false },
+      vault: { enabled: false },
+      versioning: path.resolve(root, "keja.versioning.ts"),
+      public: path.resolve(root, "src/public"),
+      service: path.resolve(root, "src/service"),
+    });
+  });
+
+  it("resolves custom paths from the project root", () => {
+    const root = path.resolve("app");
+    expect(
+      resolveProjectPaths(
+        root,
+        defineConfig({
+          versioning: "versioning/api.ts",
+          public_path: "http/public",
+          service_path: "http/service",
+        }),
+      ),
+    ).toEqual({
+      versioning: path.resolve(root, "versioning/api.ts"),
+      public: path.resolve(root, "http/public"),
+      service: path.resolve(root, "http/service"),
+    });
+  });
+});