rollout-ui 0.9.3 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4af968fe0271d80faec7b339779f81a5b8eb9bd06d23b984c7fb5436384b0593
-  data.tar.gz: 4d4ef32df14c4282b72ea2c5f6a3fee00266dd137ea612b211bcab1e9bc0786f
+  metadata.gz: 8fe93ad84dab349410b8d45fd548837b3c7057db163916ae51af5415f0b6a9bd
+  data.tar.gz: 6b451b50cc1e907a63e94976c103800f26fa6366705ed34e4a31d2faad585507
 SHA512:
-  metadata.gz: 6af36b891a09fcf1f5f22abe858c10c266db3c9c48444d58e3a72f38daa1dfa3e444b7e443857d77261d041540c0533501e9548f1ad6e7582902773b0c399f85
-  data.tar.gz: cbeb563460654cb4405a3f2eaaf515426d92311f0ae3eb32dd8eaeea1455262b86e80acb2379c41556459ab579f8cb779cb8923522bdb0dc42c4ff19d67fb369
+  metadata.gz: '09ad9b11897744854625b4654e7d2a5c543492ac945ad6b91e5359b1c6aad0bab6ba0927781588f4c8b3c16e221597f625cf9acc4ca1e6c208c260d20a6e6ee8'
+  data.tar.gz: 837fa191cde919c0a88f881cc31fe300311026acf7559410f3f23bdc9ffd27c5d6f9644955337d64019c96e2642343837569d8da31648706bdf7a80d411b9bbb

data/.github/workflows/release.yml

@@ -7,7 +7,8 @@ on:
 
 jobs:
   release:
-    runs-on: ubuntu-latest
+    # setup-ruby has no build of the .ruby-version Ruby (3.4.7) for ubuntu-26.04.
+    runs-on: ubuntu-24.04
     permissions:
       contents: write
       id-token: write
@@ -37,7 +38,7 @@ jobs:
 
   github-release:
     needs: release
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     permissions:
       contents: write
     steps:

data/.github/workflows/test.yml

@@ -5,12 +5,11 @@ on:
     branches:
       - master
   pull_request:
-    branches:
-      - master
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    # setup-ruby has no build of the .ruby-version Ruby (3.4.7) for ubuntu-26.04.
+    runs-on: ubuntu-24.04
     services:
       redis:
         image: redis:7-alpine

data/README.md

@@ -1,14 +1,12 @@
 # Rollout::UI
 
-Minimalist UI for the [rollout](https://github.com/fetlife/rollout) gem that
-you can just mount as a Rack app and it will just work.
+A Rack-mountable UI for the [rollout](https://github.com/fetlife/rollout) gem.
 
 ![Index Page](./screenshot_index.png)
 <!-- ![Feature Page](./screenshot_show.png) -->
 
 ## Usage with Rails
 
-
 Add it to your application's Gemfile:
 
 ```ruby
@@ -17,20 +15,20 @@ gem "rollout-redis-adapter", "~> 0.1"
 gem "rollout-ui"
 ```
 
-`rollout-ui` 0.9+ requires Rollout 3.1 and does not support Rollout 2.x. The UI is backend-neutral: applications using Redis should add `rollout-redis-adapter` and pass a configured Rollout instance into the UI.
+`rollout-ui` 0.9+ requires Rollout 3.1 or later within 3.x. It works with any
+Rollout adapter; Redis applications also need `rollout-redis-adapter`.
 
-Mount it
+Mount the Rack app:
 
 ```ruby
 Rails.application.routes.draw do
-  mount Rollout::UI::Web.new => '/admin/rollout'
+  mount Rollout::UI::Web.new => "/admin/rollout"
 
   # ...
 end
 ```
 
-And to configure it with your `Rollout` instance, you can put your configuration
-in `routes.rb` or in a standalone initializer.
+Configure your Rollout instance in `routes.rb` or an initializer:
 
 ```ruby
 Rollout::UI.configure do
@@ -40,12 +38,10 @@ end
 
 ## Authentication
 
-If you are using Rails, you can put `constraints` on your mount.
-
-So in case of usafe with Devise, your constraints might look like:
+Protect the Rails mount with a constraint. For example, with Devise:
 
 ```ruby
-module Constraint::Admin
+class AdminConstraint
   def self.matches?(request)
     id = request.session["warden.user.user.key"].try(:[], 0).try(:[], 0)
     return false if id.blank?
@@ -56,32 +52,119 @@ module Constraint::Admin
 end
 
 Rails.application.routes.draw do
-  mount Rollout::UI::Web.new => '/admin/rollout', constraints: Constraints::Admin
+  mount Rollout::UI::Web.new => "/admin/rollout", constraints: AdminConstraint
 
   # ...
 end
 ```
 
-## Host Header Validation
+## Nickname user selector
 
-This gem performs no Host header validation of its own. When mounted inside a Rails app (as shown above), requests already pass through Rails' own `config.hosts` checks before reaching this mount point.
+Configure **both** callbacks below to replace the user ID field with a searchable
+nickname picker alongside the enrolled-user list. Your application supplies the
+queries; the UI displays nicknames and Rollout stores user IDs. This example
+uses Rails and PostgreSQL:
 
-If you run this as a standalone app (e.g. via `rackup`), you're responsible for host header validation in the same way you're responsible for authentication, for example with
-[`Rack::Protection::HostAuthorization`](https://github.com/sinatra/sinatra/tree/main/rack-protection#host-authorization-api) in front of it, or a reverse proxy that only forwards trusted hosts.
+```ruby
+Rollout::UI.configure do
+  instance { $rollout }
 
-## API Endpoints
+  user_search do |query, limit|
+    prefix = User.sanitize_sql_like(query.downcase) + "%"
+    User.where("lower(nickname) LIKE ?", prefix)
+      .limit(limit)
+      .pluck(:id, :nickname)
+      .map { |id, nickname| { id: id.to_s, nickname: nickname } }
+  end
 
-The index and show routes can also respond with JSON data instead of HTML when the request's `Accept` header is
-`application/json`
+  user_lookup do |ids|
+    User.where(id: ids)
+      .pluck(:id, :nickname)
+      .map { |id, nickname| { id: id.to_s, nickname: nickname } }
+  end
+end
+```
 
-The index route also accepts query parameters to filter by user or group:
-`/admin/rollout?user=someone`
-`/admin/rollout?group=developers`
+Both callbacks return arrays of hashes with `id` and `nickname` keys (symbols or
+strings). `user_search` receives a trimmed nickname query and a result limit.
+`user_lookup` receives a batch of selected or historical user IDs as strings;
+omit missing accounts. Apply your account visibility rules in both callbacks.
+
+Search defaults to **3 characters** and **20 results**, with a 300 ms debounce.
+Override these settings inside the same configuration block:
+
+```ruby
+user_search_min_length { 3 }
+user_search_limit { 20 }
+```
+
+For large directories, use **indexed nickname-only prefix matching** and apply
+the limit in the database. Escape wildcards as above; avoid loading all users or
+running unindexed `%contains%` queries. A matching index for this example is:
+
+```sql
+CREATE INDEX CONCURRENTLY users_nickname_prefix_idx
+  ON users (lower(nickname) text_pattern_ops);
+```
+
+Check the query plan against your schema and collation. The selector supports
+keyboard navigation and preserves pending changes if a lookup fails. The
+enrolled count includes unresolved accounts, shown as `Unknown user` with their
+ID in a separate column, but excludes users enabled through groups or percentage.
+
+### Paginated enrollment editing
+
+Every feature shows a paginated enrollment list with **25 users per page**.
+Rows are ordered by user ID. Nicknames are
+looked up only for the visible page, independently of the bounded history lookup.
+There is no longer a 150-user enrollment editing cutoff.
+
+Remove/Undo and nickname additions are staged until **Update**. With JavaScript,
+switching enrollment pages leaves pending changes and unsaved description,
+groups, and percentage fields intact. A pending-changes callout below the table
+opens a **Review** popover listing additions and removals across all pages. Search marks
+already-enrolled users even when they are on another page. The heading counts
+stored enrollments; pending changes are reported separately until saved.
+
+The form submits additions and removals, not a replacement list from the visible
+page. Delta requests use `user_changes=1` and require a full-state
+`feature_version`; malformed markers and missing versions are rejected. After
+version validation, these deltas are applied to the full membership
+inside `with_feature`. Duplicate additions are idempotent; removals take
+precedence if an ID appears in both sets. Legacy full-list `users` submissions
+remain supported.
+
+Without JavaScript or nickname callbacks, add users using comma-separated IDs
+and check Remove for visible rows. **Update before following page links** to
+avoid discarding unsaved form changes. Enrollment pagination remains available
+when nickname lookup fails; unknown IDs are never silently dropped.
+
+## Concurrent edits
+
+Feature forms include a `feature_version` fingerprint of the editable state:
+percentage, groups, enrolled IDs, and description. Ordering of IDs and groups,
+timestamps, and unrelated metadata do not change the fingerprint. Distinct edits
+in the same second and changes made outside the UI are detected.
+
+Updates validate the submitted fingerprint inside `with_feature`, before changing
+state. A stale submission is rejected without saving state or history, and the
+UI redirects to the latest feature so the administrator can review and retry.
+Older non-delta forms without `feature_version` retain the `last_updated_at`
+timestamp check; that legacy check cannot distinguish same-second edits.
+
+Atomic conflict detection depends on the adapter's mutation guarantees. The
+ActiveRecord adapter locks existing feature rows during `with_feature`. The
+Redis adapter does not provide the equivalent lock or compare-and-set guarantee.
+
+Use uncached feature reads for the Rollout instance supplied to the admin UI.
+Process-local adapter caches can otherwise display an older enrolled list and
+form version after another worker saves. Normal feature evaluation can use a
+separate cached instance with the same group definitions. Feature responses send
+`Cache-Control: no-store`; this does not bypass an adapter's server-side cache.
 
 ## Logging
 
-To get the most out of **rollout-ui**, we recommend you to turn on logging
-on your rollout instance to see history of changes in the UI.
+Enable logging on your Rollout instance to display change history:
 
 ```ruby
 require "redis"
@@ -95,14 +178,12 @@ $rollout = Rollout.new(
 )
 ```
 
-To also see who updated states of your rollouts, you can configure `actor` and
-`actor_url`. So if you are using Rails with Devise, your configuration might
-look like:
+Configure `actor` and `actor_url` to attribute changes. For example, with Devise:
 
 ```ruby
 Rollout::UI.configure do
   instance { $rollout }
-  actor { current_user&.username }
+  actor { current_user&.nickname }
   actor_url { |actor| "/#{actor}" }
 end
 ```
@@ -112,6 +193,46 @@ deletions appear in the overview history with the configured actor. This
 requires global logging (`global: true`); adapters without event-aware deletion
 retain the previous behavior and do not add a deletion event.
 
+With `user_lookup` configured, feature and overview history display current
+nicknames while audit events retain IDs. History resolves up to 150 additional
+distinct IDs per page; missing accounts, failed lookups, and IDs beyond that limit
+use ID-based labels.
+
+## API Endpoints
+
+Send `Accept: application/json` to the index or feature route for JSON responses.
+The index also accepts filters such as `/admin/rollout?user=123` and
+`/admin/rollout?group=developers`.
+
+When both nickname callbacks are configured, `GET /users/search?q=alice`
+(relative to the mount) returns `{"users":[{"id":"123","nickname":"alice"}]}`.
+It uses the mount's authentication, caps results server-side, and sends
+`Cache-Control: no-store`. Queries below the configured minimum return an empty
+list without calling `user_search`. Queries are limited to 100 characters;
+configured minimum lengths and result limits are bounded to 1–100.
+
+`GET /features/:name/users?page=2` returns the visible enrollment
+page, total enrollment count, page metadata, full-state `feature_version`, and
+`lookup_failed`. Pages contain at most 25 users and page numbers are clamped to
+the available range. The response never contains the entire
+membership list and sends `Cache-Control: no-store`.
+
+`GET /features/:name/users/search?q=alice` uses the same nickname callbacks and
+limits, adds an `enrolled` flag to each match based on the full membership, and
+includes `feature_version`. The unscoped `/users/search` response is unchanged.
+Paginated reads never replace the form's original version token; if the rollout
+changes while editing, the administrator must review the newer state.
+
+## Host Header Validation
+
+When mounted in Rails, requests pass through Rails' `config.hosts` checks. The gem
+performs no additional Host header validation.
+
+For standalone use (e.g. `rackup`), configure authentication and host validation
+through middleware such as
+[`Rack::Protection::HostAuthorization`](https://github.com/sinatra/sinatra/tree/main/rack-protection#host-authorization-api)
+or a reverse proxy that only forwards trusted hosts.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/fetlife/rollout-ui.
@@ -141,7 +262,7 @@ bundle exec rerun rackup
 
 And visit [http://localhost:9292/](http://localhost:9292/).
 
-Alternatively, you can also configure which Redis with:
+To use a different Redis connection:
 
 ```sh
 REDIS_HOST=localhost REDIS_PORT=6379 REDIS_DB=10 bundle exec rerun rackup

data/lib/rollout/ui/config.rb

@@ -9,10 +9,16 @@ module Rollout::UI
       actor
       actor_url
       timestamp_format
+      user_search
+      user_lookup
+      user_search_min_length
+      user_search_limit
     ].freeze
 
     DEFAULT_VALUES = {
-      timestamp_format: '%Y-%m-%d %H:%M %Z'
+      timestamp_format: '%Y-%m-%d %H:%M %Z',
+      user_search_min_length: 3,
+      user_search_limit: 20
     }.freeze
 
     KEYS.each do |key|

data/lib/rollout/ui/helpers.rb

@@ -1,3 +1,5 @@
+require "digest/sha2"
+require "json"
 require "rack"
 require "rollout"
 
@@ -5,10 +7,60 @@ require "rollout/ui/version"
 
 module Rollout::UI
   module Helpers
+    USER_PAGE_SIZE = 25
+    USER_SEARCH_MAX_LENGTH = 100
+
     def stylesheet_path(name)
       "#{request.script_name}/css/#{name}.css"
     end
 
+    def javascript_path(name)
+      "#{request.script_name}/js/#{name}.js"
+    end
+
+    def user_search_path
+      "#{request.script_name}/users/search"
+    end
+
+    def enrolled_users_path(feature_name)
+      "#{request.script_name}/features/#{feature_name}/users"
+    end
+
+    def feature_user_search_path(feature_name)
+      "#{request.script_name}/features/#{feature_name}/users/search"
+    end
+
+    def user_selector_enabled?
+      config.defined?(:user_search) && config.defined?(:user_lookup)
+    end
+
+    def user_search_min_length
+      config.get(:user_search_min_length).to_i.clamp(1, USER_SEARCH_MAX_LENGTH)
+    end
+
+    def user_search_limit
+      config.get(:user_search_limit).to_i.clamp(1, 100)
+    end
+
+    def user_label(id, include_id: true)
+      id = id.to_s
+      return @user_nicknames[id] if @user_nicknames&.key?(id)
+
+      label = @user_lookup_attempted&.key?(id) ? "Unknown user" : "User"
+      include_id ? "#{label} (##{id})" : label
+    end
+
+    def feature_version(feature)
+      state = [
+        feature.name.to_s,
+        feature.percentage.to_f,
+        feature.groups.map(&:to_s).uniq.sort,
+        feature.users.map(&:to_s).uniq.sort,
+        feature.data["description"].to_s,
+      ]
+      Digest::SHA256.hexdigest(state.to_json)
+    end
+
     def index_path
       "#{request.script_name}/"
     end
@@ -84,10 +136,15 @@ module Rollout::UI
       key.to_s.gsub('data.', '')
     end
 
-    def format_change_value(value)
+    def format_change_value(value, key: nil)
       case value
       when Array
-        "[#{value.join(', ')}]"
+        values = if key.to_s == 'users' && config.defined?(:user_lookup)
+          value.map { |id| user_label(id) }
+        else
+          value
+        end
+        "[#{values.join(', ')}]"
       when String, nil
         "'#{value}'"
       else
@@ -106,9 +163,16 @@ module Rollout::UI
     def event_summary(event)
       return "deleted this feature" if event.name.to_s == "delete"
 
-      changes = event.data.fetch(:before).keys.reject { |key| key.to_s == 'data.updated_at' }.map do |key|
-        before = format_change_value(event.data.fetch(:before).fetch(key))
-        after = format_change_value(event.data.fetch(:after).fetch(key))
+      changes = event.data.fetch(:before).keys.filter_map do |key|
+        next if key.to_s == 'data.updated_at'
+
+        before_value = event.data.fetch(:before).fetch(key)
+        after_value = event.data.fetch(:after).fetch(key)
+        next if before_value == after_value
+        next if key.to_s == 'data.description' && before_value.to_s == after_value.to_s
+
+        before = format_change_value(before_value, key: key)
+        after = format_change_value(after_value, key: key)
         "#{format_change_key(key)} from #{before} to #{after}"
       end
       "changed #{changes.empty? ? 'nothing!' : changes.join(', ')}"

data/lib/rollout/ui/public/css/enrolled-users.css

@@ -0,0 +1,191 @@
+#enrolled-users .enrolled-user-search-field,
+#enrolled-users #pending-user-slot {
+  position: relative;
+}
+
+#enrolled-users .text-gray-500,
+#enrolled-users .text-gray-600,
+#enrolled-users .text-gray-400 {
+  color: #4a5568;
+}
+
+.dark #enrolled-users .text-gray-500,
+.dark #enrolled-users .text-gray-600,
+.dark #enrolled-users .text-gray-400 {
+  color: #b8b8b8;
+}
+
+#enrolled-users input::placeholder {
+  color: #4a5568;
+  opacity: 1;
+}
+
+.dark #enrolled-users input::placeholder {
+  color: #b8b8b8;
+}
+
+#enrolled-users #user-search-dropdown {
+  position: absolute;
+  top: calc(100% + 0.25rem);
+  left: 0;
+  right: 0;
+  z-index: 20;
+  box-shadow: 0 4px 12px rgb(0 0 0 / 15%);
+}
+
+#enrolled-users #user-search-results {
+  max-height: min(16rem, 40vh);
+  overflow-y: auto;
+}
+
+#enrolled-users #user-search-result-status {
+  padding: 0.5rem 0.75rem;
+  line-height: 1rem;
+  max-height: min(8rem, 30vh);
+  overflow-y: auto;
+}
+
+#enrolled-users #user-search-results [role="option"] > span:first-child {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+#enrolled-users #user-search-results [role="option"][aria-disabled="false"]:not([aria-selected="true"]):hover {
+  background-color: #edf2f7;
+}
+
+.dark #enrolled-users #user-search-results [role="option"][aria-disabled="false"]:not([aria-selected="true"]):hover {
+  background-color: #3a3a3a;
+}
+
+#enrolled-users #user-search-results [role="option"][aria-selected="true"] {
+  background-color: #2563eb;
+  color: #ffffff;
+}
+
+#enrolled-users #user-search-results [role="option"][aria-selected="true"] .text-gray-500 {
+  color: inherit;
+}
+
+#enrolled-users #user-search-results [role="option"][aria-disabled="true"] {
+  cursor: default;
+}
+
+#enrolled-users #user-search-status {
+  height: 1.5rem;
+  line-height: 1.5rem;
+  margin-top: 0.25rem;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+#enrolled-users #pending-user-slot {
+  margin-top: 0.75rem;
+}
+
+#enrolled-users #pending-user-changes:not([hidden]) {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: center;
+  column-gap: 0.5rem;
+  row-gap: 0.5rem;
+}
+
+#enrolled-users #pending-user-summary {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+#enrolled-users #pending-user-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+#enrolled-users #pending-user-actions > button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 2.5rem;
+}
+
+#enrolled-users #review-user-changes {
+  border-color: currentColor;
+}
+
+#enrolled-users #pending-user-review {
+  position: absolute;
+  bottom: calc(100% + 0.5rem);
+  right: 0;
+  width: min(100%, 28rem);
+  z-index: 20;
+  box-shadow: 0 4px 12px rgb(0 0 0 / 15%);
+}
+
+#enrolled-users #pending-user-details {
+  max-height: min(16rem, 50vh);
+  overflow-y: auto;
+}
+
+#enrolled-users #pending-user-details li {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 0.75rem;
+  margin-bottom: 0.25rem;
+}
+
+#enrolled-users #pending-user-details li span {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+#enrolled-users button {
+  min-height: 24px;
+}
+
+#enrolled-users .enrolled-user-pagination {
+  margin-bottom: 0.5rem;
+}
+
+#enrolled-users .enrolled-user-pagination [aria-disabled="true"] {
+  opacity: 0.5;
+}
+
+@media (max-width: 480px) {
+  #enrolled-users #pending-user-changes:not([hidden]) {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  #enrolled-users #pending-user-actions {
+    justify-self: center;
+  }
+
+  #enrolled-users #enrolled-users-table {
+    table-layout: fixed;
+  }
+
+  #enrolled-users #enrolled-users-table th,
+  #enrolled-users #enrolled-users-table td {
+    padding-left: 0.375rem;
+    padding-right: 0.375rem;
+  }
+
+  #enrolled-users #enrolled-users-table th:nth-child(2) {
+    width: 35%;
+  }
+
+  #enrolled-users #enrolled-users-table th:last-child {
+    width: 4rem;
+  }
+
+  #enrolled-users #enrolled-users-table td:nth-child(2) {
+    overflow-wrap: anywhere;
+  }
+
+  #enrolled-users .enrolled-user-pagination a {
+    padding-left: 0.5rem;
+    padding-right: 0.5rem;
+  }
+}