hub_kernel-api 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16098ba0ceb84acb8536551867732dae646869b478d18299bb85a6839d1db8e1
-  data.tar.gz: 5b5b3d49bd804284796e8c7702b861b704c6e6ac77dba9a8e90b73f216845d52
+  metadata.gz: a1ab149c312d3eededfba4646f9903a4113369fed1869f5e9165623d60e05b0d
+  data.tar.gz: 0c3f1837992e569bb231859be331eabaf3dfa0d37f7f4494078bed6fb1e8d68e
 SHA512:
-  metadata.gz: 816027b58264d0c192482819bd043cf28f14c3ec65c91043953c7fba75abdf21725c09db3809f65f506cdab7e89b04a556d7a225cce99da925e1c4b4726fbffc
-  data.tar.gz: 2befb90df535ea4e2df15e8d229b058d46339bf730937dabb3e4511bc890abc0a1d2a1f945b6b38b15258453d7ea9c8ef57212685ff0a7f7e8e32038de40bfbb
+  metadata.gz: 00c278912444e2bf2ad857e06a48fc16d166e251d2e51ee3a60679e7149eb422c1e49eb46340273a22774104a152b5b1506bd705898484ff20f0a36b036e2377
+  data.tar.gz: 8eb8929362a24395413e2191cc40e5f6d99089f13624bcb8b917af814c1bedfd7022aa75ef9541d5beeb7d1ba60c5c5ed0c597f8a87f951f97d0b183a9274144

data/README.md

@@ -1,8 +1,9 @@
 # hub_kernel-api
 
 Serves a hub_kernel hub's exposed methods as a JSON API. The host lists the hubs it
-serves, and every call goes through the host's own sign-in, then hub_kernel's permission
-check and account scope.
+serves, and every call goes through the host's own sign-in, then the permission check and
+account scope that hub_kernel-interface holds. It depends on hub_kernel-interface alone, not
+on hub_kernel.
 
 ## Usage
 
@@ -26,8 +27,13 @@ exposes no methods, when two served hubs answer at the same address, or when a s
 hub's exposed list has a problem, naming each. Inside `to_prepare` it runs again after
 every code reload.
 
-The base controller's own sign-in runs before every call. hub_kernel's permission check
-and account scope must also be set, as hub_kernel's readme describes. Mount the engine:
+`HubKernel::Api.hubs` reads and writes hub_kernel-interface's one served list,
+`HubKernel::Interface.hubs`, so every interface gem in the host, such as hub_kernel-mcp,
+serves the same hubs at the same names. The list is set once, through either gem.
+
+The base controller's own sign-in runs before every call. The permission check and account
+scope must also be set, `HubKernel::Authz.check` and `HubKernel::Context.scope`, as
+hub_kernel-interface's readme describes. Mount the engine:
 
 ```ruby
 mount HubKernel::Api::Engine => "/api/v1/hubs"

data/app/controllers/hub_kernel/api/hub_calls_controller.rb

@@ -8,8 +8,8 @@ module HubKernel
 
       def answer
         raise ActionController::RoutingError, "Not found" unless asked_with_the_right_verb?
-        return refuse_unlisted_values if unlisted_values.any?
 
+        HubKernel::Interface::CallReasons.refuse_unlisted_values(hub, params[:name], values: values, person: caller_person, account: caller_account)
         render json: { answer: hub.call_exposed(params[:name], values: values, person: caller_person, account: caller_account) }
       end
 
@@ -17,23 +17,11 @@ module HubKernel
 
       def asked_with_the_right_verb? = hub.exposed(params[:name])&.writes == request.post?
 
-      def refuse_unlisted_values
-        raise HubKernel::NotAllowed unless permitted?
-
-        refused(HubKernel::Refused.new("#{params[:name]} does not take #{unlisted_values.join(", ")}"))
-      end
-
-      def permitted? = hub.exposures_for(person: caller_person, account: caller_account).any? { |exposure| exposure.name.to_s == params[:name] }
-
-      def unlisted_values = values.keys - hub.exposed(params[:name]).takes
-
       def values = request.query_parameters.merge(request.request_parameters).deep_symbolize_keys
 
       def refused(refusal) = render(json: { error: refusal.message }, status: :unprocessable_content)
 
-      def missing_record(missing)
-        render json: { error: "No #{missing.model.demodulize.underscore.humanize(capitalize: false)} has the id #{missing.id}" }, status: :not_found
-      end
+      def missing_record(missing) = render(json: { error: HubKernel::Interface::CallReasons.missing_record(missing) }, status: :not_found)
     end
   end
 end

data/lib/hub_kernel/api/version.rb

@@ -1,5 +1,5 @@
 module HubKernel
   module Api
-    VERSION = "0.6.0"
+    VERSION = "0.8.0"
   end
 end

data/lib/hub_kernel/api.rb

@@ -1,36 +1,23 @@
-require "hub_kernel"
+require "hub_kernel-interface"
 require "hub_kernel/api/version"
 require "hub_kernel/api/engine"
 
 module HubKernel
   module Api
-    class UnservableHubError < StandardError; end
+    UnservableHubError = HubKernel::Interface::UnservableHubError
 
-    mattr_accessor :hubs, default: []
     mattr_accessor :base_controller, default: "ActionController::API"
     mattr_accessor :person_method
     mattr_accessor :account_method
 
-    def self.find(name) = addresses[name]
+    def self.hubs = HubKernel::Interface.hubs
 
-    def self.check!
-      problems = unexposed_hubs + shared_addresses + exposure_problems
-      raise UnservableHubError, problems.join("\n") if problems.any?
+    def self.hubs=(hubs)
+      HubKernel::Interface.hubs = hubs
     end
 
-    def self.addresses = served.to_h
+    def self.find(name) = HubKernel::Interface.find(name)
 
-    def self.served = hubs.flat_map { |entry| entry.is_a?(Hash) ? entry.to_a : [ [ entry.name.demodulize.underscore, entry ] ] }
-
-    def self.unexposed_hubs = served.map(&:last).reject { |hub| hub.respond_to?(:exposures) }.map { |hub| "#{hub.name} exposes no methods to serve" }
-
-    def self.shared_addresses
-      served.group_by(&:first).select { |_address, entries| entries.size > 1 }.map do |address, entries|
-        "#{entries.map { |_address, hub| hub.name }.join(" and ")} both answer at #{address}"
-      end
-    end
-
-    def self.exposure_problems = served.map(&:last).select { |hub| hub.respond_to?(:exposure_problems) }.flat_map(&:exposure_problems)
-    private_class_method :served, :unexposed_hubs, :shared_addresses, :exposure_problems
+    def self.check! = HubKernel::Interface.check!
   end
 end

data/the_local/agents/hub_kernel-api-develop.md

@@ -2,7 +2,7 @@
 name: hub_kernel-api-develop
 description: Use PROACTIVELY for calling a served hub over HTTP — listing the methods a caller may call at a hub's address, calling a read with GET, calling a write with POST, sending its values, and reading its answer or error status — MUST BE USED instead of hand-writing a controller or endpoint per hub method, or guessing at the API's responses.
 tools: Read, Write, Edit, Grep
-scope: hub JSON API — serving a hub_kernel hub's exposed methods as a JSON API in a host Rails app, each call behind the host's own sign-in and hub_kernel's permission check and account scope
+scope: hub JSON API — serving a hub_kernel hub's exposed methods as a JSON API in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope
 ---
 
 This local writes client code against the three endpoints below and follows the steps in
@@ -11,11 +11,11 @@ order. Where a step names a decision, it asks the developer and does not pick.
 ## What hub_kernel-api is
 
 A Rails engine that answers HTTP calls to the exposed methods of the hubs a host serves,
-each call made after the host's sign-in and checked and scoped by hub_kernel's permission
-check and account scope. Use this local when writing a front end, mobile app, service or
-request test that calls those methods, or when working out why a call answered as it did.
-Adding the gem, choosing the served hubs and mounting the engine belong to the install
-local.
+each call made after the host's sign-in and checked and scoped by the permission check and
+account scope that hub_kernel-interface holds. Use this local when writing a front end,
+mobile app, service or request test that calls those methods, or when working out why a
+call answered as it did. Adding the gem, choosing the served hubs and mounting the engine
+belong to the install local.
 
 ## Interface
 
@@ -32,8 +32,7 @@ Every path is relative to the path the host mounted the engine at, such as
 ## How to use it
 
 1. Find the path the host mounted the API at in its `config/routes.rb`. Every URL
-   below starts with it. If the API is not mounted,
-   stop and use the install local.
+   below starts with it. If the API is not mounted, stop and use the install local.
 
 2. Find the hub's address. A hub answers at its module name underscored, so `Supplies`
    answers at `supplies`, unless the host listed it under a name of its own, such as
@@ -106,6 +105,6 @@ Every path is relative to the path the host mounted the engine at, such as
 - The account a call is made for comes from the host's sign-in, never from a value in the
   request.
 - Only the methods a hub exposes are reachable; adding a method to the API means exposing
-  it on the hub in hub_kernel, not adding a route.
+  it on the hub, not adding a route.
 - Installing the gem, configuring it and choosing the served hubs are out of scope here;
   they belong to the install local.

data/the_local/agents/hub_kernel-api-info.md

@@ -2,7 +2,7 @@
 name: hub_kernel-api-info
 description: Use to learn what hub_kernel-api offers — serving a hub's exposed methods as a JSON API, the served hubs and their addresses, reads and writes, and how sign-in, permission and account scope apply to each call.
 tools: Read
-scope: hub JSON API — serving a hub_kernel hub's exposed methods as a JSON API in a host Rails app, each call behind the host's own sign-in and hub_kernel's permission check and account scope
+scope: hub JSON API — serving a hub_kernel hub's exposed methods as a JSON API in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope
 ---
 
 This local explains hub_kernel-api and makes no changes.
@@ -15,10 +15,13 @@ gem answers HTTP calls to their exposed methods and to a listing of them. It add
 business logic of its own: every answer is the return value of a method the hub
 already exposes.
 
+It depends on hub_kernel-interface alone, not on hub_kernel. hub_kernel-interface
+holds the permission check and the account scope, and the host sets both.
+
 Reach for it when a hub's exposed methods need to be called over HTTP, by a mobile
 app, another service or a front end, without writing a controller per method. Each
-call runs the host's own sign-in first, then hub_kernel's permission check and
-account scope, so the API never shows a caller more than the app itself would.
+call runs the host's own sign-in first, then hub_kernel-interface's permission check
+and account scope, so the API never shows a caller more than the app itself would.
 
 ## Interface
 
@@ -40,8 +43,8 @@ This local declares no commands. The surface is split between the other two loca
 
 ## Conventions
 
-- **Hub** — a hub_kernel module whose methods are declared as exposed. Only exposed
-  methods are reachable; nothing else on the hub is.
+- **Hub** — a module whose methods are declared as exposed through
+  hub_kernel-interface. Only exposed methods are reachable; nothing else on the hub is.
 - **Served hub** — a hub the host has listed for the API. A hub that is not served is
   answered as not found, as if it did not exist.
 - **Address** — the name a served hub answers at. By default it is the hub's module

data/the_local/agents/hub_kernel-api-install.md

@@ -2,7 +2,7 @@
 name: hub_kernel-api-install
 description: Use to hook hub_kernel-api into a project — adding the gem, naming the base controller and its person and account methods, listing the served hubs, running the startup check, and mounting the engine.
 tools: Bash, Read, Edit
-scope: hub JSON API — serving a hub_kernel hub's exposed methods as a JSON API in a host Rails app, each call behind the host's own sign-in and hub_kernel's permission check and account scope
+scope: hub JSON API — serving a hub_kernel hub's exposed methods as a JSON API in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope
 ---
 
 This local follows the steps below exactly and invents none. Where a step names a
@@ -10,12 +10,13 @@ decision, it asks the developer and does not pick.
 
 ## What hub_kernel-api is
 
-A Rails engine that serves the exposed methods of hub_kernel hubs as a JSON API; hook it
+A Rails engine that serves the exposed methods of hub_kernel hubs as a JSON API. Hook it
 in when a Rails app needs its hubs callable over HTTP.
 
 ## Interface
 
-- `gem "hub_kernel-api"` — the Gemfile line that adds the gem; it brings hub_kernel with it.
+- `gem "hub_kernel-api"` — the Gemfile line that adds the gem; it brings
+  hub_kernel-interface with it, and not hub_kernel.
 - `HubKernel::Api.base_controller=` — the name, as a String, of the host controller the
   API's controllers inherit from; defaults to `"ActionController::API"`.
 - `HubKernel::Api.person_method=` — the name, as a Symbol, of the method on the base
@@ -37,10 +38,11 @@ in when a Rails app needs its hubs callable over HTTP.
    gem "hub_kernel-api"
    ```
 
