athar 0.1.0

data/lib/athar/deletion.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "actor_lookup"
+
+module Athar
+  class Deletion < ActiveRecord::Base
+    include ActorLookup
+
+    self.table_name = Athar::DELETIONS_TABLE_NAME
+
+    class << self
+      def recent
+        order(deleted_at: :desc, id: :desc)
+      end
+
+      def for_record(record_or_class, id = nil)
+        # Filter by (schema_name, table_name, record_id):
+        #   - `record_type` is unreliable because STI subclass rows are stored
+        #     under the concrete class name (`"Admin"`) while
+        #     `Admin.base_class.name` is `"User"`.
+        #   - Active Record returns `"reporting.reporting_buckets"` for models
+        #     in non-public schemas, but Athar stores schema and table in
+        #     separate columns. Splitting on `.` mirrors what the generator
+        #     does at trigger-install time.
+        if id.nil? && record_or_class.is_a?(ActiveRecord::Base)
+          schema, table = split_schema_qualified(record_or_class.class.table_name)
+          where(schema_name: schema, table_name: table, record_id: record_or_class.id)
+        else
+          raise ArgumentError, "id is required when passing a record class or type" if id.nil?
+
+          klass = record_or_class.is_a?(Class) ? record_or_class : record_or_class.to_s.constantize
+          schema, table = split_schema_qualified(klass.table_name)
+          where(schema_name: schema, table_name: table, record_id: id)
+        end
+      end
+
+      def for_record_type(type)
+        where(record_type: type.to_s)
+      end
+
+      def for_table(table_name)
+        where(table_name: table_name.to_s)
+      end
+
+      def before(time)
+        where(arel_table[:deleted_at].lt(time))
+      end
+
+      def after(time)
+        where(arel_table[:deleted_at].gt(time))
+      end
+
+      private
+
+      def split_schema_qualified(qualified)
+        full = qualified.to_s
+        full.include?(".") ? full.split(".", 2) : ["public", full]
+      end
+    end
+  end
+end

data/lib/athar/engine.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Athar
+  class Engine < ::Rails::Engine
+    isolate_namespace Athar
+
+    initializer "athar.set_logger" do
+      Athar.configuration.logger ||= Rails.logger
+    end
+  end
+end

data/lib/athar/metadata_stack.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "active_support/isolated_execution_state"
+
+module Athar
+  # Fiber-aware metadata stack used by Athar::Context to merge nested
+  # `with_metadata` blocks. Storage is delegated to ActiveSupport's
+  # IsolatedExecutionState so the stack tracks the request/job execution
+  # boundary correctly under fiber-based runtimes (Solid Queue, Falcon, etc.).
+  class MetadataStack
+    STATE_KEY = :athar_metadata_stack
+
+    class << self
+      def push(meta)
+        stack << meta
+        current
+      end
+
+      def pop
+        stack.pop
+        current
+      end
+
+      def current
+        stack.reduce({}) { |acc, meta| acc.merge(meta) }
+      end
+
+      def clear!
+        ActiveSupport::IsolatedExecutionState[STATE_KEY] = []
+      end
+
+      def stack
+        ActiveSupport::IsolatedExecutionState[STATE_KEY] ||= []
+      end
+    end
+  end
+end

