immutable_struct_ex_redactable 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f17e2eaa97e190007e9d795ffd67d994b95fad1f31e6ba1cac068bed1f1738a
-  data.tar.gz: 395fddfefe67e8271bf01fd7440c322d92055b97b234de76c3e4242f40c5bb18
+  metadata.gz: d52c752fa013e9231b263b7f0395f2d6713ce627bd42c9c7bb664c47030d6a58
+  data.tar.gz: 17a8fe47bf9b7890d38075ac82d25fdd0aae91b2eb824a25636bbf9116f8900a
 SHA512:
-  metadata.gz: 4a246e5fb6044949e70b56371faed89913d574588e21a989178e51b388609fe85af9bc0c8c9634afa3d6dff5bc0fe94f9288c769fcea708cd790ae4ab6623811
-  data.tar.gz: 7882512c517e1d1c6ec649cda8654687675c042a96f7e1976e2dd112b1d67dcdcb23cdb70540197367b03b5a689b998325959b2e99ec22e4dcac637f44890613
+  metadata.gz: e89673ded8ec3cdd8517914aab113b61e65c5f2b4b8b3deaeb729cc61381c2b43e4e6502a81d90fc64427ddf4cda426b4252bbd1dc1dad5f584b2b169dd4010c
+  data.tar.gz: 70e2d85a032dae78691435c3a01b749d15fdaa4c28b944887eef8384813ffe509967032d2d4100e83870f5dcc31e149e201e65b9279e5ac40a59da1c3fd37262

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [1.3.0] - 2023-09-03
+
+Changes
+
+- `ImmutableStructExRedactable::Configuration#whitelist` is now supported. Attributes added to #whitelist will not be redacted. All other attributes will be redacted.
+- `ImmutableStructExRedactable::Configuration#redacted` will be deprecated in a future release. Please use `ImmutableStructExRedactable::Configuration#blacklist` instead.
+
 ## [1.2.2] - 2023-08-29
 
 Changes

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    immutable_struct_ex_redactable (1.2.2)
+    immutable_struct_ex_redactable (1.3.0)
       immutable_struct_ex (~> 1.0, >= 1.0.1)
 
 GEM
@@ -13,7 +13,7 @@ GEM
     coderay (1.1.3)
     diff-lcs (1.5.0)
     docile (1.4.0)
-    immutable_struct_ex (1.0.1)
+    immutable_struct_ex (1.0.2)
     json (2.6.3)
     kwalify (0.7.2)
     language_server-protocol (3.17.0.3)

data/README.md

