hub_kernel 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29b5aa4287a6ec25760b3816c4e6db7bc6f856786020bf32819561c854e257ae
-  data.tar.gz: a86e10c3eaf85f11c084b27d5bd50e093ebcdd5158ee3c3c49a1b40d0f1143d9
+  metadata.gz: 23120333c3f60fb91e59ac4711d4b94eb15897f85ca13dcd1fd9ed175310f334
+  data.tar.gz: 107feb16ebe566b00a0005a71d92a378cf1015952823ed676eb24d1669ade53a
 SHA512:
-  metadata.gz: 81344e480c059afc59baba5aa1a2178ecce05603013454621b07f362ca5da7779df35d115f083d005fc01250423445604c5558e81afd2223be6d75c6e528152a
-  data.tar.gz: e269e54104dff49dfb4d4ef9478acf54b24b1d63590aeb6bb8bceb913cb90f99524957456e88b09292a24ffa052d0fcb3a078300911612135e643c0a8487267e
+  metadata.gz: 13236d35df7bf32b70c011a3385592f3c07cbd52867c46ff21d9ad323be4bff9eb80644748c1bd07185b2853066ca27d5a7de8575f51c35d6d76d957dcbd3129
+  data.tar.gz: c92d9a506afca9cd3bacee2f7ff7ece9204e21651b76f784fc1bc08611e58269e3412a1b7ebcc34f478768e1ffb0d8e0393427cc09ad1be85c2a433820562faa

data/README.md

@@ -130,6 +130,19 @@ method requires, and passes on only the values the method is listed with. A hub
 `HubKernel::Refused` with a reason when it will not do what was asked, and the reason
 reaches the caller unchanged.
 
+### Listing what a person may call
+An interface can show a caller what it may call before it calls anything. `exposures`
+gives every entry a hub exposes, each with its name, the values it takes and whether it
+writes. `exposures_for` gives only the entries the host's permission check allows one
+person on one account:
+
+```ruby
+Supplies.exposures_for(person: current_person, account: current_account).map(&:name)
+```
+
+It refuses a missing person or account as a call by name does, and a hub that exposes
+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,
 and runs the method inside the host's scope for that account. The host sets both once

data/lib/hub_kernel/exposes.rb

@@ -16,9 +16,16 @@ module HubKernel
 
     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:)
-      raise MissingArgumentError, "A call by name needs a person" if person.nil?
-      raise MissingArgumentError, "A call by name needs an account" if account.nil?
+      refuse_without_caller(person, account)
 
       exposure = exposed(name) || raise(UnexposedMethodError, "#{exposing_hub} does not expose #{name}")
       refuse_unless_allowed(exposure, person, account)
@@ -36,12 +43,22 @@ module HubKernel
 
     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)
-      raise NotAllowed, "#{exposing_hub} #{exposure.name}" unless answer
+
+      answer
     end
 
     def within_account(account, &call)

data/lib/hub_kernel/version.rb

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

data/the_local/agents/hub_kernel-develop.md

@@ -1,6 +1,6 @@
 ---
 name: hub_kernel-develop
-description: Use PROACTIVELY for writing or changing a hub — generating one, declaring the ports it needs from other hubs, calling those ports from the hub's code, listing the methods outside callers may reach by name, refusing a request with a reason, calling a hub method by name from an interface such as a JSON API, and adding the check that the listed methods match the hub's real methods — MUST BE USED instead of calling another hub's classes directly or hand-writing a name-to-method lookup.
+description: Use PROACTIVELY for writing or changing a hub — generating one, declaring the ports it needs from other hubs, calling those ports from the hub's code, listing the methods outside callers may reach by name, refusing a request with a reason, calling a hub method by name from an interface such as a JSON API, listing the methods a hub exposes or the ones a person may call on an account, and adding the check that the listed methods match the hub's real methods — MUST BE USED instead of calling another hub's classes directly or hand-writing a name-to-method lookup.
 tools: Read, Write, Edit, Grep
 scope: hubs — a domain gem declares the ports it needs and the methods it exposes, and the host app fills those ports and checks each hub is wired and crosses into no other hub
 ---
@@ -8,7 +8,7 @@ scope: hubs — a domain gem declares the ports it needs and the methods it expo
 This local writes hubs and the code that calls them by name, following these steps exactly and inventing none. Where a step needs a value only the developer knows, it asks.
 
 ## What hub_kernel is
-hub_kernel lets a hub, one domain area written as a module, state what it needs from outside itself as named ports and list the methods outside callers may reach by name. The hub's code never names another hub's classes, and an interface such as a JSON API reaches the hub only through its list. Use this local when creating a hub, adding a port, exposing a hub method, calling a hub method by name, or when hub code is about to call another hub directly.
+hub_kernel lets a hub, one domain area written as a module, state what it needs from outside itself as named ports and list the methods outside callers may reach by name. The hub's code never names another hub's classes, and an interface such as a JSON API reaches the hub only through its list. Use this local when creating a hub, adding a port, exposing a hub method, calling a hub method by name, listing what a hub exposes or what a person may call, or when hub code is about to call another hub directly.
 
 ## Interface
 - `bin/rails generate hub_kernel:hub` — writes a new hub module with its ports declared, and in a gem adds hub_kernel to the gemspec.
