tasker-engine 1.0.0

data/lib/generators/tasker/templates/devise_authenticator_spec.rb.erb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= class_name %>Authenticator, type: :model do
+  let(:options) { { scope: :user } }
+  let(:authenticator) { described_class.new(options) }
+  let(:controller) { instance_double('ActionController::Base') }
+
+  describe '#initialize' do
+    it 'sets default scope to :user' do
+      authenticator = described_class.new
+      expect(authenticator.send(:scope)).to eq(:user)
+    end
+
+    it 'accepts custom scope' do
+      authenticator = described_class.new(scope: :admin)
+      expect(authenticator.send(:scope)).to eq(:admin)
+    end
+  end
+
+  describe '#authenticate!' do
+    context 'when Devise authentication succeeds' do
+      before do
+        allow(controller).to receive(:authenticate_user!).and_return(true)
+      end
+
+      it 'returns true' do
+        expect(authenticator.authenticate!(controller)).to be true
+      end
+    end
+
+    context 'when Devise authentication fails' do
+      before do
+        allow(controller).to receive(:authenticate_user!).and_raise(StandardError, 'Authentication failed')
+      end
+
+      it 'raises AuthenticationError' do
+        expect do
+          authenticator.authenticate!(controller)
+        end.to raise_error(Tasker::Authentication::AuthenticationError, /Devise authentication failed/)
+      end
+    end
+  end
+
+  describe '#current_user' do
+    let(:user) { double('User', id: 1) }
+
+    context 'when Devise current_user returns a user' do
+      before do
+        allow(controller).to receive(:current_user).and_return(user)
+      end
+
+      it 'returns the user' do
+        expect(authenticator.current_user(controller)).to eq(user)
+      end
+    end
+
+    context 'when Devise current_user returns nil' do
+      before do
+        allow(controller).to receive(:current_user).and_return(nil)
+      end
+
+      it 'returns nil' do
+        expect(authenticator.current_user(controller)).to be_nil
+      end
+    end
+  end
+
+  describe '#authenticated?' do
+    context 'when user_signed_in? is available' do
+      before do
+        allow(controller).to receive(:respond_to?).with(:user_signed_in?).and_return(true)
+        allow(controller).to receive(:user_signed_in?).and_return(true)
+      end
+
+      it 'uses Devise signed_in helper' do
+        expect(authenticator.authenticated?(controller)).to be true
+      end
+    end
+
+    context 'when user_signed_in? is not available' do
+      let(:user) { double('User') }
+
+      before do
+        allow(controller).to receive(:respond_to?).with(:user_signed_in?).and_return(false)
+        allow(authenticator).to receive(:current_user).with(controller).and_return(user)
+      end
+
+      it 'falls back to checking current_user presence' do
+        expect(authenticator.authenticated?(controller)).to be true
+      end
+    end
+  end
+
+  describe '#validate_configuration' do
+    context 'when Devise is available' do
+      before do
+        stub_const('Devise', double('Devise', mappings: { user: double('mapping') }))
+      end
+
+      it 'returns no errors for valid configuration' do
+        errors = authenticator.validate_configuration(scope: :user)
+        expect(errors).to be_empty
+      end
+    end
+
+    context 'when Devise is not available' do
+      before do
+        hide_const('Devise')
+      end
+
+      it 'returns validation error' do
+        errors = authenticator.validate_configuration(options)
+        expect(errors).to include('Devise gem is required for DeviseAuthenticator')
+      end
+    end
+
+    context 'with invalid scope type' do
+      it 'returns validation error' do
+        errors = authenticator.validate_configuration(scope: 'user')
+        expect(errors).to include('Devise scope must be a symbol')
+      end
+    end
+  end
+end

data/lib/generators/tasker/templates/initialize.rb.erb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+# Configure Tasker
+Tasker.configuration do |config|
+  # Engine configuration
+  # config.engine do |engine|
+  #   engine.task_handler_directory = 'custom_tasks'
+  #   engine.task_config_directory = 'custom_tasks'
+  #   engine.default_module_namespace = 'OurTasks'
+  #   engine.identity_strategy = :hash
+  #   engine.identity_strategy_class = 'MyApp::CustomIdentityStrategy'
+  # end
+
+  # Authentication and authorization configuration
+  # config.auth do |auth|
+  #   auth.strategy = :devise
+  #   auth.options = { scope: :user }
+  #   auth.enabled = true
+  #   auth.coordinator_class = 'MyApp::AuthorizationCoordinator'
+  #   auth.user_class = 'User'
+  # end
+
+  # Database configuration
+  # config.database do |db|
+  #   db.enable_secondary_database = true
+  #   db.name = :tasker
+  # end
+
+  # Telemetry and observability configuration
+  # Tasker provides two complementary observability systems:
+  # 1. TelemetrySubscriber (event-driven OpenTelemetry spans for detailed tracing)
+  # 2. MetricsBackend (native metrics collection for dashboards and alerting)
+  # config.telemetry do |tel|
+  #   # === OPENTELEMETRY SPANS (Event-Driven Tracing) ===
+  #   tel.enabled = true                              # Enable TelemetrySubscriber
+  #   tel.service_name = 'my_app_tasker'
+  #   tel.service_version = '1.2.3'
+  #
+  #   # === STRUCTURED LOGGING ===
+  #   tel.structured_logging_enabled = true
+  #   tel.correlation_id_header = 'X-Correlation-ID'  # HTTP header for correlation ID propagation
+  #   tel.log_level = 'info'                          # debug, info, warn, error, fatal
+  #   tel.log_format = 'json'                         # json, pretty_json, logfmt
+  #
+  #   # === SENSITIVE DATA FILTERING ===
+  #   tel.filter_mask = '***REDACTED***'
+  #   tel.filter_parameters = [:password, :api_key, 'credit_card.number', /token/i]
+  #
+  #   # === NATIVE METRICS COLLECTION (Direct Collection) ===
+  #   tel.metrics_enabled = true                      # Enable MetricsBackend
+  #   tel.metrics_format = 'prometheus'               # 'prometheus', 'json', 'csv'
+  #
+  #   # Prometheus export configuration (matches TelemetryConfig.default_prometheus_config)
+  #   tel.prometheus = {
+  #     endpoint: ENV['PROMETHEUS_ENDPOINT'],         # Prometheus remote write endpoint (nil disables)
+  #
+  #     # Basic authentication for Prometheus endpoint
+  #     username: ENV['PROMETHEUS_USERNAME'],
+  #     password: ENV['PROMETHEUS_PASSWORD'],
+  #
+  #     # Job configuration
+  #     job_timeout: 5.minutes,
+  #     export_timeout: 2.minutes,
+  #     retry_attempts: 3,
+  #
+  #     # Export scheduling
+  #     retention_window: 5.minutes,                 # How long metrics are retained before TTL expiry
+  #     safety_margin: 1.minute,                     # Export before TTL expires (safety buffer)
+  #
+  #     # Metric naming
+  #     metric_prefix: 'tasker',
+  #     include_instance_labels: true,
+  #
+  #     # Performance tuning
+  #     compression: 'snappy',                       # 'snappy', 'gzip', or nil
+  #     batch_size: 1000,
+  #
+  #     # Test/development mode
+  #     skip_if_unavailable: true                    # Don't fail if Prometheus is unreachable
+  #   }
+  #
+  #   # === PERFORMANCE MONITORING ===
+  #   tel.performance_monitoring_enabled = true
+  #   tel.slow_query_threshold_seconds = 1.0         # Detect slow operations
+  #   tel.memory_threshold_mb = 100                   # Memory spike detection
+  #   tel.event_sampling_rate = 1.0                   # 1.0 = 100%, 0.1 = 10% sampling
+  #   tel.filtered_events = []                        # Events to exclude from collection
+  # end
+
+  # Dependency graph and bottleneck analysis configuration
+  # These settings control how Tasker analyzes workflow dependencies,
+  # identifies bottlenecks, and calculates impact scores for optimization.
+  # config.dependency_graph do |graph|
+  #   # Impact multipliers for bottleneck scoring calculations
+  #   # These affect how different factors influence bottleneck impact scores
+  #   graph.impact_multipliers = {
+  #     downstream_weight: 5,      # Weight for downstream step count (higher = more impact)
+  #     blocked_weight: 15,        # Weight for blocked step count (higher = more critical)
+  #     path_length_weight: 10,    # Weight for critical path length
+  #     completed_penalty: 15,     # Penalty for completed steps (reduce priority)
+  #     blocked_penalty: 25,       # Penalty for blocked steps (increase priority)
+  #     error_penalty: 30,         # Penalty for error steps (highest priority)
+  #     retry_penalty: 10          # Penalty for retry steps (moderate priority)
+  #   }
+  #
+  #   # Severity multipliers for state-based calculations
+  #   # These adjust impact scores based on step states and conditions
+  #   graph.severity_multipliers = {
+  #     error_state: 2.0,          # Multiplier for steps in error state
+  #     exhausted_retry_bonus: 0.5, # Additional multiplier for exhausted retries
+  #     dependency_issue: 1.2       # Multiplier for dependency-related issues
+  #   }
+  #
+  #   # Penalty constants for problematic step conditions
+  #   # These add penalty points for specific retry and failure conditions
+  #   graph.penalty_constants = {
+  #     retry_instability: 3,      # Points per retry attempt (instability indicator)
+  #     non_retryable: 10,         # Points for non-retryable failures
+  #     exhausted_retry: 20        # Points for exhausted retry attempts
+  #   }
+  #
+  #   # Severity thresholds for impact score classification
+  #   # These determine when bottlenecks are classified as Critical/High/Medium/Low
+  #   graph.severity_thresholds = {
+  #     critical: 100,             # Score >= 100: Critical bottleneck
+  #     high: 50,                  # Score >= 50: High priority bottleneck
+  #     medium: 20                 # Score >= 20: Medium priority bottleneck
+  #   }                            # Score < 20: Low priority
+  #
+  #   # Duration estimation constants for path analysis
+  #   # These are used for calculating estimated execution times
+  #   graph.duration_estimates = {
+  #     base_step_seconds: 30,     # Estimated time per step (default)
+  #     error_penalty_seconds: 60, # Additional time penalty for error steps
+  #     retry_penalty_seconds: 30  # Additional time penalty per retry attempt
+  #   }
+  # end
+
+  # Execution and performance configuration
+  # These settings control concurrent step execution, memory management,
+  # and timeout behavior for optimal performance and system tuning.
+  # config.execution do |exec|
+  #   # === CONCURRENCY SETTINGS ===
+  #   # These control dynamic concurrency calculation bounds
+  #   exec.min_concurrent_steps = 3           # Conservative lower bound for system stability
+  #   exec.max_concurrent_steps_limit = 12    # Upper bound (should align with DB connection pool)
+  #   exec.concurrency_cache_duration = 30    # Cache duration in seconds for concurrency calculations
+  #
+  #   # === TIMEOUT CONFIGURATION ===
+  #   # These control batch execution timeouts with automatic calculation
+  #   exec.batch_timeout_base_seconds = 30    # Base timeout before per-step adjustments
+  #   exec.batch_timeout_per_step_seconds = 5 # Additional timeout per step in batch
+  #   exec.max_batch_timeout_seconds = 120    # Absolute maximum timeout cap
+  #
+  #   # === ARCHITECTURAL CONSTANTS (Ruby-specific, not configurable) ===
+  #   # These are set based on Ruby/Rails characteristics and should not be changed:
+  #   # - future_cleanup_wait_seconds: 1 second (optimal for Concurrent::Future cleanup)
+  #   # - gc_trigger_batch_size_threshold: 6 operations (Ruby memory pressure detection)
+  #   # - gc_trigger_duration_threshold: 30 seconds (Ruby GC timing characteristics)
+  # end
+
+  # Backoff and retry configuration
+  # These settings control retry timing, exponential backoff calculations,
+  # and task reenqueue delays for optimal failure recovery.
+  # config.backoff do |backoff|
+  #   # Default backoff progression for retry attempts (in seconds)
+  #   # Each element represents the backoff time for that attempt number.
+  #   # For attempts beyond this array, exponential backoff calculation is used.
+  #   backoff.default_backoff_seconds = [1, 2, 4, 8, 16, 32]
+  #
+  #   # Maximum backoff time to cap exponential backoff calculations
+  #   # Prevents excessively long delays between retry attempts
+  #   backoff.max_backoff_seconds = 300  # 5 minutes maximum
+  #
+  #   # Multiplier for exponential backoff calculation
+  #   # Formula: backoff_time = attempt_number ^ backoff_multiplier * base_seconds
+  #   backoff.backoff_multiplier = 2.0
+  #
+  #   # Whether to apply jitter to backoff calculations
+  #   # Helps prevent "thundering herd" when many steps retry simultaneously
+  #   backoff.jitter_enabled = true
+  #
+  #   # Maximum jitter percentage for randomization
+  #   # E.g., 0.1 means ±10% variation in backoff times
+  #   backoff.jitter_max_percentage = 0.1
+  #
+  #   # Task reenqueue delays for different execution states
+  #   # Controls how long to wait before retrying tasks in different states
+  #   backoff.reenqueue_delays = {
+  #     has_ready_steps: 0,              # Steps ready - immediate processing
+  #     waiting_for_dependencies: 45,    # Waiting for dependencies - moderate delay
+  #     processing: 10                   # Steps processing - short delay
+  #   }
+  #
+  #   # Default reenqueue delay for unclear or unmatched states
+  #   backoff.default_reenqueue_delay = 30
+  #
+  #   # Buffer time added to optimal backoff calculations
+  #   # Ensures steps are definitely ready for retry when tasks are reenqueued
+  #   backoff.buffer_seconds = 5
+  # end
+end

data/lib/generators/tasker/templates/jwt_authenticator.rb.erb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# JWT authenticator for <%= class_name %>
+# Generated by: rails generate tasker:authenticator <%= file_name %> --type=jwt
+#
+# This authenticator implements JWT-based authentication with security best practices.
+# Supports both Bearer token and raw token formats in Authorization headers.
+#
+# Configuration example:
+#   Tasker.configuration do |config|
+#     config.auth do |auth|
+#       auth.strategy = :custom
+#       auth.options = {
+#         authenticator_class: '<%= class_name %>Authenticator',
+#         secret: Rails.application.credentials.jwt_secret,
+#         algorithm: 'HS256',
+#         header_name: 'Authorization',
+#         user_class: '<%= user_model_class %>'
+#       }
+#     end
+#   end
+
+class <%= class_name %>Authenticator
+  include Tasker::Authentication::Interface
+
+  def initialize(options = {})
+    @secret = options[:secret] || Rails.application.secret_key_base
+    @algorithm = options[:algorithm] || 'HS256'
+    @header_name = options[:header_name] || 'Authorization'
+    @user_class = options[:user_class] || '<%= user_model_class %>'
+  end
+
+  # Required: Authenticate the request, raise exception if fails
+  def authenticate!(controller)
+    user = current_user(controller)
+    unless user
+      raise Tasker::Authentication::AuthenticationError,
+            'Invalid or missing JWT token'
+    end
+    true
+  end
+
+  # Required: Get the current authenticated user
+  def current_user(controller)
+    return @current_user if defined?(@current_user)
+
+    @current_user = begin
+      token = extract_token(controller.request)
+      return nil unless token
+
+      payload = decode_token(token)
+      return nil unless payload
+
+      find_user(payload)
+    rescue JWT::DecodeError, StandardError => e
+      Rails.logger.debug "JWT authentication failed: #{e.message}"
+      nil
+    end
+  end
+
+  # Optional: Configuration validation with security best practices
+  def validate_configuration(options = {})
+    errors = []
+
+    # Validate JWT secret
+    secret = options[:secret]
+    if secret.blank?
+      errors << 'JWT secret is required'
+    elsif secret.length < 32
+      errors << 'JWT secret should be at least 32 characters for security'
+    end
+
+    # Validate algorithm
+    algorithm = options[:algorithm] || 'HS256'
+    allowed_algorithms = %w[HS256 HS384 HS512 RS256 RS384 RS512 ES256 ES384 ES512]
+    unless allowed_algorithms.include?(algorithm)
+      errors << "JWT algorithm must be one of: #{allowed_algorithms.join(', ')}"
+    end
+
+    # Validate user class
+    user_class = options[:user_class] || '<%= user_model_class %>'
+    begin
+      user_class.constantize
+    rescue NameError
+      errors << "User class '#{user_class}' not found"
+    end
+
+    errors
+  end
+
+  # Helper method for generating test tokens (useful for testing)
+  def self.generate_test_token(payload, secret: nil, algorithm: 'HS256')
+    secret ||= Rails.application.secret_key_base
+
+    # Add standard JWT claims
+    now = Time.current.to_i
+    full_payload = {
+      'iat' => now,
+      'exp' => now + 1.hour.to_i
+    }.merge(payload.stringify_keys)
+
+    JWT.encode(full_payload, secret, algorithm)
+  end
+
+  private
+
+  attr_reader :secret, :algorithm, :header_name, :user_class
+
+  def extract_token(request)
+    header = request.headers[@header_name]
+    return nil unless header.present?
+
+    # Support both "Bearer <token>" and raw token formats
+    header.start_with?('Bearer ') ? header.sub(/^Bearer /, '') : header
+  end
+
+  def decode_token(token)
+    payload, _header = JWT.decode(
+      token,
+      @secret,
+      true, # verify signature
+      {
+        algorithm: @algorithm,
+        verify_expiration: true,
+        verify_iat: true
+      }
+    )
+    payload
+  rescue JWT::ExpiredSignature, JWT::InvalidIatError
+    # These are expected errors for expired tokens
+    nil
+  end
+
+  def find_user(payload)
+    # Support both 'user_id' and 'sub' (subject) claims
+    user_id = payload['user_id'] || payload['sub']
+    return nil unless user_id
+
+    user_model = @user_class.constantize
+    user_model.find_by(id: user_id)
+  rescue ActiveRecord::RecordNotFound, NoMethodError
+    nil
+  end
+end