@push.rocks/smartdb 1.0.1

package/ts/ts_smartdb/engine/SessionEngine.ts

@@ -0,0 +1,292 @@
+import * as plugins from '../plugins.js';
+import type { TransactionEngine } from './TransactionEngine.js';
+
+/**
+ * Session state
+ */
+export interface ISession {
+  /** Session ID (UUID) */
+  id: string;
+  /** Timestamp when the session was created */
+  createdAt: number;
+  /** Timestamp of the last activity */
+  lastActivityAt: number;
+  /** Current transaction ID if any */
+  txnId?: string;
+  /** Transaction number for ordering */
+  txnNumber?: number;
+  /** Whether the session is in a transaction */
+  inTransaction: boolean;
+  /** Session metadata */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Session engine options
+ */
+export interface ISessionEngineOptions {
+  /** Session timeout in milliseconds (default: 30 minutes) */
+  sessionTimeoutMs?: number;
+  /** Interval to check for expired sessions in ms (default: 60 seconds) */
+  cleanupIntervalMs?: number;
+}
+
+/**
+ * Session engine for managing client sessions
+ * - Tracks session lifecycle (create, touch, end)
+ * - Links sessions to transactions
+ * - Auto-aborts transactions on session expiry
+ */
+export class SessionEngine {
+  private sessions: Map<string, ISession> = new Map();
+  private sessionTimeoutMs: number;
+  private cleanupInterval?: ReturnType<typeof setInterval>;
+  private transactionEngine?: TransactionEngine;
+
+  constructor(options?: ISessionEngineOptions) {
+    this.sessionTimeoutMs = options?.sessionTimeoutMs ?? 30 * 60 * 1000; // 30 minutes default
+    const cleanupIntervalMs = options?.cleanupIntervalMs ?? 60 * 1000; // 1 minute default
+
+    // Start cleanup interval
+    this.cleanupInterval = setInterval(() => {
+      this.cleanupExpiredSessions();
+    }, cleanupIntervalMs);
+  }
+
+  /**
+   * Set the transaction engine to use for auto-abort
+   */
+  setTransactionEngine(engine: TransactionEngine): void {
+    this.transactionEngine = engine;
+  }
+
+  /**
+   * Start a new session
+   */
+  startSession(sessionId?: string, metadata?: Record<string, any>): ISession {
+    const id = sessionId ?? new plugins.bson.UUID().toHexString();
+    const now = Date.now();
+
+    const session: ISession = {
+      id,
+      createdAt: now,
+      lastActivityAt: now,
+      inTransaction: false,
+      metadata,
+    };
+
+    this.sessions.set(id, session);
+    return session;
+  }
+
+  /**
+   * Get a session by ID
+   */
+  getSession(sessionId: string): ISession | undefined {
+    const session = this.sessions.get(sessionId);
+    if (session && this.isSessionExpired(session)) {
+      // Session expired, clean it up
+      this.endSession(sessionId);
+      return undefined;
+    }
+    return session;
+  }
+
+  /**
+   * Touch a session to update last activity time
+   */
+  touchSession(sessionId: string): boolean {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+
+    if (this.isSessionExpired(session)) {
+      this.endSession(sessionId);
+      return false;
+    }
+
+    session.lastActivityAt = Date.now();
+    return true;
+  }
+
+  /**
+   * End a session explicitly
+   * This will also abort any active transaction
+   */
+  async endSession(sessionId: string): Promise<boolean> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+
+    // If session has an active transaction, abort it
+    if (session.inTransaction && session.txnId && this.transactionEngine) {
+      try {
+        await this.transactionEngine.abortTransaction(session.txnId);
+      } catch (e) {
+        // Ignore abort errors during cleanup
+      }
+    }
+
+    this.sessions.delete(sessionId);
+    return true;
+  }
+
+  /**
+   * Start a transaction in a session
+   */
+  startTransaction(sessionId: string, txnId: string, txnNumber?: number): boolean {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+
+    if (this.isSessionExpired(session)) {
+      this.endSession(sessionId);
+      return false;
+    }
+
+    session.txnId = txnId;
+    session.txnNumber = txnNumber;
+    session.inTransaction = true;
+    session.lastActivityAt = Date.now();
+
+    return true;
+  }
+
+  /**
+   * End a transaction in a session (commit or abort)
+   */
+  endTransaction(sessionId: string): boolean {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+
+    session.txnId = undefined;
+    session.txnNumber = undefined;
+    session.inTransaction = false;
+    session.lastActivityAt = Date.now();
+
+    return true;
+  }
+
+  /**
+   * Get transaction ID for a session
+   */
+  getTransactionId(sessionId: string): string | undefined {
+    const session = this.sessions.get(sessionId);
+    return session?.txnId;
+  }
+
+  /**
+   * Check if session is in a transaction
+   */
+  isInTransaction(sessionId: string): boolean {
+    const session = this.sessions.get(sessionId);
+    return session?.inTransaction ?? false;
+  }
+
+  /**
+   * Check if a session is expired
+   */
+  isSessionExpired(session: ISession): boolean {
+    return Date.now() - session.lastActivityAt > this.sessionTimeoutMs;
+  }
+
+  /**
+   * Cleanup expired sessions
+   * This is called periodically by the cleanup interval
+   */
+  private async cleanupExpiredSessions(): Promise<void> {
+    const expiredSessions: string[] = [];
+
+    for (const [id, session] of this.sessions) {
+      if (this.isSessionExpired(session)) {
+        expiredSessions.push(id);
+      }
+    }
+
+    // End all expired sessions (this will also abort their transactions)
+    for (const sessionId of expiredSessions) {
+      await this.endSession(sessionId);
+    }
+  }
+
+  /**
+   * Get all active sessions
+   */
+  listSessions(): ISession[] {
+    const activeSessions: ISession[] = [];
+    for (const session of this.sessions.values()) {
+      if (!this.isSessionExpired(session)) {
+        activeSessions.push(session);
+      }
+    }
+    return activeSessions;
+  }
+
+  /**
+   * Get session count
+   */
+  getSessionCount(): number {
+    return this.sessions.size;
+  }
+
+  /**
+   * Get sessions with active transactions
+   */
+  getSessionsWithTransactions(): ISession[] {
+    return this.listSessions().filter(s => s.inTransaction);
+  }
+
+  /**
+   * Refresh session timeout
+   */
+  refreshSession(sessionId: string): boolean {
+    return this.touchSession(sessionId);
+  }
+
+  /**
+   * Close the session engine and cleanup
+   */
+  close(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = undefined;
+    }
+
+    // Clear all sessions
+    this.sessions.clear();
+  }
+
+  /**
+   * Get or create a session for a given session ID
+   * Useful for handling MongoDB driver session requests
+   */
+  getOrCreateSession(sessionId: string): ISession {
+    let session = this.getSession(sessionId);
+    if (!session) {
+      session = this.startSession(sessionId);
+    } else {
+      this.touchSession(sessionId);
+    }
+    return session;
+  }
+
+  /**
+   * Extract session ID from MongoDB lsid (logical session ID)
+   */
+  static extractSessionId(lsid: any): string | undefined {
+    if (!lsid) return undefined;
+
+    // MongoDB session ID format: { id: UUID }
+    if (lsid.id) {
+      if (lsid.id instanceof plugins.bson.UUID) {
+        return lsid.id.toHexString();
+      }
+      if (typeof lsid.id === 'string') {
+        return lsid.id;
+      }
+      if (lsid.id.$binary?.base64) {
+        // Binary UUID format
+        return Buffer.from(lsid.id.$binary.base64, 'base64').toString('hex');
+      }
+    }
+
+    return undefined;
+  }
+}

