foreman-tasks 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+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,139 @@
+Foreman Tasks
+=============
+
+Tasks management engine for Foreman. Gives you and overview of what's
+happening/happened in your Foreman instance.
+
+Installation
+------------
+
+Put the following to your Foreman's bundle.d/Gemfile.local.rb:
+
+```ruby
+gem 'dynflow', :git => 'git@github.com:iNecas/dynflow.git'
+gem 'foreman-tasks', :git => 'git@github.com:iNecas/foreman-tasks.git'
+```
+
+Run:
+
+```bash
+bundle install
+rake db:migrate
+```
+
+Usage
+-----
+
+In the UI, go to `/foreman_tasks/tasks`. This should give a list of
+tasks that were run in the system. It's possible to filter that using
+scoped search. Possible searches:
+
+```
+# search all tasks by user
+owner.login = admin
+# search all tasks on architecture with id 9
+resource_type = Architecture and resource_id = 9
+```
+
+Clicking on the action, it should provide more details.
+
+Via API:
+
+```bash
+curl -k -u admin:changeme\
+  https://foreman.example.com/foreman_tasks/api/tasks/b346db45-76fd-4217-9247-aac51b5cde4e -H 'Accept: application/json'
+```
+
+Features
+--------
+
+* Current tasks progress
+* Audit: tasks history for resources and users
+* Possibility to generate CLI examples
+* Locking: connection between task and resource: allows listing tasks
+  for a resource but also allows preventing to run two
+  conflicting tasks on one resource.
+* Dynflow integration allowing async processing, workflows definitions etc.
+
+
+Dynflow Integration
+-------------------
+
+This engine is agnostic on background processing tool and can be used
+with anything that allows supports some kind of execution hooks.
+
+On the other side, since we started this as part of Katello
+integration with Dynflow, the dynflow adapters are already there.
+
+Also, since dynflow has no additional dependencies in terms of another
+database (tested mainly on Postgres), this gem ships the Dynflow
+setting so that Dynflow can be used directly.
+
+It's turned off by default, but you can turn that on with putting this
+code somewhere in Rails initialization process. In case of an engine,
+it would be:
+
+```ruby
+initializer "your_engine.dynflow_initialize" do |app|
+  ForemanTasks.dynflow.require!
+end
+```
+
+Additionally, there are also examples of using Dynflow for async tasks
+and auditing included in this repository. To enable them you just need
+to set `FOREMAN_TASKS_MONKEYS` env variable to `true`
+
+```bash
+FOREMAN_TASKS_MONKEYS=true bundle exec rails s
+```
+
+The example for async tasks handling is the puppet facts import. Next
+time puppet imports the facts to Foreman, the task should appear in
+the tasks list.
+
+The example for auditing features is the architecture model. On every
+modification, there is a corresponding Dynflow action triggered. This
+leads to it appearing in the tasks list as well, even there was no
+async processing involved, but still using the same interface to
+show the task.
+
+The Dynflow console is accessible on `/foreman_tasks/dynflow` path.
+
+## Production mode
+
+In development mode, the Dynflow executor is part of the web server
+process. However, in production, it's more than suitable to have the
+web server process separated from the async executor. Therefore,
+Dynflow is set to use external process in production mode by default
+(can be changed with `ForemanTasks.dynflow.config.remote = false`).
+
+The executor process needs to be executed before the web server. You
+can run it by:
+
+```
+RAILS_ENV=production bundle exec rake foreman_tasks:dynflow:executor
+```
+
+Also, there is a possibility to run the executor in daemonized mode
+using the `dynflow-executor`. It expects to be executed from Foreman
+rails root directory. See `-h` for more details and options
+
+Documentation
+-------------
+
+TBD - dig into the code for now (happy hacking:)
+
+Tests
+-----
+
+TBD
+
+License
+-------
+
+MIT
+
+Author
+------
+
+Ivan Nečas

data/app/controllers/foreman_tasks/api/tasks_controller.rb

@@ -0,0 +1,140 @@
+#
+# Copyright 2013 Red Hat, Inc.
+#
+# This software is licensed to you under the GNU General Public
+# License as published by the Free Software Foundation; either version
+# 2 of the License (GPLv2) or (at your option) any later version.
+# There is NO WARRANTY for this software, express or implied,
+# including the implied warranties of MERCHANTABILITY,
+# NON-INFRINGEMENT, or FITNESS FOR A PARTICULAR PURPOSE. You should
+# have received a copy of GPLv2 along with this software; if not, see
+# http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
+
+module ForemanTasks
+  module Api
+    class TasksController < ::Api::V2::BaseController
+
+      # Foreman right now doesn't have mechanism to
+      # cause general BadRequest handling, resuing the Apipie::ParamError
+      # for now http://projects.theforeman.org/issues/3957
+      class BadRequest < Apipie::ParamError
+      end
+
+      before_filter :find_task, :only => [:show]
+
+      def show
+      end
+
+      api :POST, "/tasks/bulk_search", "List dynflow tasks for uuids"
+      param :searches, Array, :desc => 'List of uuids to fetch info about' do
+        param :search_id, String, :desc => <<-DESC
+        Arbitraty value for client to identify the the request parts with results.
+        It's passed in the results to be able to pair the requests and responses properly.
+      DESC
+        param :type, %w[user resource task]
+        param :task_id, String, :desc => <<-DESC
+        In case :type = 'task', find the task by the uuid
+      DESC
+        param :user_id, String, :desc => <<-DESC
+        In case :type = 'user', find tasks for the user
+      DESC
+        param :resource_type, String, :desc => <<-DESC
+        In case :type = 'resource', what resource type we're searching the tasks for
+      DESC
+        param :resource_type, String, :desc => <<-DESC
+        In case :type = 'resource', what resource id we're searching the tasks for
+      DESC
+        param :active_only, :bool
+        param :page, String
+        param :per_page, String
+      end
+      desc <<-DESC
+        For every search it returns the list of tasks that satisfty the condition.
+        The reason for supporting multiple searches is the UI that might be ending
+        needing periodic updates on task status for various searches at the same time.
+        This way, it is possible to get all the task statuses with one request.
+      DESC
+      def bulk_search
+        searches = Array(params[:searches])
+        @tasks = {}
+
+        ret = searches.map do |search_params|
+          { search_params: search_params,
+            results: search_tasks(search_params) }
+        end
+        render :json => ret
+      end
+
+      private
+
+      def search_tasks(search_params)
+        scope = ::ForemanTasks::Task.select('DISTINCT foreman_tasks_tasks.*')
+        scope = ordering_scope(scope, search_params)
+        scope = search_scope(scope, search_params)
+        scope = active_scope(scope, search_params)
+        scope = pagination_scope(scope, search_params)
+        scope.all.map { |task| task_hash(task) }
+      end
+
+      def search_scope(scope, search_params)
+        case search_params[:type]
+        when 'all'
+          scope
+        when 'user'
+          if search_params[:user_id].blank?
+            raise BadRequest, _("User search_params requires user_id to be specified")
+          end
+          scope.joins(:locks).where(foreman_tasks_locks:
+                                    { name: ::ForemanTasks::Lock::OWNER_LOCK_NAME,
+                                      resource_type: 'User',
+                                      resource_id:   search_params[:user_id] })
+        when 'resource'
+          if search_params[:resource_type].blank? || search_params[:resource_id].blank?
+            raise BadRequest, _("Resource search_params requires resource_type and resource_id to be specified")
+          end
+          scope.joins(:locks).where(foreman_tasks_locks:
+                                    { resource_type: search_params[:resource_type],
+                                      resource_id:   search_params[:resource_id] })
+        when 'task'
+          if search_params[:task_id].blank?
+            raise BadRequest, _("Task search_params requires task_id to be specified")
+          end
+          scope.where(id: search_params[:task_id])
+        else
+          raise BadRequest, _("Search_Params %s not supported") % search_params[:type]
+        end
+      end
+
+      def active_scope(scope, search_params)
+        if search_params[:active_only]
+          scope.active
+        else
+          scope
+        end
+      end
+
+      def pagination_scope(scope, search_params)
+        page     = search_params[:page] || 1
+        per_page = search_params[:per_page] || 10
+        scope = scope.limit(per_page).offset((page - 1) * per_page)
+      end
+
+      def ordering_scope(scope, search_params)
+        scope.order('started_at DESC')
+      end
+
+      def task_hash(task)
+        return @tasks[task.id] if @tasks[task.id]
+        task_hash = Rabl.render(task, 'show', :view_path => "#{ForemanTasks::Engine.root}/app/views/foreman_tasks/api/tasks", :format => :hash, :scope => self)
+        @tasks[task.id] = task_hash
+        return task_hash
+      end
+
+      private
+
+      def find_task
+        @task = Task.find_by_id(params[:id])
+      end
+    end
+  end
+end

data/app/controllers/foreman_tasks/concerns/hosts_controller_extension.rb

