chook 1.0.0.b1

data/lib/chook/event/handled_event.rb

@@ -0,0 +1,154 @@
+### 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.
+###
+###
+
+require 'chook/event/handled_event/handlers'
+
+#
+module Chook
+
+  # Load sample JSON files, one per event type
+  @sample_jsons = {}
+  base_dir = Pathname.new(__FILE__)
+  data_dir = base_dir.parent.parent.parent.parent
+  sample_json_dir = Pathname.new(data_dir.to_s + '/data/sample_jsons')
+  sample_json_dir.children.each do |jf|
+    event = jf.basename.to_s.chomp(jf.extname).to_sym
+    @sample_jsons[event] = jf.read
+  end
+
+  def self.sample_jsons
+    @sample_jsons
+  end
+
+  # An event that has been recieved and needs to be handled.
+  #
+  # This is the parent class to all of the classes in the
+  # Chook::HandledEvents module, which are dynamically defined when this
+  # file is loaded.
+  #
+  # All constants, methods, and attributes that are common to HandledEvent
+  # classes are defined here, including the interaction with the Handlers
+  # module.
+  #
+  # Subclasses are automatically generated from the keys and values of
+  # Chook::Event::EVENTS
+  #
+  # Each subclass will have a constant SUBJECT_CLASS containing the
+  # class of their #subject attribute.
+  #
+  class HandledEvent < Chook::Event
+
+    #### 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.
+    #
+    # @return [void]
+    #
+    def self.generate_classes
+      Chook::Event::EVENTS.each do |class_name, subject|
+        next if Chook::HandledEvents.const_defined? class_name
+
+        # make the new HandledEvent subclass
+        the_class = Class.new(Chook::HandledEvent)
+
+        # Set its EVENT_NAME constant, which is used
+        # for finding it's handlers, among other things.
+        the_class.const_set Chook::Event::EVENT_NAME_CONST, class_name
+
+        # Set its SUBJECT_CLASS constant to the appropriate
+        # class in the HandledSubjects module.
+        the_class.const_set Chook::Event::SUBJECT_CLASS_CONST, Chook::HandledSubjects.const_get(subject)
+
+        # Add the new class to the HandledEvents module.
+        Chook::HandledEvents.const_set(class_name, the_class)
+      end # each classname, subject
+    end # self.generate_classes
+
+    # Given the raw json from the JSS webhook,
+    # create an object of the correct Event subclass
+    #
+    # @param [String] raw_event_json The JSON http POST content from the JSS
+    #
+    # @return [JSSWebHooks::Event subclass] the Event subclass matching the event
+    #
+    def self.parse_event(raw_event_json)
+      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
+    end
+
+    #### Attributes
+
+    # @return [Array<Proc,Pathname>] the handlers defined for this event.
+    #   Each is either a proc, in which case it is called with this
+    #   instance as its sole paramter, or its a Pathname to an executable
+    #   file, in which case the @raw_json is passed to its stdin.
+    #   See the Chook::HandledEvent::Handlers module.
+    attr_reader :handlers
+
+    #### Constructor
+
+    # Handled Events are always built from raw_json.
+    #
+    def initialize(raw_event_json)
+      super raw_json: raw_event_json
+    end # init
+
+    def handle
+      handlers = Handlers.handlers[self.class.const_get(Chook::Event::EVENT_NAME_CONST)]
+      handlers.each do |handler|
+        case handler
+        when Pathname
+          pipe_to_executable handler
+        when Proc
+          handle_with_proc handler
+        end # case
+      end # @handlers.each do |handler|
+
+      # 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"
+    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
+    end
+
+    def handle_with_proc(handler)
+      _thread = Thread.new { handler.call self }
+    end
+
+  end # class HandledEvent
+
+end # module

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

@@ -0,0 +1,206 @@
+### 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.
+  #
+  # Loading them should 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.
+  #
+  # NOTE: the files should be read with 'load' not 'require', so that they can
+  # be re-loaded as needed
+  #
+  # @see_also Chook::load_handlers
+  #
+  # @param [Block] block the block to be used as an event handler
+  #
+  # @yieldparam [JSS::WebHooks::Event subclass] The event to be handled
+  #
+  # @return [Proc] the block converted to a Proc
+  #
+  def self.event_handler(&block)
+    HandledEvent::Handlers.loaded_handler = Proc.new(&block)
+  end
+
+  # the server class
+  class HandledEvent < Event
+
+    # 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
+
+      # Getter for @loaded_handler
+      #
+      # @return [Proc,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
+      #
+      # @param a_proc [Proc]  a Proc object for storage in @handlers
+      #
+      def self.loaded_handler=(a_proc)
+        @loaded_handler = a_proc
+      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
+      #
+      # @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
+      ############################
+
+      # Load all the event handlers from the handler_dir or an arbitrary dir.
+      #
+      # @param from_dir [String, Pathname] directory from which to load the
+      #   handlers. Defaults to CONFIG.handler_dir or DEFAULT_HANDLER_DIR if
+      #   config is unset
+      #
+      # @param reload [Boolean] should we reload handlers if they've already
+      #   been loaded?
+      #
+      # @return [void]
+      #
+      def self.load_handlers(from_dir: Chook::CONFIG.handler_dir, reload: false)
+        from_dir ||= DEFAULT_HANDLER_DIR
+        if reload
+          @handlers_loaded_from = nil
+          @handlers = {}
+          @loaded_handler = nil
+        end
+
+        handler_dir = Pathname.new(from_dir)
+        return unless handler_dir.directory? && handler_dir.readable?
+
+        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
+      end # load handlers
+
+      # Load an event handler from a file.
+      # Handler files must begin with the name of the event they handle,
+      # e.g. ComputerAdded,  followed by: nothing, a dot, a dash, or
+      # and underscore. Case doesn't matter.
+      # So all of these are OK:
+      # ComputerAdded
+      # computeradded.sh
+      # COMPUTERAdded_notify_team
+      # Computeradded-update-ldap
+      # There can be as many as desired for each event.
+      #
+      # Each must be either:
+      #   - An executable file, which will have the raw JSON from the JSS piped
+      #     to it's stdin when executed
+      # or
+      #   - A non-executable file of ruby code like this:
+      #     Chook.event_handler do |event|
+      #       # your code goes here.
+      #     end
+      #
+      # (see the Chook README for details about writing the ruby handlers)
+      #
+      # @param from_file [Pathname] the file from which to load the handler
+      #
+      # @return [void]
+      #
+      def self.load_handler(from_file)
+        handler_file = Pathname.new from_file
+        event_name = event_name_from_handler_filename(handler_file)
+        return unless event_name
+
+        # 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
+        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}'"
+        end
+      end # self.load_handler(handler_file)
+
+      # Given a handler filename, return the event name it wants to handle
+      #
+      # @param [Pathname] filename The filename from which to glean the
+      #   event name.
+      #
+      # @return [String,nil] The matching event name or nil if no match
+      #
+      def self.event_name_from_handler_filename(filename)
+        @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
+      end
+
+    end # module Handler
+
+  end # class handledevent
+
+end # module

data/lib/chook/event/test_event.rb

