feat(m193): 下载并发/重试/gh-proxy 真接进引擎（schema 与引擎同源常量）

- download.concurrency / download.retry_limit 以前引擎侧零消费者（恒用 EngineConfig::default() 的 64，而 schema 说 8）。现在默认值与硬上限收成 download/config.rs 的常量，schema、EngineConfig::default()、Semaphore 容量三处同源；宿主把三个键翻译成 DownloadTuning 后经 shared::set_tuning（按数据根）灌进装配点，改了设置下一次取引擎就生效。 - download.gh_proxy 三态（留空=跟随内置默认 / off=关 / 前缀=覆盖）下沉到 shared::build，所有走共享引擎的下载路径（内容库/版本清单/字体/安装）一致。 - 删掉 MirrorTable::set_gh_proxy 与 default_gh_proxy 两个改了没用的入口。 - 下载设置页把三条假演示值换成说语义的中文行（含三态说明与 1~64 硬上限）。 - 守卫：探针读 Semaphore 真实许可数（不是读配置），每条配变异证明。 - docs/download-settings.md 记下取证表（另四个键仍零消费，已立 finding）。
2026-11-09 05:24:11 +08:00
1 parent 98262d3835
commit e8544b19a7
@@ -1,17 +1,51 @@
 //! 引擎配置：设置层（core::setting）直接映射到这里。
+//!
+//! # 出厂默认值与设置 schema 的唯一来源（M193）
+//!
+//! 四个常量是**唯一**写死数字的地方：schema 的默认值/范围、`EngineConfig::default()`、
+//! `Semaphore` 容量全从它们取。此前 schema 写 8、引擎写 64 ⇒ 调并发完全无效（引擎侧零消费者）。
+//! 收成常量后「改一处另一个不变」会直接变红（守卫见 `shared.rs` 与本文件的用例）。

+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::{Mutex, OnceLock};
 use std::time::Duration;

 use super::backoff::BackoffPolicy;
 use super::chunked::ChunkedConfig;
+use super::region::RegionProfile;
 use super::types::ResumePolicy;