@@ -15,10 +15,9 @@
 
 `immutable_struct_ex_redactable` is the *redactable version* of the world-famous *immutable_struct_ex* immutable struct :). To find out more about the *immutable_struct_ex* gem, visit the Rubygems.org entry for [immutable_struct_ex](https://rubygems.org/gems/immutable_struct_ex).
 
-`immutable_struct_ex_redactable` maintains all the functionality of the *immutable_struct_ex* gem, but allows you to create immutable structs that can be configured to redact field values using standard gem configuration (`ImmutableStructExRedactable.configure { |config| ... }`) or by passing configuration options to the appropriate method (`ImmutableStructExRedactable.create_with(config, ...)`)
+`immutable_struct_ex_redactable` maintains all the functionality of the *immutable_struct_ex* gem, but allows you to create immutable structs that can be configured to redact field values using standard gem configuration (`ImmutableStructExRedactable.configure { |config| ... }`) or by passing configuration options to the appropriate method (`ImmutableStructExRedactable.create_with(config, ...)`).
 
-### Future Enhancements
-- Future functionality will probably accept regex pattern for redacting field values (e.g. 'gen***@***.com').
+NOTE: both **whitelisting** and **blacklisting** are supported.
 
 ## Usage
 
@@ -28,11 +27,12 @@ Follow the instructions for [Installation](#installation) first, to incorporate
 
 #### Configure Gem Global Defaults
 
-*immutable_struct_ex_redactable*, by default, will redact fields named `:password` using the redacted label `"******"`. This will not meet your needs in all circumstances most likely. If this is *not* the case, you may change the default redactable fields and redactable label by changing the *immutable_struct_ex_redactable* configuration as follows:
+*immutable_struct_ex_redactable*, by default, will redact fields named `:password` using the redacted label `"******"`. This will not meet your needs in all circumstances most likely. If this is *not* the case, you may change the fields that are redacted and the redactable label by changing the *immutable_struct_ex_redactable* configuration via the `#whitelist` or `#blacklist` configuration options:
 
+##### Using a whitelist
 ```ruby
 ImmutableStructExRedactable::configure do |config|
-  config.redacted = %i[password dob ssn phone]
+  config.whitelist = %i[first last]
   config.redacted_label = '[REDACTED]'
 end
 
@@ -55,7 +55,34 @@ fields = {
 
 ImmutableStructExRedactable.create(**fields)
 => #<struct  first="Jane", last="Smith", password="[REDACTED]", dob="[REDACTED]">
+```
+
+##### Using a blacklist
+```ruby
+ImmutableStructExRedactable::configure do |config|
+  config.blacklist = %i[password dob ssn phone]
+  config.redacted_label = '[REDACTED]'
+end
+
+fields = {
+  first: 'John',
+  last: 'Smith',
+  password: 'p@ssw0rd',
+  dob: '1986-05-12'
+}
 
+ImmutableStructExRedactable.create(**fields)
+=> #<struct  first="John", last="Smith", password="[REDACTED]", dob="[REDACTED]">
+
+fields = {
+  first: 'Jane',
+  last: 'Smith',
+  password: 'h3l10W04lD',
+  dob: '1990-12-26'
+}
+
+ImmutableStructExRedactable.create(**fields)
+=> #<struct  first="Jane", last="Smith", password="[REDACTED]", dob="[REDACTED]">
 ```
 
 NOTE: Setting the global defaults in the above manner will affect **every** *immutable_struct_ex_redactable* struct instance you create unless you override the global configuration options, by passing a custom configuration.
@@ -67,7 +94,7 @@ To override the global configuration options, you may do so by calling the `Immu
 ```ruby
 # Create a custom configuration with the options you want to use.
 custom_config = ImmutableStructExRedactable::Configuration.new.tap do |config|
-  config.redacted = %i[password dob]
+  config.whitelist = %i[first last]
   config.redacted_label = '[NO WAY JOSE]'
 end
 
@@ -85,7 +112,7 @@ ImmutableStructExRedactable.create_with(custom_config, **fields)
 
 ### Access to the Original Redacted Field Values
 
-By default, *immutable_struct_ex_redactable* **will not** allow access to redacted field values; that is, field values marked for redaction via the global configuration (`ImmutableStructExRedactable::Configuration#redacted`) or by overriding the global configuration by passing a custom configuration (`ImmutableStructExRedactable.create_with(my_config, ...)`). However, if you really *need* access to redacted field values in their original, *un*redacted form, you can turn on the `ImmutableStructExRedactable::Configuration#redacted_unsafe` option in the global configuration or turn this same option on when passing a custom configuration. Turning the `redacted_unsafe` configuration option on in either scenario will instruct *immutable_struct_ex_redactable* to create *private methods* on structs created that will allow access to the original *un*redacted field values via `send:`. The *private methods* created that will allow access to the original *un*redacted field values, will have the following naming convention:
+By default, *immutable_struct_ex_redactable* **will not** allow access to redacted field values; that is, field values marked for redaction via the global configuration (`ImmutableStructExRedactable::Configuration#whitelist/#blacklist`) or by overriding the global configuration by passing a custom configuration (`ImmutableStructExRedactable.create_with(my_config, ...)`). However, if you really *need* access to redacted field values in their original, *un*redacted form, you can turn on the `ImmutableStructExRedactable::Configuration#redacted_unsafe` option in the global configuration or turn this same option on when passing a custom configuration. Turning the `redacted_unsafe` configuration option on in either scenario will instruct *immutable_struct_ex_redactable* to create *private methods* on structs created that will allow access to the original *un*redacted field values via `send:`. The *private methods* created that will allow access to the original *un*redacted field values, will have the following naming convention:
 
 ```ruby
 unredacted_<redacted field>
@@ -97,6 +124,7 @@ For example:
 
 ```ruby
 custom_config = ImmutableStructExRedactable::Configuration.new.tap do |config|
+  config.whitelist = %i[username]
   config.redacted_unsafe = true
 end
 
@@ -119,7 +147,6 @@ struct.send :unredacted_password
 
 struct.to_h_unredacted
 #=> {:username=>"jsmith", :password=>"p@ssw0rd"}
-
 ```
 
 ### &blocks are Permitted
@@ -165,7 +192,7 @@ class MyRedactableImmutableStruct
 
   def config
     @config ||= ImmutableStructExRedactable::Configuration.new.tap do |config|
-      config.redacted = %i[password]
+      config.whitelist = %i[username]
       config.redacted_label = 'xxxxxx'
     end
   end

data/lib/immutable_struct_ex_redactable/configuration.rb

@@ -24,12 +24,21 @@ module ImmutableStructExRedactable
   # This class encapsulates the configuration properties for this gem and
   # provides methods and attributes that allow for management of the same.
   class Configuration
-    # Gets/sets the fields that should be redacted for this gem.
+    # Gets/sets the blacklisted fields that should be redacted for this gem.
     #
     # The default is %i[password].
     #
     # @return [Array<Symbol>] an Array of Symbols that should be redacted.
-    attr_accessor :redacted
+    attr_accessor :blacklist
+    alias redacted blacklist
+    alias redacted= blacklist=
+
+    # Gets/sets the whitelisted fields that should not be redacted for this gem.
+    #
+    # The default is [].
+    #
+    # @return [Array<Symbol>] an Array of Symbols that should be whitelisted.
+    attr_accessor :whitelist
 
     # Gets/sets the label that should replace redacted field values.
     #
@@ -62,7 +71,8 @@ module ImmutableStructExRedactable
     #
     # @return [void]
     def reset
-      @redacted = %i[password]
+      @blacklist = %i[password]
+      @whitelist = []
       @redacted_label = '******'
       @redacted_unsafe = false
     end

data/lib/immutable_struct_ex_redactable/redacted_accessible.rb

@@ -11,15 +11,30 @@ module ImmutableStructExRedactable
     module ClassModules
       def redacted_accessible_module_for(hash:, config:)
         Module.new do
-          config.redacted.each do |attr|
-            unredacted_attr_method = "unredacted_#{attr}"
-            code = <<~CODE
-              def #{unredacted_attr_method}
-                "#{hash[attr]}"
-              end
-              private :#{unredacted_attr_method}
-            CODE
-            class_eval code
+          if config.whitelist.any?
+            hash.each do |attr, _|
+              next if config.whitelist.include? attr
+
+              unredacted_attr_method = "unredacted_#{attr}"
+              code = <<~CODE
+                def #{unredacted_attr_method}
+                  "#{hash[attr]}"
+                end
+                private :#{unredacted_attr_method}
+              CODE
+              class_eval code
+            end
+          else
+            config.blacklist.each do |attr|
+              unredacted_attr_method = "unredacted_#{attr}"
+              code = <<~CODE
+                def #{unredacted_attr_method}
+                  "#{hash[attr]}"
+                end
+                private :#{unredacted_attr_method}
+              CODE
+              class_eval code
+            end
           end
         end
       end

data/lib/immutable_struct_ex_redactable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ImmutableStructExRedactable
-  VERSION = '1.2.2'
+  VERSION = '1.3.0'
 end

data/lib/immutable_struct_ex_redactable.rb

@@ -21,10 +21,18 @@ module ImmutableStructExRedactable
         redacted_accessible_module_for(hash: hash, config: config)
     end
 
-    config.redacted.each do |attr|
-      next unless hash.key? attr
-
-      hash[attr] = config.redacted_label
+    if config.whitelist.any?
+      hash.each do |key, _|
+        next if config.whitelist.include? key
+
+        hash[key] = config.redacted_label
+      end
+    else
+      config.blacklist.each do |attr|
+        next unless hash.key? attr
+
+        hash[attr] = config.redacted_label
+      end
     end
 
     ImmutableStructEx.new(**hash, &block).tap do |struct|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: immutable_struct_ex_redactable
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Gene M. Angelo, Jr.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-29 00:00:00.000000000 Z
+date: 2023-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: immutable_struct_ex
@@ -63,7 +63,14 @@ metadata:
   source_code_uri: https://github.com/gangelo/immutable_struct_ex_redactable
   changelog_uri: https://github.com/gangelo/immutable_struct_ex_redactable/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: |
+  Thank you for installing immutable_struct_ex_redactable.
+
+  immutable_struct_ex_redactable now supports `ImmutableStructExRedactable::Configuration#whitelist`
+  See the README.md for more information.
+
+  Please note that `ImmutableStructExRedactable::Configuration#redacted` will be deprecated in a future release.
+  Please use `ImmutableStructExRedactable::Configuration#blacklist` instead.
 rdoc_options: []
 require_paths:
 - lib