onyxcord 1.1.2 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db2ea75e128f4af32b52f4294172ebbee5faf88b7902f8de2acddb8acbd2d2e3
-  data.tar.gz: 272050db561c6c336af4cc6139739e89ed2d6106d7aff2a57dc638d36f488644
+  metadata.gz: faa13116d56881eff441634bdd885ed2650739cdea9be5e3807ec94d0c4c8965
+  data.tar.gz: 8738d765d59e229c5c1476bc1029e32c82f6ad1d417295380ffaae4fb8d65e22
 SHA512:
-  metadata.gz: 5c42dd6e2d9f0164e980f51900aa88b54dac91c9ce6d8089eae79abfe4f2713f394d89e183a8c283c5b5cb2da08071e8a199575bfc737b3ef6db2f358522f8de
-  data.tar.gz: eb7893bc0509de3d71e31434fbdaead376d51e97e96744f5b7448d5f1aeb721d6fe55d2585cac219bd3742d1c4402b5e0cb61234e5bdcfe3e7cebeead0ee75a9
+  metadata.gz: e36c649784e3eda4f2928bf2801013072fabf8bd40b4f5bcba232fef37155fc36ccfa27041656ef988152a78d1bbe9b4d3145e7cf384169b8279d1f80417f5f6
+  data.tar.gz: a4dd38f5c246e0bc9e9432ee0f75f54a641bbce30cf143a4b95eb73f8da08810baa76d4fd46e81e279e9d2cac5e4618df8f3f0acbb9c15ecc5643e411ac21592

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 1.1.4 - 2026-06-28
+
+### Melhorias
+
+- `MediaGallery` agora aceita URLs diretas e hashes no builder, como `media_gallery('https://...')`, alem do formato em bloco.
+- `FileComponent`/`file_display` agora aceita a URL do attachment como primeiro argumento, como `file_display('attachment://arquivo.txt')`.
+
+### Correcoes
+
+- Parser de `MediaGallery` e `FileUpload` ficou mais tolerante quando o payload nao traz `items` ou `values`.
+
+### Validacao
+
+- `bundle exec rspec spec/components_v2_spec.rb`: 13 exemplos, 0 falhas.
+
+## 1.1.3 - 2026-06-23
+
+### Melhorias
+
+- Alterado o modo padrao do bot para `:hybrid`, mantendo suporte a handlers raw e eventos em objeto sem configuracao extra.
+- Adicionado `event_queue_size` para permitir fila de eventos com limite via `SizedQueue`.
+- Application commands agora usam o `EventExecutor`, evitando criacao direta de threads por interaction.
+- Adicionados `runtime_stats`, `cache_stats`, `prune_cache!` e `OnyxCord::API.rate_limiter_stats` para diagnostico de memoria e runtime.
+- Rate limiter REST agora expoe `stats`, `prune!` e limpeza automatica de bookkeeping antigo.
+- Voice recebeu limpeza mais segura de UDP, WebSocket, threads e leitura DCA com fechamento garantido de arquivo.
+- Dependencias principais receberam upper bounds conservadores para reduzir risco de quebra em releases futuras.
+
+### Correcoes
+
+- Corrigido retry de respostas REST `202` para reutilizar a rota e o major parameter originais.
+- Removidos logs temporarios de interaction no caminho quente de dispatch.
+- Corrigido warning de spec causado por expectativa em cache de usuarios nulo.
+
+### Validacao
+
+- `bundle exec rspec`: 456 exemplos, 0 falhas, 3 pendentes.
+- RuboCop nos arquivos alterados: sem offenses.
+- `gem build onyxcord.gemspec`: sucesso.
+- `gem build onyxcord-webhooks.gemspec`: sucesso.

data/README.md

