hub_kernel 0.24.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 278e7929cc3994d1e1149a5fa9ce387922748cb829f615e9bf56e52d960f1d06
-  data.tar.gz: b60a8992e16825e54d1c8f211e9ce09a814bfe4d0215d94bc40d8da77f74a281
+  metadata.gz: fbd4a1ca059e2203955aab7a07510cd07620427086b6153455f0e84d1f4ea639
+  data.tar.gz: 26a9be066b129fa83177261e5f9e15cc72c206c3210dc4fc1f26c6a65ac29676
 SHA512:
-  metadata.gz: 82a223294f8bbe74427019e44a38ef20678e8d6680d4e384e2c68be6322abe05da574dfa47dca5689d0ee31103ff903f841001906378842ed25aa81f1f6e5310
-  data.tar.gz: bb81b8f0de934af592603666605e30349170ac35bd89fe59a6903cf51e62a5e4cf0dc36070dd1dd44d9c201999efddfc46e79c45002698787e3b9015f99c7819
+  metadata.gz: 80bcd028c34e3be272d7c81b81852a0814c592df1cdbfb58954095dc4f240db87d02e4cd78afebd7cec0a0a9d1212d5f0585203724eefab74e81d42901b43050
+  data.tar.gz: 782767a253efd77447d8be7b2d16dc7086f8715515d19189435cb4a4fc5c64663cb25e721e2056fd19356b82b84b742bfbedab434652b6030a5a9c21fb41323c

data/README.md

@@ -102,6 +102,117 @@ returns its answer. An error it raises reaches the caller unchanged. Calling a p
 app left unfilled raises `HubKernel::UnwiredPortError`, such as "Supplies' spend
 recorder is not wired".
 
+### Record ports
+A record port is a port the app fills with an Active Record model class, so a hub can
+name a model another part of the app owns without naming its class. The hub declares it
+by name:
+
+```ruby
+module Fulfillment
+  extend HubKernel::Ports
+
+  record_port :job_record
+end
+```
+
+The app fills it with the model, in the same setup as its other ports:
+
+```ruby
+Rails.application.config.to_prepare do
+  Fulfillment.job_record = Job
+end
+```
+
+`Fulfillment.job_record` then answers `Job`. A record port is on the hub's
+`port_names`, so the start check, the hub check and kept ports all read it.
+
+### Links through a record port
+A hub's model links to a record another hub owns with `belongs_to_port`, naming its own
+hub and one of that hub's record ports instead of the other model's class:
+
+```ruby
+module Sales
+  class Quote < ApplicationRecord
+    belongs_to_port :job, port: Sales, record: :job_record
+  end
+end
+```
+
+hub_kernel defines an ordinary `belongs_to :job` whose class is the model the app filled
+the port with. `quote.job` reads the job, and `includes`, `preload`, `joins`, `where` and
+`order` work on the link as on any `belongs_to`. Every other `belongs_to` option, such as
+`foreign_key:` or `optional:`, and a scope passed before the options, reach the
+association unchanged. The class name comes from the port, so one passed is not used.
+
+A link is always read-only, and no option makes it writable:
+
+- A record read through the link, loaded or preloaded, raises
+  `ActiveRecord::ReadOnlyRecord` when it is saved or destroyed.
+- `build_job`, `create_job` and `create_job!` raise `ActiveRecord::ReadOnlyRecord`, and so
+  does assigning an unsaved record to `job`.
+- The records a scope loads are read-only too.
+- `autosave`, `dependent`, `touch` and `counter_cache` each write to the linked record, so
+  passing any of them raises an `ArgumentError` naming it.
+
+The model still sets which record it links to, by assigning a saved record or its id, and
+saves itself. A change to the linked record goes through the hub that owns it.
+
+The link is defined as soon as both the model has loaded and the port is filled, in
+whichever order those happen. A model that loads after its port is filled has the link
+when it loads. A model that loads first waits on its hub, and filling the port defines the
+link. A boot with eager loading on defines it the same way. After a code reload in
+development, the reloaded model has the link again, and it points at the reloaded model
+the app fills the port with.
+
+The model names only its own hub, so the crossing check passes it. The app's
+`to_prepare` block that fills the port is the one place both models are named.
+
+### Has-many links through a record port
+A hub's model lists the records another hub owns that point back at it with
+`has_many_port`, naming its own hub and one of that hub's record ports:
+
+```ruby
+module Sales
+  class Job < ApplicationRecord
+    has_many_port :quotes, port: Sales, record: :quote_record
+  end
+end
+```
+
+hub_kernel defines an ordinary `has_many :quotes` whose class is the model the app filled
+the port with. `job.quotes` lists the quotes, and `includes`, `preload`, `joins`, `where`
+and `order` work on the link as on any `has_many`. Every other `has_many` option, such as
+`foreign_key:` or `inverse_of:`, and a scope passed before the options, reach the
+association unchanged, apart from the options below that write to the listed records.
+The class name comes from the port, so one passed is not used.
+
+A has-many link is always read-only, and no option makes it writable:
+
+- A record listed through the link, loaded, preloaded or queried, raises
+  `ActiveRecord::ReadOnlyRecord` when it is saved or destroyed.
+- Adding a record to the list with `<<`, `push`, `append`, `concat` or `replace`, removing
+  one with `delete`, `destroy`, `delete_all`, `destroy_all` or `clear`, and building or
+  creating one with `build`, `new`, `create` or `create!` raise
+  `ActiveRecord::ReadOnlyRecord`, on the list and on a query made from it.
+- Assigning the list with `quotes=` or `quote_ids=` raises `ActiveRecord::ReadOnlyRecord`.
+- Writing the listed records all at once with `update_all`, `update_counters`, `insert`,
+  `insert!`, `insert_all`, `insert_all!`, `upsert` or `upsert_all` raises
+  `ActiveRecord::ReadOnlyRecord`.
+- `autosave`, `counter_cache` and a `dependent` value that destroys, deletes or nullifies
+  the listed records each write to them, so passing any of them raises an `ArgumentError`
+  naming it.
+
+`dependent: :restrict_with_exception` and `dependent: :restrict_with_error` write nothing
+to the listed records, so the link takes them. Deleting the model while the link lists
+records is refused, the first way by raising `ActiveRecord::DeleteRestrictionError` and
+the second by adding an error and returning false, and deleting it when the link lists
+none goes ahead.
+
+The link is defined as soon as both the model has loaded and the port is filled, in
+whichever order those happen, the same way as a `belongs_to_port` link. A boot with eager
+loading on defines it, and after a code reload in development the reloaded model lists
+the reloaded model the app fills the port with.
+
 ### The start check
 Every hub that declares a port or exposes a method is on `HubKernel::Hubs.list`. Call
 `HubKernel::Hubs.check!` after the app fills its ports, and the app refuses to start
@@ -115,7 +226,9 @@ end
 ```
 
 It raises `HubKernel::UnwiredPortError` naming every unfilled port with its hub, one per
-line. Running it inside `to_prepare` checks again after every code reload, and a hub
+line. It also names each record port filled with something that is not an Active Record
+model, such as "Fulfillment's job record is filled with something that is not an Active
+Record model". Running it inside `to_prepare` checks again after every code reload, and a hub
 declared again on a reload stays on the list once.
 
 While any hub exposes a method, it also names the permission check or the account scope
@@ -136,8 +249,9 @@ class SuppliesHubTest < ActiveSupport::TestCase
 end
 ```
 
-The test fails and names each port the app left unfilled, and each port filled with
-something that cannot be called.
+The test fails and names each port the app left unfilled, each port filled with
+something that cannot be called, and each record port filled with something that is not
+an Active Record model.
 
 ### The exposed list
 The exposed list, calling by name, the permission check, the account scope and the errors

data/lib/hub_kernel/conformance/hub.rb

@@ -13,7 +13,7 @@ module HubKernel
 
       included do
         test "every port of the hub is filled with something that can be called" do
-          problems = the_hub.unwired_ports + the_hub.uncallable_ports
+          problems = the_hub.unwired_ports + the_hub.uncallable_ports + the_hub.unmodelled_ports
           flunk problems.join("\n") if problems.any?
         end
       end

data/lib/hub_kernel/engine.rb

@@ -1,4 +1,5 @@
 require "hub_kernel/hub_folders"
+require "hub_kernel/port_associations"
 
 module HubKernel
   class Engine < ::Rails::Engine
@@ -16,6 +17,10 @@ module HubKernel
       ActiveSupport.on_load(:action_controller) { append_view_path(views) }
     end
 
+    initializer "hub_kernel.port_associations" do
+      ActiveSupport.on_load(:active_record) { extend HubKernel::PortAssociations }
+    end
+
     config.to_prepare { HubFolders.hub_modules(Rails.root).each(&:constantize) }
   end
 end

data/lib/hub_kernel/hubs.rb

@@ -14,7 +14,7 @@ module HubKernel
     def self.list = (registered + Interface::ExposingHubs.list).uniq { |hub| hub.name || hub }
 
     def self.check!
-      unwired = list.select { |hub| hub.respond_to?(:unwired_ports) }.flat_map(&:unwired_ports) + unfilled_host_answers
+      unwired = list.select { |hub| hub.respond_to?(:unwired_ports) }.flat_map { |hub| hub.unwired_ports + hub.unmodelled_ports } + unfilled_host_answers
       raise UnwiredPortError, unwired.join("\n") if unwired.any?
     end
 

data/lib/hub_kernel/port_associations.rb

