solid_mcp 0.5.0-x86_64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cf672c564312b8d0c7c66441e9658f760789084b3aa691b780750ee397f54b30
+  data.tar.gz: 367a24bf22aba2d57979f45c1fc2dd781972d2dc935f5b3580d36d19e6626e32
+SHA512:
+  metadata.gz: 35b523facc31c635babc42176eed6eee47db6d1d0bd58612c2f29e14bf1ca8de62af33560c2af50a7bf68e0a693704f071bd4bb65069cadace6f56a5f5ce2018
+  data.tar.gz: aa9db45969ac26e74d7e43afa356e72e62d79093b032e2f017f47bb4d034350d8564056be8530c3209c148dc166bcbba0d38273b0df25465d199994dd33eb6fc

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,328 @@
+# SolidMCP
+
+SolidMCP is a high-performance, database-backed pub/sub engine specifically designed for ActionMCP (Model Context Protocol for Rails). It provides reliable message delivery for MCP's Server-Sent Events (SSE) with support for SQLite, PostgreSQL, and MySQL.
+
+## Features
+
+- **Database-agnostic**: Works with SQLite, PostgreSQL, and MySQL
+- **Session-based routing**: Optimized for MCP's point-to-point messaging pattern
+- **Batched writes**: Handles SQLite's single-writer limitation efficiently
+- **Automatic cleanup**: Configurable retention periods for delivered/undelivered messages
+- **Thread-safe**: Dedicated writer thread with in-memory queuing
+- **SSE resumability**: Supports reconnection with last-event-id
+- **Rails Engine**: Seamless integration with Rails applications
+- **Multiple backends**: Database backend by default, Redis backend coming soon
+
+## Requirements
+
+- Ruby 3.0+
+- Rails 8.0+
+- ActiveRecord 8.0+
+- SQLite, PostgreSQL, or MySQL database
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'solid_mcp'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Run the installation generator:
+
+```bash
+bin/rails generate solid_mcp:install
+bin/rails db:migrate
+```
+
+This will:
+- Create a migration for the `solid_mcp_messages` table
+- Create an initializer with default configuration
+
+## Configuration
+
+Configure SolidMCP in your Rails application:
+
+```ruby
+# config/initializers/solid_mcp.rb
+SolidMcp.configure do |config|
+  # Number of messages to write in a single batch
+  config.batch_size = 200
+  
+  # Seconds between batch flushes
+  config.flush_interval = 0.05
+  
+  # Polling interval for checking new messages
+  config.polling_interval = 0.1
+  
+  # Maximum time to wait for messages before timeout
+  config.max_wait_time = 30
+  
+  # How long to keep delivered messages
+  config.delivered_retention = 1.hour
+  
+  # How long to keep undelivered messages
+  config.undelivered_retention = 24.hours
+end
+```
+
+## Usage with ActionMCP
+
+In your `config/mcp.yml`:
+
+```yaml
+production:
+  adapter: solid_mcp
+  polling_interval: 0.5.seconds
+  batch_size: 200
+  flush_interval: 0.05
+```
+
+## Architecture
+
+SolidMCP is implemented as a Rails Engine with the following components:
+
+### Core Components
+
+1. **SolidMCP::MessageWriter**: Singleton that handles batched writes to the database
+   - Non-blocking enqueue operation
+   - Dedicated writer thread per Rails process
+   - Automatic batching and flushing
+   - Graceful shutdown with pending message delivery
+
+2. **SolidMCP::PubSub**: Main interface for publishing and subscribing to messages
+   - Session-based subscriptions (not channel-based)
+   - Automatic listener management per session
+   - Thread-safe operations
+
+3. **SolidMCP::Subscriber**: Handles polling for new messages
+   - Efficient database queries using indexes
+   - Automatic message delivery tracking
+   - Configurable polling intervals
+
+4. **SolidMCP::Message**: ActiveRecord model for message storage
+   - Optimized indexes for polling and cleanup
+   - Scopes for message filtering
+   - Built-in cleanup methods
+
+### Message Flow
+
+1. Publisher calls `broadcast(session_id, event_type, data)`
+2. MessageWriter queues the message in memory
+3. Writer thread batches messages and writes to database
+4. Subscriber polls for new messages for its session
+5. Messages are marked as delivered after successful processing
+
+## Database Schema
+
+The gem creates a `solid_mcp_messages` table:
+
+```ruby
+create_table :solid_mcp_messages do |t|
+  t.string :session_id, null: false, limit: 36      # MCP session identifier
+  t.string :event_type, null: false, limit: 50      # SSE event type
+  t.text :data                                       # Message payload (usually JSON)
+  t.datetime :created_at, null: false                # Message creation time
+  t.datetime :delivered_at                           # Delivery timestamp
+  
+  t.index [:session_id, :id], name: 'idx_solid_mcp_messages_on_session_and_id'
+  t.index [:delivered_at, :created_at], name: 'idx_solid_mcp_messages_on_delivered_and_created'
+end
+```
+
+## Performance Considerations
+
+### SQLite
+- Single writer thread prevents "database is locked" errors
+- Batching reduces write frequency
+- Consider WAL mode for better concurrency
+
+### PostgreSQL/MySQL
+- Benefits from batching to reduce transaction overhead
+- Can handle multiple writers but single writer is maintained for consistency
+- Consider partitioning for high-volume applications
+
+## Maintenance
+
+### Automatic Cleanup
+
+Old messages are automatically cleaned up based on retention settings:
+
+```ruby
+# Run periodically (e.g., with whenever gem or solid_queue)
+SolidMCP::CleanupJob.perform_later
+
+# Or directly:
+SolidMCP::Message.cleanup
+```
+
+### Manual Cleanup
+
+```ruby
+# Clean up delivered messages older than 1 hour
+SolidMCP::Message.old_delivered(1.hour).delete_all
+
+# Clean up undelivered messages older than 24 hours
+SolidMCP::Message.old_undelivered(24.hours).delete_all
+```
+
+### Monitoring
+
+```ruby
+# Check message queue size
+SolidMCP::Message.undelivered.count
+
+# Check messages for a specific session
+SolidMCP::Message.for_session(session_id).count
+
+# Find stuck messages
+SolidMCP::Message.undelivered.where('created_at < ?', 1.hour.ago)
+```
+
+## Testing
+
+The gem includes a test implementation for use in test environments:
+
+```ruby
+# In test environment, SolidMCP::PubSub automatically uses TestPubSub
+# which provides immediate delivery without database persistence
+```
+
+Run the test suite:
+
+```bash
+bundle exec rake test
+```
+
+### Testing in Your Application
+
+```ruby
+# test/test_helper.rb
+class ActiveSupport::TestCase
+  setup do
+    SolidMCP::Message.delete_all
+  end
+end
+
+# In your tests
+test "broadcasts message to session" do
+  pubsub = SolidMCP::PubSub.new
+  messages = []
+  
+  pubsub.subscribe("test-session") do |msg|
+    messages << msg
+  end
+  
+  pubsub.broadcast("test-session", "test_event", { data: "test" })
+  
+  assert_equal 1, messages.size
+  assert_equal "test_event", messages.first[:event_type]
+end
+```
+
+## SSE Integration
+
+SolidMCP is designed to work seamlessly with Server-Sent Events:
+
+```ruby
+# In your SSE controller
+def sse_endpoint
+  response.headers['Content-Type'] = 'text/event-stream'
+  
+  pubsub = SolidMCP::PubSub.new
+  last_event_id = request.headers['Last-Event-ID']
+  
+  # Resume from last event if reconnecting
+  if last_event_id
+    missed_messages = SolidMCP::Message
+      .for_session(session_id)
+      .after_id(last_event_id)
+      .undelivered
+    
+    missed_messages.each do |msg|
+      response.stream.write "id: #{msg.id}\n"
+      response.stream.write "event: #{msg.event_type}\n"
+      response.stream.write "data: #{msg.data}\n\n"
+    end
+  end
+  
+  # Subscribe to new messages
+  pubsub.subscribe(session_id) do |message|
+    response.stream.write "id: #{message[:id]}\n"
+    response.stream.write "event: #{message[:event_type]}\n"
+    response.stream.write "data: #{message[:data]}\n\n"
+  end
+ensure
+  pubsub&.unsubscribe(session_id)
+  response.stream.close
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run specific test file
+bundle exec ruby test/solid_mcp/message_test.rb
+```
+
+## Roadmap
+
+### Redis Backend (Coming Soon)
+
+Future versions will support Redis as an alternative backend:
+
+```ruby
+# config/initializers/solid_mcp.rb
+SolidMCP.configure do |config|
+  config.backend = :redis
+  config.redis_url = ENV['REDIS_URL']
+end
+```
+
+This will provide:
+- Lower latency for high-traffic applications
+- Pub/Sub without polling
+- Automatic expiration of old messages
+- Better horizontal scaling
+
+## Comparison with Other Solutions
+
+| Feature | SolidMCP | ActionCable + Redis | Custom Polling |
+|---------|----------|-------------------|----------------|
+| No Redis Required | ✅ | ❌ | ✅ |
+| SSE Resumability | ✅ | ❌ | Manual |
+| Horizontal Scaling | ✅ (with DB) | ✅ | ❌ |
+| Message Persistence | ✅ | ❌ | Manual |
+| Batch Writing | ✅ | N/A | ❌ |
+| SQLite Support | ✅ | ❌ | ✅ |
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/seuros/solid_mcp.
+
+### Development Setup
+
+1. Fork the repository
+2. Clone your fork
+3. Install dependencies: `bundle install`
+4. Create a feature branch: `git checkout -b my-feature`
+5. Make your changes and add tests
+6. Run tests: `bundle exec rake test`
+7. Push to your fork and submit a pull request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/ext/solid_mcp_native/extconf.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ffi/extconf'

data/lib/generators/solid_mcp/install/install_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module SolidMCP
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      namespace "solid_mcp:install"
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def create_migration_file
+        migration_template "create_solid_mcp_messages.rb.erb", "db/migrate/create_solid_mcp_messages.rb"
+      end
+
+      def add_initializer
+        template "solid_mcp.rb", "config/initializers/solid_mcp.rb"
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/solid_mcp/install/templates/create_solid_mcp_messages.rb.erb

@@ -0,0 +1,26 @@
+class CreateSolidMCPMessages < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :solid_mcp_messages do |t|
+      # Session this message belongs to
+      t.string :session_id, null: false, limit: 36
+      
+      # Type of event (e.g., 'message', 'ping', 'connection_closed')
+      t.string :event_type, null: false, limit: 50
+      
+      # The actual data payload
+      t.text :data
+      
+      # Timestamp when message was created
+      t.datetime :created_at, null: false
+      
+      # Timestamp when message was delivered
+      t.datetime :delivered_at
+      
+      # Composite index for efficient polling
+      t.index [:session_id, :id], name: 'idx_solid_mcp_messages_on_session_and_id'
+      
+      # Index for cleanup
+      t.index [:delivered_at, :created_at], name: 'idx_solid_mcp_messages_on_delivered_and_created'
+    end
+  end
+end

