rails_surrogate_key_logging 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51ed41b166599e90b95c595ecbd87fb3812dbeca4087dec61f4a6d4efc03793f
-  data.tar.gz: 5389b994867bac68b6edaeaf90e2af777af74634bfea2d505378bb8f5ec55432
+  metadata.gz: 2e6e90f9c083df089f9b7cee7d45bddb3e27cc8b6f33ca926810a5006c374f40
+  data.tar.gz: 942657d9c5b766de9b879071a79e1bd7a5928c9d371a7a015174499875a52238
 SHA512:
-  metadata.gz: 799c109ed078447639c5c06f2f6f20ba9d27d5fa1674b61cfc9f8ac96f0d033fe9c01b8472f03676e2852752ae42ca108b2b5b3f13093f22d03d5ae222b1eb4f
-  data.tar.gz: 2c06278e7a1744f49bd90e88682b82d69b40f502a5af20b69fb0bc1e264110996806a7a340cdd2ab63c5e1cbbbb9a329ff1483273ff8d46fc2c75cc1c6e4b502
+  metadata.gz: ec95153a37880c2f9421595e32c840bf0ac292785f83f2cd59f0358767cc673e53918dbde9e7999511282ccd5db8e0c787082d0b4de5915e2d8d0deb8552ebbe
+  data.tar.gz: 7620c957e9a36efef906e4bfa8a7a68a467fff0201d2149966b33cae0da6e2cd6e67c753eff3df4dd8e2d8ccee939fb2fea5bfb3e119e44449b7b9259f41a682

data/README.md

@@ -1 +1,134 @@
 # rails-surrogate-key-logging
