waldit 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: afad3b16943e3984c6584b02ef8edb2fb8abb8413687726a657110018e9fcbd4
+  data.tar.gz: 934aacd6442c00b7fd40287360e2d8a1b52e0f37328711e029d36812d9cf94d1
+SHA512:
+  metadata.gz: ff61b8c0d473390f5197ae4544ad932014483ba68cdb8972e79eee35d4747814c5e64ae60cc53a078653de82f483ae94e98db69b40796a8be0d38b1a9db694d1
+  data.tar.gz: a9e6c961b67f1be3335d773af2c42d76b7f74fd5d0eb48bd3cb5dce4cf355ce88144caa626ede05de357af47ce03986893bd0b9accab687bf4490c077fc8c787

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Rodrigo Navarro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1 @@
+# Waldit

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+task(:test) { sh "bundle exec rspec" }
+
+task default: %i[build]
+
+task("sig/waldit.rbi") { sh "bundle exec parlour" }
+task("rbi/waldit.rbs" => "sig/waldit.rbi") { sh "rbs prototype rbi rbi/waldit.rbi > sig/waldit.rbs" }
+
+Rake::Task["build"].enhance(["sig/waldit.rbi", "rbi/waldit.rbs"])

data/lib/waldit/context.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# typed: true
+
+module Waldit
+  module Context
+    extend T::Sig
+
+    Context = T.type_alias { T::Hash[T.any(String, Symbol), T.untyped] }
+
+    sig do
+      type_parameters(:U)
+        .params(context: Context, block: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def with_context(context, &block)
+      current_context = self.context || {}
+      Thread.current[:waldit_context] ||= []
+      Thread.current[:waldit_context].push(current_context.merge(context.as_json))
+      block.call
+    ensure
+      Thread.current[:waldit_context].pop
+    end
+
+    sig { returns(T.nilable(Context)) }
+    def context
+      Thread.current[:waldit_context]&.last
+    end
+
+    sig { params(added_context: Context).void }
+    def add_context(added_context)
+      if (context = self.context)
+        context.merge!(added_context.as_json)
+      else
+        new_context(added_context)
+      end
+    end
+
+    sig { params(context: Context).void }
+    def new_context(context = {})
+      Thread.current[:waldit_context] ||= []
+      Thread.current[:waldit_context].push(context.as_json)
+    end
+  end
+end

data/lib/waldit/postgresql_adapter.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+# typed: ignore
+
+require "active_record/connection_adapters/postgresql_adapter"
+
+module Waldit
+  class PostgreSQLAdapter < ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+    READ_QUERY_REGEXP = build_read_query_regexp(%i[close declare fetch move set show])
+
+    def raw_execute(sql, ...)
+      return super if READ_QUERY_REGEXP.match? sql
+      return super if @current_waldit_context == Waldit.context.hash
+
+      if transaction_open?
+        set_waldit_context!
+        super
+
+      elsif Waldit.context
+        # We are trying to execute a query with waldit context while not in a transaction, so we start one
+        transaction do
+          set_waldit_context!
+          super
+        end
+
+      else
+        super
+      end
+    end
+
+    def begin_db_transaction(...)
+      @current_waldit_context = nil.hash
+      super
+    end
+
+    def begin_isolated_db_transaction(...)
+      @current_waldit_context = nil.hash
+      super
+    end
+
+    def commit_db_transaction
+      @current_waldit_context = nil.hash
+      super
+    end
+
+    private
+
+    def set_waldit_context!
+      context = Waldit.context
+      prefix = Waldit.context_prefix
+      context_hash = context.hash
+      set_wal_watcher_context(context, prefix:) if context_hash != @current_waldit_context
+      @current_waldit_context = context_hash
+    end
+  end
+end

data/lib/waldit/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+# typed: false
+
+require "rails/railtie"
+
+module Waldit
+  class Railtie < Rails::Railtie
+    config.before_configuration do
+      ActiveRecord::ConnectionAdapters.register(
+        "postgresqlwaldit",
+        "Waldit::PostgreSQLAdapter",
+        "waldit/postgresql_adapter",
+      )
+    end
+  end
+end

data/lib/waldit/record.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# typed: true
+
+module Waldit
+  module Record
+    extend T::Sig
+    extend T::Helpers
+    abstract!
+
+    sig { abstract.returns(T::Hash[T.any(String, Symbol), T.untyped]) }
+    def new; end
+
+    sig { abstract.returns(T::Hash[T.any(String, Symbol), T.untyped]) }
+    def old; end
+
+    sig { returns(T::Hash[T.any(String, Symbol), [T.untyped, T.untyped]]) }
+    def diff
+      (old.keys | new.keys).reduce({}.with_indifferent_access) do |diff, key|
+        old[key] != new[key] ? diff.merge(key => [old[key], new[key]]) : diff
+      end
+    end
+  end
+end

data/lib/waldit/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# typed: true
+
+module Waldit
+  VERSION = "0.0.1"
+end

data/lib/waldit/watcher.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+# typed: true
+
+require "wal"
+
+module Waldit
+  class Watcher < Wal::StreamingWatcher
+    extend T::Sig
+
+    sig { params(event: T.any(InsertEvent, UpdateEvent, DeleteEvent)).void }
+    def audit_event(event)
+      return unless event.primary_key
+
+      audit = {
+        transaction_id: event.transaction_id,
+        lsn: event.lsn,
+        context: event.context,
+        table_name: event.table,
+        primary_key: event.primary_key,
+      }
+
+      unique_by = %i[table_name primary_key transaction_id]
+
+      case event
+      when InsertEvent
+        record.upsert(
+          audit.merge(action: "insert", new: event.new),
+          unique_by:,
+          on_duplicate: :update,
+        )
+
+      when UpdateEvent
+        return if event.diff.without(ignored_columns(event.table)).empty?
+        record.upsert(
+          audit.merge(action: "update", old: event.old, new: event.new),
+          unique_by:,
+          on_duplicate: :update,
+          update_only: %w[new],
+        )
+
+      when DeleteEvent
+        case record.where(audit.slice(*unique_by)).pluck(:action, :old).first
+        in ["insert", _]
+          # We are deleting a record that was inserted on this transaction, which means we don't need to audit anything,
+          # as the record was never commited
+          record.where(audit.slice(*unique_by)).delete_all
+
+        in ["update", old]
+          # We are deleting a record we updated on this transaction. Here we are making sure we keep the correct previous
+          # state, and not the state at the moment of the deletion
+          record.upsert(
+            audit.merge(action: "delete", old:, new: {}),
+            unique_by:,
+            on_duplicate: :update,
+          )
+
+        in ["delete", _]
+          # This should never happend, we wouldn't be able to delete a record that was already deleted on this transaction
+
+        else
+          # Finally the most common case: just deleting a record not created or updated on this transaction
+          record.upsert(
+            audit.merge(action: "delete", old:),
+            unique_by:,
+            on_duplicate: :update,
+          )
+        end
+      end
+    end
+
+    sig { override.params(events: T::Enumerator[Event]).void }
+    def on_transaction_events(events)
+      counter = 0
+      catch :finish do
+        loop do
+          record.transaction do
+            events.each do |event|
+              case event
+              when CommitTransactionEvent
+                record
+                  .where(transaction_id: event.transaction_id)
+                  .update_all(commited_at: event.timestamp) if counter > 0
+                # Using throw to break the outside loop and finish the thread gracefully
+                throw :finish
+
+              when InsertEvent, UpdateEvent, DeleteEvent
+                audit_event(event)
+
+                counter += 1
+                # We break here to force a commit, so we don't keep a single big transaction pending
+                break if counter % max_transaction_size == 0
+              end
+            end
+          end
+        end
+      end
+    end
+
+    sig { params(table: String).returns(T::Boolean) }
+    def should_watch_table?(table)
+      Waldit.watched_tables.call(table)
+    end
+
+    sig { params(prefix: String).returns(T::Boolean) }
+    def valid_context_prefix?(prefix)
+      prefix == Waldit.context_prefix
+    end
+
+    sig { params(table: String).returns(T::Array[String]) }
+    def ignored_columns(table)
+      Waldit.ignored_columns.call(table)
+    end
+
+    sig { returns(Integer) }
+    def max_transaction_size
+      Waldit.max_transaction_size
+    end
+
+    sig { returns(T.class_of(ActiveRecord::Base)) }
+    def record
+      Waldit.model
+    end
+  end
+end

data/lib/waldit.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative "waldit/version"
+require_relative "waldit/context"
+require_relative "waldit/railtie"
+require_relative "waldit/record"
+require_relative "waldit/watcher"
+
+module Waldit
+  extend T::Sig
+  extend Waldit::Context
+
+  class << self
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_accessor :context_prefix
+
+    sig { returns(T.proc.params(table: String).returns(T::Boolean)) }
+    attr_reader :watched_tables
+
+    sig { params(tables: T.any(T::Array[String], T.proc.params(table: String).returns(T::Boolean))).void }
+    def watched_tables=(tables)
+      case tables
+      when Array
+        @watched_tables = -> table { tables.include? table }
+      else
+        @watched_tables = tables
+      end
+    end
+
+    sig { returns(T.proc.params(table: String).returns(T::Array[String])) }
+    attr_accessor :ignored_columns
+
+    sig { returns(Integer) }
+    attr_accessor :max_transaction_size
+
+    sig { returns(T.class_of(ActiveRecord::Base)) }
+    attr_accessor :model
+  end
+
+  sig { params(block: T.proc.params(config: T.class_of(Waldit)).void).void }
+  def self.configure(&block)
+    yield self
+  end
+
+  configure do |config|
+    config.context_prefix = "waldit_context"
+
+    config.watched_tables = -> table { table != "waldit" }
+
+    config.ignored_columns = -> table { %w[created_at updated_at] }
+
+    config.max_transaction_size = 10_000
+
+    config.model = Class.new(ActiveRecord::Base) do
+      include Waldit::Record
+      self.table_name = "waldit"
+    end
+  end
+end

data/rbi/waldit.rbi

@@ -0,0 +1,90 @@
+# typed: strong
+module Waldit
+  extend T::Sig
+  extend Waldit::Context
+  VERSION = "0.0.1"
+
+  class << self
+    sig { returns(String) }
+    attr_accessor :context_prefix
+
+    sig { returns(T.proc.params(table: String).returns(T::Boolean)) }
+    attr_reader :watched_tables
+
+    sig { returns(T.proc.params(table: String).returns(T::Array[String])) }
+    attr_accessor :ignored_columns
+
+    sig { returns(Integer) }
+    attr_accessor :max_transaction_size
+
+    sig { returns(T.class_of(ActiveRecord::Base)) }
+    attr_accessor :model
+  end
+
+  sig { params(tables: T.any(T::Array[String], T.proc.params(table: String).returns(T::Boolean))).void }
+  def self.watched_tables=(tables); end
+
+  sig { params(block: T.proc.params(config: T.class_of(Waldit)).void).void }
+  def self.configure(&block); end
+
+  module Context
+    extend T::Sig
+    Context = T.type_alias { T::Hash[T.any(String, Symbol), T.untyped] }
+
+    sig { type_parameters(:U).params(context: Context, block: T.proc.returns(T.type_parameter(:U))).returns(T.type_parameter(:U)) }
+    def with_context(context, &block); end
+
+    sig { returns(T.nilable(Context)) }
+    def context; end
+
+    sig { params(added_context: Context).void }
+    def add_context(added_context); end
+
+    sig { params(context: Context).void }
+    def new_context(context = {}); end
+  end
+
+  class Railtie < Rails::Railtie
+  end
+
+  module Record
+    abstract!
+
+    extend T::Sig
+    extend T::Helpers
+
+    sig { abstract.returns(T::Hash[T.any(String, Symbol), T.untyped]) }
+    def new; end
+
+    sig { abstract.returns(T::Hash[T.any(String, Symbol), T.untyped]) }
+    def old; end
+
+    sig { returns(T::Hash[T.any(String, Symbol), [T.untyped, T.untyped]]) }
+    def diff; end
+  end
+
+  class Watcher < Wal::StreamingWatcher
+    extend T::Sig
+
+    sig { params(event: T.any(InsertEvent, UpdateEvent, DeleteEvent)).void }
+    def audit_event(event); end
+
+    sig { override.params(events: T::Enumerator[Event]).void }
+    def on_transaction_events(events); end
+
+    sig { params(table: String).returns(T::Boolean) }
+    def should_watch_table?(table); end
+
+    sig { params(prefix: String).returns(T::Boolean) }
+    def valid_context_prefix?(prefix); end
+
+    sig { params(table: String).returns(T::Array[String]) }
+    def ignored_columns(table); end
+
+    sig { returns(Integer) }
+    def max_transaction_size; end
+
+    sig { returns(T.class_of(ActiveRecord::Base)) }
+    def record; end
+  end
+end

data/sig/waldit.rbs

@@ -0,0 +1,56 @@
+# typed: strong
+module Waldit
+  extend Waldit::Context
+
+  def self.watched_tables=: () -> String
+                          | () -> ^(String table) -> bool
+                          | () -> ^(String table) -> ::Array[String]
+                          | () -> Integer
+                          | () -> singleton(ActiveRecord::Base)
+                          | (::Array[String] | ^(String table) -> bool tables) -> void
+
+  def self.configure: () { (singleton(Waldit) config) -> void } -> void
+end
+
+Waldit::VERSION: untyped
+
+module Waldit::Context
+  def with_context: [U] (Context context) { () -> U } -> U
+
+  def context: () -> Context?
+
+  def add_context: (Context added_context) -> void
+
+  def new_context: (?Context context) -> void
+end
+
+Waldit::Waldit::Context::Context: untyped
+
+class Waldit::Railtie < Rails::Railtie
+end
+
+module Waldit::Record
+  extend T::Helpers
+
+  def new: () -> ::Hash[String | Symbol, untyped]
+
+  def old: () -> ::Hash[String | Symbol, untyped]
+
+  def diff: () -> ::Hash[String | Symbol, [ untyped, untyped ]]
+end
+
+class Waldit::Watcher < Wal::StreamingWatcher
+  def audit_event: (InsertEvent | UpdateEvent | DeleteEvent event) -> void
+
+  def on_transaction_events: (::Enumerator[Event] events) -> void
+
+  def should_watch_table?: (String table) -> bool
+
+  def valid_context_prefix?: (String prefix) -> bool
+
+  def ignored_columns: (String table) -> ::Array[String]
+
+  def max_transaction_size: () -> Integer
+
+  def record: () -> singleton(ActiveRecord::Base)
+end

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: waldit
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Rodrigo Navarro
+bindir: exe
+cert_chain: []
+date: 2025-06-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: wal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tapioca
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: parlour
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Postgres based audit trail for your Active Records, with 100% consistency.
+email:
+- rnavarro@rnavarro.com.br
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/waldit.rb
+- lib/waldit/context.rb
+- lib/waldit/postgresql_adapter.rb
+- lib/waldit/railtie.rb
+- lib/waldit/record.rb
+- lib/waldit/version.rb
+- lib/waldit/watcher.rb
+- rbi/waldit.rbi
+- sig/waldit.rbs
+homepage: https://github.com/reu/waldit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/reu/waldit
+  source_code_uri: https://github.com/reu/waldit
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Postgres based audit trail for Rails.
+test_files: []