data/lib/generators/solid_mcp/install/templates/solid_mcp.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Initialize SolidMCP message writer
+Rails.application.config.to_prepare do
+  # Ensure the writer thread is started
+  SolidMCP::MessageWriter.instance
+end
+
+# Gracefully shutdown on exit
+at_exit do
+  SolidMCP::MessageWriter.instance.shutdown if defined?(SolidMCP::MessageWriter)
+end
+
+# Configure SolidMCP
+SolidMCP.configure do |config|
+  config.batch_size = 200
+  config.flush_interval = 0.05
+  config.delivered_retention = 1.hour
+  config.undelivered_retention = 24.hours
+end

data/lib/solid_mcp/cleanup_job.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SolidMCP
+  class CleanupJob < ActiveJob::Base
+    def perform
+      SolidMCP::Message.cleanup(
+        delivered_retention: SolidMCP.configuration.delivered_retention_seconds,
+        undelivered_retention: SolidMCP.configuration.undelivered_retention_seconds
+      )
+    end
+  end
+end

data/lib/solid_mcp/configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module SolidMCP
+  class Configuration
+    attr_accessor :batch_size, :flush_interval, :delivered_retention,
+                  :undelivered_retention, :polling_interval, :max_wait_time, :logger,
+                  :max_queue_size, :shutdown_timeout
+
+    def initialize
+      @batch_size = 200
+      @flush_interval = 0.05 # 50ms
+      @polling_interval = 0.1 # 100ms
+      @max_wait_time = 30 # 30 seconds
+      @delivered_retention = 3600 # 1 hour in seconds
+      @undelivered_retention = 86400 # 24 hours in seconds
+      @max_queue_size = 10_000 # Maximum messages in memory queue
+      @shutdown_timeout = 30 # Maximum seconds to wait for graceful shutdown
+      @logger = default_logger
+    end
+
+    def delivered_retention_seconds
+      @delivered_retention.seconds
+    end
+
+    def undelivered_retention_seconds
+      @undelivered_retention.seconds
+    end
+
+    private
+
+    def default_logger
+      if defined?(Rails) && Rails.respond_to?(:logger)
+        Rails.logger
+      else
+        require 'active_support/tagged_logging'
+        ActiveSupport::TaggedLogging.new(::Logger.new($stdout))
+      end
+    end
+  end
+end

data/lib/solid_mcp/engine.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SolidMCP
+  class Engine < ::Rails::Engine
+    isolate_namespace SolidMCP
+
+    config.generators do |g|
+      g.test_framework :minitest
+    end
+
+    # Ensure app/models is in the autoload paths
+    config.autoload_paths << root.join("app/models")
+
+    # Don't automatically add migrations - use the generator instead
+    # initializer "solid_mcp.migrations" do
+    #   config.paths["db/migrate"].expanded.each do |expanded_path|
+    #     Rails.application.config.paths["db/migrate"] << expanded_path
+    #   end
+    # end
+
+    initializer "solid_mcp.configuration" do
+      # Set default configuration if not already configured
+      SolidMCP.configuration ||= Configuration.new
+    end
+
+    initializer "solid_mcp.start_message_writer" do
+      # Start the message writer in non-test environments
+      unless Rails.env.test?
+        Rails.application.config.to_prepare do
+          SolidMCP::MessageWriter.instance
+        end
+      end
+    end
+  end
+end

data/lib/solid_mcp/logger.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SolidMCP
+  module Logger
+    class << self
+      def logger
+        SolidMCP.configuration.logger
+      end
+
+      def tagged(*tags, &block)
+        logger.tagged(*tags, &block)
+      end
+
+      def debug(message = nil, &block)
+        logger.debug(message, &block)
+      end
+
+      def info(message = nil, &block)
+        logger.info(message, &block)
+      end
+
+      def warn(message = nil, &block)
+        logger.warn(message, &block)
+      end
+
+      def error(message = nil, &block)
+        logger.error(message, &block)
+      end
+
+      def fatal(message = nil, &block)
+        logger.fatal(message, &block)
+      end
+    end
+  end
+end

