vert-core 1.0.0

data/lib/vert/generators/install_generator.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/base"
+
+module Vert
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs Vert and generates configuration files"
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/vert.rb"
+      end
+
+      def create_current_model
+        template "current.rb.tt", "app/models/current.rb"
+      end
+
+      def create_application_record
+        template "application_record.rb.tt", "app/models/application_record.rb"
+      end
+
+      def create_outbox_event_model
+        template "outbox_event.rb.tt", "app/models/outbox_event.rb"
+      end
+
+      def create_outbox_migration
+        migration_template "create_outbox_events.rb.tt",
+                           "db/migrate/#{timestamp}_create_outbox_events.rb"
+      end
+
+      def create_health_controller
+        template "health_controller.rb.tt", "app/controllers/health_controller.rb"
+      end
+
+      def add_routes
+        route 'get "/health", to: "health#show"'
+        route 'get "/health/live", to: "health#live"'
+        route 'get "/health/ready", to: "health#ready"'
+      end
+
+      def show_instructions
+        say "\n"
+        say "Vert installed successfully!", :green
+        say "\n"
+        say "Next steps:", :yellow
+        say "1. Edit config/initializers/vert.rb to enable the features you need"
+        say "2. Run migrations: rails db:migrate"
+        say "3. Include Vert concerns in your models as needed:"
+        say "   include Vert::Concerns::UuidPrimaryKey"
+        say "   include Vert::Concerns::MultiTenant"
+        say "   include Vert::Concerns::Auditable"
+        say "   include Vert::Concerns::SoftDeletable"
+        say "\n"
+      end
+
+      private
+
+      def timestamp
+        Time.current.strftime("%Y%m%d%H%M%S")
+      end
+    end
+  end
+end

data/lib/vert/generators/rls_migration_generator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/base"
+
+module Vert
+  module Generators
+    class RlsMigrationGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates PostgreSQL Row Level Security setup migration"
+
+      class_option :tables, type: :array, default: [],
+                            desc: "Tables to enable RLS on"
+
+      def create_rls_functions_migration
+        migration_template "create_rls_functions.rb.tt",
+                           "db/migrate/#{timestamp}_create_rls_functions.rb"
+      end
+
+      def create_enable_rls_migration
+        return if options[:tables].empty?
+
+        migration_template "enable_rls_on_tables.rb.tt",
+                           "db/migrate/#{next_timestamp}_enable_rls_on_tables.rb"
+      end
+
+      def show_instructions
+        say "\n"
+        say "RLS migrations generated!", :green
+        say "\n"
+        say "Next steps:", :yellow
+        say "1. Run migrations: rails db:migrate"
+        say "2. Set enable_rls = true in config/initializers/vert.rb"
+        say "3. Ensure your database user has appropriate privileges"
+        say "\n"
+        say "To enable RLS on additional tables, run:", :cyan
+        say "  rails generate vert:rls_migration --tables orders invoices"
+        say "\n"
+      end
+
+      private
+
+      def timestamp
+        @timestamp ||= Time.current.strftime("%Y%m%d%H%M%S")
+      end
+
+      def next_timestamp
+        @next_timestamp ||= (Time.current + 1.second).strftime("%Y%m%d%H%M%S")
+      end
+
+      def tables_list
+        options[:tables]
+      end
+    end
+  end
+end

data/lib/vert/generators/templates/application_record.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+
+  # Optional: include Vert::Concerns::UuidPrimaryKey for UUID v7 primary keys
+  # include Vert::Concerns::UuidPrimaryKey
+end

data/lib/vert/generators/templates/create_outbox_events.rb.tt

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class CreateOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    create_table :outbox_events, id: :uuid do |t|
+      t.uuid :tenant_id, null: false
+      t.string :event_type, null: false
+      t.string :aggregate_type, null: false
+      t.uuid :aggregate_id, null: false
+      t.jsonb :payload, null: false, default: {}
+      t.string :status, null: false, default: "pending"
+      t.integer :retry_count, null: false, default: 0
+      t.text :last_error
+      t.datetime :published_at
+      t.datetime :failed_at
+
+      t.timestamps
+    end
+
+    add_index :outbox_events, :tenant_id
+    add_index :outbox_events, [:status, :created_at]
+    add_index :outbox_events, [:aggregate_type, :aggregate_id]
+  end
+end

data/lib/vert/generators/templates/create_rls_functions.rb.tt

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class CreateRlsFunctions < ActiveRecord::Migration[7.1]
+  def up
+    execute <<~SQL
+      CREATE OR REPLACE FUNCTION current_tenant_id() RETURNS uuid AS $$
+        SELECT NULLIF(current_setting('app.current_tenant_id', true), '')::uuid;
+      $$ LANGUAGE SQL STABLE;
+
+      CREATE OR REPLACE FUNCTION current_company_id() RETURNS uuid AS $$
+        SELECT NULLIF(current_setting('app.current_company_id', true), '')::uuid;
+      $$ LANGUAGE SQL STABLE;
+
+      CREATE OR REPLACE FUNCTION current_user_id() RETURNS uuid AS $$
+        SELECT NULLIF(current_setting('app.current_user_id', true), '')::uuid;
+      $$ LANGUAGE SQL STABLE;
+    SQL
+  end
+
+  def down
+    execute <<~SQL
+      DROP FUNCTION IF EXISTS current_tenant_id();
+      DROP FUNCTION IF EXISTS current_company_id();
+      DROP FUNCTION IF EXISTS current_user_id();
+    SQL
+  end
+end

data/lib/vert/generators/templates/current.rb.tt

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Current - Thread-safe request context
+#
+# Provides access to current tenant, user, and company context.
+#
+class Current < Vert::Current
+  # Add any application-specific attributes here
+  # attribute :custom_attribute
+end

data/lib/vert/generators/templates/enable_rls_on_tables.rb.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class EnableRlsOnTables < ActiveRecord::Migration[7.1]
+  TABLES = <%= tables_list.inspect %>.freeze
+
+  def up
+    TABLES.each do |table_name|
+      enable_rls_on_table(table_name)
+    end
+  end
+
+  def down
+    TABLES.each do |table_name|
+      disable_rls_on_table(table_name)
+    end
+  end
+
+  private
+
+  def enable_rls_on_table(table_name)
+    execute <<~SQL
+      ALTER TABLE #{table_name} ENABLE ROW LEVEL SECURITY;
+      ALTER TABLE #{table_name} FORCE ROW LEVEL SECURITY;
+
+      DROP POLICY IF EXISTS tenant_isolation_#{table_name} ON #{table_name};
+      CREATE POLICY tenant_isolation_#{table_name} ON #{table_name}
+        FOR ALL
+        USING (tenant_id = current_tenant_id())
+        WITH CHECK (tenant_id = current_tenant_id());
+    SQL
+  end
+
+  def disable_rls_on_table(table_name)
+    execute <<~SQL
+      DROP POLICY IF EXISTS tenant_isolation_#{table_name} ON #{table_name};
+      ALTER TABLE #{table_name} DISABLE ROW LEVEL SECURITY;
+    SQL
+  end
+end

data/lib/vert/generators/templates/health_controller.rb.tt

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class HealthController < ActionController::API
+  include Vert::Health::ControllerMixin
+end

data/lib/vert/generators/templates/initializer.rb.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Vert - Configuration
+#
+# Enable only the features you need. All flags default to false except enable_health.
+#
+Vert.configure do |config|
+  # --- Row Level Security (PostgreSQL) ---
+  # config.enable_rls = ENV.fetch("ENABLE_RLS", "false") == "true"
+  # config.rls_user = ENV.fetch("RLS_USER", "app_user")
+
+  # --- Outbox (reliable event publishing to RabbitMQ) ---
+  # config.enable_outbox = true
+  # config.rabbitmq_url = ENV.fetch("RABBITMQ_URL", "amqp://guest:guest@localhost:5672/")
+  # config.exchange_name = ENV.fetch("RABBITMQ_EXCHANGE", "vert.events")
+
+  # --- Health checks ---
+  # config.enable_health = true
+  # config.health_check_path = "/health"
+  # config.auto_mount_health_routes = false
+  # config.health_check_database = true
+  # config.health_check_redis = false
+  # config.health_check_rabbitmq = false
+  # config.health_check_sidekiq = false
+
+  # --- Authorization (RBAC/ABAC with Pundit) ---
+  # config.enable_authorization = false
+
+  # --- Model concerns (enable if your app uses these patterns) ---
+  # config.enable_multi_tenant = false
+  # config.enable_auditable = false
+  # config.enable_soft_deletable = false
+  # config.enable_uuid_primary_key = false
+  # config.enable_company_scoped = false
+  # config.enable_document_storeable = false
+
+  # --- Document service (for has_document) ---
+  # config.document_service_url = ENV.fetch("DOCUMENT_SERVICE_URL", "http://localhost:3020")
+end

data/lib/vert/generators/templates/outbox_event.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# OutboxEvent - Transactional outbox for reliable event publishing
+#
+# Events are stored in the database and published asynchronously
+# to RabbitMQ. Enable enable_outbox in config/initializers/vert.rb
+# and run the OutboxPublisherJob (e.g. via Sidekiq-Cron) to publish.
+#
+class OutboxEvent < ApplicationRecord
+  include Vert::Outbox::Event
+end

data/lib/vert/health/checker.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Vert
+  module Health
+    class Checker
+      attr_reader :checks
+
+      def initialize
+        @checks = {}
+        setup_default_checks
+      end
+
+      def add_check(name, &block)
+        @checks[name] = block
+      end
+
+      alias register add_check
+
+      def remove_check(name)
+        @checks.delete(name)
+      end
+
+      def check_all
+        results = {}
+        overall_healthy = true
+
+        @checks.each do |name, check|
+          result = check.call
+          results[name] = result
+          overall_healthy = false unless result[:status] == "ok"
+        rescue StandardError => e
+          results[name] = { status: "error", message: e.message }
+          overall_healthy = false
+        end
+
+        {
+          status: overall_healthy ? "healthy" : "unhealthy",
+          timestamp: Time.current.iso8601,
+          checks: results
+        }
+      end
+
+      def liveness
+        { status: "ok", timestamp: Time.current.iso8601 }
+      end
+
+      def readiness
+        db_ok = check_database[:status] == "ok"
+        {
+          status: db_ok ? "ready" : "not_ready",
+          timestamp: Time.current.iso8601,
+          checks: { database: check_database }
+        }
+      end
+
+      def check_database
+        ActiveRecord::Base.connection.execute("SELECT 1")
+        { status: "ok" }
+      rescue StandardError => e
+        { status: "error", message: e.message }
+      end
+
+      def check_redis
+        return { status: "skipped", message: "Redis check disabled" } unless Vert.config.health_check_redis
+        return { status: "skipped", message: "Redis not configured" } unless redis_available?
+
+        Redis.current.ping == "PONG" ? { status: "ok" } : { status: "error", message: "Ping failed" }
+      rescue StandardError => e
+        { status: "error", message: e.message }
+      end
+
+      def check_rabbitmq
+        return { status: "skipped", message: "RabbitMQ check disabled" } unless Vert.config.health_check_rabbitmq
+
+        connection = Bunny.new(Vert.config.rabbitmq_url, connection_timeout: 5)
+        connection.start
+        connection.close
+        { status: "ok" }
+      rescue StandardError => e
+        { status: "error", message: e.message }
+      end
+
+      def check_sidekiq
+        return { status: "skipped", message: "Sidekiq check disabled" } unless Vert.config.health_check_sidekiq
+        return { status: "skipped", message: "Sidekiq not configured" } unless sidekiq_available?
+
+        stats = Sidekiq::Stats.new
+        { status: "ok", processed: stats.processed, failed: stats.failed, queues: stats.queues }
+      rescue StandardError => e
+        { status: "error", message: e.message }
+      end
+
+      class << self
+        def checker
+          @checker ||= new
+        end
+
+        delegate :check_all, :liveness, :readiness, :add_check, :register, to: :checker
+      end
+
+      private
+
+      def setup_default_checks
+        add_check(:database) { check_database } if Vert.config.health_check_database
+        add_check(:redis) { check_redis } if Vert.config.health_check_redis
+        add_check(:rabbitmq) { check_rabbitmq } if Vert.config.health_check_rabbitmq
+        add_check(:sidekiq) { check_sidekiq } if Vert.config.health_check_sidekiq
+      end
+
+      def redis_available?
+        defined?(Redis) && Redis.respond_to?(:current)
+      end
+
+      def sidekiq_available?
+        defined?(Sidekiq::Stats)
+      end
+    end
+  end
+end

data/lib/vert/health/routes.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Vert
+  module Health
+    module Routes
+      class << self
+        def mount(router, path: nil)
+          path ||= Vert.config.health_check_path
+          router.instance_eval do
+            scope path do
+              get "/", to: "health#show", as: :health
+              get "/live", to: "health#live", as: :health_live
+              get "/ready", to: "health#ready", as: :health_ready
+            end
+          end
+        end
+      end
+    end
+
+    module ControllerMixin
+      extend ActiveSupport::Concern
+
+      def show
+        result = Vert::Health.check_all
+        status = result[:status] == "healthy" ? :ok : :service_unavailable
+        render json: result, status: status
+      end
+
+      def live
+        render json: Vert::Health.liveness, status: :ok
+      end
+
+      def ready
+        result = Vert::Health.readiness
+        status = result[:status] == "ready" ? :ok : :service_unavailable
+        render json: result, status: status
+      end
+    end
+
+    class Controller < ActionController::API
+      include ControllerMixin
+    end
+  end
+end if defined?(ActionController::API)

data/lib/vert/outbox/event.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Vert
+  module Outbox
+    module Event
+      extend ActiveSupport::Concern
+
+      included do
+        validates :event_type, presence: true
+        validates :aggregate_type, presence: true
+        validates :aggregate_id, presence: true
+        validates :payload, presence: true
+        validates :status, presence: true
+        enum :status, { pending: 0, published: 1, failed: 2 }, prefix: true
+        scope :pending_events, -> { status_pending.order(:created_at) }
+        scope :failed_events, -> { status_failed.where("retry_count < ?", max_retry_count).order(:created_at) }
+        scope :by_aggregate, ->(type, id) { where(aggregate_type: type, aggregate_id: id) }
+        scope :publishable, -> { pending_events.or(failed_events) }
+      end
+
+      class_methods do
+        def max_retry_count
+          5
+        end
+
+        def create_event(event_type:, aggregate_type:, aggregate_id:, payload:)
+          create!(
+            tenant_id: Vert::Current.tenant_id,
+            event_type: event_type,
+            aggregate_type: aggregate_type,
+            aggregate_id: aggregate_id,
+            payload: payload,
+            status: :pending
+          )
+        end
+
+        def publish_for(aggregate, event_type:, payload: {})
+          create_event(
+            event_type: event_type,
+            aggregate_type: aggregate.class.name,
+            aggregate_id: aggregate.id,
+            payload: payload.merge(id: aggregate.id, tenant_id: aggregate.tenant_id)
+          )
+        end
+      end
+
+      def mark_as_published!
+        update!(status: :published, published_at: Time.current)
+      end
+
+      def mark_as_failed!(error)
+        update!(status: :failed, retry_count: retry_count + 1, last_error: error.to_s, failed_at: Time.current)
+      end
+
+      def can_retry?
+        status_failed? && retry_count < self.class.max_retry_count
+      end
+
+      def routing_key
+        event_type.tr("_", ".")
+      end
+
+      def message_headers
+        { tenant_id: tenant_id, event_type: event_type, aggregate_type: aggregate_type, aggregate_id: aggregate_id, event_id: id, timestamp: created_at.iso8601 }
+      end
+    end
+  end
+end

data/lib/vert/outbox/publisher.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "bunny"
+
+module Vert
+  module Outbox
+    class Publisher
+      attr_reader :connection, :channel, :exchange
+
+      def initialize
+        @connection = nil
+        @channel = nil
+        @exchange = nil
+      end
+
+      def connect
+        @connection = Bunny.new(Vert.config.rabbitmq_url)
+        @connection.start
+        @channel = @connection.create_channel
+        @exchange = @channel.topic(Vert.config.exchange_name, durable: true)
+        self
+      end
+
+      def close
+        @connection&.close
+        @connection = nil
+        @channel = nil
+        @exchange = nil
+      end
+
+      def connected?
+        @connection&.open? && @channel&.open?
+      end
+
+      def publish(event)
+        connect unless connected?
+        message = build_message(event)
+        @exchange.publish(
+          message.to_json,
+          routing_key: event.routing_key,
+          persistent: true,
+          content_type: "application/json",
+          message_id: event.id.to_s,
+          timestamp: event.created_at.to_i,
+          headers: event.message_headers
+        )
+        event.mark_as_published!
+        true
+      rescue StandardError => e
+        event.mark_as_failed!(e)
+        false
+      end
+
+      def publish_batch(events)
+        results = { published: 0, failed: 0 }
+        events.each { |event| publish(event) ? results[:published] += 1 : results[:failed] += 1 }
+        results
+      end
+
+      class << self
+        def with_connection
+          publisher = new
+          publisher.connect
+          yield publisher
+        ensure
+          publisher&.close
+        end
+
+        def publish_pending(batch_size: 100)
+          return { published: 0, failed: 0, error: "OutboxEvent not defined" } unless outbox_event_class
+          results = { published: 0, failed: 0 }
+          with_connection do |publisher|
+            outbox_event_class.publishable.find_in_batches(batch_size: batch_size) do |events|
+              batch_results = publisher.publish_batch(events)
+              results[:published] += batch_results[:published]
+              results[:failed] += batch_results[:failed]
+            end
+          end
+          results
+        end
+
+        private
+
+        def outbox_event_class
+          @outbox_event_class ||= (Object.const_get("OutboxEvent") rescue nil)
+        end
+      end
+
+      private
+
+      def build_message(event)
+        {
+          event_id: event.id.to_s,
+          event_type: event.event_type,
+          aggregate_type: event.aggregate_type,
+          aggregate_id: event.aggregate_id.to_s,
+          tenant_id: event.tenant_id.to_s,
+          occurred_at: event.created_at.iso8601,
+          metadata: { tenant_id: event.tenant_id.to_s, published_at: Time.current.iso8601 },
+          data: event.payload.is_a?(Hash) ? (event.payload[:data] || event.payload["data"] || event.payload) : event.payload
+        }
+      end
+    end
+  end
+end

data/lib/vert/outbox/publisher_job.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Vert
+  module Outbox
+    class PublisherJob
+      include Sidekiq::Job if defined?(Sidekiq::Job)
+      sidekiq_options queue: :critical, retry: 3 if respond_to?(:sidekiq_options)
+
+      def perform
+        return unless Vert.config.enable_outbox
+        return unless outbox_event_class
+
+        outbox_event_class.pending_events.find_each { |event| publish_event(event) }
+        outbox_event_class.failed_events.find_each { |event| publish_event(event) }
+      end
+
+      private
+
+      def publish_event(event)
+        Publisher.with_connection { |publisher| publisher.publish(event) }
+      rescue StandardError => e
+        Rails.logger.error("[Vert::Outbox] Failed #{event.event_type}: #{e.message}") if defined?(Rails)
+      end
+
+      def outbox_event_class
+        @outbox_event_class ||= (Object.const_get("OutboxEvent") rescue nil)
+      end
+    end
+  end
+end