akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/server/ops/snapshotRestore.ts

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync } from "node:fs";
+import { readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import type { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import type { SnapshotFile, SnapshotManifest, SnapshotSources } from "./snapshotTypes";
+import { SqliteSnapshot } from "./sqliteSnapshot";
+
+export interface SnapshotDecryptor {
+  transform(): Transform;
+}
+
+export interface SnapshotRestoreOptions {
+  manifestPath: string;
+  sources: SnapshotSources;
+  decryptor?: SnapshotDecryptor | null;
+  now?: Date;
+}
+
+export interface RestoredFile {
+  role: SnapshotFile["role"];
+  target: string;
+  preservedAs: string | null;
+}
+
+interface StagedFile {
+  file: SnapshotFile;
+  target: string;
+  staged: string;
+}
+
+/** Offline only: it swaps files under a closed database, and nothing here can tell an open connection to let go. */
+export class SnapshotRestore {
+  static async run({ manifestPath, sources, decryptor = null, now = new Date() }: SnapshotRestoreOptions) {
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as SnapshotManifest;
+    if (manifest.format !== "akan-snapshot/v1") throw new Error(`Unknown snapshot format "${String(manifest.format)}"`);
+    const dir = path.dirname(manifestPath);
+    const stamp = now.toISOString().replace(/[:.]/g, "-");
+    const staged: StagedFile[] = [];
+    try {
+      for (const file of manifest.files) {
+        const target = file.role === "main" ? sources.main : sources.solid;
+        if (!target) throw new Error(`This deployment has no ${file.role} database to restore into`);
+        staged.push({
+          file,
+          target,
+          staged: await SnapshotRestore.#stage(file, dir, target, stamp, manifest, decryptor),
+        });
+      }
+    } catch (error) {
+      await Promise.all(staged.map(({ staged: file }) => rm(file, { force: true })));
+      throw error;
+    }
+    const restored: RestoredFile[] = [];
+    for (const { file, target, staged: stagedPath } of staged) {
+      const preservedAs = await SnapshotRestore.#preserve(target, stamp);
+      await rename(stagedPath, target);
+      restored.push({ role: file.role, target, preservedAs });
+    }
+    return { manifest, restored };
+  }
+
+  static async #stage(
+    file: SnapshotFile,
+    dir: string,
+    target: string,
+    stamp: string,
+    manifest: SnapshotManifest,
+    decryptor: SnapshotDecryptor | null,
+  ) {
+    const packed = path.join(dir, file.name);
+    const decryptedName = manifest.encryption ? file.name.replace(/\.age$/, "") : null;
+    
+    const predecrypted = decryptedName && !decryptor ? path.join(dir, decryptedName) : null;
+    if (predecrypted && !existsSync(predecrypted))
+      throw new Error(`${file.name} is encrypted; pass --identity or run age -d -o ${decryptedName} first`);
+    const input = predecrypted ?? packed;
+    if (!existsSync(input)) throw new Error(`Snapshot file missing: ${input}`);
+    if (!predecrypted) {
+      const uploadSha = await SnapshotRestore.#sha256(input);
+      if (uploadSha !== file.uploadSha256) throw new Error(`${file.name} does not match its manifest checksum`);
+    }
+    const stagedPath = `${target}.restore-${stamp}.tmp`;
+    const hash = createHash("sha256");
+    const stages: NodeJS.ReadWriteStream[] = [];
+    if (manifest.encryption && decryptor && !predecrypted) stages.push(decryptor.transform());
+    stages.push(createGunzip(), SqliteSnapshot.tap(hash));
+    await pipeline([createReadStream(input), ...stages, createWriteStream(stagedPath)]);
+    if (hash.digest("hex") !== file.sha256) {
+      await rm(stagedPath, { force: true });
+      throw new Error(`${file.name} decompressed to different bytes than the snapshot recorded`);
+    }
+    const problems = SqliteSnapshot.integrityProblems(stagedPath);
+    if (problems.length) {
+      await rm(stagedPath, { force: true });
+      throw new Error(`${file.name} fails integrity_check: ${problems.slice(0, 3).join("; ")}`);
+    }
+    return stagedPath;
+  }
+
+  static async #preserve(target: string, stamp: string) {
+    if (!existsSync(target)) return null;
+    const preserved = `${target}.pre-restore-${stamp}`;
+    await rename(target, preserved);
+    for (const suffix of ["-wal", "-shm"]) {
+      if (existsSync(`${target}${suffix}`)) await rename(`${target}${suffix}`, `${preserved}${suffix}`);
+    }
+    return preserved;
+  }
+
+  static async #sha256(file: string) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(file)) hash.update(chunk as Buffer);
+    return hash.digest("hex");
+  }
+}

package/server/ops/snapshotTypes.ts

@@ -0,0 +1,52 @@
+import type { DatabaseMode } from "../../base/baseEnv";
+
+export type SnapshotFileRole = "main" | "solid";
+
+export interface SnapshotFile {
+  role: SnapshotFileRole;
+  name: string;
+  sizeBytes: number;
+  sha256: string;
+  encoding: "gzip";
+  uploadBytes: number;
+  uploadSha256: string;
+}
+
+export interface SnapshotEncryption {
+  format: "age";
+  recipients: string[];
+}
+
+export interface SnapshotManifest {
+  format: "akan-snapshot/v1";
+  id: string;
+  appName: string;
+  environment: string;
+  akanVersion: string | null;
+  buildId: string | null;
+  databaseMode: DatabaseMode;
+  createdAt: string;
+  files: SnapshotFile[];
+  integrity: "ok" | string[];
+  encryption: SnapshotEncryption | null;
+}
+
+export interface SnapshotSources {
+  main: string;
+  solid: string | null;
+}
+
+export interface SnapshotUploadUrls {
+  main: string;
+  solid?: string;
+  manifest: string;
+}
+
+export interface SnapshotJobState {
+  id: string;
+  status: "running" | "uploading" | "done" | "failed";
+  startedAt: string;
+  finishedAt?: string;
+  manifest?: SnapshotManifest;
+  error?: string;
+}

package/server/ops/sqliteFiles.ts

@@ -0,0 +1,20 @@
+import path from "node:path";
+import { getEnv } from "../../base/baseEnv";
+import { defaultSqliteFile } from "../../service/predefinedAdaptor/sqlitePath";
+import type { SnapshotSources } from "./snapshotTypes";
+
+export class SqliteFiles {
+  static fromEnv(): SnapshotSources {
+    const { databaseMode } = getEnv();
+    const workspaceRoot = process.env.AKAN_WORKSPACE_ROOT;
+    const main = process.env.SQLITE_DATABASE_PATH ?? defaultSqliteFile("", workspaceRoot);
+    
+    const solid =
+      databaseMode === "single" ? (process.env.AKAN_SOLID_DB_PATH ?? defaultSqliteFile("_solid", workspaceRoot)) : null;
+    return { main: path.resolve(main), solid: solid ? path.resolve(solid) : null };
+  }
+
+  static snapshotDir(sources: SnapshotSources) {
+    return process.env.AKAN_OPS_SNAPSHOT_DIR ?? path.join(path.dirname(sources.main), "snapshots");
+  }
+}

package/server/ops/sqliteSnapshot.ts

