@veducio/keja 0.0.0-stage → 0.3.0

package/src/self-test/run.ts

@@ -0,0 +1,105 @@
+import { Chalk, type ChalkInstance } from "chalk";
+import {
+  type BunCheck,
+  type BunRuntime,
+  checkBun,
+  checkEnv,
+  checkMachine,
+  type MachineCheck,
+  type MachineInfo,
+} from "./checks.ts";
+
+export type SelfTestResult =
+  | {
+      ok: false;
+      step: "bun" | "machine" | "env";
+      error: string;
+    }
+  | {
+      ok: true;
+      bun: Extract<BunCheck, { ok: true }>;
+      machine: Extract<MachineCheck, { ok: true }>;
+    };
+
+export type SelfTestOptions = {
+  runtime?: BunRuntime | undefined;
+  machine?: MachineInfo;
+  env?: Record<string, string | undefined>;
+};
+
+export function runSelfTest(options: SelfTestOptions = {}): SelfTestResult {
+  const runtime = Object.hasOwn(options, "runtime")
+    ? options.runtime
+    : globalThis.Bun;
+  const bun = checkBun(runtime);
+  if (!bun.ok) {
+    return { ok: false, step: "bun", error: bun.error };
+  }
+
+  const machine = checkMachine(options.machine);
+  if (!machine.ok) {
+    return { ok: false, step: "machine", error: machine.error };
+  }
+
+  const env = options.env ?? runtime?.env ?? process.env;
+  const checkedEnv = checkEnv(env);
+  if (!checkedEnv.ok) {
+    return { ok: false, step: "env", error: checkedEnv.error };
+  }
+
+  return { ok: true, bun, machine };
+}
+
+export function formatSelfTest(result: SelfTestResult, color = false): string {
+  const style = ink(color);
+  const heading = `  ${style.dim("SELF TEST")}`;
+  if (!result.ok) {
+    const details = result.error
+      .split("\n")
+      .map((line) => `    ${line}`)
+      .join("\n");
+    return `\n${heading}\n\n  ${style.red(`x ${stepLabel(result.step)}`)}\n${details}\n\n  ${style.red("failed, exiting")}\n`;
+  }
+  return [
+    "",
+    heading,
+    "",
+    row("Bun", result.bun.version, style),
+    row(
+      "Machine",
+      `${result.machine.platform} ${result.machine.arch} ${result.machine.hostname}`,
+      style,
+    ),
+    row("Env", "ready", style),
+    "",
+    `  ${style.green("successful")}`,
+    "",
+  ].join("\n");
+}
+
+function stepLabel(step: "bun" | "machine" | "env") {
+  if (step === "bun") {
+    return "Bun";
+  }
+  if (step === "machine") {
+    return "Machine";
+  }
+  return "Env";
+}
+
+function row(label: string, value: string, style: ChalkInstance) {
+  return `  ${style.dim(`- ${label.padEnd(8)}`)} ${value}`;
+}
+
+function ink(color: boolean) {
+  return new Chalk({ level: color ? 1 : 0 });
+}
+
+if (import.meta.main) {
+  const result = runSelfTest();
+  if (!result.ok) {
+    console.error(formatSelfTest(result, process.stderr.isTTY === true));
+    process.exit(1);
+  }
+  console.log(formatSelfTest(result, process.stdout.isTTY === true));
+}

package/src/server/identity.test.ts

@@ -0,0 +1,57 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  accessibleHosts,
+  buildIdentity,
+  readServiceName,
+  serviceName,
+} from "./identity.ts";
+
+const lan = {
+  Ethernet: [
+    { address: "192.168.1.10", family: "IPv4", internal: false },
+    { address: "fe80::1", family: "IPv6", internal: false },
+    { address: "127.0.0.1", family: "IPv4", internal: true },
+  ],
+  Tailscale: [{ address: "100.96.0.5", family: "IPv4", internal: false }],
+};
+
+describe("service identity", () => {
+  it("uses the package name without a scope", () => {
+    expect(serviceName("@veducio/billing", "app")).toBe("billing");
+    expect(serviceName(undefined, "notes")).toBe("notes");
+  });
+
+  it("prefers the configured name over package.json", () => {
+    const root = mkdtempSync(path.join(tmpdir(), "keja-identity-"));
+    writeFileSync(
+      path.join(root, "package.json"),
+      JSON.stringify({ name: "@veducio/billing" }),
+    );
+    expect(readServiceName(root, null)).toBe("billing");
+    expect(readServiceName(root, "payments")).toBe("payments");
+  });
+
+  it("lists reachable addresses for both API surfaces", () => {
+    expect(accessibleHosts("127.0.0.1", lan)).toEqual(["127.0.0.1"]);
+    expect(accessibleHosts("0.0.0.0", lan)).toEqual([
+      "192.168.1.10",
+      "100.96.0.5",
+    ]);
+    expect(
+      buildIdentity({
+        name: "billing",
+        bindHost: "0.0.0.0",
+        publicPort: 3000,
+        servicePort: 3001,
+        interfaces: lan,
+      }),
+    ).toEqual({
+      name: "billing",
+      public: ["http://192.168.1.10:3000", "http://100.96.0.5:3000"],
+      service: ["http://192.168.1.10:3001", "http://100.96.0.5:3001"],
+    });
+  });
+});

package/src/server/identity.ts

@@ -0,0 +1,116 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+export type NetworkAddress = {
+  address: string;
+  family: string | number;
+  internal: boolean;
+};
+
+export type ServiceIdentity = {
+  name: string;
+  public: string[];
+  service: string[];
+};
+
+export function serviceName(
+  packageName: string | undefined,
+  directoryName: string,
+) {
+  const trimmed = packageName?.trim() ?? "";
+  if (!trimmed) {
+    return directoryName;
+  }
+  const slash = trimmed.lastIndexOf("/");
+  return slash === -1 ? trimmed : trimmed.slice(slash + 1);
+}
+
+export function readServiceName(root: string, configured: string | null) {
+  if (configured) {
+    return configured;
+  }
+  return serviceName(readPackage(root).name, path.basename(root));
+}
+
+export function readPackageVersion(root: string) {
+  const version = readPackage(root).version?.trim();
+  return version ? version : undefined;
+}
+
+export function accessibleHosts(
+  bindHost: string,
+  interfaces: Record<string, readonly NetworkAddress[] | undefined>,
+) {
+  const bind = bindHost.trim();
+  if (bind !== "0.0.0.0" && bind !== "::" && bind !== "[::]") {
+    return [bind];
+  }
+  const found: string[] = [];
+  for (const entries of Object.values(interfaces)) {
+    for (const entry of entries ?? []) {
+      if (!usableAddress(entry) || found.includes(entry.address)) {
+        continue;
+      }
+      found.push(entry.address);
+    }
+  }
+  const ipv4 = found.filter((address) => !address.includes(":"));
+  const chosen = ipv4.length > 0 ? ipv4 : found;
+  return chosen.length > 0 ? chosen : ["127.0.0.1"];
+}
+
+export function buildIdentity(input: {
+  name: string;
+  bindHost: string;
+  publicPort: number;
+  servicePort: number;
+  interfaces: Record<string, readonly NetworkAddress[] | undefined>;
+}): ServiceIdentity {
+  const hosts = accessibleHosts(input.bindHost, input.interfaces);
+  return {
+    name: input.name,
+    public: hosts.map((host) => endpoint(host, input.publicPort)),
+    service: hosts.map((host) => endpoint(host, input.servicePort)),
+  };
+}
+
+function usableAddress(entry: NetworkAddress) {
+  if (entry.internal || entry.address.includes("%")) {
+    return false;
+  }
+  if (
+    entry.address.startsWith("169.254.") ||
+    entry.address.startsWith("fe80:")
+  ) {
+    return false;
+  }
+  return (
+    entry.family === 4 ||
+    entry.family === "IPv4" ||
+    entry.family === 6 ||
+    entry.family === "IPv6"
+  );
+}
+
+function endpoint(host: string, port: number) {
+  const formatted =
+    host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+  return `http://${formatted}:${port}`;
+}
+
+function readPackage(root: string) {
+  try {
+    const parsed = JSON.parse(
+      readFileSync(path.join(root, "package.json"), "utf8"),
+    ) as {
+      name?: unknown;
+      version?: unknown;
+    };
+    return {
+      name: typeof parsed.name === "string" ? parsed.name : undefined,
+      version: typeof parsed.version === "string" ? parsed.version : undefined,
+    };
+  } catch {
+    return { name: undefined, version: undefined };
+  }
+}

package/src/server/index.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+import { createHttpApp } from "../http/create-app.ts";
+import { defineVersions } from "../versioning/define.ts";
+
+describe("createServer import", () => {
+  it("does not listen when the http app is created", async () => {
+    const app = createHttpApp({
+      title: "Public",
+      versions: defineVersions({ v1: { releasedAt: "2020-01-15" } }).versions,
+      routes: [],
+    });
+    const response = await app.request("/_health");
+    expect(response.status).toBe(200);
+  });
+});

package/src/server/index.ts

@@ -0,0 +1,171 @@
+import { networkInterfaces } from "node:os";
+import { setArgus } from "../argus/call.ts";
+import { startArgusHeartbeat } from "../argus/heartbeat.ts";
+import { argusRegistrations, publishArgus } from "../argus/register.ts";
+import { connectDatabase } from "../db/postgres.ts";
+import { readOpenApiServers, readRequiredEnv } from "../env/required-env.ts";
+import { projectError } from "../errors/framework-errors.ts";
+import { createHttpApp } from "../http/create-app.ts";
+import { type LoadedProject, loadProject } from "../project/load.ts";
+import { formatSelfTest, runSelfTest } from "../self-test/run.ts";
+import { connectVault, setVault } from "../vault/client.ts";
+import {
+  buildIdentity,
+  readPackageVersion,
+  readServiceName,
+} from "./identity.ts";
+import { swapProjectHandlers } from "./swap.ts";
+
+export type { AccessIdentity } from "../access/cloudflare.ts";
+export { cloudflareAccess, verifyAccessJwt } from "../access/cloudflare.ts";
+export { callService, ServiceCallError } from "../argus/call.ts";
+export { DBCall } from "../db/client.ts";
+export {
+  DependencyNotMet,
+  frameworkErrors,
+} from "../errors/framework-errors.ts";
+export type { Grant } from "../grant/grant.ts";
+export { grant, verifyGrant } from "../grant/grant.ts";
+export { defineConfig } from "../project/config.ts";
+export { defineRepositories } from "../repository/define.ts";
+export { repository } from "../repository/runtime.ts";
+export { defineRoute, response } from "../route/define.ts";
+export { defineMiddleware } from "../route/middleware.ts";
+export { defineSeeder } from "../seed/define.ts";
+export type {
+  CreateObjectRowOptions,
+  ObjectRowMeta,
+  ParsedTypeId,
+} from "../typeid/id.ts";
+export {
+  assertObjectType,
+  createObjectRow,
+  createTypeId,
+  idPrefixFromObjectType,
+  isObjectType,
+  isTypeId,
+  objectTypeFromRoute,
+  parseTypeId,
+  TypeIdError,
+} from "../typeid/id.ts";
+export type { OwnedObject } from "../typeid/owned.ts";
+export { assertOwnedObject } from "../typeid/owned.ts";
+export { createVault, VaultError, vaultSecret } from "../vault/client.ts";
+export { defineVersions } from "../versioning/define.ts";
+
+export async function listen(
+  root = process.cwd(),
+  options?: { generation?: string },
+) {
+  const project = await loadProject(root, options);
+  const result = runSelfTest();
+  if (!result.ok) {
+    console.error(formatSelfTest(result, process.stderr.isTTY === true));
+    process.exit(1);
+  }
+  console.log(formatSelfTest(result, process.stdout.isTTY === true));
+
+  const env = readRequiredEnv(Bun.env);
+  const openApiServers = readOpenApiServers(Bun.env);
+  if (project.database.enabled) {
+    await connectDatabase(Bun.env.DATABASE_URL ?? "");
+  }
+  if (project.vault.enabled) {
+    await connectVault(project.vault);
+  } else {
+    setVault(null);
+  }
+  const mounted = mountProject(root, project, env, openApiServers);
+  const identity = mounted.identity;
+  if (project.argus.enabled) {
+    const errors = await publishArgus({
+      url: project.argus.url,
+      username: project.argus.username,
+      password: project.argus.password,
+      registrations: argusRegistrations({
+        identity,
+        argus: project.argus,
+        version: readPackageVersion(root),
+      }),
+    });
+    if (errors.length > 0) {
+      throw projectError("argusInit", errors.join("; "));
+    }
+  }
+  const publicServer = Bun.serve({
+    hostname: env.host,
+    port: env.httpPort,
+    fetch(request) {
+      return mounted.publicApp.fetch(request);
+    },
+  });
+  const serviceServer = Bun.serve({
+    hostname: env.host,
+    port: env.httpServicePort,
+    fetch(request) {
+      return mounted.serviceApp.fetch(request);
+    },
+  });
+  setArgus(project.argus.enabled ? project.argus : null);
+  if (project.argus.enabled) {
+    startArgusHeartbeat({
+      argus: project.argus,
+      identity,
+      version: readPackageVersion(root),
+      lead: false,
+    });
+  }
+  return {
+    publicServer,
+    serviceServer,
+    paths: project.paths,
+    identity,
+    argus: project.argus,
+    vault: project.vault,
+    database: project.database.enabled ? { connected: true as const } : null,
+    reload(next: LoadedProject) {
+      swapProjectHandlers(
+        { publicServer, serviceServer },
+        mountProject(root, next, env, openApiServers),
+      );
+    },
+  };
+}
+
+function mountProject(
+  root: string,
+  project: LoadedProject,
+  env: { host: string; httpPort: number; httpServicePort: number },
+  openApiServers: {
+    openapiServer: string | null;
+    openapiServiceServer: string | null;
+  },
+) {
+  const identity = buildIdentity({
+    name: readServiceName(root, project.name),
+    bindHost: env.host,
+    publicPort: env.httpPort,
+    servicePort: env.httpServicePort,
+    interfaces: networkInterfaces(),
+  });
+  return {
+    identity,
+    publicApp: createHttpApp({
+      title: "Public",
+      versions: project.versions,
+      routes: project.publicRoutes,
+      middleware: project.publicMiddleware,
+      server: openApiServers.openapiServer,
+      identity,
+    }),
+    serviceApp: createHttpApp({
+      title: "Service",
+      versions: project.versions,
+      routes: project.serviceRoutes,
+      middleware: project.serviceMiddleware,
+      server: openApiServers.openapiServiceServer,
+      identity,
+      postOnly: true,
+    }),
+  };
+}

