vox 0.2.0

data/lib/vox/http/error.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Vox
+  module HTTP
+    # Standard API errors for bad requests
+    class Error < Vox::Error
+      # @return [Hash<Symbol, Object>] The response object
+      attr_reader :data
+
+      # @return [String, nil] The trace identifier this error originated from.
+      attr_reader :trace
+
+      def initialize(data, req_id = nil)
+        @data = data
+        @trace = req_id
+        super(data[:message])
+      end
+
+      # Status Code 400
+      class BadRequest < self
+      end
+
+      # Status Code 401
+      class Unauthorized < self
+      end
+
+      # Status Code 403
+      class Forbidden < self
+      end
+
+      # Status Code 404
+      class NotFound < self
+      end
+
+      # Status Code 405
+      class MethodNotAllowed < self
+      end
+
+      # Status Code 429
+      class TooManyRequests < self
+      end
+
+      # Status Code 502
+      class GatewayUnavailable < self
+      end
+
+      # Status Code 5XX
+      class ServerError < StandardError
+        def initialize(req_id)
+          @trace = req_id
+          super('Internal Server Error')
+        end
+      end
+    end
+  end
+end

data/lib/vox/http/middleware.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'logging'
+
+require 'vox/http/middleware/rate_limiter'
+require 'vox/http/middleware/log_formatter'
+
+log = Logging.logger['Vox::HTTP']
+
+log.debug { 'Registering rate_limiter middleware' }
+Faraday::Middleware.register_middleware(
+  vox_ratelimiter: Vox::HTTP::Middleware::RateLimiter
+)

data/lib/vox/http/middleware/log_formatter.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/logging/formatter'
+
+module Vox
+  module HTTP
+    # Collection of middleware used to process requests internally.
+    module Middleware
+      # @!visibility private
+      class LogFormatter < Faraday::Logging::Formatter
+        # Request processing
+        def request(env)
+          req_id = env.request.context[:trace]
+
+          log_request_info(env, req_id)
+          # Debug just logs the response with the response body
+          log_request_debug(env, req_id) if env.request_headers['Content-Type'] == 'application/json'
+          debug { "{#{req_id}} [OUT] #{env.request_headers}" }
+        end
+
+        # Info level logging for requests. Logs the HTTP verb, the url path, query string arguments, and
+        # request body size.
+        def log_request_info(env, req_id)
+          query_string = "?#{env.url.query}" if env.url.query
+          size = env.body.respond_to?(:size) ? env.body.size : env.request_headers['Content-Length']
+          info { "{#{req_id}} [OUT] #{env.method} #{env.url.path}#{query_string} (#{size || 0})" }
+        end
+
+        # Debug level logging for requests. Displays the request body.
+        def log_request_debug(env, req_id)
+          debug { "{#{req_id}} [OUT] #{env.body}" }
+        end
+
+        # Response processing
+        def response(env)
+          resp = env.response
+          req_id = env.request.context[:trace]
+
+          log_response_error(env, resp, req_id) unless resp.success?
+          log_response_info(env, resp, req_id)
+          log_response_debug(env, resp, req_id) unless resp.body.empty?
+        end
+
+        # Error level logging for responses. Logs status code, url path, and response body.
+        def log_response_error(env, resp, req_id)
+          error { "{#{req_id}} [IN] #{resp.status} #{env.url.path} #{resp.body}" }
+        end
+
+        # Info level logging for responses. Logs status code, url path, and body size.
+        def log_response_info(env, resp, req_id)
+          info { "{#{req_id}} [IN] #{resp.status} #{env.url.path} (#{resp.body&.size || 0})" }
+        end
+
+        # Debug level logging for responses. Logs the response body.
+        def log_response_debug(_env, resp, req_id)
+          debug { "{#{req_id}} [IN] #{resp.body}" }
+        end
+      end
+    end
+  end
+end

data/lib/vox/http/middleware/rate_limiter.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Vox
+  module HTTP
+    # @!visibility private
+    # A bucket used for HTTP rate limiting
+    class Bucket
+      # @!attribute [r] limit
+      # @return [Integer]
+      attr_reader :limit
+
+      # @!attribute [r] remaining
+      # @return [Integer]
+      attr_reader :remaining
+
+      # @!attribute [r] reset_time
+      # @return [Time]
+      attr_reader :reset_time
+
+      def initialize(limit, remaining, reset_time)
+        update(limit, remaining, reset_time)
+
+        @mutex = Mutex.new
+      end
+
+      # @param limit [Integer]
+      # @param remaining [Integer]
+      # @param reset_time [Time]
+      def update(limit, remaining, reset_time)
+        @limit = limit
+        @remaining = remaining
+        @reset_time = reset_time
+      end
+
+      # @return [true, false]
+      def will_limit?
+        (@remaining - 1).negative? && Time.now <= @reset_time
+      end
+
+      # Lock and unlock this mutex (prevents access during reset)
+      def wait_until_available
+        return unless locked?
+
+        @mutex.synchronize {}
+      end
+
+      # Lock the mutex for a given duration. Used for cooldown periods
+      def lock_for(duration)
+        @mutex.synchronize { sleep duration }
+      end
+
+      # Lock the mutex until the bucket resets
+      def lock_until_reset
+        time_remaining = @reset_time - Time.now
+
+        raise 'Cannot sleep for negative duration.' if time_remaining.negative?
+
+        lock_for(time_remaining) unless locked?
+      end
+
+      # @return [true, false]
+      def locked?
+        @mutex.locked?
+      end
+    end
+
+    # @!visibility private
+    # A rate limiting class used for our {Client}
+    class LimitTable
+      def initialize
+        @bucket_key_map = {}
+        @bucket_id_map = {}
+        @key_to_id = {}
+      end
+
+      # Index a bucket based on the route key
+      def get_from_key(key)
+        @bucket_key_map[key]
+      end
+
+      # Index a bucket based on server side bucket id
+      def get_from_id(id)
+        @bucket_id_map[id]
+      end
+
+      # Get a bucket from a rl_key if it exists
+      def id_from_key(key)
+        @key_to_id[key]
+      end
+
+      # Update a rate limit bucket from response headers
+      def update_from_headers(key, headers, req_id = nil)
+        limit = headers['x-ratelimit-limit']&.to_i
+        remaining = headers['x-ratelimit-remaining']&.to_i
+        bucket_id = headers['x-ratelimit-bucket']
+        reset_after = headers['x-ratelimit-reset-after']&.to_f
+        retry_after = headers['retry-after']&.to_f
+
+        if limit && remaining && reset_after && bucket_id
+          reset = if retry_after
+                    retry_after / 1000
+                  else
+                    reset_after
+                  end
+          update(key, bucket_id, limit, remaining, Time.now + reset)
+        elsif retry_after
+          update(key, bucket_id, 0, 0, Time.now + (retry_after / 1000))
+        else
+          LOGGER.debug { "{#{req_id}} Unable to set RL for #{key}" }
+        end
+      end
+
+      # Update a rate limit bucket
+      def update(key, bucket_id, limit, remaining, reset_time)
+        bucket = @bucket_id_map[bucket_id]
+        if bucket
+          bucket.update(limit, remaining, reset_time)
+          @bucket_key_map[key] = bucket_id
+        else
+          bucket = Bucket.new(limit, remaining, reset_time)
+          @bucket_key_map[key] = bucket
+          if bucket_id
+            @bucket_id_map[bucket_id] = bucket
+            @key_to_id[key] = bucket_id
+          end
+        end
+      end
+
+      # @!visibility private
+      LOGGER = Logging.logger[self]
+    end
+
+    module Middleware
+      # Faraday middleware to handle ratelimiting based on
+      # bucket ids and the rate limit key provided by {Client#request}
+      # in the request context
+      class RateLimiter < Faraday::Middleware
+        def initialize(app, **_options)
+          super(app)
+          @limit_table = LimitTable.new
+          @mutex_table = Hash.new { |hash, key| hash[key] = Mutex.new }
+        end
+
+        # Request handler
+        def call(env)
+          rl_key = env.request.context[:rl_key]
+          req_id = env.request.context[:trace]
+          mutex = @mutex_table[rl_key]
+
+          mutex.synchronize do
+            rl_wait(rl_key, req_id)
+            rl_wait(:global, req_id)
+            @app.call(env).on_complete do |environ|
+              on_complete(environ, req_id)
+            end
+          end
+        end
+
+        # Handler for response data
+        def on_complete(env, req_id)
+          resp = env.response
+
+          if resp.status == 429 && resp.headers['x-ratelimit-global']
+            @limit_table.update_from_headers(:global, resp.headers, req_id)
+            Thread.new { @limit_table.get_from_key(:global).lock_until_reset }
+            LOGGER.error { "{#{req_id}}} Global ratelimit hit" }
+          end
+
+          update_from_headers(env)
+        end
+
+        private
+
+        # Lock a rate limit mutex preemptively if the next request would deplete the bucket.
+        def rl_wait(key, trace)
+          bucket_id = @limit_table.id_from_key(key)
+          bucket = if bucket_id
+                     @limit_table.get_from_id(bucket_id)
+                   else
+                     @limit_table.get_from_key(key)
+                   end
+          return if bucket.nil?
+
+          bucket.wait_until_available
+          return unless bucket.will_limit?
+
+          LOGGER.info do
+            duration = bucket.reset_time - Time.now
+            "{#{trace}} [RL] Locking #{key} for #{duration.truncate(3)} seconds"
+          end
+
+          bucket.lock_until_reset
+        end
+
+        def update_from_headers(env)
+          rl_key = env.request.context[:rl_key]
+          req_id = env.request.context[:trace]
+          @limit_table.update_from_headers(rl_key, env.response.headers, req_id)
+        end
+
+        # @!visibility private
+        LOGGER = Logging.logger[Vox::HTTP]
+      end
+    end
+  end
+end

data/lib/vox/http/route.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Vox
+  module HTTP
+    # Route that contains information about a request path, intended
+    # for use with {HTTP::Client#request}.
+    class Route
+      # Major parameters that are significant when forming a rate limit key.
+      MAJOR_PARAMS = %i[guild_id channel_id webhook_id].freeze
+
+      # @return [Symbol, String] HTTP verb to be used when accessing the API
+      #   path.
+      attr_reader :verb
+
+      # @return [String] Unformatted API path, using Kernel.format
+      #   syntax referencing keys in {params}.
+      attr_reader :key
+
+      # @return [String] String that defines an endpoint based on HTTP verb,
+      #   API path, and major parameter if any.
+      attr_reader :rl_key
+
+      # @return [Hash] Parameters that are passed to be used when formatting
+      #   the API path.
+      attr_reader :params
+
+      # @param verb [#to_sym] The HTTP verb to be used when accessing the API path.
+      # @param key [String] The unformatted route using Kernel.format syntax to
+      #   incorporate the data provided in `params`.
+      # @param params [Hash<String, #to_s>] Parameters passed when formatting `key`.
+      def initialize(verb, key, **params)
+        @verb = verb.downcase.to_sym
+        @key = key
+        @params = params
+        @rl_key = "#{@verb}:#{@key}:#{major_param}"
+      end
+
+      # Format the route with the given params
+      # @return [String] Formatted API path.
+      def format
+        return @key if @params.empty?
+
+        Kernel.format(@key, @params) if @params.any?
+      end
+
+      # @return [String, Integer, nil] The major param value of the route key if any
+      def major_param
+        params.slice(*MAJOR_PARAMS).values.first
+      end
+
+      # Compare a {Route} or {Route} like object (responds to `#verb`, `#key`, and `#params`).
+      # @param other [Route]
+      # @return [true, false]
+      def ==(other)
+        @verb == other.verb && @key == other.key && @params == other.params
+      end
+    end
+  end
+end

