symphony-metronome 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 37cbbf6323e8b23dc0c63e6c0a7e6e6c5162931e
-  data.tar.gz: c55bc0d55c479f0598cf0f191888ff193f05710b
+SHA256:
+  metadata.gz: 7924d613c9657d90bf4214bb9408d1f23bb9ecb677fdad75e47517fb8f30846d
+  data.tar.gz: e1ee7ba0db1f90c3d0e71ab05209493590d00f00d560b743938f986e869a872c
 SHA512:
-  metadata.gz: 63abf234a35e8cca4a92a734220cb62eedf2d91f5bf88842225ab0d1a5b7ce154b62205155271417a3246747407e8bd06b17cfd1bd8c17ffc6d93974bb182965
-  data.tar.gz: c68f12fe582f81931262cc902cb316254b9f30d021bc5f924c7eba8d5575b4a0875ef9d7069efda10c6f735b8b9434b5462c8889a7bebc66bbe8f3dec70208b4
+  metadata.gz: a4146c565cf102bf1adf6979a4f57ffd5c2f8baedc8f6570da3654b0d65fd5183ae53778ee17d489de735c2f235875951d03347a84fe6143cf7fae86656ce95f
+  data.tar.gz: d9e6dd409f5206a1d98c8899626c2921465b013c2c160c84ffc43add998c3e32a672f5e75dbaa2f0c68f082dc6329f8b6cbaa9ac1def09847add88f7ca7549a2

data/History.md

@@ -0,0 +1,27 @@
+# Release History for Symphony-Metronome
+
+---
+
+## v0.3.0 [2023-03-20] Mahlon E. Smith <mahlon@martini.nu>
+
+- Updates for Ruby 3.
+- Dependency updates.
+- Conversion to more modern ruby development tooling.
+
+
+## v0.2.1 [2015-07-08] Mahlon E. Smith <mahlon@martini.nu>
+
+Enhancements:
+
+- Add "last run" timestamps for recurring events.
+
+Fixes:
+
+- Repair exact start times for recurring events, ie
+  'starting at 2015-01-01 09:00:00 run every other minute for 2 days'
+
+
+## v0.1.0 [2014-04-22] Mahlon E. Smith <mahlon@martini.nu>
+
+Initial release.
+

data/README.md

@@ -0,0 +1,224 @@
+# Metronome
+
+home
+: https://code.martini.nu/fossil/symphony-metronome
+
+docs
+: https://martini.nu/docs/symphony-metronome
+
+github_mirror
+: https://github.com/mahlonsmith/symphony-metronome
+
+
+
+## Description
+
+Metronome is an interval scheduler and task runner.  It can be used locally as a
+cron replacement, or as a network-wide job executor.  It is intended to be run
+alongside Symphony, a Ruby AMQP event consumer.
+
+Events are stored via simple database rows, and optionally themselves managed
+via AMQP events.  Interval/time values are expressed with intuitive English
+phrases, ie.: 'at 2pm', or 'Starting in 20 minutes, run every 10 seconds and
+then finish in 2 days', or 'execute 12 times during the next minute'.
+
+## Synopsis
+
+Here's an example of a simple cron clone:
+
+```
+#!ruby
+
+require 'symphony/metronome'
+
+Symphony.load_config
+
+Symphony::Metronome.run do |opts, id|
+	Thread.new do
+		pid = fork { exec opts.delete('command') }
+		Process.waitpid( pid )
+	end
+end
+```
+
+
+And here's a simplistic timed AMQP message broadcaster, using existing Symphony
+connection information:
+
+```
+#!ruby
+
+require 'symphony/metronome'
+
+Symphony.load_config
+
+Symphony::Metronome.run do |opts, id|
+	key = opts.delete( 'routing_key' ) or next
+	exchange = Symphony::Queue.amqp_exchange
+	exchange.publish( 'hi from Metronome!', routing_key: key )
+end
+```
+
+## Adding Actions
+
+There are two primary components to Metronome -- getting actions into
+its database, and performing some task with those actions when the time
+is appropriate.
+
+By default, Metronome will start up an AMQP listener, attached to your
+Symphony exchange, and wait for new scheduling messages.  There are two
+events it will take action on:
+
+metronome.create:
+
+	Create a new scheduled event.  The payload should be a hash.  An
+	'expression' key is required, that provides the interval description.
+	Anything additional is serialized to 'options', that are passed to the
+	block when the interval fires.  You can populate it with anything
+	your task requires to execute.
+
+metronome.delete:
+
+	The payload is the row ID of the action.  Metronome removes it from
+	the database.
+
+If you'd prefer not to use the AMQP listener, you can put actions into
+Metronome using any database methodology you please.  When the daemon
+starts up or receives a HUP signal, it will re-read and schedule out
+upcoming work.
+
+
+## Options
+
+Metronome uses
+[Configurability](https://rubygems.org/gems/configurability) to determine
+behavior.  The configuration is a [YAML](http://www.yaml.org/) file.  It
+shares AMQP configuration with Symphony, and adds metronome specific
+controls in the 'metronome' key.
+
+	metronome:
+		splay: 0
+		listen: true
+		db: sqlite:///tmp/metronome.db
+
+
+### splay
+
+Randomize all start times for actions by this many seconds on either
+side of the original execution time.  Defaults to none.
+
+### listen
+
+Start up an AMQP listener using Symphony configuration, for remote
+administration of schedule events.  Defaults to true.
+
+### db
+
+A [Sequel](https://rubygems.org/gems/sequel) connection URI.  Currently,
+Metronome is tested under SQLite and PostgreSQL.  Defaults to a SQLite
+file at /tmp/metronome.db.
+
+
+## Scheduling Examples
+
+Note that Metronome is designed as an interval scheduler, not a
+calendaring app.  It doesn't have any concepts around phrases like "next
+tuesday", or "the 3rd sunday after christmas".  If that's what you're
+after, check out the [chronic](http://rubygems.org/gems/chronic)
+library instead.
+
+Here are a small set of example expressions.  Feel free to use the
+*metronome-exp* utility to get a feel for what Metronome anticipates.
+
+```
+in 30.5 minutes
+once an hour
+every 15 minutes for 2 days
+at 2014-05-01
+at 2014-04-01 14:00:25
+at 2pm
+starting at 2pm once a day
+start in 1 hour from now run every 5 seconds end at 11:15pm
+every other hour
+run every 7th minute for a day
+once a day ending in 1 week
+run once a minute for an hour starting in 6 days
+10 times a minute for 2 days
+run 45 times every hour
+30 times per day
+start at 2010-01-02 run 12 times and end on 2010-01-03
+starting in an hour from now run 6 times a minute for 2 hours
+beginning a day from now, run 30 times per minute and finish in 2 weeks
+execute 12 times during the next 2 minutes
+once a minute beginning in 5 minutes
+```
+
+In general, you can use reasonably intuitive phrasings.  Capitalization,
+whitespace, and punctuation doesn't matter.  When describing numbers,
+use digit/integer form instead of words, ie: '1 hour' instead of 'one
+hour'.
+
+
+## Installation
+
+```
+gem install symphony-metronome
+```
+
+## Contributing
+
+You can check out the source via Fossil from the following uri:
+
+% fossil clone https://code.martini.nu/fossil/symphony-metronome
+
+or via its GitHub mirror at:
+
+% git clone https://github.com/mahlonsmith/Symphony-Metronome
+
+After checking out the source, run:
+
+    $ gem install -Ng
+    $ rake setup
+
+This will install dependencies, and do any other necessary setup for
+development.
+
+Please report any issues
+[here](https://code.martini.nu/fossil/symphony-metronome/tktnew).
+
+
+## Authors
+
+- Mahlon E. Smith <mahlon@martini.nu>
+
+
+## License
+
+Copyright (c) 2014-2023 Mahlon E. Smith
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/lib/symphony/metronome/intervalexpression.rb

@@ -1916,7 +1916,7 @@ self.interval_expression_en_main = 1;
 	### an expression was generated, you can 'reconstitute' an interval
 	### object this way.
 	###
-	def self::parse( exp, time=nil )
+	def self::parse( exp, time=Time.now )
 
 		# Normalize the expression before parsing
 		#
@@ -1927,7 +1927,7 @@ self.interval_expression_en_main = 1;
 			gsub( /([:\-])+/, '\1' ).                    # collapse multiple - or : chars
 			gsub( /\.+$/, '' )                           # trailing periods
 
-		event = new( exp, time || Time.now )
+		event = new( exp, time )
 		data  = event.instance_variable_get( :@data )
 
 		# Ragel interface variables

data/lib/symphony/metronome/scheduledevent.rb

@@ -21,19 +21,17 @@ class Symphony::Metronome::ScheduledEvent
 	config_key :metronome
 
 
-	# Configure defaults.
-	#
-	CONFIG_DEFAULTS = {
-		:db    => 'sqlite:///tmp/metronome.db',
-		:splay => 0
-	}
-
-	class << self
+	### Configurability API.
+	###
+	configurability do
+
+		##
 		# A Sequel-style DB connection URI.
-		attr_reader :db
+		setting :db, default: 'sqlite:///tmp/metronome.db'
 
+		##
 		# Adjust recurring intervals by a random window.
-		attr_reader :splay
+		setting :splay, default: 0
 	end
 
 
@@ -62,7 +60,6 @@ class Symphony::Metronome::ScheduledEvent
 	### Delete any rows that are invalid expressions.
 	###
 	def self::load
-		now    = Time.now
 		events = SortedSet.new
 
 		# Force reset the DB handle.

data/lib/symphony/metronome/scheduler.rb

@@ -17,22 +17,15 @@ class Symphony::Metronome::Scheduler
 	# Signals the daemon responds to.
 	SIGNALS = [ :HUP, :INT, :TERM ]
 
-	CONFIG_DEFAULTS = {
-		:listen => false
-	}
 
-	class << self
+	### Configurability API.
+	###
+	configurability do
+
 		# Should Metronome register and schedule events via AMQP?
 		# If +false+, you'll need a separate way to add event actions
 		# to the database, and manually HUP the daemon.
-		attr_reader :listen
-	end
-
-	### Configurability API
-	###
-	def self::configure( config=nil )
-		config = self.defaults.merge( config || {} )
-		@listen = config.delete( :listen )
+		setting :listen, default: false
 	end
 
 
@@ -131,17 +124,19 @@ class Symphony::Metronome::Scheduler
 	def process_events
 		now = Time.now
 
+		events_to_delete = []
+		events_to_add = []
 		self.queue.each do |ev|
 			next unless now >= ev.runtime
 
-			self.queue.delete( ev )
+			events_to_delete << ev
 			rv = ev.fire( &@proc )
 
 			# Reschedule the event and place it back on the queue.
 			#
 			if ev.event.recurring
 				ev.reset_runtime
-				self.queue.add( ev ) unless rv.nil?
+				events_to_add << ev unless rv.nil?
 
 			# It was a single run event, torch it!
 			#
@@ -150,6 +145,9 @@ class Symphony::Metronome::Scheduler
 
 			end
 		end
+
+		events_to_delete.map{|e| self.queue.delete( e ) }
+		events_to_add.map{|e| self.queue.add( e ) }
 	end
 
 end # Symphony::Metronome::Scheduler

data/lib/symphony/metronome.rb

@@ -9,10 +9,7 @@ module Symphony::Metronome
 	       Configurability
 
 	# Library version constant
-	VERSION = '0.2.1'
-
-	# Version-control revision constant
-	REVISION = %q$Revision: 87e45dca63b3 $
+	VERSION = '0.3.0'
 
 	# The name of the environment variable to check for config file overrides
 	CONFIG_ENV = 'METRONOME_CONFIG'
@@ -23,11 +20,11 @@ module Symphony::Metronome
 	# The data directory that contains migration files.
 	#
 	DATADIR = if ENV['METRONOME_DATADIR']
-				   Pathname.new( ENV['METRONOME_DATADIR'] )
-			   elsif Gem.datadir( 'symphony-metronome' )
-				   Pathname.new( Gem.datadir('symphony-metronome') )
+				   Pathname( ENV['METRONOME_DATADIR'] )
+			   elsif Gem.loaded_specs[ 'symphony-metronome' ] && File.exist?( Gem.loaded_specs['symphony-metronome'].datadir )
+				   Pathname( Gem.loaded_specs['symphony-metronome'].datadir )
 			   else
-				   Pathname.new( __FILE__ ).dirname.parent.parent + 'data/symphony-metronome'
+				   Pathname( __FILE__ ).dirname.parent.parent + 'data/symphony-metronome'
 			   end