mos-eisley-lambda 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e38c9c1ecdcab343fc118677a1f7b515d4fe4ce19a0b4a056b50f515f81f87b
-  data.tar.gz: a0b90f7bfb4c67bf383ce059fab48a7ce93d0588bd0766603dc879ea14783789
+  metadata.gz: 1c7bb756dd5b280ff9fb49dc6d7a52776d1e86eea6d0295585317d8bcf36c079
+  data.tar.gz: 3747893c11d3255af90bc925700020ce8b4be4b77c2fd29c9de009c3e436bb8e
 SHA512:
-  metadata.gz: 31a6c405c9b10616063c4c7d99579d16bbfbd816ba1476640662a9123aa631d8d51886ee39a1f1007ff7fa1b2b7c46ecf10cbf24dd7f6b45629bbc102c47f43f
-  data.tar.gz: 3dca76f821c4d4be95544eccdc599be61eef6715cdf0f7083649b3ac8ac8cc934d138c7757a31d2d3461491070d6327f8444abc143028f8d438b14a3b3540606
+  metadata.gz: 12d43754b4fafe23f9b83997b014a3884fecda7d269f65e10ef33799bcf7f9dce20748196252757b2cffe2cb3b3e6a9f82ced3cab5aa32b6d90ed2c6a2bcb2ca
+  data.tar.gz: 88801d7784949fdb5cedb9ff44cfcac774447ade46c844f9c23ff59b83a42e8615d1c989928520b680a9d4022cec81037fc958fa8e426c3caeca52360c4dbae0

data/README.md

@@ -22,6 +22,7 @@ Configure Lambda environment variable.
 - `SLACK_CREDENTIALS_SSMPS_PATH`: hierarchy path to System Managers Parameter Store; e.g., `/slack/credentials/` would reference two parameters:
   - `/slack/credetials/signing_secret`
   - `/slack/credetials/bot_access_token`
+- `MOSEISLEY_HANDLERS_DIR`: _optional_, if other than `./handlers` 
 - `MOSEISLEY_LOG_LEVEL`: _optional_, could be `DEBUG`, `INFO`, `WARN`, or `ERROR` 
 - `SLACK_LOG_CHANNEL_ID`: _optional_, if you want to use `ME::SlackWeb.post_log()`
 
@@ -32,10 +33,6 @@ require 'mos-eisley-lambda'
 # Or, you can just copy the `lib` directory to your Lambda and...
 # require_relative './lib/mos-eisley-lambda'
 
-MosEisley::Handler.import
-# Or, if you store your handlers in a non-default location, dictate by...
-# MosEisley::Handler.import_from_path('./my-handlers')
-
 def lambda_handler(event:, context:)
   MosEisley::lambda_event(event, context)
 end
@@ -52,21 +49,26 @@ Create a Slack app and configure the following.
 
 ### Handlers
 
-Create your own Mos Eisley handlers as blocks and register them. By default, store these Ruby files in the `handlers` directory.
+Create your own Mos Eisley handlers as blocks and register them. By default, store these Ruby files in the `handlers` directory. Add handlers by passing a block to `MosEisley::Handler.add()` for the types below.
+
+```ruby
+:action
+:command_response
+:command
+:event
+:menu
+:nonslack
+```
 
