sendproof-activerecord 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.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 130911ae0f268e2899b93c1eec06c16e85aa5124a6a5d7cbcc896907b110b860
4
+ data.tar.gz: 52615d83084877515331f64cec061d73463477f44ea501c5bc81f128e75a07db
5
+ SHA512:
6
+ metadata.gz: c7f5dda5402e794795697228ad238597a9b11f4244ee4764e9ae6e149229cd345a9106920a671d505fbd1e3610881a9ef4e65f3cde1e305fd78df15ef8403c1f
7
+ data.tar.gz: c5177c9655d27429b6deceb6672274630a8cdd55a81d3f164bcab48734eab079bf0a3f713f09d3af146aca565154b5134594da78ecf376922f34f550e5a1c2c1
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sendproof contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,39 @@
1
+ # sendproof-activerecord
2
+
3
+ ActiveRecord preview provider for [Sendproof](../README.md).
4
+
5
+ ```ruby
6
+ config.sendproof.use Sendproof::ActiveRecord::Provider.new # default connection
7
+ config.sendproof.use Sendproof::ActiveRecord::Provider.new(
8
+ database: "inventory_dev", # display label only
9
+ connection_classes: [ApplicationRecord, AnalyticsRecord] # every database the handler writes
10
+ )
11
+ ```
12
+
13
+ ## How a preview works
14
+
15
+ 1. Before the request is dispatched, a **non-joinable transaction** begins on each listed connection's leased connection. The handler's own `transaction` blocks become savepoints; they cannot commit it.
16
+ 2. Model callbacks (`after_create`, `after_update`, `after_destroy`) record `insert` / `update` / `delete` with the real primary key (composite keys included) and before/after snapshots. A change rolled back by the handler's own savepoint is removed.
17
+ 3. `sql.active_record` notifications become SQL log entries. Values are shown only when `include_sql_parameter_values` allows it, and any statement or parameter whose name contains a secret word (`password`, `token`, `api_key`, `hash`, …) is `[REDACTED]`.
18
+ 4. After the handler returns, the session rolls back, verifies that the transaction is rolled back (a handler that committed it makes the preview fail instead of confirming), and releases the connection state.
19
+
20
+ ## Coverage
21
+
22
+ Rollback covers every statement on the enrolled connections. The **diff** covers what model callbacks see. `update_all`, `delete_all`, `insert_all`, `touch`, raw SQL and database triggers still roll back, are never synthesized into before/after rows, and cause a `Warning` log ("N write statement(s) bypassed model callbacks"). `after_commit` callbacks run at each inner transaction boundary (Rails treats a non-joinable parent like a transactional test), so send their side effects through `Sendproof.deliver`. Databases the provider does not list, other threads, caches, files and external services are not enrolled.
23
+
24
+ Tested with ActiveRecord 8.0.5.2 on SQLite, through Trilogy on MySQL 8.4, and through the `pg` gem on PostgreSQL 17. On PostgreSQL a unique violation aborts the transaction, and the savepoint backstop's `ROLLBACK TO SAVEPOINT` clears that state, so a handler that answers 409 after one still rolls back cleanly. `rowsAffected` is omitted because `sql.active_record` does not report affected rows for writes.
25
+
26
+ ## Transaction control and MySQL
27
+
28
+ - A handler statement that would end or escape the Preview transaction (`COMMIT`, `END`, `ROLLBACK` without `TO`, `BEGIN`, `SET autocommit` anywhere in a `SET`, the provider's `sendproof_preview` savepoint, and on MySQL and MariaDB the statements that commit implicitly, SQL-level `PREPARE` and `EXECUTE` (and MariaDB's `EXECUTE IMMEDIATE`), executable comments containing any of these, and `CALL`) is refused before it reaches the database, and the Preview answers 500 without confirmation. `SAVEPOINT` stays allowed. Statements sent on `connection.raw_connection` are not covered.
29
+ - **Stored procedures (MySQL and MariaDB).** A procedure can `COMMIT`, so `CALL` is refused unless you declare the procedure safe by exact name (optionally `schema.name`; case-insensitive like MySQL; no wildcards). The binding trusts the list: a listed procedure that commits makes the Preview's writes durable, and the backstop below then answers 500.
30
+
31
+ ```ruby
32
+ config.sendproof.use Sendproof::ActiveRecord::Provider.new(safe_procedures: %w[refresh_totals reports.rebuild_cache])
33
+ ```
34
+
35
+ - **Backstop (every database).** The Preview opens its transaction at once with `SAVEPOINT sendproof_preview` and, before rolling back, rolls back to it. On SQLite and PostgreSQL this catches a commit on `raw_connection` followed by a new transaction, which a plain rollback would otherwise have confirmed. Any commit, explicit or implicit, erases every savepoint (and with autocommit off MySQL then opens a new transaction by itself, so only a savepoint made at the start proves anything), so a Preview whose transaction was committed anyway, for example on `raw_connection`, answers 500 without confirmation. The writes before that commit are durable; the check only stops the Preview from claiming otherwise.
36
+ - **Deadlocks (MySQL and MariaDB).** A deadlock (1213), or a lock wait timeout (1205) with `innodb_rollback_on_timeout` on, rolls back the whole Preview transaction, and Rails runs MySQL with autocommit on outside `BEGIN`, so a retry would commit for real. The handler still gets the original error (`ActiveRecord::Deadlocked`), but every later statement in that Preview is refused before it is sent, and the Preview answers 500 without confirmation. The lock wait timeout case shares the deadlock code path and is covered by unit tests only, because `innodb_rollback_on_timeout` can be set only at server startup.
37
+ - On MySQL and MariaDB, one Preview runs at a time in each process: InnoDB deadlocks (1213) when three or more Previews insert the same new key and the first rolls back. Pass `serialize_previews: true` or `false` to override. See [data stores](../data-stores.md#mysql-previews-take-turns).
38
+ - Without prepared statements (MySQL), Active Record inlines parameter values into the SQL text, so a statement that names a secret, or any statement when parameter values are hidden, is logged with every literal replaced by `?`.
39
+ - `Provider.new(system: "mariadb")` names the SQL system for discovery; by default it comes from the adapter (`sqlite`, `postgresql`, `mysql`, `mssql`).
@@ -0,0 +1,66 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module ActiveRecord
5
+ # Keeps the binds an adapter without prepared statements inlines into the SQL text, so the SQL log
6
+ # can still report them by name and redact them.
7
+ #
8
+ # Trilogy (and any connection inside +unprepared_statement+) compiles a query with Arel's
9
+ # +SubstituteBinds+ collector, which quotes each bind into the text: the +sql.active_record+ event then
10
+ # carries no binds, and a secret-named bind such as +api_token+ would show its value in the text
11
+ # whenever the statement itself doesn't name a secret. This module records the binds the collector
12
+ # substitutes while a capture runs, and {SqlSubscriber} attaches them to the event for the same text.
13
+ module InlinedBinds
14
+ KEY = :sendproof_inlined_binds
15
+ COLLECTOR = :sendproof_substitute_collector
16
+
17
+ # Records what the collector substitutes.
18
+ module Recording
19
+ def add_bind(bind, &)
20
+ sendproof_binds << bind
21
+ super
22
+ end
23
+
24
+ def add_binds(binds, proc_for_binds = nil, &)
25
+ sendproof_binds.concat(binds)
26
+ super
27
+ end
28
+
29
+ def sendproof_binds = @sendproof_binds ||= []
30
+ end
31
+
32
+ # Returns the binds inlined into +sql+, the text of the statement about to be logged, once.
33
+ # @return [Array, nil]
34
+ def self.take(sql)
35
+ entry = Thread.current[KEY] or return nil
36
+ return nil unless sql.to_s.include?(entry.first)
37
+
38
+ Thread.current[KEY] = nil
39
+ entry.last
40
+ end
41
+
42
+ def to_sql_and_binds(arel_or_sql_string, binds = [], *rest)
43
+ return super if prepared_statements || Sendproof::Capture.current.nil?
44
+
45
+ Thread.current[COLLECTOR] = nil
46
+ result = super
47
+ collector = Thread.current[COLLECTOR]
48
+ Thread.current[KEY] = [result.first.to_s, collector.sendproof_binds.dup] if collector && !collector.sendproof_binds.empty?
49
+ result
50
+ ensure
51
+ Thread.current[COLLECTOR] = nil
52
+ end
53
+
54
+ private
55
+
56
+ def collector
57
+ super.tap do |collector|
58
+ if collector.is_a?(::Arel::Collectors::SubstituteBinds) && Sendproof::Capture.current
59
+ collector.extend(Recording)
60
+ Thread.current[COLLECTOR] = collector
61
+ end
62
+ end
63
+ end
64
+ end
65
+ end
66
+ end
@@ -0,0 +1,30 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module ActiveRecord
5
+ # Captures model changes of an ordinary send. It never touches the transaction.
6
+ class Observation < Sendproof::Provider::Observation
7
+ def initialize(tracker)
8
+ super()
9
+ @tracker = tracker
10
+ @tracker.activate
11
+ end
12
+
13
+ def changes = @tracker.changes
14
+ def changes_truncated? = @tracker.truncated?
15
+
16
+ def finalize_capture(recorder)
17
+ missed = @tracker.sql_writes - @tracker.tracked_writes
18
+ return unless missed.positive?
19
+
20
+ recorder.log(level: "Warning", category: "Sendproof",
21
+ message: "#{missed} write statement(s) bypassed model callbacks and are missing from the changes.")
22
+ end
23
+
24
+ def close
25
+ @tracker.freeze!
26
+ @tracker.deactivate
27
+ end
28
+ end
29
+ end
30
+ end
@@ -0,0 +1,91 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module ActiveRecord
5
+ # Preview provider for ActiveRecord.
6
+ #
7
+ # @example Default connection
8
+ # config.sendproof.use Sendproof::ActiveRecord::Provider.new
9
+ # @example Several databases; every one the handler writes to must be listed
10
+ # Sendproof::ActiveRecord::Provider.new(connection_classes: [ApplicationRecord, AnalyticsRecord])
11
+ class Provider < Sendproof::Provider
12
+ # Adapters whose Previews take turns: MySQL and MariaDB (see {Turns}).
13
+ SERIAL_ADAPTERS = %w[mysql2 trilogy mysql].freeze
14
+
15
+ # The SQL provider ids the workbench has a store mark for, by Active Record adapter name.
16
+ SYSTEMS = { "sqlite3" => "sqlite", "postgresql" => "postgresql", "postgis" => "postgresql", "mysql2" => "mysql",
17
+ "trilogy" => "mysql", "mysql" => "mysql", "sqlserver" => "mssql" }.freeze
18
+
19
+ # @param database [String, nil] display label; defaults to the first connection's database name
20
+ # @param connection_classes [Array<Class>] abstract record classes whose connections are enrolled
21
+ # @param system [String, nil] the SQL provider id for capabilities +database.system+ (+sqlite+,
22
+ # +postgresql+, +mysql+, +mariadb+, +mssql+); defaults to the first connection's adapter, so pass
23
+ # +"mariadb"+ yourself for a MariaDB server
24
+ # @param serialize_previews [Boolean, nil] whether Previews take turns; nil means "only on MySQL and MariaDB"
25
+ # @param safe_procedures [Array<String>] on MySQL and MariaDB a Preview refuses +CALL+, because a
26
+ # stored procedure can commit the Preview transaction; list the procedures that never commit, by
27
+ # exact name (optionally +schema.name+; case-insensitive, like MySQL), to allow calling them. The
28
+ # binding trusts the list: a listed procedure that does commit makes the Preview's writes durable,
29
+ # and the savepoint check before the rollback then answers 500.
30
+ # @raise [ArgumentError] when a safe procedure is not an exact name
31
+ def initialize(database: nil, connection_classes: [::ActiveRecord::Base], system: nil, serialize_previews: nil,
32
+ safe_procedures: [])
33
+ super()
34
+ @database = database
35
+ @connection_classes = connection_classes
36
+ @system = system
37
+ @serialize_previews = serialize_previews
38
+ @safe_procedures = Sendproof::TransactionControl.normalize_procedures(safe_procedures)
39
+ @turns = Turns.new
40
+ end
41
+
42
+ # @return [String, nil] the SQL provider id, so the workbench shows the right store mark
43
+ def database_system
44
+ return @system if @system
45
+
46
+ adapter = adapter_names.first
47
+ SYSTEMS[adapter] || adapter
48
+ end
49
+
50
+ # @return [String, nil] a label that never contains hosts or credentials
51
+ def database
52
+ return @database if @database
53
+
54
+ name = @connection_classes.first.connection_db_config.database.to_s
55
+ name.empty? ? nil : File.basename(name, ".*")
56
+ rescue StandardError
57
+ nil
58
+ end
59
+
60
+ def begin_preview(_context)
61
+ tracker = Tracker.new(safe_procedures: @safe_procedures)
62
+ # Wait for this provider's turn before leasing a connection (MySQL only; see {Turns}).
63
+ session = Session.new(tracker, release_turn: serialize? ? @turns.take : nil)
64
+ begin
65
+ @connection_classes.each { |klass| session.enroll(klass.lease_connection) }
66
+ tracker.activate
67
+ session
68
+ rescue StandardError
69
+ session.close
70
+ raise
71
+ end
72
+ end
73
+
74
+ def begin_observation(_context)
75
+ Observation.new(Tracker.new)
76
+ end
77
+
78
+ private
79
+
80
+ def serialize?
81
+ @serialize_previews.nil? ? adapter_names.any? { |adapter| SERIAL_ADAPTERS.include?(adapter) } : @serialize_previews
82
+ end
83
+
84
+ def adapter_names
85
+ @connection_classes.map { |klass| klass.connection_db_config.adapter.to_s }
86
+ rescue StandardError
87
+ []
88
+ end
89
+ end
90
+ end
91
+ end
@@ -0,0 +1,130 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module ActiveRecord
5
+ # One rollback-only preview: open non-joinable transactions on the handler's connections.
6
+ #
7
+ # Because the outer transaction is not joinable, the handler's own +transaction+ blocks become
8
+ # savepoints and can neither commit nor leak it. Records never reach +after_commit+.
9
+ class Session < Sendproof::Provider::PreviewSession
10
+ # @!attribute marked [Boolean] whether the transaction opened with {SAVEPOINT} (MySQL and MariaDB)
11
+ Enrollment = Struct.new(:connection, :transaction, :marked)
12
+
13
+ # The savepoint every Preview opens its transaction with, for the backstop in
14
+ # {#rollback!}. Rails names its own savepoints +active_record_<n>+, so it never makes this one, and
15
+ # the {TransactionGuard} refuses a handler's +RELEASE+ or +ROLLBACK TO+ of it like a +COMMIT+.
16
+ SAVEPOINT = "sendproof_preview"
17
+
18
+ # @param release_turn [#call, nil] hands the provider's MySQL turn back (see {Turns})
19
+ def initialize(tracker, release_turn: nil)
20
+ super()
21
+ @tracker = tracker
22
+ @release_turn = release_turn
23
+ @enrollments = []
24
+ @rolled_back = false
25
+ @closed = false
26
+ end
27
+
28
+ # Starts a transaction on +connection+ and opens it at once with {SAVEPOINT}, the backstop's mark
29
+ # (on every database: a commit the guard can't see erases it).
30
+ def enroll(connection)
31
+ return if @enrollments.any? { |enrollment| enrollment.connection.equal?(connection) }
32
+
33
+ enrollment = Enrollment.new(connection, connection.begin_transaction(joinable: false), false)
34
+ @enrollments << enrollment
35
+ connection.create_savepoint(SAVEPOINT) # materializes the BEGIN first
36
+ enrollment.marked = true
37
+ end
38
+
39
+ def changes = @tracker.changes
40
+ def changes_truncated? = @tracker.truncated?
41
+
42
+ # Rolls back every enrolled transaction, then verifies none was committed.
43
+ # @raise [RuntimeError] when a rollback is not confirmed
44
+ def rollback!
45
+ @tracker.freeze!
46
+ failures = []
47
+ @enrollments.reverse_each do |enrollment|
48
+ rollback_one(enrollment, failures)
49
+ rescue StandardError => error
50
+ failures << error
51
+ end
52
+ @rolled_back = failures.empty?
53
+ raise failures.first, cause: failures.first if failures.any?
54
+
55
+ # The transaction has ended with the rollback, so the next MySQL Preview may run. A failed
56
+ # rollback keeps the turn until +close+ has tried again.
57
+ hand_back_turn
58
+ end
59
+
60
+ # Warns when write statements bypassed the model callbacks and so are missing from the diff.
61
+ def finalize_capture(recorder)
62
+ missed = @tracker.sql_writes - @tracker.tracked_writes
63
+ return unless missed.positive?
64
+
65
+ recorder.log(level: "Warning", category: "Sendproof",
66
+ message: "#{missed} write statement(s) bypassed model callbacks (update_all, delete_all, " \
67
+ "insert_all, touch or raw SQL). They were rolled back but are missing from the changes.")
68
+ end
69
+
70
+ def close
71
+ return if @closed
72
+
73
+ @closed = true
74
+ begin
75
+ unless @rolled_back
76
+ # Every connection is retried: one that fails again never leaves the others in a transaction.
77
+ failures = []
78
+ @enrollments.reverse_each do |enrollment|
79
+ rollback_one(enrollment)
80
+ rescue StandardError => error
81
+ failures << error
82
+ end
83
+ raise failures.first if failures.any?
84
+ end
85
+ ensure
86
+ @tracker.deactivate
87
+ hand_back_turn
88
+ end
89
+ end
90
+
91
+ private
92
+
93
+ # The backstop, on every database: the savepoint the Preview transaction opened with must still
94
+ # exist. Any commit, explicit or implicit, erases every savepoint, and the driver (or MySQL with
95
+ # autocommit off) may then open a new transaction by itself, so a savepoint made now would prove nothing. Error 1305
96
+ # (SAVEPOINT does not exist), or a lost connection, means the rollback can't be confirmed; the
97
+ # rollback itself still runs.
98
+ def check_still_open(enrollment, failures)
99
+ return unless enrollment.marked
100
+
101
+ enrollment.connection.exec_rollback_to_savepoint(SAVEPOINT)
102
+ rescue StandardError => error
103
+ failures << RuntimeError.new("The Preview transaction was committed before its rollback (its savepoint is gone: " \
104
+ "#{error.class}), so the Preview can't be confirmed.")
105
+ end
106
+
107
+ def hand_back_turn
108
+ release = @release_turn
109
+ @release_turn = nil
110
+ release&.call
111
+ end
112
+
113
+ # @param failures [Array, nil] where the savepoint check reports; nil skips it (the retry in {#close})
114
+ def rollback_one(enrollment, failures = nil)
115
+ connection = enrollment.connection
116
+ transaction = enrollment.transaction
117
+ # A handler may leave nested transactions open after a crash; unwind them first, because rolling
118
+ # back to the start savepoint erases their savepoints.
119
+ while connection.open_transactions.positive? && !connection.current_transaction.equal?(transaction)
120
+ connection.rollback_transaction
121
+ end
122
+ check_still_open(enrollment, failures) if failures
123
+ connection.rollback_transaction(transaction) if connection.current_transaction.equal?(transaction)
124
+ return if transaction.state.rolledback?
125
+
126
+ raise "The #{transaction.state.class} transaction was not rolled back; the preview cannot be confirmed."
127
+ end
128
+ end
129
+ end
130
+ end
@@ -0,0 +1,76 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module ActiveRecord
5
+ # Turns +sql.active_record+ notifications into captured SQL log entries, redacting secrets.
6
+ module SqlSubscriber
7
+ WRITE = /\A\s*(?:INSERT|UPDATE|DELETE|REPLACE)\b/i
8
+ IGNORED_NAMES = %w[SCHEMA TRANSACTION].freeze
9
+
10
+ module_function
11
+
12
+ def subscribe
13
+ ActiveSupport::Notifications.subscribe("sql.active_record") { |event| handle(event) }
14
+ end
15
+
16
+ def handle(event)
17
+ recorder = Capture.current or return
18
+ payload = event.payload
19
+ return if payload[:cached] || IGNORED_NAMES.include?(payload[:name])
20
+
21
+ text = payload[:sql].to_s
22
+ Tracker.current&.sql_write! if text.match?(WRITE)
23
+ # An adapter without prepared statements quoted the binds into the text instead of sending them.
24
+ inlined = InlinedBinds.take(text) if Array(payload[:binds]).empty?
25
+ recorder.record_sql(duration_ms: event.duration, category: "ActiveRecord") do
26
+ snapshot(text, payload, recorder.include_sql_values?, inlined)
27
+ end
28
+ end
29
+
30
+ # @return [Array(Hash, Boolean)] the captured SQL and whether anything was truncated
31
+ # @param inlined [Array, nil] binds an adapter without prepared statements quoted into +text+
32
+ def snapshot(text, payload, show_values, inlined = nil)
33
+ binds = inlined || Array(payload[:binds])
34
+ # Placeholders carry no column information, so one secret-looking name hides every value, and a
35
+ # statement that names a secret is shown without its literals: a database without prepared
36
+ # statements (MySQL) inlines values into the text instead of binding them. A secret-named bind
37
+ # that was inlined is in the text too, so it hides the literals even when the text names no secret.
38
+ redact_all = !show_values || Redaction.looks_secret?(text) ||
39
+ (inlined && inlined.any? { |bind| bind.respond_to?(:name) && bind.name && Redaction.looks_secret?(bind.name.to_s) })
40
+ text = Redaction.mask_literals(text) if redact_all
41
+ clipped = Limits.clip(text)
42
+ values = if inlined
43
+ inlined.map { |bind| bind.respond_to?(:value_for_database) ? bind.value_for_database : bind }
44
+ else
45
+ payload[:type_casted_binds]
46
+ end
47
+ values = values.call if values.respond_to?(:call)
48
+ values = Array(values)
49
+ truncated = clipped.length != text.length || binds.length > Limits::PARAMETERS
50
+
51
+ parameters = binds.first(Limits::PARAMETERS).each_with_index.map do |bind, index|
52
+ name = bind.respond_to?(:name) && bind.name ? bind.name.to_s : "p#{index}"
53
+ redact = redact_all || Redaction.looks_secret?(name)
54
+ value = redact ? Redaction::REDACTED : parameter_value(values[index])
55
+ { name: Limits.clip(name, Limits::NAME), value: value, dbType: db_type(bind) }
56
+ end
57
+ [{ text: clipped, parameters: parameters }, truncated]
58
+ end
59
+
60
+ def parameter_value(value)
61
+ return nil if value.nil?
62
+ return Limits.clip(value.unpack1("H*"), Limits::TEXT) if value.is_a?(String) && value.encoding == Encoding::BINARY
63
+
64
+ text = value.respond_to?(:iso8601) ? value.iso8601(6) : value.to_s
65
+ Limits.clip(text)
66
+ rescue ArgumentError
67
+ Limits.clip(value.to_s)
68
+ end
69
+
70
+ def db_type(bind)
71
+ type = bind.respond_to?(:type) ? bind.type : nil
72
+ (type.respond_to?(:type) && type.type ? type.type : type.class.name.to_s.split("::").last).to_s.downcase
73
+ end
74
+ end
75
+ end
76
+ end
@@ -0,0 +1,91 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module ActiveRecord
5
+ # Collects model changes for one preview or observed send on the current thread.
6
+ class Tracker
7
+ KEY = :sendproof_active_record_tracker
8
+
9
+ # @return [Tracker, nil] the tracker active on this thread
10
+ def self.current = Thread.current[KEY]
11
+
12
+ attr_reader :sql_writes, :tracked_writes
13
+
14
+ # @return [Array<String>] the procedures the host declared never commit (see {Provider#initialize})
15
+ attr_reader :safe_procedures
16
+
17
+ def initialize(safe_procedures: [])
18
+ @safe_procedures = safe_procedures
19
+ @ended = {}.compare_by_identity
20
+ @mutex = Mutex.new
21
+ @changes = []
22
+ @frozen = false
23
+ @truncated = false
24
+ @sql_writes = 0
25
+ @tracked_writes = 0
26
+ @previous = nil
27
+ end
28
+
29
+ # Records that the server itself ended the Preview transaction on +connection+ (a MySQL deadlock).
30
+ def end_transaction(connection, reason)
31
+ @mutex.synchronize { @ended[connection] ||= reason }
32
+ end
33
+
34
+ # @return [String, nil] why the server ended the Preview transaction on +connection+, if it did
35
+ def ended(connection) = @mutex.synchronize { @ended[connection] }
36
+
37
+ # Makes this tracker current on the calling thread.
38
+ def activate
39
+ @previous = Thread.current[KEY]
40
+ Thread.current[KEY] = self
41
+ end
42
+
43
+ def deactivate
44
+ Thread.current[KEY] = @previous if Thread.current[KEY].equal?(self)
45
+ end
46
+
47
+ # Stops further changes from being recorded or removed (so the final rollback cannot erase the diff).
48
+ def freeze!
49
+ @mutex.synchronize { @frozen = true }
50
+ end
51
+
52
+ # @return [Array<Hash>] changes in the order they happened
53
+ def changes
54
+ @mutex.synchronize { @changes.map { |entry| entry[:change] } }
55
+ end
56
+
57
+ def truncated? = @mutex.synchronize { @truncated }
58
+
59
+ def truncate!
60
+ @mutex.synchronize { @truncated = true }
61
+ end
62
+
63
+ def sql_write!
64
+ @mutex.synchronize { @sql_writes += 1 }
65
+ end
66
+
67
+ # Records a change made by +record+.
68
+ def record(record, change)
69
+ @mutex.synchronize do
70
+ return if @frozen
71
+
72
+ @tracked_writes += 1
73
+ if @changes.length >= Limits::CHANGES
74
+ @truncated = true
75
+ else
76
+ @changes << { record: record, change: change }
77
+ end
78
+ end
79
+ end
80
+
81
+ # Forgets changes of +record+ after its transaction rolled back (a savepoint, or the request's own).
82
+ def rolled_back(record)
83
+ @mutex.synchronize do
84
+ return if @frozen
85
+
86
+ @changes.reject! { |entry| entry[:record].equal?(record) }
87
+ end
88
+ end
89
+ end
90
+ end
91
+ end
@@ -0,0 +1,100 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "base64"
4
+
5
+ module Sendproof
6
+ module ActiveRecord
7
+ # Model callbacks, mixed into +ActiveRecord::Base+, that feed the active {Tracker}.
8
+ # They do nothing when no preview or observed send is running.
9
+ module Tracking
10
+ extend ActiveSupport::Concern
11
+
12
+ included do
13
+ after_create { Tracking.created(self) }
14
+ after_update { Tracking.updated(self) }
15
+ after_destroy { Tracking.destroyed(self) }
16
+ after_rollback { Tracking.rolled_back(self) }
17
+ end
18
+
19
+ class << self
20
+ def created(record)
21
+ tracker = Tracker.current or return
22
+ tracker.record(record, change("insert", record, nil, row(record, tracker), tracker))
23
+ end
24
+
25
+ def updated(record)
26
+ tracker = Tracker.current or return
27
+ saved = record.saved_changes
28
+ return if saved.empty?
29
+
30
+ current = row(record, tracker)
31
+ before = current.merge(saved.to_h { |name, (old, _)| [name, value(old, tracker)] })
32
+ tracker.record(record, change("update", record, before, current, tracker))
33
+ end
34
+
35
+ def destroyed(record)
36
+ tracker = Tracker.current or return
37
+ tracker.record(record, change("delete", record, row(record, tracker), nil, tracker))
38
+ end
39
+
40
+ def rolled_back(record)
41
+ Tracker.current&.rolled_back(record)
42
+ end
43
+
44
+ private
45
+
46
+ def change(operation, record, before, after, tracker)
47
+ filter = filter_for(record.class)
48
+ { operation:, table: record.class.table_name, key: redact(key(record, tracker), filter),
49
+ before: redact(before, filter), after: redact(after, filter) }
50
+ end
51
+
52
+ # Masks columns that name a secret (+password_digest+, +api_key+, +reset_token+) and the
53
+ # model's +filter_attributes+ (Rails' +filter_parameters+), so snapshots never carry
54
+ # credentials even when SQL parameter values are hidden.
55
+ def redact(row, filter)
56
+ return nil if row.nil?
57
+
58
+ row = filter.filter(row) if filter
59
+ row.to_h { |name, value| [name, Redaction.looks_secret?(name) ? Redaction::REDACTED : value] }
60
+ end
61
+
62
+ def filter_for(model)
63
+ filters = model.respond_to?(:filter_attributes) ? Array(model.filter_attributes) : []
64
+ filters.empty? ? nil : ActiveSupport::ParameterFilter.new(filters, mask: Redaction::REDACTED)
65
+ end
66
+
67
+ def key(record, tracker)
68
+ primary_key = record.class.primary_key
69
+ return nil if primary_key.nil?
70
+
71
+ Array(primary_key).to_h { |name| [name, value(record[name], tracker)] }
72
+ end
73
+
74
+ def row(record, tracker)
75
+ attributes = record.attributes
76
+ tracker.truncate! if attributes.length > Limits::PARAMETERS
77
+ attributes.first(Limits::PARAMETERS).to_h { |name, item| [name, value(item, tracker)] }
78
+ end
79
+
80
+ # Reduces a column value to plain JSON data without raising.
81
+ def value(item, tracker)
82
+ case item
83
+ when nil, true, false, Integer then item
84
+ when Float then item.finite? ? item : item.to_s
85
+ when String
86
+ return Base64.strict_encode64(item[0, Limits::TEXT * 3 / 4]) if item.encoding == Encoding::BINARY
87
+
88
+ clipped = Limits.clip(item)
89
+ tracker.truncate! if clipped.length != item.length
90
+ clipped
91
+ when Symbol then item.to_s
92
+ else
93
+ json = item.as_json
94
+ json.is_a?(String) ? Limits.clip(json) : json
95
+ end
96
+ end
97
+ end
98
+ end
99
+ end
100
+ end
@@ -0,0 +1,90 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module ActiveRecord
5
+ # Refuses, before it reaches the database, any statement a handler runs during a Preview that
6
+ # would end or escape the Preview transaction: +COMMIT+, +END+, +ROLLBACK+ without +TO+,
7
+ # +BEGIN+, +SET autocommit+ and, on MySQL and MariaDB, the statements that commit implicitly (the
8
+ # shared +raw-commit+ rule, spec/data-stores.md). A refusal records a fault on the Preview, so it
9
+ # answers 500 without confirmation even if the handler rescues the error.
10
+ #
11
+ # It sits on the adapter's lowest statement path, +raw_execute+, which +execute+, +exec_query+,
12
+ # +select_all+ and every model query go through. Statements Rails itself issues to manage
13
+ # transactions carry the name +TRANSACTION+ and pass, so savepoints and the Preview's own rollback
14
+ # keep working. A statement sent on the driver's own handle (+raw_connection+) never reaches this
15
+ # path and is not covered.
16
+ module TransactionGuard
17
+ # The adapters that are MySQL or MariaDB, which also commit implicitly.
18
+ MYSQL_ADAPTERS = %w[mysql2 trilogy mysql].freeze
19
+
20
+ private
21
+
22
+ def raw_execute(sql, name = nil, *args, **options, &block)
23
+ refuse_transaction_control(sql, name)
24
+ begin
25
+ super
26
+ rescue StandardError => error
27
+ notice_server_rollback(error)
28
+ raise
29
+ end
30
+ end
31
+
32
+ # A MySQL deadlock (1213), or a lock wait timeout (1205) with +innodb_rollback_on_timeout+ on, rolls
33
+ # back the whole Preview transaction. Rails runs MySQL with autocommit on outside +BEGIN+, so every
34
+ # later statement would commit for real: remember it, and refuse them all (see
35
+ # {#refuse_transaction_control}). The handler still gets the original error.
36
+ def notice_server_rollback(error)
37
+ tracker = Tracker.current
38
+ return if tracker.nil? || Sendproof::Capture.preview.nil? || tracker.ended(self)
39
+ return unless MYSQL_ADAPTERS.include?(pool.db_config.adapter.to_s)
40
+
41
+ code = server_error_code(error)
42
+ reason = if code == 1213 || error.is_a?(::ActiveRecord::Deadlocked)
43
+ "a deadlock rolled back the Preview transaction"
44
+ elsif (code == 1205 || error.is_a?(::ActiveRecord::LockWaitTimeout)) && rollback_on_timeout?
45
+ "a lock wait timeout rolled back the Preview transaction"
46
+ end
47
+ return unless reason
48
+
49
+ tracker.end_transaction(self, reason)
50
+ Sendproof::Capture.preview&.refuse(Sendproof::PreviewTransactionControl.new("The Preview can't be confirmed: #{reason}."))
51
+ end
52
+
53
+ def server_error_code(error)
54
+ [error, error.cause].compact.each do |candidate|
55
+ %i[error_code error_number errno].each do |reader|
56
+ value = candidate.respond_to?(reader) ? candidate.public_send(reader) : nil
57
+ return value if value.is_a?(Integer)
58
+ end
59
+ end
60
+ nil
61
+ end
62
+
63
+ # Whether the server rolls back the whole transaction on a lock wait timeout; unknown counts as yes.
64
+ def rollback_on_timeout?
65
+ value = with_raw_connection { |connection| connection.query("SELECT @@innodb_rollback_on_timeout").to_a.dig(0, 0) }
66
+ value.to_i == 1
67
+ rescue StandardError
68
+ true
69
+ end
70
+
71
+ def refuse_transaction_control(sql, name)
72
+ tracker = Tracker.current
73
+ return if name == "TRANSACTION" || tracker.nil?
74
+
75
+ recorder = Sendproof::Capture.preview or return
76
+ if (ended = tracker.ended(self))
77
+ error = Sendproof::Stores::Guard.refuse_in_preview("Preview can't run this statement: #{ended}, so it would run outside the Preview transaction.")
78
+ raise error if error
79
+ end
80
+ mysql = MYSQL_ADAPTERS.include?(pool.db_config.adapter.to_s)
81
+ reason = Sendproof::TransactionControl.reason(sql, mysql: mysql, safe_procedures: tracker.safe_procedures,
82
+ reserved: Session::SAVEPOINT)
83
+ return unless reason
84
+
85
+ error = Sendproof::Stores::Guard.refuse_in_preview("Preview owns the database transaction, so #{reason}; it cannot run during Preview.")
86
+ raise error if error && recorder
87
+ end
88
+ end
89
+ end
90
+ end
@@ -0,0 +1,34 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendproof
4
+ module ActiveRecord
5
+ # Lets MySQL and MariaDB Previews run one at a time in each process.
6
+ #
7
+ # InnoDB checks a new key for duplicates under a shared lock. When three or more transactions
8
+ # insert the same key and the first one rolls back, as every Preview does, the waiters each hold
9
+ # that shared lock and each need the exclusive one, so InnoDB aborts all but one with a deadlock
10
+ # (error 1213). Sent for real, the first insert would commit and the others would get a
11
+ # duplicate-key error instead. No isolation level avoids it, so a Preview takes its provider's turn
12
+ # before it leases a connection and hands the turn back once its transaction has ended, as SQLite
13
+ # Previews already queue behind +BEGIN IMMEDIATE+. Previews sent to different processes still run
14
+ # at the same time. Sends and observed sends never wait.
15
+ class Turns
16
+ def initialize
17
+ @mutex = Mutex.new
18
+ end
19
+
20
+ # Waits for the turn and returns a callable that hands it back (idempotent).
21
+ # @return [#call]
22
+ def take
23
+ @mutex.lock
24
+ released = false
25
+ lambda do
26
+ next if released
27
+
28
+ released = true
29
+ @mutex.unlock
30
+ end
31
+ end
32
+ end
33
+ end
34
+ end
@@ -0,0 +1,40 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "active_record"
4
+ require "sendproof"
5
+
6
+ module Sendproof
7
+ # ActiveRecord persistence provider: real SQL transactions, rolled back after every preview.
8
+ #
9
+ # config.sendproof.use Sendproof::ActiveRecord::Provider.new
10
+ #
11
+ # Coverage is explicit. The transaction encloses every statement the handler runs on the
12
+ # enrolled connections, so the database is unchanged afterwards. The *diff* comes from model
13
+ # callbacks, so it lists what +save+, +update+ and +destroy+ did. Writes that skip callbacks
14
+ # (+update_all+, +delete_all+, +insert_all+, +touch+, raw SQL, triggers) are rolled back but
15
+ # never synthesized into before/after rows; the preview logs a warning when it sees them.
16
+ module ActiveRecord
17
+ autoload :InlinedBinds, "sendproof/active_record/inlined_binds"
18
+ autoload :Observation, "sendproof/active_record/observation"
19
+ autoload :Provider, "sendproof/active_record/provider"
20
+ autoload :Session, "sendproof/active_record/session"
21
+ autoload :SqlSubscriber, "sendproof/active_record/sql_subscriber"
22
+ autoload :Tracker, "sendproof/active_record/tracker"
23
+ autoload :Tracking, "sendproof/active_record/tracking"
24
+ autoload :TransactionGuard, "sendproof/active_record/transaction_guard"
25
+ autoload :Turns, "sendproof/active_record/turns"
26
+
27
+ # Hooks the model callbacks and the SQL subscriber into ActiveRecord. Idempotent.
28
+ def self.install!
29
+ return if @installed
30
+
31
+ @installed = true
32
+ ::ActiveRecord::Base.include(Tracking)
33
+ ::ActiveRecord::ConnectionAdapters::AbstractAdapter.prepend(TransactionGuard)
34
+ ::ActiveRecord::ConnectionAdapters::AbstractAdapter.prepend(InlinedBinds)
35
+ SqlSubscriber.subscribe
36
+ end
37
+ end
38
+ end
39
+
40
+ Sendproof::ActiveRecord.install!
@@ -0,0 +1,3 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "sendproof/active_record"
metadata ADDED
@@ -0,0 +1,93 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: sendproof-activerecord
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0.alpha.1
5
+ platform: ruby
6
+ authors:
7
+ - Sendproof contributors
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 2026-11-22 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: sendproof-core
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - '='
17
+ - !ruby/object:Gem::Version
18
+ version: 0.1.0.alpha.1
19
+ type: :runtime
20
+ prerelease: false
21
+ version_requirements: !ruby/object:Gem::Requirement
22
+ requirements:
23
+ - - '='
24
+ - !ruby/object:Gem::Version
25
+ version: 0.1.0.alpha.1
26
+ - !ruby/object:Gem::Dependency
27
+ name: activerecord
28
+ requirement: !ruby/object:Gem::Requirement
29
+ requirements:
30
+ - - ">="
31
+ - !ruby/object:Gem::Version
32
+ version: '8.0'
33
+ - - "<"
34
+ - !ruby/object:Gem::Version
35
+ version: '9'
36
+ type: :runtime
37
+ prerelease: false
38
+ version_requirements: !ruby/object:Gem::Requirement
39
+ requirements:
40
+ - - ">="
41
+ - !ruby/object:Gem::Version
42
+ version: '8.0'
43
+ - - "<"
44
+ - !ruby/object:Gem::Version
45
+ version: '9'
46
+ description: Opens a non-joinable transaction on the handler's connection, captures
47
+ model changes and SQL, and rolls everything back before the preview envelope is
48
+ returned.
49
+ executables: []
50
+ extensions: []
51
+ extra_rdoc_files: []
52
+ files:
53
+ - LICENSE
54
+ - README.md
55
+ - lib/sendproof-activerecord.rb
56
+ - lib/sendproof/active_record.rb
57
+ - lib/sendproof/active_record/inlined_binds.rb
58
+ - lib/sendproof/active_record/observation.rb
59
+ - lib/sendproof/active_record/provider.rb
60
+ - lib/sendproof/active_record/session.rb
61
+ - lib/sendproof/active_record/sql_subscriber.rb
62
+ - lib/sendproof/active_record/tracker.rb
63
+ - lib/sendproof/active_record/tracking.rb
64
+ - lib/sendproof/active_record/transaction_guard.rb
65
+ - lib/sendproof/active_record/turns.rb
66
+ homepage: https://github.com/mprync/sendproof
67
+ licenses:
68
+ - MIT
69
+ metadata:
70
+ source_code_uri: https://github.com/mprync/sendproof
71
+ bug_tracker_uri: https://github.com/mprync/sendproof/issues
72
+ changelog_uri: https://github.com/mprync/sendproof/releases
73
+ documentation_uri: https://github.com/mprync/sendproof/tree/main/adapters/ruby#readme
74
+ rubygems_mfa_required: 'true'
75
+ rdoc_options: []
76
+ require_paths:
77
+ - lib
78
+ required_ruby_version: !ruby/object:Gem::Requirement
79
+ requirements:
80
+ - - ">="
81
+ - !ruby/object:Gem::Version
82
+ version: '3.3'
83
+ required_rubygems_version: !ruby/object:Gem::Requirement
84
+ requirements:
85
+ - - ">="
86
+ - !ruby/object:Gem::Version
87
+ version: '0'
88
+ requirements: []
89
+ rubygems_version: 3.6.9
90
+ specification_version: 4
91
+ summary: 'ActiveRecord preview provider for Sendproof: real SQL transactions, rolled
92
+ back.'
93
+ test_files: []