ltbxd-actorle/docs/superpowers/plans/2026-04-05-tmdb-retry.md

TMDB Retry on Timeout / 5xx — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Retry TMDB HTTP requests automatically on idle timeout and 5xx errors, without retrying legitimate "not found" cases.

Architecture: Wrap the default Symfony HttpClient with RetryableHttpClient (3 retries, exponential backoff) and inject it into TMDBGateway via service configuration. No PHP class changes needed.

Tech Stack: Symfony 8, symfony/http-client (already installed), Symfony\Component\HttpClient\RetryableHttpClient

---

Task 1: Configure RetryableHttpClient for TMDBGateway

Files:

• Modify: config/services.yaml

• Step 1: Add the service definition to config/services.yaml

Append the following inside the existing services: block (after the App\: resource declaration):

    app.http_client.tmdb:
        class: Symfony\Component\HttpClient\RetryableHttpClient
        arguments:
            $client: '@http_client'
            $maxRetries: 3

    App\Gateway\TMDBGateway:
        arguments:
            $client: '@app.http_client.tmdb'

The full services.yaml should look like:

# yaml-language-server: $schema=../vendor/symfony/dependency-injection/Loader/schema/services.schema.json

imports:
    - { resource: parameters.yml }

services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\:
        resource: '../src/'

    app.http_client.tmdb:
        class: Symfony\Component\HttpClient\RetryableHttpClient
        arguments:
            $client: '@http_client'
            $maxRetries: 3

    App\Gateway\TMDBGateway:
        arguments:
            $client: '@app.http_client.tmdb'

• Step 2: Verify the container compiles without errors

php bin/console cache:clear --env=test

Expected output ends with: [OK] Cache for the "test" environment (debug) was successfully cleared.

If you see a ServiceNotFoundException or AutowiringFailedException, double-check the indentation in services.yaml (YAML is indent-sensitive).

• Step 3: Verify TMDBGateway is wired with RetryableHttpClient

php bin/console debug:container App\\Gateway\\TMDBGateway

Expected: the $client argument shows app.http_client.tmdb (or RetryableHttpClient).

• Step 4: Run the test suite to confirm nothing is broken

php bin/phpunit

Expected: all tests pass (no failures, no errors). The existing tests mock TMDBGateway directly so they are unaffected by this wiring change.

• Step 5: Commit

git add config/services.yaml
git commit -m "fix: retry TMDB requests on timeout and 5xx errors"