asana_exception_notifier 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bfdc4b272be9f6414781dafe42e0162f1ffee60e
-  data.tar.gz: f4f13163c9e1f825764b1d5c08c5934f97e75ded
+  metadata.gz: 4347775ca62029a21993e4af21d0ce3ab69fba95
+  data.tar.gz: dc0fbe28a472e7b9ed3c32d30f2539b60f3693b2
 SHA512:
-  metadata.gz: 0f6f2005e5eebd44234b8f8307e171ef50aebf5f287a7d1055e1b6a7743c9612fd66f59659f6908dc4d6aab0dd86980345c7ac61765787167ebbecec9d9dfabf
-  data.tar.gz: 2d4d567f75b6aa041c22e6fb7d7e3f9943218bf7b1c8afb11bb1c62e5aedfab82e0dd7871d6817e46eaccd0950d4fbb6bc137d03e07f8389517047e44e2a0b19
+  metadata.gz: 8ec4281a81123c92a7065b0d93e3418d3bf7d5f86cfc358db5f062a890212d777a1a42d1297697874aee2c037430bff1151c0226eeca1e65888b8d33b99d78bb
+  data.tar.gz: 7e8cb03ef5d3decfee940816af3747c483818c4e2329136c87811beabaccd2a7bff77e0aaf8ab22ef4d456fc5e79257aee71548e05c68e3776d5ebf500f1b31f

data/README.md

@@ -179,7 +179,7 @@ Array of projects this task is associated with and the section it is in. At task
 
 *Array, optional*
 
-Array of tags associated with this task. This property may be specified on creation using just an array of existing tag IDs. (Default: false).
+Array of tags associated with this task. This property may be specified on creation using just an array of existing tag IDs. (Default: []).
 
 ##### name
 

data/asana_exception_notifier.gemspec

@@ -34,7 +34,7 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'rubyzip', '~> 1.0',  '>= 1.0.0' # will load new rubyzip version
   s.add_runtime_dependency 'zip-zip', '~> 0.3', '>= 0.3' # will load compatibility for old rubyzip API
   s.add_runtime_dependency 'sys-uname', '~> 1.0', '>= 1.0.2'
-
+  
   s.add_development_dependency 'appraisal', '~> 2.1', '>= 2.1'
   s.add_development_dependency 'rspec', '~> 3.4', '>= 3.4'
   s.add_development_dependency 'simplecov', '~> 0.11', '>= 0.10'

data/lib/asana_exception_notifier/classes/asana.rb

@@ -1,22 +1,68 @@
 # frozen_string_literal: true
 require_relative '../helpers/application_helper'
-# class used for connecting to github api and retrieves information about repository
+# class used for connecting to connecting to Asana and creation of task and upload of archives
 #
-# @!attribute callback
-#   @return [Proc] The callback that is executed after the info is fetched from Github API
+# @!attribute [r] initial_options
+#   @return [Hash] THe initial options that the notifier received ( blank values are filtered )
+# @!attribute [r] default_options
+#   @return [Hash] The permitted_options that are merged with initial options ( blank values are filtered )
 module ExceptionNotifier
   # module that is used for formatting numbers using metrics
   class AsanaNotifier < ExceptionNotifier::BaseNotifier
     include AsanaExceptionNotifier::ApplicationHelper
-    # the base url to which the API will connect for fetching information about gems
-    attr_reader :initial_options, :default_options
 
+    # The initial options that the middleware was configured with
+    # @return [Hash] THe initial options that the notifier received ( blank values are filtered )
+    attr_reader :initial_options
+
+    # The resulting options after merging with permitted_options and with initial_options
+    # @return [Hash] The permitted_options that are merged with initial options ( blank values are filtered )
+    attr_reader :default_options
+
+    # Initializes the instance with the options from the configuration and
+    # parses the options
+    # @see #parse_options
+    #
+    # @param [options] options The options that can be set in the configuration block
+    # @option params [String] :asana_api_key Your Personal Access Token from Asana. You can get it from https://app.asana.com/-/account_api.
+    #   Please make sure you keep the token secret, and don't commit it in your repository.
+    #   I suggest to put it into an environment variable and use it from that variable. ( This is REQUIRED )
+    # @option params [Integer] :workspace The workspace ID where the task will be created. ( This is REQUIRED )
+    # @option params [String, nil] :assignee Who will be assigned by default to the task that is going to be created. (Default: 'me').
+    #   Can be disabled by setting it to NIL value
+    # @option params [String, nil] :assignee_status Scheduling status of this task for the user it is assigned to.
+    #   This field can only be set if the assignee is non-null. (Default: 'today'). Can be disabled by setting it to NIL value.
+    # @option params [Time, nil] :due_at Date and time on which this task is due, or null if the task has no due time.
+    #   This takes a UTC timestamp and should not be used together with due_on. Default ( Time.now.iso8601)
+    # @option params [Time, nil] :due_on Date on which this task is due, or null if the task has no due date.
+    #   This takes a date with YYYY-MM-DD format and should not be used together with due_at
+    # @option params [Boolean, nil] :hearted True if the task is hearted by the authorized user, false if not (Default: false).
+    # @option params [Array<String>] :hearts Array of users who will heart the task after creation. (Default: empty Array)
+    # @option params [Array<String>] :projects Array of projects this task is associated with.
+    #   At task creation time, this array can be used to add the task to many projects at once.(Default: empty array).
+    # @option params [Array<String>] :followers Array of users following this task. (Default: empty array).
+    # @option params [Array<String>] :memberships Array of projects this task is associated with and the section it is in.
+    #   At task creation time, this array can be used to add the task to specific sections.
+    #   Note that over time, more types of memberships may be added to this property.(Default: []).
+    # @option params [Array<String>] :tags Array of tags associated with this task.
+    #   This property may be specified on creation using just an array of existing tag IDs. (Default: false).
+    # @option params [String] :notes More detailed, free-form textual information associated with the task. (Default: '')
+    # @option params [String] :name Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability.
+    #   However, it can be longer. (Default: "[AsanaExceptionNotifier] %Exception Class Name%").
+    # @option params [String] :template_path This can be used to override the default template when rendering the exception details with customized template.
+    # @option params [Array<String>] :unsafe_options This can be used to specify options as strings that will be filtered from session and from request parameters
+    #   ( The options will not be displayed in the HTML template)
+    # @return [void]
     def initialize(options)
       super
       @initial_options = options.symbolize_keys.reject { |_key, value| value.blank? }
       parse_options(@initial_options)
     end
 
+    # Returns the asana client that will be used to connect to Asana API and sets the configuration for the client
+    # @see #faraday_configuration
+    #
+    # @return [Asana::Client] Returns the client used for connecting to Asana API's
     def asana_client
       @asana_client = Asana::Client.new do |config|
         config.authentication :access_token, asana_api_key
@@ -26,54 +72,107 @@ module ExceptionNotifier
       end
     end
 
+    # Returns the asana client that will be used to connect to Asana API
+    # @param [Asana::Configuration] config The configuration object that will be used to set the faraday adapter options for connecting to API's
+    #
+    # @return [void]
     def faraday_configuration(config)
       config.configure_faraday do |conn|
-        conn.request  :url_encoded
+        conn.request :url_encoded
         conn.response :logger
       end
     end
 
+    # When a exception is caught , this method will be called to publish to Asana the exception details
+    # In order not to block the main thread, while we are parsing the exception, and constructing the template date,
+    # and connecting to asana, this will spawn a new thread to ensure that the processing of the exception is deferred
+    # from the main thread.
+    # This method will also create the asana task after the processing of the exception and all the other data is gathered
+    # by the AsanaExceptionNotifier::ErrorPage class
+    #
+    #
+    # @see #ensure_thread_running
+    # @see #execute_with_rescue
+    # @see AsanaExceptionNotifier::ErrorPage#new
+    # @see #create_asana_task
+    #
+    # @param [Exception] exception The exception that was caught by the middleware
+    # @param [Hash] options Additional options that the middleware can send ( Default : {})
+    #
+    # @return [void]
     def call(exception, options = {})
       ensure_thread_running do
         execute_with_rescue do
-          EM::HttpRequest.use AsanaExceptionNotifier::Request::Middleware if ENV['DEBUG_ASANA_EXCEPTION_NOTIFIER']
           error_page = AsanaExceptionNotifier::ErrorPage.new(template_path, exception, options)
           create_asana_task(error_page) if active?
         end
       end
     end
 
+    # Method that is used to fetch the Asana api key from the default_options
+    #
+    # @return [String, nil] returns the asana api key if was provided in configuration, or nil otherwise
     def asana_api_key
       @default_options.fetch(:asana_api_key, nil)
     end
 
+    # Method that is used to fetch the workspace ID from the default_options
+    #
+    # @return [String, nil] returns the workspace ID if was provided in configuration, or nil otherwise
     def workspace
       @default_options.fetch(:workspace, nil)
     end
 
+    # Method that is used to fetch the notes from the default_options
+    #
+    # @return [String, nil] returns the notes if they were provided in configuration, or nil otherwise
     def notes
       @default_options.fetch(:notes, nil)
     end
 
+    # Method that is used to fetch the task name from the default_options
+    #
+    # @return [String, nil] returns the task name if was were provided in configuration, or nil otherwise
     def task_name
       @default_options.fetch(:name, nil)
     end
 
+    # Method that is used by the ExceptionNotifier gem to check if this notifier can be activated.
+    # The method checks if the asana api key and workspace ID were provided
+    #
+    # @return [Boolean] returns true if the asana api key and the workspace ID were provided in the configuration, otherwise false
     def active?
       asana_api_key.present? && workspace.present?
     end
 
+    # Method that retrieves the template_path for rendering the exception details
+    #
+    # @return [String, nil] returns the template_path if was were provided in configuration, or nil otherwise
     def template_path
       @default_options.fetch(:template_path, nil)
     end
 
   private
 
+    # Method that parses the options, and rejects keys that are not permitted , and values that are blank
+    # @see #permitted_options
+    #
+    # @param [Hash] options Additional options that are merged in the default options
+    #
+    # @return [void]
     def parse_options(options)
       options = options.reject { |key, _value| !permitted_options.key?(key) }
       @default_options = permitted_options.merge(options).reject { |_key, value| value.blank? }
     end
 
+    # Method that tries to render a custom notes template or the default notes template
+    # @see #path_is_a_template
+    # @see #expanded_path
+    # @see AsanaExceptionNotifier::ErrorPage#render_template
+    #
+    # @param [AsanaExceptionNotifier::ErrorPage] error_page the Erorr page class that is responsible for rendering the exception templates
+    #
+    # @return [String] The content of the notes templates after being rendered
     def note_content(error_page)
       if path_is_a_template?(notes)
         error_page.render_template(expanded_path(notes))
@@ -82,10 +181,22 @@ module ExceptionNotifier
       end
     end
 
+    # Returns the customized task name ( if any provided ) or the default one
+    #
+    # @param [AsanaExceptionNotifier::ErrorPage] error_page the Erorr page class that is responsible handling exceptions
+    #
+    # @return [String] The task name that will be used when creating the asana task
     def task_name_content(error_page)
       task_name.present? ? task_name : "[AsanaExceptionNotifier] #{error_page.exception_data[:message]}"
     end
 
+    # Builds all the options needed for creating a asana task
+    # @see #task_name_content
+    # @see #note_content
+    #
+    # @param [AsanaExceptionNotifier::ErrorPage] error_page the Erorr page class that is responsible handling exceptions
+    #
+    # @return [void]
     def build_request_options(error_page)
       @default_options.except(:asana_api_key, :template_path).merge(
         name: task_name_content(error_page),
@@ -94,7 +205,12 @@ module ExceptionNotifier
       ).symbolize_keys!
     end
 
+    # Method that is used to create the asana task and upload the log files to the task
+    # @see Asana::Resources::Task#create
+    # @see #build_request_options
+    # @see #upload_log_file_to_task
     #
+    # @param [AsanaExceptionNotifier::ErrorPage] error_page the Erorr page class that is responsible handling exceptions
     #
     # @return [void]
     def create_asana_task(error_page)
@@ -104,6 +220,15 @@ module ExceptionNotifier
       end
     end
 
+    # Method that is used to fetch all the needed archives that will be uploaded to the task
+    # and upload each of them
+    # @see AsanaExceptionNotifier::ErrorPage#fetch_all_archives
+    # @see #upload_archive
+    #
+    # @param [AsanaExceptionNotifier::ErrorPage] error_page the Erorr page class that is responsible handling exceptions
+    # @param [Asana::Resources::Task] task the task that was created, and needed to upload archives to the task
+    #
+    # @return [void]
     def upload_log_file_to_task(error_page, task)
       archives = error_page.fetch_all_archives
       archives.each do |zip|
@@ -111,6 +236,13 @@ module ExceptionNotifier
       end
     end
 
+    # Method that is used to upload an archive to a task, The file will be deleted after the upload finishes
+    # @see Asana::Resources::Task#attach
+    #
+    # @param [String] zip the file path to the archive that will be uploaded
+    # @param [Asana::Resources::Task] task the task that was created, and needed to upload archives to the task
+    #
+    # @return [void]
     def upload_archive(zip, task)
       return if task.blank?
       task.attach(

data/lib/asana_exception_notifier/classes/error_page.rb

@@ -3,11 +3,39 @@ require_relative '../helpers/application_helper'
 require_relative './unsafe_filter'
 module AsanaExceptionNotifier
   # class used for rendering the template for exception
+  #
+  # @!attribute [r] template_path
+  #   @return [Hash] The template_path that will be used to render the exception details
+  # @!attribute [r] exception
+  #   @return [Hash] The exception that will be parsed
+  # @!attribute [r] options
+  #   @return [Hash] Additional options sent by the middleware that will be used to provide additional informatio
+  # @!attribute [r] template_details
+  #   @return [Hash] The name and the extension of the template
+  # @!attribute [r] env
+  #   @return [Hash] The environment that was sent by the middleware or the ENV variable
+  # @!attribute [r] request
+  #   @return [Hash] The request that is built based on the environment, in order to provide more information
+  # @!attribute [r] tempfile
+  #   @return [Hash] The archive that will be created and then splitted into multiple archives (if needed )
+  # @!attribute [r] template_params
+  #   @return [Hash] The template params that will be sent to the template
   class ErrorPage
     include AsanaExceptionNotifier::ApplicationHelper
 
-    attr_reader :template_path, :exception, :options, :boundary, :template_details, :env, :request, :tempfile, :template_params, :content
+    attr_reader :template_path, :exception, :options, :template_details, :env, :request, :tempfile, :template_params
 
+    # Initializes the instance with the template path that will be used to render the template,
+    # the exception caught by the middleware and additional options sent by the middleware
+    # @see #html_template
+    # @see #setup_template_details
+    # @see #parse_exception_options
+    #
+    # @param [String] template_path The template_path that will be used to render the exception details
+    # @param [Exception] exception The exception that was caught by the middleware
+    # @param [Hash] options Additional options that the middleware can send ( Default : {})
+    #
+    # @return [void]
     def initialize(template_path, exception, options)
       @exception = exception
       @options = options.symbolize_keys
@@ -19,6 +47,15 @@ module AsanaExceptionNotifier
       parse_exception_options
     end
 
+    # Initializes the instance with the template path that will be used to render the template,
+    # the exception caught by the middleware and additional options sent by the middleware
+    # @see #path_is_a_template
+    # @see #expanded_path
+    # @see #template_dir
+    #
+    # @param [String] path The template_path that will be used to render the exception details
+    #
+    # @return [void]
     def html_template(path)
       @template_path = if path_is_a_template?(path)
                          expanded_path(path)
@@ -27,10 +64,18 @@ module AsanaExceptionNotifier
                        end
     end
 
+    # Returns true or false if ActionDispatch is available
+    #
+    # @return [Boolean] returns true if ActionDispatch::Request is defined, false otherwise
     def action_dispatch?
       defined?(ActionDispatch::Request)
     end
 
+    # Gets the name and the extension of the template path, if was provided custom
+    # ( this is needed in case someone wants something else than ERB template , since Tilt can support multiple formats)
+    # @see #get_extension_and_name_from_file
+    #
+    # @return [Hash] Returns a hash containing the name and the extension of the template
     def setup_template_details
       template_extension = @template_path.scan(/\.(\w+)\.?(.*)?/)[0][0]
       get_extension_and_name_from_file(@template_path).merge(
@@ -39,6 +84,19 @@ module AsanaExceptionNotifier
     end
 
     # :reek:TooManyStatements: { max_statements: 10 }
+    #
+    # Fetches information about request, exception, environment and other additional information needed for the template
+    # @see #fetch_basic_info
+    # @see #exception_data
+    # @see #setup_env_params
+    # @see #filter_params
+    # @see #session
+    # @see #request_params
+    # @see Rack::Request#cookies
+    # @see ActionDispatch::Request#filtered_env
+    # @see ActionDispatch::Request#filtered_parameters
+    #
+    # @return [Hash] Returns a hash containing all the information gathered about the exception, including env, cookies, session, and other additional information
     def parse_exception_options
       @template_params ||= {
         basic_info: fetch_basic_info,
@@ -54,10 +112,19 @@ module AsanaExceptionNotifier
       }.merge(@options).reject { |_key, value| value.blank? }
     end
 
+    # returns the session from the request, (either from ActionDispatch or from Rack)
+    #
+    # @return [Hash] Returns the session of the request
     def session
       @request.session
     end
 
+    # returns basic information about the system, like hostname, rails root directory, the process Id, the uname , the timestamp, and the Program name
+    # @see Socket#gethostname
+    # @see Rails::root
+    # @see Sys::Uname#uname
+    #
+    # @return [Hash] Returns basic information about the system, like hostname, and other additionl information
     def fetch_basic_info
       {
         server:  Socket.gethostname,
@@ -69,6 +136,9 @@ module AsanaExceptionNotifier
       }
     end
 
+    # returns information about the exception, like the class name, the message, the backtrace, the cause ( if gem 'cause' is used)
+    #
+    # @return [Hash] Returns information about the exception, like the class name, the message, the backtrace, the cause ( if gem 'cause' is used)
     def exception_data
       exception_service.merge(
         error_class: @exception.class.to_s,
@@ -78,6 +148,9 @@ module AsanaExceptionNotifier
       )
     end
 
+    # returns the instance variables defined by the exception, useful when using custom exceptions
+    #
+    # @return [Hash] Returns information about the instance variables defined by the exception, useful when using custom exceptions
     def exception_service
       hash = {}
       @exception.instance_variables.select do |ivar|
@@ -87,6 +160,9 @@ module AsanaExceptionNotifier
       hash
     end
 
+    # returns information about URL, referer, http_method used, ip address and user agent
+    #
+    # @return [Hash] Returns information about URL, referer, http_method used, ip address and user agent
     def setup_env_params
       {
         url: @request.respond_to?(:original_url) ? @request.original_url : @request.path_info,
@@ -97,25 +173,46 @@ module AsanaExceptionNotifier
       }
     end
 
+    # Filters sensitive information from parameters so that they won't get leaked into the template
+    # @see AsanaExceptionNotifier::UnsafeFilter#new
+    #
+    # @return [Hash] Returns the information filtered , by using custom filters or the default one
     def filter_params(params)
       AsanaExceptionNotifier::UnsafeFilter.new(params, @options.fetch(:unsafe_options, [])).arguments
     end
 
+    # returns the params sent with the initial request
+    #
+    # @return [Hash] Returns the params sent with the initial request
     def request_params
       @request.params
     rescue
       {}
     end
 
+    # returns the names that will be used on the table header in the template
+    # @see #fieldsets
+    # @see #link_helper
+    #
+    # @return [String] returns the names that will be used on the table header in the template
     def fieldsets_links
       fieldsets.map { |key, _value| link_helper(key.to_s) }.join(' | ')
     end
 
+    # returns fieldsets that will be showned in the template on separate table
+    # @see #mount_tables_for_fieldsets
+    #
+    # @return [Array<Hash>] returns fieldsets that will be showned in the template on separate table
     def fieldsets
       @fieldsets ||= mount_tables_for_fieldsets
       @fieldsets
     end
 
+    # returns fieldsets that will be showned in the template on separate table
+    # @see #fetch_fieldsets
+    # @see #mount_table_for_hash
+    #
+    # @return [Hash] returns the tables that will be used to render on the template as a Hash
     def mount_tables_for_fieldsets
       hash = fetch_fieldsets
       hash.each do |key, value|
@@ -125,6 +222,12 @@ module AsanaExceptionNotifier
       hash
     end
 
+    # iterates over the template params and sets the fieldsets that will be will be displayed in tables
+    # @see #set_fieldset_key
+    #
+    # @param [Hash] hash the hash that will contain the data will be displayed in tables
+    #
+    # @return [void]
     def build_template_params_hash(hash)
       @template_params.each_with_parent do |parent, key, value|
         next if value.blank? || key.blank?
@@ -133,17 +236,33 @@ module AsanaExceptionNotifier
       end
     end
 
+    # builds the template params that wil be used to construct the fieldsets and sorts them alphabetically
+    # @see #build_template_params_hash
+    #
+    # @param [Hash] hash the hash that will contain the template params that wil be used to construct the fieldsets sorted alphabetically
+    #
+    # @return [Hash] returns the hash that will contain the template params that wil be used to construct the fieldsets sorted alphabetically
     def fetch_fieldsets(hash = {})
       build_template_params_hash(hash)
       hash.keys.map(&:to_s).sort
       hash
     end
 
+    # adds the fieldsets and the fieldsets_links to the template params
+    # @see #fieldsets
+    # @see #fieldsets_links
+    #
+    # @return [void]
     def setup_template_params_for_rendering
       @template_params[:fieldsets] = fieldsets
       @template_params[:fieldsets_links] = fieldsets_links
     end
 
+    # renders the template or the default template with the template params
+    # @see #execute_with_rescue
+    # @see #setup_template_params_for_rendering
+    #
+    # @return [void]
     def render_template(template = nil)
       execute_with_rescue do
         current_template = template.present? ? template : @template_path
@@ -152,6 +271,14 @@ module AsanaExceptionNotifier
       end
     end
 
+    # Creates a archive from the render_template outpout and returns the filename and the path of the file
+    # @see Tempfile#new
+    # @see Tempfile#write
+    # @see ObjectSpace#undefine_finalizer
+    # @see Tempfile#close
+    # @see #tempfile_details
+    #
+    # @return [Array<String>] returns an array containing the filename as first value, and the path to the tempfile created as second value
     def create_tempfile(output = render_template)
       tempfile = Tempfile.new([SecureRandom.uuid, ".#{@template_details[:template_extension]}"], encoding: 'utf-8')
       tempfile.write(output)
@@ -160,20 +287,35 @@ module AsanaExceptionNotifier
       tempfile_details(tempfile).slice(:filename, :path).values
     end
 
+    # Executes the fetch_archives and returns the result or empty array in case of exception
+    # @see #fetch_archives
+    #
+    # @return [Array] returns an array with file paths to the created archives
     def fetch_all_archives
       fetch_archives
     rescue
       []
     end
 
+    # Creates the archive, compresses it , and then removes the temporary file and splits the archive if needed
+    # @see #create_tempfile
+    # @see #archive_files
+    # @see #remove_tempfile
+    # @see #split_archive
+    #
+    # @return [Array] returns an array with file paths to the created archives
     def fetch_archives(output = render_template)
       return [] if output.blank?
       filename, path = create_tempfile(output)
-      archive = compress_files(File.dirname(path), filename, [expanded_path(path)])
+      archive = archive_files(File.dirname(path), filename, [expanded_path(path)])
       remove_tempfile(path)
-      split_archive(archive, "part_#{filename}", 1024 * 1024 * 100)
+      split_archive(archive, "part_#{filename}", 1024 * 1024 * 100) # 104_857_600
     end
 
+    # If DEBUG_ASANA_TEMPLATE is present this method will only log the path , otherwise will remove the file.
+    # @param [String] path The path of the Tempfile that needs to be removed or logged
+    #
+    # @return [void]
     def remove_tempfile(path)
       if ENV['DEBUG_ASANA_TEMPLATE']
         logger.debug(path)

data/lib/asana_exception_notifier/classes/unsafe_filter.rb

@@ -2,16 +2,36 @@
 require_relative '../helpers/application_helper'
 module AsanaExceptionNotifier
   # class used to filter unsafe params
+  #
+  # @!attribute [r] arguments
+  #   @return [#delete] THe arguments that will be filtered
+  # @!attribute [r] unsafe_options
+  #   @return [Array<String>, Array<Symbol>] Additional unsafe options that will be used for filtering
   class UnsafeFilter
     include AsanaExceptionNotifier::ApplicationHelper
 
+    # the default options that are considered unsafe
     UNSAFE_OPTIONS = %w(
       password password_confirmation new_password new_password_confirmation
       old_password email_address email authenticity_token utf8
     ).freeze
 
-    attr_reader :arguments, :unsafe_options
+    # The arguments that will be filtered
+    # @return [#delete] THe arguments that will be filtered
+    attr_reader :arguments
 
+    # Additional unsafe options that will be used for filtering
+    # @return [Array<String>, Array<Symbol>] Additional unsafe options that will be used for filtering
+    attr_reader :unsafe_options
+
+    # Initializes the instance with the arguments that will be filtered and the additional unsafe options
+    # and starts filtering the arguments
+    # @see #remove_unsafe
+    #
+    # @param [#delete] arguments The arguments that will be filtered
+    # @param [Array<String>, Array<Symbol>] unsafe_options Additional unsafe options that will be used for filtering
+    #
+    # @return [void]
     def initialize(arguments, unsafe_options = [])
       @unsafe_options = unsafe_options.present? && unsafe_options.is_a?(Array) ? unsafe_options.map(&:to_s) : []
       @arguments = arguments.present? ? arguments : {}
@@ -20,6 +40,15 @@ module AsanaExceptionNotifier
 
   private
 
+    # Returns the arguments, if they are blank
+    # Otherwise first tries to remove attributes
+    # then the blank values, and then tries to remove any remaining unsafe from the remaining object
+    # @see #remove_blank
+    # @see #remove_unsafe_from_object
+    #
+    # @param [#delete] args The arguments that will be filtered
+    #
+    # @return [Object, nil]
     def remove_unsafe(args)
       return args if args.blank?
       args.delete(:attributes!)
@@ -28,6 +57,14 @@ module AsanaExceptionNotifier
       args
     end
 
+    # If arguments is a hash will try to remove any unsafe values
+    # otherwise will call the remove_unsafe to start removing from object
+    # @see #verify_unsafe_pair
+    # @see #remove_unsafe
+    #
+    # @param [#delete] args The arguments that will be filtered
+    #
+    # @return [Object, nil]
     def remove_unsafe_from_object(args)
       if args.is_a?(Hash)
         args.each_pair do |key, value|
@@ -38,10 +75,21 @@ module AsanaExceptionNotifier
       end
     end
 
+    # returns true if the key is included in the default unsafe options or in the custom ones, otherwise false
+    #
+    # @param [String] key The key that will be checked if is unsafe
+    #
+    # @return [Boolean] returns true if the key is included in the default unsafe options or in the custom ones, otherwise false
     def unsafe?(key)
       @unsafe_options.include?(key) || AsanaExceptionNotifier::UnsafeFilter::UNSAFE_OPTIONS.include?(key)
     end
 
+    # If the value is a hash, we start removing unsafe options from the hash, otherwise we check the key
+    # @see #unsafe?
+    # @param [String] key The key that will be checked if is unsafe
+    # @param [Object] value The value that will be checked if it is unsafe
+    #
+    # @return [void]
     def verify_unsafe_pair(key, value)
       case value
         when Hash

data/lib/asana_exception_notifier/helpers/application_helper.rb

@@ -8,6 +8,9 @@ module AsanaExceptionNotifier
 
   module_function
 
+    # returns the Hash containing as keys the permitted options and as values their default values
+    #
+    # @return [Hash] Returns the Hash containing as keys the permitted options and as values their default values
     def permitted_options
       {
         asana_api_key:  nil,
@@ -29,18 +32,28 @@ module AsanaExceptionNotifier
       }
     end
 
+    # returns the expanded path of a file path
+    #
+    # @param [String] path The file path that will be expanded
+    #
+    # @return [String]  returns the expanded path of a file path
     def expanded_path(path)
       File.expand_path(path)
     end
 
+    # checks to see if a path is valid
+    # @see #template_path_exist
+    # @param [String] path The file path that will be used
+    #
+    # @return [Boolean]  returns true if the path is valid otherwise false
     def path_is_a_template?(path)
-      path.present? && template_path_exist(expanded_path(path))
-    end
-
-    def multi_request_manager
-      @multi_manager ||= EventMachine::MultiRequest.new
+      path.present? && template_path_exist(path)
     end
 
+    # method used to extract the body of a IO object
+    # @param [IO] io The IO object that will be used
+    #
+    # @return [String]  returns the body of the IO object by rewinding it and reading the content, or executes inspect if a exception happens
     def extract_body(io)
       return unless io.respond_to?(:rewind)
       io.rewind
@@ -49,6 +62,11 @@ module AsanaExceptionNotifier
       io.inspect
     end
 
+    # method used to return the file and the path of a tempfile , along with the extension and the name of the file
+    # @see #get_extension_and_name_from_file
+    # @param [Tempfile] tempfile the temporary file that will be used
+    #
+    # @return [Hash] returns the the file and the path of a tempfile , along with the extension and the name of the file
     def tempfile_details(tempfile)
       file_details = get_extension_and_name_from_file(tempfile)
       {
@@ -59,39 +77,62 @@ module AsanaExceptionNotifier
 
     # Returns utf8 encoding of the msg
     # @param [String] msg
-    # @return [String] ReturnsReturns utf8 encoding of the msg
+    # @return [String] Returns utf8 encoding of the msg
     def force_utf8_encoding(msg)
       msg.respond_to?(:force_encoding) && msg.encoding.name != 'UTF-8' ? msg.force_encoding('UTF-8') : msg
     end
 
-    #  returns the logger used to log messages and errors
+    # returns the logger used to log messages and errors
     #
     # @return [Logger]
-    #
-    # @api public
     def logger
       @logger ||= (defined?(Rails) && rails_logger.present? ? rails_logger : ExceptionNotifier.logger)
       @logger = @logger.present? ? @logger : Logger.new(STDOUT)
     end
 
+    # returns the rails logger
+    #
+    # @return [Rails::Logger]
     def rails_logger
       Rails.logger
     end
 
+    # returns the newly created thread
+    # @see #run_new_thread
+    # @see Thread#abort_on_exception
+    # @param [Proc] &block the block that the new thread will execute
+    #
+    # @return [Thread] returns the newly created thread
     def ensure_thread_running(&block)
       Thread.abort_on_exception = true
       run_new_thread(&block)
     end
 
+    # method used to log exceptions
+    # @see #log_bactrace
+    # @param [Exception] exception the exception that will be used
+    #
+    # @return [void]
     def log_exception(exception)
       logger.debug exception.inspect
       log_bactrace(exception) if exception.respond_to?(:backtrace)
     end
 
+    # method used to log exception backtrace
+    # @param [Exception] exception the exception that will be used
+    #
+    # @return [void]
     def log_bactrace(exception)
       logger.debug exception.backtrace.join("\n")
     end
 
+    # method used to rescue exceptions
+    # @see #rescue_interrupt
+    # @see #log_exception
+    #
+    # @param [Hash] options Additional options used for returning values when a exception occurs, or empty string
+    #
+    # @return [String, nil, Object] Returns nil if the exception is a interrupt or a String empty if no value was provided in the options hash or the value from the options
     def execute_with_rescue(options = {})
       yield if block_given?
     rescue Interrupt
@@ -101,87 +142,165 @@ module AsanaExceptionNotifier
       options.fetch(:value, '')
     end
 
+    # method used to rescue from interrupt and show a message
+    #
+    # @return [void]
     def rescue_interrupt
       `stty icanon echo`
       puts "\n Command was cancelled due to an Interrupt error."
     end
 
+    # method used to create a thread and execute a block
+    # @see Thread#new
+    # @return [Thread] returns the newly created thread
     def run_new_thread
       Thread.new do
         yield if block_given?
       end.join
     end
 
+    # returns the templates directory
+    # @see #root
+    # @return [String] returns the path to the templates directory
     def template_dir
       File.expand_path(File.join(root, 'templates'))
     end
 
+    # returns true if file exists or false otherwise
+    #
+    # @see File#exist?
+    #
+    # @return [String] returns the path to the templates directory
     def template_path_exist(path)
-      File.exist?(path)
+      File.exist?(expanded_path(path))
     end
 
-    def get_hash_rows(hash, rows = [], _prefix = '')
+    # Method used to construct table rows from a Hash, by constructing an array of arrays with two elements ( First is the key and the value )
+    # This is useful for constructing the table, the number of elements in a array means the number of columns of the table
+    #
+    # This is a recursive function if the Hash contains other Hash values.
+    # @see #inspect_value
+    #
+    # @param [Hash] hash the Hash that wil be used to construct the array of arrays with two columns
+    # @param [Array<Array<String>>] rows This is the array that will contain the result ( Default: empty array).
+    #
+    # @return [Array<Array<String>>] Returns an array of arrays (with two elements), useful for printing tables from a Hash
+    def get_hash_rows(hash, rows = [])
       hash.each do |key, value|
         if value.is_a?(Hash)
-          get_object_rows(value, rows)
+          get_hash_rows(value, rows)
         else
-          rows.push([key.inspect, escape(inspect_value(value).inspect)])
+          rows.push([inspect_value(key), inspect_value(value)])
         end
       end
       rows
     end
 
+    # Method used to inspect a value, by checking if is a IO object, and in that case extract the body from the IO object,
+    # otherwise will just use the "inpspect" method. The final result will be escaped so that it can be printed in HTML
+    # @see #extract_body
+    # @see #escape
+    #
+    # @param [#inspect, #to_s] value The value that will be inspected and escaped
+    #
+    # @return [String] Returns the value inspected and escaped
     def inspect_value(value)
-      value.is_a?(IO) ? extract_body(value) : value
+      inspected_value = value.is_a?(IO) ? extract_body(value) : value.inspect
+      escape(inspected_value)
     end
 
+    # Method used to escape a text by escaping some characters like '&', '<' and '>' , which could affect HTML format
+    # @param [#to_s] text The text that will be escaped
+    #
+    # @return [String] Returns the text HTML escaped
     def escape(text)
-      text.gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;')
+      text.to_s.gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;')
     end
 
+    # Method used to set the prefix name on the links Hash, this is needed when building a table from a hash,
+    # because when going through the first level of a Hash, we don't have a title of what this level is about ,
+    # but deeper levels can have a title, by using the key to which the value is associated
+    #
+    # Because of this this method expects a default name, in case the prefix is blank
+    # @param [Hash] links The links Hash object that will be used to print the fieldsets links in HTML template
+    # @param [String] prefix The prefix that will be set as key on the links Hash and associated with a empty Hash , if the links hash does not have this key yet
+    # @param [String] default The default prefix that will be set as key on the links Hash and associated with a empty Hash , if the links hash does not have this key yet and the prefix is blank
+    #
+    # @return [String] Returns the prefix that was used to set the key on the links Hash, either the 'prefix' variable or the 'default' variable
     def set_fieldset_key(links, prefix, default)
       prefix_name = prefix.present? ? prefix : default
       links[prefix_name] ||= {}
       prefix_name
     end
 
-    # Mount table for hash, using name and value and adding a name_value class
-    # to the generated table.
+    # This method is used to mount a table from a hash. After the table is mounted, since the generated table has two columns ( Array of array with two elements),
+    # We're going to prepend to this generated table a array with two elements (Name and Value) , which will be the columns headers on the generated table .
+    # We also will add a HTML class attribute to the generated table ('name_values')
+    # @see #get_hash_rows
+    # @see #mount_table
     #
+    # @param [Hash] hash The Hash that will be used to mount a table from the keys and values
+    # @param [Hash] options Additional options that will be used to set HTML attributes on the generated table
+    #
+    # @return [String] Returns the HTML table generated as a string, which can be printed anywhere
     def mount_table_for_hash(hash, options = {})
       return if hash.blank?
       rows = get_hash_rows(hash, options.fetch('rows', []))
       mount_table(rows.unshift(%w(Name Value)), { class: 'name_values' }.merge(options))
     end
 
+    # This method receives a options list which will be used to construct a string which will be used to set HTML attributes on a HTML element
+    #
+    # @param [Hash] hash The Hash that will be used to construct the string of HTML attributes
+    #
+    # @return [String] Returns the string of HTML attributes which can be used on any HTML element
     def hash_to_html_attributes(hash)
       hash.map do |key, value|
         "#{key}=\"#{value.gsub('"', '\"')}\" "
       end.join(' ')
     end
 
+    # This method can receive either a Hash or an Array, which will be filtered of blank values
+    #
+    # @param [Hash, Array] args The Hash or the array which will be used for filtering blank values
+    #
+    # @return [Hash, Array] Returns the Hash or the array received , filtered of blank values
     def remove_blank(args)
       args.delete_if { |_key, value| value.blank? } if args.is_a?(Hash)
       args.reject!(&:blank?) if args.is_a?(Array)
     end
 
+    # This method is used to construct the Th header elements that can be used on HTML table from a array, by humanizing and escaping the values
+    # @see #escape
+    #
+    # @param [#map] header the Header array that will be used to construct the Th header elements that can be used on HTML table
+    #
+    # @return [String] Returns the HTML th elements constructed from the array , that can be used on a HTML table
     def get_table_headers(header)
       header.map { |name| escape(name.to_s.humanize) }.join('</th><th>')
     end
 
+    # This method is to construct a HTML row for each value that exists in the array, each value from the array is a array itself.
+    # The row is constructed by joining the values from each array with td element, so the result will be a valid HTML row element
+    # The final result is a concatenation of multiple row elements that can be displayed inside a tbody element from a HTML table
+    # @param [#map] array The Array that will be used to construct the inner rows of a HTML table
+    #
+    # @return [String] Returns a concatenation of multiple HTML tr and td elements that are in fact the inner rows of HTML table
     def get_table_rows(array)
       array.map { |name| "<tr><td>#{name.join('</td><td>')}</td></tr>" }.join
     end
 
-    # returns the root path of the gem
-    #
-    # @return [void]
+    # returns the root path of the gem ( the lib directory )
     #
-    # @api public
+    # @return [String] Returns the root path of the gem ( the lib directory )
     def root
       File.expand_path(File.dirname(__dir__))
     end
 
+    # returns the extension of the file, the filename and the file path of the Tempfile file received as argument
+    # @param [Tempfile] tempfile the Tempfile that will be used
+    #
+    # @return [Hash] returns the extension of the file, the filename and the file path of the Tempfile file received as argument
     def get_extension_and_name_from_file(tempfile)
       path = tempfile.respond_to?(:path) ? tempfile.path : tempfile
       pathname = Pathname.new(path)
@@ -193,6 +312,13 @@ module AsanaExceptionNotifier
       }
     end
 
+    # Splits a archive into multiple archives if the size of the archive is greater than the segment_size received as argument
+    # and returns a array that contains the paths to each of the archives that were resulted after splitting
+    # @param [::Zip::File] archive the archive that will try to be splitted
+    # @param [String] partial_name the partial name that will be used when splitting the archives
+    # @param [Integer] segment_size the size that will be used for splitting the archive
+    #
+    # @return [Array<String>] returns a array that contains the paths to each of the archives that were resulted after splitting
     def split_archive(archive, partial_name, segment_size)
       indexes = Zip::File.split(archive, segment_size, true, partial_name)
       archives = Array.new(indexes) do |index|
@@ -201,21 +327,42 @@ module AsanaExceptionNotifier
       archives.blank? ? [archive] : archives
     end
 
-    def compress_files(directory, name, files)
-      archive = create_archive(directory, name)
+    # This method receives multiple files, that will be added to a archive and will return the resulting archive
+    # @see #prepare_archive_creation
+    # @see #add_files_to_zip
+    # @see Zip::File::open
+    #
+    # @param [String] directory The directory where the archive will be created
+    # @param [String] name The name of the archive ( without the .zip extension )
+    # @param [Array<File>] files The Array of files that will be added to the archive
+    #
+    # @return [Zip::File] returns the archive that was created after each of the files were added to the archive and compressed
+    def archive_files(directory, name, files)
+      archive = prepare_archive_creation(directory, name)
       ::Zip::File.open(archive, Zip::File::CREATE) do |zipfile|
         add_files_to_zip(zipfile, files)
       end
       archive
     end
 
+    # This method receives multiple files, that will be added to a archive
+    # @param [::Zip::File] zipfile The archive that will be used to add files to it
+    # @param [Array<File>] files The Array of files that will be added to the archive
+    #
+    # @return [void]
     def add_files_to_zip(zipfile, files)
       files.each do |file|
         zipfile.add(file.sub(File.dirname(file) + '/', ''), file)
       end
     end
 
-    def create_archive(directory, name)
+    # This method prepares the creation of a archive, by making sure that the directory is created and
+    # if the archive already exists, will be removed, and the path to where this archive needs to be created will be returned
+    # @param [String] directory The directory where the archive should be created
+    # @param [String] name The name of the archive ( without the .zip extension )
+    #
+    # @return [String] returns the path to where this archive needs to be created
+    def prepare_archive_creation(directory, name)
       archive = File.join(directory, name + '.zip')
       archive_dir = File.dirname(archive)
       FileUtils.mkdir_p(archive_dir) unless File.directory?(archive_dir)

data/lib/asana_exception_notifier/helpers/heredoc_helper.rb

@@ -4,6 +4,10 @@ module AsanaExceptionNotifier
   module HeredocHelper
   module_function
 
+    # This method creates a HTML link , that when will be clicked will trigger the toggle of a fieldset, by either making it hidden or visible
+    # @param [String] link The link id of the fieldset that will be toggled when the resulting HTML link will be clicked
+    #
+    # @return [String] returns HTML link that will be used to toggle between fieldsets
     def link_helper(link)
       <<-HTML
       <a href="javascript:void(0)" onclick="AjaxExceptionNotifier.hideAllAndToggle('#{link.downcase}')">#{link.camelize}</a>
@@ -12,13 +16,16 @@ module AsanaExceptionNotifier
 
     # Gets a bidimensional array and create a table.
     # The first array is used as label.
+    # @param [Array<Array<String>>] array The array of arrays of strings that will be used for constructing the HTML table
+    # @param [Hash] options The options list that will be used to construct the HTML attributes on the HTML table
     #
+    # @return [String] returns the HTML table that was generated from the received array
     def mount_table(array, options = {})
       header = array.extract_options!
       <<-HTML
       <table #{hash_to_html_attributes(options)}>
-      <thead><tr><th>#{get_table_headers(header)}</th></tr></thead>
-      <tbody>#{get_table_rows(array)}</tbody>
+        <thead><tr><th>#{get_table_headers(header)}</th></tr></thead>
+        <tbody>#{get_table_rows(array)}</tbody>
       </table>
       HTML
     end

data/lib/asana_exception_notifier/initializers/hash.rb

@@ -1,6 +1,30 @@
 # frozen_string_literal: true
 # override Hash class
 class Hash
+  # This method is used for iterating over a Hash , but besides yielding the key and the value, this will also yield the parent
+  # key of the current Hash object if the Hash is associated to a key
+  #
+  # @example Printing a Hash that contains other hashes inside, and fetching the parent keys
+  #  hash = {
+  #           key: :my_value,
+  #           key2: {
+  #             innner_key: :inner_value
+  #           }
+  #         }
+  #   hash.each_with_parent { |parent, key, value| puts [parent, key, value].inspect }
+  #   will print:
+  #       [nil, :key, :my_value]
+  #       [:key2, :innner_key, :inner_value]
+  #
+  # @see #deep_hash_with_parent
+  #
+  # @param [String, nil] parent The parent key of the current level of the Hash
+  #   ( first level of any Hash has no parent, but if the hash has a value which is also a Hash,
+  #   the parent of that value will be the key associated to the value )
+  # @param [Proc] &block The block which will be used to yield the parent string, the current key and the value,
+  #   while the Hash is being iterated over
+  #
+  # @return [void]
   def each_with_parent(parent = nil, &block)
     each do |key, value|
       if value.is_a?(Hash)
@@ -11,7 +35,17 @@ class Hash
     end
   end
 
+  # Checks if the value is a Hash , and will execute the each with parent for the given hash
+  # @see #each_with_parent
+  #
+  # @param [Hash] value The Hash that will be used for iteration
+  # @param [Hash] key The key that will be sent as the parent key of the specified Hash
+  # @param [Proc] &block The block which will be used to yield the parent string, the current key and the value,
+  #   while the Hash is being iterated over
+  #
+  # @return [void]
   def deep_hash_with_parent(value, key, &block)
+    return unless value.is_a?(Hash)
     value.each_with_parent(key, &block)
   end
 end

data/lib/asana_exception_notifier/initializers/zip.rb

@@ -1,15 +1,43 @@
 # frozen_string_literal: true
 Zip.setup do |c|
+  # By default, rubyzip will not overwrite files if they already exist inside of the extracted path.
+  # To change this behavior, you may specify a configuration option like so:
   c.on_exists_proc = true
+  # Additionally, if you want to configure rubyzip to overwrite existing files while creating a .zip file, you can do so with the following:
   c.continue_on_exists_proc = true
+  # If you want to store non-english names and want to open them on Windows(pre 7) you need to set this option: ( We don't want that)
   c.unicode_names = false
+  # Some zip files might have an invalid date format, which will raise a warning. You can hide this warning with the following setting:
+  c.warn_invalid_date = false
+  # You can set the default compression level like so: Possible values are Zlib::BEST_COMPRESSION, Zlib::DEFAULT_COMPRESSION and Zlib::NO_COMPRESSION
   c.default_compression = Zlib::BEST_COMPRESSION
+  # To save zip archives in sorted order like below, you need to set ::Zip.sort_entries to true
+  c.sort_entries = true
 end
 
-Zip::File.class_eval do
-  singleton_class.send(:alias_method, :original_get_segment_size_for_split, :get_segment_size_for_split)
-
-  def self.get_segment_size_for_split(segment_size)
-    segment_size
-  end
-end
+# Zip::File.class_eval do
+#   singleton_class.send(:alias_method, :original_get_segment_size_for_split, :get_segment_size_for_split)
+#
+#   # This method was overidden from the original method that contained this code
+#   #   case
+#   #      when MIN_SEGMENT_SIZE > segment_size
+#   #        MIN_SEGMENT_SIZE
+#   #      when MAX_SEGMENT_SIZE < segment_size
+#   #          MAX_SEGMENT_SIZE
+#   #      else
+#   #        segment_size
+#   #      end
+#   # where
+#   #  MAX_SEGMENT_SIZE     = 3_221_225_472 (1024 * 1024 * 1024 * 3)
+#   #  MIN_SEGMENT_SIZE     = 65_536 (1024 * 64)
+#   #
+#   # Because if you wanted to split a archive using a smaller size than the minimum size, it wouldn't be possible
+#   # because will always return the minimum size which is 64 Kb
+#   #
+#   # @param [Integer] segment_size the size that will be used to split an archive called by the Zip::File.split method
+#   #
+#   # @return [Integer] returns the size that will be used for splitting an archive
+#   def self.get_segment_size_for_split(segment_size)
+#     segment_size
+#   end
+# end

data/lib/asana_exception_notifier/version.rb

@@ -16,7 +16,7 @@ module AsanaExceptionNotifier
     # major release version
     MAJOR = 0
     # minor release version
-    MINOR = 4
+    MINOR = 5
     # tiny release version
     TINY = 0
     # prelease version ( set this only if it is a prelease)

data/lib/asana_exception_notifier.rb

@@ -22,6 +22,7 @@ require 'exception_notification'
 require 'asana'
 require 'typhoeus'
 require 'typhoeus/adapters/faraday'
+require 'faraday_middleware'
 
 require 'rack'
 require 'zip'

data/lib/generators/asana_exception_notifier/install_generator.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 module AsanaExceptionNotifier
+  # module that defines the available generators for this gem
   module Generators
     # module that is used for formatting numbers using metrics
     class InstallGenerator < Rails::Generators::Base
@@ -7,6 +8,9 @@ module AsanaExceptionNotifier
 
       source_root File.expand_path('../templates', __FILE__)
 
+      # This method will copy the template from this gem into the `config/initializers/asana_exception_notifier.rb` file in the application
+      #
+      # @return [void]
       def copy_initializer
         template 'asana_exception_notifier.rb', 'config/initializers/asana_exception_notifier.rb'
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asana_exception_notifier
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - bogdanRada
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-08 00:00:00.000000000 Z
+date: 2016-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport