sqs_simplify 0.2.0

data/README.pt-br.md

@@ -0,0 +1,384 @@
+# SqsSimplify
+
+[![Gem Version](https://badge.fury.io/rb/sqs_simplify.svg)](https://badge.fury.io/rb/sqs_simplify)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-red.svg)](https://www.ruby-lang.org)
+
+Uma DSL Ruby de alto nível sobre o `aws-sdk-sqs` para produzir e consumir mensagens do AWS SQS com o mínimo de boilerplate.
+
+Possui 3 papéis principais:
+* **SqsSimplify::Scheduler**: Envia mensagens para uma fila.
+* **SqsSimplify::Consumer**: Consome mensagens de uma fila.
+* **SqsSimplify::Job**: Envia e consome mensagens de uma fila.
+
+> 🇺🇸 An English version of this document is available at [README.md](README.md).
+
+## Sumário
+
+* [Requisitos](#requisitos)
+* [Instalação](#instalação)
+* [Como usar](#como-usar)
+  * [Configuração Inicial](#1-configuração-inicial)
+  * [Scheduler](#2-scheduler)
+  * [Consumer](#3-consumer)
+  * [Job](#4-job)
+* [Configurações](#configurações)
+  * [Configuração Global](#1-configuração-global)
+  * [Hooks](#2-hooks)
+* [Processo Background](#processo-background)
+* [Recursos avançados](#recursos-avançados)
+* [Desenvolvimento](#desenvolvimento)
+* [Contribuição](#contribuição)
+* [Licença](#licença)
+
+## Requisitos
+
+* Ruby `>= 3.0.0`
+* Dependências de runtime (instaladas automaticamente junto com a gem):
+  * [`aws-sdk-sqs`](https://rubygems.org/gems/aws-sdk-sqs) `~> 1.116`
+  * [`parallel`](https://rubygems.org/gems/parallel) `~> 2.1`
+
+Você também precisa de credenciais AWS válidas com acesso ao SQS.
+
+## Instalação
+
+Adicione esta linha na Gemfile da aplicação:
+
+```ruby
+gem 'sqs_simplify'
+```
+
+E execute:
+
+    $ bundle install
+
+Ou instale você mesmo com:
+
+    $ gem install sqs_simplify
+___
+
+## Como usar
+### 1. Configuração Inicial
+
+Crie um arquivo de configuração para ser carregado na inicialização da aplicação.
+
+Exemplo: *sqs_simplify.rb*
+
+Se for uma aplicação **Rails**, crie em *config/initializers/sqs_simplify.rb*.
+
+Neste arquivo você pode configurar as credenciais da AWS e outras customizações.
+
+```ruby
+# sqs_simplify.rb
+
+SqsSimplify.configure do |config|
+  config.access_key_id = ENV['AWS_ACCESS_KEY_ID']
+  config.secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
+  config.region = 'us-east-1'
+
+  config.queue_prefix = Rails.env # optional
+  config.queue_suffix = 'my_application_name' # optional
+end
+```
+___
+
+
+### 2. Scheduler
+
+O componente Scheduler é responsável por enviar mensagens para a fila SQS.
+
+Seu foco principal é na utilização de uma fila como barramento entre duas aplicações distintas.
+
+Por exemplo: a aplicação **A** tem um Scheduler que envia mensagem para a fila SQS, mas quem vai consumir esta mensagem será a aplicação **B**.
+
+```ruby
+# app/jobs/my_scheduler
+
+class MyScheduler < SqsSimplify::Scheduler
+end
+
+
+# app/model/wheel_factory.rb
+
+class WheelFactory
+  def send_now
+    message = { wheels: ['back_wheel', 'front_wheel'], type: 'motorcycle' }
+    MyScheduler.send_message(message: message)
+  end
+  
+  def send_later(delay)
+    message = { wheels: ['back_wheel', 'front_wheel'], type: 'motorcycle' }
+    MyScheduler.send_message(message: message, after: delay)
+  end
+end
+
+
+wheel_factory = WheelFactory.new
+
+# run now
+wheel_factory.send_now # "8685d169-f4a0-476b-b970-39ee055f957b"
+
+# run after 2 minutes
+wheel_factory.send_later(120) # "5ebd6a74-8571-43e2-a9c8-7866b7598765"
+
+```
+
+#### `group_id`
+
+O parâmetro `group_id` é enviado ao SQS como `message_group_id`. Informe-o em
+`send_message`:
+
+```ruby
+MyScheduler.send_message(message: message, group_id: 'tenant-123')
+```
+
+Seu significado depende do tipo de fila:
+
+* **Filas FIFO**: o SQS exige `message_group_id`. Mensagens com o mesmo
+  `group_id` são processadas em ordem (FIFO).
+* **Filas standard**: o `message_group_id` é usado como identificador de
+  *tenant* para o recurso de [fair queues](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-fair-queues.html),
+  que mitiga o impacto de *noisy neighbor* em filas multi-tenant. Aqui ele
+  **não** garante ordenação — serve apenas para agrupar mensagens por tenant.
+
+Se omitido (`nil`), nenhum `message_group_id` é enviado.
+
+### 3. Consumer
+
+O componente Consumer é responsável por consumir mensagens da fila SQS.
+
+Seu foco principal também é na utilização de uma fila como barramento entre duas aplicações distintas.
+
+Por exemplo: a aplicação **B** tem um Consumer que solicita mensagens da fila SQS que foram enviadas pela aplicação **A**.
+
+```ruby
+# app/jobs/motorcycle_assembler.rb
+
+class MotorcycleAssembler < SqsSimplify::Consumer
+  
+  def perform
+    # your logic here
+    # your object has "message" method with data of sqs_message
+    p message # {:wheels=>["back_wheel", "front_wheel"], :type=>"motorcycle"}
+  end
+  
+end
+
+```
+
+
+### 4. Job
+
+O componente Job é responsável por enviar e consumir mensagens da fila SQS dentro da mesma aplicação.
+
+Diferente dos outros componentes, seu foco **não** é na utilização de uma fila como barramento.
+
+Por exemplo: sua aplicação tem uma classe **Report** que gera um relatório.
+Este processamento demora muito para ser executado.
+Então você pode agendar a execução para mais tarde.
+
+O método de negócio **deve** se chamar `perform`.
+
+```ruby
+# app/jobs/report.rb
+
+class Report < SqsSimplify::Job
+  
+  def perform(list)
+    # your logic here
+    PersistReport.save(list)
+  end
+  
+end
+
+list = # many data
+
+# enfileira para execução posterior
+Report.perform_later(list) # "76107a55-43d9-4f2e-b449-02c329a51692"
+
+# enfileira com atraso de 180 segundos
+Report.new_job(after: 180).perform_later(list) # "be6837d5-c11f-495c-a03e-cb093011f1d0"
+
+# executa inline, sem enfileirar
+# atenção, não será agendado
+Report.perform(list) # :executed
+```
+
+___
+
+## Configurações
+
+### 1. Configuração Global
+
+#### SqsSimplify
+Toda configuração feita na classe SqsSimplify será aplicada em todos os componentes.
+
+Exemplo:
+
+```ruby
+# sqs_simplify.rb
+
+SqsSimplify.configure do |config|
+  config.access_key_id = ENV['AWS_ACCESS_KEY_ID']
+  config.secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
+  config.region = 'us-east-2'
+
+  config.queue_prefix = 'production'
+end
+```
+
+Com esta configuração todos os componentes — Scheduler, Consumer e Job — terão a mesma configuração.
+
+Todos terão acesso às filas SQS de *us-east-2*
+
+Todos terão o prefixo de *production*
+
+
+```ruby
+
+class MyScheduler < SqsSimplify::Scheduler
+  
+end
+
+class MyConsumer < SqsSimplify::Consumer
+
+end
+
+class MyJob < SqsSimplify::Job
+
+end
+
+# same prefix
+MyScheduler.queue_name # "production_my_scheduler"
+MyConsumer.queue_name # "production_my_consumer"
+MyJob.queue_name # "production_my_job"
+
+```
+
+### 2. Hooks
+
+**resolver_exception:** É invocado sempre que ocorrer uma **Exception** na sua aplicação.
+Disponibiliza dois parâmetros:
+* o **primeiro parâmetro** é uma **Exception**.
+* o **segundo parâmetro** pode variar de acordo com o componente e onde ocorreu a **Exception**.
+
+**message_not_deleted:** É invocado quando um Job ou Consumer pega uma mensagem da fila SQS e não consegue apagá-la.
+Há dois principais motivos para isso ocorrer:
+* **Exception**: quando ocorre uma **Exception**. Obs: também será invocado o hook **resolver_exception**.
+* **Default visibility timeout**: a mensagem não foi processada no tempo definido.
+
+```ruby
+# sqs_simplify.rb
+
+SqsSimplify.configure do |config|
+  config.hooks.resolver_exception do |exception, args|
+    logger.info "Exception => #{exception.message}, args => #{args}"
+  end
+
+  config.hooks.message_not_deleted do |consumer|
+    logger.info "Consumer => #{consumer}"
+  end
+end
+```
+
+___
+
+## Processo Background
+### 1. Configuração
+Para rodar o processo de consumo deve criar um arquivo de script.
+O método `run` roda um loop em foreground que consome as filas até receber
+`SIGINT` (Ctrl+C) — não daemoniza o processo.
+Exemplo de um arquivo de script nomeado de *sqs_simplify*
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'sqs_simplify/command'
+SqsSimplify::Command.new(ARGV).run
+```
+
+Para projeto Rails você pode carregar a aplicação antes da invocação da GEM.
+Exemplo de um arquivo de script nomeado de *bin/sqs_simplify*
+```ruby
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'config', 'environment'))
+require 'sqs_simplify/command'
+SqsSimplify::Command.new(ARGV).run
+```
+
+E deve dar permissão de execução.
+````bash
+$ chmod +x sqs_simplify
+````
+
+### 2. Comandos
+Para ver as opções do comando, execute no diretório do arquivo:
+
+````bash
+$ sqs_simplify -h
+Usage: sqs_simplify [options]
+    -h, --help                       Show help
+    -n, --number_of_workers=workers  Number of unique workers to spawn
+    -e, --environment=environment    Environment
+        --queues=queues              queues that will be consumed
+        --priority                   with priority in the queues
+    -f, --fork                       parallel in processes
+    -t, --thread                     parallel in threads
+
+
+````
+
+___
+
+## Recursos avançados
+
+Além do básico apresentado acima, a gem também oferece:
+
+* **`map_queue(nickname, &block)`** — roteia um único Scheduler para filas
+  alternativas dinamicamente (`SqsSimplify::Scheduler`).
+* **Sobrescrita de destino por chamada** — passe `queue_url:` para `send_message`
+  para enviar uma mensagem a uma fila específica no momento da chamada.
+* **DSL `set` por classe** — sobrescreve configurações por classe, como o nome da
+  fila, o visibility timeout, a serialização (`dump_message`/`load_message`) e mais,
+  por exemplo `set :queue_name, 'custom_name'`.
+* **Dead-letter queues automáticas** — cada fila ganha uma `<nome>_dead`
+  pareada como dead-letter queue.
+* **Hooks adicionais** — além de `resolver_exception` e `message_not_deleted`, o
+  pipeline também suporta os hooks `before`/`after` (`:each` / `:all`) e `around`.
+* **Testes sem AWS** — defina `config.faker = true` para usar o `FakerClient` em
+  memória, ou `config.stub_responses = true` para stubar o cliente `aws-sdk-sqs`.
+
+## Desenvolvimento
+
+Após clonar o repositório, instale as dependências e rode a suíte de testes:
+
+```bash
+bin/setup                  # instala as dependências
+bundle exec rake spec      # roda a suíte de testes completa
+bundle exec rubocop        # lint
+bin/console                # prompt interativo para experimentar
+```
+
+Os testes rodam contra um cliente SQS falso em memória, então nenhum acesso real à
+AWS é necessário.
+
+Para instalar esta gem na sua máquina local, rode `bundle exec rake install`. Para
+publicar uma nova versão, atualize o número da versão em `lib/sqs_simplify/version.rb`
+e então rode `bundle exec rake release`.
+
+## Contribuição
+
+Relatos de bugs e pull requests são bem-vindos no GitHub em
+https://github.com/ralphsbaesso/sqs_simplify. Para contribuir:
+
+1. Faça um fork do repositório.
+2. Crie um branch de feature (`git checkout -b minha-feature`).
+3. Faça commit das suas alterações e garanta que os testes (`bundle exec rake spec`)
+   e o linter (`bundle exec rubocop`) passem.
+4. Abra um pull request.
+
+
+## Licença
+
+A gem está disponível como código aberto sob os termos da [Licença MIT](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'sqs_simplify'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/sqs_simplify/base.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module SqsSimplify
+  class Base
+    include SqsSimplify::Client
+
+    VISIBILITY_TIMEOUT = 10 * 60
+    MESSAGE_RETENTION_PERIOD = 14 * 24 * 60 * 60
+    DELAY_SECONDS = 0
+
+    protected
+
+    def dump_message(value)
+      self.class.dump_message value
+    end
+
+    def load_message(value)
+      self.class.load_message value
+    end
+
+    class << self
+      def set(key, value)
+        settings[key.to_sym] = value
+      end
+
+      def queue_name
+        (settings[:queue_name] || to_underscore(name)).to_s
+      end
+
+      def queue_full_name
+        build_queue_full_name
+      end
+
+      def queue_url
+        @queue_url ||= client.get_queue_url(queue_name: queue_full_name).queue_url
+      rescue Aws::SQS::Errors::NonExistentQueue
+        raise SqsSimplify::Errors::NonExistentQueue, queue_full_name
+      end
+
+      def dead_queue
+        @dead_queue ||= build_dead_queue_class
+      end
+
+      def count_messages
+        approximate_number_of_messages(load: true)
+      end
+
+      def approximate_number_of_messages(load: false)
+        queue_info(load: load)['ApproximateNumberOfMessages'].to_i
+      end
+
+      def queue_info(load: false)
+        @queue_info = nil if load
+        @queue_info ||= client.get_queue_attributes(queue_url: queue_url, attribute_names: ['All']).attributes
+      end
+
+      def queue_arn(load: false)
+        queue_info(load: load)['QueueArn']
+      end
+
+      def approximate_number_of_messages_not_visible(load: false)
+        queue_info(load: load)['ApproximateNumberOfMessagesNotVisible'].to_i
+      end
+
+      def created_at(load: false)
+        DateTime.strptime(queue_info(load: load)['CreatedTimestamp'], '%s')
+      end
+
+      def updated_at(load: false)
+        DateTime.strptime(queue_info(load: load)['LastModifiedTimestamp'], '%s')
+      end
+
+      def visibility_timeout(load: false)
+        queue_info(load: load)['VisibilityTimeout'].to_i
+      end
+
+      def message_retention_period(load: false)
+        queue_info(load: load)['MessageRetentionPeriod'].to_i
+      end
+
+      def max_receive_count
+        @max_receive_count ||= build_max_receive_count
+      end
+
+      def dump_message(value)
+        dump_message = settings[:dump_message] || :to_json
+
+        case dump_message
+        when Proc
+          dump_message.call value
+        when :to_json
+          value.to_json
+        else
+          value.to_s
+        end
+      end
+
+      def load_message(message)
+        body = message.body
+        load_message = settings[:load_message] || :to_json
+
+        case load_message
+        when Proc
+          load_message.call body
+        when :to_json
+          JSON.parse(body)
+        else
+          body
+        end
+      end
+
+      def settings
+        @settings ||= {}
+      end
+
+      def create_queue_and_dead_queue
+        create_queue
+        dead_queue.create_queue
+        true
+      end
+
+      def create_queue
+        queue = find_queue_by_name(queue_full_name)
+        return queue if queue
+
+        client.create_queue(
+          queue_name: queue_full_name,
+          attributes: default_attributes
+        )
+      end
+
+      def find_queue_by_name(name)
+        client.get_queue_url(queue_name: name)
+      rescue Aws::SQS::Errors::NonExistentQueue
+        nil
+      end
+
+      def update_attributes(**attributes)
+        attributes = attributes.map { |att| att.map(&:to_s) }.to_h
+        client.set_queue_attributes(
+          queue_url: queue_url,
+          attributes: attributes
+        )
+        true
+      end
+
+      private
+
+      def build_queue_full_name
+        [
+          settings[:queue_prefix] || SqsSimplify.settings.queue_prefix,
+          queue_name,
+          settings[:queue_suffix] || SqsSimplify.settings.queue_suffix
+        ].reject { |value| value.nil? || value.empty? }
+          .join('_')
+      end
+
+      def build_dead_queue_class
+        class_name = "::#{name}::DeadQueue"
+
+        class_eval <<~M, __FILE__, __LINE__ + 1
+          class #{class_name} < SqsSimplify::DeadQueue; end
+        M
+
+        dead_queue_class = const_get class_name
+        dead_queue_class.set :queue_name, "#{queue_name}_dead"
+        dead_queue_class
+      end
+
+      def build_max_receive_count
+        value = settings[:max_receive_count].to_i
+        value.positive? ? value : 1
+      rescue StandardError
+        1
+      end
+
+      def default_attributes
+        visibility_timeout = settings[:visibility_timeout] || self::VISIBILITY_TIMEOUT # Should be between 0 seconds and 12 hours.
+        message_retention_period = settings[:message_retention_period] || self::MESSAGE_RETENTION_PERIOD # retention, Should be between 1 minute and 14 days.
+        delay_seconds = settings[:delay_seconds] || self::DELAY_SECONDS
+
+        {
+          VisibilityTimeout: visibility_timeout.to_s,
+          MessageRetentionPeriod: message_retention_period.to_s,
+          DelaySeconds: delay_seconds.to_s
+        }
+      end
+
+      def to_underscore(value)
+        value.gsub(/::/, '_')
+             .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+             .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+             .tr('-', '_')
+             .downcase
+      end
+
+      def inherited(sub)
+        super
+        return if sub.name.nil?
+        return if %w[SqsSimplify::Job SqsSimplify::Consumer SqsSimplify::Scheduler].include? sub.name
+
+        if sub < SqsSimplify::Consumer || sub < SqsSimplify::Job
+          SqsSimplify.consumers << sub
+        elsif sub < SqsSimplify::Scheduler
+          SqsSimplify.schedulers << sub
+        end
+      end
+    end
+  end
+end

data/lib/sqs_simplify/client.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SqsSimplify
+  module Client
+    protected
+
+    def client
+      self.class.client
+    end
+
+    module ClassMethods
+      def client
+        @client ||= build_client
+      end
+
+      private
+
+      def build_client
+        args = {
+          access_key_id: settings[:access_key_id] || SqsSimplify.settings.access_key_id,
+          secret_access_key: settings[:secret_access_key] || SqsSimplify.settings.secret_access_key,
+          region: settings[:region] || SqsSimplify.settings.region,
+          stub_responses: SqsSimplify.settings.stub_responses
+        }.select { |_k, v| v }
+
+        SqsSimplify.settings.faker ? SqsSimplify::FakerClient.new : Aws::SQS::Client.new(args)
+      end
+    end
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+  end
+end