waylon-core 0.1.0

data/lib/waylon/skill.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Waylon
+  # Skills are what Waylon can do based on inputs from Senses
+  class Skill
+    include BaseComponent
+
+    attr_reader :sense, :tokens, :request
+
+    # Config namespace for config keys
+    # @return [String] The namespace for config keys
+    def self.config_namespace
+      "skills.#{component_namespace}"
+    end
+
+    # Resque uses this to execute the Skill. Just defers to the `action` subclass method
+    # @param action [Symbol,String] The method on the Skill subclass to call
+    # @param details [Hash] Input details about the message for running a Skill action
+    def self.perform(action, details)
+      new(details["sense"], details["tokens"], details["message"], details["meta"])
+        .send(action.to_sym)
+    end
+
+    # Redis/Resque queue name
+    # @api private
+    # @return [Symbol]
+    def self.queue
+      :senses
+    end
+
+    # Adds skills to the SkillRegistry
+    # @param condition [Condition,Regexp] The condition that determines if this route applies
+    # @param action [Symbol,String] The method on the Skill subclass to call
+    # @param allowed_groups [Symbol,Array<Symbol>] The group or list of groups allowed to use this
+    # @param help [String] A description of how to use the skill
+    def self.route(condition, action, allowed_groups: :everyone, help: nil, name: nil)
+      name ||= "#{to_s.split("::").last.downcase}##{action}"
+      real_cond = case condition
+                  when Condition
+                    condition
+                  when Regexp
+                    Conditions::Regex.new(condition, action, allowed_groups, help)
+                  else
+                    log("Unknown condition for route for #{name}##{action}", :warn)
+                    nil
+                  end
+      SkillRegistry.instance.register(name, self, real_cond) if real_cond
+    end
+
+    # @param sense [Class,String] Class (or Class name) of the source Sense
+    # @param tokens [Array<String>] Tokenized message content for use in the Skill
+    # @param request [String,Integer] Reference to the request from the Sense provider (usually an ID)
+    # @param meta [Hash] Optional meta data that can be passed along from a Sense for use in Skills
+    def initialize(sense, tokens, request, meta)
+      @sense   = sense.is_a?(Class) ? sense : Module.const_get(sense)
+      @tokens  = tokens || []
+      @request = request
+      @meta    = meta
+    end
+
+    # Provides a random entry from a list of canned acknowledgements
+    # @return [String]
+    def acknowledgement
+      responses = [
+        "I'll get back to you in just a sec.",
+        "You got it!",
+        "As you wish.",
+        "Certainly!",
+        "Sure thing!",
+        "Absolutely!",
+        "No problem.",
+        "Consider it done.",
+        "Of course!",
+        "I'd be delighted!",
+        "Right away!",
+        "Gladly",
+        "All right.",
+        "I'm all over it.",
+        "I'm on it!",
+        "Let me see what I can do.",
+        "Will do!"
+      ]
+      responses.sample
+    end
+
+    # Provides a simple way to convert some text to a code block in a way the Sense understands
+    # @param text [String] The string to codify
+    # @return [String] Properly wrapped content
+    def codify(text)
+      sense.codify(text)
+    end
+
+    # The details used to call this Skill
+    # @return [Hash]
+    def details
+      {
+        sense: @sense,
+        message: @request,
+        tokens: @tokens,
+        meta: @meta
+      }
+    end
+
+    # Defers to the Sense to determine how to mention a user
+    # @param [Waylon::User] user The user to mention
+    # @return [String]
+    def mention(user)
+      sense.mention(user)
+    end
+
+    # Provides a wrapped message for responding to the received Sense
+    # @return [Waylon::Message]
+    def message
+      sense.message_class.new(request)
+    end
+
+    # Defers to the Sense to react to a message
+    # @param [String] type The type of reaction to send
+    # @return [Boolean,String]
+    def react(type)
+      return false unless sense.supports?(:reactions)
+
+      sense.react(request, type)
+    end
+
+    # Defers to the Sense to determine how to reply to a message
+    # @param [String] text The reply text
+    def reply(text)
+      sense.reply(request, text)
+    end
+  end
+end

data/lib/waylon/skill_registry.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Waylon
+  # A place to track all skills known to this instance of Waylon
+  class SkillRegistry
+    include Singleton
+
+    # A wrapper around the singleton #register method
+    # @param name [String] The name of the skill in the registry
+    # @param class_name [Class] The class to associate with the name
+    # @param condition [Condition] Criteria for whether or not the given subclass applies
+    # @return [Route] The created Route instance
+    def self.register(name, class_name, condition)
+      instance.register(name, class_name, condition)
+    end
+
+    def default_route
+      Routes::Default.new
+    end
+
+    # Gathers a Hash of help data for all routes a user is permitted to access
+    # @param user [User] The user asking for help
+    # @return [Hash]
+    def help(user)
+      data = {}
+      @routes.select { |r| r.permits?(user) }.each do |permitted|
+        data[permitted.destination.config_namespace] ||= []
+        data[permitted.destination.config_namespace] << { name: permitted.name, help: permitted.help } if permitted.help
+      end
+
+      data.reject { |_k, v| v.empty? }
+    end
+
+    # Simple pass-through for logging through the Waylon Logger
+    # @param [String] message The message to log
+    # @param [String,Symbol] level The log level for this message
+    def log(message, level = :info)
+      ::Waylon::Logger.log(message, level)
+    end
+
+    # Add the provided Skill subclass to the registry under `name`
+    # @param name [String] The name of the component in the registry
+    # @param skill_class [Class] The class to associate with the name
+    # @param condition [Condition] Criteria for whether or not the given subclass applies
+    # @return [Route] The created Route instance
+    def register(name, skill_class, condition)
+      raise Exceptions::ValidationError, "Must be a kind of Skill" unless skill_class.ancestors.include?(Skill)
+
+      @routes ||= []
+      @routes << Route.new(name: name.to_s, destination: skill_class, condition: condition)
+    end
+
+    # Given a message, find a suitable skill Route for it (sorted by priority, highest first)
+    # @param message [Waylon::Message] A Message instance
+    # @return [Hash]
+    def route(message)
+      route = nil
+      message_text = message.text.strip
+      @routes ||= []
+      @routes.sort_by(&:priority).reverse.each do |candidate_route|
+        if candidate_route.permits?(message.author) && candidate_route.matches?(message_text)
+          route = candidate_route
+        elsif candidate_route.matches?(message_text)
+          route = Routes::PermissionDenied.new
+        end
+        if route
+          log("Using route '#{route.name}' based on '#{message_text}' from '#{message.author.email}'", :debug)
+          break
+        end
+      end
+      route
+    end
+  end
+end

data/lib/waylon/skills/default.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Waylon
+  module Skills
+    # The default skill for Waylon, mostly for fallback actions like permissions issues
+    class Default < Skill
+      # This action is performed when a User tries to run something they aren't allowed to
+      def denied
+        log("Denied '#{tokens.first}' from #{message.author.email}")
+        prefix = message.private_message? ? "" : "#{mention(message.author)},"
+
+        react :lock
+
+        responses = [
+          "I can't do that. You'll need an admin adjust your permissions.",
+          "I know what you'd like to do, but you don't have permission for that.",
+          "You don't have permission to do that."
+        ]
+
+        reply("#{prefix} #{responses.sample} #{help_postfix}")
+      end
+
+      # A useful addition to message to tell the User how to get help
+      # @return [String]
+      def help_postfix
+        "Use `help` to see what you're allowed to do."
+      end
+
+      # This is run for unroutable messages (meaning no Skill has claimed them)
+      def unknown
+        log("Unroutable message '#{tokens.first}' from #{message.author.email}")
+
+        prefix = message.private_message? ? "" : "#{mention(message.author)},"
+
+        react :shrug
+
+        responses = [
+          "Sorry, I'm not sure what you mean by that.",
+          "I don't have the ability to handle that request, but PRs are welcome!",
+          "I don't know what that means.",
+          "My AI and NLP is only so good... Maybe try rephrasing that request?"
+        ]
+
+        reply("#{prefix} #{responses.sample} #{help_postfix}")
+      end
+    end
+  end
+end

data/lib/waylon/skills/fun.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Waylon
+  module Skills
+    # A place for some builtin fun
+    class Fun < Skill
+      # Say hello to Waylon
+      route(
+        /^(hello|hi)$/i,
+        :hello
+      )
+
+      # Responds to "hello" in less boring ways
+      def hello
+        responses = [
+          "Hello there!",
+          "Hi!",
+          "Hi, how's it going?",
+          "How can I be of service?"
+        ]
+
+        reply responses.sample
+      end
+    end
+  end
+end

data/lib/waylon/user.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Waylon
+  # Abstract User module
+  # @abstract
+  module User
+    # Extends the base class when included
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    include Comparable
+
+    # Class-level methods to be added to User subclasses
+    module ClassMethods
+      # This should be overridden by subclasses to provide a mechanism for looking up Users
+      def find_by_email(_email)
+        raise NotImplementedError, "find_by_email isn't implemented"
+      end
+
+      # Provides a simple mechanism for referencing User subclass's Sense
+      # @return [Class] A Sense subclass
+      def sense
+        Sense
+      end
+
+      # This should be overridden by subclasses to provide a mechanism for the bot to get its own User
+      def whoami
+        raise NotImplementedError, "whoami isn't implemented"
+      end
+    end
+
+    def initialize(id)
+      @id = id
+    end
+
+    def <=>(other)
+      id <=> other.id
+    end
+
+    # Meant to provide the User's email
+    def email
+      nil
+    end
+
+    # Meant to provide the User's handle
+    def handle
+      nil
+    end
+
+    # Meant to provide the User's id from the underlying Sense platform
+    def id
+      @id
+    end
+
+    # Meant to determine if the User's is "real" per the Sense platform
+    def valid?
+      true
+    end
+  end
+end

data/lib/waylon/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Waylon
+  module Core
+    # The Waylon::Core version
+    VERSION = [
+      0, # Major
+      1, # Minor
+      0  # Patch
+    ].join(".")
+  end
+end

data/lib/waylon/webhook.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Waylon
+  # Base class for Webhooks
+  class Webhook < Sinatra::Base
+    include BaseComponent
+
+    # Config namespace for config keys
+    # @return [String] The namespace for config keys
+    def self.config_namespace
+      "webhooks.#{component_namespace}"
+    end
+
+    # Places the incoming request body onto the Senses queue for processing by workers
+    # @param [Hash] content The verified request body
+    def enqueue(content)
+      Resque.enqueue sense_class, content
+    end
+
+    # Provides the Sense class that corresponds to this Webhook, with some sensible assumptions
+    # @return [Class] The name of the corresponding Sense class
+    def sense_class
+      last = self.class.name.split("::").last
+      Module.const_get("Senses::#{last}")
+    end
+
+    # This must be implemented on every Webhook to provide a mechanism to ensure received payloads are legit
+    # @param [String] _payload The raw, unparsed request body
+    # @param [Hash] _headers The raw, unparsed request headers as a Hash
+    # @return [Boolean]
+    def verify(_payload, _headers)
+      raise GenericException, "Not Implemented"
+    end
+
+    configure do
+      set :protection, except: :http_origin
+      set :logging, ::Waylon::Logger
+    end
+
+    before do
+      content_type "application/json"
+
+      begin
+        unless request.get? || request.options?
+          request.body.rewind
+          @parsed_body = JSON.parse(request.body.read, symbolize_names: true)
+        end
+      rescue StandardError => e
+        halt(400, { error: "Request must be JSON: #{e.message}" }.to_json)
+      end
+    end
+
+    after do
+      request.options? && headers("Access-Control-Allow-Methods" => @allowed_types || %w[OPTIONS POST])
+    end
+
+    post "/" do
+      begin
+        request.body.rewind
+        verify request.body.read, request.env
+        enqueue @parsed_body
+      rescue StandardError => e
+        halt(422, { error: "Unprocessable entity: #{e.message}" }.to_json)
+      end
+
+      { status: :ok }.to_json
+    end
+
+    options "/" do
+      halt 200
+    end
+  end
+end

data/lib/waylon.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "waylon/core"
+require "waylon/skills/default"
+require "waylon/skills/fun"

data/scripts/test.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+gem install bundler -v '~> 2.2'
+bundle install
+bundle exec rake

data/waylon-core.gemspec

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "lib/waylon/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "waylon-core"
+  spec.version       = Waylon::Core::VERSION
+  spec.authors       = ["Jonathan Gnagy"]
+  spec.email         = ["jonathan@therubyist.org"]
+
+  spec.summary       = "Core library for the Waylon bot framework"
+  spec.description   = "The core components of the Waylon bot framework for Ruby"
+  spec.homepage      = "https://github.com/jgnagy/waylon-core"
+  spec.license       = "MIT"
+  spec.required_ruby_version = "~> 3.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/jgnagy/waylon-core"
+  spec.metadata["changelog_uri"] = "https://github.com/jgnagy/waylon-core/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency "addressable", "~> 2.8"
+  spec.add_dependency "faraday", "~> 1.8"
+  spec.add_dependency "i18n", "~> 1.8"
+  spec.add_dependency "json", "~> 2.6"
+  spec.add_dependency "moneta", "~> 1.4"
+  spec.add_dependency "puma", "~> 5.5"
+  spec.add_dependency "resque", "~> 2.2"
+
+  spec.add_development_dependency "bundler", "~> 2.2"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.10"
+  spec.add_development_dependency "rubocop", "~> 1.23"
+  spec.add_development_dependency "rubocop-rake", "~> 0.6"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.6"
+  spec.add_development_dependency "simplecov", "~> 0.21"
+  spec.add_development_dependency "yard", "~> 0.9", ">= 0.9.27"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end