-2. Confirm hub_kernel's permission check and account scope are already configured in
-   the host. Every call is checked and scoped by them. If the host has a hub_kernel
-   install local, use it for this; otherwise stop and ask the developer how they are
-   set, and do not configure them from guesswork.
+2. Confirm the permission check and account scope that hub_kernel-interface holds are
+   already set in the host: `HubKernel::Authz.check` and `HubKernel::Context.scope`.
+   Every call is checked and scoped by them. If the host has a hub_kernel-interface
+   install local, use it for this. Otherwise stop and ask the developer how they are
+   set, and do not set them from guesswork.
 
 3. Ask the developer which controller the API inherits from. It must:
    - run the host's sign-in before every action, as a `before_action` that refuses an
@@ -56,8 +58,7 @@ in when a Rails app needs its hubs callable over HTTP.
 4. Ask the developer which hubs to serve and at what address each answers. A hub module
    answers at its module name underscored, so `Supplies` answers at `supplies`. To use a
    different address, the hub is listed as a one-pair Hash, `{ "money" => Billing::Ledger }`.
-   Every listed hub must be a hub_kernel hub that exposes methods, and no two may share
-   an address.
+   Every listed hub must expose methods, and no two may share an address.
 
 5. Create `config/initializers/hub_kernel_api.rb` with the answers from steps 3 and 4:
 
