51class NHLApiClient:
 52    """Client for interacting with the NHL API.
 53
 54    This client provides methods to fetch team standings and roster data
 55    from the official NHL API with built-in retry logic, rate limiting,
 56    SSRF protection, DoS prevention, and enforced SSL/TLS certificate verification.
 57
 58    SSL/TLS Security:
 59        - Certificate verification is always enabled and cannot be disabled
 60        - Uses certifi CA bundle for up-to-date certificate authorities
 61        - SSL errors are caught and logged for security monitoring
 62
 63    DoS Prevention:
 64        - Circuit breaker pattern to prevent cascading failures
 65        - Connection pool limits to prevent resource exhaustion
 66        - Configurable failure thresholds and timeouts
 67
 68    Attributes:
 69        base_url: Base URL for the NHL API (SSRF-validated)
 70        timeout: Request timeout in seconds
 71        retries: Number of retry attempts for failed requests
 72        rate_limiter: Token bucket rate limiter for API requests
 73        circuit_breaker: Circuit breaker for DoS prevention
 74        ca_bundle: Path to CA bundle for SSL verification (uses certifi)
 75    """
 76
 77    BASE_URL = "https://api-web.nhle.com/v1"  # Default base URL
 78    _instances: ClassVar[set[weakref.ref["NHLApiClient"]]] = set()  # Track all instances
 79
 80    @classmethod
 81    def _cleanup_callback(cls, ref: weakref.ref["NHLApiClient"]) -> None:
 82        """Remove dead instance from tracking set.
 83
 84        Args:
 85            ref: Weak reference to the instance being garbage collected.
 86        """
 87        cls._instances.discard(ref)
 88
 89    @classmethod
 90    def _cleanup_all(cls) -> None:
 91        """Close all remaining open sessions at program exit (safety net)."""
 92        alive_instances = [ref() for ref in cls._instances if ref() is not None]
 93        if alive_instances:
 94            logger.warning(
 95                f"Cleaning up {len(alive_instances)} unclosed NHLApiClient session(s) at exit",
 96            )
 97            for instance in alive_instances:
 98                if instance and not instance._closed:  # noqa: SLF001
 99                    instance.close()
100
101    def __init__(  # noqa: PLR0913
102        self,
103        base_url: str | None = None,
104        timeout: int = 10,
105        retries: int = 3,
106        rate_limit_max_requests: int = 30,
107        rate_limit_window: float = 60.0,
108        backoff_factor: float = 2.0,
109        max_backoff: float = 30.0,
110        cache_enabled: bool = True,
111        cache_expiry: int = 3600,
112        cache_dir: str | Path | None = None,
113        verify_ssl: bool = True,
114        dos_max_connections: int = 10,
115        dos_max_per_host: int = 5,
116        dos_circuit_breaker_threshold: int = 5,
117        dos_circuit_breaker_timeout: float = 60.0,
118    ) -> None:
119        """Initialize the NHL API client.
120
121        Args:
122            base_url: Base URL for NHL API (default: https://api-web.nhle.com/v1).
123                Will be validated for SSRF protection on first request.
124            timeout: Request timeout in seconds (default: 10)
125            retries: Number of retry attempts for failed requests (default: 3)
126            rate_limit_max_requests: Maximum requests per time window (default: 30)
127            rate_limit_window: Time window for rate limiting in seconds (default: 60.0)
128            backoff_factor: Exponential backoff multiplier (default: 2.0)
129            max_backoff: Maximum backoff delay in seconds (default: 30.0)
130            cache_enabled: Enable HTTP caching (default: True)
131            cache_expiry: Cache expiration in seconds (default: 3600 = 1 hour)
132            cache_dir: Cache directory path (default: platform-specific user cache directory)
133            verify_ssl: SSL verification (must be True, cannot be disabled for security)
134            dos_max_connections: Maximum connection pool connections (default: 10)
135            dos_max_per_host: Maximum connections per host (default: 5)
136            dos_circuit_breaker_threshold: Circuit breaker failure threshold (default: 5)
137            dos_circuit_breaker_timeout: Circuit breaker timeout in seconds (default: 60.0)
138
139        Raises:
140            NHLApiError: If base_url fails SSRF protection validation or cache directory not writable
141            ValueError: If verify_ssl is False (SSL verification cannot be disabled)
142        """
143        # Initialize state tracking FIRST (before any potential exceptions)
144        # This prevents AttributeError in __del__ if __init__ fails
145        self._closed = False
146
147        # Enforce SSL verification - cannot be disabled
148        if not verify_ssl:
149            error_msg = "SSL verification cannot be disabled for security reasons"
150            logger.error(error_msg)
151            raise ValueError(error_msg)
152
153        # Use provided base_url or fall back to class default
154        self.base_url = base_url or self.BASE_URL
155
156        self.timeout = timeout
157        self.retries = retries
158        self.backoff_factor = backoff_factor
159        self.max_backoff = max_backoff
160        self.cache_enabled = cache_enabled
161        self.cache_expiry = cache_expiry
162
163        # Initialize rate limiter
164        self.rate_limiter = RateLimiter(
165            max_requests=rate_limit_max_requests,
166            time_window=rate_limit_window,
167        )
168        logger.debug(
169            f"Rate limiter initialized: {rate_limit_max_requests} requests per {rate_limit_window}s",
170        )
171
172        # Initialize circuit breaker for DoS prevention
173        self.circuit_breaker = CircuitBreaker(
174            failure_threshold=dos_circuit_breaker_threshold,
175            timeout=dos_circuit_breaker_timeout,
176            expected_exception=(
177                requests.exceptions.RequestException,
178                NHLApiError,
179            ),
180        )
181        logger.debug(
182            f"Circuit breaker initialized: threshold={dos_circuit_breaker_threshold}, "
183            f"timeout={dos_circuit_breaker_timeout}s",
184        )
185
186        # Use certifi CA bundle for SSL verification
187        self.ca_bundle = certifi.where()
188        logger.debug(f"Using CA bundle for SSL verification: {self.ca_bundle}")
189
190        # Session can be either CachedSession or regular Session
191        self.session: requests_cache.CachedSession | requests.Session
192        if cache_enabled:
193            # Determine cache directory
194            if cache_dir is None:
195                # Use platform-specific user cache directory
196                cache_path = Path(platformdirs.user_cache_dir("nhl-scrabble", "bdperkin"))
197            else:
198                cache_path = Path(cache_dir)
199
200            # Create cache directory with permission checking
201            try:
202                cache_path.mkdir(parents=True, exist_ok=True)
203            except (OSError, PermissionError) as e:
204                logger.error(f"Cannot create cache directory {cache_path}: {e}")
205                raise NHLApiError(
206                    f"Cache directory not writable: {cache_path}. "
207                    f"Check permissions or specify a different cache directory "
208                    f"with the cache_dir parameter.",
209                ) from e
210
211            # Verify directory is writable
212            if not os.access(cache_path, os.W_OK):
213                error_msg = (
214                    f"Cache directory not writable: {cache_path}. "
215                    f"Check permissions or specify a different cache directory."
216                )
217                logger.error(error_msg)
218                raise NHLApiError(error_msg)
219
220            # Create cached session with platform-specific path
221            cache_file = cache_path / "api_cache"
222            self.session = requests_cache.CachedSession(
223                cache_name=str(cache_file),
224                backend="sqlite",
225                expire_after=timedelta(seconds=cache_expiry),
226                allowable_codes=[200],  # Only cache successful responses
227                allowable_methods=["GET"],
228                cache_control=True,  # Respect Cache-Control headers
229            )
230            logger.debug(f"HTTP caching enabled (directory: {cache_path}, expiry: {cache_expiry}s)")
231        else:
232            self.session = requests.Session()
233            logger.debug("HTTP caching disabled")
234
235        # Configure connection pool limits for DoS protection
236        adapter = HTTPAdapter(
237            pool_connections=dos_max_connections,
238            pool_maxsize=dos_max_per_host,
239        )
240        self.session.mount("https://", adapter)
241        self.session.mount("http://", adapter)
242        logger.debug(
243            f"Connection pool configured: max_connections={dos_max_connections}, "
244            f"max_per_host={dos_max_per_host}",
245        )
246
247        self.session.headers.update({"User-Agent": "NHL-Scrabble/2.0"})
248
249        # Register instance for cleanup at exit (safety net)
250        self._instances.add(weakref.ref(self, self._cleanup_callback))
251        atexit.register(self._cleanup_all)
252
253    def __del__(self) -> None:
254        """Destructor - close session if not already closed (safety net)."""
255        if not self._closed:
256            logger.warning(
257                "NHLApiClient session was not explicitly closed - cleaning up in destructor",
258            )
259            self.close()
260
261    def _validate_request_url(self, url: str) -> None:
262        """Validate URL with SSRF protection before making request.
263
264        Args:
265            url: Full URL to validate
266
267        Raises:
268            NHLApiError: If URL fails SSRF protection validation
269        """
270        try:
271            validate_url_for_ssrf(url)
272        except SSRFProtectionError as e:
273            logger.error(
274                "SSRF protection blocked request to %s: %s",
275                sanitize_for_logging(url),
276                sanitize_for_logging(e),
277            )
278            raise NHLApiError(f"Request blocked by security protection: {e}") from e
279
280    def _is_url_cached(self, url: str) -> bool:
281        """Check if a URL response is cached and not expired.
282
283        Args:
284            url: The URL to check
285
286        Returns:
287            True if the URL response is cached and valid, False otherwise
288
289        Examples:
290            >>> client = NHLApiClient(cache_enabled=True)  # doctest: +SKIP
291            >>> client._is_url_cached("https://api-web.nhle.com/v1/roster/TOR/current")  # doctest: +SKIP
292            False  # Not cached initially  # doctest: +SKIP
293        """
294        if not self.cache_enabled:
295            return False
296
297        if not hasattr(self.session, "cache"):
298            return False
299
300        try:
301            # Check if URL is in cache using has_url() method (requests-cache 1.0+)
302            if hasattr(self.session.cache, "has_url"):
303                return self.session.cache.has_url(url)  # type: ignore[no-any-return]
304
305            # Fallback: check using contains() method
306            if hasattr(self.session.cache, "contains"):
307                return self.session.cache.contains(url=url)  # type: ignore[no-any-return]
308
309            # If no cache checking method available, assume not cached
310            return False
311        except Exception:  # noqa: BLE001
312            # If anything goes wrong checking cache, assume not cached
313            # This ensures we always apply rate limiting if uncertain
314            return False
315
316    def get_teams(self, season: str | None = None) -> dict[str, dict[str, str]]:
317        """Fetch all NHL teams with division and conference information.
318
319        This method uses the retry decorator to automatically retry on network errors.
320        The URL is validated with SSRF protection before making the request.
321
322        Args:
323            season: Optional season in format 'YYYYYYYY' (e.g., '20222023' for 2022-23).
324                If None, fetches current season data.
325
326        Returns:
327            Dictionary mapping team abbreviations to their metadata:
328            {
329                'TOR': {'division': 'Atlantic', 'conference': 'Eastern'},
330                'MTL': {'division': 'Atlantic', 'conference': 'Eastern'},
331                ...
332            }
333
334        Raises:
335            NHLApiConnectionError: If unable to connect to the API
336            NHLApiError: For other API errors, including SSRF protection blocks
337
338        Examples:
339            >>> client = NHLApiClient()
340            >>> teams = client.get_teams()
341            >>> "TOR" in teams
342            True
343            >>> teams_2022 = client.get_teams(season="20222023")
344            >>> "TOR" in teams_2022
345            True
346        """
347        # Use season-specific endpoint or current season endpoint
348        endpoint = f"standings/{season}" if season else "standings/now"
349        url = f"{self.base_url}/{endpoint}"
350
351        season_desc = f"season {season}" if season else "current season"
352        logger.debug(f"Fetching NHL teams from standings endpoint for {season_desc}")
353
354        # Validate URL with SSRF protection
355        self._validate_request_url(url)
356
357        @retry(
358            max_attempts=self.retries,
359            backoff_factor=self.backoff_factor,
360            max_backoff=self.max_backoff,
361            exceptions=(
362                requests.exceptions.Timeout,
363                requests.exceptions.ConnectionError,
364            ),
365        )
366        def _fetch_teams() -> dict[str, dict[str, str]]:
367            """Fetch teams with retry logic."""
368            # Check if URL is cached
369            is_cached = self._is_url_cached(url)
370
371            # Only rate limit for actual API calls (not cached responses)
372            if not is_cached:
373                if logger.isEnabledFor(logging.DEBUG):
374                    logger.debug("Rate limiting: acquiring token for teams request")
375                self.rate_limiter.acquire()
376
377            try:
378                response = self.session.get(
379                    url,
380                    timeout=self.timeout,
381                    verify=self.ca_bundle,  # Explicit SSL verification with certifi CA bundle
382                )
383
384                # Handle rate limiting (429)
385                if response.status_code == 429:
386                    retry_after = get_retry_after(response)
387                    logger.warning(f"Rate limited (429). Waiting {retry_after}s before retry.")
388                    time.sleep(retry_after)
389                    # Raise to trigger retry
390                    response.raise_for_status()
391
392                response.raise_for_status()
393                data = response.json()
394
395                teams_info: dict[str, dict[str, str]] = {}
396                for team in data["standings"]:
397                    team_abbrev = team["teamAbbrev"]["default"]
398                    team_name = team.get("teamName", {}).get("default", team_abbrev)
399                    teams_info[team_abbrev] = {
400                        "name": team_name,
401                        "division": team.get("divisionName", "Unknown"),
402                        "conference": team.get("conferenceName", "Unknown"),
403                    }
404
405                logger.debug(f"Successfully fetched {len(teams_info)} teams")
406
407                # Log cache status
408                from_cache = (
409                    hasattr(response, "from_cache")
410                    and isinstance(response.from_cache, bool)
411                    and response.from_cache
412                )
413                if from_cache:
414                    logger.debug("Cache hit - skipped rate limiting")
415                else:
416                    logger.debug("Real API request - rate limited")
417
418                return teams_info
419
420            except requests.exceptions.SSLError as e:
421                logger.error(f"SSL certificate verification failed for {url}: {e}")
422                raise NHLApiSSLError(f"SSL certificate verification failed for {url}: {e}") from e
423            except requests.exceptions.HTTPError as e:
424                logger.error(f"HTTP error while fetching teams: {e}")
425                raise NHLApiError(f"HTTP error: {e}") from e
426            except (KeyError, ValueError) as e:
427                logger.error(f"Error parsing teams response: {e}")
428                raise NHLApiError(f"Invalid API response format: {e}") from e
429
430        try:
431            # Wrap with circuit breaker for DoS prevention
432            return self.circuit_breaker.call(_fetch_teams)
433        except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as e:
434            # Convert to NHLApiConnectionError after retries exhausted
435            logger.error(f"Connection error after retries: {e}")
436            raise NHLApiConnectionError("Unable to connect to NHL API after retries") from e
437
438    def _sanitize_roster_player_names(self, roster_data: dict[str, Any]) -> None:
439        """Sanitize player names in roster data to prevent injection attacks.
440
441        Validates and sanitizes all player names (firstName and lastName) in the
442        roster data for all positions (forwards, defensemen, goalies).
443
444        Args:
445            roster_data: Roster data dictionary with forwards, defensemen, goalies
446
447        Raises:
448            NHLApiError: If player names contain invalid characters (potential attack)
449
450        Note:
451            Modifies roster_data in-place for efficiency
452        """
453        for position in ("forwards", "defensemen", "goalies"):
454            if position not in roster_data:
455                continue
456
457            for player in roster_data[position]:
458                # Validate and sanitize first name
459                if (
460                    "firstName" in player
461                    and isinstance(player["firstName"], dict)
462                    and "default" in player["firstName"]
463                ):
464                    try:
465                        player["firstName"]["default"] = validate_player_name(
466                            player["firstName"]["default"],
467                        )
468                    except ValidationError as e:
469                        logger.warning(f"Invalid player first name in API response: {e}")
470                        # Use sanitized version or skip
471                        player["firstName"]["default"] = "Unknown"
472
473                # Validate and sanitize last name
474                if (
475                    "lastName" in player
476                    and isinstance(player["lastName"], dict)
477                    and "default" in player["lastName"]
478                ):
479                    try:
480                        player["lastName"]["default"] = validate_player_name(
481                            player["lastName"]["default"],
482                        )
483                    except ValidationError as e:
484                        logger.warning(f"Invalid player last name in API response: {e}")
485                        # Use sanitized version or skip
486                        player["lastName"]["default"] = "Unknown"
487
488    def get_team_roster(  # noqa: PLR0915
489        self,
490        team_abbrev: str,
491        season: str | None = None,
492    ) -> dict[str, Any]:
493        """Fetch the roster for a specific team with input and response validation.
494
495        Validates team abbreviation before making API call and validates response
496        structure to prevent errors from malformed data.
497
498        The URL is validated with SSRF protection before making the request.
499
500        Args:
501            team_abbrev: Team abbreviation (e.g., 'TOR', 'MTL')
502            season: Optional season in format 'YYYYYYYY' (e.g., '20222023' for 2022-23).
503                If None, fetches current season roster.
504
505        Returns:
506            Dictionary containing roster data with 'forwards', 'defensemen', and 'goalies' keys
507
508        Raises:
509            ValidationError: If team abbreviation is invalid
510            NHLApiNotFoundError: If the roster is not found (404 response)
511            NHLApiConnectionError: If unable to connect to the API after all retries
512            NHLApiError: For other API errors, including SSRF protection blocks and malformed responses
513
514        Security:
515            - Validates team abbreviation to prevent injection attacks
516            - Validates response structure to prevent KeyError exceptions
517            - Sanitizes player names from API responses
518            - SSRF protection on all API requests
519
520        Examples:
521            >>> client = NHLApiClient()
522            >>> roster = client.get_team_roster("TOR")
523            >>> "forwards" in roster
524            True
525            >>> roster_2022 = client.get_team_roster("TOR", season="20222023")
526            >>> "forwards" in roster_2022
527            True
528            >>> client.get_team_roster("INVALID")
529            Traceback (most recent call last):
530            ValidationError: Team abbreviation must be 2-3 characters...
531        """
532        # Validate team abbreviation BEFORE making API call
533        try:
534            validated_abbrev = validate_team_abbreviation(team_abbrev)
535        except ValidationError:
536            # Re-raise validation errors for consistency with other API errors
537            logger.error("Invalid team abbreviation: %s", sanitize_for_logging(team_abbrev))
538            raise
539
540        # Use season-specific endpoint or current season endpoint
541        endpoint = (
542            f"roster/{validated_abbrev}/{season}"
543            if season
544            else f"roster/{validated_abbrev}/current"
545        )
546        url = f"{self.base_url}/{endpoint}"
547
548        season_desc = f"season {season}" if season else "current season"
549        if logger.isEnabledFor(logging.DEBUG):
550            logger.debug(
551                "Fetching roster for %s (%s)",
552                sanitize_for_logging(validated_abbrev),
553                sanitize_for_logging(season_desc),
554            )
555
556        # Validate URL with SSRF protection
557        self._validate_request_url(url)
558
559        def _fetch_roster() -> dict[str, Any]:  # noqa: PLR0915
560            """Fetch roster with retry logic."""
561            for attempt in range(self.retries):
562                try:
563                    # Check if URL is cached
564                    is_cached = self._is_url_cached(url)
565
566                    # Only rate limit for actual API calls (not cached responses)
567                    if not is_cached:
568                        if logger.isEnabledFor(logging.DEBUG):
569                            logger.debug(f"Rate limiting: acquiring token for {team_abbrev} roster")
570                        self.rate_limiter.acquire()
571
572                    response = self.session.get(
573                        url,
574                        timeout=self.timeout,
575                        verify=self.ca_bundle,  # Explicit SSL verification with certifi CA bundle
576                    )
577
578                    if response.status_code == 404:
579                        logger.warning(f"No roster data available for {team_abbrev}")
580                        raise NHLApiNotFoundError(f"Roster not found for team: {team_abbrev}")
581
582                    # Handle 429 rate limiting with exponential backoff
583                    if response.status_code == 429:
584                        if attempt < self.retries - 1:
585                            retry_after = get_retry_after(response)
586                            logger.warning(
587                                f"Rate limited (429) for {team_abbrev} "
588                                f"(attempt {attempt + 1}/{self.retries}), "
589                                f"retrying in {retry_after:.2f}s...",
590                            )
591                            time.sleep(retry_after)
592                            continue
593                        logger.error(
594                            f"Rate limited (429) for {team_abbrev} after {self.retries} attempts",
595                        )
596                        raise NHLApiConnectionError(
597                            f"Rate limited after {self.retries} attempts",
598                        ) from None
599
600                    response.raise_for_status()
601                    data = response.json()
602
603                    # Validate response structure
604                    try:
605                        validate_api_response_structure(
606                            data,
607                            required_keys=["forwards", "defensemen", "goalies"],
608                            context=f"Team roster response for {validated_abbrev}",
609                        )
610                    except ValidationError as e:
611                        logger.error(
612                            f"Invalid roster response structure for {validated_abbrev}: {e}",
613                        )
614                        raise NHLApiError(f"Invalid API response: {e}") from e
615
616                    # Sanitize player names in response
617                    self._sanitize_roster_player_names(data)
618
619                    if logger.isEnabledFor(logging.DEBUG):
620                        logger.debug(
621                            f"Successfully fetched and validated roster for {validated_abbrev}",
622                        )
623
624                    # Log cache status
625                    from_cache = (
626                        hasattr(response, "from_cache")
627                        and isinstance(response.from_cache, bool)
628                        and response.from_cache
629                    )
630                    if from_cache:
631                        logger.debug("Cache hit - skipped rate limiting")
632                    else:
633                        logger.debug("Real API request - rate limited")
634
635                    return data  # type: ignore[no-any-return]
636
637                except requests.exceptions.Timeout:
638                    if attempt < self.retries - 1:
639                        backoff_delay = _calculate_backoff_delay(
640                            attempt=attempt,
641                            backoff_factor=self.backoff_factor,
642                            max_backoff=self.max_backoff,
643                        )
644                        logger.warning(
645                            f"Timeout fetching {team_abbrev} "
646                            f"(attempt {attempt + 1}/{self.retries}), "
647                            f"retrying in {backoff_delay:.2f}s...",
648                        )
649                        time.sleep(backoff_delay)
650                    else:
651                        logger.error(f"Failed to fetch {team_abbrev} after {self.retries} attempts")
652                        raise NHLApiConnectionError(
653                            f"Request timed out after {self.retries} attempts",
654                        ) from None
655
656                except requests.exceptions.SSLError as e:
657                    # SSL errors should not be retried - certificate validation failure is permanent
658                    logger.error(f"SSL certificate verification failed for {team_abbrev}: {e}")
659                    raise NHLApiSSLError(
660                        f"SSL certificate verification failed for {url}: {e}",
661                    ) from e
662
663                except requests.exceptions.ConnectionError:
664                    if attempt < self.retries - 1:
665                        backoff_delay = _calculate_backoff_delay(
666                            attempt=attempt,
667                            backoff_factor=self.backoff_factor,
668                            max_backoff=self.max_backoff,
669                        )
670                        logger.warning(
671                            f"Connection error for {team_abbrev} "
672                            f"(attempt {attempt + 1}/{self.retries}), "
673                            f"retrying in {backoff_delay:.2f}s...",
674                        )
675                        time.sleep(backoff_delay)
676                    else:
677                        logger.error(f"Failed to fetch {team_abbrev} after {self.retries} attempts")
678                        raise NHLApiConnectionError(
679                            f"Connection failed after {self.retries} attempts",
680                        ) from None
681
682                except requests.exceptions.HTTPError as e:
683                    logger.error(f"HTTP error fetching {team_abbrev}: {e}")
684                    raise NHLApiError(f"HTTP error: {e}") from e
685
686            # This should never be reached as all paths above either return or raise
687            raise NHLApiError("Unexpected error: retry loop completed without returning data")
688
689        # Wrap with circuit breaker for DoS prevention
690        return self.circuit_breaker.call(_fetch_roster)
691
692    def get_player_details(self, player_id: int) -> dict[str, Any]:
693        """Fetch detailed player information from NHL API.
694
695        Args:
696            player_id: NHL player ID (numeric)
697
698        Returns:
699            Player detail data including photo, birthplace, position, etc.
700
701        Raises:
702            NHLApiNotFoundError: If player not found
703            NHLApiConnectionError: If unable to connect to the API
704            NHLApiError: If API request fails
705
706        Examples:
707            >>> client = NHLApiClient()
708            >>> try:
709            ...     player = client.get_player_details(8478402)  # Connor McDavid
710            ...     assert "playerId" in player
711            ...     assert "firstName" in player
712            ... finally:
713            ...     client.close()
714        """
715        url = f"{self.base_url}/player/{player_id}/landing"
716
717        logger.debug("Fetching player details for player ID %s", sanitize_for_logging(player_id))
718
719        # Validate URL with SSRF protection
720        self._validate_request_url(url)
721
722        @retry(
723            max_attempts=self.retries,
724            backoff_factor=self.backoff_factor,
725            max_backoff=self.max_backoff,
726            exceptions=(
727                requests.exceptions.Timeout,
728                requests.exceptions.ConnectionError,
729            ),
730        )
731        def _fetch_player_details() -> dict[str, Any]:
732            """Fetch player details with retry logic."""
733            # Check if URL is cached
734            is_cached = self._is_url_cached(url)
735
736            # Only rate limit for actual API calls (not cached responses)
737            if not is_cached:
738                if logger.isEnabledFor(logging.DEBUG):
739                    logger.debug(f"Rate limiting: acquiring token for player {player_id}")
740                self.rate_limiter.acquire()
741
742            try:
743                response = self.session.get(
744                    url,
745                    timeout=self.timeout,
746                    verify=self.ca_bundle,  # Explicit SSL verification with certifi CA bundle
747                )
748
749                # Handle 404 - player not found
750                if response.status_code == 404:
751                    logger.warning(f"Player {player_id} not found")
752                    raise NHLApiNotFoundError(f"Player {player_id} not found")
753
754                # Handle rate limiting (429)
755                if response.status_code == 429:
756                    retry_after = get_retry_after(response)
757                    logger.warning(f"Rate limited (429). Waiting {retry_after}s before retry.")
758                    time.sleep(retry_after)
759                    # Raise to trigger retry
760                    response.raise_for_status()
761
762                response.raise_for_status()
763                data = response.json()
764
765                # Validate response structure
766                validate_api_response_structure(
767                    data,
768                    required_keys=["playerId", "firstName", "lastName"],
769                )
770
771                logger.debug(f"Successfully fetched player details for {player_id}")
772
773                # Log cache status
774                from_cache = (
775                    hasattr(response, "from_cache")
776                    and isinstance(response.from_cache, bool)
777                    and response.from_cache
778                )
779                if from_cache:
780                    logger.debug("Cache hit - skipped rate limiting")
781                else:
782                    logger.debug("Real API request - rate limited")
783
784                return data  # type: ignore[no-any-return]
785
786            except requests.exceptions.SSLError as e:
787                logger.error(f"SSL certificate verification failed for player {player_id}: {e}")
788                raise NHLApiSSLError(
789                    f"SSL certificate verification failed for {url}: {e}",
790                ) from e
791            except requests.exceptions.HTTPError as e:
792                if e.response is not None and e.response.status_code == 404:
793                    raise NHLApiNotFoundError(f"Player {player_id} not found") from e
794                logger.error(f"HTTP error while fetching player {player_id}: {e}")
795                raise NHLApiError(f"HTTP error: {e}") from e
796            except (KeyError, ValueError) as e:
797                logger.error(f"Error parsing player details response: {e}")
798                raise NHLApiError(f"Invalid API response format: {e}") from e
799
800        try:
801            # Wrap with circuit breaker for DoS prevention
802            return self.circuit_breaker.call(_fetch_player_details)
803        except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as e:
804            # Convert to NHLApiConnectionError after retries exhausted
805            logger.error(f"Connection error after retries: {e}")
806            raise NHLApiConnectionError("Unable to connect to NHL API after retries") from e
807
808    def get_rate_limit_stats(self) -> dict[str, Any]:
809        """Get rate limiter statistics.
810
811        Returns:
812            Dictionary with rate limiter statistics including:
813                - total_requests: Total requests made
814                - total_waits: Total times waited for tokens
815                - total_wait_time: Total time spent waiting
816                - average_wait: Average wait time per wait
817                - current_tokens: Current token count
818                - max_tokens: Maximum token capacity
819
820        Examples:
821            >>> client = NHLApiClient()
822            >>> stats = client.get_rate_limit_stats()
823            >>> "total_requests" in stats
824            True
825        """
826        return self.rate_limiter.get_stats()
827
828    def clear_cache(self) -> None:
829        """Clear the HTTP cache."""
830        if self.cache_enabled and hasattr(self.session, "cache"):
831            self.session.cache.clear()
832            logger.info("API cache cleared")
833        else:
834            logger.debug("Cache not available or caching disabled")
835
836    def get_cache_info(self) -> dict[str, Any]:
837        """Get cache statistics and information.
838
839        Returns:
840            Dictionary with cache information:
841            - enabled (bool): Whether caching is enabled
842            - backend (str | None): Cache backend type (e.g., "sqlite")
843            - size (int | None): Number of cached responses
844            - expiry (int): Cache expiry time in seconds
845
846        Examples:
847            >>> client = NHLApiClient(cache_enabled=True)
848            >>> info = client.get_cache_info()
849            >>> print(info["enabled"])
850            True
851            >>> print(info["backend"])
852            'sqlite'
853        """
854        info: dict[str, Any] = {
855            "enabled": self.cache_enabled,
856            "backend": None,
857            "size": None,
858            "expiry": self.cache_expiry,
859        }
860
861        if self.cache_enabled and hasattr(self.session, "cache"):
862            # Get backend type
863            if hasattr(self.session.cache, "db_path"):
864                info["backend"] = "sqlite"
865
866            # Get cache size (number of responses)
867            try:
868                if hasattr(self.session.cache, "responses"):
869                    # requests-cache 1.0+
870                    info["size"] = len(self.session.cache.responses)
871                elif hasattr(self.session.cache, "__len__"):
872                    # Fallback to __len__ if available
873                    info["size"] = len(self.session.cache)
874            except Exception:  # noqa: BLE001
875                # If we can't get size, leave it as None
876                logger.debug("Could not retrieve cache size")
877
878        return info
879
880    def close(self) -> None:
881        """Close the session and release resources."""
882        if not self._closed and hasattr(self, "session"):
883            self.session.close()
884            self._closed = True
885            logger.debug("NHL API client session closed")
886
887    def __enter__(self) -> "NHLApiClient":
888        """Support context manager protocol."""
889        return self
890
891    def __exit__(
892        self,
893        exc_type: type[BaseException] | None,
894        exc_val: BaseException | None,
895        exc_tb: types.TracebackType | None,
896    ) -> None:
897        """Close session when exiting context manager."""
898        self.close()