waitmate 0.1.0

data/bin/quality

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Waitmate Quality Gate Suite
+# Runs all non-negotiable gates in sequence.
+# Usage: bin/quality [--skip-appraisal]
+#
+# Individual gates can be run via:
+#   bin/quality rspec
+#   bin/quality standardrb
+#   bin/quality appraisal
+#   bin/quality audit
+
+SKIP_APPRAISAL=false
+SINGLE_GATE=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --skip-appraisal) SKIP_APPRAISAL=true ;;
+    rspec|standardrb|appraisal|audit) SINGLE_GATE="$arg" ;;
+  esac
+done
+
+red()   { printf '\033[31m%s\033[0m\n' "$*" >&2; }
+green() { printf '\033[32m%s\033[0m\n' "$*"; }
+dim()   { printf '\033[2m%s\033[0m\n' "$*"; }
+
+run_gate() {
+  local label="$1"; shift
+  dim "⏳ ${label}..."
+  if "$@" > /dev/null 2>&1; then
+    green "✅ ${label}"
+    return 0
+  else
+    red "❌ ${label} FAILED — check output above"
+    return 1
+  fi
+}
+
+gate_rspec() {
+  run_gate "RSpec" bundle exec rspec
+}
+
+gate_standardrb() {
+  run_gate "StandardRB" bundle exec standardrb
+}
+
+gate_appraisal() {
+  run_gate "Rails 7.1 appraisal" bundle exec appraisal rails-7.1 rspec \
+    && run_gate "Rails 7.2 appraisal" bundle exec appraisal rails-7.2 rspec \
+    && run_gate "Rails 8.0 appraisal" bundle exec appraisal rails-8.0 rspec
+}
+
+gate_audit() {
+  dim "⏳ bundler-audit: updating advisory DB..."
+  bundle exec bundler-audit update > /dev/null 2>&1 || true
+  run_gate "bundler-audit" bundle exec bundler-audit check
+}
+
+run_all() {
+  local failed=0
+
+  gate_rspec      || failed=$((failed + 1))
+  gate_standardrb || failed=$((failed + 1))
+
+  if [ "$SKIP_APPRAISAL" = false ]; then
+    gate_appraisal || failed=$((failed + 1))
+  else
+    dim "⏭️  Skipping appraisal (--skip-appraisal)"
+  fi
+
+  gate_audit      || failed=$((failed + 1))
+
+  echo ""
+  if [ "$failed" -eq 0 ]; then
+    green "All quality gates passed"
+  else
+    red "${failed} gate(s) failed"
+    return 1
+  fi
+}
+
+case "$SINGLE_GATE" in
+  rspec)      gate_rspec ;;
+  standardrb) gate_standardrb ;;
+  appraisal)  gate_appraisal ;;
+  audit)      gate_audit ;;
+  "")         run_all ;;
+esac

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Waitmate::Engine.routes.draw do
+  get "room", to: "rooms#show"
+  get "room/position", to: "rooms#position"
+end

data/lib/generators/waitmate/install_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Waitmate
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Waitmate initializer in config/initializers/waitmate.rb"
+
+      def copy_initializer
+        template "waitmate.rb", "config/initializers/waitmate.rb"
+      end
+    end
+  end
+end

data/lib/generators/waitmate/templates/waitmate.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+Waitmate.configure do |config|
+  # Storage adapter. :redis is recommended for high-traffic rooms.
+  # :solid_cache is supported when you want a Rails/Solid Stack setup
+  # without running Redis. Install and migrate Solid Cache first.
+  config.adapter = :redis
+
+  # Seconds before an abandoned queue entry expires. Each poll extends TTL.
+  config.queue_ttl = 300
+
+  # Seconds between browser polls for queue position.
+  config.polling_interval = 5
+
+  # Seconds before an admission ticket expires.
+  config.ticket_ttl = 120
+
+  # Engine path for the waiting-room page. The host app must mount
+  # Waitmate::Engine at the matching prefix in config/routes.rb.
+  config.waiting_room_path = "/waitmate/room"
+end

data/lib/waitmate/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Waitmate
+  class Configuration
+    attr_accessor :adapter, :queue_ttl, :polling_interval, :ticket_ttl, :waiting_room_path
+
+    def initialize
+      @adapter = :redis
+      @queue_ttl = 300
+      @polling_interval = 5
+      @ticket_ttl = 120
+      @waiting_room_path = "/waitmate/room"
+    end
+  end
+end

data/lib/waitmate/controller_concern.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/concern"
+
+module Waitmate
+  # Shared validation for the relative target URL that is threaded between the
+  # host controller and the Engine waiting room. Keeping this in one place
+  # ensures the concern-emit path and the room-redirect path never diverge.
+  module TargetValidation
+    extend ActiveSupport::Concern
+
+    included { private }
+
+    def valid_waiting_room_target?(target)
+      return false unless target.is_a?(String) && target.start_with?("/")
+      return false if target.start_with?("//")
+      return false if target.include?("://")
+      return false if target.match?(/\Ajavascript:/i)
+      true
+    end
+  end
+
+  # Provides the +wait_room+ controller macro. Host controllers include this
+  # concern and declare which actions are capacity-gated:
+  #
+  #   class CheckoutsController < ApplicationController
+  #     include Waitmate::ControllerConcern
+  #     wait_room :create, max_concurrent: 500
+  #   end
+  #
+  # The macro is transport-agnostic: it performs capacity-check → redirect →
+  # return-verify without knowing whether the waiting room uses polling,
+  # ActionCable, or full-page reloads.
+  module ControllerConcern
+    extend ActiveSupport::Concern
+    include TargetValidation
+
+    class_methods do
+      def wait_room(action, max_concurrent:)
+        before_action(only: action) { handle_wait_room(max_concurrent: max_concurrent) }
+        after_action(only: action) { release_wait_room_slot(max_concurrent: max_concurrent) }
+      end
+    end
+
+    private
+
+    def handle_wait_room(max_concurrent:)
+      queue_name = action_name.to_s
+      session_id = session.id.to_s
+
+      if params[:ticket].present?
+        handle_return(queue_name, session_id, max_concurrent)
+      else
+        handle_initial(queue_name, session_id, max_concurrent)
+      end
+    end
+
+    def handle_initial(queue_name, session_id, max_concurrent)
+      Store.enqueue(queue_name, session_id)
+      Store.admit(queue_name, max_concurrent, count: 1)
+
+      return if Store.position(queue_name, session_id) == 0
+
+      redirect_to_waiting_room(
+        ticket: Ticket.issue(queue_name: queue_name, session_id: session_id),
+        queue: queue_name,
+        target: request.fullpath
+      )
+    end
+
+    def handle_return(queue_name, session_id, max_concurrent)
+      result = Ticket.verify(token: params[:ticket], queue_name: queue_name, session_id: session_id)
+      target = request.fullpath
+      return redirect_to_waiting_room(queue: queue_name, target: target) unless result.success?
+
+      Store.admit(queue_name, max_concurrent, count: 1)
+
+      return if Store.position(queue_name, session_id) == 0
+
+      redirect_to_waiting_room(ticket: params[:ticket], queue: queue_name, target: target)
+    end
+
+    def redirect_to_waiting_room(ticket: nil, queue: nil, target: nil)
+      path = Waitmate.configuration.waiting_room_path
+      query = {ticket: ticket, queue: queue}.compact
+      query[:target] = target if valid_waiting_room_target?(target)
+      path += "?#{query.to_query}" if query.any?
+      redirect_to(path)
+    end
+
+    def release_wait_room_slot(max_concurrent:)
+      queue_name = action_name.to_s
+      session_id = session.id.to_s
+
+      Store.admit(queue_name, max_concurrent, count: 1) if Store.release(queue_name, session_id)
+    end
+  end
+end

data/lib/waitmate/engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Waitmate
+  class Engine < ::Rails::Engine
+    isolate_namespace Waitmate
+  end
+end

data/lib/waitmate/store/redis.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+begin
+  require "redis" unless defined?(::Redis)
+rescue LoadError
+  # Redis is optional; instantiation without the gem raises ConfigurationError.
+end
+
+module Waitmate
+  module Store
+    # Redis-backed store contract implementation. All operations that touch
+    # capacity or ordering run inside atomic Lua scripts so concurrent callers
+    # cannot double-count or lose slots.
+    #
+    # Per-queue data model:
+    #   waitmate:queue:{q}          - sorted set keyed by enqueue timestamp (FIFO)
+    #   waitmate:waiting_expiry:{q} - sorted set keyed by expiry timestamp
+    #   waitmate:active:{q}         - sorted set keyed by expiry timestamp
+    class Redis
+      KEY_PREFIX = "waitmate"
+      LUA_SCRIPTS = {
+        enqueue: <<~LUA,
+          local queue_key = KEYS[1]
+          local expiry_key = KEYS[2]
+          local active_key = KEYS[3]
+          local identity = ARGV[1]
+          local now = tonumber(ARGV[2])
+          local expiry = tonumber(ARGV[3])
+
+          redis.call('ZREMRANGEBYSCORE', active_key, '-inf', now)
+
+          if redis.call('ZRANK', active_key, identity) ~= false then
+            return 0
+          end
+
+          local waiting_rank = redis.call('ZRANK', queue_key, identity)
+          if waiting_rank ~= false then
+            redis.call('ZADD', expiry_key, expiry, identity)
+            return waiting_rank + 1
+          end
+
+          redis.call('ZADD', queue_key, now, identity)
+          redis.call('ZADD', expiry_key, expiry, identity)
+          return redis.call('ZRANK', queue_key, identity) + 1
+        LUA
+
+        position: <<~LUA,
+          local queue_key = KEYS[1]
+          local expiry_key = KEYS[2]
+          local active_key = KEYS[3]
+          local identity = ARGV[1]
+          local now = tonumber(ARGV[2])
+
+          redis.call('ZREMRANGEBYSCORE', active_key, '-inf', now)
+
+          local expired = redis.call('ZRANGEBYSCORE', expiry_key, '-inf', now)
+          for i = 1, #expired do
+            redis.call('ZREM', queue_key, expired[i])
+            redis.call('ZREM', expiry_key, expired[i])
+          end
+
+          if redis.call('ZRANK', active_key, identity) ~= false then
+            return 0
+          end
+
+          local waiting_rank = redis.call('ZRANK', queue_key, identity)
+          if waiting_rank ~= false then
+            return waiting_rank + 1
+          end
+
+          return -1
+        LUA
+
+        active_count: <<~LUA,
+          local active_key = KEYS[1]
+          local now = tonumber(ARGV[1])
+
+          redis.call('ZREMRANGEBYSCORE', active_key, '-inf', now)
+          return redis.call('ZCARD', active_key)
+        LUA
+
+        admit: <<~LUA,
+          local queue_key = KEYS[1]
+          local expiry_key = KEYS[2]
+          local active_key = KEYS[3]
+          local now = tonumber(ARGV[1])
+          local active_ttl = tonumber(ARGV[2])
+          local max_concurrent = tonumber(ARGV[3])
+          local count = tonumber(ARGV[4])
+
+          redis.call('ZREMRANGEBYSCORE', active_key, '-inf', now)
+
+          local expired_waiting = redis.call('ZRANGEBYSCORE', expiry_key, '-inf', now)
+          for i = 1, #expired_waiting do
+            redis.call('ZREM', queue_key, expired_waiting[i])
+            redis.call('ZREM', expiry_key, expired_waiting[i])
+          end
+
+          local active_count = redis.call('ZCARD', active_key)
+          local available = max_concurrent - active_count
+          if available <= 0 then
+            return {}
+          end
+
+          local admit_count = math.min(available, count)
+          local waiting = redis.call('ZRANGE', queue_key, 0, admit_count - 1)
+          if #waiting == 0 then
+            return {}
+          end
+
+          local active_expiry = now + active_ttl
+          for i = 1, #waiting do
+            local identity = waiting[i]
+            redis.call('ZREM', queue_key, identity)
+            redis.call('ZREM', expiry_key, identity)
+            redis.call('ZADD', active_key, active_expiry, identity)
+          end
+
+          return waiting
+        LUA
+
+        heartbeat: <<~LUA,
+          local queue_key = KEYS[1]
+          local expiry_key = KEYS[2]
+          local active_key = KEYS[3]
+          local identity = ARGV[1]
+          local now = tonumber(ARGV[2])
+          local ttl = tonumber(ARGV[3])
+
+          if redis.call('ZRANK', active_key, identity) ~= false then
+            redis.call('ZADD', active_key, now + ttl, identity)
+            return 1
+          end
+
+          if redis.call('ZRANK', queue_key, identity) ~= false then
+            redis.call('ZADD', expiry_key, now + ttl, identity)
+            return 1
+          end
+
+          return 0
+        LUA
+
+        expire_stale: <<~LUA
+          local queue_key = KEYS[1]
+          local expiry_key = KEYS[2]
+          local active_key = KEYS[3]
+          local now = tonumber(ARGV[1])
+
+          local expired_waiting = redis.call('ZRANGEBYSCORE', expiry_key, '-inf', now)
+          for i = 1, #expired_waiting do
+            redis.call('ZREM', queue_key, expired_waiting[i])
+            redis.call('ZREM', expiry_key, expired_waiting[i])
+          end
+
+          local active_removed = redis.call('ZREMRANGEBYSCORE', active_key, '-inf', now)
+
+          return {#expired_waiting, active_removed}
+        LUA
+      }.freeze
+
+      def initialize(redis: nil, config: Waitmate.configuration)
+        unless defined?(::Redis)
+          raise ConfigurationError,
+            "Redis gem is not available. Add `gem 'redis'` to your Gemfile to use the Redis adapter."
+        end
+
+        @config = config
+        @redis = redis || ::Redis.new
+      end
+
+      attr_reader :redis
+
+      def enqueue(queue_name, identity, ttl: nil)
+        ttl ||= @config.queue_ttl
+        now = current_timestamp
+        expiry = now + ttl
+
+        eval_script(
+          :enqueue,
+          keys: [queue_key(queue_name), expiry_key(queue_name), active_key(queue_name)],
+          argv: [identity.to_s, now, expiry]
+        )
+      end
+
+      def position(queue_name, identity)
+        rank = eval_script(
+          :position,
+          keys: [queue_key(queue_name), expiry_key(queue_name), active_key(queue_name)],
+          argv: [identity.to_s, current_timestamp]
+        )
+
+        (rank == -1) ? nil : rank
+      end
+
+      def active_count(queue_name)
+        eval_script(
+          :active_count,
+          keys: [active_key(queue_name)],
+          argv: [current_timestamp]
+        )
+      end
+
+      def admit(queue_name, max_concurrent, count: max_concurrent)
+        eval_script(
+          :admit,
+          keys: [queue_key(queue_name), expiry_key(queue_name), active_key(queue_name)],
+          argv: [current_timestamp, @config.queue_ttl, max_concurrent, count]
+        )
+      end
+
+      def release(queue_name, identity)
+        result = with_redis do |redis|
+          redis.zrem(active_key(queue_name), identity.to_s)
+        end
+        !!result
+      end
+
+      def heartbeat(queue_name, identity, ttl: nil)
+        ttl ||= @config.queue_ttl
+        result = eval_script(
+          :heartbeat,
+          keys: [queue_key(queue_name), expiry_key(queue_name), active_key(queue_name)],
+          argv: [identity.to_s, current_timestamp, ttl]
+        )
+        result == 1
+      end
+
+      def expire_stale(queue_name)
+        waiting, active = eval_script(
+          :expire_stale,
+          keys: [queue_key(queue_name), expiry_key(queue_name), active_key(queue_name)],
+          argv: [current_timestamp]
+        )
+
+        {waiting: waiting, active: active}
+      end
+
+      private
+
+      def queue_key(queue_name)
+        "#{KEY_PREFIX}:queue:#{queue_name}"
+      end
+
+      def expiry_key(queue_name)
+        "#{KEY_PREFIX}:waiting_expiry:#{queue_name}"
+      end
+
+      def active_key(queue_name)
+        "#{KEY_PREFIX}:active:#{queue_name}"
+      end
+
+      def current_timestamp
+        ::Time.now.to_f
+      end
+
+      def eval_script(name, keys:, argv:)
+        with_redis do |redis|
+          redis.eval(LUA_SCRIPTS[name], keys: keys, argv: argv)
+        end
+      end
+
+      def with_redis
+        yield @redis
+      rescue ::Redis::CannotConnectError, ::Redis::ConnectionError, ::Redis::TimeoutError => e
+        raise ConnectionError,
+          "Waitmate could not reach Redis (#{e.class}: #{e.message}). " \
+          "Verify REDIS_URL or the configured Redis server."
+      rescue ::Redis::BaseError => e
+        raise Error, "Waitmate Redis store error (#{e.class}: #{e.message})"
+      end
+    end
+  end
+end