shoryuken-template 0.3.0

data/examples/fifo_worker_example.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'shoryuken/template'
+
+# Exemplo de Worker FIFO
+# Processa mensagens sequencialmente de uma fila FIFO
+class AccountTransactionWorker
+  include Shoryuken::Template::Workers::FifoWorker
+
+  # Configuração do worker para fila FIFO
+  worker_options queue: 'transactions-queue.fifo'
+
+  # Processa mensagens sequencialmente
+  # message_group_id garante a ordem dentro do grupo
+  def process_message(body, message_group_id)
+    transaction_id = body['transaction_id']
+    account_id = body['account_id']
+    amount = body['amount']
+    transaction_type = body['type']
+
+    log_info(
+      "Processando transação sequencialmente",
+      transaction_id:,
+      account_id:,
+      message_group_id:
+    )
+
+    # Lógica que requer processamento sequencial
+    # Por exemplo: débitos e créditos em uma conta
+    account = load_account(account_id)
+    
+    case transaction_type
+    when 'credit'
+      account.add_credit(amount)
+    when 'debit'
+      account.add_debit(amount)
+    end
+
+    account.save!
+
+    log_info(
+      "Transação processada com sucesso",
+      transaction_id:,
+      new_balance: account.balance
+    )
+  end
+
+  private
+
+  def load_account(account_id)
+    # Lógica de carregamento da conta
+    OpenStruct.new(
+      id: account_id,
+      balance: 1000,
+      add_credit: ->(amount) { @balance = balance + amount },
+      add_debit: ->(amount) { @balance = balance - amount },
+      save!: -> { true }
+    )
+  end
+end

data/examples/heroku_setup.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Configuração para Heroku
+# Este arquivo deve ser carregado antes de iniciar os workers
+# Ruby 3.4.2+ com YJIT habilitado para melhor performance
+
+require 'shoryuken/template'
+
+# Configuração otimizada para Heroku
+Shoryuken::Template.configure do |config|
+  # Dyno padrão tem 512MB de RAM
+  # Ajuste baseado no tipo de dyno
+  dyno_type = ENV['DYNO_SIZE'] || 'standard-1x'
+  
+  # Pool de threads global baseado no tipo de dyno
+  config.thread_pool_size = case dyno_type
+                            when 'standard-1x'
+                              10
+                            when 'standard-2x'
+                              20
+                            when 'performance-m'
+                              40
+                            when 'performance-l'
+                              80
+                            else
+                              10
+                            end
+
+  # Timeout menor para evitar timeout do Heroku (30s) em workers web-facing
+  # Para workers assíncronos, pode usar timeout maior
+  config.thread_timeout = 25
+
+  # Log level baseado no ambiente
+  config.logger_level = ENV['RACK_ENV'] == 'production' ? :info : :debug
+
+  # Retry configurado
+  config.max_retries = 3
+  config.retry_delay = 5
+
+  # Configurações específicas por worker se necessário
+  # Workers que processam tarefas longas podem ter timeout maior
+  if ENV['RACK_ENV'] == 'production'
+    config.configure_worker('HeavyProcessingWorker',
+      thread_pool_size: 5,
+      thread_timeout: 600  # 10 minutos para tarefas pesadas
+    )
+  end
+end
+
+# Graceful shutdown para Heroku
+Signal.trap('TERM') do
+  puts 'SIGTERM recebido, iniciando shutdown graceful...'
+  
+  # Aguarda finalização de todas as threads
+  Shoryuken::Template.configuration.reset_thread_pools!
+  
+  puts 'Shutdown concluído'
+  exit(0)
+end

