@veducio/keja 0.0.0-stage → 0.2.3

package/src/http/create-app.test.ts

@@ -0,0 +1,340 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { frameworkErrors } from "../errors/framework-errors.ts";
+import { defineRoute, response } from "../route/define.ts";
+import { defineMiddleware } from "../route/middleware.ts";
+import { defineVersions } from "../versioning/define.ts";
+import { createHttpApp } from "./create-app.ts";
+
+const versions = defineVersions({
+  v1: { releasedAt: "2020-01-15" },
+  v2: { releasedAt: "2024-06-01" },
+}).versions;
+
+const userResponse = z.object({
+  id: z.string(),
+});
+
+const publicRoutes = [
+  defineRoute({
+    method: "get",
+    path: "/users/:id",
+    version: "v1",
+    request: {
+      params: z.object({ id: z.string().min(1) }),
+    },
+    responses: {
+      User: response({ code: 200, json: userResponse }),
+    },
+    handler: ({ params, respond }) => respond.User({ id: params.id }),
+  }),
+];
+
+const serviceRoutes = [
+  defineRoute({
+    method: "post",
+    path: "/jobs",
+    version: "v2",
+    request: {
+      body: z.object({ name: z.string() }),
+    },
+    responses: {
+      Created: response({ code: 201, json: z.object({ name: z.string() }) }),
+    },
+    handler: ({ body, respond }) => respond.Created(body),
+  }),
+];
+
+describe("createHttpApp", () => {
+  const publicApp = createHttpApp({
+    title: "Public",
+    versions,
+    routes: publicRoutes,
+    server: "http://127.0.0.1:3500",
+  });
+  const serviceApp = createHttpApp({
+    title: "Service",
+    versions,
+    routes: serviceRoutes,
+    server: "https://service.example",
+    postOnly: true,
+  });
+
+  it("serves health, OpenAPI, and Scalar docs on both servers", async () => {
+    for (const app of [publicApp, serviceApp]) {
+      const health = await app.request("/_health");
+      expect(health.status).toBe(200);
+      await expect(health.json()).resolves.toEqual({ status: "ok" });
+
+      const docs = await app.request("/docs");
+      expect(docs.status).toBe(200);
+      expect(docs.headers.get("content-type")).toContain("text/html");
+      const html = await docs.text();
+      expect(html).toContain('"hideClientButton": true');
+      expect(html).toContain('"showDeveloperTools": "never"');
+    }
+
+    const identified = createHttpApp({
+      title: "Public",
+      versions,
+      routes: publicRoutes,
+      identity: {
+        name: "billing",
+        public: ["http://192.168.1.10:3000"],
+        service: ["http://192.168.1.10:3001"],
+      },
+    });
+    const identity = await identified.request("/_identity");
+    expect(identity.status).toBe(200);
+    await expect(identity.json()).resolves.toEqual({
+      name: "billing",
+      public: ["http://192.168.1.10:3000"],
+      service: ["http://192.168.1.10:3001"],
+    });
+
+    const spec = await publicApp.request("/_openapi.json");
+    const document = (await spec.json()) as {
+      openapi: string;
+      paths: Record<string, unknown>;
+      servers?: { url: string }[];
+    };
+    expect(document.openapi).toMatch(/^3\./);
+    expect(document.paths["/v1/users/{id}"]).toBeDefined();
+    expect(document.servers).toEqual([{ url: "http://127.0.0.1:3500" }]);
+
+    const serviceSpec = await serviceApp.request("/_openapi.json");
+    const serviceDocument = (await serviceSpec.json()) as {
+      servers?: { url: string }[];
+    };
+    expect(serviceDocument.servers).toEqual([
+      { url: "https://service.example" },
+    ]);
+  });
+
+  it("runs the newest available handler and validates the request", async () => {
+    const found = await publicApp.request("/v2/users/ada");
+    expect(found.status).toBe(200);
+    await expect(found.json()).resolves.toEqual({ id: "ada" });
+
+    const dated = await publicApp.request("/2020-09-20/users/ada");
+    expect(dated.status).toBe(200);
+
+    const invalid = await publicApp.request("/latest/users/");
+    expect(invalid.status).toBe(404);
+    await expect(invalid.json()).resolves.toEqual(frameworkErrors.notFound);
+
+    const missing = await publicApp.request("/2019-01-01/users/ada");
+    expect(missing.status).toBe(404);
+    await expect(missing.json()).resolves.toEqual(
+      frameworkErrors.unknownVersion,
+    );
+
+    const service = await serviceApp.request("/v1/jobs", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name: "sync" }),
+    });
+    expect(service.status).toBe(404);
+    await expect(service.json()).resolves.toEqual(frameworkErrors.notFound);
+
+    const getJob = await serviceApp.request("/v2/jobs");
+    expect(getJob.status).toBe(405);
+    await expect(getJob.json()).resolves.toEqual(
+      frameworkErrors.methodNotAllowed,
+    );
+
+    const created = await serviceApp.request("/current/jobs", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name: "sync" }),
+    });
+    expect(created.status).toBe(201);
+
+    const rejected = await serviceApp.request("/v2/jobs", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(rejected.status).toBe(400);
+    await expect(rejected.json()).resolves.toMatchObject(
+      frameworkErrors.invalidRequest,
+    );
+  });
+
+  it("rejects a service route that is not POST", () => {
+    expect(() =>
+      createHttpApp({
+        title: "Service",
+        versions,
+        routes: publicRoutes,
+        postOnly: true,
+      }),
+    ).toThrow("GET /users/:id must use POST");
+  });
+
+  it("fills constant response fields that are not handler arguments", async () => {
+    const app = createHttpApp({
+      title: "Public",
+      versions,
+      routes: [
+        defineRoute({
+          method: "get",
+          path: "/missing/:id",
+          version: "v1",
+          request: { params: z.object({ id: z.string() }) },
+          responses: {
+            IdDoesNotExist: response({
+              code: 404,
+              json: z.object({
+                id: z.string(),
+                error: z.literal("ID_DOES_NOT_EXIST"),
+              }),
+              const: { error: "ID_DOES_NOT_EXIST" },
+            }),
+            Gone: response({
+              code: 410,
+              json: z.object({ error: z.literal("GONE") }),
+              const: { error: "GONE" },
+            }),
+          },
+          handler: ({ params, respond }) =>
+            params.id === "gone"
+              ? respond.Gone()
+              : respond.IdDoesNotExist(params),
+        }),
+      ],
+    });
+
+    const missing = await app.request("/v1/missing/ada");
+    expect(missing.status).toBe(404);
+    await expect(missing.json()).resolves.toEqual({
+      id: "ada",
+      error: "ID_DOES_NOT_EXIST",
+    });
+
+    const gone = await app.request("/v1/missing/gone");
+    expect(gone.status).toBe(410);
+    await expect(gone.json()).resolves.toEqual({ error: "GONE" });
+  });
+
+  it("runs code around next and passes values into the handler", async () => {
+    const events: string[] = [];
+    const server = defineMiddleware(async ({ next }) => {
+      events.push("server-before");
+      const response = await next();
+      events.push("server-after");
+      response.headers.set("x-server", "yes");
+      return response;
+    });
+    const route = defineMiddleware(async ({ version, params, next }) => {
+      events.push("route-before");
+      const response = await next({ seen: `${version}:${params.id}` });
+      events.push("route-after");
+      response.headers.set("x-route", "yes");
+      return response;
+    });
+    const app = createHttpApp({
+      title: "Public",
+      versions,
+      middleware: [server],
+      routes: [
+        defineRoute({
+          method: "get",
+          path: "/items/:id",
+          version: "v1",
+          request: { params: z.object({ id: z.string() }) },
+          middleware: [route],
+          responses: {
+            Ok: response({
+              code: 200,
+              json: z.object({ seen: z.string() }),
+            }),
+          },
+          handler: ({ seen, respond }) => {
+            events.push("handler");
+            return respond.Ok({ seen });
+          },
+        }),
+      ],
+    });
+
+    const health = await app.request("/_health");
+    expect(health.status).toBe(200);
+    expect(events).toEqual([]);
+
+    const result = await app.request("/v2/items/ada");
+    expect(result.status).toBe(200);
+    expect(result.headers.get("x-server")).toBe("yes");
+    expect(result.headers.get("x-route")).toBe("yes");
+    await expect(result.json()).resolves.toEqual({ seen: "v2:ada" });
+    expect(events).toEqual([
+      "server-before",
+      "route-before",
+      "handler",
+      "route-after",
+      "server-after",
+    ]);
+  });
+
+  it("stops the chain when middleware returns its own response", async () => {
+    let handled = false;
+    const app = createHttpApp({
+      title: "Public",
+      versions,
+      routes: [
+        defineRoute({
+          method: "get",
+          path: "/items/:id",
+          version: "v1",
+          middleware: [
+            defineMiddleware(async () =>
+              Response.json({ message: "Unauthorized" }, { status: 401 }),
+            ),
+          ],
+          responses: {
+            Ok: response({ code: 200, json: z.object({}) }),
+          },
+          handler: ({ respond }) => {
+            handled = true;
+            return respond.Ok({});
+          },
+        }),
+      ],
+    });
+
+    const result = await app.request("/v1/items/ada");
+    expect(result.status).toBe(401);
+    await expect(result.json()).resolves.toEqual({
+      message: "Unauthorized",
+    });
+    expect(handled).toBe(false);
+  });
+
+  it("returns the framework error when a response misses its schema", async () => {
+    const app = createHttpApp({
+      title: "Public",
+      versions,
+      routes: [
+        defineRoute({
+          method: "get",
+          path: "/items/:id",
+          version: "v1",
+          request: { params: z.object({ id: z.string() }) },
+          responses: {
+            Ok: response({
+              code: 200,
+              json: z.object({ id: z.string() }),
+            }),
+          },
+          handler: ({ respond }) => respond.Ok({ id: 1 } as never),
+        }),
+      ],
+    });
+
+    const result = await app.request("/v1/items/ada");
+    expect(result.status).toBe(500);
+    await expect(result.json()).resolves.toMatchObject(
+      frameworkErrors.invalidResponse,
+    );
+  });
+});

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}`);
+}