mirror of
https://github.com/Corfirean/coa-server-manager.git
synced 2026-11-21 11:25:56 +00:00
feat(core): implement AzerothCore module catalogue engine, overlay and caching
This commit is contained in:
1 parent
3dbfffba76
commit
4e661e6986
4 files changed
+1448
No files matched your search
@@ -0,0 +1,838 @@
|
||||
//! Public AzerothCore Module Catalogue integration for CoA Server Manager.
|
||||
//!
|
||||
//! Provides cached, prioritized, and overlay-enriched discovery of AzerothCore modules
|
||||
//! sourced from `https://www.azerothcore.org/data/catalogue.json`.
|
||||
//!
|
||||
//! Features:
|
||||
//! - Thread-safe periodic synchronization with ETag (`If-None-Match`) support
|
||||
//! - Transparent offline caching with atomic disk persistence
|
||||
//! - Priority ordering: CoA Recommended / Verified modules always appear first
|
||||
//! - Seamless deduplication by GitHub Repository ID and normalized slug
|
||||
//! - Deep integration with the CoA Compatibility Overlay (`coa-modules-overlay.json`)
|
||||
//! - Hard policy blocking to prevent installation of known crashers or security risks
|
||||
|
||||
use std::collections::{BTreeMap, HashSet};
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
use std::sync::Mutex;
|
||||
use std::time::Duration;
|
||||
|
||||
use chrono::Utc;
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use crate::error::{Error, Result};
|
||||
use crate::fsx;
|
||||
|
||||
pub const OFFICIAL_CATALOGUE_URL: &str = "https://www.azerothcore.org/data/catalogue.json";
|
||||
pub const DEFAULT_CACHE_TTL_SECS: i64 = 12 * 3600; // 12 hours
|
||||
const CONNECT_TIMEOUT_SECS: u64 = 10;
|
||||
const READ_TIMEOUT_SECS: u64 = 25;
|
||||
|
||||
static CATALOGUE_LOCK: Mutex<()> = Mutex::new(());
|
||||
static EMBEDDED_OVERLAY_JSON: &str = include_str!("coa-modules-overlay.json");
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// External Data Models (matching official AzerothCore JSON)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
#[derive(Debug, Clone, Deserialize)]
|
||||
pub struct OfficialCatalogueRaw {
|
||||
#[serde(default)]
|
||||
pub global_search: bool,
|
||||
#[serde(default)]
|
||||
pub organizations: BTreeMap<String, BTreeMap<String, Vec<OfficialRepoRaw>>>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Deserialize)]
|
||||
pub struct OfficialRepoRaw {
|
||||
pub id: u64,
|
||||
pub name: String,
|
||||
pub full_name: String,
|
||||
#[serde(default)]
|
||||
pub description: Option<String>,
|
||||
#[serde(default)]
|
||||
pub stargazers_count: u32,
|
||||
#[serde(default)]
|
||||
pub created_at: Option<String>,
|
||||
#[serde(default = "default_branch_val")]
|
||||
pub default_branch: String,
|
||||
#[serde(default)]
|
||||
pub owner: Option<OfficialOwnerRaw>,
|
||||
pub html_url: String,
|
||||
#[serde(default)]
|
||||
pub forks_count: u32,
|
||||
#[serde(default)]
|
||||
pub watchers_count: u32,
|
||||
#[serde(default)]
|
||||
pub pushed_at: Option<String>,
|
||||
#[serde(default)]
|
||||
pub updated_at: Option<String>,
|
||||
#[serde(default)]
|
||||
pub license: Option<OfficialLicenseRaw>,
|
||||
#[serde(default)]
|
||||
pub topics: Vec<String>,
|
||||
}
|
||||
|
||||
fn default_branch_val() -> String {
|
||||
"master".into()
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Deserialize)]
|
||||
pub struct OfficialOwnerRaw {
|
||||
pub login: String,
|
||||
#[serde(default)]
|
||||
pub avatar_url: Option<String>,
|
||||
#[serde(default)]
|
||||
pub html_url: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Deserialize)]
|
||||
pub struct OfficialLicenseRaw {
|
||||
#[serde(default)]
|
||||
pub spdx_id: Option<String>,
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// CoA Overlay Models
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct CoaOverlayDocument {
|
||||
pub version: u32,
|
||||
#[serde(default)]
|
||||
pub description: Option<String>,
|
||||
pub rules: Vec<CoaOverlayRule>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct CoaOverlayRule {
|
||||
#[serde(default)]
|
||||
pub repo_id: Option<u64>,
|
||||
pub repo_slug: String,
|
||||
pub status: CoaCompatibilityStatus,
|
||||
#[serde(default)]
|
||||
pub is_recommended: bool,
|
||||
#[serde(default)]
|
||||
pub reason: Option<String>,
|
||||
#[serde(default)]
|
||||
pub tested_version: Option<String>,
|
||||
#[serde(default)]
|
||||
pub tested_abi: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
|
||||
pub enum CoaCompatibilityStatus {
|
||||
Recommended,
|
||||
Verified,
|
||||
RequiresAdapter,
|
||||
Unverified,
|
||||
Incompatible,
|
||||
Blocked,
|
||||
}
|
||||
|
||||
impl std::fmt::Display for CoaCompatibilityStatus {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
match self {
|
||||
Self::Recommended => write!(f, "Recommended"),
|
||||
Self::Verified => write!(f, "Verified"),
|
||||
Self::RequiresAdapter => write!(f, "RequiresAdapter"),
|
||||
Self::Unverified => write!(f, "Unverified"),
|
||||
Self::Incompatible => write!(f, "Incompatible"),
|
||||
Self::Blocked => write!(f, "Blocked"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Internal Normalized Item & API Response
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
|
||||
pub struct PublicCatalogueItem {
|
||||
pub id: u64,
|
||||
pub name: String,
|
||||
pub full_name: String,
|
||||
pub owner: String,
|
||||
pub html_url: String,
|
||||
pub description: String,
|
||||
pub stars: u32,
|
||||
pub forks: u32,
|
||||
pub default_branch: String,
|
||||
#[serde(default)]
|
||||
pub pushed_at: Option<String>,
|
||||
#[serde(default)]
|
||||
pub updated_at: Option<String>,
|
||||
#[serde(default)]
|
||||
pub license: Option<String>,
|
||||
#[serde(default)]
|
||||
pub topics: Vec<String>,
|
||||
pub coa_status: CoaCompatibilityStatus,
|
||||
pub coa_status_source: String, // "Overlay", "VerifiedCatalog", "AutoPublic"
|
||||
pub conflict_reason: Option<String>,
|
||||
pub is_coa_recommended: bool,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct CachedDocument {
|
||||
pub schema_version: u32,
|
||||
pub cached_at: String,
|
||||
pub timestamp: i64,
|
||||
#[serde(default)]
|
||||
pub etag: Option<String>,
|
||||
pub items: Vec<PublicCatalogueItem>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct PublicCatalogueResponse {
|
||||
pub items: Vec<PublicCatalogueItem>,
|
||||
pub cached_at: String,
|
||||
pub is_offline: bool,
|
||||
#[serde(default)]
|
||||
pub etag: Option<String>,
|
||||
pub total_count: usize,
|
||||
pub recommended_count: usize,
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helper: Normalization of Slugs & URLs
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
pub fn normalize_repo_slug(url_or_slug: &str) -> String {
|
||||
let mut s = url_or_slug.trim();
|
||||
if let Some(pos) = s.find("://") {
|
||||
s = &s[pos + 3..];
|
||||
}
|
||||
if let Some(pos) = s.find('@') {
|
||||
if let Some(colon) = s[pos..].find(':') {
|
||||
s = &s[pos + colon + 1..];
|
||||
}
|
||||
}
|
||||
if let Some(stripped) = s.strip_prefix("github.com/") {
|
||||
s = stripped;
|
||||
}
|
||||
// Remove query params or fragments
|
||||
if let Some(pos) = s.find('?') {
|
||||
s = &s[..pos];
|
||||
}
|
||||
if let Some(pos) = s.find('#') {
|
||||
s = &s[..pos];
|
||||
}
|
||||
// Remove tree/branches if present (e.g. repo/tree/branch/sub)
|
||||
let parts: Vec<&str> = s.split('/').filter(|p| !p.is_empty()).collect();
|
||||
if parts.len() >= 2 {
|
||||
let owner = parts[0].to_ascii_lowercase();
|
||||
let mut repo = parts[1].to_ascii_lowercase();
|
||||
if repo.ends_with(".git") {
|
||||
repo.truncate(repo.len() - 4);
|
||||
}
|
||||
format!("{owner}/{repo}")
|
||||
} else {
|
||||
s.trim_end_matches(".git").to_ascii_lowercase()
|
||||
}
|
||||
}
|
||||
|
||||
pub fn load_coa_overlay(optional_overlay_path: Option<&Path>) -> CoaOverlayDocument {
|
||||
let mut doc: CoaOverlayDocument = serde_json::from_str(EMBEDDED_OVERLAY_JSON)
|
||||
.unwrap_or_else(|_| CoaOverlayDocument {
|
||||
version: 1,
|
||||
description: None,
|
||||
rules: Vec::new(),
|
||||
});
|
||||
|
||||
if let Some(path) = optional_overlay_path {
|
||||
if path.is_file() {
|
||||
if let Ok(content) = fs::read_to_string(path) {
|
||||
if let Ok(external) = serde_json::from_str::<CoaOverlayDocument>(&content) {
|
||||
for ext_rule in external.rules {
|
||||
if let Some(existing) = doc
|
||||
.rules
|
||||
.iter_mut()
|
||||
.find(|r| normalize_repo_slug(&r.repo_slug) == normalize_repo_slug(&ext_rule.repo_slug))
|
||||
{
|
||||
*existing = ext_rule;
|
||||
} else {
|
||||
doc.rules.push(ext_rule);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
doc
|
||||
}
|
||||
|
||||
/// Checks if a repository is explicitly blocked by CoA policy.
|
||||
/// Returns `Some(reason)` if blocked, otherwise `None`.
|
||||
pub fn is_blocked_repo(url_or_slug: &str) -> Option<String> {
|
||||
let target = normalize_repo_slug(url_or_slug);
|
||||
let overlay = load_coa_overlay(None);
|
||||
for rule in overlay.rules {
|
||||
if rule.status == CoaCompatibilityStatus::Blocked && normalize_repo_slug(&rule.repo_slug) == target {
|
||||
return Some(rule.reason.unwrap_or_else(|| "Module blocked by CoA stability/security policy.".into()));
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Normalization & Deduplication Logic
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
pub fn normalize_catalogue(
|
||||
raw: &OfficialCatalogueRaw,
|
||||
overlay: &CoaOverlayDocument,
|
||||
) -> Vec<PublicCatalogueItem> {
|
||||
let mut normalized = Vec::new();
|
||||
let mut seen_ids = HashSet::new();
|
||||
let mut seen_slugs = HashSet::new();
|
||||
|
||||
// 1. Map overlay rules by slug for O(1) lookup
|
||||
let mut overlay_map: BTreeMap<String, &CoaOverlayRule> = BTreeMap::new();
|
||||
for rule in &overlay.rules {
|
||||
overlay_map.insert(normalize_repo_slug(&rule.repo_slug), rule);
|
||||
}
|
||||
|
||||
// 2. Extract repos from the category "azerothcore-module"
|
||||
let mut repos = Vec::new();
|
||||
for (_, topics) in &raw.organizations {
|
||||
for (topic_name, list) in topics {
|
||||
if topic_name == "azerothcore-module" {
|
||||
repos.extend(list.iter());
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// If "azerothcore-module" was empty or structure differs, collect all modules
|
||||
if repos.is_empty() {
|
||||
for (_, topics) in &raw.organizations {
|
||||
for (_, list) in topics {
|
||||
repos.extend(list.iter());
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 3. Process and deduplicate
|
||||
for repo in repos {
|
||||
let slug = normalize_repo_slug(&repo.full_name);
|
||||
|
||||
if repo.id != 0 && !seen_ids.insert(repo.id) {
|
||||
continue;
|
||||
}
|
||||
if !seen_slugs.insert(slug.clone()) {
|
||||
continue;
|
||||
}
|
||||
|
||||
let owner = repo
|
||||
.owner
|
||||
.as_ref()
|
||||
.map(|o| o.login.clone())
|
||||
.unwrap_or_else(|| {
|
||||
slug.split('/').next().unwrap_or("unknown").to_string()
|
||||
});
|
||||
|
||||
// Determine CoA status from overlay or default to Unverified
|
||||
let (coa_status, coa_source, reason, is_rec) = if let Some(rule) = overlay_map.get(&slug) {
|
||||
(
|
||||
rule.status,
|
||||
"Overlay".to_string(),
|
||||
rule.reason.clone(),
|
||||
rule.is_recommended || rule.status == CoaCompatibilityStatus::Recommended,
|
||||
)
|
||||
} else {
|
||||
(
|
||||
CoaCompatibilityStatus::Unverified,
|
||||
"AutoPublic".to_string(),
|
||||
None,
|
||||
false,
|
||||
)
|
||||
};
|
||||
|
||||
let license = repo.license.as_ref().and_then(|l| l.spdx_id.clone());
|
||||
|
||||
normalized.push(PublicCatalogueItem {
|
||||
id: repo.id,
|
||||
name: repo.name.clone(),
|
||||
full_name: repo.full_name.clone(),
|
||||
owner,
|
||||
html_url: repo.html_url.clone(),
|
||||
description: repo.description.clone().unwrap_or_default(),
|
||||
stars: repo.stargazers_count,
|
||||
forks: repo.forks_count,
|
||||
default_branch: repo.default_branch.clone(),
|
||||
pushed_at: repo.pushed_at.clone(),
|
||||
updated_at: repo.updated_at.clone(),
|
||||
license,
|
||||
topics: repo.topics.clone(),
|
||||
coa_status,
|
||||
coa_status_source: coa_source,
|
||||
conflict_reason: reason,
|
||||
is_coa_recommended: is_rec,
|
||||
});
|
||||
}
|
||||
|
||||
// 4. Also ensure any Recommended overlay rules that were not present in the public raw catalog
|
||||
// are included so they are never lost
|
||||
for rule in &overlay.rules {
|
||||
let slug = normalize_repo_slug(&rule.repo_slug);
|
||||
if seen_slugs.insert(slug.clone()) {
|
||||
let parts: Vec<&str> = slug.split('/').collect();
|
||||
let (owner, name) = if parts.len() >= 2 {
|
||||
(parts[0].to_string(), parts[1].to_string())
|
||||
} else {
|
||||
("corfirean".to_string(), slug.clone())
|
||||
};
|
||||
|
||||
normalized.push(PublicCatalogueItem {
|
||||
id: rule.repo_id.unwrap_or(0),
|
||||
name: name.clone(),
|
||||
full_name: slug.clone(),
|
||||
owner,
|
||||
html_url: format!("https://github.com/{}", slug),
|
||||
description: rule.reason.clone().unwrap_or_default(),
|
||||
stars: 0,
|
||||
forks: 0,
|
||||
default_branch: "master".to_string(),
|
||||
pushed_at: None,
|
||||
updated_at: None,
|
||||
license: Some("AGPL-3.0".to_string()),
|
||||
topics: vec!["azerothcore-module".to_string(), "coa-verified".to_string()],
|
||||
coa_status: rule.status,
|
||||
coa_status_source: "Overlay".to_string(),
|
||||
conflict_reason: rule.reason.clone(),
|
||||
is_coa_recommended: rule.is_recommended || rule.status == CoaCompatibilityStatus::Recommended,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// 5. Sort:
|
||||
// Group A (Recommended/Verified) first, then by Stars desc, then by pushed_at desc
|
||||
normalized.sort_by(|a, b| {
|
||||
// Priority 1: Recommended modules first
|
||||
match (a.is_coa_recommended, b.is_coa_recommended) {
|
||||
(true, false) => return std::cmp::Ordering::Less,
|
||||
(false, true) => return std::cmp::Ordering::Greater,
|
||||
_ => {}
|
||||
}
|
||||
// Priority 2: Status order (Verified before Unverified, Blocked at end)
|
||||
if a.coa_status != b.coa_status {
|
||||
return a.coa_status.cmp(&b.coa_status);
|
||||
}
|
||||
// Priority 3: Stars descending
|
||||
if b.stars != a.stars {
|
||||
return b.stars.cmp(&a.stars);
|
||||
}
|
||||
// Priority 4: pushed_at descending
|
||||
let pa = a.pushed_at.as_deref().unwrap_or("");
|
||||
let pb = b.pushed_at.as_deref().unwrap_or("");
|
||||
if pb != pa {
|
||||
return pb.cmp(pa);
|
||||
}
|
||||
// Deterministic tie-breaker
|
||||
a.full_name.cmp(&b.full_name)
|
||||
});
|
||||
|
||||
normalized
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Network Fetcher & Cache Manager
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
pub fn fetch_or_load_catalogue(
|
||||
cache_dir: &Path,
|
||||
force_refresh: bool,
|
||||
) -> Result<PublicCatalogueResponse> {
|
||||
let _guard = CATALOGUE_LOCK.lock().map_err(|_| {
|
||||
Error::Invalid("Failed to acquire catalogue cache lock.".into())
|
||||
})?;
|
||||
|
||||
fs::create_dir_all(cache_dir)?;
|
||||
let cache_file = cache_dir.join("catalogue_cache.json");
|
||||
let etag_file = cache_dir.join("catalogue_etag.txt");
|
||||
let overlay_path = cache_dir.join("coa-modules-overlay.json");
|
||||
let overlay = load_coa_overlay(Some(&overlay_path));
|
||||
|
||||
let now_ts = Utc::now().timestamp();
|
||||
|
||||
// 1. Check if disk cache exists and is fresh
|
||||
if !force_refresh && cache_file.is_file() {
|
||||
if let Ok(content) = fs::read_to_string(&cache_file) {
|
||||
if let Ok(cached) = serde_json::from_str::<CachedDocument>(&content) {
|
||||
let age = now_ts - cached.timestamp;
|
||||
if age < DEFAULT_CACHE_TTL_SECS && !cached.items.is_empty() {
|
||||
let rec_count = cached.items.iter().filter(|i| i.is_coa_recommended).count();
|
||||
return Ok(PublicCatalogueResponse {
|
||||
total_count: cached.items.len(),
|
||||
recommended_count: rec_count,
|
||||
cached_at: cached.cached_at,
|
||||
is_offline: false,
|
||||
etag: cached.etag,
|
||||
items: cached.items,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Perform Network Fetch with ETag support
|
||||
let stored_etag = fs::read_to_string(&etag_file).ok().map(|s| s.trim().to_string());
|
||||
let client = reqwest::blocking::Client::builder()
|
||||
.connect_timeout(Duration::from_secs(CONNECT_TIMEOUT_SECS))
|
||||
.timeout(Duration::from_secs(READ_TIMEOUT_SECS))
|
||||
.redirect(reqwest::redirect::Policy::limited(5))
|
||||
.build()
|
||||
.map_err(|e| Error::Invalid(format!("HTTP client initialization failed: {}", e)))?;
|
||||
|
||||
let mut request = client.get(OFFICIAL_CATALOGUE_URL)
|
||||
.header(reqwest::header::USER_AGENT, "CSM-Modules-Preview/0.7.1");
|
||||
|
||||
if let Some(ref etag) = stored_etag {
|
||||
if !force_refresh && cache_file.is_file() {
|
||||
request = request.header(reqwest::header::IF_NONE_MATCH, etag.as_str());
|
||||
}
|
||||
}
|
||||
|
||||
let fetch_result = request.send();
|
||||
|
||||
match fetch_result {
|
||||
Ok(response) => {
|
||||
let status = response.status();
|
||||
|
||||
// 2.1 Handle 304 Not Modified
|
||||
if status == reqwest::StatusCode::NOT_MODIFIED {
|
||||
if cache_file.is_file() {
|
||||
if let Ok(content) = fs::read_to_string(&cache_file) {
|
||||
if let Ok(mut cached) = serde_json::from_str::<CachedDocument>(&content) {
|
||||
cached.timestamp = now_ts;
|
||||
cached.cached_at = Utc::now().to_rfc3339();
|
||||
let _ = fsx::atomic_write_json(&cache_file, &cached);
|
||||
let rec_count = cached.items.iter().filter(|i| i.is_coa_recommended).count();
|
||||
return Ok(PublicCatalogueResponse {
|
||||
total_count: cached.items.len(),
|
||||
recommended_count: rec_count,
|
||||
cached_at: cached.cached_at,
|
||||
is_offline: false,
|
||||
etag: cached.etag,
|
||||
items: cached.items,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
// If 304 received but cache file was missing or corrupt, re-fetch without etag
|
||||
return fetch_or_load_catalogue(cache_dir, true);
|
||||
}
|
||||
|
||||
// 2.2 Handle 200 OK
|
||||
if status.is_success() {
|
||||
let new_etag = response
|
||||
.headers()
|
||||
.get(reqwest::header::ETAG)
|
||||
.and_then(|h| h.to_str().ok())
|
||||
.map(|s| s.to_string());
|
||||
|
||||
let text = response.text().map_err(|e| {
|
||||
Error::Invalid(format!("Failed to read catalogue response body: {}", e))
|
||||
})?;
|
||||
|
||||
let raw: OfficialCatalogueRaw = serde_json::from_str(&text).map_err(|e| {
|
||||
Error::Invalid(format!("Failed to parse AzerothCore official catalogue JSON: {}", e))
|
||||
})?;
|
||||
|
||||
let items = normalize_catalogue(&raw, &overlay);
|
||||
let rec_count = items.iter().filter(|i| i.is_coa_recommended).count();
|
||||
let now_str = Utc::now().to_rfc3339();
|
||||
|
||||
let cached_doc = CachedDocument {
|
||||
schema_version: 1,
|
||||
cached_at: now_str.clone(),
|
||||
timestamp: now_ts,
|
||||
etag: new_etag.clone(),
|
||||
items: items.clone(),
|
||||
};
|
||||
|
||||
// Persist cache and etag atomically
|
||||
let _ = fsx::atomic_write_json(&cache_file, &cached_doc);
|
||||
if let Some(ref tag) = new_etag {
|
||||
let _ = fs::write(&etag_file, tag);
|
||||
}
|
||||
|
||||
return Ok(PublicCatalogueResponse {
|
||||
total_count: items.len(),
|
||||
recommended_count: rec_count,
|
||||
cached_at: now_str,
|
||||
is_offline: false,
|
||||
etag: new_etag,
|
||||
items,
|
||||
});
|
||||
}
|
||||
|
||||
// If non-200 and non-304 HTTP status, fallback to existing cache if available
|
||||
try_offline_fallback(&cache_file, stored_etag, &overlay)
|
||||
}
|
||||
Err(_net_err) => {
|
||||
// Network unreachable, DNS timeout, connection reset -> offline fallback
|
||||
try_offline_fallback(&cache_file, stored_etag, &overlay)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn try_offline_fallback(
|
||||
cache_file: &Path,
|
||||
stored_etag: Option<String>,
|
||||
overlay: &CoaOverlayDocument,
|
||||
) -> Result<PublicCatalogueResponse> {
|
||||
if cache_file.is_file() {
|
||||
if let Ok(content) = fs::read_to_string(cache_file) {
|
||||
if let Ok(cached) = serde_json::from_str::<CachedDocument>(&content) {
|
||||
let rec_count = cached.items.iter().filter(|i| i.is_coa_recommended).count();
|
||||
return Ok(PublicCatalogueResponse {
|
||||
total_count: cached.items.len(),
|
||||
recommended_count: rec_count,
|
||||
cached_at: cached.cached_at,
|
||||
is_offline: true,
|
||||
etag: cached.etag.or(stored_etag),
|
||||
items: cached.items,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// If completely offline and no cache file exists, build minimal catalog from overlay rules
|
||||
let empty_raw = OfficialCatalogueRaw {
|
||||
global_search: false,
|
||||
organizations: BTreeMap::new(),
|
||||
};
|
||||
let items = normalize_catalogue(&empty_raw, overlay);
|
||||
let rec_count = items.iter().filter(|i| i.is_coa_recommended).count();
|
||||
|
||||
Ok(PublicCatalogueResponse {
|
||||
total_count: items.len(),
|
||||
recommended_count: rec_count,
|
||||
cached_at: Utc::now().to_rfc3339(),
|
||||
is_offline: true,
|
||||
etag: None,
|
||||
items,
|
||||
})
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Unit & Integration Tests
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use tempfile::tempdir;
|
||||
|
||||
fn sample_official_json() -> &'static str {
|
||||
r#"{
|
||||
"global_search": true,
|
||||
"organizations": {
|
||||
"azerothcore": {
|
||||
"azerothcore-module": [
|
||||
{
|
||||
"id": 101,
|
||||
"name": "mod-npc-buffer",
|
||||
"full_name": "azerothcore/mod-npc-buffer",
|
||||
"description": "NPC buffer master",
|
||||
"stargazers_count": 55,
|
||||
"default_branch": "master",
|
||||
"html_url": "https://github.com/azerothcore/mod-npc-buffer",
|
||||
"forks_count": 12,
|
||||
"watchers_count": 55,
|
||||
"pushed_at": "2026-10-10T12:00:00Z",
|
||||
"updated_at": "2026-10-10T12:00:00Z",
|
||||
"license": { "spdx_id": "AGPL-3.0" },
|
||||
"topics": ["azerothcore-module", "utility"]
|
||||
},
|
||||
{
|
||||
"id": 102,
|
||||
"name": "mod-random-community",
|
||||
"full_name": "author/mod-random-community",
|
||||
"description": "A community module",
|
||||
"stargazers_count": 120,
|
||||
"default_branch": "main",
|
||||
"html_url": "https://github.com/author/mod-random-community",
|
||||
"forks_count": 5,
|
||||
"watchers_count": 120,
|
||||
"pushed_at": "2026-09-01T12:00:00Z",
|
||||
"updated_at": "2026-09-01T12:00:00Z",
|
||||
"license": null,
|
||||
"topics": ["azerothcore-module"]
|
||||
},
|
||||
{
|
||||
"id": 103,
|
||||
"name": "mod-learn-spells",
|
||||
"full_name": "azerothcore/mod-learn-spells",
|
||||
"description": "Auto teach spells",
|
||||
"stargazers_count": 48,
|
||||
"default_branch": "master",
|
||||
"html_url": "https://github.com/azerothcore/mod-learn-spells",
|
||||
"forks_count": 8,
|
||||
"watchers_count": 48,
|
||||
"pushed_at": "2026-08-01T12:00:00Z",
|
||||
"updated_at": "2026-08-01T12:00:00Z",
|
||||
"license": { "spdx_id": "AGPL-3.0" },
|
||||
"topics": ["azerothcore-module"]
|
||||
},
|
||||
{
|
||||
"id": 104,
|
||||
"name": "mod-ahbot",
|
||||
"full_name": "azerothcore/mod-ahbot",
|
||||
"description": "Upstream ahbot",
|
||||
"stargazers_count": 80,
|
||||
"default_branch": "master",
|
||||
"html_url": "https://github.com/azerothcore/mod-ahbot",
|
||||
"forks_count": 20,
|
||||
"watchers_count": 80,
|
||||
"pushed_at": "2026-07-01T12:00:00Z",
|
||||
"updated_at": "2026-07-01T12:00:00Z",
|
||||
"license": null,
|
||||
"topics": ["azerothcore-module"]
|
||||
},
|
||||
{
|
||||
"id": 101,
|
||||
"name": "mod-npc-buffer-duplicate",
|
||||
"full_name": "azerothcore/mod-npc-buffer",
|
||||
"description": "Duplicate entry with same id and slug",
|
||||
"stargazers_count": 55,
|
||||
"default_branch": "master",
|
||||
"html_url": "https://github.com/azerothcore/mod-npc-buffer",
|
||||
"forks_count": 12,
|
||||
"watchers_count": 55,
|
||||
"pushed_at": "2026-10-10T12:00:00Z",
|
||||
"updated_at": "2026-10-10T12:00:00Z",
|
||||
"license": { "spdx_id": "AGPL-3.0" },
|
||||
"topics": ["azerothcore-module"]
|
||||
}
|
||||
],
|
||||
"azerothcore-lua": [
|
||||
{
|
||||
"id": 201,
|
||||
"name": "pure-lua-script",
|
||||
"full_name": "some/pure-lua-script",
|
||||
"stargazers_count": 10,
|
||||
"default_branch": "main",
|
||||
"html_url": "https://github.com/some/pure-lua-script"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}"#
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_slug_normalization() {
|
||||
assert_eq!(normalize_repo_slug("https://github.com/azerothcore/mod-npc-buffer.git"), "azerothcore/mod-npc-buffer");
|
||||
assert_eq!(normalize_repo_slug("https://github.com/AzerothCore/Mod-NPC-Buffer/"), "azerothcore/mod-npc-buffer");
|
||||
assert_eq!(normalize_repo_slug("git@github.com:Corfirean/mod-coa-playerbots.git"), "corfirean/mod-coa-playerbots");
|
||||
assert_eq!(normalize_repo_slug("author/repo"), "author/repo");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_overlay_loading_and_blocked_detection() {
|
||||
let overlay = load_coa_overlay(None);
|
||||
assert!(!overlay.rules.is_empty(), "Embedded overlay must contain rules");
|
||||
|
||||
// Verify mod-ahbot is blocked
|
||||
assert!(is_blocked_repo("https://github.com/azerothcore/mod-ahbot").is_some());
|
||||
assert!(is_blocked_repo("azerothcore/mod-ahbot").is_some());
|
||||
|
||||
// Verify clean repo is not blocked
|
||||
assert!(is_blocked_repo("https://github.com/azerothcore/mod-npc-buffer").is_none());
|
||||
assert!(is_blocked_repo("random-author/clean-module").is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_official_json_parsing_and_normalization() {
|
||||
let raw: OfficialCatalogueRaw = serde_json::from_str(sample_official_json()).expect("Must parse sample JSON");
|
||||
let overlay = load_coa_overlay(None);
|
||||
let items = normalize_catalogue(&raw, &overlay);
|
||||
|
||||
// Deduplication: id 101 was duplicated, should only appear once
|
||||
let buffer_count = items.iter().filter(|i| i.full_name == "azerothcore/mod-npc-buffer").count();
|
||||
assert_eq!(buffer_count, 1, "Duplicate repo with ID 101 must be deduplicated");
|
||||
|
||||
// Check statuses assigned via overlay
|
||||
let buffer = items.iter().find(|i| i.full_name == "azerothcore/mod-npc-buffer").expect("mod-npc-buffer must exist");
|
||||
assert_eq!(buffer.coa_status, CoaCompatibilityStatus::Verified);
|
||||
assert!(buffer.is_coa_recommended);
|
||||
|
||||
let learn_spells = items.iter().find(|i| i.full_name == "azerothcore/mod-learn-spells").expect("mod-learn-spells must exist");
|
||||
assert_eq!(learn_spells.coa_status, CoaCompatibilityStatus::Incompatible);
|
||||
assert!(!learn_spells.is_coa_recommended);
|
||||
assert!(learn_spells.conflict_reason.is_some());
|
||||
|
||||
let ahbot = items.iter().find(|i| i.full_name == "azerothcore/mod-ahbot").expect("mod-ahbot must exist");
|
||||
assert_eq!(ahbot.coa_status, CoaCompatibilityStatus::Blocked);
|
||||
|
||||
let community = items.iter().find(|i| i.full_name == "author/mod-random-community").expect("community module must exist");
|
||||
assert_eq!(community.coa_status, CoaCompatibilityStatus::Unverified);
|
||||
assert_eq!(community.coa_status_source, "AutoPublic");
|
||||
assert!(!community.is_coa_recommended);
|
||||
|
||||
// Check priority sorting: Recommended modules must come first
|
||||
let first_non_rec_idx = items.iter().position(|i| !i.is_coa_recommended).unwrap_or(items.len());
|
||||
for (idx, item) in items.iter().enumerate() {
|
||||
if idx < first_non_rec_idx {
|
||||
assert!(item.is_coa_recommended, "Items before boundary must be recommended");
|
||||
} else {
|
||||
assert!(!item.is_coa_recommended, "Items after boundary must not be recommended");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_disk_caching_and_offline_fallback() {
|
||||
let d = tempdir().expect("tempdir");
|
||||
let cache_dir = d.path();
|
||||
|
||||
// 1. Manually write a cached document
|
||||
let items = vec![
|
||||
PublicCatalogueItem {
|
||||
id: 999,
|
||||
name: "cached-mod".into(),
|
||||
full_name: "test/cached-mod".into(),
|
||||
owner: "test".into(),
|
||||
html_url: "https://github.com/test/cached-mod".into(),
|
||||
description: "Test description".into(),
|
||||
stars: 42,
|
||||
forks: 2,
|
||||
default_branch: "master".into(),
|
||||
pushed_at: Some("2026-10-01T00:00:00Z".into()),
|
||||
updated_at: Some("2026-10-01T00:00:00Z".into()),
|
||||
license: Some("MIT".into()),
|
||||
topics: vec!["azerothcore-module".into()],
|
||||
coa_status: CoaCompatibilityStatus::Unverified,
|
||||
coa_status_source: "CacheTest".into(),
|
||||
conflict_reason: None,
|
||||
is_coa_recommended: false,
|
||||
}
|
||||
];
|
||||
|
||||
let cached_doc = CachedDocument {
|
||||
schema_version: 1,
|
||||
cached_at: Utc::now().to_rfc3339(),
|
||||
timestamp: Utc::now().timestamp(),
|
||||
etag: Some("\"sample-etag\"".into()),
|
||||
items: items.clone(),
|
||||
};
|
||||
|
||||
let cache_file = cache_dir.join("catalogue_cache.json");
|
||||
fsx::atomic_write_json(&cache_file, &cached_doc).expect("write cache");
|
||||
|
||||
// 2. Read without force refresh -> should return cached doc instantly without network
|
||||
let resp = fetch_or_load_catalogue(cache_dir, false).expect("load from cache");
|
||||
assert_eq!(resp.total_count, 1);
|
||||
assert_eq!(resp.items[0].name, "cached-mod");
|
||||
assert!(!resp.is_offline);
|
||||
|
||||
// 3. Corrupt the cache file -> test resilience
|
||||
fs::write(&cache_file, b"NOT_A_VALID_JSON").expect("write corrupt cache");
|
||||
let overlay = load_coa_overlay(None);
|
||||
let fallback_resp = try_offline_fallback(&cache_file, None, &overlay).expect("fallback must succeed");
|
||||
assert!(fallback_resp.is_offline);
|
||||
assert!(!fallback_resp.items.is_empty(), "Fallback must supply overlay items even on corrupt cache");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,132 @@
|
||||
{
|
||||
"version": 1,
|
||||
"description": "Curated CoA compatibility and recommendation overlay for AzerothCore modules",
|
||||
"rules": [
|
||||
{
|
||||
"repo_slug": "corfirean/mod-coa-playerbots",
|
||||
"status": "Recommended",
|
||||
"is_recommended": true,
|
||||
"reason": "Official companion bots for groups, dungeons and guild in Conquest of Azeroth."
|
||||
},
|
||||
{
|
||||
"repo_slug": "corfirean/mod-coa-content-scaling",
|
||||
"status": "Recommended",
|
||||
"is_recommended": true,
|
||||
"reason": "Official dynamic dungeon and raid scaling system with solo modes."
|
||||
},
|
||||
{
|
||||
"repo_slug": "zyth45/mod-playerbots",
|
||||
"status": "Recommended",
|
||||
"is_recommended": true,
|
||||
"reason": "SQUID's Playerbots with full autonomous AI. Mutually exclusive with CoA Companions."
|
||||
},
|
||||
{
|
||||
"repo_slug": "corfirean/azerothcore-wotlk-coa",
|
||||
"status": "Recommended",
|
||||
"is_recommended": true,
|
||||
"reason": "Official Conquest of Azeroth modular core features."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-npc-buffer",
|
||||
"status": "Verified",
|
||||
"is_recommended": true,
|
||||
"reason": "NPC buff master offering spells, sickness removal, and player restoration. Verified dynamic DLL on CoA Plugin SDK."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-congrats-on-level",
|
||||
"status": "Verified",
|
||||
"is_recommended": true,
|
||||
"reason": "Level-up celebration animations, fireworks and announcements. Verified dynamic DLL on CoA Plugin SDK."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-npc-enchanter",
|
||||
"status": "Recommended",
|
||||
"is_recommended": true,
|
||||
"reason": "Official NPC equipment enchanting module."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-reward-played-time",
|
||||
"status": "Verified",
|
||||
"is_recommended": true,
|
||||
"reason": "Periodic rewards and tokens granted based on active playtime. Verified dynamic DLL on CoA Plugin SDK."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-solocraft",
|
||||
"status": "RequiresAdapter",
|
||||
"is_recommended": true,
|
||||
"reason": "Dynamically boosts player stats in group content. Verified DLL build; requires calibration with CoA Content Scaling."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-cfbg",
|
||||
"status": "Verified",
|
||||
"is_recommended": false,
|
||||
"reason": "Cross-faction battlegrounds system. Built into CoA core fork."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-duel-reset",
|
||||
"status": "Verified",
|
||||
"is_recommended": false,
|
||||
"reason": "Resets health, mana, cooldowns and auras after duels. Verified dynamic DLL."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-pvp-titles",
|
||||
"status": "Verified",
|
||||
"is_recommended": false,
|
||||
"reason": "Classic PvP rank titles awarded based on honorable kills."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-starter-guild",
|
||||
"status": "Verified",
|
||||
"is_recommended": false,
|
||||
"reason": "Automatically invites newly created characters into a designated starter guild."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-skip-dk-starting-area",
|
||||
"status": "Verified",
|
||||
"is_recommended": false,
|
||||
"reason": "Allows Death Knights to skip the Scarlet Enclave starter zone."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-learn-spells",
|
||||
"status": "Incompatible",
|
||||
"is_recommended": false,
|
||||
"reason": "Directly conflicts with CoA classless progression & spell draft: automatically grants standard class spells, breaking player builds."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-autobalance",
|
||||
"status": "Incompatible",
|
||||
"is_recommended": false,
|
||||
"reason": "Direct gameplay authority collision with mod-coa-content-scaling: both systems attempt to dynamically scale creature health and damage."
|
||||
},
|
||||
{
|
||||
"repo_slug": "zhengpeiru21/mod-individual-progression",
|
||||
"status": "Incompatible",
|
||||
"is_recommended": false,
|
||||
"reason": "Conflicts with CoA progression curve, dungeon level brackets, and content scaling gating."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-arac",
|
||||
"status": "Incompatible",
|
||||
"is_recommended": false,
|
||||
"reason": "Incompatible with CoA custom races DBC table (Esteria, etc.) and expanded race limits."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-ahbot",
|
||||
"status": "Blocked",
|
||||
"is_recommended": false,
|
||||
"reason": "Upstream repository has missing script loader entrypoint (Addmod_ahbotScripts) causing compilation and linking failures. Use official mod-ah-bot-plus instead."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-eluna",
|
||||
"status": "RequiresAdapter",
|
||||
"is_recommended": false,
|
||||
"reason": "Requires external LuaJIT runtime and custom CoA spell system exports."
|
||||
},
|
||||
{
|
||||
"repo_slug": "azerothcore/mod-transmog",
|
||||
"status": "RequiresAdapter",
|
||||
"is_recommended": false,
|
||||
"reason": "Redundant: CoA already provides a built-in wardrobe and transmog system configured in coa.conf."
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -12,6 +12,7 @@ pub mod allsettings;
|
||||
pub mod analyzer;
|
||||
pub mod backup;
|
||||
pub mod build_engine;
|
||||
pub mod catalogue;
|
||||
pub mod channels;
|
||||
pub mod cleanbase;
|
||||
pub mod client;
|
||||
|
||||
Reference in new issue
Block a user