@@ -0,0 +1,26 @@
+module ForemanTasks
+  module Concerns
+    module HostsControllerExtension
+      extend ActiveSupport::Concern
+
+      included do
+        alias_method_chain :facts, :dynflow
+      end
+
+      def facts_with_dynflow
+        task = ForemanTasks.async_task(::Actions::Foreman::Host::ImportFacts,
+                                       detect_host_type,
+                                       params[:name],
+                                       params[:facts],
+                                       params[:certname],
+                                       detected_proxy.try(:id))
+
+        render :json => {:task_id => task.id}, :status => 202
+      rescue ::Foreman::Exception => e
+        render :json => {'message'=>e.to_s}, :status => :unprocessable_entity
+      end
+
+    end
+  end
+end
+

data/app/controllers/foreman_tasks/tasks_controller.rb

@@ -0,0 +1,19 @@
+module ForemanTasks
+  class TasksController < ::ApplicationController
+    include Foreman::Controller::AutoCompleteSearch
+
+    def show
+      @task = Task.find(params[:id])
+    end
+
+    def index
+      params[:order] ||= "started_at DESC"
+      @tasks = Task.search_for(params[:search], :order => params[:order]).paginate(:page => params[:page])
+    end
+
+    # we need do this to make the Foreman helpers working properly
+    def controller_name
+      "foreman_tasks_tasks"
+    end
+  end
+end

data/app/helpers/foreman_tasks/tasks_helper.rb

@@ -0,0 +1,16 @@
+module ForemanTasks
+  module TasksHelper
+    def format_task_input(task, include_action = false)
+      parts = []
+      parts << task.humanized[:action] if include_action
+      parts << Array(task.humanized[:input]).map do |part|
+        if part.is_a? Array
+          part[1][:text]
+        else
+          part.to_s
+        end
+      end.join('; ')
+      h(parts.join(" "))
+    end
+  end
+end

data/app/lib/actions/base.rb

@@ -0,0 +1,36 @@
+module Actions
+  class Base < Dynflow::Action
+
+    # This method says what data form input gets into the task details in Rest API
+    # By default, it sends the whole input there.
+    def task_input
+      self.input
+    end
+
+    # This method says what data form output gets into the task details in Rest API
+    # It should aggregate the important data that are worth to propagate to Rest API,
+    # perhaps also aggraget data from subactions if needed (using +all_actions+) method
+    # of Dynflow::Action::Presenter
+    def task_output
+      self.output
+    end
+
+    # This method should return humanized description of the action, e.g. "Install Package"
+    def humanized_name
+      action_class.name[/\w+$/].gsub(/([a-z])([A-Z])/) { "#{$1} #{$2}" }
+    end
+
+    # This method should return String of Array<String> describing input for the task
+    def humanized_input
+      task_input.pretty_inspect
+    end
+
+    # This method should return String describing output for the task.
+    # It should aggregate the data from subactions as well and it's used for humanized
+    # description of restuls of the action
+    def humanized_output
+      task_output.pretty_inspect
+    end
+
+  end
+end

data/app/lib/actions/entry_action.rb

@@ -0,0 +1,51 @@
+module Actions
+
+  class EntryAction < Actions::Base
+    include Helpers::ArgsSerialization
+    include Helpers::Lock
+
+    # what locks to use on the resource? All by default, can be overriden.
+    # It might one or more locks available for the resource. This following
+    # special values are supported as well:
+    #
+    #  * `:all`:        lock all possible operations (all locks defined in resource's
+    #                   `available_locks` method. Only tasks that link to the resource are
+    #                   allowed while running this task
+    #  * `:exclusive`:  same as `:all` + doesn't allow even linking to the resoruce.
+    #                   typical example is deleting a container, preventing all actions
+    #                   heppening on it's sub-resources (such a system).
+    def resource_locks
+      :all
+    end
+
+    # Peforms all that's needed to connect the action to the resource.
+    # It converts the resource (and it's relatives defined in +related_resources+
+    # to serialized form (using +to_action_input+).
+    #
+    # It also locks the resource on the actions defined in +resource_locks+ method.
+    #
+    # The additional args can include more resources and/or a hash
+    # with more data describing the action that should appear in the
+    # action's input.
+    def action_subject(resource, *additional_args)
+      if resource.respond_to?(:related_resources_recursive)
+        related_resources = resource.related_resources_recursive
+      else
+        related_resources = []
+      end
+      plan_self(serialize_args(resource, *related_resources, *additional_args))
+      if resource.is_a? ActiveRecord::Base
+        if resource_locks == :exclusive
+          exclusive_lock!(resource)
+        else
+          lock!(resource, resource_locks)
+        end
+      end
+    end
+
+    def humanized_input
+      Helpers::Humanizer.new(self).input
+    end
+
+  end
+end