nolo-cli 0.1.33 → 0.1.35

package/database/server/cliAuthorityBrokerClient.ts

@@ -0,0 +1,227 @@
+import type {
+  AuthorityBatchOperation,
+  AuthorityBatchWriter,
+  AuthorityIteratorOptions,
+  AuthorityStore,
+} from "./authorityStoreTypes";
+import type {
+  CliAuthorityBrokerRequest,
+  CliAuthorityBrokerResponse,
+} from "./cliAuthorityBrokerTypes";
+import { createConnection } from "node:net";
+
+const DEFAULT_ITERATOR_PAGE_SIZE = 200;
+
+export class CliAuthorityBrokerUnavailableError extends Error {
+  readonly reason = "cli_authority_broker_unavailable";
+  readonly status = 503;
+  readonly endpoint: string;
+
+  constructor(endpoint: string, cause?: unknown) {
+    super(`CLI authority broker unavailable at ${endpoint}. Start the local authority broker and retry.`);
+    this.name = "CliAuthorityBrokerUnavailableError";
+    this.endpoint = endpoint;
+    if (cause !== undefined) {
+      (this as Error & { cause?: unknown }).cause = cause;
+    }
+  }
+}
+
+export class CliAuthorityBrokerProtocolError extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+
+  constructor(error: { code: string; message: string; retryable?: boolean }) {
+    super(error.message);
+    this.name = "CliAuthorityBrokerProtocolError";
+    this.code = error.code;
+    this.retryable = error.retryable === true;
+  }
+}
+
+export function isCliAuthorityBrokerUnavailableError(
+  error: unknown
+): error is CliAuthorityBrokerUnavailableError {
+  return (
+    error instanceof CliAuthorityBrokerUnavailableError ||
+    (
+      typeof error === "object" &&
+      error !== null &&
+      (error as any).reason === "cli_authority_broker_unavailable" &&
+      (error as any).status === 503
+    )
+  );
+}
+
+function isCliAuthorityBrokerProtocolError(
+  error: unknown
+): error is CliAuthorityBrokerProtocolError {
+  return error instanceof CliAuthorityBrokerProtocolError;
+}
+
+export type CliAuthorityBrokerRequestInvoker = (
+  request: CliAuthorityBrokerRequest
+) => Promise<CliAuthorityBrokerResponse>;
+
+export type CliAuthorityBrokerClientOptions = {
+  endpoint: string;
+  location?: string;
+  status?: string;
+  invoke: CliAuthorityBrokerRequestInvoker;
+  iteratorPageSize?: number;
+};
+
+type BrokerSocketTarget =
+  | { kind: "unix"; path: string }
+  | { kind: "tcp"; host: string; port: number };
+
+function resolveBrokerSocketTarget(endpoint: string): BrokerSocketTarget {
+  if (endpoint.startsWith("unix://")) {
+    return { kind: "unix", path: endpoint.slice("unix://".length) };
+  }
+  if (endpoint.startsWith("tcp://")) {
+    const url = new URL(endpoint);
+    return {
+      kind: "tcp",
+      host: url.hostname,
+      port: Number(url.port),
+    };
+  }
+  throw new Error(`Unsupported CLI authority broker endpoint: ${endpoint}`);
+}
+
+export function createCliAuthorityBrokerSocketInvoker(options: {
+  endpoint: string;
+}): CliAuthorityBrokerRequestInvoker {
+  const target = resolveBrokerSocketTarget(options.endpoint);
+  return async (request: CliAuthorityBrokerRequest) => {
+    return await new Promise<CliAuthorityBrokerResponse>((resolve, reject) => {
+      const socket = target.kind === "unix"
+        ? createConnection(target.path)
+        : createConnection({ host: target.host, port: target.port });
+      let responseBuffer = "";
+      let settled = false;
+
+      const finish = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        fn();
+      };
+
+      socket.setEncoding("utf8");
+      socket.on("connect", () => {
+        socket.write(`${JSON.stringify(request)}\n`);
+      });
+      socket.on("data", (chunk) => {
+        responseBuffer += chunk;
+      });
+      socket.on("end", () => {
+        finish(() => {
+          const payload = responseBuffer.trim();
+          if (!payload) {
+            reject(new Error(`CLI authority broker at ${options.endpoint} returned no response`));
+            return;
+          }
+          try {
+            resolve(JSON.parse(payload) as CliAuthorityBrokerResponse);
+          } catch (error) {
+            reject(error);
+          }
+        });
+      });
+      socket.on("error", (error) => {
+        finish(() => reject(error));
+      });
+    });
+  };
+}
+
+async function invokeBrokerRequest(
+  options: CliAuthorityBrokerClientOptions,
+  request: CliAuthorityBrokerRequest
+) {
+  try {
+    const response = await options.invoke(request);
+    if (response.ok) return response.result;
+    if (response.error.code === "BROKER_UNAVAILABLE") {
+      throw new CliAuthorityBrokerUnavailableError(options.endpoint, response.error);
+    }
+    throw new CliAuthorityBrokerProtocolError(response.error);
+  } catch (error) {
+    if (isCliAuthorityBrokerUnavailableError(error)) throw error;
+    if (isCliAuthorityBrokerProtocolError(error)) throw error;
+    throw new CliAuthorityBrokerUnavailableError(options.endpoint, error);
+  }
+}
+
+export function createCliAuthorityBrokerClient(
+  options: CliAuthorityBrokerClientOptions
+): AuthorityStore {
+  const pageSize = options.iteratorPageSize ?? DEFAULT_ITERATOR_PAGE_SIZE;
+
+  return {
+    get location() {
+      return options.location ?? options.endpoint;
+    },
+    get status() {
+      return options.status ?? "broker";
+    },
+    async open() {
+      await invokeBrokerRequest(options, { type: "status" });
+    },
+    async close() {},
+    async get<T = any>(key: string) {
+      const result = await invokeBrokerRequest(options, { type: "get", key });
+      if (result.type !== "get") {
+        throw new Error(`CLI authority broker protocol mismatch for get at ${options.endpoint}`);
+      }
+      return result.value as T;
+    },
+    async put(key: string, value: unknown) {
+      await invokeBrokerRequest(options, { type: "put", key, value });
+    },
+    async del(key: string) {
+      await invokeBrokerRequest(options, { type: "del", key });
+    },
+    async batchWrite(ops: AuthorityBatchOperation[]) {
+      await invokeBrokerRequest(options, { type: "batchWrite", ops });
+    },
+    createBatch(): AuthorityBatchWriter {
+      const ops: AuthorityBatchOperation[] = [];
+      return {
+        put(key: string, value: unknown) {
+          ops.push({ type: "put", key, value });
+        },
+        del(key: string) {
+          ops.push({ type: "del", key });
+        },
+        async write() {
+          await invokeBrokerRequest(options, { type: "batchWrite", ops });
+        },
+      };
+    },
+    iterator(iteratorOptions: AuthorityIteratorOptions = {}) {
+      return (async function* iterate() {
+        let cursor: string | null | undefined = undefined;
+        while (true) {
+          const result = await invokeBrokerRequest(options, {
+            type: "iterator",
+            options: iteratorOptions,
+            cursor,
+            limit: pageSize,
+          });
+          if (result.type !== "iterator") {
+            throw new Error(
+              `CLI authority broker protocol mismatch for iterator at ${options.endpoint}`
+            );
+          }
+          for (const entry of result.page.entries) {
+            yield entry;
+          }
+          if (result.page.done || !result.page.nextCursor) return;
+          cursor = result.page.nextCursor;
+        }
+      })();
+    },
+  };
+}

