has_public_record 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dadeae14d61a8a853dff01a3fc146bf16903fde443c4863a537987ccb9edaa04
-  data.tar.gz: 7d348eb1f8c4f76be37625666c2e99ecbb824355189eb4cdaa8796058c7bcceb
+  metadata.gz: bccfeb56d4de4b2cc334b9e090d990be30970367278a6ad96175365692ac3e19
+  data.tar.gz: 3bcd2494228239500b849cac40abe4d16ca9ac5b3680862b8a9bac8c2e11fca0
 SHA512:
-  metadata.gz: 402e8cd8f72ffc69f45d326cae433f28b3e13aad4fce4de6bd99ca55192976c4346e01e51eb2eab1e37577246e85dd8324e305fd73ace87841f48f0322ebcee9
-  data.tar.gz: 292344f738d26c9a99e4eb4bb020dcbbbc51da61626cbb7e5d5fbb15d781d65886f21b1ef96ec31c1c36a71ebf02c91991bb287a63d5b5d3f0076ff95e22a770
+  metadata.gz: fd13f5114d34aed5fa93cc8a249bd6ffaefbd66f1807e844c098cf097b38ace21d125eae44d7ce8667f57d538cb74e775eb9574bb917d2fc3b227f2beb3a41e7
+  data.tar.gz: 6a1d43e2c924db64231390da8d129d0c0153ca30368f14f4a73985b00a394954684cf32fea41ad563936e69871fcef72da406085992000415a536a6f8cb9fb4a

data/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
+## 0.1.1
+
+Fixes
+- Ids are validated against the alphabet when created; lower-case and bare ids assigned to a record are normalized
+  (a custom attribute type also normalizes `where` / `find_by` values). Reading a row returns exactly what is stored.
+- `missing_public_id` counts empty strings, like the report does, so backfill and report agree.
+- `has_public_record` on an abstract class raises at declaration instead of breaking `resolve` later.
+- Learned length can no longer ratchet past `starting length + max_bumps` during an outage.
+- `rename_prefix` reports the rows it actually changed.
+- Rake helpers no longer define methods on `Object`; `MODEL=` accepts `user`, `users` or `User`.
+- Maintenance no longer drops models that share a table name across databases.
+- `--concurrently` only asks for a concurrent index on PostgreSQL.
+- The gem now ships its LICENSE and declares `concurrent-ruby`.
+
+Added
+- `regenerate_public_id!`, `generate_public_ids(count)`, `HasPublicRecord.well_formed?`, `HasPublicRecord.reset_registry!`.
+- `with_generated_public_ids` and `backfill_public_ids!` use one existence query per batch instead of one per row.
+- The registry resets when Rails reloads code in development.
+- Generator specs; README covers every public method.
+
 ## 0.1.0
 
-First release: prefixed public ids with length growth, lookup helpers, resolve and resolve_many, a standalone
-generator, migration and install generators, backfill / report / rename tasks, and testing helpers.
+First release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baden
+
+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/lib/generators/has_public_record/migration/migration_generator.rb

@@ -16,7 +16,7 @@ module HasPublicRecord
       class_option :column, type: :string, default: "public_id", desc: "Column name"
       class_option :enforce, type: :boolean, default: false, desc: "Make the column NOT NULL (run after the backfill)"
       class_option :concurrently, type: :boolean, default: false,
