transactional_outbox 1.0.0beta1 → 1.0.0beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42a54d284ea636e8eb359b0811d7ac27ad8824bf3e13770d48e73eab16bfd708
-  data.tar.gz: 9e16996f3bebea49f9cfd3fb8c25013194e55d5a5895e87f4bc2cee5d88c46ab
+  metadata.gz: 0fdc9de5705816c6e7a07d44d5ca43fa972d6d83935b861cc6ea42f477af6f24
+  data.tar.gz: c0b9b3743a73d142153b480a52260a4e030c6496d18c57adb0f0c6b2f43bee4b
 SHA512:
-  metadata.gz: 82c60dccae95ff5a06e943e176376e7b04138035eba2e2f2630dcba71c975bccfb198fcd283c8dac32d3bcd26433410f1cd997cd1244b5d87b43cda32483cb32
-  data.tar.gz: b488181838b78ef608225482e60ccdfe4d845129372eaad3c55acb0481409bc7a6afa4fa526b3bcfd31ee100d626c37aac1bcbe3ed5ff4581e0e7cf95d154e59
+  metadata.gz: 2e588b796c4c5b22c9c0188a8d5ed857695c832d961df5c4ebfc3c4bbbe3237e61339a13b763412d4e52a3dd087e1f40749a0cba777518262486e95623cd952c
+  data.tar.gz: a2b31bcca2501c6f19ba593caa80badbfdc75301b4c97affd3e8e02bf2a6cac8cb835d105aad8d96825d8002d6c38ef6e618d84f68ff51e60b55377aad9a5ca8

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.0.0beta2] - 2026-08-25
+
+- Added examples
+- Fixed some minor bugs
+- Added status model to outbox events table
+
 ## [1.0.0beta1] - 2026-08-24
 
 - Beta implementation of transactional outbox

data/README.md

@@ -8,13 +8,13 @@
 
 ## Installation
 
-Add this line to your application's Gemfile:
+1. Add this line to your application's Gemfile:
 
 ```ruby
 gem 'transactional_outbox'
 ```
 
-And then execute:
+2. Execute:
 
     $ bundle install
 
@@ -22,6 +22,31 @@ Or install it yourself as:
 
     $ gem install transactional_outbox
 
