shared_broker 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bd8ee9106eaae6c3d6dc646f85ba199a94788dc05d4f295401867af33067f1e
-  data.tar.gz: 53f5375846be98871776de4756caad2143ca9c3732cf5b012df0bdeaabea840a
+  metadata.gz: 545d29807ba6d68209d43f93f98b81b0e30532efe6d799d5df4f59650e8c44f8
+  data.tar.gz: 5eb9ac3cf999257d3c9f94db10140aee626ed42c1658dd727ca4e2b05f25eee9
 SHA512:
-  metadata.gz: 20296dd5d51625729e336b9bbb8e224ba9e4964cd6d4b2a5561c250f4e72f7329760de8d53c91809d3be1bb779bc516d773d3a4158c7e0d605d3c93385cf16a0
-  data.tar.gz: 630b5a633699b1fc8ff6707ca9e8ce61dbad0004a6d0cd2e0dc98f5c223a29de75e609c9012e2d5b43c50262da5c48e8f4919ab0345e11e2a0e15db458e5d8a2
+  metadata.gz: 64d138f86ba1e88e86b2a65224df35946972843c928a73531b92b00e21bda3ab102a45b32e51db09a5c1f1d1ef7a6b9983e04978c5597408f74537ce01cbec1d
+  data.tar.gz: 7239a6c03ae9b78a8682e579a7d6becdd3c3edc782f8df587d13440d26f3f96e3695c96768890cb110372c3e6819f81bbd40ea90f628c21d03427743275dabb3

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# 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.1.0] - Unreleased
+
+### Added
+- Phase 4: Pipeline of customizable Middlewares (Interceptors) for publishing and subscribing messages.
+- Phase 4: Distributed Tracing using W3C Trace Context (`traceparent`/`tracestate`) injection and extraction.
+
+## [1.0.0] - 2026-06-06
+
+### Added
+- Phase 1: 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.
+- Phase 2: 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`.
+- Phase 3: Scalable Adapters:
+  - Apache Kafka adapter (`SharedBroker::Adapters::Kafka`) with dynamic dependency loading.
+  - Redis Pub/Sub adapter (`SharedBroker::Adapters::Redis`) with list-based DLQ routing.
+- 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 (Advanced Features)
+
+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/adapters/redis.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require "json"
+require "time"
+
+module SharedBroker
+  module Adapters
+    class Redis < Base
+      def initialize(redis_url:)
+        begin
+          require "redis"
+        rescue LoadError
+          raise unless defined?(::Redis)
+        end
+        @redis = ::Redis.new(url: redis_url)
+      end
+
+      def publish(topic, message, correlation_id: nil)
+        unless message.is_a?(Hash)
+          raise ArgumentError, "Expected message to be a Hash, got #{message.class} with value #{message.inspect}"
+        end
+
+        payload = message.merge(_correlation_id: correlation_id)
+        @redis.publish(topic, payload.to_json)
+      end
+
+      def subscribe(topic, queue_name, max_retries: 3, backoff_base: 2, &block)
+        Thread.new do
+          @redis.subscribe(topic) do |on|
+            on.message do |_channel, msg_json|
+              data = JSON.parse(msg_json, symbolize_names: true)
+              attempts = 0
+              begin
+                block.call(data)
+              rescue => e
+                attempts += 1
+                if attempts <= max_retries
+                  sleep(backoff_base**attempts)
+                  retry
+                else
+                  publish_to_dlq(topic, queue_name, msg_json, e)
+                end
+              end
+            end
+          end
+        end
+      end
+
+      private
+
+      def publish_to_dlq(topic, queue_name, payload_json, exception)
+        dlq_key = "dlq:#{topic}:#{queue_name}"
+        dlq_payload = {
+          payload: JSON.parse(payload_json, symbolize_names: true),
+          x_failed_at: Time.now.utc.iso8601,
+          x_exception_class: exception.class.name,
+          x_exception_message: exception.message
+        }
+        @redis.rpush(dlq_key, dlq_payload.to_json)
+      end
+    end
+  end
+end

data/lib/shared_broker/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shared_broker
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Gemini Antigravity
@@ -130,6 +130,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - README.md
 - Rakefile
 - lib/shared_broker.rb
@@ -137,18 +138,19 @@ files:
 - lib/shared_broker/adapters/in_memory.rb
 - lib/shared_broker/adapters/kafka.rb
 - lib/shared_broker/adapters/rabbit_mq.rb
+- lib/shared_broker/adapters/redis.rb
 - lib/shared_broker/cipher.rb
 - lib/shared_broker/circuit_breaker.rb
 - lib/shared_broker/telemetry.rb
 - lib/shared_broker/validation.rb
 - lib/shared_broker/version.rb
 - sig/shared_broker.rbs
-homepage: https://github.com/onkai/shared_broker
+homepage: https://github.com/wesleyskap/shared_broker
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/onkai/shared_broker
-  changelog_uri: https://github.com/onkai/shared_broker/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/wesleyskap/shared_broker
+  changelog_uri: https://github.com/wesleyskap/shared_broker/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: