active_job_store 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 913b4d81b0dfb938f013f907696dc04354a106818140d25003ae44ab4e4ed9f9
-  data.tar.gz: 39874892b9ee2443311d54cfedf7589697959c5ccb4184d8d934d67960838c7d
+  metadata.gz: 0ef6d562f0f4a15a496ba433ec3c540e141936afb70c25c49d733989c5244662
+  data.tar.gz: bb6790c404ed7aecfc16a54838a01a25d366221e23898cb9bd52e73b2311de9e
 SHA512:
-  metadata.gz: 18b9c5696a4b4092ae9ea5d6ae8ed74ed45aaef567804f53a7b59fee306038f6ce2e63f0832b9bdc6f6ad61dbb7d69b81239c5801fe39db2b163be50f0e468ad
-  data.tar.gz: 0ad46829f63b6a6347812df19f0b0a3ef8b9e0c092ecf6f8f1743b08ddfeef9077735cdcb19690421222ca9557b2c6338b9e122d7e747f76a50d3357d62e3534
+  metadata.gz: 5a88f03f2af219714771a7d9dcf320e72d99753f4327ce7f1c699ef8f0132bf62d124872e83ae2be589d88afba4f06aaecdc9506fc13cfe87b36e0777b46c4a3
+  data.tar.gz: b2544a3499f8a0d3a18b34fee58e171ef37cc3402890e1790746c75b97a6f22c236582185769738301aca986afa05e44fa27645a76a75f95480368dbee376aaf

data/README.md

@@ -7,14 +7,13 @@
 Persist job execution information on a support model `ActiveJobStore::Record`.
 
 It can be useful to:
-- improve jobs logging capabilities;
-- query historical data about job executions;
-- extract job's statistical data;
-- track a job's state / set progress value / add custom data to the jobs.
+- store the job's state / set progress value / add custom data to the jobs;
+- query historical data about job executions / extract job's statistical data;
+- improve jobs' logging capabilities.
 
-Support some customizations:
-- set custom data attributes (via `active_job_store_custom_data` accessor);
-- format the job result to store (overriding `active_job_store_format_result` method).
+By default gem's internal errors are sent to stderr without compromising the job's perform.
+
+Please ⭐ if you like it.
 
 ## Installation
 
@@ -24,6 +23,20 @@ Support some customizations:
 - Add to your job `include ActiveJobStore` (or to your `ApplicationJob` class if you prefer)
 - Access to the job executions data using the class method `job_executions` on your job (ex. `YourJob.job_executions`)
 
+## API
+
+attr_accessor on the jobs:
+- `active_job_store_custom_data`: to set / manipulate job's custom data
+
+Instance methods on the jobs:
+- `active_job_store_format_result(result) => result2`: to format / manipulate / serialize the job result
+- `active_job_store_internal_error(context, exception)`: handler for internal errors
+- `active_job_store_record => store record`: returns the store's record
+- `save_job_custom_data(custom_data = nil)`: to persist custom data while the job is performing
+
+Class methods on the jobs:
+- `job_executions => relation`: query the list of job executions for the specific job class (returns an ActiveRecord Relation)
+
 ## Usage examples
 
 ```rb
@@ -48,18 +61,6 @@ SomeJob.job_executions.first
 #  created_at: Wed, 09 Nov 2022 21:09:50.611900000 UTC +00:00>
 ```
 
-Extract some logs:
-
-```rb
-puts ::ActiveJobStore::Record.order(id: :desc).pluck(:created_at, :job_class, :arguments, :state, :completed_at).map { _1.join(', ') }
-# 2022-11-09 21:20:57 UTC, SomeJob, 123, completed, 2022-11-09 21:20:58 UTC
-# 2022-11-09 21:18:26 UTC, AnotherJob, another test 2, completed, 2022-11-09 21:18:26 UTC
-# 2022-11-09 21:13:18 UTC, SomeJob, Some test 3, completed, 2022-11-09 21:13:19 UTC
-# 2022-11-09 21:12:18 UTC, SomeJob, Some test 2, error,
-# 2022-11-09 21:10:13 UTC, AnotherJob, another test, completed, 2022-11-09 21:10:13 UTC
-# 2022-11-09 21:09:50 UTC, SomeJob, Some test, completed, 2022-11-09 21:09:50 UTC
-```
-
 Query jobs in a specific range of time:
 
 ```rb
@@ -77,9 +78,36 @@ SomeJob.job_executions.completed.map { |job| { id: job.id, execution_time: job.c
 #  {:id=>1, :execution_time=>0.011442, :started_at=>Wed, 09 Nov 2022 21:09:50.611355000 UTC +00:00}]
 ```
 
-## Customizations
+Extract some logs:
 
-To store the custom data (ex. a progress value):
+```rb
+puts ::ActiveJobStore::Record.order(id: :desc).pluck(:created_at, :job_class, :arguments, :state, :completed_at).map { _1.join(', ') }
+# 2022-11-09 21:20:57 UTC, SomeJob, 123, completed, 2022-11-09 21:20:58 UTC
+# 2022-11-09 21:18:26 UTC, AnotherJob, another test 2, completed, 2022-11-09 21:18:26 UTC
+# 2022-11-09 21:13:18 UTC, SomeJob, Some test 3, completed, 2022-11-09 21:13:19 UTC
+# 2022-11-09 21:12:18 UTC, SomeJob, Some test 2, error,
+# 2022-11-09 21:10:13 UTC, AnotherJob, another test, completed, 2022-11-09 21:10:13 UTC
+# 2022-11-09 21:09:50 UTC, SomeJob, Some test, completed, 2022-11-09 21:09:50 UTC
+```
+
+Query information from a job (even while performing):
+
+```rb
+job = SomeJob.perform_later 123
+job.active_job_store_record.slice(:job_id, :job_class, :arguments)
+# => {"job_id"=>"b009f7c7-a264-4fb5-a1f8-68a8141f323b", "job_class"=>"SomeJob", "arguments"=>[123]}
+
+job = AnotherJob.perform_later 456
+job.active_job_store_record.custom_data
+# => {"progress"=>0.5}
+### After a while:
+job.active_job_store_record.reload.custom_data
+# => {"progress"=>1.0}
+```
+
+## Features' examples
+
+To persist some custom data during the perform (ex. a progress value):
 
 ```rb
 class AnotherJob < ApplicationJob
@@ -100,7 +128,7 @@ AnotherJob.perform_later(456)
 AnotherJob.job_executions.last.custom_data['progress'] # 1.0 (at the end)
 ```
 
-If you need to manipulate the custom data, there is the `active_job_store_custom_data` accessor:
+To manipulate the custom data persisted only at the end:
 
 ```rb
 class AnotherJob < ApplicationJob
@@ -123,7 +151,7 @@ AnotherJob.job_executions.last.custom_data
 # => [{"time"=>"2022-11-09T21:20:57.580Z", "message"=>"SomeJob step 1"}, {"time"=>"2022-11-09T21:20:58.581Z", "message"=>"SomeJob step 2"}]
 ```
 
-If for any reason it's needed to process the result before storing it, just override `active_job_store_format_result`:
+To process the job's result before storing it (ex. for serialization):
 
 ```rb
 class AnotherJob < ApplicationJob
@@ -144,6 +172,21 @@ AnotherJob.job_executions.last.result
 # => 84
 ```
 
+To raise an exception also when there is a gem's internal error:
+
+```rb
+class AnotherJob < ApplicationJob
+  include ActiveJobStore
+
+  # ...
+
+  def active_job_store_internal_error(context, exception)
+    raise exception
+    # Or simply monitor these errors using services like Sentry/Honeybadger/etc.
+  end
+end
+```
+
 ## Do you like it? Star it!
 
 If you use this component just star it. A developer is more motivated to improve a project when there is some interest.

data/lib/active_job_store/store.rb

@@ -6,55 +6,101 @@ module ActiveJobStore
 
     attr_reader :record
 
+    def around_enqueue(job)
+      prepare_record_on_enqueue(job)
+      lock_record!
+      result = yield
+      job_enqueued!
+      job.active_job_store_internal_error('ActiveJobStore::Store around_enqueue', internal_error) if internal_error
+      result
+    end
+
+    def around_perform(job)
+      prepare_record_on_perform(job)
+      job_started!
+      result = yield
+      formatted_result = job.active_job_store_format_result(result)
+      job_competed!(custom_data: job.active_job_store_custom_data, result: formatted_result)
+      job.active_job_store_internal_error('ActiveJobStore::Store around_perform', internal_error) if internal_error
+      result
+    rescue StandardError => e
+      job_failed!(exception: e, custom_data: job.active_job_store_custom_data)
+      raise
+    end
+
+    def update_job_custom_data(custom_data)
+      wrap_errors do
+        record.update!(custom_data: custom_data)
+      end
+    end
+
+    private
+
+    attr_accessor :internal_error
+
     def job_competed!(result:, custom_data:)
-      record.update!(state: :completed, completed_at: Time.current, result: result, custom_data: custom_data)
-      record
+      wrap_errors do
+        record.update!(state: :completed, completed_at: Time.current, result: result, custom_data: custom_data)
+      end
     end
 
     def job_enqueued!
-      record.lock! # NOTE: needed to avoid update conflicts with perform when setting the state to enqueued
-      yield
-      record.update!(state: :enqueued, enqueued_at: Time.current)
-      record
+      wrap_errors do
+        record.update!(state: :enqueued, enqueued_at: Time.current)
+      end
     end
 
     def job_failed!(exception:, custom_data:)
-      record.update!(state: :error, exception: exception.inspect, custom_data: custom_data)
-      record
+      wrap_errors do
+        record.update!(state: :error, exception: exception.inspect, custom_data: custom_data)
+      end
     end
 
     def job_started!
-      record.update!(state: :started, started_at: Time.current)
-      record
+      wrap_errors do
+        record.update!(state: :started, started_at: Time.current)
+      end
     end
 
-    def prepare_record_on_enqueue(job)
-      @record = ::ActiveJobStore::Record.find_or_create_by!(record_reference(job)) do |record|
-        record.arguments = job.arguments
-        record.details = DETAILS_ATTRS.zip(DETAILS_ATTRS.map { job.send(_1) }).to_h
-        record.state = :initialized
+    def lock_record!
+      wrap_errors do
+        record.lock! # NOTE: needed to avoid update conflicts with perform when setting the state to enqueued
       end
     end
 
-    def prepare_record_on_perform(job)
-      @record = ::ActiveJobStore::Record.find_or_initialize_by(record_reference(job)) do |record|
-        record.arguments = job.arguments
+    def prepare_record_on_enqueue(job)
+      wrap_errors do
+        @record = ::ActiveJobStore::Record.find_or_create_by!(record_reference(job)) do |record|
+          record.arguments = job.arguments
+          record.details = DETAILS_ATTRS.zip(DETAILS_ATTRS.map { job.send(_1) }).to_h
+          record.state = :initialized
+        end
       end
-      record.details = DETAILS_ATTRS.zip(DETAILS_ATTRS.map { job.send(_1) }).to_h
-      record
     end
 
-    def update_job_custom_data(custom_data)
-      record.update!(custom_data: custom_data)
+    def prepare_record_on_perform(job)
+      wrap_errors do
+        @record = ::ActiveJobStore::Record.find_or_initialize_by(record_reference(job)) do |record|
+          record.arguments = job.arguments
+        end
+        record.details = DETAILS_ATTRS.zip(DETAILS_ATTRS.map { job.send(_1) }).to_h
+        record
+      end
     end
 
-    private
-
     def record_reference(job)
       {
         job_id: job.job_id,
         job_class: job.class.to_s
       }
     end
+
+    def wrap_errors
+      return if internal_error
+
+      yield
+    rescue StandardError => e
+      self.internal_error = e
+    end
   end
 end

data/lib/active_job_store/version.rb

@@ -2,6 +2,6 @@
 
 # :nocov:
 module ActiveJobStore
-  VERSION = '0.2.0'
+  VERSION = '0.4.0'
 end
 # :nocov:

data/lib/active_job_store.rb

@@ -4,47 +4,63 @@ require_relative 'active_job_store/engine'
 require_relative 'active_job_store/store'
 
 module ActiveJobStore
+  # Set / manipulate job's custom data
   attr_accessor :active_job_store_custom_data
 
-  class << self
-    def included(base)
-      base.extend(ClassMethods)
-
-      base.around_enqueue do |job, block|
-        store.prepare_record_on_enqueue(job)
-        store.job_enqueued! do
-          block.call
-        end
-      end
-
-      base.around_perform do |job, block|
-        store.prepare_record_on_perform(job)
-        store.job_started!
-        result = block.call
-        formatted_result = job.active_job_store_format_result(result)
-        store.job_competed!(custom_data: active_job_store_custom_data, result: formatted_result)
-      rescue StandardError => e
-        store.job_failed!(exception: e, custom_data: active_job_store_custom_data)
-        raise
-      end
-    end
-  end
-
+  # Format / manipulate / serialize the job result
+  #
+  # @param result [any] Job's return value
+  #
+  # @return [any] Processed job's return value
   def active_job_store_format_result(result)
     result
   end
 
+  # Persist custom data while the job is performing
+  #
+  # @param custom_data [any] Attributes to serialize (it must be serializable in JSON)
   def save_job_custom_data(custom_data = nil)
     self.active_job_store_custom_data = custom_data if custom_data
     store.update_job_custom_data(active_job_store_custom_data)
   end
 
+  # Return the associated Active Job Store record
+  #
+  # @return [ActiveJobStore::Record] the corresponding record
+  def active_job_store_record
+    store.record
+  end
+
+  # Internal errors handler method
+  #
+  # @param exception [exception] The internal exception
+  def active_job_store_internal_error(context, exception)
+    warn("#{context}: #{exception}")
+  end
+
   module ClassMethods
+    # Query the list of job executions for the current job class
+    #
+    # @return [ActiveRecord Relation] query result
     def job_executions
       ::ActiveJobStore::Record.where(job_class: to_s)
     end
   end
 
+  class << self
+    def included(base)
+      base.extend(ClassMethods)
+
+      base.around_enqueue do |job, block|
+        store.around_enqueue(job) { block.call }
+      end
+
+      base.around_perform do |job, block|
+        store.around_perform(job) { block.call }
+      end
+    end
+  end
+
   private
 
   def store

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_job_store
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Mattia Roccoberton
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-11-12 00:00:00.000000000 Z
+date: 2022-11-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
 description: ActiveJob Store permits to store jobs state and custom data on a database
 email: mat@blocknot.es
 executables: []
@@ -46,7 +60,7 @@ metadata:
   source_code_uri: https://github.com/blocknotes/active_job_store
   changelog_uri: https://github.com/blocknotes/active_job_store/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -62,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.6
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Persist jobs information on DB
 test_files: []