-`ME::Handler.command_acks` holds `[Hash<String, Hash>]` which are Slack command keyword and response pair. The response is sent as-is back to Slack as an [immediate response](https://api.slack.com/interactivity/slash-commands#responding_immediate_response).
+`:command_response` types are Slack command keyword and response pair. The response is sent as-is back to Slack as an [immediate response](https://api.slack.com/interactivity/slash-commands#responding_immediate_response). `ME` is an alias to `MosEisley`.
 
 ```ruby
-ME::Handler.command_acks.merge!({
-  '/command' => {
-    response_type: 'in_channel',
-    text: '_Working on it…_',
-  },
-  '/secret' => {
-    response_type: 'ephemeral',
-    text: '_Just for you…_',
-  },
-})
+ME::Handler.add(:command_response, '/sample') do |event, myself|
+  {
+    response_type: "in_channel",
+    text: "_Working on `#{event[:command]}`..._",
+  }
+end
 ```
 
 Add handlers to process the Slack event.
@@ -85,25 +87,48 @@ ME::Handler.add(:command, 'A Slack command') do |event, myself|
 end
 ```
 
+If your function receives non-Slack events, you can add handlers for that as well.
+
+```ruby
+ME::Handler.add(:nonslack, 'A CloudWatch event') do |event, myself|
+  next unless event['source'] == 'aws.events'
+  myself.stop
+  channel = 'C123SLCK'
+  txt = 'Shceduled event was received.'
+  ME::SlackWeb.chat_postmessage(channel: channel, text: txt)
+end
+```
+
 ### Helpers
 
-- `ME::S3PO` – collection of helpers to analyze/create Slack messages.
-- `ME::SlackWeb` – methods for sending payloads to Slack Web API calls.
+- `MosEisley::S3PO` – collection of helpers to analyze/create Slack messages.
+- `MosEisley::SlackWeb` – methods for sending payloads to Slack Web API calls.
 
 ## Event Lifecycle
 
 ### Inbound
 
-1. Slack event is sent to Mos Eisley Lambda function via API Gateway
-1. Slack event is verified and produces a parsed object
-1. If it's a slash command, MosEisley::Handler.command_acks is referenced and immediate response is sent
-1. The original Slack event JSON is sent to the function in a recursive fashion (this is to return the inital response ASAP)
-
-### Event Processing
-
-1. Lambda function is invoked by itself with the original Slack event
-1. Handlers are called and processed according to original endpoint the event was sent to; actions, commands, events, menus
-1. Send a Slack message as necessary and the Slack event cycle is complete
+To an incoming Slack event, Mos Eisley will quickly respond with a blank HTTP 200. This is to keep [Slack's 3-second rule](https://api.slack.com/apis/connections/events-api#the-events-api__responding-to-events). To do this, handlers are not called yet, but the Slack event is passed on to a recursive asynchronous invoke and then the handlers are called.
+
+The exception is when the incoming Slack event is for a slash command. You can define `:command_response` handlers for the purpose of generating a simple response message, but nothing more.
+
+```mermaid
+sequenceDiagram
+  participant S as Slack
+  participant L as Lambda MosEisley
+  S->>+L: Slack event via API Gateway
+  alt Slash command
+    L-->>S: Response message
+    Note left of L: If a response handler is defined
+  else All other events
+    L-->>-S: HTTP 200 (blank)
+  end
+  L->>+L: Slack event
+  Note right of L: Handlers are called
+  opt
+  L-->>-S: E.g., chat.postMessage
+  end
+```
 
 <!-- ### Outbound, Messaging Only
 

data/handlers/sample.rb

@@ -0,0 +1,55 @@
+##
+## Sample handlers for Mos Eisley
+##
+ME::Handler.add(:event, 'DEBUG') do |event, myself|
+  l = ME.logger
+  l.debug("[Slack-Event]\n#{event}")
+end
+
+ME::Handler.add(:event, 'Request - diagnostics') do |event, myself|
+  se = event[:event]
+  next unless se[:type] == 'app_mention' && /\bdiag/i =~ se[:text]
+  myself.stop
+  l = ME.logger
+  bk = ME::S3PO::BlockKit
+  fs = []
+  ME.config.info[:handlers].each{ |k, v| fs << "*#{k}*\n#{v}" }
+  blks = [
+    bk.sec_text('Handler Count'),
+    bk.sec_fields(fs),
+  ]
+  fs = []
+  ME.config.info[:versions].each{ |k, v| fs << "*#{k}*\n#{v}" }
+  blks << bk.sec_text('Software Versions')
+  blks << bk.sec_fields(fs)
+  ME::SlackWeb.chat_postmessage(channel: se[:channel], text: "Diagnostics", blocks: blks)
+end
+
+ME::Handler.add(:nonslack, 'DEBUG') do |event, myself|
+  l = ME.logger
+  l.debug("[Non-Slack]\n#{event}")
+end
+
+ME::Handler.add(:command_response, '/sample') do |event, myself|
+  {
+    response_type: "in_channel",
+    text: "_Working on `#{event[:command]}`..._",
+  }
+end
+
+ME::Handler.add(:command, 'DEBUG') do |event, myself|
+  l = ME.logger
+  l.debug("[Slack-Command]\n#{event}")
+end
+
+ME::Handler.add(:command, 'Request - /sample') do |event, myself|
+  next unless event[:command] == '/sample'
+  myself.stop
+  bk = ME::S3PO::BlockKit
+  t = "`S A M P L E` I did it!"
+  blks = [
+    bk.sec_text(t),
+    bk.con_text('By: Mos Eisley sampler'),
+  ]
+  ME::SlackWeb.chat_postmessage(channel: event[:command], text: t, blocks: blks)
+end

data/lib/handler.rb

@@ -31,6 +31,7 @@ module MosEisley
         command: [],
         event: [],
         menu: [],
+        nonslack: [],
       }
       h = MosEisley::Handler.new(type, name, &block)
       if type == :command_response
@@ -38,13 +39,7 @@ module MosEisley
       else
         @handlers[type] << h
       end
-      MosEisley.logger.debug("Added #{type} handler: #{h}")
-    end
-
-    # Example: {'/command' => {response_type: 'ephemeral', text: nil}}
-    # @return [Hash<String, Hash>] commands to acknowledge
-    def self.command_acks
-      @command_acks ||= {}
+      MosEisley.logger.debug("Added handler: #{h}")
     end
 
     # @return [Hash<Symbol, Array>] containing all the handlers
@@ -106,7 +101,7 @@ module MosEisley
     end
 
     def to_s
-      "#<#{self.class}:#{self.object_id.to_s(16)}(#{name})>"
+      "#<#{self.class}:#{self.object_id.to_s(16)}(#{type}:#{name})>"
     end
   end
 end

data/lib/mos-eisley-lambda.rb

@@ -2,6 +2,7 @@ require_relative './logger'
 require_relative './slack'
 require_relative './s3po/s3po'
 require_relative './handler'
+require_relative './version'
 require 'aws-sdk-lambda'
 require 'aws-sdk-ssm'
 require 'base64'
@@ -10,13 +11,24 @@ require 'json'
 ME = MosEisley
 
 module MosEisley
-  def self.config
-    @config ||= {}
+  def self.config(context = nil, data = nil)
+    if data
+      unless @config
+        @config = Config.new(context, data)
+        MosEisley.logger.info('Config loaded')
+      else
+        MosEisley.logger.warn('Ignored, already configured')
+      end
+    end
+    @config
   end
 
   def self.lambda_event(event, context)
-    raise 'Pre-flight check failed!' unless preflightcheck
+    raise 'Pre-flight check failed!' unless preflightcheck(context)
     case
+    when event['initializeOnly']
+      MosEisley.logger.info('Dry run, initializing only')
+      return
     when event['routeKey']
       # Inbound Slack event (via API GW)
       MosEisley.logger.info('API GW event')
@@ -26,22 +38,28 @@ module MosEisley
       MosEisley.logger.info('Invoke event')
       MosEisley.logger.debug("#{event}")
       return invoke_event(event)
+    when event.dig('Records',0,'eventSource').start_with?('MosEisley:Slack_message:')
+      # Outbound Slack messaging request (via invoke)
+      MosEisley.logger.info('Messaging event')
+      MosEisley.logger.debug("#{event}")
+      return # TODO implement
     else
-      # Unknown event
-      MosEisley.logger.info('Unknown event')
-      return unknown_event(event)
+      # Non-Slack event
+      MosEisley.logger.info('Non-Slack event')
+      return nonslack_event(event)
     end
   end
 
-  def self.preflightcheck
-    if config[:timestamp]
-      MosEisley.logger.debug("Confing already loaded at: #{config[:timestamp]}")
+  def self.preflightcheck(context)
+    if config
+      MosEisley.logger.debug("Confing already loaded at: #{config.timestamp}")
       return true
     end
     env_required = [
       'SLACK_CREDENTIALS_SSMPS_PATH',
     ]
     env_optional = [
+      'MOSEISLEY_HANDLERS_DIR',
       'MOSEISLEY_LOG_LEVEL',
       'SLACK_LOG_CHANNEL_ID',
     ]
@@ -53,6 +71,11 @@ module MosEisley
     if String === l && ['DEBUG', 'INFO', 'WARN', 'ERROR'].include?(l.upcase)
       MosEisley.logger.level = eval("Logger::#{l.upcase}")
     end
+    if dir = ENV['MOSEISLEY_HANDLERS_DIR']
+      MosEisley::Handler.import_from_path(dir)
+    else
+      MosEisley::Handler.import
+    end
     env_required.each do |v|
       if ENV[v].nil?
         MosEisley.logger.error("Missing environment variable: #{v}")
@@ -65,20 +88,20 @@ module MosEisley
           path: ENV['SLACK_CREDENTIALS_SSMPS_PATH'],
           with_decryption: true,
         }
+        c = {}
         ssm.get_parameters_by_path(rparams).parameters.each do |prm|
           k = prm[:name].split('/').last.to_sym
-          config[k] = prm[:value]
+          c[k] = prm[:value]
           config_required.delete(k)
         end
+        unless config_required.empty?
+          t = "Missing config values: #{config_required.join(', ')}"
+          MosEisley.logger.error(t)
+          return false
+        end
+        config(context, c)
       end
     end
-    unless config_required.empty?
-      t = "Missing config values: #{config_required.join(', ')}"
-      MosEisley.logger.error(t)
-      return false
-    end
-    config[:timestamp] = Time.now
-    MosEisley.logger.info('Config loaded')
     return true
   end
 
@@ -163,7 +186,42 @@ module MosEisley
     end
   end
 
-  def self.unknown_event(event)
-    # TODO hand off to a handler
+  def self.nonslack_event(event)
+    MosEisley::Handler.run(:nonslack, event)
+  end
+
+  class Config
+    attr_reader :context, :info, :timestamp
+    attr_reader :bot_access_token, :signing_secret
+
+    def initialize(context, data)
+      data.each do |k, v|
+        instance_variable_set("@#{k}", v)
+      end
+      @context = context
+      @info = {
+        handlers: {
+          action: MosEisley.handlers[:action].length,
+          command_response: MosEisley.handlers[:command_response].length,
+          command: MosEisley.handlers[:command].length,
+          event: MosEisley.handlers[:event].length,
+        },
+        versions: {
+          mos_eisley: MosEisley::VERSION,
+          neko_http: Neko::HTTP::VERSION,
+          s3po: MosEisley::S3PO::VERSION,
+          s3po_blockkit: MosEisley::S3PO::BlockKit::VERSION,
+        },
+      }
+      @timestamp = Time.now
+    end
+
+    def arn
+      context.invoked_function_arn
+    end
+
+    def remaining_time
+      context.get_remaining_time_in_millis
+    end
   end
 end

