solid_cable_mongoid_adapter 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 859363aab566363aae944af0dcb524a9d5298cb4e56bf6ded6c2abf8618a568f
+  data.tar.gz: 4cf1bb50558c4e8b1f452b9a604f98d7626fb53c5a814fd1fa540bbdfe78c5f1
+SHA512:
+  metadata.gz: 7cd25df03ed0b311c5cf9c621dfa8cd4db5aed42f9b16971de682aa85a4e2ce29d9f16d6df997a3179e51e82af70cfc40530bf8bcfea2eafe80c8c53bf8ef622
+  data.tar.gz: 7032517c894e1e8f602a602bbae5f90c6f93487593136cc596d36e2e3a42bc769198f0361b70621435c664845a3c93aaf4fe9befb1c1846e97e68f9fc4b92b97

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--color
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,45 @@
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'bin/**/*'
+    - 'tmp/**/*'
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Max: 25
+  Exclude:
+    - 'lib/action_cable/subscription_adapter/solid_mongoid.rb'
+
+Metrics/ClassLength:
+  Max: 250
+
+Metrics/AbcSize:
+  Max: 25
+  Exclude:
+    - 'lib/action_cable/subscription_adapter/solid_mongoid.rb'
+
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'lib/action_cable/subscription_adapter/solid_mongoid.rb'
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'lib/action_cable/subscription_adapter/solid_mongoid.rb'

data/CHANGELOG.md

@@ -0,0 +1,46 @@
+# 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.0.0] - 2025-02-09
+
+### Added
+- Initial release of SolidCableMongoidAdapter
+- MongoDB Change Streams support for real-time message delivery
+- Automatic TTL-based message expiration
+- Replica set requirement validation
+- Exponential backoff for reconnection attempts
+- Resume token support for continuity across reconnections
+- Fallback polling mode for standalone MongoDB
+- Comprehensive logging and error handling
+- Thread-safe listener implementation
+- Rails 7+ and Rails 8+ compatibility
+- Production-grade code quality and documentation
+
+### Features
+- Channel-based subscription management
+- Configurable message expiration (TTL)
+- Configurable reconnection delays with exponential backoff
+- Configurable polling parameters for fallback mode
+- Automatic collection and index creation
+- Fork-safe operation (Passenger, Puma cluster mode)
+
+### Configuration Options
+- `collection_name`: MongoDB collection name
+- `expiration`: Message TTL in seconds
+- `reconnect_delay`: Initial retry delay
+- `max_reconnect_delay`: Maximum retry delay
+- `poll_interval_ms`: Polling interval
+- `poll_batch_limit`: Max messages per poll
+- `require_replica_set`: Enforce replica set requirement
+
+## [Unreleased]
+
+### Planned
+- Performance metrics and monitoring hooks
+- Support for multiple MongoDB databases
+- Message compression options
+- Custom serialization support