+
+This gem enhances and uses Rails' built-in `ParameterFilter` to add "Surrogate Key" logging.
+
+## Installation
+
+- Add `gem :rails_surrogate_key_logging` to your Gemfile.
+- Run `bin/bundle install`
+- Add `include SurrogateKeyLogging::ActionController::Params` to your `ApplicationController`
+- Add `include SurrogateKeyLogging::ActiveRecord::Attributes` to your `ApplicationRecord`
+
+
+
+## Configuration
+
+In a new application initializer (`config/initializers/surrogate_key_logging.rb`) or in your `config/environments/*.rb`, use the following block:
+
+```ruby
+SurrogateKeyLogging.configure do |config|
+  config.key = value
+end
+```
+
+### Config
+
+Key | Type | Default | Description
+---|---|---|---
+`enabled` | Boolean | `Rails.env.production?` | Whether surrogate logging is injected into Rails.
+`debug` | Boolean | `false` | Whether to log a statement showing that a surrogate replacement happened and what the mapping from surrogate to value, and logs from the key store (Such as queries made by ActiveRecord to it's Surrogate model).
+`key_prefix` | String | `''` | This string will be prepended to generated surrogates. Can make it easier to identify a surrogate in logs.
+`key_for` | Proc \| Lambda \| `responds_to?(:call)` | `-> (value) { "#{config.key_prefix}#{SecureRandom.uuid}" }` | The method used to generate a surrogate for a given value. While the `value` is supplied to the method, it is generally considered insecure for the surrogate to be derivable from it's value.
+`cache` | Boolean | `true` | Should the key mananger maintain an in-memory cache of value -> surrogate map that have been used. When in a server context, this cache will last for the lifetime of a single request. The cache can also be manually busted at any time by calling `SurrogateKeyLogging.reset!`.
+`cache_key_for` | Proc \| Lambda \| `responds_to?(:call)` | `-> (value) { value }` | The method used to create the keys used in the cache. Typically this should be left to the default unless you expect to make many surrogates for very large values.
+`key_ttl` | Integer | `90.days` | Used by `bin/rails skl:clear:stale` to delete old surrogates.
+`key_store` | Symbol | None | The key store to use. See [Key Stores](#key-stores).
+
+
+
+## Key Stores
+
+Key Store | Config Value
+---|---
+[ActiveRecord](#active-record) | `:active_record`
+
+### Active Record
+
+This will use a `SurrogateKeyLogging::Surrogate` model to manage surrogates. This will require adding `surrogate_key_logging_#{Rails.env}` to your application's `config/database.yml` See [Example](#example-database-yml). After configuring your `config/database.yml` you will need to run `bin/rails skl:key_store:active_record:db:create` and `bin/rails skl:key_store:active_record:db:migrate`.
+
+#### Example database.yml
+```yml
+default: &default
+  adapter: mysql2
+  username: <%= Rails.application.credentials.database[:username] %>
+  password: <%= Rails.application.credentials.database[:password] %>
+  host: 127.0.0.1
+  port: 3306
+  database: myapp_<%= Rails.env %>
+  prepared_statements: true
+
+surrogate_key_logging_default: &surrogate_key_logging_default
+  <<: *default
+  database: surrogate_keys_<%= Rails.env %>
+
+
+
+development:
+  <<: *default
+
+test:
+  <<: *default
+
+production:
+  <<: *default
+
+
+
+surrogate_key_logging_development:
+  <<: *surrogate_key_logging_default
+
+surrogate_key_logging_test:
+  <<: *surrogate_key_logging_default
+
+surrogate_key_logging_production:
+  <<: *surrogate_key_logging_default
+```
+
+
+
+## Usage
+
+### Controllers
+
+In any controller including `SurrogateKeyLogging::ActionController::Params` you may use the `surrogate_params(*params, action: '*')` method. This method may be used multiple times. Pass the `action` argument to limit those `params` to only that `action` or omit it to apply those `params` to ALL actions in that controller.
+
+#### Params format
+Param | Examples | Output
+---|---|---
+`:foo` | `{ foo: 'bar1', another: {foo: 'baz1'}, foobar: 'barbaz' }` | `{foo: SURROGATE, another: { foo: SURROGATE }, foobar: 'barbaz' }`
+`'another.foo'` | `{ foo: 'bar1', another: { foo: 'baz1' }, foobar: { another: { foo: 'barbaz' } } }` | `{ foo: 'bar1', another: { foo: SURROGATE }, foobar: { another: { foo: SURROGATE } } }`
+`'another[foo]'` | `{ foo: 'bar1', another: { foo: 'baz1' }, foobar: { another: { foo: 'barbaz' } } }` | `{ foo: 'bar1', another: { foo: SURROGATE }, foobar: { another: { foo: 'barbaz' } } }`
+
+#### Example Controller
+```ruby
+class WidgetsController < ApplicationController
+  surrogate_params :name
+  surrogate_params :owner, action: :search
+
+  def name
+    ...
+  end
+
+  def search
+    ...
+  end
+end
+```
+
+In this example the `name` parameter will be surrogated in all requests to this controller, and the `owner` parameter will surrogated only in requests to the `search` action.
+
+
+
+### Models
+
+In any controller including `SurrogateKeyLogging::ActiveRecord::Attributes` you may use `surrogate_parent_names(*names)` and `surrogate_attributes(*attrs)`. All permutations of parent names to attributes will be used to create filters. By default `surrogate_parent_names` is initialized with the singular and plural names of the model.
+
+#### Example Model
+```ruby
+class Widget < ApplicationRecord
+  surrogate_parent_names :things
+  surrogate_attributes :name, :owner
+end
+```
+
+In this example, the following filters will be used to look for attributes to be surrogated: `widget.name`, `widget[name]`, `[widget][name]`, `widgets.name`, `widgets[name]`, `[widgets][name]`, `things.name`, `things[name]`, `[things][name]`

data/lib/surrogate_key_logging/engine.rb

@@ -18,14 +18,14 @@ module SurrogateKeyLogging
     end
 
     rake_tasks do
-      load 'tasks/surrogate_key_logging.rake'
-      load 'tasks/key_store/active_record.rake'
+      # load 'tasks/surrogate_key_logging.rake'
+      # load 'tasks/key_store/active_record.rake'
     end
 
     initializer 'surrogate_key_logging.config' do |app|
       SurrogateKeyLogging.configure do |config|
         config.enabled = Rails.env.production? unless config.key?(:enabled)
-        config.debug = !Rails.env.production? unless config.key?(:debug)
+        config.debug = false unless config.key?(:debug)
         config.key_prefix = '' unless config.key?(:key_prefix)
         config.key_for ||= -> (value) { "#{config.key_prefix}#{SecureRandom.uuid}" }
         config.cache = true unless config.key?(:cache)

data/lib/surrogate_key_logging/key_manager.rb

@@ -15,6 +15,7 @@ module SurrogateKeyLogging
     end
 
     def get(value)
+      return if value.blank?
       if should_cache
         get_cached(value)
       else
@@ -36,7 +37,7 @@ module SurrogateKeyLogging
     
     def call(_key, value, _parents = [], _original_params = nil)
       surrogate = get(value)
-      # Rails.logger.tagged('SurrogateKeyLogging') { Rails.logger.info "Surrogate: `#{surrogate}`, value: `#{value}`" } if SurrogateKeyLogging.config.debug
+      Rails.logger.tagged('SurrogateKeyLogging') { Rails.logger.info "Surrogate: `#{surrogate}`, value: `#{value}`" } if SurrogateKeyLogging.config.debug
       surrogate
     end
 

data/lib/surrogate_key_logging/version.rb

@@ -4,7 +4,7 @@ module SurrogateKeyLogging
 
   module Version
     MAJOR = 0
-    MINOR = 2
+    MINOR = 3
     PATCH = 0
 
   end

data/lib/surrogate_key_logging.rb

@@ -64,6 +64,10 @@ module SurrogateKeyLogging
       parameter_filter.filter params
     end
 
+    def surrogate_for(value)
+      key_manager.get(value)
+    end
+
     def add_param_to_filter(attr, *parents)
       if parents.empty?
         surrogate_attributes attr.to_s

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_surrogate_key_logging
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Taylor Yelverton
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-24 00:00:00.000000000 Z
+date: 2023-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack