Merge pull request #56 from airbrake/53-refactor-filtering-api

Refactor Airbrake.blacklist/whitelist_keys to be an option

CHANGELOG.md

@@ -3,6 +3,23 @@ Airbrake Ruby Changelog
 
 ### master
 
+* **IMPORTANT:** changed public API of blacklist and whitelist filters. Instead
+  of `Airbrake.blacklist_keys` and `Airbrake.whitelist_keys` please use the
+  respective new config options
+  ([#56](https://github.com/airbrake/airbrake-ruby/pull/56)):
+
+  ```ruby
+  # v1.1.0 and older
+  Airbrake.blacklist_keys([:password, /credit/i])
+  Airbrake.whitelist_keys([:page_id, 'user'])
+
+  # New way
+  Airbrake.configure do |c|
+    c.blacklist_keys = [:password, /credit/i]
+    c.whitelist_keys = [:page_id, 'user']
+  end
+  ```
+
 * Started filtering the context payload
   ([#55](https://github.com/airbrake/airbrake-ruby/pull/55))
 * Fixed bug when similar keys would be filtered out using non-regexp values for

README.md

@@ -258,6 +258,64 @@ Airbrake.configure do |c|
 end
 ```
 
+#### blacklist_keys
+
+Specifies which keys in the payload (parameters, session data, environment data,
+etc) should be filtered. Before sending an error, filtered keys will be
+substituted with the `[Filtered]` label.
+
+It accepts Strings, Symbols & Regexps, which represent keys of values to be
+filtered.
+
+```ruby
+Airbrake.configure do |c|
+  c.blacklist_keys = [:email, /credit/i, 'password']
+end
+
+Airbrake.notify('App crashed!', {
+  user: 'John',
+  password: 's3kr3t',
+  email: '[email protected]',
+  credit_card: '5555555555554444'
+})
+
+# The dashboard will display this parameter as filtered, but other values won't
+# be affected:
+#   { user: 'John',
+#     password: '[Filtered]',
+#     email: '[Filtered]',
+#     credit_card: '[Filtered]' }
+```
+
+#### whitelist_keys
+
+Specifies which keys in the payload (parameters, session data, environment data,
+etc) should _not_ be filtered. All other keys will be substituted with the
+`[Filtered]` label.
+
+It accepts Strings, Symbols & Regexps, which represent keys the values of which
+shouldn't be filtered.
+
+```ruby
+Airbrake.configure do |c|
+  c.whitelist_keys = [:email, /user/i, 'account_id']
+end
+
+Airbrake.notify(StandardError.new('App crashed!'), {
+  user: 'John',
+  password: 's3kr3t',
+  email: '[email protected]',
+  account_id: 42
+})
+
+# The dashboard will display this parameter as is, but all other values will be
+# filtered:
+#   { user: 'John',
+#     password: '[Filtered]',
+#     email: '[email protected]',
+#     account_id: 42 }
+```
+
 ### Asynchronous Airbrake options
 
 The options listed below apply to [`Airbrake.notify`](#airbrakenotify), they do
@@ -382,56 +440,6 @@ Airbrake.add_filter(MyFilter.new)
 The library provides two default filters that you can use to filter notices:
 [KeysBlacklist][keysblacklist] & [KeysWhitelist][keyswhitelist].
 
-##### The KeysBlacklist filter
-
-The KeysBlacklist filter filters specific keys (parameters, session data,
-environment data). Before sending the notice, filtered keys will be substituted
-with the `[Filtered]` label.
-
-It accepts Strings, Symbols & Regexps, which represent keys to be filtered.
-
-```ruby
-Airbrake.blacklist_keys([:email, /credit/i, 'password'])
-Airbrake.notify('App crashed!', {
-  user: 'John',
-  password: 's3kr3t',
-  email: '[email protected]',
-  credit_card: '5555555555554444'
-})
-
-# The dashboard will display this parameter as filtered, but other values won't
-# be affected:
-#   { user: 'John',
-#     password: '[Filtered]',
-#     email: '[Filtered]',
-#     credit_card: '[Filtered]' }
-```
-
-##### The KeysWhitelist filter
-
-The KeysWhitelist filter allows you to specify which keys should not be
-filtered. All other keys will be substituted with the `[Filtered]` label.
-
-It accepts Strings, Symbols & Regexps, which represent keys the values of which
-shouldn't be filtered.
-
-```ruby
-Airbrake.whitelist([:email, /user/i, 'account_id'])
-Airbrake.notify(StandardError.new('App crashed!'), {
-  user: 'John',
-  password: 's3kr3t',
-  email: '[email protected]',
-  account_id: 42
-})
-
-# The dashboard will display this parameter as is, but all other values will be
-# filtered:
-#   { user: 'John',
-#     password: '[Filtered]',
-#     email: '[email protected]',
-#     account_id: 42 }
-```
-
 #### Airbrake.build_notice
 
 Builds an [Airbrake notice][notice-v3]. This is useful, if you want to add or

lib/airbrake-ruby.rb

@@ -196,6 +196,7 @@ def add_filter(filter = nil, notifier = :default, &block)
     # @return [void]
     # @since v5.0.0
     # @see .blacklist_keys
+    # @deprecated Please use {Airbrake::Config#whitelist_keys} instead
     def whitelist_keys(keys, notifier = :default)
       call_notifier(notifier, __method__, keys)
     end
@@ -213,6 +214,7 @@ def whitelist_keys(keys, notifier = :default)
     # @return [void]
     # @since v5.0.0
     # @see .whitelist_keys
+    # @deprecated Please use {Airbrake::Config#blacklist_keys} instead
     def blacklist_keys(keys, notifier = :default)
       call_notifier(notifier, __method__, keys)
     end

lib/airbrake-ruby/config.rb

@@ -57,6 +57,18 @@ class Config
     # @return [Integer] The HTTP timeout in seconds.
     attr_accessor :timeout
 
+    ##
+    # @return [Array<String, Symbol, Regexp>] the keys, which should be
+    #   filtered
+    # @since 1.2.0
+    attr_accessor :blacklist_keys
+
+    ##
+    # @return [Array<String, Symbol, Regexp>] the keys, which shouldn't be
+    #   filtered
+    # @since 1.2.0
+    attr_accessor :whitelist_keys
+
     ##
     # @param [Hash{Symbol=>Object}] user_config the hash to be used to build the
     #   config
@@ -76,6 +88,9 @@ def initialize(user_config = {})
 
       self.timeout = user_config[:timeout]
 
+      self.blacklist_keys = []
+      self.whitelist_keys = []
+
       merge(user_config)
     end
 

lib/airbrake-ruby/notifier.rb

@@ -7,6 +7,10 @@ module Airbrake
   # @api private
   # @since v5.0.0
   class Notifier
+    ##
+    # @return [String] the label to be prepended to the log output
+    LOG_LABEL = '**Airbrake:'.freeze
+
     ##
     # Creates a new Airbrake notifier with the given config options.
     #
@@ -31,6 +35,15 @@ def initialize(user_config)
       end
 
       @filter_chain = FilterChain.new(@config)
+
+      if @config.blacklist_keys.any?
+        add_filter(Filters::KeysBlacklist.new(*@config.blacklist_keys))
+      end
+
+      if @config.whitelist_keys.any?
+        add_filter(Filters::KeysWhitelist.new(*@config.whitelist_keys))
+      end
+
       @async_sender = AsyncSender.new(@config)
       @sync_sender = SyncSender.new(@config)
     end
@@ -60,13 +73,23 @@ def add_filter(filter = nil, &block)
 
     ##
     # @macro see_public_api_method
+    # @deprecated Please use {Airbrake::Config#whitelist_keys} instead
     def whitelist_keys(keys)
+      @config.logger.warn(
+        "#{LOG_LABEL} Airbrake.whitelist_keys is deprecated. Please use the " \
+        "whitelist_keys option instead (https://goo.gl/sQwpYN)"
+      )
       add_filter(Filters::KeysWhitelist.new(*keys))
     end
 
     ##
     # @macro see_public_api_method
+    # @deprecated Please use {Airbrake::Config#blacklist_keys} instead
     def blacklist_keys(keys)
+      @config.logger.warn(
+        "#{LOG_LABEL} Airbrake.blacklist_keys is deprecated. Please use the " \
+        "blacklist_keys option instead (https://goo.gl/jucrFt)"
+      )
       add_filter(Filters::KeysBlacklist.new(*keys))
     end
 

spec/config_spec.rb

@@ -66,6 +66,14 @@
       it "doesn't set default timeout" do
         expect(config.timeout).to be_nil
       end
+
+      it "doesn't set default blacklist" do
+        expect(config.blacklist_keys).to be_empty
+      end
+
+      it "doesn't set default whitelist" do
+        expect(config.whitelist_keys).to be_empty
+      end
     end
   end
 end