dbwatcher 0.1.5 → 1.0.0

data/lib/dbwatcher/storage/session_storage.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/ClassLength
+
+require_relative "session_operations"
+require_relative "null_session"
+
+module Dbwatcher
+  module Storage
+    # Handles persistence and retrieval of database monitoring sessions
+    #
+    # This class manages the storage of session data including metadata,
+    # timestamps, and associated database changes. Sessions are stored
+    # as individual JSON files with an index for efficient querying.
+    # Follows Ruby style guide patterns for storage class organization.
+    #
+    # @example Basic usage
+    #   storage = SessionStorage.new
+    #   session = Session.new(id: "123", name: "Test Session")
+    #   storage.save(session)
+    #   loaded_session = storage.find("123")
+    #
+    # @see Session
+    # @see NullSession
+    class SessionStorage < BaseStorage
+      # Include shared concerns
+      include Concerns::Validatable
+      include Concerns::DataNormalizer
+
+      # Configuration constants
+      DEFAULT_INDEX_FILENAME = "index.json"
+      SESSIONS_DIRECTORY = "sessions"
+
+      # Validation rules
+      validates_presence_of :id
+
+      # @return [String] path to sessions directory
+      attr_reader :sessions_path
+
+      # @return [String] path to index file
+      attr_reader :index_file
+
+      # @return [SessionOperations] operations helper
+      attr_reader :operations
+
+      # @return [Mutex] thread safety mutex
+      attr_reader :mutex
+
+      # Initializes a new SessionStorage instance
+      #
+      # Sets up the necessary directories and index files for session storage.
+      # Creates the sessions directory and index file if they don't exist.
+      # Includes thread safety for concurrent operations.
+      #
+      # @param storage_path [String, nil] custom storage path (optional)
+      def initialize(storage_path = nil)
+        super
+        @sessions_path = File.join(self.storage_path, SESSIONS_DIRECTORY)
+        @index_file = File.join(self.storage_path, DEFAULT_INDEX_FILENAME)
+        @operations = SessionOperations.new(@sessions_path, @index_file)
+        @mutex = Mutex.new
+
+        setup_directories
+      end
+
+      # Persists a session to storage
+      #
+      # Saves the session data to a JSON file and updates the session index.
+      # Automatically triggers cleanup of old sessions after successful save.
+      # Uses thread safety to prevent concurrent write conflicts.
+      #
+      # @param session [Session, Hash] the session object or hash to save
+      # @return [Boolean] true if saved successfully, false otherwise
+      # @raise [ValidationError] if session data is invalid
+      #
+      # @example
+      #   session = Session.new(id: "123", name: "Test")
+      #   storage.save(session) # => true
+      # rubocop:disable Naming/PredicateMethod
+      def save(session)
+        session_data = normalize_session_data(session)
+        validate_session_data!(session_data)
+
+        mutex.synchronize do
+          persist_session_file(session_data)
+          update_session_index(session_data)
+          trigger_cleanup
+        end
+
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Alternative save method that raises on failure
+      #
+      # @param session [Session, Hash] the session object or hash to save
+      # @return [Boolean] true if saved successfully
+      # @raise [ValidationError] if session data is invalid
+      # @raise [StorageError] if save operation fails
+      def save!(session)
+        with_error_handling("save session") do
+          save(session) or raise StorageError, "Failed to save session"
+        end
+      end
+
+      # Finds a session by ID
+      #
+      # Retrieves session data from storage and constructs a Session object.
+      # Returns nil if the session is not found.
+      #
+      # @param id [String, Integer] the session ID to find
+      # @return [Session, nil] the loaded session or nil if not found
+      #
+      # @example
+      #   session = storage.find("123")
+      #   puts session.name if session
+      def find(id)
+        return nil unless valid_id?(id)
+
+        session_data = load_session_data(id)
+        return nil if session_data.empty?
+
+        build_session_from_data(session_data)
+      end
+
+      # Finds a session by ID or raises an exception
+      #
+      # @param id [String, Integer] the session ID to find
+      # @return [Session] the loaded session
+      # @raise [SessionNotFoundError] if session is not found
+      def find!(id)
+        find(id) or raise SessionNotFoundError, "Session with id '#{id}' not found"
+      end
+
+      # Loads a session by ID (legacy method, use find instead)
+      #
+      # @deprecated Use {#find} instead
+      # @param id [String, Integer] the session ID to load
+      # @return [Session, NullSession] the loaded session or null object
+      def load(id)
+        find(id) || NullSession.instance
+      end
+
+      # Returns all session summaries from the index
+      #
+      # @return [Array<Hash>] array of session summary hashes
+      def all
+        safe_read_json(index_file)
+      end
+
+      # Checks if a session exists
+      #
+      # @param id [String, Integer] the session ID to check
+      # @return [Boolean] true if session exists
+      def exists?(id)
+        return false unless valid_id?(id)
+
+        session_file = operations.session_file_path(id)
+        file_manager.file_exists?(session_file)
+      end
+
+      # Counts total number of sessions
+      #
+      # @return [Integer] number of sessions
+      def count
+        all.size
+      end
+
+      # Clears all session storage
+      #
+      # Removes all session files and reinitializes the storage structure.
+      # This operation cannot be undone.
+      #
+      # @return [Integer] number of files removed
+      def clear_all
+        with_error_handling("clear all sessions") do
+          # Count files before deleting
+          file_count = count_session_files
+
+          safe_delete_directory(sessions_path)
+          safe_write_json(index_file, [])
+          setup_directories
+          touch_updated_at
+
+          file_count
+        end
+      end
+
+      # Removes old session files based on configuration
+      #
+      # Automatically called after each save operation to maintain
+      # storage size within configured limits.
+      #
+      # @return [void]
+      def cleanup_old_sessions
+        return unless cleanup_enabled?
+
+        cutoff_date = calculate_cleanup_cutoff
+        remove_old_session_files(cutoff_date)
+      end
+
+      private
+
+      # Sets up required directories and files
+      #
+      # @return [void]
+      def setup_directories
+        file_manager.ensure_directory(sessions_path)
+        file_manager.write_json(index_file, []) unless File.exist?(index_file)
+      end
+
+      # Validates session data
+      #
+      # @param session_data [Hash] session data to validate
+      # @return [void]
+      # @raise [ValidationError] if data is invalid
+      def validate_session_data!(session_data)
+        validate_presence!(session_data, :id)
+        validate_id!(session_data[:id])
+      end
+
+      # Persists session data to file
+      #
+      # @param session_data [Hash] session data to persist
+      # @return [void]
+      def persist_session_file(session_data)
+        session_file = operations.session_file_path(session_data[:id])
+        safe_write_json(session_file, session_data)
+      end
+
+      # Updates the session index
+      #
+      # @param session_data [Hash] session data for index update
+      # @return [void]
+      def update_session_index(session_data)
+        index = safe_read_json(index_file)
+        session_summary = operations.build_session_summary(session_data)
+
+        updated_index = [session_summary] + index
+        limited_index = operations.apply_session_limits(updated_index)
+
+        safe_write_json(index_file, limited_index)
+      end
+
+      # Triggers cleanup of old sessions
+      #
+      # @return [void]
+      def trigger_cleanup
+        cleanup_old_sessions
+      end
+
+      # Loads session data from file
+      #
+      # @param id [String] session ID
+      # @return [Hash] session data or empty hash
+      def load_session_data(id)
+        session_file = operations.session_file_path(id)
+        safe_read_json(session_file, {})
+      end
+
+      # Builds session object from data
+      #
+      # @param data [Hash] session data
+      # @return [Session] session object
+      def build_session_from_data(data)
+        Storage::Session.new(data)
+      rescue StandardError => e
+        log_error("Failed to build session from data", e)
+        raise CorruptedDataError, "Session data is corrupted: #{e.message}"
+      end
+
+      # Counts the number of session files
+      #
+      # @return [Integer] number of session files
+      def count_session_files
+        return 0 unless Dir.exist?(sessions_path)
+
+        Dir.glob(File.join(sessions_path, "*.json")).count
+      end
+
+      # Checks if cleanup is enabled
+      #
+      # @return [Boolean] true if cleanup is enabled
+      def cleanup_enabled?
+        Dbwatcher.configuration.auto_clean_after_days&.positive?
+      end
+
+      # Calculates cleanup cutoff date
+      #
+      # @return [Time] cutoff date for cleanup
+      def calculate_cleanup_cutoff
+        days = Dbwatcher.configuration.auto_clean_after_days
+        current_time - (days * 24 * 60 * 60)
+      end
+
+      # Removes old session files
+      #
+      # @param cutoff_date [Time] files older than this date are removed
+      # @return [void]
+      def remove_old_session_files(cutoff_date)
+        safe_operation("cleanup old sessions") do
+          Dir.glob(File.join(sessions_path, "*.json")).each do |file|
+            File.delete(file) if File.mtime(file) < cutoff_date
+          end
+        end
+      end
+
+      # Returns current time (compatible with and without Rails)
+      #
+      # @return [Time] current time
+      def current_time
+        if defined?(Time.current)
+          Time.current
+        else
+          Time.now
+        end
+      end
+    end
+  end
+end
+
+# rubocop:enable Metrics/ClassLength