data/lib/solid_mcp/message_writer.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "concurrent"
+
+module SolidMCP
+  class MessageWriter
+    include Singleton
+
+    # Reset the singleton (for testing only)
+    def self.reset!
+      @singleton__instance__ = nil
+    end
+
+    def initialize
+      @queue = SizedQueue.new(SolidMCP.configuration.max_queue_size)
+      @shutdown = Concurrent::AtomicBoolean.new(false)
+      @dropped_count = Concurrent::AtomicFixnum.new(0)
+      @worker_ready = Concurrent::CountDownLatch.new(1)
+      @executor = Concurrent::ThreadPoolExecutor.new(
+        min_threads: 1,
+        max_threads: 1,  # Single thread for ordered writes
+        max_queue: 0,    # Unbounded queue
+        fallback_policy: :caller_runs
+      )
+      start_worker
+      # Wait for worker thread to be ready (with short timeout)
+      # Using 0.1s is enough for worker to start, avoids 1s delay per test
+      @worker_ready.wait(0.1)
+    end
+
+    # Called by publish API - non-blocking with backpressure
+    def enqueue(session_id, event_type, data)
+      message = {
+        session_id: session_id,
+        event_type: event_type,
+        data: data.is_a?(String) ? data : data.to_json,
+        created_at: Time.now.utc
+      }
+
+      # Try non-blocking push with backpressure
+      begin
+        @queue.push(message, true) # non-blocking
+        true
+      rescue ThreadError
+        # Queue full - drop message and log
+        @dropped_count.increment
+        SolidMCP::Logger.warn "SolidMCP queue full (#{SolidMCP.configuration.max_queue_size}), dropped message for session #{session_id}"
+        false
+      end
+    end
+
+    # Get count of dropped messages
+    def dropped_count
+      @dropped_count.value
+    end
+
+    # Blocks until executor has flushed everything
+    def shutdown
+      SolidMCP::Logger.info "SolidMCP::MessageWriter shutting down, #{@queue.size} messages pending"
+
+      # Mark as shutting down (worker will exit after draining queue)
+      @shutdown.make_true
+
+      # Wait for executor to finish processing
+      @executor.shutdown
+      @executor.wait_for_termination(SolidMCP.configuration.shutdown_timeout)
+
+      if @queue.size > 0
+        SolidMCP::Logger.warn "SolidMCP::MessageWriter shutdown timeout, #{@queue.size} messages not written"
+      end
+    end
+
+    # Force flush any pending messages (useful for tests)
+    def flush
+      return unless @executor.running?
+
+      # Add a marker and wait for it to be processed
+      processed = Concurrent::CountDownLatch.new(1)
+
+      # Use blocking push for flush marker (not subject to queue limits)
+      begin
+        @queue.push({ flush_marker: processed }, false) # blocking
+      rescue ThreadError
+        # Queue is shutting down
+        return
+      end
+
+      # Wait up to 1 second for flush to complete
+      processed.wait(1)
+    end
+
+    private
+
+    def start_worker
+      @executor.post do
+        begin
+          SolidMCP::Logger.debug "MessageWriter worker thread started" if ENV["DEBUG_SOLID_MCP"]
+          run_loop
+        rescue => e
+          SolidMCP::Logger.error "MessageWriter worker thread crashed: #{e.message}"
+          SolidMCP::Logger.error e.backtrace.join("\n")
+        end
+      end
+    end
+
+    def run_loop
+      # Signal that worker is ready
+      @worker_ready.count_down
+
+      loop do
+        break if @shutdown.true? && @queue.empty?
+
+        batch = drain_batch
+        if batch.any?
+          SolidMCP::Logger.debug "MessageWriter processing batch of #{batch.size} messages" if ENV["DEBUG_SOLID_MCP"]
+          write_batch(batch)
+        end
+      end
+    rescue => e
+      SolidMCP::Logger.error "SolidMCP::MessageWriter error: #{e.message}"
+      retry unless @shutdown.true?
+    end
+
+    def drain_batch
+      batch = []
+      batch_size = SolidMCP.configuration.batch_size
+      flush_markers = []
+
+      # Get first item - use blocking pop with timeout to avoid busy spin
+      item = nil
+      until @shutdown.true? && @queue.empty?
+        begin
+          # Blocking pop with timeout allows clean shutdown checking
+          item = @queue.pop(timeout: 0.1)
+          break if item
+        rescue ThreadError
+          # Queue closed, exit
+          break
+        end
+      end
+
+      return batch unless item
+
+      # Handle flush markers
+      if item.is_a?(Hash) && item[:flush_marker]
+        flush_markers << item[:flush_marker]
+      else
+        batch << item
+      end
+
+      # Get remaining items up to batch size (non-blocking)
+      while batch.size < batch_size
+        begin
+          item = @queue.pop(true) # non-blocking
+          # Handle flush markers
+          if item.is_a?(Hash) && item[:flush_marker]
+            flush_markers << item[:flush_marker]
+          else
+            batch << item
+          end
+        rescue ThreadError
+          break
+        end
+      end
+
+      # Signal any flush markers we've collected
+      flush_markers.each(&:count_down)
+      batch
+    end
+
+    def write_batch(batch)
+      return if batch.empty?
+
+      # Use ActiveRecord insert_all for safety and database portability
+      records = batch.map do |msg|
+        {
+          session_id: msg[:session_id],
+          event_type: msg[:event_type],
+          data: msg[:data],
+          created_at: msg[:created_at]
+        }
+      end
+
+      SolidMCP::Message.insert_all(records)
+    rescue => e
+      SolidMCP::Logger.error "SolidMCP::MessageWriter batch write error: #{e.message}"
+      # Could implement retry logic or dead letter queue here
+    end
+  end
+end

