04-data-hub

🛡️ DATA HUB — ANTI-CORRUPTION LAYER v3.0

MISIÓN

MarketDataHub es el ÚNICO componente que toca APIs externas. Fases B/C son motores de cálculo aislados de la red. Si ves import httpx en backend/phases/phase_b/ → RECHAZAR inmediatamente.

PATRÓN DE LLAMADA — Los motores solo ven esto:

# Lo que el motor recibe — nada más:
snapshot: MarketSnapshot = await hub.get_market_snapshot(ticker="AAPL")

# Lo que el Hub hace internamente (invisible para el motor):
# 1. Selecciona proveedor (FMP / Massive)
# 2. Rota API keys
# 3. Aplica exponential backoff
# 4. Verifica circuit breaker
# 5. Normaliza respuesta → MarketSnapshot
# 6. Adjunta data_lineage
# 7. Retorna Result[MarketSnapshot]

GESTIÓN DE SECRETOS — REGLAS CRÍTICAS

# ✅ CORRECTO — pydantic-settings con SecretStr
from pydantic import SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict

class MarketDataSettings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
    fmp_api_key: SecretStr      # repr() muestra "**********"
    massive_api_key: SecretStr

# Acceso al valor:
key = settings.fmp_api_key.get_secret_value()

# ❌ PROHIBIDO — hardcodeado
API_KEY = "sk-abc123"

# ❌ PROHIBIDO — sin validación
key = os.getenv("API_KEY")  # Puede ser None, vacío, o formato incorrecto

RESILIENCIA — Backoff + Circuit Breaker

# Exponential backoff con jitter:
@exponential_backoff(
    max_retries=3,
    base_delay_seconds=1.0,
    max_delay_seconds=30.0,
    jitter=True,
)
async def _call_fmp_api(self, endpoint: str, params: dict[str, str]) -> dict:
    ...

# Circuit breaker:
# CLOSED → OPEN (5 fallos en 60s) → HALF-OPEN (probe) → CLOSED
# Cuando OPEN: retorna Result.failure() sin llamar la API

RESULTADO — NUNCA LANZAR EXCEPCIONES A CALLERS

# ✅ CORRECTO — Hub retorna Result, nunca lanza
async def get_market_snapshot(self, ticker: str) -> Result[MarketSnapshot]:
    try:
        raw = await self._call_fmp_api(f"/quote/{ticker}", {})
        snapshot = self._fmp_normalizer.normalize(raw, time.time_ns())
        return Result.success(snapshot)
    except (httpx.TimeoutException, ValidationError) as exc:
        logger.error("Hub falló para %s", ticker, exc_info=True)
        return Result.failure(reason=str(exc))

# ❌ PROHIBIDO — excepción cruda al caller
    raise Exception("API no disponible")