shared_broker 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b161a64893a9f15f9bb4568c1b281c2851904bc9e8730e8992d5f6d0847a4de4
-  data.tar.gz: 6a771b8df2dc371516b2d7f97d6e157ff493141034106c40236f952c6aef0f2e
+  metadata.gz: 7fef9571ebd7987fe360d47b8a4374206808487afc3b641b19cb19c6dbfaf85f
+  data.tar.gz: 98fc3d5712273e6d426ac380e5ebd3ff4c9cd6319a1eb00b333ea25cc977cb0f
 SHA512:
-  metadata.gz: '06494d11f1575ac5e13353acad3e9896f9ff7e5b7f64b164cecaa39b492aadeb170590e2ec9c9628c80691d08fc521e07e384fa43d2fe4e7874424704e39aedb'
-  data.tar.gz: 6781b513d75bd232c5c75738a6078aad08d096133e410335ec707ac203548b653af222bbb37ee7594fff40044e8122f8e362b12f68927939a7a19655f021ca16
+  metadata.gz: b6d52305cbfe8cd4e72d9e5bcbd84cc8bbda1c5c738a43e2727586e82f88bbe01d9e060d31ee28443c0b73172b4206ba33fd8640be394e6fba6b9b190f808a44
+  data.tar.gz: fdf993c33a31f8364aa613123159aebbeeae8ebfdd4f5548d6f1eb7210b318e0cc81f660e7ab28d4bc998868386c63086fbcc793d0cfe3ade14ffae82f8afd58

data/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-06-10
+
+### Added
+- Concurrency Control & Adaptive Backpressure.
+- `SharedBroker::Concurrency::Semaphore` pure-Ruby thread-safe semaphore implementation.
+- `SharedBroker::Concurrency::Limiter` to manage dynamic backpressure checks and concurrency limits on message ingestion.
+- Integrated concurrency parameters (`max_concurrency`, `backpressure_check`, `backpressure_backoff`) into `Client#subscribe`.
+
 ## [1.4.0] - 2026-06-10
 
 ### Added

data/README.md