data/lib/solid_mcp/native_speedup.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+# Native Rust acceleration for SolidMCP (optional)
+#
+# This module provides a Rust-powered pub/sub engine using Tokio for async I/O.
+# Falls back gracefully to pure Ruby if the native extension is unavailable.
+#
+# Features:
+# - 50-100x faster message throughput
+# - PostgreSQL LISTEN/NOTIFY support (no polling)
+# - SQLite WAL mode with efficient async polling
+# - Compile-time thread safety guarantees
+
+module SolidMCP
+  module NativeSpeedup
+    class << self
+      def available?
+        @available ||= load_native_extension
+      end
+
+      def version
+        return nil unless available?
+        SolidMCPNative.version
+      end
+
+      private
+
+      def load_native_extension
+        return false if ENV["DISABLE_SOLID_MCP_NATIVE"]
+
+        begin
+          require "solid_mcp_native/solid_mcp_native"
+          log_info "SolidMCP native extension loaded (v#{SolidMCPNative.version})"
+          true
+        rescue LoadError => e
+          log_debug "SolidMCP native extension not available: #{e.message}"
+          false
+        end
+      end
+
+      def log_info(msg)
+        SolidMCP::Logger.info(msg)
+      rescue StandardError
+        # Logger not ready, silently ignore
+      end
+
+      def log_debug(msg)
+        SolidMCP::Logger.debug(msg)
+      rescue StandardError
+        # Logger not ready, silently ignore
+      end
+    end
+
+    # Override MessageWriter with native implementation
+    module MessageWriterOverride
+      def self.prepended(base)
+        # Only prepend if native extension is available
+        return unless SolidMCP::NativeSpeedup.available?
+
+        SolidMCP::Logger.debug "Enabling native MessageWriter"
+      end
+
+      def initialize
+        if SolidMCP::NativeSpeedup.available? && !@native_initialized
+          # Initialize native engine with SQLite/PostgreSQL URL
+          db_config = SolidMCP.configuration.database_config
+          database_url = build_database_url(db_config)
+
+          SolidMCPNative.init_with_config(
+            database_url,
+            SolidMCP.configuration.batch_size,
+            (SolidMCP.configuration.polling_interval * 1000).to_i, # Convert to ms
+            SolidMCP.configuration.max_queue_size
+          )
+          @native_initialized = true
+        else
+          super
+        end
+      end
+
+      def enqueue(session_id, event_type, data)
+        if SolidMCP::NativeSpeedup.available? && @native_initialized
+          json_data = data.is_a?(String) ? data : data.to_json
+          SolidMCPNative.broadcast(session_id.to_s, event_type.to_s, json_data)
+        else
+          super
+        end
+      end
+
+      def flush
+        if SolidMCP::NativeSpeedup.available? && @native_initialized
+          SolidMCPNative.flush
+        else
+          super
+        end
+      end
+
+      def shutdown
+        if SolidMCP::NativeSpeedup.available? && @native_initialized
+          SolidMCPNative.shutdown
+          @native_initialized = false
+        else
+          super
+        end
+      end
+
+      private
+
+      def build_database_url(config)
+        adapter = config[:adapter] || "sqlite3"
+
+        case adapter
+        when "sqlite3"
+          # SQLite URL format
+          database = config[:database] || ":memory:"
+          "sqlite://#{database}"
+        when "postgresql", "postgres"
+          # PostgreSQL URL format
+          host = config[:host] || "localhost"
+          port = config[:port] || 5432
+          database = config[:database] || "solid_mcp"
+          username = config[:username]
+          password = config[:password]
+
+          auth = username ? "#{username}:#{password}@" : ""
+          "postgres://#{auth}#{host}:#{port}/#{database}"
+        else
+          raise SolidMCP::Error, "Unsupported database adapter: #{adapter}"
+        end
+      end
+    end
+  end
+end
+
+# Auto-load native extension on require (if available)
+if SolidMCP::NativeSpeedup.available?
+  # MessageWriter.prepend(SolidMCP::NativeSpeedup::MessageWriterOverride)
+  # Note: Uncommenting this line enables automatic native acceleration
+  # For now, keep it opt-in until the Rust code is battle-tested
+end

