waitmate 0.1.0

data/lib/waitmate/store/solid_cache.rb

@@ -0,0 +1,358 @@
+# frozen_string_literal: true
+
+require "digest"
+
+begin
+  require "solid_cache" if defined?(Rails)
+rescue LoadError
+  # Solid Cache is optional; instantiation without the gem raises ConfigurationError.
+end
+
+module Waitmate
+  module Store
+    # SQL-backed fallback adapter built on top of SolidCache::Entry.
+    #
+    # Solid Cache is a fixed-schema key/value store, so Waitmate queue state
+    # is separated into two key prefixes:
+    #   waitmate:waiting:{queue}:{identity}  — waiting entries
+    #   waitmate:active:{queue}:{identity}   — admitted entries
+    #
+    # This mirrors the Redis adapter's separate sorted sets and lets SQL
+    # +LIKE+ narrow scans to one state before Ruby-side JSON parsing.
+    # Active scans are bounded by +max_concurrent+; waiting scans are
+    # bounded by queue depth ahead of the target entry.
+    #
+    # FIFO ordering relies on an +enqueued_at+ timestamp stored in the JSON
+    # value, avoiding reliance on the binary +created_at+ column which has
+    # cross-Rails-version comparison issues.
+    #
+    # Single-key lookups use +SolidCache::Entry.read+ / +delete_by_key+
+    # which operate on the indexed +key_hash+ integer column, avoiding
+    # binary +key+ column comparison entirely.
+    #
+    # Admission is serialized per queue with a mutex row so capacity
+    # accounting never follows a read-modify-write path under concurrency.
+    class SolidCache
+      KEY_PREFIX = "waitmate"
+
+      def initialize(config: Waitmate.configuration)
+        begin
+          require "solid_cache" unless defined?(::SolidCache)
+        rescue LoadError
+          # Fall through to the contract check below.
+        end
+
+        unless defined?(::SolidCache::Entry)
+          raise ConfigurationError,
+            "Solid Cache gem is not available. Add `gem 'solid_cache'` to your Gemfile " \
+            "to use the Solid Cache adapter."
+        end
+
+        @queue_ttl = config.queue_ttl
+      end
+
+      # enqueue(queue_name, identity, ttl: nil) -> Integer (1-based position) or 0 (already active)
+      def enqueue(queue_name, identity, ttl: nil)
+        ttl ||= @queue_ttl
+        now = current_timestamp
+        expires_at = now + ttl
+        a_key = active_entry_key(queue_name, identity)
+        w_key = waiting_entry_key(queue_name, identity)
+
+        with_ar do
+          # Already active and not expired?
+          active_value = read_value(a_key)
+          if active_value
+            return 0 if active_value["expires_at"] > now
+          end
+
+          # Already waiting and not expired?
+          waiting_value = read_value(w_key)
+          if waiting_value
+            if waiting_value["expires_at"] > now
+              waiting_value["expires_at"] = expires_at
+              ::SolidCache::Entry.write(w_key, waiting_value.to_json)
+              return waiting_position(queue_name, waiting_value["enqueued_at"], now)
+            end
+            # Expired waiting entry — delete so the new write gets a fresh enqueued_at
+            ::SolidCache::Entry.delete_by_key(w_key)
+          end
+
+          # New entry
+          value = {state: "waiting", expires_at: expires_at, enqueued_at: now}
+          ::SolidCache::Entry.write(w_key, value.to_json)
+          waiting_position(queue_name, now, now)
+        end
+      end
+
+      # position(queue_name, identity) -> Integer (1-based), 0 (active), or nil
+      def position(queue_name, identity)
+        now = current_timestamp
+        a_key = active_entry_key(queue_name, identity)
+        w_key = waiting_entry_key(queue_name, identity)
+
+        with_ar do
+          # Check active
+          active_value = read_value(a_key)
+          if active_value
+            if active_value["expires_at"] <= now
+              ::SolidCache::Entry.delete_by_key(a_key)
+              return nil
+            end
+            return 0
+          end
+
+          # Check waiting
+          waiting_value = read_value(w_key)
+          if waiting_value
+            if waiting_value["expires_at"] <= now
+              ::SolidCache::Entry.delete_by_key(w_key)
+              return nil
+            end
+            return waiting_position(queue_name, waiting_value["enqueued_at"], now)
+          end
+
+          nil
+        end
+      end
+
+      # active_count(queue_name) -> Integer
+      def active_count(queue_name)
+        now = current_timestamp
+
+        with_ar do
+          active_count_internal(queue_name, now)
+        end
+      end
+
+      # admit(queue_name, max_concurrent, count: max_concurrent) -> Array<String>
+      def admit(queue_name, max_concurrent, count: max_concurrent)
+        now = current_timestamp
+        active_ttl = @queue_ttl
+
+        with_ar do
+          admitted = []
+
+          ActiveRecord::Base.transaction do
+            ensure_mutex(queue_name)
+            expire_stale_internal(queue_name, now)
+
+            active = active_count_internal(queue_name, now)
+            available = max_concurrent - active
+            break admitted if available <= 0
+
+            admit_count = [available, count].min
+
+            # Separate waiting prefix guarantees all returned rows are waiting.
+            # No Ruby-side state filter needed — fixes the S2-NEWBUG capacity bug.
+            # Sort by enqueued_at from the JSON value for FIFO ordering.
+            # uncached is required because SolidCache's own write/delete methods do
+            # not dirty the Rails query cache, so a subsequent scan in the same
+            # request (e.g. release → admit) could read stale waiting rows.
+            waiting = ::SolidCache::Entry.uncached do
+              ::SolidCache::Entry
+                .where("key LIKE ?", waiting_key_pattern(queue_name))
+                .to_a
+                .map { |entry| [entry, parse_value(entry.value, key: entry.key)] }
+                .select { |_, value| value["expires_at"] > now }
+                .sort_by { |_, value| value["enqueued_at"] }
+                .first(admit_count)
+            end
+
+            waiting.each do |entry, value|
+              identity = identity_from_key(entry.key, queue_name)
+              value["state"] = "active"
+              value["expires_at"] = now + active_ttl
+              ::SolidCache::Entry.delete_by_key(waiting_entry_key(queue_name, identity))
+              ::SolidCache::Entry.write(active_entry_key(queue_name, identity), value.to_json)
+              admitted << identity
+            end
+          end
+
+          admitted
+        end
+      end
+
+      # release(queue_name, identity) -> Boolean
+      def release(queue_name, identity)
+        key = active_entry_key(queue_name, identity)
+
+        with_ar do
+          result = ::SolidCache::Entry.delete_by_key(key)
+          result.is_a?(Integer) ? result > 0 : result
+        end
+      end
+
+      # heartbeat(queue_name, identity, ttl: nil) -> Boolean
+      def heartbeat(queue_name, identity, ttl: nil)
+        ttl ||= @queue_ttl
+        now = current_timestamp
+        w_key = waiting_entry_key(queue_name, identity)
+        a_key = active_entry_key(queue_name, identity)
+
+        with_ar do
+          # Check waiting first
+          value = read_value(w_key)
+          if value
+            return false if value["expires_at"] <= now
+            value["expires_at"] = now + ttl
+            ::SolidCache::Entry.write(w_key, value.to_json)
+            return true
+          end
+
+          # Check active
+          value = read_value(a_key)
+          if value
+            return false if value["expires_at"] <= now
+            value["expires_at"] = now + ttl
+            ::SolidCache::Entry.write(a_key, value.to_json)
+            return true
+          end
+
+          false
+        end
+      end
+
+      # expire_stale(queue_name) -> Hash {waiting: Integer, active: Integer}
+      def expire_stale(queue_name)
+        now = current_timestamp
+
+        with_ar do
+          ActiveRecord::Base.transaction do
+            ensure_mutex(queue_name)
+            expire_stale_internal(queue_name, now)
+          end
+        end
+      end
+
+      private
+
+      def waiting_entry_key(queue_name, identity)
+        "#{KEY_PREFIX}:waiting:#{queue_name}:#{identity}"
+      end
+
+      def active_entry_key(queue_name, identity)
+        "#{KEY_PREFIX}:active:#{queue_name}:#{identity}"
+      end
+
+      def mutex_key(queue_name)
+        "#{KEY_PREFIX}:mutex:#{queue_name}"
+      end
+
+      def waiting_key_pattern(queue_name)
+        "#{KEY_PREFIX}:waiting:#{ActiveRecord::Base.sanitize_sql_like(queue_name)}:%"
+      end
+
+      def active_key_pattern(queue_name)
+        "#{KEY_PREFIX}:active:#{ActiveRecord::Base.sanitize_sql_like(queue_name)}:%"
+      end
+
+      def identity_from_key(key, queue_name)
+        key_s = key.to_s
+        %w[waiting active].each do |state|
+          prefix = "#{KEY_PREFIX}:#{state}:#{queue_name}:"
+          return key_s.sub(prefix, "") if key_s.start_with?(prefix)
+        end
+        key_s
+      end
+
+      def current_timestamp
+        ::Time.now.to_f
+      end
+
+      # Reads and parses a JSON value using Solid Cache's key_hash-based read.
+      # Returns nil if the key does not exist.
+      def read_value(key)
+        raw = ::SolidCache::Entry.read(key)
+        return nil unless raw
+        parse_value(raw, key: key)
+      end
+
+      # Parses a JSON value. On parse failure, includes a hashed key fragment
+      # for debugging without leaking PII (L0036).
+      def parse_value(value, key: nil)
+        JSON.parse(value.to_s)
+      rescue JSON::ParserError => e
+        if key
+          digest = Digest::SHA256.hexdigest(key.to_s)[0, 12]
+          raise JSON::ParserError, "#{e.message} [key digest: #{digest}]"
+        end
+        raise
+      end
+
+      # Counts active entries by scanning only the active key prefix.
+      # Materializes active rows only (bounded by max_concurrent), not the
+      # full queue. Ruby-side JSON parsing for expires_at is unavoidable
+      # because Solid Cache's KV schema has no per-entry TTL column.
+      def active_count_internal(queue_name, now)
+        ::SolidCache::Entry.uncached do
+          ::SolidCache::Entry
+            .where("key LIKE ?", active_key_pattern(queue_name))
+            .count do |entry|
+              parse_value(entry.value, key: entry.key)["expires_at"] > now
+            end
+        end
+      end
+
+      # Counts non-expired waiting entries with enqueued_at <= target.
+      # Scans only the waiting key prefix; does not touch active rows.
+      def waiting_position(queue_name, enqueued_at, now)
+        ::SolidCache::Entry.uncached do
+          ::SolidCache::Entry
+            .where("key LIKE ?", waiting_key_pattern(queue_name))
+            .count do |entry|
+              value = parse_value(entry.value, key: entry.key)
+              value["expires_at"] > now && value["enqueued_at"] <= enqueued_at
+            end
+        end
+      end
+
+      def ensure_mutex(queue_name)
+        key = mutex_key(queue_name)
+        ::SolidCache::Entry.write(key, "1")
+        # Verify the mutex row exists using read (key_hash-based lookup)
+        raise Error, "Waitmate Solid Cache mutex acquisition failed" unless ::SolidCache::Entry.read(key)
+      end
+
+      # Purges expired entries from both waiting and active prefixes.
+      # Called inside the mutex-protected transaction so no concurrent
+      # reader sees partially-purged state.
+      def expire_stale_internal(queue_name, now)
+        waiting_count = 0
+        active_count = 0
+
+        ::SolidCache::Entry.uncached do
+          ::SolidCache::Entry.where("key LIKE ?", waiting_key_pattern(queue_name)).each do |entry|
+            if parse_value(entry.value, key: entry.key)["expires_at"] <= now
+              ::SolidCache::Entry.delete_by_key(entry.key)
+              waiting_count += 1
+            end
+          end
+        end
+
+        ::SolidCache::Entry.uncached do
+          ::SolidCache::Entry.where("key LIKE ?", active_key_pattern(queue_name)).each do |entry|
+            if parse_value(entry.value, key: entry.key)["expires_at"] <= now
+              ::SolidCache::Entry.delete_by_key(entry.key)
+              active_count += 1
+            end
+          end
+        end
+
+        {waiting: waiting_count, active: active_count}
+      end
+
+      def with_ar
+        yield
+      rescue ActiveRecord::ActiveRecordError => e
+        raise ConnectionError,
+          "Waitmate could not reach Solid Cache (#{e.class}: #{e.message}). " \
+          "Verify the database connection."
+      rescue JSON::ParserError => e
+        raise Error, "Waitmate Solid Cache store corrupted value (#{e.class}: #{e.message})"
+      rescue => e
+        raise Error, "Waitmate Solid Cache store error (#{e.class}: #{e.message})"
+      end
+    end
+  end
+end

