ros-apartment 4.0.0.alpha6 → 4.0.0.alpha7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ce0a7124b9df22be74f2899b8a38046f52fcd7e1e0b068b3ebd778e16f57969
-  data.tar.gz: 0f40a39d073ae13bd59dce2e72e3e2aaa3759f2ffc270491f6dbbfcc7ef623fe
+  metadata.gz: '093f09466c1e39d4344764096cec982394980fb08c8b72712c96bd8ad30fdcc7'
+  data.tar.gz: 402f7ef009203bb95296a90d7c6ff3dd34eeebca2d70c7da86cdb398ecc6fa60
 SHA512:
-  metadata.gz: ebbc9775707e60c7e7bd896e6f1efa02487017519770dda6558cd89552e53558f47a39df31b73f4c90f6c7039e86399536ce586ce1bd30ac263ad67071c7407a
-  data.tar.gz: 8339cc7eb7b07adcb5df1f923c55f7e3aa96bad5faa47a13975550563af0d77191736b4afe0a8aa97f6a446adc59cc148a21739ff0c36224d3608371e6a0efe0
+  metadata.gz: 99343f0efe17d444cc23b244581c56135a293371c97ee3fc5d2d2931e51c688c50d9d3d93d8ae55489ec36d3a6a43a910cacdc85d22c43a6c7e80a1bad189faa
+  data.tar.gz: 2ccd4c456cf1a5ce190d4b50dedfc131231cd1f02518c0444313987ef0a5fda8acc00c1376bfc5daac791768f1b13685d0bb47a08ae5ba755943a2cd6eb5d04b

data/README.md