data/lib/athar/retention.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Athar
+  module Retention
+    Result = Struct.new(:deleted_by_age, :deleted_by_count, :table_events_deleted, :batches, keyword_init: true) do
+      def total_deleted
+        deleted_by_age + deleted_by_count + table_events_deleted
+      end
+    end
+
+    class << self
+      def prune!(max_age: nil, max_count: nil, batch_size: nil, max_batches: nil, prune_table_events: nil) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+        config = Athar.configuration.retention
+        max_age ||= config.max_age
+        max_count ||= config.max_count
+        batch_size ||= config.batch_size
+        max_batches ||= config.max_batches_per_run
+        prune_table_events = config.prune_table_events if prune_table_events.nil?
+
+        result = Result.new(deleted_by_age: 0, deleted_by_count: 0, table_events_deleted: 0, batches: 0)
+
+        if max_age
+          cutoff = Time.current - max_age
+          result.deleted_by_age, age_batches = prune_by_age(
+            :athar_deletions,
+            "deleted_at",
+            cutoff,
+            batch_size,
+            max_batches
+          )
+          result.batches += age_batches
+
+          if prune_table_events
+            result.table_events_deleted, table_event_batches = prune_by_age(
+              :athar_table_events,
+              "occurred_at",
+              cutoff,
+              batch_size,
+              [max_batches - result.batches, 0].max
+            )
+            result.batches += table_event_batches
+          end
+        end
+
+        if max_count && result.batches < max_batches
+          result.deleted_by_count, count_batches = prune_by_count(
+            :athar_deletions,
+            max_count,
+            batch_size,
+            max_batches - result.batches
+          )
+          result.batches += count_batches
+        end
+
+        result
+      end
+
+      private
+
+      def prune_by_age(table, time_column, cutoff, batch_size, max_batches) # rubocop:disable Metrics/MethodLength
+        return [0, 0] if max_batches <= 0
+
+        connection = ActiveRecord::Base.connection
+        total = 0
+        batches = 0
+        loop do
+          break if batches >= max_batches
+
+          deleted = connection.delete(
+            <<~SQL
+              DELETE FROM #{table}
+              WHERE id IN (
+                SELECT id FROM #{table}
+                WHERE #{time_column} < #{connection.quote(cutoff)}
+                ORDER BY #{time_column} ASC
+                LIMIT #{batch_size.to_i}
+              )
+            SQL
+          )
+          batches += 1
+          total += deleted
+          break if deleted < batch_size.to_i
+        end
+
+        [total, batches]
+      end
+
+      def prune_by_count(table, max_count, batch_size, max_batches) # rubocop:disable Metrics/MethodLength
+        return [0, 0] if max_batches <= 0
+
+        connection = ActiveRecord::Base.connection
+        boundary = connection.select_one(
+          <<~SQL
+            SELECT deleted_at, id
+            FROM #{table}
+            ORDER BY deleted_at DESC, id DESC
+            OFFSET #{max_count.to_i}
+            LIMIT 1
+          SQL
+        )
+        return [0, 0] unless boundary
+
+        boundary_deleted_at = connection.quote(boundary.fetch("deleted_at"))
+        boundary_id = connection.quote(boundary.fetch("id"))
+
+        total = 0
+        batches = 0
+        loop do
+          break if batches >= max_batches
+
+          deleted = connection.delete(
+            <<~SQL
+              DELETE FROM #{table}
+              WHERE id IN (
+                SELECT id FROM #{table}
+                WHERE (deleted_at, id) <= (#{boundary_deleted_at}, #{boundary_id})
+                ORDER BY deleted_at ASC, id ASC
+                LIMIT #{batch_size.to_i}
+              )
+            SQL
+          )
+          batches += 1
+          total += deleted
+          break if deleted < batch_size.to_i
+        end
+
+        [total, batches]
+      end
+    end
+  end
+end

data/lib/athar/retention_job.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Athar
+  class RetentionJob < ActiveJob::Base
+    queue_as { Athar.configuration.retention.queue_name || :default }
+
+    def perform(max_age: nil, max_count: nil, batch_size: nil, max_batches: nil)
+      Athar::Retention.prune!(max_age:, max_count:, batch_size:, max_batches:)
+    end
+  end
+end

data/lib/athar/sql.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Athar
+  module SQL
+    GENERATORS_ROOT = File.expand_path("../generators/athar", __dir__)
+
+    INSTALL_FUNCTIONS_DIR = File.join(GENERATORS_ROOT, "install", "functions")
+    MODEL_TRIGGERS_DIR = File.join(GENERATORS_ROOT, "model", "triggers")
+
+    STATIC_FUNCTIONS = %w[
+      athar_filter_keys
+      athar_capture_delete
+    ].freeze
+
+    TEMPLATE_FUNCTIONS = %w[
+      athar_capture_truncate
+    ].freeze
+
+    INSTALLED_FUNCTIONS = (STATIC_FUNCTIONS + TEMPLATE_FUNCTIONS).freeze
+
+    class << self
+      def read_function(name, locals = {})
+        if STATIC_FUNCTIONS.include?(name)
+          File.read(File.join(INSTALL_FUNCTIONS_DIR, "#{name}.sql"))
+        elsif TEMPLATE_FUNCTIONS.include?(name)
+          path = File.join(INSTALL_FUNCTIONS_DIR, "#{name}.sql.erb")
+          render(File.read(path), locals)
+        else
+          raise ArgumentError, "unknown SQL function: #{name.inspect}"
+        end
+      end
+
+      def all_functions(locals = {})
+        INSTALLED_FUNCTIONS.to_h { |name| [name, read_function(name, locals)] }
+      end
+
+      def function_signature(name)
+        case name
+        when "athar_filter_keys" then "jsonb, text[]"
+        when "athar_capture_delete", "athar_capture_truncate" then ""
+        else
+          raise ArgumentError, "unknown SQL function: #{name.inspect}"
+        end
+      end
+
+      def render(template, locals)
+        Render.new(locals).result(template)
+      end
+    end
+
+    class Render
+      def initialize(locals)
+        @locals = locals
+      end
+
+      def result(template)
+        binding_context = binding
+        @locals.each do |key, value|
+          binding_context.local_variable_set(key, value)
+        end
+        ERB.new(template, trim_mode: "-").result(binding_context)
+      end
+    end
+  end
+end

data/lib/athar/table_event.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "actor_lookup"
+
+module Athar
+  class TableEvent < ActiveRecord::Base
+    include ActorLookup
+
+    EVENT_TYPE_TRUNCATE = "truncate"
+
+    self.table_name = Athar::TABLE_EVENTS_TABLE_NAME
+
+    class << self
+      def recent
+        order(occurred_at: :desc, id: :desc)
+      end
+
+      def for_table(table_name)
+        where(table_name: table_name.to_s)
+      end
+
+      def truncate
+        where(event_type: EVENT_TYPE_TRUNCATE)
+      end
+    end
+  end
+end

data/lib/athar/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Athar
+  VERSION = "0.1.0"
+end

data/lib/athar.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/numeric/time"
+require "active_support/core_ext/string/inflections"
+require "active_support/json"
+require "active_record"
+require "active_job"
+require "fx"
+
+require_relative "athar/version"
+require_relative "athar/configuration"
+require_relative "athar/sql"
+require_relative "athar/metadata_stack"
+require_relative "athar/context"
+require_relative "athar/deletion"
+require_relative "athar/table_event"
+require_relative "athar/retention"
+
+module Athar
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def logger
+      configuration.logger || (Rails.logger if defined?(Rails)) || Logger.new($stdout)
+    end
+
+    def with_actor(...)
+      Context.with_actor(...)
+    end
+
+    def with_metadata(...)
+      Context.with_metadata(...)
+    end
+
+    def with_context(...)
+      Context.with_context(...)
+    end
+
+    def without_capture(...)
+      Context.without_capture(...)
+    end
+  end
+end
+
+require_relative "athar/retention_job" if defined?(ActiveJob)
+require_relative "athar/engine" if defined?(Rails::Engine)

data/lib/generators/athar/fx_helper.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "fx"
+
+module Athar
+  module Generators
+    module FxHelper
+      def self.included(base)
+        base.class_option :fx,
+                          type: :boolean,
+                          optional: true,
+                          desc: "Use the fx gem to manage SQL functions and triggers (default when fx is loaded)."
+      end
+
+      def fx?
+        return true if options[:fx] == true
+        return false if options[:fx] == false
+
+        defined?(::Fx::SchemaDumper) ? true : false
+      end
+
+      def schema_format
+        return :ruby unless Rails.application
+
+        Rails.application.config.active_record.schema_format || :ruby
+      end
+
+      def ensure_raw_sql_supported!
+        return if schema_format == :sql
+
+        raise ::Thor::Error,
+              "Athar requires the fx gem (default) or `config.active_record.schema_format = :sql` " \
+              "when using --no-fx. Either install fx or switch the host app to SQL schema dumps."
+      end
+
+      # Indent each non-blank line of `text` by `spaces` spaces.
+      def indent_sql(text, spaces)
+        prefix = " " * spaces
+        text.each_line.map { |line| line.strip.empty? ? line : prefix + line }.join
+      end
+
+      # Resolve the app-wide Rails generator primary/foreign-key types.
+      def athar_primary_key_type
+        primary_key_setting || :primary_key
+      end
+
+      def athar_foreign_key_type
+        primary_key_setting || :bigint
+      end
+
+      def primary_key_setting
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:configuration)
+
+        generators_config = ::Rails.configuration.generators
+        orm = generators_config.orm
+        generators_config.options[orm][:primary_key_type]
+      end
+    end
+  end
+end

