Skip to content

Linger is An Open-Source Personal Agent That Runs Fully on Your PC. We aim to break Big Tech’s grip on AI by bringing powerful local AI to everyday computers through efficient model–harness co-design, so everyone can run their own.

6.3 KB
Raw Blame
import type { Server } from "node:http";

import { createAdaptorServer } from "@hono/node-server";

export type RoleReadiness =
  | { readonly ready: true }
  | { readonly ready: false; readonly reason: string };

/** One role's share of the process HTTP listener. */
export interface HttpRoute {
  /** Path prefixes this role answers; the longest matching prefix wins. */
  readonly prefixes: readonly string[];
  fetch(request: Request): Response | Promise<Response>;
  /** Contributes to the aggregate /readyz; omitted means always ready. */
  readiness?(): RoleReadiness | Promise<RoleReadiness>;
}

/**
 * The single HTTP listener that the Agent, Memory, and LLM Wiki roles share. It
 * owns the aggregate probes /healthz, /startupz, and /readyz
 * and routes every other request to the role that mounted its path prefix.
 */
export interface HttpHost {
  /** The Node server, for roles that also accept WebSocket upgrades. */
  readonly server: Server;
  /** The configured bind address. */
  readonly host: string;
  readonly port: number;
  /** This listener's own URL; a wildcard bind address becomes loopback. */
  readonly url: string;
  /** Routes the given prefixes to a role; the returned function unmounts it. */
  mount(route: HttpRoute): () => void;
  /**
   * Ends startup: /startupz and /readyz stop answering "starting", and paths
   * that no role mounted answer 404 instead of 503.
   */
  finishStartup(): void;
  close(): Promise<void>;
}

const PROBES = new Set(["/healthz", "/startupz", "/readyz"]);

/** Listens on host:port and resolves once the TCP address is bound. */
export async function startHttpHost(options: {
  host: string;
  port: number;
}): Promise<HttpHost> {
  const routes: { prefix: string; route: HttpRoute }[] = [];
  let starting = true;
  const routeFor = (path: string): HttpRoute | undefined => {
    let match: { prefix: string; route: HttpRoute } | undefined;
    for (const candidate of routes) {
      if (
        path.startsWith(candidate.prefix) &&
        candidate.prefix.length > (match?.prefix.length ?? -1)
      ) {
        match = candidate;
      }
    }
    return match?.route;
  };
  const readiness = async (): Promise<RoleReadiness> => {
    if (starting) return { ready: false, reason: "starting" };
    const mounted = new Set(routes.map(({ route }) => route));
    for (const route of mounted) {
      let result: RoleReadiness;
      try {
        result = (await route.readiness?.()) ?? { ready: true };
      } catch {
        result = { ready: false, reason: "dependency_check_failed" };
      }
      if (!result.ready) return result;
    }
    return { ready: true };
  };
  const probe = async (path: string): Promise<Response> => {
    if (path === "/healthz") return Response.json({ status: "ok" });
    if (path === "/startupz") {
      return starting
        ? Response.json({ status: "starting" }, { status: 503 })
        : Response.json({ status: "ok" });
    }
    const result = await readiness();
    return result.ready
      ? Response.json({ status: "ok" })
      : Response.json(
          { reason: result.reason, status: "not_ready" },
          { status: 503 },
        );
  };
  const dispatch = async (request: Request): Promise<Response> => {
    const path = new URL(request.url).pathname;
    if (PROBES.has(path)) {
      if (request.method !== "GET") {
        return new Response(null, { status: 405, headers: { allow: "GET" } });
      }
      return probe(path);
    }
    const route = routeFor(path);
    if (route) return route.fetch(request);
    if (starting) {
      return Response.json(
        {
          error: {
            code: "SERVICE_NOT_READY",
            message: "Node Services is starting",
          },
        },
        { status: 503 },
      );
    }
    return new Response(null, { status: 404 });
  };
  const server = createAdaptorServer({
    fetch: dispatch,
    hostname: options.host,
    // Roles on the main thread must not replace process globals.
    overrideGlobalObjects: false,
  }) as Server;
  await new Promise<void>((resolve, reject) => {
    server.once("error", reject);
    server.listen(options.port, options.host, () => {
      server.off("error", reject);
      resolve();
    });
  });
  const address = server.address();
  if (!address || typeof address === "string") {
    server.close();
    throw new Error("HTTP server did not receive a TCP address");
  }
  const host = options.host;
  // A wildcard listener is reached through loopback from this machine.
  const urlHost =
    host === "0.0.0.0" ? "127.0.0.1" : host === "::" ? "::1" : host;
  return {
    server,
    host,
    port: address.port,
    url: `http://${urlHost.includes(":") ? `[${urlHost}]` : urlHost}:${address.port}`,
    mount(route) {
      for (const prefix of route.prefixes) {
        if (!prefix.startsWith("/") || PROBES.has(prefix)) {
          throw new TypeError(`Invalid HTTP route prefix: ${prefix}`);
        }
        if (routes.some((mounted) => mounted.prefix === prefix)) {
          throw new TypeError(`HTTP route prefix already mounted: ${prefix}`);
        }
      }
      const entries = route.prefixes.map((prefix) => ({ prefix, route }));
      routes.push(...entries);
      return () => {
        for (const entry of entries) {
          const index = routes.indexOf(entry);
          if (index >= 0) routes.splice(index, 1);
        }
      };
    },
    finishStartup() {
      starting = false;
    },
    close: () =>
      new Promise<void>((resolve, reject) => {
        if (!server.listening) {
          resolve();
          return;
        }
        server.close((error) => (error ? reject(error) : resolve()));
      }),
  };
}

/**
 * Reads a request body, stopping as soon as it exceeds `maxBytes`. Returns
 * undefined when the limit is exceeded.
 */
export async function readBodyWithLimit(
  request: Request,
  maxBytes: number,
): Promise<Buffer | undefined> {
  const reader = request.body?.getReader();
  if (!reader) return Buffer.alloc(0);
  const chunks: Buffer[] = [];
  let sizeBytes = 0;
  for (;;) {
    const { done, value } = await reader.read();
    if (done) return Buffer.concat(chunks, sizeBytes);
    sizeBytes += value.byteLength;
    if (sizeBytes > maxBytes) {
      await reader.cancel().catch(() => undefined);
      return undefined;
    }
    chunks.push(Buffer.from(value.buffer, value.byteOffset, value.byteLength));
  }
}