hub_kernel-api 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 005a2ef443ca851aa60b1e07bbf00d20f36ad682a7dcba572fcb2c5847181831
-  data.tar.gz: 3da76e3b5993936cc999d4641e2d4b70476a8fb7d86451294a7a5f583b85fb0c
+  metadata.gz: 16098ba0ceb84acb8536551867732dae646869b478d18299bb85a6839d1db8e1
+  data.tar.gz: 5b5b3d49bd804284796e8c7702b861b704c6e6ac77dba9a8e90b73f216845d52
 SHA512:
-  metadata.gz: 36883d22bb606c36eca8c7e80620d1a8c07105254f41152a87e28c4317f91ff23ec58f5a6aa17971d106577695f25f2e8c5e3aa8b329108303a0ca8f341326fb
-  data.tar.gz: 78348ad9a3c18cffff53beadc24f99a15a5d0b4524a592da883e807966648bef9f550945bd059cacc60e03d60084bed3c0d8a8ead26c7d702baaca0c43eabaeb
+  metadata.gz: 816027b58264d0c192482819bd043cf28f14c3ec65c91043953c7fba75abdf21725c09db3809f65f506cdab7e89b04a556d7a225cce99da925e1c4b4726fbffc
+  data.tar.gz: 2befb90df535ea4e2df15e8d229b058d46339bf730937dabb3e4511bc890abc0a1d2a1f945b6b38b15258453d7ea9c8ef57212685ff0a7f7e8e32038de40bfbb

data/Rakefile

@@ -4,3 +4,5 @@ APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
 load "rails/tasks/engine.rake"
 
 require "bundler/gem_tasks"
+
+require "the_local/rake"

data/lib/hub_kernel/api/version.rb

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

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

@@ -0,0 +1,111 @@
+---
+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
+---
+
+This local writes client code against the three endpoints below and follows the steps in
+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.
+
+## Interface
+
+- `GET /<hub>` — lists the methods the signed-in caller may call on the hub at that
+  address, for the caller's account, each as `{ "name", "takes", "verb" }`.
+- `GET /<hub>/<method>` — calls an exposed read with the values sent in the query string
+  and answers `{ "answer": <return value> }`.
+- `POST /<hub>/<method>` — calls an exposed write with the values sent in the request body
+  or query string and answers `{ "answer": <return value> }`.
+
+Every path is relative to the path the host mounted the engine at, such as
+`/api/v1/hubs`.
+
+## 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.
+
+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
+   `{ "money" => Billing::Ledger }`, in which case it answers only at `money`. Read the
+   host's served hubs list in its initializer to find it.
+
+3. Authenticate the request the way the host's sign-in requires, such as a session
+   cookie or a bearer token. Ask the developer which one the client uses. A request the
+   host's sign-in refuses is answered by the host, with the host's own status, and
+   reaches no hub.
+
+4. List what the caller may call:
+
+   ```
+   GET /api/v1/hubs/supplies
+   ```
+
+   ```json
+   [{ "name": "price_of", "takes": ["item"], "verb": "GET" },
+    { "name": "reorder", "takes": ["item", "quantity"], "verb": "POST" }]
+   ```
+
+   The list holds only the methods this caller is permitted on this account. Use `verb`
+   to choose GET or POST, and `takes` for the value names the method accepts.
+
+5. Call a read with GET, sending its values as query parameters:
+
+   ```
+   GET /api/v1/hubs/supplies/price_of?item=42
+   ```
+
+   Query values arrive as strings.
+
+6. Call a write with POST, sending its values as a JSON body with
+   `Content-Type: application/json`, keyed directly by value name with no wrapping key:
+
+   ```
+   POST /api/v1/hubs/supplies/reorder
+   Content-Type: application/json
+
+   { "item": 42, "quantity": 3 }
+   ```
+
+   Query parameters on a POST are sent to the method as well. Do not send a value whose
+   name is not in `takes`.
+
+7. Read the response by status:
+
+   | Case | Status | Body |
+   | --- | --- | --- |
+   | The method answers | 200 | `{"answer": <return value>}` |
+   | The hub is not served, the method is not exposed, the verb is wrong, or the permission check refuses the caller | 404 | `{"error": "Not found"}` |
+   | The hub refuses the call, or a required value is missing | 422 | `{"error": "<reason>"}` |
+   | A permitted call sends a value the method does not take | 422 | `{"error": "<method> does not take <values>"}` |
+   | A record the call names does not exist | 404 | `{"error": "No <record> has the id <id>"}` |
+
+   Show the `error` text of a 422 to the user, since it is the hub's reason. Treat
+   `Not found` as a method that does not exist for this caller.
+
+8. For a request test in the host, sign in as a person with and without the permission,
+   and assert the 200 answer for one and the `Not found` 404 for the other.
+
+## Conventions
+
+- Never send GET to a write or POST to a read; the wrong verb is answered as not found,
+  never as a method error.
+- A forbidden method and a missing one both answer `Not found`, so a client cannot tell
+  them apart, and must not try.
+- The `answer` is the method's return value as JSON; nothing else is added to it.
+- 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.
+- 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

