resque-reports 0.0.2 → 0.3.0

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format progress
+--order random

data/.rubocop.yml

@@ -0,0 +1,18 @@
+# This is the configuration used to check the rubocop source code.
+# inherit_from: config/default.yml
+
+MethodLength:
+  Max: 20
+LineLength:
+  Max: 80
+
+AsciiComments:
+  Enabled: false
+SpaceInsideHashLiteralBraces:
+  EnforcedStyleIsWithSpaces: false
+Documentation:
+  Enabled: false
+TrivialAccessors:
+  Enabled: false
+EmptyLiteral:
+  Enabled: false

data/app/jobs/resque/reports/report_job.rb

@@ -1,21 +1,61 @@
 # coding: utf-8
+require 'json'
+require 'active_support'
+
 module Resque
   module Reports
-    # ReportJob accepts report_type and current report arguments to build it in background
+    # ReportJob accepts report_type, its arguments in json
+    # and building report in background
+    # @example:
+    #
+    #    ReportJob.enqueue('Resque::Reports::MyReport', [1, 2].to_json)
+    #
     class ReportJob
       include Resque::Integration
 
-      queue :reports
-      unique { |report_type, args_json| [report_type, args_json] }
+      unique
 
+      # resque-integration main job method
+      # @param [String] report_type - name of BaseReport successor
+      #                 to build report for
+      # @param [String(JSON)] args_json - json array of report arguments
       def self.execute(report_type, args_json)
-        report_class = constant(report_type) # Get report class from string (through ActiveSupport)
-        raise "Resque::Reports::ReportJob can work only with successors of Resque::Reports::BaseReport, but got #{report_class}" unless report_class.ancestors.include? BaseReport
+        report_class = report_type.constantize # избавиться от ActiveSupport
+
+        unless report_class < BaseReport
+          fail "Supports only successors of BaseReport, but got #{report_class}"
+        end
+
+        fail 'Report queue is not specified' unless report_class.job_queue
+        queue report_class.job_queue
+
+        args = JSON.parse(args_json)
+        force = args.pop
+
+        init_report(report_class, args)
+          .build(force)
+      end
+
+      private
+
+      # Initializes report of given class with given arguments
+      def self.init_report(report_class, args_array)
+        report = report_class.new(*args_array)
+
+        report_class.on_progress do |progress, total|
+          unless total.zero?
+            at(progress, total, report.progress_message(progress, total))
+          end
+        end
 
-        args = Json.parse(args_json)
-        report = report_class.new *args
+        report_class.on_error do |error|
+          meta = get_meta(@meta_id)
+          meta['payload'] ||= {'error_messages' => []}
+          meta['payload']['error_messages'] << report.error_message(error)
+          meta.save
+        end
 
-        report.build
+        report
       end
     end # class ReportJob
   end # module Reports

data/lib/resque/reports/base_report.rb

@@ -1,150 +1,203 @@
 # coding: utf-8
+# Resque namespace
 module Resque
+  # Resque::Reports namespace
   module Reports
+    # Class describes base report class for inheritance.
+    # BaseReport successor must implement "write(io, force)" method
+    # and may specify file extension with "extension" method call
+    # example:
+    #
+    #   class CustomTypeReport < Resque::Reports::BaseReport
+    #     extension :type # specify that report file must ends
+    #                     # with '.type', e.g. 'abc.type'
+    #
+    #     # Method specifies how to output report data
+    #     def write(io, force)
+    #       io << 'Hello World!'
+    #     end
+    #   end
+    #
+    # BaseReport provides followed DSL, example:
+    #
+    #   class CustomReport < CustomTypeReport
+    #     queue :custom_reports # Resque queue name
+    #     source :select_data # method called to retrieve report data
+    #     encoding UTF8 # file encoding
+    #
+    #     # Specify in which directory to keep this type files
+    #     directory File.join(Dir.tmpdir, 'resque-reports')
+    #
+    #     # Describe table using 'column' method
+    #     table do |element|
+    #       column 'Column 1 Header', :decorate_one
+    #       column 'Column 2 Header', decorate_two(element[1])
+    #       column 'Column 3 Header', 'Column 3 Cell'
+    #     end
+    #
+    #     # Class initialize
+    #     # NOTE: must be used instead of define 'initialize' method
+    #     create do |param|
+    #       @main_param = param
+    #     end
+    #
+    #     # decorate method, called by symbol-name
+    #     def decorate_one(element)
+    #       "decorate_one: #{element[0]}"
+    #     end
+    #
+    #     # decorate method, called directly when filling cell
+    #     def decorate_two(text)
+    #       "decorate_two: #{text}"
+    #     end
+    #
+    #     # method returns report data Enumerable
+    #     def select_data
+    #       [[0, 'text0'], [1, 'text1']]
+    #     end
+    #   end
     class BaseReport
