thecore_backend_commons 3.4.1 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47f357e5a5b355623f7eaa5443e8ba8cfb5566311f6c5f866cbda9740a48a044
-  data.tar.gz: 52725ea116ba712bc9c68b4c3b757c2a64a7b1270b2efd1f56cd16c503d21bbe
+  metadata.gz: 5e57106019f11e4ac721eaee6a0d974f3c640e32bd6d031a462d3356a20f1091
+  data.tar.gz: 2ad214f8fe011dafc87a3323d22b8d5f0e69bf0cc8ba61766385f219e14e41b6
 SHA512:
-  metadata.gz: fbb02e11840fdd2608ce289285424c5792e50ce09ef207c08a4aafd943761e01f2ed72e50bbe855c0fb8d35e61bb6e24c0ee170d335d26f19f8645b00b918d1e
-  data.tar.gz: cfbcd1ecdfb625c4eaa3119a64394afb73806f5c764b3c7982a44432aee24143de465ec268a60ed927714abf0702190e751401377d703dbe4226cc4bd49ac2b8
+  metadata.gz: fec2dcd9fe2769f2853a34ec1f8b887a8c9e6f9766e911821ef741df81cfa58399da343745dc589b384b05746ed599f6e61fd3d8ba6d48f928fe2156fcd3b527
+  data.tar.gz: f46bf3f1ee9ff55bbabd17b7e5f3614d1a9d04ad7a58113d014f5030c2ed1f1f39d39d11f2a0556876d3540356f9a2565a9d75d5cb0c5fd882343cd8f5c9f6ed

data/README.md

@@ -126,6 +126,39 @@ PushNotificationChannel.broadcast_to(subscriber, message)
 
 ---
 
+## `DefaultModuleRegistry` — shared `ApplicationRecord.inherited` hook
+
+Other gems in the ecosystem (`model_driven_api`, `thecore_ui_rails_admin`, ...) need to give
+*every* model some default behavior — a default API serialization shape, a default RailsAdmin
+navigation entry — without requiring a generated per-model concern file for the
+no-customization case. Rather than each gem independently overriding
+`ApplicationRecord.inherited` (and risking one override clobbering another), they all register
+into this one shared registry:
+
+```ruby
+ThecoreBackendCommons::DefaultModuleRegistry.register(
+  MyDefaultModule, # normally an ActiveSupport::Concern with an `included do ... end` block
+  applies_to: ->(klass) { true } # optional; defaults to every ApplicationRecord subclass
+)
+```
+
+Every registered module is `include`d, in registration order, into every `ApplicationRecord`
+subclass for which `applies_to` returns true — at the moment the subclass is *defined*, not via
+a post-boot scan (which would miss classes not yet autoloaded in development). This is wired up
+by installing an `ApplicationRecord.inherited` hook from `config.to_prepare` (see
+`config/initializers/default_module_registry.rb`), so it's already in place before Rails eager
+loads every model in production.
+
+Consumers today: `model_driven_api`'s `ModelDrivenApiDefaultJsonAttrs` (default `json_attrs`)
+and `thecore_ui_rails_admin`'s `ThecoreUiRailsAdminDefaultNavigationConcern` (default
+`navigation_label`/`navigation_icon`) — see their own READMEs for what each one does. A model
+that still needs custom behavior keeps (or adds) an explicit `Api::ModelName`/
+`RailsAdmin::ModelName` concern exactly as before; it simply runs *after* the default and
+overrides it. Full mechanics (idempotency, abstract/STI exclusion, `to_prepare` vs
+`after_initialize` timing) are documented in this gem's `CLAUDE.md`.
+
+---
+
 ## Invio email e configurazione SMTP
 
 ### Configurazione

data/config/initializers/default_module_registry.rb

@@ -0,0 +1,10 @@
+Rails.application.configure do
+  # Installed from `to_prepare` (not `after_initialize`) so the hook is in
+  # place *before* `eager_load!` runs -- see
+  # `ThecoreBackendCommons::DefaultModuleRegistry.install!` for why that
+  # ordering matters. `to_prepare` also re-runs on every class reload in
+  # development, so `install!` is idempotent.
+  config.to_prepare do
+    ThecoreBackendCommons::DefaultModuleRegistry.install!(ApplicationRecord)
+  end
+end

data/lib/thecore_backend_commons/default_module_registry.rb

@@ -0,0 +1,133 @@
+module ThecoreBackendCommons
+  # Shared registry other gems use to register "default" modules that get
+  # `include`d automatically into every `ApplicationRecord` subclass, as it
+  # is defined -- not via a post-boot scan of `ApplicationRecord.subclasses`.
+  #
+  # This exists so multiple gems (`model_driven_api`, `thecore_ui_rails_admin`,
+  # ...) can each contribute default model behavior (API serialization shape,
+  # RailsAdmin config, ...) through ONE shared `ApplicationRecord.inherited`
+  # hook instead of each gem independently overriding `inherited` itself.
+  # See ADR 0001/0002 (`vendor/external/thecore/docs/adr/` in the host app).
+  #
+  # == Usage
+  #
+  #   ThecoreBackendCommons::DefaultModuleRegistry.register(
+  #     MyDefaultModule,
+  #     applies_to: ->(klass) { klass.table_exists? rescue false }
+  #   )
+  #
+  # `applies_to` defaults to "every subclass" (`->(_klass) { true }`) when
+  # omitted. Registered modules are `include`d, in registration order, into
+  # every `ApplicationRecord` subclass for which `applies_to` returns true,
+  # at the moment the subclass is defined -- see `InheritedHook` below.
+  #
+  # `MyDefaultModule` should normally be an `ActiveSupport::Concern` with an
+  # `included do ... end` block, so its default methods/callbacks/DSL calls
+  # land as *own* behavior on each model class (see ADR 0001's consequences
+  # section -- `model_driven_api`'s introspection depends on this).
+  #
+  # == Idempotency
+  #
+  # - Calling `.register` twice with the *same* module object is a no-op the
+  #   second time -- it will not be applied twice to any subclass.
+  # - `.apply_to` never re-includes a module a class already has in its
+  #   ancestor chain (e.g. an STI subclass that already inherited it from its
+  #   base class), so STI subclasses are never double-included.
+  # - `.apply_to` never applies anything to an abstract class
+  #   (`klass.abstract_class?`) -- most importantly `ApplicationRecord`
+  #   itself (`primary_abstract_class`), which never receives default
+  #   modules through this mechanism since `ApplicationRecord.inherited` only
+  #   fires for classes that inherit *from* `ApplicationRecord`, never for
+  #   `ApplicationRecord`'s own definition.
+  module DefaultModuleRegistry
+    Entry = Struct.new(:mod, :applies_to)
+    private_constant :Entry
+
+    # Prepended onto `ApplicationRecord.singleton_class` (see `.install!`)
+    # so that every subsequent subclass definition applies the registry.
+    #
+    # Calls `super` first so it composes correctly with ActiveRecord's own
+    # `inherited` (which sets up `base_class`, STI bookkeeping, ...) and with
+    # any other gem's pre-existing `inherited` override further up the
+    # singleton-class ancestor chain.
+    module InheritedHook
+      def inherited(subclass)
+        super
+        ThecoreBackendCommons::DefaultModuleRegistry.apply_to(subclass)
+      end
+    end
+
+    class << self
+      # Registers +mod+ so it gets `include`d into every matching
+      # `ApplicationRecord` subclass defined from now on. Returns +mod+.
+      #
+      # +applies_to+ is a 1-arity callable invoked with the candidate class;
+      # only classes for which it returns truthy receive +mod+.
+      #
+      # Registering the same module object again is a no-op -- the original
+      # registration (and its original `applies_to`) is kept.
+      def register(mod, applies_to: ->(_klass) { true })
+        entries << Entry.new(mod, applies_to) unless registered?(mod)
+        mod
+      end
+
+      # True if +mod+ has already been registered.
+      def registered?(mod)
+        entries.any? { |entry| entry.mod.equal?(mod) }
+      end
+
+      # Applies every registered module whose `applies_to` predicate matches
+      # +klass+, in registration order. No-op for abstract classes. Never
+      # re-includes a module +klass+ already has in its ancestor chain.
+      #
+      # Called automatically by `InheritedHook` -- only call directly from
+      # application/test code that needs to (re-)apply defaults to a class
+      # defined before the registry/hook was set up.
+      def apply_to(klass)
+        return klass if klass.abstract_class?
+
+        entries.each do |entry|
+          next unless entry.applies_to.call(klass)
+          next if klass.include?(entry.mod)
+
+          klass.include(entry.mod)
+        end
+
+        klass
+      end
+
+      # Installs `InheritedHook` onto +base_class+'s singleton class so every
+      # subsequently-defined subclass triggers `.apply_to`. Idempotent --
+      # safe to call on every `to_prepare` cycle in development.
+      #
+      # Must run before any subclass of +base_class+ is defined (i.e. before
+      # eager loading), which is why the host initializer installs it from
+      # `config.to_prepare` rather than `config.after_initialize` -- Rails
+      # runs `to_prepare` callbacks *before* `eager_load!`, while
+      # `after_initialize` runs *after* it (see
+      # `Rails::Application::Finisher`). Installing from `after_initialize`
+      # would miss every subclass already loaded by eager loading in
+      # production.
+      def install!(base_class)
+        return base_class if base_class.singleton_class.ancestors.include?(InheritedHook)
+
+        base_class.singleton_class.prepend(InheritedHook)
+        base_class
+      end
+
+      # Test helper: clears all registrations. Not intended for production
+      # use -- does not uninstall `InheritedHook` from any class it was
+      # already installed on, and does not un-include modules already
+      # included into existing classes.
+      def reset!
+        @entries = []
+      end
+
+      private
+
+      def entries
+        @entries ||= []
+      end
+    end
+  end
+end

data/lib/thecore_backend_commons/version.rb

@@ -1,3 +1,3 @@
 module ThecoreBackendCommons
-  VERSION = "3.4.1".freeze
+  VERSION = "3.5.0".freeze
 end

data/lib/thecore_backend_commons.rb

@@ -17,6 +17,7 @@ require "thecore_backend_commons/engine"
 require "thecore_backend_commons/smtp_config"
 require "thecore_backend_commons/smtp_tester"
 require "thecore_backend_commons/push_notification_service"
+require "thecore_backend_commons/default_module_registry"
 
 module ThecoreBackendCommons
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thecore_backend_commons
 version: !ruby/object:Gem::Version
-  version: 3.4.1
+  version: 3.5.0
 platform: ruby
 authors:
 - Gabriele Tassoni
@@ -216,6 +216,7 @@ files:
 - config/initializers/concern_integer.rb
 - config/initializers/concern_string.rb
 - config/initializers/concern_user.rb
+- config/initializers/default_module_registry.rb
 - config/initializers/extension_nil.rb
 - config/initializers/extension_string.rb
 - config/locales/en.devise.custom.yml
@@ -229,6 +230,7 @@ files:
 - db/seeds.rb
 - lib/tasks/thecore_backend_commons_tasks.rake
 - lib/thecore_backend_commons.rb
+- lib/thecore_backend_commons/default_module_registry.rb
 - lib/thecore_backend_commons/engine.rb
 - lib/thecore_backend_commons/push_notification_service.rb
 - lib/thecore_backend_commons/smtp_config.rb