rails_surrogate_key_logging 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +133 -0
- data/lib/surrogate_key_logging/engine.rb +1 -1
- data/lib/surrogate_key_logging/key_manager.rb +1 -1
- data/lib/surrogate_key_logging/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 4f209a8f18098917e60dbd9dbe93a1d6367eeaf16e2da104bbbba0351fb09956
|
4
|
+
data.tar.gz: 0d70d2d6ed37c4981c286fbed4f409f397babd3695a90141a886d24b19ba2634
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: c12692d51a77d61a606193aee29f77016f2386076c6334e35f8dfeb324a52f3caed7860a3ea83c44f2a91c861cd379eb8d2ed21002ace9732f5e9b8acfebe6fb
|
7
|
+
data.tar.gz: 969985b95d785c04f0c90042e57ce3bf2826d529adf96aac611994fa061a7c254175e4bcaa13eee4f39f18e95000bbd2ddaa268547d1317f6893d3e24a43d5db
|
data/README.md
CHANGED
@@ -1 +1,134 @@
|
|
1
1
|
# rails-surrogate-key-logging
|
2
|
+
|
3
|
+
This gem enhances and uses Rails' built-in `ParameterFilter` to add "Surrogate Key" logging.
|
4
|
+
|
5
|
+
## Installation
|
6
|
+
|
7
|
+
- Add `gem :rails_surrogate_key_logging` to your Gemfile.
|
8
|
+
- Run `bin/bundle install`
|
9
|
+
- Add `include SurrogateKeyLogging::ActionController::Params` to your `ApplicationController`
|
10
|
+
- Add `include SurrogateKeyLogging::ActiveRecord::Attributes` to your `ApplicationRecord`
|
11
|
+
|
12
|
+
|
13
|
+
|
14
|
+
## Configuration
|
15
|
+
|
16
|
+
In a new application initializer (`config/initializers/surrogate_key_logging.rb`) or in your `config/environments/*.rb`, use the following block:
|
17
|
+
|
18
|
+
```ruby
|
19
|
+
SurrogateKeyLogging.configure do |config|
|
20
|
+
config.key = value
|
21
|
+
end
|
22
|
+
```
|
23
|
+
|
24
|
+
### Config
|
25
|
+
|
26
|
+
Key | Type | Default | Description
|
27
|
+
---|---|---|---
|
28
|
+
`enabled` | Boolean | `Rails.env.production?` | Whether surrogate logging is injected into Rails.
|
29
|
+
`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).
|
30
|
+
`key_prefix` | String | `''` | This string will be prepended to generated surrogates. Can make it easier to identify a surrogate in logs.
|
31
|
+
`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.
|
32
|
+
`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!`.
|
33
|
+
`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.
|
34
|
+
`key_ttl` | Integer | `90.days` | Used by `bin/rails skl:clear:stale` to delete old surrogates.
|
35
|
+
`key_store` | Symbol | None | The key store to use. See [Key Stores](#key-stores).
|
36
|
+
|
37
|
+
|
38
|
+
|
39
|
+
## Key Stores
|
40
|
+
|
41
|
+
Key Store | Config Value
|
42
|
+
---|---
|
43
|
+
[ActiveRecord](#active-record) | `:active_record`
|
44
|
+
|
45
|
+
### Active Record
|
46
|
+
|
47
|
+
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`.
|
48
|
+
|
49
|
+
#### Example database.yml
|
50
|
+
```yml
|
51
|
+
default: &default
|
52
|
+
adapter: mysql2
|
53
|
+
username: <%= Rails.application.credentials.database[:username] %>
|
54
|
+
password: <%= Rails.application.credentials.database[:password] %>
|
55
|
+
host: 127.0.0.1
|
56
|
+
port: 3306
|
57
|
+
database: myapp_<%= Rails.env %>
|
58
|
+
prepared_statements: true
|
59
|
+
|
60
|
+
surrogate_key_logging_default: &surrogate_key_logging_default
|
61
|
+
<<: *default
|
62
|
+
database: surrogate_keys_<%= Rails.env %>
|
63
|
+
|
64
|
+
|
65
|
+
|
66
|
+
development:
|
67
|
+
<<: *default
|
68
|
+
|
69
|
+
test:
|
70
|
+
<<: *default
|
71
|
+
|
72
|
+
production:
|
73
|
+
<<: *default
|
74
|
+
|
75
|
+
|
76
|
+
|
77
|
+
surrogate_key_logging_development:
|
78
|
+
<<: *surrogate_key_logging_default
|
79
|
+
|
80
|
+
surrogate_key_logging_test:
|
81
|
+
<<: *surrogate_key_logging_default
|
82
|
+
|
83
|
+
surrogate_key_logging_production:
|
84
|
+
<<: *surrogate_key_logging_default
|
85
|
+
```
|
86
|
+
|
87
|
+
|
88
|
+
|
89
|
+
## Usage
|
90
|
+
|
91
|
+
### Controllers
|
92
|
+
|
93
|
+
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.
|
94
|
+
|
95
|
+
#### Params format
|
96
|
+
Param | Examples | Output
|
97
|
+
---|---|---
|
98
|
+
`:foo` | `{ foo: 'bar1', another: {foo: 'baz1'}, foobar: 'barbaz' }` | `{foo: SURROGATE, another: { foo: SURROGATE }, foobar: 'barbaz' }`
|
99
|
+
`'another.foo'` | `{ foo: 'bar1', another: { foo: 'baz1' }, foobar: { another: { foo: 'barbaz' } } }` | `{ foo: 'bar1', another: { foo: SURROGATE }, foobar: { another: { foo: SURROGATE } } }`
|
100
|
+
`'another[foo]'` | `{ foo: 'bar1', another: { foo: 'baz1' }, foobar: { another: { foo: 'barbaz' } } }` | `{ foo: 'bar1', another: { foo: SURROGATE }, foobar: { another: { foo: 'barbaz' } } }`
|
101
|
+
|
102
|
+
#### Example Controller
|
103
|
+
```ruby
|
104
|
+
class WidgetsController < ApplicationController
|
105
|
+
surrogate_params :name
|
106
|
+
surrogate_params :owner, action: :search
|
107
|
+
|
108
|
+
def name
|
109
|
+
...
|
110
|
+
end
|
111
|
+
|
112
|
+
def search
|
113
|
+
...
|
114
|
+
end
|
115
|
+
end
|
116
|
+
```
|
117
|
+
|
118
|
+
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.
|
119
|
+
|
120
|
+
|
121
|
+
|
122
|
+
### Models
|
123
|
+
|
124
|
+
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.
|
125
|
+
|
126
|
+
#### Example Model
|
127
|
+
```ruby
|
128
|
+
class Widget < ApplicationRecord
|
129
|
+
surrogate_parent_names :things
|
130
|
+
surrogate_attributes :name, :owner
|
131
|
+
end
|
132
|
+
```
|
133
|
+
|
134
|
+
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]`
|
@@ -25,7 +25,7 @@ module SurrogateKeyLogging
|
|
25
25
|
initializer 'surrogate_key_logging.config' do |app|
|
26
26
|
SurrogateKeyLogging.configure do |config|
|
27
27
|
config.enabled = Rails.env.production? unless config.key?(:enabled)
|
28
|
-
config.debug =
|
28
|
+
config.debug = false unless config.key?(:debug)
|
29
29
|
config.key_prefix = '' unless config.key?(:key_prefix)
|
30
30
|
config.key_for ||= -> (value) { "#{config.key_prefix}#{SecureRandom.uuid}" }
|
31
31
|
config.cache = true unless config.key?(:cache)
|
@@ -36,7 +36,7 @@ module SurrogateKeyLogging
|
|
36
36
|
|
37
37
|
def call(_key, value, _parents = [], _original_params = nil)
|
38
38
|
surrogate = get(value)
|
39
|
-
|
39
|
+
Rails.logger.tagged('SurrogateKeyLogging') { Rails.logger.info "Surrogate: `#{surrogate}`, value: `#{value}`" } if SurrogateKeyLogging.config.debug
|
40
40
|
surrogate
|
41
41
|
end
|
42
42
|
|