@@ -0,0 +1,149 @@
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync } from "node:fs";
+import { mkdir, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+import { getEnv } from "../../base/baseEnv";
+import { AppInfo } from "./appInfo";
+import type {
+  SnapshotEncryption,
+  SnapshotFile,
+  SnapshotFileRole,
+  SnapshotManifest,
+  SnapshotSources,
+} from "./snapshotTypes";
+
+export interface SnapshotEncryptor {
+  readonly encryption: SnapshotEncryption;
+  readonly extension: string;
+  transform(): Transform;
+}
+
+export interface SnapshotCaptureOptions {
+  id: string;
+  dir: string;
+  sources: SnapshotSources;
+  includeSolid?: boolean;
+  encryptor?: SnapshotEncryptor | null;
+}
+
+export interface SnapshotCapture {
+  dir: string;
+  manifest: SnapshotManifest;
+  manifestPath: string;
+  paths: { [role in SnapshotFileRole]?: string };
+}
+
+export class SqliteSnapshot {
+  static readonly manifestName = "manifest.json";
+  static readonly idPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+  static async capture({
+    id,
+    dir,
+    sources,
+    includeSolid = false,
+    encryptor = null,
+  }: SnapshotCaptureOptions): Promise<SnapshotCapture> {
+    if (!SqliteSnapshot.idPattern.test(id)) throw new Error(`Invalid snapshot id "${id}"`);
+    const { appName, environment, databaseMode } = getEnv();
+    if (databaseMode === "cluster" || !databaseMode)
+      throw new Error(`Snapshots support SQLite database modes only, not "${databaseMode ?? "unknown"}"`);
+    const targetDir = path.join(dir, id);
+    if (existsSync(targetDir)) throw new Error(`Snapshot ${id} already exists at ${targetDir}`);
+    await mkdir(targetDir, { recursive: true });
+    try {
+      const roles: [SnapshotFileRole, string][] = [["main", sources.main]];
+      if (includeSolid && sources.solid) roles.push(["solid", sources.solid]);
+      const files: SnapshotFile[] = [];
+      const integrity: string[] = [];
+      const paths: SnapshotCapture["paths"] = {};
+      for (const [role, source] of roles) {
+        const { file, problems, packedPath } = await SqliteSnapshot.#captureOne(role, source, targetDir, encryptor);
+        files.push(file);
+        paths[role] = packedPath;
+        integrity.push(...problems.map((problem) => `${role}: ${problem}`));
+      }
+      const { akanVersion, buildId } = AppInfo.build();
+      const manifest: SnapshotManifest = {
+        format: "akan-snapshot/v1",
+        id,
+        appName,
+        environment,
+        akanVersion,
+        buildId,
+        databaseMode,
+        createdAt: new Date().toISOString(),
+        files,
+        integrity: integrity.length ? integrity : "ok",
+        encryption: encryptor?.encryption ?? null,
+      };
+      const manifestPath = path.join(targetDir, SqliteSnapshot.manifestName);
+      await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+      return { dir: targetDir, manifest, manifestPath, paths };
+    } catch (error) {
+      await rm(targetDir, { recursive: true, force: true });
+      throw error;
+    }
+  }
+
+  static async #captureOne(role: SnapshotFileRole, source: string, dir: string, encryptor: SnapshotEncryptor | null) {
+    if (!existsSync(source)) throw new Error(`No ${role} database at ${source}`);
+    const baseName = path.basename(source);
+    const rawPath = path.join(dir, baseName);
+    SqliteSnapshot.vacuumInto(source, rawPath);
+    const problems = SqliteSnapshot.integrityProblems(rawPath);
+    const sizeBytes = (await stat(rawPath)).size;
+    const name = `${baseName}.gz${encryptor?.extension ?? ""}`;
+    const packedPath = path.join(dir, name);
+    const sourceHash = createHash("sha256");
+    const uploadHash = createHash("sha256");
+    const stages: NodeJS.ReadWriteStream[] = [SqliteSnapshot.tap(sourceHash), createGzip()];
+    if (encryptor) stages.push(encryptor.transform());
+    stages.push(SqliteSnapshot.tap(uploadHash));
+    await pipeline([createReadStream(rawPath), ...stages, createWriteStream(packedPath)]);
+    await rm(rawPath, { force: true });
+    const file: SnapshotFile = {
+      role,
+      name,
+      sizeBytes,
+      sha256: sourceHash.digest("hex"),
+      encoding: "gzip",
+      uploadBytes: (await stat(packedPath)).size,
+      uploadSha256: uploadHash.digest("hex"),
+    };
+    return { file, problems, packedPath };
+  }
+
+  static vacuumInto(source: string, target: string) {
+    const db = new Database(source, { readonly: true });
+    try {
+      db.run(`VACUUM INTO '${target.replaceAll("'", "''")}'`);
+    } finally {
+      db.close();
+    }
+  }
+
+  static integrityProblems(file: string): string[] {
+    const db = new Database(file, { readonly: true });
+    try {
+      const rows = db.query("PRAGMA integrity_check").all() as { integrity_check: string }[];
+      const messages = rows.map((row) => row.integrity_check);
+      return messages.length === 1 && messages[0] === "ok" ? [] : messages;
+    } finally {
+      db.close();
+    }
+  }
+
+  static tap(hash: ReturnType<typeof createHash>) {
+    return new Transform({
+      transform(chunk: Buffer, _encoding, callback) {
+        hash.update(chunk);
+        callback(null, chunk);
+      },
+    });
+  }
+}