data/lib/vox/http/routes.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'vox/http/routes/audit_log'
+require 'vox/http/routes/channel'
+require 'vox/http/routes/emoji'
+require 'vox/http/routes/guild'
+require 'vox/http/routes/invite'
+require 'vox/http/routes/user'
+require 'vox/http/routes/voice'
+require 'vox/http/routes/webhook'
+
+module Vox
+  module HTTP
+    # Module that contains all route containers.
+    module Routes
+      # Include all route containers if this module is included
+      def self.included(klass)
+        [AuditLog, Channel, Emoji, Guild, Invite, User, Voice, Webhook].each { |m| klass.include m }
+      end
+    end
+  end
+end

data/lib/vox/http/routes/audit_log.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'vox/http/route'
+require 'vox/http/util'
+
+module Vox
+  module HTTP
+    module Routes
+      # HTTP methods for accessing information about a {Guild}'s {AuditLog}
+      module AuditLog
+        include Util
+
+        # TODO: Is this the best place for these?
+        EVENTS = {
+          GUILD_UPDATE: 1,
+          CHANNEL_CREATE: 10,
+          CHANNEL_UPDATE: 11,
+          CHANNEL_DELETE: 12,
+          CHANNEL_OVERWRITE_CREATE: 13,
+          CHANNEL_OVERWRITE_UPDATE: 14,
+          CHANNEL_OVERWRITE_DELETE: 15,
+          MEMBER_KICK: 20,
+          MEMBER_PRUNE: 21,
+          MEMBER_BAN_ADD: 22,
+          MEMBER_BAN_REMOVE: 23,
+          MEMBER_UPDATE: 24,
+          MEMBER_ROLE_UPDATE: 25,
+          MEMBER_MOVE: 26,
+          MEMBER_DISCONNECT: 27,
+          BOT_ADD: 28,
+          ROLE_CREATE: 30,
+          ROLE_UPDATE: 31,
+          ROLE_DELETE: 32,
+          INVITE_CREATE: 40,
+          INVITE_UPDATE: 41,
+          INVITE_DELETE: 42,
+          WEBHOOK_CREATE: 50,
+          WEBHOOK_UPDATE: 51,
+          WEBHOOK_DELETE: 52,
+          EMOJI_CREATE: 60,
+          EMOJI_UPDATE: 61,
+          EMOJI_DELETE: 62,
+          MESSAGE_DELETE: 72,
+          MESSAGE_BULK_DELETE: 73,
+          MESSAGE_PIN: 74,
+          MESSAGE_UNPIN: 75,
+          INTEGRATION_CREATE: 80,
+          INTEGRATION_UPDATE: 81,
+          INTEGRATION_DELETE: 82
+        }.freeze
+
+        # Fetch a guild's audit log. [View on Discord's docs](https://discord.com/developers/docs/resources/audit-log#get-guild-audit-log)
+        # @param guild_id [String, Integer] The ID of the guild to fetch audit log entries from.
+        # @param user_id [String, Integer] The ID of the user to filter events for.
+        # @param action_type [Symbol, Integer] The name of the audit log event to filter for. Either a key from {EVENTS}
+        #   or the corresponding integer value.
+        # @param before [String, Integer] The ID of the audit log entry to fetch before chronologically.
+        # @param limit [Integer] The maximum amount of entries to return. Defaults to 50 if no value is supplied.
+        #   Maximum of 100, minimum of 1.
+        # @return [Hash<:audit_log_entries, Array<Object>>]
+        # @vox.permissions VIEW_AUDIT_LOG
+        # @vox.api_docs https://discord.com/developers/docs/resources/audit-log#get-guild-audit-log
+        def get_guild_audit_log(guild_id, user_id: :undef, action_type: :undef, before: :undef, limit: :undef)
+          route = HTTP::Route.new(:GET, '/guilds/%{guild_id}/audit-logs', guild_id: guild_id)
+          query_params = filter_undef({ user_id: user_id, action_type: action_type, before: before, limit: limit })
+          request(route, query: query_params)
+        end
+      end
+    end
+  end
+end