shared_broker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 113868a35ebcb87b89d4ce8b0ba3079276ffdb8a07a519ec5ee5cbb28d605f24
+  data.tar.gz: 5d7cbddbf655269f55bc9b752172de08d52bbcf8d3864ef1164c9458731ae66b
+SHA512:
+  metadata.gz: dd263b0bf50aec4e4ac83e85de4c8fadf8a59bc8ddbcdc4195862bc791aeb2770c866f15cfecec5633313b457897923cc56c2ab990299f95f1fbff03465b9022
+  data.tar.gz: 7693f227da2d82c5389074f4e8375ed011ffe2cd77c7e4517480ec38308500c15ccab679a2a326af31ac3ca08f77cc084b7031ebb3d0e291e18745c9335e97ab

data/README.md

@@ -0,0 +1,102 @@
+# SharedBroker
+
+`SharedBroker` is a high-performance Ruby library designed to simplify event-based communication (asynchronous messaging) and telemetry (observability) in Rails microservice architectures.
+
+The library implements the **Adapter Pattern** to decouple your application from physical queue providers (like RabbitMQ), allowing easy broker swapping and clean synchronous testing with an in-memory adapter.
+
+---
+
+## Key Features
+
+- **Pluggable Messaging**: Adapter pattern to decouple Rails from physical messaging queues.
+- **RabbitMQ Adapter**: Robust, persistent connection wrapper using the `bunny` gem.
+- **InMemory Adapter**: Synchronous local queue simulation for fast TDD testing (no inline external I/O stubs required).
+- **Integrated OpenTelemetry**: Centralized SDK configuration with auto-instrumentation for all supported libraries (ActiveRecord, Bunny, Faraday, Rails, PG, etc.).
+
+---
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem "shared_broker", path: "gems/shared_broker" # for local gem
+# or when published:
+# gem "shared_broker"
+```
+
+And execute:
+
+```bash
+bundle install
+```
+
+---
+
+## Configuration
+
+Create an initializer in your Rails application (`config/initializers/shared_broker.rb`):
+
+```ruby
+require "shared_broker"
+
+# 1. 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
+else
+  # 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
+
+# 2. Instantiate the Client by Injecting the Adapter
+SPOT_BROKER = SharedBroker::Client.new(adapter: BROKER_ADAPTER)
+
+# 3. Initialize Telemetry (OpenTelemetry)
+SharedBroker::Telemetry.configure(service_name: "my_microservice")
+```
+
+---
+
+## Usage
+
+### Publishing Events
+Send simple events by passing the topic name and a structured payload (must be a `Hash`):
+
+```ruby
+event_data = {
+  id: 1,
+  name: "Eiffel Tower",
+  latitude: 48.8584,
+  longitude: 2.2945
+}
+
+SPOT_BROKER.publish("spot.created", event_data)
+```
+
+### Subscribing to Events (Consumer)
+To start a persistent event subscriber daemon, register a queue associated with the topic:
+
+```ruby
+SPOT_BROKER.subscribe("spot.created", "my_consumption_queue") do |payload|
+  puts "Event successfully consumed! ID: #{payload[:id]}"
+  # execute your business logic here...
+end
+```
+
+---
+
+## Running Gem Tests
+
+To run the unit test suite using **Minitest**:
+
+```bash
+bundle exec rake test
+```
+
+---
+
+## License
+
+This Gem is available under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+task default: :test

data/lib/shared_broker/version.rb

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

data/lib/shared_broker.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "shared_broker/version"
+require_relative "shared_broker/telemetry"
+require_relative "shared_broker/adapters/base"
+require_relative "shared_broker/adapters/in_memory"
+require_relative "shared_broker/adapters/rabbit_mq"
+
+module SharedBroker
+  class Client
+    def initialize(adapter:)
+      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
+    end
+
+    def publish(topic, message)
+      @adapter.publish(topic, message)
+    end
+
+    def subscribe(topic, queue_name, &block)
+      @adapter.subscribe(topic, queue_name, &block)
+    end
+  end
+end

data/sig/shared_broker.rbs

@@ -0,0 +1,4 @@
+module SharedBroker
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: shared_broker
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gemini Antigravity
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bunny
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.22'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.22'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-all
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Shared library for asynchronous messaging, distributed tracing, and customizable
+  adapters.
+email:
+- antigravity@google.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/shared_broker.rb
+- lib/shared_broker/version.rb
+- sig/shared_broker.rbs
+homepage: https://github.com/onkai/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
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Pluggable message broker abstraction with RabbitMQ and OpenTelemetry support.
+test_files: []