hub_kernel 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 026174ef5963518769182562042464615e204f2a32f7e4260c9ed390fc5b2160
-  data.tar.gz: 5d2fbdbb14248e8e145eb545246063e883fd196fb68b930180ff9b067a9c341c
+  metadata.gz: 3efd66220ac58f67d7c6018b2e552f70641539e11da6ef13810d274cb1daea52
+  data.tar.gz: 803ca1aa3d1258ae639ae2a6beb842b8e969f213b3d604e07d7acff7b9dc6523
 SHA512:
-  metadata.gz: 9a7a2a568be438e982a2c0d688fdc61e5fd4ade3b49070d3ffccff71e662b6748185e2e19a1b1beedb6f3c2d14bf5e899faf12598ce7cbcf6e225d7a8c859389
-  data.tar.gz: 5f189db08ded136cb2adc871613545ba62f8f163938b63587e47a7382a745d12cceff6606fb7a5f137b4b0db5ca2c09db321cd91dc600140a7c4edde1e2f4c1f
+  metadata.gz: 111dfbefdd5d3fbb62241dc8142a5b16b8626f9af8d227df56033c60205a2d2bbd9db4a27fa39e487f31ea891dd1041a18c76519e5ba88e2a7a7279659e667cc
+  data.tar.gz: bac66dfb083524ae2f30f2db97c637df7d88a70f19ce59f264acdbc40baa24e39fa3218ef19d472713e3c3c6ba7df8cf959078f2993ceddbc0b9790b44badff1

data/README.md

@@ -105,6 +105,11 @@ The test fails and names each port the app left unfilled, and each port filled w
 something that cannot be called.
 
 ### The exposed list
+The exposed list, calling by name, the permission check, the account scope and the errors
+they raise come from hub_kernel-interface, which hub_kernel depends on, so a hub keeps
+writing `extend HubKernel::Exposes` with no other gem to add. Interface gems such as
+hub_kernel-api depend on hub_kernel-interface alone.
+
 A hub names each method outside callers may reach, the values it takes, and whether it
 writes. A layer such as a JSON endpoint looks a method up by name and serves only what
 the hub exposes:
@@ -148,7 +153,7 @@ It refuses a missing person or account as a call by name does, and a hub that ex
 nothing, or a person allowed nothing, gets an empty list.
 
 ### The host's permission check and account scope
-Every call by name asks the host whether the person may take the action on the account,
+hub_kernel-interface holds both settings. Every call by name asks the host whether the person may take the action on the account,
 and runs the method inside the host's scope for that account. The host sets both once
 for the whole app:
 

data/lib/hub_kernel/action.rb

@@ -1,6 +1,6 @@
-module HubKernel
-  class MissingArgumentError < ArgumentError; end
+require "hub_kernel/exposes"
 
+module HubKernel
   module Action
     attr_reader :person, :account, :values
 

data/lib/hub_kernel/hubs.rb

@@ -1,14 +1,17 @@
 require "hub_kernel/authz"
 require "hub_kernel/context"
+require "hub_kernel/interface/exposing_hubs"
 
 module HubKernel
   module Hubs
     def self.add(hub)
-      list.reject! { |listed| listed.name == hub.name }
-      list << hub
+      registered.reject! { |listed| listed.name == hub.name }
+      registered << hub
     end
 
-    def self.list = @list ||= []
+    def self.registered = @registered ||= []
+
+    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

data/lib/hub_kernel/ports.rb

@@ -1,9 +1,9 @@
 require "active_support/core_ext/string/inflections"
 require "hub_kernel/hubs"
 
-module HubKernel
-  class UnwiredPortError < StandardError; end
+require "hub_kernel/exposes"
 
+module HubKernel
   module Ports
     def port(name, as:)
       Hubs.add(self)

data/lib/hub_kernel/version.rb

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

data/lib/hub_kernel.rb

@@ -1,3 +1,4 @@
+require "hub_kernel-interface"
 require "hub_kernel/version"
 require "hub_kernel/engine"
 require "hub_kernel/action"
@@ -5,7 +6,6 @@ require "hub_kernel/answer"
 require "hub_kernel/follow_up"
 require "hub_kernel/markup"
 require "hub_kernel/ports"
-require "hub_kernel/exposes"
 
 module HubKernel
 end

data/the_local/agents/hub_kernel-develop.md

@@ -164,10 +164,7 @@ hub_kernel lets a hub, one domain area written as a module, state what it needs
     - Each entry is the same one `exposed` answers.
     - A hub that lists nothing answers `[]` from both, and a person allowed nothing answers `[]` from `exposures_for`.
     - `exposures_for` asks the permission check once per entry with the same action name `call_exposed` uses, such as `"supplies:record_purchase"`, and runs no hub method.
-    - `exposures_for` fails in this order, and each failure stops it:
-      1. `HubKernel::MissingArgumentError` when `person:` or `account:` is `nil`.
-      2. An error naming the host's permission check when the host has not set it and the hub lists at least one method.
-      3. `HubKernel::NonBooleanAnswerError` when the permission check answers anything but `true` or `false`.
+    - `exposures_for` raises `HubKernel::MissingArgumentError` when `person:` or `account:` is `nil`, before asking the permission check.
     - Pass the same `person:` and `account:` the interface passes to `call_exposed`.
     - Ask the developer whether the interface shows every exposed method or only those the person may call. Do not pick yourself.
 

data/the_local/agents/hub_kernel-info.md

@@ -11,7 +11,7 @@ This local explains hub_kernel and the words it uses. It makes no changes and gi
 
 hub_kernel splits a Rails app into hubs, where each hub is one area of the domain, such as supplies or finance, usually shipped in its own domain gem. A hub states what it needs from outside itself as named ports, and the host app decides what fills each one, so a hub never names another hub's code directly.
 
-A hub also lists the methods outside callers may reach by name, with the values each takes and whether it writes. An interface such as a JSON API calls through that list, and every call is checked against the host's permission rule and run inside the host's account scope. The same list can be read back whole, or cut down to only the methods one person is allowed to call on one account, so an interface can show a person what they may do before they try it. Reach for hub_kernel when an app has several domain areas that should talk to each other only through declared entry points, and you want the app to refuse to start, or the suite to fail, when that is not true.
+A hub also lists the methods outside callers may reach by name, with the values each takes and whether it writes. An interface such as a JSON API calls through that list, and every call is checked against the host's permission rule and run inside the host's account scope. The same list can be read back whole, or cut down to only the methods one person is allowed to call on one account, so an interface can show a person what they may do before they try it. That list, calling by name, the permission check and the account scope come from hub_kernel-interface, which hub_kernel depends on, so a hub that lists methods needs no second gem. Reach for hub_kernel when an app has several domain areas that should talk to each other only through declared entry points, and you want the app to refuse to start, or the suite to fail, when that is not true.
 
 ## Interface
 
@@ -29,7 +29,8 @@ Decide which side you are on:
 
 ## Conventions
 
-- **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.
+- **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, and the start check covers both kinds.
+- **hub_kernel-interface** — the smaller gem hub_kernel builds on, holding the methods-callable-by-name list, the permission check and the account scope. Interface gems such as hub_kernel-api depend on it alone, while hubs and host apps keep depending on hub_kernel.
 - **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". 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.

data/the_local/agents/hub_kernel-install.md

@@ -14,7 +14,7 @@ hub_kernel lets a Rails host app fill the ports each hub declares, refuse to sta
 - `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", 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::UnwiredPortError` — raised by the start check, by calling an unfilled port, and by a call by name while the permission check or the account scope 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.
 - `HubKernel::Conformance::Hub` — a test module that fails naming each of one hub's ports left unfilled or filled with something that cannot be called.
