async-job-adapter-active_job 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c8a40a83434c1941f79c05f10a410830cae9b4333ec0601f989c99b5dea7864
-  data.tar.gz: 9a1df3164ee43b93ab5ee0ca86a6d1ca1f5d5fc2fc5385b91e89d1f44baa7ede
+  metadata.gz: 438122b9f40ef9fd97ebe48bb50ff7a015a4dcd4837f6d9cd70cfb2dfba86a70
+  data.tar.gz: 19308266ced3a1fe91990d4b865aeb68cbdd5b82c1f99e4f62de068c0e0f97f2
 SHA512:
-  metadata.gz: 2798b359ff0467480e7fdffa824291270ff8692945e1716ebbbc7fdf2607bcf0b69aea5d0e90cd469d5952bad9a75f0d38c935ac24b67198156cd7f17ca8bde6
-  data.tar.gz: 735b4f1c2e02174a73ac9ce02cde46dafe38b96f7819f655bcf42fc85f9e62335f61f2fe5df5da66be3d418ab8a7248487562abd04ec2b8a56c3e922edce433f
+  metadata.gz: 64ec94d3dd9421049c342ab7702cb2f9ed4ae38859f76ba5a41d9f09bb1cc0a459f43d5229969a10a58e800e98ae0d68e065a8e65ab06d63e75694bccf13cfd7
+  data.tar.gz: 26733df41fe820a33a31dddae659610ee11a7d709f2b3fcbff4d0319e850c6b46ac676cfa4d8566cc0ffbf5aa10a6c0fdacc418836d70f1e6fdf036206329d55

data/context/getting-started.md

@@ -1,98 +1,66 @@
 # Getting Started
 
-This guide explains how to get started with the `async-job-adapter-active_job` gem.
+This guide explains how to use `async-job-adapter-active_job` to run Rails Active Job workloads with inline or Redis-backed queues.
 
 ## Installation
 
-Add the gem to your Rails project:
+Add the adapter to your Rails application:
 
-``` bash
+```shell
 $ bundle add async-job-adapter-active_job
 ```
 
 ## Core Concepts
 
-The `async-job-adapter-active_job` gem provides an Active Job adapter for the `async-job` gem. This allows you to use the `async-job` gem with Rails' built-in Active Job framework.
+The adapter connects Active Job's standard API to an `async-job` processing pipeline:
 
-- The {ruby Async::Job::ActiveJob::Dispatcher} class manages zero or more queues.
-- The {ruby Async::Job::ActiveJob::Railtie} class provides a convenient interface for configuring the integration.
+- ruby:`ActiveJob::QueueAdapters::AsyncJobAdapter` receives jobs from `perform_later` and dispatches their serialized payloads.
+- A queue definition maps an Active Job queue name to an `async-job` processor.
+- The processor determines where jobs wait and run. The built-in inline processor keeps work in the application process, while processors such as Redis support separate workers.
+- ruby:`Async::Job::Adapter::ActiveJob::Executor` deserializes queued payloads and invokes Active Job.
 
-In general, `Async::Job` has a concept of queues, where jobs enter into a queue, may get serialized to a queue, then deserialized and processed. This ActiveJob adapter provides {ruby Async::Job::ActiveJob::Interface} which goes at the head of the queue, and matches the interface that ActiveJob expects for enqueueing jobs. At the tail of the queue, the {ruby Async::Job::ActiveJob::Executor} class is responsible for processing jobs by dispatching back into ActiveJob.
+Active Job remains responsible for arguments, callbacks, retries, and error handling. This gem supplies the queue adapter and worker integration.
 
-## Usage
+## Quick Start
 
-In order to use `Async::Job`, you need to define your queues and configure the Active Job adapter. Here is an example configuration:
+The built-in inline queue is the quickest way to get started because it does not require Redis or a separate worker. It is useful during development and for non-critical work that can remain in the application process.
 
-### `ActiveJob` Queue Adapter Configuration
+Configure Active Job to use the adapter in `config/application.rb`:
 
-You can configure the ActiveJob queue adapter globally (in `config/application.rb`) or per-environment (in `config/environments/*.rb`).
-
-```
-# In config/application.rb or config/environments/*.rb
-
-config.active_job.queue_adapter = :async_job
-```
-
-### `Async::Job` Queue Configuration
-
-You can define your queues in an initializer file (e.g., `config/initializers/async_job.rb`). Here is an example configuration that sets up two queues: a default queue using Redis and a local queue that processes jobs inline. NOTE that inline jobs will run **sequentially** (that is, not concurrently) outside of an `Async` event loop (that is to say, your jobs will block unless you're running your server using falcon).
-
-``` ruby
-# config/initializers/async_job.rb
-
-require "async/job/processor/redis"
-require "async/job/processor/inline"
-
-Rails.application.configure do
-	# Create a queue for the "default" backend:
-	config.async_job.define_queue "default" do
-		dequeue Async::Job::Processor::Redis
-	end
-	
-	# Create a queue named "local" which uses the Inline backend:
-	config.async_job.define_queue "local" do
-		dequeue Async::Job::Processor::Inline
+```ruby
+module MyApplication
+	class Application < Rails::Application
+		config.active_job.queue_adapter = :async_job
 	end
 end
 ```
 
-#### Job Specific Configuration
-
-Rather than using `Async::Job` for all jobs, you could opt in using a specific queue adapter for a specific job. Here is an example:
+Create an Active Job as usual. Define retry and discard behavior on the job so expected failures are handled explicitly:
 
-``` ruby
-class MyJob < ApplicationJob
-	self.queue_adapter = :async_job
-	queue_as :local
+```ruby
+class SearchIndexRefreshJob < ApplicationJob
+	queue_as :default
+	retry_on SearchIndex::Unavailable, wait: 5.seconds, attempts: 3
+	discard_on ActiveRecord::RecordNotFound
 	
-	# ...
+	def perform(product_id)
+		Product.find(product_id).refresh_search_index!
+	end
 end
 ```
 
-### Running A Server
-
-If you are using a queue that requires a server (e.g. Redis), you will need to run a server. A simple server is provided `async-job-adapter-active_job-server`, which by default will run all define queues.
+Enqueue it with `perform_later`:
 
-``` bash
-$ bundle exec async-job-adapter-active_job-server
+```ruby
+SearchIndexRefreshJob.perform_later(product.id)
 ```
 
-You can specify different queues using the `ASYNC_JOB_ADAPTER_ACTIVE_JOB_QUEUE_NAMES` environment variable.
+Scheduled jobs use the standard Active Job API too:
 
-Alternatively, you may prefer to run your own service. See the code in `bin/async-job-adapter-active_job-server` for an example of how to run a server using a service definition.
-
-### Enqueuing Jobs
+```ruby
+SearchIndexRefreshJob.set(wait: 5.minutes).perform_later(product.id)
+```
 
-To enqueue a job, you can use the `perform_later` method in your Active Job class. Here is an example:
+That is enough for a working setup. The adapter provides a `default` queue backed by ruby:`Async::Job::Processor::Inline`.
 
-``` ruby
-class MyJob < ApplicationJob
-	queue_as :default
-	
-	def perform(message)
-		puts message
-	end
-end
-
-MyJob.perform_later("Hello, world!")
-```
+The inline processor is intentionally simple: jobs remain in the application process and will not survive a restart. Inside an Async event loop, such as a Rails application served by Falcon, jobs can run concurrently in background tasks. Outside an Async event loop, `perform_later` waits for the job to finish before returning.

data/context/index.yaml

@@ -3,10 +3,24 @@
 ---
 description: A asynchronous job queue for Ruby on Rails.
 metadata:
+  bug_tracker_uri: https://github.com/socketry/async-job-adapter-active_job/issues
+  changelog_uri: https://github.com/socketry/async-job-adapter-active_job/blob/main/releases.md
   documentation_uri: https://socketry.github.io/async-job-adapter-active_job/
   source_code_uri: https://github.com/socketry/async-job-adapter-active_job.git
 files:
 - path: getting-started.md
   title: Getting Started
-  description: This guide explains how to get started with the `async-job-adapter-active_job`
-    gem.
+  description: This guide explains how to use `async-job-adapter-active_job` to run
+    Rails Active Job workloads with inline or Redis-backed queues.
+- path: testing.md
+  title: Testing
+  description: This guide explains how to test Active Job workloads without running
+    `async-job` queues inline during every test.
+- path: production-deployment.md
+  title: Production Deployment
+  description: This guide explains how to deploy `async-job-adapter-active_job` with
+    Redis-backed queues and separate worker processes.
+- path: queue-configuration.md
+  title: Queue Configuration
+  description: This guide explains how to configure `async-job` queue definitions,
+    route Active Jobs, and adopt the adapter incrementally.

data/context/production-deployment.md

@@ -0,0 +1,79 @@
+# Production Deployment
+
+This guide explains how to deploy `async-job-adapter-active_job` with Redis-backed queues and separate worker processes.
+
+## Overview
+
+The built-in inline processor keeps jobs inside the Rails process. That is convenient for development, but jobs cannot survive a process restart or be consumed by another machine.
+
+Use a shared queue and separate workers when jobs must:
+
+- Survive web process restarts.
+- Run outside request-serving processes.
+- Be distributed across one or more worker machines.
+
+Keep the inline processor when those operational guarantees are unnecessary; it has fewer moving parts and requires no external service.
+
+## Installing the Redis Processor
+
+Redis support is provided by a separate gem:
+
+```shell
+$ bundle add async-job-processor-redis
+```
+
+Ensure a Redis service is available to both the Rails and worker processes.
+
+## Configuring the Queue
+
+Replace the built-in `default` queue definition in `config/initializers/async_job.rb`:
+
+```ruby
+require "async/job/processor/redis"
+
+Rails.application.configure do
+	config.async_job.define_queue "default" do
+		dequeue Async::Job::Processor::Redis
+	end
+end
+```
+
+The processor connects to Redis on its local default endpoint unless another endpoint is provided. With one logical queue, the default `async-job` prefix is sufficient. Configure distinct, stable prefixes when multiple queue definitions share a Redis endpoint.
+
+## Starting Workers
+
+Run the bundled worker from the Rails application root so it can load `config/environment.rb`:
+
+```shell
+$ RAILS_ENV=production bundle exec async-job-adapter-active_job-server
+```
+
+The server loads the Rails environment and starts every defined queue. The service container supervises worker instances and reports their readiness.
+
+If the command cannot run from the application root, set `RAILS_ROOT` explicitly:
+
+```shell
+$ RAILS_ROOT=/srv/my-application RAILS_ENV=production bundle exec async-job-adapter-active_job-server
+```
+
+## Selecting Queues
+
+Worker groups can listen to a subset of definitions. Provide their names as a comma-separated list:
+
+```shell
+$ ASYNC_JOB_ADAPTER_ACTIVE_JOB_QUEUE_NAMES=default,critical bundle exec async-job-adapter-active_job-server
+```
+
+The values must be definition names, not aliases, and should not contain spaces. Run at least one worker group for every Redis-backed definition that should make progress.
+
+## Deployment Checklist
+
+Before sending production traffic, confirm that:
+
+- Rails and workers deploy the same application code and queue configuration.
+- Both process types use the same `RAILS_ENV`, Redis endpoint, and queue prefixes.
+- Each required queue definition has an active worker group.
+- Jobs define appropriate Active Job retry and discard behavior for expected failures.
+- Redis persistence and availability match the durability requirements of the application.
+
+An inline definition cannot transfer jobs into another process. If a job runs in the web process or never appears in Redis, confirm that the Rails process actually replaced the built-in inline definition.

data/context/queue-configuration.md

@@ -0,0 +1,120 @@
+# Queue Configuration
+
+This guide explains how to configure `async-job` queue definitions, route Active Jobs, and adopt the adapter incrementally.
+
+## Overview
+
+Active Job assigns every job a queue name. The adapter must map that name to an `async-job` queue definition, which specifies the processor responsible for storing and running the job.
+
+The adapter includes a `default` definition backed by ruby:`Async::Job::Processor::Inline`. Define additional queues when you need:
+
+- A shared processor such as Redis instead of in-process execution.
+- Separate capacity for latency-sensitive and bulk workloads.
+- Several Active Job queue names routed through one processor.
+
+Every name selected by `queue_as` must have a matching definition or alias.
+
+## Defining a Queue
+
+Queue definitions belong in `config/initializers/async_job.rb`. The examples below use the Redis processor so independently operated queues have shared storage:
+
+```shell
+$ bundle add async-job-processor-redis
+```
+
+This definition replaces the built-in inline `default` queue:
+
+```ruby
+require "async/job/processor/redis"
+
+Rails.application.configure do
+	config.async_job.define_queue "default" do
+		dequeue Async::Job::Processor::Redis
+	end
+end
+```
+
+Processors can accept positional and keyword arguments after the processor class.
+
+## Redis Prefixes
+
+Without an explicit `prefix`, every Redis processor uses `async-job`. Queue definition names do not alter that default, so two definitions using the same Redis endpoint and prefix operate on the same underlying queue.
+
+For each independently processed queue, the prefix must be:
+
+- Distinct from other queues using the same Redis endpoint.
+- Identical in Rails and worker processes.
+- Stable across deployments so existing jobs remain reachable.
+
+Include an application or environment namespace only when those workloads share a Redis endpoint.
+
+## Defining Multiple Queues
+
+Multiple definitions allow independent worker groups to process different workloads. For example, payment capture can use a dedicated queue while ordinary work remains on `default`:
+
+```ruby
+require "async/job/processor/redis"
+
+Rails.application.configure do
+	config.async_job.define_queue "default" do
+		dequeue Async::Job::Processor::Redis, prefix: "async-job:default"
+	end
+	
+	config.async_job.define_queue "critical" do
+		dequeue Async::Job::Processor::Redis, prefix: "async-job:critical"
+	end
+end
+```
+
+Select the definition using the standard Active Job API:
+
+```ruby
+class PaymentCaptureJob < ApplicationJob
+	queue_as :critical
+	retry_on PaymentGateway::Unavailable, wait: 5.seconds, attempts: 5
+	discard_on ActiveRecord::RecordNotFound
+	
+	def perform(payment_id)
+		Payment.find(payment_id).capture!
+	end
+end
+```
+
+Create separate definitions only when workloads need distinct storage, capacity, or operational controls. A single definition is simpler when those differences do not matter.
+
+## Aliasing Queue Names
+
+Aliases route several Active Job queue names through one queue definition. This is useful for framework-defined names such as `mailers` when they do not need independent worker capacity:
+
+```ruby
+Rails.application.configure do
+	config.async_job.alias_queue "default", "mailers", "low_priority"
+end
+```
+
+Jobs assigned to `mailers` or `low_priority` are submitted through the `default` definition. Aliases do not create queues and are not valid values for `ASYNC_JOB_ADAPTER_ACTIVE_JOB_QUEUE_NAMES`; worker selection uses definition names.
+
+## Opting In One Job at a Time
+
+Applications can adopt the adapter without replacing their global Active Job backend. Set `queue_adapter` on an individual job and leave other jobs unchanged:
+
+```ruby
+class SearchIndexRefreshJob < ApplicationJob
+	self.queue_adapter = :async_job
+	queue_as :default
+	retry_on SearchIndex::Unavailable, wait: 5.seconds, attempts: 3
+	discard_on ActiveRecord::RecordNotFound
+	
+	def perform(product_id)
+		Product.find(product_id).refresh_search_index!
+	end
+end
+```
+
+The selected queue must still have a definition or alias in `config.async_job`.
+
+## Understanding the Pipeline
+
+When `perform_later` is called, ruby:`ActiveJob::QueueAdapters::AsyncJobAdapter` serializes the Active Job and sends it to the definition selected by `queue_as`. The configured processor transports or schedules the payload. On the consumer side, ruby:`Async::Job::Adapter::ActiveJob::Executor` deserializes it and invokes Active Job.
+
+Definitions use `async-job`'s pipeline builder. The processor is written as `dequeue` because it wraps the consumer side of the pipeline; it still supplies the client used by Rails to enqueue jobs. The Active Job executor is appended automatically and should not be added to the definition.

data/context/testing.md

@@ -0,0 +1,91 @@
+# Testing
+
+This guide explains how to test Active Job workloads without running `async-job` queues inline during every test.
+
+## Recommended Configuration
+
+Configure the adapter for the application in `config/application.rb` so development and production use the same Active Job integration:
+
+```ruby
+module MyApplication
+	class Application < Rails::Application
+		config.active_job.queue_adapter = :async_job
+	end
+end
+```
+
+Override the adapter in `config/environments/test.rb`:
+
+```ruby
+Rails.application.configure do
+	config.active_job.queue_adapter = :test
+end
+```
+
+The Rails test adapter records enqueued jobs instead of sending them to an `async-job` processor. This keeps tests deterministic, prevents the built-in inline queue from performing jobs unexpectedly, and enables Rails' standard Active Job test helpers.
+
+Keeping `:async_job` in the application configuration still exercises the adapter during development. Restricting it to production would make development behave differently from the deployed application.
+
+## Testing Job Behavior
+
+Use `perform_now` when testing the behavior implemented by a job. This invokes the job directly without involving a queue adapter:
+
+```ruby
+class SearchIndexRefreshJobTest < ActiveJob::TestCase
+	test "refreshes the product index" do
+		product = products(:example)
+		
+		assert_changes ->{product.reload.indexed_at} do
+			SearchIndexRefreshJob.perform_now(product.id)
+		end
+	end
+end
+```
+
+## Testing Enqueueing
+
+Use `assert_enqueued_with` to verify that application code submits the expected job and arguments:
+
+```ruby
+class ProductTest < ActiveSupport::TestCase
+	include ActiveJob::TestHelper
+	
+	test "schedules an index refresh" do
+		product = products(:example)
+		
+		assert_enqueued_with(job: SearchIndexRefreshJob, args: [product.id]) do
+			product.schedule_index_refresh
+		end
+	end
+end
+```
+
+Rails also provides `assert_enqueued_jobs` when only the number of submitted jobs matters.
+
+## Performing Enqueued Jobs
+
+Use `perform_enqueued_jobs` when a test needs to exercise the code that enqueues a job and the job itself:
+
+```ruby
+class ProductTest < ActiveSupport::TestCase
+	include ActiveJob::TestHelper
+	
+	test "refreshes the index asynchronously" do
+		product = products(:example)
+		
+		perform_enqueued_jobs do
+			product.schedule_index_refresh
+		end
+		
+		assert product.reload.indexed_at
+	end
+end
+```
+
+The helper performs jobs captured by the Rails test adapter within the block. It does not start an `async-job` processor or worker.
+
+## Testing Production Queue Integration
+
+Tests using `:test` verify job behavior and enqueueing through Active Job, but they do not exercise the production queue transport. Cover Redis-backed definitions and separate workers with a focused integration or deployment smoke test using the same queue configuration as production.
+
+Such a test should submit a uniquely identifiable job, wait for a worker to consume it, and verify its externally visible result. Keep this separate from the unit test suite so ordinary tests do not depend on Redis, worker timing, or another process.

data/lib/async/job/adapter/active_job/dispatcher.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "executor"
 
@@ -61,6 +61,8 @@ module Async
 						@definitions.keys
 					end
 					
+					# Generate a summary of the configured queues and their server status.
+					# @returns [String] A comma-separated summary of all configured queues.
 					def status_string
 						self.keys.map do |name|
 							queue = @queues[name]

data/lib/async/job/adapter/active_job/service.rb

@@ -48,7 +48,7 @@ module Async
 										Console.debug(self, "Starting queue...", queue_name: queue_name)
 										dispatcher.start(queue_name)
 									rescue => error
-										Console::Event::Failure.for(error).emit(self, "Queue failed!")
+										Console.error(self, "Failed to start queue!", queue_name: queue_name, exception: error)
 									end
 								end
 								

data/lib/async/job/adapter/active_job/version.rb

@@ -7,7 +7,7 @@ module Async
 	module Job
 		module Adapter
 			module ActiveJob
-				VERSION = "0.19.0"
+				VERSION = "0.20.0"
 			end
 		end
 	end

data/readme.md

@@ -8,7 +8,13 @@ Provides an adapter for ActiveJob on top of `Async::Job`.
 
 Please see the [project documentation](https://socketry.github.io/async-job-adapter-active_job/) for more details.
 
-  - [Getting Started](https://socketry.github.io/async-job-adapter-active_job/guides/getting-started/index) - This guide explains how to get started with the `async-job-adapter-active_job` gem.
+  - [Getting Started](https://socketry.github.io/async-job-adapter-active_job/guides/getting-started/index) - This guide explains how to use `async-job-adapter-active_job` to run Rails Active Job workloads with inline or Redis-backed queues.
+
+  - [Testing](https://socketry.github.io/async-job-adapter-active_job/guides/testing/index) - This guide explains how to test Active Job workloads without running `async-job` queues inline during every test.
+
+  - [Production Deployment](https://socketry.github.io/async-job-adapter-active_job/guides/production-deployment/index) - This guide explains how to deploy `async-job-adapter-active_job` with Redis-backed queues and separate worker processes.
+
+  - [Queue Configuration](https://socketry.github.io/async-job-adapter-active_job/guides/queue-configuration/index) - This guide explains how to configure `async-job` queue definitions, route Active Jobs, and adopt the adapter incrementally.
 
 ## Releases
 
@@ -64,26 +70,26 @@ Please see the [project releases](https://socketry.github.io/async-job-adapter-a
 
 We welcome contributions to this project.
 
-1.  Fork it.
+1.  Fork the repository.
 2.  Create your feature branch (`git checkout -b my-new-feature`).
-3.  Commit your changes (`git commit -am 'Add some feature'`).
+3.  Commit your changes (`git commit -am 'Add some feature.'`).
 4.  Push to the branch (`git push origin my-new-feature`).
-5.  Create new Pull Request.
+5.  Create a new pull request.
 
 ### Running Tests
 
 To run the test suite:
 
-``` shell
-bundle exec sus
+``` bash
+$ bundle exec sus
 ```
 
 ### Making Releases
 
 To make a new release:
 
-``` shell
-bundle exec bake gem:release:patch # or minor or major
+``` bash
+$ bundle exec bake gem:release:patch # or minor or major
 ```
 
 ### Developer Certificate of Origin

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-job-adapter-active_job
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -92,6 +92,9 @@ files:
 - bin/async-job-adapter-active_job-server
 - context/getting-started.md
 - context/index.yaml
+- context/production-deployment.md
+- context/queue-configuration.md
+- context/testing.md
 - lib/active_job/queue_adapters/async_job_adapter.rb
 - lib/async/job/adapter/active_job.rb
 - lib/async/job/adapter/active_job/dispatcher.rb
@@ -108,6 +111,8 @@ homepage: https://github.com/socketry/async-job-adapter-active_job
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/socketry/async-job-adapter-active_job/issues
+  changelog_uri: https://github.com/socketry/async-job-adapter-active_job/blob/main/releases.md
   documentation_uri: https://socketry.github.io/async-job-adapter-active_job/
   source_code_uri: https://github.com/socketry/async-job-adapter-active_job.git
 rdoc_options: []
@@ -124,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A asynchronous job queue for Ruby on Rails.
 test_files: []