rails_surrogate_key_logging 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51ed41b166599e90b95c595ecbd87fb3812dbeca4087dec61f4a6d4efc03793f
-  data.tar.gz: 5389b994867bac68b6edaeaf90e2af777af74634bfea2d505378bb8f5ec55432
+  metadata.gz: 4f209a8f18098917e60dbd9dbe93a1d6367eeaf16e2da104bbbba0351fb09956
+  data.tar.gz: 0d70d2d6ed37c4981c286fbed4f409f397babd3695a90141a886d24b19ba2634
 SHA512:
-  metadata.gz: 799c109ed078447639c5c06f2f6f20ba9d27d5fa1674b61cfc9f8ac96f0d033fe9c01b8472f03676e2852752ae42ca108b2b5b3f13093f22d03d5ae222b1eb4f
-  data.tar.gz: 2c06278e7a1744f49bd90e88682b82d69b40f502a5af20b69fb0bc1e264110996806a7a340cdd2ab63c5e1cbbbb9a329ff1483273ff8d46fc2c75cc1c6e4b502
+  metadata.gz: c12692d51a77d61a606193aee29f77016f2386076c6334e35f8dfeb324a52f3caed7860a3ea83c44f2a91c861cd379eb8d2ed21002ace9732f5e9b8acfebe6fb
+  data.tar.gz: 969985b95d785c04f0c90042e57ce3bf2826d529adf96aac611994fa061a7c254175e4bcaa13eee4f39f18e95000bbd2ddaa268547d1317f6893d3e24a43d5db

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

@@ -25,7 +25,7 @@ module SurrogateKeyLogging
     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

@@ -36,7 +36,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

@@ -5,7 +5,7 @@ module SurrogateKeyLogging
   module Version
     MAJOR = 0
     MINOR = 2
-    PATCH = 0
+    PATCH = 1
 
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_surrogate_key_logging
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Taylor Yelverton