marj 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4feb80230bafd2d67bdb0316598f4c46eabd01ca86c35fb8b01e04c865f91a8
-  data.tar.gz: be461234b8359c9f974dd4160d896cc048d0dcc1f4b7d74b57042d62f9950a18
+  metadata.gz: '078c3d48b27784e09425ba8eda2207038d6ce5c7a711953e8567c76aac689435'
+  data.tar.gz: c129b4848de1e2fe55de0de3a4893586a052cd814df798879dc196a81c1a94d5
 SHA512:
-  metadata.gz: 31735c1c143a47ab490ed08eca12af6d8fce73b551637ed92e37bcb42e8b2560135ad674dfc832353988f4246c10f9ff2822f624bb10ba256070632dd35c209c
-  data.tar.gz: 7f19dee3c8b0510d27ca10eb8f9d64ecfc2e1174ae1cea71e17abf42f0ce8ef07be4f84e1eff9cf0150e6162bb3a790e066e36f17db131056e30ebbeada1bdc3
+  metadata.gz: 4cef48fb7c862123f4a5ad7ed5bf7a9d95eb3d7036831db79ad3dc9cf94f074a112ce58f0189484f991a52185cdf8e8ceed48dd9237bf4a04d5e3bbe30b2d274
+  data.tar.gz: 7631b1a0fef1ece1edcf15541dc85d25b2d5d3ba1cb8ca716133975126e5ce9bb4f28d627a4c2a5d751029ce8f67ba4db47c6fa9d197467fade4c09d20a04716

data/README.md

@@ -1,6 +1,8 @@
-# Marj
+# Marj - Minimal ActiveRecord Jobs
 
-Marj is a Minimal ActiveRecord-based Jobs library.
+The simplest database-backed ActiveJob queueing backend.
+
+## Quick Links
 
 API docs: https://www.rubydoc.info/github/nicholasdower/marj <br>
 RubyGems: https://rubygems.org/gems/marj <br>
@@ -8,27 +10,52 @@ Changelog: https://github.com/nicholasdower/marj/releases <br>
 Issues: https://github.com/nicholasdower/marj/issues <br>
 Development: https://github.com/nicholasdower/marj/blob/master/CONTRIBUTING.md
 
-For more information on ActiveJob, see:
+## Features
 
-- https://edgeguides.rubyonrails.org/active_job_basics.html
-- https://www.rubydoc.info/gems/activejob
-- https://github.com/nicholasdower/marj/blob/master/README.md#activejob-cheatsheet
+- Enqueued jobs are written to the database.
+- Successfully executed jobs are deleted from the database.
+- Failed jobs which should be retried are updated in the database.
+- Failed jobs which should not be retried are deleted from the database.
+
+## Features Not Provided
+
+- Workers
+- Timeouts
+- Concurrency Controls
+- Observability
+- A User Interace
+- Anything else you might dream up.
+
+## Interface
+
+- `Marj` - An ActiveRecord model class
+- `Marj.ready` - Used to retrieve jobs ready to be executed
+- `Marj#execute` - Used to execute jobs retrieved from the database
+- `MarjConfig.table_name=` - Used to override the default table name
 
 ## Setup
 
 ### 1. Install
 
-Add the following to your Gemfile:
+```shell
+bundle add marj
 
-```ruby
-gem 'marj', '~> 1.0'
+# or
+
+gem install marj
 ```
 
-```shell
-bundle install
+### 2. Configure
+
+By default, the database table is named "jobs". To use a different table name:
+
+```ruby
+require 'marj'
+
+MarjConfig.table_name = 'some_name'
 ```
 
-### 2. Create the jobs table
+### 3. Create the database table
 
 ```ruby
 class CreateJobs < ActiveRecord::Migration[7.1]
@@ -57,15 +84,7 @@ class CreateJobs < ActiveRecord::Migration[7.1]
 end
 ```
 
-To use a different table name:
-
-```ruby
-require 'marj'
-
-MarjConfig.table_name = 'some_name'
-```
-
-### 3. Configure the queue adapter
+### 4. Configure the queue adapter
 
 ```ruby
 require 'marj'
@@ -93,28 +112,40 @@ job.perform_now
 
 # Enqueue, retrieve and manually run a job:
 SomeJob.perform_later('foo')
-record = Marj.first
-record.execute
+Marj.first.execute
 
 # Run all ready jobs:
-while (record = Marj.ready.first)
-  record.execute
-end
+Marj.ready.each(&:execute)
+
+# Run all ready jobs, querying each time:
+loop { Marj.ready.first&.tap(&:execute) || break }
 
 # Run all ready jobs in a specific queue:
-while (record = Marj.where(queue_name: 'foo').ready.first)
-  record.execute
-end
+loop { Marj.where(queue_name: 'foo').ready.first&.tap(&:execute) || break }
 
 # Run jobs as they become ready:
 loop do
-  while (record = Marj.ready.first)
-    record.execute
-  end
+  loop { Marj.ready.first&.tap(&:execute) || break }
+rescue Exception => e
+  logger.error(e)
+ensure
   sleep 5.seconds
 end
 ```
 
+## Testing
+
+By default, jobs enqeued during tests will be written to the database. Enqueued jobs can be executed via:
+
+```ruby
+Marj.ready.each(&:execute)
+```
+
+Alternatively, to use [ActiveJob::QueueAdapters::TestAdapter](https://api.rubyonrails.org/classes/ActiveJob/QueueAdapters/TestAdapter.html):
+```ruby
+ActiveJob::Base.queue_adapter = :test
+```
+
 ## Extension Examples
 
 ### Timeouts
@@ -176,6 +207,12 @@ end
 
 ## ActiveJob Cheatsheet
 
+For more information on ActiveJob, see:
+
+- https://edgeguides.rubyonrails.org/active_job_basics.html
+- https://www.rubydoc.info/gems/activejob
+- https://github.com/nicholasdower/marj/blob/master/README.md#activejob-cheatsheet
+
 ### Configuring a Queue Adapter
 
 ```ruby
@@ -253,6 +290,8 @@ SomeJob.perform_now(args)
 SomeJob.new(args).enqueue
 SomeJob.new(args).enqueue(options)
 
+SomeJob.perform_later(SomeJob.new(args))
+
 SomeJob.perform_later(args)
 SomeJob.set(options).perform_later(args)
 

data/lib/marj.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+# See https://github.com/nicholasdower/marj
+
 require_relative 'marj_adapter'
 require_relative 'marj_config'
 
-Kernel.autoload(:Marj, File.expand_path('../app/models/marj.rb', __dir__))
+Kernel.autoload(:Marj, File.expand_path('marj_record.rb', __dir__))

data/lib/marj_adapter.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 # ActiveJob queue adapter for Marj.
+#
+# See https://github.com/nicholasdower/marj
 class MarjAdapter
   # Enqueue a job for immediate execution.
   #

data/lib/marj_config.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 # Marj configuration.
+#
+# See https://github.com/nicholasdower/marj
 class MarjConfig
   @table_name = 'jobs'
 

data/{app/models/marj.rb → lib/marj_record.rb}

@@ -2,14 +2,14 @@
 
 require 'active_job'
 require 'active_record'
-require_relative '../../lib/marj_config'
+require_relative 'marj_config'
 
-# Marj is a Minimal ActiveRecord-based Jobs library.
+# The Marj ActiveRecord model class.
 #
 # See https://github.com/nicholasdower/marj
 class Marj < ActiveRecord::Base
   # The Marj version.
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 
   # Executes the job associated with this record and returns the result.
   def execute
@@ -29,13 +29,9 @@ class Marj < ActiveRecord::Base
 
       # ActiveJob::Base#deserialize expects dates to be strings rather than Time objects.
       job_data = job_data.to_h { |k, v| [k, %w[enqueued_at scheduled_at].include?(k) ? v&.iso8601 : v] }
-      job.deserialize(job_data)
 
-      new_executions = executions + 1
-      job.perform_now.tap do
-        # If no error was raised, the job should either be destroyed (success) or updated (retryable failure).
-        raise "job #{job_id} not destroyed or updated" unless destroyed? || (executions == new_executions && !changed?)
-      end
+      job.deserialize(job_data)
+      job.perform_now
     end
   end
 
@@ -97,15 +93,20 @@ class Marj < ActiveRecord::Base
   # @param job [ActiveJob::Base]
   # @return [ActiveJob::Base]
   def self.register_callbacks(job, record)
-    raise 'callbacks already registered' if job.singleton_class.instance_variable_get(:@__marj)
+    if job.singleton_class.instance_variable_get(:@__marj)
+      # Callbacks already registered. We just need to update the record.
+      job.singleton_class.instance_variable_set(:@__marj, record)
+      return
+    end
 
     # We need to detect three cases:
     #  - If a job succeeds, after_perform will be called.
     #  - If a job fails and should be retried, enqueue will be called. This is handled by the enqueue method.
     #  - If a job exceeds its max attempts, after_discard will be called.
-    job.singleton_class.after_perform { |_j| record.destroy! }
-    job.singleton_class.after_discard { |_j, _exception| record.destroy! }
+    job.singleton_class.after_perform { |_j| job.singleton_class.instance_variable_get(:@__marj).destroy! }
+    job.singleton_class.after_discard { |_j, _exception| job.singleton_class.instance_variable_get(:@__marj).destroy! }
     job.singleton_class.instance_variable_set(:@__marj, record)
+
     job
   end
   private_class_method :register_callbacks
@@ -124,19 +125,28 @@ class Marj < ActiveRecord::Base
     # registered on the job instance so that when the job is executed, the database record is deleted or updated
     # (depending on the result).
     #
-    # There are three cases:
+    # There are two normal cases:
     #  - The first time a job is enqueued, we need to create the record and register callbacks.
     #  - If a previously enqueued job instance is re-enqueued, for instance after execution fails, callbacks have
     #    already been registered. In this case we only need to update the record.
-    #  - It is also possible for new job instance to be created for a job that is already in the database. In this case
-    #    we need to update the record and register callbacks.
     #
     # We keep track of whether callbacks have been registered by setting the @__marj instance variable on the job's
     # singleton class. This holds a reference to the record. This allows us to update the record without re-fetching it
     # and also ensures that if execute is called on a record any updates to the database are reflected on that record
     # instance.
+    #
+    # There are also two edge cases:
+    #  - It is possible for new job instance to be created for a job that is already in the database. In this case
+    #    we need to update the record and register callbacks.
+    #  - It is possible for the underlying row corresponding to an existing job to have been deleted. In this case we
+    #    need to create a new record and update the reference on the job's singleton class.
     if (record = job.singleton_class.instance_variable_get(:@__marj))
-      record.update!(serialized)
+      if Marj.exists?(job_id: job.job_id)
+        record.update!(serialized)
+      else
+        record = Marj.create!(serialized)
+        register_callbacks(job, record)
+      end
     else
       record = Marj.find_or_create_by!(job_id: job.job_id) { _1.assign_attributes(serialized) }
       register_callbacks(job, record)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: marj
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Nick Dower
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-22 00:00:00.000000000 Z
+date: 2024-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -38,7 +38,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
-description: Minimal ActiveRecord-based Jobs library
+description: Marj (Minimal ActiveRecord Jobs) is the simplest database-backed ActiveJob
+  queueing backend.
 email: nicholasdower@gmail.com
 executables: []
 extensions: []
@@ -46,17 +47,17 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
-- app/models/marj.rb
 - lib/marj.rb
 - lib/marj_adapter.rb
 - lib/marj_config.rb
+- lib/marj_record.rb
 homepage: https://github.com/nicholasdower/marj
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/nicholasdower/marj/issues
-  changelog_uri: https://github.com/nicholasdower/marj/releases/tag/v2.0.0
-  documentation_uri: https://www.rubydoc.info/github/nicholasdower/marj/v2.0.0
+  changelog_uri: https://github.com/nicholasdower/marj/releases/tag/v2.1.0
+  documentation_uri: https://www.rubydoc.info/github/nicholasdower/marj/v2.1.0
   homepage_uri: https://github.com/nicholasdower/marj
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/nicholasdower/marj
@@ -78,5 +79,5 @@ requirements: []
 rubygems_version: 3.5.3
 signing_key: 
 specification_version: 4
-summary: An ActiveJob queuing backend backed by ActiveRecord.
+summary: Minimal ActiveRecord Jobs
 test_files: []