-      # TODO: Hook initialize of successor to collect init params into @args array
-      # include ActiveSupport
       extend Forwardable
-      include Encodings # include encoding constants CP1251, UTF8...
+      include Extensions
 
       class << self
-        protected
 
-        attr_reader :row_object, 
-                    :directory, 
-                    :create_block
+        attr_reader :job_queue
 
-        attr_accessor :extension, 
-                      :encoding, 
-                      :source_method, 
-                      :table_block, 
-                      :header_collecting
-        
-        alias_method :source, :source_method
+        protected
 
-        def table(&block)
-          @table_block = block
+        attr_reader :create_block
+        attr_writer :job_queue
+        attr_accessor :file_extension,
+                      :file_encoding,
+                      :file_directory
+
+        alias_method :super_extension, :file_extension
+        alias_method :extension, :file_extension=
+        alias_method :set_extension, :file_extension=
+        alias_method :encoding, :file_encoding=
+        alias_method :directory, :file_directory=
+        alias_method :queue, :job_queue=
+
+        def set_instance(obj)
+          @instance = obj
         end
 
         def create(&block)
           @create_block = block
         end
 
-        def build_table_row(row_object)
-          header_collecting = false
-
-          @row_object = row_object # for instance decorate methods calls
-          row = @table_block.call(row_object)
-
-          finish_row
-
-          row
+        # override for Extenstions::TableBuilding, to use custom encoding
+        def encoded_string(obj)
+          obj.to_s.encode(file_encoding,
+                          invalid: :replace,
+                          undef: :replace)
         end
 
-        def build_table_header
-          header_collecting = true
-          @table_block.call(nil)
+        #--
+        # Hooks #
+        #++
+
+        def method_missing(method_name, *args, &block)
+          if @instance.respond_to?(method_name)
+            @instance.send(method_name, *args, &block)
+          else
+            super
+          end
         end
 
-        def get_data
-          send(@source_method)
+        def respond_to?(method, include_private = false)
+          super || @instance.respond_to?(method, include_private)
         end
       end # class methods
 
-      # Constants
+      #--
+      # Constants #
+      #++
 
       DEFAULT_EXTENSION = 'txt'
 
+      #--
+      # Delegators
+      #++
+
+      def_delegators Const::TO_EIGENCLASS,
+                     :file_directory,
+                     :file_extension,
+                     :file_encoding,
+                     :create_block,
+                     :set_instance,
+                     :set_extension
+
+      def_delegators :@cache_file, :filename, :exists?, :ready?
+      def_delegator Const::TO_SUPER, :super_extension
+
+      #--
       # Public instance methods
+      #++
 
       def initialize(*args)
-        create_block.call(*args) if create_block
+        # TODO: Check consistance, fail if user initialized wrong object
+        set_instance(self)
 
-        @args = args
-        extension ||= DEFAULT_EXTENSION
+        if create_block
+          define_singleton_method(:create_dispatch, create_block)
+          create_dispatch(*args)
+        end
 
-        @cache_file = CacheFile.new(directory, generate_filename, coding: encoding)
+        @args = args
 
+        init_cache_file
         init_table
       end
 
-      def build
-        @cache_file.open { |file| write file }
+      # Builds report synchronously
+      def build(force = false)
+        init_table if force
+
+        @cache_file.open(force) { |file| write(file, force) }
       end
 
-      def bg_build
+      # Builds report in background, returns job_id, to watch progress
+      def bg_build(force = false)
         report_class = self.class.to_s
-        args_json = @args.to_json
+
+        args_json = [*@args, force].to_json
 
         # Check report if it already in progress and tring return its job_id...
         job_id = ReportJob.enqueued?(report_class, args_json).try(:meta_id)
-        
         # ...and start new job otherwise
-        ReportJob.enqueue(report_class, args_json) unless job_id
+        job_id || ReportJob.enqueue(report_class, args_json).try(:meta_id)
       end
 
-      def_delegators :@cache_file, :filename, :exists?
-
       protected
 
