chook 1.0.1.b2 → 1.1.0

data/data/sample_handlers/RestAPIOperation.rb

@@ -23,23 +23,27 @@
 ###
 ###
 
-Chook.event_handler do |event|
-  eobject = event.event_object
-  whook = event.webhook
+# this module is just a namespace so we don't conflict with other handlers
+module APIOpHandler
 
   REPORT_ACTIONS = {
     'PUT' => 'update',
     'POST' => 'create',
     'DELETE' => 'delete'
-  }.freeze unless defined? REPORT_ACTIONS
+  }.freeze
+
+end
+
+Chook.event_handler do |event|
+  event.logger.debug "This is a handler-level debug message for event #{event.object_id}"
 
-  action = REPORT_ACTIONS[eobject.restAPIOperationType]
+  action = APIOpHandler::REPORT_ACTIONS[event.subject.restAPIOperationType]
 
   return nil unless action
 
   puts <<-ENDMSG
-The JSS WebHook named '#{whook.name}' was just triggered.
-It indicates that Casper user '#{eobject.authorizedUsername}' just used the JSS API to #{action}
-the JSS #{eobject.objectTypeName} named '#{eobject.objectName}' (id #{eobject.objectID})
+The JSS WebHook named '#{event.webhook_name}' was just triggered.
+It indicates that Casper user '#{event.subject.authorizedUsername}' just used the JSS API to #{action}
+the JSS #{event.subject.objectTypeName} named '#{event.subject.objectName}' (id #{event.subject.objectID})
 ENDMSG
 end

data/data/sample_handlers/SmartGroupComputerMembershipChange.rb

@@ -23,11 +23,8 @@
 ###
 ###
 
-HANDLER_NAME = File.basename __FILE__
-CHANGELOG = '/tmp/smart-computer-group-changes.log'.freeze
-
 Chook.event_handler do |event|
-  now = Time.now.strftime '%Y-%m-%d %H:%M:%S'
-  msg = "#{now} #{HANDLER_NAME}: Smart Computer Group '#{event.event_object.name}' changed.\n"
-  open(CHANGELOG, 'a') { |file| file.write msg }
+  event.logger.debug "Computer Smart Group Changed: #{event.subject.name}"
+  event.logger.debug "  Additions: #{event.subject.groupAddedDevicesIds.join ', '}"
+  event.logger.debug "  Removals: #{event.subject.groupRemovedDevicesIds.join ', '}"
 end

data/data/sample_jsons/SmartGroupComputerMembershipChange.json

@@ -8,6 +8,8 @@
     "name": "OddComputers",
     "smartGroup": true,
     "jssid": 95,
-    "computer": true
+    "computer": true,
+    "groupAddedDevicesIds": [1,2,3,4,5],
+    "groupRemovedDevicesIds": [6,7,8,9,10]
   }
 }

data/data/sample_jsons/SmartGroupMobileDeviceMembershipChange.json

@@ -8,6 +8,8 @@
     "name": "OddMobileDevs",
     "smartGroup": true,
     "jssid": 99,
-    "computer": false
+    "computer": false,
+    "groupAddedDevicesIds": [1,2,3,4,5],
+    "groupRemovedDevicesIds": [6,7,8,9,10]
   }
 }

data/lib/chook/configuration.rb

@@ -35,16 +35,26 @@ module Chook
     # The location of the default config file
     DEFAULT_CONF_FILE = Pathname.new '/etc/chook.conf'
 
-    # The attribute keys we maintain, and the type they should be stored as
+    SAMPLE_CONF_FILE = Pathname.new(__FILE__).parent.parent.parent + 'data/chook.conf.example'
+
+    # The attribute keys we maintain, and how they should be converted to
+    # the value used by chook internally.
+    #
+    # For descriptions of the keys, see data/chook.conf.example
+    #
     CONF_KEYS = {
-      server_port: :to_i,
-      server_engine:  :to_sym,
-      handler_dir: nil,
+      port: :to_i,
+      concurrency: Chook::Procs::STRING_TO_BOOLEAN,
+      handler_dir: Chook::Procs::STRING_TO_PATHNAME,
       use_ssl: Chook::Procs::STRING_TO_BOOLEAN,
-      ssl_private_key_path: Chook::Procs::STRING_TO_PATHNAME,
-      ssl_private_key_pw_path: nil,
       ssl_cert_path: Chook::Procs::STRING_TO_PATHNAME,
-      ssl_cert_name: nil
+      ssl_private_key_path: Chook::Procs::STRING_TO_PATHNAME,
+      log_file: Chook::Procs::STRING_TO_PATHNAME,
+      log_level: Chook::Procs::STRING_TO_LOG_LEVEL,
+      log_max_megs:  :to_i,
+      logs_to_keep: :to_i,
+      webhooks_user: nil,
+      webhooks_user_pw: nil
     }.freeze
 
     # Class Variables
@@ -193,6 +203,8 @@ module Chook
   end # class Configuration
 
   # The single instance of Configuration
-  CONFIG = Chook::Configuration.instance
+  def self.config
+    Chook::Configuration.instance
+  end
 
 end # module

data/lib/chook/event/handled_event.rb

@@ -25,7 +25,6 @@
 
 require 'chook/event/handled_event/handlers'
 
-#
 module Chook
 
   # Load sample JSON files, one per event type
@@ -62,9 +61,6 @@ module Chook
 
     #### Class Methods
 
-    # Given some raw_json from the jss, create and return the correct
-    # HandledEvent subclass
-
     # For each event type in Chook::Event::EVENTS
     # generate a class for it, set its SUBJECT_CLASS constant
     # and add it to the HandledEvents module.
@@ -99,6 +95,7 @@ module Chook
     # @return [JSSWebHooks::Event subclass] the Event subclass matching the event
     #
     def self.parse_event(raw_event_json)
+      return nil if raw_event_json.to_s.empty?
       event_json = JSON.parse(raw_event_json, symbolize_names: true)
       event_name = event_json[:webhook][:webhookEvent]
       Chook::HandledEvents.const_get(event_name).new raw_event_json
@@ -122,12 +119,15 @@ module Chook
     end # init
 
     def handle
-      handlers = Handlers.handlers[self.class.const_get(Chook::Event::EVENT_NAME_CONST)]
+      handler_key = self.class.const_get(Chook::Event::EVENT_NAME_CONST)
+      handlers = Handlers.handlers[handler_key]
+      return 'No handlers loaded' unless handlers.is_a? Array
+
       handlers.each do |handler|
         case handler
         when Pathname
           pipe_to_executable handler
-        when Proc
+        when Object
           handle_with_proc handler
         end # case
       end # @handlers.each do |handler|
@@ -135,18 +135,21 @@ module Chook
       # the handle method should return a string,
       # which is the body of the HTTP result for
       # POSTing the event
-      "Processed by #{handlers.count} handlers\n"
+      "Processed by #{handlers.count} handlers"
     end # def handle
 
-    # TODO: Add something here that cleans up old threads and forks
     def pipe_to_executable(handler)
-      _thread = Thread.new do
-        IO.popen([handler.to_s], 'w') { |h| h.puts @raw_json }
-      end
+      logger.debug "Sending JSON to stdin of '#{handler}'"
+      IO.popen([handler.to_s], 'w') { |h| h.puts @raw_json }
     end
 
     def handle_with_proc(handler)
-      _thread = Thread.new { handler.call self }
+      logger.debug "Running Handler defined in #{handler.handler_file}"
+      handler.handle self
+    end
+
+    def logger
+      @logger ||= Chook::HandledEventLogger.new self
     end
 
   end # class HandledEvent

data/lib/chook/event/handled_event/handlers.rb

@@ -1,36 +1,45 @@
-### Copyright 2017 Pixar
-
-###
-###    Licensed under the Apache License, Version 2.0 (the "Apache License")
-###    with the following modification; you may not use this file except in
-###    compliance with the Apache License and the following modification to it:
-###    Section 6. Trademarks. is deleted and replaced with:
-###
-###    6. Trademarks. This License does not grant permission to use the trade
-###       names, trademarks, service marks, or product names of the Licensor
-###       and its affiliates, except as required to comply with Section 4(c) of
-###       the License and to reproduce the content of the NOTICE file.
-###
-###    You may obtain a copy of the Apache License at
-###
-###        http://www.apache.org/licenses/LICENSE-2.0
-###
-###    Unless required by applicable law or agreed to in writing, software
-###    distributed under the Apache License with the above modification is
-###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-###    KIND, either express or implied. See the Apache License for the specific
-###    language governing permissions and limitations under the Apache License.
-###
-###
+# Copyright 2017 Pixar
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
 module Chook
 
-  # This method is used by the Ruby event-handler files.
+  # This method is used by the Ruby 'internal' event-handler files.
+  #
+  # those handlers are defined by passing a block to this method, like so:
+  #
+  #   Chook.event_handler do |event|
+  #     # so something with the event
+  #   end
   #
