job-workflow 0.1.3

data/sig/generated/job_workflow/cache_store_adapters.rbs

@@ -0,0 +1,28 @@
+# Generated from lib/job_workflow/cache_store_adapters.rb with RBS::Inline
+
+module JobWorkflow
+  module CacheStoreAdapters
+    NAMESPACE: String
+
+    DEFAULT_OPTIONS: Hash[Symbol, untyped]
+
+    def self._current: () -> ActiveSupport::Cache::Store
+
+    def self._current=: (ActiveSupport::Cache::Store?) -> void
+
+    # :  () -> ActiveSupport::Cache::Store
+    def self.current: () -> ActiveSupport::Cache::Store
+
+    # :  () -> void
+    def self.reset!: () -> void
+
+    # @note
+    #   - Rails.cache is NOT used directly because JobWorkflow requires namespace isolation from the Rails application's cache store.
+    #   - JobWorkflow caches are namespaced with "job_workflow" prefix to prevent key collisions with application-level caches.
+    #   - Using Rails.cache would share namespace configuration with the Rails app, which could lead to conflicts or unintended cache invalidations.
+    #   - Instead, JobWorkflow creates dedicated ActiveSupport::Cache::Store instances with explicit namespace options.
+    #
+    # :  () -> ActiveSupport::Cache::Store
+    private def self.detect_adapter: () -> ActiveSupport::Cache::Store
+  end
+end

data/sig/generated/job_workflow/context.rbs

@@ -0,0 +1,155 @@
+# Generated from lib/job_workflow/context.rb with RBS::Inline
+
+module JobWorkflow
+  class Context
+    # rubocop:disable Metrics/ClassLength
+    attr_reader workflow: Workflow
+
+    attr_reader arguments: Arguments
+
+    attr_reader output: Output
+
+    attr_reader job_status: JobStatus
+
+    # :  (Hash[Symbol, untyped]) -> Context
+    def self.from_hash: (Hash[Symbol, untyped]) -> Context
+
+    # :  (Hash[String, untyped]) -> Context
+    def self.deserialize: (Hash[String, untyped]) -> Context
+
+    # :  (
+    #      workflow: Workflow,
+    #      arguments: Arguments,
+    #      task_context: TaskContext,
+    #      output: Output,
+    #      job_status: JobStatus,
+    #      ?job: DSL?
+    #    ) -> void
+    def initialize: (workflow: Workflow, arguments: Arguments, task_context: TaskContext, output: Output, job_status: JobStatus, ?job: DSL?) -> void
+
+    # :  () -> Hash[String, untyped]
+    def serialize: () -> Hash[String, untyped]
+
+    # :  (Hash[Symbol, untyped]) -> Context
+    def _update_arguments: (Hash[Symbol, untyped]) -> Context
+
+    # :  (DSL) -> void
+    def _job=: (DSL) -> void
+
+    # :  () -> DSL?
+    def _job: () -> DSL?
+
+    # :  () -> String
+    def job_id: () -> String
+
+    # :  () -> bool
+    def sub_job?: () -> bool
+
+    # :  () -> String?
+    def concurrency_key: () -> String?
+
+    # :  (Task) -> Enumerator[Context]
+    def _with_each_value: (Task) -> Enumerator[Context]
+
+    # :  () { () -> void } -> void
+    def _with_task_throttle: () { () -> void } -> void
+
+    # :  (limit: Integer, ?key: String?, ?ttl: Integer) { () -> void } -> void
+    def throttle: (limit: Integer, ?key: String?, ?ttl: Integer) { () -> void } -> void
+
+    # Instruments a custom operation with ActiveSupport::Notifications.
+    # This creates a span in OpenTelemetry (if enabled) and logs the event.
+    #
+    # @example Basic usage
+    #   ```ruby
+    #   ctx.instrument("api_call", endpoint: "/users") do
+    #     HTTP.get("https://api.example.com/users")
+    #   end
+    #   ```
+    #
+    # @example With automatic operation name
+    #   ```ruby
+    #   ctx.instrument do
+    #     # operation name defaults to "custom"
+    #     expensive_operation()
+    #   end
+    #   ```
+    #
+    # :  (?String, **untyped) { () -> untyped } -> untyped
+    def instrument: (?String, **untyped) { () -> untyped } -> untyped
+
+    # :  () -> bool
+    def dry_run?: () -> bool
+
+    # :  (?Symbol?, ?fallback: untyped) { () -> untyped } -> untyped
+    def skip_in_dry_run: (?Symbol?, ?fallback: untyped) { () -> untyped } -> untyped
+
+    # :  () -> untyped
+    def each_value: () -> untyped
+
+    # :  () -> TaskOutput?
+    def each_task_output: () -> TaskOutput?
+
+    # :  () -> TaskContext
+    def _task_context: () -> TaskContext
+
+    # :  (TaskOutput) -> void
+    def _add_task_output: (TaskOutput) -> void
+
+    # :  () -> void
+    def _load_parent_task_output: () -> void
+
+    private
+
+    attr_accessor job: DSL?
+
+    attr_writer workflow: Workflow
+
+    attr_writer arguments: Arguments
+
+    attr_writer output: Output
+
+    attr_writer job_status: JobStatus
+
+    attr_accessor task_context: TaskContext
+
+    attr_accessor enabled_with_each_value: bool
+
+    attr_accessor throttle_index: Integer
+
+    attr_accessor skip_in_dry_run_index: Integer
+
+    # :  () -> String
+    def parent_job_id: () -> String
+
+    # :  () -> Hash[String, untyped]
+    def serialize_for_job: () -> Hash[String, untyped]
+
+    # :  () -> Hash[String, untyped]
+    def serialize_for_sub_job: () -> Hash[String, untyped]
+
+    # :  (Task, Enumerator::Yielder) -> void
+    def with_task_context: (Task, Enumerator::Yielder) -> void
+
+    # :  (Task) -> void
+    def reset_task_context_if_task_changed: (Task) -> void
+
+    # :  (Task) { (untyped, Integer) -> void } -> void
+    def with_each_index_and_value: (Task) { (untyped, Integer) -> void } -> void
+
+    # :  () -> void
+    def clear_after_each_index_and_value: () -> void
+
+    # :  () { () -> void } -> void
+    def with_task_timeout: () { () -> void } -> void
+
+    # :  (Task) { (Integer) -> void } -> void
+    def with_retry: (Task) { (Integer) -> void } -> void
+
+    # :  (Task, TaskRetry, Integer, StandardError) -> void
+    def wait_next_retry: (Task, TaskRetry, Integer, StandardError) -> void
+
+    # :  (Task) -> bool
+    def calculate_dry_run: (Task) -> bool
+  end
+end

