rito 0.1.0

data/lib/rito/middleware/riot_errors.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Rito
+  module Middleware
+    # Raises the mapped Rito::Error for 4xx/5xx responses.
+    # Registered below RateLimitObserve so observation happens first.
+    class RiotErrors < Faraday::Middleware
+      ERROR_CLASSES = {
+        400 => Rito::BadRequest,
+        401 => Rito::Unauthorized,
+        403 => Rito::Forbidden,
+        404 => Rito::NotFound,
+        405 => Rito::MethodNotAllowed,
+        415 => Rito::UnsupportedMediaType
+      }.freeze
+
+      def initialize(app, client:)
+        super(app)
+        @client = client
+      end
+
+      def call(env)
+        @app.call(env).on_complete { |completed| on_complete(completed) }
+      rescue Faraday::RetriableResponse => e
+        response = e.response
+        raise error_class_for(response.status).new(
+          "#{response.status} (after transport retries)",
+          response: response
+        )
+      rescue Faraday::ConnectionFailed => e
+        raise Rito::ConnectionError.new("#{e.class}: #{e.message}", wrapped: e)
+      rescue Faraday::TimeoutError, Timeout::Error => e
+        raise Rito::TimeoutError.new("#{e.class}: #{e.message}", wrapped: e)
+      rescue Faraday::SSLError => e
+        raise Rito::SSLError.new("#{e.class}: #{e.message}", wrapped: e)
+      end
+
+      def on_complete(env)
+        return if env.status.between?(200, 299)
+        # 5xx are retried by faraday-retry (registered above this middleware);
+        # raising here would abort the retry loop on the first attempt.
+        return if env.status >= 500
+
+        error_class = error_class_for(env.status)
+        return unless error_class
+
+        response = Faraday::Response.new(env)
+        if error_class == Rito::RateLimited
+          headers = env.response_headers
+          raise error_class.new(message(env),
+                                retry_after: RateLimiting::HeaderParser.retry_after(headers),
+                                limit_type: RateLimiting::HeaderParser.limit_type(headers),
+                                response: response)
+        end
+
+        raise error_class.new(message(env), response: response)
+      end
+
+      private
+
+      def error_class_for(status)
+        if status == 429
+          Rito::RateLimited
+        elsif status.between?(500, 599)
+          status == 503 ? Rito::ServiceUnavailable : Rito::ServerError
+        else
+          ERROR_CLASSES[status]
+        end
+      end
+
+      def message(env)
+        parsed = env.response_body
+        parsed = JSON.parse(parsed) if parsed.is_a?(String) && !parsed.empty?
+        detail = parsed.is_a?(Hash) ? (parsed['message'] || parsed.dig('status', 'message')) : nil
+
+        base = "#{env.status} #{env.method.to_s.upcase} #{env.url}"
+        detail ? "#{base}: #{detail}" : base
+      end
+    end
+  end
+end

data/lib/rito/models/account.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Rito
+  module Models
+    Account = Data.define(:puuid, :game_name, :tag_line, :raw) do
+      def self.from_api(hash)
+        new(
+          puuid: hash['puuid'],
+          game_name: hash['gameName'],
+          tag_line: hash['tagLine'],
+          raw: hash.freeze
+        )
+      end
+    end
+
+    ActiveShard = Data.define(:puuid, :game, :active_shard, :raw) do
+      def self.from_api(hash)
+        new(
+          puuid: hash['puuid'],
+          game: hash['game'],
+          active_shard: hash['activeShard'],
+          raw: hash.freeze
+        )
+      end
+    end
+
+    AccountRegion = Data.define(:puuid, :game, :region, :raw) do
+      def self.from_api(hash)
+        new(
+          puuid: hash['puuid'],
+          game: hash['game'],
+          region: hash['region'],
+          raw: hash.freeze
+        )
+      end
+    end
+  end
+end

