waitmate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 30977673b611b02e63ff8fe02255181639bf00b51a09a23746deeea6328fc57a
+  data.tar.gz: 17ca45a6543aa8dd96376c0f77c10e4bf45908b4b20dc1ae5627fa01a4bb4322
+SHA512:
+  metadata.gz: 05f4fdb33d0ad3f340425d81b872f8a1c07c851ea25d265bbd74238631ec94521fe8e86c512396c47627bb65ed2e9d146ce72ad7de9983a318754ccd40f064be
+  data.tar.gz: 5377f2ff5b718989ec0a3c67decb03c221470eb31f15c12a355202df85a5e102930af84c1df21ff6964cce83688b1957d2a1c67bf683d48509e7f094f851d163

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BartOz
+
+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,136 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset=".github/waitmate_logo_dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset=".github/waitmate_logo_light.svg">
+    <img alt="Waitmate" src=".github/waitmate_logo_light.svg" width="220">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="https://github.com/bart-oz/waitmate/releases"><img src="https://img.shields.io/badge/version-0.1.0-blue.svg" alt="Version"></a>
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+  <a href="https://github.com/bart-oz/waitmate/actions"><img src="https://img.shields.io/badge/tests-passing-brightgreen.svg" alt="Tests"></a>
+  <a href="https://github.com/bart-oz/waitmate/actions"><img src="https://img.shields.io/badge/coverage-96.36%25-brightgreen.svg" alt="Coverage"></a>
+</p>
+
+---
+
+Virtual waiting room for Rails applications.
+
+Waitmate protects expensive controller actions from thundering-herd overload by queuing overflow users, issuing encrypted admission tickets, and letting users wait on a lightweight Engine-provided page.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "waitmate"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Mount the engine in your routes:
+
+```ruby
+mount Waitmate::Engine => "/waitmate"
+```
+
+Run the install generator to create an initializer:
+
+```bash
+rails generate waitmate:install
+```
+
+This copies `config/initializers/waitmate.rb` with the current defaults.
+
+## Configuration
+
+All config keys and their defaults:
+
+```ruby
+Waitmate.configure do |config|
+  config.adapter = :redis              # :redis or :solid_cache
+  config.queue_ttl = 300             # seconds before abandoned queue entries expire
+  config.polling_interval = 5        # seconds between queue status polls
+  config.ticket_ttl = 120            # seconds before admission tickets expire
+  config.waiting_room_path = "/waitmate/room" # Engine path for the waiting-room page
+end
+```
+
+- `adapter` — Storage backend. `:redis` is primary; `:solid_cache` is the SQL fallback.
+- `queue_ttl` — Time-to-live for a queue entry. Each successful poll extends the TTL.
+- `polling_interval` — How often the browser asks for its position.
+- `ticket_ttl` — How long an issued admission ticket remains valid.
+- `waiting_room_path` — The URL the waiting-room controller renders. Must match the `mount` path in the host routes plus the engine's `/room` route.
+
+### Choosing an adapter
+
+- **Redis (`:redis`)** — Best for high-traffic or latency-sensitive rooms. Each poll is roughly O(1) for the requesting user.
+- **Solid Cache (`:solid_cache`)** — Best when you want a Rails/Solid Stack setup without running Redis. It keeps the same queue correctness contract, but throughput depends on your database. Each poll materializes the waiting rows for that queue to compute a position, so it becomes the throughput bottleneck for large or long queues.
+
+For Solid Cache, install and migrate Solid Cache first, then set `config.adapter = :solid_cache`. Use Redis when you need the highest concurrency; use Solid Cache when simpler Rails-only operations matter more.
+
+## Usage
+
+```ruby
+class TicketsController < ApplicationController
+  wait_room :purchase, max_concurrent: 100
+end
+```
+
+### Waiting-room flow
+
+1. The first request to a protected action is enqueued. If capacity is available, the action runs immediately.
+2. When the action is at capacity, Waitmate issues an encrypted ticket and redirects the browser to the Engine waiting room (`/waitmate/room` by default, controlled by `config.waiting_room_path`).
+3. The waiting room verifies the ticket against the user's session and queue, then polls the `/waitmate/room/position` endpoint every `polling_interval` seconds (default 5). Each poll extends the queue entry's TTL.
+4. When the user's position reaches 0, the waiting room redirects back to the original target URL with the ticket. The concern re-verifies the ticket and admits the user.
+5. Invalid tickets or unsafe targets show a generic, safe error page with no raw tickets, session IDs, queue internals, or adapter errors.
+
+Tickets expire after `ticket_ttl` seconds (default 120). If a user waits longer than the ticket TTL without a successful poll, the ticket becomes invalid and the waiting room shows the generic error page; the user must refresh or re-enter the protected action to obtain a new ticket.
+
+### Overriding the waiting-room view
+
+Hosts can replace the default waiting-room page by creating:
+
+```
+app/views/waitmate/rooms/show.html.erb
+```
+
+The controller sets the following instance variables:
+
+- `@position` — the user's current queue position (`0` means admitted; `nil` on the error path).
+- `@polling_interval` — value of `config.polling_interval`.
+- `@ticket` — the encrypted ticket string.
+- `@queue` — the queue name.
+- `@target` — the validated target URL to return to after admission.
+- `@error` — `true` on the invalid-ticket / unsafe-target path, otherwise unset.
+
+On the normal waiting path, all of the above except `@error` are present. On the error path, only `@error`, `@position` (nil), and `@polling_interval` are guaranteed. Override templates must not assume `@ticket`, `@queue`, or `@target` exist when `@error` is truthy.
+
+### Polling interval and Solid Cache caveat
+
+`polling_interval` controls how often the browser asks for its queue position. Lower intervals feel more responsive but generate more requests.
+
+The Redis adapter answers each poll in roughly O(1) time for the requesting user. The Solid Cache adapter, by design, must scan and rank waiting rows to compute a position, so each poll materializes the waiting rows for that queue. This is acceptable for moderate traffic but becomes the throughput bottleneck for large or long queues. Use Redis when polling latency and queue depth matter.
+
+## Limitations (v0.1)
+
+- **Transport:** HTTP polling only. ActionCable/Turbo Streams are deferred to a future release.
+- **Integration:** Controller concern only. No Rack middleware.
+- **Storage:** Redis and Solid Cache only. No additional adapters.
+- **Framework:** Rails-only. No standalone Rack or non-Rails support.
+- **UI:** A single, overridable ERB waiting-room page. No admin dashboard, CAPTCHA, or anti-bot functionality.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bin/quality` to run the full gate suite: RSpec, StandardRB, appraisal runs against Rails 7.1/7.2/8.0, and `bundler-audit`.
+
+Use `bin/quality --skip-appraisal` for a fast inner-loop check that skips the Rails-version matrix.
+
+## License
+
+Released under the MIT License.

data/app/controllers/waitmate/application_controller.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Waitmate
+  class ApplicationController < ActionController::Base
+    layout false
+  end
+end

data/app/controllers/waitmate/rooms_controller.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Waitmate
+  class RoomsController < ApplicationController
+    include TargetValidation
+
+    before_action :verify_ticket, only: [:show]
+
+    def show
+      pos = current_position
+      return render_invalid if pos.nil?
+
+      if pos == 0
+        url = admission_url
+        return redirect_to(url) if url
+        return render_invalid
+      end
+
+      @position = pos
+      @polling_interval = Waitmate.configuration.polling_interval
+      @ticket = ticket_param
+      @queue = queue_param
+      @target = validated_target
+    end
+
+    def position
+      result = Ticket.verify(token: ticket_param, queue_name: queue_param, session_id: session.id.to_s)
+      return render_position_json(position: nil, admitted: false) unless result.success?
+
+      Store.heartbeat(queue_param, session.id.to_s)
+      pos = Store.position(queue_param, session.id.to_s)
+
+      render_position_json(position: pos, admitted: pos == 0)
+    end
+
+    private
+
+    def verify_ticket
+      result = Ticket.verify(token: ticket_param, queue_name: queue_param, session_id: session.id.to_s)
+      return render_invalid unless result.success?
+
+      Store.heartbeat(queue_param, session.id.to_s)
+    end
+
+    def current_position
+      Store.position(queue_param, session.id.to_s)
+    end
+
+    def render_invalid
+      @error = true
+      @position = nil
+      @polling_interval = Waitmate.configuration.polling_interval
+      render "waitmate/rooms/show", status: :ok
+    end
+
+    def render_position_json(position:, admitted:)
+      render json: {
+        position: position,
+        admitted: admitted,
+        retry: Waitmate.configuration.polling_interval
+      }, status: :ok, headers: private_cache_headers
+    end
+
+    def admission_url
+      target = validated_target
+      return nil unless target
+
+      separator = target.include?("?") ? "&" : "?"
+      query = {ticket: ticket_param}.to_query
+      "#{target}#{separator}#{query}"
+    end
+
+    def ticket_param
+      params[:ticket].to_s
+    end
+
+    def queue_param
+      params[:queue].to_s
+    end
+
+    def target_param
+      params[:target].to_s
+    end
+
+    def validated_target
+      @validated_target ||= target_param if valid_waiting_room_target?(target_param)
+    end
+
+    def private_cache_headers
+      interval = Waitmate.configuration.polling_interval
+      {
+        "Cache-Control" => "private, max-age=#{[interval - 1, 0].max}",
+        "Pragma" => "no-cache"
+      }
+    end
+  end
+end

data/app/views/waitmate/rooms/show.html.erb

@@ -0,0 +1,350 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Waiting Room</title>
+  <style>
+    :root {
+      --wm-bg: #ffffff;
+      --wm-text: #111827;
+      --wm-muted: #6b7280;
+      --wm-rule: #d1d5db;
+      --wm-accent: #2563eb;
+      --wm-success: #15803d;
+      --wm-danger: #b91c1c;
+      --wm-focus: #1d4ed8;
+      --wm-shell-max: 640px;
+      --wm-radius: 14px;
+      --wm-space-2: 8px;
+      --wm-space-3: 12px;
+      --wm-space-4: 16px;
+      --wm-space-6: 24px;
+      --wm-space-8: 32px;
+      --wm-space-10: 40px;
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    body {
+      margin: 0;
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      background: var(--wm-bg);
+      color: var(--wm-text);
+      line-height: 1.5;
+    }
+
+    .wm-room {
+      min-height: 100vh;
+      display: grid;
+      place-items: center;
+      padding: var(--wm-space-6);
+    }
+
+    .wm-room__shell {
+      width: min(100%, var(--wm-shell-max));
+      padding: var(--wm-space-10);
+      border: 1px solid var(--wm-rule);
+      border-radius: var(--wm-radius);
+      text-align: center;
+    }
+
+    .wm-room__badge {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--wm-space-2);
+      padding: var(--wm-space-2) var(--wm-space-3);
+      border-radius: 999px;
+      border: 1px solid var(--wm-rule);
+      font-size: 0.875rem;
+      font-weight: 500;
+      color: var(--wm-muted);
+    }
+
+    .wm-room__badge-dot {
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      background: var(--wm-accent);
+    }
+
+    .wm-room__title {
+      margin: var(--wm-space-6) 0 var(--wm-space-4);
+      font-size: 2rem;
+      font-weight: 700;
+      line-height: 1.2;
+    }
+
+    .wm-room__metric {
+      margin: var(--wm-space-6) 0;
+      padding: var(--wm-space-6) 0;
+      border-top: 1px solid var(--wm-rule);
+      border-bottom: 1px solid var(--wm-rule);
+    }
+
+    .wm-room__metric-label {
+      display: block;
+      font-size: 0.875rem;
+      color: var(--wm-muted);
+      margin-bottom: var(--wm-space-2);
+    }
+
+    .wm-room__metric-value {
+      display: block;
+      font-size: 4rem;
+      font-weight: 700;
+      line-height: 1;
+      color: var(--wm-text);
+    }
+
+    .wm-room__message {
+      margin: 0 0 var(--wm-space-6);
+      color: var(--wm-muted);
+      font-size: 1rem;
+    }
+
+    .wm-room__actions {
+      display: flex;
+      justify-content: center;
+      gap: var(--wm-space-3);
+    }
+
+    .wm-room__rule {
+      border: none;
+      border-top: 1px solid var(--wm-rule);
+    }
+
+    .wm-room__button {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      padding: var(--wm-space-3) var(--wm-space-4);
+      border: 1px solid var(--wm-rule);
+      border-radius: var(--wm-radius);
+      background: var(--wm-bg);
+      color: var(--wm-text);
+      font-size: 1rem;
+      font-weight: 500;
+      text-decoration: none;
+      cursor: pointer;
+    }
+
+    .wm-room__button:focus {
+      outline: 2px solid var(--wm-focus);
+      outline-offset: 3px;
+    }
+
+    .wm-room__button[hidden] {
+      display: none;
+    }
+
+    .wm-room__progress {
+      height: 2px;
+      margin-top: var(--wm-space-6);
+      background: var(--wm-accent);
+      border-radius: 1px;
+      transform: translateX(-100%);
+      animation: wm-progress 1000ms cubic-bezier(0.4, 0, 0.2, 1) infinite;
+    }
+
+    .wm-room__progress[hidden] {
+      display: none;
+    }
+
+    @keyframes wm-progress {
+      from { transform: translateX(-100%); }
+      to { transform: translateX(100%); }
+    }
+
+    .is-admitted .wm-room__badge-dot {
+      background: var(--wm-success);
+    }
+
+    .is-error .wm-room__badge-dot {
+      background: var(--wm-danger);
+    }
+
+    .is-admitted .wm-room__progress {
+      display: block;
+    }
+
+    .is-error .wm-room__metric,
+    .is-error .wm-room__progress,
+    .is-admitted[hidden] {
+      display: none;
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .wm-room__progress {
+        animation: none;
+        transform: none;
+      }
+    }
+
+    @media (max-width: 520px) {
+      .wm-room__shell {
+        padding: var(--wm-space-6);
+      }
+
+      .wm-room__title {
+        font-size: 1.75rem;
+      }
+
+      .wm-room__metric-value {
+        font-size: 3.5rem;
+      }
+
+      .wm-room__actions {
+        flex-direction: column;
+      }
+
+      .wm-room__button {
+        width: 100%;
+      }
+    }
+  </style>
+</head>
+<body class="wm-room">
+  <main class="wm-room__shell <%= @error ? "is-error" : "is-queued" %>" aria-labelledby="wm-room-title">
+    <div class="wm-room__badge">
+      <span class="wm-room__badge-dot"></span>
+      <span class="wm-room__badge-text" id="wm-badge-text">
+        <%= @error ? "Retrying" : "Waiting" %>
+      </span>
+    </div>
+
+    <h1 id="wm-room-title" class="wm-room__title">
+      <%= @error ? "Still holding your place" : "You're in line" %>
+    </h1>
+
+    <div class="wm-room__metric" id="wm-metric" aria-live="polite" <% if @error %>hidden<% end %>>
+      <span class="wm-room__metric-label">Place in line</span>
+      <span class="wm-room__metric-value" id="wm-position"><%= @position %></span>
+    </div>
+
+    <p class="wm-room__message" id="wm-message">
+      <% if @error %>
+        We couldn't update your place. We'll try again shortly.
+      <% else %>
+        Keep this tab open — we'll send you through automatically.
+      <% end %>
+    </p>
+
+    <div class="wm-room__actions">
+      <button class="wm-room__button" id="wm-retry" <% unless @error %>hidden<% end %>>Retry now</button>
+      <a class="wm-room__button" id="wm-continue" href="#" hidden>Continue</a>
+    </div>
+
+    <div class="wm-room__progress" id="wm-progress" hidden></div>
+  </main>
+
+  <% unless @error %>
+    <script>
+      (function() {
+        var shell = document.querySelector('.wm-room__shell');
+        var badgeText = document.getElementById('wm-badge-text');
+        var title = document.getElementById('wm-room-title');
+        var metric = document.getElementById('wm-metric');
+        var positionEl = document.getElementById('wm-position');
+        var message = document.getElementById('wm-message');
+        var retryBtn = document.getElementById('wm-retry');
+        var continueLink = document.getElementById('wm-continue');
+        var progress = document.getElementById('wm-progress');
+
+        var target = <%= raw json_escape(@target.to_json) %>;
+        var ticket = <%= raw json_escape(@ticket.to_json) %>;
+        var pollUrl = <%= raw json_escape(room_position_path(ticket: @ticket, queue: @queue).to_json) %>;
+        var interval = <%= Waitmate.configuration.polling_interval * 1000 %>;
+
+        var timer = null;
+
+        function setState(state) {
+          shell.classList.remove('is-queued', 'is-admitted', 'is-error');
+          shell.classList.add('is-' + state);
+        }
+
+        function navigateToTarget() {
+          var separator = target.indexOf('?') === -1 ? '?' : '&';
+          window.location.href = target + separator + 'ticket=' + encodeURIComponent(ticket);
+        }
+
+        function schedule() {
+          clearTimeout(timer);
+          var jitter = interval * (0.8 + Math.random() * 0.4);
+          timer = setTimeout(poll, jitter);
+        }
+
+        function showQueued(position) {
+          setState('queued');
+          badgeText.textContent = 'Waiting';
+          title.textContent = "You're in line";
+          metric.hidden = false;
+          positionEl.textContent = position;
+          message.textContent = 'Keep this tab open — we'll send you through automatically.';
+          retryBtn.hidden = true;
+          continueLink.hidden = true;
+          progress.hidden = true;
+        }
+
+        function showAdmitted() {
+          setState('admitted');
+          badgeText.textContent = 'Admitted';
+          title.textContent = "You're next";
+          metric.hidden = true;
+          message.textContent = 'Redirecting you now…';
+          retryBtn.hidden = true;
+          continueLink.hidden = false;
+          continueLink.href = target + (target.indexOf('?') === -1 ? '?' : '&') + 'ticket=' + encodeURIComponent(ticket);
+          progress.hidden = false;
+          navigateToTarget();
+        }
+
+        function showError() {
+          setState('error');
+          badgeText.textContent = 'Retrying';
+          title.textContent = 'Still holding your place';
+          metric.hidden = true;
+          message.textContent = "We couldn't update your place. We'll try again shortly.";
+          retryBtn.hidden = false;
+          continueLink.hidden = true;
+          progress.hidden = true;
+        }
+
+        function poll() {
+          fetch(pollUrl, {headers: {'Accept': 'application/json'}})
+            .then(function(response) { return response.json(); })
+            .then(function(data) {
+              if (data.admitted) {
+                showAdmitted();
+              } else if (data.position === null) {
+                showError();
+                schedule();
+              } else {
+                showQueued(data.position);
+                schedule();
+              }
+            })
+            .catch(function() {
+              showError();
+              schedule();
+            });
+        }
+
+        retryBtn.addEventListener('click', function() {
+          showQueued(positionEl.textContent || '—');
+          poll();
+        });
+
+        continueLink.addEventListener('click', function(event) {
+          event.preventDefault();
+          navigateToTarget();
+        });
+
+        schedule();
+      })();
+    </script>
+  <% end %>
+</body>
+</html>