@@ -28,6 +28,8 @@ hub_kernel lets a Rails host app fill the ports each hub declares, refuse to sta
    gem "hub_kernel"
    ```
 
+   `bundle install` also installs hub_kernel-interface, which holds the permission check and the account scope, so add no other gem for them.
+
 2. List the hubs the app uses and each port they declare. Ask the developer what fills each port, such as another hub's method. Do not pick a filler yourself.
 
 3. Fill every port and run the start check in a `to_prepare` block in an initializer, such as `config/initializers/hubs.rb`, so both run again after every code reload:
@@ -57,7 +59,6 @@ hub_kernel lets a Rails host app fill the ports each hub declares, refuse to sta
 
    - 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'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.

data/the_local/interface.yml

@@ -32,10 +32,7 @@ sources:
   - lib/hub_kernel.rb
   - lib/hub_kernel/ports.rb
   - lib/hub_kernel/hubs.rb
-  - lib/hub_kernel/exposes.rb
   - lib/hub_kernel/action.rb
-  - lib/hub_kernel/authz.rb
-  - lib/hub_kernel/context.rb
   - lib/hub_kernel/crossings.rb
   - lib/hub_kernel/conformance/hub.rb
   - lib/hub_kernel/conformance/exposed.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - tylercschneider
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 8.1.3
+- !ruby/object:Gem::Dependency
+  name: hub_kernel-interface
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 description: 'hub_kernel wraps a domain and connects it to a host app''s infrastructure
   through named ports. It ships no domain of its own: each hub is hub_kernel wrapped
   around one domain.'
@@ -40,16 +54,13 @@ files:
 - lib/hub_kernel.rb
 - lib/hub_kernel/action.rb
 - lib/hub_kernel/answer.rb
-- lib/hub_kernel/authz.rb
 - lib/hub_kernel/conformance/action.rb
 - lib/hub_kernel/conformance/crossings.rb
 - lib/hub_kernel/conformance/exposed.rb
 - lib/hub_kernel/conformance/hub.rb
 - lib/hub_kernel/conformance/partial.rb
-- lib/hub_kernel/context.rb
 - lib/hub_kernel/crossings.rb
 - lib/hub_kernel/engine.rb
-- lib/hub_kernel/exposes.rb
 - lib/hub_kernel/follow_up.rb
 - lib/hub_kernel/hubs.rb
 - lib/hub_kernel/markup.rb

data/lib/hub_kernel/authz.rb

@@ -1,8 +0,0 @@
-module HubKernel
-  class NonBooleanAnswerError < StandardError; end
-  class NotAllowed < StandardError; end
-
-  module Authz
-    singleton_class.attr_accessor :check
-  end
-end

data/lib/hub_kernel/context.rb

@@ -1,5 +0,0 @@
-module HubKernel
-  module Context
-    singleton_class.attr_accessor :scope
-  end
-end

data/lib/hub_kernel/exposes.rb

@@ -1,92 +0,0 @@
-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
-  class Refused < StandardError; end
-
-  module Exposes
-    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
-
-    def exposed(name) = exposed_methods[name.to_s]
-
-    def exposures = exposed_methods.values
-
-    def exposures_for(person:, account:)
-      refuse_without_caller(person, account)
-
-      exposures.select { |exposure| allowed?(exposure, person, account) }
-    end
-
-    def call_exposed(name, values:, person:, account:)
-      refuse_without_caller(person, account)
-
-      exposure = exposed(name) || raise(UnexposedMethodError, "#{exposing_hub} does not expose #{name}")
-      refuse_unless_allowed(exposure, person, account)
-      refuse_missing_values(exposure, values)
-      within_account(account) { public_send(exposure.name, **values.slice(*exposure.takes)) }
-    end
-
-    def exposure_problems
-      exposed_methods.values.filter_map { |exposure| exposure_problem(exposure) }
-    end
-
-    private
-
-    def exposed_methods = @exposed_methods ||= {}
-
-    def exposing_hub = name.demodulize
-
-    def refuse_without_caller(person, account)
-      raise MissingArgumentError, "A call by name needs a person" if person.nil?
-      raise MissingArgumentError, "A call by name needs an account" if account.nil?
-    end
-
-    def refuse_unless_allowed(exposure, person, account)
-      raise NotAllowed, "#{exposing_hub} #{exposure.name}" unless allowed?(exposure, person, account)
-    end
-
-    def allowed?(exposure, person, account)
-      raise UnwiredPortError, "hub_kernel's permission check is not filled" unless Authz.check
-
-      answer = Authz.check.call(person, "#{exposing_hub.underscore}:#{exposure.name}", account)
-      raise NonBooleanAnswerError, "The permission check must answer true or false, got #{answer.inspect}" unless [ true, false ].include?(answer)
-
-      answer
-    end
-
-    def within_account(account, &call)
-      raise UnwiredPortError, "hub_kernel's account scope is not filled" unless Context.scope
-
-      Context.scope.call(account, &call)
-    end
-
-    def refuse_missing_values(exposure, values)
-      missing = keywords(exposure, :keyreq) - values.keys
-      raise MissingArgumentError, "Give #{missing.join(", ")}" if missing.any?
-    end
-
-    def exposure_problem(exposure)
-      return "#{exposing_hub} exposes #{exposure.name}, which it has no method for" unless respond_to?(exposure.name)
-      return if takes_listed_values?(exposure)
-
-      "#{exposing_hub} exposes #{exposure.name} with #{exposure.takes.join(", ")}, but it takes #{keywords(exposure, :keyreq, :key).join(", ")}"
-    end
-
-    def takes_listed_values?(exposure)
-      (keywords(exposure, :keyreq) - exposure.takes).empty? && (takes_any_values?(exposure) || (exposure.takes - keywords(exposure, :keyreq, :key)).empty?)
-    end
-
-    def takes_any_values?(exposure) = method(exposure.name).parameters.any? { |kind, _| kind == :keyrest }
-
-    def keywords(exposure, *kinds) = method(exposure.name).parameters.filter_map { |kind, value| value if kinds.include?(kind) }
-  end
-end