hub_kernel-api 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16098ba0ceb84acb8536551867732dae646869b478d18299bb85a6839d1db8e1
-  data.tar.gz: 5b5b3d49bd804284796e8c7702b861b704c6e6ac77dba9a8e90b73f216845d52
+  metadata.gz: 012cd9631dd8925bcd3d6982acc076ee8ade6a159dbca527d3618ba4ff80eec4
+  data.tar.gz: 98850fb2e56aca0a182d1f70adc2deedb440e9b54f0f188e321a2738034d8991
 SHA512:
-  metadata.gz: 816027b58264d0c192482819bd043cf28f14c3ec65c91043953c7fba75abdf21725c09db3809f65f506cdab7e89b04a556d7a225cce99da925e1c4b4726fbffc
-  data.tar.gz: 2befb90df535ea4e2df15e8d229b058d46339bf730937dabb3e4511bc890abc0a1d2a1f945b6b38b15258453d7ea9c8ef57212685ff0a7f7e8e32038de40bfbb
+  metadata.gz: b2e7fc3101f127f70f515be313c0532efd5a64bce8f568dc693fa2e7e3a962dad5703ea5a295e3020cc56b644fc283854a140ac24d7f588d891227b30934bf70
+  data.tar.gz: 67b21cabf1dd75ad74c7c97a3d908432a7c508c5fd39b13a3108a63ede102b8864fc4dde26c47f6da666dbdd3234351e764a3d1d0f6431d4275fc94f7dbb12e9

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,9 @@ 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:
+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/lib/hub_kernel/api/version.rb

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

data/lib/hub_kernel/api.rb

@@ -1,4 +1,4 @@
-require "hub_kernel"
+require "hub_kernel-interface"
 require "hub_kernel/api/version"
 require "hub_kernel/api/engine"
 

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.7.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.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.3'
 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.'