shoryuken-template 0.3.0

data/PUBLISHING.md

@@ -0,0 +1,111 @@
+# 📦 Guia de Publicação no RubyGems
+
+## Pré-requisitos
+
+1. Conta no RubyGems: https://rubygems.org/sign_up
+2. Gem configurada localmente
+
+## Publicar pela Primeira Vez
+
+### 1. Configure suas credenciais
+
+```bash
+gem signin
+```
+
+Isso vai pedir suas credenciais do RubyGems.
+
+### 2. Publique a gem
+
+```bash
+cd /Users/sousmile/github/shoryuken-template
+
+# Método 1: Usando rake (recomendado)
+rake release
+
+# Método 2: Manual
+gem build shoryuken-template.gemspec
+gem push shoryuken-template-0.3.0.gem
+```
+
+## Publicar Nova Versão
+
+### 1. Atualize a versão
+
+Edite `lib/shoryuken/template/version.rb`:
+
+```ruby
+module Shoryuken
+  module Template
+    VERSION = "0.3.1"  # Atualize aqui
+  end
+end
+```
+
+### 2. Commit e tag
+
+```bash
+git add lib/shoryuken/template/version.rb
+git commit -m "Bump version to 0.3.1"
+git push origin master
+
+git tag -a v0.3.1 -m "Version 0.3.1"
+git push origin v0.3.1
+```
+
+### 3. Publique
+
+```bash
+rake release
+```
+
+## Versionamento Semântico
+
+Siga o padrão [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (1.0.0): Mudanças incompatíveis na API
+- **MINOR** (0.1.0): Nova funcionalidade compatível
+- **PATCH** (0.0.1): Correção de bugs compatível
+
+### Exemplos:
+
+- Bug fix: `0.3.0` → `0.3.1`
+- Nova feature: `0.3.0` → `0.4.0`
+- Breaking change: `0.3.0` → `1.0.0`
+
+## Usar no Projeto Depois de Publicar
+
+```ruby
+# Gemfile
+gem 'shoryuken-template', '~> 0.3.0'
+```
+
+```bash
+bundle install
+```
+
+## Troubleshooting
+
+### Erro: "You have already activated X"
+
+```bash
+bundle update shoryuken-template
+```
+
+### Erro: "Permission denied"
+
+Verifique se está logado:
+
+```bash
+gem signin
+```
+
+### Reverter uma publicação
+
+⚠️ **CUIDADO**: Não é possível deletar gems do RubyGems. Você só pode "yankar" (remover de listagens):
+
+```bash
+gem yank shoryuken-template -v 0.3.0
+```
+
+Mas a gem ainda estará disponível para quem já a instalou.

data/Procfile.example

@@ -0,0 +1,13 @@
+# Procfile para Heroku
+# Copie para Procfile na raiz do seu projeto
+
+# Worker padrão com YJIT habilitado (Ruby 3.4+)
+worker: RUBY_YJIT_ENABLE=1 bundle exec shoryuken -R -C config/shoryuken.yml
+
+# Workers específicos (opcional) - com YJIT
+# worker_orders: RUBY_YJIT_ENABLE=1 bundle exec shoryuken -q orders-queue -R
+# worker_images: RUBY_YJIT_ENABLE=1 bundle exec shoryuken -q images-queue -R
+# worker_transactions: RUBY_YJIT_ENABLE=1 bundle exec shoryuken -q transactions-queue.fifo -R
+
+# Web (se necessário)
+# web: bundle exec puma -C config/puma.rb

data/QUICKSTART.md

@@ -0,0 +1,156 @@
+# 🚀 Guia de Início Rápido
+
+Este guia mostra como começar a usar o Shoryuken Template em 5 minutos.
+
+## Requisitos
+
+- Ruby >= 3.4.2
+- AWS SQS configurado
+
+## 1. Instalação
+
+Adicione ao seu `Gemfile`:
+
+```ruby
+gem 'shoryuken-template'
+```
+
+Execute:
+
+```bash
+bundle install
+```
+
+## 2. Configuração Básica
+
+Crie `config/initializers/shoryuken_template.rb`:
+
+```ruby
+require 'shoryuken/template'
+
+Shoryuken::Template.configure do |config|
+  config.thread_pool_size = 10
+  config.thread_timeout = 300
+end
+```
+
+## 3. Crie seu Primeiro Worker
+
+### Worker Padrão
+
+```ruby
+# app/workers/my_first_worker.rb
+class MyFirstWorker
+  include Shoryuken::Template::Workers::StandardWorker
+
+  worker_options queue: 'my-queue'
+
+  def process_message(body)
+    log_info("Processando mensagem", data: body)
+    
+    # Sua lógica aqui
+    puts "Recebido: #{body}"
+  end
+end
+```
+
+## 4. Configure o Shoryuken
+
+Crie `config/shoryuken.yml`:
+
+```yaml
+aws:
+  region: us-east-1
+
+concurrency: 10
+delay: 0
+
+queues:
+  - [my-queue, 1]
+
+require:
+  - ./config/environment.rb
+  - ./app/workers/my_first_worker.rb
+```
+
+## 5. Execute Localmente
+
+```bash
+bundle exec shoryuken -R -C config/shoryuken.yml
+```
+
+## 6. Deploy no Heroku
+
+### Adicione as variáveis de ambiente:
+
+```bash
+heroku config:set AWS_REGION=us-east-1
+heroku config:set AWS_ACCESS_KEY_ID=your_key
+heroku config:set AWS_SECRET_ACCESS_KEY=your_secret
+heroku config:set SHORYUKEN_THREAD_POOL_SIZE=10
+```
+
+### Crie um `Procfile`:
+
+```
+worker: bundle exec shoryuken -R -C config/shoryuken.yml
+```
+
+### Deploy:
+
+```bash
+git add .
+git commit -m "Adiciona Shoryuken workers"
+git push heroku main
+heroku ps:scale worker=1
+```
+
+## 7. Monitoramento
+
+Visualize os logs:
+
+```bash
+heroku logs --tail --ps worker
+```
+
+## Próximos Passos
+
+### Worker Paralelo (para processar em lote)
+
+```ruby
+class BatchWorker
+  include Shoryuken::Template::Workers::ParallelWorker
+
+  worker_options queue: 'batch-queue', batch: true
+
+  def process_message(body)
+    # Cada mensagem é processada em uma thread
+    process_item(body)
+  end
+end
+```
+
+### Worker FIFO (para processamento ordenado)
+
+```ruby
+class FifoWorker
+  include Shoryuken::Template::Workers::FifoWorker
+
+  worker_options queue: 'fifo-queue.fifo'
+
+  def process_message(body, message_group_id)
+    # Processamento sequencial garantido
+    process_in_order(body)
+  end
+end
+```
+
+## Ajuda
+
+- 📖 Documentação completa: [README.md](README.md)
+- 💡 Exemplos: [examples/](examples/)
+- 🐛 Problemas: [GitHub Issues](https://github.com/sousmile/shoryuken-template/issues)
+
+---
+
+**Dica**: Use `log_info`, `log_error`, etc. dentro dos workers para logs estruturados automáticos!

data/README.md

@@ -0,0 +1,393 @@
+# Shoryuken Template
+
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.4.2-ruby.svg)](https://www.ruby-lang.org)
+[![Gem Version](https://badge.fury.io/rb/shoryuken-template.svg)](https://badge.fury.io/rb/shoryuken-template)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Template estruturado para projetos que utilizam a gem [Shoryuken](https://github.com/ruby-shoryuken/shoryuken) para consumir mensagens de filas SQS da AWS.
+
+## 📋 Requisitos
+
+- Ruby >= 3.4.2
+- Shoryuken >= 6.0
+- Concurrent-ruby >= 1.3
+- AWS SQS
+
+## 🚀 Funcionalidades
+
+- **3 tipos de workers prontos para uso:**
+  - 🔹 Worker Padrão: processa uma mensagem por vez
+  - 🔹 Worker Paralelo: processa mensagens em lote usando threads
+  - 🔹 Worker FIFO: processa mensagens sequencialmente de filas FIFO
+
+- **Pool de threads configurável** com `concurrent-ruby`
+  - Configuração global ou específica por worker
+  - Timeouts individuais por worker
+- **Tratamento de erros robusto** com retry automático
+- **Logging estruturado** em formato JSON
+- **Timeout por thread** para evitar travamentos
+- **Otimizado para Heroku**
+
+## 📦 Instalação
+
+### Via Git (Recomendado atualmente)
+
+Adicione ao seu `Gemfile`:
+
+```ruby
+# Usando uma versão específica (tag)
+gem 'shoryuken-template', git: 'https://github.com/sousmile/shoryuken-template.git', tag: 'v0.3.0'
+
+# OU usando sempre a última versão do master
+gem 'shoryuken-template', git: 'https://github.com/sousmile/shoryuken-template.git', branch: 'master'
+```
+
+Execute:
+
+```bash
+bundle install
+```
+
+### Via RubyGems (Em breve)
+
+```ruby
+gem 'shoryuken-template', '~> 0.3.0'
+```
+
+```bash
+bundle install
+```
+
+### 🚀 Habilitando YJIT (Recomendado)
+
+Para melhor performance, habilite o YJIT do Ruby 3.4:
+
+```bash
+# Localmente
+RUBY_YJIT_ENABLE=1 bundle exec shoryuken -R -C config/shoryuken.yml
+
+# No Heroku (Procfile)
+worker: RUBY_YJIT_ENABLE=1 bundle exec shoryuken -R -C config/shoryuken.yml
+```
+
+**Performance:** YJIT pode melhorar a performance em até 20%! 🚀
+
+## 🔧 Configuração
+
+### Configuração Básica
+
+```ruby
+require 'shoryuken/template'
+
+Shoryuken::Template.configure do |config|
+  # Pool de threads GLOBAL (padrão para todos os workers)
+  config.thread_pool_size = 20        # Número de threads no pool global
+  config.thread_timeout = 300         # Timeout em segundos (global)
+
+  # Logging
+  config.logger_level = :info
+
+  # Retry
+  config.max_retries = 3
+  config.retry_delay = 5
+
+  # Configuração ESPECÍFICA por worker (opcional)
+  config.configure_worker('ImageProcessorWorker',
+    thread_pool_size: 30,   # Pool dedicado com 30 threads
+    thread_timeout: 600      # Timeout de 10 minutos
+  )
+
+  config.configure_worker('EmailWorker',
+    thread_pool_size: 50,   # Pool maior para I/O bound
+    thread_timeout: 30       # Timeout menor
+  )
+
+  # Error handler customizado (opcional)
+  config.error_handler = lambda do |error, worker_name, message|
+    # Enviar para Sentry, Rollbar, etc
+    Sentry.capture_exception(error)
+  end
+end
+```
+
+### Variáveis de Ambiente
+
+Todas as configurações podem ser definidas via variáveis de ambiente:
+
+```bash
+SHORYUKEN_THREAD_POOL_SIZE=20
+SHORYUKEN_THREAD_TIMEOUT=300
+SHORYUKEN_LOG_LEVEL=info
+SHORYUKEN_MAX_RETRIES=3
+SHORYUKEN_RETRY_DELAY=5
+```
+
+### Configuração para Heroku
+
+```ruby
+# config/initializers/shoryuken.rb
+require 'shoryuken/template'
+
+Shoryuken::Template.configure do |config|
+  # Ajusta threads baseado no tipo de dyno
+  config.thread_pool_size = ENV.fetch('SHORYUKEN_THREAD_POOL_SIZE', 10).to_i
+  config.thread_timeout = 25  # Menor que o timeout do Heroku (30s)
+  
+  # Workers específicos podem ter configurações diferentes
+  config.configure_worker('HeavyProcessingWorker',
+    thread_pool_size: 5,
+    thread_timeout: 600  # 10 minutos para tarefas pesadas
+  )
+end
+
+# Graceful shutdown
+Signal.trap('TERM') do
+  Shoryuken::Template.configuration.reset_thread_pools!
+  exit(0)
+end
+```
+
+## 📝 Uso
+
+### Worker Padrão (StandardWorker)
+
+Processa uma mensagem por vez de uma fila SQS normal:
+
+```ruby
+class OrderProcessorWorker
+  include Shoryuken::Template::Workers::StandardWorker
+
+  worker_options queue: 'orders-queue'
+
+  def process_message(body)
+    order_id = body['order_id']
+    
+    log_info("Processando pedido", order_id: order_id)
+    
+    # Sua lógica aqui
+    process_order(order_id)
+    
+    log_info("Pedido processado", order_id: order_id)
+  end
+end
+```
+
+### Worker Paralelo (ParallelWorker)
+
+Processa múltiplas mensagens em paralelo usando threads:
+
+```ruby
+class ImageProcessorWorker
+  include Shoryuken::Template::Workers::ParallelWorker
+
+  worker_options queue: 'images-queue', batch: true
+
+  def process_message(body)
+    image_id = body['image_id']
+    
+    log_info("Processando imagem", image_id: image_id)
+    
+    # Cada mensagem é processada em uma thread separada
+    download_and_process_image(image_id)
+    
+    log_info("Imagem processada", image_id: image_id)
+  end
+end
+```
+
+### Worker FIFO (FifoWorker)
+
+Processa mensagens sequencialmente de filas FIFO:
+
+```ruby
+class TransactionWorker
+  include Shoryuken::Template::Workers::FifoWorker
+
+  worker_options queue: 'transactions-queue.fifo'
+
+  def process_message(body, message_group_id)
+    transaction_id = body['transaction_id']
+    
+    log_info(
+      "Processando transação",
+      transaction_id: transaction_id,
+      message_group_id: message_group_id
+    )
+    
+    # Processamento sequencial garantido
+    process_transaction(transaction_id)
+  end
+end
+```
+
+## ⚙️ Configuração Avançada
+
+### Pool e Timeout Específico por Worker
+
+Você pode configurar pool de threads e timeout individualmente para cada worker:
+
+```ruby
+Shoryuken::Template.configure do |config|
+  # Configuração global (fallback)
+  config.thread_pool_size = 10
+  config.thread_timeout = 300
+
+  # Workers I/O bound: mais threads, timeout menor
+  config.configure_worker('EmailWorker',
+    thread_pool_size: 50,
+    thread_timeout: 30
+  )
+
+  # Workers CPU bound: menos threads, timeout maior
+  config.configure_worker('VideoProcessorWorker',
+    thread_pool_size: 5,
+    thread_timeout: 1800  # 30 minutos
+  )
+
+  # Workers com tarefas variadas: usa configuração global
+  # (não precisa configurar explicitamente)
+end
+```
+
+**Como funciona:**
+- Cada worker configurado tem seu próprio pool de threads
+- Workers não configurados usam o pool global
+- Timeout é verificado por thread individualmente
+
+**Quando usar configuração específica:**
+- ✅ Workers com necessidades muito diferentes de recursos
+- ✅ Separar workers I/O bound de CPU bound
+- ✅ Isolar workers críticos de workers experimentais
+- ❌ Não abuse: muitos pools pequenos = overhead desnecessário
+
+## 🔍 Logging
+
+Todos os logs são estruturados em formato JSON:
+
+```json
+{
+  "timestamp": "2026-01-16T10:30:45.123Z",
+  "level": 2,
+  "message": "Mensagem processada com sucesso",
+  "pid": 12345,
+  "thread_id": 70123456789,
+  "environment": "production",
+  "worker": "OrderProcessorWorker",
+  "order_id": "ORD-123",
+  "duration": 1.234
+}
+```
+
+### Métodos de Log Disponíveis
+
+```ruby
+log_debug("Mensagem de debug", context: "valor")
+log_info("Mensagem informativa", user_id: 123)
+log_warn("Aviso", count: 10)
+log_error("Erro encontrado", error: e.message)
+```
+
+## 🛡️ Tratamento de Erros
+
+### Retry Automático
+
+O sistema tenta automaticamente reprocessar mensagens que falharam:
+
+```ruby
+# Configuração
+config.max_retries = 3
+config.retry_delay = 5  # segundos com backoff exponencial
+```
+
+### Error Handler Customizado
+
+```ruby
+config.error_handler = lambda do |error, worker_name, message|
+  Sentry.capture_exception(error, extra: {
+    worker: worker_name,
+    message_id: message&.message_id
+  })
+end
+```
+
+## 🏗️ Estrutura do Projeto
+
+```
+lib/shoryuken/template/
+├── configuration.rb      # Configuração e pool de threads
+├── logger.rb            # Sistema de logging estruturado
+├── error_handler.rb     # Tratamento de erros e retry
+└── workers/
+    ├── base_worker.rb       # Worker base
+    ├── standard_worker.rb   # Worker padrão
+    ├── parallel_worker.rb   # Worker paralelo
+    └── fifo_worker.rb       # Worker FIFO
+```
+
+## 🎯 Boas Práticas
+
+### 1. Configuração de Threads
+
+**Pool Global (recomendações por tipo de dyno):**
+- **Dyno Standard-1X**: 10 threads
+- **Dyno Standard-2X**: 20 threads
+- **Performance-M**: 40 threads
+- **Performance-L**: 80 threads
+
+**Pools Específicos por Worker:**
+- Configure apenas workers com necessidades muito diferentes
+- Workers I/O bound: mais threads (ex: 50 para email/HTTP)
+- Workers CPU bound: menos threads (ex: 5 para processamento de vídeo)
+
+### 2. Timeouts
+
+- Mantenha timeouts menores que 30s para workers web-facing no Heroku
+- Use timeouts maiores (600-1800s) para operações batch/assíncronas
+- Configure timeout específico para workers com necessidades especiais
+
+### 3. Worker Paralelo
+
+- Use para operações I/O bound (downloads, uploads, chamadas HTTP)
+- Evite para operações CPU intensivas (use menos threads)
+- Monitore o uso de memória
+- Configure pool específico se necessário
+
+### 4. Worker FIFO
+
+- Use apenas para operações que DEVEM ser sequenciais
+- Garante ordem dentro do mesmo `message_group_id`
+- Performance menor que workers padrão
+- Geralmente não precisa de configuração específica de pool
+
+## 📚 Exemplos
+
+Veja a pasta `examples/` para exemplos completos:
+
+- `standard_worker_example.rb` - Worker padrão
+- `parallel_worker_example.rb` - Worker paralelo
+- `fifo_worker_example.rb` - Worker FIFO
+- `configuration_example.rb` - Configuração completa
+- `heroku_setup.rb` - Setup para Heroku
+
+## 🧪 Testes
+
+```bash
+bundle exec rake test
+```
+
+## 📄 Licença
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 🤝 Contribuindo
+
+1. Fork o projeto
+2. Crie uma branch para sua feature (`git checkout -b feature/nova-feature`)
+3. Commit suas mudanças (`git commit -am 'Adiciona nova feature'`)
+4. Push para a branch (`git push origin feature/nova-feature`)
+5. Abra um Pull Request
+
+## 📞 Suporte
+
+- GitHub Issues: https://github.com/sousmile/shoryuken-template/issues
+- Email: andrade.rmn@gmail.com