git-restart 0.0.14.pre.dev → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6eb1eb18f538b107ff746a74bd5e915d086d7a42
-  data.tar.gz: 7f027170a97419f103005c983818a53f533df720
+  metadata.gz: 89f6a4a1fa9ad535f9a80f69fc2729e28fa4c077
+  data.tar.gz: '09e3329d30be30ea60511e894dc0f1e0ba44375b'
 SHA512:
-  metadata.gz: 66c6d72431590ae182bb58498d826a4601fbb9e8f1af8f2fb65fc00e5517b2bac2ce814943f2a64b29351de683fea521ab036bdfaa4b1bbe3fe0c504a68f3574
-  data.tar.gz: fa56dd81445f2858f4d547286332c7132ec461e8e44a67f60791720b8d9f44c66eb6b4670ff0e1eedfc2afaee22d0b0e67c035ff6206c1df26c0711f1a3bba68
+  metadata.gz: e46803d3834a7fec3c2166f8864d45b746de31b0ca9d6e87c839ab806a4b5943ff822739ef209d447d7e45aa4a88d8dd77b812b478f7ac8d042b1a08983965e8
+  data.tar.gz: 6e883c22e0dd8b1ee5c09a2c51a193d67ff82c2abcdbc33f3ed1232bdf73d3373b8835365d1a248b242b985e0eae30226f1d008a9375318aefc43e2bc0b134a6

data/bin/git-restart

@@ -8,9 +8,9 @@ puts "Starting runner ..."
 $taskfiles = Array.new();
 target = ".gitrun"
 ARGV.each do |t|
-	if(File.extname(t) == ".gitrun")
+	if(t =~ /\.gitrun$/)
 		target = t;
-	elsif(File.extname(t) == ".gittask")
+	else
 		$taskfiles << t;
 	end
 end

data/lib/git-restart/runner.rb

@@ -8,23 +8,41 @@ require_relative "task.rb"
 
 module GitRestart
 	class Runner
+		# Sets a name for this Runner, used for reporting to GitHub
 		attr_accessor :name
 
-		attr_accessor :repo, :branches, :exclude_branches, :start_on
+		# Which repository to listen to. Uses "Owner/Repo" syntax.
+		attr_accessor :repo
+		# A white- and blacklist of branches. If neither are specified, all are used.
+		# If the whitelist is used, only it is considered.
+		attr_accessor :branches, :exclude_branches
+		# Which branch to start on.
+		# This not only makes the system switch branch, but it will also execute
+		# ALL active tasks. Very useful for auto-updating servers.
+		attr_accessor :start_on
+		# A list of tasks that this Runner will actually look at.
+		# If nil, all tasks are allowed.
 		attr_accessor :allowed_tasks
 
 		attr_reader	  	:next_tasks
 		attr_reader		:current_task_file
 
+		# The MQTT::SubHandler to use to listen to GitHub updates.
+		# Can be specified as either MQTT::SubHandler class or String, the latter
+		# will be interpreted as URI
 		attr_reader		:mqtt
+		# Octokit to use for optional status reporting
 		attr_accessor	:octokit
 
+		# @return [String] Full SHA of the current commit
 		def current_commit()
 			@git.object("HEAD").sha;
 		end
+		# @return [String] Name of the current branch
 		def current_branch()
 			@git.current_branch();
 		end
+		# @return [Array<String>] A list of all files that were modified in the commit we are checking
 		def current_modified()
 			@current_modified;
 		end
@@ -77,20 +95,24 @@ module GitRestart
 			}
 		end
 
+		# Update the GitHub status for the task of given name, with optional status message
+		# Only prints a line if no octokit is specified
 		def update_status(name, newStatus, message = nil)
-			puts "Task #{@name} assumed a new status: #{newStatus}#{message ? " MSG:#{message}" : ""}"
+			puts "Task #{name} assumed a new status: #{newStatus}#{message ? " MSG:#{message}" : ""}"
 
 			return unless @octokit;
 
 			begin
 			@octokit.create_status(@repo, current_commit(), newStatus, {
-					context: "#{@name}/#{name}".gsub(" ", "_"),
+					context: "#{name}/#{name}".gsub(" ", "_"),
 					description: message,
 				})
 			rescue
 			end
 		end
 
+		# Start the task responsible for queueing and executing the individual
+		# task stop, branch switch, task start cycles
 		def _start_task_thread()
 			@taskThread = Thread.new do
 				loop do
@@ -101,7 +123,9 @@ module GitRestart
 				end
 			end.abort_on_exception = true;
 		end
+		private :_start_task_thread
 
+		# Stop all tasks of the given hash, not list. Waits for them to stop.
 		def _stop_tasks(taskList)
 			taskList.each do |name, t|
 				t.stop();
@@ -111,19 +135,27 @@ module GitRestart
 				@current_tasks.delete(name);
 			end
 		end
+		private :_stop_tasks
 		def _stop_all_tasks()
 			_stop_tasks(@current_tasks);
 		end
