@veducio/keja 0.0.0-stage → 0.2.3

package/src/argus/call.ts

@@ -0,0 +1,153 @@
+import { DependencyNotMet } from "../errors/framework-errors.ts";
+import { processValue } from "../process/slot.ts";
+import type { ArgusSettings } from "../project/config.ts";
+import { type ArgusFetch, argusHeaders, joinUrl } from "./register.ts";
+
+const state = processValue("argus", () => ({
+  active: null as ArgusSettings | null,
+}));
+
+export class ServiceCallError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ServiceCallError";
+  }
+}
+
+export function setArgus(config: ArgusSettings | null) {
+  state.active = config;
+}
+
+export async function callService<Data = unknown>(
+  service: string,
+  path: string,
+  body?: unknown,
+  options: {
+    fetchImpl?: ArgusFetch;
+    random?: () => number;
+  } = {},
+): Promise<Data> {
+  if (!state.active) {
+    throw new DependencyNotMet("service call", "argus");
+  }
+  const serviceName = serviceNameOf(service);
+  const requestPath = servicePath(path);
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const discovery = await fetchImpl(
+    `${joinUrl(state.active.url, `/v1/services/${encodeURIComponent(serviceName)}`)}?env=${encodeURIComponent(state.active.env)}`,
+    { headers: argusHeaders(state.active.username, state.active.password) },
+  );
+  if (!discovery.ok) {
+    throw await discoveryFailure(discovery, serviceName);
+  }
+  const listed = (await discovery.json()) as { instances?: unknown };
+  const baseUrl = pickInstance(listed.instances, options.random ?? Math.random);
+  if (!baseUrl) {
+    throw new ServiceCallError(
+      `Argus has no healthy instance for ${serviceName}`,
+    );
+  }
+  const response = await fetchImpl(joinUrl(baseUrl, requestPath), {
+    method: "POST",
+    headers: new Headers({ "content-type": "application/json" }),
+    body: JSON.stringify(body ?? {}),
+  });
+  const payload = await readPayload(response);
+  if (!response.ok) {
+    const detail = payload === undefined ? "" : `: ${payloadText(payload)}`;
+    throw new ServiceCallError(
+      `${serviceName} returned ${response.status}${detail}`,
+    );
+  }
+  return payload as Data;
+}
+
+function serviceNameOf(service: string) {
+  const name = service.trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
+    throw new ServiceCallError(`invalid service name: ${service}`);
+  }
+  return name;
+}
+
+function servicePath(path: string) {
+  const trimmed = path.trim();
+  if (trimmed === "" || trimmed.includes("://") || trimmed.startsWith("//")) {
+    throw new ServiceCallError(`invalid service path: ${path}`);
+  }
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+function pickInstance(value: unknown, random: () => number) {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  const healthy = value.flatMap((item) => {
+    if (!item || typeof item !== "object") {
+      return [];
+    }
+    const instance = item as {
+      base_url?: unknown;
+      weight?: unknown;
+      status?: unknown;
+    };
+    if (
+      instance.status !== "healthy" ||
+      typeof instance.base_url !== "string"
+    ) {
+      return [];
+    }
+    const weight =
+      typeof instance.weight === "number" && instance.weight > 0
+        ? instance.weight
+        : 0;
+    return [{ baseUrl: instance.base_url, weight }];
+  });
+  if (healthy.length === 0) {
+    return null;
+  }
+  const total = healthy.reduce((sum, instance) => sum + instance.weight, 0);
+  if (total === 0) {
+    const index = Math.min(
+      healthy.length - 1,
+      Math.floor(random() * healthy.length),
+    );
+    return healthy[index]?.baseUrl ?? null;
+  }
+  let cursor = random() * total;
+  for (const instance of healthy) {
+    cursor -= instance.weight;
+    if (cursor < 0) {
+      return instance.baseUrl;
+    }
+  }
+  return healthy[healthy.length - 1]?.baseUrl ?? null;
+}
+
+async function discoveryFailure(response: Response, service: string) {
+  const payload = await readPayload(response);
+  if (response.status === 404) {
+    return new ServiceCallError(`Argus has no service ${service}`);
+  }
+  const detail = payload === undefined ? "" : `: ${payloadText(payload)}`;
+  return new ServiceCallError(
+    `Argus rejected ${service} with status ${response.status}${detail}`,
+  );
+}
+
+async function readPayload(response: Response) {
+  const text = await response.text();
+  if (text.trim() === "") {
+    return undefined;
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+function payloadText(payload: unknown) {
+  const text = typeof payload === "string" ? payload : JSON.stringify(payload);
+  return text.length > 200 ? `${text.slice(0, 200)}...` : text;
+}

package/src/argus/heartbeat.ts

@@ -0,0 +1,65 @@
+import type { ArgusSettings } from "../project/config.ts";
+import type { ServiceIdentity } from "../server/identity.ts";
+import {
+  type ArgusFetch,
+  argusRegistrations,
+  publishArgus,
+  withdrawArgus,
+} from "./register.ts";
+
+export const argusHeartbeatMs = 10_000;
+
+export function startArgusHeartbeat(options: {
+  argus: ArgusSettings;
+  lead?: boolean;
+  identity: ServiceIdentity;
+  version?: string;
+  fetchImpl?: ArgusFetch;
+  intervalMs?: number;
+  log?: (message: string) => void;
+}) {
+  const log = options.log ?? ((message: string) => console.error(message));
+  const registrations = () =>
+    argusRegistrations({
+      identity: options.identity,
+      argus: options.argus,
+      version: options.version,
+    });
+  const beat = async () => {
+    const errors = await publishArgus({
+      url: options.argus.url,
+      username: options.argus.username,
+      password: options.argus.password,
+      registrations: registrations(),
+      fetchImpl: options.fetchImpl,
+    });
+    for (const error of errors) {
+      log(`Argus register failed: ${error}`);
+    }
+  };
+  if (options.lead !== false) {
+    void beat();
+  }
+  const timer = setInterval(() => {
+    void beat();
+  }, options.intervalMs ?? argusHeartbeatMs);
+  timer.unref?.();
+  let stopped = false;
+  return async () => {
+    if (stopped) {
+      return;
+    }
+    stopped = true;
+    clearInterval(timer);
+    const errors = await withdrawArgus({
+      url: options.argus.url,
+      username: options.argus.username,
+      password: options.argus.password,
+      registrations: registrations(),
+      fetchImpl: options.fetchImpl,
+    });
+    for (const error of errors) {
+      log(`Argus deregister failed: ${error}`);
+    }
+  };
+}

package/src/argus/register.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import { defineConfig } from "../project/config.ts";
+import { argusRegistrations, publishArgus } from "./register.ts";
+
+const identity = {
+  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"],
+};
+
+describe("argusRegistrations", () => {
+  it("registers every reachable address for both surfaces", () => {
+    const argus = defineConfig({
+      argus: {
+        enabled: true,
+        url: "https://argus.veducio.com",
+        env: "staging",
+        username: "argus",
+        password: "secret",
+      },
+    }).argus;
+    if (!argus.enabled) {
+      throw new Error("missing argus config");
+    }
+    const registrations = argusRegistrations({
+      identity,
+      argus,
+      version: "0.1.0",
+    });
+    expect(
+      registrations.map((item) => [
+        item.service,
+        item.base_url,
+        item.instance_id,
+      ]),
+    ).toEqual([
+      ["billing", "http://192.168.1.10:3000", "billing-192-168-1-10-3000"],
+      ["billing", "http://100.96.0.5:3000", "billing-100-96-0-5-3000"],
+      [
+        "billing-service",
+        "http://192.168.1.10:3001",
+        "billing-service-192-168-1-10-3001",
+      ],
+      [
+        "billing-service",
+        "http://100.96.0.5:3001",
+        "billing-service-100-96-0-5-3001",
+      ],
+    ]);
+    expect(registrations[0]).toMatchObject({
+      env: "staging",
+      version: "0.1.0",
+      ttl_seconds: 30,
+      metadata: {
+        surface: "public",
+        public: identity.public,
+        service: identity.service,
+      },
+    });
+  });
+
+  it("sends a basic-auth heartbeat to the registry", async () => {
+    const calls: {
+      url: string;
+      authorization: string | null;
+      body: unknown;
+    }[] = [];
+    const errors = await publishArgus({
+      url: "https://argus.veducio.com/",
+      username: "argus",
+      password: "secret",
+      registrations: [
+        {
+          instance_id: "billing-192-168-1-10-3000",
+          service: "billing",
+          env: "staging",
+          base_url: "http://192.168.1.10:3000",
+          weight: 100,
+          status: "healthy",
+          ttl_seconds: 30,
+          metadata: {
+            surface: "public",
+            public: identity.public,
+            service: identity.service,
+          },
+        },
+      ],
+      fetchImpl: async (url, init) => {
+        const headers = new Headers(init?.headers);
+        calls.push({
+          url: String(url),
+          authorization: headers.get("authorization"),
+          body: JSON.parse(String(init?.body)),
+        });
+        return new Response(JSON.stringify({ ok: true }), { status: 200 });
+      },
+    });
+    expect(errors).toEqual([]);
+    expect(calls).toEqual([
+      {
+        url: "https://argus.veducio.com/v1/register",
+        authorization: `Basic ${Buffer.from("argus:secret").toString("base64")}`,
+        body: {
+          instance_id: "billing-192-168-1-10-3000",
+          service: "billing",
+          env: "staging",
+          base_url: "http://192.168.1.10:3000",
+          weight: 100,
+          status: "healthy",
+          ttl_seconds: 30,
+          metadata: {
+            surface: "public",
+            public: identity.public,
+            service: identity.service,
+          },
+        },
+      },
+    ]);
+  });
+});

package/src/argus/register.ts

@@ -0,0 +1,145 @@
+import type { ArgusSettings } from "../project/config.ts";
+import type { ServiceIdentity } from "../server/identity.ts";
+
+export const argusTtlSeconds = 30;
+
+export type ArgusRegistration = {
+  instance_id: string;
+  service: string;
+  env: string;
+  base_url: string;
+  weight: number;
+  status: "healthy";
+  version?: string;
+  ttl_seconds: number;
+  metadata: {
+    surface: "public" | "service";
+    public: string[];
+    service: string[];
+  };
+};
+
+export function argusRegistrations(input: {
+  identity: ServiceIdentity;
+  argus: ArgusSettings;
+  version?: string;
+}) {
+  const publicService = input.argus.public ?? input.identity.name;
+  const serviceService =
+    input.argus.service ?? `${input.identity.name}-service`;
+  return [
+    ...registrations(publicService, "public", input.identity.public, input),
+    ...registrations(serviceService, "service", input.identity.service, input),
+  ];
+}
+
+export type ArgusFetch = (
+  url: string,
+  init?: { method?: string; headers?: Headers; body?: string },
+) => Promise<Response>;
+
+export async function publishArgus(options: {
+  url: string;
+  username: string | null;
+  password: string | null;
+  registrations: readonly ArgusRegistration[];
+  fetchImpl?: ArgusFetch;
+}) {
+  return sendArgus(options, "/v1/register", (registration) => registration);
+}
+
+export async function withdrawArgus(options: {
+  url: string;
+  username: string | null;
+  password: string | null;
+  registrations: readonly ArgusRegistration[];
+  fetchImpl?: ArgusFetch;
+}) {
+  return sendArgus(options, "/v1/deregister", (registration) => ({
+    instance_id: registration.instance_id,
+    service: registration.service,
+    env: registration.env,
+  }));
+}
+
+function registrations(
+  service: string,
+  surface: "public" | "service",
+  urls: readonly string[],
+  input: {
+    identity: ServiceIdentity;
+    argus: ArgusSettings;
+    version?: string;
+  },
+): ArgusRegistration[] {
+  return urls.map((baseUrl) => ({
+    instance_id: instanceId(service, baseUrl),
+    service,
+    env: input.argus.env,
+    base_url: baseUrl,
+    weight: 100,
+    status: "healthy",
+    ...(input.version ? { version: input.version } : {}),
+    ttl_seconds: argusTtlSeconds,
+    metadata: {
+      surface,
+      public: input.identity.public,
+      service: input.identity.service,
+    },
+  }));
+}
+
+function instanceId(service: string, baseUrl: string) {
+  const host = new URL(baseUrl).host
+    .replaceAll(/[^A-Za-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+  return `${service}-${host}`;
+}
+
+async function sendArgus(
+  options: {
+    url: string;
+    username: string | null;
+    password: string | null;
+    registrations: readonly ArgusRegistration[];
+    fetchImpl?: ArgusFetch;
+  },
+  pathname: string,
+  body: (registration: ArgusRegistration) => unknown,
+) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const errors: string[] = [];
+  for (const registration of options.registrations) {
+    try {
+      const response = await fetchImpl(joinUrl(options.url, pathname), {
+        method: "POST",
+        headers: argusHeaders(options.username, options.password),
+        body: JSON.stringify(body(registration)),
+      });
+      if (!response.ok) {
+        errors.push(
+          `${registration.service} ${registration.base_url} ${response.status}`,
+        );
+      }
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : "request failed";
+      errors.push(`${registration.service} ${registration.base_url} ${detail}`);
+    }
+  }
+  return errors;
+}
+
+export function argusHeaders(username: string | null, password: string | null) {
+  const headers = new Headers({ "content-type": "application/json" });
+  if (username !== null && password !== null) {
+    headers.set(
+      "authorization",
+      `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`,
+    );
+  }
+  return headers;
+}
+
+export function joinUrl(url: string, pathname: string) {
+  return `${url.replace(/\/+$/, "")}${pathname}`;
+}

package/src/cli/banner.test.ts

@@ -0,0 +1,98 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { Chalk } from "chalk";
+import { describe, expect, it } from "vitest";
+import {
+  formatAddresses,
+  formatBanner,
+  formatDatabase,
+  formatIdentity,
+  formatProjectPaths,
+  formatProjectReady,
+  formatReloading,
+  projectLabel,
+  readProjectLabel,
+  veducioAnnotation,
+} from "./banner.ts";
+
+describe("projectLabel", () => {
+  it("prints the package name and version", () => {
+    expect(projectLabel({ name: "example-app", version: "0.1.0" }, "app")).toBe(
+      "example-app 0.1.0",
+    );
+    expect(projectLabel({}, "app")).toBe("app");
+  });
+
+  it("reads the project package and keeps the Veducio annotation", () => {
+    const root = mkdtempSync(path.join(tmpdir(), "keja-"));
+    writeFileSync(
+      path.join(root, "package.json"),
+      JSON.stringify({ name: "@veducio/keja", version: "0.1.0" }),
+    );
+    expect(readProjectLabel(root)).toBe("@veducio/keja 0.1.0");
+    expect(veducioAnnotation).toBe(
+      "Veducio Keja is part of Veducio and its Labs program, with a mission to contribute quality software to open source.",
+    );
+  });
+
+  it("lays the banner and addresses out like a dev server", () => {
+    expect(formatBanner({ name: "example-app", version: "0.1.0" })).toBe(
+      `\n  example-app 0.1.0\n\n  Veducio Keja is part of Veducio and its Labs program, with a mission to\n  contribute quality software to open source.\n`,
+    );
+    expect(
+      formatAddresses("http://127.0.0.1:3500", "http://127.0.0.1:3501"),
+    ).toBe(
+      "\n  - Public   http://127.0.0.1:3500\n  - Service  http://127.0.0.1:3501\n",
+    );
+    expect(
+      formatIdentity(
+        {
+          name: "billing",
+          public: ["http://192.168.1.10:3000"],
+          service: ["http://192.168.1.10:3001"],
+        },
+        { url: "https://argus.veducio.com", env: "staging" },
+      ),
+    ).toBe(
+      "\n  - Name       billing\n  - Public     http://192.168.1.10:3000\n  - Service    http://192.168.1.10:3001\n  - Argus      https://argus.veducio.com (staging)\n",
+    );
+    expect(formatDatabase(null)).toBe("\n  - Database   disabled\n");
+    expect(
+      formatDatabase({
+        migrations: "C:/app/migrations",
+        applied: ["0001_init.sql"],
+      }),
+    ).toBe(
+      "\n  - Database   postgres\n  - Migrations C:/app/migrations\n  - Applied    0001_init.sql\n",
+    );
+    expect(
+      formatProjectPaths({
+        config: "C:/app/keja.config.ts",
+        versioning: "C:/app/keja.versioning.ts",
+        public: "C:/app/src/public",
+        service: "C:/app/src/service",
+      }),
+    ).toBe(
+      "\n  - Config     C:/app/keja.config.ts\n  - Versioning C:/app/keja.versioning.ts\n  - Public     C:/app/src/public\n  - Service    C:/app/src/service\n",
+    );
+    expect(
+      formatProjectPaths({
+        config: null,
+        versioning: "C:/app/keja.versioning.ts",
+        public: "C:/app/src/public",
+        service: "C:/app/src/service",
+      }),
+    ).toContain("- Config     defaults");
+  });
+
+  it("prints reloading and a clean project", () => {
+    const style = new Chalk({ level: 1 });
+    expect(formatReloading()).toBe("\n  reloading...\n");
+    expect(formatProjectReady()).toBe("\n  no issues found\n");
+    expect(formatReloading(true)).toBe(`\n  ${style.dim("reloading...")}\n`);
+    expect(formatProjectReady(true)).toBe(
+      `\n  ${style.green("no issues found")}\n`,
+    );
+  });
+});