hub_kernel 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23120333c3f60fb91e59ac4711d4b94eb15897f85ca13dcd1fd9ed175310f334
-  data.tar.gz: 107feb16ebe566b00a0005a71d92a378cf1015952823ed676eb24d1669ade53a
+  metadata.gz: 026174ef5963518769182562042464615e204f2a32f7e4260c9ed390fc5b2160
+  data.tar.gz: 5d2fbdbb14248e8e145eb545246063e883fd196fb68b930180ff9b067a9c341c
 SHA512:
-  metadata.gz: 13236d35df7bf32b70c011a3385592f3c07cbd52867c46ff21d9ad323be4bff9eb80644748c1bd07185b2853066ca27d5a7de8575f51c35d6d76d957dcbd3129
-  data.tar.gz: c92d9a506afca9cd3bacee2f7ff7ece9204e21651b76f784fc1bc08611e58269e3412a1b7ebcc34f478768e1ffb0d8e0393427cc09ad1be85c2a433820562faa
+  metadata.gz: 9a7a2a568be438e982a2c0d688fdc61e5fd4ade3b49070d3ffccff71e662b6748185e2e19a1b1beedb6f3c2d14bf5e899faf12598ce7cbcf6e225d7a8c859389
+  data.tar.gz: 5f189db08ded136cb2adc871613545ba62f8f163938b63587e47a7382a745d12cceff6606fb7a5f137b4b0db5ca2c09db321cd91dc600140a7c4edde1e2f4c1f

data/README.md

@@ -68,7 +68,7 @@ app left unfilled raises `HubKernel::UnwiredPortError`, such as "Supplies' spend
 recorder is not wired".
 
 ### The start check
-Every hub that declares a port is on `HubKernel::Hubs.list`. Call
+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
 while any port is unfilled:
 
@@ -83,6 +83,10 @@ It raises `HubKernel::UnwiredPortError` naming every unfilled port with its hub,
 line. 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
+when either is unset or set to something that cannot be called. An app whose hubs expose
+nothing starts without either.
+
 ### The hub check
 A hub's own test can check that the app filled every one of its ports, so a missing
 fill shows in the suite rather than on the next start:

data/lib/hub_kernel/authz.rb

@@ -4,26 +4,5 @@ module HubKernel
 
   module Authz
     singleton_class.attr_accessor :check
-
-    module Vocabulary
-      def gates(*actions)
-        gated_actions.concat(actions)
-      end
-
-      def gated_actions
-        @gated_actions ||= []
-      end
-    end
-
-    def self.included(hub)
-      hub.extend(Vocabulary)
-    end
-
-    def allowed?(actor, action)
-      answer = authz.allowed?(actor, action)
-      raise NonBooleanAnswerError, "allowed? must return true or false, got #{answer.inspect}" unless [ true, false ].include?(answer)
-
-      answer
-    end
   end
 end

data/lib/hub_kernel/context.rb

@@ -1,15 +1,5 @@
 module HubKernel
   module Context
     singleton_class.attr_accessor :scope
-
-    class Null
-      def actor
-        :null_actor
-      end
-
-      def tenant
-        :null_tenant
-      end
-    end
   end
 end

data/lib/hub_kernel/exposes.rb

@@ -2,6 +2,7 @@ require "hub_kernel/action"
 require "hub_kernel/authz"
 require "hub_kernel/context"
 require "hub_kernel/ports"
+require "hub_kernel/hubs"
 
 module HubKernel
   class UnexposedMethodError < StandardError; end
@@ -11,6 +12,7 @@ module HubKernel
     Exposed = Data.define(:name, :takes, :writes)
 
     def exposes(name, takes:, writes:)
+      Hubs.add(self)
       exposed_methods[name.to_s] = Exposed.new(name: name, takes: takes, writes: writes)
     end
 

data/lib/hub_kernel/hubs.rb

@@ -1,3 +1,6 @@
+require "hub_kernel/authz"
+require "hub_kernel/context"
+
 module HubKernel
   module Hubs
     def self.add(hub)
@@ -8,8 +11,22 @@ module HubKernel
     def self.list = @list ||= []
 
     def self.check!