package/src/server/swap.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { createHttpApp } from "../http/create-app.ts";
+import { defineRoute, response } from "../route/define.ts";
+import { defineVersions } from "../versioning/define.ts";
+import { swapProjectHandlers } from "./swap.ts";
+
+const versions = defineVersions({
+  v1: { releasedAt: "2026-01-01" },
+  v2: { releasedAt: "2026-06-01" },
+}).versions;
+
+describe("project handler swap", () => {
+  it("reloads openapi and docs on both servers", async () => {
+    const first = apps("/notes", "v1");
+    const second = apps("/posts", "v2");
+    const fetches: Array<(request: Request) => Response | Promise<Response>> =
+      [];
+    const server = () => ({
+      reload(options: {
+        fetch: (request: Request) => Response | Promise<Response>;
+      }) {
+        fetches.push(options.fetch);
+      },
+    });
+    swapProjectHandlers(
+      { publicServer: server(), serviceServer: server() },
+      second,
+    );
+    expect(
+      await (await first.publicApp.request("/_openapi.json")).json(),
+    ).toMatchObject({
+      paths: { "/v1/notes": { get: expect.any(Object) } },
+    });
+    const publicSpec = await fetches[0]?.(
+      new Request("http://localhost/_openapi.json"),
+    );
+    const serviceSpec = await fetches[1]?.(
+      new Request("http://localhost/_openapi.json"),
+    );
+    const publicDocs = await fetches[0]?.(new Request("http://localhost/docs"));
+    expect(publicSpec?.status).toBe(200);
+    expect(await publicSpec?.json()).toMatchObject({
+      paths: { "/v2/posts": { get: expect.any(Object) } },
+    });
+    expect(serviceSpec?.status).toBe(200);
+    expect(await serviceSpec?.json()).toMatchObject({
+      paths: { "/v2/posts": { post: expect.any(Object) } },
+    });
+    expect(publicDocs?.status).toBe(200);
+    expect(await publicDocs?.text()).toContain("/_openapi.json");
+  });
+});
+
+function apps(routePath: string, version: "v1" | "v2") {
+  const routes = [
+    defineRoute({
+      method: "get",
+      path: routePath,
+      version,
+      responses: {
+        Ok: response({ code: 200, json: z.object({ ok: z.literal(true) }) }),
+      },
+      handler: ({ respond }) => respond.Ok({ ok: true }),
+    }),
+    defineRoute({
+      method: "post",
+      path: routePath,
+      version,
+      responses: {
+        Ok: response({ code: 200, json: z.object({ ok: z.literal(true) }) }),
+      },
+      handler: ({ respond }) => respond.Ok({ ok: true }),
+    }),
+  ];
+  return {
+    publicApp: createHttpApp({
+      title: "Public",
+      versions,
+      routes: routes.filter((route) => route.method === "get"),
+    }),
+    serviceApp: createHttpApp({
+      title: "Service",
+      versions,
+      routes: routes.filter((route) => route.method === "post"),
+      postOnly: true,
+    }),
+  };
+}

package/src/server/swap.ts

@@ -0,0 +1,29 @@
+export function swapProjectHandlers(
+  servers: {
+    publicServer: {
+      reload: (options: {
+        fetch: (request: Request) => Response | Promise<Response>;
+      }) => void;
+    };
+    serviceServer: {
+      reload: (options: {
+        fetch: (request: Request) => Response | Promise<Response>;
+      }) => void;
+    };
+  },
+  apps: {
+    publicApp: {
+      fetch: (request: Request) => Response | Promise<Response>;
+    };
+    serviceApp: {
+      fetch: (request: Request) => Response | Promise<Response>;
+    };
+  },
+) {
+  servers.publicServer.reload({
+    fetch: (request) => apps.publicApp.fetch(request),
+  });
+  servers.serviceServer.reload({
+    fetch: (request) => apps.serviceApp.fetch(request),
+  });
+}

package/src/typeid/id.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import {
+  createObjectRow,
+  createTypeId,
+  idPrefixFromObjectType,
+  isObjectType,
+  isTypeId,
+  objectTypeFromRoute,
+  parseTypeId,
+} from "./id.ts";
+
+describe("typeids", () => {
+  it("creates a prefixed typeid and reads it back", () => {
+    const id = createTypeId("user");
+    expect(isTypeId(id, "user")).toBe(true);
+    expect(parseTypeId(id)).toEqual({
+      prefix: "user",
+      suffix: id.slice("user_".length),
+    });
+    expect(id.slice("user_".length)).toHaveLength(26);
+    expect(parseTypeId("User_abc")).toBeNull();
+    expect(() => createTypeId("User")).toThrow("invalid type prefix: User");
+  });
+
+  it("derives an object type from a route and builds an OwnedObjects row", () => {
+    expect(objectTypeFromRoute(2, "/core/users")).toBe("v2.core.users");
+    expect(idPrefixFromObjectType("v2.core.users")).toBe("users");
+    expect(isObjectType("v2.core.users")).toBe(true);
+    expect(isObjectType("users")).toBe(false);
+    const row = createObjectRow("v2.core.users", { tenant: "acme" });
+    expect(row._object).toBe("v2.core.users");
+    expect(row._tenant).toBe("acme");
+    expect(row._archived).toBe(false);
+    expect(row._createdAt).toEqual(row._updatedAt);
+    expect(isTypeId(row._id, "users")).toBe(true);
+  });
+
+  it("rejects a route that cannot become an object type", () => {
+    expect(() => objectTypeFromRoute(0, "/users")).toThrow(
+      "invalid API version: 0",
+    );
+    expect(() => objectTypeFromRoute(1, "/users/:id")).toThrow(
+      'invalid route segment ":id" in /users/:id',
+    );
+  });
+});