studio-engine 0.92.2 → 0.93.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e0b538d638180facefc1cff85cc4c5ccbea6aa49711d6ac48f1863a87e8d776
-  data.tar.gz: c48c355f0e8e9e2164649383eb61c7f47eaece289dfd0007e1f4f2d849137023
+  metadata.gz: 3769d755a39684b1488e69948a2c671c736c655400bf035d6c69e8db5c990a8e
+  data.tar.gz: 2941057ba862ce883d57e58f56d9dfae793c6ad0781802af6147848583604ecf
 SHA512:
-  metadata.gz: 9ac3c8a86695295f537aaa8355bfdc393a3b6a7ff5409308b7fe6ab402021e145089adc5a212d44aaced6921904563ccb16cf838ec5c46a33f7c9850196e2dda
-  data.tar.gz: 6d0fbbc3746e31d7dfd570185740ce394f91fb5503e5c3ce6f0ad7d59c4a6ba4f302669d8fd96e4bd1e6c2ef509aa5703951b8417381411bfb5d276cc8607e1d
+  metadata.gz: 443ae3e30df171f7ff4614a82785a0e40f231dc11d792d3e36a8160b9d13d112bd1e55fc420759a564b02ec6b69d0f64406c9d7265eca2bf2885edb8f7be58a4
+  data.tar.gz: 7f1b7c14d366cb9cd26f7c0a3caf8c5135d13ac79b359e8ca095047602657bf3a4eb28d5127fe13fcb5175137fe9fbb8844b370b89c13340bdbf4540679b8cc0

data/CHANGELOG.md

@@ -4,6 +4,8 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.93.0 — 2026-10-07
+
 ## 0.92.2 — 2026-10-07
 
 ## 0.92.1 — 2026-10-07
@@ -22,6 +24,26 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
   raises `Studio::HostSchemaError` in development and test, and logs (and reports
   to Sentry) in production; `Studio.host_schema_check = :raise | :log | false`
   overrides. Extra host columns are never reported, and rake tasks skip it.
+- **`Sluggable#rename_slug!` changes a slug on purpose and cascades.** It updates
+  the row and every child column that holds the old slug in one transaction:
+  each `has_many`/`has_one` declared with `primary_key: :slug`, plus the pairs a
+  model declares with `has_slug_children "table" => :column`. A blank, badly
+  formed (`slug_format`, parameterize-shaped by default) or taken slug raises
+  `Sluggable::SlugRefused`, a `RecordInvalid` with the reason on
+  `errors[:slug]`; `rename_slug` returns false instead.
+- **`Studio::ErrorHandling` answers a refused slug rename with 422** and the
+  reason (JSON and other formats), or a redirect back with the reason as the
+  alert (HTML), never the 500 catch-all and no ErrorLog row.
+
+### Changed
+
+- **A slug is written once, at create.** `Sluggable` no longer recomputes
+  `slug` from `name_slug` on every save, so a name edit stops renaming the row
+  and orphaning the child rows that point at it. A persisted row with a blank
+  slug still gets one on its next save, and a `name_slug` that reads the id is
+  settled inside the create, so `user-<id>` no longer waits for a second save.
+  Code that relied on a save moving the slug calls `rename_slug!(name_slug)`
+  instead.
 
 ### Fixed
 

data/README.md

@@ -35,7 +35,7 @@ resolved.
 - **Theme system**: Dynamic CSS custom properties generated from 7 role colors (primary, dark, light, success, accent, warning, danger). Dark/light mode toggle. Admin theme editor at `/admin/theme`.
 - **UI primitives**: Shared component partials and CSS primitives such as `components/emoji_swap` for nav/sidebar emoji hover transitions.
 - **Operator tooling**: Shared `studio/banners/environment` banner with Dev Mode + email connector controls and `studio/banners/impersonation`.
-- **Sluggable concern**: `before_save :set_slug` with `to_param` for human-readable URLs
+- **Sluggable concern**: a human-readable slug written once at create (`to_param` returns it); `rename_slug!` changes it and cascades to every child column in one transaction, and a refused rename answers 422
 - **ThemeSetting model**: Per-app DB overrides with fallback to config defaults
 - **Geo**: `Studio::GeoDetection` places every visitor (IP → country + subdivision, session-cached), `Studio::GeoSetting` stores the operator's blocked countries and regions, `require_geo_allowed` locks whichever surfaces an app chooses, and the shared badge + `/admin/geo` manager ship with it. See [`docs/GEO.md`](docs/GEO.md).
 - **Site identity and link previews**: `Studio::SiteIdentity` holds the app's title, description and image, edited at `/admin/link_preview` beside a live unfurl card and read anywhere through `Studio.site_identity`. Every page unfurls with it unless it calls `link_preview image:, title:, description:`, and `Studio::LinkPreviewBots` serves preview fetchers a slim page under iMessage's 1 MiB limit. Adopt with `bin/rails g studio:site_identity`. See [`docs/LINK_PREVIEW.md`](docs/LINK_PREVIEW.md).

