ex-brain 0.1.1 → 0.2.0

package/src/db/client.ts

@@ -6,6 +6,7 @@ import type { ResolvedSettings } from "../settings";
 import { createBrainEmbeddingFunction } from "../ai/embed-factory";
 import { DEFAULT_DB_NAME, PAGES_COLLECTION } from "../config";
 import { SQL_SCHEMA } from "./schema";
+import { DbError, wrapDbError, DbErrorCategory } from "./errors";
 
 function useRemoteSeekdb(): boolean {
   return Boolean(process.env.EBRAIN_SEEKDB_HOST?.trim());
@@ -15,30 +16,127 @@ function seekdbPassword(): string {
   return process.env.EBRAIN_SEEKDB_PASSWORD ?? process.env.SEEKDB_PASSWORD ?? "";
 }
 
+const MAX_RETRY_ATTEMPTS = 3;
+const RETRY_DELAY_MS = 1000;
+const RETRY_BACKOFF_FACTOR = 2;
+
 export class BrainDb {
+  private _isConnected = false;
+  private _lastConnectedAt: Date | null = null;
+
   private constructor(
     public readonly dbPath: string,
     public readonly client: SeekdbClient,
     public readonly pagesCollection: Collection,
   ) {}
 
-  static async connect(dbPath: string, settings?: ResolvedSettings): Promise<BrainDb> {
-    const client = settings?.remote
-      ? await BrainDb.openRemoteClient(settings.remote)
-      : useRemoteSeekdb()
-        ? await BrainDb.openRemoteClientFromEnv()
-        : await BrainDb.openEmbeddedClient(dbPath);
-
-    for (const sql of SQL_SCHEMA) {
-      await client.execute(sql);
+  /**
+   * Check if the database is currently connected.
+   */
+  get isConnected(): boolean {
+    return this._isConnected;
+  }
+
+  /**
+   * Get the last successful connection timestamp.
+   */
+  get lastConnectedAt(): Date | null {
+    return this._lastConnectedAt;
+  }
+
+  /**
+   * Execute with automatic reconnection on failure.
+   */
+  async executeWithRetry<T>(
+    operation: () => Promise<T>,
+    operationName: string,
+  ): Promise<T> {
+    let lastError: DbError | null = null;
+
+    for (let attempt = 1; attempt <= MAX_RETRY_ATTEMPTS; attempt++) {
+      try {
+        const result = await operation();
+        if (!this._isConnected) {
+          this._isConnected = true;
+          this._lastConnectedAt = new Date();
+        }
+        return result;
+      } catch (error) {
+        const wrappedError = wrapDbError(error, operationName as any);
+        lastError = wrappedError;
+
+        // Only retry on connection/timeout errors
+        if (!wrappedError.isRetryable() || attempt === MAX_RETRY_ATTEMPTS) {
+          throw wrappedError;
+        }
+
+        // Check if it's a connection error that might be resolved by reconnecting
+        if (wrappedError.category === DbErrorCategory.CONNECTION) {
+          console.warn(
+            `\x1b[33m[DB]\x1b[0m Connection error on attempt ${attempt}/${MAX_RETRY_ATTEMPTS}, retrying...`,
+          );
+          await this.attemptReconnect();
+        } else {
+          // Exponential backoff for other retryable errors
+          const delay = RETRY_DELAY_MS * Math.pow(RETRY_BACKOFF_FACTOR, attempt - 1);
+          console.warn(
+            `\x1b[33m[DB]\x1b[0m ${operationName} failed on attempt ${attempt}/${MAX_RETRY_ATTEMPTS}, retrying in ${delay}ms...`,
+          );
+          await this.sleep(delay);
+        }
+      }
     }
 
-    const pagesCollection = await client.getOrCreateCollection({
-      name: PAGES_COLLECTION,
-      embeddingFunction: createBrainEmbeddingFunction(settings?.embed),
-    });
+    throw lastError;
+  }
+
+  private async attemptReconnect(): Promise<void> {
+    try {
+      // Test if we can execute a simple query
+      await this.client.execute("SELECT 1");
+      this._isConnected = true;
+      this._lastConnectedAt = new Date();
+      console.error("\x1b[32m[DB] Reconnected successfully\x1b[0m");
+    } catch {
+      // Connection still failed, will retry on next operation
+      this._isConnected = false;
+    }
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  static async connect(dbPath: string, settings?: ResolvedSettings): Promise<BrainDb> {
+    try {
+      const client = settings?.remote
+        ? await BrainDb.openRemoteClient(settings.remote)
+        : useRemoteSeekdb()
+          ? await BrainDb.openRemoteClientFromEnv()
+          : await BrainDb.openEmbeddedClient(dbPath);
+
+      // Test connection with a simple query
+      await client.execute("SELECT 1");
 
-    return new BrainDb(dbPath, client, pagesCollection);
+      for (const sql of SQL_SCHEMA) {
+        await client.execute(sql);
+      }
+
+      const pagesCollection = await client.getOrCreateCollection({
+        name: PAGES_COLLECTION,
+        embeddingFunction: createBrainEmbeddingFunction(settings?.embed),
+      });
+
+      const db = new BrainDb(dbPath, client, pagesCollection);
+      db._isConnected = true;
+      db._lastConnectedAt = new Date();
+      console.error("\x1b[32m[DB] Connected successfully\x1b[0m");
+      return db;
+    } catch (error) {
+      const wrappedError = wrapDbError(error, "connect");
+      console.error(`\x1b[31m[DB]\x1b[0m Connection failed:`, wrappedError.toJSON());
+      throw wrappedError;
+    }
   }
 
   private static async openEmbeddedClient(dbPath: string): Promise<SeekdbClient> {
@@ -96,6 +194,14 @@ export class BrainDb {
   }
 
   async close(): Promise<void> {
-    await this.client.close();
+    try {
+      await this.client.close();
+      this._isConnected = false;
+      console.error("\x1b[32m[DB] Disconnected\x1b[0m");
+    } catch (error) {
+      const wrappedError = wrapDbError(error, "close");
+      console.error(`\x1b[31m[DB]\x1b[0m Error closing connection:`, wrappedError.message);
+      // Don't throw on close errors - best effort
+    }
   }
 }

package/src/db/errors.ts

@@ -0,0 +1,178 @@
+/**
+ * Database error types and utilities.
+ * Provides unified error handling for all database operations.
+ */
+
+/**
+ * Database error categories
+ */
+export const DbErrorCategory = {
+  CONNECTION: "CONNECTION",
+  QUERY: "QUERY",
+  SCHEMA: "SCHEMA",
+  VALIDATION: "VALIDATION",
+  NOT_FOUND: "NOT_FOUND",
+  CONSTRAINT: "CONSTRAINT",
+  TIMEOUT: "TIMEOUT",
+  UNKNOWN: "UNKNOWN",
+} as const;
+
+export type DbErrorCategory = (typeof DbErrorCategory)[keyof typeof DbErrorCategory];
+
+/**
+ * Database operation types for error context
+ */
+export type DbOperation =
+  | "getPage"
+  | "putPage"
+  | "listPages"
+  | "deletePage"
+  | "search"
+  | "query"
+  | "syncPageToSearch"
+  | "syncPagesToSearch"
+  | "embedAll"
+  | "link"
+  | "unlink"
+  | "timeline"
+  | "timelineAdd"
+  | "timelineAddBatch"
+  | "timelineDelete"
+  | "timelineUpdate"
+  | "timelineGlobal"
+  | "tags"
+  | "tag"
+  | "untag"
+  | "readRaw"
+  | "writeRaw"
+  | "backlinks"
+  | "allSlugs"
+  | "stats"
+  | "findSimilarSlug"
+  | "ensureEntityPage"
+  | "compilePage"
+  | "extractAndAddTimeline"
+  | "ingestContent"
+  | "init"
+  | "connect"
+  | "close";
+
+/**
+ * Unified database error class
+ */
+export class DbError extends Error {
+  constructor(
+    message: string,
+    public readonly category: DbErrorCategory,
+    public readonly operation: DbOperation,
+    public readonly dbCause?: unknown,
+    public readonly retryable: boolean = false,
+  ) {
+    super(message);
+    this.name = "DbError";
+    // Maintains proper stack trace in V8 (Node.js)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, DbError);
+    }
+  }
+
+  /**
+   * Check if this error is retryable
+   */
+  isRetryable(): boolean {
+    return this.retryable;
+  }
+
+  /**
+   * Convert to JSON for logging
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      message: this.message,
+      category: this.category,
+      operation: this.operation,
+      retryable: this.retryable,
+      dbCause: this.dbCause instanceof Error
+        ? { name: this.dbCause.name, message: this.dbCause.message }
+        : this.dbCause,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Create database error from any caught exception
+ */
+export function wrapDbError(
+  error: unknown,
+  operation: DbOperation,
+  context?: Record<string, unknown>,
+): DbError {
+  const message = error instanceof Error ? error.message : String(error);
+  const cause = error instanceof Error ? error : undefined;
+
+  // Determine error category and retryability based on error message/type
+  let category: DbErrorCategory = "UNKNOWN";
+  let retryable = false;
+
+  const errorStr = message.toLowerCase();
+
+  if (
+    errorStr.includes("connect") ||
+    errorStr.includes("connection") ||
+    errorStr.includes("econnrefused") ||
+    errorStr.includes("etimedout") ||
+    errorStr.includes("network")
+  ) {
+    category = "CONNECTION";
+    retryable = true;
+  } else if (
+    errorStr.includes("timeout") ||
+    errorStr.includes("timed out")
+  ) {
+    category = "TIMEOUT";
+    retryable = true;
+  } else if (
+    errorStr.includes("not found") ||
+    errorStr.includes("no such table") ||
+    errorStr.includes("no such database")
+  ) {
+    category = "NOT_FOUND";
+  } else if (
+    errorStr.includes("constraint") ||
+    errorStr.includes("duplicate") ||
+    errorStr.includes("unique")
+  ) {
+    category = "CONSTRAINT";
+  } else if (
+    errorStr.includes("syntax") ||
+    errorStr.includes("parse") ||
+    errorStr.includes("invalid")
+  ) {
+    category = "VALIDATION";
+  } else if (
+    errorStr.includes("schema") ||
+    errorStr.includes("column")
+  ) {
+    category = "SCHEMA";
+  } else {
+    category = "QUERY";
+  }
+
+  const fullMessage = context
+    ? `${operation} failed: ${message} ${JSON.stringify(context)}`
+    : `${operation} failed: ${message}`;
+
+  return new DbError(fullMessage, category, operation, cause, retryable);
+}
+
+/**
+ * Log database error with context
+ */
+export function logDbError(
+  error: DbError,
+  logger: { error: (msg: string, meta?: Record<string, unknown>) => void } = console,
+): void {
+  logger.error("[DB Error]", error.toJSON());
+}

package/src/db/schema.ts

@@ -24,6 +24,7 @@ export const SQL_SCHEMA = [
     source VARCHAR(128) NOT NULL,
     summary VARCHAR(1024) NOT NULL,
     detail MEDIUMTEXT NOT NULL,
+    importance INT NOT NULL DEFAULT 3,
     created_at VARCHAR(64) NOT NULL
   )`,
   `CREATE TABLE IF NOT EXISTS raw_data (