waldit 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8367ecd692940c28ead4bc255173137f7d9f34b9db3df262c15081ab64334ce0
-  data.tar.gz: 84a7c6eeee1b62ff8a3f507e5ae6128759292a80d6e5bd1f1a936ca33c431326
+  metadata.gz: 81634f3ce5d00503e50882a14495a960dfc8fb1072b53c92e3cd2a08441666c9
+  data.tar.gz: b235c7ee87fda30c747db3a678a3b9f6c7b5f5b95861f998b037a63418bee29b
 SHA512:
-  metadata.gz: 161fafcaba15339898929328f103ff1b659aa17aa89179e7e9124ecb7f7b0487da39d55402711f02f724326203a28c2f7e322ba97a28b3672007663114ac33fd
-  data.tar.gz: cd4cc774d28e9f14732bc807478716c190fa52f6b2f4ec243512655db7fbd3d5aae6c712e7a9a301192702ea5b5a3753e315921ca62c64ea8c7c0119ffa27950
+  metadata.gz: ad16ce87f467600879c9358540143cb1ad4eeeb1fe278472647aad21e28db4420a5238b13e6d70c02a65014d72251d54acfdfb0fe6c448191644871a28d4ef45
+  data.tar.gz: e932e94f85304d7b8f756a5fce3a3ba0e2c07ca302766e0f8ff3563b4acac9e14b7943ae0bcc3030ee68567571315e635fa172c02c945e70d68e45c46fba4d41

data/README.md

@@ -1 +1,117 @@
 # Waldit
+
+[![Gem Version](https://badge.fury.io/rb/waldit.svg)](https://badge.fury.io/rb/waldit)
+
+Waldit is a Ruby gem that provides a simple and extensible way to audit changes to your ActiveRecord models. It leverages PostgreSQL's logical replication capabilities to capture changes directly from your database with 100% consistency.
+
+## Features
+
+- **Automatic Auditing:** Automatically track `create`, `update`, and `delete` operations on your models.
+- **Contextual Auditing:** Add custom context to your audit records to understand who made the change and why.
+- **Flexible Configuration:** Configure which tables and columns to watch, and how to store audit information.
+- **High Performance:** Built on top of [`wal`](https://github.com/reu/wal), which uses PostgreSQL's logical replication for minimal overhead.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "waldit"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install waldit
+
+## Usage
+
+1.  **Configure your database adapter:**
+
+    First step is to configure in your `config/database.yml` and change your adapter to `postgresqlwaldit`, which is a special adapter that allows injecting `waldit` contextual information on your transactions:
+
+    ```yaml
+    default: &default
+      adapter: postgresqlwaldit
+      # ...
+    ```
+
+2.  **Create an audit table:**
+
+    Generate a migration to create the `waldit` table:
+
+    ```bash
+    rails generate migration create_waldit
+    ```
+
+    And then add the following to your migration file:
+
+    ```ruby
+    class CreateWalditTable < ActiveRecord::Migration[7.0]
+      def change
+        create_table :waldit do |t|
+          t.bigint :transaction_id, null: false
+          t.bigint :lsn, null: false
+          t.string :action, null: false
+          t.jsonb :context, default: {}
+          t.string :table_name, null: false
+          t.string :primary_key, null: false
+          t.jsonb :old, default: {}
+          t.jsonb :new, default: {}
+          t.timestamp :commited_at
+
+          t.index [:table_name, :primary_key, :transaction_id], unique: true
+        end
+      end
+    end
+    ```
+
+3.  **Configure Waldit:**
+
+    Create an initializer file at `config/initializers/waldit.rb`:
+
+    ```ruby
+    Waldit.configure do |config|
+      # A callback that returns true if a table should be watched.
+      config.watched_tables = ->(table) { table != "waldit" }
+
+      # A callback that returns an array of columns to ignore for a given table.
+      config.ignored_columns = ->(table) { %w[created_at updated_at] }
+    end
+    ```
+
+4.  **Add context to your changes:**
+
+    Use the `with_context` method to add context to your database operations:
+
+    ```ruby
+    Waldit.with_context(user_id: 1, reason: "User updated their profile") do
+      user.update(name: "New Name")
+    end
+    ```
+
+5.  **Start the watcher:**
+
+    To process the events, you need to start a WAL watcher. The recommended way is to have a config/waldit.yml
+
+    ```yml
+    slots:
+      audit:
+        publications: [waldit_publication]
+        watcher: Waldit::Watcher
+    ```
+
+    And then run:
+
+    ```bash
+    bundle exec wal start config/waldit.yml
+    ```
+
+## How it Works
+
+Waldit uses a custom PostgreSQL adapter to set the `waldit_context` session variable before each transaction. This context is then captured by the logical replication slot and stored in the `waldit` table by the `Waldit::Watcher`.
+
+The `Waldit::Watcher` is a streaming watcher that listens for changes in the logical replication slot and creates audit records in the `waldit` table. It processes events in batches to minimize the number of database transactions.

data/Rakefile

@@ -3,10 +3,3 @@
 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

@@ -1,17 +1,7 @@
 # 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] ||= []
@@ -21,12 +11,10 @@ module Waldit
       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)
@@ -35,7 +23,6 @@ module Waldit
       end
     end
 
-    sig { params(context: Context).void }
     def new_context(context = {})
       Thread.current[:waldit_context] ||= []
       Thread.current[:waldit_context].push(context.as_json)

data/lib/waldit/postgresql_adapter.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# typed: ignore
 
 require "active_record/connection_adapters/postgresql_adapter"
 
@@ -27,6 +26,46 @@ module Waldit
       end
     end
 
+    def exec_no_cache(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 exec_cache(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

data/lib/waldit/railtie.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# typed: false
 
 require "rails/railtie"
 

data/lib/waldit/record.rb

@@ -1,19 +1,7 @@
 # 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

data/lib/waldit/sidekiq.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# typed: false
 
 module Waldit
   module Sidekiq

data/lib/waldit/version.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
-# typed: true
 
 module Waldit
-  VERSION = "0.0.2"
+  VERSION = "0.0.4"
 end

data/lib/waldit/watcher.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
-# typed: true
 
 require "wal"
 
 module Waldit
   class Watcher < Wal::StreamingWatcher
-    extend T::Sig
+    include Wal
 
-    sig { params(event: T.any(InsertEvent, UpdateEvent, DeleteEvent)).void }
     def audit_event(event)
       return unless event.primary_key
 
@@ -60,7 +58,7 @@ module Waldit
         else
           # Finally the most common case: just deleting a record not created or updated on this transaction
           record.upsert(
-            audit.merge(action: "delete", old:),
+            audit.merge(action: "delete", old: event.old),
             unique_by:,
             on_duplicate: :update,
           )
@@ -68,7 +66,6 @@ module Waldit
       end
     end
 
-    sig { override.params(events: T::Enumerator[Event]).void }
     def on_transaction_events(events)
       counter = 0
       catch :finish do
@@ -96,27 +93,22 @@ module Waldit
       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

data/lib/waldit.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# typed: true
 
 require_relative "waldit/version"
 require_relative "waldit/context"
@@ -8,19 +7,11 @@ 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
@@ -30,17 +21,12 @@ module Waldit
       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
+    attr_accessor :context_prefix
   end
 
-  sig { params(block: T.proc.params(config: T.class_of(Waldit)).void).void }
   def self.configure(&block)
     yield self
   end

data/rbi/waldit.rbi

@@ -2,7 +2,7 @@
 module Waldit
   extend T::Sig
   extend Waldit::Context
-  VERSION = "0.0.2"
+  VERSION = "0.0.4"
 
   class << self
     sig { returns(String) }

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: waldit
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Rodrigo Navarro
 bindir: exe
 cert_chain: []
-date: 2025-07-02 00:00:00.000000000 Z
+date: 2025-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: wal
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.0.2
+        version: 0.0.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.0.2
+        version: 0.0.3
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -37,62 +37,6 @@ dependencies:
     - - ">="
       - !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'
 - !ruby/object:Gem::Dependency
   name: sidekiq
   requirement: !ruby/object:Gem::Requirement