sendproof-core 0.1.0.alpha.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.
Files changed (229) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +21 -0
  3. data/README.md +55 -0
  4. data/lib/sendproof/assets.rb +70 -0
  5. data/lib/sendproof/attribution.rb +98 -0
  6. data/lib/sendproof/capture.rb +66 -0
  7. data/lib/sendproof/clock.rb +54 -0
  8. data/lib/sendproof/configuration.rb +241 -0
  9. data/lib/sendproof/data_store.rb +34 -0
  10. data/lib/sendproof/dynamodb/store.rb +183 -0
  11. data/lib/sendproof/dynamodb.rb +17 -0
  12. data/lib/sendproof/elasticsearch/store.rb +24 -0
  13. data/lib/sendproof/elasticsearch.rb +17 -0
  14. data/lib/sendproof/firestore/interceptor.rb +38 -0
  15. data/lib/sendproof/firestore/store.rb +150 -0
  16. data/lib/sendproof/firestore.rb +99 -0
  17. data/lib/sendproof/handler.rb +23 -0
  18. data/lib/sendproof/identity.rb +37 -0
  19. data/lib/sendproof/limits.rb +113 -0
  20. data/lib/sendproof/middleware.rb +68 -0
  21. data/lib/sendproof/mongo/engine.rb +692 -0
  22. data/lib/sendproof/mongo/guarded.rb +100 -0
  23. data/lib/sendproof/mongo/plain.rb +45 -0
  24. data/lib/sendproof/mongo/store.rb +54 -0
  25. data/lib/sendproof/mongo/subscriber.rb +21 -0
  26. data/lib/sendproof/mongo.rb +41 -0
  27. data/lib/sendproof/mongoid/store.rb +58 -0
  28. data/lib/sendproof/mongoid.rb +65 -0
  29. data/lib/sendproof/observed_request.rb +108 -0
  30. data/lib/sendproof/opensearch/store.rb +21 -0
  31. data/lib/sendproof/opensearch.rb +17 -0
  32. data/lib/sendproof/operation_matcher.rb +28 -0
  33. data/lib/sendproof/pool_hooks.rb +80 -0
  34. data/lib/sendproof/preview_request.rb +44 -0
  35. data/lib/sendproof/preview_transport.rb +331 -0
  36. data/lib/sendproof/protocol.rb +81 -0
  37. data/lib/sendproof/provider.rb +83 -0
  38. data/lib/sendproof/recorder.rb +298 -0
  39. data/lib/sendproof/redaction.rb +98 -0
  40. data/lib/sendproof/redis/commands.rb +76 -0
  41. data/lib/sendproof/redis/store.rb +205 -0
  42. data/lib/sendproof/redis.rb +18 -0
  43. data/lib/sendproof/search/middleware.rb +39 -0
  44. data/lib/sendproof/search/store.rb +213 -0
  45. data/lib/sendproof/search.rb +82 -0
  46. data/lib/sendproof/stores/classify.rb +346 -0
  47. data/lib/sendproof/stores/guard.rb +127 -0
  48. data/lib/sendproof/stores/tables.rb +1328 -0
  49. data/lib/sendproof/stores.rb +12 -0
  50. data/lib/sendproof/trace_store.rb +110 -0
  51. data/lib/sendproof/transaction_control.rb +187 -0
  52. data/lib/sendproof/ui/action-bar.js +91 -0
  53. data/lib/sendproof/ui/api.js +239 -0
  54. data/lib/sendproof/ui/app.css +848 -0
  55. data/lib/sendproof/ui/app.js +742 -0
  56. data/lib/sendproof/ui/autofill.js +137 -0
  57. data/lib/sendproof/ui/code-copy.js +71 -0
  58. data/lib/sendproof/ui/code-picker.js +149 -0
  59. data/lib/sendproof/ui/commands.js +197 -0
  60. data/lib/sendproof/ui/components.js +77 -0
  61. data/lib/sendproof/ui/context-bar.js +82 -0
  62. data/lib/sendproof/ui/copy.js +92 -0
  63. data/lib/sendproof/ui/coverage-popover.js +35 -0
  64. data/lib/sendproof/ui/crumb-fit.js +80 -0
  65. data/lib/sendproof/ui/deprecation.js +164 -0
  66. data/lib/sendproof/ui/display-settings.js +175 -0
  67. data/lib/sendproof/ui/doc-diff.js +209 -0
  68. data/lib/sendproof/ui/docs-view.js +347 -0
  69. data/lib/sendproof/ui/favicon.png +0 -0
  70. data/lib/sendproof/ui/favicon.svg +1 -0
  71. data/lib/sendproof/ui/field-help.js +52 -0
  72. data/lib/sendproof/ui/field-modules.js +23 -0
  73. data/lib/sendproof/ui/fields/controls.js +179 -0
  74. data/lib/sendproof/ui/fields/dom.js +36 -0
  75. data/lib/sendproof/ui/fields/infer.js +71 -0
  76. data/lib/sendproof/ui/fields/lookup-source.js +63 -0
  77. data/lib/sendproof/ui/fields/lookup.js +285 -0
  78. data/lib/sendproof/ui/fields/render.js +496 -0
  79. data/lib/sendproof/ui/fields/select.js +175 -0
  80. data/lib/sendproof/ui/fields/validate.js +363 -0
  81. data/lib/sendproof/ui/fields/validation-formats.js +164 -0
  82. data/lib/sendproof/ui/fields/validation-references.js +68 -0
  83. data/lib/sendproof/ui/fields/validation-values.js +137 -0
  84. data/lib/sendproof/ui/generate-menu.js +44 -0
  85. data/lib/sendproof/ui/generate.js +184 -0
  86. data/lib/sendproof/ui/header-editor.js +777 -0
  87. data/lib/sendproof/ui/headers.js +188 -0
  88. data/lib/sendproof/ui/highlight.js +257 -0
  89. data/lib/sendproof/ui/history-popover.js +24 -0
  90. data/lib/sendproof/ui/i18n.js +253 -0
  91. data/lib/sendproof/ui/icons.js +87 -0
  92. data/lib/sendproof/ui/index.html +70 -0
  93. data/lib/sendproof/ui/issues.js +187 -0
  94. data/lib/sendproof/ui/json-view.js +166 -0
  95. data/lib/sendproof/ui/lang-icons.js +62 -0
  96. data/lib/sendproof/ui/layout.js +262 -0
  97. data/lib/sendproof/ui/listbox.js +334 -0
  98. data/lib/sendproof/ui/locales/ar-capture.js +366 -0
  99. data/lib/sendproof/ui/locales/ar-stores.js +116 -0
  100. data/lib/sendproof/ui/locales/ar.js +561 -0
  101. data/lib/sendproof/ui/locales/cs-capture.js +442 -0
  102. data/lib/sendproof/ui/locales/cs-stores.js +116 -0
  103. data/lib/sendproof/ui/locales/cs.js +689 -0
  104. data/lib/sendproof/ui/locales/da-capture.js +347 -0
  105. data/lib/sendproof/ui/locales/da-stores.js +116 -0
  106. data/lib/sendproof/ui/locales/da.js +522 -0
  107. data/lib/sendproof/ui/locales/de-capture.js +347 -0
  108. data/lib/sendproof/ui/locales/de-stores.js +116 -0
  109. data/lib/sendproof/ui/locales/de.js +519 -0
  110. data/lib/sendproof/ui/locales/el-capture.js +347 -0
  111. data/lib/sendproof/ui/locales/el-stores.js +116 -0
  112. data/lib/sendproof/ui/locales/el.js +520 -0
  113. data/lib/sendproof/ui/locales/en-capture.js +349 -0
  114. data/lib/sendproof/ui/locales/en-stores.js +95 -0
  115. data/lib/sendproof/ui/locales/en.js +522 -0
  116. data/lib/sendproof/ui/locales/es-capture.js +353 -0
  117. data/lib/sendproof/ui/locales/es-stores.js +116 -0
  118. data/lib/sendproof/ui/locales/es.js +525 -0
  119. data/lib/sendproof/ui/locales/fa-capture.js +348 -0
  120. data/lib/sendproof/ui/locales/fa-stores.js +116 -0
  121. data/lib/sendproof/ui/locales/fa.js +521 -0
  122. data/lib/sendproof/ui/locales/fi-capture.js +347 -0
  123. data/lib/sendproof/ui/locales/fi-stores.js +116 -0
  124. data/lib/sendproof/ui/locales/fi.js +523 -0
  125. data/lib/sendproof/ui/locales/fr-capture.js +353 -0
  126. data/lib/sendproof/ui/locales/fr-stores.js +116 -0
  127. data/lib/sendproof/ui/locales/fr.js +525 -0
  128. data/lib/sendproof/ui/locales/he-capture.js +358 -0
  129. data/lib/sendproof/ui/locales/he-stores.js +116 -0
  130. data/lib/sendproof/ui/locales/he.js +529 -0
  131. data/lib/sendproof/ui/locales/hi-capture.js +348 -0
  132. data/lib/sendproof/ui/locales/hi-stores.js +116 -0
  133. data/lib/sendproof/ui/locales/hi.js +523 -0
  134. data/lib/sendproof/ui/locales/id-capture.js +347 -0
  135. data/lib/sendproof/ui/locales/id-stores.js +116 -0
  136. data/lib/sendproof/ui/locales/id.js +521 -0
  137. data/lib/sendproof/ui/locales/it-capture.js +361 -0
  138. data/lib/sendproof/ui/locales/it-stores.js +116 -0
  139. data/lib/sendproof/ui/locales/it.js +523 -0
  140. data/lib/sendproof/ui/locales/ja-capture.js +346 -0
  141. data/lib/sendproof/ui/locales/ja-stores.js +116 -0
  142. data/lib/sendproof/ui/locales/ja.js +521 -0
  143. data/lib/sendproof/ui/locales/ko-capture.js +346 -0
  144. data/lib/sendproof/ui/locales/ko-stores.js +116 -0
  145. data/lib/sendproof/ui/locales/ko.js +522 -0
  146. data/lib/sendproof/ui/locales/nb-capture.js +349 -0
  147. data/lib/sendproof/ui/locales/nb-stores.js +116 -0
  148. data/lib/sendproof/ui/locales/nb.js +521 -0
  149. data/lib/sendproof/ui/locales/nl-capture.js +355 -0
  150. data/lib/sendproof/ui/locales/nl-stores.js +116 -0
  151. data/lib/sendproof/ui/locales/nl.js +520 -0
  152. data/lib/sendproof/ui/locales/pl-capture.js +432 -0
  153. data/lib/sendproof/ui/locales/pl-stores.js +116 -0
  154. data/lib/sendproof/ui/locales/pl.js +528 -0
  155. data/lib/sendproof/ui/locales/pt-BR-capture.js +350 -0
  156. data/lib/sendproof/ui/locales/pt-BR-stores.js +116 -0
  157. data/lib/sendproof/ui/locales/pt-BR.js +523 -0
  158. data/lib/sendproof/ui/locales/pt-PT-capture.js +350 -0
  159. data/lib/sendproof/ui/locales/pt-PT-stores.js +116 -0
  160. data/lib/sendproof/ui/locales/pt-PT.js +523 -0
  161. data/lib/sendproof/ui/locales/ru-capture.js +437 -0
  162. data/lib/sendproof/ui/locales/ru-stores.js +116 -0
  163. data/lib/sendproof/ui/locales/ru.js +624 -0
  164. data/lib/sendproof/ui/locales/sv-capture.js +349 -0
  165. data/lib/sendproof/ui/locales/sv-stores.js +116 -0
  166. data/lib/sendproof/ui/locales/sv.js +518 -0
  167. data/lib/sendproof/ui/locales/th-capture.js +347 -0
  168. data/lib/sendproof/ui/locales/th-stores.js +116 -0
  169. data/lib/sendproof/ui/locales/th.js +521 -0
  170. data/lib/sendproof/ui/locales/tr-capture.js +348 -0
  171. data/lib/sendproof/ui/locales/tr-stores.js +116 -0
  172. data/lib/sendproof/ui/locales/tr.js +521 -0
  173. data/lib/sendproof/ui/locales/uk-capture.js +442 -0
  174. data/lib/sendproof/ui/locales/uk-stores.js +116 -0
  175. data/lib/sendproof/ui/locales/uk.js +630 -0
  176. data/lib/sendproof/ui/locales/vi-capture.js +346 -0
  177. data/lib/sendproof/ui/locales/vi-stores.js +116 -0
  178. data/lib/sendproof/ui/locales/vi.js +523 -0
  179. data/lib/sendproof/ui/locales/zh-Hans-capture.js +347 -0
  180. data/lib/sendproof/ui/locales/zh-Hans-stores.js +116 -0
  181. data/lib/sendproof/ui/locales/zh-Hans.js +523 -0
  182. data/lib/sendproof/ui/locales/zh-Hant-capture.js +346 -0
  183. data/lib/sendproof/ui/locales/zh-Hant-stores.js +116 -0
  184. data/lib/sendproof/ui/locales/zh-Hant.js +522 -0
  185. data/lib/sendproof/ui/manifest.json +866 -0
  186. data/lib/sendproof/ui/markdown.js +39 -0
  187. data/lib/sendproof/ui/model-view.js +182 -0
  188. data/lib/sendproof/ui/navigation.js +233 -0
  189. data/lib/sendproof/ui/operation-header.js +76 -0
  190. data/lib/sendproof/ui/operations.js +7 -0
  191. data/lib/sendproof/ui/overview-view.js +63 -0
  192. data/lib/sendproof/ui/personas.js +59 -0
  193. data/lib/sendproof/ui/popover.js +71 -0
  194. data/lib/sendproof/ui/preview-false.js +108 -0
  195. data/lib/sendproof/ui/request-editor.js +496 -0
  196. data/lib/sendproof/ui/response-metadata.js +354 -0
  197. data/lib/sendproof/ui/response-viewer.js +618 -0
  198. data/lib/sendproof/ui/result-blocked.js +155 -0
  199. data/lib/sendproof/ui/result-capture.js +25 -0
  200. data/lib/sendproof/ui/result-database.js +185 -0
  201. data/lib/sendproof/ui/result-effects.js +176 -0
  202. data/lib/sendproof/ui/result-headers.js +106 -0
  203. data/lib/sendproof/ui/result-logs.js +408 -0
  204. data/lib/sendproof/ui/result-states.js +213 -0
  205. data/lib/sendproof/ui/results.js +371 -0
  206. data/lib/sendproof/ui/router.js +118 -0
  207. data/lib/sendproof/ui/schema-model.js +336 -0
  208. data/lib/sendproof/ui/schema-tree.js +344 -0
  209. data/lib/sendproof/ui/schema.js +397 -0
  210. data/lib/sendproof/ui/security.js +31 -0
  211. data/lib/sendproof/ui/seeded-menu.js +69 -0
  212. data/lib/sendproof/ui/settings.js +93 -0
  213. data/lib/sendproof/ui/shortcuts-sheet.js +73 -0
  214. data/lib/sendproof/ui/shortcuts.js +190 -0
  215. data/lib/sendproof/ui/sidebar.js +289 -0
  216. data/lib/sendproof/ui/signin.js +259 -0
  217. data/lib/sendproof/ui/snippets.js +530 -0
  218. data/lib/sendproof/ui/store-marks.js +47 -0
  219. data/lib/sendproof/ui/stores.js +131 -0
  220. data/lib/sendproof/ui/styles.css +971 -0
  221. data/lib/sendproof/ui/toggletip.js +53 -0
  222. data/lib/sendproof/ui/uuid.js +10 -0
  223. data/lib/sendproof/ui/view.js +122 -0
  224. data/lib/sendproof/ui/views.css +653 -0
  225. data/lib/sendproof/version.rb +9 -0
  226. data/lib/sendproof/workbench.rb +102 -0
  227. data/lib/sendproof-core.rb +3 -0
  228. data/lib/sendproof.rb +121 -0
  229. metadata +292 -0