data/lib/generators/athar/install/functions/athar_capture_delete.sql

@@ -0,0 +1,111 @@
+-- Athar capture delete trigger function (v1).
+-- Args:
+--   TG_ARGV[0] record_type        (e.g. 'User') or 'null'
+--   TG_ARGV[1] schema_name        (e.g. 'public')
+--   TG_ARGV[2] table_name         (e.g. 'users')
+--   TG_ARGV[3] primary_key        (e.g. 'id')
+--   TG_ARGV[4] id_type            ('bigint' | 'integer' | 'uuid')
+--   TG_ARGV[5] record_type_column ('type' | 'null')
+--   TG_ARGV[6] capture_mode       ('identity' | 'only' | 'snapshot')
+--   TG_ARGV[7] columns            ('{email,name}' or 'null')
+
+CREATE OR REPLACE FUNCTION athar_capture_delete()
+RETURNS trigger AS $$
+DECLARE
+  arg_record_type text;
+  arg_schema_name text;
+  arg_table_name text;
+  arg_primary_key text;
+  arg_id_type text;
+  arg_record_type_column text;
+  arg_capture_mode text;
+  arg_columns text[];
+
+  full_row jsonb;
+  filtered_data jsonb;
+  meta jsonb;
+  meta_text text;
+  computed_record_type text;
+  computed_record_id text;
+  computed_actor_type text;
+  computed_actor_id text;
+BEGIN
+  arg_record_type := NULLIF(TG_ARGV[0], 'null');
+  arg_schema_name := NULLIF(TG_ARGV[1], 'null');
+  arg_table_name := NULLIF(TG_ARGV[2], 'null');
+  arg_primary_key := NULLIF(TG_ARGV[3], 'null');
+  arg_id_type := NULLIF(TG_ARGV[4], 'null');
+  arg_record_type_column := NULLIF(TG_ARGV[5], 'null');
+  arg_capture_mode := NULLIF(TG_ARGV[6], 'null');
+  arg_columns := NULLIF(TG_ARGV[7], 'null')::text[];
+
+  full_row := to_jsonb(OLD);
+
+  computed_record_type := arg_record_type;
+  IF arg_record_type_column IS NOT NULL AND full_row ? arg_record_type_column THEN
+    IF (full_row ->> arg_record_type_column) IS NOT NULL THEN
+      computed_record_type := full_row ->> arg_record_type_column;
+    END IF;
+  END IF;
+
+  IF arg_capture_mode = 'identity' THEN
+    filtered_data := '{}'::jsonb;
+  ELSIF arg_capture_mode = 'snapshot' THEN
+    filtered_data := full_row;
+  ELSIF arg_capture_mode = 'only' THEN
+    filtered_data := athar_filter_keys(full_row, arg_columns);
+  ELSE
+    RAISE EXCEPTION 'Unsupported Athar capture mode: %', arg_capture_mode;
+  END IF;
+
+  meta := '{}'::jsonb;
+  meta_text := current_setting('athar.meta', true);
+  IF coalesce(meta_text, '') <> '' THEN
+    meta := meta_text::jsonb;
+  END IF;
+
+  computed_record_id := full_row ->> arg_primary_key;
+  computed_actor_type := meta ->> 'actor_type';
+  computed_actor_id := meta ->> 'actor_id';
+
+  EXECUTE format(
+    'INSERT INTO athar_deletions (
+      record_type,
+      record_id,
+      actor_type,
+      actor_id,
+      schema_name,
+      table_name,
+      deleted_at,
+      record_data,
+      metadata,
+      created_at
+    )
+    VALUES (
+      $1,
+      ($2)::%s,
+      $3,
+      CASE WHEN $4 IS NULL THEN NULL ELSE ($4)::%s END,
+      $5,
+      $6,
+      statement_timestamp(),
+      $7,
+      $8,
+      statement_timestamp()
+    )',
+    arg_id_type,
+    arg_id_type
+  )
+  USING
+    computed_record_type,
+    computed_record_id,
+    computed_actor_type,
+    computed_actor_id,
+    arg_schema_name,
+    arg_table_name,
+    filtered_data,
+    meta - 'actor_type' - 'actor_id';
+
+  RETURN OLD;
+END;
+$$ LANGUAGE plpgsql;