data/lib/rito/models/lol.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Rito
+  module Models
+    ChampionMastery = Data.define(
+      :puuid, :champion_id, :champion_level, :champion_points,
+      :champion_points_until_next_level, :champion_points_since_last_level,
+      :last_play_time, :tokens_earned, :raw
+    ) do
+      def self.from_api(hash)
+        new(
+          puuid: hash['puuid'],
+          champion_id: hash['championId'],
+          champion_level: hash['championLevel'],
+          champion_points: hash['championPoints'],
+          champion_points_until_next_level: hash['championPointsUntilNextLevel'],
+          champion_points_since_last_level: hash['championPointsSinceLastLevel'],
+          last_play_time: hash['lastPlayTime'],
+          tokens_earned: hash['tokensEarned'],
+          raw: hash.freeze
+        )
+      end
+    end
+
+    ChampionInfo = Data.define(:sr, :newplayer, :raw) do
+      def self.from_api(hash)
+        new(
+          sr: hash['sr'],
+          newplayer: hash['newplayer'],
+          raw: hash.freeze
+        )
+      end
+    end
+
+    LeagueEntry = Data.define(
+      :puuid, :summoner_id, :queue_type, :tier, :rank, :league_id,
+      :league_points, :wins, :losses, :veteran, :fresh_blood, :hot_streak,
+      :inactive, :raw
+    ) do
+      def self.from_api(hash)
+        new(
+          puuid: hash['puuid'],
+          summoner_id: hash['summonerId'],
+          queue_type: hash['queueType'],
+          tier: hash['tier'],
+          rank: hash['rank'],
+          league_id: hash['leagueId'],
+          league_points: hash['leaguePoints'],
+          wins: hash['wins'],
+          losses: hash['losses'],
+          veteran: hash['veteran'],
+          fresh_blood: hash['freshBlood'],
+          hot_streak: hash['hotStreak'],
+          inactive: hash['inactive'],
+          raw: hash.freeze
+        )
+      end
+
+      def winrate
+        total = wins.to_i + losses.to_i
+        return nil if total.zero?
+
+        (wins.to_f / total * 100).round(2)
+      end
+    end
+
+    LeagueList = Data.define(:league_id, :tier, :name, :queue, :entries, :raw) do
+      def self.from_api(hash)
+        new(
+          league_id: hash['leagueId'],
+          tier: hash['tier'],
+          name: hash['name'],
+          queue: hash['queue'],
+          entries: hash['entries'].to_a.freeze,
+          raw: hash.freeze
+        )
+      end
+    end
+  end
+end

data/lib/rito/models/match.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Rito
+  module Models
+    Match = Data.define(:metadata, :info, :raw) do
+      def match_id
+        metadata&.match_id
+      end
+
+      def self.from_api(hash)
+        new(
+          metadata: MatchMetadata.from_api(hash['metadata']),
+          info: MatchInfo.from_api(hash['info']),
+          raw: hash.freeze
+        )
+      end
+    end
+
+    MatchMetadata = Data.define(:match_id, :participants, :raw) do
+      def self.from_api(hash)
+        return nil if hash.nil?
+
+        new(
+          match_id: hash['matchId'],
+          participants: hash['participants'],
+          raw: hash.freeze
+        )
+      end
+    end
+
+    MatchInfo = Data.define(:game_creation, :game_duration, :game_end_timestamp,
+                            :game_id, :game_mode, :game_start_timestamp, :game_type,
+                            :game_version, :map_id, :participants, :queue_id, :raw) do
+      def self.from_api(hash)
+        return nil if hash.nil?
+
+        new(
+          game_creation: hash['gameCreation'],
+          game_duration: hash['gameDuration'],
+          game_end_timestamp: hash['gameEndTimestamp'],
+          game_id: hash['gameId'],
+          game_mode: hash['gameMode'],
+          game_start_timestamp: hash['gameStartTimestamp'],
+          game_type: hash['gameType'],
+          game_version: hash['gameVersion'],
+          map_id: hash['mapId'],
+          participants: hash['participants']&.map { |p| MatchParticipant.from_api(p) },
+          queue_id: hash['queueId'],
+          raw: hash.freeze
+        )
+      end
+    end
+
+    MatchParticipant = Data.define(:champion_name, :kills, :deaths, :assists,
+                                   :puuid, :summoner_name, :team_id, :win, :raw) do
+      def self.from_api(hash)
+        new(
+          champion_name: hash['championName'],
+          kills: hash['kills'],
+          deaths: hash['deaths'],
+          assists: hash['assists'],
+          puuid: hash['puuid'],
+          summoner_name: hash['summonerName'],
+          team_id: hash['teamId'],
+          win: hash['win'],
+          raw: hash.freeze
+        )
+      end
+    end
+  end
+end