package/server/processMetricsCollector.ts

@@ -1,3 +1,4 @@
+import { round } from "akanjs/common";
 import type { AkanMetricsReport } from "akanjs/service";
 import { getTraceSnapshot, isTraceEnabled } from "../signal/trace";
 
@@ -9,11 +10,6 @@ type BunJscHeapStats = {
   protectedObjectCount?: number;
 };
 
-/**
- * Samples event-loop scheduling delay by measuring how late a fixed-interval timer
- * actually fires. The sample window is summarized and reset on each metrics report,
- * so values reflect recent load rather than process lifetime.
- */
 class EventLoopLagMonitor {
   static readonly #maxSamples = 600;
   #timer: ReturnType<typeof setInterval> | null = null;
@@ -34,11 +30,9 @@ class EventLoopLagMonitor {
       if (this.#samples.length < EventLoopLagMonitor.#maxSamples) this.#samples.push(lag);
       else this.#samples[Math.floor(Math.random() * EventLoopLagMonitor.#maxSamples)] = lag;
     }, intervalMs);
-    
     (this.#timer as { unref?: () => void }).unref?.();
   }
 
-  /** Summarize the current window and reset it. */
   snapshotAndReset(): { meanMs: number; p99Ms: number; maxMs: number } | null {
     if (this.#samples.length === 0) return null;
     const sorted = [...this.#samples].sort((a, b) => a - b);
@@ -55,11 +49,6 @@ class EventLoopLagMonitor {
   }
 }
 
-const round = (value: number, digits = 3): number => {
-  const factor = 10 ** digits;
-  return Math.round(value * factor) / factor;
-};
-
 export class ProcessMetricsCollector {
   static readonly #defaultMemoryLogIntervalMs = 60_000;
   static readonly #lagMonitor = new EventLoopLagMonitor();
@@ -69,7 +58,16 @@ export class ProcessMetricsCollector {
     return Number.isFinite(parsed) && parsed > 0 ? parsed : ProcessMetricsCollector.#defaultMemoryLogIntervalMs;
   }
 
-  /** Begin sampling event-loop lag. Idempotent; safe to call from each server role. */
+  /** Calls `report` now and then every AKAN_MEMORY_LOG_INTERVAL_MS; the caller owns the returned timer. */
+  static startReporting(report: () => Promise<void>) {
+    const tick = () => {
+      void report();
+    };
+    tick();
+    return setInterval(tick, ProcessMetricsCollector.parseMemoryLogIntervalMs());
+  }
+
+  /** Idempotent; safe to call from each server role. */
   static startEventLoopLagMonitor(intervalMs = 500): void {
     ProcessMetricsCollector.#lagMonitor.start(intervalMs);
   }
@@ -138,7 +136,7 @@ export class ProcessMetricsCollector {
       ...(metrics.jscHeapSizeBytes !== undefined
         ? [`jscHeap=${ProcessMetricsCollector.formatBytes(metrics.jscHeapSizeBytes)}`]
         : []),
-
+      
       ...(metrics.rscWorkerRssBytes !== undefined
         ? [`rscWorkerRss=${ProcessMetricsCollector.formatBytes(metrics.rscWorkerRssBytes)}`]
         : []),

package/server/proxy/hostBasePathWebProxy.ts

@@ -3,8 +3,7 @@ import path from "node:path";
 import { getEnv } from "akanjs/base";
 import { Logger, resolveSubRouteHosts } from "akanjs/common";
 import type { BaseBuildArtifact } from "../types";
-import { AkanResponse } from "./akanResponse";
-import type { WebProxy } from "./types";
+import { AkanResponse, type WebProxy } from "./types";
 
 export class HostBasePathWebProxy implements WebProxy {
   static readonly refName = "HostBasePathWebProxy";
@@ -43,7 +42,9 @@ export class HostBasePathWebProxy implements WebProxy {
   }
 
   #getBasePath(request: Request): string | null {
-    const host = normalizeHost(request.headers.get("x-forwarded-host") ?? request.headers.get("host"));
+    const host = normalizeHost(
+      request.headers.get("x-forwarded-host")?.split(",")[0]?.trim() ?? request.headers.get("host"),
+    );
     if (!host) return null;
     const domainMap = this.#getDomainMap();
     return domainMap.get(host) ?? null;
@@ -57,10 +58,7 @@ export class HostBasePathWebProxy implements WebProxy {
       basePaths: metadata.basePaths,
       env: process.env.AKAN_SUB_ROUTE_HOSTS,
     });
-    if (ignoredBasePaths.length)
-      this.#logger.warn(
-        `AKAN_SUB_ROUTE_HOSTS names basePaths this build does not serve, ignoring: ${ignoredBasePaths.join(", ")}`,
-      );
+    warnIgnoredSubRouteBasePaths(this.#logger, ignoredBasePaths);
     const map = new Map<string, string>();
     for (const [basePath, domains] of Object.entries(subRoutes)) {
       for (const domain of domains) map.set(normalizeHost(domain), basePath);
@@ -81,20 +79,29 @@ function loadWebRouteMetadata(): Pick<BaseBuildArtifact, "subRoutes" | "basePath
   }
 }
 
-function resolveArtifactDir(): string {
+export function resolveArtifactDir(): string {
   const localArtifactDir = path.join(process.cwd(), ".akan", "artifact");
   if (fs.existsSync(path.join(localArtifactDir, "base-artifact.json"))) return localArtifactDir;
   return path.join(process.cwd(), "apps", getEnv().appName, ".akan", "artifact");
 }
 
-function normalizeHost(host: string | null): string {
+const warnedIgnoredBasePaths = new Set<string>();
+
+export function warnIgnoredSubRouteBasePaths(logger: Logger, ignoredBasePaths: string[]) {
+  const list = ignoredBasePaths.join(", ");
+  if (!list || warnedIgnoredBasePaths.has(list)) return;
+  warnedIgnoredBasePaths.add(list);
+  logger.warn(`AKAN_SUB_ROUTE_HOSTS names basePaths this build does not serve, ignoring: ${list}`);
+}
+
+export function normalizeHost(host: string | null): string {
   return (host ?? "").toLowerCase().replace(/:\d+$/, "");
 }
 
-function getPublicRequestUrl(request: Bun.BunRequest): URL {
+export function getPublicRequestUrl(request: Bun.BunRequest): URL {
   const url = new URL(request.url);
-  const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host");
-  const proto = request.headers.get("x-forwarded-proto");
+  const host = request.headers.get("x-forwarded-host")?.split(",")[0]?.trim() ?? request.headers.get("host");
+  const proto = request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
   if (host) url.host = host;
   if (host && !host.includes(":")) url.port = "";
   if (proto) url.protocol = proto.endsWith(":") ? proto : `${proto}:`;
@@ -114,6 +121,6 @@ function toProxyRequestUrl(requestUrl: URL, targetUrl: URL): URL {
   return rewritten;
 }
 
-function isInternalProxyRequest(requestUrl: URL): boolean {
+export function isInternalProxyRequest(requestUrl: URL): boolean {
   return requestUrl.pathname === "/__rsc";
 }

package/server/proxy/index.ts

@@ -1,5 +1,3 @@
-export { AkanResponse } from "./akanResponse";
-export { copyBunRequestFields } from "./bunRequestFields";
 export { HostBasePathWebProxy } from "./hostBasePathWebProxy";
 export { LocaleWebProxy } from "./localeWebProxy";
 export type {
@@ -12,4 +10,5 @@ export type {
   WebProxyReturn,
   WebProxyRunResult,
 } from "./types";
-export { WebProxyRunner } from "./webProxyRunner";
+export { AkanResponse } from "./types";
+export { copyBunRequestFields, WebProxyRunner } from "./webProxyRunner";

package/server/proxy/localeWebProxy.ts

@@ -1,7 +1,7 @@
 import { getApiPrefix } from "akanjs/base";
 import { parseAkanI18nEnv } from "akanjs/common";
-import { AkanResponse } from "./akanResponse";
-import type { WebProxy } from "./types";
+import { getPublicRequestUrl, isInternalProxyRequest } from "./hostBasePathWebProxy";
+import { AkanResponse, type WebProxy } from "./types";
 
 function getLocale(request: Bun.BunRequest): string {
   const i18n = parseAkanI18nEnv();
@@ -74,25 +74,11 @@ export class LocaleWebProxy implements WebProxy {
 }
 
 function getProxyTargetUrl(requestUrl: URL): URL {
-  if (requestUrl.pathname !== "/__rsc") return requestUrl;
+  if (!isInternalProxyRequest(requestUrl)) return requestUrl;
   const target = requestUrl.searchParams.get("url");
   return target ? new URL(target, requestUrl.origin) : requestUrl;
 }
 
-function getPublicRequestUrl(request: Bun.BunRequest): URL {
-  const url = new URL(request.url);
-  const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host");
-  const proto = request.headers.get("x-forwarded-proto");
-  if (host) url.host = host;
-  if (host && !host.includes(":")) url.port = "";
-  if (proto) url.protocol = proto.endsWith(":") ? proto : `${proto}:`;
-  return url;
-}
-
-function isInternalProxyRequest(requestUrl: URL): boolean {
-  return requestUrl.pathname === "/__rsc";
-}
-
 function isWellKnownRequest(pathname: string): boolean {
   return pathname === "/.well-known" || pathname.startsWith("/.well-known/");
 }

package/server/proxy/types.ts

@@ -39,3 +39,17 @@ export interface WebProxyRunResult {
   request: Request;
   response?: Response;
 }
+
+export class AkanResponse {
+  static next(init: WebProxyNextInit = {}): WebProxyResult {
+    return { [WEB_PROXY_RESULT]: true, type: "next", request: init.request };
+  }
+
+  static redirect(url: string | URL, status = 307): Response {
+    return Response.redirect(url, status);
+  }
+
+  static rewrite(url: string | URL, init: WebProxyNextInit = {}): WebProxyResult {
+    return { [WEB_PROXY_RESULT]: true, type: "rewrite", url, request: init.request };
+  }
+}

package/server/proxy/webProxyRunner.ts

@@ -1,4 +1,3 @@
-import { copyBunRequestFields } from "./bunRequestFields";
 import {
   WEB_PROXY_RESULT,
   type WebProxy,
@@ -9,6 +8,19 @@ import {
   type WebProxyRunResult,
 } from "./types";
 
+export const copyBunRequestFields = (target: Request, source: Request): Request => {
+  const sourceWithParams = source as Request & { params?: Record<string, string> };
+  if (sourceWithParams.params) {
+    Object.defineProperty(target, "params", {
+      configurable: true,
+      enumerable: true,
+      value: sourceWithParams.params,
+      writable: true,
+    });
+  }
+  return target;
+};
+
 export class WebProxyRunner {
   readonly #proxies: Array<{ proxy: WebProxy; matcher?: WebProxyMatcher }>;