feat: Add ScreenScraper metadata proxy support via Hasheous

[gantoine]

TL;DR
Adds ScreenScraper metadata fetching through the Hasheous proxy as a credential-free fallback when users don't have their own ScreenScraper account. This leverages new Hasheous endpoints for game metadata lookups by hash or game ID.

What changed?

• Hasheous Handler Enhancement: Added get_ss_game() and get_ss_rom_by_id() methods to fetch ScreenScraper metadata through the Hasheous proxy endpoint (/MetadataProxy/ScreenScraper/jeuInfos.php)

  • get_ss_game() performs hash-based lookups (MD5, SHA1, CRC) with file size and name as fallbacks
  • get_ss_rom_by_id() refetches metadata by existing game ID
  • Both methods reuse existing ScreenScraper parsing logic via build_ss_game() to maintain consistent metadata structure

• Scan Handler Integration: Updated ROM scanning logic to fall back to Hasheous ScreenScraper proxy when:

  • ScreenScraper direct access is disabled (meta_ss_handler not enabled)
  • Hasheous is enabled and the platform is in the supported list
  • Prioritizes direct ScreenScraper if available, falls back to Hasheous proxy otherwise

• File Filtering: Implemented platform-specific file extension filtering for hash-based lookups, selecting the largest valid file as most likely to contain the main ROM

• Test Coverage: Added comprehensive unit tests for the Hasheous ScreenScraper proxy functionality

Checklist

• I've tested the changes locally
• I've updated relevant comments
• I've assigned reviewers for this PR
• I've added unit tests that cover the changes

---

Created with PostHog Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[greptile-apps]

Greptile Summary

This PR adds ScreenScraper metadata lookup through the Hasheous proxy. The main changes are:

• Hash- and game-ID-based ScreenScraper proxy requests.
• Reuse of existing ScreenScraper parsing and file filtering.
• Integration of proxy metadata into ROM scans.
• Unit tests for handler success and empty-result paths.

Confidence Score: 4/5

The scan integration can replace preferred metadata and lets an optional proxy outage fail the combined fetch.

• The proxy runs even when direct ScreenScraper is available.
• Proxy fields overwrite existing IGDB fields in the Hasheous result.
• A proxy network error propagates through the shared gather and can fail the scan.

backend/handler/scan_handler.py

Important Files Changed

Filename	Overview
backend/handler/metadata/hasheous_handler.py	Adds the ScreenScraper proxy endpoint, lookup methods, filtering, and shared metadata parsing.
backend/handler/scan_handler.py	Adds the proxy request to the Hasheous fetch and merges its metadata into the scan result.
backend/tests/handler/metadata/test_hasheous_handler.py	Adds unit coverage for successful, disabled, empty, not-game, and game-ID proxy lookups.

_{Reviews (1): Last reviewed commit: "mroe cleanup" | Re-trigger Greptile}

[greptile-apps]

Proxy Bypasses Fallback Gate

When both direct ScreenScraper and Hasheous are enabled, this lookup runs alongside the direct request instead of waiting for it to be unavailable or return no match. The proxy result can then replace metadata from the configured ScreenScraper account, so the direct source is not actually prioritized.

[greptile-apps]

Fallback Metadata Wins Merge

When the IGDB and ScreenScraper proxy lookups both succeed, spreading ss_game last replaces overlapping IGDB fields such as name, summary, and media URLs. This makes the new fallback discard metadata already selected by the existing Hasheous IGDB path.

[greptile-apps]

Optional Lookup Aborts Scan

A network error from this new proxy request raises an HTTP 503 through _request(), and asyncio.gather propagates it from the combined Hasheous fetch. An outage limited to the optional ScreenScraper endpoint can therefore discard successful IGDB and RA work and fail the ROM scan.