package/database/server/cliAuthorityBrokerServer.ts

@@ -0,0 +1,283 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createServer, type AddressInfo, type Server, type Socket } from "node:net";
+
+import type { AuthorityStore } from "./authorityStoreTypes";
+import type {
+  CliAuthorityBrokerIteratorPage,
+  CliAuthorityBrokerRequest,
+  CliAuthorityBrokerResponse,
+} from "./cliAuthorityBrokerTypes";
+
+const brokerRegistry = new Map<string, Promise<CliAuthorityBrokerServerHandle>>();
+const DEFAULT_ITERATOR_LIMIT = 200;
+
+export type CliAuthorityBrokerServerOptions = {
+  endpoint: string;
+  createStore: () => AuthorityStore | Promise<AuthorityStore>;
+  metadataPath?: string;
+  healthPath?: string;
+  now?: () => number;
+  transportMode?: "socket" | "inprocess";
+};
+
+export type CliAuthorityBrokerServerHandle = {
+  endpoint: string;
+  listeningEndpoint: string;
+  authorityStore: AuthorityStore;
+  request(request: CliAuthorityBrokerRequest): Promise<CliAuthorityBrokerResponse>;
+  close(): Promise<void>;
+};
+
+type BrokerListenTarget =
+  | { kind: "unix"; path: string }
+  | { kind: "tcp"; host: string; port: number };
+
+function resolveBrokerListenTarget(endpoint: string): BrokerListenTarget {
+  if (endpoint.startsWith("unix://")) {
+    return { kind: "unix", path: endpoint.slice("unix://".length) };
+  }
+  if (endpoint.startsWith("tcp://")) {
+    const url = new URL(endpoint);
+    return {
+      kind: "tcp",
+      host: url.hostname,
+      port: Number(url.port),
+    };
+  }
+  throw new Error(`Unsupported CLI authority broker endpoint: ${endpoint}`);
+}
+
+function buildListeningEndpoint(server: Server, target: BrokerListenTarget) {
+  if (target.kind === "unix") {
+    return `unix://${target.path}`;
+  }
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    return `tcp://${target.host}:${target.port}`;
+  }
+  const info = address as AddressInfo;
+  return `tcp://${target.host}:${info.port}`;
+}
+
+function ensureParentDir(filePath: string) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function writeJsonFile(filePath: string | undefined, data: Record<string, unknown>) {
+  if (!filePath) return;
+  ensureParentDir(filePath);
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+function removeFileIfPresent(filePath: string | undefined) {
+  if (!filePath) return;
+  try {
+    fs.rmSync(filePath, { force: true });
+  } catch {}
+}
+
+async function buildIteratorPage(
+  store: AuthorityStore,
+  request: Extract<CliAuthorityBrokerRequest, { type: "iterator" }>
+): Promise<CliAuthorityBrokerIteratorPage> {
+  const rows: Array<[string, unknown]> = [];
+  for await (const entry of store.iterator(request.options ?? {})) {
+    rows.push(entry as [string, unknown]);
+  }
+
+  const startIndex = request.cursor
+    ? rows.findIndex(([key]) => key === request.cursor) + 1
+    : 0;
+  const limit = request.limit ?? DEFAULT_ITERATOR_LIMIT;
+  const entries = rows.slice(startIndex, startIndex + limit);
+  const lastEntry = entries.at(-1) ?? null;
+
+  return {
+    entries,
+    nextCursor: lastEntry ? lastEntry[0] : null,
+    done: startIndex + entries.length >= rows.length,
+  };
+}
+
+function createErrorResponse(error: unknown): CliAuthorityBrokerResponse {
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    typeof (error as any).code === "string" &&
+    typeof (error as any).message === "string"
+  ) {
+    return {
+      ok: false,
+      error: {
+        code: (error as any).code,
+        message: (error as any).message,
+        retryable: (error as any).retryable === true,
+      },
+    };
+  }
+  return {
+    ok: false,
+    error: {
+      code: "BROKER_INTERNAL_ERROR",
+      message: error instanceof Error ? error.message : String(error),
+    },
+  };
+}
+
+export async function dispatchCliAuthorityBrokerRequest(
+  store: AuthorityStore,
+  request: CliAuthorityBrokerRequest
+): Promise<CliAuthorityBrokerResponse> {
+  try {
+    switch (request.type) {
+      case "status":
+        return { ok: true, result: { type: "status" } };
+      case "open":
+        await store.open();
+        return { ok: true, result: { type: "open" } };
+      case "close":
+        await store.close();
+        return { ok: true, result: { type: "close" } };
+      case "get":
+        return { ok: true, result: { type: "get", value: await store.get(request.key) } };
+      case "put":
+        await store.put(request.key, request.value);
+        return { ok: true, result: { type: "put" } };
+      case "del":
+        await store.del(request.key);
+        return { ok: true, result: { type: "del" } };
+      case "batchWrite":
+        await store.batchWrite(request.ops);
+        return { ok: true, result: { type: "batchWrite" } };
+      case "iterator":
+        return {
+          ok: true,
+          result: {
+            type: "iterator",
+            page: await buildIteratorPage(store, request),
+          },
+        };
+    }
+  } catch (error) {
+    return createErrorResponse(error);
+  }
+}
+
+async function createBrokerHandle(
+  options: CliAuthorityBrokerServerOptions
+): Promise<CliAuthorityBrokerServerHandle> {
+  const target = resolveBrokerListenTarget(options.endpoint);
+  if (target.kind === "unix") {
+    ensureParentDir(target.path);
+    removeFileIfPresent(target.path);
+  }
+
+  const store = await options.createStore();
+  await store.open();
+
+  const server = createServer((socket) => {
+    bindSocketRequestHandler({ socket, store });
+  });
+
+  if ((options.transportMode ?? "socket") === "socket") {
+    try {
+      await new Promise<void>((resolve, reject) => {
+        server.once("error", reject);
+        if (target.kind === "unix") {
+          server.listen(target.path, () => {
+            server.off("error", reject);
+            resolve();
+          });
+          return;
+        }
+        server.listen(target.port, target.host, () => {
+          server.off("error", reject);
+          resolve();
+        });
+      });
+      server.unref();
+    } catch (error) {
+      await store.close().catch(() => {});
+      throw error;
+    }
+  }
+
+  const now = options.now ?? Date.now;
+  const listeningEndpoint = (options.transportMode ?? "socket") === "socket"
+    ? buildListeningEndpoint(server, target)
+    : options.endpoint;
+  writeJsonFile(options.metadataPath, {
+    pid: process.pid,
+    endpoint: listeningEndpoint,
+    location: store.location ?? listeningEndpoint,
+    startedAt: new Date(now()).toISOString(),
+  });
+  writeJsonFile(options.healthPath, {
+    ok: true,
+    pid: process.pid,
+    endpoint: listeningEndpoint,
+    checkedAt: new Date(now()).toISOString(),
+  });
+
+  let closed = false;
+  return {
+    endpoint: options.endpoint,
+    listeningEndpoint,
+    authorityStore: store,
+    request(request: CliAuthorityBrokerRequest) {
+      return dispatchCliAuthorityBrokerRequest(store, request);
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      brokerRegistry.delete(options.endpoint);
+      if ((options.transportMode ?? "socket") === "socket") {
+        await new Promise<void>((resolve, reject) => {
+          server.close((error) => error ? reject(error) : resolve());
+        });
+      }
+      await store.close();
+      if (target.kind === "unix") {
+        removeFileIfPresent(target.path);
+      }
+      removeFileIfPresent(options.metadataPath);
+      removeFileIfPresent(options.healthPath);
+    },
+  };
+}
+
+function bindSocketRequestHandler(args: { socket: Socket; store: AuthorityStore }) {
+  let buffer = "";
+  args.socket.setEncoding("utf8");
+  args.socket.on("data", async (chunk) => {
+    buffer += chunk;
+    if (!buffer.includes("\n")) return;
+    const [rawRequest] = buffer.split("\n");
+    buffer = "";
+    let response: CliAuthorityBrokerResponse;
+    try {
+      response = await dispatchCliAuthorityBrokerRequest(
+        args.store,
+        JSON.parse(rawRequest) as CliAuthorityBrokerRequest
+      );
+    } catch (error) {
+      response = createErrorResponse(error);
+    }
+    args.socket.end(`${JSON.stringify(response)}\n`);
+  });
+}
+
+export function getOrCreateCliAuthorityBrokerServer(
+  options: CliAuthorityBrokerServerOptions
+): Promise<CliAuthorityBrokerServerHandle> {
+  const existing = brokerRegistry.get(options.endpoint);
+  if (existing) return existing;
+
+  const pending = createBrokerHandle(options).catch((error) => {
+    brokerRegistry.delete(options.endpoint);
+    throw error;
+  });
+  brokerRegistry.set(options.endpoint, pending);
+  return pending;
+}

package/database/server/cliAuthorityBrokerTypes.ts

@@ -0,0 +1,43 @@
+import type {
+  AuthorityBatchOperation,
+  AuthorityIteratorOptions,
+} from "./authorityStoreTypes";
+
+export type CliAuthorityBrokerRequest =
+  | { type: "status" }
+  | { type: "open" }
+  | { type: "close" }
+  | { type: "get"; key: string }
+  | { type: "put"; key: string; value: unknown }
+  | { type: "del"; key: string }
+  | { type: "batchWrite"; ops: AuthorityBatchOperation[] }
+  | {
+      type: "iterator";
+      options?: AuthorityIteratorOptions;
+      cursor?: string | null;
+      limit?: number;
+    };
+
+export type CliAuthorityBrokerIteratorPage = {
+  entries: Array<[string, unknown]>;
+  nextCursor: string | null;
+  done: boolean;
+};
+
+export type CliAuthorityBrokerSuccessResponse =
+  | { ok: true; result: { type: "status" | "open" | "close" | "put" | "del" | "batchWrite" } }
+  | { ok: true; result: { type: "get"; value: unknown } }
+  | { ok: true; result: { type: "iterator"; page: CliAuthorityBrokerIteratorPage } };
+
+export type CliAuthorityBrokerErrorResponse = {
+  ok: false;
+  error: {
+    code: string;
+    message: string;
+    retryable?: boolean;
+  };
+};
+
+export type CliAuthorityBrokerResponse =
+  | CliAuthorityBrokerSuccessResponse
+  | CliAuthorityBrokerErrorResponse;