-      unwired = list.flat_map(&:unwired_ports)
+      unwired = list.select { |hub| hub.respond_to?(:unwired_ports) }.flat_map(&:unwired_ports) + unfilled_host_answers
       raise UnwiredPortError, unwired.join("\n") if unwired.any?
     end
+
+    def self.unfilled_host_answers
+      return [] unless list.any? { |hub| hub.respond_to?(:exposures) && hub.exposures.any? }
+
+      { "permission check" => Authz.check, "account scope" => Context.scope }.filter_map { |answer, filled| host_answer_problem(answer, filled) }
+    end
+    private_class_method :unfilled_host_answers
+
+    def self.host_answer_problem(answer, filled)
+      return "hub_kernel's #{answer} is not filled" unless filled
+
+      "hub_kernel's #{answer} is filled with something that cannot be called" unless filled.respond_to?(:call)
+    end
+    private_class_method :host_answer_problem
   end
 end

data/lib/hub_kernel/version.rb

@@ -1,3 +1,3 @@
 module HubKernel
-  VERSION = "0.16.0"
+  VERSION = "0.18.0"
 end

data/the_local/agents/hub_kernel-develop.md

@@ -38,7 +38,9 @@ hub_kernel lets a hub, one domain area written as a module, state what it needs
    bin/rails generate hub_kernel:hub Ledger entry_recorder:record_entry
    ```
 
-   - In a Rails engine gem it writes the hub under the gem's namespace, such as `app/models/billing/ledger.rb` holding `module Billing::Ledger`, and adds hub_kernel to the gemspec. It writes no test, since the gem never fills its own ports.
+   - In a Rails engine gem it adds hub_kernel to the gemspec once, and writes no test, since the gem never fills its own ports.
+   - When the engine isolates its namespace, the hub goes under that namespace, such as `app/models/billing/ledger.rb` holding `module Billing::Ledger`.
+   - A namespaced name such as `Console::Hubs::Billing` writes the hub at the matching nested path, such as `app/models/console/hubs/billing.rb`.
    - In an app it writes the hub under `app/models` and the hub's wiring test under `test/models`.
 
    The generated hub:
@@ -177,4 +179,5 @@ hub_kernel lets a hub, one domain area written as a module, state what it needs
 - Every exposed method is listed with `exposes`, and the exposed-list check passes.
 - When an exposed method gains, loses or renames a keyword, update its `takes:` in the same change.
 - When a hub gains a port, tell the developer every host app must fill it, since calling it unfilled raises an error and the host's start check fails.
+- When a hub exposes its first method, tell the developer every host app must set the permission check and the account scope, since the host's start check fails while any hub exposes a method and either is unset or cannot be called.
 - Adding the gem to a host, filling ports, running the start check, setting the permission check and the account scope, and the host's hub and crossing checks belong to the install local and are out of scope here.

data/the_local/agents/hub_kernel-info.md

@@ -24,21 +24,23 @@ This local documents no commands. The surface belongs to the other two locals:
 
 Decide which side you are on:
 
-- You are wiring hubs into an app, or the app will not start because something is not wired: use **hub_kernel-install**.
+- You are wiring hubs into an app, or the app will not start because something is not wired or not filled: use **hub_kernel-install**.
 - You are writing or changing a hub, inside a domain gem or the app: use **hub_kernel-develop**.
 
 ## Conventions
 
-- **Hub** — one domain area, written as a module. In a domain gem it sits under the gem's namespace, such as Billing::Ledger.
+- **Hub** — one domain area, written as a module. In a domain gem it sits under the gem's namespace, such as Billing::Ledger. A hub is known to the app once it declares a port or lists a method callable by name.
 - **Ports** — what a hub needs from outside. Each has a name and the method the hub's own code calls, such as a spend recorder called as record_spend.
 - **Filling ports** — the host app sets each of a hub's ports to any callable, usually another hub's method, in its setup that runs again on every code reload. Ports are "wired" once they are filled.
-- **Start check** — the app refuses to start while any hub's ports are not wired, and names each one, such as "Supplies' spend recorder is not wired".
+- **Start check** — the app refuses to start while any hub's ports are not wired, and names each one, such as "Supplies' spend recorder is not wired". While any hub lists a method callable by name, it also refuses to start until the permission check and the account scope are both set to something that can be called, and names whichever is missing or cannot be called. An app whose hubs list no such methods starts without either.
 - **Hub check** — a host test that fails naming each of a hub's ports left unfilled or filled with something that cannot be called. A domain gem never runs it, since the gem never fills its own ports.
-- **Call by name** — a caller reaches a hub method by its name as a string, with the values sent, the person, and the account. Unknown names, a missing person or account, and missing required values are refused.
+- **Call by name** — a caller reaches a hub method by its name as a string, with the values sent, the person, and the account. A missing person or account, an unknown name, a call the permission check does not allow, and missing required values are each refused, in that order. Only the values the method is listed with are passed on.
 - **What a person may call** — the hub's list of methods callable by name, kept to those the permission check allows for one person on one account. Asking with no person or no account is refused, the same as a call by name. A hub that lists nothing, or a person allowed nothing, gets an empty list rather than an error.
 - **Action** — the name a permission is asked for, made of the hub and the method, such as supplies:record_purchase.
 - **Permission check** — one host-wide rule answering true or false for a person, an action, and an account. Any other answer is an error.
 - **Account scope** — one host-wide wrapper that runs each call by name inside the account it was made for.
 - **Refusing** — what a hub does when it will not do what was asked, and its reason reaches the caller unchanged.
+- **Listed-methods check** — a hub's own test that fails naming each listed method the hub has no method for, and each one listed with values it does not take.
 - **Crossing** — a file in one hub naming a class another hub owns. A constant inside that class counts.
-- **Crossing map** — the host's statement of which classes each hub owns, plus the classes shared by all, the host's own layer, each hub's interface module, and any namespace a hub owns whole. Only the host's layer may name a hub's interface module, and a view belongs to the hub that owns its controller.
+- **Crossing map** — the host's statement of which classes each hub owns, plus the classes shared by all, the host's own layer, each hub's interface module, and any namespace a hub owns whole. Only the host's layer may name a hub's interface module. A view belongs to the hub that owns its controller, then to the hub that owns the record its folder is named after, and otherwise to the host's layer.
+- **Crossing check** — a host test that fails naming each crossing, each class no hub owns, each class given to two hubs, and each class the map names that no longer exists. It also fails when none of the files it read belongs to a hub, so a wrong file pattern does not pass unnoticed.

data/the_local/agents/hub_kernel-install.md

@@ -12,8 +12,8 @@ hub_kernel lets a Rails host app fill the ports each hub declares, refuse to sta
 
 ## Interface
 - `gem "hub_kernel"` — the Gemfile line that adds the gem to the host app.
-- `HubKernel::Hubs.check!` — raises `HubKernel::UnwiredPortError` naming every unfilled port of every loaded hub, one per line, such as "Supplies' spend recorder is not wired".
-- `HubKernel::Hubs.list` — the hubs that have loaded and declared at least one port.
+- `HubKernel::Hubs.check!` — raises `HubKernel::UnwiredPortError` naming every unfilled port of every loaded hub, one per line, such as "Supplies' spend recorder is not wired", and, while any loaded hub exposes a method, the permission check or the account scope when either is unset or cannot be called.
+- `HubKernel::Hubs.list` — the hubs that have loaded and declared at least one port or exposed at least one method.
 - `HubKernel::UnwiredPortError` — raised by the start check, by calling an unfilled port, by a call by name while the permission check or the account scope is unset, and by listing what a person may call from a hub that exposes at least one method while the permission check is unset.
 - `HubKernel::Authz.check` — the host-wide permission rule, a callable taking a person, an action and an account and answering `true` or `false`.
 - `HubKernel::Context.scope` — the host-wide account scope, a callable taking an account and a block and running the block inside that account.
@@ -42,22 +42,27 @@ hub_kernel lets a Rails host app fill the ports each hub declares, refuse to sta
 
    A port accepts any object that responds to `call`. The start check only sees hubs that have loaded, so name every hub in this block. Run `HubKernel::Hubs.list` in `bin/rails console` to see which hubs it saw.
 
-4. Ask the developer whether any interface, such as a JSON API, calls hub methods by name or lists which of a hub's exposed methods a person may call. If neither, skip to step 6.
+4. Run `bin/rails runner 'HubKernel::Hubs.check!'`. If the error names "hub_kernel's permission check" or "hub_kernel's account scope", a loaded hub exposes a method and step 5 is required. If it names neither, skip to step 6.
 
-5. Ask the developer for the app's permission rule and the account scope, since neither has a default. Set both once, in the same initializer:
+5. Ask the developer for the app's permission rule and the account scope, since neither has a default. Set both in the same `to_prepare` block, before the start check:
 
    ```ruby
-   HubKernel::Authz.check = ->(person, action, account) { Permissions.allow?(person, action, account) }
-   HubKernel::Context.scope = ->(account, &call) { Current.set(account: account, &call) }
+   Rails.application.config.to_prepare do
+     Supplies.spend_recorder = Finance.method(:record_spend)
+     HubKernel::Authz.check = ->(person, action, account) { Permissions.allow?(person, action, account) }
+     HubKernel::Context.scope = ->(account, &call) { Current.set(account: account, &call) }
+     HubKernel::Hubs.check!
+   end
    ```
 
+   - While any loaded hub exposes a method, the start check refuses to start until both are set to something that responds to `call`.
    - The permission check answers both a call by name and a listing of what a person may call, so the two always agree.
    - Listing what a person may call needs only the permission check, while a call by name needs both.
-   - The action is a string made of the hub and the method, such as `"supplies:record_purchase"`.
+   - The action is a string made of the hub's own name, without its namespace and in snake case, then the method, such as `"supplies:record_purchase"` for `Shop::Supplies`.
    - The permission check must answer exactly `true` or `false`, and any other answer makes the call or the listing raise an error.
    - The account scope must take the block and run it, or the hub method never runs.
 
-6. Add one hub check per hub to the host's tests, such as `test/hubs/supplies_hub_test.rb`:
+6. Add one hub check to the host's tests for each hub that declares at least one port, such as `test/hubs/supplies_hub_test.rb`:
 
    ```ruby
    require "hub_kernel/conformance/hub"
