active_job_store 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 913b4d81b0dfb938f013f907696dc04354a106818140d25003ae44ab4e4ed9f9
-  data.tar.gz: 39874892b9ee2443311d54cfedf7589697959c5ccb4184d8d934d67960838c7d
+  metadata.gz: a9fd49a85e50473450a09a741acaf01d5e6565116cb6f945f314bd6e4dd74f6d
+  data.tar.gz: d5655ec674b4a86d99b267c8a851e2a8d1cd687e188c58c8a292bf5120cffc3b
 SHA512:
-  metadata.gz: 18b9c5696a4b4092ae9ea5d6ae8ed74ed45aaef567804f53a7b59fee306038f6ce2e63f0832b9bdc6f6ad61dbb7d69b81239c5801fe39db2b163be50f0e468ad
-  data.tar.gz: 0ad46829f63b6a6347812df19f0b0a3ef8b9e0c092ecf6f8f1743b08ddfeef9077735cdcb19690421222ca9557b2c6338b9e122d7e747f76a50d3357d62e3534
+  metadata.gz: f9e1a166e181d32afb0265ac062b954930b8d748af36b21e837d2ee6fe28a7d57edc2f9ad590339e49fefbc3256e6b43317d19ab4e9ff1de36e7f2aa67d0dac4
+  data.tar.gz: a407a4446dec032e4bf6f7b5f55536dadd703c0d1d1a75d61cdf37ace3388e09c836c520ffde6c0b31043867bd92c82ad04c57b54d7398ca126baa080715e0a5

data/README.md

@@ -7,14 +7,11 @@
 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).
+Please ⭐ if you like it.
 
 ## Installation
 
@@ -24,6 +21,19 @@ 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_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 +58,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,7 +75,34 @@ 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:
+
+```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 when it's 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' details
 
 To store the custom data (ex. a progress value):
 
@@ -100,7 +125,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, there is the `active_job_store_custom_data` accessor:
 
 ```rb
 class AnotherJob < ApplicationJob
@@ -123,7 +148,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 result before storing it (ex. for serialization), override `active_job_store_format_result`:
 
 ```rb
 class AnotherJob < ApplicationJob

data/lib/active_job_store/store.rb

@@ -6,14 +6,36 @@ module ActiveJobStore
 
     attr_reader :record
 
+    def around_enqueue(job)
+      prepare_record_on_enqueue(job)
+      record.lock! # NOTE: needed to avoid update conflicts with perform when setting the state to enqueued
+      yield
+      job_enqueued!
+    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)
+    rescue StandardError => e
+      job_failed!(exception: e, custom_data: job.active_job_store_custom_data)
+      raise
+    end
+
+    def update_job_custom_data(custom_data)
+      record.update!(custom_data: custom_data)
+    end
+
+    private
+
     def job_competed!(result:, custom_data:)
       record.update!(state: :completed, completed_at: Time.current, result: result, custom_data: custom_data)
       record
     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
     end
@@ -44,12 +66,6 @@ module ActiveJobStore
       record
     end
 
-    def update_job_custom_data(custom_data)
-      record.update!(custom_data: custom_data)
-    end
-
-    private
-
     def record_reference(job)
       {
         job_id: job.job_id,

data/lib/active_job_store/version.rb

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

data/lib/active_job_store.rb

@@ -4,47 +4,56 @@ 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
+
   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.3.0
 platform: ruby
 authors:
 - Mattia Roccoberton
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-12 00:00:00.000000000 Z
+date: 2022-11-15 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: []