package/database/server/cliAuthorityStoreDriver.ts

@@ -0,0 +1,98 @@
+import path from "node:path";
+
+import { resolveNoloHome, type ResolveServerDbPathOptions } from "./dbPath";
+
+export type CliAuthorityStoreDriver = "broker";
+export type CliAuthorityBrokerTransport = "tcp" | "unix";
+
+type EnvLike = Record<string, string | undefined>;
+
+type CliAuthorityStoreDriverOptions = ResolveServerDbPathOptions & {
+  env?: EnvLike;
+};
+
+type CliAuthorityBrokerOptions = CliAuthorityStoreDriverOptions & {
+  transport: CliAuthorityBrokerTransport;
+};
+
+function readCliAuthorityDriver(
+  env: EnvLike
+): { driver: CliAuthorityStoreDriver; invalidDriver: string | null } {
+  const value = env.NOLO_CLI_AUTHORITY_DRIVER?.trim();
+  if (value === "broker") {
+    return { driver: "broker", invalidDriver: null };
+  }
+  return {
+    driver: "broker",
+    invalidDriver: value ? value : null,
+  };
+}
+
+function resolveCliAuthorityRunDir(options: CliAuthorityStoreDriverOptions = {}) {
+  return path.join(resolveNoloHome({
+    ...options,
+    env: options.env ?? {},
+  }), "run");
+}
+
+function hashString(value: string) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = ((hash << 5) - hash + value.charCodeAt(index)) | 0;
+  }
+  return Math.abs(hash);
+}
+
+export function resolveCliAuthorityBrokerPort(
+  options: CliAuthorityStoreDriverOptions = {}
+) {
+  const envPort = options.env?.NOLO_CLI_AUTHORITY_BROKER_PORT?.trim();
+  if (envPort) {
+    const port = Number(envPort);
+    if (Number.isInteger(port) && port > 0 && port < 65536) return port;
+  }
+  const noloHome = resolveNoloHome({
+    ...options,
+    env: options.env ?? {},
+  });
+  return 47000 + (hashString(noloHome) % 2000);
+}
+
+export function resolveCliAuthorityStoreDriver(
+  options: CliAuthorityStoreDriverOptions = {}
+): CliAuthorityStoreDriver {
+  return readCliAuthorityDriver(options.env ?? {}).driver;
+}
+
+export function resolveCliAuthorityStoreDriverConfig(
+  options: CliAuthorityStoreDriverOptions = {}
+) {
+  return readCliAuthorityDriver(options.env ?? {});
+}
+
+export function resolveCliAuthorityBrokerSocketPath(
+  options: CliAuthorityBrokerOptions
+) {
+  return path.join(resolveCliAuthorityRunDir(options), "authority-store-broker.sock");
+}
+
+export function resolveCliAuthorityBrokerEndpoint(
+  options: CliAuthorityBrokerOptions
+) {
+  if (options.transport === "tcp") {
+    return `tcp://127.0.0.1:${resolveCliAuthorityBrokerPort(options)}`;
+  }
+  return `unix://${resolveCliAuthorityBrokerSocketPath(options)}`;
+}
+
+export function resolveCliAuthorityBrokerMetadataPath(
+  options: CliAuthorityBrokerOptions
+) {
+  return path.join(resolveCliAuthorityRunDir(options), "authority-store-broker.json");
+}
+
+export function resolveCliAuthorityBrokerHealthPath(
+  options: CliAuthorityBrokerOptions
+) {
+  return path.join(resolveCliAuthorityRunDir(options), "authority-store-broker.health.json");
+}