-      # You must use ancestor methods to work with report data:
-      #   1) get_data => returns Enumerable of report source objects
-      #   2) build_table_header => returns Array of report column names
-      #   3) build_table_row(object) => returns Array of report cell values (same order as header)
-      def write(io)
-        raise NotImplementedError, "write must be implemented in successor"          
-      end
-      
-      def column(name, value)
-        add_column_header(name) || add_column_cell(value)
-      end
-
-      private
-
-      def_delegators 'self.class',
-                     :directory, 
-                     :extension, 
-                     :encoding,
-                     :get_data, 
-                     :build_table_header, 
-                     :build_table_row,
-                     :header_collecting, 
-                     :row_object,
-                     :create_block
-
-      # Fill report table #
-
-      def init_table
-        @table_header = []
-        @table_row = []
-      end
-
-      def add_column_header(column_name)
-        @table_header << column_name if header_collecting
-      end
-
-      def add_column_cell(column_value)
-        return if header_collecting
-        column_value = send(column_value, row_object) if column_value.is_a? Symbol
-        @table_row << encoded_string(value)
-      end
-
-      def encoded_string(obj)
-        obj.to_s.encode(encoding, :invalid => :replace, :undef => :replace)
-      end
-
-      def finish_row
-        @table_row = []
-      end
+      def init_cache_file
+        set_extension super_extension || DEFAULT_EXTENSION
 
-      # Generate filename #
-      
-      def generate_filename
-        "#{ self.class }-#{ hash_args }.#{ extension }"
+        @cache_file = CacheFile.new(file_directory,
+                                    generate_filename(@args, file_extension),
+                                    coding: file_encoding)
       end
 
-      def hash_args
-        Digest::SHA1.hexdigest(@args.to_json)
+      # Method specifies how to output report data
+      # @param [IO] io stream for output
+      # @param [true, false] force write to output or skip due its existance
+      def write(io, force)
+        # You must use ancestor methods to work with report data:
+        # 1) data_size => returns source data size (calls #count on data
+        #                 retrieved from 'source')
+        # 2) data_each => yields given block for each source data element
+        # 3) build_table_header => returns Array of report column names
+        # 4) build_table_row(object) => returns Array of report cell
+        #                               values (same order as header)
+        # 5) progress_message(progress,
+        #                    total) => call to iterate job progress
+        # 6) error_message(error) => call to handle error in job
+        #
+        # HINT: You may override data_size and data_each, to retrieve them
+        #       effectively
+        fail NotImplementedError
       end
     end # class BaseReport
   end # module Report

data/lib/resque/reports/cache_file.rb

@@ -1,15 +1,19 @@
 # coding: utf-8
 module Resque
   module Reports
+    # Class describes how to storage and access cache file
+    # NOTE: Every time any cache file is opening,
+    #       cache is cleared from old files.
     class CacheFile
+      include Extensions::Encodings
 
-      DEFAULT_EXPIRE_TIME = 86400
-      DEFAULT_CODING = 'utf-8'
+      DEFAULT_EXPIRE_TIME = 86_400
+      DEFAULT_CODING = UTF8
 
-      # TODO: Description!
       def initialize(dir, filename, options = {})
         @dir = dir
         @filename = File.join(dir, filename)
+        @ext = File.extname(filename)
 
         # options
         @coding = options[:coding] || DEFAULT_CODING
@@ -22,15 +26,17 @@ module Resque
       alias_method :ready?, :exists?
 
       def filename
-        raise "File doesn't exists, check for its existance before" unless exists?
+        fail 'File doesn\'t exists, check exists? before' unless exists?
         @filename
       end
 
-      def open
+      def open(force = false)
         prepare_cache_dir
 
+        force ? FileUtils.rm_f(@filename) : return if File.exists?(@filename)
+
         remove_unfinished_on_error do
-          File.open(@filename, @coding) do |file|
+          File.open(@filename, "w:#{@coding}") do |file|
             yield file
           end
         end
@@ -45,7 +51,8 @@ module Resque
       end
 
       def clear_expired_files
-        # TODO: avoid races when worker building his report longer than @expiration_time
+        # TODO: avoid races when worker building
+        #       his report longer than @expiration_time
         files_to_delete = cache_files_array.select { |fname| expired?(fname) }
 
         FileUtils.rm_f files_to_delete
@@ -56,14 +63,19 @@ module Resque
       end
 
       def cache_files_array
-        Dir.new(@dir).map { |fname| File.join(@dir.path, fname) }
+        Dir.new(@dir)
+           .map { |fname| File.join(@dir, fname) if File.extname(fname) == @ext }
+           .compact
       end
 
       def remove_unfinished_on_error
         yield
       rescue => error
-        FileUtils.rm_f @filename # remove everything that was written due to it inconsistance
-        raise error # don't suppress any errors here
+        # remove everything that was written due to it inconsistance
+        FileUtils.rm_f @filename
+
+        # don't suppress any errors here
+        raise error
       end
     end
   end