-  # Loading them should call this method and pass in a block
+  # Loading them will call this method and pass in a block
   # with one parameter: a Chook::HandledEvent subclass instance.
   #
-  # The block is then converted to a Proc instance in @loaded_event_handler
-  # and from there can be stored for use by the event identified by the filename.
+  # The block is then converted to a #handle method in an anonymous object.
+  # The object is stored for use by the event identified by the filename.
+  #
+  # By storing it as a method in an object, the handlers themselves
+  # can use #break or #return to exit (or even #next)
   #
   # NOTE: the files should be read with 'load' not 'require', so that they can
   # be re-loaded as needed
@@ -44,7 +53,13 @@ module Chook
   # @return [Proc] the block converted to a Proc
   #
   def self.event_handler(&block)
-    HandledEvent::Handlers.loaded_handler = Proc.new(&block)
+    obj = Object.new
+    obj.define_singleton_method(:handle, &block)
+    # Loading the file created the object by calling this method
+    # but to access it after loading the file, we need to
+    # store it in here:
+    HandledEvent::Handlers.loaded_handler = obj
+    Chook.logger.debug "Code block for 'Chook.event_handler' loaded into \#handle method of runner-object #{obj.object_id}"
   end
 
   # the server class
@@ -53,53 +68,42 @@ module Chook
     # The Handlers namespace module
     module Handlers
 
-      # Module Constants
-      ############################
-
       DEFAULT_HANDLER_DIR = '/Library/Application Support/Chook'.freeze
 
-      # Module Instance Variables, & accessors
-      ############################
-
-      # This holds the most recently loaded Proc handler
-      # until it can be stored in the @handlers Hash
-      @loaded_handler = nil
+      # internal handler files must match this regex somewhere
+      INTERNAL_HANDLER_BLOCK_START_RE = /Chook.event_handler( ?\{| do) *\|/
 
-      # Getter for @loaded_handler
+      # self loaded_handler=
       #
-      # @return [Proc,nil] the most recent Proc loaded from a handler file.
+      # @return [Obj,nil] the most recent Proc loaded from a handler file.
       # destined for storage in @handlers
       #
       def self.loaded_handler
         @loaded_handler
       end
 
-      # Setter for @loaded_event_handler
+      # A holding place for internal handlers as they are loaded
+      # before being added to the @handlers Hash
+      # see Chook.event_handler(&block)
       #
-      # @param a_proc [Proc]  a Proc object for storage in @handlers
+      # @param a_proc [Object]  An object instance with a #handle method
       #
-      def self.loaded_handler=(a_proc)
-        @loaded_handler = a_proc
+      def self.loaded_handler=(anon_obj)
+        @loaded_handler = anon_obj
       end
 
-      # A hash of loaded handlers.
-      # Keys are Strings - the name of the events handled
-      # Values are Arrays of either Procs, or Pathnames to executable files.
-      # See the .handlers getter Methods
-      @handlers = {}
-
-      # Getter for @event_handlers
+      # Getter for @handlers
+      #
+      # @return [Hash{String => Array}] a mapping of Event Names as they
+      # come from the JSS to an Array of handlers for the event.
+      # The handlers are either Pathnames to executable external handlers
+      # or Objcts with a #handle method, for internal handlers
+      #  (The objects also have a #handler_file attribute that is the Pathname)
       #
-      # @return [Hash{String => Array}] a mapping of Event Names as the come from
-      # the JSS to an Array of handlers for the event. The handlers are either
-      # Proc objects to call from within ruby, or Pathnames to executable files
-      # which will take raw JSON on stdin.
       def self.handlers
         @handlers
       end
-
-      # Module Methods
-      ############################
+      @handlers ||= {}
 
       # Load all the event handlers from the handler_dir or an arbitrary dir.
       #
@@ -112,23 +116,31 @@ module Chook
       #
       # @return [void]
       #
-      def self.load_handlers(from_dir: Chook::CONFIG.handler_dir, reload: false)
+      def self.load_handlers(from_dir: Chook.config.handler_dir, reload: false)
+        # use default if needed
         from_dir ||= DEFAULT_HANDLER_DIR
+        handler_dir = Pathname.new(from_dir)
+        load_type = 'Loading'
+
         if reload
-          @handlers_loaded_from = nil
           @handlers = {}
           @loaded_handler = nil
+          load_type = 'Re-loading'
         end
 
-        handler_dir = Pathname.new(from_dir)
-        return unless handler_dir.directory? && handler_dir.readable?
+        Chook.logger.info "#{load_type} handlers from directory: #{handler_dir}"
+
+        unless handler_dir.directory? && handler_dir.readable?
+          Chook.logger.error "Handler directory '#{from_dir}' not a readable directory. No handlers loaded. "
+          return
+        end
 
         handler_dir.children.each do |handler_file|
           load_handler(handler_file) if handler_file.file? && handler_file.readable?
         end
 
-        @handlers_loaded_from = handler_dir
-        @handlers.values.flatten.size
+        Chook.logger.info "Loaded #{@handlers.values.flatten.size} handlers for #{@handlers.keys.size} event triggers"
+        @loaded_handler = nil
       end # load handlers
 
       # Load an event handler from a file.
@@ -158,33 +170,67 @@ module Chook
       # @return [void]
       #
       def self.load_handler(from_file)
+        Chook.logger.debug "Starting load of handler file '#{from_file.basename}'"
         handler_file = Pathname.new from_file
         event_name = event_name_from_handler_filename(handler_file)
-        return unless event_name
+        unless event_name
+          Chook.logger.debug "Ignoring file '#{from_file.basename}'"
+          return
+        end
 
         # create an array for this event's handlers, if needed
         @handlers[event_name] ||= []
 
-        if handler_file.executable?
-          # store as a Pathname, we'll pipe JSON to it
-          unless @handlers[event_name].include? handler_file
-            @handlers[event_name] << handler_file
-            puts "===> Loaded executable handler file '#{handler_file.basename}'"
-          end
+        return if load_external_handler(handler_file, event_name)
+
+        load_internal_handler(handler_file, event_name)
+      end # self.load_handler(handler_file)
+
+      # if the given file is executable, store it's path as a handler for the event
+      #
+      #
+      def self.load_external_handler(handler_file, event_name)
+        return false unless handler_file.executable?
+
+        Chook.logger.info "Loading external handler file '#{handler_file.basename}' for #{event_name} events"
+
+        # store the Pathname, we'll pipe JSON to it
+        @handlers[event_name] << handler_file
+        true
+      end
+
+      # if a given path is not executable, try to load it as an internal handler
+      #
+      #
+      def self.load_internal_handler(handler_file, event_name)
+        # load the file. If written correctly, it will
+        # put an anon. Object with a #handle method into @loaded_handler
+        Chook.logger.info "Loading internal handler file '#{handler_file.basename}' for #{event_name} events"
+
+        unless handler_file.read =~ INTERNAL_HANDLER_BLOCK_START_RE
+          Chook.logger.error "Internal handler file '#{handler_file.basename}' missing event_handler block"
           return
         end
 
-        # load the file. If written correctly, it will
-        # put a Proc into @loaded_handler
-        load handler_file.to_s
-        if @loaded_handler
-          @handlers[event_name] << @loaded_handler
-          puts "===> Loaded internal handler file '#{handler_file.basename}'"
-          @loaded_handler = nil
-        else
-          puts "===> FAILED loading internal handler file '#{handler_file.basename}'"
+        # reset @loaded_handler - the `load` call will refill it
+        # see Chook.event_handler
+        @loaded_handler = nil
+        begin
+          load handler_file.to_s
+          raise '@loaded handler nil after loading file' unless @loaded_handler
+        rescue => e
+          Chook.logger.error "FAILED loading internal handler file '#{handler_file.basename}': #{e}"
+          return
         end
-      end # self.load_handler(handler_file)
+
+        # add a method to the object to get its filename
+        @loaded_handler.define_singleton_method(:handler_file) { handler_file.basename.to_s }
+
+        @handlers[event_name] << @loaded_handler
+
+        Chook.logger.debug "Loaded internal handler file '#{handler_file.basename}'"
+        @loaded_handler = nil
+      end
 
       # Given a handler filename, return the event name it wants to handle
       #
@@ -194,9 +240,16 @@ module Chook
       # @return [String,nil] The matching event name or nil if no match
       #
       def self.event_name_from_handler_filename(filename)
+        filename = filename.basename
         @event_names ||= Chook::Event::EVENTS.keys
-        desired_event_name = filename.basename.to_s.split(/\.|-|_/).first
-        @event_names.select { |n| desired_event_name.casecmp(n).zero? }.first
+        desired_event_name = filename.to_s.split(/\.|-|_/).first
+        ename = @event_names.select { |n| desired_event_name.casecmp(n).zero? }.first
+        if ename
+          Chook.logger.debug "Found event name '#{ename}' at start of filename '#{filename}'"
+        else
+          Chook.logger.debug "No known event name at start of filename '#{filename}'"
+        end
+        ename
       end
 
     end # module Handler