package/database/server/legacyServerDb.ts

@@ -0,0 +1,58 @@
+import type {
+  AuthorityBatchOperation,
+  AuthorityBatchWriter,
+  AuthorityIteratorOptions,
+  AuthorityStore,
+} from "./authorityStoreTypes";
+
+export type LegacyServerDb = {
+  readonly location?: string;
+  readonly status?: string;
+  open(): Promise<void>;
+  close(): Promise<void>;
+  get<T = any>(key: string): Promise<T>;
+  put(key: string, value: unknown): Promise<void>;
+  del(key: string): Promise<void>;
+  batch(ops: AuthorityBatchOperation[]): Promise<void>;
+  batch(): AuthorityBatchWriter;
+  iterator(
+    options?: AuthorityIteratorOptions
+  ): AsyncIterableIterator<[string, unknown]>;
+};
+
+export function createLegacyServerDb(store: AuthorityStore): LegacyServerDb {
+  const batch = (ops?: AuthorityBatchOperation[]) => {
+    if (Array.isArray(ops)) {
+      return store.batchWrite(ops);
+    }
+    return store.createBatch();
+  };
+
+  return {
+    get location() {
+      return store.location;
+    },
+    get status() {
+      return store.status;
+    },
+    async open() {
+      await store.open();
+    },
+    async close() {
+      await store.close();
+    },
+    async get<T = any>(key: string) {
+      return store.get<T>(key);
+    },
+    async put(key: string, value: unknown) {
+      await store.put(key, value);
+    },
+    async del(key: string) {
+      await store.del(key);
+    },
+    batch: batch as LegacyServerDb["batch"],
+    iterator(options: AuthorityIteratorOptions = {}) {
+      return store.iterator(options);
+    },
+  };
+}