activejob-status 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8a41508ce07744c1b0372a313f3d47a981986145423b5ded100bd1f39b3b37d
-  data.tar.gz: 6dea6ede3e4f251a637ecf5ff7dc1c824145fb7bd2a55edb4f38bfed409f74fe
+  metadata.gz: fa875564067c50989a462e58c7dc6cda721f9c737d90555842a45ff45c26a39a
+  data.tar.gz: 4275fd985ad9007cbbb841bee0e6a6f3eace42baacb4609ecedbc04883388bf9
 SHA512:
-  metadata.gz: 4eab47f16733e16c9006ce3dff76d239ffdf2932e47bcd8eafe30c953d1131292f9fee1f4298f5f642461394f4cb7f1f41407fa8d922a4b1486a34a71f7e32f1
-  data.tar.gz: 9fb5a5f0fc42f5c90b1a8839b856317a7f7544555dfda2e94798ad08fefeb223491b15743af8dcb3df0659351f072f27aaabfc04f7ee82a8ed5b60d56ed2b6fc
+  metadata.gz: 004c5a2e04dc3f780a97737531becd4baeee68d453283d07e6826c4712a54e9cbec151500e7c1dd8cf0e1561b9e319668ae469989999769bedd2d256ffb16af9
+  data.tar.gz: 4f6e55367525b445d13b2b524f55913cc57cf871dc4407001ce32cc8e0a4ee92b8fc28284471fe0525f77a2782afb505cbc14a13f53d4026ba56eb3b40180972

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2023 Savater Sebastien
+
+MIT License
+
+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,420 @@
+# ActiveJob::Status
+
+Simple monitoring status for ActiveJob, independent of your queuing backend or cache storage.
+
+[![Gem Version](https://badge.fury.io/rb/activejob-status.svg)](https://rubygems.org/gems/activejob-status)
+[![CI Status](https://github.com/inkstak/activejob-status/actions/workflows/ci.yml/badge.svg)](https://github.com/inkstak/activejob-status/actions/workflows/ci.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+[![Maintainability](https://api.codeclimate.com/v1/badges/a7b1ec1d3769e49021fd/maintainability)](https://codeclimate.com/github/inkstak/activejob-status/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/a7b1ec1d3769e49021fd/test_coverage)](https://codeclimate.com/github/inkstak/activejob-status/test_coverage)
+
+## Installation
+
+```bash
+gem install activejob-status
+```
+or
+```bash
+bundle add activejob-status
+```
+
+## Dependencies
+
+This is a legacy branch of `ActiveJob::Status` to support [EOL versions](https://endoflife.date/rails) of `ActiveJob` & `ActiveSupport`.
+
+This version works with `ActiveSupport >= 5.0` but requires `ruby < 3.0`.
+
+
+## Configuration
+
+### Cache Store
+
+By default, ActiveJob::Status use the <code>Rails.cache</code> to store data.
+You can use any compatible ActiveSupport::Cache::Store you want (memory, memcache, redis, ..)
+or any storage responding to <code>read/write/delete</code>
+
+> **Note** : `Rails.cache` defaults to  `ActiveSupport::Cache::NullStore` which will result in empty status.
+Setting a cache store for ActiveJob::Status is therefore mandatory.
+
+You can set your own store:
+
+```ruby
+# config/initializers/activejob_status.rb
+
+# Use an alternative cache store:
+#   ActiveJob::Status.store = :file_store, "/path/to/cache/directory"
+#   ActiveJob::Status.store = :redis_cache_store, { url: ENV['REDIS_URL'] }
+#   ActiveJob::Status.store = :mem_cache_store
+#
+# You should avoid using cache store that are not shared between web and background processes
+# (ex: :memory_store).
+#
+if Rails.cache.is_a?(ActiveSupport::Cache::NullStore)
+  ActiveJob::Status.store = :mem_cache_store
+end
+```
+
+### Select data to store by default
+
+By default, ActiveJob::Status already stores a status key at each step of a job's life cycle.  
+To understand what data are stored and what data to add, see [Data stored by default](#data-stored-by-default).
+
+> **Warning** : adding more data means more memory consumed.  
+> For example, adding `:serialized_job` might require as much memory for caching as your use for your job backend.
+
+```ruby
+# config/initializers/activejob_status.rb
+
+# Select what data you want to store.
+# Available options are: :status, :serialized_job, :exception
+# Default is [:status]
+#
+ActiveJob::Status.options = { includes: %i[status exception] }
+```
+
+### Expiration time
+
+Because ActiveJob::Status relies on cache store, all statuses come with an expiration time.  
+It's set to 1 hour by default.
+
+You can set a longer expiration:
+
+```ruby
+# config/initializers/activejob_status.rb
+
+# Set your own status expiration time:
+# Default is 1 hour.
+#
+ActiveJob::Status.options = { expires_in: 30.days.to_i }
+```
+
+### Throttling
+
+Depending on the cache storage latency, updating a status too often can cause bottlenecks.  
+To narrow this effect, you can force a time interval between each updates:
+
+```ruby
+# config/initializers/activejob_status.rb
+
+# Apply a time interval in seconds between every status updates.
+# Default is 0 - no throttling mechanism
+#
+ActiveJob::Status.options = { throttle_interval: 0.1 }
+```
+
+
+## Usage
+
+### Updating status
+
+Include the <code>ActiveJob::Status</code> module in your jobs.
+
+```ruby
+class MyJob < ActiveJob::Base
+  include ActiveJob::Status
+end
+```
+
+The module introduces two methods:
+
+* <code>progress</code> to implement a progress status
+
+```ruby
+class MyJob < ActiveJob::Base
+  include ActiveJob::Status
+
+  def perform
+    progress.total = 1000
+
+    1000.time do
+      # ...do something...
+      progress.increment
+    end
+  end
+end
+```
+
+* <code>status</code> to directly read/update status
+
+```ruby
+class MyJob < ActiveJob::Base
+  include ActiveJob::Status
+
+  def perform
+    status[:step] = "A"
+
+    # ...do something...
+
+    status[:step]   = "B"
+    status[:result] = "...."
+  end
+end
+```
+
+You can combine both to update status and progress in a single call.
+
+```ruby
+class MyJob < ActiveJob::Base
+  include ActiveJob::Status
+
+  def perform
+    status.update(step: "A", total: 100)
+    
+    100.times do
+      # ...do something...
+      progress.increment
+    end
+
+    # Reset the progress for the next step
+    status.update(step: "B", total: 50, progress: 0)
+
+    50.times do
+      # ...do something...
+      progress.increment
+    end
+  end
+end
+```
+
+Throttling mechanism (see configuration) is applied when doing:
+
+```ruby
+progress.increment
+progress.decrement
+status.update(foo: 'bar')
+```
+
+Throttling mechanism is not applied when doing:
+
+```ruby
+progress.total    = 100
+progress.progress = 0
+progress.finish
+status[:foo]      = 'bar'
+status.update({ foo: 'bar' }, force: true)
+```
+
+### Data stored by default
+
+By default, ActiveJob::Status stores a status key.   
+You can add more information about the job using `includes` config.  
+
+Setting `ActiveJob::Status.options = { includes: %i[status] }` is equivalent to:
+
+```ruby
+before_enqueue { |job| job.status[:status] = :queued }
+before_perform { |job| job.status[:status] = :working }
+after_perform { |job| job.status[:status] = :completed }
+
+rescue_from(Exception) do |e|
+  status[:status] = :failed
+  raise e
+end
+```
+
+Setting `ActiveJob::Status.options = { includes: %i[serialized_job] }` is equivalent to:
+
+```ruby
+before_enqueue { |job| job.status[:serialized_job] = job.serialize }
+```
+
+Setting `ActiveJob::Status.options = { includes: %i[exception] }` is equivalent to:
+
+```ruby
+rescue_from(Exception) do |e|
+  status[:exception] = { class: e.class, message: e.message }
+  raise e
+end
+```
+
+### Reading status
+
+Check the status of a job
+
+```ruby
+job    = MyJob.perform_later
+status = ActiveJob::Status.get(job)
+# => { status: :queued }
+```
+
+You can also use the job_id
+
+```ruby
+status = ActiveJob::Status.get('d11b64e6-8631-4118-ae76-e19376769171')
+# => { status: :queued }
+```
+
+Follow the progression of your job
+
+```ruby
+loop do
+  puts status
+  break if status.completed?
+end
+
+# => { status: :queued }
+# => { status: :working, progress: 0, total: 100, step: "A" }
+# => { status: :working, progress: 60, total: 100, step: "A" }
+# => { status: :working, progress: 90, total: 100, step: "A" }
+# => { status: :working, progress: 0, total: 50, step: "B" }
+# => { status: :completed, progress: 50, total: 50, step: "B" }
+```
+
+The status provides you getters:
+
+```ruby
+status.status     # => "working"
+status.queued?    # => false
+status.working?   # => true
+status.completed? # => false
+status.failed?    # => false
+status.progress   # => 0.5 (progress / total)
+status[:step]     # => "A"
+```
+
+... until it's completed
+
+```ruby
+status.status     # => "completed"
+status.completed? # => true
+status.progress   # => 1
+```
+
+### Serializing status to JSON
+
+Within a controller, you can serialize a status to JSON:
+
+```ruby
+class JobsController
+  def show
+    status = ActiveJob::Status.get(params[:id])
+    render json: status.to_json
+  end
+end
+```
+
+```
+GET /jobs/status/d11b64e6-8631-4118-ae76-e19376769171.json
+
+{
+  "status":   "working",
+  "progress": 50
+  "total":    100,
+  "step":     "A"
+}
+```
+
+### Setting options per job
+
+You can override default options per job:
+
+```ruby
+class MyJob < ActiveJob::Base
+  include ActiveJob::Status
+
+  def status
+    @status ||= ActiveJob::Status::Status.new(self,
+      expires_in: 3.days,
+      throttle_interval: 0.5,
+      includes: %i[status serialized_job])
+  end
+
+  def perform
+    ...
+  end
+end
+```
+
+## ActiveJob::Status and exceptions
+
+Internally, ActiveJob::Status uses `ActiveSupport#rescue_from` to catch every `Exception` to apply the `failed` status
+before throwing the exception again.
+
+[Rails](https://api.rubyonrails.org/classes/ActiveSupport/Rescuable/ClassMethods.html#method-i-rescue_from) says:
+> Handlers are inherited. They are searched from right to left, from bottom to top, and up the hierarchy. The handler of
+the first class for which exception.is_a?(klass) holds true is the one invoked, if any.
+
+Thus, there are a few points to consider when using `rescue_from`:
+
+1 - Do not declare `rescue_from` handlers before including `ActiveJob::Status`. They cannot be called:
+
+```ruby
+class ApplicationJob < ActiveJob::Base
+  rescue_from Exception do |e|
+    ExceptionMonitoring.notify(e)
+    raise e
+  end
+end
+
+class MyJob < ApplicationJob
+  # The rescue handlers from ApplicationJob won't ever be executed
+  # and the exception monitoring won't be notified.
+
+  include ActiveJob::Status
+end
+```
+
+2 - If you're rescuing any or all exceptions, the status will never be set to `failed`. You need to update it by
+yourself:
+
+```ruby
+class ApplicationJob < ActiveJob::Base
+  include ActiveJob::Status
+
+  rescue_from Exception do |e|
+    ExceptionMonitoring.notify(e)
+    status.catch_exception(e)
+    raise e
+  end
+end
+```
+
+3 - Subsequent handlers will stop the rescuing mechanism:
+
+```ruby
+class MyJob < ApplicationJob
+  # With the exceptions handled below:
+  # - the monitor won't be notified
+  # - the job status will remains to `working`
+
+  retry_on    'SomeTimeoutError', wait: 5.seconds
+  discard_on  'DeserializationError'
+  rescue_from 'AnotherCustomException' do |e|
+    do_something_else
+  end
+end
+```
+
+## Contributing
+
+1. Don't hesitate to submit your feature/idea/fix in [issues](https://github.com/inkstak/activejob-status)
+2. Fork the [repository](https://github.com/inkstak/activejob-status)
+3. Create your feature branch
+4. Ensure RSpec & Rubocop are passing
+4. Create a pull request
+
+### Tests & lint
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+bundle exec standardrb
+```
+
+All of them can be run with:
+
+```bash
+bundle exec rake
+```
+
+To run test suite against various version of Rails dependencies:
+```bash
+bundle exec appraisal install
+bundle exec appraisal
+```
+
+## License & credits
+
+Please see [LICENSE](https://github.com/inkstak/coverart/blob/main/LICENSE) for further details.
+
+Contributors: [./graphs/contributors](https://github.com/inkstak/coverart/graphs/contributors)

data/lib/activejob-status/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveJob
   module Status
-    VERSION = "0.4.1"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activejob-status
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Savater Sebastien
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-30 00:00:00.000000000 Z
+date: 2023-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -16,35 +16,188 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description:
-email:
-- savater.sebastien@gmail.com
+email: github.60k5k@simplelogin.co
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - lib/activejob-status.rb
 - lib/activejob-status/progress.rb
 - lib/activejob-status/status.rb
@@ -61,16 +214,16 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "<"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: Monitor your jobs