data/lib/rito/models/summoner.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rito
+  module Models
+    Summoner = Data.define(
+      :id, :account_id, :puuid, :name, :profile_icon_id,
+      :revision_date, :summoner_level, :raw
+    ) do
+      def self.from_api(hash)
+        new(
+          id: hash['id'],
+          account_id: hash['accountId'],
+          puuid: hash['puuid'],
+          name: hash['name'],
+          profile_icon_id: hash['profileIconId'],
+          revision_date: hash['revisionDate'],
+          summoner_level: hash['summonerLevel'],
+          raw: hash.freeze
+        )
+      end
+    end
+  end
+end

data/lib/rito/rate_limiting/adaptive_limiter.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Rito
+  module RateLimiting
+    # Pre-emptive limiter driven entirely by rate limit headers.
+    # Buckets are keyed per (api key, region, endpoint) so multiple keys
+    # and regions never share state.
+    class AdaptiveLimiter
+      def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
+                     sleeper: Kernel.method(:sleep))
+        @buckets = {}
+        @mutex = Mutex.new
+        @clock = clock
+        @sleeper = sleeper
+      end
+
+      def acquire!(key:, region:, bucket:)
+        app_bucket(key, region).wait_until_allowed!
+        method_bucket(key, region, bucket).wait_until_allowed!
+      end
+
+      def observe!(response, key:, region:, bucket:)
+        headers = response.headers
+        status = response.status
+
+        app = app_bucket(key, region)
+        method = method_bucket(key, region, bucket)
+
+        app.apply!(limits: HeaderParser.app_limits(headers), counts: HeaderParser.app_counts(headers))
+        method.apply!(limits: HeaderParser.method_limits(headers), counts: HeaderParser.method_counts(headers))
+
+        return unless status == 429
+
+        retry_after = HeaderParser.retry_after(headers)
+        case HeaderParser.limit_type(headers)
+        when :application
+          app.limit_block!(retry_after)
+        when :method, :service
+          method.limit_block!(retry_after)
+        else
+          method.limit_block!(retry_after)
+        end
+      end
+
+      def bucket_blocked?(key:, region:, bucket: nil, scope: :app)
+        bucket_for_scope(key, region, bucket, scope).blocked?
+      end
+
+      private
+
+      def app_bucket(key, region)
+        bucket_for('app', key, region, nil)
+      end
+
+      def method_bucket(key, region, bucket)
+        bucket_for('method', key, region, bucket)
+      end
+
+      def bucket_for_scope(key, region, bucket, scope)
+        scope == :app ? app_bucket(key, region) : method_bucket(key, region, bucket)
+      end
+
+      def bucket_for(scope, key, region, endpoint)
+        @mutex.synchronize do
+          @buckets[[scope, key, Routing.normalize(region), endpoint]] ||=
+            Bucket.new(clock: @clock, sleeper: @sleeper)
+        end
+      end
+    end
+  end
+end

data/lib/rito/rate_limiting/bucket.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Rito
+  module RateLimiting
+    # Tracks windows learned from X-App-Rate-Limit / X-Method-Rate-Limit headers
+    # and blocks callers before limits are hit.
+    class Bucket
+      DEFAULT_BACKOFF = 1
+      MAX_BACKOFF = 32
+      JITTER = 0.5
+
+      def initialize(clock:, sleeper: Kernel.method(:sleep))
+        @clock = clock
+        @sleeper = sleeper
+        @mutex = Mutex.new
+        @windows = []
+        @blocked_until = nil
+        @limited_streak = 0
+      end
+
+      def apply!(limits:, counts:)
+        @mutex.synchronize do
+          now = @clock.call
+          if limits.any?
+            counts_by_window = counts.to_h { |count, window| [window, count] }
+            @windows = limits.map do |limit, window|
+              previous = @windows.find { |w| w[:window] == window && w[:reset_at] > now }
+              {
+                limit: limit,
+                window: window,
+                reset_at: now + window,
+                count: counts_by_window.fetch(window) { previous&.fetch(:count) || 0 }
+              }
+            end
+          end
+          @limited_streak = 0
+        end
+      end
+
+      # Blocks the bucket. When retry_after is nil (missing Retry-After header),
+      # falls back to exponential backoff with jitter based on the streak of
+      # consecutive 429s.
+      def limit_block!(retry_after)
+        @mutex.synchronize do
+          now = @clock.call
+          @limited_streak += 1
+          delay = retry_after || [@limited_streak * DEFAULT_BACKOFF, MAX_BACKOFF].min
+          delay += rand * JITTER
+          until_time = now + delay
+          @blocked_until = until_time if @blocked_until.nil? || @blocked_until < until_time
+        end
+      end
+
+      def wait_until_allowed!
+        loop do
+          delay = nil
+          @mutex.synchronize do
+            now = @clock.call
+            if @blocked_until && @blocked_until > now
+              delay = @blocked_until - now
+            else
+              @windows.reject! { |w| w[:reset_at] <= now }
+              violating = @windows.find { |w| w[:count] >= w[:limit] }
+              if violating
+                delay = violating[:reset_at] - now
+              else
+                @windows.each { |w| w[:count] += 1 }
+                return
+              end
+            end
+          end
+          @sleeper.call(delay + 0.001)
+        end
+      end
+
+      def blocked?
+        @mutex.synchronize do
+          @blocked_until && @blocked_until > @clock.call
+        end
+      end
+    end
+  end
+end

data/lib/rito/rate_limiting/header_parser.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Rito
+  module RateLimiting
+    module HeaderParser
+      module_function
+
+      def parse_pairs(value)
+        return [] if value.nil?
+
+        value.split(',').filter_map do |part|
+          limit, window = part.strip.split(':', 2)
+          next if limit.nil? || window.nil?
+
+          [Integer(limit), Integer(window)]
+        rescue ArgumentError
+          next
+        end
+      end
+
+      def app_limits(headers)
+        parse_pairs(headers['X-App-Rate-Limit'])
+      end
+
+      def app_counts(headers)
+        parse_pairs(headers['X-App-Rate-Limit-Count'])
+      end
+
+      def method_limits(headers)
+        parse_pairs(headers['X-Method-Rate-Limit'])
+      end
+
+      def method_counts(headers)
+        parse_pairs(headers['X-Method-Rate-Limit-Count'])
+      end
+
+      def retry_after(headers)
+        value = headers['Retry-After']
+        Integer(value) if value&.match?(/\A\d+\z/)
+      end
+
+      LIMIT_TYPES = {
+        'application' => :application,
+        'method' => :method,
+        'service' => :service
+      }.freeze
+
+      def limit_type(headers)
+        LIMIT_TYPES[headers['X-Rate-Limit-Type']]
+      end
+    end
+  end
+end

data/lib/rito/rate_limiting/null_limiter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Rito
+  module RateLimiting
+    class NullLimiter
+      def acquire!(key:, region:, bucket:); end
+
+      def observe!(response, key:, region:, bucket:); end
+    end
+  end
+end