-                                  desc: "PostgreSQL only: build the index without locking writes"
+                                  desc: "Build the index without locking writes (PostgreSQL; elsewhere it is built normally)"
 
       def create_migration_file
         migration_template(options[:enforce] ? "enforce.rb.tt" : "add.rb.tt",
@@ -25,6 +25,9 @@ module HasPublicRecord
 
       private
 
+      # The name as given: Rails would pluralize it ("status" -> "statuses").
+      def table_name = name.to_s
+
       def public_column = options[:column]
 
       def migration_name

data/lib/generators/has_public_record/migration/templates/add.rb.tt

@@ -6,11 +6,18 @@
 #   rails g has_public_record:migration <%= table_name %> --enforce
 class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
 <% if options[:concurrently] -%>
-  disable_ddl_transaction!
+  disable_ddl_transaction! # needed to build an index concurrently; harmless on other databases
 
 <% end -%>
   def change
     add_column :<%= table_name %>, :<%= public_column %>, :string
-    add_index :<%= table_name %>, :<%= public_column %>, unique: true<%= ", algorithm: :concurrently" if options[:concurrently] %>
+<% if options[:concurrently] -%>
+    # Only PostgreSQL can build an index without locking writes; other databases build it normally.
+    index_options = { unique: true }
+    index_options[:algorithm] = :concurrently if connection.adapter_name.match?(/postgres/i)
+    add_index :<%= table_name %>, :<%= public_column %>, **index_options
+<% else -%>
+    add_index :<%= table_name %>, :<%= public_column %>, unique: true
+<% end -%>
   end
 end

data/lib/generators/has_public_record/migration/templates/enforce.rb.tt

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 # Run after the backfill: fails if any row still has no id.
+#
+# Big PostgreSQL table? change_column_null scans it under a lock. The lock-light way (PostgreSQL 12+) is a CHECK
+# constraint added unvalidated and validated separately; with a validated constraint in place, NOT NULL needs no scan:
+#   add_check_constraint :<%= table_name %>, "<%= public_column %> IS NOT NULL", name: "<%= table_name %>_<%= public_column %>_not_null", validate: false
+#   validate_check_constraint :<%= table_name %>, name: "<%= table_name %>_<%= public_column %>_not_null"
 class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     change_column_null :<%= table_name %>, :<%= public_column %>, false

data/lib/has_public_record/generator.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 require "securerandom"
+require "set"
 require "concurrent/map"
 
 module HasPublicRecord
   # Makes codes. Starts at a length (config.lengths[name] > the explicit length > config.default_length) and grows
-  # when random tries keep hitting taken codes, remembering the grown length per key (per process). Growth is
-  # announced with "grow.has_public_record" (key, table, column, from, to; table and column only for a scope).
+  # when random tries keep hitting taken codes, remembering the grown length per key (per process). The length never
+  # goes past start + max_bumps, so a long outage cannot ratchet it up for good. Growth is announced with
+  # "grow.has_public_record" (key, table, column, from, to; table and column only for a scope).
   #
   # Whether a code is free is a callable, so nothing here needs a model:
   #   Generator.generate(prefix: "inv", length: 8) { |id| !Redis.exists?(id) }
@@ -14,6 +16,7 @@ module HasPublicRecord
   module Generator
     EVENT = "grow.has_public_record"
     LEARNED = Concurrent::Map.new # key => length reached after growing
+    EXISTS_CHUNK = 500            # candidates per existence query (keeps IN lists inside every database's limits)
 
     class << self
       def random(length:, alphabet: HasPublicRecord.config.alphabet)
@@ -26,27 +29,50 @@ module HasPublicRecord
       def generate(prefix: nil, length: nil, max_bumps: nil, key: nil, scope: nil, column: nil, &free)
         prefix = check_prefix(prefix)
         free, key, table = source_for(prefix, key, scope, column, free)
-        config = HasPublicRecord.config
-        limit = max_bumps || config.max_length_bumps
-        current = [starting_length(table || key, length), LEARNED[key].to_i].max
-        bumps = 0
+        start, ceiling = bounds(table || key, length, max_bumps)
+        current = start_at(key, start, ceiling)
 
         loop do
-          config.attempts_per_length.times do
+          HasPublicRecord.config.attempts_per_length.times do
             candidate = compose(prefix, random(length: current))
             return candidate if free.call(candidate)
           end
+          current = grow(key, table, column, current, start, ceiling)
+        end
+      end
 
-          if bumps >= limit
-            raise ExhaustedError, "no unique code after #{bumps} length bumps (length #{current}) for #{key}"
+      # count distinct ids for a scope with ONE existence query per round (per 500 candidates), not one per id.
+      # reserved: ids that are not in the database yet but must not be handed out (a batch's supplied ids).
+      def generate_many(count, scope:, column:, prefix: nil, length: nil, max_bumps: nil, key: nil, reserved: [])
+        prefix = check_prefix(prefix)
+        count = Integer(count)
+        return [] if count <= 0
+
+        table = scope.table_name.to_s
+        key = (key || "#{table}.#{column}").to_s
+        start, ceiling = bounds(table, length, max_bumps)
+        current = start_at(key, start, ceiling)
+        seen = Set.new(reserved.map(&:to_s))
+        made = []
+        rounds = 0
+
+        while made.size < count
+          if rounds >= HasPublicRecord.config.attempts_per_length
+            current = grow(key, table, column, current, start, ceiling)
+            rounds = 0
           end
+          rounds += 1
+
+          candidates = Array.new(count - made.size) { compose(prefix, random(length: current)) }.uniq.reject { |id| seen.include?(id) }
+          taken = taken_among(scope, column, candidates)
+          candidates.each do |id|
+            next if taken.include?(id)
 
-          bumps += 1
-          from = current
-          current += 1
-          learn(key, current)
-          ActiveSupport::Notifications.instrument(EVENT, key: key, table: table, column: column, from: from, to: current)
+            seen << id
+            made << id
+          end
         end
+        made
       end
 
       # The length a name (a table, or a standalone key) starts at.
@@ -86,6 +112,30 @@ module HasPublicRecord
         end
       end
 
+      # [where this name starts, the longest it may ever get]
+      def bounds(name, length, max_bumps)
+        start = starting_length(name, length)
+        [start, start + (max_bumps || HasPublicRecord.config.max_length_bumps)]
+      end
+
+      def start_at(key, start, ceiling) = [[LEARNED[key].to_i, ceiling].min, start].max
+
+      # One step longer, remembered and announced; ExhaustedError once the ceiling is reached.
+      def grow(key, table, column, current, start, ceiling)
+        if current >= ceiling
+          raise ExhaustedError, "no unique code after #{current - start} length bumps (length #{current}) for #{key}"
+        end
+
+        longer = current + 1
+        learn(key, longer)
+        ActiveSupport::Notifications.instrument(EVENT, key: key, table: table, column: column, from: current, to: longer)
+        longer
+      end
+
+      def taken_among(scope, column, candidates)
+        candidates.each_slice(EXISTS_CHUNK).flat_map { |chunk| scope.where(column => chunk).pluck(column) }.to_set
+      end
+
       def compose(prefix, bare) = prefix ? "#{prefix}#{SEPARATOR}#{bare}" : bare
 
       # Atomic per key: a smaller length never overwrites a larger one.

data/lib/has_public_record/maintenance.rb

@@ -18,14 +18,25 @@ module HasPublicRecord
     end
 
     class << self
-      # Every model that declared has_public_record (one per table and column), optionally only the named one.
+      # Every model that declared has_public_record (base classes only, so STI subclasses are not listed twice).
+      # only: accepts "User", "user" or "users" (also "billing/invoice").
       def models(only: nil)
         found = ActiveRecord::Base.descendants.select do |model|
           model.respond_to?(:public_record_options) && model.public_record_options && model.name.present? &&
             !model.abstract_class? && model == model.base_class
-        end
-        found = found.uniq { |model| [model.table_name, model.public_id_column] }.sort_by(&:to_s)
-        only ? found.select { |model| model.name == only.to_s } : found
+        end.sort_by(&:to_s)
+        return found unless only
+
+        names = name_variants(only)
+        found.select { |model| names.include?(model.name) }
+      end
+
+      # Like models, but raises HasPublicRecord::Error when nothing matches (the rake tasks turn that into an abort).
+      def models!(only: nil)
+        found = models(only: only)
+        return found unless found.empty?
+
+        raise Error, only ? "No model named #{only} declares has_public_record." : "No model declares has_public_record."
       end
 
       def reports(only: nil) = models(only: only).map { |model| report(model) }
@@ -49,8 +60,15 @@ module HasPublicRecord
                    duplicates: present.group(column).having("COUNT(*) > 1").count.size, problem: nil)
       end
 