@@ -177,14 +177,26 @@ event_data = {
 SPOT_BROKER.publish("user.created", event_data)
 ```
 
-### Subscribing to Events (Consumer with Retry and DLQ)
-To start a persistent event subscriber daemon, register a queue/group name associated with the topic. You can customize the retries and backoff rate:
+### Subscribing to Events (Consumer with Retry, DLQ, Concurrency & Backpressure)
+To start a persistent event subscriber daemon, register a queue/group name associated with the topic. You can customize the retries, backoff rate, concurrency limits, and dynamic backpressure checks:
 
 ```ruby
+# Basic subscriber
 SPOT_BROKER.subscribe("user.created", "my_consumption_queue", max_retries: 3, backoff_base: 2) do |payload|
   puts "Decrypted event successfully validated & consumed! ID: #{payload[:id]}"
   # execute your business logic here...
 end
+
+# Advanced subscriber with Concurrency limits and Dynamic Backpressure
+SPOT_BROKER.subscribe(
+  "user.created",
+  "my_consumption_queue",
+  max_concurrency: 5,                       # Process up to 5 events concurrently
+  backpressure_check: -> { db_overloaded? }, # Stop pulling new events if true
+  backpressure_backoff: 2.0                 # Check health again after 2 seconds
+) do |payload|
+  # business logic running within the concurrency wrapper
+end
 ```
 
 ---

data/lib/shared_broker/concurrency/limiter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "semaphore"
+
+module SharedBroker
+  module Concurrency
+    class Limiter
+      def initialize(max_concurrency: nil, backpressure_check: nil, backpressure_backoff: 1.0)
+        @backpressure_check = backpressure_check
+        @backpressure_backoff = backpressure_backoff
+        @semaphore = max_concurrency ? Semaphore.new(max_concurrency) : nil
+      end
+
+      def run
+        wait_while_overloaded
+        if @semaphore
+          @semaphore.synchronize { yield }
+        else
+          yield
+        end
+      end
+
+      private
+
+      def wait_while_overloaded
+        return unless @backpressure_check
+
+        while @backpressure_check.call
+          sleep(@backpressure_backoff)
+        end
+      end
+    end
+  end
+end

data/lib/shared_broker/concurrency/semaphore.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module SharedBroker
+  module Concurrency
+    class Semaphore
+      def initialize(limit)
+        unless limit.is_a?(Integer) && limit > 0
+          raise ArgumentError, "Expected limit to be a positive Integer, got: #{limit.inspect} (class: #{limit.class})"
+        end
+
+        @limit = limit
+        @count = 0
+        @mutex = Mutex.new
+        @cond = ConditionVariable.new
+      end
+
+      def acquire
+        @mutex.synchronize do
+          while @count >= @limit
+            @cond.wait(@mutex)
+          end
+          @count += 1
+        end
+      end
+
+      def release
+        @mutex.synchronize do
+          @count -= 1
+          @cond.signal
+        end
+      end
+
+      def synchronize
+        acquire
+        begin
+          yield
+        ensure
+          release
+        end
+      end
+    end
+  end
+end

data/lib/shared_broker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SharedBroker
-  VERSION = "1.4.0"
+  VERSION = "1.5.0"
 end

data/lib/shared_broker.rb

@@ -8,6 +8,8 @@ require_relative "shared_broker/schema_registry/providers/local"
 require_relative "shared_broker/schema_registry/providers/http"
 require_relative "shared_broker/validation"
 require_relative "shared_broker/cipher"
+require_relative "shared_broker/concurrency/semaphore"
+require_relative "shared_broker/concurrency/limiter"
 require_relative "shared_broker/middleware_pipeline"
 require_relative "shared_broker/middlewares/open_telemetry_propagation"
 require_relative "shared_broker/adapters/base"
@@ -46,14 +48,22 @@ module SharedBroker
       end
     end
 
-    def subscribe(topic, queue_name, max_retries: 3, backoff_base: 2, &block)
-      resolve_adapter(topic).subscribe(topic, queue_name, max_retries: max_retries, backoff_base: backoff_base) do |raw_message|
-        decrypted_msg = SharedBroker::Cipher.decrypt(raw_message, SharedBroker.encryption_key)
-        SharedBroker::Validation.validate!(topic, decrypted_msg)
+    def subscribe(topic, queue_name, max_retries: 3, backoff_base: 2, max_concurrency: nil, backpressure_check: nil, backpressure_backoff: 1.0, &block)
+      limiter = SharedBroker::Concurrency::Limiter.new(
+        max_concurrency: max_concurrency,
+        backpressure_check: backpressure_check,
+        backpressure_backoff: backpressure_backoff
+      )
 
-        metadata = { correlation_id: decrypted_msg[:_correlation_id], operation: :subscribe, queue_name: queue_name }
-        @middleware_pipeline.execute(topic, decrypted_msg, metadata) do
-          block.call(decrypted_msg)
+      resolve_adapter(topic).subscribe(topic, queue_name, max_retries: max_retries, backoff_base: backoff_base) do |raw_message|
+        limiter.run do
+          decrypted_msg = SharedBroker::Cipher.decrypt(raw_message, SharedBroker.encryption_key)
+          SharedBroker::Validation.validate!(topic, decrypted_msg)
+
+          metadata = { correlation_id: decrypted_msg[:_correlation_id], operation: :subscribe, queue_name: queue_name }
+          @middleware_pipeline.execute(topic, decrypted_msg, metadata) do
+            block.call(decrypted_msg)
+          end
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shared_broker
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Wesley Lima
@@ -155,6 +155,8 @@ files:
 - lib/shared_broker/adapters/redis.rb
 - lib/shared_broker/cipher.rb
 - lib/shared_broker/circuit_breaker.rb
+- lib/shared_broker/concurrency/limiter.rb
+- lib/shared_broker/concurrency/semaphore.rb
 - lib/shared_broker/middleware_pipeline.rb
 - lib/shared_broker/middlewares/open_telemetry_propagation.rb
 - lib/shared_broker/schema_registry.rb