userpattern 0.2.0

data/app/assets/stylesheets/user_pattern/dashboard.css

@@ -0,0 +1,169 @@
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  background: #f5f7fa;
+  color: #1a1a2e;
+  line-height: 1.5;
+  padding: 2rem;
+}
+
+.container { max-width: 1200px; margin: 0 auto; }
+
+header {
+  display: flex;
+  align-items: baseline;
+  gap: 1rem;
+  margin-bottom: 2rem;
+}
+
+header h1 { font-size: 1.6rem; font-weight: 700; }
+header .version { color: #888; font-size: 0.85rem; }
+
+.mode-badge {
+  font-size: 0.75rem;
+  font-weight: 600;
+  padding: 0.2rem 0.6rem;
+  border-radius: 4px;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+
+.mode-badge.collection { background: #dbeafe; color: #1d4ed8; }
+.mode-badge.alert { background: #fee2e2; color: #dc2626; }
+
+.page-tabs {
+  display: flex;
+  gap: 0.5rem;
+  margin-bottom: 1.5rem;
+}
+
+.page-tabs a {
+  display: inline-block;
+  padding: 0.5rem 1.25rem;
+  text-decoration: none;
+  color: #555;
+  font-weight: 600;
+  background: #e2e8f0;
+  border-radius: 6px 6px 0 0;
+  transition: color 0.15s, background 0.15s;
+}
+
+.page-tabs a:hover { background: #cbd5e1; color: #1a1a2e; }
+.page-tabs a.active { background: #fff; color: #2563eb; }
+
+.tabs {
+  display: flex;
+  gap: 0.25rem;
+  margin-bottom: 1.5rem;
+  border-bottom: 2px solid #e0e0e0;
+}
+
+.tabs a {
+  display: inline-block;
+  padding: 0.5rem 1.25rem;
+  text-decoration: none;
+  color: #555;
+  font-weight: 500;
+  border-bottom: 2px solid transparent;
+  margin-bottom: -2px;
+  transition: color 0.15s, border-color 0.15s;
+}
+
+.tabs a:hover { color: #1a1a2e; }
+.tabs a.active { color: #2563eb; border-bottom-color: #2563eb; }
+
+.filter-bar {
+  display: flex;
+  gap: 0.5rem;
+  margin-bottom: 1.5rem;
+}
+
+.filter-bar a {
+  display: inline-block;
+  padding: 0.35rem 0.9rem;
+  text-decoration: none;
+  color: #555;
+  font-size: 0.85rem;
+  font-weight: 500;
+  background: #e2e8f0;
+  border-radius: 4px;
+  transition: color 0.15s, background 0.15s;
+}
+
+.filter-bar a:hover { background: #cbd5e1; }
+.filter-bar a.active { background: #2563eb; color: #fff; }
+
+.card {
+  background: #fff;
+  border-radius: 8px;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.08);
+  overflow-x: auto;
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.9rem;
+}
+
+thead { background: #f8fafc; }
+
+th, td {
+  padding: 0.75rem 1rem;
+  text-align: left;
+  border-bottom: 1px solid #eee;
+  white-space: nowrap;
+}
+
+th {
+  font-weight: 600;
+  color: #475569;
+  cursor: pointer;
+  user-select: none;
+}
+
+th:hover { color: #2563eb; }
+
+th .arrow {
+  display: inline-block;
+  margin-left: 4px;
+  font-size: 0.7rem;
+  color: #94a3b8;
+}
+
+th.sorted-asc .arrow::after { content: "\25B2"; color: #2563eb; }
+th.sorted-desc .arrow::after { content: "\25BC"; color: #2563eb; }
+th:not(.sorted-asc):not(.sorted-desc) .arrow::after { content: "\25B4\25BE"; }
+
+td.endpoint { font-family: "SF Mono", Monaco, "Cascadia Code", monospace; font-size: 0.85rem; }
+td.mono { font-family: "SF Mono", Monaco, "Cascadia Code", monospace; font-size: 0.85rem; color: #64748b; }
+
+td.num { text-align: right; font-variant-numeric: tabular-nums; }
+th.num { text-align: right; }
+
+td.threshold { color: #9333ea; font-weight: 500; }
+td.violation-exceeded { color: #dc2626; font-weight: 600; }
+
+tbody tr:hover { background: #f1f5f9; }
+tr.violation-row:hover { background: #fef2f2; }
+
+.empty-state {
+  text-align: center;
+  padding: 4rem 2rem;
+  color: #94a3b8;
+}
+
+.empty-state code {
+  background: #f1f5f9;
+  padding: 0.15rem 0.4rem;
+  border-radius: 3px;
+  font-size: 0.85rem;
+}
+
+.footer {
+  margin-top: 1.5rem;
+  font-size: 0.8rem;
+  color: #94a3b8;
+  text-align: center;
+}

data/app/controllers/user_pattern/dashboard_controller.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'userpattern/stats_calculator'
+
+module UserPattern
+  class DashboardController < ActionController::Base
+    before_action :authenticate_dashboard!
+    layout false
+
+    def index
+      UserPattern.buffer.flush
+      load_stats
+      apply_sort!
+    end
+
+    def violations
+      @violations = Violation
+                    .recent(params[:days]&.to_i || 7)
+                    .order(occurred_at: :desc)
+      @violations = @violations.where(model_type: params[:model_type]) if params[:model_type].present?
+    end
+
+    def stylesheet
+      css_path = UserPattern::Engine.root.join('app', 'assets', 'stylesheets', 'user_pattern', 'dashboard.css')
+      expires_in 1.hour, public: true
+      render plain: css_path.read, content_type: 'text/css'
+    end
+
+    private
+
+    def load_stats
+      @stats = UserPattern::StatsCalculator.compute_all
+      @model_types = @stats.map { |s| s[:model_type] }.uniq.sort
+      @selected_model = params[:model_type].presence || @model_types.first
+      @filtered_stats = @stats.select { |s| s[:model_type] == @selected_model }
+      @alert_mode = UserPattern.configuration.alert_mode?
+      @threshold_limits = load_threshold_limits
+    end
+
+    def load_threshold_limits
+      return {} unless @alert_mode && UserPattern.threshold_cache
+
+      UserPattern.threshold_cache.all_limits
+    end
+
+    def authenticate_dashboard!
+      instance_exec(&UserPattern.configuration.dashboard_auth)
+    end
+
+    def apply_sort!
+      sort_key = params[:sort]&.to_sym
+      return unless sort_key && @filtered_stats.first&.key?(sort_key)
+
+      @filtered_stats.sort_by! { |s| s[sort_key] || 0 }
+      @filtered_stats.reverse! unless params[:dir] == 'asc'
+    end
+  end
+end

data/app/models/user_pattern/request_event.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module UserPattern
+  class RequestEvent < ActiveRecord::Base
+    self.table_name = 'userpattern_request_events'
+
+    scope :expired, lambda {
+      where('recorded_at < ?', UserPattern.configuration.retention_period.days.ago)
+    }
+  end
+end

data/app/models/user_pattern/violation.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module UserPattern
+  class Violation < ActiveRecord::Base
+    self.table_name = 'userpattern_violations'
+
+    scope :recent, ->(days = 7) { where('occurred_at > ?', days.days.ago) }
+  end
+end

data/app/views/user_pattern/dashboard/index.html.erb

@@ -0,0 +1,116 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>UserPattern — Usage Dashboard</title>
+  <link rel="stylesheet" href="<%= user_pattern.stylesheet_path %>">
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1>UserPattern</h1>
+      <span class="version">v<%= UserPattern::VERSION %></span>
+      <% if @alert_mode %>
+        <span class="mode-badge alert">Alert Mode</span>
+      <% else %>
+        <span class="mode-badge collection">Collection Mode</span>
+      <% end %>
+    </header>
+
+    <nav class="page-tabs">
+      <a href="<%= user_pattern.root_path %>" class="active">Usage</a>
+      <a href="<%= user_pattern.violations_path %>">Violations</a>
+    </nav>
+
+    <% if @model_types.any? %>
+      <nav class="tabs">
+        <% @model_types.each do |mt| %>
+          <a href="<%= user_pattern.root_path(model_type: mt) %>"
+             class="<%= 'active' if mt == @selected_model %>">
+            <%= mt %>
+          </a>
+        <% end %>
+      </nav>
+    <% end %>
+
+    <div class="card">
+      <% if @filtered_stats.present? %>
+        <table id="stats-table">
+          <thead>
+            <tr>
+              <%
+                columns = [
+                  { key: "endpoint",        label: "Endpoint",      numeric: false },
+                  { key: "total_requests",  label: "Total Reqs",    numeric: true },
+                  { key: "total_sessions",  label: "Sessions",      numeric: true },
+                  { key: "avg_per_session", label: "Avg / Session", numeric: true },
+                  { key: "avg_per_minute",  label: "Avg / Min",     numeric: true },
+                  { key: "max_per_minute",  label: "Max / Min",     numeric: true },
+                  { key: "max_per_hour",    label: "Max / Hour",    numeric: true },
+                  { key: "max_per_day",     label: "Max / Day",     numeric: true },
+                ]
+
+                current_sort = params[:sort]
+                current_dir  = params[:dir] || "desc"
+              %>
+              <% columns.each do |col| %>
+                <%
+                  is_sorted = current_sort == col[:key]
+                  next_dir  = is_sorted && current_dir == "desc" ? "asc" : "desc"
+                  css_class = []
+                  css_class << "num" if col[:numeric]
+                  css_class << "sorted-#{current_dir}" if is_sorted
+                %>
+                <th class="<%= css_class.join(' ') %>">
+                  <a href="<%= user_pattern.root_path(model_type: @selected_model, sort: col[:key], dir: next_dir) %>"
+                     style="text-decoration:none; color:inherit;">
+                    <%= col[:label] %><span class="arrow"></span>
+                  </a>
+                </th>
+              <% end %>
+              <% if @alert_mode %>
+                <th class="num">Limit / Min</th>
+                <th class="num">Limit / Hour</th>
+                <th class="num">Limit / Day</th>
+              <% end %>
+            </tr>
+          </thead>
+          <tbody>
+            <% @filtered_stats.each do |stat| %>
+              <% limits = @threshold_limits[[@selected_model, stat[:endpoint]]] || {} %>
+              <tr>
+                <td class="endpoint"><%= stat[:endpoint] %></td>
+                <td class="num"><%= stat[:total_requests] %></td>
+                <td class="num"><%= stat[:total_sessions] %></td>
+                <td class="num"><%= stat[:avg_per_session] %></td>
+                <td class="num"><%= stat[:avg_per_minute] %></td>
+                <td class="num"><%= stat[:max_per_minute] %></td>
+                <td class="num"><%= stat[:max_per_hour] %></td>
+                <td class="num"><%= stat[:max_per_day] %></td>
+                <% if @alert_mode %>
+                  <td class="num threshold"><%= limits[:per_minute] || "—" %></td>
+                  <td class="num threshold"><%= limits[:per_hour] || "—" %></td>
+                  <td class="num threshold"><%= limits[:per_day] || "—" %></td>
+                <% end %>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      <% else %>
+        <div class="empty-state">
+          <p>No data collected yet for <strong><%= @selected_model || "any model" %></strong>.</p>
+          <p>Requests from logged-in users will appear here automatically.</p>
+        </div>
+      <% end %>
+    </div>
+
+    <p class="footer">
+      Data retained for <%= UserPattern.configuration.retention_period %> days
+      &middot;
+      <% total_events = UserPattern::RequestEvent.count %>
+      <%= total_events %> event<%= total_events == 1 ? "" : "s" %> in store
+    </p>
+  </div>
+</body>
+</html>

data/app/views/user_pattern/dashboard/violations.html.erb

@@ -0,0 +1,79 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>UserPattern — Violations</title>
+  <link rel="stylesheet" href="<%= user_pattern.stylesheet_path %>">
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1>UserPattern</h1>
+      <span class="version">v<%= UserPattern::VERSION %></span>
+      <% if UserPattern.configuration.alert_mode? %>
+        <span class="mode-badge alert">Alert Mode</span>
+      <% else %>
+        <span class="mode-badge collection">Collection Mode</span>
+      <% end %>
+    </header>
+
+    <nav class="page-tabs">
+      <a href="<%= user_pattern.root_path %>">Usage</a>
+      <a href="<%= user_pattern.violations_path %>" class="active">Violations</a>
+    </nav>
+
+    <div class="filter-bar">
+      <% [7, 14, 30].each do |days| %>
+        <a href="<%= user_pattern.violations_path(days: days) %>"
+           class="<%= 'active' if (params[:days]&.to_i || 7) == days %>">
+          Last <%= days %> days
+        </a>
+      <% end %>
+    </div>
+
+    <div class="card">
+      <% if @violations.any? %>
+        <table id="violations-table">
+          <thead>
+            <tr>
+              <th>Endpoint</th>
+              <th>Model</th>
+              <th>Period</th>
+              <th class="num">Count</th>
+              <th class="num">Limit</th>
+              <th>User (hashed)</th>
+              <th>Occurred At</th>
+            </tr>
+          </thead>
+          <tbody>
+            <% @violations.each do |v| %>
+              <tr class="violation-row">
+                <td class="endpoint"><%= v.endpoint %></td>
+                <td><%= v.model_type %></td>
+                <td><%= v.period %></td>
+                <td class="num violation-exceeded"><%= v.count %></td>
+                <td class="num"><%= v.limit %></td>
+                <td class="mono"><%= v.user_identifier[0, 8] %>&hellip;</td>
+                <td><%= v.occurred_at.strftime("%Y-%m-%d %H:%M:%S") %></td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      <% else %>
+        <div class="empty-state">
+          <p>No violations recorded in the selected period.</p>
+          <% unless UserPattern.configuration.alert_mode? %>
+            <p>Switch to <strong>alert mode</strong> and enable <code>:record</code> in <code>violation_actions</code> to capture violations.</p>
+          <% end %>
+        </div>
+      <% end %>
+    </div>
+
+    <p class="footer">
+      <% total_violations = UserPattern::Violation.count %>
+      <%= total_violations %> total violation<%= total_violations == 1 ? "" : "s" %> on record
+    </p>
+  </div>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+UserPattern::Engine.routes.draw do
+  get 'stylesheet', to: 'dashboard#stylesheet', as: :stylesheet
+  get 'violations', to: 'dashboard#violations', as: :violations
+  root to: 'dashboard#index'
+end

data/lib/generators/userpattern/install_generator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Userpattern
+  class InstallGenerator < Rails::Generators::Base
+    include ActiveRecord::Generators::Migration
+
+    source_root File.expand_path('templates', __dir__)
+
+    desc 'Install UserPattern: creates the initializer and migrations.'
+
+    def copy_initializer
+      template 'initializer.rb', 'config/initializers/userpattern.rb'
+    end
+
+    def copy_request_events_migration
+      migration_template(
+        'create_userpattern_request_events.rb.erb',
+        'db/migrate/create_userpattern_request_events.rb'
+      )
+    end
+
+    def copy_violations_migration
+      migration_template(
+        'create_userpattern_violations.rb.erb',
+        'db/migrate/create_userpattern_violations.rb'
+      )
+    end
+
+    def mount_engine
+      route 'mount UserPattern::Engine, at: "/userpatterns"'
+    end
+
+    def display_post_install
+      say ''
+      say 'UserPattern installed! Next steps:', :green
+      say '  1. Run `rails db:migrate`'
+      say '  2. Edit config/initializers/userpattern.rb to configure tracked models'
+      say '  3. Set USERPATTERN_DASHBOARD_USER and USERPATTERN_DASHBOARD_PASSWORD env vars'
+      say '  4. Visit /userpatterns to see the dashboard'
+      say ''
+    end
+  end
+end

data/lib/generators/userpattern/templates/create_userpattern_request_events.rb.erb

@@ -0,0 +1,23 @@
+class CreateUserpatternRequestEvents < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :userpattern_request_events do |t|
+      t.string   :model_type,           null: false
+      t.string   :endpoint,             null: false
+      t.string   :anonymous_session_id, null: false
+      t.datetime :recorded_at,          null: false
+      t.datetime :created_at,           null: false
+    end
+
+    add_index :userpattern_request_events,
+              [:model_type, :endpoint, :recorded_at],
+              name: "idx_up_model_endpoint_time"
+
+    add_index :userpattern_request_events,
+              [:model_type, :endpoint, :anonymous_session_id],
+              name: "idx_up_model_endpoint_session"
+
+    add_index :userpattern_request_events,
+              :recorded_at,
+              name: "idx_up_recorded_at"
+  end
+end

data/lib/generators/userpattern/templates/create_userpattern_violations.rb.erb

@@ -0,0 +1,22 @@
+class CreateUserpatternViolations < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :userpattern_violations do |t|
+      t.string   :model_type,      null: false
+      t.string   :endpoint,        null: false
+      t.string   :period,          null: false
+      t.integer  :count,           null: false
+      t.integer  :limit,           null: false
+      t.string   :user_identifier, null: false
+      t.datetime :occurred_at,     null: false
+      t.datetime :created_at,      null: false
+    end
+
+    add_index :userpattern_violations,
+              %i[model_type endpoint],
+              name: 'idx_up_violations_model_endpoint'
+
+    add_index :userpattern_violations,
+              :occurred_at,
+              name: 'idx_up_violations_occurred_at'
+  end
+end

data/lib/generators/userpattern/templates/initializer.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+UserPattern.configure do |config|
+  # ─── Tracked models ────────────────────────────────────────────────
+  # Each entry needs a :name and optionally a :current_method.
+  # If :current_method is omitted, it defaults to :current_<underscored_name>.
+  config.tracked_models = [
+    { name: 'User', current_method: :current_user }
+    # { name: "Admin", current_method: :current_admin },
+  ]
+
+  # ─── Session detection ─────────────────────────────────────────────
+  # How to identify a session for anonymized grouping.
+  #   :auto    – use Authorization header (JWT) if present, otherwise session cookie
+  #   :session – always use session cookie
+  #   :header  – always use Authorization header
+  #   Proc     – custom: ->(request) { request.headers["X-Session-Token"] }
+  config.session_detection = :auto
+
+  # ─── Performance ───────────────────────────────────────────────────
+  # Events are buffered in memory and flushed in batches.
+  # config.buffer_size    = 100   # flush when buffer reaches this size
+  # config.flush_interval = 30    # flush at least every N seconds
+
+  # ─── Data retention ────────────────────────────────────────────────
+  # Raw events older than this are deleted by `rake userpattern:cleanup`.
+  # config.retention_period = 30  # days
+
+  # ─── Dashboard authentication ──────────────────────────────────────
+  # The dashboard is secure by default. Set these environment variables:
+  #   USERPATTERN_DASHBOARD_USER
+  #   USERPATTERN_DASHBOARD_PASSWORD
+  #
+  # Or provide a custom Proc:
+  #   config.dashboard_auth = -> {
+  #     redirect_to main_app.root_path unless current_user&.admin?
+  #   }
+
+  # ─── Mode ──────────────────────────────────────────────────────────
+  # :collection — observe and record usage patterns (default)
+  # :alert      — enforce rate limits derived from observed data
+  # config.mode = :collection
+
+  # ─── Alert mode settings ───────────────────────────────────────────
+  # config.threshold_multiplier = 1.5       # limit = observed_max * multiplier
+  # config.threshold_refresh_interval = 300 # reload limits from DB every N seconds
+  # config.block_unknown_endpoints = false  # allow endpoints not seen during collection
+
+  # Cache store for rate-limiter counters (defaults to Rails.cache).
+  # For multi-process setups, use Redis:
+  # config.rate_limiter_store = ActiveSupport::Cache::RedisCacheStore.new(url: ENV["REDIS_URL"])
+
+  # Actions to take when a threshold is exceeded (combine multiple):
+  #   :raise   — raise ThresholdExceeded (handle via rescue_from)
+  #   :log     — write to Rails.logger
+  #   :record  — persist to userpattern_violations table (visible in dashboard)
+  #   :logout  — call config.logout_method to terminate the session
+  # config.violation_actions = [:raise]
+
+  # Logout method (only used when :logout is in violation_actions):
+  # config.logout_method = ->(controller) { controller.sign_out(controller.current_user) }
+
+  # Optional callback for custom handling (Sentry, Slack, etc.):
+  # config.on_threshold_exceeded = ->(violation) {
+  #   Sentry.capture_message("Rate limit: #{violation.message}")
+  # }
+
+  # ─── Ignored paths ────────────────────────────────────────────────
+  # Paths matching any entry are silently skipped — no event is recorded.
+  # Each entry can be a String (exact match) or a Regexp (pattern match).
+  # Matching is performed against the raw request path (no query string).
+  #
+  # Examples:
+  #   config.ignored_paths = [
+  #     "/health",            # exact match
+  #     "/up",
+  #     %r{\A/api/internal},  # any path starting with /api/internal
+  #   ]
+  # config.ignored_paths = []
+
+  # ─── Enable / disable ─────────────────────────────────────────────
+  # config.enabled = true
+end

data/lib/tasks/userpattern.rake

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+namespace :userpattern do
+  desc 'Remove request events older than the configured retention period'
+  task cleanup: :environment do
+    deleted = UserPattern.cleanup!
+    puts "[UserPattern] Cleaned up #{deleted} expired events."
+  end
+end