+      def capacity(model)
+        length = Generator.starting_length(model.table_name, model.public_record_options.length)
+        used = model.base_class.unscoped.where.not(model.public_id_column => [nil, ""]).count
+        Capacity.new(length: length, slots: HasPublicRecord.config.alphabet.size**length, used: used)
+      end
+
       # Moves stored ids from an old prefix to the model's declared one (change prefix: in the model first).
-      # Counts only unless apply: true. One transaction: all rows move or none do. Returns the rows concerned.
+      # Counts only unless apply: true (the count is then an estimate from the database). One transaction: all rows
+      # move or none do. Returns the rows actually changed.
       def rename_prefix(model, from:, apply: false, batch_size: 1000)
         from = from.to_s
         to = model.public_id_prefix
@@ -60,30 +78,29 @@ module HasPublicRecord
         column = model.public_id_column
         old = "#{from}#{SEPARATOR}"
         scope = model.base_class.unscoped.where(with_prefix(model, old))
-        count = scope.count
-        return count unless apply && count.positive?
+        return scope.count unless apply
 
+        renamed = 0
         model.transaction do
           scope.find_each(batch_size: batch_size) do |record|
-            next unless record[column].start_with?(old) # the LIKE may be case-insensitive on some databases
+            current = record[column]
+            next unless current.start_with?(old) # the LIKE may be case-insensitive on some databases
 
