feat(hasheous): add hasheous provider with hash-based matching

Author: DevYukine

.env.example

@@ -37,6 +37,12 @@ MOBYGAMES_API_KEY=YOUR_MOBYGAMES_API_KEY
 # exposed by playmatch for this provider.
 # EMUREADY_ENABLED=true
 
+# Hasheous provides hash-based ROM matching against public signature DATs
+# (No-Intros, Redump, TOSEC, MAMEArcade, etc.). Set the flag below to join
+# Hasheous to the daily match cycle. The hash-lookup endpoints are open and
+# require no API key.
+# HASHEOUS_ENABLED=true
+
 # OpenVGDB is a bulk metadata source distributed as a small SQLite snapshot
 # (~9 MB zip). Setting OPENVGDB_ENABLED=true enables a daily download of the
 # OpenVGDB release zip and the import of its ROMs and RELEASES tables into

api/src/lib.rs

@@ -120,6 +120,7 @@ use sea_orm::{ConnectOptions, Database};
 use service::config::http::X_VERSION_HEADER_API;
 use service::db::constants::MAX_CONNECTIONS;
 use service::providers::emuready::EmuReadyClient;
+use service::providers::hasheous::HasheousClient;
 use service::providers::igdb::IgdbClient;
 use service::providers::launchbox::LaunchBoxClient;
 use service::providers::mobygames::MobyGamesClient;
@@ -202,6 +203,8 @@ async fn start() -> anyhow::Result<()> {
 
 	let er_http_client = Client::builder().cookie_store(false).build()?;
 
+	let hasheous_http_client = Client::builder().cookie_store(false).build()?;
+
 	let tgdb_http_client = Client::builder().cookie_store(false).build()?;
 
 	// DAT downloads use a cookieless client so hostile mirrors cannot set cookies that
@@ -223,6 +226,7 @@ async fn start() -> anyhow::Result<()> {
 	let ra_client_opt =
 		build_retroachievements_client(ra_http_client, redis_conn.clone(), conn.clone());
 	let er_client_opt = build_emuready_client(er_http_client, redis_conn.clone());
+	let hasheous_client_opt = build_hasheous_client(hasheous_http_client, redis_conn.clone());
 	let tgdb_client_opt =
 		build_thegamesdb_client(tgdb_http_client, redis_conn.clone(), conn.clone());
 
@@ -265,6 +269,9 @@ async fn start() -> anyhow::Result<()> {
 	if let Some(c) = er_client_opt.clone() {
 		providers.push(c as Arc<dyn MetadataProvider>);
 	}
+	if let Some(c) = hasheous_client_opt.clone() {
+		providers.push(c as Arc<dyn MetadataProvider>);
+	}
 	if let Some(c) = tgdb_client_opt.clone() {
 		providers.push(c as Arc<dyn MetadataProvider>);
 	}
@@ -579,6 +586,33 @@ fn build_emuready_client(
 	}
 }
 
+/// Returns `None` when HASHEOUS_ENABLED is unset or not "true". The Hasheous
+/// hash-lookup endpoints are open and unauthenticated; the flag exists so
+/// existing deployments do not silently start hitting an external service on
+/// next deploy. Matching only. No proxy routes are exposed.
+fn build_hasheous_client(
+	http: Client,
+	redis_conn: redis::aio::MultiplexedConnection,
+) -> Option<Arc<HasheousClient>> {
+	let enabled = env::var("HASHEOUS_ENABLED")
+		.unwrap_or_default()
+		.eq_ignore_ascii_case("true");
+	if !enabled {
+		warn!("HASHEOUS_ENABLED not set to true, Hasheous provider disabled");
+		return None;
+	}
+	match HasheousClient::new(http, redis_conn) {
+		Ok(c) => {
+			info!("Hasheous provider enabled");
+			Some(Arc::new(c))
+		}
+		Err(e) => {
+			warn!("Hasheous provider construction failed, disabled: {e}");
+			None
+		}
+	}
+}
+
 /// Returns `None` when TGDB_ENABLED is unset or not "true". TheGamesDB is
 /// match-only; no proxy routes are exposed. The bootstrap dataset is seeded
 /// via a migration so no daily import job runs. TGDB_API_KEY is optional;

entity/src/sea_orm_active_enums.rs

@@ -122,6 +122,8 @@ pub enum MetadataProviderEnum {
 	#[strum(serialize = "thegamesdb")]
 	#[allow(clippy::upper_case_acronyms)]
 	TheGamesDB,
+	#[sea_orm(string_value = "hasheous")]
+	Hasheous,
 }
 #[derive(Debug, Clone, PartialEq, Eq, EnumIter, DeriveActiveEnum, Copy, Serialize, Deserialize)]
 #[sea_orm(

migration/src/lib.rs

@@ -45,6 +45,7 @@ mod m20260518_120100_create_thegamesdb_tables;
 mod m20260518_120200_bootstrap_thegamesdb_seed;
 mod m20260522_120000_add_too_many_files_failed_match_reason;
 mod m20260523_120000_drop_legacy_api_key_hash;
+mod m20260524_120000_add_hasheous_provider_enum_value;
 
 pub struct Migrator;
 
@@ -97,6 +98,7 @@ impl MigratorTrait for Migrator {
 			Box::new(m20260518_120200_bootstrap_thegamesdb_seed::Migration),
 			Box::new(m20260522_120000_add_too_many_files_failed_match_reason::Migration),
 			Box::new(m20260523_120000_drop_legacy_api_key_hash::Migration),
+			Box::new(m20260524_120000_add_hasheous_provider_enum_value::Migration),
 		]
 	}
 }

