jumbotron 0.1.1

data/app/models/jumbotron/public/translate_outcome.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Public
+    module TranslateOutcome
+      NOT_FOUND_CODES = %w[
+        not_found
+        game_not_found
+        league_not_found
+        season_not_found
+        season_phase_not_found
+        schedule_group_not_found
+      ].freeze
+
+      module_function
+
+      def call(result, payload_key:)
+        unless result.is_a?(CommandTower::Workflows::WorkflowResult)
+          raise Jumbotron::Error, "unexpected internal result"
+        end
+
+        return result.payload.fetch(payload_key) if result.success?
+
+        raise public_error_for(result)
+      end
+
+      def public_error_for(result)
+        code, message = error_code_and_message(result)
+        klass = exception_class_for(code)
+        klass.new(message)
+      end
+      module_function :public_error_for
+
+      def error_code_and_message(result)
+        error = Array(result.errors).first
+        case error
+        when CommandTower::Errors::ApplicationError
+          [error.code.to_s, error.message]
+        when Hash
+          [(error[:code] || error["code"]).to_s, (error[:message] || error["message"]).to_s]
+        else
+          ["internal_error", error.to_s]
+        end
+      end
+      module_function :error_code_and_message
+
+      def exception_class_for(code)
+        return Jumbotron::NotFoundError if NOT_FOUND_CODES.include?(code)
+        return Jumbotron::InvalidRequestError if code == "invalid_request"
+        return Jumbotron::UnsupportedCapabilityError if code == "unsupported"
+
+        Jumbotron::Error
+      end
+      module_function :exception_class_for
+    end
+  end
+end

data/app/models/jumbotron/public.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Public
+    ALLOWED_INCLUDES = %i[consensus current_lines consensus_constituents].freeze
+
+    Sport = Data.define(:id, :name)
+    League = Data.define(:id, :name, :sport)
+    Season = Data.define(:id, :name, :starts_on, :ends_on)
+    SeasonPhase = Data.define(:id, :name)
+    ScheduleGroup = Data.define(:id, :kind, :number, :name)
+    ScheduleGroupEnumeration = Data.define(:groups, :completeness)
+    ScheduleGroupsRequest = Data.define(
+      :league_id,
+      :sport,
+      :league,
+      :season_id,
+      :season,
+      :season_phase,
+      :kind
+    )
+    Team = Data.define(:id, :name)
+    Venue = Data.define(:id, :name)
+    Participant = Data.define(:role, :score, :result, :team)
+    GameSegment = Data.define(:kind, :number)
+    # Clock label text. Name is canonical/public contract, not Kernel#display.
+    GameClock = Data.define(:mode, :seconds, :display) # rubocop:disable Lint/DataDefineOverride
+    GameProgress = Data.define(:state, :segment, :clock)
+    ConsensusConstituent = Data.define(:bookmaker_id)
+    CurrentLine = Data.define(
+      :game_id,
+      :bookmaker_id,
+      :bookmaker_name,
+      :market,
+      :outcome,
+      :line_value,
+      :price_american,
+      :observed_at,
+      :changed_at
+    )
+    ConsensusLine = Data.define(
+      :game_id,
+      :market,
+      :outcome,
+      :line_value,
+      :constituent_count,
+      :observed_at,
+      :constituents
+    )
+    Game = Data.define(
+      :id,
+      :scheduled_at,
+      :lifecycle,
+      :progress,
+      :neutral_site,
+      :observed_at,
+      :changed_at,
+      :venue,
+      :participants,
+      :consensus_lines,
+      :current_lines
+    )
+    Schedule = Data.define(
+      :league,
+      :season,
+      :season_phase,
+      :group,
+      :starts_at,
+      :ends_at,
+      :games
+    )
+    GameRequest = Data.define(:id, :includes)
+    GameIdsRequest = Data.define(:game_ids)
+    ScheduleRequest = Data.define(
+      :league_id,
+      :sport,
+      :league,
+      :season_id,
+      :season,
+      :season_phase,
+      :schedule_group_id,
+      :group,
+      :starts_at,
+      :ends_at,
+      :includes
+    )
+  end
+end

data/app/models/jumbotron/schedule_group.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  class ScheduleGroup < ApplicationRecord
+    belongs_to :season, inverse_of: :schedule_groups
+    belongs_to :season_phase, optional: true, inverse_of: :schedule_groups
+    has_many :games, inverse_of: :schedule_group, dependent: :restrict_with_exception
+
+    validates :kind, presence: true
+    validates :name, presence: true
+    validate :season_phase_belongs_to_season
+
+    private
+
+    def season_phase_belongs_to_season
+      return if season_phase.blank? || season.blank?
+      return if season_phase.season_id == season_id
+
+      errors.add(:season_phase, "must belong to the same season")
+    end
+  end
+end

data/app/models/jumbotron/season.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  class Season < ApplicationRecord
+    belongs_to :league, inverse_of: :seasons
+    has_many :season_phases, inverse_of: :season, dependent: :restrict_with_exception
+    has_many :schedule_groups, inverse_of: :season, dependent: :restrict_with_exception
+    has_many :games, inverse_of: :season, dependent: :restrict_with_exception
+    has_many :provider_identities, as: :target, inverse_of: :target, dependent: :restrict_with_exception
+
+    validates :name, presence: true
+  end
+end

data/app/models/jumbotron/season_phase.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  class SeasonPhase < ApplicationRecord
+    belongs_to :season, inverse_of: :season_phases
+    has_many :schedule_groups, inverse_of: :season_phase, dependent: :restrict_with_exception
+    has_many :games, inverse_of: :season_phase, dependent: :restrict_with_exception
+    has_many :provider_identities, as: :target, inverse_of: :target, dependent: :restrict_with_exception
+
+    validates :name, presence: true
+  end
+end

data/app/models/jumbotron/sport.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  class Sport < ApplicationRecord
+    has_many :leagues, inverse_of: :sport, dependent: :restrict_with_exception
+    has_many :provider_identities, as: :target, inverse_of: :target, dependent: :restrict_with_exception
+
+    validates :name, presence: true
+  end
+end

data/app/models/jumbotron/team.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  class Team < ApplicationRecord
+    has_many :game_participants, inverse_of: :team, dependent: :restrict_with_exception
+    has_many :games, through: :game_participants
+    has_many :provider_identities, as: :target, inverse_of: :target, dependent: :restrict_with_exception
+
+    validates :name, presence: true
+  end
+end

data/app/models/jumbotron/venue.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  class Venue < ApplicationRecord
+    has_many :games, inverse_of: :venue, dependent: :restrict_with_exception
+    has_many :provider_identities, as: :target, inverse_of: :target, dependent: :restrict_with_exception
+
+    validates :name, presence: true
+  end
+end

data/app/providers/jumbotron/providers/espn/cooldown.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Providers
+    module Espn
+      # Provider-wide ESPN availability cooldown. Backed by Rails-configured cache/store.
+      class Cooldown
+        STATE_KEY = "jumbotron:providers:espn:cooldown"
+        BASE_DELAY_SECONDS = 5
+        MAX_DELAY_SECONDS = 180
+
+        def initialize(store: Rails.cache, clock: -> { Time.current })
+          @store = store
+          @clock = clock
+        end
+
+        # rubocop:disable Naming/PredicateMethod -- bang mutators report whether state changed
+        def record_failure!(error, now: clock.call)
+          return false unless ProviderFailure.availability_failure?(error)
+
+          state = read_state
+          count = state.fetch(:failure_count, 0) + 1
+          delay = delay_for(count)
+          write_state(failure_count: count, cooldown_until: now + delay)
+          true
+        end
+
+        def record_success!
+          store.delete(STATE_KEY)
+          true
+        end
+        # rubocop:enable Naming/PredicateMethod
+
+        def cooling_down?(now: clock.call)
+          retry_after(now: now).positive?
+        end
+
+        def retry_after(now: clock.call)
+          until_time = read_state[:cooldown_until]
+          return 0 if until_time.nil?
+
+          remaining = (until_time - now).to_f
+          remaining.positive? ? remaining.ceil : 0
+        end
+
+        def failure_count
+          read_state.fetch(:failure_count, 0)
+        end
+
+        def self.delay_for(failure_count)
+          [BASE_DELAY_SECONDS * (2**(failure_count - 1)), MAX_DELAY_SECONDS].min
+        end
+
+        delegate :delay_for, to: :class
+
+        private
+
+        attr_reader :store, :clock
+
+        def read_state
+          raw = store.read(STATE_KEY)
+          return { failure_count: 0, cooldown_until: nil } if raw.blank?
+
+          {
+            failure_count: Integer(raw[:failure_count] || raw["failure_count"] || 0),
+            cooldown_until: parse_time(raw[:cooldown_until] || raw["cooldown_until"])
+          }
+        end
+
+        def write_state(failure_count:, cooldown_until:)
+          store.write(
+            STATE_KEY,
+            { failure_count: failure_count, cooldown_until: cooldown_until.utc.iso8601(6) },
+            expires_in: MAX_DELAY_SECONDS * 2
+          )
+        end
+
+        def parse_time(value)
+          return if value.nil?
+          return value if value.is_a?(Time)
+          return value.to_time if value.respond_to?(:to_time)
+
+          Time.iso8601(value.to_s)
+        end
+      end
+    end
+  end
+end

data/app/providers/jumbotron/providers/espn/cooldown_active_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Providers
+    module Espn
+      class CooldownActiveError < StandardError
+        def initialize(msg = "ESPN provider cooldown is active")
+          super
+        end
+      end
+    end
+  end
+end

data/app/providers/jumbotron/providers/espn/provider_failure.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Providers
+    module Espn
+      module ProviderFailure
+        module_function
+
+        def availability_failure?(error)
+          return false unless error.is_a?(CommandTower::Clients::Errors::UpstreamError)
+
+          return true if server_error_status?(error)
+          return true if transport_cause?(error.cause)
+
+          false
+        end
+
+        def server_error_status?(error)
+          status = error.details.is_a?(Hash) ? error.details[:status] : nil
+          status.is_a?(Integer) && status >= 500
+        end
+
+        def transport_cause?(cause)
+          return false if cause.nil?
+          return true if cause.is_a?(CommandTower::Clients::Transport::Error)
+          return true if defined?(Faraday) && cause.is_a?(Faraday::Error)
+          return true if cause.is_a?(Timeout::Error)
+          return true if cause.is_a?(SocketError)
+          return true if cause.is_a?(Errno::ECONNREFUSED)
+          return true if cause.is_a?(Errno::ECONNRESET)
+          return true if cause.is_a?(Errno::ETIMEDOUT)
+          return true if cause.is_a?(Net::OpenTimeout)
+          return true if cause.is_a?(Net::ReadTimeout)
+
+          false
+        end
+      end
+    end
+  end
+end

data/app/providers/jumbotron/providers/espn/resources/competition_odds.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Providers
+    module Espn
+      module Resources
+        class CompetitionOdds
+          def self.acquire(sport:, league:, event_id:, competition_id:)
+            cooldown = Cooldown.new
+            return CommandTower::Clients::ClientResult.failure(error: CooldownActiveError.new) if cooldown.cooling_down?
+
+            result = Jumbotron::Clients.espn.competition_odds.get(
+              sport: sport,
+              league: league,
+              event_id: event_id,
+              competition_id: competition_id
+            )
+            if result.success?
+              cooldown.record_success!
+            else
+              cooldown.record_failure!(result.error)
+            end
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/app/providers/jumbotron/providers/espn/resources/scoreboard.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Providers
+    module Espn
+      module Resources
+        class Scoreboard
+          DISCOVERY_SEASON_TYPES = [1, 2, 3].freeze
+
+          def self.acquire(adapter:, **query)
+            cooldown = Cooldown.new
+            return CommandTower::Clients::ClientResult.failure(error: CooldownActiveError.new) if cooldown.cooling_down?
+
+            result = Jumbotron::Clients.espn.scoreboard.get(
+              sport: adapter.sport,
+              league: adapter.league,
+              **query
+            )
+            if result.success?
+              cooldown.record_success!
+            else
+              cooldown.record_failure!(result.error)
+            end
+            result
+          end
+
+          # ESPN year-only and phase-only scoreboards are capped (~100 events) and do not
+          # isolate a season. Full-season discovery expands leagues[].calendar into
+          # dates + seasontype + week requests, then concatenates unique events.
+          def self.acquire_full_season(adapter:, season_year:)
+            year = Integer(season_year)
+            seed = acquire(adapter: adapter, dates: year)
+            return seed unless seed.success?
+
+            requests = discovery_requests(year, seed.output.season_calendar)
+            return unavailable_calendar(year) if requests.empty?
+
+            events_by_id = {}
+            requests.each do |query|
+              result = acquire(adapter: adapter, **query)
+              return result unless result.success?
+
+              Array(result.output.events).each do |event|
+                events_by_id[event.id] ||= event
+              end
+            end
+
+            CommandTower::Clients::ClientResult.success(
+              output: Jumbotron::Deserializers::Clients::Espn::Scoreboard::Get::Result.build!(
+                events: events_by_id.values,
+                season_calendar: seed.output.season_calendar
+              )
+            )
+          end
+
+          def self.expand_full_season(adapter:, season_year:)
+            year = Integer(season_year)
+            seed = acquire(adapter: adapter, dates: year)
+            return seed unless seed.success?
+
+            requests = discovery_requests(year, seed.output.season_calendar)
+            return unavailable_calendar(year) if requests.empty?
+
+            CommandTower::Clients::ClientResult.success(output: requests)
+          end
+
+          def self.discovery_requests(year, season_calendar)
+            Array(season_calendar).filter_map do |phase|
+              next unless DISCOVERY_SEASON_TYPES.include?(phase.season_type)
+
+              phase.weeks.map do |week|
+                { dates: year, season_type: phase.season_type, week: week }
+              end
+            end.flatten
+          end
+          private_class_method :discovery_requests
+
+          def self.unavailable_calendar(year)
+            CommandTower::Clients::ClientResult.failure(
+              error: CommandTower::Clients::Errors::UpstreamError.new(
+                message: "ESPN scoreboard calendar missing for season #{year}; cannot expand full-season discovery"
+              )
+            )
+          end
+          private_class_method :unavailable_calendar
+        end
+      end
+    end
+  end
+end

data/app/providers/jumbotron/providers/espn/resources/teams.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Providers
+    module Espn
+      module Resources
+        class Teams
+          def self.acquire(adapter:, **query)
+            Jumbotron::Clients.espn.teams.get(
+              sport: adapter.sport,
+              league: adapter.league,
+              **query
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/scheduling/jumbotron/scheduling/backends/sidekiq_cron.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Jumbotron
+  module Scheduling
+    module Backends
+      class SidekiqCron
+        def initialize(job_class: nil)
+          @job_class = job_class
+        end
+
+        def materialize(schedules, **)
+          klass = job_class
+          remove_stale(klass, schedules)
+          upsert_desired(klass, schedules)
+        end
+
+        def cron_string(cadence)
+          Clock.cron(cadence)
+        end
+
+        private
+
+        def remove_stale(klass, schedules)
+          desired_ids = schedules.map(&:id)
+          Array(klass.all).each do |job|
+            name = job_name(job)
+            next unless Owned.key?(name)
+            next if desired_ids.include?(name)
+
+            destroy_job(klass, name, job)
+          end
+        end
+
+        def upsert_desired(klass, schedules)
+          schedules.sort_by(&:id).each do |definition|
+            klass.create(
+              "name" => definition.id,
+              "class" => definition.job_class_name,
+              "cron" => cron_string(definition.cadence),
+              "args" => [definition.arguments]
+            )
+          end
+        end
+
+        def job_class
+          @job_class || (defined?(::Sidekiq::Cron::Job) && ::Sidekiq::Cron::Job) ||
+            raise(UnsupportedIntegrationError, "Sidekiq::Cron::Job is not available")
+        end
+
+        def job_name(job)
+          if job.respond_to?(:name)
+            job.name
+          elsif job.is_a?(Hash)
+            job[:name] || job["name"]
+          else
+            job.to_s
+          end
+        end
+
+        def destroy_job(klass, name, job)
+          if job.respond_to?(:destroy)
+            job.destroy
+          elsif klass.respond_to?(:destroy)
+            klass.destroy(name)
+          end
+        end
+      end
+    end
+  end
+end

data/app/scheduling/jumbotron/scheduling/backends/solid_queue.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require "yaml"
+
+module Jumbotron
+  module Scheduling
+    module Backends
+      class SolidQueue
+        ENV_SECTIONS = %w[development test production staging].freeze
+        DEFAULT_RELATIVE = "config/recurring.yml"
+
+        def initialize(path: nil)
+          @explicit_path = path
+        end
+
+        def materialize(schedules, path: nil)
+          destination = Pathname.new(path || @explicit_path || default_path)
+          document = load_document(destination)
+          section = current_section(document)
+          section.delete_if { |key, _| Owned.key?(key) }
+          schedules.sort_by(&:id).each do |definition|
+            section[definition.id] = task_for(definition)
+          end
+          write_document(destination, document)
+          destination
+        end
+
+        def schedule_string(cadence)
+          Clock.fugit(cadence)
+        end
+
+        private
+
+        def default_path
+          ENV.fetch("SOLID_QUEUE_RECURRING_SCHEDULE") do
+            ENV.fetch("JUMBOTRON_SOLID_QUEUE_RECURRING") do
+              Rails.root.join(DEFAULT_RELATIVE).to_s
+            end
+          end
+        end
+
+        def load_document(destination)
+          return {} unless destination.exist?
+
+          loaded = YAML.safe_load_file(destination, permitted_classes: [Symbol], aliases: true)
+          stringify_keys(loaded || {})
+        end
+
+        def current_section(document)
+          if document.empty? || env_keyed?(document)
+            document[Rails.env.to_s] ||= {}
+          else
+            document
+          end
+        end
+
+        def env_keyed?(document)
+          document.is_a?(Hash) && !document.empty? && document.keys.all? { |key| ENV_SECTIONS.include?(key.to_s) }
+        end
+
+        def task_for(definition)
+          {
+            "class" => definition.job_class_name,
+            "args" => [definition.arguments],
+            "schedule" => schedule_string(definition.cadence)
+          }
+        end
+
+        def write_document(destination, document)
+          FileUtils.mkdir_p(destination.dirname)
+          header = "# jumbotron:* keys are managed by `bin/rails jumbotron:schedules:materialize`.\n"
+          destination.write(header + YAML.dump(stringify_keys(document)))
+        end
+
+        def stringify_keys(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), memo|
+              memo[key.to_s] = stringify_keys(nested)
+            end
+          when Array
+            value.map { |item| stringify_keys(item) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end