hub_kernel 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 278e7929cc3994d1e1149a5fa9ce387922748cb829f615e9bf56e52d960f1d06
-  data.tar.gz: b60a8992e16825e54d1c8f211e9ce09a814bfe4d0215d94bc40d8da77f74a281
+  metadata.gz: 3e8e24b52cfa8070ea79fc420ec714555b3e81377725ac9ea8e8a3a20ac280bb
+  data.tar.gz: 130ba409bb6db19a6cd0d1c34ffc535407ba03255f8e282bd2f333c53bef6000
 SHA512:
-  metadata.gz: 82a223294f8bbe74427019e44a38ef20678e8d6680d4e384e2c68be6322abe05da574dfa47dca5689d0ee31103ff903f841001906378842ed25aa81f1f6e5310
-  data.tar.gz: bb81b8f0de934af592603666605e30349170ac35bd89fe59a6903cf51e62a5e4cf0dc36070dd1dd44d9c201999efddfc46e79c45002698787e3b9015f99c7819
+  metadata.gz: d159cfc7e9b03980d03de84433ca09d3f1b5a11d758b10a3412a54eff96b8636b1187d9b2e4d54d2582ef7610d43c8df0e63c8a99de1553f17cb698175b34e9a
+  data.tar.gz: 7e075af8fa7fbe2cc6b7952a45c5a710c7702a39686cf38b0b121166c39f89f06f53e3e9114e3543e606cb22e9628c42ca09f96ba70ceafe31922b74bf491dce

data/README.md

@@ -102,6 +102,71 @@ 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.
+
 ### 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 +180,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 +203,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,33 @@
+module HubKernel
+  module PortAssociations
+    WRITING_OPTIONS = %i[autosave dependent touch counter_cache].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
+
+    private
+
+    def refuse_writing_options(name, options)
+      writing = options.keys & WRITING_OPTIONS
+      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)
+      return -> { readonly } unless scope
+      return -> { instance_exec(&scope).readonly } if scope.arity.zero?
+
+      ->(owner) { instance_exec(owner, &scope).readonly }
+    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.25.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.25.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