data/lib/neko-http.rb

@@ -1,7 +1,6 @@
+#
 # NekoHTTP - Pure Ruby HTTP client using net/http
-# 
-# v.20200629
-
+#
 require 'json'
 require 'logger'
 require 'net/http'
@@ -17,6 +16,8 @@ module Neko
   end
 
   class HTTP
+    VERSION = '20220224'.freeze
+
     METHOD_HTTP_CLASS = {
       get: Net::HTTP::Get,
       put: Net::HTTP::Put,
@@ -25,6 +26,11 @@ module Neko
       delete: Net::HTTP::Delete
     }
 
+    # Simple GET request
+    # @param url [String] full URL string
+    # @param params [Array, Hash] it will be converted to URL encoded query
+    # @param hdrs [Hash] HTTP headers
+    # @return [Hash] contains: :code, :headers, :body, :message
     def self.get(url, params, hdrs = nil)
       h = HTTP.new(url, hdrs)
       data = h.get(params: params)
@@ -32,6 +38,11 @@ module Neko
       return data
     end
 
+    # Send POST request with form data URL encoded body
+    # @param url [String] full URL string
+    # @param params [Array, Hash] it will be converted to URL encoded body
+    # @param hdrs [Hash] HTTP headers
+    # @return (see #self.get)
     def self.post_form(url, params, hdrs = nil)
       h = HTTP.new(url, hdrs)
       data = h.post(params: params)
@@ -43,7 +54,8 @@ module Neko
     # It will set the Content-Type to application/json.
     # @param url [String] full URL string
     # @param obj [Array, Hash, String] Array/Hash will be converted to JSON
-    # @param hdrs [Array, Hash, String] Array/Hash will be converted to JSON
+    # @param hdrs [Hash] HTTP headers
+    # @return (see #self.get)
     def self.post_json(url, obj, hdrs = {})
       hdrs['Content-Type'] = 'application/json'
       h = HTTP.new(url, hdrs)
@@ -63,6 +75,9 @@ module Neko
     attr_reader :init_uri, :http
     attr_accessor :logger, :headers
 
+    # Instance constructor for tailored use
+    # @param url [String] full URL string
+    # @param hdrs [Hash] HTTP headers
     def initialize(url, hdrs = nil)
       @logger = Neko.logger
       @init_uri = URI(url)

data/lib/s3po/blockkit.rb