data/lib/solid_mcp/pub_sub.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+require "concurrent/array"
+
+module SolidMCP
+  class PubSub
+    def initialize(options = {})
+      @options = options
+      @subscriptions = Concurrent::Map.new
+      @listeners = Concurrent::Map.new
+    end
+
+    # Subscribe to messages for a specific session
+    def subscribe(session_id, &block)
+      # Atomically get or create callbacks array
+      callbacks = @subscriptions.compute_if_absent(session_id) { Concurrent::Array.new }
+      callbacks << block
+
+      # Start a listener for this session if not already running
+      ensure_listener_for(session_id)
+    end
+
+    # Unsubscribe from a session
+    def unsubscribe(session_id)
+      @subscriptions.delete(session_id)
+      stop_listener_for(session_id)
+    end
+
+    # Broadcast a message to a session (uses MessageWriter for batching)
+    def broadcast(session_id, event_type, data)
+      MessageWriter.instance.enqueue(session_id, event_type, data)
+    end
+
+    # Shutdown all listeners
+    def shutdown
+      @listeners.each do |_, listener|
+        listener.stop
+      end
+      @listeners.clear
+      MessageWriter.instance.shutdown
+    end
+
+    private
+
+    def ensure_listener_for(session_id)
+      # Atomically create and start listener only once
+      @listeners.compute_if_absent(session_id) do
+        listener = Subscriber.new(session_id, @subscriptions[session_id])
+        listener.start
+        listener
+      end
+    end
+
+    def stop_listener_for(session_id)
+      listener = @listeners.delete(session_id)
+      listener&.stop
+    end
+  end # class PubSub
+end

data/lib/solid_mcp/subscriber.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "concurrent/atomic/atomic_boolean"
+require "concurrent/atomic/atomic_reference"
+require "concurrent/timer_task"
+
+module SolidMCP
+  class Subscriber
+    def initialize(session_id, callbacks)
+      @session_id = session_id
+      @callbacks = callbacks
+      @running = Concurrent::AtomicBoolean.new(false)
+      @last_message_id = Concurrent::AtomicReference.new(0)
+      @timer_task = nil
+      @max_retries = ENV["RAILS_ENV"] == "test" ? 3 : Float::INFINITY
+      @retry_count = 0
+    end
+
+    def start
+      return if @running.true?
+
+      @running.make_true
+      @retry_count = 0
+
+      @timer_task = Concurrent::TimerTask.new(
+        execution_interval: SolidMCP.configuration.polling_interval,
+        run_now: true
+      ) do
+        poll_once
+      end
+
+      @timer_task.execute
+    end
+
+    def stop
+      @running.make_false
+      @timer_task&.shutdown
+      @timer_task&.wait_for_termination(5)
+    end
+
+    private
+
+    def poll_once
+      return unless @running.true?
+
+      # Ensure connection in thread
+      SolidMCP::Message.connection_pool.with_connection do
+        messages = fetch_new_messages
+        if messages.any?
+          process_messages(messages)
+          mark_delivered(messages)
+          @retry_count = 0
+        end
+      end
+    rescue => e
+      @retry_count += 1
+      SolidMCP::Logger.error "SolidMCP::Subscriber error for session #{@session_id}: #{e.message} (retry #{@retry_count}/#{@max_retries})"
+
+      if @retry_count >= @max_retries && @max_retries != Float::INFINITY
+        SolidMCP::Logger.error "SolidMCP::Subscriber max retries reached for session #{@session_id}, stopping"
+        stop
+      end
+    end
+
+    def fetch_new_messages
+      SolidMCP::Message
+        .for_session(@session_id)
+        .undelivered
+        .after_id(@last_message_id.get)
+        .order(:id)
+        .limit(100)
+        .to_a
+    end
+
+    def process_messages(messages)
+      messages.each do |message|
+        # Process all callbacks first
+        all_successful = true
+        @callbacks.each do |callback|
+          begin
+            callback.call({
+              event_type: message.event_type,
+              data: message.data,  # data is already a JSON string from the database
+              id: message.id
+            })
+          rescue => e
+            all_successful = false
+            SolidMCP::Logger.error "SolidMCP callback error: #{e.message}"
+          end
+        end
+
+        # Only update last_message_id if all callbacks succeeded
+        if all_successful
+          @last_message_id.set(message.id)
+        else
+          # Stop processing remaining messages on first callback failure
+          break
+        end
+      end
+    end
+
+    def mark_delivered(messages)
+      SolidMCP::Message.mark_delivered(messages.map(&:id))
+    end
+  end
+end

