shared_broker 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a691e6fa4ea7eb0d9b7974a55ed217c25a325be29c7beba0211d05633e947c02
-  data.tar.gz: '09abf8886190595bbcf09d7faeaf0676f848c763b8efef6ed092c8b23eac5853'
+  metadata.gz: d47439f3383e9d40d13664b67dc8b77318b64f628e6a1efa0f4684130ff2ff4b
+  data.tar.gz: 85d081f58ac1608a1629b29f14c634b370b963c65338eb7f9a32ace26bc90502
 SHA512:
-  metadata.gz: 96d856ee56c3d1db971a0a751920d03b65c3f67922b77ef67e42443f2586cc6e6063a5301fff1e050e8f2b81ab334e4479d80739604938c76f1880824692b097
-  data.tar.gz: 46d39087d7e875d84cd8a82223e68edadd965651e795c013c1da85cbfc847663fe594ed90bf8b1f60c5eb7ade7f14056f4aed3fbb5fe2a46e43fa5bc7aaf7ed0
+  metadata.gz: 25151e9182b26d17334f04b121831703eee6c8b95981ac2b235085472501f06ec97c2a6b14cedc434dd3ee49963577b8eceedc175680525025d31e3246ac81dd
+  data.tar.gz: 07cb36e946dd24260fdd70d7cd995f4aeae8167b764d1df18e2026bc523481ec4d788308f720494472985a3b1a4adc7ae8751ded5abbd20b02c8c475c10a97c6

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+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.2.0] - 2026-06-07
+
+### Added
+- Pipeline of customizable Middlewares (Interceptors) for publishing and subscribing messages.
+- Distributed Tracing using W3C Trace Context (`traceparent`/`tracestate`) context injection and extraction.
+
+## [1.1.1] - 2026-06-06
+
+### Changed
+- Restructured `README.md` to clearly separate minimum required configuration from optional/advanced setups.
+
+## [1.1.0] - 2026-06-06
+
+### Added
+- Scalable Adapters:
+  - Apache Kafka adapter (`SharedBroker::Adapters::Kafka`) with dynamic dependency loading.
+  - Redis Pub/Sub adapter (`SharedBroker::Adapters::Redis`) with list-based DLQ routing.
+  - Mock test configurations for Kafka and Redis to run adapter unit tests.
+
+## [1.0.0] - 2026-06-06
+
+### Added
+- Fault Tolerance & Resilience features:
+  - Exponential backoff retry loop for message processing.
+  - Automatic Dead Letter Queue (DLQ) routing with rich metadata headers (`x_failed_at`, `x_exception_class`, `x_exception_message`, `x_original_routing_key`).
+  - Thread-safe `CircuitBreaker` wrapping all outbound publisher calls.
+- Schema Validation and Security:
+  - Outbound/Inbound boundary validation using `dry-schema`.
+  - Transparent AES-256-GCM symmetric payload encryption by default, configurable with `SharedBroker.encryption_key`.
+- Comprehensive test coverage for all the above features using isolated fakes and Minitest.
+
+## [0.1.0] - 2026-06-06
+
+### Added
+- Initial release with the pluggable `Client` messaging system.
+- `InMemory` adapter for local testing.
+- `RabbitMQ` adapter using the `bunny` gem.
+- Basic OpenTelemetry instrumentation utility (`SharedBroker::Telemetry`).

data/README.md

@@ -44,36 +44,55 @@ bundle install
 
 ## Configuration
 