data/lib/dbwatcher/storage/table_storage.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require_relative "change_processor"
+
+module Dbwatcher
+  module Storage
+    # Handles retrieval and processing of table change data
+    #
+    # This class provides access to database table changes by coordinating
+    # with the change processor to aggregate and filter table modifications
+    # from stored session data. Follows Ruby style guide patterns for
+    # storage class organization.
+    #
+    # @example Basic usage
+    #   storage = TableStorage.new(session_storage)
+    #   changes = storage.find_changes("users")
+    #   changes.each { |change| puts "#{change[:operation]} on #{change[:table]}" }
+    #
+    # @example Advanced filtering
+    #   recent_changes = storage.find_recent_changes("users", limit: 10)
+    #   filtered_changes = storage.find_changes_by_operation("users", "INSERT")
+    class TableStorage < BaseStorage
+      # Include validation capabilities
+      include Concerns::Validatable
+
+      # Configuration constants
+      DEFAULT_CHANGE_LIMIT = 100
+      SUPPORTED_OPERATIONS = %w[INSERT UPDATE DELETE].freeze
+
+      # @return [ChangeProcessor] processor for handling table changes
+      attr_reader :change_processor
+
+      # @return [SessionStorage] session storage dependency
+      attr_reader :session_storage
+
+      # Initializes table storage with session storage dependency
+      #
+      # @param session_storage [SessionStorage] storage instance for session data
+      # @param storage_path [String, nil] custom storage path (optional)
+      def initialize(session_storage, storage_path = nil)
+        super(storage_path)
+        @session_storage = session_storage
+        @change_processor = ChangeProcessor.new(session_storage)
+      end
+
+      # Finds all changes for a specific table
+      #
+      # Retrieves and processes all database changes related to the specified
+      # table from stored session data. Returns an empty array if the table
+      # name is invalid or no changes are found.
+      #
+      # @param table_name [String] name of the table to load changes for
+      # @param options [Hash] filtering options
+      # @option options [Integer] :limit maximum number of changes to return
+      # @option options [String] :operation filter by operation type (INSERT, UPDATE, DELETE)
+      # @option options [Time] :since only return changes after this time
+      # @return [Array<Hash>] array of change records for the table
+      #
+      # @example
+      #   changes = storage.find_changes("users")
+      #   puts "Found #{changes.length} changes for users table"
+      #
+      # @example With filtering
+      #   recent_inserts = storage.find_changes("users", operation: "INSERT", limit: 50)
+      def find_changes(table_name, **options)
+        validate_table_name!(table_name)
+        validate_operation!(options[:operation]) if options[:operation]
+
+        changes = change_processor.process_table_changes(table_name)
+        apply_filters(changes, **options)
+      rescue StandardError => e
+        log_error("Failed to load changes for table #{table_name}", e)
+        []
+      end
+
+      # Finds changes for a table with a specific operation
+      #
+      # @param table_name [String] name of the table
+      # @param operation [String] operation type (INSERT, UPDATE, DELETE)
+      # @param limit [Integer] maximum number of changes to return
+      # @return [Array<Hash>] filtered change records
+      def find_changes_by_operation(table_name, operation, limit: DEFAULT_CHANGE_LIMIT)
+        find_changes(table_name, operation: operation, limit: limit)
+      end
+
+      # Finds recent changes for a table
+      #
+      # @param table_name [String] name of the table
+      # @param limit [Integer] maximum number of changes to return
+      # @param since [Time] only return changes after this time
+      # @return [Array<Hash>] recent change records
+      def find_recent_changes(table_name, limit: DEFAULT_CHANGE_LIMIT, since: 1.day.ago)
+        find_changes(table_name, limit: limit, since: since)
+      end
+
+      # Counts total changes for a table
+      #
+      # @param table_name [String] name of the table
+      # @return [Integer] number of changes for the table
+      def count_changes(table_name)
+        find_changes(table_name).size
+      end
+
+      # Counts changes by operation type
+      #
+      # @param table_name [String] name of the table
+      # @return [Hash] hash with operation types as keys and counts as values
+      def count_changes_by_operation(table_name)
+        changes = find_changes(table_name)
+
+        SUPPORTED_OPERATIONS.each_with_object({}) do |operation, counts|
+          counts[operation] = changes.count { |change| change[:operation] == operation }
+        end
+      end
+
+      # Lists all tables that have changes
+      #
+      # @return [Array<String>] array of table names with changes
+      def tables_with_changes
+        change_processor.tables_with_changes
+      rescue StandardError => e
+        log_error("Failed to load tables with changes", e)
+        []
+      end
+
+      # Checks if a table has any changes
+      #
+      # @param table_name [String] name of the table to check
+      # @return [Boolean] true if table has changes
+      def changes?(table_name)
+        return false unless valid_table_name?(table_name)
+
+        count_changes(table_name).positive?
+      end
+
+      # Legacy method for backward compatibility
+      #
+      # @deprecated Use {#find_changes} instead
+      # @param table_name [String] name of the table to load changes for
+      # @return [Array<Hash>] array of change records
+      def load_changes(table_name)
+        find_changes(table_name)
+      end
+
+      private
+
+      # Validates table name for presence and format
+      #
+      # @param table_name [String] table name to validate
+      # @return [void]
+      # @raise [ValidationError] if table name is invalid
+      def validate_table_name!(table_name)
+        raise ValidationError, "Table name cannot be nil or empty" if table_name.nil? || table_name.to_s.strip.empty?
+
+        return unless table_name.to_s.include?(" ")
+
+        raise ValidationError, "Table name cannot contain spaces"
+      end
+
+      # Validates operation type
+      #
+      # @param operation [String] operation to validate
+      # @return [void]
+      # @raise [ValidationError] if operation is invalid
+      def validate_operation!(operation)
+        return if SUPPORTED_OPERATIONS.include?(operation.to_s.upcase)
+
+        raise ValidationError,
+              "Unsupported operation: #{operation}. Must be one of: #{SUPPORTED_OPERATIONS.join(", ")}"
+      end
+
+      # Checks if table name is valid
+      #
+      # @param table_name [String] table name to check
+      # @return [Boolean] true if table name is valid
+      def valid_table_name?(table_name)
+        !table_name.nil? && !table_name.to_s.strip.empty?
+      end
+
+      # Applies filtering options to changes
+      #
+      # @param changes [Array<Hash>] changes to filter
+      # @param options [Hash] filtering options
+      # @return [Array<Hash>] filtered changes
+      def apply_filters(changes, **options)
+        filtered_changes = changes
+        filtered_changes = filter_by_operation(filtered_changes, options[:operation]) if options[:operation]
+        filtered_changes = filter_by_time(filtered_changes, options[:since]) if options[:since]
+        filtered_changes = apply_limit(filtered_changes, options[:limit]) if options[:limit]
+        filtered_changes
+      end
+
+      # Filters changes by operation type
+      #
+      # @param changes [Array<Hash>] changes to filter
+      # @param operation [String, Symbol] operation to filter by
+      # @return [Array<Hash>] filtered changes
+      def filter_by_operation(changes, operation)
+        operation_str = operation.to_s.upcase
+        changes.select { |change| change[:operation] == operation_str }
+      end
+
+      # Filters changes by timestamp
+      #
+      # @param changes [Array<Hash>] changes to filter
+      # @param since_time [Time] minimum timestamp
+      # @return [Array<Hash>] filtered changes
+      def filter_by_time(changes, since_time)
+        changes.select do |change|
+          change_time = parse_timestamp(change[:timestamp])
+          change_time && change_time >= since_time
+        end
+      end
+
+      # Applies limit to changes (returns most recent)
+      #
+      # @param changes [Array<Hash>] changes to limit
+      # @param limit [Integer] maximum number of changes to return
+      # @return [Array<Hash>] limited changes
+      def apply_limit(changes, limit)
+        changes.sort_by { |change| change[:timestamp] }
+               .reverse
+               .first(limit)
+      end
+
+      # Parses timestamp safely
+      #
+      # @param timestamp [String, Time] timestamp to parse
+      # @return [Time, nil] parsed time or nil if invalid
+      def parse_timestamp(timestamp)
+        Time.parse(timestamp.to_s)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end