@remnic/server 9.54.5 → 9.54.7

package/src/server-env.ts

@@ -0,0 +1,68 @@
+/**
+ * @remnic/server — environment-sourced server config.
+ *
+ * Extracted from index.ts (issue #2029): keeps the env → server-config surface
+ * in one place and keeps index.ts under its structural size ceiling. Values are
+ * returned as raw strings; `parseServerConfig` coerces/validates them.
+ */
+
+import type { ServerConfig } from "./index.js";
+
+/**
+ * Read an env var by its current `REMNIC_` name, falling back to the legacy
+ * `ENGRAM_` name.
+ */
+export function readCompatEnv(primary: string, legacy: string): string | undefined {
+  return process.env[primary] ?? process.env[legacy];
+}
+
+/**
+ * Collect server-config overrides sourced from environment variables. Merged
+ * over file config (file < env < cli) by the server startup path.
+ */
+export function envOverrides(): Partial<ServerConfig["server"]> & { remnic?: Record<string, unknown> } {
+  const overrides: Record<string, unknown> = {};
+  const remnic: Record<string, unknown> = {};
+
+  const port = readCompatEnv("REMNIC_PORT", "ENGRAM_PORT");
+  const host = readCompatEnv("REMNIC_HOST", "ENGRAM_HOST");
+  const authToken = readCompatEnv("REMNIC_AUTH_TOKEN", "ENGRAM_AUTH_TOKEN");
+  const adminConsoleEnabled = readCompatEnv("REMNIC_ADMIN_CONSOLE_ENABLED", "ENGRAM_ADMIN_CONSOLE_ENABLED");
+  const adminConsolePublicDir = readCompatEnv("REMNIC_ADMIN_CONSOLE_PUBLIC_DIR", "ENGRAM_ADMIN_CONSOLE_PUBLIC_DIR");
+  const adminConsolePrefillToken = readCompatEnv("REMNIC_ADMIN_CONSOLE_PREFILL_TOKEN", "ENGRAM_ADMIN_CONSOLE_PREFILL_TOKEN");
+  const readinessOverride = process.env.REMNIC_READY_OVERRIDE;
+  const readinessDegradedAfterAttempts = readCompatEnv(
+    "REMNIC_READY_DEGRADED_AFTER_ATTEMPTS",
+    "ENGRAM_READY_DEGRADED_AFTER_ATTEMPTS",
+  );
+  // issue #2029: size the global write rate limit from env. The standalone
+  // server already honors `server.writeRateLimit*` in config; this makes it
+  // settable via the launchd/systemd environment without editing config.json.
+  const writeRateLimitMaxRequests = readCompatEnv(
+    "REMNIC_WRITE_RATE_LIMIT_MAX_REQUESTS",
+    "ENGRAM_WRITE_RATE_LIMIT_MAX_REQUESTS",
+  );
+  const writeRateLimitWindowMs = readCompatEnv(
+    "REMNIC_WRITE_RATE_LIMIT_WINDOW_MS",
+    "ENGRAM_WRITE_RATE_LIMIT_WINDOW_MS",
+  );
+  if (port) overrides.port = port;
+  if (host) overrides.host = host;
+  if (authToken) overrides.authToken = authToken;
+  if (adminConsoleEnabled) overrides.adminConsoleEnabled = adminConsoleEnabled;
+  if (adminConsolePublicDir) overrides.adminConsolePublicDir = adminConsolePublicDir;
+  if (adminConsolePrefillToken) overrides.adminConsolePrefillToken = adminConsolePrefillToken;
+  if (readinessOverride !== undefined) overrides.readinessOverride = readinessOverride;
+  if (readinessDegradedAfterAttempts !== undefined) overrides.readinessDegradedAfterAttempts = readinessDegradedAfterAttempts;
+  // Use `!== undefined` (not truthiness) so an explicitly-set empty/invalid
+  // value still reaches parseServerConfig and is rejected, rather than being
+  // silently dropped so file config wins (issue #2029 review).
+  if (writeRateLimitMaxRequests !== undefined) overrides.writeRateLimitMaxRequests = writeRateLimitMaxRequests;
+  if (writeRateLimitWindowMs !== undefined) overrides.writeRateLimitWindowMs = writeRateLimitWindowMs;
+
+  if (process.env.OPENAI_API_KEY) remnic.openaiApiKey = process.env.OPENAI_API_KEY;
+  const memoryDir = readCompatEnv("REMNIC_MEMORY_DIR", "ENGRAM_MEMORY_DIR");
+  if (memoryDir) remnic.memoryDir = memoryDir;
+
+  return { ...overrides, ...(Object.keys(remnic).length > 0 ? { remnic } : {}) };
+}

package/src/startup-readiness.ts

@@ -0,0 +1,238 @@
+/**
+ * @remnic/server — standalone startup readiness gate.
+ *
+ * Extracted from index.ts (issue #2215): owns the search warm-up loop that
+ * drives `/engram/v1/health` readiness, including the degraded-mode transition
+ * that keeps a functional daemon from reporting itself offline forever when
+ * warm-up cannot complete. Keeps index.ts under its structural size ceiling.
+ */
+
+import { log } from "@remnic/core";
+
+interface PromiseResolvers<T> {
+  promise: Promise<T>;
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: unknown) => void;
+}
+
+type PromiseConstructorWithResolvers = PromiseConstructor & {
+  withResolvers<T>(): PromiseResolvers<T>;
+};
+
+/**
+ * Like `setTimeout` wrapped in a Promise, but respects an `AbortSignal`.
+ * Resolves immediately (without throwing) when the signal fires so the
+ * caller can check `signal.aborted` and exit cleanly.
+ */
+export function abortableDelay(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.resolve();
+  const { promise, resolve } = (Promise as PromiseConstructorWithResolvers).withResolvers<void>();
+  const timer = setTimeout(resolve, ms);
+  const onAbort = () => {
+    clearTimeout(timer);
+    resolve();
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  return promise.finally(() => signal.removeEventListener("abort", onAbort));
+}
+
+const STARTUP_WARMUP_TIMEOUT_MS = 20_000;
+const STARTUP_WARMUP_RETRY_INTERVAL_MS = 30_000;
+/**
+ * Failed warm-up attempts before the init gate opens in degraded mode
+ * (issue #2215). The daemon keeps serving recall via fallback retrieval while
+ * search warm-up cannot complete (e.g. `qmd` missing from the service PATH),
+ * so a permanently-closed gate reports a working service as offline. After
+ * this many failed attempts the gate opens with `degraded: true` and warm-up
+ * retries continue in the background until they succeed.
+ */
+export const STARTUP_DEGRADED_AFTER_ATTEMPTS = 3;
+
+export interface StartupReadinessState {
+  ready: boolean;
+  warmupAttempts: number;
+  lastError?: string | null;
+  /** True when the gate opened before search warm-up completed (issue #2215). */
+  degraded?: boolean;
+}
+
+export type StartupReadinessOutcome = "warmed" | "cancelled" | "overridden" | "search-disabled";
+
+class StartupWarmupDegradationError extends Error {
+  constructor(code: string) {
+    super(`startup search degraded: ${code}`);
+    this.name = "StartupWarmupDegradationError";
+  }
+}
+
+class StartupSyncPendingError extends Error {
+  constructor() {
+    super("startup search sync is not complete");
+    this.name = "StartupSyncPendingError";
+  }
+}
+
+export async function runStartupSearchWarmup(options: {
+  signal: AbortSignal;
+  isAvailable: () => boolean;
+  search: (onDegradation: (code: string) => void) => Promise<unknown>;
+}): Promise<void> {
+  let degradationCode: string | undefined;
+  await options.search((code) => {
+    degradationCode = code;
+  });
+  if (options.signal.aborted) return;
+  if (degradationCode) throw new StartupWarmupDegradationError(degradationCode);
+  if (!options.isAvailable()) {
+    throw new StartupWarmupDegradationError("backend_unavailable");
+  }
+}
+
+export async function completeStartupReadiness(options: {
+  deferredReady: Promise<void>;
+  warmup: (signal: AbortSignal) => Promise<unknown>;
+  prepareWarmup?: (signal: AbortSignal) => Promise<boolean>;
+  state: StartupReadinessState;
+  timeoutMs?: number;
+  retryIntervalMs?: number;
+  /** Failed attempts before the gate opens degraded; 0 disables (strict gate). */
+  degradedAfterAttempts?: number;
+  override?: boolean;
+  skipWarmup?: () => boolean;
+  openGate: () => void;
+  shutdownSignal?: AbortSignal;
+  warn?: (message: string) => void;
+  info?: (message: string) => void;
+  error?: (message: string) => void;
+}): Promise<StartupReadinessOutcome> {
+  const timeoutMs = options.timeoutMs ?? STARTUP_WARMUP_TIMEOUT_MS;
+  const retryIntervalMs = options.retryIntervalMs ?? STARTUP_WARMUP_RETRY_INTERVAL_MS;
+  const degradedAfterAttempts = options.degradedAfterAttempts ?? STARTUP_DEGRADED_AFTER_ATTEMPTS;
+  const warn = options.warn ?? ((message: string) => log.warn(message));
+  const info = options.info ?? ((message: string) => log.info(message));
+  const error = options.error ?? ((message: string) => log.error(message));
+
+  options.state.ready = false;
+  options.state.lastError = null;
+  options.state.degraded = false;
+  if (options.override) {
+    options.openGate();
+    options.state.ready = true;
+    error(
+      "CRITICAL: emergency readiness override enabled; exposing a cold search backend to traffic",
+    );
+    return "overridden";
+  }
+  if (options.skipWarmup?.()) {
+    options.openGate();
+    options.state.ready = true;
+    info("Standalone init gate opened without search warm-up (search intentionally disabled)");
+    return "search-disabled";
+  }
+
+  let removeDeferredShutdownListener: () => void = () => undefined;
+  const deferredShutdown = new Promise<"shutdown">((resolve) => {
+    if (options.shutdownSignal?.aborted) {
+      resolve("shutdown");
+      return;
+    }
+    const onDeferredShutdown = () => resolve("shutdown");
+    options.shutdownSignal?.addEventListener("abort", onDeferredShutdown, { once: true });
+    removeDeferredShutdownListener = () =>
+      options.shutdownSignal?.removeEventListener("abort", onDeferredShutdown);
+  });
+  try {
+    const deferredOutcome = await Promise.race([
+      options.deferredReady.then(() => "ready" as const),
+      deferredShutdown,
+    ]);
+    if (deferredOutcome === "shutdown") return "cancelled";
+  } catch (err) {
+    if (options.shutdownSignal?.aborted) return "cancelled";
+    options.state.lastError = err instanceof Error ? err.name : typeof err;
+    warn(`Standalone deferred initialization failed; warm-up retries will continue: ${err}`);
+  } finally {
+    removeDeferredShutdownListener();
+  }
+  if (options.shutdownSignal?.aborted) return "cancelled";
+
+  const lifecycleAbort = new AbortController();
+  const onShutdown = () => lifecycleAbort.abort(options.shutdownSignal?.reason);
+  options.shutdownSignal?.addEventListener("abort", onShutdown, { once: true });
+
+  try {
+    while (!lifecycleAbort.signal.aborted) {
+      if (options.skipWarmup?.()) {
+        options.state.degraded = false;
+        options.openGate();
+        options.state.ready = true;
+        info("Standalone init gate opened without search warm-up (search intentionally disabled)");
+        return "search-disabled";
+      }
+      options.state.warmupAttempts += 1;
+      const warmupAbort = new AbortController();
+      const onLifecycleAbort = () => warmupAbort.abort(lifecycleAbort.signal.reason);
+      lifecycleAbort.signal.addEventListener("abort", onLifecycleAbort, { once: true });
+      const timeout = (Promise as PromiseConstructorWithResolvers).withResolvers<never>();
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        warmupAbort.abort();
+        timeout.reject(new Error(`startup warm-up timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      timer.unref();
+
+      try {
+        const attempt = async () => {
+          if (options.prepareWarmup && !await options.prepareWarmup(warmupAbort.signal)) {
+            throw new StartupSyncPendingError();
+          }
+          return options.warmup(warmupAbort.signal);
+        };
+        await Promise.race([attempt(), timeout.promise]);
+        if (lifecycleAbort.signal.aborted) return "cancelled";
+        const recovered = options.state.degraded === true;
+        options.state.lastError = null;
+        options.state.degraded = false;
+        options.openGate();
+        options.state.ready = true;
+        info(
+          `Standalone init gate opened after search warm-up attempt ${options.state.warmupAttempts}${recovered ? " (recovered from degraded mode)" : ""}`,
+        );
+        return "warmed";
+      } catch (err) {
+        if (lifecycleAbort.signal.aborted) return "cancelled";
+        options.state.lastError = timedOut
+          ? "TimeoutError"
+          : err instanceof Error
+            ? err.name
+            : typeof err;
+        warn(
+          timedOut
+            ? `Standalone startup warm-up attempt ${options.state.warmupAttempts} timed out after ${timeoutMs}ms; retrying in ${retryIntervalMs}ms`
+            : `Standalone startup warm-up attempt ${options.state.warmupAttempts} failed (${options.state.lastError}); retrying in ${retryIntervalMs}ms`,
+        );
+        if (
+          degradedAfterAttempts > 0 &&
+          !options.state.ready &&
+          options.state.warmupAttempts >= degradedAfterAttempts
+        ) {
+          options.state.degraded = true;
+          options.openGate();
+          options.state.ready = true;
+          warn(
+            `Standalone init gate opened in DEGRADED mode after ${options.state.warmupAttempts} failed search warm-up attempts (${options.state.lastError}); recall keeps serving via fallback retrieval and warm-up retries continue in the background`,
+          );
+        }
+      } finally {
+        clearTimeout(timer);
+        lifecycleAbort.signal.removeEventListener("abort", onLifecycleAbort);
+      }
+
+      await abortableDelay(retryIntervalMs, lifecycleAbort.signal);
+    }
+    return "cancelled";
+  } finally {
+    options.shutdownSignal?.removeEventListener("abort", onShutdown);
+  }
+}

package/src/support-passport-runtime.ts

@@ -0,0 +1,29 @@
+import {
+  EngramAccessService,
+  type Orchestrator,
+  type PluginConfig,
+  type SupportPassportExternalRequestHandler,
+  SupportPassportModelBridge,
+  composeSupportPassportExternalRequestHandlers,
+} from "@remnic/core";
+
+export interface SupportPassportServerRuntime {
+  service: EngramAccessService;
+  externalRequestHandler: SupportPassportExternalRequestHandler;
+  close(): void;
+}
+
+export function createSupportPassportServerRuntime(
+  orchestrator: Orchestrator,
+  config: PluginConfig,
+  fallbackHandler?: SupportPassportExternalRequestHandler
+): SupportPassportServerRuntime {
+  const bridge = config.supportPassport.enabled ? new SupportPassportModelBridge() : null;
+  return {
+    service: new EngramAccessService(orchestrator, {
+      supportPassportGatewayRoute: bridge?.route,
+    }),
+    externalRequestHandler: composeSupportPassportExternalRequestHandlers(bridge?.requestHandler, fallbackHandler),
+    close: () => bridge?.close(),
+  };
+}