-Create an initializer in your Rails application (`config/initializers/shared_broker.rb`):
+Create an initializer in your Rails application (`config/initializers/shared_broker.rb`). Below is the breakdown of what is **required** versus what is **optional**.
+
+### 1. Required Configuration (Minimum Setup)
+
+You must configure the adapter depending on the environment, initialize the client, and configure the payload encryption key (required since AES-256-GCM is active by default):
 
 ```ruby
 require "shared_broker"
 
-# 1. Configure Validation Schemas (dry-schema)
-user_created_schema = Dry::Schema.Params do
-  required(:id).filled(:integer)
-  required(:email).filled(:string)
-end
-SharedBroker::Validation.register("user.created", user_created_schema)
-
-# 2. Configure Payload Encryption Key (AES-256-GCM)
-# Expects a 32-byte string. Default key is used in development if ENV is not set.
+# A. Configure Payload Encryption Key (AES-256-GCM)
+# Expects a 32-byte string. Use a secure production key in production.
 SharedBroker.encryption_key = ENV.fetch("SHARED_BROKER_ENCRYPTION_KEY") { "a" * 32 }
 
-# 3. Configure the Adapter based on Environment
+# B. Configure the Adapter based on Environment
 if Rails.env.test?
   # In-memory adapter prevents external queue dependency during unit tests
   BROKER_ADAPTER = SharedBroker::Adapters::InMemory.new
-elsif Rails.env.production?
-  # High-throughput production setup using Kafka
-  BROKER_ADAPTER = SharedBroker::Adapters::Kafka.new(seed_brokers: ["kafka-1:9092", "kafka-2:9092"])
 else
-  # Connects to RabbitMQ or Redis for development
+  # Connects to real RabbitMQ broker
   amqp_url = ENV.fetch("RABBITMQ_URL") { "amqp://guest:guest@localhost:5672" }
   BROKER_ADAPTER = SharedBroker::Adapters::RabbitMQ.new(amqp_url: amqp_url)
 end
 
-# 4. Instantiate the Client by Injecting the Adapter and optional custom Circuit Breaker configuration
+# C. Instantiate the Client by Injecting the Adapter
+SPOT_BROKER = SharedBroker::Client.new(adapter: BROKER_ADAPTER)
+```
+
+---
+
+### 2. Optional Configuration
+
+These features can be configured optionally depending on your needs.
+
+#### A. Event Payload Validation (dry-schema)
+Register schemas to validate payload structure automatically on outbound (`publish`) and inbound (`subscribe`) boundaries:
+
+```ruby
+user_created_schema = Dry::Schema.Params do
+  required(:id).filled(:integer)
+  required(:email).filled(:string)
+end
+
+SharedBroker::Validation.register("user.created", user_created_schema)
+```
+
+#### B. Custom Circuit Breaker
+By default, the client instantiates a standard Circuit Breaker. You can provide a custom one to tune the failure threshold and recovery window:
+
+```ruby
 custom_circuit_breaker = SharedBroker::CircuitBreaker.new(
   failure_threshold: 5,   # trip circuit after 5 failures
   recovery_timeout: 30    # wait 30 seconds before attempting recovery
@@ -83,8 +102,12 @@ SPOT_BROKER = SharedBroker::Client.new(
   adapter: BROKER_ADAPTER,
   circuit_breaker: custom_circuit_breaker
 )
+```
+
+#### C. Initialize Distributed Tracing (OpenTelemetry)
+Initialize the OpenTelemetry SDK with auto-instrumentation for the microservice:
 
-# 5. Initialize Telemetry (OpenTelemetry)
+```ruby
 SharedBroker::Telemetry.configure(service_name: "my_microservice")
 ```
 

data/lib/shared_broker/middleware_pipeline.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SharedBroker
+  class MiddlewarePipeline
+    def initialize(middlewares)
+      @middlewares = Array(middlewares)
+    end
+
+    def execute(topic, message, metadata = {}, &block)
+      run_middleware(0, topic, message, metadata, &block)
+    end
+
+    private
+
+    def run_middleware(index, topic, message, metadata, &block)
+      if index >= @middlewares.size
+        yield
+      else
+        @middlewares[index].call(topic, message, metadata) do
+          run_middleware(index + 1, topic, message, metadata, &block)
+        end
+      end
+    end
+  end
+end

data/lib/shared_broker/middlewares/open_telemetry_propagation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "opentelemetry"
+
+module SharedBroker
+  module Middlewares
+    class OpenTelemetryPropagation
+      def call(topic, message, metadata)
+        if metadata[:operation] == :publish
+          carrier = {}
+          ::OpenTelemetry.propagation.inject(carrier)
+          carrier.each do |key, value|
+            message["_#{key}".to_sym] = value
+          end
+          yield
+        elsif metadata[:operation] == :subscribe
+          carrier = {}
+          message.each do |key, value|
+            if key.to_s.start_with?("_trace")
+              carrier[key.to_s.sub(/^_/, "")] = value
+            end
+          end
+
+          parent_context = ::OpenTelemetry.propagation.extract(carrier)
+          ::OpenTelemetry::Context.with_current(parent_context) do
+            tracer = ::OpenTelemetry.tracer_provider.tracer("shared_broker")
+            tracer.in_span("#{topic} process", kind: :consumer) do |span|
+              span.set_attribute("messaging.system", "shared_broker")
+              span.set_attribute("messaging.destination", topic)
+              yield
+            end
+          end
+        else
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/shared_broker/version.rb

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

data/lib/shared_broker.rb