-            renamed = "#{to}#{SEPARATOR}#{record[column].delete_prefix(old)}"
-            model.public_record_row_scope(record).update_all(column => renamed)
+            renamed += model.public_record_row_scope(record).update_all(column => "#{to}#{SEPARATOR}#{current.delete_prefix(old)}")
           end
         end
         ActiveSupport::Notifications.instrument("rename.has_public_record",
-                                                table: model.table_name, column: column, from: from, to: to, count: count)
-        count
-      end
-
-      def capacity(model)
-        length = Generator.starting_length(model.table_name, model.public_record_options.length)
-        used = model.base_class.unscoped.where.not(model.public_id_column => [nil, ""]).count
-        Capacity.new(length: length, slots: HasPublicRecord.config.alphabet.size**length, used: used)
+                                                table: model.table_name, column: column, from: from, to: to, count: renamed)
+        renamed
       end
 
       private
 
+      def name_variants(only)
+        text = only.to_s.strip
+        [text, text.camelize, text.singularize.camelize].uniq
+      end
+
       def broken(model, problem)
         Report.new(model: model, table: model.table_name, column: model.public_id_column, total: 0, missing: 0,
                    wrong_prefix: 0, wrong_samples: [], duplicates: 0, problem: problem)

data/lib/has_public_record/model.rb

@@ -15,6 +15,11 @@ module HasPublicRecord
     class_methods do
       # Called by the has_public_record macro. Touches no database table, so it is safe while the app boots.
       def declare_public_record(prefix:, column:, length:, max_bumps:)
+        if abstract_class?
+          raise HasPublicRecord::Error,
+                "#{name || inspect}: has_public_record cannot be declared on an abstract class (it has no table); " \
+                "declare it on each concrete model"
+        end
         if public_record_options
           raise HasPublicRecord::Error,
                 "#{name || inspect} already has has_public_record (prefix #{public_record_options.prefix.inspect}); " \
@@ -22,9 +27,11 @@ module HasPublicRecord
         end
 
         prefix = HasPublicRecord.registry.register(prefix, name)
-        self.public_record_options = Options.new(prefix: prefix, column: column.to_sym, length: length, max_bumps: max_bumps)
+        column = column.to_sym
+        self.public_record_options = Options.new(prefix: prefix, column: column, length: length, max_bumps: max_bumps)
 
-        attr_readonly column # a public id never changes once created
+        attribute column, HasPublicRecord::PublicIdType.new(prefix: prefix)
+        attr_readonly column # a public id never changes once created (regenerate_public_id! is the one way)
         before_create :assign_public_record
         validate :validate_public_record_format, on: :create
       end
@@ -32,8 +39,16 @@ module HasPublicRecord
       def public_id_prefix = public_record_options.prefix
       def public_id_column = public_record_options.column
 
+      # Rails would call the column "Public" (it strips _id as if it were a foreign key).
+      def human_attribute_name(attribute, options = {})
+        return super unless public_record_options && attribute.to_s == public_id_column.to_s
+
+        super(attribute, options.merge(default: "Public ID"))
+      end
+
       # The stored form of a ref: "usr_K3F9A2". Accepts the bare code and any letter case (see HasPublicRecord.fold_case).
-      # nil for another model's id, for junk and for blank.
+      # nil for another model's id, for junk and for blank. The alphabet is not checked: ids made under an older
+      # alphabet must stay findable.
       def normalize_public_id(ref) = HasPublicRecord.canonicalize(ref, public_id_prefix)
 
       def public_id?(ref) = !normalize_public_id(ref).nil?
@@ -58,14 +73,15 @@ module HasPublicRecord
       end
 
       # A regexp for route constraints (no anchors, as Rails wants): resources :users, constraints: { id: User.public_id_format }
+      # It follows the CURRENT alphabet: when changing the alphabet, widen it rather than replace it.
       def public_id_format
         alphabet = HasPublicRecord.config.alphabet
         chars = Regexp.escape((alphabet.chars + alphabet.swapcase.chars).uniq.join)
         /(?i:#{Regexp.escape(public_id_prefix)})#{SEPARATOR}[#{chars}]+/
       end
 
-      # Rows that have no public id yet (after adding the column to an existing table).
-      def missing_public_id = where(public_id_column => nil)
+      # Rows that have no public id yet: NULL or an empty string (the report counts both).
+      def missing_public_id = where(public_id_column => [nil, ""])
 
       # A fresh unused id for this model (what before_create uses).
       def generate_public_id
@@ -73,6 +89,14 @@ module HasPublicRecord
                                             length: public_record_options.length, max_bumps: public_record_options.max_bumps)
       end
 
+      # count distinct fresh ids with one existence query instead of one per id. reserved: ids to avoid that are not
+      # in the table yet.
+      def generate_public_ids(count, reserved: [])
+        HasPublicRecord::Generator.generate_many(count, scope: base_class.unscoped, column: public_id_column,
+                                                        prefix: public_id_prefix, length: public_record_options.length,
+                                                        max_bumps: public_record_options.max_bumps, reserved: reserved)
+      end
+
       # The one row a record is stored in, ignoring default scopes. Handles composite primary keys. A table with no
       # primary key is refused: an empty condition would match every row.
       def public_record_row_scope(record)
@@ -82,33 +106,32 @@ module HasPublicRecord
         base_class.unscoped.where(keys.zip(Array(record.id)).to_h)
       end
 
-      # Gives every row without an id one; returns how many. Plain SQL updates: the column is readonly through the
-      # model, and callbacks and updated_at stay untouched.
+      # Gives every row without an id one; returns how many. One existence query and one transaction per batch.
+      # Plain SQL updates: the column is readonly through the model, and callbacks and updated_at stay untouched.
       def backfill_public_ids!(batch_size: 1000)
         count = 0
-        missing_public_id.find_each(batch_size: batch_size) do |record|
-          count += public_record_row_scope(record).update_all(public_id_column => generate_public_id)
+        missing_public_id.find_in_batches(batch_size: batch_size) do |records|
+          ids = generate_public_ids(records.size)
+          transaction do
+            records.zip(ids) do |record, id|
+              count += public_record_row_scope(record).update_all(public_id_column => id)
+            end
+          end
         end
         count
       end
 
-      # insert_all / upsert_all skip callbacks, so rows get no id. This fills it in, one distinct id per row, and
-      # keeps ids you supplied:  User.insert_all(User.with_generated_public_ids(rows))
+      # insert_all / upsert_all skip callbacks, so rows get no id. This fills it in (one existence query for the
+      # whole batch) and keeps ids you supplied:  User.insert_all(User.with_generated_public_ids(rows))
       def with_generated_public_ids(rows)
         column = public_id_column
-        taken = Set.new
-        rows.map do |row|
-          row = row.to_h.symbolize_keys
-          if row[column].present?
-            taken << row[column]
-            next row
-          end
+        rows = rows.map { |row| row.to_h.symbolize_keys }
+        needed = rows.count { |row| row[column].blank? }
+        return rows if needed.zero?
 
-          id = generate_public_id
-          id = generate_public_id while taken.include?(id) # the database probe cannot see the rest of this batch
-          taken << id
-          row.merge(column => id)
-        end
+        reserved = rows.filter_map { |row| row[column].presence && (normalize_public_id(row[column]) || row[column]) }
+        fresh = generate_public_ids(needed, reserved: reserved).each
+        rows.map { |row| row[column].present? ? row : row.merge(column => fresh.next) }
       end
 
       # A stable id for a fixture label, for ERB in fixtures (Rails fixtures skip callbacks):
@@ -136,6 +159,24 @@ module HasPublicRecord
     # Rails' url helpers use this: user_path(user) -> /users/usr_K3F9A2
     def to_param = (self[self.class.public_id_column] if persisted?)
 
+    # Replaces the id (a leaked link, a rotated invite) and returns the new one. Every old URL stops working.
+    # The column stays readonly for everything else.
+    def regenerate_public_id!
+      raise HasPublicRecord::Error, "#{self.class.name} must be saved before its public id can be regenerated" unless persisted?
+
+      column = self.class.public_id_column
+      previous = self[column]
+      fresh = self.class.generate_public_id
+      if self.class.public_record_row_scope(self).update_all(column => fresh).zero?
+        raise ActiveRecord::RecordNotFound, "#{self.class.name} #{id.inspect} no longer exists"
+      end
+
+      @attributes.write_from_database(column.to_s, fresh) # not a dirty change, and not an assignment to a readonly column
+      ActiveSupport::Notifications.instrument("regenerate.has_public_record",
+                                              table: self.class.table_name, column: column, from: previous, to: fresh)
+      fresh
+    end
+
     private
 
     def assign_public_record
@@ -143,10 +184,11 @@ module HasPublicRecord
       self[column] = self.class.generate_public_id if self[column].blank?
     end
 
+    # Only ids being created are held to the current alphabet.
     def validate_public_record_format
       column = self.class.public_id_column
       value = self[column]
-      return if value.blank? || self.class.normalize_public_id(value) == value
+      return if value.blank? || HasPublicRecord.well_formed?(value, self.class.public_id_prefix)
 
       errors.add(column, :invalid)
     end

data/lib/has_public_record/public_id_type.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module HasPublicRecord
+  # The attribute type of a public id column. Assigning "usr_k3f9a2" or "K3F9A2" stores "usr_K3F9A2", and values used
+  # in where / find_by are normalized the same way, so lookups work in any letter case.
+  #
+  # Reading is deliberately NOT normalized: a row is returned exactly as stored. A legacy bare code stays visible as
+  # bare (the report and the prefix tools need to see it) instead of looking fine while the database says otherwise.
+  class PublicIdType < ActiveRecord::Type::String
+    attr_reader :prefix
+
+    def initialize(prefix:, **options)
+      super(**options)
+      @prefix = prefix
+    end
+
+    def cast(value) = canonical(super)
+
+    def serialize(value) = value.is_a?(::String) ? super(canonical(value)) : super
+
+    def deserialize(value) = value.nil? ? nil : value.to_s
+
+    # Two types with different prefixes are different types (the base class would call them equal).
+    def ==(other) = super && prefix == other.prefix
+    def eql?(other) = self == other
+    def hash = [super, prefix].hash
+
+    private
+
+    # Junk is left as typed: the model's validation reports it, nothing is silently rewritten.
+    def canonical(text)
+      return text if text.blank?
+
+      HasPublicRecord.canonicalize(text, prefix) || text
+    end
+  end
+end

data/lib/has_public_record/railtie.rb

@@ -3,8 +3,16 @@
 require "rails/railtie"
 
 module HasPublicRecord
-  # Loads the rake tasks. Generators need no hook: Rails finds lib/generators of every gem on the load path.
+  # Loads the rake tasks, and forgets declared prefixes when Rails unloads code in development. Generators need no
+  # hook: Rails finds lib/generators of every gem on the load path.
+  #
+  # before_class_unload, not to_prepare: to_prepare also runs at boot, and a model loaded before it would be wiped
+  # from the registry without ever being reloaded to declare itself again.
   class Railtie < ::Rails::Railtie
     rake_tasks { load File.expand_path("../tasks/has_public_record.rake", __dir__) }
+
+    initializer "has_public_record.reloader" do
+      ActiveSupport::Reloader.before_class_unload { HasPublicRecord.reset_registry! }
+    end
   end
 end

data/lib/has_public_record/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HasPublicRecord
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/has_public_record.rb

@@ -71,6 +71,17 @@ module HasPublicRecord
       end
     end
 
+    # Whether ref is an id this prefix could have issued: the prefix, then only characters of the current alphabet.
+    # For vetting ids that are GIVEN. Lookups use canonicalize, which does not check the alphabet, so ids made under an
+    # older alphabet stay findable.
+    def well_formed?(ref, prefix)
+      head, separator, tail = ref.to_s.partition(SEPARATOR)
+      return false if separator.empty? || head != prefix.to_s || tail.empty?
+
+      alphabet = config.alphabet
+      tail.each_char.all? { |char| alphabet.include?(char) }
+    end
+
     # { "usr" => "User", ... } for every model declared so far.
     def prefixes = registry.to_h
 