package/ts/ts_smartdb/engine/TransactionEngine.ts

@@ -0,0 +1,351 @@
+import * as plugins from '../plugins.js';
+import type { IStorageAdapter } from '../storage/IStorageAdapter.js';
+import type { Document, IStoredDocument, ITransactionOptions } from '../types/interfaces.js';
+import { SmartdbTransactionError, SmartdbWriteConflictError } from '../errors/SmartdbErrors.js';
+
+/**
+ * Transaction state
+ */
+export interface ITransactionState {
+  id: string;
+  sessionId: string;
+  startTime: plugins.bson.Timestamp;
+  status: 'active' | 'committed' | 'aborted';
+  readSet: Map<string, Set<string>>; // ns -> document _ids read
+  writeSet: Map<string, Map<string, { op: 'insert' | 'update' | 'delete'; doc?: IStoredDocument; originalDoc?: IStoredDocument }>>; // ns -> _id -> operation
+  snapshots: Map<string, IStoredDocument[]>; // ns -> snapshot of documents
+}
+
+/**
+ * Transaction engine for ACID transaction support
+ */
+export class TransactionEngine {
+  private storage: IStorageAdapter;
+  private transactions: Map<string, ITransactionState> = new Map();
+  private txnCounter = 0;
+
+  constructor(storage: IStorageAdapter) {
+    this.storage = storage;
+  }
+
+  /**
+   * Start a new transaction
+   */
+  startTransaction(sessionId: string, options?: ITransactionOptions): string {
+    this.txnCounter++;
+    const txnId = `txn_${sessionId}_${this.txnCounter}`;
+
+    const transaction: ITransactionState = {
+      id: txnId,
+      sessionId,
+      startTime: new plugins.bson.Timestamp({ t: Math.floor(Date.now() / 1000), i: this.txnCounter }),
+      status: 'active',
+      readSet: new Map(),
+      writeSet: new Map(),
+      snapshots: new Map(),
+    };
+
+    this.transactions.set(txnId, transaction);
+    return txnId;
+  }
+
+  /**
+   * Get a transaction by ID
+   */
+  getTransaction(txnId: string): ITransactionState | undefined {
+    return this.transactions.get(txnId);
+  }
+
+  /**
+   * Check if a transaction is active
+   */
+  isActive(txnId: string): boolean {
+    const txn = this.transactions.get(txnId);
+    return txn?.status === 'active';
+  }
+
+  /**
+   * Get or create a snapshot for a namespace
+   */
+  async getSnapshot(txnId: string, dbName: string, collName: string): Promise<IStoredDocument[]> {
+    const txn = this.transactions.get(txnId);
+    if (!txn || txn.status !== 'active') {
+      throw new SmartdbTransactionError('Transaction is not active');
+    }
+
+    const ns = `${dbName}.${collName}`;
+    if (!txn.snapshots.has(ns)) {
+      const snapshot = await this.storage.createSnapshot(dbName, collName);
+      txn.snapshots.set(ns, snapshot);
+    }
+
+    // Apply transaction writes to snapshot
+    const snapshot = txn.snapshots.get(ns)!;
+    const writes = txn.writeSet.get(ns);
+
+    if (!writes) {
+      return snapshot;
+    }
+
+    // Create a modified view of the snapshot
+    const result: IStoredDocument[] = [];
+    const deletedIds = new Set<string>();
+    const modifiedDocs = new Map<string, IStoredDocument>();
+
+    for (const [idStr, write] of writes) {
+      if (write.op === 'delete') {
+        deletedIds.add(idStr);
+      } else if (write.op === 'update' || write.op === 'insert') {
+        if (write.doc) {
+          modifiedDocs.set(idStr, write.doc);
+        }
+      }
+    }
+
+    // Add existing documents (not deleted, possibly modified)
+    for (const doc of snapshot) {
+      const idStr = doc._id.toHexString();
+      if (deletedIds.has(idStr)) {
+        continue;
+      }
+      if (modifiedDocs.has(idStr)) {
+        result.push(modifiedDocs.get(idStr)!);
+        modifiedDocs.delete(idStr);
+      } else {
+        result.push(doc);
+      }
+    }
+
+    // Add new documents (inserts)
+    for (const doc of modifiedDocs.values()) {
+      result.push(doc);
+    }
+
+    return result;
+  }
+
+  /**
+   * Record a read operation
+   */
+  recordRead(txnId: string, dbName: string, collName: string, docIds: string[]): void {
+    const txn = this.transactions.get(txnId);
+    if (!txn || txn.status !== 'active') return;
+
+    const ns = `${dbName}.${collName}`;
+    if (!txn.readSet.has(ns)) {
+      txn.readSet.set(ns, new Set());
+    }
+
+    const readSet = txn.readSet.get(ns)!;
+    for (const id of docIds) {
+      readSet.add(id);
+    }
+  }
+
+  /**
+   * Record a write operation (insert)
+   */
+  recordInsert(txnId: string, dbName: string, collName: string, doc: IStoredDocument): void {
+    const txn = this.transactions.get(txnId);
+    if (!txn || txn.status !== 'active') {
+      throw new SmartdbTransactionError('Transaction is not active');
+    }
+
+    const ns = `${dbName}.${collName}`;
+    if (!txn.writeSet.has(ns)) {
+      txn.writeSet.set(ns, new Map());
+    }
+
+    txn.writeSet.get(ns)!.set(doc._id.toHexString(), {
+      op: 'insert',
+      doc,
+    });
+  }
+
+  /**
+   * Record a write operation (update)
+   */
+  recordUpdate(
+    txnId: string,
+    dbName: string,
+    collName: string,
+    originalDoc: IStoredDocument,
+    updatedDoc: IStoredDocument
+  ): void {
+    const txn = this.transactions.get(txnId);
+    if (!txn || txn.status !== 'active') {
+      throw new SmartdbTransactionError('Transaction is not active');
+    }
+
+    const ns = `${dbName}.${collName}`;
+    if (!txn.writeSet.has(ns)) {
+      txn.writeSet.set(ns, new Map());
+    }
+
+    const idStr = originalDoc._id.toHexString();
+    const existing = txn.writeSet.get(ns)!.get(idStr);
+
+    // If we already have a write for this document, update it
+    if (existing) {
+      existing.doc = updatedDoc;
+    } else {
+      txn.writeSet.get(ns)!.set(idStr, {
+        op: 'update',
+        doc: updatedDoc,
+        originalDoc,
+      });
+    }
+  }
+
+  /**
+   * Record a write operation (delete)
+   */
+  recordDelete(txnId: string, dbName: string, collName: string, doc: IStoredDocument): void {
+    const txn = this.transactions.get(txnId);
+    if (!txn || txn.status !== 'active') {
+      throw new SmartdbTransactionError('Transaction is not active');
+    }
+
+    const ns = `${dbName}.${collName}`;
+    if (!txn.writeSet.has(ns)) {
+      txn.writeSet.set(ns, new Map());
+    }
+
+    const idStr = doc._id.toHexString();
+    const existing = txn.writeSet.get(ns)!.get(idStr);
+
+    if (existing && existing.op === 'insert') {
+      // If we inserted and then deleted, just remove the write
+      txn.writeSet.get(ns)!.delete(idStr);
+    } else {
+      txn.writeSet.get(ns)!.set(idStr, {
+        op: 'delete',
+        originalDoc: doc,
+      });
+    }
+  }
+
+  /**
+   * Commit a transaction
+   */
+  async commitTransaction(txnId: string): Promise<void> {
+    const txn = this.transactions.get(txnId);
+    if (!txn) {
+      throw new SmartdbTransactionError('Transaction not found');
+    }
+    if (txn.status !== 'active') {
+      throw new SmartdbTransactionError(`Cannot commit transaction in state: ${txn.status}`);
+    }
+
+    // Check for write conflicts
+    for (const [ns, writes] of txn.writeSet) {
+      const [dbName, collName] = ns.split('.');
+      const ids = Array.from(writes.keys()).map(id => new plugins.bson.ObjectId(id));
+
+      const hasConflicts = await this.storage.hasConflicts(dbName, collName, ids, txn.startTime);
+      if (hasConflicts) {
+        txn.status = 'aborted';
+        throw new SmartdbWriteConflictError();
+      }
+    }
+
+    // Apply all writes
+    for (const [ns, writes] of txn.writeSet) {
+      const [dbName, collName] = ns.split('.');
+
+      for (const [idStr, write] of writes) {
+        switch (write.op) {
+          case 'insert':
+            if (write.doc) {
+              await this.storage.insertOne(dbName, collName, write.doc);
+            }
+            break;
+          case 'update':
+            if (write.doc) {
+              await this.storage.updateById(dbName, collName, new plugins.bson.ObjectId(idStr), write.doc);
+            }
+            break;
+          case 'delete':
+            await this.storage.deleteById(dbName, collName, new plugins.bson.ObjectId(idStr));
+            break;
+        }
+      }
+    }
+
+    txn.status = 'committed';
+  }
+
+  /**
+   * Abort a transaction
+   */
+  async abortTransaction(txnId: string): Promise<void> {
+    const txn = this.transactions.get(txnId);
+    if (!txn) {
+      throw new SmartdbTransactionError('Transaction not found');
+    }
+    if (txn.status !== 'active') {
+      // Already committed or aborted, just return
+      return;
+    }
+
+    // Simply discard all buffered writes
+    txn.writeSet.clear();
+    txn.readSet.clear();
+    txn.snapshots.clear();
+    txn.status = 'aborted';
+  }
+
+  /**
+   * End a transaction (cleanup)
+   */
+  endTransaction(txnId: string): void {
+    this.transactions.delete(txnId);
+  }
+
+  /**
+   * Get all pending writes for a namespace
+   */
+  getPendingWrites(txnId: string, dbName: string, collName: string): Map<string, { op: 'insert' | 'update' | 'delete'; doc?: IStoredDocument }> | undefined {
+    const txn = this.transactions.get(txnId);
+    if (!txn) return undefined;
+
+    const ns = `${dbName}.${collName}`;
+    return txn.writeSet.get(ns);
+  }
+
+  /**
+   * Execute a callback within a transaction, with automatic retry on conflict
+   */
+  async withTransaction<T>(
+    sessionId: string,
+    callback: (txnId: string) => Promise<T>,
+    options?: ITransactionOptions & { maxRetries?: number }
+  ): Promise<T> {
+    const maxRetries = options?.maxRetries ?? 3;
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      const txnId = this.startTransaction(sessionId, options);
+
+      try {
+        const result = await callback(txnId);
+        await this.commitTransaction(txnId);
+        this.endTransaction(txnId);
+        return result;
+      } catch (error: any) {
+        await this.abortTransaction(txnId);
+        this.endTransaction(txnId);
+
+        if (error instanceof SmartdbWriteConflictError && attempt < maxRetries - 1) {
+          // Retry on write conflict
+          lastError = error;
+          continue;
+        }
+
+        throw error;
+      }
+    }
+
+    throw lastError || new SmartdbTransactionError('Transaction failed after max retries');
+  }
+}