marj 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5fd21edb773f1e25cc23e4099e7b0e6a3e2bb58485a988b063c37fdb71f31b82
+  data.tar.gz: aadc1963f4283a092a000bf0c8f732cd57a53f0ed69ad4c83c8c4dbd053907a3
+SHA512:
+  metadata.gz: 7ddc1d33db20fb9d9ee3a587a67e66c54dcffb8d7f04dc366f53d40605b3239642c5466196e27debe86b1a8c74e10138557f2797232324c7f7a4d49b5df0134c
+  data.tar.gz: 04a4170a8e39b64648bf125da0f1fe1eae1e5888bd33412ff896dc0358f1a6c5b37bd4df1305fb9b2be715812318a49354b0eae1ccc756ceff65bf96879060cc

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Nicholas Dower
+
+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,215 @@
+# Marj
+
+Marj is a Minimal ActiveRecord-based Jobs library.
+
+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
+
+For more information on ActiveJob, see:
+
+- https://edgeguides.rubyonrails.org/active_job_basics.html
+- https://www.rubydoc.info/gems/activejob
+
+## Setup
+
+### 1. Install
+
+Add the following to your Gemfile:
+
+```ruby
+gem 'marj', '~> 1.0'
+```
+
+### 2. Create the jobs table
+
+Apply a database migration:
+
+```ruby
+class CreateJobs < ActiveRecord::Migration[7.1]
+  def self.up
+    create_table :jobs, id: :string, primary_key: :job_id do |table|
+      table.string   :job_class,            null: false
+      table.text     :arguments,            null: false
+      table.string   :queue_name,           null: false
+      table.integer  :priority
+      table.integer  :executions,           null: false
+      table.text     :exception_executions, null: false
+      table.datetime :enqueued_at,          null: false
+      table.datetime :scheduled_at
+      table.string   :locale,               null: false
+      table.string   :timezone,             null: false
+    end
+
+    add_index :jobs, %i[enqueued_at]
+    add_index :jobs, %i[scheduled_at]
+    add_index :jobs, %i[priority scheduled_at enqueued_at]
+  end
+
+  def self.down
+    drop_table :jobs
+  end
+end
+```
+
+### 3. Configure the queue adapter
+
+If using Rails, configure the queue adapter via `Rails::Application`:
+
+```ruby
+require 'marj'
+
+# Configure via Rails::Application:
+class MyApplication < Rails::Application
+  config.active_job.queue_adapter = :marj
+end
+
+# Or for specific jobs:
+class SomeJob < ActiveJob::Base
+  self.queue_adapter = :marj
+end
+```
+
+If not using Rails:
+
+```ruby
+require 'marj'
+require 'marj/record' # Loads ActiveRecord
+
+# Configure via ActiveJob::Base:
+ActiveJob::Base.queue_adapter = :marj
+
+# Or for specific jobs:
+class SomeJob < ActiveJob::Base
+  self.queue_adapter = :marj
+end
+```
+
+## Example Usage
+
+```ruby
+# Enqueue and manually run a job:
+job = SomeJob.perform_later('foo')
+job.perform_now
+
+# Enqueue, retrieve and manually run a job:
+SomeJob.perform_later('foo')
+Marj.first.execute
+
+# Run all available jobs:
+Marj.work_off
+
+# Run jobs as they become available:
+loop do
+  Marj.work_off
+  sleep 5.seconds
+end
+```
+
+## ActiveJob Cheatsheet
+
+### Configuring a Queue Adapter
+
+```ruby
+# With Rails
+class MyApplication < Rails::Application
+  config.active_job.queue_adapter = :foo           # Instantiates FooAdapter
+  config.active_job.queue_adapter = FooAdapter.new # Uses FooAdapter directly
+end
+
+# Without Rails
+ActiveJob::Base.queue_adapter = :foo               # Instantiates FooAdapter
+ActiveJob::Base.queue_adapter = FooAdapter.new     # Uses FooAdapter directly
+
+# Single Job
+SomeJob.queue_adapter = :foo                       # Instantiates FooAdapter
+SomeJob.queue_adapter = FooAdapter.new             # Uses FooAdapter directly
+```
+
+## Configuration
+
+- `config.active_job.default_queue_name`
+- `config.active_job.queue_name_prefix`
+- `config.active_job.queue_name_delimiter`
+- `config.active_job.retry_jitter`
+- `SomeJob.queue_name_prefix`
+- `SomeJob.queue_name_delimiter`
+- `SomeJob.retry_jitter`
+- `SomeJob.queue_name`
+- `SomeJob.queue_as`
+
+### Options
+
+- `:wait` - Enqueues the job with the specified delay
+- `:wait_until` - Enqueues the job at the time specified
+- `:queue` - Enqueues the job on the specified queue
+- `:priority` - Enqueues the job with the specified priority
+
+### Callbacks
+
+- `SomeJob.before_enqueue`
+- `SomeJob.after_enqueue`
+- `SomeJob.around_enqueue`
+- `SomeJob.before_perform`
+- `SomeJob.after_perform`
+- `SomeJob.around_perform`
+- `ActiveJob::Callbacks.singleton_class.set_callback(:execute, :before, &block)`
+- `ActiveJob::Callbacks.singleton_class.set_callback(:execute, :after, &block)`
+- `ActiveJob::Callbacks.singleton_class.set_callback(:execute, :around, &block)`
+
+## Handling Exceptions
+
+- `SomeJob.retry_on`
+- `SomeJob.discard_on`
+- `SomeJob.after_discard`
+
+### Creating Jobs
+
+```ruby
+# Create without enqueueing
+job = SomeJob.new
+job = SomeJob.new(args)
+
+# Create and enqueue
+job = SomeJob.perform_later
+job = SomeJob.perform_later(args)
+
+# Create and run (enqueued on failure)
+SomeJob.perform_now
+SomeJob.perform_now(args)
+```
+
+### Enqueueing Jobs
+
+```ruby
+SomeJob.new(args).enqueue
+SomeJob.new(args).enqueue(options)
+
+SomeJob.perform_later(args)
+SomeJob.set(options).perform_later(args)
+
+# Enqueued on failure
+SomeJob.perform_now(args)
+
+# Enqueue multiple
+ActiveJob.perform_all_later(SomeJob.new, SomeJob.new)
+ActiveJob.perform_all_later(SomeJob.new, SomeJob.new, options:)
+
+# Enqueue multiple
+SomeJob.set(options).perform_all_later(SomeJob.new, SomeJob.new)
+SomeJob.set(options).perform_all_later(SomeJob.new, SomeJob.new, options:)
+```
+
+### Executing Jobs
+
+```ruby
+# Executed without enqueueing, enqueued on failure if retries configured
+SomeJob.new(args).perform_now
+SomeJob.perform_now(args)
+ActiveJob::Base.exeucute(SomeJob.new(args).serialize)
+
+# Executed after enqueueing
+SomeJob.perform_later(args).perform_now
+ActiveJob::Base.exeucute(SomeJob.perform_later(args).serialize)
+```

data/app/models/marj.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'active_record'
+
+# Marj is a Minimal ActiveRecord-based Jobs library.
+#
+# See https://github.com/nicholasdower/marj
+class Marj < ActiveRecord::Base
+  # The Marj version.
+  VERSION = '1.0.0'
+
+  self.table_name = 'jobs'
+  self.implicit_order_column = 'enqueued_at' # Order by +enqueued_at+ rather than +job_id+ (the default)
+
+  serialize(:exception_executions, coder: JSON)
+  serialize(:arguments, coder: Class.new do
+    def self.dump(arguments)
+      return ActiveJob::Arguments.serialize(arguments).to_json if arguments.is_a?(Array)
+      return arguments if arguments.is_a?(String) || arguments.nil?
+
+      raise "invalid arguments: #{arguments}"
+    end
+
+    def self.load(arguments)
+      arguments ? ActiveJob::Arguments.deserialize(JSON.parse(arguments)) : nil
+    end
+  end)
+  serialize(:job_class, coder: Class.new do
+    def self.dump(clazz)
+      return clazz.name if clazz.is_a?(Class)
+      return clazz if clazz.is_a?(String) || clazz.nil?
+
+      raise "invalid class: #{clazz}"
+    end
+
+    def self.load(str)
+      str&.constantize
+    end
+  end)
+
+  # Returns an ActiveRecord::Relation scope for enqueued jobs with a +scheduled_at+ that is either +null+ or in the
+  # past. Jobs are ordered by +priority+ (+null+ last), then +scheduled_at+ (+null+ last), then +enqueued_at+.
+  #
+  # @return [ActiveRecord::Relation]
+  def self.available
+    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,
+        CASE WHEN scheduled_at IS NULL THEN 1 ELSE 0 END, scheduled_at,
+        enqueued_at
+      SQL
+    )
+  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
+
+  # Registers job callbacks used to keep the database record for the specified job in sync.
+  #
+  # @param job [ActiveJob::Base]
+  # @return [ActiveJob::Base]
+  def self.register_callbacks(job, record)
+    return if job.singleton_class.instance_variable_get(:@__marj)
+
+    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
+
+  # Enqueue a job for execution at the specified time.
+  #
+  # @param job [ActiveJob::Base] the job to enqueue
+  # @param time [Time, NilClass] optional time at which to execute the job
+  # @return [ActiveJob::Base] the enqueued job
+  def self.enqueue(job, time = nil)
+    job.scheduled_at = time
+    serialized = job.serialize.symbolize_keys!.without(:provider_job_id).merge(arguments: job.arguments)
+    if (record = job.singleton_class.instance_variable_get(:@__marj))
+      record.update!(serialized)
+    else
+      record = Marj.find_by(job_id: job.job_id)&.update!(serialized) || Marj.create!(serialized)
+    end
+    register_callbacks(job, record)
+  end
+  private_class_method :enqueue
+
+  # Executes the job associated with this record and returns the result.
+  def execute
+    job = Marj.send(:register_callbacks, job_class.new, self)
+    job_data = attributes.merge('arguments' => JSON.parse(read_attribute_before_type_cast(:arguments)))
+    job_data = job_data.to_h { |k, v| [k, %w[enqueued_at scheduled_at].include?(k) ? v&.iso8601 : v] }
+    job.deserialize(job_data)
+    ActiveJob::Callbacks.run_callbacks(:execute) { job.perform_now }
+  end
+end

data/lib/marj/record.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative '../../app/models/marj'

data/lib/marj.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# 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
+
+  # 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
+
+# Enable auto-loading when running in Rails.
+class MarjEngine < Rails::Engine; end if defined?(Rails)

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: marj
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Nick Dower
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-01-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: Minimal ActiveRecord-based Jobs library
+email: nicholasdower@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- app/models/marj.rb
+- lib/marj.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.0.0
+  documentation_uri: https://www.rubydoc.info/github/nicholasdower/marj/v1.0.0
+  homepage_uri: https://github.com/nicholasdower/marj
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/nicholasdower/marj
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key: 
+specification_version: 4
+summary: An ActiveJob queuing backend backed by ActiveRecord.
+test_files: []