@@ -69,7 +74,8 @@ hub_kernel lets a Rails host app fill the ports each hub declares, refuse to sta
    end
    ```
 
-   The `require` line is needed because the gem does not load the test modules on its own.
+   - The `require` line is needed because the gem does not load the test modules on its own.
+   - A hub that exposes methods but declares no port gets no hub check, since the check errors on a hub with no ports.
 
 7. Ask the developer for the crossing map, since only they know which hub owns which class:
    - which classes each hub owns;
@@ -109,12 +115,14 @@ hub_kernel lets a Rails host app fill the ports each hub declares, refuse to sta
 
 ## Conventions
 - After installing, `bin/rails runner 'HubKernel::Hubs.check!'` exits with no error, and every hub check and the crossing check pass.
-- The start check reports unfilled ports only, while the hub check also reports a port filled with something that cannot be called.
+- The start check reports unfilled ports, and the permission check or account scope when unset or not callable while a hub exposes a method.
+- The hub check reports one hub's unfilled ports and each port filled with something that cannot be called, which the start check does not report.
 - A domain gem never runs the hub check, since it never fills its own ports, so the hub check always lives in the host's tests.
 - A view belongs to the hub that owns its controller, then to the hub that owns the record its folder is named after, and otherwise to the host's layer.
 - A constant inside another hub's class counts as naming that class.
-- Only the host's layer may name a hub's interface module.
+- A hub's interface module may be named by the host's layer and by that hub, and by no other hub.
 - A class listed by name under `owners` belongs to that hub even inside another hub's namespace.
+- The check for unowned classes reads only Ruby files outside `app/views`, so a view never needs its own entry in the map.
 - The crossing check fails with "The crossing check found no files to read" when its `files:` pattern matches nothing the map owns, so fix the pattern or the map rather than the test.
-- When a hub gains a port, fill it in the `to_prepare` block. When a class is added, renamed or removed, update the crossing map, since the check fails on a class no hub owns and on a mapped class that no longer exists.
+- When a hub gains a port, fill it in the `to_prepare` block. When a hub first exposes a method, set the permission check and the account scope there too. When a class is added, renamed or removed, update the crossing map, since the check fails on a class no hub owns and on a mapped class that no longer exists.
 - Writing a hub, declaring its ports, and listing the methods it exposes are not part of installing and are out of scope here.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.18.0
 platform: ruby
 authors:
 - tylercschneider