data/lib/waitmate/store.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Waitmate
+  # Public seam for all queue/storage operations. Host controllers and engine UI
+  # call +Waitmate::Store+, never a concrete adapter.
+  module Store
+    class Error < Waitmate::Error; end
+    class ConfigurationError < Error; end
+    class ConnectionError < Error; end
+
+    @adapter = nil
+
+    class << self
+      # enqueue(queue_name, identity, ttl: nil) -> Integer (1-based position) or 0 (already active)
+      def enqueue(queue_name, identity, ttl: nil)
+        adapter.enqueue(queue_name, identity, ttl: ttl)
+      end
+
+      # position(queue_name, identity) -> Integer (1-based), 0 (active), or nil
+      def position(queue_name, identity)
+        adapter.position(queue_name, identity)
+      end
+
+      # active_count(queue_name) -> Integer
+      def active_count(queue_name)
+        adapter.active_count(queue_name)
+      end
+
+      # admit(queue_name, max_concurrent, count: max_concurrent) -> Array<String>
+      def admit(queue_name, max_concurrent, count: max_concurrent)
+        adapter.admit(queue_name, max_concurrent, count: count)
+      end
+
+      # release(queue_name, identity) -> Boolean
+      def release(queue_name, identity)
+        adapter.release(queue_name, identity)
+      end
+
+      # heartbeat(queue_name, identity, ttl: nil) -> Boolean
+      def heartbeat(queue_name, identity, ttl: nil)
+        adapter.heartbeat(queue_name, identity, ttl: ttl)
+      end
+
+      # expire_stale(queue_name) -> Hash {waiting: Integer, active: Integer}
+      def expire_stale(queue_name)
+        adapter.expire_stale(queue_name)
+      end
+
+      def adapter
+        @adapter ||= build_adapter(Waitmate.configuration.adapter)
+      end
+
+      attr_writer :adapter
+
+      def reset_adapter!
+        @adapter = nil
+      end
+
+      private
+
+      def build_adapter(name)
+        case name
+        when :redis
+          Redis.new
+        when :solid_cache
+          SolidCache.new
+        else
+          raise ConfigurationError, "Unknown Waitmate adapter: #{name.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/waitmate/ticket.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "digest"
+require "active_support"
+require "active_support/message_encryptor"
+
+module Waitmate
+  module Ticket
+    PURPOSE = "waitmate:ticket"
+    SALT = "waitmate ticket v1"
+    KEY_LENGTH = 32
+
+    class Result
+      attr_reader :reason
+
+      def initialize(success:, reason: nil)
+        @success = success
+        @reason = reason
+      end
+
+      def success?
+        @success
+      end
+    end
+
+    class << self
+      def issue(queue_name:, session_id:)
+        encryptor.encrypt_and_sign(
+          payload(queue_name, session_id),
+          expires_in: Waitmate.configuration.ticket_ttl,
+          purpose: PURPOSE
+        )
+      end
+
+      def verify(token:, queue_name:, session_id:)
+        data = encryptor.decrypt_and_verify(token.to_s, purpose: PURPOSE)
+        return failure(:invalid) unless valid_payload?(data, queue_name, session_id)
+
+        success
+      rescue ActiveSupport::MessageEncryptor::InvalidMessage
+        failure(:invalid)
+      end
+
+      private
+
+      def payload(queue_name, session_id)
+        {
+          "queue_name" => queue_name.to_s,
+          "identity_digest" => identity_digest(session_id)
+        }
+      end
+
+      def identity_digest(session_id)
+        Digest::SHA256.hexdigest(session_id.to_s)
+      end
+
+      def valid_payload?(data, queue_name, session_id)
+        data.is_a?(Hash) &&
+          data["queue_name"] == queue_name.to_s &&
+          data["identity_digest"] == identity_digest(session_id)
+      end
+
+      def encryptor
+        @encryptor ||= ActiveSupport::MessageEncryptor.new(
+          Rails.application.key_generator.generate_key(SALT, KEY_LENGTH)
+        )
+      end
+
+      def success
+        Result.new(success: true, reason: nil)
+      end
+
+      def failure(reason)
+        Result.new(success: false, reason: reason)
+      end
+    end
+  end
+end

data/lib/waitmate/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Waitmate
+  VERSION = "0.1.0"
+  RUBY_MINIMUM_VERSION = "3.2.0"
+  RAILS_MINIMUM_VERSION = "7.1.0"
+end

data/lib/waitmate.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "waitmate/version"
+
+module Waitmate
+  class Error < StandardError; end
+end
+
+require_relative "waitmate/configuration"
+require_relative "waitmate/ticket"
+require_relative "waitmate/store"
+require_relative "waitmate/store/redis"
+require_relative "waitmate/store/solid_cache"
+require_relative "waitmate/controller_concern"
+require_relative "waitmate/engine" if defined?(Rails::Engine)
+
+module Waitmate
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: waitmate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- BartOz
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: solid_cache
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: Protects expensive controller actions from thundering-herd overload by
+  queuing overflow users, issuing signed admission tickets, and letting users wait
+  on a lightweight Engine-provided page.
+email:
+- bartek.ozdoba@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- app/controllers/waitmate/application_controller.rb
+- app/controllers/waitmate/rooms_controller.rb
+- app/views/waitmate/rooms/show.html.erb
+- bin/quality
+- config/routes.rb
+- lib/generators/waitmate/install_generator.rb
+- lib/generators/waitmate/templates/waitmate.rb
+- lib/waitmate.rb
+- lib/waitmate/configuration.rb
+- lib/waitmate/controller_concern.rb
+- lib/waitmate/engine.rb
+- lib/waitmate/store.rb
+- lib/waitmate/store/redis.rb
+- lib/waitmate/store/solid_cache.rb
+- lib/waitmate/ticket.rb
+- lib/waitmate/version.rb
+homepage: https://github.com/bart-oz/waitmate
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bart-oz/waitmate
+  source_code_uri: https://github.com/bart-oz/waitmate
+  changelog_uri: https://github.com/bart-oz/waitmate/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Virtual waiting room for Rails applications
+test_files: []