tasker-engine 1.0.0

data/lib/generators/tasker/subscriber_generator.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Tasker
+  module Generators
+    class SubscriberGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Generate a new Tasker event subscriber'
+
+      class_option :events, type: :array, default: [],
+                            desc: 'Events to subscribe to (e.g., task.completed step.failed)'
+
+      class_option :directory, type: :string, default: 'app/subscribers',
+                               desc: 'Directory to place the subscriber'
+
+      class_option :metrics, type: :boolean, default: false,
+                             desc: 'Generate a specialized metrics collection subscriber'
+
+      def create_subscriber_file
+        if options[:metrics]
+          template 'metrics_subscriber.rb.erb', File.join(options[:directory], "#{file_name}_subscriber.rb")
+        else
+          template 'subscriber.rb.erb', File.join(options[:directory], "#{file_name}_subscriber.rb")
+        end
+      end
+
+      def create_spec_file
+        return unless defined?(RSpec)
+
+        if options[:metrics]
+          template 'metrics_subscriber_spec.rb.erb', File.join('spec', 'subscribers', "#{file_name}_subscriber_spec.rb")
+        else
+          template 'subscriber_spec.rb.erb', File.join('spec', 'subscribers', "#{file_name}_subscriber_spec.rb")
+        end
+      end
+
+      def show_usage_instructions
+        say "\n#{set_color('Subscriber created successfully!', :green)}"
+
+        if options[:metrics]
+          say "\n#{set_color('Metrics subscriber features:', :cyan)}"
+          say '  - Built-in helper methods for extracting timing, error, and performance metrics'
+          say '  - Automatic tag generation for categorization'
+          say '  - Examples for StatsD, DataDog, Prometheus, and other metrics systems'
+          say '  - Safe numeric value extraction with defaults'
+        end
+
+        say "\nTo register your subscriber, add this to an initializer:"
+        say set_color("  #{class_name}Subscriber.subscribe(Tasker::Events::Publisher.instance)", :cyan)
+
+        if options[:events].any?
+          say "\nYour subscriber will handle these events:"
+          options[:events].each do |event|
+            method_name = "handle_#{event.tr('.', '_')}"
+            say set_color("  #{event} -> #{method_name}", :yellow)
+          end
+        end
+
+        say "\nAvailable events can be viewed with:"
+        say set_color('  Tasker::Events.catalog.keys', :cyan)
+
+        return unless options[:metrics]
+
+        say "\n#{set_color('Metrics collection examples:', :green)}"
+        say '  - Task completion rates and durations'
+        say '  - Error categorization and retry patterns'
+        say '  - Performance monitoring and resource usage'
+        say '  - Business metrics with proper tagging'
+      end
+
+      private
+
+      def file_name
+        @file_name ||= name.underscore
+      end
+
+      def class_name
+        @class_name ||= name.camelize
+      end
+
+      def subscribed_events
+        if options[:metrics] && options[:events].empty?
+          # Default to common metrics events if none specified
+          %w[task.completed task.failed step.completed step.failed]
+        else
+          options[:events]
+        end
+      end
+
+      def handler_methods
+        subscribed_events.map do |event|
+          {
+            event: event,
+            method_name: "handle_#{event.tr('.', '_')}",
+            method_signature: "handle_#{event.tr('.', '_')}(event)"
+          }
+        end
+      end
+
+      def metrics_type?
+        options[:metrics]
+      end
+    end
+  end
+end

data/lib/generators/tasker/task_handler_generator.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Tasker
+  module Generators
+    class TaskHandlerGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Generate a new Tasker task handler with TaskNamespace + versioning support, YAML configuration and tests'
+
+      class_option :module_namespace, type: :string, default: nil,
+                                      desc: 'The module namespace for the task handler ' \
+                                            '(defaults to Tasker.configuration.engine.default_module_namespace)'
+      class_option :namespace_name, type: :string, default: 'default',
+                                    desc: 'The TaskNamespace for organizing the task (e.g., payments, inventory, notifications)'
+      class_option :version, type: :string, default: '0.1.0',
+                             desc: 'Semantic version for the task handler (e.g., 1.0.0, 2.1.0)'
+      class_option :description, type: :string, default: nil,
+                                 desc: 'Description of what this task handler does'
+      class_option :steps, type: :array, default: [],
+                           desc: 'Step names to include in the task (e.g., --steps=validate,process,complete)'
+
+      def create_task_handler_files
+        # Set variables first
+        @module_namespace = options[:module_namespace] || Tasker.configuration.engine.default_module_namespace
+        @module_path = @module_namespace&.underscore
+        @task_handler_class = name.camelize
+        @task_name = name.underscore
+        @namespace_name = options[:namespace_name]
+        @version = options[:version]
+        @description = options[:description]
+        @steps = options[:steps]
+
+        # Load configuration
+        ensure_configuration_loaded
+
+        # Get directory paths from configuration
+        @task_handler_directory = Tasker.configuration.engine.task_handler_directory
+        @task_config_directory = Tasker.configuration.engine.task_config_directory
+
+        # Ensure directories exist
+        ensure_directories_exist(
+          [
+            task_handler_directory_with_module_path,
+            spec_directory_with_module_path,
+            task_config_directory_with_module_path
+          ]
+        )
+
+        # Create the YAML config file
+        template 'task_config.yaml.erb', "#{task_config_directory_with_module_path}/#{@task_name}.yaml"
+
+        # Create the task handler class
+        template 'task_handler.rb.erb', "#{task_handler_directory_with_module_path}/#{@task_name}.rb"
+
+        # Create the task handler spec
+        template 'task_handler_spec.rb.erb', "#{spec_directory_with_module_path}/#{@task_name}_spec.rb"
+
+        display_success_message
+      end
+
+      private
+
+      def usable_module_path
+        @module_path ? "#{@module_path}/" : ''
+      end
+
+      def task_handler_directory_with_module_path
+        Rails.root.join("app/#{@task_handler_directory}/#{usable_module_path}")
+      end
+
+      def task_config_directory_with_module_path
+        Rails.root.join("config/#{@task_config_directory}/#{usable_module_path}")
+      end
+
+      def spec_directory_with_module_path
+        Rails.root.join("spec/#{@task_handler_directory}/#{usable_module_path}")
+      end
+
+      def ensure_configuration_loaded
+        # Check if Tasker is already loaded
+        return if defined?(Tasker) && Tasker.respond_to?(:configuration)
+
+        initializer_path = Rails.root.join('config/initializers/tasker.rb')
+
+        # Copy initializer if it doesn't exist
+        unless File.exist?(initializer_path)
+          template_path = File.expand_path('templates/initialize.rb.erb', __dir__)
+          FileUtils.cp(template_path, initializer_path)
+          Rails.logger.debug { "Created Tasker configuration at #{initializer_path}" }
+        end
+
+        # Load the initializer
+        require initializer_path
+      end
+
+      def ensure_directories_exist(dirs)
+        dirs.each do |dir|
+          unless File.directory?(dir)
+            FileUtils.mkdir_p(dir)
+            Rails.logger.debug { "Created directory: #{dir}" }
+          end
+        end
+      end
+
+      def display_success_message
+        say "\nTask handler created successfully!"
+        say ''
+        say 'Files created:'
+        say "  - #{task_handler_directory_with_module_path}/#{@task_name}.rb"
+        say "  - #{task_config_directory_with_module_path}/#{@task_name}.yaml"
+        say "  - #{spec_directory_with_module_path}/#{@task_name}_spec.rb"
+        say ''
+        say 'Next steps:'
+        say '  1. Define your step handlers in the YAML configuration'
+        say '  2. Implement step handlers as needed'
+        test_path = "spec/#{@task_handler_directory}/#{usable_module_path}#{@task_name}_spec.rb"
+        say "  3. Run your tests: bundle exec rspec #{test_path}"
+        say ''
+        say 'Usage example:'
+        say '  task_request = Tasker::Types::TaskRequest.new('
+        say "    name: '#{@task_name}',"
+        say "    namespace: '#{@namespace_name}',"
+        say "    version: '#{@version}',"
+        say '    context: { /* your task context */ }'
+        say '  )'
+        say ''
+        say '  handler = Tasker::HandlerFactory.instance.get('
+        say "    '#{@task_name}',"
+        say "    namespace_name: '#{@namespace_name}',"
+        say "    version: '#{@version}'"
+        say '  )'
+        say '  task = handler.initialize_task!(task_request)'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# API Token authenticator for <%= class_name %>
+# Generated by: rails generate tasker:authenticator <%= file_name %> --type=api_token
+#
+# This authenticator implements API token-based authentication.
+# Expects tokens to be passed in request headers and looks up users by token.
+#
+# Configuration example:
+#   Tasker.configuration do |config|
+#     config.auth do |auth|
+#       auth.strategy = :custom
+#       auth.options = {
+#         authenticator_class: '<%= class_name %>Authenticator',
+#         header_name: 'X-API-Token',
+#         user_class: '<%= user_model_class %>',
+#         token_field: 'api_token'
+#       }
+#     end
+#   end
+
+class <%= class_name %>Authenticator
+  include Tasker::Authentication::Interface
+
+  def initialize(options = {})
+    @header_name = options[:header_name] || 'X-API-Token'
+    @user_class = options[:user_class] || '<%= user_model_class %>'
+    @token_field = options[:token_field] || 'api_token'
+    @options = options
+  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 API 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
+
+      find_user_by_token(token)
+    rescue StandardError => e
+      Rails.logger.debug "API token authentication failed: #{e.message}"
+      nil
+    end
+  end
+
+  # Optional: Configuration validation
+  def validate_configuration(options = {})
+    errors = []
+
+    # Validate user class
+    user_class = options[:user_class] || '<%= user_model_class %>'
+    begin
+      model = user_class.constantize
+
+      # Check if the token field exists
+      token_field = options[:token_field] || 'api_token'
+      unless model.column_names.include?(token_field.to_s)
+        errors << "User model '#{user_class}' does not have '#{token_field}' column"
+      end
+    rescue NameError
+      errors << "User class '#{user_class}' not found"
+    end
+
+    # Validate header name
+    header_name = options[:header_name]
+    if header_name.present? && !header_name.is_a?(String)
+      errors << 'Header name must be a string'
+    end
+
+    errors
+  end
+
+  private
+
+  attr_reader :header_name, :user_class, :token_field, :options
+
+  def extract_token(request)
+    # Try configured header first
+    token = request.headers[@header_name]
+    return token if token.present?
+
+    # Fallback to Authorization header with Bearer format
+    auth_header = request.headers['Authorization']
+    return nil unless auth_header.present?
+
+    # Support "Bearer <token>" format
+    auth_header.start_with?('Bearer ') ? auth_header.sub(/^Bearer /, '') : auth_header
+  end
+
+  def find_user_by_token(token)
+    return nil if token.blank?
+
+    user_model = @user_class.constantize
+    user_model.find_by(@token_field => token)
+  rescue ActiveRecord::RecordNotFound, NoMethodError
+    nil
+  end
+
+  def user_model
+    @user_model ||= @user_class.constantize
+  end
+end

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

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= class_name %>Authenticator, type: :model do
+  let(:options) do
+    {
+      header_name: 'X-API-Token',
+      user_class: '<%= user_model_class %>',
+      token_field: 'api_token'
+    }
+  end
+
+  let(:authenticator) { described_class.new(options) }
+  let(:controller) { instance_double('ActionController::Base') }
+  let(:request) { instance_double('ActionDispatch::Request') }
+  let(:headers) { {} }
+
+  before do
+    allow(controller).to receive(:request).and_return(request)
+    allow(request).to receive(:headers).and_return(headers)
+  end
+
+  describe '#initialize' do
+    it 'sets configuration options' do
+      expect(authenticator.send(:header_name)).to eq('X-API-Token')
+      expect(authenticator.send(:user_class)).to eq('<%= user_model_class %>')
+      expect(authenticator.send(:token_field)).to eq('api_token')
+    end
+
+    it 'uses default values when options are not provided' do
+      authenticator = described_class.new
+      expect(authenticator.send(:header_name)).to eq('X-API-Token')
+      expect(authenticator.send(:user_class)).to eq('<%= user_model_class %>')
+      expect(authenticator.send(:token_field)).to eq('api_token')
+    end
+  end
+
+  describe '#current_user' do
+    let(:token) { 'abc123token' }
+    let(:user) { double('User', id: 1) }
+
+    before do
+      # Mock the user model
+      user_model = double('UserModel')
+      allow('<%= user_model_class %>').to receive(:constantize).and_return(user_model)
+      allow(user_model).to receive(:find_by).with('api_token' => token).and_return(user)
+    end
+
+    context 'with valid token in configured header' do
+      before do
+        headers['X-API-Token'] = token
+      end
+
+      it 'returns the authenticated user' do
+        expect(authenticator.current_user(controller)).to eq(user)
+      end
+    end
+
+    context 'with valid token in Authorization header (Bearer format)' do
+      before do
+        headers['Authorization'] = "Bearer #{token}"
+      end
+
+      it 'returns the authenticated user' do
+        expect(authenticator.current_user(controller)).to eq(user)
+      end
+    end
+
+    context 'with valid token in Authorization header (raw format)' do
+      before do
+        headers['Authorization'] = token
+      end
+
+      it 'returns the authenticated user' do
+        expect(authenticator.current_user(controller)).to eq(user)
+      end
+    end
+
+    context 'with missing token' do
+      it 'returns nil' do
+        expect(authenticator.current_user(controller)).to be_nil
+      end
+    end
+
+    context 'with invalid token' do
+      before do
+        headers['X-API-Token'] = 'invalid_token'
+        user_model = double('UserModel')
+        allow('<%= user_model_class %>').to receive(:constantize).and_return(user_model)
+        allow(user_model).to receive(:find_by).with('api_token' => 'invalid_token').and_return(nil)
+      end
+
+      it 'returns nil' do
+        expect(authenticator.current_user(controller)).to be_nil
+      end
+    end
+  end
+
+  describe '#validate_configuration' do
+    context 'with valid configuration' do
+      before do
+        # Mock valid user model with token field
+        user_model = double('UserModel', column_names: ['id', 'name', 'api_token'])
+        allow('<%= user_model_class %>').to receive(:constantize).and_return(user_model)
+      end
+
+      it 'returns no errors' do
+        errors = authenticator.validate_configuration(options)
+        expect(errors).to be_empty
+      end
+    end
+
+    context 'with invalid user class' do
+      let(:invalid_options) { options.merge(user_class: 'NonExistentUser') }
+
+      it 'returns validation error' do
+        errors = authenticator.validate_configuration(invalid_options)
+        expect(errors).to include(/not found/)
+      end
+    end
+
+    context 'when user model is missing token field' do
+      before do
+        user_model = double('UserModel', column_names: ['id', 'name'])
+        allow('<%= user_model_class %>').to receive(:constantize).and_return(user_model)
+      end
+
+      it 'returns validation error' do
+        errors = authenticator.validate_configuration(options)
+        expect(errors).to include(/does not have 'api_token' column/)
+      end
+    end
+
+    context 'with invalid header name type' do
+      let(:invalid_options) { options.merge(header_name: 123) }
+
+      it 'returns validation error' do
+        errors = authenticator.validate_configuration(invalid_options)
+        expect(errors).to include('Header name must be a string')
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# Authorization coordinator for <%= @coordinator_class_name %>
+#
+# This coordinator provides authorization logic for Tasker resources.
+# Customize the authorization methods below to implement your business logic.
+#
+# For more advanced examples, see:
+# - docs/AUTH.md (Authorization System section)
+# - spec/examples/custom_authorization_coordinator.rb
+# - spec/lib/tasker/authorization/ (test examples)
+#
+class <%= @coordinator_class_name %> < Tasker::Authorization::BaseCoordinator
+  protected
+
+  # Implement your authorization logic here
+  #
+  # @param resource [String] The resource being accessed (e.g., 'tasker.task')
+  # @param action [Symbol] The action being performed (e.g., :show, :create)
+  # @param context [Hash] Additional context (controller, params, user, etc.)
+  # @return [Boolean] true if authorized, false otherwise
+  def authorized?(resource, action, context = {})
+    # Return false if no user or user doesn't have permission methods
+    return false unless user&.respond_to?(:has_tasker_permission?)
+
+    case resource
+    when Tasker::Authorization::ResourceConstants::RESOURCES::TASK
+      authorize_task(action, context)
+    when Tasker::Authorization::ResourceConstants::RESOURCES::WORKFLOW_STEP
+      authorize_workflow_step(action, context)
+    when Tasker::Authorization::ResourceConstants::RESOURCES::TASK_DIAGRAM
+      authorize_task_diagram(action, context)
+    when Tasker::Authorization::ResourceConstants::RESOURCES::HEALTH_STATUS
+      authorize_system_status(action, context)
+    else
+      # Deny access to unknown resources
+      false
+    end
+  end
+
+  private
+
+  # Authorize task operations
+  def authorize_task(action, context)
+    case action
+    when :index, :show
+      # TODO: Implement your read permission logic
+      user.has_tasker_permission?("tasker.task:#{action}")
+    when :create, :update, :destroy, :retry, :cancel
+      # TODO: Implement your write permission logic
+      # Example: Admin users or users with specific permissions
+      user.tasker_admin? || user.has_tasker_permission?("tasker.task:#{action}")
+    else
+      false
+    end
+  end
+
+  # Authorize workflow step operations
+  def authorize_workflow_step(action, context)
+    case action
+    when :index, :show
+      # TODO: Implement your step read logic
+      user.has_tasker_permission?("tasker.workflow_step:#{action}")
+    when :update, :destroy, :retry, :cancel
+      # TODO: Implement your step write logic
+      # Example: Only admins can modify steps
+      user.tasker_admin?
+    else
+      false
+    end
+  end
+
+  # Authorize task diagram operations
+  def authorize_task_diagram(action, context)
+    case action
+    when :index, :show
+      # TODO: Implement your diagram access logic
+      user.has_tasker_permission?("tasker.task_diagram:#{action}")
+    else
+      false
+    end
+  end
+
+  # Authorize system status operations
+  def authorize_system_status(action, context)
+    case action
+    when :read
+      # TODO: Implement your system status access logic
+      # Example: Admin users or users with explicit permission
+      user.tasker_admin? || user.has_tasker_permission?("tasker.system_status:#{action}")
+    else
+      false
+    end
+  end
+end