@@ -132,6 +143,13 @@ module HasPublicRecord
       prefix ? "#{prefix}#{SEPARATOR}#{bare}" : bare
     end
 
+    # Forgets which class declared which prefix. Rails calls this when it unloads code in development, so a renamed
+    # class or prefix does not raise DuplicatePrefixError; the reloaded classes declare themselves again.
+    def reset_registry!
+      registry.clear!
+      @models_loaded = false
+    end
+
     # For specs: forget every declaration, learned length and setting.
     def reset!
       registry.clear!

data/lib/tasks/has_public_record.rake

@@ -6,16 +6,16 @@ namespace :has_public_record do
     Rails.application.eager_load!
   end
 
-  def hpr_models
-    only = ENV["MODEL"].presence
-    models = HasPublicRecord::Maintenance.models(only: only)
-    abort "No model#{" named #{only}" if only} declares has_public_record." if models.empty?
-    models
+  # A lambda, not a def: a def inside a rake file defines a method on Object for the whole host app.
+  pick_models = lambda do
+    HasPublicRecord::Maintenance.models!(only: ENV["MODEL"].presence)
+  rescue HasPublicRecord::Error => e
+    abort e.message
   end
 
   desc "Give every row without a public id one (MODEL=User to limit)"
   task backfill: :prepare do
-    hpr_models.each do |model|
+    pick_models.call.each do |model|
       problem = HasPublicRecord::Maintenance.report(model).problem
       next puts("#{model.name}: skipped, #{problem}") if problem
 
@@ -23,10 +23,9 @@ namespace :has_public_record do
     end
   end
 
-  desc "Missing ids, wrong prefixes, duplicates and capacity (MODEL=User to limit). Exits 1 when anything is off"
+  desc "Missing ids, wrong prefixes, duplicates and capacity (MODEL=User to limit). Fails when anything is off"
   task report: :prepare do
-    reports = HasPublicRecord::Maintenance.reports(only: ENV["MODEL"].presence)
-    abort "No model declares has_public_record." if reports.empty?
+    reports = pick_models.call.map { |model| HasPublicRecord::Maintenance.report(model) }
 
     reports.each do |r|
       label = "#{r.model.name} (#{r.table}.#{r.column}, prefix #{r.model.public_id_prefix})"
@@ -40,14 +39,14 @@ namespace :has_public_record do
              "#{HasPublicRecord::Maintenance.capacity(r.model)}"
       end
     end
-    exit 1 unless reports.all?(&:ok?)
+    abort "has_public_record:report found problems (see above)" unless reports.all?(&:ok?)
   end
 
   desc "Rename stored ids from an old prefix to the model's declared one: MODEL=User FROM=old [APPLY=1]"
   task rename: :prepare do
     from = ENV["FROM"].presence or abort "Give the old prefix: FROM=old"
     ENV["MODEL"].presence or abort "Give the model: MODEL=User"
-    model = hpr_models.first
+    model = pick_models.call.first
     apply = ENV["APPLY"].present?
 
     count = HasPublicRecord::Maintenance.rename_prefix(model, from: from, apply: apply)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: has_public_record
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Baden
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -74,6 +88,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- LICENSE.txt
 - README.md
 - lib/generators/has_public_record/install/install_generator.rb
 - lib/generators/has_public_record/install/templates/initializer.rb.tt
@@ -87,6 +102,7 @@ files:
 - lib/has_public_record/macro.rb
 - lib/has_public_record/maintenance.rb
 - lib/has_public_record/model.rb
+- lib/has_public_record/public_id_type.rb
 - lib/has_public_record/railtie.rb
 - lib/has_public_record/registry.rb
 - lib/has_public_record/version.rb
@@ -95,7 +111,6 @@ homepage: https://github.com/BadenRushworth/has_public_record
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/BadenRushworth/has_public_record
   source_code_uri: https://github.com/BadenRushworth/has_public_record
   changelog_uri: https://github.com/BadenRushworth/has_public_record/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/BadenRushworth/has_public_record/issues