@dotdo/postgres 0.1.0

package/src/worker/session-manager.ts

@@ -0,0 +1,732 @@
+/**
+ * Session Manager
+ *
+ * Task: postgres-9i9 - Connection/session management optimizations
+ *
+ * Provides efficient session management with:
+ * - Session state tracking
+ * - Transaction context management
+ * - Query history for debugging
+ * - Session-level configuration
+ * - Idle session cleanup
+ */
+
+import type { QueryRequest, QueryResponse, IsolationLevel } from './types'
+
+// Re-export for external use
+export type { QueryResultRow } from './types'
+import { SessionError, TransactionError } from './errors'
+
+/**
+ * Session state
+ */
+export type SessionState = 'idle' | 'active' | 'transaction' | 'error' | 'closed'
+
+/**
+ * Transaction state
+ */
+export interface TransactionState {
+  /** Transaction ID */
+  id: string
+  /** Isolation level */
+  isolationLevel: IsolationLevel
+  /** Started timestamp */
+  startedAt: number
+  /** Number of queries executed in transaction */
+  queryCount: number
+  /** Savepoints created */
+  savepoints: string[]
+}
+
+/**
+ * Query history entry
+ */
+export interface QueryHistoryEntry {
+  /** SQL query */
+  sql: string
+  /** Parameters */
+  params?: unknown[] | undefined
+  /** Execution duration */
+  durationMs: number
+  /** Row count */
+  rowCount: number
+  /** Timestamp */
+  timestamp: number
+  /** Success/failure */
+  success: boolean
+  /** Error message if failed */
+  error?: string | undefined
+}
+
+/**
+ * Session configuration
+ */
+export interface SessionConfig {
+  /** Session ID */
+  id: string
+  /** User ID (optional) */
+  userId?: string | undefined
+  /** Database name */
+  database: string
+  /** Preserve case in identifiers */
+  preserveCase?: boolean | undefined
+  /** Default isolation level */
+  defaultIsolationLevel?: IsolationLevel | undefined
+  /** Query timeout in ms (0 = no timeout) */
+  queryTimeoutMs?: number | undefined
+  /** Max queries in history (0 = disabled) */
+  maxHistorySize?: number | undefined
+  /** Session timeout for idle cleanup (ms) */
+  idleTimeoutMs?: number | undefined
+}
+
+/**
+ * Session statistics
+ */
+export interface SessionStats {
+  /** Total queries executed */
+  totalQueries: number
+  /** Successful queries */
+  successfulQueries: number
+  /** Failed queries */
+  failedQueries: number
+  /** Total execution time */
+  totalExecutionMs: number
+  /** Average execution time */
+  avgExecutionMs: number
+  /** Transactions started */
+  transactionsStarted: number
+  /** Transactions committed */
+  transactionsCommitted: number
+  /** Transactions rolled back */
+  transactionsRolledBack: number
+  /** Session uptime */
+  uptimeMs: number
+  /** Time since last activity */
+  idleTimeMs: number
+}
+
+/**
+ * Session event types
+ */
+export type SessionEventType =
+  | 'query_start'
+  | 'query_complete'
+  | 'query_error'
+  | 'transaction_begin'
+  | 'transaction_commit'
+  | 'transaction_rollback'
+  | 'session_idle'
+  | 'session_close'
+
+/**
+ * Session event
+ */
+export interface SessionEvent {
+  type: SessionEventType
+  sessionId: string
+  timestamp: number
+  data?: Record<string, unknown> | undefined
+}
+
+/**
+ * Session event listener
+ */
+export type SessionEventListener = (event: SessionEvent) => void
+
+/**
+ * Generate a unique session ID
+ */
+function generateSessionId(): string {
+  return `sess-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+/**
+ * Generate a unique transaction ID
+ */
+function generateTransactionId(): string {
+  return `txn-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+/**
+ * Session Manager
+ *
+ * Manages database sessions with:
+ * - State tracking
+ * - Transaction management
+ * - Query history
+ * - Statistics collection
+ */
+export class Session {
+  readonly id: string
+  readonly config: Required<SessionConfig>
+  readonly createdAt: number
+
+  private state: SessionState = 'idle'
+  private transaction: TransactionState | null = null
+  private history: QueryHistoryEntry[] = []
+  private stats: {
+    totalQueries: number
+    successfulQueries: number
+    failedQueries: number
+    totalExecutionMs: number
+    transactionsStarted: number
+    transactionsCommitted: number
+    transactionsRolledBack: number
+  }
+  private lastActivityAt: number
+  private eventListeners: SessionEventListener[] = []
+
+  constructor(config: Partial<SessionConfig> = {}) {
+    this.id = config.id ?? generateSessionId()
+    this.config = {
+      id: this.id,
+      userId: config.userId ?? '',
+      database: config.database ?? 'postgres',
+      preserveCase: config.preserveCase ?? false,
+      defaultIsolationLevel: config.defaultIsolationLevel ?? 'READ COMMITTED',
+      queryTimeoutMs: config.queryTimeoutMs ?? 0,
+      maxHistorySize: config.maxHistorySize ?? 100,
+      idleTimeoutMs: config.idleTimeoutMs ?? 0,
+    }
+
+    this.createdAt = Date.now()
+    this.lastActivityAt = this.createdAt
+    this.stats = {
+      totalQueries: 0,
+      successfulQueries: 0,
+      failedQueries: 0,
+      totalExecutionMs: 0,
+      transactionsStarted: 0,
+      transactionsCommitted: 0,
+      transactionsRolledBack: 0,
+    }
+  }
+
+  /**
+   * Get current session state
+   */
+  getState(): SessionState {
+    return this.state
+  }
+
+  /**
+   * Check if session is in a transaction
+   */
+  isInTransaction(): boolean {
+    return this.state === 'transaction' && this.transaction !== null
+  }
+
+  /**
+   * Get current transaction state
+   */
+  getTransaction(): TransactionState | null {
+    return this.transaction ? { ...this.transaction } : null
+  }
+
+  /**
+   * Begin a transaction
+   */
+  beginTransaction(isolationLevel?: IsolationLevel): TransactionState {
+    if (this.state === 'closed') {
+      throw new SessionError('Session is closed', {
+        currentState: 'closed',
+        expectedStates: ['idle', 'active'],
+        sessionId: this.id,
+      })
+    }
+    if (this.isInTransaction()) {
+      // Build error options without undefined values for exactOptionalPropertyTypes
+      const errorOptions: { currentState: string; expectedStates: string[]; transactionId?: string } = {
+        currentState: 'transaction',
+        expectedStates: ['idle'],
+      }
+      if (this.transaction?.id !== undefined) {
+        errorOptions.transactionId = this.transaction.id
+      }
+      throw new TransactionError('Transaction already in progress', errorOptions)
+    }
+
+    const txnIsolation = isolationLevel ?? this.config.defaultIsolationLevel ?? 'READ COMMITTED'
+
+    this.transaction = {
+      id: generateTransactionId(),
+      isolationLevel: txnIsolation,
+      startedAt: Date.now(),
+      queryCount: 0,
+      savepoints: [],
+    }
+
+    this.state = 'transaction'
+    this.stats.transactionsStarted++
+    this.lastActivityAt = Date.now()
+
+    this.emitEvent('transaction_begin', {
+      transactionId: this.transaction.id,
+      isolationLevel: this.transaction.isolationLevel,
+    })
+
+    return {
+      id: this.transaction.id,
+      isolationLevel: this.transaction.isolationLevel,
+      startedAt: this.transaction.startedAt,
+      queryCount: this.transaction.queryCount,
+      savepoints: [...this.transaction.savepoints],
+    }
+  }
+
+  /**
+   * Commit the current transaction
+   */
+  commitTransaction(): void {
+    if (!this.isInTransaction()) {
+      throw new TransactionError('No transaction in progress', {
+        currentState: this.state,
+        expectedStates: ['transaction'],
+      })
+    }
+
+    const txn = this.transaction!
+    this.transaction = null
+    this.state = 'idle'
+    this.stats.transactionsCommitted++
+    this.lastActivityAt = Date.now()
+
+    this.emitEvent('transaction_commit', {
+      transactionId: txn.id,
+      queryCount: txn.queryCount,
+      durationMs: Date.now() - txn.startedAt,
+    })
+  }
+
+  /**
+   * Rollback the current transaction
+   */
+  rollbackTransaction(): void {
+    if (!this.isInTransaction()) {
+      throw new TransactionError('No transaction in progress', {
+        currentState: this.state,
+        expectedStates: ['transaction'],
+      })
+    }
+
+    const txn = this.transaction!
+    this.transaction = null
+    this.state = 'idle'
+    this.stats.transactionsRolledBack++
+    this.lastActivityAt = Date.now()
+
+    this.emitEvent('transaction_rollback', {
+      transactionId: txn.id,
+      queryCount: txn.queryCount,
+      durationMs: Date.now() - txn.startedAt,
+    })
+  }
+
+  /**
+   * Create a savepoint in the current transaction
+   */
+  createSavepoint(name: string): void {
+    if (!this.isInTransaction()) {
+      throw new TransactionError('No transaction in progress', {
+        currentState: this.state,
+        expectedStates: ['transaction'],
+      })
+    }
+
+    this.transaction!.savepoints.push(name)
+    this.lastActivityAt = Date.now()
+  }
+
+  /**
+   * Release a savepoint
+   */
+  releaseSavepoint(name: string): void {
+    if (!this.isInTransaction()) {
+      throw new TransactionError('No transaction in progress', {
+        currentState: this.state,
+        expectedStates: ['transaction'],
+      })
+    }
+
+    const idx = this.transaction!.savepoints.indexOf(name)
+    if (idx > -1) {
+      this.transaction!.savepoints.splice(idx, 1)
+    }
+    this.lastActivityAt = Date.now()
+  }
+
+  /**
+   * Rollback to a savepoint
+   */
+  rollbackToSavepoint(name: string): void {
+    if (!this.isInTransaction()) {
+      throw new TransactionError('No transaction in progress', {
+        currentState: this.state,
+        expectedStates: ['transaction'],
+      })
+    }
+
+    const idx = this.transaction!.savepoints.indexOf(name)
+    if (idx > -1) {
+      // Remove all savepoints after this one
+      this.transaction!.savepoints = this.transaction!.savepoints.slice(0, idx + 1)
+    }
+    this.lastActivityAt = Date.now()
+  }
+
+  /**
+   * Record a query execution
+   */
+  recordQuery(
+    request: QueryRequest,
+    result: QueryResponse | null,
+    error?: Error
+  ): void {
+    if (this.state === 'closed') return
+
+    this.lastActivityAt = Date.now()
+    this.state = this.isInTransaction() ? 'transaction' : (error ? 'error' : 'active')
+
+    // Update stats
+    this.stats.totalQueries++
+    if (error) {
+      this.stats.failedQueries++
+    } else {
+      this.stats.successfulQueries++
+    }
+
+    const durationMs = result?.durationMs ?? 0
+    if (durationMs > 0) {
+      this.stats.totalExecutionMs += durationMs
+    }
+
+    // Update transaction query count
+    if (this.transaction) {
+      this.transaction.queryCount++
+    }
+
+    const historySize = this.config.maxHistorySize ?? 0
+    // Add to history if enabled
+    if (historySize > 0) {
+      const entry: QueryHistoryEntry = {
+        sql: request.sql,
+        params: request.params,
+        durationMs,
+        rowCount: result?.rowCount ?? 0,
+        timestamp: Date.now(),
+        success: !error,
+        error: error?.message,
+      }
+
+      this.history.push(entry)
+
+      // Trim history if needed
+      while (this.history.length > historySize) {
+        this.history.shift()
+      }
+    }
+
+    // Emit event
+    if (error) {
+      this.emitEvent('query_error', {
+        sql: request.sql,
+        error: error.message,
+      })
+    } else {
+      this.emitEvent('query_complete', {
+        sql: request.sql,
+        rowCount: result?.rowCount ?? 0,
+        durationMs,
+      })
+    }
+
+    // Reset to idle if not in transaction
+    if (!this.isInTransaction() && !error) {
+      this.state = 'idle'
+    }
+  }
+
+  /**
+   * Get query history
+   */
+  getHistory(limit?: number): QueryHistoryEntry[] {
+    if (limit && limit < this.history.length) {
+      return this.history.slice(-limit)
+    }
+    return [...this.history]
+  }
+
+  /**
+   * Clear query history
+   */
+  clearHistory(): void {
+    this.history = []
+  }
+
+  /**
+   * Get session statistics
+   */
+  getStats(): SessionStats {
+    const now = Date.now()
+    return {
+      totalQueries: this.stats.totalQueries,
+      successfulQueries: this.stats.successfulQueries,
+      failedQueries: this.stats.failedQueries,
+      totalExecutionMs: this.stats.totalExecutionMs,
+      avgExecutionMs: this.stats.totalQueries > 0
+        ? this.stats.totalExecutionMs / this.stats.totalQueries
+        : 0,
+      transactionsStarted: this.stats.transactionsStarted,
+      transactionsCommitted: this.stats.transactionsCommitted,
+      transactionsRolledBack: this.stats.transactionsRolledBack,
+      uptimeMs: now - this.createdAt,
+      idleTimeMs: now - this.lastActivityAt,
+    }
+  }
+
+  /**
+   * Check if session is idle (no activity for configured timeout)
+   */
+  isIdle(): boolean {
+    const idleTimeout = this.config.idleTimeoutMs ?? 0
+    if (idleTimeout <= 0) return false
+    return Date.now() - this.lastActivityAt > idleTimeout
+  }
+
+  /**
+   * Touch session to update last activity
+   */
+  touch(): void {
+    this.lastActivityAt = Date.now()
+  }
+
+  /**
+   * Close the session
+   */
+  close(): void {
+    if (this.state === 'closed') return
+
+    // Rollback any active transaction
+    if (this.isInTransaction()) {
+      this.rollbackTransaction()
+    }
+
+    this.state = 'closed'
+    this.emitEvent('session_close', {
+      stats: this.getStats(),
+    })
+  }
+
+  /**
+   * Check if session is closed
+   */
+  isClosed(): boolean {
+    return this.state === 'closed'
+  }
+
+  /**
+   * Add event listener
+   */
+  addEventListener(listener: SessionEventListener): () => void {
+    this.eventListeners.push(listener)
+    return () => {
+      const idx = this.eventListeners.indexOf(listener)
+      if (idx > -1) {
+        this.eventListeners.splice(idx, 1)
+      }
+    }
+  }
+
+  /**
+   * Remove all event listeners
+   */
+  removeAllEventListeners(): void {
+    this.eventListeners = []
+  }
+
+  private emitEvent(type: SessionEventType, data?: Record<string, unknown>): void {
+    const event: SessionEvent = {
+      type,
+      sessionId: this.id,
+      timestamp: Date.now(),
+      data,
+    }
+
+    for (const listener of this.eventListeners) {
+      try {
+        listener(event)
+      } catch {
+        // Ignore listener errors
+      }
+    }
+  }
+}
+
+/**
+ * Session Manager for multiple sessions
+ */
+export class SessionManager {
+  private sessions = new Map<string, Session>()
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null
+  private defaultConfig: Partial<SessionConfig>
+
+  constructor(config?: {
+    defaultSessionConfig?: Partial<SessionConfig>
+    cleanupIntervalMs?: number
+  }) {
+    this.defaultConfig = config?.defaultSessionConfig ?? {}
+
+    // Start cleanup interval if idle timeout is configured
+    if (config?.cleanupIntervalMs && config.cleanupIntervalMs > 0) {
+      this.cleanupInterval = setInterval(
+        () => this.cleanupIdleSessions(),
+        config.cleanupIntervalMs
+      )
+    }
+  }
+
+  /**
+   * Create a new session
+   */
+  createSession(config?: Partial<SessionConfig>): Session {
+    const session = new Session({
+      ...this.defaultConfig,
+      ...config,
+    })
+
+    this.sessions.set(session.id, session)
+    return session
+  }
+
+  /**
+   * Get a session by ID
+   */
+  getSession(id: string): Session | null {
+    return this.sessions.get(id) ?? null
+  }
+
+  /**
+   * Get or create a session
+   */
+  getOrCreateSession(id: string, config?: Partial<SessionConfig>): Session {
+    let session = this.sessions.get(id)
+    if (!session) {
+      session = new Session({
+        ...this.defaultConfig,
+        ...config,
+        id,
+      })
+      this.sessions.set(id, session)
+    }
+    return session
+  }
+
+  /**
+   * Close a session
+   */
+  closeSession(id: string): boolean {
+    const session = this.sessions.get(id)
+    if (session) {
+      session.close()
+      this.sessions.delete(id)
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Get all active sessions
+   */
+  getActiveSessions(): Session[] {
+    return Array.from(this.sessions.values()).filter(s => !s.isClosed())
+  }
+
+  /**
+   * Get session count
+   */
+  getSessionCount(): number {
+    return this.sessions.size
+  }
+
+  /**
+   * Get aggregate statistics
+   */
+  getAggregateStats(): {
+    sessionCount: number
+    totalQueries: number
+    totalTransactions: number
+    avgQueriesPerSession: number
+  } {
+    let totalQueries = 0
+    let totalTransactions = 0
+
+    for (const session of this.sessions.values()) {
+      const stats = session.getStats()
+      totalQueries += stats.totalQueries
+      totalTransactions += stats.transactionsStarted
+    }
+
+    return {
+      sessionCount: this.sessions.size,
+      totalQueries,
+      totalTransactions,
+      avgQueriesPerSession: this.sessions.size > 0
+        ? totalQueries / this.sessions.size
+        : 0,
+    }
+  }
+
+  /**
+   * Clean up idle sessions
+   */
+  cleanupIdleSessions(): number {
+    let cleaned = 0
+    for (const [id, session] of this.sessions) {
+      if (session.isIdle() && !session.isInTransaction()) {
+        session.close()
+        this.sessions.delete(id)
+        cleaned++
+      }
+    }
+    return cleaned
+  }
+
+  /**
+   * Close all sessions
+   */
+  closeAll(): void {
+    for (const session of this.sessions.values()) {
+      session.close()
+    }
+    this.sessions.clear()
+  }
+
+  /**
+   * Destroy the manager
+   */
+  destroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval)
+      this.cleanupInterval = null
+    }
+    this.closeAll()
+  }
+}
+
+/**
+ * Create a session manager
+ */
+export function createSessionManager(config?: {
+  defaultSessionConfig?: Partial<SessionConfig>
+  cleanupIntervalMs?: number
+}): SessionManager {
+  return new SessionManager(config)
+}
+
+/**
+ * Create a standalone session
+ */
+export function createSession(config?: Partial<SessionConfig>): Session {
+  return new Session(config)
+}