+		private :_stop_all_tasks
+		# Stop all tasks that have marked themselves as affected by the
+		# current set of file-changes. This way, applications are only
+		# restarted when their own files have been altered.
 		def _stop_triggered_tasks()
 			_stop_tasks(@current_tasks.select {|k,v| v.triggered?});
 		end
+		private :_stop_triggered_tasks
 
+		# Scan through the file-tree for .gittask files, or use the @allowed_tasks
+		# list of tasks.
 		def _generate_next_tasks()
 			puts "Generating new tasks..."
 			@next_tasks = Hash.new();
 
 			taskFiles = `find ./ -nowarn -iname "*.gittask"`
-			taskFiles.split("\n").each do |t|
+			[taskFiles.split("\n"), @allowed_tasks].flatten.each do |t|
 				puts "Looking at: #{t}"
 				t.gsub!(/^\.\//,"");
 				@current_task_file = t;
@@ -145,7 +177,10 @@ module GitRestart
 
 			puts "Finished loading! Next tasks: #{@next_tasks.keys}"
 		end
+		private :_generate_next_tasks
 
+		# Start all new tasks that have marked themselves as affected by the current
+		# set of filechanges
 		def _start_next_tasks()
 			_generate_next_tasks();
 
@@ -158,7 +193,10 @@ module GitRestart
 				@current_tasks[name] = t;
 			end
 		end
+		private :_start_next_tasks
 
+		# Perform an entire cycle of git fetch & checkout, stop tasks, pull, restart.
+		# *CAUTION* A HARD RESET IS USED HERE
 		def _switch_to(branch, commit = nil)
 			puts "\n\nSwitching to branch: #{branch}#{commit ? ",commit: #{commit}" : ""}"
 
@@ -180,11 +218,13 @@ module GitRestart
 
 			_start_next_tasks();
 		end
+		private :_switch_to
 
 		def autostart()
 			return unless @start_on;
 			@branchQueue << {branch: @start_on};
 		end
+		private :autostart
 
 		def mqtt=(mqtt)
 			if(mqtt.is_a? String)

data/lib/git-restart/task.rb

@@ -1,39 +1,82 @@
 
+# @author Xasin
 module GitRestart
+	# The Error-Class used to signal when a Task is set up wrong
 	class TaskValidityError < StandardError
 	end
 
+	# This class is used to define "Tasks". Each task represents
+	# a set of commands, which it executes in chronological order, or until
+	# a task errors.
+	# Additionally, it will kill execution of tasks with a specified kill-signal
+	# when an update was detected from GitHub.
+	# The failure-status of the tasks can also be reported via Octokit, allowing this
+	# to be used as a simple CI or Test system for various languages.
 	class Task
+		# The array of tasks to execute. Each target will be executed in the given
+		# order via `Process.spawn`.
+		# @return [Array<String>]
 		attr_reader 	:targets
 
+		# The signal (as String, like Signal.list) to use to kill the process.
+		# Can be nil to disable killing
 		attr_accessor 	:signal
+		# Whether or not to report failure if the currently running target
+		# has a non-zero exit status after having been killed. Only makes sense
+		# together with report_status
 		attr_accessor	:expect_clean_exit
+		# Whether or not to report failure/success status to GitHub using Octokit
 		attr_accessor	:report_status
+		# Defines this as a "CI_Task". Such a task will always run on an update,
+		# regardless what files changed. Useful if you always want a status report
+		# on GitHub.
 		attr_accessor  :ci_task
-		attr_accessor	:name, :status_file
-
+		# Name of the Task. *Required*. Used as *unique* ID, and to report status to GitHub
+		attr_accessor	:name
+		# The file to use to retrieve a single-line status info for the "description"
+		# string of the GitHub status. Only the last *non-indented* line is used,
+		# which allows the output of Minitest to be used directly.
+		attr_accessor  :status_file
+
+		# Whether or not this task is active. Usually set via #on_branches,
+		# but can be used to manually disable or enable this task based on
+		# config files, ENV variables etc.
 		attr_accessor	:active
 
+		# The last status-code of this Task. Used internally.
 		attr_reader		:lastStatus
+		# The last status-message of this task. Used internally.
 		attr_reader		:status_message
 
+		# @api private
 		def self.runner=(runner)
 			@runner = runner;
 		end
+		# @api private
 		def self.runner()
 			return @runner;
 		end
+		# @return [GitRestart::Runner] Responsible Runner class
 		def runner()
 			return self.class.runner();
 		end
 
+		# @return [String] Name of the current branch
 		def branch()
 			runner().current_branch();
 		end
+		# @return [String] Full SHA of the current commit
+		def current_commit()
+			runner().current_commit();
+		end
+
+		# @return [Array<String>] A list of all files that were modified in the commit we are checking
 		def modified()
 			runner().current_modified();
 		end
 
+		# Use this function to specify which files trigger a restart for this Task
+		# Files can be specified as a RegEx, and can be "local/like.this" or "/reference/from/project.root"
 		def watch(regEx)
 			if(regEx.is_a? String)
 				regEx = Regexp.quote(regEx);
@@ -42,12 +85,17 @@ module GitRestart
 			@watched << Regexp.new(regEx);
 		end
 
+		# Specify which branches to run on. Not needed if "active" is just set to true
 		def on_branches(branches)
 			[branches].flatten.each do |b|
 				@active |= (b == branch());
 			end
 		end
 
+		# Create a new Task. This function does not take any input values, instead,
+		# one has to set the class up inside the block!
+		# A validity check will be run directly after yield(), as such, at the very least
+		# the name and a valid signal must have been specified!
 		def initialize()
 			@statuschange_mutex = Mutex.new();
 
@@ -67,6 +115,8 @@ module GitRestart
 
 			valid?
 
+			@status_file ||= "/tmp/TaskLog_#{@name}_#{current_commit()}";
+
 			if(runner().next_tasks[@name])
 				raise TaskValidityError, "A task of name #{@name} already exists!"
 			else
@@ -74,20 +124,31 @@ module GitRestart
 			end
 		end
 
+		# Checks whether or not the current set of modified files would require this
+		# task to be (re)started. Always returns true if @ci_task is set, or if
+		# the runner just has been started using @start_on
+		# @api private
 		def triggered?
 			return true if modified().nil?
 			return true if @ci_task
 
 			@watched.each do |regEx|
 				modified().each do |f|
-					next unless f =~ /#{Regexp.quote(@chdir)}(.*)/
-					return true if $1 =~ regEx;
+					if regEx.to_s =~ /^\(\?\-mix:\\\/(.*)\)$/ then
+						return true if f =~ Regexp.new($1);
+					else
+						next unless f =~ /#{Regexp.quote(@chdir)}(.*)/
+						return true if $1 =~ regEx;
+					end
 				end
 			end
 
 			return false;
 		end
 
+		# Checks whether or not this task has been set up properly. Currently only
+		# checks the name and abort signal.
+		# @api private
 		def valid?()
 			unless Signal.list[@signal] or @signal.nil?
 				raise TaskValidityError, "The specified kill-signal is not valid!"
@@ -98,8 +159,33 @@ module GitRestart
 			end
 		end
 
+		def _rm_logfile()
+			if File.exist?("/tmp/TaskLog_#{@name}_#{current_commit()}") then
+				File.delete("/tmp/TaskLog_#{@name}_#{current_commit()}");
+			end
+		end
+		private :_rm_logfile
+		def _get_statusline()
+			return "No status specified" unless File.exist? @status_file
+
+			sMsg = ""
+			File.open(@status_file, "r") do |sFile|
+				sFile.each_line do |l|
+					l.chomp!
+					next if l == "";
+					next if l =~ /^\s+/;
+
+					sMsg = l;
+				end
+			end
+
+			return sMsg;
+		end
+		private :_rm_logfile
+
 		def _report_status(status, message = nil)
-			@status_message = ""
+			message ||= _get_statusline();
+			@status_message = message;
 
 			return unless @report_status
 
@@ -107,6 +193,13 @@ module GitRestart
 		end
 		private :_report_status
 
+		# Starts this task.
+		# Once the task has been started it will run each given
+		# target one after another, waiting for each one to finish. If @report_status
+		# is set, it will also do just that.
+		# Task execution is handled within a thread, meaning that the function
+		# itself does not block.
+		# @api private
 		def start()
 			puts "Starting Task: #{@name}"
 
@@ -118,11 +211,13 @@ module GitRestart
 			@executionThread = Thread.new do
 				_report_status(:pending);
 
+				_rm_logfile();
 				@targets.each do |target|
+					# Mutex to ensure there either is no task running or a PID given
 					@statuschange_mutex.synchronize {
 						break if @exiting
 						options = {
-							[:out, :err] => "/dev/null"
+							[:out, :err] => "/tmp/TaskLog_#{@name}_#{current_commit()}"
 						}
 						options[:chdir] = @chdir if @chdir
 
@@ -138,6 +233,7 @@ module GitRestart
 
 				if(@lastStatus == 0)
 					_report_status(:success);
+					_rm_logfile();
 				elsif(!@exiting || @expect_clean_exit)
 					_report_status(:failure);
 				end
@@ -147,6 +243,11 @@ module GitRestart
 			sleep 0.01
 		end
 
+		# Stop this task.
+		# Stopping it means immediately killing the currently running target with
+		# the specified signal, and not running any further targets.
+		# *Except* when nil is specified as signal, in which case the stop will be ignored!
+		# @api private
 		def stop()
 			puts "Stopping Task: #{@name}"
 			return if @signal.nil?
@@ -159,6 +260,8 @@ module GitRestart
 			}
 		end
 
+		# Wait for this task to finish execution.
+		# Either by naturally ending, or by being killed.
 		def join()
 			@executionThread.join();
 		end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: git-restart
 version: !ruby/object:Gem::Version
-  version: 0.0.14.pre.dev
+  version: 0.1.0
 platform: ruby
 authors:
 - Xasin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-17 00:00:00.000000000 Z
+date: 2018-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mqtt-sub_handler
@@ -121,12 +121,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.14.1
+rubygems_version: 2.5.2.1
 signing_key: 
 specification_version: 4
 summary: "(Re)start scripts and monitor them on a GitHub push"