data/examples/parallel_worker_example.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'shoryuken/template'
+
+# Exemplo de Worker Paralelo
+# Processa múltiplas mensagens em paralelo usando threads
+class ImageProcessorWorker
+  include Shoryuken::Template::Workers::ParallelWorker
+
+  # Configuração do worker com batch habilitado
+  worker_options queue: 'images-queue', batch: true
+
+  # Cada mensagem do batch será processada em uma thread separada
+  def process_message(body)
+    image_url = body['image_url']
+    image_id = body['image_id']
+
+    log_info(
+      "Processando imagem em thread",
+      image_id:,
+      thread_id: Thread.current.object_id
+    )
+
+    # Sua lógica de processamento aqui
+    # Cada imagem é processada em paralelo
+    download_image(image_url)
+    resize_image(image_id)
+    upload_to_cdn(image_id)
+
+    log_info("Imagem processada com sucesso", image_id:)
+  end
+
+  private
+
+  def download_image(url)
+    # Lógica de download
+    sleep 2 # Simula download
+  end
+
+  def resize_image(image_id)
+    # Lógica de redimensionamento
+    sleep 1 # Simula processamento
+  end
+
+  def upload_to_cdn(image_id)
+    # Lógica de upload
+    sleep 1 # Simula upload
+  end
+end

data/examples/standard_worker_example.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'shoryuken/template'
+
+# Exemplo de Worker Padrão
+# Processa uma mensagem por vez de uma fila SQS padrão
+class OrderProcessorWorker
+  include Shoryuken::Template::Workers::StandardWorker
+
+  # Configuração do worker
+  worker_options queue: 'orders-queue'
+
+  # Implementa o método de processamento
+  def process_message(body)
+    order_id = body['order_id']
+    customer_id = body['customer_id']
+
+    log_info("Processando pedido", order_id:, customer_id:)
+
+    # Sua lógica de negócio aqui
+    process_order(order_id)
+    notify_customer(customer_id)
+
+    log_info("Pedido processado com sucesso", order_id:)
+  end
+
+  private
+
+  def process_order(order_id)
+    # Lógica de processamento do pedido
+    sleep 1 # Simula processamento
+  end
+
+  def notify_customer(customer_id)
+    # Lógica de notificação
+    sleep 0.5 # Simula envio de notificação
+  end
+end

data/examples/worker_specific_config_example.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'shoryuken/template'
+
+# Exemplo de configuração específica por worker
+# Demonstra como configurar diferentes pools e timeouts para diferentes tipos de workers
+
+Shoryuken::Template.configure do |config|
+  # ===== CONFIGURAÇÃO GLOBAL (FALLBACK) =====
+  # Usada por workers que não têm configuração específica
+  config.thread_pool_size = 10
+  config.thread_timeout = 300  # 5 minutos
+
+  # ===== WORKERS I/O BOUND =====
+  # Processamento de emails, chamadas HTTP, etc
+  # Podem ter muitas threads pois ficam esperando I/O
+  config.configure_worker('EmailWorker',
+    thread_pool_size: 50,   # Muitas threads
+    thread_timeout: 30       # Timeout curto
+  )
+
+  config.configure_worker('NotificationWorker',
+    thread_pool_size: 40,
+    thread_timeout: 60
+  )
+
+  # ===== WORKERS CPU BOUND =====
+  # Processamento de vídeos, imagens pesadas, cálculos complexos
+  # Devem ter menos threads para não sobrecarregar a CPU
+  config.configure_worker('VideoProcessorWorker',
+    thread_pool_size: 5,    # Poucas threads
+    thread_timeout: 1800     # Timeout longo (30 minutos)
+  )
+
+  config.configure_worker('ImageProcessorWorker',
+    thread_pool_size: 10,
+    thread_timeout: 600      # 10 minutos
+  )
+
+  # ===== WORKERS CRÍTICOS =====
+  # Workers importantes que precisam de recursos dedicados
+  config.configure_worker('PaymentProcessorWorker',
+    thread_pool_size: 20,   # Pool dedicado
+    thread_timeout: 120      # 2 minutos
+  )
+
+  # ===== WORKERS EXPERIMENTAIS =====
+  # Workers novos ou em teste com recursos limitados
+  config.configure_worker('ExperimentalWorker',
+    thread_pool_size: 2,    # Pool pequeno
+    thread_timeout: 60       # Timeout curto
+  )
+
+  # Outros workers não listados usarão a configuração global
+  # Ex: 'OrderProcessorWorker' usará thread_pool_size: 10, timeout: 300
+end
+
+# ===== IMPLEMENTAÇÃO DOS WORKERS =====
+
+# Worker I/O Bound - Email
+class EmailWorker
+  include Shoryuken::Template::Workers::ParallelWorker
+
+  worker_options queue: 'emails-queue', batch: true
+
+  def process_message(body)
+    # Usa pool de 50 threads, timeout de 30s
+    send_email(body['to'], body['subject'], body['body'])
+  end
+
+  private
+
+  def send_email(to, subject, body)
+    log_info("Enviando email", to:)
+    # Simula envio de email (I/O bound)
+    sleep 2
+  end
+end
+
+# Worker CPU Bound - Vídeo
+class VideoProcessorWorker
+  include Shoryuken::Template::Workers::ParallelWorker
+
+  worker_options queue: 'videos-queue', batch: true
+
+  def process_message(body)
+    # Usa pool de 5 threads, timeout de 30 minutos
+    process_video(body['video_id'])
+  end
+
+  private
+
+  def process_video(video_id)
+    log_info("Processando vídeo", video_id:)
+    # Processamento pesado de vídeo (CPU bound)
+    sleep 10
+  end
+end
+
+# Worker sem configuração específica - usa global
+class OrderProcessorWorker
+  include Shoryuken::Template::Workers::StandardWorker
+
+  worker_options queue: 'orders-queue'
+
+  def process_message(body)
+    # Usa configuração global: pool de 10 threads, timeout de 5 minutos
+    process_order(body['order_id'])
+  end
+
+  private
+
+  def process_order(order_id)
+    log_info("Processando pedido", order_id:)
+    sleep 1
+  end
+end
+
+# ===== DICAS =====
+#
+# 1. Configure apenas workers com necessidades muito diferentes
+#    - Não configure todos os workers individualmente
+#
+# 2. Workers I/O bound: mais threads (30-50)
+#    - Email, HTTP, API calls, Database queries
+#
+# 3. Workers CPU bound: menos threads (5-10)
+#    - Processamento de vídeo, imagens, cálculos complexos
+#
+# 4. Monitore o uso de memória
+#    - Muitos pools grandes = muita memória
+#
+# 5. Use configuração global como fallback
+#    - Deixe valores sensatos na configuração global

