active_job_metadata 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 843028f1e40916f667c6bae2fa228919eb0ed5d3
+  data.tar.gz: 068b6ec80c5f3560a907d3fa609fa4b6408482a5
+SHA512:
+  metadata.gz: 2fe763b81691b7fa827e4dd41b2a37185a13d65205f4b9a03057d789600780f0925a50f21adf1004afce8b41071c1304c0e60284332e6f817cdeac6c9cc9a416
+  data.tar.gz: 25ef63615d7e34c1b91bca5d5baeb37e792ad729d4ae7a3275f7b29770d680bc84d10a5408c377c05a4a7a0ebe9ea6198eaa2c0393d55878056295f94ef1756e

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.3
+before_install: gem install bundler -v 1.10.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in active_job_metadata.gemspec
+gemspec

data/README.md

@@ -0,0 +1,128 @@
+# ActiveJobMetadata
+
+ActiveJobMetadata lets you store and retrieve metadata associated with ActiveJob jobs regardless of the queue processing library you use.
+
+Primary use cases include:
+
+- Providing job status clients
+- Tracking job performance
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_job_metadata'
+```
+
+## Usage
+
+You can use as much or as little of ActiveJobMetadata as you need.
+
+Use **Lifecyle** to track the current status of your job:
+
+    class MyJob < ActiveJob::Base
+      include ActiveJobMetadata::Lifecycle
+      
+      def perform
+        #...
+      end
+    end
+    
+    job = MyJob.new
+    job.enque
+    job.status #=> "enqueued"
+    ActiveJobMetadata.find(job.job_id) #=> {status: "enqueued"}
+
+You can use this in RESTful controllers to let clients query for a job's status:    
+
+    class JobsController
+      def create
+        job = MyJob.new
+        job.enque
+        
+        render json: {id: job.job_id}
+      end
+      
+      def show
+        metadata = ActiveJobMetadata.find(params[:id])
+        
+        if metadata
+          render json: metadata
+        else
+          render json: {message: "Not Found"}, status: 404
+        end
+      end
+    end
+    
+Use the **Timing** module to track and report on execution times:
+
+    class TimedJob < ActiveJob::Base
+      include ActiveJobMetadata::Timing
+      after_peform :report_timing
+      
+      def perform
+        #...
+      end
+      
+      def report_timing
+        Rails.logger.info "Queue Duration: #{queue_duration}"
+        Rails.logger.info "Processing Duration: #{working_duration}"
+        Rails.logger.info "Total Duration: #{total_duration}"
+      end
+    end
+
+Of course you could hook this up to [statsd](https://github.com/reinh/statsd), or any other place you collect metrics.
+
+Use the **Metadata** module to track custom information.  For instance a long running job might report the percent complete and the name of the last file it processed:
+
+    class LongRunningJob < ActiveJob::Base
+      include ActiveJobMetadata::Metadata
+      metadata :percent_complete, :current_file
+      
+      def perform(files)
+        files.each_with_index do |file, i|
+          self.percent_complete = (files.length / i.to_f)
+          self.current_file = file
+          
+          IO.open(file) do |io|
+            #...
+          end
+        end
+      end
+      
+    end
+
+Use this approach to enrich metadata you send back to your client.
+
+## Configuration
+
+Although ActiveJobMetadata should mostly work out of the box in a development environment, you will probably want to customize the backing store.  ActiveJobMetadata reads and writes to an [ActiveSupport::Cache::Store](http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html).  If you use more than one web server, which is likely, you will probably want to use something like [Readthis](https://github.com/sorentwo/readthis) which provides a shared interface via Redis.  If you want to use a different backend for ActiveJobMetadata than Rails, create an initializer with your custom store:
+
+    # initializers/active_job_metadata.rb
+    
+    # Configure ActiveJobMetadata to use Readthis:
+    ActiveJobMetadata.store = Readthis::Cache.new(
+      expires_in: 2.days.to_i
+    )
+
+Currently ActiveJobMetadata only uses the `read` and `write` methods, so you can easily store your metadata wherever all your servers can easily access it if you don't mind implementing something that quacks like a [ActiveSupport::Cache::Store](http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html).
+
+## Alternatives
+
+It is always wise to consider your alternatives:
+
+* [active_job_status](https://github.com/cdale77/active_job_status)
+* [resque-status](https://github.com/quirkey/resque-status) for Resque
+* [sidekiq-status](https://github.com/utgarda/sidekiq-status) for Sidekiq
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/adamsanderson/active_job_metadata.
+

data/Rakefile

@@ -0,0 +1,14 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  
+  # Disable warnings to avoid circular load warnings in dependencies
+  t.warning = false
+  
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/active_job_metadata.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'active_job_metadata/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "active_job_metadata"
+  spec.version       = ActiveJobMetadata::VERSION
+  spec.authors       = ["adam sanderson"]
+  spec.email         = ["netghost@gmail.com"]
+
+  spec.summary       = "Store status and metadata for ActiveJobs"
+  spec.description   = "ActiveJobMetadata lets you store and retrieve metadata associated with ActiveJob jobs regardless of the queue processing library you use."
+  spec.homepage      = "https://github.com/adamsanderson/active_job_metadata"
+  
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  
+  spec.add_dependency "activejob",      ">= 4.2", "< 5.1"
+  spec.add_dependency "activesupport",  ">= 4.2", "< 5.1"
+  
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 11.0"
+  spec.add_development_dependency "minitest", "~> 5.9"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "active_job_metadata"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/active_job_metadata.rb

@@ -0,0 +1,54 @@
+require "active_job_metadata/version"
+require "active_support"
+
+module ActiveJobMetadata
+
+  # Prefix used by ActiveJobMetadata for finding and setting metadata
+  # by job id.
+  mattr_accessor(:prefix) do
+    "ActiveJobMetadata"
+  end
+  
+  # ActiveSupport::Cache::Store used to save metadata.  By default this uses the Rails cache,
+  # though you may want to use a special store if metadata is likely to fall out of the cache.
+  # 
+  # Consider adjusting the retention policies to be long enough to last the total lifetime of
+  # a job plus some time afterwards if client code may check it at a later date.
+  mattr_accessor(:store) do
+    Rails.cache if defined? Rails
+  end
+  
+  # Same as find, but will raise an ActiveJobMetadata::MetadataNotFound exception if 
+  # the job's metadata is not found.
+  def self.find!(job_id)
+    find(job_id) || raise(MetadataNotFound.new("Could not find metadata: #{job_id.inspect}"))
+  end
+  
+  # Finds a job's metadata, otherwise returns nil.  Note that depending on how your store is
+  # configured, metadata may not always be available.  For instance, if your store is configured
+  # to expire data after one day, then that metadata will no longer be available.
+  def self.find(job_id)
+    metadata_key = self.key(job_id)
+    store.read(metadata_key)
+  end
+  
+  # Writes metadata for a job directly to the cache.  Typically you should use accessors defined
+  # via `metadata` on a class.  See ActiveJobMetadata::Metdadata for more information.
+  def self.write(job_id, metadata)
+    metadata_key = self.key(job_id)
+    store.write(metadata_key, metadata)
+  end
+  
+  # Generates a key for a given job id.  You generally shouldn't need this.
+  def self.key(job_id)
+    "#{ActiveJobMetadata.prefix}-#{job_id}"
+  end
+  
+  class MetadataNotFound < StandardError
+  end
+end
+
+require "active_job_metadata/metadata"
+require "active_job_metadata/lifecycle"
+require "active_job_metadata/timing"
+require "active_job_metadata/all"

data/lib/active_job_metadata/all.rb

@@ -0,0 +1,7 @@
+module ActiveJobMetadata::All
+  extend ActiveSupport::Concern
+  
+  include ActiveJobMetadata::Metadata
+  include ActiveJobMetadata::Lifecycle
+  include ActiveJobMetadata::Timing
+end

data/lib/active_job_metadata/lifecycle.rb

@@ -0,0 +1,19 @@
+# Use Lifecyle to track the current status of your job.
+# 
+module ActiveJobMetadata::Lifecycle
+  ENQUEUED = "enqueued"
+  RUNNING  = "running"
+  DONE     = "done"
+  
+  extend ActiveSupport::Concern
+  include ActiveJobMetadata::Metadata
+  
+  included do
+    metadata :status
+    
+    after_enqueue   { self.status = "enqueued" }
+    before_perform  { self.status = "running"  }
+    after_perform   { self.status = "done"     }
+  end
+  
+end

data/lib/active_job_metadata/metadata.rb

@@ -0,0 +1,58 @@
+# Use Metadata to define custom metadata for your job.
+# 
+module ActiveJobMetadata::Metadata
+  extend ActiveSupport::Concern
+  
+  included do
+    # No-op
+  end
+  
+  class_methods do
+    
+    # Defines metadata accessors for each specified attribute.
+    # 
+    #     class LongRunningJob < ActiveJob::Base
+    #       include ActiveJobMetadata::Metadata
+    #       metadata :percent_complete, :current_file
+    #     end
+    #     
+    #     job = LongRunningJob.new
+    #     job.percent_complete = 80
+    #     job.metadata #=> {percent_complete: 80}
+    # 
+    def metadata *names
+      names.each do |name|
+        
+        define_method(name) do
+          self.metadata[name.to_sym]
+        end
+        
+        define_method("#{name}=") do |value|
+          self.metadata[name.to_sym] = value
+          save_metadata
+          value
+        end
+        
+      end
+    end
+  end
+  
+  # Returns all metadata for the current job.
+  def metadata
+    @metadata ||= ActiveJobMetadata.find(job_id) || {}
+  end
+  
+  # Merges data into the current job's metdata.
+  def metadata= hash
+    metadata.merge!(hash)
+    save_metadata
+  end
+  
+  # Writes metadata to `ActiveJobMetadata.store`
+  def save_metadata
+    ActiveJobMetadata.write(job_id, metadata)
+    
+    metadata
+  end
+  
+end

data/lib/active_job_metadata/timing.rb

@@ -0,0 +1,44 @@
+# Use Timing to track and report on execution times.
+# 
+module ActiveJobMetadata::Timing
+  extend ActiveSupport::Concern
+  include ActiveJobMetadata::Metadata
+  
+  included do
+    metadata :enqueued_at
+    metadata :started_at
+    metadata :done_at
+    
+    after_enqueue   { self.enqueued_at = Time.now }
+    before_perform  { self.started_at = Time.now  }
+    after_perform   { self.done_at = Time.now     }
+  end
+  
+  # The queue duration is the time in seconds a job spent in the queue before
+  # it was processed.  If it has not been enqueued or processing
+  # has not yet begun, it will return nil.
+  def queue_duration
+    return nil unless enqueued_at && started_at
+    started_at - enqueued_at
+  end
+  
+  # The working duration is the time in seconds a job spent in the process
+  # method.  If process has not yet been called, or process has not finished
+  # it will return nil.
+  def working_duration
+    return nil unless done_at && started_at
+    done_at - started_at
+  end
+  
+  # The total duration is the sum of the queue and working duration.  This
+  # gives a measure of how long it took from enqueuing the job to completing
+  # all processing.
+  def total_duration
+    q = queue_duration
+    w = working_duration
+    return nil unless q && w
+    
+    queue_duration + working_duration
+  end
+  
+end

data/lib/active_job_metadata/version.rb

@@ -0,0 +1,3 @@
+module ActiveJobMetadata
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: active_job_metadata
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- adam sanderson
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-09-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.9'
+description: ActiveJobMetadata lets you store and retrieve metadata associated with
+  ActiveJob jobs regardless of the queue processing library you use.
+email:
+- netghost@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- active_job_metadata.gemspec
+- bin/console
+- bin/setup
+- lib/active_job_metadata.rb
+- lib/active_job_metadata/all.rb
+- lib/active_job_metadata/lifecycle.rb
+- lib/active_job_metadata/metadata.rb
+- lib/active_job_metadata/timing.rb
+- lib/active_job_metadata/version.rb
+homepage: https://github.com/adamsanderson/active_job_metadata
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Store status and metadata for ActiveJobs
+test_files: []