marj 1.1.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5fe8134484360b68c0cf69356f6a037897c6896be81bc393a9dfc0fb0684055
-  data.tar.gz: 4b7575b721d05681876846f3f06d47440d366bc875e02cadeae7de4582270114
+  metadata.gz: 42a85f9f7752849bf9e7781eef989294d45420763c16fb5fadee3df3fc7a0c2e
+  data.tar.gz: acadf4b197599bd3150629a557857b8d48fa8bed662a2f4140a8dbe16f01e7ba
 SHA512:
-  metadata.gz: dbfa1cd4cfb90ca4c47b039f0f320e5cc847aa9863b640cd52b445f5074c13aaa0f2679f4ec950001a086f0b981f58f6aa180a250a4790753691b249dc4fa19f
-  data.tar.gz: d1903bcb55c22522d270d950b316ee99ce05edca0c279cc055cb39a71ecfd389d02acd5d1bcc029e931636e26c4708bfd872a20ab71ecc9328e69928a3b535c2
+  metadata.gz: a30fe477c647ca284fdcde1bcccc8b000f3b4ef78b62de84f486376fa65450fcf3a52c7132df520fd45ee7e0f2856d8812a16b804ce89baa93a8d2353dc8348f
+  data.tar.gz: 72a63c15a36f6bade30e93bb5f84d5d8c6bbab33b12f4c92c78579f07eb86689e8e7609dae9ec16b94334140e8e4c2828b6e6cb19a580ad9a42730f27afab8cb

data/README.md

@@ -1,30 +1,61 @@
-# 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>
 Changelog: https://github.com/nicholasdower/marj/releases <br>
-Issues: https://github.com/nicholasdower/marj/issues
+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
+- 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
 ```
 
-### 2. Create the jobs table
+### 2. Configure
+
+By default, the database table is named "jobs". To use a different table name:
+
+```ruby
+require 'marj'
+
+MarjConfig.table_name = 'some_name'
+```
 
-Apply a database migration:
+### 3. Create the database table
 
 ```ruby
 class CreateJobs < ActiveRecord::Migration[7.1]
@@ -53,7 +84,7 @@ class CreateJobs < ActiveRecord::Migration[7.1]
 end
 ```
 
-### 3. Configure the queue adapter
+### 4. Configure the queue adapter
 
 ```ruby
 require 'marj'
@@ -81,24 +112,107 @@ job.perform_now
 
 # Enqueue, retrieve and manually run a job:
 SomeJob.perform_later('foo')
-record = Marj.first
-record.execute
+Marj.first.execute
 
-# Run all available jobs:
-Marj.work_off
+# Run all ready jobs:
+Marj.ready.each(&:execute)
 
-# Run all available jobs in a specific queue:
-Marj.work_off(source = -> { Marj.where(queue_name: 'foo').available.first })
+# Run all ready jobs, querying each time:
+loop { Marj.ready.first&.tap(&:execute) || break }
 
-# Run jobs as they become available:
+# Run all ready jobs in a specific queue:
+loop { Marj.where(queue_name: 'foo').ready.first&.tap(&:execute) || break }
+
+# Run jobs as they become ready:
 loop do
-  Marj.work_off
+  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
+
+```ruby
+class ApplicationJob < ActiveJob::Base
+  def self.timeout_after(duration)
+    @timeout = duration
+  end
+
+  around_perform do |job, block|
+    if (timeout = job.class.instance_variable_get(:@timeout))
+      ::Timeout.timeout(timeout, StandardError, 'execution expired') { block.call }
+    else
+      block.call
+    end
+  end
+end
+```
+
+### Last Error
+
+```ruby
+class AddLastErrorToJobs < ActiveRecord::Migration[7.1]
+  def self.up
+    add_column :jobs, :last_error, :text
+  end
+
+  def self.down
+    remove_column :jobs, :last_error
+  end
+end
+
+class ApplicationJob < ActiveJob::Base
+  attr_reader :last_error
+
+  def last_error=(error)
+    if error.is_a?(Exception)
+      backtrace = error.backtrace&.map { |line| "\t#{line}" }&.join("\n")
+      error = backtrace ? "#{error.class}: #{error.message}\n#{backtrace}" : "#{error.class}: #{error.message}"
+    end
+
+    @last_error = error&.truncate(10_000, omission: '… (truncated)')
+  end
+
+  def set(options = {})
+    super.tap { self.last_error = options[:error] if options[:error] }
+  end
+
+  def serialize
+    super.merge('last_error' => @last_error)
+  end
+
+  def deserialize(job_data)
+    super.tap { self.last_error = job_data['last_error'] }
+  end
+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

data/lib/marj.rb

@@ -1,23 +1,8 @@
 # frozen_string_literal: true
 
-Kernel.autoload(:Marj, File.expand_path('../app/models/marj.rb', __dir__))
+# See https://github.com/nicholasdower/marj
 
-# ActiveJob queue adapter for Marj.
-class MarjAdapter
-  # Enqueue a job for immediate execution.
-  #
-  # @param job [ActiveJob::Base] the job to enqueue
-  # @return [ActiveJob::Base] the enqueued job
-  def enqueue(job)
-    Marj.send(:enqueue, job)
-  end
+require_relative 'marj_adapter'
+require_relative 'marj_config'
 
-  # Enqueue a job for execution at the specified time.
-  #
-  # @param job [ActiveJob::Base] the job to enqueue
-  # @param timestamp [Numeric, NilClass] optional number of seconds since Unix epoch at which to execute the job
-  # @return [ActiveJob::Base] the enqueued job
-  def enqueue_at(job, timestamp)
-    Marj.send(:enqueue, job, timestamp ? Time.at(timestamp).utc : nil)
-  end
-end
+Kernel.autoload(:Marj, File.expand_path('marj_record.rb', __dir__))

data/lib/marj_adapter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# ActiveJob queue adapter for Marj.
+#
+# See https://github.com/nicholasdower/marj
+class MarjAdapter
+  # Enqueue a job for immediate execution.
+  #
+  # @param job [ActiveJob::Base] the job to enqueue
+  # @return [ActiveJob::Base] the enqueued job
+  def enqueue(job)
+    Marj.send(:enqueue, job)
+  end
+
+  # Enqueue a job for execution at the specified time.
+  #
+  # @param job [ActiveJob::Base] the job to enqueue
+  # @param timestamp [Numeric, NilClass] optional number of seconds since Unix epoch at which to execute the job
+  # @return [ActiveJob::Base] the enqueued job
+  def enqueue_at(job, timestamp)
+    Marj.send(:enqueue, job, timestamp ? Time.at(timestamp).utc : nil)
+  end
+end

data/lib/marj_config.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Marj configuration.
+#
+# See https://github.com/nicholasdower/marj
+class MarjConfig
+  @table_name = 'jobs'
+
+  class << self
+    # The name of the database table. Defaults to "jobs".
+    #
+    # @return [String]
+    attr_accessor :table_name
+  end
+end

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

@@ -2,17 +2,18 @@
 
 require 'active_job'
 require 'active_record'
+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 = '1.1.0'
+  VERSION = '2.0.1'
 
   # Executes the job associated with this record and returns the result.
   def execute
-    # Normally we would call ActiveJob::Base#execute which has the following implemenation:
+    # Normally we would call ActiveJob::Base#execute which has the following implementation:
     #   ActiveJob::Callbacks.run_callbacks(:execute) do
     #     job = deserialize(job_data)
     #     job.perform_now
@@ -28,8 +29,8 @@ 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)
 
+      job.deserialize(job_data)
       job.perform_now
     end
   end
@@ -38,7 +39,7 @@ class Marj < ActiveRecord::Base
   # past. Jobs are ordered by +priority+ (+null+ last), then +scheduled_at+ (+null+ last), then +enqueued_at+.
   #
   # @return [ActiveRecord::Relation]
-  def self.available
+  def self.ready
     where('scheduled_at is null or scheduled_at <= ?', Time.now.utc).order(
       Arel.sql(<<~SQL.squish)
         CASE WHEN priority IS NULL THEN 1 ELSE 0 END, priority,
@@ -48,23 +49,7 @@ class Marj < ActiveRecord::Base
     )
   end
 
-  # Executes any available jobs from the specified source.
-  #
-  # @param source [Proc] a job source
-  # @return [NilClass]
-  def self.work_off(source = -> { Marj.available.first })
-    while (record = source.call)
-      executions = record.executions
-      begin
-        record.execute
-      rescue Exception
-        # The job should either be discarded or updated. Otherwise, something went wrong.
-        raise unless record.destroyed? || (record.executions == (executions + 1) && !record.changed?)
-      end
-    end
-  end
-
-  self.table_name = 'jobs'
+  self.table_name = MarjConfig.table_name
 
   # Order by +enqueued_at+ rather than +job_id+ (the default)
   self.implicit_order_column = 'enqueued_at'
@@ -117,6 +102,7 @@ class Marj < ActiveRecord::Base
     job.singleton_class.after_perform { |_j| record.destroy! }
     job.singleton_class.after_discard { |_j, _exception| record.destroy! }
     job.singleton_class.instance_variable_set(:@__marj, record)
+
     job
   end
   private_class_method :register_callbacks

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: marj
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Nick Dower
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-22 00:00:00.000000000 Z
+date: 2024-01-23 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,15 +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/v1.1.0
-  documentation_uri: https://www.rubydoc.info/github/nicholasdower/marj/v1.1.0
+  changelog_uri: https://github.com/nicholasdower/marj/releases/tag/v2.0.1
+  documentation_uri: https://www.rubydoc.info/github/nicholasdower/marj/v2.0.1
   homepage_uri: https://github.com/nicholasdower/marj
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/nicholasdower/marj
@@ -76,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: []