+/// 全局并发许可数的出厂默认（`download.concurrency` 的 schema 默认值同源）。
+pub const DEFAULT_MAX_CONCURRENCY: usize = 8;
+
+/// 全局并发许可的**硬上限**（`download.concurrency` 的 schema 上界同源）。schema 在写入口就拒绝
+/// 越界值，这里再夹一次是纵深防御（手改文件、老 schema 允许的大数）——9999 会把机器拖死。
+pub const MAX_CONCURRENCY: usize = 64;
+
+/// 每个源尝试次数的出厂默认（`download.retry_limit` 的 schema 默认值同源）。
+pub const DEFAULT_MAX_ATTEMPTS_PER_SOURCE: u32 = 3;
+
+/// 每个源尝试次数的硬上限（`download.retry_limit` 的 schema 上界同源）。
+pub const MAX_ATTEMPTS_PER_SOURCE: u32 = 10;
+
+/// 三个设置键名（层间契约）：登记在 `setting::keys`，读取在宿主。只写在这里，两侧都引用常量。
+pub const KEY_CONCURRENCY: &str = "download.concurrency";
+/// 见 [`KEY_CONCURRENCY`]。
+pub const KEY_RETRY_LIMIT: &str = "download.retry_limit";
+/// gh-proxy 前缀覆盖键（三态语义见 [`gh_proxy_override`]）。
+///
+/// **暂未登记**：由 M197 在 `setting::keys::proxy` 登记，尚未合入 dev；宿主读它得到 `None` ⇒
+/// [`GhProxyOverride::Builtin`]（行为正确）。**M197 合入后这条断言应升级为 schema 断言**——现在
+/// 只断言常量本身，别把这条弱断言当成可以随手删的。
+pub const KEY_GH_PROXY: &str = "download.gh_proxy";
+
 /// 引擎配置。
 #[derive(Debug, Clone)]
 pub struct EngineConfig {
-    /// 全局并发许可数（tokio `Semaphore`），默认 64。
+    /// 全局并发许可数（tokio `Semaphore`），默认 [`DEFAULT_MAX_CONCURRENCY`]。
    pub max_concurrency: usize,
-    /// 每个源的尝试次数上限，默认 3。
+    /// 每个源的尝试次数上限，默认 [`DEFAULT_MAX_ATTEMPTS_PER_SOURCE`]。
    pub max_attempts_per_source: u32,
    /// 连接超时，默认 10s。
    pub connect_timeout: Duration,
@@ -32,8 +66,8 @@ pub struct EngineConfig {
 impl Default for EngineConfig {
    fn default() -> Self {
        Self {
-            max_concurrency: 64,
-            max_attempts_per_source: 3,
+            max_concurrency: DEFAULT_MAX_CONCURRENCY,
+            max_attempts_per_source: DEFAULT_MAX_ATTEMPTS_PER_SOURCE,
            connect_timeout: Duration::from_secs(10),
            read_timeout: Duration::from_secs(30),
            user_agent: concat!("UnluckyLauncher/", env!("CARGO_PKG_VERSION")).to_string(),
@@ -44,3 +78,323 @@ impl Default for EngineConfig {
        }
    }
 }
+
+/// `download.gh_proxy` 的三种取值（三态语义见 [`gh_proxy_override`]）。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub enum GhProxyOverride {
+    /// 空串：**没有覆盖**，跟随内置默认（地区判定 + 镜像表里的前缀）。
+    #[default]
+    Builtin,
+    /// 明确关掉：一个 gh-proxy 候选都不生成（`RegionProfile::with_gh_proxy(None)`）。
+    Off,
+    /// 用这个前缀覆盖（仍然只在镜像优先 / 国内判定时启用）。
+    Prefix(String),
+}
+
+/// 设置原文 → gh-proxy 三态（纯函数：`off` 与 URL 的边界在这里定死，不散落到宿主）。
+///
+/// **空串不等于关**：「我不想用加速」和「我还没决定」是两件事。空串 = 跟随内置默认，
+/// 要关必须写 `off`（`none` / `direct` / `disable` / `disabled` / `no` 这些口语词一并认，
+/// 大小写不敏感、前后空白忽略——用户拿哪个词表达「关掉」都合理，专门要求某一个会造出
+/// 「填了没生效」的坑）。
+#[must_use]
+pub fn gh_proxy_override(raw: &str) -> GhProxyOverride {
+    let text = raw.trim();
+    if text.is_empty() {
+        return GhProxyOverride::Builtin;
+    }
+    let lowered = text.to_ascii_lowercase();
+    if matches!(
+        lowered.as_str(),
+        "off" | "none" | "direct" | "disable" | "disabled" | "no"
+    ) {
+        return GhProxyOverride::Off;
+    }
+    GhProxyOverride::Prefix(text.to_string())
+}
+
+/// 设置侧灌进来的下载调优（M193）：并发 / 每个源的尝试次数 / gh-proxy 覆盖。
+///
+/// 这是「`launcher.json` 的三个键」到「引擎装配参数」之间**唯一**的翻译层：键名由宿主读（core
+/// 不认识设置键名），默认值、合法区间、回落策略都在这里——否则「UI 说 8、引擎跑 64」会从缝里长回来。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DownloadTuning {
+    /// 全局并发许可数（已夹在 `1..=MAX_CONCURRENCY`）。
+    pub max_concurrency: usize,
+    /// 每个源的尝试次数上限（已夹在 `1..=MAX_ATTEMPTS_PER_SOURCE`）。
+    pub max_attempts_per_source: u32,
+    /// gh-proxy 覆盖。
+    pub gh_proxy: GhProxyOverride,
+}
+
+impl Default for DownloadTuning {
+    fn default() -> Self {
+        Self {
+            max_concurrency: DEFAULT_MAX_CONCURRENCY,
+            max_attempts_per_source: DEFAULT_MAX_ATTEMPTS_PER_SOURCE,
+            gh_proxy: GhProxyOverride::Builtin,
+        }
+    }
+}
+
+impl DownloadTuning {
+    /// 设置原文 → 调优（**未填 / 越界 / 非法值一律回落出厂默认**，绝不报错阻断下载）。
+    ///
+    /// 口径与 schema 的 `(min, max)` 同源但独立实现（用户可能手改文件绕过 `store.set`）：键不存在
+    /// → 出厂默认；落在区间内 → 原值；0 / 负数 / 超上限 → 出厂默认（**不夹到边界**：那是「想 9999
+    /// 给 64」，界面仍会说谎）。
+    #[must_use]
+    pub fn from_settings(
+        concurrency: Option<i64>,
+        attempts: Option<i64>,
+        gh_proxy: Option<&str>,
+    ) -> Self {
+        let default = Self::default();
+        Self {
+            max_concurrency: concurrency
+                .and_then(|raw| usize::try_from(raw).ok())
+                .filter(|raw| (1..=MAX_CONCURRENCY).contains(raw))
+                .unwrap_or(default.max_concurrency),
+            max_attempts_per_source: attempts
+                .and_then(|raw| u32::try_from(raw).ok())
+                .filter(|raw| (1..=MAX_ATTEMPTS_PER_SOURCE).contains(raw))
+                .unwrap_or(default.max_attempts_per_source),
+            gh_proxy: gh_proxy.map_or(GhProxyOverride::Builtin, gh_proxy_override),
+        }
+    }
+
+    /// 把调优盖到 `EngineConfig` 上（其余字段保持传入值）。
+    #[must_use]
+    pub fn apply_to(&self, mut cfg: EngineConfig) -> EngineConfig {
+        cfg.max_concurrency = self.max_concurrency;
+        cfg.max_attempts_per_source = self.max_attempts_per_source;
+        cfg
+    }
+
+    /// 把 gh-proxy 覆盖盖到档案上（`Builtin` 原样返回 = 跟随地区判定与镜像表）。
+    #[must_use]
+    pub fn apply_gh_proxy(&self, profile: RegionProfile) -> RegionProfile {
+        match &self.gh_proxy {
+            GhProxyOverride::Builtin => profile,
+            GhProxyOverride::Off => profile.with_gh_proxy(None),
+            GhProxyOverride::Prefix(prefix) => profile.with_gh_proxy(Some(prefix)),
+        }
+    }
+}
+
+/// 每个缓存根一份「宿主想要什么」（`engine_for` 构造时用它，见 [`wanted`]）。按数据根而不是进程级：
+/// 登记处本就是「一个数据根一个引擎」；进程级那份在多数据根时会互相踩（A 根改 2、B 根冲回 8）。
+fn wanted_slot() -> &'static Mutex<HashMap<PathBuf, DownloadTuning>> {
+    static WANTED: OnceLock<Mutex<HashMap<PathBuf, DownloadTuning>>> = OnceLock::new();
+    WANTED.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// 该数据根当前想要的调优（没灌过 = 出厂默认）。
+#[must_use]
+pub fn wanted(cache_root: &Path) -> DownloadTuning {
+    wanted_slot()
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+        .get(cache_root)
+        .cloned()
+        .unwrap_or_default()
+}
+
+/// 记下该数据根想要的调优，返回**是否真的变了**（没变时调用方不该重建引擎）。
+pub fn publish(cache_root: &Path, next: DownloadTuning) -> bool {
+    let mut wanted = wanted_slot()
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    // 归一化比较：「没灌过」与「灌了出厂默认」是同一件事，不能因为 `None != Some(default)`
+    // 就把每次取引擎都当成「参数变了」（那会每次重建引擎、把连接池与健康度记忆全丢掉）。
+    let current = wanted.get(cache_root).cloned().unwrap_or_default();
+    if current == next {
+        return false;
+    }
+    if next == DownloadTuning::default() {
+        // 默认值不占格子（也顺手回收测试造的临时根）。
+        wanted.remove(cache_root);
+    } else {
+        wanted.insert(cache_root.to_path_buf(), next);
+    }
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::setting::keys::{launcher_schema, launcher_version};
+
+    /// **守门③**：schema 的默认值与 `EngineConfig::default()` / 调优默认值是同一个常量。
+    ///
+    /// 变异证明（只改实现侧）：把 `EngineConfig::default()` 的 `max_concurrency` 写回字面量 64
+    /// ⇒ 本用例红在 `max_concurrency`；把 `setting/keys.rs` 的 `download.concurrency` 默认值写回
+    /// 字面量 8 而常量改成 16 ⇒ 红在 schema 一侧。这条防的正是「两处各写一个数」长回来
+    /// （8 vs 64 就是这么长出来的）。
+    #[test]
+    fn the_schema_defaults_are_the_engine_defaults() {
+        let schema = launcher_schema();
+        assert_eq!(schema.version(), launcher_version());
+        let cfg = EngineConfig::default();
+        let tune = DownloadTuning::default();
+
+        // 键名常量与 schema 登记是同一份（宿主按常量读，schema 按常量登记）。
+        assert!(schema.spec(KEY_CONCURRENCY).is_some(), "{KEY_CONCURRENCY}");
+        assert!(schema.spec(KEY_RETRY_LIMIT).is_some(), "{KEY_RETRY_LIMIT}");
+
+        let concurrency = schema.spec(KEY_CONCURRENCY).expect("键已登记");
+        assert_eq!(
+            concurrency.default,
+            serde_json::json!(DEFAULT_MAX_CONCURRENCY)
+        );
+        assert_eq!(cfg.max_concurrency, DEFAULT_MAX_CONCURRENCY);
+        assert_eq!(tune.max_concurrency, DEFAULT_MAX_CONCURRENCY);
+
+        let retry = schema.spec(KEY_RETRY_LIMIT).expect("键已登记");
+        assert_eq!(
+            retry.default,
+            serde_json::json!(DEFAULT_MAX_ATTEMPTS_PER_SOURCE)
+        );
+        assert_eq!(cfg.max_attempts_per_source, DEFAULT_MAX_ATTEMPTS_PER_SOURCE);
+        assert_eq!(
+            tune.max_attempts_per_source,
+            DEFAULT_MAX_ATTEMPTS_PER_SOURCE
+        );
+    }
+
+    /// 硬上限：schema 的上界与引擎的夹取上限是同一个常量（防「schema 收 256、引擎不知情」）。
+    /// 变异证明：只改 `MAX_CONCURRENCY` 而 schema 仍写 64 ⇒ 红。
+    #[test]
+    fn the_hard_caps_are_single_sourced() {
+        let schema = launcher_schema();
+        let concurrency = i64::try_from(MAX_CONCURRENCY).expect("装得下");
+        let attempts = i64::from(MAX_ATTEMPTS_PER_SOURCE);
+        for (key, max) in [(KEY_CONCURRENCY, concurrency), (KEY_RETRY_LIMIT, attempts)] {
+            let spec = schema.spec(key).expect("键已登记");
+            assert_eq!(
+                spec.kind,
+                crate::setting::spec::ValueKind::Int { min: 1, max }
+            );
+        }
+    }
+
+    /// 未填 / 非法值回落默认，不阻断（任务书的边界条款）。
+    ///
+    /// 变异证明：把 `filter(|raw| (1..=MAX_CONCURRENCY).contains(raw))` 删掉 ⇒ `9999` 与 `0`
+    /// 两处断言红；把 `unwrap_or(default.max_concurrency)` 改成 `unwrap_or(1)` ⇒ `None` 断言红。
+    #[test]
+    fn missing_or_illegal_values_fall_back_to_the_defaults() {
+        let tune = DownloadTuning::from_settings(None, None, None);
+        assert_eq!(tune, DownloadTuning::default());
+
+        let just_over = i64::try_from(MAX_CONCURRENCY).expect("上限装得下") + 1;
+        for bad in [0_i64, -1, 9_999, just_over] {
+            let tune = DownloadTuning::from_settings(Some(bad), Some(bad), None);
+            assert_eq!(
+                tune,
+                DownloadTuning::default(),
+                "{bad} 越界时应回落默认而不是夹到边界"
+            );
+        }
+
+        let tune = DownloadTuning::from_settings(Some(2), Some(1), None);
+        assert_eq!(tune.max_concurrency, 2);
+        assert_eq!(tune.max_attempts_per_source, 1);
+    }
+
+    /// 三态：**空串 ≠ 关**（这条是「设置项说假话」的高发点，M197 的键语义同源）。
+    #[test]
+    fn empty_gh_proxy_means_follow_builtin_not_off() {
+        assert_eq!(gh_proxy_override(""), GhProxyOverride::Builtin);
+        assert_eq!(gh_proxy_override("   "), GhProxyOverride::Builtin);
+        for off in [
+            "off", "OFF", " none ", "direct", "disable", "disabled", "no",
+        ] {
+            assert_eq!(gh_proxy_override(off), GhProxyOverride::Off, "{off}");
+        }
+        assert_eq!(
+            gh_proxy_override(" https://gh.example/ "),
+            GhProxyOverride::Prefix("https://gh.example/".to_string())
+        );
+        // 未填（键不存在）也是 Builtin，不是 Off。
+        assert_eq!(
+            DownloadTuning::from_settings(None, None, None).gh_proxy,
+            GhProxyOverride::Builtin
+        );
+    }
+
+    /// `apply_gh_proxy` 的三档真的改到档案上、并且**改到候选链上**（`MirrorTable::expand()` 读的就是
+    /// 档案里那个前缀，内容库/版本清单都走它）。这是「改键 ⇒ 候选链变」的 core 级一半。
+    /// 变异证明：把 `Off` 分支改成原样返回 `profile` ⇒ `off` 那条红。
+    #[test]
+    fn gh_proxy_override_reaches_the_region_profile_and_the_candidate_chain() {
+        use crate::download::mirrors::{MirrorTable, SOURCE_GH_PROXY};
+        use crate::download::types::ResourceKind;
+
+        let url = "https://github.com/o/r/releases/download/v1/a.jar";
+        let table = MirrorTable::builtin();
+        let chain = |profile: &RegionProfile| -> Vec<String> {
+            table
+                .expand(url, ResourceKind::Other, profile)
+                .into_iter()
+                .map(|candidate| candidate.url)
+                .collect()
+        };
+
+        let mirror_first = RegionProfile::mirror_first(0);
+        let kept = DownloadTuning::default().apply_gh_proxy(mirror_first.clone());
+        assert_eq!(kept.gh_proxy, mirror_first.gh_proxy, "Builtin 不该动档案");
+        assert!(
+            chain(&kept).iter().any(|url| url.contains("gh-proxy")),
+            "出厂默认会套前缀"
+        );
+
+        let off = DownloadTuning::from_settings(None, None, Some("off"))
+            .apply_gh_proxy(mirror_first.clone());
+        assert!(!off.gh_proxy_enabled(), "off 必须关掉 gh-proxy");
+        assert_eq!(off.gh_proxy, None);
+        assert!(
+            !chain(&off).iter().any(|url| url.contains("gh-proxy")),
+            "关了就不该有候选"
+        );
+        assert!(
+            table
+                .expand(url, ResourceKind::Other, &off)
+                .iter()
+                .all(|candidate| candidate.source != SOURCE_GH_PROXY),
+            "连 source 也不该出现"
+        );
+
+        let prefix = DownloadTuning::from_settings(None, None, Some("https://gh.example/"))
+            .apply_gh_proxy(mirror_first);
+        assert_eq!(prefix.gh_proxy.as_deref(), Some("https://gh.example/"));
+        assert!(prefix.gh_proxy_enabled());
+        assert!(
+            chain(&prefix)
+                .iter()
+                .any(|url| url.starts_with("https://gh.example/")),
+            "覆盖前缀必须进候选链"
+        );
+    }
+
+    /// 每个数据根的调优互不串味（一个根改成 2 不该改另一个根的引擎）。
+    /// 变异证明：把 `wanted`/`publish` 的键改回单一进程级槽位 ⇒ 第二个根读到 2，红。
+    #[test]
+    fn tuning_is_per_cache_root_and_no_change_is_reported_as_such() {
+        let a = PathBuf::from("/tmp/ull-tuning-a");
+        let b = PathBuf::from("/tmp/ull-tuning-b");
+        assert_eq!(wanted(&a), DownloadTuning::default());
+
+        let changed = DownloadTuning::from_settings(Some(2), None, None);
+        assert!(publish(&a, changed.clone()), "真变了要报变更");
+        assert_eq!(wanted(&a), changed);
+        assert!(!publish(&a, changed.clone()), "同值不该报变更");
+        assert_eq!(wanted(&b), DownloadTuning::default(), "别的根不受影响");
+
+        assert!(
+            publish(&a, DownloadTuning::default()),
+            "恢复默认也是一次变更"
+        );
+        assert_eq!(wanted(&a), DownloadTuning::default());
+    }
+}