Merge pull request #1141 from ludovic111/feat/mod-browser-sources

🤖 Agent: merged. Verify and CI parity pass. Mod browser part 1/3: Modrinth source and checksum verification. The CurseForge source stays inactive until a key is configured.
This commit is contained in:
Ludovic Marie
2026-10-22 05:03:13 +02:00
committed by GitHub
11 changed files with 1310 additions and 1 deletions
+3
View File
@@ -116,6 +116,9 @@ jobs:
# Horizon's Azure app for Microsoft sign-in (docs/microsoft-account.md): a repository
# variable, not a secret. Unset, the launcher says sign-in is not configured.
HORIZON_MSA_CLIENT_ID: ${{ vars.HORIZON_MSA_CLIENT_ID }}
# The mod browser's CurseForge source (docs/mod-browser.md#curseforge): a repository secret. Unset, the
# launcher searches Modrinth only.
HORIZON_CURSEFORGE_API_KEY: ${{ secrets.HORIZON_CURSEFORGE_API_KEY }}
# The release's version and tag, built in (launcher/src/backend.rs VERSION and own_tag: the tag says which
# line it is on, docs/versioning.md); a launcher branch's build keeps Cargo.toml's.
HORIZON_LAUNCHER_VERSION: ${{ (github.event_name != 'push' || github.ref == 'refs/heads/main') && needs.decide.outputs.version || '' }}
+55
View File
@@ -0,0 +1,55 @@
# The launcher's mod browser
Search Modrinth (and CurseForge, once the launcher has a key) for packs Horizon loads, see how well each one runs,
and install it with its checksum checked. This is item 16 of the roadmap and issue #577. The code is in
`launcher/src/browser.rs` and `launcher/src/browser/`.
## What it offers
Only what Horizon actually loads is offered. Java mod jars (Fabric, NeoForge, Forge) don't run in Horizon
([mods.md](mods.md), [research/java-mod-compat.md](research/java-mod-compat.md)), so they are never searched.
Horizon `.hmod` mods aren't on Modrinth or CurseForge yet (Modrinth has no `horizon` loader).
| Kind | Goes to | How well it runs |
|---|---|---|
| Resource packs | `resourcepacks/` beside `options.txt` | **Works** when made for 26.3 ([resource-packs.md](resource-packs.md) lists what Horizon reads). Older packs are **Partly**: they load with vanilla's compatibility warning |
| Shader packs (Iris, OptiFine) | `shaderpacks/` | **Partly**: translated to WGSL, the full-screen passes draw and the world and shadow passes don't yet ([shader-packs.md](shader-packs.md)). Packs for other loaders (Canvas, core-shader packs) **don't run** and can't be installed |
| Modpacks (`.mrpack`, CurseForge zip) | the Modpacks page's import | **Partly**: Horizon runs the mods it can port, from the player's own downloads ([modpacks.md](modpacks.md)) |
By default a search shows only what runs: resource packs made for 26.3, shader packs for Iris or OptiFine, and every
modpack. **Show everything** lists the rest of the kind too, each marked with how well it runs; what doesn't run is
never offered for install.
## Checks on every download
- The file must come from Modrinth's or CurseForge's file servers (`cdn.modrinth.com`, `edge.forgecdn.net`,
`mediafilez.forgecdn.net`), over HTTPS.
- Its name must be one plain file name (no folders, `..`, hidden names or reserved characters).
- It is written as `.<name>.part`, hashed as it arrives, and renamed into place only when its size and checksum match
what the source lists: SHA-512 on Modrinth, SHA-1 on CurseForge (the strongest hash CurseForge publishes). Anything
else removes the part file and installs nothing.
- A file whose source lists no checksum is refused.
## Sources
**Modrinth.** The public API (`api.modrinth.com/v2`) needs no key. The launcher names itself in its user agent, as
Modrinth asks.
### CurseForge
CurseForge's API (`api.curseforge.com/v1`) needs an API key from its developer console. Ludovic approved CurseForge
for the browser on 2026-10-21; the key is his (agents never sign up for him). Until a key exists the CurseForge source
is off and the browser searches Modrinth only.
To turn it on:
1. Ludovic gets a key at <https://console.curseforge.com/> (sign in, API keys). CurseForge's terms for a launcher
that ships the key apply: the key is built into the binary, so anyone with the binary can read it.
2. He stores it in the 1Password **Agents** vault as an item `CurseForge API`, field `credential`.
3. It goes into the repository secret `HORIZON_CURSEFORGE_API_KEY`
(`~/fleet/op read "op://Agents/CurseForge API/credential" | gh secret set HORIZON_CURSEFORGE_API_KEY`).
The launcher workflow passes it to the build, which builds it in (`option_env!`).
At run time `HORIZON_CURSEFORGE_API_KEY` in the environment overrides the built-in key; empty means none. A file
whose author allows downloads from CurseForge's own site only (no `downloadUrl` in the API) is shown but can't be
installed.
+2 -1
View File
@@ -17,7 +17,8 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
| Runtime | `crates/horizon-mods` | wasmtime 36 LTS, component model |
| Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new / build / run` |
| In the game | `crates/horizon-client/src/game/mods.rs`, Options > Mods | client mods |
| Launcher mod browser, signing, server mods, registries | this page, [Roadmap](#roadmap) | planned |
| Launcher mod browser (Modrinth, CurseForge with a key) | [mod-browser.md](mod-browser.md) | resource packs, shader packs, modpacks |
| `.hmod` index, signing, server mods, registries | this page, [Roadmap](#roadmap) | planned |
## Design goals
+1
View File
@@ -2685,6 +2685,7 @@ dependencies = [
"serde",
"serde_json",
"sha1",
"sha2 0.10.9",
"tar",
"ureq",
"winresource",
+2
View File
@@ -14,6 +14,8 @@ serde = { version = "1", features = ["derive"] }
serde_json = "1"
# Checks the client jar and the version file found in other launchers' folders (sources.rs).
sha1 = "0.10"
# The mod browser checks Modrinth's SHA-512 before a pack reaches the game folder (browser/download.rs).
sha2 = "0.10"
pulldown-cmark = { version = "0.12", default-features = false }
flate2 = "1"
tar = { version = "0.4", default-features = false }
+296
View File
@@ -0,0 +1,296 @@
//! The mod browser's sources: search Modrinth (and CurseForge, once a key exists) for what
//! Horizon loads, say how well each result runs, and download a file only after its checksum
//! matches (docs/mod-browser.md).
//!
//! Only what Horizon actually loads is offered: resource packs (`resourcepacks/`), Java shader
//! packs (`shaderpacks/`, Iris and OptiFine) and modpacks (imported and ported on the Modpacks
//! page). Java mod jars don't run in Horizon (docs/mods.md), so they are never searched.
pub mod curseforge;
pub mod download;
pub mod modrinth;
/// The Minecraft version Horizon plays. A version port updates it with the other `"26.3"` sites
/// (docs/version-ports.md).
pub const GAME: &str = "26.3";
/// What a project is, as far as Horizon is concerned.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Kind {
ResourcePack,
ShaderPack,
Modpack,
}
impl Kind {
pub const ALL: [Kind; 3] = [Kind::ResourcePack, Kind::ShaderPack, Kind::Modpack];
pub fn label(self) -> &'static str {
match self {
Kind::ResourcePack => "Resource packs",
Kind::ShaderPack => "Shader packs",
Kind::Modpack => "Modpacks",
}
}
/// The folder beside `options.txt` the file goes in; a modpack is imported instead.
pub fn folder(self) -> Option<&'static str> {
match self {
Kind::ResourcePack => Some("resourcepacks"),
Kind::ShaderPack => Some("shaderpacks"),
Kind::Modpack => None,
}
}
}
/// Where a project comes from.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum SourceId {
Modrinth,
CurseForge,
}
impl SourceId {
pub fn label(self) -> &'static str {
match self {
SourceId::Modrinth => "Modrinth",
SourceId::CurseForge => "CurseForge",
}
}
}
/// How well a project runs in Horizon.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Support {
/// Made for the version Horizon plays, and Horizon reads everything it uses.
Works,
/// It loads, with the limit said.
Partial(String),
/// It can't run in Horizon: never offered for install.
No(String),
}
impl Support {
pub fn installable(&self) -> bool {
!matches!(self, Support::No(_))
}
pub fn label(&self) -> &'static str {
match self {
Support::Works => "Works",
Support::Partial(_) => "Partly",
Support::No(_) => "Doesn't run",
}
}
pub fn reason(&self) -> Option<&str> {
match self {
Support::Works => None,
Support::Partial(r) | Support::No(r) => Some(r),
}
}
}
/// A search result or a looked-up project.
#[derive(Clone, Debug, PartialEq)]
pub struct Project {
pub source: SourceId,
pub id: String,
pub slug: String,
pub title: String,
pub summary: String,
pub author: String,
pub downloads: u64,
/// The project's page on its source, for the player to read before installing.
pub page: String,
pub icon: Option<String>,
pub license: String,
pub kind: Kind,
/// The Minecraft versions its files list, and the loaders (`iris`, `optifine`, `minecraft`...).
pub game_versions: Vec<String>,
pub loaders: Vec<String>,
}
impl Project {
pub fn support(&self) -> Support {
support(self.kind, &self.game_versions, &self.loaders)
}
}
/// One downloadable file of a version, with the checksums its source publishes.
#[derive(Clone, Debug, PartialEq)]
pub struct FileRef {
pub url: String,
pub name: String,
pub size: u64,
pub sha512: Option<String>,
pub sha1: Option<String>,
pub primary: bool,
}
impl FileRef {
/// The strongest checksum the source gives: what the download is checked against.
pub fn checksum(&self) -> Option<(&'static str, &str)> {
match (&self.sha512, &self.sha1) {
(Some(h), _) => Some(("SHA-512", h)),
(None, Some(h)) => Some(("SHA-1", h)),
(None, None) => None,
}
}
}
/// A version of a project: its files and what it needs.
#[derive(Clone, Debug, PartialEq)]
pub struct Version {
pub id: String,
pub number: String,
pub published: String,
pub game_versions: Vec<String>,
pub loaders: Vec<String>,
pub files: Vec<FileRef>,
/// Required dependencies, as project ids on the same source.
pub required: Vec<String>,
/// Why this version can't be downloaded from here (CurseForge authors can forbid it).
pub blocked: Option<String>,
}
impl Version {
/// The file to install: the primary one, else the first.
pub fn file(&self) -> Option<&FileRef> {
self.files
.iter()
.find(|f| f.primary)
.or_else(|| self.files.first())
}
}
/// A search.
#[derive(Clone, Debug, PartialEq)]
pub struct Query {
pub text: String,
pub kind: Kind,
/// Off: only what runs (made for [`GAME`], Iris or OptiFine shaders). On: everything of the
/// kind, each result marked with how well it runs.
pub everything: bool,
pub offset: usize,
pub limit: usize,
}
impl Query {
pub fn new(text: &str, kind: Kind) -> Self {
Self {
text: text.trim().to_owned(),
kind,
everything: false,
offset: 0,
limit: 20,
}
}
}
/// A place projects come from.
pub trait Source: Send + Sync {
fn id(&self) -> SourceId;
fn search(&self, query: &Query) -> Result<Vec<Project>, String>;
fn project(&self, id: &str) -> Result<Project, String>;
/// Versions, newest first.
fn versions(&self, project: &Project) -> Result<Vec<Version>, String>;
}
/// The sources this launcher can use: Modrinth always, CurseForge when it has an API key.
pub fn sources() -> Vec<Box<dyn Source>> {
let mut all: Vec<Box<dyn Source>> = vec![Box::new(modrinth::Modrinth)];
if let Some(cf) = curseforge::CurseForge::from_env() {
all.push(Box::new(cf));
}
all
}
/// The loaders a Java shader pack may name that Horizon translates.
const SHADER_LOADERS: [&str; 2] = ["iris", "optifine"];
/// How well a project of `kind` made for `game_versions` and `loaders` runs in Horizon.
pub fn support(kind: Kind, game_versions: &[String], loaders: &[String]) -> Support {
match kind {
Kind::ResourcePack => {
if game_versions.iter().any(|v| v == GAME) {
Support::Works
} else if let Some(newest) = newest_release(game_versions) {
Support::Partial(format!(
"Made for {newest}: it loads with vanilla's compatibility warning, and \
what changed since may look wrong."
))
} else {
Support::Partial("Lists no Minecraft version.".into())
}
}
Kind::ShaderPack => {
if loaders.iter().any(|l| SHADER_LOADERS.contains(&l.as_str())) {
Support::Partial(
"Java shader packs are translated: their full-screen passes draw, the world \
and shadow passes don't yet (BSL and Complementary tested)."
.into(),
)
} else {
let named = loaders.first().map(String::as_str).unwrap_or("unknown");
Support::No(format!(
"A shader pack for {named}: Horizon runs Iris and OptiFine packs only."
))
}
}
Kind::Modpack => Support::Partial(
"Imported on the Modpacks page: Horizon runs the mods it can port, from your own \
downloads."
.into(),
),
}
}
/// The newest plain release (`1.21.4`, `26.2`) in a list of Minecraft versions.
fn newest_release(versions: &[String]) -> Option<&str> {
versions
.iter()
.filter(|v| {
v.split('.')
.all(|p| !p.is_empty() && p.bytes().all(|b| b.is_ascii_digit()))
})
.max_by_key(|v| {
v.split('.')
.map(|p| p.parse::<u32>().unwrap_or(0))
.collect::<Vec<_>>()
})
.map(String::as_str)
}
/// The version to install: the newest one that runs, or with `everything` the newest at all.
/// `versions` is newest first, as [`Source::versions`] gives them.
pub fn pick(kind: Kind, versions: &[Version], everything: bool) -> Option<&Version> {
let mut usable = versions
.iter()
.filter(|v| v.blocked.is_none() && v.file().is_some());
let runs = |v: &&Version| match support(kind, &v.game_versions, &v.loaders) {
Support::Works => true,
// A modpack's version is for its own Minecraft; any shader pack Horizon translates.
Support::Partial(_) => kind != Kind::ResourcePack,
Support::No(_) => false,
};
if let Some(v) = usable.clone().find(runs) {
return Some(v);
}
usable.find(|v| everything && support(kind, &v.game_versions, &v.loaders).installable())
}
/// A file name from a source, kept only when it is one plain name: no folders, no `..`, no
/// hidden file, nothing a file system would read as something else.
pub fn safe_name(name: &str) -> Option<&str> {
let ok = !name.is_empty()
&& name.len() <= 200
&& !name.starts_with('.')
&& !name.ends_with(['.', ' '])
&& name.chars().all(|c| {
!c.is_control() && !matches!(c, '/' | '\\' | ':' | '*' | '?' | '"' | '<' | '>' | '|')
});
ok.then_some(name)
}
#[cfg(test)]
mod tests;
+237
View File
@@ -0,0 +1,237 @@
//! CurseForge's API (api.curseforge.com/v1). It needs a key from CurseForge's developer console,
//! so this source stays off until one is given (docs/mod-browser.md#curseforge):
//! `HORIZON_CURSEFORGE_API_KEY` in the environment, else the same variable when the launcher was
//! built (the release workflow passes the repository secret). Files carry SHA-1 and MD5; the
//! download is checked against the SHA-1.
use super::{modrinth::encode, FileRef, Kind, Project, Query, Source, SourceId, Version, GAME};
use serde_json::Value;
const API: &str = "https://api.curseforge.com/v1";
/// Minecraft's game id on CurseForge.
const MINECRAFT: u64 = 432;
/// `HashAlgo` in CurseForge's schema.
const SHA1: u64 = 1;
/// `FileRelationType::RequiredDependency`.
const REQUIRED: u64 = 3;
pub struct CurseForge {
key: String,
}
/// CurseForge's class id for a kind.
fn class(kind: Kind) -> u64 {
match kind {
Kind::ResourcePack => 12,
Kind::ShaderPack => 6552,
Kind::Modpack => 4471,
}
}
fn kind_of(class_id: u64) -> Option<Kind> {
Kind::ALL.into_iter().find(|k| class(*k) == class_id)
}
/// The key: the environment's, else the one built in. Empty counts as none.
pub(super) fn key(runtime: Option<String>, built: Option<&str>) -> Option<String> {
runtime
.or_else(|| built.map(str::to_owned))
.map(|k| k.trim().to_owned())
.filter(|k| !k.is_empty())
}
impl CurseForge {
/// The source, when a key exists; else None and CurseForge isn't offered.
pub fn from_env() -> Option<Self> {
key(
std::env::var("HORIZON_CURSEFORGE_API_KEY").ok(),
option_env!("HORIZON_CURSEFORGE_API_KEY"),
)
.map(|key| Self { key })
}
fn get(&self, url: &str) -> Result<Value, String> {
let response = super::download::agent()
.get(url)
.set("x-api-key", &self.key)
.set("Accept", "application/json")
.call()
.map_err(|e| match e {
ureq::Error::Status(403, _) => "CurseForge refused the launcher's API key.".into(),
ureq::Error::Status(code, _) => format!("CurseForge answered {code}."),
ureq::Error::Transport(t) => format!("No connection to CurseForge: {t}"),
})?;
response
.into_json()
.map_err(|e| format!("CurseForge's answer wasn't readable: {e}"))
}
}
pub(super) fn search_url(query: &Query) -> String {
let mut url = format!(
"{API}/mods/search?gameId={MINECRAFT}&classId={}&sortField=2&sortOrder=desc&index={}&pageSize={}",
class(query.kind),
query.offset,
query.limit.clamp(1, 50),
);
if !query.everything && query.kind == Kind::ResourcePack {
url.push_str(&format!("&gameVersion={GAME}"));
}
if !query.text.is_empty() {
url.push_str("&searchFilter=");
url.push_str(&encode(&query.text));
}
url
}
/// CurseForge mixes Minecraft versions and loader names (`Iris`, `OptiFine`, `NeoForge`) in one
/// list: digits first is a version, the rest are loaders, in lowercase as Modrinth names them.
fn split_versions(list: &Value) -> (Vec<String>, Vec<String>) {
let mut versions = Vec::new();
let mut loaders = Vec::new();
for v in list
.as_array()
.into_iter()
.flatten()
.filter_map(Value::as_str)
{
if v.starts_with(|c: char| c.is_ascii_digit()) {
versions.push(v.to_owned());
} else {
loaders.push(v.to_ascii_lowercase());
}
}
versions.sort();
versions.dedup();
loaders.sort();
loaders.dedup();
(versions, loaders)
}
pub(super) fn parse_mod(m: &Value) -> Option<Project> {
let kind = kind_of(m["classId"].as_u64()?)?;
let latest = Value::Array(
m["latestFilesIndexes"]
.as_array()
.into_iter()
.flatten()
.filter_map(|i| i["gameVersion"].as_str())
.map(|v| Value::String(v.to_owned()))
.collect(),
);
let (game_versions, mut loaders) = split_versions(&latest);
// A shader pack's files name its loader; the index often doesn't.
if kind == Kind::ShaderPack && loaders.is_empty() {
let (_, own) = split_versions(&Value::Array(
m["latestFiles"]
.as_array()
.into_iter()
.flatten()
.flat_map(|f| f["gameVersions"].as_array().cloned().unwrap_or_default())
.collect(),
));
loaders = own;
}
Some(Project {
source: SourceId::CurseForge,
id: m["id"].as_u64()?.to_string(),
slug: m["slug"].as_str().unwrap_or_default().to_owned(),
title: m["name"].as_str().unwrap_or_default().to_owned(),
summary: m["summary"].as_str().unwrap_or_default().to_owned(),
author: m["authors"][0]["name"]
.as_str()
.unwrap_or_default()
.to_owned(),
downloads: m["downloadCount"].as_f64().unwrap_or(0.) as u64,
page: m["links"]["websiteUrl"]
.as_str()
.unwrap_or_default()
.to_owned(),
icon: m["logo"]["thumbnailUrl"].as_str().map(str::to_owned),
// CurseForge's API doesn't say; the project page does.
license: String::new(),
kind,
game_versions,
loaders,
})
}
pub(super) fn parse_file(f: &Value) -> Option<Version> {
let (game_versions, loaders) = split_versions(&f["gameVersions"]);
let name = f["fileName"].as_str()?.to_owned();
let sha1 = f["hashes"]
.as_array()
.into_iter()
.flatten()
.find(|h| h["algo"].as_u64() == Some(SHA1))
.and_then(|h| h["value"].as_str())
.map(str::to_ascii_lowercase);
let url = f["downloadUrl"].as_str().filter(|u| !u.is_empty());
let files = url
.map(|url| {
vec![FileRef {
url: url.to_owned(),
name: name.clone(),
size: f["fileLength"].as_u64().unwrap_or(0),
sha512: None,
sha1,
primary: true,
}]
})
.unwrap_or_default();
Some(Version {
id: f["id"].as_u64()?.to_string(),
number: f["displayName"].as_str().unwrap_or(&name).to_owned(),
published: f["fileDate"].as_str().unwrap_or_default().to_owned(),
game_versions,
loaders,
files,
required: f["dependencies"]
.as_array()
.into_iter()
.flatten()
.filter(|d| d["relationType"].as_u64() == Some(REQUIRED))
.filter_map(|d| d["modId"].as_u64().map(|id| id.to_string()))
.collect(),
blocked: url
.is_none()
.then(|| "Its author allows downloads from CurseForge's own site only.".to_owned()),
})
}
impl Source for CurseForge {
fn id(&self) -> SourceId {
SourceId::CurseForge
}
fn search(&self, query: &Query) -> Result<Vec<Project>, String> {
let found = self.get(&search_url(query))?;
Ok(found["data"]
.as_array()
.into_iter()
.flatten()
.filter_map(parse_mod)
.collect())
}
fn project(&self, id: &str) -> Result<Project, String> {
let m = self.get(&format!("{API}/mods/{}", encode(id)))?;
parse_mod(&m["data"])
.ok_or_else(|| format!("CurseForge: {id} is not a pack Horizon loads."))
}
fn versions(&self, project: &Project) -> Result<Vec<Version>, String> {
let found = self.get(&format!(
"{API}/mods/{}/files?pageSize=50",
encode(&project.id)
))?;
let mut all: Vec<Version> = found["data"]
.as_array()
.into_iter()
.flatten()
.filter(|f| f["isAvailable"].as_bool() != Some(false))
.filter_map(parse_file)
.collect();
all.sort_by(|a, b| b.published.cmp(&a.published));
Ok(all)
}
}
+144
View File
@@ -0,0 +1,144 @@
//! Downloads that reach the game folder only when their checksum matches the source's.
use super::{safe_name, FileRef};
use sha1::Sha1;
use sha2::{Digest, Sha512};
use std::fs;
use std::io::{Read, Write};
use std::path::{Path, PathBuf};
/// Hosts a file may come from: Modrinth's and CurseForge's file servers.
const HOSTS: [&str; 3] = [
"https://cdn.modrinth.com/",
"https://edge.forgecdn.net/",
"https://mediafilez.forgecdn.net/",
];
/// Bigger than any pack these sources serve (Modrinth caps uploads at 500 MiB).
const MAX: u64 = 1 << 30;
/// The HTTP agent the sources share. Modrinth asks for a user agent that names the project.
pub(super) fn agent() -> ureq::Agent {
ureq::AgentBuilder::new()
.user_agent(&format!(
"ludovic111/horizon horizon-launcher/{} (github.com/ludovic111/horizon)",
crate::backend::VERSION
))
.timeout_connect(std::time::Duration::from_secs(15))
.timeout_read(std::time::Duration::from_secs(60))
.build()
}
/// Why a file can't be downloaded at all, before any byte is read.
pub fn refuse(file: &FileRef) -> Option<String> {
if !HOSTS.iter().any(|h| file.url.starts_with(h)) {
return Some(format!(
"{} isn't on Modrinth's or CurseForge's file servers.",
file.url
));
}
if safe_name(&file.name).is_none() {
return Some(format!("{:?} isn't a plain file name.", file.name));
}
if file.checksum().is_none() {
return Some("Its source gives no checksum, so it can't be checked.".into());
}
if file.size > MAX {
return Some("It is larger than any pack should be.".into());
}
None
}
/// Hashes as they are written: the strongest one the file lists.
enum Hasher {
Sha512(Sha512),
Sha1(Sha1),
}
impl Hasher {
fn for_file(file: &FileRef) -> Self {
if file.sha512.is_some() {
Hasher::Sha512(Sha512::new())
} else {
Hasher::Sha1(Sha1::new())
}
}
fn update(&mut self, bytes: &[u8]) {
match self {
Hasher::Sha512(h) => h.update(bytes),
Hasher::Sha1(h) => h.update(bytes),
}
}
fn hex(self) -> String {
let bytes: Vec<u8> = match self {
Hasher::Sha512(h) => h.finalize().to_vec(),
Hasher::Sha1(h) => h.finalize().to_vec(),
};
bytes.iter().map(|b| format!("{b:02x}")).collect()
}
}
/// Copies `reader` into `<folder>/<file.name>`, hashing on the way, and keeps it only when the
/// size and checksum match: until then it is `.<name>.part`, removed on any failure.
/// `progress` gets the fraction done.
pub fn save(
file: &FileRef,
mut reader: impl Read,
folder: &Path,
progress: &dyn Fn(f32),
) -> Result<PathBuf, String> {
if let Some(why) = refuse(file) {
return Err(why);
}
let (algo, want) = file.checksum().expect("refuse checks for one");
fs::create_dir_all(folder).map_err(|e| format!("{}: {e}", folder.display()))?;
let target = folder.join(&file.name);
let part = folder.join(format!(".{}.part", file.name));
let result = (|| {
let mut out = fs::File::create(&part).map_err(|e| format!("{}: {e}", part.display()))?;
let mut hasher = Hasher::for_file(file);
let (mut done, mut buf) = (0u64, vec![0u8; 1 << 16]);
loop {
let n = reader
.read(&mut buf)
.map_err(|e| format!("Download interrupted: {e}"))?;
if n == 0 {
break;
}
done += n as u64;
if done > MAX || (file.size > 0 && done > file.size) {
return Err("The download is larger than its source says.".to_string());
}
hasher.update(&buf[..n]);
out.write_all(&buf[..n]).map_err(|e| e.to_string())?;
progress(done as f32 / file.size.max(1) as f32);
}
if file.size > 0 && done != file.size {
return Err(format!("Got {done} bytes of {}.", file.size));
}
let got = hasher.hex();
if !got.eq_ignore_ascii_case(want) {
return Err(format!(
"The {algo} checksum doesn't match: the file isn't the one its source lists. \
Nothing was installed."
));
}
out.sync_all().map_err(|e| e.to_string())?;
drop(out);
fs::rename(&part, &target).map_err(|e| format!("{}: {e}", target.display()))
})();
if result.is_err() {
let _ = fs::remove_file(&part);
}
result.map(|()| target)
}
/// Downloads `file` into `folder`, checked as [`save`] does.
pub fn fetch(file: &FileRef, folder: &Path, progress: &dyn Fn(f32)) -> Result<PathBuf, String> {
if let Some(why) = refuse(file) {
return Err(why);
}
let response = agent().get(&file.url).call().map_err(|e| match e {
ureq::Error::Status(code, _) => format!("{} answered {code}.", file.url),
ureq::Error::Transport(t) => format!("No connection: {t}"),
})?;
save(file, response.into_reader(), folder, progress)
}
+214
View File
@@ -0,0 +1,214 @@
//! Modrinth's public API (api.modrinth.com/v2): no key, files with SHA-512 and SHA-1.
use super::{FileRef, Kind, Project, Query, Source, SourceId, Version, GAME};
use serde_json::Value;
const API: &str = "https://api.modrinth.com/v2";
const SITE: &str = "https://modrinth.com";
pub struct Modrinth;
/// Modrinth's project type for a kind.
fn project_type(kind: Kind) -> &'static str {
match kind {
Kind::ResourcePack => "resourcepack",
Kind::ShaderPack => "shader",
Kind::Modpack => "modpack",
}
}
fn kind_of(project_type: &str) -> Option<Kind> {
Kind::ALL
.into_iter()
.find(|k| self::project_type(*k) == project_type)
}
/// The search's facets (AND of ORs): the kind, and unless `everything` what runs.
pub(super) fn facets(query: &Query) -> String {
let mut all = vec![vec![format!("project_type:{}", project_type(query.kind))]];
if !query.everything {
match query.kind {
Kind::ResourcePack => all.push(vec![format!("versions:{GAME}")]),
Kind::ShaderPack => {
all.push(vec!["categories:iris".into(), "categories:optifine".into()])
}
Kind::Modpack => {}
}
}
serde_json::to_string(&all).unwrap_or_default()
}
pub(super) fn search_url(query: &Query) -> String {
let mut url = format!(
"{API}/search?facets={}&index={}&offset={}&limit={}",
encode(&facets(query)),
if query.text.is_empty() {
"downloads"
} else {
"relevance"
},
query.offset,
query.limit.clamp(1, 100),
);
if !query.text.is_empty() {
url.push_str("&query=");
url.push_str(&encode(&query.text));
}
url
}
fn strings(v: &Value) -> Vec<String> {
v.as_array()
.into_iter()
.flatten()
.filter_map(|s| s.as_str().map(str::to_owned))
.collect()
}
fn text(v: &Value) -> String {
v.as_str().unwrap_or_default().to_owned()
}
/// A search hit. Its `categories` hold the loaders too; `versions` its Minecraft versions.
pub(super) fn parse_hit(hit: &Value) -> Option<Project> {
let kind = kind_of(hit["project_type"].as_str()?)?;
let slug = text(&hit["slug"]);
Some(Project {
source: SourceId::Modrinth,
id: hit["project_id"].as_str()?.to_owned(),
page: format!("{SITE}/{}/{slug}", project_type(kind)),
slug,
title: text(&hit["title"]),
summary: text(&hit["description"]),
author: text(&hit["author"]),
downloads: hit["downloads"].as_u64().unwrap_or(0),
icon: hit["icon_url"]
.as_str()
.filter(|u| !u.is_empty())
.map(str::to_owned),
license: text(&hit["license"]),
kind,
game_versions: strings(&hit["versions"]),
loaders: strings(&hit["categories"]),
})
}
/// `GET /project/{id}`: the fields differ from a search hit's.
pub(super) fn parse_project(p: &Value) -> Option<Project> {
let kind = kind_of(p["project_type"].as_str()?)?;
let slug = text(&p["slug"]);
Some(Project {
source: SourceId::Modrinth,
id: p["id"].as_str()?.to_owned(),
page: format!("{SITE}/{}/{slug}", project_type(kind)),
slug,
title: text(&p["title"]),
summary: text(&p["description"]),
author: String::new(),
downloads: p["downloads"].as_u64().unwrap_or(0),
icon: p["icon_url"]
.as_str()
.filter(|u| !u.is_empty())
.map(str::to_owned),
license: text(&p["license"]["id"]),
kind,
game_versions: strings(&p["game_versions"]),
loaders: strings(&p["loaders"]),
})
}
pub(super) fn parse_version(v: &Value) -> Option<Version> {
let files = v["files"]
.as_array()?
.iter()
.filter_map(|f| {
Some(FileRef {
url: f["url"].as_str()?.to_owned(),
name: f["filename"].as_str()?.to_owned(),
size: f["size"].as_u64().unwrap_or(0),
sha512: f["hashes"]["sha512"].as_str().map(str::to_ascii_lowercase),
sha1: f["hashes"]["sha1"].as_str().map(str::to_ascii_lowercase),
primary: f["primary"].as_bool().unwrap_or(false),
})
})
.collect();
let required = v["dependencies"]
.as_array()
.into_iter()
.flatten()
.filter(|d| d["dependency_type"] == "required")
.filter_map(|d| d["project_id"].as_str().map(str::to_owned))
.collect();
Some(Version {
id: v["id"].as_str()?.to_owned(),
number: text(&v["version_number"]),
published: text(&v["date_published"]),
game_versions: strings(&v["game_versions"]),
loaders: strings(&v["loaders"]),
files,
required,
blocked: None,
})
}
impl Source for Modrinth {
fn id(&self) -> SourceId {
SourceId::Modrinth
}
fn search(&self, query: &Query) -> Result<Vec<Project>, String> {
let found = get(&search_url(query))?;
Ok(found["hits"]
.as_array()
.into_iter()
.flatten()
.filter_map(parse_hit)
.collect())
}
fn project(&self, id: &str) -> Result<Project, String> {
let p = get(&format!("{API}/project/{}", encode(id)))?;
parse_project(&p).ok_or_else(|| format!("Modrinth: {id} is not a pack Horizon loads."))
}
fn versions(&self, project: &Project) -> Result<Vec<Version>, String> {
let found = get(&format!("{API}/project/{}/version", encode(&project.id)))?;
let mut all: Vec<Version> = found
.as_array()
.into_iter()
.flatten()
.filter(|v| v["status"].as_str().is_none_or(|s| s == "listed"))
.filter_map(parse_version)
.collect();
// Modrinth lists newest first already; ISO dates sort as text.
all.sort_by(|a, b| b.published.cmp(&a.published));
Ok(all)
}
}
fn get(url: &str) -> Result<Value, String> {
let response = super::download::agent()
.get(url)
.call()
.map_err(|e| match e {
ureq::Error::Status(429, _) => {
"Modrinth asks to slow down: try again in a minute.".into()
}
ureq::Error::Status(code, _) => format!("Modrinth answered {code}."),
ureq::Error::Transport(t) => format!("No connection to Modrinth: {t}"),
})?;
response
.into_json()
.map_err(|e| format!("Modrinth's answer wasn't readable: {e}"))
}
/// Percent-encoding for a query value or a path segment.
pub(super) fn encode(s: &str) -> String {
s.bytes()
.map(|b| match b {
b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
(b as char).to_string()
}
_ => format!("%{b:02X}"),
})
.collect()
}
+355
View File
@@ -0,0 +1,355 @@
use super::*;
use serde_json::json;
use sha2::Digest;
fn v(list: &[&str]) -> Vec<String> {
list.iter().map(|s| s.to_string()).collect()
}
fn version(id: &str, games: &[&str], loaders: &[&str]) -> Version {
Version {
id: id.into(),
number: id.into(),
published: String::new(),
game_versions: v(games),
loaders: v(loaders),
files: vec![FileRef {
url: format!("https://cdn.modrinth.com/data/x/versions/{id}/{id}.zip"),
name: format!("{id}.zip"),
size: 3,
sha512: Some("ab".into()),
sha1: None,
primary: true,
}],
required: Vec::new(),
blocked: None,
}
}
#[test]
fn support_by_kind() {
assert_eq!(
support(
Kind::ResourcePack,
&v(&["1.21.4", GAME]),
&v(&["minecraft"])
),
Support::Works
);
let old = support(
Kind::ResourcePack,
&v(&["1.20.1", "1.21.10", "1.21.9", "26.4-snapshot-1"]),
&[],
);
assert_eq!(old.label(), "Partly");
assert!(
old.reason().unwrap().starts_with("Made for 1.21.10:"),
"{old:?}"
);
assert!(support(Kind::ShaderPack, &[], &v(&["iris"])).installable());
assert!(support(Kind::ShaderPack, &[], &v(&["optifine"])).installable());
let canvas = support(Kind::ShaderPack, &[], &v(&["canvas"]));
assert!(!canvas.installable());
assert!(canvas.reason().unwrap().contains("canvas"));
assert!(!support(Kind::ShaderPack, &[], &[]).installable());
assert!(support(Kind::Modpack, &v(&["1.21.1"]), &v(&["neoforge"])).installable());
}
#[test]
fn picks_the_newest_version_that_runs() {
let versions = [
version("snapshot", &["26.4-snapshot-5"], &["minecraft"]),
version("now", &["26.2", GAME], &["minecraft"]),
version("old", &["1.21.1"], &["minecraft"]),
];
assert_eq!(
pick(Kind::ResourcePack, &versions, false).unwrap().id,
"now"
);
let old = [version("old", &["1.21.1"], &["minecraft"])];
assert!(pick(Kind::ResourcePack, &old, false).is_none());
assert_eq!(pick(Kind::ResourcePack, &old, true).unwrap().id, "old");
let shaders = [
version("canvas", &[GAME], &["canvas"]),
version("iris", &["1.21.1"], &["iris"]),
];
assert_eq!(pick(Kind::ShaderPack, &shaders, false).unwrap().id, "iris");
let only_canvas = [version("canvas", &[GAME], &["canvas"])];
assert!(pick(Kind::ShaderPack, &only_canvas, true).is_none());
let mut blocked = version("blocked", &[GAME], &["minecraft"]);
blocked.blocked = Some("no".into());
let mut empty = version("empty", &[GAME], &["minecraft"]);
empty.files.clear();
assert!(pick(Kind::ResourcePack, &[blocked, empty], true).is_none());
}
#[test]
fn file_names_must_be_plain() {
for good in [
"Faithful 32x.zip",
"FreshAnimations_v1.11.1_26.1+.zip",
"BSL_v10.zip",
] {
assert_eq!(safe_name(good), Some(good));
}
for bad in [
"",
"../x.zip",
"a/b.zip",
"a\\b.zip",
".hidden.zip",
"c:x.zip",
"x.zip.",
"x\n.zip",
] {
assert_eq!(safe_name(bad), None, "{bad:?}");
}
}
#[test]
fn modrinth_search_asks_for_what_runs() {
let q = Query::new(" faithful ", Kind::ResourcePack);
assert_eq!(q.text, "faithful");
assert_eq!(
modrinth::facets(&q),
r#"[["project_type:resourcepack"],["versions:26.3"]]"#
);
let url = modrinth::search_url(&q);
assert!(url.starts_with("https://api.modrinth.com/v2/search?facets=%5B%5B%22project_type"));
assert!(
url.contains("&index=relevance&") && url.ends_with("&query=faithful"),
"{url}"
);
let shaders = Query::new("", Kind::ShaderPack);
assert_eq!(
modrinth::facets(&shaders),
r#"[["project_type:shader"],["categories:iris","categories:optifine"]]"#
);
assert!(modrinth::search_url(&shaders).contains("&index=downloads&"));
let everything = Query {
everything: true,
..Query::new("", Kind::ResourcePack)
};
assert_eq!(
modrinth::facets(&everything),
r#"[["project_type:resourcepack"]]"#
);
assert_eq!(
modrinth::facets(&Query::new("", Kind::Modpack)),
r#"[["project_type:modpack"]]"#
);
}
#[test]
fn modrinth_answers() {
let hit = json!({
"project_id": "50dA9Sha", "project_type": "resourcepack", "slug": "fresh-animations",
"title": "Fresh Animations", "description": "Animated entities.", "author": "FreshLX",
"downloads": 51404735, "icon_url": "https://cdn.modrinth.com/data/50dA9Sha/icon.webp",
"license": "LicenseRef-See-Terms", "versions": ["1.21.11", "26.3"],
"categories": ["16x", "minecraft"]
});
let p = modrinth::parse_hit(&hit).unwrap();
assert_eq!(p.id, "50dA9Sha");
assert_eq!(p.kind, Kind::ResourcePack);
assert_eq!(p.page, "https://modrinth.com/resourcepack/fresh-animations");
assert_eq!(p.support(), Support::Works);
assert_eq!(p.downloads, 51404735);
// A Java mod is never a result.
let jar = json!({"project_id": "AANobbMI", "project_type": "mod", "slug": "sodium"});
assert!(modrinth::parse_hit(&jar).is_none());
let project = json!({
"id": "HVnmMxH1", "project_type": "shader", "slug": "complementary-reimagined",
"title": "Complementary Shaders - Reimagined", "description": "d",
"license": {"id": "LicenseRef-Complementary", "name": ""},
"game_versions": ["1.21.1"], "loaders": ["iris", "optifine"]
});
let p = modrinth::parse_project(&project).unwrap();
assert_eq!(p.kind, Kind::ShaderPack);
assert_eq!(p.license, "LicenseRef-Complementary");
assert_eq!(
p.page,
"https://modrinth.com/shader/complementary-reimagined"
);
assert!(p.support().installable());
let version = json!({
"id": "tvGVYMD4", "version_number": "1.11.1", "date_published": "2026-10-20T02:23:13Z",
"game_versions": ["26.2", "26.3"], "loaders": ["minecraft"],
"dependencies": [
{"project_id": "need", "dependency_type": "required"},
{"project_id": "maybe", "dependency_type": "optional"},
{"version_id": "x", "project_id": null, "dependency_type": "required"}
],
"files": [
{"hashes": {"sha512": "AB12", "sha1": "cd34"}, "url": "https://cdn.modrinth.com/data/a/b.zip",
"filename": "b.zip", "primary": false, "size": 10},
{"hashes": {"sha512": "ef56", "sha1": "0789"}, "url": "https://cdn.modrinth.com/data/a/c.zip",
"filename": "c.zip", "primary": true, "size": 20}
]
});
let ver = modrinth::parse_version(&version).unwrap();
assert_eq!(ver.required, ["need"]);
assert_eq!(ver.files[0].sha512.as_deref(), Some("ab12"));
let file = ver.file().unwrap();
assert_eq!(file.name, "c.zip");
assert_eq!(file.checksum(), Some(("SHA-512", "ef56")));
}
#[test]
fn curseforge_stays_off_without_a_key() {
assert_eq!(curseforge::key(None, None), None);
assert_eq!(curseforge::key(Some(" ".into()), None), None);
assert_eq!(curseforge::key(None, Some("")), None);
assert_eq!(
curseforge::key(None, Some("built")).as_deref(),
Some("built")
);
assert_eq!(
curseforge::key(Some("env ".into()), Some("built")).as_deref(),
Some("env")
);
}
#[test]
fn curseforge_answers() {
let q = Query::new("bsl", Kind::ShaderPack);
let url = curseforge::search_url(&q);
assert!(url.contains("gameId=432&classId=6552&"), "{url}");
assert!(
!url.contains("gameVersion=") && url.ends_with("&searchFilter=bsl"),
"{url}"
);
assert!(
curseforge::search_url(&Query::new("", Kind::ResourcePack)).contains("&gameVersion=26.3")
);
let m = json!({
"id": 228756, "classId": 6552, "slug": "bsl-shaders", "name": "BSL Shaders",
"summary": "s", "authors": [{"name": "CaptTatsu"}], "downloadCount": 1.5e7,
"links": {"websiteUrl": "https://www.curseforge.com/minecraft/shaders/bsl-shaders"},
"logo": {"thumbnailUrl": "https://media.forgecdn.net/avatars/thumbnails/x.png"},
"latestFilesIndexes": [{"gameVersion": "1.21.1"}],
"latestFiles": [{"gameVersions": ["1.21.1", "Iris", "OptiFine"]}]
});
let p = curseforge::parse_mod(&m).unwrap();
assert_eq!(
(p.source, p.id.as_str(), p.kind),
(SourceId::CurseForge, "228756", Kind::ShaderPack)
);
assert_eq!(p.loaders, ["iris", "optifine"]);
assert_eq!(p.author, "CaptTatsu");
assert!(p.support().installable());
assert!(curseforge::parse_mod(&json!({"id": 1, "classId": 6})).is_none());
let file = json!({
"id": 5000, "displayName": "BSL v10", "fileName": "BSL_v10.zip", "fileLength": 300,
"fileDate": "2026-01-01T00:00:00Z", "downloadUrl": "https://edge.forgecdn.net/files/5/0/BSL_v10.zip",
"gameVersions": ["1.21.1", "Iris"],
"hashes": [{"value": "D41D8CD9", "algo": 2}, {"value": "DA39A3EE", "algo": 1}],
"dependencies": [{"modId": 7, "relationType": 3}, {"modId": 8, "relationType": 2}]
});
let ver = curseforge::parse_file(&file).unwrap();
assert_eq!(ver.required, ["7"]);
assert_eq!(ver.loaders, ["iris"]);
assert_eq!(ver.file().unwrap().checksum(), Some(("SHA-1", "da39a3ee")));
assert!(ver.blocked.is_none());
let mut closed = file.clone();
closed["downloadUrl"] = serde_json::Value::Null;
let ver = curseforge::parse_file(&closed).unwrap();
assert!(ver.files.is_empty() && ver.blocked.is_some());
}
fn scratch(name: &str) -> std::path::PathBuf {
let dir = std::env::temp_dir().join(format!("horizon-browser-{name}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
dir
}
fn hex(bytes: &[u8]) -> String {
bytes.iter().map(|b| format!("{b:02x}")).collect()
}
fn file_for(body: &[u8], sha512: bool) -> FileRef {
FileRef {
url: "https://cdn.modrinth.com/data/a/versions/b/pack.zip".into(),
name: "pack.zip".into(),
size: body.len() as u64,
sha512: sha512.then(|| hex(&sha2::Sha512::digest(body))),
sha1: (!sha512).then(|| hex(&sha1::Sha1::digest(body))),
primary: true,
}
}
#[test]
fn a_download_is_kept_only_when_its_checksum_matches() {
let dir = scratch("save");
let body = b"a resource pack";
for strong in [true, false] {
let file = file_for(body, strong);
let path = download::save(&file, &body[..], &dir, &|_| {}).unwrap();
assert_eq!(std::fs::read(&path).unwrap(), body);
std::fs::remove_file(path).unwrap();
}
// Another file than the one listed: refused, and nothing is left behind.
let file = file_for(body, true);
let other = b"a resource paCk";
let e = download::save(&file, &other[..], &dir, &|_| {}).unwrap_err();
assert!(e.contains("SHA-512 checksum doesn't match"), "{e}");
let short = download::save(&file, &body[..4], &dir, &|_| {}).unwrap_err();
assert!(short.starts_with("Got 4 bytes"), "{short}");
let long = download::save(&file, &b"a resource pack and more"[..], &dir, &|_| {}).unwrap_err();
assert!(long.contains("larger"), "{long}");
assert_eq!(std::fs::read_dir(&dir).unwrap().count(), 0);
std::fs::remove_dir_all(&dir).unwrap();
}
#[test]
fn downloads_refused_before_any_byte() {
let body = b"x";
let mut file = file_for(body, true);
file.url = "https://example.com/pack.zip".into();
assert!(download::refuse(&file).unwrap().contains("file servers"));
let mut file = file_for(body, true);
file.url = "http://cdn.modrinth.com/data/a/pack.zip".into();
assert!(download::refuse(&file).is_some());
let mut file = file_for(body, true);
file.name = "../../options.txt".into();
assert!(download::refuse(&file).unwrap().contains("plain file name"));
let mut file = file_for(body, true);
file.sha512 = None;
assert!(download::refuse(&file).unwrap().contains("no checksum"));
let mut file = file_for(body, false);
file.url = "https://edge.forgecdn.net/files/1/2/pack.zip".into();
assert_eq!(download::refuse(&file), None);
}
/// Against the real Modrinth: `cargo test --lib browser::tests::live -- --ignored`.
#[test]
#[ignore = "needs the network"]
fn live_modrinth_search_pick_and_download() {
let source = modrinth::Modrinth;
for kind in Kind::ALL {
let found = source.search(&Query::new("", kind)).unwrap();
assert!(!found.is_empty(), "{kind:?}");
assert!(found
.iter()
.all(|p| p.kind == kind && p.support().installable()));
}
let packs = source
.search(&Query::new("fresh animations", Kind::ResourcePack))
.unwrap();
let p = packs.iter().find(|p| p.slug == "fresh-animations").unwrap();
assert_eq!(p.support(), Support::Works);
let versions = source.versions(p).unwrap();
let chosen = pick(p.kind, &versions, false).unwrap();
assert!(chosen.game_versions.iter().any(|g| g == GAME));
let dir = scratch("live");
let path = download::fetch(chosen.file().unwrap(), &dir, &|_| {}).unwrap();
assert!(path.is_file());
std::fs::remove_dir_all(&dir).unwrap();
assert_eq!(source.project(&p.id).unwrap().slug, p.slug);
}
+1
View File
@@ -1,6 +1,7 @@
//! The launcher's core, shared by the GUI, the CLI and the MCP server.
pub mod account;
pub mod backend;
pub mod browser;
pub mod desktop;
pub mod heads;
pub mod modpacks;