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,44 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ # State of one rollback preview, stored in the Rack environment under {ENV_KEY}.
5
+ class PreviewRequest
6
+ attr_reader :clock, :recorder
7
+ # @return [#rollback!, nil] the provider session opened before the handler ran
8
+ attr_accessor :session
9
+
10
+ def initialize(recorder:, clock:)
11
+ @recorder = recorder
12
+ @clock = clock
13
+ @invoked = false
14
+ @completed = false
15
+ @rejected = false
16
+ end
17
+
18
+ # @return [Boolean] whether the endpoint handler started
19
+ def invoked? = @invoked
20
+ # @return [Boolean] whether the endpoint handler returned normally
21
+ def completed? = @completed
22
+ # @return [Boolean] whether the handler was refused because the endpoint is not preview-enabled
23
+ def rejected? = @rejected
24
+
25
+ # Marks the handler complete when the framework turned its exception into a handled client-error response.
26
+ def complete!
27
+ @completed = true
28
+ end
29
+
30
+ # Wraps the endpoint handler. See {Handler.around}.
31
+ def around_handler(request:, eligible:)
32
+ if !eligible || @invoked
33
+ @rejected = true
34
+ raise IneligibleHandler, "The endpoint is not enabled for Sendproof preview."
35
+ end
36
+
37
+ @invoked = true
38
+ @clock.start_handler
39
+ result = yield
40
+ @completed = true
41
+ result
42
+ end
43
+ end
44
+ end
@@ -0,0 +1,331 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ # Runs a request through the application's real middleware and handler, then rolls it back
5
+ # and answers with a confirmed envelope (preview.schema.json).
6
+ #
7
+ # Nothing here returns a successful envelope unless the endpoint handler ran to completion,
8
+ # the provider confirmed the rollback, and the buffered response stayed within its limit.
9
+ class PreviewTransport
10
+ # The inner response exceeded {Limits::RESPONSE_BYTES}.
11
+ class ResponseTooLarge < StandardError; end
12
+
13
+ # Result of draining the inner response body.
14
+ Response = Struct.new(:status, :headers, :body)
15
+
16
+ def initialize(app, config)
17
+ @app = app
18
+ @config = config
19
+ end
20
+
21
+ # @param env [Hash] the Rack environment of the +/sendproof/_preview/...+ request
22
+ # @param prefix [Integer] index of the reserved prefix in PATH_INFO
23
+ # @return [Array] Rack response
24
+ def call(env, request, prefix)
25
+ started = Clock.now
26
+ path = env["PATH_INFO"].to_s
27
+ rejection = precheck(env, request, path, prefix)
28
+ return rejection if rejection.is_a?(Array)
29
+
30
+ rewritten = path[0, prefix] + path[(prefix + Protocol::PREFIX.length)..]
31
+ resolution = @config.resolve_target(request.request_method, rewritten, env)
32
+ return Protocol.problem(404, "The preview target was not found for this method.") if resolution.nil?
33
+ return Protocol.problem(409, "This operation is unavailable for preview.") if resolution == :ineligible
34
+
35
+ provider = @config.preview_provider
36
+ return Protocol.problem(503, "Preview requires one available preview provider.") unless provider
37
+
38
+ execute(env, request, provider, rewritten, started)
39
+ end
40
+
41
+ private
42
+
43
+ def precheck(env, request, path, prefix)
44
+ return Protocol.problem(400, "A Sendproof preview requires Prefer: tx=rollback.") unless Protocol.exact_preference?(env)
45
+ return Protocol.problem(405, "A preview requires a response body.") if request.head?
46
+
47
+ target = path[(prefix + Protocol::PREFIX.length)..]
48
+ if target.empty? || target.start_with?("//") || bench_target?(target) || !valid_target?(target)
49
+ return Protocol.problem(400, "The Sendproof preview target is invalid.")
50
+ end
51
+ return Protocol.problem(403, "A preview must come from the application's own origin.") unless Protocol.same_origin?(request)
52
+ return denied(request) unless @config.authorized?(request)
53
+
54
+ nil
55
+ end
56
+
57
+ def denied(request)
58
+ @config.identity_for(request) ? Protocol.problem(403, "This preview is forbidden.") :
59
+ Protocol.problem(401, "Authentication is required for this preview.")
60
+ end
61
+
62
+ def bench_target?(target)
63
+ target.casecmp?("/sendproof") || target.downcase.start_with?("/sendproof/")
64
+ end
65
+
66
+ def valid_target?(target)
67
+ decoded = Rack::Utils.unescape_path(target)
68
+ decoded.valid_encoding? && !decoded.start_with?("//") && !decoded.include?("\\") &&
69
+ decoded.match?(/\A[^[:cntrl:]]*\z/) && decoded.split("/").none? { |segment| [".", ".."].include?(segment) }
70
+ rescue ArgumentError
71
+ false
72
+ end
73
+
74
+ # Runs one preview in the order spec/data-stores.md fixes: begin the SQL transaction and each
75
+ # store, run the handler, finish every store (capture changes, abort its transaction), then roll
76
+ # back SQL. Afterwards a failed step or a recorded fault answers 500, a refused write answers 409,
77
+ # and only then is the preview confirmed.
78
+ def execute(env, request, provider, rewritten, started)
79
+ recorder = Recorder.new(rollback: true, started:, include_sql_values: @config.sql_parameter_values?)
80
+ preview = PreviewRequest.new(recorder:, clock: Clock::Request.new(started))
81
+ failure = nil # a begin, finish or rollback step failed: nothing can be confirmed
82
+ handler_failure = nil # the handler raised, or its response was unusable
83
+ response = nil
84
+ envelope = nil
85
+ context = ProviderContext.new(env:, request:, config: @config)
86
+ escaped = nil # an error that isn't a StandardError (a timeout, an interrupt): re-raised after cleanup
87
+
88
+ # While it is open, a store write that belongs to no request fails this Preview (see {Attribution}).
89
+ Attribution.open(recorder)
90
+ begin
91
+ Capture.with(recorder) do
92
+ begin
93
+ preview.session = provider.begin_preview(context)
94
+ raise "The preview provider returned no session." unless preview.session
95
+
96
+ @config.data_stores.each { |store| store.begin_preview(context, recorder) if store.respond_to?(:begin_preview) }
97
+ response, handler_failure = dispatch(env, rewritten, preview)
98
+ rescue StandardError => error
99
+ failure = combine(failure, error)
100
+ rescue Exception => error # rubocop:disable Lint/RescueException -- stores and SQL must still be aborted
101
+ # rack-timeout, Timeout and Interrupt unwind with errors outside StandardError. Skipping the steps
102
+ # below would leave a store transaction open and the SQL connection (and its MySQL turn) held.
103
+ escaped = error
104
+ failure = combine(failure, error)
105
+ end
106
+
107
+ # Every store finishes before the SQL rollback, and one that fails, however it fails, never stops
108
+ # the others or the rollback.
109
+ @config.data_stores.each do |store|
110
+ store.finish_preview(recorder) if store.respond_to?(:finish_preview)
111
+ rescue StandardError => error
112
+ failure = combine(failure, error)
113
+ rescue Exception => error # rubocop:disable Lint/RescueException -- the rollback must still run
114
+ escaped ||= error
115
+ failure = combine(failure, error)
116
+ end
117
+
118
+ if (session = preview.session)
119
+ begin
120
+ session.rollback!
121
+ session.finalize_capture(recorder) if session.respond_to?(:finalize_capture)
122
+ if failure.nil? && handler_failure.nil? && preview.completed? && response && !recorder.fault && !recorder.blocked
123
+ envelope = [response, session, recorder.finish]
124
+ end
125
+ rescue StandardError => error
126
+ failure = combine(failure, error)
127
+ ensure
128
+ recorder.finish if recorder.active?
129
+ begin
130
+ session.close
131
+ rescue StandardError => error
132
+ failure = combine(failure, error)
133
+ end
134
+ end
135
+ end
136
+ end
137
+ ensure
138
+ Attribution.close(recorder)
139
+ end
140
+ raise escaped if escaped
141
+
142
+ preview.clock.end_handler
143
+ skip_session_commit(env)
144
+
145
+ outcome(request, preview, response, failure, handler_failure, recorder, envelope)
146
+ end
147
+
148
+ # Runs the inner request. Returns the buffered response and any failure.
149
+ def dispatch(env, rewritten, preview)
150
+ inner = inner_env(env, rewritten, preview)
151
+ begin
152
+ status, headers, body = @app.call(inner)
153
+ [drain(status, headers, body), nil]
154
+ rescue ResponseTooLarge => error
155
+ [nil, error]
156
+ rescue IneligibleHandler
157
+ [nil, nil]
158
+ rescue StandardError => error
159
+ mapped = @config.status_for_error(error)
160
+ return [nil, error] unless mapped
161
+
162
+ preview.complete! if preview.invoked?
163
+ [handled_error(mapped), nil]
164
+ end
165
+ end
166
+
167
+ def handled_error(status)
168
+ title = Rack::Utils::HTTP_STATUS_CODES[status] || "Error"
169
+ Response.new(status, { "content-type" => "application/problem+json" },
170
+ JSON.generate({ type: "about:blank", title:, status: }))
171
+ end
172
+
173
+ # The environment the application sees: the original request at its real path, with caches
174
+ # from the outer request cleared so routing and parameters are computed again.
175
+ def inner_env(env, rewritten, preview)
176
+ inner = env.dup
177
+ inner.delete_if do |key, _|
178
+ key.start_with?("action_dispatch.request.", "rack.request.query", "rack.request.form") ||
179
+ %w[action_dispatch.cookies action_dispatch.route_uri_pattern rack.hijack rack.upgrade].include?(key)
180
+ end
181
+ inner["PATH_INFO"] = rewritten
182
+ query = env["QUERY_STRING"].to_s
183
+ full = env["SCRIPT_NAME"].to_s + rewritten + (query.empty? ? "" : "?#{query}")
184
+ inner["REQUEST_PATH"] = env["SCRIPT_NAME"].to_s + rewritten if env.key?("REQUEST_PATH")
185
+ inner["REQUEST_URI"] = full if env.key?("REQUEST_URI")
186
+ inner["ORIGINAL_FULLPATH"] = full if env.key?("ORIGINAL_FULLPATH")
187
+ inner["rack.hijack?"] = false
188
+ inner.delete("HTTP_ACCEPT_ENCODING")
189
+ inner["HTTP_CACHE_CONTROL"] = "no-cache, no-store"
190
+ inner["rack.input"].rewind if inner["rack.input"].respond_to?(:rewind)
191
+ inner[ENV_KEY] = preview
192
+ inner
193
+ end
194
+
195
+ # The preview must not persist the session or write cookies on the real response.
196
+ def skip_session_commit(env)
197
+ options = env["rack.session.options"]
198
+ options[:skip] = true if options.respond_to?(:[]=)
199
+ end
200
+
201
+ def drain(status, headers, body)
202
+ buffer = String.new(encoding: Encoding::BINARY)
203
+ append = lambda do |chunk|
204
+ buffer << chunk.to_s
205
+ raise ResponseTooLarge if buffer.bytesize > Limits::RESPONSE_BYTES
206
+ end
207
+ begin
208
+ if body.respond_to?(:each)
209
+ body.each(&append)
210
+ elsif body.respond_to?(:call)
211
+ body.call(BoundedStream.new(append))
212
+ end
213
+ ensure
214
+ body.close if body.respond_to?(:close)
215
+ end
216
+ Response.new(status.to_i, normalize(headers), buffer)
217
+ end
218
+
219
+ def normalize(headers)
220
+ headers.each_with_object({}) do |(name, value), result|
221
+ result[name.to_s.downcase] = Array(value).join(", ")
222
+ end
223
+ end
224
+
225
+ def outcome(request, preview, response, failure, handler_failure, recorder, envelope)
226
+ fault = failure || recorder.fault
227
+ if fault
228
+ log_failure(request, fault)
229
+ return Protocol.problem(500, "The preview could not be completed safely.")
230
+ end
231
+ # The refused-write mark decides, whatever the handler did with the error or returned.
232
+ return blocked_response(recorder.blocked) if recorder.blocked
233
+
234
+ if handler_failure
235
+ log_failure(request, handler_failure)
236
+ return handler_failure.is_a?(ResponseTooLarge) ? too_large : Protocol.problem(500, "The preview could not be completed safely.")
237
+ end
238
+ return reject_unexecuted(preview, response) unless envelope
239
+
240
+ response, session, capture = envelope
241
+ serialize(response, session, capture, preview)
242
+ end
243
+
244
+ def log_failure(request, failure)
245
+ @config.logger&.error("A Sendproof preview failed for #{request.request_method} #{request.path}: " \
246
+ "#{failure.class}: #{failure.message}")
247
+ end
248
+
249
+ # The blocked-Preview response of spec/data-stores.md: 409 problem+json, never a confirmation. It
250
+ # carries nothing the handler produced and names the command, never its arguments.
251
+ def blocked_response(blocked)
252
+ body = JSON.generate({ type: "about:blank", title: "Preview unavailable", status: 409, code: "preview_unavailable",
253
+ detail: blocked.detail, store: blocked.store, operation: blocked.operation, rolledBack: false })
254
+ [409, { "content-type" => "application/problem+json", "cache-control" => "no-store",
255
+ "content-length" => body.bytesize.to_s }, [body]]
256
+ end
257
+
258
+ def too_large = Protocol.problem(413, "The preview response exceeds the 1 MiB limit.")
259
+
260
+ def reject_unexecuted(preview, response)
261
+ return Protocol.problem(500, "The preview operation did not finish.") if preview.invoked?
262
+ return Protocol.problem(409, "This operation is unavailable for preview.") if preview.rejected? || response.nil?
263
+
264
+ status = response.status
265
+ title = case status
266
+ when 401 then "Authentication is required for this preview."
267
+ when 403 then "This preview is forbidden."
268
+ when 404, 405 then "The preview target was not found for this method."
269
+ when 503 then "Preview requires one available preview provider."
270
+ when 300...400 then "Preview redirects are disabled. Sign in through the workbench first."
271
+ when 400...500 then status == 409 ? "This operation is unavailable for preview." : "The host rejected the preview request."
272
+ else "This operation is unavailable for preview."
273
+ end
274
+ status = status.between?(300, 399) ? 401 : 409 if status < 400 || (status >= 500 && status != 503)
275
+ extra = {}
276
+ challenge = response.headers["www-authenticate"]
277
+ extra["www-authenticate"] = challenge if challenge
278
+ Protocol.problem(status, title, extra)
279
+ end
280
+
281
+ def serialize(response, session, capture, preview)
282
+ changes, truncated = Limits.snapshot_changes(session.changes + capture.changes)
283
+ headers = response.headers.reject { |name, _| Protocol::PRIVATE_HEADERS.include?(name) || name.length > Limits::NAME }
284
+ .first(Limits::PARAMETERS).to_h { |name, value| [name, Limits.clip(value)] }
285
+ document = { status: response.status, headers:, body: read_body(response), changes:,
286
+ effects: capture.effects, logs: capture.logs, rolledBack: true }
287
+ document[:changesTruncated] = true if truncated || session.changes_truncated? || capture.changes_truncated
288
+ document[:effectsTruncated] = true if capture.effects_truncated
289
+ document[:logsTruncated] = true if capture.logs_truncated
290
+ started = Clock.now
291
+ json = JSON.generate(document)
292
+ timing = preview.recorder.timing(preview.clock, Clock.elapsed_ms(started))
293
+ [200, { "content-type" => Protocol::JSON_TYPE, "cache-control" => "no-store",
294
+ "preference-applied" => Protocol::ROLLBACK_PREFERENCE,
295
+ "server-timing" => Clock.server_timing(timing), "content-length" => json.bytesize.to_s }, [json]]
296
+ end
297
+
298
+ # JSON bodies are parsed, text is returned as a string and anything else is base64.
299
+ def read_body(response)
300
+ bytes = response.body
301
+ return nil if bytes.empty?
302
+
303
+ type = response.headers["content-type"].to_s.split(";", 2).first.to_s.strip.downcase
304
+ text = bytes.dup.force_encoding(Encoding::UTF_8)
305
+ if type == "application/json" || type.end_with?("+json")
306
+ begin
307
+ return JSON.parse(text)
308
+ rescue JSON::ParserError
309
+ return text.scrub
310
+ end
311
+ end
312
+ return text.scrub if type.empty? || type.start_with?("text/")
313
+
314
+ [bytes].pack("m0")
315
+ end
316
+
317
+ def combine(previous, error)
318
+ previous.nil? ? error : error.tap { |e| e.define_singleton_method(:cause) { previous } }
319
+ end
320
+
321
+ # Receives the chunks of a streaming (+call+) Rack body.
322
+ class BoundedStream
323
+ def initialize(sink) = @sink = sink
324
+ def write(chunk) = (@sink.call(chunk); chunk.to_s.bytesize)
325
+ def <<(chunk) = (write(chunk); self)
326
+ def flush = self
327
+ def close = nil
328
+ def closed? = false
329
+ end
330
+ end
331
+ end
@@ -0,0 +1,81 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "uri"
4
+
5
+ module Sendproof
6
+ # Wire-level helpers of bench protocol v1.
7
+ module Protocol
8
+ PREFIX = "/sendproof/_preview"
9
+ ROLLBACK_PREFERENCE = "tx=rollback"
10
+ TRACE_HEADER = "x-sendproof-trace"
11
+ JSON_TYPE = "application/json; charset=utf-8"
12
+
13
+ # Headers of the inner response that never reach the envelope.
14
+ PRIVATE_HEADERS = %w[set-cookie location content-length transfer-encoding connection upgrade trailer
15
+ keep-alive proxy-authenticate proxy-authorization te].freeze
16
+
17
+ module_function
18
+
19
+ # @return [Boolean] whether the request asks for a rollback in any form
20
+ def requests_rollback?(env)
21
+ env["HTTP_PREFER"].to_s.split(/[,;]/).any? do |part|
22
+ name, value = part.split("=", 2).map(&:strip)
23
+ value && name.casecmp?("tx") && value.delete_prefix('"').delete_suffix('"').casecmp?("rollback")
24
+ end
25
+ end
26
+
27
+ # The single, exact +Prefer: tx=rollback+ value required by the preview route.
28
+ def exact_preference?(env)
29
+ env["HTTP_PREFER"].to_s.strip.casecmp?(ROLLBACK_PREFERENCE)
30
+ end
31
+
32
+ # @return [Boolean] whether +Prefer+ lists the +trace+ token
33
+ def requests_trace?(env)
34
+ env["HTTP_PREFER"].to_s.split(",").any? { |value| value.split(";", 2).first.strip.casecmp?("trace") }
35
+ end
36
+
37
+ # Rejects cross-site browsers and any Origin that does not match the request origin.
38
+ def same_origin?(request)
39
+ return false if request.get_header("HTTP_SEC_FETCH_SITE").to_s.casecmp?("cross-site")
40
+
41
+ origin = request.get_header("HTTP_ORIGIN")
42
+ return true if origin.nil?
43
+ return false if origin.include?(",")
44
+
45
+ uri = URI.parse(origin)
46
+ uri.scheme == request.scheme && uri.host.to_s.casecmp?(request.host) && uri.port == request.port &&
47
+ uri.userinfo.nil? && ["", "/"].include?(uri.path) && uri.query.nil? && uri.fragment.nil?
48
+ rescue URI::InvalidURIError
49
+ false
50
+ end
51
+
52
+ # A Rack response carrying an RFC 9457 problem document, never cacheable.
53
+ def problem(status, title, headers = {})
54
+ body = JSON.generate({ type: "about:blank", title:, status: })
55
+ [status, { "content-type" => "application/problem+json", "cache-control" => "no-store",
56
+ "content-length" => body.bytesize.to_s }.merge(headers), [body]]
57
+ end
58
+
59
+ def json(status, document, headers = {})
60
+ body = JSON.generate(document)
61
+ [status, { "content-type" => JSON_TYPE, "content-length" => body.bytesize.to_s }.merge(headers), [body]]
62
+ end
63
+
64
+ # Case-insensitive header lookup that tolerates plain hashes with mixed-case keys.
65
+ def header(headers, name)
66
+ key = headers.keys.find { |candidate| candidate.to_s.casecmp?(name) }
67
+ key && headers[key]
68
+ end
69
+
70
+ def set_header(headers, name, value)
71
+ key = headers.keys.find { |candidate| candidate.to_s.casecmp?(name) } || name
72
+ headers[key] = value
73
+ end
74
+
75
+ # Appends +value+ to a comma-separated header.
76
+ def append_header(headers, name, value)
77
+ existing = header(headers, name)
78
+ set_header(headers, name, existing.nil? || existing.to_s.empty? ? value : "#{Array(existing).join(', ')}, #{value}")
79
+ end
80
+ end
81
+ end
@@ -0,0 +1,83 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ # Describes what a provider receives when a preview or observation begins.
5
+ # @!attribute env [Hash] the Rack environment of the original request
6
+ # @!attribute request [Rack::Request]
7
+ # @!attribute config [Configuration]
8
+ ProviderContext = Data.define(:env, :request, :config)
9
+
10
+ # Base class and contract for a persistence provider.
11
+ #
12
+ # A provider opens a rollback-only session on the connection the request handler will use,
13
+ # captures change snapshots, rolls back explicitly, and releases every resource on every
14
+ # failure path. Subclassing is optional; any object with these methods works.
15
+ class Provider
16
+ # @return [Boolean] whether this request can be previewed
17
+ def available?
18
+ true
19
+ end
20
+
21
+ # @return [String, nil] a display label for the database; never connection details
22
+ def database
23
+ nil
24
+ end
25
+
26
+ # @return [String, nil] the SQL provider id, matching the workbench's store marks: +sqlite+,
27
+ # +postgresql+, +mysql+, +mariadb+, +mssql+. Capabilities then name the database as
28
+ # +{name:, system:}+ so the workbench shows the right mark instead of guessing from the name.
29
+ def database_system
30
+ nil
31
+ end
32
+
33
+ # Starts the transaction before the handler runs.
34
+ # @param context [ProviderContext]
35
+ # @return [PreviewSession]
36
+ def begin_preview(context)
37
+ raise NotImplementedError, "#{self.class} must implement begin_preview"
38
+ end
39
+
40
+ # Optionally observes changes of an ordinary send without managing its transaction.
41
+ # @return [Observation, nil]
42
+ def begin_observation(_context)
43
+ nil
44
+ end
45
+
46
+ # The rollback-only session for one preview request.
47
+ #
48
+ # Duck-typed interface: +changes+ (array of hashes with +:operation+, +:table+, +:key+, +:before+, +:after+),
49
+ # +changes_truncated?+, +rollback!+ (raise on failure), +close+ (idempotent) and optionally
50
+ # +finalize_capture(recorder)+, called after rollback while the recorder is still active.
51
+ class PreviewSession
52
+ def changes = []
53
+ def changes_truncated? = false
54
+
55
+ def rollback!
56
+ raise NotImplementedError
57
+ end
58
+
59
+ def close; end
60
+ end
61
+
62
+ # Observes an ordinary send. Interface: +changes+, +changes_truncated?+, +close+, and optionally
63
+ # +finalize_capture(recorder)+ called before the trace is built.
64
+ class Observation
65
+ def changes = []
66
+ def changes_truncated? = false
67
+ def close; end
68
+ end
69
+
70
+ # The provider used when the host registered data stores but no SQL provider. It opens no
71
+ # transaction: each store aborts its own and guards its writes, so a Preview needs no database.
72
+ class None < Provider
73
+ # A session with nothing to roll back.
74
+ class Session < PreviewSession
75
+ def rollback! = nil
76
+ end
77
+
78
+ def begin_preview(_context) = Session.new
79
+
80
+ def begin_observation(_context) = Observation.new
81
+ end
82
+ end
83
+ end