hub_kernel-interface 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 38b1b23f80d6d9309426a790f9f7e44d0ab7d3da6c092e5845a4a6ba7bbe9b36
+  data.tar.gz: 4e82d38b3c66e95e5ca4388d1ba45ef25e0b36984ed52bac9dc86c1cfa9fa45c
+SHA512:
+  metadata.gz: ccdc332bfa7357d30249401bbef0e7fca543840bb3a580410a001c310aabbdbf7ddeea058ccee121da6e4915e1084eff5c82fabc62e3a7ffe88945c45fbd72d2
+  data.tar.gz: ab16e65c6a53358f99766428a2ff35ac46500a1cd0c0d4cbcf96177da11e89978793dc28d36b179b193b2dc37808140b8d2ea8b9d3faa156926971119dd8c202

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright tylercschneider
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,55 @@
+# hub_kernel-interface
+
+The exposed-method contract every hub_kernel interface gem builds on: what a hub exposes, who
+may call it, and calling it in an account's scope. An interface gem, such as a JSON API or an
+MCP server, depends on this gem alone rather than on all of hub_kernel.
+
+## Usage
+
+A hub lists the methods outside callers may reach by name, the values each takes, and whether
+it writes:
+
+```ruby
+module Supplies
+  extend HubKernel::Exposes
+
+  exposes :price_of, takes: %i[item], writes: false
+
+  def self.price_of(item:) = "#{item} costs 3"
+end
+```
+
+The host sets the permission check, asked with the person, `hub:method` and the account, and
+the account scope, wrapped around every call:
+
+```ruby
+HubKernel::Authz.check = ->(person, action, account) { true }
+HubKernel::Context.scope = ->(account, &call) { call.call }
+```
+
+An interface gem lists the methods a person may call on an account, and calls one by name:
+
+```ruby
+Supplies.exposures_for(person: person, account: account)
+Supplies.call_exposed("price_of", values: { item: "soap" }, person: person, account: account)
+```
+
+A call is refused with `HubKernel::UnexposedMethodError` for a name the hub does not expose,
+`HubKernel::NotAllowed` when the permission check refuses, and `HubKernel::MissingArgumentError`
+for a missing person, account or required value. A hub refuses with `HubKernel::Refused` and a
+reason a person can read. A call made while the permission check or the account scope is unset
+raises `HubKernel::UnwiredPortError`.
+
+`Supplies.exposure_problems` names each exposed method the hub has no method for, or lists
+with values it does not take. `HubKernel::Interface::ExposingHubs.list` holds every hub that
+declares an exposed method.
+
+## Installation
+
+```ruby
+gem "hub_kernel-interface"
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << "test"
+  task.pattern = "test/**/*_test.rb"
+end
+
+task default: :test

data/lib/hub_kernel/authz.rb

@@ -0,0 +1,5 @@
+module HubKernel
+  module Authz
+    singleton_class.attr_accessor :check
+  end
+end

data/lib/hub_kernel/context.rb

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

data/lib/hub_kernel/exposes.rb

@@ -0,0 +1,95 @@
+require "active_support/core_ext/string/inflections"
+require "hub_kernel/authz"
+require "hub_kernel/context"
+require "hub_kernel/interface/exposing_hubs"
+
+module HubKernel
+  class MissingArgumentError < ArgumentError; end
+  class UnwiredPortError < StandardError; end
+  class NonBooleanAnswerError < StandardError; end
+  class UnexposedMethodError < StandardError; end
+  class NotAllowed < StandardError; end
+  class Refused < StandardError; end
+
+  module Exposes
+    Exposed = Data.define(:name, :takes, :writes)
+
+    def exposes(name, takes:, writes:)
+      Interface::ExposingHubs.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

data/lib/hub_kernel/interface/exposing_hubs.rb

@@ -0,0 +1,12 @@
+module HubKernel
+  module Interface
+    module ExposingHubs
+      def self.add(hub)
+        list.reject! { |listed| listed.name == hub.name }
+        list << hub
+      end
+
+      def self.list = @list ||= []
+    end
+  end
+end

data/lib/hub_kernel/interface/version.rb

@@ -0,0 +1,5 @@
+module HubKernel
+  module Interface
+    VERSION = "0.1.0"
+  end
+end

data/lib/hub_kernel/interface.rb

@@ -0,0 +1,2 @@
+require "hub_kernel/interface/version"
+require "hub_kernel/exposes"

data/lib/hub_kernel-interface.rb

@@ -0,0 +1 @@
+require "hub_kernel/interface"

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: hub_kernel-interface
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- tylercschneider
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+description: hub_kernel-interface holds what a hub exposes, who may call it, and calling
+  it in an account's scope, so an interface gem can serve hubs without depending on
+  the rest of hub_kernel.
+email:
+- tylercschneider@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/hub_kernel-interface.rb
+- lib/hub_kernel/authz.rb
+- lib/hub_kernel/context.rb
+- lib/hub_kernel/exposes.rb
+- lib/hub_kernel/interface.rb
+- lib/hub_kernel/interface/exposing_hubs.rb
+- lib/hub_kernel/interface/version.rb
+homepage: https://github.com/DYB-Development/hub_kernel-interface
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/DYB-Development/hub_kernel-interface
+  source_code_uri: https://github.com/DYB-Development/hub_kernel-interface
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: The exposed-method contract every hub_kernel interface gem builds on.
+test_files: []