data/app/controllers/concerns/studio/error_handling.rb

@@ -17,6 +17,8 @@ module Studio
       # handlers BELOW this line, never above it.
       rescue_from StandardError, with: :handle_unexpected_error
       rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found
+      # A string, so including this concern does not load the model concern.
+      rescue_from "Sluggable::SlugRefused", with: :handle_slug_refused
 
       before_action :require_authentication
 
@@ -243,6 +245,19 @@ module Studio
       raise exception
     end
 
+    # Layer 1: a refused slug rename (Sluggable#rename_slug!) is the caller's
+    # input, not a fault: 422 with the reason for JSON and other formats, and a
+    # redirect back with the reason as the alert for HTML. No ErrorLog row.
+    def handle_slug_refused(exception)
+      reason = exception.record.errors.full_messages_for(:slug).to_sentence.presence || exception.message
+
+      respond_to do |format|
+        format.html { redirect_back_or_to root_path, alert: reason }
+        format.json { render json: { error: reason }, status: :unprocessable_entity }
+        format.any  { render plain: reason, status: :unprocessable_entity }
+      end
+    end
+
     # Layer 1: Catch-all for unexpected errors — log + friendly response.
     # Skips logging if rescue_and_log already captured it.
     def handle_unexpected_error(exception)

data/app/controllers/studio/onboarding_controller.rb

@@ -79,12 +79,10 @@ module Studio
         #   2. It steps around any host before_save that DERIVES first_name FROM
         #      name — set_name_parts does exactly that — which would discard the
         #      value we were just handed.
-        #   3. THE SLUG. Sluggable's `before_save :set_slug` is UNGATED, and
-        #      mcritchie-studio's User#name_slug is built from `name`. A full
-        #      save right after this writes `name` would therefore re-point the
-        #      slug the account answers on — a URL change, on a column carrying
-        #      a unique index, for every signup. That is the constraint this
-        #      endpoint has always been protecting; it is not a shortcut.
+        #   3. A host save can carry other callbacks that react to a name
+        #      write; this endpoint writes only the name columns. (Sluggable
+        #      writes the slug once, at create, so the slug stays put either
+        #      way.)
         #
         # WHAT SKIPPING CALLBACKS USED TO COST. Because set_name_parts never
         # ran, `first_name` got the WHOLE typed value: someone answering "Ada

data/app/models/concerns/sluggable.rb

@@ -1,17 +1,167 @@
+# A human-readable `slug` that is written once and changed only on purpose.
+#
+# The slug is set at create from `name_slug` (each including model defines it)
+# and never recomputed by a later save, because other tables point at it by
+# value: a display-name edit must not rename the row and orphan its children.
+# A persisted row whose slug is blank gets one on its next save, since filling a
+# blank is still the first write. A `name_slug` that reads the id (`user-<id>`)
+# is settled once more right after the insert, inside the create, because the
+# id does not exist when before_save runs.
+#
+# The one way to change a persisted slug is `rename_slug!` (or `rename_slug`),
+# which updates the row and every child column that references it in one
+# transaction. The children are found two ways:
+#
+#   * every `has_many` / `has_one` on the model with `primary_key: :slug`;
+#   * every pair declared with `has_slug_children`, for a table that has no
+#     association here:
+#
+#       class Person < ApplicationRecord
+#         include Sluggable
+#         has_slug_children "athletes" => :person_slug,
+#                           "news" => %i[primary_person_slug secondary_person_slug]
+#       end
+#
+# The declaration lives on the parent so the cascade never depends on whether a
+# child class happens to be loaded.
+#
+# A refusal (blank, badly formed, or taken) raises Sluggable::SlugRefused, a
+# subclass of ActiveRecord::RecordInvalid, with the reason on `errors[:slug]`.
+# Studio::ErrorHandling answers it with 422 and the reason, never a 500, and
+# `rename_slug` returns false instead of raising, for an inline form error.
 module Sluggable
   extend ActiveSupport::Concern
 
+  # Lowercase words of letters and digits joined by single hyphens: the shape
+  # `String#parameterize` produces. A model whose slugs legitimately hold other
+  # characters sets its own `self.slug_format`.
+  DEFAULT_SLUG_FORMAT = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+
+  # The refusal rename_slug! raises: a RecordInvalid, so a caller that already
+  # rescues RecordInvalid keeps working, with a class of its own so the
+  # controller layer can answer it with 422 without claiming every invalid save.
+  class SlugRefused < ActiveRecord::RecordInvalid; end
+
   included do
-    before_save :set_slug
+    class_attribute :slug_format, instance_writer: false, default: DEFAULT_SLUG_FORMAT
+    class_attribute :declared_slug_children, instance_writer: false, default: [].freeze
+
+    before_save :set_slug, if: :sluggable_unwritten?
+    after_create :sluggable_settle_derived_slug
+  end
+
+  class_methods do
+    # Declares child columns that hold this model's slug: a hash of table name to
+    # one column or a list of columns. Repeatable; each call adds to the set.
+    def has_slug_children(pairs)
+      added = pairs.flat_map do |table, columns|
+        Array(columns).map { |column| [table.to_s, column.to_s].freeze }
+      end
+      self.declared_slug_children = (declared_slug_children + added).uniq.freeze
+    end
+
+    # Every [table, column] pair `rename_slug!` updates: the slug-keyed
+    # associations plus the declared pairs, without duplicates.
+    def slug_children
+      from_associations = reflect_on_all_associations.filter_map do |reflection|
+        next unless %i[has_many has_one].include?(reflection.macro)
+        next if reflection.through_reflection? || reflection.polymorphic? || reflection.options[:as]
+        next unless reflection.options[:primary_key].to_s == "slug"
+
+        [reflection.klass.table_name, reflection.foreign_key.to_s].freeze
+      end
+      (from_associations + declared_slug_children).uniq
+    end
   end
 
   def to_param
     slug
   end
 
+  # Changes this row's slug to `new_slug` and rewrites every child column that
+  # held the old one, all or nothing. Returns { "table.column" => rows updated }.
+  # Raises Sluggable::SlugRefused, with the reason on errors[:slug], when
+  # the slug is blank, badly formed, or already taken.
+  def rename_slug!(new_slug)
+    raise ActiveRecord::RecordNotSaved.new("a slug can be renamed only on a saved record", self) unless persisted?
+
+    new_slug = new_slug.to_s.strip
+    old_slug = slug_in_database
+    errors.delete(:slug)
+    return {} if new_slug == old_slug
+
+    sluggable_refuse!(:blank) if new_slug.empty?
+    sluggable_refuse!(:invalid) unless slug_format.match?(new_slug)
+    sluggable_refuse!(:taken, value: new_slug) if sluggable_taken?(new_slug)
+
+    renamed = { slug: new_slug }
+    renamed[:updated_at] = Time.current if has_attribute?(:updated_at)
+    counts = {}
+    self.class.transaction(requires_new: true) do
+      self.class.base_class.unscoped.where(self.class.primary_key => id).update_all(renamed)
+      self.class.slug_children.each do |table, column|
+        counts["#{table}.#{column}"] = sluggable_cascade(table, column, old_slug, new_slug)
+      end
+    end
+    renamed.each { |name, value| write_attribute(name, value) }
+    clear_attribute_changes(renamed.keys)
+    counts
+  rescue ActiveRecord::RecordNotUnique
+    # The pre-check passed and a concurrent write took the slug first; the
+    # unique index is the arbiter, and the answer is the same refusal.
+    sluggable_refuse!(:taken, value: new_slug)
+  rescue ActiveRecord::InvalidForeignKey
+    sluggable_refuse!(:invalid, message: "cannot change while a constraint without ON UPDATE CASCADE references it")
+  end
+
+  # rename_slug! for a form: false, with the reason on errors[:slug], instead of
+  # raising.
+  def rename_slug(new_slug)
+    rename_slug!(new_slug)
+    true
+  rescue SlugRefused
+    false
+  end
+
   private
 
+  def sluggable_unwritten?
+    new_record? || slug.blank?
+  end
+
+  # A model may override this; the override owns its slug, and the post-insert
+  # settle below leaves it alone.
   def set_slug
-    self.slug = name_slug
+    self.slug = @sluggable_derived_slug = name_slug
+  end
+
+  def sluggable_settle_derived_slug
+    derived = @sluggable_derived_slug
+    @sluggable_derived_slug = nil
+    return if derived.nil? || slug != derived
+
+    settled = name_slug
+    update_column(:slug, settled) if settled.present? && settled != slug
+  end
+
+  def sluggable_taken?(candidate)
+    self.class.base_class.unscoped.where(slug: candidate).where.not(self.class.primary_key => id).exists?
+  end
+
+  # One UPDATE on the parent's connection: the cascade a foreign key with
+  # ON UPDATE CASCADE would run, and it needs no model for the child table.
+  def sluggable_cascade(table, column, old_slug, new_slug)
+    connection = self.class.connection
+    quoted_column = connection.quote_column_name(column)
+    connection.update(<<~SQL.squish, "Sluggable cascade")
+      UPDATE #{connection.quote_table_name(table)}
+      SET #{quoted_column} = #{connection.quote(new_slug)}
+      WHERE #{quoted_column} = #{connection.quote(old_slug)}
+    SQL
+  end
+
+  def sluggable_refuse!(reason, **options)
+    errors.add(:slug, reason, **options)
+    raise SlugRefused, self
   end
 end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.92.2"
+  VERSION = "0.93.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.92.2
+  version: 0.93.0
 platform: ruby
 authors:
 - Alex McRitchie