@@ -40,6 +40,25 @@ This gem is a maintained fork of the original [Apartment gem](https://github.com
 - Rails 7.2+
 - PostgreSQL 14+, MySQL 8.4+, or SQLite3
 
+### Ruby version manager
+
+`.ruby-version` is the single source of truth for the local Ruby version (the
+same file `ruby/setup-ruby` reads in CI). Both [mise](https://mise.jdx.dev) and
+[rbenv](https://github.com/rbenv/rbenv) honor it — use whichever you prefer:
+
+```bash
+# mise (recommended)
+brew install mise                 # then add `eval "$(mise activate zsh)"` to ~/.zshrc
+mise trust && mise install        # one-time trust per clone, then install the pinned Ruby
+
+# rbenv (also works, unchanged)
+rbenv install "$(cat .ruby-version)"
+```
+
+The committed `mise.toml` carries settings only (never a version): it tells mise
+to honor `.ruby-version` without any per-developer global config. `mise trust`
+is required once per clone; `bin/dev/setup-worktree` handles it for new worktrees.
+
 ### Setup
 
 ```ruby

data/lib/apartment/cli/migrations.rb

@@ -5,6 +5,13 @@ require 'thor'
 module Apartment
   class CLI < Thor
     class Migrations < Thor
+      # The raised Thor::Error message is the low-context surface a monitor or
+      # CI-log tail captures even when the stdout summary is dropped/unindexed.
+      # Name a few failed tenants there (capped, so a 600-tenant run does not
+      # produce a wall of text); the full per-tenant detail is in the summary
+      # and in the migrate_tenant_failed.apartment events.
+      FAILED_TENANTS_PREVIEW = 5
+
       def self.exit_on_failure? = true
 
       desc 'migrate [TENANT]', 'Run migrations for tenants'
@@ -62,7 +69,15 @@ module Apartment
         say(result.summary)
 
         trigger_schema_dump if result.success?
-        raise(Thor::Error, "Migration failed for #{result.failed.size} tenant(s)") unless result.success?
+        raise(Thor::Error, migration_failure_message(result.failed)) unless result.success?
+      end
+
+      def migration_failure_message(failures)
+        names = failures.map(&:tenant)
+        shown = names.first(FAILED_TENANTS_PREVIEW)
+        more = names.size - shown.size
+        suffix = more.positive? ? ", and #{more} more" : ''
+        "Migration failed for #{names.size} tenant(s): #{shown.join(', ')}#{suffix} (see summary above)"
       end
 
       # Rollback bypasses the Migrator's parallelism and Result tracking but

data/lib/apartment/instrumentation.rb

@@ -3,8 +3,8 @@
 require 'active_support/notifications'
 
 module Apartment
-  # Thin wrapper around ActiveSupport::Notifications.
-  # Known events: create, drop, evict (all namespaced as *.apartment).
+  # Thin wrapper around ActiveSupport::Notifications. All events are namespaced
+  # *.apartment; see docs/observability.md for the authoritative event catalog.
   module Instrumentation
     def self.instrument(event, payload = {}, &block)
       event_name = "#{event}.apartment"

data/lib/apartment/migrator.rb

@@ -121,9 +121,15 @@ module Apartment
         duration: monotonic_now - start, error: nil, versions_run: versions
       )
     rescue StandardError => e
+      duration = monotonic_now - start
+      # Symmetric with the :migrate_tenant success event above: the gem holds the
+      # full structured error here, so emit it for subscribers rather than
+      # stranding it in the returned Result. See migrate_tenant's rescue.
+      instrument_failure(tenant_name, e, duration)
+
       Result.new(
         tenant: tenant_name, status: :failed,
-        duration: monotonic_now - start, error: e, versions_run: []
+        duration: duration, error: e, versions_run: []
       )
     end
 
@@ -166,9 +172,17 @@ module Apartment
         end
       end
     rescue StandardError => e
+      duration = monotonic_now - start
+      # Failure counterpart to the :migrate_tenant success event. On SUCCESS the
+      # gem instruments; on FAILURE it previously only returned a failed Result,
+      # leaving adopters no hook to observe the (structured) error. This closes
+      # that asymmetry — generic payload (tenant + error + duration); routing to
+      # an error tracker is the subscriber's job.
+      instrument_failure(tenant, e, duration)
+
       Result.new(
         tenant: tenant, status: :failed,
-        duration: monotonic_now - start, error: e, versions_run: []
+        duration: duration, error: e, versions_run: []
       )
     ensure
       Apartment::Current.migrating = false
@@ -242,6 +256,34 @@ module Apartment
       conn.instance_variable_set(ADVISORY_LOCKS_IVAR, original) if conn&.instance_variable_defined?(ADVISORY_LOCKS_IVAR)
     end
 
+    # Emit the failure event without letting a raising subscriber break the
+    # Migrator's non-raising contract: the failed Result MUST still be returned.
+    # ActiveSupport::Notifications propagates subscriber exceptions through
+    # instrument (verified against AS 8.0), and this fires from inside a rescue
+    # block, so an un-isolated call would convert a captured per-tenant failure
+    # into an unhandled raise out of #run.
+    #
+    # Scope of the guarantee: a subscriber raising a StandardError is swallowed
+    # and warned. Process-control exceptions (SystemExit, SignalException /
+    # Interrupt) are deliberately NOT rescued — they must propagate so exit and
+    # Ctrl-C still work mid-migration; a subscriber raising a bare Exception
+    # subclass is itself a bug (Ruby errors should descend from StandardError).
+    # The warn is nested-rescued so a broken $stderr (IOError is a StandardError)
+    # cannot re-escape the handler. Success-path instrumentation is left
+    # un-isolated by design — only the failure path carries the hard no-raise
+    # guarantee, and swallowing there would mask real subscriber bugs.
+    def instrument_failure(tenant, error, duration)
+      Instrumentation.instrument(:migrate_tenant_failed, tenant: tenant, error: error, duration: duration)
+    rescue StandardError => e
+      # Nested rescue: a sibling `rescue` on this method would NOT catch an
+      # exception raised by warn (a broken $stderr), so the warn gets its own.
+      begin
+        warn "[Apartment::Migrator] migrate_tenant_failed subscriber raised #{e.class}: #{e.message}"
+      rescue StandardError
+        nil
+      end
+    end
+
     def monotonic_now
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end

data/lib/apartment/tasks/v4.rake

@@ -34,6 +34,13 @@ namespace :apartment do
     else
       Apartment::CLI::Migrations.new.invoke(:migrate)
     end
+    # Parity with apartment:drop: `.new.invoke` bypasses Thor.start's
+    # exit_on_failure? handling, so an unrescued Thor::Error (raised on
+    # migration failure) would surface as a raw `rake aborted!` backtrace that
+    # buries the actionable message. abort re-emits it as a clean one-liner
+    # with a non-zero exit.
+  rescue Thor::Error => e
+    abort(e.message)
   end
 
   desc 'Seed all tenants'

data/lib/apartment/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apartment
-  VERSION = '4.0.0.alpha6'
+  VERSION = '4.0.0.alpha7'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ros-apartment
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha6
+  version: 4.0.0.alpha7
 platform: ruby
 authors:
 - Ryan Brunner