@@ -1,11 +1,12 @@
+#
 # S3PO - Slack protocol droid in Mos Eisley
 #     ::BlockKit - Block Kit tools
 #
-# v.20220201
-
 module MosEisley
   module S3PO
     module BlockKit
+      VERSION = '20220224'.freeze
+
       # @param txt [String]
       # @param type [Symbol] :plain | :emoji | :mrkdwn
       # @return [Hash] Block Kit section object
@@ -37,6 +38,16 @@ module MosEisley
         }
       end
 
+      # @param fields [Array<String>]
+      # @param type [Symbol] :plain | :emoji | :mrkdwn
+      # @return [Hash] Block Kit section object
+      def self.sec_fields(fields, type = :mrkdwn)
+        {
+          type: :section,
+          fields: fields.map{ |txt| text(txt, type) },
+        }
+      end
+
       # @param txt [String]
       # @param type [Symbol] :plain | :emoji | :mrkdwn
       # @return [Hash] Block Kit text object

data/lib/s3po/s3po.rb

@@ -1,13 +1,14 @@
+#
 # S3PO - Slack protocol droid in Mos Eisley
 #
-# v.20210626
-
 require 'json'
 require 'time'
 require_relative './blockkit'
 
 module MosEisley
   module S3PO
+    VERSION = '20210626'.freeze
+
     def self.parse_json(json)
       return JSON.parse(json, {symbolize_names: true})
     rescue => e

data/lib/slack.rb

@@ -15,7 +15,7 @@ module MosEisley
       end
       b = e['isBase64Encoded'] ? Base64.decode64(e['body']) : e['body']
       s = "v0:#{t}:#{b}"
-      k = MosEisley.config[:signing_secret]
+      k = MosEisley.config.signing_secret
       sig = "v0=#{OpenSSL::HMAC.hexdigest('sha256', k, s)}"
       if e.dig('headers', 'x-slack-signature') != sig
         return {valid?: false, msg: 'Invalid signature.'}
@@ -155,7 +155,7 @@ module MosEisley
     def self.get_from_slack(m, params)
       l = MosEisley.logger
       url ||= BASE_URL + m
-      head = {authorization: "Bearer #{MosEisley.config[:bot_access_token]}"}
+      head = {authorization: "Bearer #{MosEisley.config.bot_access_token}"}
       r = Neko::HTTP.get(url, params, head)
       if r[:code] != 200
         l.warn("#{m} HTTP failed: #{r[:message]}")
@@ -178,7 +178,7 @@ module MosEisley
     def self.post_to_slack(method, data, url = nil)
       l = MosEisley.logger
       url ||= BASE_URL + method
-      head = {authorization: "Bearer #{MosEisley.config[:bot_access_token]}"}
+      head = {authorization: "Bearer #{MosEisley.config.bot_access_token}"}
       r = Neko::HTTP.post_json(url, data, head)
       if r[:code] != 200
         l.warn("post_to_slack HTTP failed: #{r[:message]}")

data/lib/version.rb

@@ -0,0 +1,3 @@
+module MosEisley
+  VERSION = '0.7.0'.freeze
+end

data/mos-eisley-lambda.gemspec

@@ -1,6 +1,8 @@
+require_relative './lib/version'
+
 Gem::Specification.new do |s|
   s.name          = 'mos-eisley-lambda'
-  s.version       = '0.6.0'
+  s.version       = MosEisley::VERSION
   s.authors       = ['Ken J.']
   s.email         = ['kenjij@gmail.com']
   s.summary       = %q{Ruby based Slack bot framework, for AWS Lambda use}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mos-eisley-lambda
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Ken J.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-02-24 00:00:00.000000000 Z
+date: 2022-03-03 00:00:00.000000000 Z
 dependencies: []
 description: Ruby based Slack bot framework, for AWS Lambda; event queue based. Also
   provides Block Kit helper.
@@ -21,6 +21,7 @@ files:
 - LICENSE
 - Makefile
 - README.md
+- handlers/sample.rb
 - lib/handler.rb
 - lib/logger.rb
 - lib/mos-eisley-lambda.rb
@@ -28,6 +29,7 @@ files:
 - lib/s3po/blockkit.rb
 - lib/s3po/s3po.rb
 - lib/slack.rb
+- lib/version.rb
 - mos-eisley-lambda.gemspec
 - openapi3.yaml
 homepage: https://github.com/kenjij/mos-eisley-lambda