active_capture 1.1.1 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35e9f57cd205fbbb0ed7e4139101787cb4f66e53a32186b27473f9db72b40498
-  data.tar.gz: ea2747f578ebc4dff315d542b7e6e4cb9193e53e0dd49f2231f37654d39047bc
+  metadata.gz: 408cdbd0f3cea245a023857573782eab133c6f8d3a41981ff190702c8f6424bb
+  data.tar.gz: 9726c3c013f766036550a1170d8f4b71f382043058e78701fee884654b002f6c
 SHA512:
-  metadata.gz: f72ad16293a0f39eed9e2471ba7ece51022abdcb6f6005244f25502f7d903eb5054b983a2414fbbeb18c0b1878a93bf674333c71bcd4e4cea57a37df841cc8bf
-  data.tar.gz: c4d02f5b01eb45a1a2e98cd349b4fd3d765a8a4ff27dfe48a57568ac06594431ba501dd69652292776724f548c8528f92b3cd1a613cff5c0a5f22024d4355868
+  metadata.gz: '08763c65b1bf808fbf85677e912621e34ffc2d00de886a6242f1bdc5308e425215e293d471403a6bc14c51b92bab82d4c2e6cf652421192c66977a2cd4c46a7e'
+  data.tar.gz: 6dfbb8e4974cc7382d5b6999413643d7483586843582eba130424ba0929519855f9d0519a14615ac0c37dfdea593bb6e73f353d0130f710e03836069e81d0bab

data/lib/active_capture.rb

@@ -4,6 +4,7 @@ require 'json'
 require 'active_record'
 
 module ActiveCapture
+  # Captures the state of a record and its associations
   def self.take(record, associations: [], name: nil)
     validate_record(record)
 
@@ -15,18 +16,21 @@ module ActiveCapture
     }
 
     begin
+      # Save the captured data in json file
       Support::CaptureStorage.save_capture(record, capture_data, name)
     rescue StandardError => e
       raise "Failed to save capture: #{e.message}"
     end
   end
 
+  # Restores a record and its associations from a capture file
   def self.restore(record, capture_file, merge: false)
     captured_records = Support::CaptureStorage.load_capture(capture_file)
     validate_capture(record, captured_records)
 
     ActiveRecord::Base.transaction do
       begin
+        # Update the record's attributes and restore its associations
         record.update!(captured_records['attributes'])
         restore_associations(record, captured_records['associations'], merge: merge)
       rescue StandardError => e
@@ -35,20 +39,28 @@ module ActiveCapture
     end
   end
 
+  # Flushes all captured data of a specified directory
+  def self.flush(directory)
+    Support::CaptureStorage.flush(directory)
+  end
+
   private
 
+  # Validates that the given record is an ActiveRecord instance
   def self.validate_record(record)
     unless record.is_a?(ActiveRecord::Base)
       raise ArgumentError, 'Record must be an ActiveRecord::Base instance'
     end
   end
 
+  # Validates that the capture file matches the given record
   def self.validate_capture(record, captured_records)
     unless captured_records['record_id'] == record.id
       raise ArgumentError, 'Capture file does not match the given record'
     end
   end
 
+  # Captures the specified associations of a record
   def self.capture_associations(record, associations)
     associations.each_with_object({}) do |association, association_data|
       association_name, nested_associations = parse_association(association)
@@ -56,6 +68,7 @@ module ActiveCapture
       next unless record.respond_to?(association_name)
 
       begin
+        # Capture the related records for the association
         related_records = record.send(association_name)
         association_data[association_name] = capture_related_records(related_records, nested_associations)
       rescue StandardError => e
@@ -64,6 +77,7 @@ module ActiveCapture
     end
   end
 
