@veducio/keja 0.2.3 → 0.4.0

package/src/http/batch.ts

@@ -0,0 +1,307 @@
+import { frameworkError } from "../errors/framework-errors.ts";
+import type { RouteDefinition } from "../route/define.ts";
+import {
+  type MiddlewareDefinition,
+  runMiddleware,
+} from "../route/middleware.ts";
+import {
+  isAfterVersion,
+  type VersionDefinition,
+} from "../versioning/define.ts";
+
+const methods = ["get", "post", "put", "patch", "delete"] as const;
+const batchLimit = 25;
+
+type BatchCall = {
+  method: (typeof methods)[number];
+  path: string;
+  params?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+  body?: unknown;
+};
+
+export async function runBatch(
+  request: Request,
+  versions: readonly VersionDefinition[],
+  routes: readonly RouteDefinition[],
+  middleware: readonly MiddlewareDefinition<object>[],
+  requested: VersionDefinition,
+  token: string,
+  postOnly: boolean,
+) {
+  const calls = await readCalls(request);
+  if (!calls.ok) {
+    return Response.json(
+      frameworkError("invalidRequest", { issues: calls.issues }),
+      { status: 400 },
+    );
+  }
+  const results = [];
+  for (const call of calls.calls) {
+    results.push(
+      await runCall(
+        request,
+        versions,
+        routes,
+        middleware,
+        requested,
+        token,
+        postOnly,
+        call,
+      ),
+    );
+  }
+  return Response.json({ results }, { status: 207 });
+}
+
+async function readCalls(request: Request) {
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return {
+      ok: false as const,
+      issues: [{ message: "Request body must be JSON" }],
+    };
+  }
+  if (!isRecord(body) || !Array.isArray(body.requests)) {
+    return {
+      ok: false as const,
+      issues: [{ message: "requests must be an array" }],
+    };
+  }
+  if (body.requests.length === 0 || body.requests.length > batchLimit) {
+    return {
+      ok: false as const,
+      issues: [{ message: `requests must contain 1 to ${batchLimit} calls` }],
+    };
+  }
+  const calls: BatchCall[] = [];
+  for (const item of body.requests) {
+    const call = readCall(item);
+    if (!call.ok) {
+      return call;
+    }
+    calls.push(call.call);
+  }
+  return { ok: true as const, calls };
+}
+
+function readCall(item: unknown) {
+  if (!isRecord(item)) {
+    return {
+      ok: false as const,
+      issues: [{ message: "Each request must be an object" }],
+    };
+  }
+  const method =
+    typeof item.method === "string" ? item.method.toLowerCase() : "";
+  if (!methods.includes(method as BatchCall["method"])) {
+    return {
+      ok: false as const,
+      issues: [{ message: "method must be get, post, put, patch, or delete" }],
+    };
+  }
+  if (typeof item.path !== "string" || !item.path.startsWith("/")) {
+    return {
+      ok: false as const,
+      issues: [{ message: "path must start with /" }],
+    };
+  }
+  if (item.params !== undefined && !isRecord(item.params)) {
+    return {
+      ok: false as const,
+      issues: [{ message: "params must be an object" }],
+    };
+  }
+  if (item.query !== undefined && !isRecord(item.query)) {
+    return {
+      ok: false as const,
+      issues: [{ message: "query must be an object" }],
+    };
+  }
+  return {
+    ok: true as const,
+    call: {
+      method: method as BatchCall["method"],
+      path: item.path,
+      params: item.params as Record<string, unknown> | undefined,
+      query: item.query as Record<string, unknown> | undefined,
+      body: item.body,
+    },
+  };
+}
+
+async function runCall(
+  request: Request,
+  versions: readonly VersionDefinition[],
+  routes: readonly RouteDefinition[],
+  middleware: readonly MiddlewareDefinition<object>[],
+  requested: VersionDefinition,
+  token: string,
+  postOnly: boolean,
+  call: BatchCall,
+) {
+  if (postOnly && call.method !== "post") {
+    return {
+      status: 405,
+      body: frameworkError("methodNotAllowed"),
+    };
+  }
+  const selected = selectBatchRoute(
+    routes,
+    versions,
+    call.method,
+    call.path,
+    requested,
+  );
+  if (!selected) {
+    return { status: 404, body: frameworkError("notFound") };
+  }
+  try {
+    const response = await runMiddleware(
+      [
+        ...middleware.map((definition) => ({
+          definition,
+          allowFields: false,
+        })),
+        ...selected.route.middleware.map((definition) => ({
+          definition,
+          allowFields: true,
+        })),
+      ],
+      {
+        request: callRequest(request, call, token),
+        version: requested.id,
+        params: stringParams(call.params),
+      },
+      async (fields) => {
+        const parsed = parseCall(selected.route, call);
+        if (!parsed.ok) {
+          return Response.json(
+            frameworkError("invalidRequest", { issues: parsed.issues }),
+            { status: 400 },
+          );
+        }
+        return selected.route.handle({ ...parsed.input, fields });
+      },
+    );
+    return await callResult(response);
+  } catch {
+    return { status: 500, body: { message: "The call failed." } };
+  }
+}
+
+export function parseCall(route: RouteDefinition, call: BatchCall) {
+  const input: {
+    params?: unknown;
+    query?: unknown;
+    body?: unknown;
+  } = {};
+  if (route.request.params) {
+    const parsed = route.request.params.safeParse(call.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(call.query ?? {});
+    if (!parsed.success) {
+      return { ok: false as const, issues: parsed.error.issues };
+    }
+    input.query = parsed.data;
+  }
+  if (route.request.body) {
+    if (call.body === undefined) {
+      return {
+        ok: false as const,
+        issues: [{ message: "Request body must be JSON" }],
+      };
+    }
+    const parsed = route.request.body.safeParse(call.body);
+    if (!parsed.success) {
+      return { ok: false as const, issues: parsed.error.issues };
+    }
+    input.body = parsed.data;
+  }
+  return { ok: true as const, input };
+}
+
+function selectBatchRoute(
+  routes: readonly RouteDefinition[],
+  versions: readonly VersionDefinition[],
+  method: string,
+  path: string,
+  requested: VersionDefinition,
+) {
+  const matches = [];
+  for (const route of routes) {
+    if (route.method !== method || route.path !== path) {
+      continue;
+    }
+    const version = versions.find((item) => item.id === route.version);
+    if (!version || isAfterVersion(version, requested)) {
+      continue;
+    }
+    matches.push({ route, version });
+  }
+  matches.sort((left, right) => {
+    if (left.version.releasedAt !== right.version.releasedAt) {
+      return right.version.releasedAt - left.version.releasedAt;
+    }
+    return right.version.number - left.version.number;
+  });
+  return matches[0] ?? null;
+}
+
+function callRequest(request: Request, call: BatchCall, token: string) {
+  const url = new URL(request.url);
+  url.pathname = `/${token}${call.path}`;
+  url.search = "";
+  for (const [key, value] of Object.entries(call.query ?? {})) {
+    if (typeof value === "string") {
+      url.searchParams.set(key, value);
+    }
+  }
+  const headers = new Headers(request.headers);
+  headers.delete("content-length");
+  const sendBody = call.body !== undefined && call.method !== "get";
+  if (sendBody) {
+    headers.set("content-type", "application/json");
+  }
+  const init: RequestInit = {
+    method: call.method.toUpperCase(),
+    headers,
+  };
+  if (sendBody) {
+    init.body = JSON.stringify(call.body);
+  }
+  return new Request(url.href, init);
+}
+
+function stringParams(params: Record<string, unknown> | undefined) {
+  const values: Record<string, string> = {};
+  for (const [key, value] of Object.entries(params ?? {})) {
+    if (typeof value === "string") {
+      values[key] = value;
+    }
+  }
+  return values;
+}
+
+async function callResult(response: Response) {
+  const text = await response.text();
+  if (text.length === 0) {
+    return { status: response.status, body: null };
+  }
+  try {
+    return { status: response.status, body: JSON.parse(text) as unknown };
+  } catch {
+    return { status: response.status, body: text };
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -96,10 +96,23 @@ describe("createHttpApp", () => {
     const document = (await spec.json()) as {
       openapi: string;
       paths: Record<string, unknown>;
+      tags?: { name: string }[];
       servers?: { url: string }[];
     };
     expect(document.openapi).toMatch(/^3\./);
     expect(document.paths["/v1/users/{id}"]).toBeDefined();
+    expect(document.paths["/{version}/batch"]).toBeDefined();
+    expect(document.paths["/v1/batch"]).toBeUndefined();
+    expect(document.paths["/v2/batch"]).toBeUndefined();
+    expect(document.tags?.map((tag) => tag.name)).toEqual([
+      "Batch",
+      "v1",
+      "v2",
+    ]);
+    expect(
+      (document.paths["/v1/users/{id}"] as { get?: { tags?: string[] } }).get
+        ?.tags,
+    ).toEqual(["v1"]);
     expect(document.servers).toEqual([{ url: "http://127.0.0.1:3500" }]);
 
     const serviceSpec = await serviceApp.request("/_openapi.json");
@@ -337,4 +350,132 @@ describe("createHttpApp", () => {
       frameworkErrors.invalidResponse,
     );
   });
+
+  it("runs named routes from a versioned batch", async () => {
+    const batch = await publicApp.request("/v2/batch", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        requests: [
+          {
+            method: "get",
+            path: "/users/:id",
+            params: { id: "ada" },
+          },
+          {
+            method: "get",
+            path: "/users/:id",
+            params: { id: "" },
+          },
+          {
+            method: "get",
+            path: "/missing",
+          },
+        ],
+      }),
+    });
+    expect(batch.status).toBe(207);
+    await expect(batch.json()).resolves.toEqual({
+      results: [
+        { status: 200, body: { id: "ada" } },
+        {
+          status: 400,
+          body: expect.objectContaining(frameworkErrors.invalidRequest),
+        },
+        { status: 404, body: frameworkErrors.notFound },
+      ],
+    });
+
+    const service = await serviceApp.request("/latest/batch", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        requests: [
+          { method: "post", path: "/jobs", body: { name: "sync" } },
+          { method: "get", path: "/jobs" },
+        ],
+      }),
+    });
+    expect(service.status).toBe(207);
+    await expect(service.json()).resolves.toEqual({
+      results: [
+        { status: 201, body: { name: "sync" } },
+        { status: 405, body: frameworkErrors.methodNotAllowed },
+      ],
+    });
+
+    const empty = await publicApp.request("/v1/batch", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ requests: [] }),
+    });
+    expect(empty.status).toBe(400);
+  });
+
+  it("turns batch off when disabled", async () => {
+    const app = createHttpApp({
+      title: "Public",
+      versions,
+      routes: publicRoutes,
+      batch: false,
+    });
+    const missing = await app.request("/v1/batch", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        requests: [
+          { method: "get", path: "/users/:id", params: { id: "ada" } },
+        ],
+      }),
+    });
+    expect(missing.status).toBe(404);
+    const document = (await (await app.request("/_openapi.json")).json()) as {
+      paths: Record<string, unknown>;
+    };
+    expect(document.paths["/{version}/batch"]).toBeUndefined();
+  });
+
+  it("uses an optional route name in OpenAPI", async () => {
+    const app = createHttpApp({
+      title: "Public",
+      versions,
+      routes: [
+        defineRoute({
+          method: "get",
+          path: "/named",
+          name: "Named route",
+          version: "v1",
+          responses: {
+            Ok: response({ code: 200, json: z.object({}) }),
+          },
+          handler: ({ respond }) => respond.Ok({}),
+        }),
+      ],
+    });
+    const document = (await (await app.request("/_openapi.json")).json()) as {
+      paths: Record<string, { get?: { summary?: string; tags?: string[] } }>;
+    };
+    expect(document.paths["/v1/named"]?.get?.summary).toBe("Named route");
+    expect(document.paths["/v1/named"]?.get?.tags).toEqual(["v1"]);
+  });
+
+  it("reserves POST /batch", () => {
+    expect(() =>
+      createHttpApp({
+        title: "Public",
+        versions,
+        routes: [
+          defineRoute({
+            method: "post",
+            path: "/batch",
+            version: "v1",
+            responses: {
+              Ok: response({ code: 200, json: z.object({}) }),
+            },
+            handler: ({ respond }) => respond.Ok({}),
+          }),
+        ],
+      }),
+    ).toThrow("POST /batch is reserved");
+  });
 });