data/lib/solid_mcp/test_pub_sub.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+require "concurrent/array"
+
+module SolidMCP
+  # Test implementation of PubSub for use in tests
+  class TestPubSub
+    attr_reader :subscriptions, :messages
+
+    def initialize(options = {})
+      @options = options
+      @subscriptions = Concurrent::Map.new
+      @messages = Concurrent::Array.new
+    end
+
+    def subscribe(session_id, &block)
+      @subscriptions[session_id] ||= Concurrent::Array.new
+      @subscriptions[session_id] << block
+    end
+
+    def unsubscribe(session_id)
+      @subscriptions.delete(session_id)
+    end
+
+    def broadcast(session_id, event_type, data)
+      message = { session_id: session_id, event_type: event_type, data: data }
+      @messages << message
+      
+      callbacks = @subscriptions[session_id] || []
+      callbacks.each do |callback|
+        callback.call({ event_type: event_type, data: data })
+      end
+    end
+
+    def shutdown
+      @subscriptions.clear
+      @messages.clear
+    end
+  end
+end

data/lib/solid_mcp/version.rb

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

data/lib/solid_mcp.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "solid_mcp/version"
+require_relative "solid_mcp/configuration"
+require_relative "solid_mcp/logger"
+require_relative "solid_mcp/engine" if defined?(Rails)
+
+# Always load core components
+require_relative "solid_mcp/message_writer"
+require_relative "solid_mcp/subscriber"
+require_relative "solid_mcp/cleanup_job"
+
+# Load test components in test environment
+if ENV["RAILS_ENV"] == "test"
+  require_relative "solid_mcp/test_pub_sub"
+end
+
+# Always require pub_sub after environment-specific components
+require_relative "solid_mcp/pub_sub"
+
+module SolidMCP
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+    end
+
+    def configured?
+      configuration.present?
+    end
+  end
+
+  # Initialize with default configuration
+  self.configuration = Configuration.new
+end
+
+# Load native speedup AFTER module is defined (optional - gracefully falls back to pure Ruby)
+require_relative "solid_mcp/native_speedup"

data/sig/solid_mcp.rbs

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

metadata

@@ -0,0 +1,187 @@
+--- !ruby/object:Gem::Specification
+name: solid_mcp
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: x86_64-linux-musl
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-12-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: |
+  SolidMCP implements a high-performance, bidirectional Pub/Sub transport for ActionMCP.
+  Features optional Rust native extension with Tokio for async I/O, PostgreSQL LISTEN/NOTIFY
+  support, and automatic fallback to pure Ruby when native extension is unavailable.
+email:
+- terminale@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- ext/solid_mcp_native/extconf.rb
+- lib/generators/solid_mcp/install/install_generator.rb
+- lib/generators/solid_mcp/install/templates/create_solid_mcp_messages.rb.erb
+- lib/generators/solid_mcp/install/templates/solid_mcp.rb
+- lib/solid_mcp.rb
+- lib/solid_mcp/cleanup_job.rb
+- lib/solid_mcp/configuration.rb
+- lib/solid_mcp/engine.rb
+- lib/solid_mcp/logger.rb
+- lib/solid_mcp/message_writer.rb
+- lib/solid_mcp/native_speedup.rb
+- lib/solid_mcp/pub_sub.rb
+- lib/solid_mcp/subscriber.rb
+- lib/solid_mcp/test_pub_sub.rb
+- lib/solid_mcp/version.rb
+- lib/solid_mcp_native/solid_mcp_native.so
+- sig/solid_mcp.rbs
+homepage: https://github.com/seuros/solid_mcp
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/seuros/solid_mcp
+  source_code_uri: https://github.com/seuros/solid_mcp
+  changelog_uri: https://github.com/seuros/solid_mcp/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/seuros/solid_mcp/issues
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: solid_mcp_native
+  cargo_manifest_path: ext/solid_mcp_native/ffi/Cargo.toml
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.5.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.22
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Streaming Pub/Sub transport for ActionMCP.
+test_files: []