@@ -0,0 +1,183 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module DynamoDB
5
+ # The DynamoDB data store: a Seahorse handler at the +initialize+ step of +Aws::DynamoDB::Client+.
6
+ #
7
+ # The initialize step runs before parameter validation, serialization and signing, so a refused
8
+ # operation never becomes an HTTP request, and credentials, the +Authorization+ header and signatures
9
+ # never reach the hook. The operation is the API action name (+UpdateItem+).
10
+ #
11
+ # Reads run normally. In a Preview the first write raises {Sendproof::PreviewWriteBlocked} and the
12
+ # Preview answers 409. Every operation becomes a +Db+ log entry; PartiQL text has its literals
13
+ # replaced by +?+ and parameter values are never captured.
14
+ #
15
+ # *Coverage.* Hook one client with +client:+, or every client created afterwards with +global: true+,
16
+ # or hand {#plugin} to +Aws::DynamoDB::Client.new(plugins: [...])+. A client created some other way
17
+ # is not covered.
18
+ #
19
+ # @example
20
+ # config.sendproof.data_store Sendproof::DynamoDB::Store.new(client: orders_client, name: "orders")
21
+ class Store < Sendproof::DataStore
22
+ # @param client [Aws::DynamoDB::Client, nil] a client to hook in place
23
+ # @param name [String, nil] display label for discovery, such as +orders+; never an endpoint or ARN
24
+ # @param treat_as_read [Array<String>, nil] action names you state never write, matched exactly
25
+ # @param global [Boolean] add the plugin to +Aws::DynamoDB::Client+, so every client created afterwards is hooked
26
+ def initialize(client: nil, name: nil, treat_as_read: nil, global: false)
27
+ super()
28
+ @name = Stores::Guard.store_label(name)
29
+ @reads = Stores::Guard.read_set(treat_as_read)
30
+ @active = true
31
+ @handler = build_handler
32
+ @plugin = build_plugin
33
+ hook(client) if client
34
+ ::Aws::DynamoDB::Client.add_plugin(@plugin) if global
35
+ end
36
+
37
+ # @return [Class] a +Seahorse::Client::Plugin+, for +Aws::DynamoDB::Client.new(plugins: [store.plugin])+
38
+ attr_reader :plugin
39
+
40
+ def system = "dynamodb"
41
+
42
+ def describe
43
+ { system: "dynamodb", name: @name, mode: :guard }
44
+ end
45
+
46
+ # Turns the hook off. The handler stays on the clients it was added to, but does nothing.
47
+ def unhook! = @active = false
48
+
49
+ # @return [Boolean] whether the hook is still guarding
50
+ def active? = @active
51
+
52
+ # Adds the handler to +client+ in place. Hooking a client twice is refused, so its operations are
53
+ # never logged twice.
54
+ def hook(client)
55
+ unless client.respond_to?(:handlers) && client.respond_to?(:config)
56
+ raise ArgumentError, "Sendproof::DynamoDB::Store takes an Aws::DynamoDB::Client."
57
+ end
58
+ raise ConfigurationError, "This DynamoDB client is already hooked." if client.handlers.entries.any? { |e| e.handler_class == @handler }
59
+
60
+ client.handlers.add(@handler, step: :initialize, priority: 99)
61
+ client
62
+ end
63
+
64
+ # Guards and logs one operation around +block+, which sends it.
65
+ #
66
+ # @param operation [String] the API action name, such as +UpdateItem+
67
+ # @param params [Hash] the request parameters, snake_case symbol keys as the SDK takes them
68
+ # @yieldreturn [Seahorse::Client::Response]
69
+ def around(operation, params)
70
+ return yield unless @active
71
+
72
+ input = classification_input(params)
73
+ Stores::Guard.guard("dynamodb", operation, Stores::Classify.dynamodb(operation, input, @reads))
74
+ recorder = Capture.current
75
+ return yield unless recorder
76
+
77
+ statement = statement_of(params)
78
+ target = target_of(params, statement)
79
+ started = Clock.now
80
+ begin
81
+ response = yield
82
+ rescue StandardError => error
83
+ log(recorder, operation, target, statement, started, error: error)
84
+ raise
85
+ end
86
+ log(recorder, operation, target, statement, started, error: response.respond_to?(:error) ? response.error : nil,
87
+ rows: rows_of(response))
88
+ response
89
+ end
90
+
91
+ # Replaces every literal in PartiQL text with +?+: single-quoted strings (with +''+ escapes) and
92
+ # numbers. Double-quoted identifiers (table and attribute names) are kept as written. A statement
93
+ # may inline values instead of using +?+ parameters, and a value never appears in a +Db+ entry.
94
+ def self.sanitize_partiql(text)
95
+ output = +""
96
+ index = 0
97
+ while index < text.length
98
+ char = text[index]
99
+ if char == '"'
100
+ close = text.index('"', index + 1)
101
+ stop = close ? close + 1 : text.length
102
+ output << text[index...stop]
103
+ index = stop
104
+ elsif char == "'"
105
+ stop = index + 1
106
+ stop += text[stop] == "'" ? 2 : 1 until stop >= text.length || (text[stop] == "'" && text[stop + 1] != "'")
107
+ output << "?"
108
+ index = stop + 1
109
+ elsif char.match?(/[0-9]/) && !(index.positive? && text[index - 1].match?(/[\w.]/))
110
+ number = text[index..][/\A[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/]
111
+ output << "?"
112
+ index += number.length
113
+ else
114
+ output << char
115
+ index += 1
116
+ end
117
+ end
118
+ output
119
+ end
120
+
121
+ private
122
+
123
+ def build_handler
124
+ store = self
125
+ Class.new(Seahorse::Client::Handler) do
126
+ define_method(:call) do |context|
127
+ store.around(context.operation.name, context.params || {}) { @handler.call(context) }
128
+ end
129
+ end
130
+ end
131
+
132
+ def build_plugin
133
+ handler = @handler
134
+ Class.new(Seahorse::Client::Plugin) do
135
+ define_method(:add_handlers) do |handlers, _config|
136
+ handlers.add(handler, step: :initialize, priority: 99)
137
+ end
138
+ end
139
+ end
140
+
141
+ # The request in the shape the shared classifier reads: API field names, not the SDK's snake_case.
142
+ def classification_input(params)
143
+ input = {}
144
+ input["Statement"] = params[:statement] if params.key?(:statement)
145
+ input["Statements"] = params[:statements].map { |item| { "Statement" => item[:statement] } } if params[:statements]
146
+ if params[:transact_statements]
147
+ input["TransactStatements"] = params[:transact_statements].map { |item| { "Statement" => item[:statement] } }
148
+ end
149
+ input
150
+ end
151
+
152
+ def statement_of(params)
153
+ return self.class.sanitize_partiql(params[:statement].to_s) if params[:statement].is_a?(String)
154
+
155
+ list = params[:statements] || params[:transact_statements]
156
+ list.map { |item| self.class.sanitize_partiql(item[:statement].to_s) }.join("; ") if list.is_a?(Array)
157
+ end
158
+
159
+ # The table a command targets: +table_name+, the first +request_items+ table, or the quoted PartiQL table.
160
+ def target_of(params, statement)
161
+ return params[:table_name].to_s if params[:table_name]
162
+ return params[:request_items].keys.first.to_s if params[:request_items].respond_to?(:keys) && !params[:request_items].empty?
163
+
164
+ statement && statement[/"([^"]+)"/, 1]
165
+ end
166
+
167
+ # Items matched, returned or written, when the reply says so.
168
+ def rows_of(response)
169
+ data = response.respond_to?(:data) ? response.data : nil
170
+ fields = data.respond_to?(:to_h) ? data.to_h : {}
171
+ if fields[:items].is_a?(Array) then fields[:items].length
172
+ elsif fields[:count].is_a?(Integer) then fields[:count]
173
+ elsif fields[:item] || fields[:attributes] then 1
174
+ end
175
+ end
176
+
177
+ def log(recorder, operation, target, statement, started, error: nil, rows: nil)
178
+ recorder.db(system: "dynamodb", operation: operation, target: target, statement: statement, rows_affected: rows,
179
+ error: error && error.class.name.to_s.split("::").last, duration_ms: Clock.elapsed_ms(started))
180
+ end
181
+ end
182
+ end
183
+ end
@@ -0,0 +1,17 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "aws-sdk-dynamodb"
4
+ require "sendproof"
5
+
6
+ module Sendproof
7
+ # Sendproof write guard for DynamoDB (spec/data-stores.md, +guard+ mode), for +aws-sdk-dynamodb+ and
8
+ # everything built on its client, such as +Aws::DynamoDB::Resource+ and Dynamoid.
9
+ #
10
+ # store = Sendproof::DynamoDB::Store.new(client: dynamodb, name: "orders")
11
+ # config.sendproof.data_store store
12
+ #
13
+ # Require it explicitly: +require "sendproof/dynamodb"+.
14
+ module DynamoDB
15
+ autoload :Store, "sendproof/dynamodb/store"
16
+ end
17
+ end
@@ -0,0 +1,24 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module Elasticsearch
5
+ # The Elasticsearch data store: a Faraday middleware on every connection of +Elastic::Transport+,
6
+ # the HTTP layer of the +elasticsearch+ gem. See {Sendproof::Search::Store} for the behavior,
7
+ # coverage and options. The store id is +elasticsearch+; use {Sendproof::OpenSearch::Store} for OpenSearch.
8
+ #
9
+ # @example Guard every client in the process, built before or after this line
10
+ # config.sendproof.data_store Sendproof::Elasticsearch::Store.new(name: "search")
11
+ # @example Guard one client you build yourself
12
+ # store = Sendproof::Elasticsearch::Store.new(name: "search", global: false)
13
+ # client = ::Elasticsearch::Client.new(url: url) { |faraday| store.install(faraday) }
14
+ class Store < Sendproof::Search::Store
15
+ def system = "elasticsearch"
16
+
17
+ # @return [Class] the transport client class whose instances this store guards
18
+ def client_class = ::Elastic::Transport::Client
19
+
20
+ # @return [Class] the HTTP transport class that builds the Faraday connections
21
+ def transport_class = ::Elastic::Transport::Transport::HTTP::Faraday
22
+ end
23
+ end
24
+ end
@@ -0,0 +1,17 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "elasticsearch"
4
+ require "sendproof/search"
5
+
6
+ module Sendproof
7
+ # Sendproof write guard for Elasticsearch (spec/data-stores.md, +guard+ mode), for the +elasticsearch+
8
+ # 8 gem and everything built on its client, such as Searchkick, Chewy and elasticsearch-model.
9
+ #
10
+ # store = Sendproof::Elasticsearch::Store.new(name: "search")
11
+ # config.sendproof.data_store store
12
+ #
13
+ # Require it explicitly: +require "sendproof/elasticsearch"+. It needs no Elasticsearch server.
14
+ module Elasticsearch
15
+ autoload :Store, "sendproof/elasticsearch/store"
16
+ end
17
+ end
@@ -0,0 +1,38 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module Firestore
5
+ # The gRPC client interceptor that hands every Firestore call to the store before it is sent. It
6
+ # covers all four call types. A unary or server-streaming call passes its request message; a client
7
+ # or bidirectional stream passes none, so the store classifies it by RPC name alone: +Listen+ is a
8
+ # read, and +Write+, which can't be read before its first message, is refused before it opens.
9
+ #
10
+ # The interceptor holds no state. It asks {Sendproof::Firestore.store} on each call.
11
+ class Interceptor < ::GRPC::ClientInterceptor
12
+ def request_response(request: nil, call: nil, method: nil, metadata: nil, &send)
13
+ guarded(method, request, &send)
14
+ end
15
+
16
+ def server_streamer(request: nil, call: nil, method: nil, metadata: nil, &send)
17
+ guarded(method, request, &send)
18
+ end
19
+
20
+ def client_streamer(requests: nil, call: nil, method: nil, metadata: nil, &send)
21
+ guarded(method, nil, &send)
22
+ end
23
+
24
+ def bidi_streamer(requests: nil, call: nil, method: nil, metadata: nil, &send)
25
+ guarded(method, nil, &send)
26
+ end
27
+
28
+ private
29
+
30
+ def guarded(method, message, &send)
31
+ store = Sendproof::Firestore.store
32
+ return send.call unless store&.active?
33
+
34
+ store.around(method, message, &send)
35
+ end
36
+ end
37
+ end
38
+ end
@@ -0,0 +1,150 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module Firestore
5
+ # The Firestore data store: a gRPC client interceptor ({Interceptor}) on every Firestore client's
6
+ # channel. It classifies each call by RPC name before it is sent. Reads run and are logged as +Db+
7
+ # entries. In a Preview the first write, a +Commit+ that carries writes, +BatchWrite+, +Write+ or a
8
+ # document RPC, raises {Sendproof::PreviewWriteBlocked}, and the Preview answers 409. Nothing of the
9
+ # call is sent. A Firestore transaction can be rolled back, but not for arbitrary handlers (it needs
10
+ # every read before the first write), so the store always runs in +guard+ mode.
11
+ #
12
+ # +BeginTransaction+, +Rollback+ and a +Commit+ with no writes change no data and run unlogged.
13
+ #
14
+ # *Coverage.* Create the store before any Firestore client. From then on every client built, however
15
+ # it is configured, gets the interceptor, because the hook sits where the gem creates the channel.
16
+ # A client built earlier has no interceptor, so creating a store refuses (it raises) while one is
17
+ # alive. Firestore over REST can't be guarded: with a store registered, building a REST client raises.
18
+ #
19
+ # @example
20
+ # config.sendproof.data_store Sendproof::Firestore::Store.new(name: "orders")
21
+ class Store < Sendproof::DataStore
22
+ # @param name [String, nil] display label for discovery, such as +orders+; never a project or URL
23
+ # @param treat_as_read [Array<String>, nil] RPC names you state never write, matched exactly, such
24
+ # as a future read method. A wrongly listed write is not blocked.
25
+ # @raise [Sendproof::ConfigurationError] when a Firestore client built earlier is alive, or a
26
+ # store is already registered
27
+ def initialize(name: nil, treat_as_read: nil)
28
+ super()
29
+ @name = Stores::Guard.store_label(name)
30
+ @reads = Stores::Guard.read_set(treat_as_read)
31
+ @active = true
32
+ Firestore.register(self)
33
+ begin
34
+ install_hooks
35
+ refuse_live_clients
36
+ rescue StandardError
37
+ unhook!
38
+ raise
39
+ end
40
+ end
41
+
42
+ def system = "firestore"
43
+
44
+ def describe
45
+ { system: "firestore", name: @name, mode: :guard }
46
+ end
47
+
48
+ # Turns the guard off. Clients keep their interceptor, which then does nothing, and guards for the
49
+ # next store registered.
50
+ def unhook!
51
+ @active = false
52
+ Firestore.unregister(self)
53
+ end
54
+
55
+ # @return [Boolean] whether the guard is still on
56
+ def active? = @active
57
+
58
+ # Guards and logs one call around +block+, which sends it.
59
+ #
60
+ # @param rpc [String] the gRPC path, such as +/google.firestore.v1.Firestore/Commit+
61
+ # @param message [Object, nil] the request message, when the call has one
62
+ def around(rpc, message)
63
+ return yield unless @active
64
+
65
+ result = Stores::Classify.firestore(rpc, message, @reads)
66
+ return yield if result.kind == :session
67
+
68
+ Stores::Guard.guard("firestore", result.operation, result.kind)
69
+ recorder = Capture.current
70
+ return yield unless recorder
71
+
72
+ fields = message.to_h if !message.nil? && message.respond_to?(:to_h)
73
+ entry = { system: "firestore", operation: result.operation, target: collection_of(fields),
74
+ statement: fields && JSON.generate(Stores::Guard.sanitize_document(fields)) }
75
+ started = Clock.now
76
+ begin
77
+ response = yield
78
+ rescue StandardError => error
79
+ recorder.db(**entry, error: error.class.name.to_s.split("::").last, duration_ms: Clock.elapsed_ms(started))
80
+ raise
81
+ end
82
+ recorder.db(**entry, duration_ms: Clock.elapsed_ms(started))
83
+ response
84
+ end
85
+
86
+ # Guards a write a +BulkWriter+ is about to queue, as the +BatchWrite+ it will be sent in. Called on
87
+ # the handler's thread, so in a Preview the write is refused before the writer's threads see it.
88
+ def guard_bulk_write
89
+ return unless @active
90
+
91
+ Stores::Guard.guard("firestore", "BatchWrite", Stores::Classify.firestore("BatchWrite", nil, @reads).kind)
92
+ end
93
+
94
+ private
95
+
96
+ # Prepends the hooks that cover clients built later, once per process.
97
+ def install_hooks
98
+ ::Gapic::ServiceStub.prepend(StubHook) unless ::Gapic::ServiceStub < StubHook
99
+ bulk = ::Google::Cloud::Firestore::BulkWriter
100
+ bulk.prepend(BulkWriterHook) unless bulk < BulkWriterHook
101
+ rest = rest_client_class
102
+ rest.prepend(RestRefusal) if rest && !(rest < RestRefusal)
103
+ end
104
+
105
+ # A Firestore client built before this store has no interceptor and writes straight through.
106
+ def refuse_live_clients
107
+ # A REST client whose construction was refused never got a stub, so it is no live client.
108
+ if rest_client_class && ObjectSpace.each_object(rest_client_class).any? { |client| client.instance_variable_defined?(:@firestore_stub) }
109
+ raise ConfigurationError, RestRefusal::REASON
110
+ end
111
+ unguarded = ObjectSpace.each_object(::Gapic::ServiceStub).select do |stub|
112
+ Firestore.firestore_stub?(stub_class_of(stub)) && !stub.instance_variable_get(:@sendproof_guarded)
113
+ end
114
+ return if unguarded.empty?
115
+
116
+ raise ConfigurationError, "A Firestore client was built before this store, so its calls aren't guarded. " \
117
+ "Create Sendproof::Firestore::Store before any Firestore client."
118
+ end
119
+
120
+ def rest_client_class
121
+ ::Google::Cloud::Firestore::V1::Firestore::Rest::Client if defined?(::Google::Cloud::Firestore::V1::Firestore::Rest::Client)
122
+ end
123
+
124
+ # The generated gRPC stub class behind a +Gapic::ServiceStub+, single channel or pooled.
125
+ def stub_class_of(stub)
126
+ stub.instance_variable_get(:@grpc_stub)&.class ||
127
+ stub.instance_variable_get(:@channel_pool)&.instance_variable_get(:@grpc_stub_class)
128
+ end
129
+
130
+ # The collection a request names, for +db.collection.name+: the query's collection, or the one a
131
+ # document path in the message sits in.
132
+ def collection_of(fields)
133
+ return nil unless fields.is_a?(Hash)
134
+
135
+ from = fields.dig(:structured_query, :from, 0, :collection_id) ||
136
+ fields.dig(:structured_aggregation_query, :structured_query, :from, 0, :collection_id) ||
137
+ fields.dig(:add_target, :query, :structured_query, :from, 0, :collection_id) ||
138
+ fields[:collection_id]
139
+ return from if from.is_a?(String) && !from.empty?
140
+
141
+ name = fields.dig(:documents, 0) || fields.dig(:writes, 0, :update, :name) || fields.dig(:writes, 0, :delete) ||
142
+ fields.dig(:add_target, :documents, :documents, 0) || fields[:name]
143
+ segments = name.to_s.split("/documents/", 2)[1]&.split("/")
144
+ return nil unless segments&.any?
145
+
146
+ segments.length.even? ? segments[-2] : segments[-1]
147
+ end
148
+ end
149
+ end
150
+ end
@@ -0,0 +1,99 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "grpc"
4
+ require "gapic/grpc"
5
+ require "google/cloud/firestore"
6
+ require "sendproof"
7
+
8
+ module Sendproof
9
+ # Sendproof write guard for Google Cloud Firestore (spec/data-stores.md, +guard+ mode), for the
10
+ # +google-cloud-firestore+ gem over gRPC and every generated Firestore client under it.
11
+ #
12
+ # store = Sendproof::Firestore::Store.new(name: "orders") # create it before any Firestore client
13
+ # config.sendproof.data_store store
14
+ #
15
+ # Require it explicitly: +require "sendproof/firestore"+. It needs no Firestore server.
16
+ #
17
+ # A gRPC client interceptor sees every call before it is sent, unary or streaming, which is why the
18
+ # hook sits there: +Write+ is a bidirectional stream and a unary-only hook would let it through.
19
+ module Firestore
20
+ autoload :Interceptor, "sendproof/firestore/interceptor"
21
+ autoload :Store, "sendproof/firestore/store"
22
+
23
+ @store = nil
24
+ @mutex = Mutex.new
25
+
26
+ class << self
27
+ # The store guarding Firestore, or +nil+. The interceptor asks on every call, so replacing a store
28
+ # never leaves a client pointing at an old one.
29
+ def store = @mutex.synchronize { @store }
30
+
31
+ # Registers +store+ as the one guarding Firestore.
32
+ # @raise [ConfigurationError] when another store is already guarding it
33
+ def register(store)
34
+ @mutex.synchronize do
35
+ raise ConfigurationError, "A Firestore store is already registered; call unhook! on it first." if @store&.active?
36
+
37
+ @store = store
38
+ end
39
+ end
40
+
41
+ # Removes +store+ from the registry, if it is the registered one.
42
+ def unregister(store) = @mutex.synchronize { @store = nil if @store.equal?(store) }
43
+
44
+ # Whether a gRPC stub class belongs to a Firestore client (the data or admin API).
45
+ def firestore_stub?(grpc_stub_class) = grpc_stub_class.respond_to?(:name) && grpc_stub_class.name.to_s.start_with?("Google::Cloud::Firestore::")
46
+ end
47
+
48
+ # Prepended to +Gapic::ServiceStub+, the one place every generated Google client gets its gRPC channel.
49
+ # While a store is registered it adds the guard interceptor to each Firestore stub, however the client
50
+ # was configured: a host that replaces +config.interceptors+ can't drop it. A stub built with no store
51
+ # registered is not guarded, and the next store refuses to start while one is alive.
52
+ module StubHook
53
+ def initialize(grpc_stub_class, **options)
54
+ if Sendproof::Firestore.store&.active? && Sendproof::Firestore.firestore_stub?(grpc_stub_class)
55
+ @sendproof_guarded = true
56
+ options[:interceptors] = [Sendproof::Firestore::Interceptor.new, *Array(options[:interceptors])]
57
+ end
58
+ super
59
+ end
60
+ end
61
+
62
+ # Prepended to +Google::Cloud::Firestore::BulkWriter+. A BulkWriter sends from threads of its own, which
63
+ # carry no request, and retries a failed batch without end, so the guard runs as the handler queues
64
+ # each write instead: in a Preview the write is refused before it is queued.
65
+ module BulkWriterHook
66
+ def create(...)
67
+ Sendproof::Firestore.store&.guard_bulk_write
68
+ super
69
+ end
70
+
71
+ def set(...)
72
+ Sendproof::Firestore.store&.guard_bulk_write
73
+ super
74
+ end
75
+
76
+ def update(...)
77
+ Sendproof::Firestore.store&.guard_bulk_write
78
+ super
79
+ end
80
+
81
+ def delete(...)
82
+ Sendproof::Firestore.store&.guard_bulk_write
83
+ super
84
+ end
85
+ end
86
+
87
+ # Prepended to the REST clients, which have no interceptor and so can't be guarded: with a store
88
+ # registered, building one fails instead of leaving writes unguarded.
89
+ module RestRefusal
90
+ REASON = "Sendproof can't guard Firestore over REST. Use the default gRPC transport."
91
+
92
+ def initialize(*, **)
93
+ raise ConfigurationError, REASON if Sendproof::Firestore.store&.active?
94
+
95
+ super
96
+ end
97
+ end
98
+ end
99
+ end
@@ -0,0 +1,23 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ # The hook a framework adapter (or a Rack-only application) wraps around the real endpoint handler.
5
+ #
6
+ # Authorization and routing run before the block, so a rejected request never reaches it.
7
+ # The block is the point where preview rollback and observed-send capture are anchored.
8
+ module Handler
9
+ module_function
10
+
11
+ # Runs the block as the endpoint handler.
12
+ #
13
+ # @param env [Hash] Rack environment of the request being handled
14
+ # @param eligible [Boolean] whether the endpoint is preview-enabled
15
+ # @raise [IneligibleHandler] during a preview when +eligible+ is false (the block does not run)
16
+ def around(env, request: nil, eligible: true, &block)
17
+ context = env[ENV_KEY]
18
+ return yield unless context
19
+
20
+ context.around_handler(request: request || Rack::Request.new(env), eligible:, &block)
21
+ end
22
+ end
23
+ end
@@ -0,0 +1,37 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ # The authenticated principal as the workbench shows it, plus the stable subject that owns traces.
5
+ #
6
+ # Build one from a Hash (+name+, +role+, +subject+, +authentication+, +issuer+) or any object responding to those.
7
+ Identity = Data.define(:name, :role, :subject, :authentication, :issuer) do
8
+ # @return [Identity, nil]
9
+ def self.from(value)
10
+ case value
11
+ when nil, false then nil
12
+ when Identity then value
13
+ when Hash
14
+ h = value.transform_keys(&:to_sym)
15
+ new(name: h[:name], role: h[:role], subject: h[:subject], authentication: h[:authentication], issuer: h[:issuer])
16
+ else
17
+ read = ->(reader) { value.respond_to?(reader) ? value.public_send(reader) : nil }
18
+ new(name: read.(:name), role: read.(:role), subject: read.(:subject),
19
+ authentication: read.(:authentication), issuer: read.(:issuer))
20
+ end
21
+ end
22
+
23
+ # @return [Owner, nil] nil unless the identity carries a usable stable subject
24
+ def owner(path_base)
25
+ subject = self.subject.to_s
26
+ authentication = (self.authentication || "session").to_s
27
+ issuer = self.issuer.to_s
28
+ return nil if subject.empty? || subject.length > 256 || authentication.length > 256 ||
29
+ issuer.length > 256 || path_base.to_s.length > 4096
30
+
31
+ Owner.new(authentication:, subject:, issuer:, path_base: path_base.to_s)
32
+ end
33
+ end
34
+
35
+ # Identifies who may read a trace: the same subject, authentication context and mount.
36
+ Owner = Data.define(:authentication, :subject, :issuer, :path_base)
37
+ end