data/lib/shoryuken/template/configuration.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module Shoryuken
+  module Template
+    # Configuração global para o Shoryuken Template
+    class Configuration
+      attr_accessor :thread_pool_size, :thread_timeout, :error_handler, 
+                    :logger_level, :max_retries, :retry_delay
+      attr_reader :worker_configs
+
+      def initialize
+        @thread_pool_size = ENV.fetch('SHORYUKEN_THREAD_POOL_SIZE', '10').to_i
+        @thread_timeout = ENV.fetch('SHORYUKEN_THREAD_TIMEOUT', '300').to_i
+        @logger_level = ENV.fetch('SHORYUKEN_LOG_LEVEL', 'info').to_sym
+        @max_retries = ENV.fetch('SHORYUKEN_MAX_RETRIES', '3').to_i
+        @retry_delay = ENV.fetch('SHORYUKEN_RETRY_DELAY', '5').to_i
+        @error_handler = nil
+        @worker_configs = {}
+        @thread_pools = {}
+        @mutex = Mutex.new
+      end
+
+      # Configura um worker específico
+      def configure_worker(worker_class_or_name, thread_pool_size: nil, thread_timeout: nil)
+        worker_name = worker_class_or_name.is_a?(String) ? worker_class_or_name : worker_class_or_name.name
+        
+        @mutex.synchronize do
+          @worker_configs[worker_name] = {
+            thread_pool_size:,
+            thread_timeout:
+          }.compact
+        end
+      end
+
+      # Retorna o pool de threads para um worker específico ou o pool global
+      def thread_pool_for(worker_name = nil)
+        return default_thread_pool unless worker_name
+
+        config = @worker_configs[worker_name]
+        pool_size = config&.dig(:thread_pool_size)
+        
+        return default_thread_pool unless pool_size
+
+        @mutex.synchronize do
+          @thread_pools[worker_name] ||= create_thread_pool(pool_size)
+        end
+      end
+
+      # Retorna o timeout para um worker específico ou o timeout global
+      def thread_timeout_for(worker_name = nil)
+        return thread_timeout unless worker_name
+
+        @worker_configs.dig(worker_name, :thread_timeout) || thread_timeout
+      end
+
+      # Pool de threads padrão
+      def default_thread_pool
+        @default_thread_pool ||= create_thread_pool(thread_pool_size)
+      end
+
+      # Reset de todos os pools de threads
+      def reset_thread_pools!
+        @mutex.synchronize do
+          # Shutdown do pool padrão
+          shutdown_pool(@default_thread_pool)
+          @default_thread_pool = nil
+
+          # Shutdown dos pools específicos
+          @thread_pools.each_value { shutdown_pool(_1) }
+          @thread_pools.clear
+        end
+      end
+
+      # Validação da configuração
+      def validate!
+        raise ConfigurationError, "thread_pool_size deve ser maior que 0" if thread_pool_size <= 0
+        raise ConfigurationError, "thread_timeout deve ser maior que 0" if thread_timeout <= 0
+        raise ConfigurationError, "max_retries deve ser maior ou igual a 0" if max_retries < 0
+
+        # Valida configurações específicas de workers
+        @worker_configs.each do |worker_name, config|
+          if config[:thread_pool_size] && config[:thread_pool_size] <= 0
+            raise ConfigurationError, "thread_pool_size para #{worker_name} deve ser maior que 0"
+          end
+          if config[:thread_timeout] && config[:thread_timeout] <= 0
+            raise ConfigurationError, "thread_timeout para #{worker_name} deve ser maior que 0"
+          end
+        end
+      end
+
+      private
+
+      def create_thread_pool(size)
+        Concurrent::FixedThreadPool.new(
+          size,
+          max_queue: size * 2,
+          fallback_policy: :caller_runs,
+          idletime: 60
+        )
+      end
+
+      def shutdown_pool(pool)
+        return unless pool
+
+        pool.shutdown
+        pool.wait_for_termination(30)
+      end
+    end
+
+    class ConfigurationError < Error; end
+
+    # Configuração singleton
+    class << self
+      attr_writer :configuration
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+        configuration.validate!
+      end
+
+      def reset_configuration!
+        configuration.reset_thread_pools!
+        @configuration = Configuration.new
+      end
+    end
+  end
+end

data/lib/shoryuken/template/error_handler.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Shoryuken
+  module Template
+    # Tratamento de erros robusto com retry logic
+    class ErrorHandler
+      class << self
+        # Executa bloco com retry logic
+        def with_retry(max_retries: nil, delay: nil, on: StandardError)
+          config = Shoryuken::Template.configuration
+          max_retries ||= config.max_retries
+          delay ||= config.retry_delay
+          attempts = 0
+
+          begin
+            attempts += 1
+            yield
+          rescue on => e
+            if attempts <= max_retries
+              Shoryuken::Template.logger.warn(
+                "Tentativa #{attempts}/#{max_retries} falhou, tentando novamente em #{delay}s",
+                error: e.message,
+                error_class: e.class.name,
+                backtrace: e.backtrace.first(5)
+              )
+              sleep(delay * attempts) # Backoff exponencial
+              retry
+            else
+              Shoryuken::Template.logger.error(
+                "Todas as tentativas falharam",
+                error: e.message,
+                error_class: e.class.name,
+                attempts:,
+                backtrace: e.backtrace.first(10)
+              )
+              raise
+            end
+          end
+        end
+
+        # Executa bloco com tratamento de erro
+        def handle_error(worker_name, message = nil, &block)
+          start_time = Time.now
+
+          begin
+            result = block.call
+            duration = Time.now - start_time
+
+            Shoryuken::Template.logger.info(
+              "Mensagem processada com sucesso",
+              worker: worker_name,
+              duration: duration.round(3),
+              message_id: message&.message_id
+            )
+
+            result
+          rescue StandardError => e
+            duration = Time.now - start_time
+
+            Shoryuken::Template.logger.error(
+              "Erro ao processar mensagem",
+              worker: worker_name,
+              error: e.message,
+              error_class: e.class.name,
+              duration: duration.round(3),
+              message_id: message&.message_id,
+              backtrace: e.backtrace.first(10)
+            )
+
+            # Chama error handler customizado se configurado
+            if Shoryuken::Template.configuration.error_handler
+              call_custom_error_handler(e, worker_name, message)
+            end
+
+            raise
+          end
+        end
+
+        # Executa bloco com timeout
+        def with_timeout(seconds, &)
+          result = nil
+          timeout_thread = Thread.new { sleep(seconds) }
+          result_thread = Thread.new { result = yield }
+
+          if result_thread.join(seconds)
+            timeout_thread.kill
+            raise result_thread[:exception] if result_thread[:exception]
+
+            result
+          else
+            result_thread.kill
+            raise TimeoutError, "Operação excedeu o timeout de #{seconds} segundos"
+          end
+        rescue StandardError => e
+          result_thread&.kill
+          timeout_thread&.kill
+          raise e
+        end
+
+        private
+
+        def call_custom_error_handler(error, worker_name, message)
+          handler = Shoryuken::Template.configuration.error_handler
+          handler.call(error, worker_name, message)
+        rescue => handler_error
+          Shoryuken::Template.logger.error(
+            "Erro no error handler customizado",
+            error: handler_error.message,
+            error_class: handler_error.class.name,
+            backtrace: handler_error.backtrace.first(5)
+          )
+        end
+      end
+    end
+
+    class TimeoutError < Error; end
+  end
+end