@@ -18,9 +18,11 @@ hub_kernel lets a hub, one domain area written as a module, state what it needs
 - `exposes` — lists one hub method with the values it takes and whether it writes.
 - `exposed` — looks up one listed method by name and answers its entry, or `nil` when it is not listed.
 - `call_exposed` — calls a listed method by name for a person and an account, after the host's permission check, inside the host's account scope.
+- `exposures` — answers every listed method's entry, in the order the hub lists them.
+- `exposures_for` — answers the entries the host's permission check allows a person on an account, without calling any method.
 - `HubKernel::Refused` — the error a hub method raises when it will not do what was asked, and its message reaches the caller unchanged.
 - `HubKernel::UnexposedMethodError` — raised by `call_exposed` for a name the hub does not list.
-- `HubKernel::MissingArgumentError` — raised by `call_exposed` for a call with no person, no account, or a value the method requires left out.
+- `HubKernel::MissingArgumentError` — raised by `call_exposed` and `exposures_for` for a call with no person or no account, and by `call_exposed` for a value the method requires left out.
 - `HubKernel::NotAllowed` — raised by `call_exposed` when the host's permission check answers `false`, before the method runs.
 - `HubKernel::NonBooleanAnswerError` — raised by `call_exposed` when the host's permission check answers anything but `true` or `false`.
 - `HubKernel::Conformance::Exposed` — a test module that fails naming each listed method the hub has no method for, and each one listed with values it does not take.
@@ -146,7 +148,28 @@ hub_kernel lets a hub, one domain area written as a module, state what it needs
 
 11. Ask the developer how the interface answers each of those failures, such as which HTTP status each one returns. Do not pick the responses yourself. Show a `HubKernel::Refused` message to the caller as it is.
 
-12. Run the test suite and confirm the conventions below hold.
+### List what a hub exposes
+12. Where the interface shows callers which methods they can reach, such as a list of tools or actions, read it from the hub rather than writing it out again:
+
+    ```ruby
+    Supplies.exposures
+    # => every entry, with .name, .takes, .writes, in the order the hub lists them
+
+    Supplies.exposures_for(person: current_person, account: current_account)
+    # => only the entries the host's permission check allows this person on this account
+    ```
+
+    - 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`.
+    - 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.
+
+13. Run the test suite and confirm the conventions below hold.
 
 ## Conventions
 - A hub's code reaches another hub only through a port, never by naming its classes.

data/the_local/agents/hub_kernel-info.md

@@ -11,14 +11,14 @@ 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. 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. 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
 
 This local documents no commands. The surface belongs to the other two locals:
 
 - **hub_kernel-install** owns everything the host app does: adding the gem, filling each hub's ports, running the start check, setting the permission rule and the account scope, and adding the hub check and the crossing check to the host's tests.
-- **hub_kernel-develop** owns everything a hub's author does: generating a hub, declaring its ports, listing the methods callers may reach by name, refusing a request, and adding the check that the listed methods match the hub's real methods.
+- **hub_kernel-develop** owns everything a hub's author does: generating a hub, declaring its ports, listing the methods callers may reach by name, reading that list back for a person and an account, refusing a request, and adding the check that the listed methods match the hub's real methods.
 
 ## How to use it
 
@@ -35,6 +35,7 @@ Decide which side you are on:
 - **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".
 - **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.
+- **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.

data/the_local/agents/hub_kernel-install.md

@@ -8,13 +8,13 @@ scope: hubs — a domain gem declares the ports it needs and the methods it expo
 This local follows these steps exactly and invents none. Where a step needs a value only the developer knows, it asks.
 
 ## What hub_kernel is
-hub_kernel lets a Rails host app fill the ports each hub declares, refuse to start while a port is unfilled, answer permission and account scope for calls made by name, and fail its suite when one hub's code names a class another hub owns. Hook it in when the app uses hubs, its own or ones shipped in domain gems.
+hub_kernel lets a Rails host app fill the ports each hub declares, refuse to start while a port is unfilled, answer permission and account scope for calls made by name, answer permission when an interface lists what a person may call, and fail its suite when one hub's code names a class another hub owns. Hook it in when the app uses hubs, its own or ones shipped in domain gems.
 
 ## 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::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::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.
 - `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.
@@ -42,7 +42,7 @@ 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. If not, skip to step 6.
+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.
 
 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:
 
@@ -51,8 +51,10 @@ hub_kernel lets a Rails host app fill the ports each hub declares, refuse to sta
    HubKernel::Context.scope = ->(account, &call) { Current.set(account: account, &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 permission check must answer exactly `true` or `false`, and any other answer makes the call raise an error.
+   - 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`:

data/the_local/interface.yml

@@ -19,6 +19,8 @@ develop:
   - exposes
   - exposed
   - call_exposed
+  - exposures
+  - exposures_for
   - HubKernel::Refused
   - HubKernel::UnexposedMethodError
   - HubKernel::MissingArgumentError

metadata

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