data/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing to SolidCableMongoidAdapter
+
+First off, thank you for considering contributing to SolidCableMongoidAdapter!
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check existing issues as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:
+
+* Use a clear and descriptive title
+* Describe the exact steps which reproduce the problem
+* Provide specific examples to demonstrate the steps
+* Describe the behavior you observed after following the steps
+* Explain which behavior you expected to see instead and why
+* Include logs and error messages
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:
+
+* Use a clear and descriptive title
+* Provide a step-by-step description of the suggested enhancement
+* Provide specific examples to demonstrate the steps
+* Describe the current behavior and explain which behavior you expected to see instead
+* Explain why this enhancement would be useful
+
+### Pull Requests
+
+* Fill in the required template
+* Do not include issue numbers in the PR title
+* Follow the Ruby styleguide (RuboCop)
+* Include thoughtfully-worded, well-structured RSpec tests
+* Document new code
+* End all files with a newline
+
+## Development Setup
+
+1. Fork and clone the repository
+2. Install dependencies: `bundle install`
+3. Set up MongoDB replica set (see README)
+4. Run tests: `bundle exec rspec`
+5. Run linter: `bundle exec rubocop`
+
+## Testing
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/adapter_spec.rb
+
+# Run with coverage
+COVERAGE=true bundle exec rspec
+```
+
+## Style Guide
+
+We use RuboCop for code style enforcement. Run `bundle exec rubocop` before committing.
+
+## Commit Messages
+
+* Use the present tense ("Add feature" not "Added feature")
+* Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
+* Limit the first line to 72 characters or less
+* Reference issues and pull requests liberally after the first line
+
+## Release Process
+
+1. Update version in `lib/solid_cable_mongoid_adapter/version.rb`
+2. Update CHANGELOG.md
+3. Commit changes
+4. Create git tag: `git tag v1.0.0`
+5. Push: `git push origin main --tags`
+6. Build gem: `gem build solid_cable_mongoid_adapter.gemspec`
+7. Publish: `gem push solid_cable_mongoid_adapter-1.0.0.gem`
+
+## Questions?
+
+Feel free to open an issue with your question or contact the maintainers directly.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sal Scotto
+
+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,317 @@
+# SolidCableMongoidAdapter
+
+[![CI](https://github.com/washu/solid_cable_mongoid_adapter/actions/workflows/ci.yml/badge.svg)](https://github.com/washu/solid_cable_mongoid_adapter/actions/workflows/ci.yml)
+
+A production-ready Action Cable subscription adapter that uses MongoDB (via Mongoid) as a durable, cross-process broadcast backend with MongoDB Change Streams support.
+
+## Features
+
+- **Durable Message Storage**: Persists broadcasts in MongoDB with automatic expiration via TTL indexes
+- **Real-time Delivery**: Uses MongoDB Change Streams for instant message delivery across processes
+- **High Availability**: Automatic reconnection with exponential backoff
+- **Resume Token Support**: Continuity across reconnections without message loss
+- **Fallback Polling**: Gracefully degrades to polling on standalone MongoDB (not recommended for production)
+- **Thread-Safe**: Dedicated listener thread per server process
+- **Rails 7+ & 8+ Compatible**: Works with modern Rails applications
+
+## Requirements
+
+- **Ruby**: 2.7 or higher
+- **Rails**: 7.0 or higher (supports Rails 8+)
+- **MongoDB**: 4.0 or higher
+- **Mongoid**: 7.0 or higher
+- **MongoDB Replica Set**: Required for Change Streams (even single-node replica sets work)
+
+### Important: MongoDB Replica Set Requirement
+
+This adapter **requires MongoDB to be configured as a replica set** to use Change Streams for real-time message delivery. A single-node replica set is sufficient for development and smaller deployments.
+
+#### Converting Standalone MongoDB to Single-Node Replica Set
+
+```bash
+# 1. Stop MongoDB
+sudo systemctl stop mongod
+
+# 2. Edit /etc/mongod.conf and add:
+replication:
+  replSetName: "rs0"
+
+# 3. Start MongoDB
+sudo systemctl start mongod
+
+# 4. Connect with mongosh and initialize
+mongosh
+rs.initiate()
+```
+
+For Docker/Docker Compose:
+
+```yaml
+version: '3.8'
+services:
+  mongodb:
+    image: mongo:7
+    command: --replSet rs0
+    ports:
+      - "27017:27017"
+    healthcheck:
+      test: mongosh --eval "rs.status()" || mongosh --eval "rs.initiate()"
+      interval: 10s
+      timeout: 5s
+      retries: 5
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'solid_cable_mongoid_adapter'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install solid_cable_mongoid_adapter
+```
+
+## Usage
+
+### Configuration
+
+Edit `config/cable.yml`:
+
+```yaml
+production:
+  adapter: solid_mongoid
+  collection_name: "action_cable_messages"   # default
+  expiration: 300                             # TTL in seconds, default: 300
+  reconnect_delay: 1.0                        # initial retry delay, default: 1.0
+  max_reconnect_delay: 60.0                   # max retry delay, default: 60.0
+  poll_interval_ms: 500                       # polling fallback interval, default: 500
+  poll_batch_limit: 200                       # max messages per poll, default: 200
+  require_replica_set: true                   # enforce replica set, default: true
+
+development:
+  adapter: solid_mongoid
+  collection_name: "action_cable_messages_dev"
+  require_replica_set: false                  # can disable for dev if needed
+
+test:
+  adapter: test
+```
+
+### Mongoid Configuration
+
+Ensure your `config/mongoid.yml` is properly configured:
+
+```yaml
+production:
+  clients:
+    default:
+      uri: <%= ENV['MONGODB_URI'] %>
+      options:
+        max_pool_size: 50
+        min_pool_size: 5
+        wait_queue_timeout: 5
+        connect_timeout: 10
+        socket_timeout: 10
+        server_selection_timeout: 10
+        # Replica set configuration
+        replica_set: rs0
+        read:
+          mode: :primary_preferred
+        write:
+          w: 1
+```
+
+### Environment Variables
+
+```bash
+# MongoDB connection
+export MONGODB_URI="mongodb://localhost:27017/myapp_production"
+
+# Optional: Override polling settings
+export POLL_INTERVAL_MS=500
+export POLL_BATCH_LIMIT=200
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `adapter` | String | - | Must be `solid_mongoid` |
+| `collection_name` | String | `action_cable_messages` | MongoDB collection name |
+| `expiration` | Integer | `300` | Message TTL in seconds |
+| `reconnect_delay` | Float | `1.0` | Initial reconnect delay in seconds |
+| `max_reconnect_delay` | Float | `60.0` | Maximum reconnect delay (exponential backoff cap) |
+| `poll_interval_ms` | Integer | `500` | Polling interval when Change Streams unavailable |
+| `poll_batch_limit` | Integer | `200` | Max messages fetched per poll iteration |
+| `require_replica_set` | Boolean | `true` | Enforce replica set requirement |
+
+## Production Deployment
+
+### Best Practices
+
+1. **Use a Replica Set**: Always use a replica set, even if it's a single node, to enable Change Streams
+2. **Connection Pooling**: Configure appropriate pool sizes in `mongoid.yml`
+3. **Monitoring**: Monitor the `action_cable_messages` collection size and TTL index
+4. **Read Preference**: Use `:primary_preferred` for read operations
+5. **Write Concern**: Use `w: 1` for acceptable durability with good performance
+
+### MongoDB Atlas
+
+```yaml
+production:
+  clients:
+    default:
+      uri: <%= ENV['MONGODB_ATLAS_URI'] %>
+      options:
+        max_pool_size: 100
+        retry_writes: true
+        retry_reads: true
+```
+
+### Kubernetes/Docker
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  app:
+    environment:
+      MONGODB_URI: mongodb://mongodb:27017/myapp_production
+    depends_on:
+      mongodb:
+        condition: service_healthy
+
+  mongodb:
+    image: mongo:7
+    command: --replSet rs0
+    healthcheck:
+      test: mongosh --eval "rs.status()" || mongosh --eval "rs.initiate()"
+      interval: 10s
+      timeout: 5s
+      retries: 5
+```
+
+## How It Works
+
+### Architecture
+
+1. **Broadcast Phase**: When a message is broadcast to a channel:
+   - Document inserted into MongoDB collection
+   - TTL index schedules automatic cleanup
+   - All server processes are notified via Change Streams
+
+2. **Listening Phase**: Each server process:
+   - Maintains a Change Stream watching for inserts
+   - Receives new documents in real-time
+   - Dispatches to local Action Cable subscribers
+   - Maintains resume token for continuity
+
+3. **Fallback Mode**: If Change Streams unavailable:
+   - Falls back to polling every `poll_interval_ms`
+   - Maintains `@last_seen_id` to avoid replays
+   - Periodically checks if Change Streams become available
+
+### Thread Safety
+
+- One listener thread per Action Cable server process
+- Callbacks posted to Action Cable event loop
+- No shared state between processes
+- Safe for Puma cluster mode, Passenger, and other forking servers
+
+### Resilience
+
+- Automatic reconnection with exponential backoff
+- Resume tokens prevent message loss across reconnects
+- Graceful degradation to polling if needed
+- Comprehensive error logging
+
+## Troubleshooting
+
+### "MongoDB replica set is required" Error
+
+**Problem**: Getting `SolidCableMongoidAdapter::ReplicaSetRequiredError`
+
+**Solution**: Convert your MongoDB to a replica set (see Requirements section) or set `require_replica_set: false` in cable.yml (not recommended for production)
+
+### Messages Not Being Delivered
+
+**Checklist**:
+1. Verify MongoDB replica set is configured: `rs.status()` in mongosh
+2. Check Action Cable is mounted: `config/routes.rb` should have `mount ActionCable.server => '/cable'`
+3. Verify collection exists: `db.action_cable_messages.find().limit(1)`
+4. Check logs for connection errors
+5. Ensure WebSocket connection is established in browser
+
+### High Memory Usage
+
+**Solutions**:
+1. Reduce `expiration` time in cable.yml
+2. Increase `poll_batch_limit` if using polling
+3. Monitor collection size: `db.action_cable_messages.stats()`
+4. Verify TTL index is working: `db.action_cable_messages.getIndexes()`
+
+### Connection Pool Exhaustion
+
+**Solutions**:
+1. Increase `max_pool_size` in mongoid.yml
+2. Reduce number of Action Cable connections per process
+3. Use connection pooling monitoring
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+bundle exec rake spec
+bundle exec rubocop
+```
+
+To install this gem onto your local machine:
+
+```bash
+bundle exec rake install
+```
+
+## Testing
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run with coverage
+COVERAGE=true bundle exec rspec
+
+# Run specific test
+bundle exec rspec spec/adapter_spec.rb
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/washu/solid_cable_mongoid_adapter.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Created and maintained by [Aztec Software](https://aztecsoftware.com).
+
+Based on the solid_cable pattern and adapted for MongoDB with production-grade features.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/action_cable/subscription_adapter/solid_mongoid.rb

@@ -0,0 +1,452 @@
+# frozen_string_literal: true
+
+require "action_cable/subscription_adapter/base"
+require "action_cable/subscription_adapter/channel_prefix"
+require "action_cable/subscription_adapter/subscriber_map"
+require "mongoid"
+require "securerandom"
+
+module ActionCable
+  module SubscriptionAdapter
+    # SolidMongoid is an Action Cable subscription adapter that uses MongoDB (via Mongoid's client)
+    # as a durable, cross-process broadcast backend.
+    #
+    # ## Requirements
+    # - MongoDB must be configured as a replica set (even if single-node)
+    # - Change Streams require replica set or sharded cluster
+    #
+    # ## Features
+    # - Persists each broadcast as a document in a collection with TTL index
+    # - Uses MongoDB Change Streams for real-time message delivery
+    # - Falls back to polling on standalone MongoDB (not recommended for production)
+    # - Automatic reconnection with exponential backoff
+    # - Resume token support for continuity across reconnections
+    #
+    # ## Configuration
+    # Configure in `config/cable.yml` under the current environment:
+    #
+    #   production:
+    #     adapter: solid_mongoid
+    #     collection_name: "action_cable_messages"  # default
+    #     expiration: 300                            # seconds, default: 300
+    #     reconnect_delay: 1.0                       # seconds, default: 1.0
+    #     max_reconnect_delay: 60.0                  # seconds, default: 60.0
+    #     poll_interval_ms: 500                      # milliseconds, default: 500
+    #     poll_batch_limit: 200                      # default: 200
+    #     require_replica_set: true                  # default: true
+    #
+    # ## Thread Safety
+    # The adapter is thread-safe and maintains a dedicated listener thread per server process.
+    class SolidMongoid < Base
+      prepend ChannelPrefix
+
+      # Initialize the adapter and ensure the Mongo collection/index are ready.
+      # Validates replica set requirement if configured, logs a warning if not available.
+      #
+      # @return [void]
+      def initialize(*)
+        super
+        @listener = nil
+        validate_replica_set!
+        ensure_collection_state
+        logger.info "SolidCableMongoid: initialized; collection=#{collection_name.inspect}, pid=#{Process.pid}"
+      end
+
+      # Broadcast a payload to a channel by inserting a document into MongoDB.
+      # All listeners (processes/servers) will receive it through Change Streams or polling
+      # and rebroadcast to local subscribers.
+      #
+      # @param channel [String, Symbol] the channel identifier
+      # @param payload [String] the raw message payload (Action Cable provides a JSON string)
+      # @return [Boolean] true if successful, false on error
+      def broadcast(channel, payload)
+        collection.insert_one(
+          {
+            channel: channel.to_s,
+            message: payload,
+            created_at: Time.now.utc,
+            _expires: Time.now.utc + expiration
+          }
+        )
+        true
+      rescue Mongo::Error => e
+        logger.error "SolidCableMongoid: broadcast error (#{e.class}): #{e.message}"
+        false
+      rescue StandardError => e
+        logger.error "SolidCableMongoid: unexpected broadcast error (#{e.class}): #{e.message}"
+        false
+      end
+
+      # Subscribe a callback to a channel.
+      # The `success_callback` (if provided) is executed exactly once by `SubscriberMap` upon subscription success.
+      #
+      # @param channel [String, Symbol] the channel identifier
+      # @param callback [Proc] the block to invoke with each received message
+      # @param success_callback [Proc, nil] optional block to call once on successful subscription
+      # @return [void]
+      def subscribe(channel, callback, success_callback = nil)
+        listener.add_subscriber(channel, callback, success_callback)
+      end
+
+      # Unsubscribe a callback from a channel.
+      #
+      # @param channel [String, Symbol] the channel identifier
+      # @param callback [Proc] the previously registered callback
+      # @return [void]
+      def unsubscribe(channel, callback)
+        listener.remove_subscriber(channel, callback)
+      end
+
+      # Shut down the listener thread and release resources.
+      #
+      # @return [void]
+      def shutdown
+        listener&.shutdown
+      end
+
+      # Validate that MongoDB is configured as a replica set if required.
+      # Logs a warning and falls back to polling if not configured.
+      #
+      # @return [void]
+      def validate_replica_set!
+        return unless require_replica_set?
+
+        return if replica_set_configured?
+
+        logger.warn "SolidCableMongoid: MongoDB is not configured as a replica set. " \
+                    "Change Streams are unavailable; falling back to polling mode. " \
+                    "Set require_replica_set: false in cable.yml to disable this check."
+      end
+
+      # Check if MongoDB is configured as a replica set.
+      #
+      # @return [Boolean] true if replica set is configured
+      def replica_set_configured?
+        client = Mongoid.default_client
+        hello = begin
+          client.database.command({ hello: 1 }).first
+        rescue StandardError
+          nil
+        end
+        hello ||= begin
+          client.database.command({ ismaster: 1 }).first
+        rescue StandardError
+          nil
+        end
+        !!hello&.[]("setName")
+      rescue StandardError => e
+        logger.warn "SolidCableMongoid: unable to check replica set status (#{e.class}): #{e.message}"
+        false
+      end
+
+      # Ensure the MongoDB collection and indexes are in the expected state.
+      #
+      # @return [void]
+      def ensure_collection_state
+        db = Mongoid.default_client.database
+
+        # 1. Ensure collection exists
+        unless db.collection_names.include?(collection_name)
+          db.create_collection(collection_name)
+          logger.info "SolidCableMongoid: created collection #{collection_name.inspect}"
+        end
+
+        coll = db.collection(collection_name)
+
+        # 2. Create TTL index for automatic message expiration
+        begin
+          coll.indexes.create_one(
+            { _expires: 1 },
+            expire_after_seconds: 0,
+            name: "auto_expire",
+            partial_filter_expression: {
+              "_expires" => {
+                "$exists" => true,
+                "$type" => 9 # BSON Date type
+              }
+            }
+          )
+          logger.debug "SolidCableMongoid: TTL index ensured"
+        rescue Mongo::Error::OperationFailure => e
+          # Index may already exist with different options
+          if e.message.include?("already exists")
+            logger.debug "SolidCableMongoid: TTL index already exists"
+          else
+            logger.warn "SolidCableMongoid: failed to create TTL index: #{e.message}"
+          end
+        end
+
+        # 3. Create index on channel for query performance
+        begin
+          coll.indexes.create_one(
+            { channel: 1, _id: 1 },
+            name: "channel_id_index"
+          )
+          logger.debug "SolidCableMongoid: channel index ensured"
+        rescue Mongo::Error::OperationFailure => e
+          if e.message.include?("already exists")
+            logger.debug "SolidCableMongoid: channel index already exists"
+          else
+            logger.warn "SolidCableMongoid: failed to create channel index: #{e.message}"
+          end
+        end
+      rescue StandardError => e
+        logger.error "SolidCableMongoid: failed to ensure collection state: #{e.message}"
+      end
+
+      # --- Configuration accessors -------------------------------------------------
+
+      # Obtain the Mongo collection used for Action Cable messages.
+      # Not memoized to avoid issues with forking (e.g., Passenger, Puma cluster mode).
+      #
+      # @return [Mongo::Collection]
+      def collection
+        Mongoid.default_client.database.collection(collection_name)
+      end
+
+      # The name of the Mongo collection storing broadcasts.
+      #
+      # @return [String]
+      def collection_name
+        @server.config.cable.fetch("collection_name", "action_cable_messages")
+      end
+
+      # Message expiration time in seconds used by the TTL index.
+      #
+      # @return [Integer]
+      def expiration
+        @server.config.cable.fetch("expiration", 300).to_i
+      end
+
+      # Whether to require a replica set configuration.
+      #
+      # @return [Boolean]
+      def require_replica_set?
+        @server.config.cable.fetch("require_replica_set", true)
+      end
+
+      # The logger from the Action Cable server.
+      #
+      # @return [Logger]
+      def logger
+        @server.logger
+      end
+
+      # The Action Cable server instance.
+      #
+      # @return [ActionCable::Server::Base]
+      attr_reader :server
+
+      # The singleton listener for this server process. Lazily instantiated and
+      # synchronized through the server's mutex.
+      #
+      # @return [Listener]
+      def listener
+        @listener || @server.mutex.synchronize { @listener ||= Listener.new(self, @server.event_loop) }
+      end
+
+      # Listener consumes MongoDB inserts for this adapter and dispatches them
+      # to local Action Cable subscribers. It prefers MongoDB Change Streams
+      # when available and transparently falls back to polling on standalone
+      # deployments.
+      #
+      # ## Design
+      # - **Threaded**: a dedicated background thread runs the main loop
+      # - **Delivery**: callbacks are posted onto the Action Cable event loop for thread-safety
+      # - **Resilience**: on errors, uses exponential backoff before retry
+      # - **Continuity**: maintains `@resume_token` to resume Change Streams without message loss
+      #
+      # ## Configuration
+      # - `reconnect_delay` [Float] initial delay in seconds before retry (default: 1.0)
+      # - `max_reconnect_delay` [Float] maximum delay in seconds (default: 60.0)
+      # - `poll_interval_ms` [Integer] polling interval in milliseconds (default: 500)
+      # - `poll_batch_limit` [Integer] max documents per poll (default: 200)
+      class Listener < SubscriberMap
+        def initialize(adapter, event_loop)
+          super()
+          @adapter = adapter
+          @event_loop = event_loop
+          @running = true
+          @stream = nil
+          @resume_token = nil
+          @reconnect_attempts = 0
+
+          # Cache config values and collection to avoid accessing mocks from background thread
+          config = @adapter.server.config.cable
+          @reconnect_delay_base = config.fetch("reconnect_delay", 1.0).to_f
+          @max_reconnect_delay = config.fetch("max_reconnect_delay", 60.0).to_f
+          @poll_interval = config.fetch("poll_interval_ms", 500).to_i / 1000.0
+          @batch_limit = config.fetch("poll_batch_limit", 200).to_i
+          @collection = @adapter.collection
+
+          @thread = Thread.new { listen_loop }
+          @thread.name = "solid-cable-mongoid-#{Process.pid}" if @thread.respond_to?(:name=)
+          @thread.abort_on_exception = false
+        end
+
+        # Ensure callbacks fire on ActionCable's event loop for thread-safety.
+        def invoke_callback(*)
+          @event_loop.post { super }
+        end
+
+        # Graceful shutdown with configurable timeout.
+        def shutdown
+          @running = false
+          close_stream
+          return unless @thread&.alive?
+
+          @thread.join(5) || @thread.kill
+        end
+
+        private
+
+        # Calculate reconnect delay with exponential backoff.
+        #
+        # @return [Float] seconds to wait before retry
+        def reconnect_delay
+          [@reconnect_delay_base * (2**@reconnect_attempts), @max_reconnect_delay].min
+        end
+
+        # Polling interval in seconds.
+        #
+        # @return [Float]
+        attr_reader :poll_interval
+
+        # Max documents to fetch per poll.
+        #
+        # @return [Integer]
+        attr_reader :batch_limit
+
+        # Main listener loop that receives broadcasts from MongoDB.
+        #
+        # @return [void]
+        def listen_loop
+          pipeline = [{ "$match" => { "operationType" => "insert" } }]
+
+          while @running
+            begin
+              if change_stream_supported?
+                # Change Stream path (replica set / sharded)
+                opts = { max_await_time_ms: 1000 }
+                opts[:resume_after] = @resume_token if @resume_token
+
+                @stream = @collection.watch(pipeline, opts)
+                enum = @stream.to_enum
+
+                while @running && enum
+                  doc = enum.try_next
+                  next unless doc # nil when no event yet
+
+                  handle_insert_doc(doc["fullDocument"] || {})
+                  @resume_token = @stream.resume_token
+                  @reconnect_attempts = 0 # Reset on successful iteration
+                end
+              else
+                # Standalone fallback: polling
+                poll_for_inserts
+              end
+            rescue Mongo::Error::OperationFailure => e
+              unless e.message.include?("operation exceeded time limit")
+                @adapter.logger.warn "SolidCableMongoid: operation error (#{e.class}): #{e.message}"
+                @reconnect_attempts += 1
+              end
+              sleep_with_backoff
+            rescue Mongo::Error => e
+              @adapter.logger.warn "SolidCableMongoid: connection error (#{e.class}): #{e.message}"
+              @reconnect_attempts += 1
+              sleep_with_backoff
+            rescue NoMethodError => e
+              # Null stream error
+              @adapter.logger.debug "SolidCableMongoid: stream unavailable (#{e.message})"
+              @reconnect_attempts += 1
+              sleep_with_backoff
+            rescue StandardError => e
+              backtrace = Array(e.backtrace).take(10).join("\n")
+              msg = "SolidCableMongoid: unexpected listener error (#{e.class}): #{e.message}\n#{backtrace}"
+              @adapter.logger.error msg
+              @reconnect_attempts += 1
+              sleep_with_backoff
+            ensure
+              close_stream
+            end
+          end
+        end
+
+        # Sleep with exponential backoff.
+        def sleep_with_backoff
+          delay = reconnect_delay
+          @adapter.logger.debug "SolidCableMongoid: retrying in #{delay}s (attempt #{@reconnect_attempts})"
+          sleep delay
+        end
+
+        # Close the active change stream.
+        #
+        # @return [void]
+        def close_stream
+          @stream&.close
+        rescue StandardError => e
+          @adapter.logger.debug "SolidCableMongoid: stream close warning (#{e.class}): #{e.message}"
+        ensure
+          @stream = nil
+        end
+
+        # Check if Change Streams are supported.
+        #
+        # @return [Boolean]
+        def change_stream_supported?
+          @adapter.replica_set_configured?
+        end
+
+        # Poll for newly inserted broadcast documents when Change Streams are unavailable.
+        #
+        # @return [void]
+        def poll_for_inserts
+          coll = @collection
+
+          # Start after current head to avoid replaying history
+          @last_seen_id ||= begin
+            last = coll.find({}, { projection: { _id: 1 } })
+                       .sort({ _id: -1 })
+                       .limit(1)
+                       .first
+            last&.[]("_id")
+          end
+
+          interval = poll_interval
+
+          while @running && !change_stream_supported?
+            filter = @last_seen_id ? { "_id" => { "$gt" => @last_seen_id } } : {}
+            docs = coll.find(filter)
+                       .sort({ _id: 1 })
+                       .limit(batch_limit)
+                       .to_a
+
+            docs.each do |doc|
+              handle_insert_doc(doc)
+              @last_seen_id = doc["_id"]
+            end
+
+            @reconnect_attempts = 0 # Reset on successful poll
+
+            # If full batch, loop immediately; otherwise sleep
+            sleep(interval) if docs.length < batch_limit
+          end
+        end
+
+        # Dispatch a broadcast document to local subscribers.
+        #
+        # @param full [Hash] the full document
+        # @return [void]
+        def handle_insert_doc(full)
+          channel = full["channel"].to_s
+          message = full["message"]
+          return unless @subscribers.key?(channel)
+
+          broadcast(channel, message)
+        rescue StandardError => e
+          @adapter.logger.error "SolidCableMongoid: failed to handle insert (#{e.class}): #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/solid_cable_mongoid_adapter/version.rb

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

data/lib/solid_cable_mongoid_adapter.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "solid_cable_mongoid_adapter/version"
+
+module SolidCableMongoidAdapter
+  class Error < StandardError; end
+
+  class ReplicaSetRequiredError < Error
+    def initialize(msg = "MongoDB replica set is required for SolidCableMongoidAdapter")
+      super
+    end
+  end
+end
+
+# Auto-require the Action Cable adapter
+require_relative "action_cable/subscription_adapter/solid_mongoid"

data/solid_cable_mongoid_adapter.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/solid_cable_mongoid_adapter/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "solid_cable_mongoid_adapter"
+  spec.version = SolidCableMongoidAdapter::VERSION
+  spec.authors = ["Sal Scotto"]
+  spec.email = ["sscotto@gmail.com"]
+
+  spec.summary = "MongoDB adapter for Action Cable using Mongoid"
+  spec.description = "A production-ready Action Cable subscription adapter that uses MongoDB (via Mongoid) " \
+                     "as a durable, cross-process broadcast backend with Change Streams support"
+  spec.homepage = "https://github.com/washu/solid_cable_mongoid_adapter"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z 2>/dev/null`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "actioncable", ">= 7.0", "< 9.0"
+  spec.add_dependency "mongo", ">= 2.18", "< 3.0"
+  spec.add_dependency "mongoid", ">= 7.0", "< 10.0"
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: solid_cable_mongoid_adapter
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Sal Scotto
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-02-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actioncable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: mongo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.18'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.18'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: mongoid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: A production-ready Action Cable subscription adapter that uses MongoDB
+  (via Mongoid) as a durable, cross-process broadcast backend with Change Streams
+  support
+email:
+- sscotto@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/action_cable/subscription_adapter/solid_mongoid.rb
+- lib/solid_cable_mongoid_adapter.rb
+- lib/solid_cable_mongoid_adapter/version.rb
+- solid_cable_mongoid_adapter.gemspec
+homepage: https://github.com/washu/solid_cable_mongoid_adapter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/washu/solid_cable_mongoid_adapter
+  source_code_uri: https://github.com/washu/solid_cable_mongoid_adapter
+  changelog_uri: https://github.com/washu/solid_cable_mongoid_adapter/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.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: MongoDB adapter for Action Cable using Mongoid
+test_files: []