Schedulers

def calculate_urgency(self, item: dict) -> float:
    """
    Calculate urgency score for an item.

    Urgency = (time since last update) / (target polling rate)
    
    Returns 0.0 if item is in cooldown.
    """
    # If in backoff cooldown, urgency is 0 (never urgent)
    if item.get('skip_until') and datetime.now() < item['skip_until']:
        return 0.0
    
    if item['last_update'] is None:
        return float('inf')  # Never updated = infinitely urgent

    delta = datetime.now() - item['last_update']
    
    urgency = delta.total_seconds() / item['polling-interval-in-seconds']
    return urgency

async def run(self) -> None:
    """
    Main scheduler loop using urgency-based algorithm.

    Algorithm:
    1. Calculate urgency for all items
    2. If max_urgency >= 1.0, execute that item and loop
    3. If max_urgency < 1.0, sleep until next item is overdue
    4. Repeat forever
    """
    async with SteamAPIClient(rate_limiter=self.rate_limiter) as client, SQLinserts() as wizard:
        self.steam_client = client
        self.data_wizard = wizard

        while True:
            # Execute ALL items that are overdue (urgency >= 1.0)
            executed_any = False
            for item in self.live_items:
                urgency = self.calculate_urgency(item)
                if urgency >= 1.0:
                    await self.execute_item(item)
                    executed_any = True

            # If nothing was urgent, sleep until the next item becomes urgent
            if not executed_any:
                sleep_duration = self.calculate_min_sleep_duration()
                await asyncio.sleep(sleep_duration)

def calculate_min_sleep_duration(self) -> float:
    """
    Calculate MINIMUM sleep time until ANY item becomes actionable.

    Checks all items and returns the shortest time until any item:
    - Reaches urgency 1.0 (overdue), OR
    - Exits 429 cooldown (skip_until reached)
    """
    min_sleep = float('inf')

    for item in self.live_items:
        # Check if item is in 429 cooldown
        if item.get('skip_until') and datetime.now() < item['skip_until']:
            # Time until cooldown ends
            time_until_cooldown_ends = (item['skip_until'] - datetime.now()).total_seconds()
            min_sleep = min(min_sleep, time_until_cooldown_ends)

        else:
            # Normal urgency calculation
            urgency = self.calculate_urgency(item)
            if urgency < 1.0:  # Only consider items that aren't already overdue
                # Time until this item becomes urgent (urgency = 1.0)
                time_until_urgent = (1.0 - urgency) * item['polling-interval-in-seconds']
                min_sleep = min(min_sleep, time_until_urgent)

    # If all items are overdue, don't sleep
    return min_sleep if min_sleep != float('inf') else 0

def apply_exponential_backoff(self, item: dict, error_code: int) -> None:
    """
    Apply exponential backoff for rate limit (429), server (5xx), or network errors.
    
    Backoff strategy:
    - 1st error: skip 1 polling interval
    - 2nd consecutive: skip 2 intervals
    - 3rd consecutive: skip 4 intervals
    - Capped at 8x the polling interval
    """
    item['consecutive_backoffs'] = item.get('consecutive_backoffs', 0) + 1
    
    # Skip N polling intervals, where N = 2^(consecutive - 1), capped at 8
    skip_multiplier = min(2 ** (item['consecutive_backoffs'] - 1), 8)
    skip_seconds = item['polling-interval-in-seconds'] * skip_multiplier
    
    item['skip_until'] = datetime.now() + timedelta(seconds=skip_seconds)
    
    if error_code == 429:
        error_type = "rate limited"
    elif error_code == 0:
        error_type = "network error"
    else:
        error_type = f"server error {error_code}"
    
    print(f"  ⏸ {error_type} on {item['market_hash_name']}:{item['apiid']} - "
          f"cooling down {skip_seconds:.0f}s (attempt #{item['consecutive_backoffs']})")

# SUCCESS: Reset backoff tracking
item['consecutive_backoffs'] = 0
item['skip_until'] = None

async def execute_item(self, item: dict) -> None:
    # Check cooldown
    if item.get('skip_until') and datetime.now() < item['skip_until']:
        return  # Silently skip
    
    try:
        # Route to correct API endpoint
        match item['apiid']:
            case 'priceoverview':
                result = await self.steam_client.fetch_price_overview(...)
            case 'itemordershistogram':
                result = await self.steam_client.fetch_orders_histogram(...)
            case 'itemordersactivity':
                result = await self.steam_client.fetch_orders_activity(...)

        # Store to database
        await self.data_wizard.store_data(result, item)

        # SUCCESS: Reset backoff, update timestamp
        item['consecutive_backoffs'] = 0
        item['skip_until'] = None
        item['last_update'] = datetime.now()

    except aiohttp.ClientResponseError as e:
        if e.status == 429 or e.status >= 500:
            # Transient error - exponential backoff
            self.apply_exponential_backoff(item, e.status)

def get_next_execution_time(self) -> datetime:
    """
    Calculate the next execution time (:30 past the next hour).

    Returns:
        Datetime of next execution (next hour at :30 UTC)
    """
    # Get current UTC time
    now = datetime.now(timezone.utc)

    # Start with :30 of current hour
    next_run = now.replace(minute=30, second=0, microsecond=0)

    # If we're past :30, move to next hour
    if now.minute >= 30:
        next_run = next_run + timedelta(hours=1)

    return next_run

async def run(self) -> None:
    """
    Main clockwork loop.

    Algorithm:
    1. Run pricehistory immediately on startup
    2. Calculate next :30 past the hour
    3. Sleep until that time
    4. Execute all pricehistory items
    5. Repeat from step 2
    """
    async with SteamAPIClient(rate_limiter=self.rate_limiter) as client, SQLinserts() as wizard:
        self.steam_client = client
        self.data_wizard = wizard

        # Run once immediately
        await self.run_initial_fetch()

        while True:
            next_execution = self.get_next_execution_time()
            sleep_seconds = self.calculate_sleep_duration(next_execution)
            print(f"  Historical collector sleeping until {next_execution.strftime('%H:%M:%S')} UTC ({sleep_seconds:.0f} seconds)")
            await asyncio.sleep(sleep_seconds)
            await self.execute_history_items()

async def _fetch_item_with_retry(self, item: dict, max_retries: int = 4) -> None:
    """
    Fetch price history for a single item with retry logic.
    
    Retries transient errors (429, 5xx, network) and auth errors (400, 401, 403)
    with backoff. Auth errors are retried because cookies can be hot-swapped in .env.
    """
    backoff_seconds = [30, 60, 120, 240]  # Fixed delays for each retry
    
    for attempt in range(max_retries + 1):
        try:
            result = await self.steam_client.fetch_price_history(...)
            await self.data_wizard.store_data(result, item)
            item['last_update'] = datetime.now()
            return  # Success

        except aiohttp.ClientResponseError as e:
            if e.status == 429 or e.status >= 500:
                # Transient error - retry
                if attempt < max_retries:
                    delay = backoff_seconds[attempt]
                    print(f"  ⏸ {item['market_hash_name']}: {error_type} - retrying in {delay}s (attempt {attempt + 1}/{max_retries})")
                    await asyncio.sleep(delay)
            elif e.status in (400, 401, 403):
                # Auth error - retry (cookies can be hot-swapped)
                if attempt < max_retries:
                    delay = backoff_seconds[attempt]
                    print(f"  ⏸ {item['market_hash_name']}: HTTP {e.status} (cookie error?) - update .env, retrying in {delay}s")
                    await asyncio.sleep(delay)