@@ -0,0 +1,63 @@
+---
+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
+---
+
+This local explains hub_kernel-api and makes no changes.
+
+## What hub_kernel-api is
+
+hub_kernel-api is a Rails engine that serves the exposed methods of hub_kernel hubs
+as a JSON API inside a host Rails app. The host lists which hubs it serves, and the
+gem answers HTTP calls to their exposed methods and to a listing of them. It adds no
+business logic of its own: every answer is the return value of a method the hub
+already exposes.
+
+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.
+
+## Interface
+
+This local declares no commands. The surface is split between the other two locals:
+
+- **hub_kernel-api-install** owns adding the gem to a host, the configuration that
+  names the base controller, the person and account methods and the served hubs, the
+  startup check that rejects a hub that cannot be served, and mounting the engine.
+- **hub_kernel-api-develop** owns the HTTP endpoints a client calls: the listing at a
+  hub's address and the call to one exposed method, with their verbs, request values,
+  responses and error statuses.
+
+## How to use it
+
+- To put the API into a Rails app, or to serve another hub from one that has it, use
+  the install local.
+- To write a client against the API, or to work out why a call answered as it did,
+  use the develop local.
+
+## Conventions
+
+- **Hub** — a hub_kernel module whose methods are declared as exposed. 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
+  name underscored, so `Supplies` answers at `supplies`. The host may give a hub a
+  different address, and the permission check still asks about the hub by its own
+  name, such as `ledger:record_spend`.
+- **Read and write** — each exposed method is one or the other. A read answers GET
+  and a write answers POST, and the wrong verb is answered as not found.
+- **Takes** — the values an exposed method is listed with. A permitted call that
+  sends a value outside that list is refused.
+- **Person and account** — who is calling and which account the call is made for,
+  both supplied by the host's base controller after its own sign-in. Every call and
+  every listing is scoped to them.
+- **Answer** — a successful call returns the method's return value under the
+  `answer` key.
+- **Not found and refused** — a call the permission check denies is answered as not
+  found, so a caller cannot tell a forbidden method from a missing one. A call the hub
+  itself refuses, or one missing a required value, is answered as unprocessable with
+  the reason.

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

@@ -0,0 +1,106 @@
+---
+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
+---
+
+This local follows the steps below exactly and invents none. Where a step names a
+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
+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.
+- `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
+  controller that returns the person a call is made for; no default.
+- `HubKernel::Api.account_method=` — the name, as a Symbol, of the method on the base
+  controller that returns the account a call is made for; no default.
+- `HubKernel::Api.hubs=` — the Array of hubs the API serves, each a hub module or a
+  one-pair Hash of address to hub module; defaults to empty.
+- `HubKernel::Api.check!` — checks the served hubs and raises if any cannot be served.
+- `HubKernel::Api::UnservableHubError` — the error `check!` raises, its message naming
+  every problem on its own line.
+- `mount HubKernel::Api::Engine` — the routes line that puts the API at a path in the host.
+
+## How to use it
+
+1. Add the gem to the host's `Gemfile` and run `bundle install`:
+
+   ```ruby
+   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.
+
+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
+     unsigned caller;
+   - define the method that returns the calling person;
+   - define the method that returns the account the call is made for.
+
+   The methods may be private. Offer two options: an existing API base controller that
+   already does all three, or a new one under `app/controllers/` written for this API.
+   Do not leave the default `ActionController::API`: it has no sign-in and no person or
+   account method, so every call would fail.
+
+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.
+
+5. Create `config/initializers/hub_kernel_api.rb` with the answers from steps 3 and 4:
+
+   ```ruby
+   HubKernel::Api.base_controller = "Api::HubBaseController"
+   HubKernel::Api.person_method = :current_person
+   HubKernel::Api.account_method = :current_account
+
+   Rails.application.config.to_prepare do
+     HubKernel::Api.hubs = [ Supplies, { "money" => Billing::Ledger } ]
+     HubKernel::Api.check!
+   end
+   ```
+
+   - `base_controller`, `person_method` and `account_method` go at the top of the file,
+     outside `to_prepare`. The base controller name is read once, when the API's
+     controllers load, so it must be set before then.
+   - `hubs` and `check!` go inside `to_prepare`, so the hub constants resolve after each
+     code reload and the check runs again after each one.
+
+6. Ask the developer the path to mount the API at, then add the mount to
+   `config/routes.rb`:
+
+   ```ruby
+   mount HubKernel::Api::Engine => "/api/v1/hubs"
+   ```
+
+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.
+   - `<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.
+
+## Conventions
+
+- Run `bin/rails routes` after mounting and confirm the engine appears at the chosen path.
+- To serve another hub later, add it to the `hubs` list inside `to_prepare` and boot
+  again so `check!` runs.
+- 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.
+- 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

@@ -0,0 +1,25 @@
+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
+
+install:
+  - gem "hub_kernel-api"
+  - HubKernel::Api.base_controller=
+  - HubKernel::Api.person_method=
+  - HubKernel::Api.account_method=
+  - HubKernel::Api.hubs=
+  - HubKernel::Api.check!
+  - HubKernel::Api::UnservableHubError
+  - mount HubKernel::Api::Engine
+
+develop:
+  - GET /<hub>
+  - GET /<hub>/<method>
+  - POST /<hub>/<method>
+
+sources:
+  - lib/hub_kernel/api.rb
+  - lib/hub_kernel/api/engine.rb
+  - config/routes.rb
+  - app/controllers/hub_kernel/api/hub_controller.rb
+  - app/controllers/hub_kernel/api/hubs_controller.rb
+  - app/controllers/hub_kernel/api/hub_calls_controller.rb
+  - README.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel-api
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - tylercschneider
@@ -57,6 +57,10 @@ files:
 - lib/hub_kernel/api.rb
 - lib/hub_kernel/api/engine.rb
 - lib/hub_kernel/api/version.rb
+- the_local/agents/hub_kernel-api-develop.md
+- the_local/agents/hub_kernel-api-info.md
+- the_local/agents/hub_kernel-api-install.md
+- the_local/interface.yml
 homepage: https://github.com/DYB-Development/hub_kernel-api
 licenses:
 - MIT