@@ -1,51 +1,63 @@
-# frozen_string_literal: true
-
-require_relative "shared_broker/version"
-require_relative "shared_broker/telemetry"
-require_relative "shared_broker/circuit_breaker"
-require_relative "shared_broker/validation"
-require_relative "shared_broker/cipher"
-require_relative "shared_broker/adapters/base"
-require_relative "shared_broker/adapters/in_memory"
-require_relative "shared_broker/adapters/rabbit_mq"
-require_relative "shared_broker/adapters/kafka"
-require_relative "shared_broker/adapters/redis"
-
-module SharedBroker
-  class << self
-    attr_accessor :encryption_key
-  end
-
-  # Default key for development/test if not set
-  @encryption_key = ENV.fetch("SHARED_BROKER_ENCRYPTION_KEY") { "a" * 32 }
-
-  class Client
-    attr_reader :circuit_breaker
-
-    def initialize(adapter:, circuit_breaker: nil)
-      unless adapter.respond_to?(:publish) && adapter.respond_to?(:subscribe)
-        raise ArgumentError, "Expected adapter to respond to :publish and :subscribe, got #{adapter.class} with value #{adapter.inspect}"
-      end
-
-      @adapter = adapter
-      @circuit_breaker = circuit_breaker || CircuitBreaker.new
-    end
-
-    def publish(topic, message, correlation_id: nil)
-      SharedBroker::Validation.validate!(topic, message)
-      encrypted_msg = SharedBroker::Cipher.encrypt(message, SharedBroker.encryption_key)
-
-      @circuit_breaker.run do
-        @adapter.publish(topic, encrypted_msg, correlation_id: correlation_id)
-      end
-    end
-
-    def subscribe(topic, queue_name, max_retries: 3, backoff_base: 2, &block)
-      @adapter.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)
-        block.call(decrypted_msg)
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+require_relative "shared_broker/version"
+require_relative "shared_broker/telemetry"
+require_relative "shared_broker/circuit_breaker"
+require_relative "shared_broker/validation"
+require_relative "shared_broker/cipher"
+require_relative "shared_broker/middleware_pipeline"
+require_relative "shared_broker/middlewares/open_telemetry_propagation"
+require_relative "shared_broker/adapters/base"
+require_relative "shared_broker/adapters/in_memory"
+require_relative "shared_broker/adapters/rabbit_mq"
+require_relative "shared_broker/adapters/kafka"
+require_relative "shared_broker/adapters/redis"
+
+module SharedBroker
+  class << self
+    attr_accessor :encryption_key
+  end
+
+  # Default key for development/test if not set
+  @encryption_key = ENV.fetch("SHARED_BROKER_ENCRYPTION_KEY") { "a" * 32 }
+
+  class Client
+    attr_reader :circuit_breaker, :middleware_pipeline
+
+    def initialize(adapter:, circuit_breaker: nil, middlewares: nil)
+      unless adapter.respond_to?(:publish) && adapter.respond_to?(:subscribe)
+        raise ArgumentError, "Expected adapter to respond to :publish and :subscribe, got #{adapter.class} with value #{adapter.inspect}"
+      end
+
+      @adapter = adapter
+      @circuit_breaker = circuit_breaker || CircuitBreaker.new
+      
+      resolved_middlewares = middlewares || [SharedBroker::Middlewares::OpenTelemetryPropagation.new]
+      @middleware_pipeline = MiddlewarePipeline.new(resolved_middlewares)
+    end
+
+    def publish(topic, message, correlation_id: nil)
+      metadata = { correlation_id: correlation_id, operation: :publish }
+      @middleware_pipeline.execute(topic, message, metadata) do
+        SharedBroker::Validation.validate!(topic, message)
+        encrypted_msg = SharedBroker::Cipher.encrypt(message, SharedBroker.encryption_key)
+
+        @circuit_breaker.run do
+          @adapter.publish(topic, encrypted_msg, correlation_id: correlation_id)
+        end
+      end
+    end
+
+    def subscribe(topic, queue_name, max_retries: 3, backoff_base: 2, &block)
+      @adapter.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)
+
+        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
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shared_broker
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
-- Gemini Antigravity
+- Wesley Lima
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-06 00:00:00.000000000 Z
+date: 2026-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -125,11 +125,12 @@ dependencies:
 description: Shared library for asynchronous messaging, distributed tracing, and customizable
   adapters.
 email:
-- antigravity@google.com
+- wesleyskap@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - README.md
 - Rakefile
 - lib/shared_broker.rb
@@ -140,6 +141,8 @@ files:
 - lib/shared_broker/adapters/redis.rb
 - lib/shared_broker/cipher.rb
 - lib/shared_broker/circuit_breaker.rb
+- lib/shared_broker/middleware_pipeline.rb
+- lib/shared_broker/middlewares/open_telemetry_propagation.rb
 - lib/shared_broker/telemetry.rb
 - lib/shared_broker/validation.rb
 - lib/shared_broker/version.rb
@@ -149,7 +152,7 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/wesleyskap/shared_broker
-  changelog_uri: https://github.com/wesleyskap/shared_broker/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/wesleyskap/shared_broker/blob/master/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: