Skip to main content

qualia_core_db/services/
webtorrent_seeder.rs

1//! Qualia-native WebTorrent seeder — HTTP web seeds for Permissive Commons
2//! `.q42` volumes and legacy `.c.q42` ontology artifacts.
3//!
4//! This is Commons ICN transport, not a dump of every Q42 file. Unified `.q42`
5//! volumes are classified before they enter the registry: Sanctuary, medical,
6//! bilateral, mixed, and unmarked personal volumes are refused. They travel
7//! on SocialWebNet (pairwise DID / WireGuard) or stay local.
8//!
9//! Browser WebTorrent clients leech via the `ws=` magnet parameter pointing at
10//! `/torrent/webseed/{info_hash}`. One file, one SHA-1 info-hash. A Q42 volume
11//! set publishes the root plus each child as its own magnet.
12
13#![cfg(not(target_arch = "wasm32"))]
14
15use std::collections::HashMap;
16use std::fs;
17use std::path::{Path, PathBuf};
18use std::sync::atomic::{AtomicU64, Ordering};
19use std::sync::{OnceLock, RwLock};
20
21use serde::{Deserialize, Serialize};
22
23static REGISTRY: OnceLock<RwLock<HashMap<String, SeedRecord>>> = OnceLock::new();
24static BYTES_SERVED_SESSION: AtomicU64 = AtomicU64::new(0);
25static GLOBAL_POLICY: OnceLock<RwLock<SeederBandwidthPolicy>> = OnceLock::new();
26
27#[derive(Debug, Clone, Serialize, Deserialize)]
28pub struct SeederBandwidthPolicy {
29    pub global_limit_kbps: u32,
30    pub metered_mode: bool,
31}
32
33impl Default for SeederBandwidthPolicy {
34    fn default() -> Self {
35        Self {
36            global_limit_kbps: 1024,
37            metered_mode: true,
38        }
39    }
40}
41
42#[derive(Debug, Clone, Serialize)]
43pub struct SeedRecord {
44    pub info_hash: String,
45    pub file_path: PathBuf,
46    pub display_name: String,
47    pub ontology_id: String,
48    pub file_size: u64,
49    pub bytes_uploaded_total: u64,
50    pub bytes_uploaded_session: u64,
51    pub download_count: u64,
52    pub deprecated: bool,
53    /// Human principal asserted this is a Commons catalog. Never overrides
54    /// Quin-level Sanctuary / medical / bilateral bits.
55    pub commons_asserted: bool,
56}
57
58#[derive(Debug, Clone, Deserialize)]
59pub struct RegisterSeedRequest {
60    pub info_hash: String,
61    pub file_path: String,
62    pub display_name: String,
63    pub ontology_id: String,
64    #[serde(default)]
65    pub bandwidth_limit_kbps: u32,
66    /// Assert this file is a Permissive Commons catalog (ontologies, not a
67    /// person's medical record). Default false = fail closed.
68    #[serde(default)]
69    pub commons_asserted: bool,
70}
71
72#[derive(Debug, Clone, Deserialize)]
73pub struct UnregisterSeedRequest {
74    pub info_hash: String,
75}
76
77fn registry() -> &'static RwLock<HashMap<String, SeedRecord>> {
78    REGISTRY.get_or_init(|| RwLock::new(HashMap::new()))
79}
80
81fn policy_lock() -> &'static RwLock<SeederBandwidthPolicy> {
82    GLOBAL_POLICY.get_or_init(|| RwLock::new(SeederBandwidthPolicy::default()))
83}
84
85/// Trims and lowercases a btih info-hash string.
86pub fn normalize_info_hash(raw: &str) -> String {
87    raw.trim().to_ascii_lowercase()
88}
89
90/// Builds a `magnet:?xt=urn:btih:` URI with display name and a `ws=` webseed pointing at the local daemon.
91pub fn build_magnet_uri(info_hash_sha1: &str, display_name: &str, daemon_port: u16) -> String {
92    let hash = normalize_info_hash(info_hash_sha1);
93    let dn = urlencoding::encode(display_name);
94    let ws_url = format!("http://127.0.0.1:{daemon_port}/torrent/webseed/{hash}");
95    let ws = urlencoding::encode(&ws_url);
96    format!("magnet:?xt=urn:btih:{hash}&dn={dn}&ws={ws}")
97}
98
99/// Returns `magnet` unchanged when it already carries a `ws=` webseed; otherwise builds one via `build_magnet_uri`.
100pub fn ensure_magnet_webseed(
101    magnet: &str,
102    info_hash: &str,
103    display_name: &str,
104    port: u16,
105) -> String {
106    if magnet.contains("&ws=") || magnet.contains("?ws=") {
107        return magnet.to_string();
108    }
109    build_magnet_uri(info_hash, display_name, port)
110}
111
112/// Streams `path` through SHA-1 (8 KiB blocks) and returns lowercase hex.
113pub fn sha1_file(path: &Path) -> Result<String, String> {
114    use sha1::{Digest, Sha1};
115    let mut file = fs::File::open(path).map_err(|e| e.to_string())?;
116    let mut hasher = Sha1::new();
117    let mut buf = [0u8; 8192];
118    loop {
119        let n = std::io::Read::read(&mut file, &mut buf).map_err(|e| e.to_string())?;
120        if n == 0 {
121            break;
122        }
123        hasher.update(&buf[..n]);
124    }
125    Ok(hasher
126        .finalize()
127        .iter()
128        .map(|b| format!("{b:02x}"))
129        .collect())
130}
131
132/// Replaces the global seeder bandwidth policy.
133pub fn set_bandwidth_policy(policy: SeederBandwidthPolicy) {
134    *policy_lock().write().unwrap() = policy;
135}
136
137/// Current bandwidth policy.
138pub fn get_bandwidth_policy() -> SeederBandwidthPolicy {
139    policy_lock().read().unwrap().clone()
140}
141
142/// Validates the file exists, classifies unified `.q42` volumes as Commons/Sanctuary by `commons_asserted`, and records the seed.
143pub fn register_seed(req: RegisterSeedRequest) -> Result<SeedRecord, String> {
144    let hash = normalize_info_hash(&req.info_hash);
145    let path = PathBuf::from(&req.file_path);
146    if !path.is_file() {
147        return Err(format!("Seed file not found: {}", path.display()));
148    }
149    if crate::q42_volume::is_unified_volume(&path).unwrap_or(false) {
150        let intent = if req.commons_asserted {
151            crate::q42_volume::PublicationIntent::CommonsCatalog
152        } else {
153            crate::q42_volume::PublicationIntent::Default
154        };
155        let verdict = crate::q42_volume::classify_q42_path(&path, intent)
156            .map_err(|e| format!("Q42 publication denied: {e}"))?;
157        if !verdict.may_http_webseed {
158            return Err(verdict.reason);
159        }
160    }
161    let computed = sha1_file(&path)?;
162    if computed != hash {
163        return Err(format!(
164            "Info hash mismatch: file SHA1 {computed} != expected {hash}"
165        ));
166    }
167    let file_size = fs::metadata(&path).map_err(|e| e.to_string())?.len();
168    let record = SeedRecord {
169        info_hash: hash.clone(),
170        file_path: path,
171        display_name: req.display_name,
172        ontology_id: req.ontology_id,
173        file_size,
174        bytes_uploaded_total: 0,
175        bytes_uploaded_session: 0,
176        download_count: 0,
177        deprecated: false,
178        commons_asserted: req.commons_asserted,
179    };
180    registry().write().unwrap().insert(hash, record.clone());
181    println!(
182        "[Qualia WebTorrent] Seeding {} ({} bytes) as {}",
183        record.ontology_id, record.file_size, record.info_hash
184    );
185    Ok(record)
186}
187
188/// Removes the seed for `info_hash`; `true` when it existed.
189pub fn unregister_seed(info_hash: &str) -> bool {
190    let hash = normalize_info_hash(info_hash);
191    registry().write().unwrap().remove(&hash).is_some()
192}
193
194/// Marks the seed deprecated; `true` when it existed.
195pub fn deprecate_seed(info_hash: &str) -> bool {
196    let hash = normalize_info_hash(info_hash);
197    if let Some(rec) = registry().write().unwrap().get_mut(&hash) {
198        rec.deprecated = true;
199        // DHT Caching for intermittent connections: We retain the record to resume seeding
200        // seamlessly if the node drops offline and reconnects, but mark it as deprecated.
201        return true;
202    }
203    false
204}
205
206/// All currently active (non-deprecated) seed records.
207pub fn list_active_seeds() -> Vec<SeedRecord> {
208    registry().read().unwrap().values().cloned().collect()
209}
210
211/// `SeedRecord` for `info_hash`, or `None`.
212pub fn lookup_seed(info_hash: &str) -> Option<SeedRecord> {
213    registry()
214        .read()
215        .unwrap()
216        .get(&normalize_info_hash(info_hash))
217        .cloned()
218}
219
220/// Accumulates served bytes for `info_hash` in telemetry.
221pub fn record_bytes_served(info_hash: &str, bytes: u64) {
222    let hash = normalize_info_hash(info_hash);
223    BYTES_SERVED_SESSION.fetch_add(bytes, Ordering::Relaxed);
224    if let Some(rec) = registry().write().unwrap().get_mut(&hash) {
225        rec.bytes_uploaded_session += bytes;
226        rec.bytes_uploaded_total += bytes;
227    }
228}
229
230/// Increments the full-download counter for `info_hash`.
231pub fn record_full_download(info_hash: &str) {
232    let hash = normalize_info_hash(info_hash);
233    if let Some(rec) = registry().write().unwrap().get_mut(&hash) {
234        rec.download_count += 1;
235    }
236}
237
238#[derive(Debug, Clone, Serialize)]
239pub struct SeederTelemetry {
240    pub seeders: usize,
241    pub leechers: u64,
242    pub speed: String,
243    pub status: String,
244    pub uploaded_session_kb: u64,
245    pub uploaded_total_kb: u64,
246    pub active_ontologies: Vec<String>,
247    pub global_bandwidth_kbps: u32,
248    pub metered_mode: bool,
249    pub seeder: String,
250}
251
252/// Snapshot of global seeder telemetry.
253pub fn telemetry() -> SeederTelemetry {
254    let seeds = list_active_seeds();
255    let policy = get_bandwidth_policy();
256    let uploaded_session = BYTES_SERVED_SESSION.load(Ordering::Relaxed);
257    let uploaded_total: u64 = seeds.iter().map(|s| s.bytes_uploaded_total).sum();
258    let limit = policy.global_limit_kbps;
259    let speed = if limit == 0 {
260        "unlimited".to_string()
261    } else {
262        format!("{limit} KiB/s cap")
263    };
264    SeederTelemetry {
265        seeders: seeds.len(),
266        leechers: seeds.iter().map(|s| s.download_count).sum(),
267        speed,
268        status: if seeds.is_empty() { "idle" } else { "seeding" }.to_string(),
269        uploaded_session_kb: uploaded_session / 1024,
270        uploaded_total_kb: uploaded_total / 1024,
271        active_ontologies: seeds.iter().map(|s| s.ontology_id.clone()).collect(),
272        global_bandwidth_kbps: policy.global_limit_kbps,
273        metered_mode: policy.metered_mode,
274        seeder: "qualia-daemon".to_string(),
275    }
276}
277
278/// Reload active seeds from `{storage}/Index/workbench.jsonl` on daemon boot.
279pub fn sync_from_workbench(storage_path: &str, daemon_port: u16) {
280    let path = Path::new(storage_path)
281        .join("Index")
282        .join("workbench.jsonl");
283    if !path.is_file() {
284        return;
285    }
286    let Ok(text) = fs::read_to_string(&path) else {
287        return;
288    };
289    for line in text.lines() {
290        if line.trim().is_empty() {
291            continue;
292        }
293        let Ok(v) = serde_json::from_str::<serde_json::Value>(line) else {
294            continue;
295        };
296        let seed_active = v["seed_active"].as_bool().unwrap_or(false);
297        let seed_enabled = v["torrent"]["seed_enabled"].as_bool().unwrap_or(false);
298        if !seed_active || !seed_enabled {
299            continue;
300        }
301        let info_hash = v["info_hash_sha1"].as_str().unwrap_or_default();
302        let file_path = v["c_q42_path"].as_str().unwrap_or_default();
303        let ontology_id = v["ontology_id"].as_str().unwrap_or_default();
304        let title = v["title"].as_str().unwrap_or(ontology_id);
305        if info_hash.is_empty() || file_path.is_empty() {
306            continue;
307        }
308        let _ = register_seed(RegisterSeedRequest {
309            info_hash: info_hash.to_string(),
310            file_path: file_path.to_string(),
311            display_name: format!("{title}.c.q42"),
312            ontology_id: ontology_id.to_string(),
313            bandwidth_limit_kbps: v["torrent"]["bandwidth_limit_kbps"].as_u64().unwrap_or(512)
314                as u32,
315            commons_asserted: true,
316        });
317        if let Some(magnet) = v["magnet_uri"].as_str() {
318            let updated =
319                ensure_magnet_webseed(magnet, info_hash, &format!("{title}.c.q42"), daemon_port);
320            if updated != magnet {
321                // Magnet refresh is persisted by the client on next policy save.
322                let _ = updated;
323            }
324        }
325    }
326    let n = list_active_seeds().len();
327    if n > 0 {
328        println!("[Qualia WebTorrent] Restored {n} active seed(s) from workbench");
329    }
330}
331
332#[cfg(test)]
333mod tests {
334    use super::*;
335
336    #[test]
337    fn magnet_includes_qualia_webseed() {
338        let m = build_magnet_uri("abc123def", "demo.q42", 4242);
339        assert!(m.contains("urn:btih:abc123def"));
340        assert!(m.contains("ws=http"));
341        assert!(m.contains("abc123def"));
342        assert!(m.contains("torrent"));
343        assert!(m.contains("webseed"));
344    }
345
346    #[test]
347    fn normalize_hash_lowercase() {
348        assert_eq!(normalize_info_hash("ABCD"), "abcd");
349    }
350
351    #[test]
352    fn register_seed_refuses_medical_q42() {
353        use crate::q42_volume::write_unified_volume;
354        use crate::NQuin;
355        use std::collections::HashMap;
356
357        let file = tempfile::NamedTempFile::new().unwrap();
358        let mut quin = NQuin {
359            subject: 1,
360            predicate: 2,
361            object: 3,
362            context: 0,
363            metadata: 0,
364            parity: 0,
365        };
366        quin.set_sensitivity_byte(NQuin::SENSITIVITY_CLASSIFIED);
367        quin.set_sensitivity_tier(NQuin::SENSITIVITY_TIER_MEDICAL);
368        write_unified_volume(file.path(), &HashMap::new(), &[(3, 3)], &[vec![quin]]).unwrap();
369        let hash = sha1_file(file.path()).unwrap();
370        let err = register_seed(RegisterSeedRequest {
371            info_hash: hash,
372            file_path: file.path().display().to_string(),
373            display_name: "pep-record.q42".into(),
374            ontology_id: "should-not-seed".into(),
375            bandwidth_limit_kbps: 1,
376            commons_asserted: true,
377        })
378        .unwrap_err();
379        assert!(
380            err.contains("publication denied")
381                || err.contains("Selfhood")
382                || err.contains("medical"),
383            "{err}"
384        );
385    }
386}