@@ -103,8 +103,21 @@ end
 bot.run
 ```
 
-Use `mode: :raw` quando quiser evitar a criação de objetos pesados por padrão e processar apenas os pacotes de Gateway diretamente. 
-**Importante:** O `OnyxCord` roda em `:raw` por padrão. Se você quiser usar os comandos de aplicação normais (`application_command`), modais e outros eventos em objeto, **você deve inicializar o bot com `mode: :hybrid`** ou `mode: :object`!
+Use `mode: :raw` quando quiser evitar a criação de objetos pesados e processar apenas os pacotes de Gateway diretamente.
+**Importante:** O `OnyxCord` roda em `:hybrid` por padrão, entao comandos de aplicação normais (`application_command`), modais e outros eventos em objeto ja funcionam sem precisar informar `mode: :hybrid`.
+
+## Performance e memória
+
+Para limitar crescimento de fila quando handlers ficam lentos, configure um tamanho maximo para a fila do executor:
+
+```ruby
+OnyxCord.configure do |config|
+  config.event_workers = 4
+  config.event_queue_size = 1_000
+end
+```
+
+Em bots grandes, use `bot.runtime_stats`, `bot.cache_stats` e `bot.prune_cache!` para acompanhar e limpar caches em runtime.
 
 ## Components V2
 

data/lib/onyxcord/api.rb

@@ -67,6 +67,10 @@ module OnyxCord::API
     @rate_limiter ||= OnyxCord::RateLimiter::Rest.new
   end
 
+  def rate_limiter_stats
+    rate_limiter.stats
+  end
+
   # Wait a specified amount of time synchronised with the specified mutex.
   def sync_wait(time, mutex)
     mutex.synchronize { sleep time }
@@ -151,7 +155,7 @@ module OnyxCord::API
           sleep(body['retry_after'])
         end
 
-        return request(*key, type, *attributes)
+        return request(key, major_parameter, type, *attributes)
       end
     end
 

data/lib/onyxcord/bot.rb

@@ -132,13 +132,14 @@ module OnyxCord
       type: nil, name: '', fancy_log: false, suppress_ready: false, parse_self: false,
       shard_id: nil, num_shards: nil, redact_token: true, ignore_bots: false,
       compress_mode: :large, intents: :minimal,
-      mode: nil, cache: nil, event_executor: nil, event_workers: nil
+      mode: nil, cache: nil, event_executor: nil, event_workers: nil, event_queue_size: nil
     )
       config = OnyxCord.configuration
       @mode = config.normalize_mode(mode)
       @cache_policy = config.normalize_cache(cache)
       executor_type = config.normalize_event_executor(event_executor)
       executor_workers = config.normalize_event_workers(event_workers)
+      executor_queue_size = config.normalize_event_queue_size(event_queue_size)
 
       LOGGER.mode = log_mode
       LOGGER.token = token if redact_token
@@ -185,7 +186,7 @@ module OnyxCord
 
       @current_thread = 0
       @current_thread_mutex = Mutex.new
-      @event_executor = EventExecutor.build(executor_type, workers: executor_workers)
+      @event_executor = EventExecutor.build(executor_type, workers: executor_workers, queue_size: executor_queue_size)
       @event_threads = @event_executor.threads
 
       @status = :online
@@ -712,6 +713,16 @@ module OnyxCord
       LOGGER.mode = new_mode
     end
 
+    def runtime_stats
+      {
+        mode: @mode,
+        cache: cache_stats,
+        event_executor: @event_executor.class.name,
+        event_threads: @event_threads&.count(&:alive?) || 0,
+        event_queue_size: @event_executor.respond_to?(:queue_size) ? @event_executor.queue_size : 0
+      }
+    end
+
     # Prevents the READY packet from being printed regardless of debug mode.
     def suppress_ready_debug
       @prevent_ready = true
@@ -1677,30 +1688,19 @@ module OnyxCord
 
         raise_event(event)
       when :INTERACTION_CREATE
-        OnyxCord::LOGGER.info(">>> INTERACTION_CREATE received inside bot.rb! type: #{data['type']}")
         event = InteractionCreateEvent.new(data, self)
         raise_event(event)
-        OnyxCord::LOGGER.info(">>> raised InteractionCreateEvent successfully")
 
         case data['type']
         when Interaction::TYPES[:command]
-          OnyxCord::LOGGER.info(">>> creating ApplicationCommandEvent")
           event = ApplicationCommandEvent.new(data, self)
-          OnyxCord::LOGGER.info(">>> spawned Thread to execute command")
-
-          Thread.new(event) do |evt|
-            Thread.current[:onyxcord_name] = "it-#{evt.interaction.id}"
-
-            begin
-              OnyxCord::LOGGER.info(">>> Executing application command #{evt.command_name}:#{evt.command_id}")
-              handler = @application_commands[evt.command_name]
-              OnyxCord::LOGGER.info(">>> Handler found? #{!handler.nil?}")
-              handler&.call(evt)
-              OnyxCord::LOGGER.info(">>> Handler call finished")
-            rescue Exception => e
-              OnyxCord::LOGGER.error(">>> FATAL EXCEPTION IN THREAD: #{e.class}: #{e.message}")
-              log_exception(e)
-            end
+
+          @event_executor.post do
+            Thread.current[:onyxcord_name] = next_event_thread_name('it')
+            handler = @application_commands[event.command_name]
+            handler&.call(event)
+          rescue StandardError => e
+            log_exception(e)
           end
         when Interaction::TYPES[:component]
           case data['data']['component_type']

data/lib/onyxcord/cache.rb

@@ -12,6 +12,17 @@ module OnyxCord
   # the caching (like, storing the user hashes or making API calls to retrieve things) from the Bot that
   # actually uses it.
   module Cache
+    CACHE_STORES = {
+      users: :@users,
+      voice_regions: :@voice_regions,
+      servers: :@servers,
+      channels: :@channels,
+      pm_channels: :@pm_channels,
+      thread_members: :@thread_members,
+      server_previews: :@server_previews,
+      request_members: :@request_members_rl
+    }.freeze
+
     # Initializes this cache
     def init_cache
       @cache_policy ||= OnyxCord.configuration.normalize_cache(:full)
@@ -32,6 +43,24 @@ module OnyxCord
       @cache_policy.fetch(key, true)
     end
 
+    def cache_stats
+      CACHE_STORES.each_with_object({}) do |(key, ivar), stats|
+        store = instance_variable_get(ivar)
+        stats[key] = store.respond_to?(:size) ? store.size : 0
+      end
+    end
+
+    def prune_cache!(*keys)
+      keys = CACHE_STORES.keys if keys.empty?
+
+      keys.each_with_object({}) do |key, pruned|
+        ivar = CACHE_STORES.fetch(key)
+        store = instance_variable_get(ivar)
+        pruned[key] = store.respond_to?(:size) ? store.size : 0
+        store&.clear
+      end
+    end
+
     # Returns or caches the available voice regions
     def voice_regions
       return fetch_voice_regions unless cache_enabled?(:voice_regions)

data/lib/onyxcord/configuration.rb

@@ -43,13 +43,14 @@ module OnyxCord
       }
     }.freeze
 
-    attr_accessor :mode, :cache, :event_executor, :event_workers
+    attr_accessor :mode, :cache, :event_executor, :event_workers, :event_queue_size
 
     def initialize
-      @mode = :raw
+      @mode = :hybrid
       @cache = :none
       @event_executor = :pool
       @event_workers = 4
+      @event_queue_size = nil
     end
 
     def dup
@@ -58,6 +59,7 @@ module OnyxCord
       copy.cache = @cache.is_a?(Hash) ? @cache.dup : @cache
       copy.event_executor = @event_executor
       copy.event_workers = @event_workers
+      copy.event_queue_size = @event_queue_size
       copy
     end
 
@@ -82,6 +84,15 @@ module OnyxCord
       workers
     end
 
+    def normalize_event_queue_size(value = @event_queue_size)
+      return nil if value.nil?
+
+      size = Integer(value)
+      raise ArgumentError, 'event_queue_size must be greater than zero' unless size.positive?
+
+      size
+    end
+
     def normalize_cache(value = @cache)
       cache = value.nil? ? @cache : value
 

data/lib/onyxcord/data/component.rb

@@ -331,7 +331,7 @@ module OnyxCord
       def initialize(data, bot)
         @bot = bot
         @id = data['id']
-        @items = data['items'].map { |item| Item.new(item, @bot) }
+        @items = Array(data['items']).map { |item| Item.new(item, @bot) }
       end
 
       # A singular media attachment.
@@ -515,7 +515,7 @@ module OnyxCord
         @bot = bot
         @id = data['id']
         @custom_id = data['custom_id']
-        @values = data['values'].map(&:to_i)
+        @values = Array(data['values']).map(&:to_i)
       end
     end
 

data/lib/onyxcord/event_executor.rb

@@ -20,12 +20,12 @@ module OnyxCord
 
     # Fixed-size worker pool for event handlers.
     class Pool
-      attr_reader :threads
+      attr_reader :threads, :queue
 
-      def initialize(size:)
+      def initialize(size:, queue_size: nil)
         raise ArgumentError, 'Pool size must be greater than zero' unless size.positive?
 
-        @queue = Queue.new
+        @queue = queue_size ? SizedQueue.new(queue_size) : Queue.new
         @closed = false
         @threads = Array.new(size) do |index|
           Thread.new do
@@ -42,6 +42,10 @@ module OnyxCord
         @queue << block
       end
 
+      def queue_size
+        @queue.size
+      end
+
       def shutdown
         return if @closed
 
@@ -66,12 +70,12 @@ module OnyxCord
 
     module_function
 
-    def build(type, workers:)
+    def build(type, workers:, queue_size: nil)
       case type
       when :inline
         Inline.new
       when :pool
-        Pool.new(size: workers)
+        Pool.new(size: workers, queue_size: queue_size)
       else
         raise ArgumentError, "Unknown event executor: #{type.inspect}"
       end

data/lib/onyxcord/rate_limiter/rest.rb

@@ -7,10 +7,18 @@ module OnyxCord
     # Discord REST rate limiter keyed by route/major parameter and remapped to
     # X-RateLimit-Bucket whenever Discord returns a concrete bucket id.
     class Rest
-      def initialize
+      DEFAULT_ENTRY_TTL = 3600
+      DEFAULT_PRUNE_INTERVAL = 100
+
+      def initialize(clock: -> { Time.now }, entry_ttl: DEFAULT_ENTRY_TTL, prune_interval: DEFAULT_PRUNE_INTERVAL)
         @route_buckets = {}
         @bucket_mutexes = {}
+        @bucket_last_used = {}
         @global_mutex = Mutex.new
+        @clock = clock
+        @entry_ttl = entry_ttl
+        @prune_interval = prune_interval
+        @requests_since_prune = 0
       end
 
       def before_request(route, major_parameter)
@@ -21,8 +29,14 @@ module OnyxCord
       def record_response(route, major_parameter, headers)
         headers = normalize_headers(headers)
         bucket = headers[:x_ratelimit_bucket]
+        key = route_key(route, major_parameter)
+        touch(key)
 
-        @route_buckets[route_key(route, major_parameter)] = bucket_key(bucket, major_parameter) if bucket
+        if bucket
+          bucket = bucket_key(bucket, major_parameter)
+          @route_buckets[key] = bucket
+          touch(bucket)
+        end
 
         return unless headers[:x_ratelimit_remaining] == '0'
 
@@ -40,10 +54,37 @@ module OnyxCord
         sync_wait(wait_seconds, mutex) if wait_seconds.positive?
       end
 
+      def stats
+        {
+          route_buckets: @route_buckets.size,
+          bucket_mutexes: @bucket_mutexes.size,
+          tracked_keys: @bucket_last_used.size
+        }
+      end
+
+      def prune!
+        return 0 unless @entry_ttl
+
+        cutoff = @clock.call - @entry_ttl
+        stale_keys = @bucket_last_used.select { |_, last_used| last_used < cutoff }.keys
+
+        stale_keys.each do |key|
+          @bucket_mutexes.delete(key)
+          @bucket_last_used.delete(key)
+          @route_buckets.delete(key)
+          @route_buckets.delete_if { |_, bucket_key| bucket_key == key }
+        end
+
+        @requests_since_prune = 0
+        stale_keys.length
+      end
+
       private
 
       def mutex_for(route, major_parameter)
-        @bucket_mutexes[resolved_key(route, major_parameter)] ||= Mutex.new
+        key = resolved_key(route, major_parameter)
+        touch(key)
+        @bucket_mutexes[key] ||= Mutex.new
       end
 
       def resolved_key(route, major_parameter)
@@ -76,6 +117,18 @@ module OnyxCord
         end
       end
 
+      def touch(key)
+        @bucket_last_used[key] = @clock.call
+        prune_if_needed
+      end
+
+      def prune_if_needed
+        return unless @prune_interval
+
+        @requests_since_prune += 1
+        prune! if @requests_since_prune >= @prune_interval
+      end
+
       def sync_wait(time, mutex)
         mutex.synchronize { sleep time }
       end

data/lib/onyxcord/version.rb

@@ -3,5 +3,5 @@
 # OnyxCord and all its functionality, in this case only the version.
 module OnyxCord
   # The current version of onyxcord.
-  VERSION = '1.1.2'
+  VERSION = '1.1.4'
 end

data/lib/onyxcord/voice/network.rb

@@ -113,6 +113,10 @@ module OnyxCord::Voice
       send_packet(discovery_packet)
     end
 
+    def close
+      @socket.close unless @socket.closed?
+    end
+
     private
 
     # Encrypts audio data using libsodium
@@ -339,8 +343,12 @@ module OnyxCord::Voice
     end
 
     # Disconnects the websocket and kills the thread
-    def destroy
+    def destroy(join_timeout = 1)
       @heartbeat_running = false
+      @client&.close
+      @udp.close
+      @thread&.join(join_timeout)
+      @thread&.kill if @thread&.alive?
     end
 
     private

data/lib/onyxcord/voice/voice_bot.rb

@@ -265,36 +265,37 @@ module OnyxCord::Voice
       stop_playing(true) if @playing
 
       @bot.debug "Reading DCA file #{file}"
-      input_stream = File.open(file)
 
-      magic = input_stream.read(4)
-      raise ArgumentError, 'Not a DCA1 file! The file might have been corrupted, please recreate it.' unless magic == 'DCA1'
+      File.open(file) do |input_stream|
+        magic = input_stream.read(4)
+        raise ArgumentError, 'Not a DCA1 file! The file might have been corrupted, please recreate it.' unless magic == 'DCA1'
 
-      # Read the metadata header, then read the metadata and discard it as we don't care about it
-      metadata_header = input_stream.read(4).unpack1('l<')
-      input_stream.read(metadata_header)
+        # Read the metadata header, then read the metadata and discard it as we don't care about it
+        metadata_header = input_stream.read(4).unpack1('l<')
+        input_stream.read(metadata_header)
 
-      # Play the data, without re-encoding it to opus
-      play_internal do
-        begin
-          # Read header
-          header_str = input_stream.read(2)
+        # Play the data, without re-encoding it to opus
+        play_internal do
+          begin
+            # Read header
+            header_str = input_stream.read(2)
+
+            unless header_str
+              @bot.debug 'Finished DCA parsing (header is nil)'
+              next :stop
+            end
+
+            header = header_str.unpack1('s<')
 
-          unless header_str
-            @bot.debug 'Finished DCA parsing (header is nil)'
+            raise 'Negative header in DCA file! Your file is likely corrupted.' if header.negative?
+          rescue EOFError
+            @bot.debug 'Finished DCA parsing (EOFError)'
             next :stop
           end
 
-          header = header_str.unpack1('s<')
-
-          raise 'Negative header in DCA file! Your file is likely corrupted.' if header.negative?
-        rescue EOFError
-          @bot.debug 'Finished DCA parsing (EOFError)'
-          next :stop
+          # Read bytes
+          input_stream.read(header)
         end
-
-        # Read bytes
-        input_stream.read(header)
       end
     end
 

data/onyxcord-webhooks.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'rest-client', '>= 2.0.0'
+  spec.add_dependency 'rest-client', '>= 2.0.0', '< 3'
 
   spec.required_ruby_version = '>= 3.3'
   spec.metadata = {

data/onyxcord.gemspec

@@ -27,10 +27,10 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'base64', '~> 0.2'
-  spec.add_dependency 'ffi', '>= 1.9.24'
-  spec.add_dependency 'opus-ruby'
-  spec.add_dependency 'rest-client', '>= 2.0.0'
-  spec.add_dependency 'websocket-client-simple', '>= 0.9.0'
+  spec.add_dependency 'ffi', '>= 1.9.24', '< 2'
+  spec.add_dependency 'opus-ruby', '>= 0', '< 2'
+  spec.add_dependency 'rest-client', '>= 2.0.0', '< 3'
+  spec.add_dependency 'websocket-client-simple', '>= 0.9.0', '< 1'
 
   spec.add_dependency 'onyxcord-webhooks', "~> #{OnyxCord::Webhooks::VERSION}"
 

data/relator.md

@@ -0,0 +1,298 @@
+# Relatorio geral da OnyxCord
+
+Data da analise: 2026-06-23
+
+Escopo analisado:
+- Gem Ruby `onyxcord` e `onyxcord-webhooks`.
+- Areas principais: REST API, gateway WebSocket, cache, executor de eventos, comandos/interactions, voice e webhooks.
+- Teste executado: `bundle exec rspec`.
+
+Resultado da validacao atual:
+- `bundle exec rspec`: 456 exemplos, 0 falhas, 3 pendentes.
+- Cobertura reportada pelo SimpleCov: 60,84% de linhas.
+- `gem build onyxcord.gemspec`: sucesso, gerou `onyxcord-1.1.2.gem`.
+- `gem build onyxcord-webhooks.gemspec`: sucesso, gerou `onyxcord-webhooks-1.1.2.gem`.
+
+Status das correcoes aplicadas:
+- Corrigido retry REST `202` preservando route e major parameter.
+- Application commands agora executam pelo `EventExecutor`, sem `Thread.new` direto nesse caminho.
+- Adicionado `event_queue_size` com `SizedQueue` opcional.
+- Adicionados `runtime_stats`, `cache_stats`, `prune_cache!` e `OnyxCord::API.rate_limiter_stats`.
+- Rate limiter REST agora tem `stats`, `prune!` e limpeza automatica de bookkeeping antigo.
+- Voice fecha melhor recursos de UDP/WebSocket/thread, e `play_dca` usa `File.open` com bloco.
+- Dependencias principais receberam upper bounds conservadores.
+- Warning de spec em `spec/bot_spec.rb:114` foi corrigido.
+
+## Resumo executivo
+
+A lib ja tem algumas decisoes boas para performance:
+- O modo padrao do bot agora e `hybrid`, equilibrando handlers raw com eventos em objeto.
+- O cache padrao global esta em `:none`, o que ajuda a reduzir RAM para bots pequenos.
+- Ja existe `EventExecutor::Pool`, evitando uma thread nova para cada evento comum.
+- O rate limiter REST ja centraliza buckets, global limit e `retry_after`.
+- O gateway usa zlib stream, economizando trafego e CPU em payloads grandes.
+
+Os maiores ganhos agora estao em 5 frentes:
+1. Eliminar threads soltas em interactions e waits.
+2. Colocar limite/backpressure no executor de eventos.
+3. Colocar estrategia de limite/limpeza nos caches e nos mapas do rate limiter.
+4. Corrigir um bug provavel no retry de resposta REST `202`.
+5. Fechar recursos de voz/arquivos/sockets de forma garantida.
+
+## Prioridade alta
+
+### 1. Corrigir retry de REST `202` em `OnyxCord::API.request`
+
+Arquivo: `lib/onyxcord/api.rb:141-154`
+
+Problema:
+- Quando Discord retorna `202` com codigo `110000`, o metodo tenta repetir a request.
+- A chamada atual usa `return request(*key, type, *attributes)`.
+- Na maior parte da API, `key` e um `Symbol`, entao `*key` tende a quebrar com `TypeError` ou chamar `request` com parametros errados.
+
+Impacto:
+- Endpoints baseados em Elasticsearch podem falhar justamente no fluxo em que deveriam aguardar e tentar de novo.
+
+Sugestao:
+- Trocar para `return request(key, major_parameter, type, *attributes)`.
+- Adicionar spec cobrindo response `202` com `retry_after`.
+
+### 2. Application commands criam `Thread.new` fora do executor
+
+Arquivo: `lib/onyxcord/bot.rb:1679-1704`
+
+Problema:
+- O fluxo de `INTERACTION_CREATE` para command cria uma thread direta por comando.
+- Isso ignora `EventExecutor::Pool`, ignora `event_workers` e remove qualquer controle de concorrencia.
+- Tambem ha logs temporarios com prefixo `>>>` em caminho quente.
+- O rescue usa `rescue Exception`, que captura sinais de sistema e saidas do processo.
+
+Impacto:
+- Em pico de interactions, o processo pode criar muitas threads, consumindo RAM e escalonamento de CPU.
+- Logs verbosos em production aumentam I/O e custo de CPU.
+
+Sugestao:
+- Executar handler via `@event_executor.post`.
+- Usar `rescue StandardError`.
+- Trocar logs `info` temporarios por `debug` ou remover.
+- Nomear a thread dentro do bloco do executor, como ja acontece em `call_event`.
+
+### 3. Fila de eventos sem limite
+
+Arquivo: `lib/onyxcord/event_executor.rb:28-42`
+
+Problema:
+- `Queue.new` e ilimitada.
+- Se os handlers forem mais lentos que os eventos recebidos, a fila cresce sem backpressure.
+
+Impacto:
+- Pode virar crescimento progressivo de RAM em servidores grandes ou bots com handlers pesados.
+
+Sugestao:
+- Adicionar opcao `event_queue_size`, usando `SizedQueue`.
+- Expor comportamento configuravel: bloquear, rejeitar com log, ou executar inline em emergencia.
+- Medir tamanho da fila em debug/telemetria.
+
+## Prioridade media
+
+### 4. Rate limiter guarda mutexes e buckets para sempre
+
+Arquivo: `lib/onyxcord/rate_limiter/rest.rb:10-47`
+
+Problema:
+- `@route_buckets` e `@bucket_mutexes` crescem conforme novas rotas/major parameters aparecem.
+- Para bots que tocam muitos canais, guilds, mensagens ou webhooks, isso pode acumular.
+
+Impacto:
+- RAM pequena por item, mas permanente.
+
+Sugestao:
+- Guardar `last_used_at` por bucket e limpar entradas antigas.
+- Alternativa simples: limitar por LRU.
+- Adicionar metodo `prune!` chamado ocasionalmente em `record_response`.
+
+### 5. Cache full pode crescer sem limite
+
+Arquivo: `lib/onyxcord/cache.rb:16-29`
+
+Problema:
+- Caches de users, channels, pm_channels, thread_members e server_previews sao Hashes sem TTL/max size.
+- O default global e `:none`, mas quem usa `:full` pode segurar muitos objetos.
+
+Impacto:
+- Em bots grandes, memoria cresce com o tempo e dificilmente volta.
+
+Sugestao:
+- Manter `:none` como default.
+- Adicionar opcoes por cache: `max_users`, `max_channels`, `max_messages`, `ttl`.
+- Oferecer `bot.prune_cache!` e `bot.cache_stats`.
+- Considerar guardar payload cru em modo leve, criando objeto sob demanda.
+
+### 6. `request_chunks` cria buckets por guild sem limpeza
+
+Arquivo: `lib/onyxcord/cache.rb:235-253`
+
+Problema:
+- `@request_members_rl[id]` guarda mutex/time por guild e nunca remove.
+
+Impacto:
+- Baixo por guild, mas permanente em bots que entram/saem de muitos servidores.
+
+Sugestao:
+- Remover no evento de saida de guild.
+- Limpar buckets nao usados ha alguns minutos/horas.
+
+### 7. Voice pode deixar arquivo aberto em `play_dca`
+
+Arquivo: `lib/onyxcord/voice/voice_bot.rb:264-299`
+
+Problema:
+- `File.open(file)` nao usa bloco nem `ensure`.
+- Se erro ocorrer durante validacao ou playback, o descritor pode ficar aberto.
+
+Impacto:
+- Vazamento de file descriptor em uso repetido de voz.
+
+Sugestao:
+- Usar `File.open(file) do |input_stream| ... end` ou `ensure input_stream&.close`.
+
+### 8. Voice WebSocket nao fecha/junta thread explicitamente
+
+Arquivo: `lib/onyxcord/voice/network.rb:321-344`
+
+Problema:
+- `destroy` apenas seta `@heartbeat_running = false`.
+- Nao fecha o WebSocket, nao fecha UDP e nao faz join da thread.
+
+Impacto:
+- Possivel sobra de thread/socket em reconexoes ou destroy repetido.
+
+Sugestao:
+- Implementar close de `@client`, close de UDP socket e `@thread.join` com timeout curto.
+- Adicionar spec com fake socket/client garantindo cleanup.
+
+### 9. Busy wait com `sleep` em pontos sensiveis
+
+Arquivos:
+- `lib/onyxcord/voice/network.rb:338`
+- `lib/onyxcord/voice/voice_bot.rb:315`
+- `lib/onyxcord/bot.rb:413`
+
+Problema:
+- Loops `sleep until` e `sleep while` sao simples, mas acordam periodicamente sem evento real.
+
+Impacto:
+- Baixo em poucos bots, mas piora com muitas conexoes/threads.
+
+Sugestao:
+- Usar `ConditionVariable` para readiness/pausa.
+- Para voice playback, manter cuidado para nao prejudicar o timing de audio.
+
+## Prioridade baixa / limpeza
+
+### 10. Webhooks nao usam o rate limiter central
+
+Arquivo: `lib/onyxcord/webhooks/client.rb`
+
+Problema:
+- Chamadas usam `RestClient.post/patch/delete` direto.
+- Isso e simples, mas nao aproveita `OnyxCord::RateLimiter::Rest`.
+
+Impacto:
+- Clientes de webhook intensivos podem bater 429 com menos controle.
+
+Sugestao:
+- Criar transport compartilhado leve para webhooks.
+- Ou criar um rate limiter dedicado por webhook URL.
+
+### 11. Dependencias abertas demais
+
+Arquivos:
+- `onyxcord.gemspec`
+- `onyxcord-webhooks.gemspec`
+
+Problema:
+- Algumas dependencias permitem qualquer versao acima do minimo, como `rest-client >= 2.0.0`, `websocket-client-simple >= 0.9.0`, `ffi >= 1.9.24` e `opus-ruby` sem limite.
+
+Impacto:
+- Atualizacao futura pode quebrar performance ou compatibilidade.
+
+Sugestao:
+- Definir upper bounds conservadores, por exemplo `< 3` quando fizer sentido.
+- Rodar CI com Ruby 3.3 e 3.4 se a gem prometer suporte moderno.
+
+### 12. Arquivo `bot.rb` esta grande demais
+
+Arquivo: `lib/onyxcord/bot.rb` tem cerca de 1971 linhas.
+
+Problema:
+- O arquivo mistura boot, REST helpers, dispatch, cache orchestration, interactions, voice e commands.
+
+Impacto:
+- Dificulta otimizar sem regressao.
+
+Sugestao:
+- Extrair aos poucos:
+  - `Bot::Interactions`
+  - `Bot::Dispatch`
+  - `Bot::Voice`
+  - `Bot::ApplicationCommands`
+- Fazer isso depois das correcoes de runtime, para nao misturar refactor com bugfix.
+
+## Otimizacoes praticas sugeridas
+
+### Perfil leve recomendado para usuarios
+
+Documentar no README um preset para bots pequenos:
+
+```ruby
+OnyxCord.configure do |config|
+  config.mode = :raw
+  config.cache = :none
+  config.event_executor = :pool
+  config.event_workers = 2
+end
+```
+
+Para bots medios:
+
+```ruby
+OnyxCord.configure do |config|
+  config.mode = :hybrid
+  config.cache = :minimal
+  config.event_workers = 4
+end
+```
+
+### Medir antes/depois
+
+Criar specs/benchmarks simples para:
+- `INTERACTION_CREATE` com 1000 commands simulados.
+- `MESSAGE_CREATE` em modo `raw`, `hybrid` e `object`.
+- crescimento de `@users`, `@channels`, `@thread_members`.
+- fila do executor quando handler dorme 50ms.
+
+### Instrumentacao leve
+
+Adicionar metodos opcionais:
+- `bot.runtime_stats`
+- `bot.cache_stats`
+- `bot.event_queue_size`
+- `OnyxCord::API.rate_limiter_stats`
+
+Isso ajuda a diagnosticar RAM e lentidao sem profiler externo.
+
+## Plano de acao recomendado
+
+1. Corrigir `API.request` no retry `202` e adicionar spec.
+2. Remover threads soltas dos application commands e usar `@event_executor`.
+3. Remover logs `>>>` ou rebaixar para `debug`.
+4. Trocar `Queue` por `SizedQueue` configuravel.
+5. Adicionar `cache_stats` e `prune_cache!`.
+6. Fechar corretamente recursos de voice (`File.open`, UDP, WS, thread).
+7. Adicionar limpeza/LRU no rate limiter REST.
+8. Depois disso, refatorar `bot.rb` em modulos menores.
+
+## Conclusao
+
+A OnyxCord ja esta no caminho certo para ser pratica no modo padrao `hybrid` e ainda leve quando o usuario escolher `raw` com cache `:none`. O maior risco atual nao e um unico algoritmo pesado, e sim crescimento sem limite: threads por interaction, fila ilimitada, caches sem TTL e mapas internos que nao expiram. Corrigir esses pontos deve reduzir RAM em carga real, deixar o bot mais previsivel em pico e facilitar otimizar depois sem mexer na API publica.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: onyxcord
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.4
 platform: ruby
 authors:
 - Gustavo Silva
@@ -30,6 +30,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.9.24
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -37,6 +40,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.9.24
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: opus-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -44,6 +50,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -51,6 +60,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: rest-client
   requirement: !ruby/object:Gem::Requirement
@@ -58,6 +70,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -65,6 +80,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: websocket-client-simple
   requirement: !ruby/object:Gem::Requirement
@@ -72,6 +90,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.9.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -79,20 +100,23 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.9.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: onyxcord-webhooks
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.2
+        version: 1.1.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.2
+        version: 1.1.4
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -392,6 +416,8 @@ files:
 - lib/onyxcord/websocket.rb
 - onyxcord-webhooks.gemspec
 - onyxcord.gemspec
+- relator.md
+- relatorio2.md
 homepage: https://github.com/kruldevb/OnyxCord
 licenses:
 - MIT