package/src/http/create-app.ts

@@ -12,6 +12,7 @@ import {
   type VersionDefinition,
 } from "../versioning/define.ts";
 import { selectRoute } from "../versioning/select.ts";
+import { runBatch } from "./batch.ts";
 import { createOpenApiDocument } from "./openapi.ts";
 
 export function createHttpApp(options: {
@@ -22,12 +23,17 @@ export function createHttpApp(options: {
   server?: string | null;
   identity?: ServiceIdentity;
   postOnly?: boolean;
+  batch?: boolean;
 }) {
+  const batch = options.batch !== false;
   validateRoutes(options.versions, options.routes, options.postOnly === true);
   const document = createOpenApiDocument(
     options.title,
     options.routes,
     options.server,
+    options.versions,
+    options.postOnly === true,
+    batch,
   );
   const app = new Hono();
   app.get("/_health", (c) => c.json({ status: "ok" }));
@@ -50,6 +56,7 @@ export function createHttpApp(options: {
       options.routes,
       options.middleware ?? [],
       options.postOnly === true,
+      batch,
     ),
   );
   return app;
@@ -61,6 +68,7 @@ async function dispatch(
   routes: readonly RouteDefinition[],
   middleware: readonly MiddlewareDefinition<object>[],
   postOnly: boolean,
+  batch: boolean,
 ) {
   if (postOnly && request.method !== "POST") {
     return Response.json(frameworkError("methodNotAllowed"), { status: 405 });
@@ -77,6 +85,20 @@ async function dispatch(
   if (!requested) {
     return Response.json(frameworkError("unknownVersion"), { status: 404 });
   }
+  if (request.method === "POST" && remainder === "/batch") {
+    if (!batch) {
+      return Response.json(frameworkError("notFound"), { status: 404 });
+    }
+    return runBatch(
+      request,
+      versions,
+      routes,
+      middleware,
+      requested,
+      token,
+      postOnly,
+    );
+  }
   const selected = selectRoute(
     routes,
     versions,
@@ -175,6 +197,9 @@ function validateRoutes(
   const known = new Set(versions.map((version) => version.id));
   const seen = new Set<string>();
   for (const route of routes) {
+    if (route.method === "post" && route.path === "/batch") {
+      throw projectError("invalidRoute", "POST /batch is reserved");
+    }
     if (postOnly && route.method !== "post") {
       throw projectError(
         "serviceMethod",

package/src/http/openapi.ts

@@ -1,34 +1,128 @@
 import { createRoute, OpenAPIHono } from "@hono/zod-openapi";
 import { type ZodType, z } from "zod";
 import type { RouteDefinition, RouteResponse } from "../route/define.ts";
+import type { VersionDefinition } from "../versioning/define.ts";
+
+const callMethods = ["get", "post", "put", "patch", "delete"] as const;
+
+const batchResponse = z.object({
+  results: z.array(
+    z.object({
+      status: z.number().int(),
+      body: z.unknown().nullable(),
+    }),
+  ),
+});
 
 export function createOpenApiDocument(
   title: string,
   routes: readonly RouteDefinition[],
   server?: string | null,
+  versions: readonly VersionDefinition[] = [],
+  postOnly = false,
+  batch = true,
 ) {
   const spec = new OpenAPIHono();
+  if (batch && versions.length > 0) {
+    const versionIds = versions.map((version) => version.id);
+    spec.openapi(
+      createRoute({
+        method: "post",
+        path: "/{version}/batch",
+        tags: ["Batch"],
+        summary: "Call several routes",
+        description:
+          "Runs each named route under this version token. Each result has the status and JSON body that call would return on its own. The version segment is a catalog id, a release date, latest, or current.",
+        request: {
+          params: z.object({
+            version: z.string().meta({
+              description:
+                "A version token such as a catalog id, a release date, latest, or current.",
+              examples: [versionIds[0]],
+            }),
+          }),
+          body: {
+            content: {
+              "application/json": {
+                schema: batchRequest(postOnly),
+              },
+            },
+            required: true,
+          },
+        },
+        responses: {
+          207: {
+            description: "Multi-Response",
+            content: {
+              "application/json": {
+                schema: batchResponse,
+              },
+            },
+          },
+          400: {
+            description: "The batch body is missing calls or names one badly",
+            content: {
+              "application/json": {
+                schema: z.object({
+                  code: z.literal(1003),
+                  name: z.literal("InvalidRequest"),
+                }),
+              },
+            },
+          },
+        },
+      }),
+      (c) => c.json({ results: [] }, 207) as never,
+    );
+  }
   for (const route of routes) {
     spec.openapi(
       createRoute({
         method: route.method,
         path: openApiPath(route.version, route.path),
+        tags: [route.version],
+        ...(route.name ? { summary: route.name } : {}),
         request: openApiRequest(route) as never,
         responses: openApiResponses(route.responses) as never,
       }),
       (c) => c.json({}, 200) as never,
     );
   }
+  const tags = [
+    ...(batch && versions.length > 0 ? [{ name: "Batch" }] : []),
+    ...versions.map((version) => ({ name: version.id })),
+  ];
   return spec.getOpenAPIDocument({
     openapi: "3.0.0",
     info: {
       title,
       version: "0.1.0",
     },
+    ...(tags.length > 0 ? { tags } : {}),
     ...(server ? { servers: [{ url: server }] } : {}),
   });
 }
 
+function batchRequest(postOnly: boolean) {
+  return z.object({
+    requests: z
+      .array(
+        z.object({
+          method: z.enum(postOnly ? ["post"] : callMethods),
+          path: z.string().meta({
+            description:
+              "The route path, including :name where the route has parameters.",
+          }),
+          params: z.record(z.string(), z.unknown()).optional(),
+          query: z.record(z.string(), z.unknown()).optional(),
+          body: z.unknown().optional(),
+        }),
+      )
+      .min(1)
+      .max(25),
+  });
+}
+
 function openApiPath(version: string, path: string) {
   const converted = path.replaceAll(/:([A-Za-z0-9_]+)/g, "{$1}");
   return `/${version}${converted.startsWith("/") ? converted : `/${converted}`}`;

package/src/project/config.test.ts

@@ -103,6 +103,43 @@ describe("defineConfig", () => {
     });
     expect(defineConfig().vault).toEqual({ enabled: false });
   });
+
+  it("reads grants and batch settings from config", () => {
+    expect(
+      defineConfig({
+        grants: {
+          enabled: true,
+          mode: "transit",
+          transit_key: "keja-grants",
+        },
+      }).grants,
+    ).toEqual({
+      enabled: true,
+      mode: "transit",
+      max_exp: 900,
+      transit_key: "keja-grants",
+      transit_mount: "transit",
+    });
+    expect(
+      defineConfig({
+        grants: {
+          enabled: true,
+          mode: "secret",
+          secret: "test-secret",
+        },
+      }).grants,
+    ).toEqual({
+      enabled: true,
+      mode: "secret",
+      max_exp: 900,
+      secret: "test-secret",
+      secret_vault: null,
+      secret_field: "secret",
+    });
+    expect(defineConfig({ batch: false }).batch).toEqual({ enabled: false });
+    expect(defineConfig().grants).toEqual({ enabled: false });
+    expect(defineConfig().batch).toEqual({ enabled: true });
+  });
 });
 
 describe("loadConfig", () => {
@@ -114,6 +151,8 @@ describe("loadConfig", () => {
       argus: { enabled: false },
       database: { enabled: false },
       vault: { enabled: false },
+      grants: { enabled: false },
+      batch: { enabled: true },
       versioning: path.resolve(root, "keja.versioning.ts"),
       public: path.resolve(root, "src/public"),
       service: path.resolve(root, "src/service"),