data/lib/shoryuken/template/logger.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'json'
+
+module Shoryuken
+  module Template
+    # Logger estruturado com suporte a JSON
+    class StructuredLogger
+      LEVELS = {
+        debug: Logger::DEBUG,
+        info: Logger::INFO,
+        warn: Logger::WARN,
+        error: Logger::ERROR,
+        fatal: Logger::FATAL
+      }.freeze
+
+      attr_reader :logger
+
+      def initialize(output = $stdout)
+        @logger = Logger.new(output)
+        @logger.level = LEVELS[Shoryuken::Template.configuration.logger_level] || Logger::INFO
+        @logger.formatter = method(:formatter)
+      end
+
+      def debug(message = nil, **context, &block)
+        log(:debug, message, context, &block)
+      end
+
+      def info(message = nil, **context, &block)
+        log(:info, message, context, &block)
+      end
+
+      def warn(message = nil, **context, &block)
+        log(:warn, message, context, &block)
+      end
+
+      def error(message = nil, **context, &block)
+        log(:error, message, context, &block)
+      end
+
+      def fatal(message = nil, **context, &block)
+        log(:fatal, message, context, &block)
+      end
+
+      private
+
+      def log(level, message, context, &block)
+        return unless @logger.send("#{level}?")
+
+        message = block.call if block_given?
+        @logger.send(level, build_log_data(message, context))
+      end
+
+      def build_log_data(message, context)
+        {
+          timestamp: Time.now.utc.iso8601(3),
+          level: @logger.level,
+          message:,
+          pid: Process.pid,
+          thread_id: Thread.current.object_id,
+          environment: ENV.fetch('RACK_ENV') { ENV.fetch('RAILS_ENV', 'development') }
+        }.merge(context)
+      end
+
+      def formatter(_severity, _time, _progname, msg)
+        log_hash = case msg
+                   when Hash
+                     msg
+                   else
+                     {
+                       timestamp: Time.now.utc.iso8601(3),
+                       message: msg.to_s,
+                       pid: Process.pid,
+                       thread_id: Thread.current.object_id
+                     }
+                   end
+
+        "#{JSON.generate(log_hash)}\n"
+      end
+    end
+
+    # Logger singleton
+    class << self
+      attr_writer :logger
+
+      def logger
+        @logger ||= StructuredLogger.new
+      end
+    end
+  end
+end

data/lib/shoryuken/template/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Shoryuken
+  module Template
+    VERSION = "0.3.0"
+  end
+end