@@ -0,0 +1,53 @@
+module HubKernel
+  module PortAssociations
+    WRITING_OPTIONS = %i[autosave dependent touch counter_cache].freeze
+    LIST_WRITING_OPTIONS = %i[autosave dependent counter_cache].freeze
+    RESTRICTING = %i[restrict_with_error restrict_with_exception].freeze
+    LIST_WRITING_METHODS = %i[<< push append concat build new create create! delete destroy delete_all destroy_all clear replace update_all insert insert! insert_all insert_all! upsert upsert_all].freeze
+
+    def belongs_to_port(name, scope = nil, port:, record:, **options)
+      refuse_writing_options(name, options)
+      port.link_record(record, [ self.name, name ]) do |model|
+        belongs_to name, read_only(scope), **options, class_name: model.name
+        refuse_creating_through(name)
+      end
+    end
+
+    def has_many_port(name, scope = nil, port:, record:, **options)
+      refuse_writing_options(name, options.reject { |option, value| option == :dependent && RESTRICTING.include?(value) }, LIST_WRITING_OPTIONS)
+      refusal = "#{self.name}'s #{name} link is read-only, so no record can be written through it"
+      port.link_record(record, [ self.name, name ]) do |model|
+        has_many name, read_only(scope, refusing_list(refusal)), **options, class_name: model.name
+        refuse_replacing_list(name, refusal)
+      end
+    end
+
+    private
+
+    def refuse_writing_options(name, options, writers = WRITING_OPTIONS)
+      writing = options.keys & writers
+      raise ArgumentError, "#{name} is a read-only record port link, so it does not take #{writing.to_sentence}" if writing.any?
+    end
+
+    def read_only(scope, *extensions)
+      return -> { readonly.extending(*extensions) } unless scope
+      return -> { instance_exec(&scope).readonly.extending(*extensions) } if scope.arity.zero?
+
+      ->(owner) { instance_exec(owner, &scope).readonly.extending(*extensions) }
+    end
+
+    def refusing_list(refusal)
+      Module.new { LIST_WRITING_METHODS.each { |method| define_method(method) { |*| raise ActiveRecord::ReadOnlyRecord, refusal } } }
+    end
+
+    def refuse_replacing_list(name, refusal)
+      [ :"#{name}=", :"#{name.to_s.singularize}_ids=" ].each { |method| define_method(method) { |*| raise ActiveRecord::ReadOnlyRecord, refusal } }
+    end
+
+    def refuse_creating_through(name)
+      refusal = "#{self.name}'s #{name} link is read-only, so it cannot build or create a record"
+      %W[build_#{name} create_#{name} create_#{name}!].each { |method| define_method(method) { |*| raise ActiveRecord::ReadOnlyRecord, refusal } }
+      define_method(:"#{name}=") { |linked| linked&.new_record? ? raise(ActiveRecord::ReadOnlyRecord, refusal) : super(linked) }
+    end
+  end
+end

data/lib/hub_kernel/ports.rb

@@ -13,6 +13,20 @@ module HubKernel
       define_singleton_method(as) { |*args, **options| public_send(name).call(*args, **options) }
     end
 
+    def record_port(name)
+      Hubs.add(self)
+      declared_ports << name
+      record_ports << name
+      singleton_class.attr_reader name
+      define_singleton_method(:"#{name}=") { |model| fill_record_port(name, model) }
+    end
+
+    def link_record(name, model_and_link, &link)
+      links_to(name)[model_and_link] = link
+      filling = public_send(name)
+      link.call(filling) if active_record_model?(filling)
+    end
+
     def port_names = declared_ports.dup
 
     def unwired_ports
@@ -20,14 +34,31 @@ module HubKernel
     end
 
     def uncallable_ports
-      declared_ports.select { |name| instance_variable_get(:"@#{name}")&.respond_to?(:call) == false }
+      (declared_ports - record_ports).select { |name| instance_variable_get(:"@#{name}")&.respond_to?(:call) == false }
         .map { |name| "#{hub_name} #{name.to_s.tr("_", " ")} is filled with something that cannot be called" }
     end
 
+    def unmodelled_ports
+      record_ports.select { |name| instance_variable_get(:"@#{name}") }
+        .reject { |name| active_record_model?(instance_variable_get(:"@#{name}")) }
+        .map { |name| "#{hub_name} #{name.to_s.tr("_", " ")} is filled with something that is not an Active Record model" }
+    end
+
     private
 
     def declared_ports = @declared_ports ||= []
 
+    def record_ports = @record_ports ||= []
+
+    def links_to(name) = (@record_links ||= {})[name] ||= {}
+
+    def fill_record_port(name, model)
+      instance_variable_set(:"@#{name}", model)
+      links_to(name).each_value { |link| link.call(model) } if active_record_model?(model)
+    end
+
+    def active_record_model?(filling) = filling.is_a?(Class) && filling < ActiveRecord::Base
+
     def unwired(name)
       ->(*, **) { raise UnwiredPortError, unwired_message(name) }
     end

data/lib/hub_kernel/version.rb

@@ -1,3 +1,3 @@
 module HubKernel
-  VERSION = "0.24.0"
+  VERSION = "0.26.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.26.0
 platform: ruby
 authors:
 - tylercschneider
@@ -66,6 +66,7 @@ files:
 - lib/hub_kernel/hubs.rb
 - lib/hub_kernel/kept_ports.rb
 - lib/hub_kernel/markup.rb
+- lib/hub_kernel/port_associations.rb
 - lib/hub_kernel/ports.rb
 - lib/hub_kernel/records.rb
 - lib/hub_kernel/version.rb