@@ -0,0 +1,140 @@
+### 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
+
+  # An event that will be sent to a Webhook Server, simulating
+  # one from the JSS.
+  #
+  # This is the parent class to all of the classes in the
+  # Chook::TestEvents module, which are dynamically defined when this
+  # file is loaded.
+  #
+  # All constants, methods, and attributes that are common to TestEvent
+  # classes are defined here.
+  #
+  class TestEvent < Chook::Event
+
+    EVENT_ATTRIBUTES = %w(webhook_id webhook_name subject).freeze
+
+    # For each event type in Chook::Event::EVENTS.keys
+    # generate a TestEvent class for it, set its SUBJECT_CLASS constant
+    # and add it to the TestEvents module.
+    #
+    # @return [void]
+    #
+    def self.generate_classes
+      Chook::Event::EVENTS.each do |classname, subject|
+        next if Chook::TestEvents.const_defined? classname
+        # make the new TestEvent subclass
+        new_class = Class.new(Chook::TestEvent) do
+          # Setters & Getters
+          EVENT_ATTRIBUTES.each do |attribute|
+            # Getter
+            attr_reader attribute
+            # Setter
+            if attribute == 'subject'
+              define_method("#{attribute}=") do |new_val|
+                raise "Invalid TestSubject: Chook::TestEvents::#{classname} requires a Chook::TestSubjects::#{EVENTS[classname]}" unless Chook::Validators.send(:valid_test_subject, classname, new_val)
+                instance_variable_set(('@' + attribute.to_s), new_val)
+              end # end define_method
+            else
+              define_method("#{attribute}=") do |new_val|
+                instance_variable_set(('@' + attribute.to_s), new_val)
+              end # end define_method
+            end
+          end # end EVENT_ATTRIBUTES.each do |attribute|
+        end # end new_class
+
+        # Set its EVENT_NAME constant
+        new_class.const_set Chook::TestEvent::EVENT_NAME_CONST, classname
+
+        # Set its SUBJECT_CLASS constant to the appropriate
+        # class in the TestEvents module.
+        new_class.const_set Chook::TestEvent::SUBJECT_CLASS_CONST, Chook::TestSubjects.const_get(subject)
+
+        # Add the new class to the HandledEvents module.
+        Chook::TestEvents.const_set(classname, new_class)
+      end # each classname, subject
+    end # self.generate_classes
+
+    # json_hash
+    # Used by the fire method
+    #
+    # @return [Hash] A JSON Event payload formatted as a Hash.
+    #
+    def json_hash
+      raw_hash_form = {}
+      raw_hash_form['webhook'.to_sym] = { 'webhookEvent'.to_sym => self.class.to_s.split('::')[-1] }
+      EVENT_ATTRIBUTES.each do |json_attribute|
+        next if json_attribute.include? 'json'
+        if json_attribute == 'subject'
+          raw_hash_form['event'.to_sym] = instance_variable_get('@' + json_attribute).json_hash
+        else
+          json_hash_attribute = json_attribute.split('webhook_')[1] || json_attribute
+          nested_hash = Hash.new do |hash, key|
+            hash[key] = {}
+          end # end nested_hash
+          nested_hash[json_hash_attribute.to_sym] = instance_variable_get('@' + json_attribute)
+          raw_hash_form['webhook'.to_sym][nested_hash.keys[0]] = nested_hash[nested_hash.keys[0]]
+        end
+      end # end EVENT_ATTRIBUTES.each do |json_attribute|
+      raw_hash_form # This is the structural equivalent of the Chook::Event @json_hash form
+    end # end json_hash
+
+    # fire
+    #
+    # @param [String] server_url The URL of a server that can handle an Event
+    # @return [void]
+    #
+    def fire(server_url)
+      raise 'Please provide a destination server URL' unless server_url
+      uri = URI.parse(server_url)
+      raise 'Please provide a valid destination server URL' if uri.host.nil?
+      data = json_hash.to_json # This is the structural equivalent of the Chook::Event @raw_json form
+      http_connection = Net::HTTP.new uri.host, uri.port
+      http_connection.post(uri, data)
+    end # end fire
+
+    # initialize
+    # The optional argument is a Hash with the appropriate keys defiend
+    #
+    # @param [Hash] event_data nil or Hash
+    # @return [TestEvent] A new TestEvents subclass object
+    #
+    def initialize(event_data = nil)
+      if event_data
+        event_data.each do |key, value|
+          next unless EVENT_ATTRIBUTES.include? key
+          instance_variable_set(('@' + key.to_s), value)
+        end # event_data.each
+      else
+        EVENT_ATTRIBUTES.each { |attribute| instance_variable_set(('@' + attribute.to_s), nil) }
+      end # end if event_data
+    end # end init
+
+  end # class TestEvent
+
+end # module