data/lib/rito/rate_limiting/redis_limiter.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Rito
+  module RateLimiting
+    # Distributed rate limiter backed by Redis for multi-process / multi-host
+    # applications. Soft dependency: requires the `redis` gem at instantiation,
+    # not at load time.
+    #
+    # Fixed windows with atomic check-and-increment (Lua), counters synced from
+    # authoritative X-*-Count headers, and per-scope block keys for Retry-After.
+    class RedisLimiter
+      class DependencyMissing < Error; end
+
+      LIMITS_TTL = 600
+
+      # KEYS[1] = app block key, KEYS[2] = method block key, KEYS[3..] = counters
+      # ARGV = limit, window pairs matching KEYS[3..]
+      ALLOW_SCRIPT = <<~LUA
+        for i = 1, 2 do
+          if redis.call('EXISTS', KEYS[i]) == 1 then
+            return 0
+          end
+        end
+        for i = 3, #KEYS do
+          local idx = i - 3
+          local limit = tonumber(ARGV[idx * 2 + 1])
+          local window = tonumber(ARGV[idx * 2 + 2])
+          if limit then
+            local count = redis.call('INCR', KEYS[i])
+            if count == 1 then
+              redis.call('EXPIRE', KEYS[i], window)
+            end
+            if count > limit then
+              redis.call('DECR', KEYS[i])
+              return 0
+            end
+          end
+        end
+        return 1
+      LUA
+
+      def initialize(redis:, sleeper: Kernel.method(:sleep))
+        raise DependencyMissing, 'Add the `redis` gem to your Gemfile to use RedisLimiter' unless defined?(::Redis)
+
+        @redis = redis
+        @sleeper = sleeper
+      end
+
+      def acquire!(key:, region:, bucket:)
+        loop do
+          return if allowed?(key, region, bucket)
+
+          @sleeper.call(1)
+        end
+      end
+
+      def observe!(response, key:, region:, bucket:)
+        headers = response.headers
+        status = response.status
+        prefix = prefix_for(key, region)
+
+        if status == 429
+          block!(prefix, bucket, headers)
+        else
+          sync_limits!(prefix, bucket, headers)
+          sync_counts!(prefix, bucket, headers)
+        end
+      end
+
+      def blocked?(key:, region:, bucket: nil, scope: :app)
+        prefix = prefix_for(key, region)
+        block_key = scope == :app ? "#{prefix}:block" : "#{prefix}:m:#{bucket}:block"
+        @redis.exists?(block_key)
+      end
+
+      private
+
+      def allowed?(key, region, bucket)
+        prefix = prefix_for(key, region)
+        method_prefix = "#{prefix}:m:#{bucket}"
+
+        app_limits = parse_limits(@redis.hget("#{prefix}:limits", 'app'))
+        method_limits = parse_limits(@redis.hget("#{prefix}:limits", bucket))
+
+        keys = ["#{prefix}:block", "#{method_prefix}:block"]
+        argv = []
+        app_limits.each do |limit, window|
+          keys << "#{prefix}:app:#{window}"
+          argv << limit.to_s << window.to_s
+        end
+        method_limits.each do |limit, window|
+          keys << "#{method_prefix}:#{window}"
+          argv << limit.to_s << window.to_s
+        end
+
+        @redis.eval(ALLOW_SCRIPT, keys: keys, argv: argv) == 1
+      end
+
+      def block!(prefix, bucket, headers)
+        retry_after = HeaderParser.retry_after(headers) || 2
+        case HeaderParser.limit_type(headers)
+        when :application
+          @redis.set("#{prefix}:block", '1', ex: retry_after)
+        when :method, :service
+          @redis.set("#{prefix}:m:#{bucket}:block", '1', ex: retry_after)
+        else
+          @redis.set("#{prefix}:m:#{bucket}:block", '1', ex: retry_after)
+        end
+      end
+
+      def sync_limits!(prefix, bucket, headers)
+        app_limits = HeaderParser.app_limits(headers)
+        method_limits = HeaderParser.method_limits(headers)
+        return if app_limits.empty? && method_limits.empty?
+
+        mapping = {}
+        mapping['app'] = serialize(app_limits) unless app_limits.empty?
+        mapping[bucket] = serialize(method_limits) unless method_limits.empty?
+        @redis.hset("#{prefix}:limits", mapping)
+        @redis.expire("#{prefix}:limits", LIMITS_TTL)
+      end
+
+      def sync_counts!(prefix, bucket, headers)
+        sync_scope_counts!(prefix, HeaderParser.app_counts(headers), "#{prefix}:app")
+        sync_scope_counts!(prefix, HeaderParser.method_counts(headers), "#{prefix}:m:#{bucket}")
+      end
+
+      def sync_scope_counts!(_prefix, counts, counter_prefix)
+        counts.each do |count, window|
+          @redis.set("#{counter_prefix}:#{window}", count.to_s, ex: window)
+        end
+      end
+
+      def serialize(pairs)
+        pairs.map { |limit, window| "#{limit}:#{window}" }.join(',')
+      end
+
+      def parse_limits(value)
+        HeaderParser.parse_pairs(value)
+      end
+
+      def prefix_for(key, region)
+        "rito:#{digest(key)}:#{Routing.normalize(region)}"
+      end
+
+      def digest(key)
+        Digest::SHA256.hexdigest(key.to_s)[0, 16]
+      end
+    end
+  end
+end