migration/src/m20260524_120000_add_hasheous_provider_enum_value.rs

@@ -0,0 +1,25 @@
+use sea_orm::ConnectionTrait;
+use sea_orm_migration::prelude::*;
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+	async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+		manager
+			.get_connection()
+			.execute_unprepared(
+				"ALTER TYPE metadata_provider_enum ADD VALUE IF NOT EXISTS 'hasheous';",
+			)
+			.await?;
+		Ok(())
+	}
+
+	// Postgres has no DROP VALUE for enum types without rewriting every column
+	// that references it; reverting an enum-extension migration is intentionally
+	// a no-op. To roll back, drop the dependent rows and recreate the type.
+	async fn down(&self, _manager: &SchemaManager) -> Result<(), DbErr> {
+		Ok(())
+	}
+}

service/src/model/metadata.rs

@@ -131,6 +131,8 @@ pub enum MetadataProvider {
 	RetroAchievements,
 	/// TheGamesDB (https://thegamesdb.net/)
 	TheGamesDB,
+	/// Hasheous (https://hasheous.org/)
+	Hasheous,
 }
 
 /// Match types for a game
@@ -252,6 +254,7 @@ impl From<MetadataProviderEnum> for MetadataProvider {
 			MetadataProviderEnum::OpenVGDB => MetadataProvider::OpenVGDB,
 			MetadataProviderEnum::RetroAchievements => MetadataProvider::RetroAchievements,
 			MetadataProviderEnum::TheGamesDB => MetadataProvider::TheGamesDB,
+			MetadataProviderEnum::Hasheous => MetadataProvider::Hasheous,
 		}
 	}
 }
@@ -268,6 +271,7 @@ impl From<MetadataProvider> for MetadataProviderEnum {
 			MetadataProvider::OpenVGDB => MetadataProviderEnum::OpenVGDB,
 			MetadataProvider::RetroAchievements => MetadataProviderEnum::RetroAchievements,
 			MetadataProvider::TheGamesDB => MetadataProviderEnum::TheGamesDB,
+			MetadataProvider::Hasheous => MetadataProviderEnum::Hasheous,
 		}
 	}
 }