data/lib/generators/athar/install/functions/athar_capture_truncate.sql.erb

@@ -0,0 +1,51 @@
+-- Athar capture truncate trigger function (v1).
+-- Statement-level AFTER TRUNCATE trigger.
+-- Args:
+--   TG_ARGV[0] schema_name (e.g. 'public')
+--   TG_ARGV[1] table_name  (e.g. 'users')
+
+CREATE OR REPLACE FUNCTION athar_capture_truncate()
+RETURNS trigger AS $$
+DECLARE
+  arg_schema_name text;
+  arg_table_name text;
+
+  meta jsonb;
+  meta_text text;
+  actor_id_text text;
+BEGIN
+  arg_schema_name := NULLIF(TG_ARGV[0], 'null');
+  arg_table_name := NULLIF(TG_ARGV[1], 'null');
+
+  meta := '{}'::jsonb;
+  meta_text := current_setting('athar.meta', true);
+  IF coalesce(meta_text, '') <> '' THEN
+    meta := meta_text::jsonb;
+  END IF;
+
+  actor_id_text := meta ->> 'actor_id';
+
+  INSERT INTO athar_table_events (
+    event_type,
+    schema_name,
+    table_name,
+    actor_type,
+    actor_id,
+    metadata,
+    occurred_at,
+    created_at
+  )
+  VALUES (
+    'truncate',
+    arg_schema_name,
+    arg_table_name,
+    meta ->> 'actor_type',
+    CASE WHEN actor_id_text IS NULL THEN NULL ELSE actor_id_text::<%= foreign_key_type %> END,
+    meta - 'actor_type' - 'actor_id',
+    statement_timestamp(),
+    statement_timestamp()
+  );
+
+  RETURN NULL;
+END;
+$$ LANGUAGE plpgsql;

data/lib/generators/athar/install/functions/athar_filter_keys.sql

@@ -0,0 +1,29 @@
+-- Athar filter keys function (v1).
+-- Keeps only the listed keys from a JSONB object.
+-- Missing keys are ignored. Empty column list returns {}.
+
+CREATE OR REPLACE FUNCTION athar_filter_keys(
+  data jsonb,
+  columns text[]
+) RETURNS jsonb AS $$
+DECLARE
+  result jsonb := '{}'::jsonb;
+  column_name text;
+BEGIN
+  IF data IS NULL THEN
+    RETURN '{}'::jsonb;
+  END IF;
+
+  IF columns IS NULL OR array_length(columns, 1) IS NULL THEN
+    RETURN '{}'::jsonb;
+  END IF;
+
+  FOREACH column_name IN ARRAY columns LOOP
+    IF data ? column_name THEN
+      result := result || jsonb_build_object(column_name, data -> column_name);
+    END IF;
+  END LOOP;
+
+  RETURN result;
+END;
+$$ LANGUAGE plpgsql IMMUTABLE;