+## Using
+
+1. Configure it (see [configuration](docs/configuration.md)).
+
+2. Generate migrations (if you're using Rails) or use template from [here](./lib/generators/transactional_outbox/migration/templates/) and migrate it:
+
+```sh
+$ rails g transactional_outbox:migration
+$ rails db:migrate
+```
+
+3. Define your own events (see [events creation](./docs/events_creation.md)).
+
+4. Run event relay (see [event relay](./docs/event_relay.md)) with rake task (if needed):
+
+```sh
+$ rake event_relay:run
+```
+
+Or run it directly like [here](./examples/example-app/bin/relay):
+
+```ruby
+TransactionalOutbox::Relay::Runner.start
+```
+
 ## Architecture
 
 ![Architecture](docs/architecture.png)

data/lib/generators/transactional_outbox/migration/templates/active_record.rb.erb

@@ -1,18 +1,37 @@
 # frozen_string_literal: true
 
 class CreateOutboxEventsTable < ActiveRecord::Migration[7.0]
-  def change
+  def up
+    execute <<-SQL
+      CREATE TYPE <%= TransactionalOutbox.config.outbox_table_name %>_status_type AS ENUM(
+        '<%= TransactionalOutbox::EVENT_NEW_STATUS %>',
+        '<%= TransactionalOutbox::EVENT_PROCESSING_STATUS %>'
+      );
+    SQL
+
     create_table :<%= TransactionalOutbox.config.outbox_table_name %>, id: :uuid do |t|
       t.string :aggregate_type, null: false
       t.uuid :aggregate_id, null: false
       t.string :event_type, null: false
-      t.string :topic, null: false
+      t.string :queue, null: false
+      t.column :status, :<%= TransactionalOutbox.config.outbox_table_name %>_status_type, default: "<%= TransactionalOutbox::EVENT_NEW_STATUS %>", null: false
+      t.jsonb :queue_extra_parameters
       t.jsonb :headers
       t.jsonb :payload
-      t.datetime :created_at, null: false, default: "now()"
+      t.datetime :processing_started_at
+
+      t.timestamps
     end
 
-    add_index :<%= TransactionalOutbox.config.outbox_table_name %>, :topic
+    add_index :<%= TransactionalOutbox.config.outbox_table_name %>, :queue
+  end
+
+  def down
+    drop_table :<%= TransactionalOutbox.config.outbox_table_name %>
+
+    execute <<-SQL
+      DROP TYPE <%= TransactionalOutbox.config.outbox_table_name %>_status_type;
+    SQL
   end
 end
 

data/lib/generators/transactional_outbox/migration/templates/sequel.rb.erb

@@ -3,24 +3,34 @@
 Sequel.migration do
   up do
     run <<-SQL.squish
+      CREATE TYPE <%= TransactionalOutbox.config.outbox_table_name %>_status_type AS ENUM(
+        '<%= TransactionalOutbox::EVENT_NEW_STATUS %>',
+        '<%= TransactionalOutbox::EVENT_PROCESSING_STATUS %>'
+      );
+
       CREATE TABLE IF NOT EXISTS <%= TransactionalOutbox.config.outbox_table_name %> (
         id uuid NOT NULL DEFAULT gen_random_uuid() PRIMARY KEY,
-        aggregate_type text NOT NULL,
+        aggregate_type varchar(255) NOT NULL,
         aggregate_id uuid NOT NULL,
-        event_type text NOT NULL,
-        topic text NOT NULL,
+        event_type varchar(255) NOT NULL,
+        queue text NOT NULL,
+        queue_extra_parameters jsonb,
+        status <%= TransactionalOutbox.config.outbox_table_name %>_status_type NOT NULL DEFAULT '<%= TransactionalOutbox::EVENT_NEW_STATUS %>',
         headers jsonb,
         payload jsonb,
-        created_at timestamp without time zone DEFAULT now() NOT NULL
+        processing_started_at timestamp without time zone,
+        created_at timestamp without time zone DEFAULT now() NOT NULL,
+        updated_at timestamp without time zone DEFAULT now() NOT NULL
       );
 
-      CREATE INDEX idx_<%= TransactionalOutbox.config.outbox_table_name %>_topic ON <%= TransactionalOutbox.config.outbox_table_name %>(topic);
+      CREATE INDEX idx_<%= TransactionalOutbox.config.outbox_table_name %>_queue ON <%= TransactionalOutbox.config.outbox_table_name %>(queue);
     SQL
   end
 
   down do
     run <<-SQL.squish
       DROP TABLE IF EXISTS <%= TransactionalOutbox.config.outbox_table_name %>;
+      DROP TYPE <%= TransactionalOutbox.config.outbox_table_name %>_status_type;
     SQL
   end
 end

data/lib/transactional_outbox/adapters_container.rb

@@ -6,7 +6,7 @@ module TransactionalOutbox
       def resolve(adapter)
         return container.resolve(adapter) if exists?(adapter)
 
-        raise TransactionalOutbox::UnknownAdapterError, "Unknown producer adapter: #{adapter}"
+        raise TransactionalOutbox::UnknownAdapterError, "Unknown adapter: #{adapter}"
       end
 
       def register(adapter, klass)

data/lib/transactional_outbox/constants.rb

@@ -12,5 +12,8 @@ module TransactionalOutbox
     WORKER_STOPPED_MONITOR_EVENT = "worker.stopped"
     WORKER_EVENTS_PROCESSED_MONITOR_EVENT = "worker.events.processed"
     WORKER_EXCEPTIONS_TOTAL_MONITOR_EVENT = "worker.exceptions_total"
+
+    EVENT_NEW_STATUS = "new"
+    EVENT_PROCESSING_STATUS = "processing"
   end
 end

data/lib/transactional_outbox/database/adapters/active_record.rb

@@ -3,22 +3,40 @@
 module TransactionalOutbox
   class Database
     class Adapters
-      class ActiveRecord < Interface
+      class ActiveRecord < Base
         def transaction(*options, &) = model.transaction(*options, &)
 
-        def fetch_events(topic, batch_size)
-          model.where(topic:).order(:created_at).limit(batch_size).lock("FOR UPDATE SKIP LOCKED").map do |event|
-            event.attributes.symbolize_keys
-          end
+        def fetch_events(queue, batch_size)
+          claimable_scope(model.where(queue:))
+            .order(:created_at)
+            .limit(batch_size)
+            .lock("FOR UPDATE SKIP LOCKED")
+            .map { |event| event.attributes.symbolize_keys }
         end
 
         def insert_events(attributes) = model.insert_all(attributes)
         def delete_events(ids) = model.where(id: ids).delete_all
-        def fetch_topics = model.select(:topic).distinct.map(&:topic)
+        def fetch_queues = claimable_scope(model).select(:queue).distinct.map(&:queue)
+
+        def move_to_processing(ids)
+          model
+            .where(id: ids)
+            .update_all(status: TransactionalOutbox::EVENT_PROCESSING_STATUS, processing_started_at: current_time)
+        end
 
         private
 
         def model = @model ||= Object.const_get(config.db.connection_data[:model])
+
+        def claimable_scope(scope)
+          scope
+            .where(status: TransactionalOutbox::EVENT_NEW_STATUS)
+            .or(
+              scope
+                .where(status: TransactionalOutbox::EVENT_PROCESSING_STATUS)
+                .where(processing_started_at: ...outdated_events_timestamp)
+            )
+        end
       end
     end
   end

data/lib/transactional_outbox/database/adapters/base.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "interface"
+require_relative "instance_methods"
+
+module TransactionalOutbox
+  class Database
+    class Adapters
+      class Base < Interface
+        include InstanceMethods
+      end
+    end
+  end
+end

data/lib/transactional_outbox/database/adapters/instance_methods.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TransactionalOutbox
+  class Database
+    class Adapters
+      module InstanceMethods
+        def initialize
+          @outbox_table_name = TransactionalOutbox.config.outbox_table_name
+        end
+
+        private
+
+        attr_reader :outbox_table_name
+
+        def config = @config ||= TransactionalOutbox.config
+        def outdated_events_timestamp = Time.now.utc - config.relay.processing_events_claim_timeout_seconds
+        def current_time = Time.now.utc
+      end
+    end
+  end
+end

data/lib/transactional_outbox/database/adapters/interface.rb

@@ -4,21 +4,12 @@ module TransactionalOutbox
   class Database
     class Adapters
       class Interface
-        def initialize
-          @outbox_table_name = TransactionalOutbox.config.outbox_table_name
-        end
-
         def transaction(*_options, &) = raise NotImplementedError
         def insert_events(_attributes) = raise NotImplementedError
-        def fetch_events(_topic_name) = raise NotImplementedError
+        def fetch_events(_queue_name, _batch_size) = raise NotImplementedError
         def delete_events(_ids) = raise NotImplementedError
-        def fetch_topics = raise NotImplementedError
-
-        private
-
-        attr_reader :outbox_table_name
-
-        def config = @config ||= TransactionalOutbox.config
+        def fetch_queues = raise NotImplementedError
+        def move_to_processing(_ids) = raise NotImplementedError
       end
     end
   end

data/lib/transactional_outbox/database/adapters/null.rb

@@ -3,34 +3,50 @@
 module TransactionalOutbox
   class Database
     class Adapters
-      class Null < Interface
+      class Null < Base
         class << self
-          def dataset = @dataset ||= []
-          def clear_store = @dataset = []
+          def dataset = @dataset ||= {}
+          def clear_store = @dataset = {}
         end
 
         def transaction(*_options, &block) = block.call
 
         def insert_events(rows)
-          rows
-            .map { |attrs| attrs.merge(id: SecureRandom.uuid) }
-            .tap { |identified_rows| dataset.concat(identified_rows) }
+          rows.each do |row|
+            dataset[row[:id]] = row.merge(
+              status: TransactionalOutbox::EVENT_NEW_STATUS, processing_started_at: current_time
+            )
+          end
         end
 
-        def fetch_events(topic_name, batch_size) = dataset.select { |row| row[:topic] == topic_name }.first(batch_size)
-        def fetch_topics = dataset.map { |row| row[:topic] }
+        def fetch_events(queue_name, batch_size)
+          dataset.values.select { |row| row[:queue] == queue_name }.then { claimable_scope(_1) }.first(batch_size)
+        end
 
-        def delete_events(ids)
-          ids_map = ids.to_h { |id| [id, true] }
+        def fetch_queues = dataset.values.then { claimable_scope(_1) }.map { |row| row[:queue] }.uniq
 
-          dataset.delete_if { |row| ids_map[row[:id]] }
+        def move_to_processing(ids)
+          ids.each { |id| dataset[id]&.merge!(status: TransactionalOutbox::EVENT_PROCESSING_STATUS) }
+        end
+
+        def delete_events(ids)
+          ids.each { |id| dataset.delete(id) }
 
           true
         end
 
         private
 
-        def dataset = self.class.dataset ||= []
+        def dataset = self.class.dataset ||= {}
+
+        def claimable_scope(scope)
+          scope.select do |row|
+            row[:status] == TransactionalOutbox::EVENT_NEW_STATUS || (
+              row[:status] == TransactionalOutbox::EVENT_PROCESSING_STATUS &&
+                row[:processing_started_at] < outdated_events_timestamp
+            )
+          end
+        end
       end
     end
   end

data/lib/transactional_outbox/database/adapters/sequel.rb

@@ -3,14 +3,21 @@
 module TransactionalOutbox
   class Database
     class Adapters
-      class Sequel < Interface
+      class Sequel < Base
         def transaction(*options, &) = db.transaction(*options, &)
         def insert_events(attributes) = table_object.multi_insert(attributes)
-        def fetch_topics = table_object.select(:topic).distinct.map { |event| event[:topic] }
+        def fetch_queues = claimable_scope(table_object).select(:queue).distinct.map { |event| event[:queue] }
+
         def delete_events(ids) = table_object.where(id: ids).delete
 
-        def fetch_events(topic, batch_size)
-          dataset = table_object.where(topic:).order(:created_at).limit(batch_size)
+        def move_to_processing(ids)
+          table_object
+            .where(id: ids)
+            .update(status: TransactionalOutbox::EVENT_PROCESSING_STATUS, processing_started_at: current_time)
+        end
+
+        def fetch_events(queue, batch_size)
+          dataset = claimable_scope(table_object.where(queue:)).order(:created_at).limit(batch_size)
           dataset = dataset.for_update.skip_locked unless config.test_environment
 
           dataset.all
@@ -20,6 +27,18 @@ module TransactionalOutbox
 
         def db = @db ||= config.db.connection_data[:db]
         def table_object = @table_object ||= db.from(outbox_table_name)
+
+        def claimable_scope(scope)
+          scope.where(
+            ::Sequel.|(
+              { status: TransactionalOutbox::EVENT_NEW_STATUS },
+              ::Sequel.&(
+                { status: TransactionalOutbox::EVENT_PROCESSING_STATUS },
+                ::Sequel.expr(:processing_started_at) < outdated_events_timestamp
+              )
+            )
+          )
+        end
       end
     end
   end

data/lib/transactional_outbox/database.rb

@@ -4,7 +4,8 @@ module TransactionalOutbox
   class Database
     extend Forwardable
 
-    def_delegators :@adapter, :transaction, :insert_events, :fetch_events, :fetch_topics, :delete_events
+    def_delegators :@adapter, :transaction, :insert_events, :fetch_events, :fetch_queues, :delete_events,
+                   :move_to_processing
 
     attr_reader :adapter
 

data/lib/transactional_outbox/event/builder.rb

@@ -3,11 +3,13 @@
 module TransactionalOutbox
   class Event
     class Builder
-      def self.build(event_config, payload, _context)
+      def self.build(event_config, payload, context)
         {
           id: SecureRandom.uuid,
-          topic: event_config.topic,
+          queue: event_config.queue,
+          queue_extra_parameters: event_config.queue_extra_parameters,
           aggregate_type: event_config.aggregate_type,
+          aggregate_id: context[event_config.aggregate_type.to_sym][:id],
           event_type: event_config.event_type.to_s,
           headers: {},
           payload:

data/lib/transactional_outbox/event/contextable.rb

@@ -3,8 +3,6 @@
 module TransactionalOutbox
   class Event
     module Contextable
-      attr_reader :context_schema
-
       def self.extended(klass)
         klass.define_method(:validate_context!) do |params|
           ctx_schema = self.class.instance_variable_get(:@__context_schema__)

data/lib/transactional_outbox/event/payloadable.rb

@@ -11,7 +11,7 @@ module TransactionalOutbox
         end
       end
 
-      def payload(&block) = @payload ||= block
+      def prepare_payload(&block) = @payload ||= block # rubocop:disable Naming/MemoizedInstanceVariableName
     end
   end
 end

data/lib/transactional_outbox/event.rb

@@ -12,8 +12,9 @@ module TransactionalOutbox
     setting :schema
     setting :aggregate_type
     setting :event_type
-    setting :topic
     setting :event_builder
+    setting :queue
+    setting :queue_extra_parameters
 
     config.values.keys.each do |attr|
       define_singleton_method(attr) do |value|
@@ -45,7 +46,7 @@ module TransactionalOutbox
       @event_builder ||= begin
         klass = config.event_builder || TransactionalOutbox.config.default_event_builder
 
-        Object.const_get(klass)
+        klass.is_a?(String) ? Object.const_get(klass) : klass
       end
     end
 

data/lib/transactional_outbox/producer/adapters/base.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "interface"
+require_relative "instance_methods"
+
+module TransactionalOutbox
+  class Producer
+    class Adapters
+      class Base < Interface
+        include InstanceMethods
+      end
+    end
+  end
+end

data/lib/transactional_outbox/producer/adapters/instance_methods.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module TransactionalOutbox
+  class Producer
+    class Adapters
+      module InstanceMethods
+        def initialize(connection_config)
+          @connection_config = connection_config
+        end
+
+        private
+
+        attr_reader :connection_config
+      end
+    end
+  end
+end

data/lib/transactional_outbox/producer/adapters/interface.rb

@@ -4,15 +4,8 @@ module TransactionalOutbox
   class Producer
     class Adapters
       class Interface
-        def initialize(client)
-          @client = client
-        end
-
-        def produce_batch(_topic, _batch) = raise NotImplementedError
-
-        private
-
-        attr_reader :client
+        def produce_batch(_queue, _batch) = raise NotImplementedError
+        def close = raise NotImplementedError
       end
     end
   end

data/lib/transactional_outbox/producer/adapters/kafka.rb

@@ -3,15 +3,18 @@
 module TransactionalOutbox
   class Producer
     class Adapters
-      class Kafka < Interface
+      class Kafka < Base
         def produce_batch(topic, events)
           buffer_events(topic, events)
 
           producer.deliver_messages
         end
 
+        def close = client.close
+
         private
 
+        def client = @client ||= ::Kafka.new(**connection_config)
         def producer = @producer ||= client.producer
 
         def buffer_events(topic, events)

data/lib/transactional_outbox/producer/adapters/null.rb

@@ -3,17 +3,19 @@
 module TransactionalOutbox
   class Producer
     class Adapters
-      class Null < Interface
+      class Null < Base
         def messages = @messages ||= {}
         def clear_store = @messages = {}
 
-        def produce_batch(topic, events)
-          msg = messages[topic] ||= []
+        def produce_batch(queue, events)
+          msg = messages[queue] ||= []
 
           msg.concat(events)
 
-          TransactionalOutbox.config.logger.info("Batch produced")
+          TransactionalOutbox.config.logger&.info("Batch produced")
         end
+
+        def close = true
       end
     end
   end

data/lib/transactional_outbox/producer.rb

@@ -4,12 +4,12 @@ module TransactionalOutbox
   class Producer
     extend Forwardable
 
-    def_delegators :@adapter, :produce_batch
+    def_delegators :@adapter, :produce_batch, :close
 
     attr_reader :adapter
 
     def initialize
-      @adapter = TransactionalOutbox::Producer::Adapters.resolve(fetch_adapter).new(fetch_client)
+      @adapter = TransactionalOutbox::Producer::Adapters.resolve(fetch_adapter).new(config.producer.connection_config)
     end
 
     private
@@ -21,11 +21,5 @@ module TransactionalOutbox
 
       config.producer.adapter.to_sym
     end
-
-    def fetch_client
-      return if config.test_environment
-
-      config.producer.client
-    end
   end
 end

data/lib/transactional_outbox/relay/event_processor.rb

@@ -3,27 +3,23 @@
 module TransactionalOutbox
   class Relay
     class EventProcessor
-      attr_reader :topic, :db, :producer
+      attr_reader :queue, :db, :producer
 
-      def initialize(topic)
-        @topic = topic
+      def initialize(queue, producer)
+        @queue = queue
         @db = TransactionalOutbox::Database.new
-        @producer = TransactionalOutbox::Producer.new
+        @producer = producer
       end
 
       def call
-        events = db.fetch_events(topic, config.relay.batch_size)
-
-        return if events.empty?
-
-        process_events(events)
+        process
       rescue StandardError => e
         TransactionalOutbox::Relay.monitor.publish(
           TransactionalOutbox::WORKER_EXCEPTIONS_TOTAL_MONITOR_EVENT,
-          { topic:, exception: e.class.to_s }
+          { queue:, exception: e.class.to_s }
         )
 
-        resolve_failover.call(e, events)
+        resolve_failover.call(e, @events)
       end
 
       private
@@ -33,22 +29,34 @@ module TransactionalOutbox
       def resolve_failover
         configured = config.relay.failover
 
-        return Object.get_const(configured) if configured.is_a?(String)
+        return Object.const_get(configured) if configured.is_a?(String)
 
         configured
       end
 
-      def process_events(events)
-        producer.produce_batch(topic, events)
+      def process # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        db.transaction do
+          @events = db.fetch_events(queue, config.relay.batch_size)
+
+          db.move_to_processing(events_ids) unless @events.empty?
+        end
+
+        return if @events.empty?
 
-        db.delete_events(events.map { |x| x[:id] })
+        producer.produce_batch(queue, @events)
+
+        db.delete_events(events_ids)
+
+        events_count = @events.size
 
         TransactionalOutbox::Relay.monitor.publish(
-          TransactionalOutbox::WORKER_EVENTS_PROCESSED_MONITOR_EVENT, { topic:, count: events.size }
+          TransactionalOutbox::WORKER_EVENTS_PROCESSED_MONITOR_EVENT, { queue:, count: events_count }
         )
 
-        config.logger.info("Events have sent to topic #{topic}: #{events.size}")
+        config.logger&.info("Events have sent to queue #{queue}: #{events_count}")
       end
+
+      def events_ids = @events_ids ||= @events.map { |e| e[:id] }
     end
   end
 end

data/lib/transactional_outbox/relay/graceful_shutdown.rb

@@ -4,10 +4,10 @@ module TransactionalOutbox
   class Relay
     class GracefulShutdown
       class << self
-        def call(worker_set)
+        def call(worker_set, exit_code = 0)
           worker_set.stop_workers
 
-          wait_workers(worker_set)
+          call_exit(exit_code) if wait_workers(worker_set)
         end
 
         private
@@ -21,7 +21,7 @@ module TransactionalOutbox
             if worker_set.all_stopped?
               TransactionalOutbox::Relay.monitor.publish(TransactionalOutbox::RUNNER_STOPPED_MONITOR_EVENT)
 
-              config.logger.info("All workers have stopped.")
+              config.logger&.info("All workers have stopped.")
 
               return true
             end
@@ -31,6 +31,12 @@ module TransactionalOutbox
 
           false
         end
+
+        def call_exit(code)
+          return code if config.test_environment
+
+          exit(code)
+        end
       end
     end
   end

data/lib/transactional_outbox/relay/runner.rb

@@ -25,24 +25,16 @@ module TransactionalOutbox
         def start_relay(worker_set) = TransactionalOutbox::Relay::WorkerSet::Processor.new(worker_set).call
         def config = @config ||= TransactionalOutbox.config
 
-        def start_graceful_shutdown(worker_set)
+        def start_graceful_shutdown(worker_set, exit_code)
           return unless worker_set
 
-          TransactionalOutbox::Relay::GracefulShutdown.call(worker_set)
-        end
-
-        def call_exit(code)
-          return true if config.test_environment
-
-          exit(code)
+          TransactionalOutbox::Relay::GracefulShutdown.call(worker_set, exit_code)
         end
 
         def shutdown(exception, worker_set, exit_code)
-          config.logger.info("Received exception: #{exception}. Shutting down...")
-
-          start_graceful_shutdown(worker_set)
+          config.logger&.info("Received exception: #{exception}. Shutting down...")
 
-          call_exit(exit_code)
+          start_graceful_shutdown(worker_set, exit_code)
         end
       end
     end

data/lib/transactional_outbox/relay/worker_set/processor.rb

@@ -13,15 +13,15 @@ module TransactionalOutbox
           @retry_counter = 0
 
           loop do
-            topics = db.fetch_topics
+            queues = db.fetch_queues
 
-            process_topics(topics)
+            process_queues(queues)
 
             break if config.test_environment
 
             @retry_counter = 0
           rescue StandardError => e
-            config.logger.error("Exception: #{e}, trying to retry...")
+            config.logger&.error("Exception: #{e}, trying to retry...")
 
             raise e if @retry_counter >= config.relay.max_runner_retries_count
 
@@ -40,14 +40,14 @@ module TransactionalOutbox
         def config = @config ||= TransactionalOutbox.config
         def calculate_retry_delay = TransactionalOutbox::ExponentialBackoff.calculate_retry_delay(@retry_counter)
 
-        def process_topics(topics)
-          topics.each do |topic|
-            worker = worker_set.get_worker(topic)
+        def process_queues(queues)
+          queues.each do |queue|
+            worker = worker_set.get_worker(queue)
 
-            worker ? worker_set.try_to_recover_worker(topic) : worker_set.add_worker(topic)
+            worker ? worker_set.try_to_recover_worker(queue) : worker_set.add_worker(queue)
           end
 
-          sleep(config.relay.delay_between_worker_set_processor_cycles)
+          sleep(config.relay.delay_between_worker_set_processor_cycles_seconds)
         end
       end
     end

data/lib/transactional_outbox/relay/worker_set/worker.rb

@@ -6,10 +6,11 @@ module TransactionalOutbox
   class Relay
     class WorkerSet
       class Worker
-        attr_reader :topic, :db, :producer
+        attr_reader :queue, :db, :producer
 
-        def initialize(topic)
-          @topic = topic
+        def initialize(queue)
+          @queue = queue
+          @producer = TransactionalOutbox::Producer.new
         end
 
         def run
@@ -32,21 +33,21 @@ module TransactionalOutbox
         def config = @config ||= TransactionalOutbox.config
 
         def spawn_thread # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-          TransactionalOutbox::Relay.monitor.publish(TransactionalOutbox::WORKER_RUN_MONITOR_EVENT, { topic: })
+          TransactionalOutbox::Relay.monitor.publish(TransactionalOutbox::WORKER_RUN_MONITOR_EVENT, { queue: })
 
           Thread.new do
             loop do
-              TransactionalOutbox::Relay::EventProcessor.new(topic).call
+              TransactionalOutbox::Relay::EventProcessor.new(queue, producer).call
 
               if Thread.current[:shutdown]
-                config.logger.info("Thread for topic #{topic} successfully shutted down")
+                config.logger&.info("Thread for queue #{queue} successfully shutted down")
 
                 mark_thread_as_stopped
 
                 break
               end
 
-              break if config.test_environment
+              break mark_thread_as_stopped if config.test_environment
 
               sleep(config.relay.wait_between_batches_seconds)
             end
@@ -54,13 +55,15 @@ module TransactionalOutbox
             mark_thread_as_stopped
 
             raise e
+          ensure
+            producer&.close
           end
         end
 
         def mark_thread_as_stopped
           Thread.current[:stopped] = true
 
-          TransactionalOutbox::Relay.monitor.publish(TransactionalOutbox::WORKER_STOPPED_MONITOR_EVENT, { topic: })
+          TransactionalOutbox::Relay.monitor.publish(TransactionalOutbox::WORKER_STOPPED_MONITOR_EVENT, { queue: })
         end
       end
     end

data/lib/transactional_outbox/relay/worker_set.rb

@@ -9,20 +9,20 @@ module TransactionalOutbox
         @workers = {}
       end
 
-      def get_worker(topic) = workers[topic]
+      def get_worker(queue) = workers[queue]
 
-      def add_worker(topic)
-        return if workers.key?(topic)
+      def add_worker(queue)
+        return if workers.key?(queue)
 
-        create_worker(topic)
+        create_worker(queue)
       end
 
-      def try_to_recover_worker(topic)
-        worker = get_worker(topic)
+      def try_to_recover_worker(queue)
+        worker = get_worker(queue)
 
         return if !worker.nil? && (worker.shutting_down? || !worker.stopped?)
 
-        create_worker(topic)
+        create_worker(queue)
       end
 
       def stop_workers = workers.each_value(&:shutdown)
@@ -32,7 +32,7 @@ module TransactionalOutbox
 
       attr_reader :workers
 
-      def create_worker(topic) = workers[topic] = Worker.new(topic).tap(&:run)
+      def create_worker(queue) = workers[queue] = Worker.new(queue).tap(&:run)
     end
   end
 end

data/lib/transactional_outbox/tasks/{relay.rake → event_relay.rake}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-namespace :relay do
+namespace :event_relay do
   desc "Runs transactional outbox event relay"
   task run: :environment do
     TransactionalOutbox::Relay::Runner.start

data/lib/transactional_outbox/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TransactionalOutbox
-  VERSION = "1.0.0beta1"
+  VERSION = "1.0.0beta2"
 end

data/lib/transactional_outbox.rb

@@ -12,12 +12,12 @@ require "securerandom"
 require_relative "transactional_outbox/version"
 require_relative "transactional_outbox/adapters_container"
 require_relative "transactional_outbox/database/adapters"
-require_relative "transactional_outbox/database/adapters/interface"
+require_relative "transactional_outbox/database/adapters/base"
 require_relative "transactional_outbox/database/adapters/null"
 require_relative "transactional_outbox/database/adapters/active_record"
 require_relative "transactional_outbox/database/adapters/sequel"
 require_relative "transactional_outbox/producer/adapters"
-require_relative "transactional_outbox/producer/adapters/interface"
+require_relative "transactional_outbox/producer/adapters/base"
 require_relative "transactional_outbox/producer/adapters/null"
 require_relative "transactional_outbox/producer/adapters/kafka"
 require_relative "transactional_outbox/constants"
@@ -49,7 +49,7 @@ module TransactionalOutbox
 
   setting :logger
   setting :outbox_table_name, default: "outbox_events"
-  setting :default_event_builder, default: TransactionalOutbox::Event::Builder
+  setting :default_event_builder, default: "TransactionalOutbox::Event::Builder"
   setting :shutdown_waiting_time_seconds, default: 10
   setting :migrations_directory
   setting :test_environment, default: false
@@ -57,9 +57,10 @@ module TransactionalOutbox
   setting :relay do
     setting :batch_size, default: 20
     setting :wait_between_batches_seconds, default: 0.1
-    setting :failover, default: TransactionalOutbox::Relay::Failover
+    setting :failover, default: "TransactionalOutbox::Relay::Failover"
     setting :max_runner_retries_count, default: 5
-    setting :delay_between_worker_set_processor_cycles, default: 1
+    setting :delay_between_worker_set_processor_cycles_seconds, default: 1
+    setting :processing_events_claim_timeout_seconds, default: 300
   end
 
   setting :db do
@@ -69,14 +70,12 @@ module TransactionalOutbox
 
   setting :producer do
     setting :adapter
-    setting :client
+    setting :connection_config
   end
 
   class << self
-    def transaction(event)
-      Database.new.transaction do
-        yield(event.new)
-      end
+    def outboxable(&)
+      Database.new.transaction(&)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: transactional_outbox
 version: !ruby/object:Gem::Version
-  version: 1.0.0beta1
+  version: 1.0.0beta2
 platform: ruby
 authors:
 - Roman Kakorin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-24 00:00:00.000000000 Z
+date: 2026-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -202,6 +202,8 @@ files:
 - lib/transactional_outbox/database.rb
 - lib/transactional_outbox/database/adapters.rb
 - lib/transactional_outbox/database/adapters/active_record.rb
+- lib/transactional_outbox/database/adapters/base.rb
+- lib/transactional_outbox/database/adapters/instance_methods.rb
 - lib/transactional_outbox/database/adapters/interface.rb
 - lib/transactional_outbox/database/adapters/null.rb
 - lib/transactional_outbox/database/adapters/sequel.rb
@@ -213,6 +215,8 @@ files:
 - lib/transactional_outbox/exponential_backoff.rb
 - lib/transactional_outbox/producer.rb
 - lib/transactional_outbox/producer/adapters.rb
+- lib/transactional_outbox/producer/adapters/base.rb
+- lib/transactional_outbox/producer/adapters/instance_methods.rb
 - lib/transactional_outbox/producer/adapters/interface.rb
 - lib/transactional_outbox/producer/adapters/kafka.rb
 - lib/transactional_outbox/producer/adapters/null.rb
@@ -226,7 +230,7 @@ files:
 - lib/transactional_outbox/relay/worker_set.rb
 - lib/transactional_outbox/relay/worker_set/processor.rb
 - lib/transactional_outbox/relay/worker_set/worker.rb
-- lib/transactional_outbox/tasks/relay.rake
+- lib/transactional_outbox/tasks/event_relay.rake
 - lib/transactional_outbox/version.rb
 homepage: https://github.com/sigmen/transactional_outbox
 licenses: