waldit 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afad3b16943e3984c6584b02ef8edb2fb8abb8413687726a657110018e9fcbd4
-  data.tar.gz: 934aacd6442c00b7fd40287360e2d8a1b52e0f37328711e029d36812d9cf94d1
+  metadata.gz: fb7ae260f6d1af42f4e6169084c7ba79de48cea93f44ff47be032f5764df23a6
+  data.tar.gz: 7cf9d0c022ffbb457bcac4380ed635cd65d2df1db24faae5fbd169b50b5aa07c
 SHA512:
-  metadata.gz: ff61b8c0d473390f5197ae4544ad932014483ba68cdb8972e79eee35d4747814c5e64ae60cc53a078653de82f483ae94e98db69b40796a8be0d38b1a9db694d1
-  data.tar.gz: a9e6c961b67f1be3335d773af2c42d76b7f74fd5d0eb48bd3cb5dce4cf355ce88144caa626ede05de357af47ce03986893bd0b9accab687bf4490c077fc8c787
+  metadata.gz: b54045c2265401d420a276efddb20525b7b72e39d27c25e10da6a7a2c357805ea1956aed900d3c265f5cc88096dc402cd53ea52d0989eff8e3dd965d47c2ec75
+  data.tar.gz: 8d86ba10a3c94e7ca87bb90a39957663b305f19b6b5a8bfb7062fdae89879b57c82d230989bfd49b5480738f63ca81bf9db7b1093406b730578498bfc001a862

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/lib/waldit/postgresql_adapter.rb

@@ -27,6 +27,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/sidekiq.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+# typed: false
+
+module Waldit
+  module Sidekiq
+    class SaveContext
+      include ::Sidekiq::ClientMiddleware
+
+      def call(job_class, job, queue, redis)
+        if (context = Waldit.context)
+          job["waldit_context"] = context.to_json
+        end
+        yield
+      end
+    end
+
+    class LoadContext
+      include ::Sidekiq::ServerMiddleware
+
+      def call(job_instance, job, queue, &block)
+        context = deserialize_context(job) || {}
+        Waldit.with_context(context.merge(background_job: job_instance.class.to_s), &block)
+      end
+
+      private
+
+      def deserialize_context(job)
+        if (serialized_context = job["waldit_context"]) && serialized_context.is_a?(String)
+          context = JSON.parse(serialized_context)
+          context if context.is_a? Hash
+        end
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/waldit/version.rb

@@ -2,5 +2,5 @@
 # typed: true
 
 module Waldit
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 end

data/lib/waldit/watcher.rb

@@ -60,7 +60,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,
           )

data/rbi/waldit.rbi

@@ -2,7 +2,7 @@
 module Waldit
   extend T::Sig
   extend Waldit::Context
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 
   class << self
     sig { returns(String) }
@@ -63,6 +63,39 @@ module Waldit
     def diff; end
   end
 
+  module Sidekiq
+    class SaveContext
+      include ::Sidekiq::ClientMiddleware
+
+      sig do
+        params(
+          job_class: T.untyped,
+          job: T.untyped,
+          queue: T.untyped,
+          redis: T.untyped
+        ).returns(T.untyped)
+      end
+      def call(job_class, job, queue, redis); end
+    end
+
+    class LoadContext
+      include ::Sidekiq::ServerMiddleware
+
+      sig do
+        params(
+          job_instance: T.untyped,
+          job: T.untyped,
+          queue: T.untyped,
+          block: T.untyped
+        ).returns(T.untyped)
+      end
+      def call(job_instance, job, queue, &block); end
+
+      sig { params(job: T.untyped).returns(T.untyped) }
+      def deserialize_context(job); end
+    end
+  end
+
   class Watcher < Wal::StreamingWatcher
     extend T::Sig
 

data/sig/waldit.rbs

@@ -39,6 +39,23 @@ module Waldit::Record
   def diff: () -> ::Hash[String | Symbol, [ untyped, untyped ]]
 end
 
+module Waldit::Sidekiq
+end
+
+class Waldit::Waldit::Sidekiq::SaveContext
+  include ::Sidekiq::ClientMiddleware
+
+  def call: (untyped job_class, untyped job, untyped queue, untyped redis) -> untyped
+end
+
+class Waldit::Waldit::Sidekiq::LoadContext
+  include ::Sidekiq::ServerMiddleware
+
+  def call: (untyped job_instance, untyped job, untyped queue) { () -> untyped } -> untyped
+
+  def deserialize_context: (untyped job) -> untyped
+end
+
 class Waldit::Watcher < Wal::StreamingWatcher
   def audit_event: (InsertEvent | UpdateEvent | DeleteEvent event) -> void
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: waldit
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Rodrigo Navarro
 bindir: exe
 cert_chain: []
-date: 2025-06-29 00:00:00.000000000 Z
+date: 2025-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: wal
@@ -93,6 +93,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: sidekiq
+  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
@@ -109,6 +123,7 @@ files:
 - lib/waldit/postgresql_adapter.rb
 - lib/waldit/railtie.rb
 - lib/waldit/record.rb
+- lib/waldit/sidekiq.rb
 - lib/waldit/version.rb
 - lib/waldit/watcher.rb
 - rbi/waldit.rbi