@@ -88,11 +89,11 @@ in when a Rails app needs its hubs callable over HTTP.
 7. Boot the app, for example with `bin/rails runner "puts :ok"`. A
    `HubKernel::Api::UnservableHubError` at boot names each problem:
    - `<Hub> exposes no methods to serve` — the entry is not a hub with exposed methods;
-     remove it, or expose methods on it in hub_kernel.
+     remove it, or expose methods on it.
    - `<Hub> and <Hub> both answer at <address>` — give one of them its own address with
      a one-pair Hash.
-   - Any other line is a problem with that hub's list of exposed methods, reported by
-     hub_kernel; fix it in the hub.
+   - Any other line is a problem the hub reports with its own list of exposed methods;
+     fix it in the hub.
 
 ## Conventions
 
@@ -102,5 +103,7 @@ in when a Rails app needs its hubs callable over HTTP.
 - An edit to the initializer takes effect only after the server restarts.
 - Keep `HubKernel::Api.check!` in the initializer; without it a hub that cannot be served
   is found only when a client calls it.
+- Setting the permission check and account scope is out of scope here; it belongs to
+  hub_kernel-interface.
 - Calling the API, its responses and its error statuses are out of scope here; they
   belong to the develop local.

data/the_local/interface.yml

@@ -1,4 +1,4 @@
-scope: hub JSON API — serving a hub_kernel hub's exposed methods as a JSON API in a host Rails app, each call behind the host's own sign-in and hub_kernel's permission check and account scope
+scope: hub JSON API — serving a hub_kernel hub's exposed methods as a JSON API in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope
 
 install:
   - gem "hub_kernel-api"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel-api
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - tylercschneider
@@ -24,19 +24,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 8.1.3
 - !ruby/object:Gem::Dependency
-  name: hub_kernel
+  name: hub_kernel-interface
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.6'
 description: 'hub_kernel-api gives any hub built on hub_kernel a JSON API: the host
   lists the hubs it serves, and every call goes through the host''s sign-in, permission
   check and account scope.'