data/sig/generated/job_workflow/dry_run_config.rbs

@@ -0,0 +1,16 @@
+# Generated from lib/job_workflow/dry_run_config.rb with RBS::Inline
+
+module JobWorkflow
+  class DryRunConfig
+    attr_reader evaluator: ^(Context) -> bool
+
+    # :  (bool | ^(Context) -> bool | nil) -> DryRunConfig
+    def self.from_primitive_value: (bool | ^(Context) -> bool | nil) -> DryRunConfig
+
+    # :  (?evaluator: ^(Context) -> bool) -> void
+    def initialize: (?evaluator: ^(Context) -> bool) -> void
+
+    # :  (Context) -> bool
+    def evaluate: (Context) -> bool
+  end
+end

data/sig/generated/job_workflow/dsl.rbs

@@ -0,0 +1,117 @@
+# Generated from lib/job_workflow/dsl.rb with RBS::Inline
+
+module JobWorkflow
+  module DSL
+    extend ActiveSupport::Concern
+
+    include ActiveJob::Continuable
+
+    extend ClassMethods
+
+    def self._included_classes: () -> Set[singleton(DSL)]
+
+    def class: () -> ClassMethods
+
+    def job_id: () -> String
+
+    def queue_name: () -> String
+
+    def set: (Hash[Symbol, untyped]) -> self
+
+    def step: (Symbol, ?start: ActiveJob::Continuation::_Succ, ?isolated: bool) -> void
+            | (Symbol, ?start: ActiveJob::Continuation::_Succ, ?isolated: bool) { (ActiveJob::Continuation::Step) -> void } -> void
+
+    # :  (Hash[untyped, untyped]) -> void
+    def perform: (Hash[untyped, untyped]) -> void
+
+    # :  () -> Output
+    def output: () -> Output
+
+    # :  (Context) -> void
+    def _context=: (Context) -> void
+
+    # :  () -> Context?
+    def _context: () -> Context?
+
+    # :  () -> Hash[String, untyped]
+    def serialize: () -> Hash[String, untyped]
+
+    # :  (Hash[String, untyped]) -> void
+    def deserialize: (Hash[String, untyped]) -> void
+
+    module ClassMethods
+      def class_attribute: (Symbol, default: untyped) -> void
+
+      def _workflow: () -> Workflow
+
+      def new: (Hash[untyped, untyped]) -> DSL
+
+      def name: () -> String
+
+      def enqueue: (Hash[untyped, untyped]) -> void
+
+      def queue_name: () -> String
+
+      def queue_as: () -> String
+
+      def limits_concurrency: (to: Integer, key: ^(untyped) -> untyped, ?duration: ActiveSupport::Duration?, ?group: String?, ?on_conflict: Symbol?) -> void
+
+      # :  (Context) -> DSL
+      def from_context: (Context) -> DSL
+
+      # :  (Symbol argument_name, String type, ?default: untyped) -> void
+      def argument: (Symbol argument_name, String type, ?default: untyped) -> void
+
+      # :  (Symbol) { () -> void } -> void
+      def namespace: (Symbol) { () -> void } -> void
+
+      # rubocop:disable Metrics/ParameterLists
+      #
+      # :  (
+      #     Symbol task_name,
+      #     ?each: ^(Context) -> untyped,
+      #     ?enqueue: true | false | ^(Context) -> bool | Hash[Symbol, untyped],
+      #     ?retry: Integer | Hash[Symbol, untyped],
+      #     ?output: Hash[Symbol, String],
+      #     ?depends_on: Array[Symbol],
+      #     ?condition: ^(Context) -> bool,
+      #     ?throttle: Integer | Hash[Symbol, untyped],
+      #     ?timeout: Numeric?,
+      #     ?dependency_wait: Hash[Symbol, untyped],
+      #     ?dry_run: bool | ^(Context) -> bool
+      #   ) { (untyped) -> void } -> void
+      def task: (Symbol task_name, ?each: ^(Context) -> untyped, ?enqueue: true | false | ^(Context) -> bool | Hash[Symbol, untyped], ?retry: Integer | Hash[Symbol, untyped], ?output: Hash[Symbol, String], ?depends_on: Array[Symbol], ?condition: ^(Context) -> bool, ?throttle: Integer | Hash[Symbol, untyped], ?timeout: Numeric?, ?dependency_wait: Hash[Symbol, untyped], ?dry_run: bool | ^(Context) -> bool) { (untyped) -> void } -> void
+
+      # :  (*Symbol) { (Context) -> void } -> void
+      def before: (*Symbol) { (Context) -> void } -> void
+
+      # :  (*Symbol) { (Context) -> void } -> void
+      def after: (*Symbol) { (Context) -> void } -> void
+
+      # :  (*Symbol) { (Context, TaskCallable) -> void } -> void
+      def around: (*Symbol) { (Context, TaskCallable) -> void } -> void
+
+      # :  (*Symbol) { (Context, StandardError, Task) -> void } -> void
+      def on_error: (*Symbol) { (Context, StandardError, Task) -> void } -> void
+
+      # :  (?bool) ?{ (Context) -> bool } -> void
+      def dry_run: (?bool) ?{ (Context) -> bool } -> void
+
+      # rubocop:disable Metrics/ParameterLists
+      # :  (
+      #     String expression,
+      #     ?key: (String | Symbol)?,
+      #     ?queue: String?,
+      #     ?priority: Integer?,
+      #     ?args: Hash[Symbol, untyped],
+      #     ?description: String?
+      #   ) -> void
+      def schedule: (String expression, ?key: (String | Symbol)?, ?queue: String?, ?priority: Integer?, ?args: Hash[Symbol, untyped], ?description: String?) -> void
+
+      private
+
+      # :  () -> void
+      def validate_namespace!: () -> void
+    end
+  end
+end

data/sig/generated/job_workflow/error_hook.rbs

@@ -0,0 +1,18 @@
+# Generated from lib/job_workflow/error_hook.rb with RBS::Inline
+
+module JobWorkflow
+  class ErrorHook
+    attr_reader task_names: Set[Symbol]
+
+    attr_reader block: ^(Context, StandardError, Task) -> void
+
+    # :  (task_names: Array[Symbol], block: ^(Context, StandardError, Task) -> void) -> void
+    def initialize: (task_names: Array[Symbol], block: ^(Context, StandardError, Task) -> void) -> void
+
+    # :  (Symbol) -> bool
+    def applies_to?: (Symbol) -> bool
+
+    # :  () -> bool
+    def global?: () -> bool
+  end
+end

data/sig/generated/job_workflow/hook.rbs

@@ -0,0 +1,18 @@
+# Generated from lib/job_workflow/hook.rb with RBS::Inline
+
+module JobWorkflow
+  class Hook
+    attr_reader task_names: Set[Symbol]
+
+    attr_reader block: ^(Context, ?TaskCallable) -> void
+
+    # :  (task_names: Array[Symbol], block: ^(Context, ?TaskCallable) -> void) -> void
+    def initialize: (task_names: Array[Symbol], block: ^(Context, ?TaskCallable) -> void) -> void
+
+    # :  (Symbol) -> bool
+    def applies_to?: (Symbol) -> bool
+
+    # :  () -> bool
+    def global?: () -> bool
+  end
+end

data/sig/generated/job_workflow/hook_registry.rbs

@@ -0,0 +1,47 @@
+# Generated from lib/job_workflow/hook_registry.rb with RBS::Inline
+
+module JobWorkflow
+  class HookRegistry
+    # :  () -> void
+    def initialize: () -> void
+
+    # :  (task_names: Array[Symbol], block: ^(Context, ?TaskCallable) -> void) -> void
+    def add_before_hook: (task_names: Array[Symbol], block: ^(Context, ?TaskCallable) -> void) -> void
+
+    # :  (task_names: Array[Symbol], block: ^(Context, ?TaskCallable) -> void) -> void
+    def add_after_hook: (task_names: Array[Symbol], block: ^(Context, ?TaskCallable) -> void) -> void
+
+    # :  (task_names: Array[Symbol], block: ^(Context, ?TaskCallable) -> void) -> void
+    def add_around_hook: (task_names: Array[Symbol], block: ^(Context, ?TaskCallable) -> void) -> void
+
+    # :  (task_names: Array[Symbol], block: ^(Context, StandardError, Task) -> void) -> void
+    def add_error_hook: (task_names: Array[Symbol], block: ^(Context, StandardError, Task) -> void) -> void
+
+    # :  (Symbol) -> Array[Hook]
+    def before_hooks_for: (Symbol) -> Array[Hook]
+
+    # :  (Symbol) -> Array[Hook]
+    def after_hooks_for: (Symbol) -> Array[Hook]
+
+    # :  (Symbol) -> Array[Hook]
+    def around_hooks_for: (Symbol) -> Array[Hook]
+
+    # :  (Symbol) -> Array[ErrorHook]
+    def error_hooks_for: (Symbol) -> Array[ErrorHook]
+
+    private
+
+    attr_accessor before_hooks: Array[Hook]
+
+    attr_accessor after_hooks: Array[Hook]
+
+    attr_accessor around_hooks: Array[Hook]
+
+    attr_accessor error_hooks: Array[ErrorHook]
+
+    # :  (Array[Hook], Symbol) -> Array[Hook]
+    # :  (Array[ErrorHook], Symbol) -> Array[ErrorHook]
+    def hooks_for: (Array[Hook], Symbol) -> Array[Hook]
+                 | (Array[ErrorHook], Symbol) -> Array[ErrorHook]
+  end
+end

data/sig/generated/job_workflow/instrumentation/log_subscriber.rbs

@@ -0,0 +1,102 @@
+# Generated from lib/job_workflow/instrumentation/log_subscriber.rb with RBS::Inline
+
+module JobWorkflow
+  module Instrumentation
+    # LogSubscriber handles JobWorkflow instrumentation events and produces structured JSON logs.
+    # It subscribes to ActiveSupport::Notifications events and formats them for logging.
+    #
+    # @example Enable log subscriber
+    #   ```ruby
+    #   JobWorkflow::Instrumentation::LogSubscriber.attach_to(:job_workflow)
+    #   ```
+    class LogSubscriber < ActiveSupport::LogSubscriber
+      # :  () -> void
+      def self.attach!: () -> void
+
+      type log_level = :debug | :info | :warn | :error
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def workflow: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def workflow_start: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def workflow_complete: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def task: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def task_start: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def task_complete: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def task_error: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def task_skip: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def task_enqueue: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def task_retry: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def throttle_acquire: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def throttle_acquire_start: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def throttle_acquire_complete: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def throttle_release: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def dependent_wait: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def dependent_wait_start: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def dependent_wait_complete: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def queue_pause: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def queue_resume: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def dry_run: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def dry_run_skip: (ActiveSupport::Notifications::Event) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> void
+      def dry_run_execute: (ActiveSupport::Notifications::Event) -> void
+
+      private
+
+      # :  (ActiveSupport::Notifications::Event, log_level) -> void
+      def log_event: (ActiveSupport::Notifications::Event, log_level) -> void
+
+      # :  (ActiveSupport::Notifications::Event) -> Hash[Symbol, untyped]
+      def build_log_payload: (ActiveSupport::Notifications::Event) -> Hash[Symbol, untyped]
+
+      # :  (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+      def extract_loggable_attributes: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
+      # :  (Hash[Symbol, untyped], Hash[Symbol, untyped]) -> void
+      def add_error_attributes: (Hash[Symbol, untyped], Hash[Symbol, untyped]) -> void
+
+      # :  (log_level, Hash[Symbol, untyped]) -> void
+      def send_log: (log_level, Hash[Symbol, untyped]) -> void
+    end
+  end
+end

data/sig/generated/job_workflow/instrumentation/opentelemetry_subscriber.rbs

@@ -0,0 +1,113 @@
+# Generated from lib/job_workflow/instrumentation/opentelemetry_subscriber.rb with RBS::Inline
+
+module JobWorkflow
+  module Instrumentation
+    # OpenTelemetrySubscriber provides OpenTelemetry tracing integration for JobWorkflow events.
+    # It subscribes to ActiveSupport::Notifications and creates OpenTelemetry spans.
+    #
+    # @example Enable OpenTelemetry integration
+    #   ```ruby
+    #   # Ensure OpenTelemetry is configured first
+    #   OpenTelemetry::SDK.configure do |c|
+    #     c.service_name = "my-app"
+    #   end
+    #
+    #   # Then subscribe JobWorkflow events
+    #   JobWorkflow::Instrumentation::OpenTelemetrySubscriber.subscribe!
+    #   ```
+    #
+    # @note This subscriber requires the opentelemetry-api gem to be installed.
+    #   If not available, subscription will be silently skipped.
+    class OpenTelemetrySubscriber
+      # rubocop:disable Metrics/ClassLength
+      module Attributes
+        JOB_NAME: String
+
+        JOB_ID: String
+
+        TASK_NAME: String
+
+        TASK_EACH_INDEX: String
+
+        TASK_RETRY_COUNT: String
+
+        WORKFLOW_NAME: String
+
+        ERROR_CLASS: String
+
+        ERROR_MESSAGE: String
+
+        CONCURRENCY_KEY: String
+
+        CONCURRENCY_LIMIT: String
+      end
+
+      SUBSCRIBED_EVENTS: untyped
+
+      def self.subscriptions: () -> Array[untyped]
+
+      def self.subscriptions=: (Array[untyped]) -> void
+
+      # :  () -> Array[untyped]?
+      def self.subscribe!: () -> Array[untyped]?
+
+      # :  () -> void
+      def self.unsubscribe!: () -> void
+
+      # :  () -> void
+      def self.reset!: () -> void
+
+      # :  () -> bool
+      def self.opentelemetry_available?: () -> bool
+
+      # :  (String, String, Hash[Symbol, untyped]) -> void
+      def start: (String, String, Hash[Symbol, untyped]) -> void
+
+      # :  (String, String, Hash[Symbol, untyped]) -> void
+      def finish: (String, String, Hash[Symbol, untyped]) -> void
+
+      private
+
+      # :  (Hash[Symbol, untyped]) -> Array[untyped?]
+      def extract_otel_info: (Hash[Symbol, untyped]) -> Array[untyped?]
+
+      def start_span: (untyped name, untyped payload) -> untyped
+
+      # :  (untyped) -> untyped
+      def attach_span_context: (untyped) -> untyped
+
+      # :  (Hash[Symbol, untyped], untyped, untyped) -> void
+      def store_span_info: (Hash[Symbol, untyped], untyped, untyped) -> void
+
+      # :  (Hash[Symbol, untyped], untyped) -> void
+      def handle_exception: (Hash[Symbol, untyped], untyped) -> void
+
+      # :  (untyped, untyped) -> void
+      def finish_span: (untyped, untyped) -> void
+
+      # :  (untyped) -> void
+      def finish_span_safe: (untyped) -> void
+
+      # :  (untyped) -> void
+      def detach_context_safe: (untyped) -> void
+
+      # :  (String, Hash[Symbol, untyped]) -> String
+      def build_span_name: (String, Hash[Symbol, untyped]) -> String
+
+      # :  (Hash[Symbol, untyped]) -> Hash[String, untyped]
+      def build_attributes: (Hash[Symbol, untyped]) -> Hash[String, untyped]
+
+      # :  (Hash[String, untyped], Hash[Symbol, untyped]) -> void
+      def add_error_attributes: (Hash[String, untyped], Hash[Symbol, untyped]) -> void
+
+      # :  (String) -> Symbol
+      def determine_span_kind: (String) -> Symbol
+
+      # :  () -> untyped
+      def tracer: () -> untyped
+
+      # :  (StandardError) -> void
+      def handle_error: (StandardError) -> void
+    end
+  end
+end