job-workflow 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ff0a254ebd8fee848ab5eb26036e0bd98392700811e0bd55ffeaf4c348e04b6
-  data.tar.gz: ada2c0170fe7776a15802416f65070911e464f98abff416f9cbb15ed207bc7a8
+  metadata.gz: 9ac9f67bfd9ba71b60f98643a5f5ed720423239650bdf80a8bb07de594d9b502
+  data.tar.gz: 6902b370e54d0285721390a40af5ff0a7b459c6ce0a67af6c538dc1877f0df85
 SHA512:
-  metadata.gz: d406e2e4ed2671b79aac352abe0405c009d0f4b089b4ecd2fb400b2a79c7676689cdbb9992e365063f17fb7160bb45084bc18966ff101097b39c6f6e5d3ecb60
-  data.tar.gz: 8d51653d18ed1769e513c2c3b854ac21663e1a9ed168dbac1713689912fa24b0c9cb9c66469a892e946e014905fc825934b555e4d657786efd5becd99fd9a866
+  metadata.gz: 6c24f513d3c1192513fef902a92d844050a25e095b2739e9f40e774639cde3fb75c4df1a6e2878a50f13583e5df0e665faa6ef803a434e9444d020a81ec2a71b
+  data.tar.gz: 1c7218d7a1c2d45444a111956bd26d152f16b2e1c6f86fb2959fd255c2ab844444d7929863149f3c7e4322073d520ff40ec3ea02ec29a1595135350723ed4a6a

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-12
+
+### Added
+
+- Add `workflow_concurrency` DSL class method as a context-aware wrapper around SolidQueue's `limits_concurrency`. Unlike `limits_concurrency`, the key Proc receives a `Context` object, giving access to `ctx.arguments`, `ctx.sub_job?`, and `ctx.concurrency_key`. A fallback `Context` is built from job arguments when `_context` is not yet initialized (e.g. during enqueue before `perform`).
+
+### Fixed
+
+- Fix task-level concurrency key: internal `limits_concurrency` call for `enqueue: { concurrency: N }` tasks now goes through `workflow_concurrency`, ensuring the key Proc receives a proper `Context` instead of raw ActiveJob arguments. Also changed the internal key proc from `lambda` to `proc` for compatibility with SolidQueue's `instance_exec(*arguments, &proc)` call site.
+
 ## [0.1.3] - 2026-01-06
 
 ### Changed

data/guides/API_REFERENCE.md

@@ -84,6 +84,73 @@ end
 
 **Map Task Output**: When `each:` is specified, outputs are automatically collected as an array.
 
+### workflow_concurrency
+
+Configure job-level concurrency limits with workflow-aware context.
+
+```ruby
+workflow_concurrency(to:, key:, **opts)
+```
+
+**Parameters**:
+- `to` (Integer): Maximum number of concurrent executions
+- `key` (Proc): A Proc that receives a `Context` and returns a String concurrency key
+- `opts` (Hash): Additional options passed to SolidQueue's `limits_concurrency`
+  - `on_conflict` (Symbol): `:discard` to drop duplicate jobs (optional)
+  - `duration` (ActiveSupport::Duration): How long the concurrency lock is held (optional)
+  - `group` (String): Concurrency group name (optional)
+
+Unlike SolidQueue's `limits_concurrency` (which passes raw ActiveJob arguments to the key Proc), `workflow_concurrency` passes a **Context** object, giving access to `arguments`, `sub_job?`, and `concurrency_key`.
+
+**Example — simple per-tenant key**:
+
+```ruby
+class ImportJob < ApplicationJob
+  include JobWorkflow::DSL
+
+  argument :tenant_id, "Integer"
+  argument :items, "Array[Integer]"
+
+  workflow_concurrency to: 1,
+                       key: ->(ctx) { "import:#{ctx.arguments.tenant_id}" },
+                       on_conflict: :discard
+
+  task :process,
+       each: ->(ctx) { ctx.arguments.items },
+       enqueue: { concurrency: 5 },
+       output: { result: "String" } do |ctx|
+    { result: handle(ctx.each_value) }
+  end
+end
+```
+
+**Example — separating parent and sub-job keys**:
+
+```ruby
+class BatchImportJob < ApplicationJob
+  include JobWorkflow::DSL
+
+  argument :tenant_id, "Integer"
+  argument :items, "Array[Integer]"
+
+  workflow_concurrency to: 1,
+                       key: lambda { |ctx|
+                         ctx.sub_job? ? ctx.concurrency_key : "batch:#{ctx.arguments.tenant_id}"
+                       },
+                       on_conflict: :discard
+
+  task :process,
+       each: ->(ctx) { ctx.arguments.items },
+       enqueue: { concurrency: 5 },
+       output: { result: "String" } do |ctx|
+    { result: handle(ctx.each_value) }
+  end
+end
+```
+
+> **Note**: `workflow_concurrency` calls `limits_concurrency` internally. Calling it multiple times in the same class will **overwrite** the previous setting (last-wins). Define it once per job class.
+> Requires SolidQueue.
+
 **Example**:
 
 ```ruby

data/guides/PARALLEL_PROCESSING.md

@@ -110,6 +110,68 @@ The `enqueue:` option determines how map task iterations are executed:
 
 **Note**: `enqueue:` works with both regular tasks and map tasks. For map tasks, it enables asynchronous sub-job execution. For regular tasks, it allows conditional enqueueing as a separate job. Legacy syntax (`enqueue: ->(_ctx) { true }` as a Proc) is still supported for backward compatibility.
 
+### Job-Level Concurrency with `workflow_concurrency`
+
+When using SolidQueue's `limits_concurrency` directly, the key Proc receives raw ActiveJob arguments (a Hash), making it difficult to distinguish parent jobs from sub-jobs. `workflow_concurrency` is a wrapper that passes a **Context** object to the key Proc, giving access to workflow-aware information.
+
+```ruby
+class ImportJob < ApplicationJob
+  include JobWorkflow::DSL
+
+  argument :tenant_id, "Integer"
+  argument :items, "Array[Integer]"
+
+  # Limit to 1 concurrent execution per tenant.
+  # The key Proc receives a Context, not raw arguments.
+  workflow_concurrency to: 1,
+                       key: ->(ctx) { "import:#{ctx.arguments.tenant_id}" },
+                       on_conflict: :discard
+
+  task :process_items,
+       each: ->(ctx) { ctx.arguments.items },
+       enqueue: { concurrency: 5 },
+       output: { result: "String" } do |ctx|
+    { result: process(ctx.each_value) }
+  end
+end
+```
+
+**Key differences from `limits_concurrency`:**
+
+| Feature | `limits_concurrency` (SolidQueue) | `workflow_concurrency` (JobWorkflow) |
+|---|---|---|
+| Key Proc argument | Raw Hash (ActiveJob arguments) | `Context` object |
+| Access to `sub_job?` | ❌ Not available | ✅ `ctx.sub_job?` |
+| Access to `concurrency_key` | ❌ Not available | ✅ `ctx.concurrency_key` |
+| Access to `arguments` | Manual Hash parsing | ✅ `ctx.arguments.<name>` |
+
+**Separating parent and sub-job concurrency keys:**
+
+When a parent job enqueues sub-jobs (via `enqueue:` option), they share the same job class. With `limits_concurrency`, both parent and sub-jobs resolve to the same concurrency key, which can cause sub-jobs to be discarded. Use `workflow_concurrency` with `ctx.sub_job?` to generate distinct keys:
+
+```ruby
+workflow_concurrency to: 1,
+                     key: lambda { |ctx|
+                       if ctx.sub_job?
+                         # Sub-jobs use a unique key per task iteration
+                         ctx.concurrency_key
+                       else
+                         # Parent job uses a tenant-scoped key
+                         "import:#{ctx.arguments.tenant_id}"
+                       end
+                     },
+                     on_conflict: :discard
+```
+
+**Parameters:**
+- `to:` (Integer): Maximum number of concurrent executions
+- `key:` (Proc): A Proc that receives a `Context` and returns a String used as the concurrency key
+- `on_conflict:` (Symbol, optional): `:discard` to drop duplicate jobs, or omit for default SolidQueue behavior
+- `duration:` (ActiveSupport::Duration, optional): How long the concurrency lock is held
+- `group:` (String, optional): Concurrency group name
+
+> **Note**: `workflow_concurrency` requires SolidQueue. It delegates to `limits_concurrency` internally.
+
 ## Fork-Join Pattern
 
 ### Context Isolation

data/lib/job_workflow/dsl.rb

@@ -165,7 +165,7 @@ module JobWorkflow
         _workflow.add_task(new_task)
         if new_task.enqueue.should_limits_concurrency? # rubocop:disable Style/GuardClause
           concurrency = new_task.enqueue.concurrency #: Integer
-          limits_concurrency(to: concurrency, key: ->(ctx) { ctx.concurrency_key }) # rubocop:disable Style/SymbolProc
+          workflow_concurrency(to: concurrency, key: :concurrency_key.to_proc)
         end
       end
       # rubocop:enable Metrics/ParameterLists
@@ -194,6 +194,50 @@ module JobWorkflow
         _workflow.add_hook(:error, task_names:, block:)
       end
 
+      # Configures concurrency limits for this workflow job.
+      #
+      # Unlike `limits_concurrency` (SolidQueue's raw API), this method passes a
+      # {Context} as the first argument to the key Proc, giving access to
+      # workflow-aware information such as `arguments`, `sub_job?`, and
+      # `concurrency_key`.
+      #
+      # When `_context` is not yet initialized (e.g. during enqueue before
+      # perform), a temporary Context is built from the job's arguments so the
+      # key Proc can always rely on `ctx.arguments`.
+      #
+      # @example Limit duplicate workflow runs by argument
+      #   workflow_concurrency to: 1,
+      #     key: ->(ctx) { "my_job:#{ctx.arguments.tenant_id}" },
+      #     on_conflict: :discard
+      #
+      # @example Separate parent and sub-job concurrency keys
+      #   workflow_concurrency to: 1,
+      #     key: ->(ctx) {
+      #       ctx.sub_job? ? ctx.concurrency_key : "my_job:#{ctx.arguments.name}"
+      #     },
+      #     on_conflict: :discard
+      #
+      #:  (
+      #     to: Integer,
+      #     key: ^(Context) -> String?,
+      #     ?duration: ActiveSupport::Duration?,
+      #     ?group: String?,
+      #     ?on_conflict: Symbol?
+      #   ) -> void
+      def workflow_concurrency(to:, key:, **opts)
+        concurrency_key_proc = key
+        limits_concurrency(
+          to:,
+          key: proc {
+            ctx = _context || Context.from_hash(
+              job: self, workflow: self.class._workflow
+            )._update_arguments((arguments.first || {}).symbolize_keys)
+            concurrency_key_proc.call(ctx)
+          },
+          **opts
+        )
+      end
+
       #:  (?bool) ?{ (Context) -> bool } -> void
       def dry_run(value = nil, &block)
         validate_namespace!

data/lib/job_workflow/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JobWorkflow
-  VERSION = "0.1.3" # : String
+  VERSION = "0.2.0" # : String
 end

data/sig/generated/job_workflow/dsl.rbs

@@ -94,6 +94,38 @@ module JobWorkflow
       # :  (*Symbol) { (Context, StandardError, Task) -> void } -> void
       def on_error: (*Symbol) { (Context, StandardError, Task) -> void } -> void
 
+      # Configures concurrency limits for this workflow job.
+      #
+      # Unlike `limits_concurrency` (SolidQueue's raw API), this method passes a
+      # {Context} as the first argument to the key Proc, giving access to
+      # workflow-aware information such as `arguments`, `sub_job?`, and
+      # `concurrency_key`.
+      #
+      # When `_context` is not yet initialized (e.g. during enqueue before
+      # perform), a temporary Context is built from the job's arguments so the
+      # key Proc can always rely on `ctx.arguments`.
+      #
+      # @example Limit duplicate workflow runs by argument
+      #   workflow_concurrency to: 1,
+      #     key: ->(ctx) { "my_job:#{ctx.arguments.tenant_id}" },
+      #     on_conflict: :discard
+      #
+      # @example Separate parent and sub-job concurrency keys
+      #   workflow_concurrency to: 1,
+      #     key: ->(ctx) {
+      #       ctx.sub_job? ? ctx.concurrency_key : "my_job:#{ctx.arguments.name}"
+      #     },
+      #     on_conflict: :discard
+      #
+      # :  (
+      #     to: Integer,
+      #     key: ^(Context) -> String?,
+      #     ?duration: ActiveSupport::Duration?,
+      #     ?group: String?,
+      #     ?on_conflict: Symbol?
+      #   ) -> void
+      def workflow_concurrency: (to: Integer, key: ^(Context) -> String?, ?duration: ActiveSupport::Duration?, ?group: String?, ?on_conflict: Symbol?) -> void
+
       # :  (?bool) ?{ (Context) -> bool } -> void
       def dry_run: (?bool) ?{ (Context) -> bool } -> void
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: job-workflow
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - shoma07
@@ -184,7 +184,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Declarative workflow orchestration engine for Ruby on Rails
 test_files: []