+  # Captures the attributes and nested associations of related records
   def self.capture_related_records(related_records, nested_associations)
     if related_records.is_a?(ActiveRecord::Base)
       {
@@ -80,6 +94,7 @@ module ActiveCapture
     end
   end
 
+  # Parses an association to extract its name and nested associations
   def self.parse_association(association)
     if association.is_a?(Hash)
       [association.keys.first, association.values.flatten]
@@ -88,36 +103,44 @@ module ActiveCapture
     end
   end
 
+  # Restores the associations of a record from captured data
   def self.restore_associations(record, associations_data, merge: false)
     associations_data.each do |association_name, related_data|
       if related_data.is_a?(Array)
+        # Restore a collection association (e.g., has_many)
         restore_collection_association(record, association_name, related_data, merge)
       else
+        # Restore a single association (e.g., belongs_to, has_one)
         restore_single_association(record, association_name, related_data, merge)
       end
     end
   end
 
+  # Restores a collection association (e.g., has_many)
   def self.restore_collection_association(record, association_name, related_data, merge)
     associated_class = record.class.reflect_on_association(association_name).klass
     existing_records = record.send(association_name)
 
     related_data.each do |related_record_data|
       if merge && related_record_data['attributes']['id']
+        # Update existing records if merging is enabled
         existing_record = existing_records.find_by(id: related_record_data['attributes']['id'])
         if existing_record
           update_and_restore(existing_record, related_record_data, merge)
           next
         end
       end
+      # Create and restore new records
       create_and_restore(associated_class, related_record_data, record, association_name)
     end
   end
 
+  # Restores a single association (e.g., belongs_to, has_one)
   def self.restore_single_association(record, association_name, related_data, merge)
     associated_class = record.class.reflect_on_association(association_name).klass
 
     if merge && related_data['attributes']['id']
+      # Update existing record if merging is enabled
       existing_record = record.send(association_name)
       if existing_record&.id == related_data['attributes']['id']
         update_and_restore(existing_record, related_data, merge)
@@ -125,15 +148,18 @@ module ActiveCapture
       end
     end
 
+    # Create and restore a new record
     new_record = create_and_restore(associated_class, related_data)
     record.update!(association_name => new_record)
   end
 
+  # Updates an existing record and restores its associations
   def self.update_and_restore(record, related_data, merge)
     record.update!(related_data['attributes'])
     restore_associations(record, related_data['associations'], merge: merge)
   end
 
+  # Creates a new record and restores its associations
   def self.create_and_restore(associated_class, related_data, parent_record = nil, association_name = nil)
     new_record = associated_class.create!(related_data['attributes'])
     restore_associations(new_record, related_data['associations'], merge: false)

data/lib/support/capture_storage.rb

@@ -1,44 +1,95 @@
+# This module provides functionality for storing and retrieving JSON-based capture data
+# associated with specific records. It includes methods for saving captures, loading captures,
+# and flushing (deleting) files in a specific directory.
+
 require 'json'
 require 'fileutils'
 require 'pathname'
 
 module Support
   class CaptureStorage
+    # Constants for directory and filename constraints
     CAPTURE_DIR = 'captures'.freeze
     MAX_FILENAME_LENGTH = 100
     VALID_FILENAME_REGEX = /\A[a-zA-Z0-9\-_\.]+\z/
 
     class << self
+      # Saves capture data to a JSON file in a structured directory.
+      # @param record [Object] The record object (must respond to :class and :id).
+      # @param capture_data [Hash] The data to be saved.
+      # @param name [String, nil] Optional custom filename.
+      # @return [Hash] Result of the operation with success status and file path or error message.
       def save_capture(record, capture_data, name = nil)
-        validate_record(record)
-        validate_capture_data(capture_data)
+        validate_record(record) # Ensure the record is valid
+        validate_capture_data(capture_data) # Ensure the capture data is valid
         
-        file_name = generate_filename(record, name)
-        dir_path = create_capture_directory(record)
-        file_path = File.join(dir_path, file_name)
+        file_name = generate_filename(record, name) # Generate a valid filename
+        dir_path = create_capture_directory(record) # Create the directory for the capture
+        file_path = File.join(dir_path, file_name) # Full path to the capture file
 
-        write_capture_file(file_path, capture_data)
+        write_capture_file(file_path, capture_data) # Write the capture data to the file
         
         { success: true, file_path: file_path }
       rescue => e
         { success: false, error: e.message }
       end
 
+      # Loads capture data from a JSON file.
+      # @param capture_file [String] Path to the capture file.
+      # @return [Hash] Parsed JSON data from the file.
+      # @raise [StorageError] If the file cannot be loaded or parsed.
       def load_capture(capture_file)
-        validate_file_path(capture_file)
+        validate_file_path(capture_file) # Ensure the file path is valid
         
-        file_content = read_file_safely(capture_file)
-        parsed_data = JSON.parse(file_content)
+        file_content = read_file_safely(capture_file) # Read the file content
+        parsed_data = JSON.parse(file_content) # Parse the JSON content
         
-        validate_parsed_data(parsed_data)
+        validate_parsed_data(parsed_data) # Ensure the parsed data is valid
         
         parsed_data
       rescue => e
         raise StorageError, "Failed to load capture: #{e.message}"
       end
 
+      # Deletes all files in a specified directory under the capture directory.
+      # @param directory [String] Subdirectory name under the capture directory.
+      def flush(directory)
+        begin
+          dir_path = File.join(CAPTURE_DIR, directory) # Full path to the directory
+      
+          unless Dir.exist?(dir_path)
+            raise StandardError, "Directory '#{dir_path}' does not exist."
+          end
+      
+          files = Dir.glob("#{dir_path}/*") # Get all files in the directory
+          
+          if files.empty?
+            puts "No files found in #{dir_path} to delete."
+            return
+          end
+      
+          files.each do |file|
+            if File.file?(file)
+              begin
+                File.delete(file) # Delete each file
+              rescue Errno::EACCES
+                puts "Permission denied when deleting file: #{file}"
+              rescue StandardError => e
+                puts "Failed to delete file: #{file}. Error: #{e.message}"
+              end
+            end
+          end
+      
+          puts "Flushed all files in #{dir_path} successfully."
+      
+        rescue StandardError => e
+          puts "An error occurred during flush operation: #{e.message}"
+        end
+      end
+
       private
 
+      # Validates that the record has the required attributes.
       def validate_record(record)
         unless record.respond_to?(:class) && record.respond_to?(:id)
           raise ArgumentError, "Invalid record: must respond to :class and :id"
@@ -49,6 +100,7 @@ module Support
         end
       end
 
+      # Validates the structure of the capture data.
       def validate_capture_data(data)
         unless data.is_a?(Hash)
           raise ArgumentError, "Capture data must be a Hash"
@@ -61,6 +113,7 @@ module Support
         end
       end
 
+      # Generates a valid filename for the capture file.
       def generate_filename(record, custom_name)
         model_name = record.class.name.downcase.gsub(/[^a-z0-9]/, '_')
         record_id = record.id.to_s
@@ -75,6 +128,7 @@ module Support
         end
       end
 
+      # Validates the custom filename.
       def validate_filename(name)
         if name.empty?
           raise ArgumentError, "Filename cannot be empty"
@@ -89,12 +143,13 @@ module Support
         end
       end
 
+      # Creates the directory for storing capture files.
       def create_capture_directory(record)
         model_name = record.class.name.downcase.gsub(/[^a-z0-9]/, '_')
         dir_path = File.join(CAPTURE_DIR, model_name)
 
         begin
-          FileUtils.mkdir_p(dir_path)
+          FileUtils.mkdir_p(dir_path) # Create the directory if it doesn't exist
         rescue SystemCallError => e
           raise StorageError, "Failed to create directory '#{dir_path}': #{e.message}"
         end
@@ -102,17 +157,19 @@ module Support
         dir_path
       end
 
+      # Writes the capture data to a file safely.
       def write_capture_file(file_path, data)
         begin
           temp_path = "#{file_path}.tmp"
-          File.write(temp_path, JSON.pretty_generate(data))
-          File.rename(temp_path, file_path)
+          File.write(temp_path, JSON.pretty_generate(data)) # Write to a temporary file
+          File.rename(temp_path, file_path) # Rename to the final file
         rescue SystemCallError => e
           File.delete(temp_path) if File.exist?(temp_path)
           raise StorageError, "Failed to write capture file '#{file_path}': #{e.message}"
         end
       end
 
+      # Validates the file path for loading captures.
       def validate_file_path(file_path)
         unless File.exist?(file_path)
           raise StorageError, "File does not exist: #{file_path}"
@@ -127,12 +184,14 @@ module Support
         end
       end
 
+      # Reads the file content safely.
       def read_file_safely(file_path)
         File.read(file_path)
       rescue SystemCallError => e
         raise StorageError, "Failed to read file '#{file_path}': #{e.message}"
       end
 
+      # Validates the parsed JSON data structure.
       def validate_parsed_data(data)
         unless data.is_a?(Hash)
           raise StorageError, "Invalid capture format: expected JSON object"
@@ -146,6 +205,7 @@ module Support
       end
     end
 
+    # Custom error class for storage-related errors.
     class StorageError < StandardError; end
   end
 end

data/lib/support/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Support
-  VERSION = "1.1.1"
+  VERSION = "1.1.3"
 end

data/test/test_active_capture_flush.rb

@@ -0,0 +1,90 @@
+require 'minitest/autorun'
+require 'fileutils'
+require_relative '../lib/active_capture'
+
+# Test suite for the ActiveCapture.flush method
+class ActiveCaptureFlushTest < Minitest::Test
+  # Directory where test captures will be stored
+  CAPTURES_DIR = 'captures'.freeze
+
+  # Setup method to prepare the test environment
+  def setup
+    # Create the captures directory
+    FileUtils.mkdir_p(CAPTURES_DIR)
+    # Create a user subdirectory
+    @user_dir = File.join(CAPTURES_DIR, 'user')
+    FileUtils.mkdir_p(@user_dir)
+    # Add test files to the user directory
+    File.write(File.join(@user_dir, 'test1.json'), '{}')
+    File.write(File.join(@user_dir, 'test2.json'), '{}')
+  end
+
+  # Teardown method to clean up after tests
+  def teardown
+    # Remove the captures directory and its contents
+    FileUtils.rm_rf(CAPTURES_DIR)
+  end
+
+  # Test flushing a valid directory with files
+  def test_flush_valid_directory
+    # Ensure the user directory exists and contains files
+    assert Dir.exist?(@user_dir)
+    assert_equal 2, Dir.glob(File.join(@user_dir, '*')).size
+
+    # Call the flush method
+    ActiveCapture.flush('user')
+
+    # Verify the directory is empty after flushing
+    assert_empty Dir.glob(File.join(@user_dir, '*'))
+    puts "test_flush_valid_directory passed"
+  end
+
+  # Test flushing a non-existent directory
+  def test_flush_non_existent_directory
+    # Capture the output of the flush method
+    output = capture_io do
+      ActiveCapture.flush('non_existent_dir')
+    end
+    # Verify the appropriate error message is displayed
+    assert_match /Directory 'captures\/non_existent_dir' does not exist./, output[0]
+    puts "test_flush_non_existent_directory passed"
+  end
+
+  # Test flushing an empty directory
+  def test_flush_empty_directory
+    # Remove and recreate the user directory to ensure it's empty
+    FileUtils.rm_rf(@user_dir)
+    FileUtils.mkdir_p(@user_dir)
+    assert_empty Dir.glob(File.join(@user_dir, '*'))
+
+    # Capture the output of the flush method
+    output = capture_io do
+      ActiveCapture.flush('user')
+    end
+    # Verify the appropriate message is displayed for an empty directory
+    assert_match /No files found in captures\/user to delete./, output[0]
+    puts "test_flush_empty_directory passed"
+  end
+
+  # Test flushing a directory with a file that has restricted permissions
+  def test_flush_with_permission_error
+    # Skip this test unless run with restricted permissions
+    skip "Run this test with restricted permissions to verify behavior."
+
+    # Create a protected file with no permissions
+    protected_file = File.join(@user_dir, 'protected.json')
+    File.write(protected_file, '{}')
+    FileUtils.chmod(0o000, protected_file)
+
+    # Capture the output of the flush method
+    output = capture_io do
+      ActiveCapture.flush('user')
+    end
+    # Verify the appropriate error message is displayed for permission issues
+    assert_match /Permission denied when deleting file: captures\/user\/protected.json/, output[0]
+
+    # Reset permissions for cleanup
+    FileUtils.chmod(0o644, protected_file)
+    puts "test_flush_with_permission_error passed"
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_capture
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.1.3
 platform: ruby
 authors:
 - Tanmay Bhawsar
@@ -36,6 +36,7 @@ files:
 - lib/support/version.rb
 - test/support/test_capture_storage.rb
 - test/test_active_capture.rb
+- test/test_active_capture_flush.rb
 - test/test_helper.rb
 homepage: https://github.com/bhawsartanmay/active_capture
 licenses: