Skip to main content

qualia_core_db/services/solid_ldp/
bundle.rs

1//! Build a Solid-portable leave/migrate bundle from Quins.
2//!
3//! Solid stores **RDF triples/quads**, not Quins. This module projects filtered
4//! Quins into Turtle / N-Quads / JSON-LD plus a WAC ACL and a JSON-LD manifest
5//! that Solid-Databox (or any LDP server) can import with ordinary PUT.
6
7use std::collections::HashMap;
8use std::io::Write;
9
10use crate::sparql_library::serialisers::rdf_serializers::{
11    serialize_to_jsonld_compact, serialize_to_nquads, serialize_to_turtle,
12};
13use crate::NQuin;
14
15use super::consent::{export_outcome_summary, require_sanctuary_choice, SanctuaryExportChoice};
16use super::filter::{filter_for_egress, EgressStats, SolidEgressPolicy};
17use super::terms::{write_iri, write_object};
18
19/// Formats written into a leave-path bundle.
20#[derive(Debug, Clone, Copy, PartialEq, Eq)]
21pub struct SolidBundleFormats {
22    pub turtle: bool,
23    pub nquads: bool,
24    pub jsonld: bool,
25    pub acl: bool,
26}
27
28impl Default for SolidBundleFormats {
29    fn default() -> Self {
30        Self {
31            turtle: true,
32            nquads: true,
33            jsonld: true,
34            acl: true,
35        }
36    }
37}
38
39/// Options for building a migration bundle.
40#[derive(Debug, Clone, Default)]
41pub struct SolidMigrationOptions {
42    /// Required when sanctuary/restricted quins are present.
43    pub sanctuary_choice: SanctuaryExportChoice,
44    pub formats: SolidBundleFormats,
45    /// Optional owner WebID for ACL (default `urn:qualia:owner`).
46    pub owner_webid: Option<String>,
47    /// When true, emit public `foaf:Agent` Read — only for deliberately public graphs.
48    /// Default false (QW-10: never auto permissive-commons).
49    pub grant_public_read: bool,
50}
51
52impl SolidMigrationOptions {
53    fn egress_policy(&self) -> SolidEgressPolicy {
54        SolidEgressPolicy {
55            include_restricted: self.sanctuary_choice.includes_restricted(),
56        }
57    }
58}
59
60/// In-memory Solid leave bundle (files a Databox can LDP-PUT).
61#[derive(Debug, Clone)]
62pub struct SolidMigrationBundle {
63    pub turtle: Option<String>,
64    pub nquads: Option<String>,
65    pub jsonld: Option<String>,
66    pub acl: Option<String>,
67    pub manifest_jsonld: String,
68    pub stats: EgressStats,
69    pub sanctuary_choice: SanctuaryExportChoice,
70    pub outcome_summary: String,
71    pub engine_version: &'static str,
72}
73
74const ENGINE_VERSION: &str = "0.0.39";
75
76/// Build a portable Solid RDF bundle from Quins (+ optional Q42LEX map).
77///
78/// Fails with `SANCTUARY_CHOICE_REQUIRED` when sanctuary data is present and
79/// `sanctuary_choice` is still `Unset`.
80pub fn build_migration_bundle(
81    quins: &[NQuin],
82    lexicon: Option<&HashMap<u64, String>>,
83    opts: &SolidMigrationOptions,
84) -> Result<SolidMigrationBundle, String> {
85    require_sanctuary_choice(quins, opts.sanctuary_choice)?;
86    let policy = opts.egress_policy();
87    let mut filtered = Vec::with_capacity(quins.len());
88    let stats = filter_for_egress(quins, policy, &mut filtered);
89
90    let turtle = if opts.formats.turtle {
91        Some(serialize_turtle_lex(&filtered, lexicon)?)
92    } else {
93        None
94    };
95    let nquads = if opts.formats.nquads {
96        Some(serialize_nquads_lex(&filtered, lexicon)?)
97    } else {
98        None
99    };
100    let jsonld = if opts.formats.jsonld {
101        let mut buf = Vec::new();
102        serialize_to_jsonld_compact(&mut buf, &filtered)?;
103        Some(String::from_utf8(buf).map_err(|e| e.to_string())?)
104    } else {
105        None
106    };
107    let acl = if opts.formats.acl {
108        Some(render_acl(
109            opts.owner_webid.as_deref().unwrap_or("urn:qualia:owner"),
110            opts.grant_public_read,
111        ))
112    } else {
113        None
114    };
115
116    let manifest_jsonld = render_manifest(&stats, opts, turtle.as_deref(), nquads.as_deref());
117    let outcome_summary = export_outcome_summary(opts.sanctuary_choice, &stats);
118
119    Ok(SolidMigrationBundle {
120        turtle,
121        nquads,
122        jsonld,
123        acl,
124        manifest_jsonld,
125        stats,
126        sanctuary_choice: opts.sanctuary_choice,
127        outcome_summary,
128        engine_version: ENGINE_VERSION,
129    })
130}
131
132/// Lexicon-aware Turtle (preferred over demo-only `serialize_to_turtle` for leave).
133fn serialize_turtle_lex(
134    quins: &[NQuin],
135    lex: Option<&HashMap<u64, String>>,
136) -> Result<String, String> {
137    let mut out = Vec::new();
138    writeln!(&mut out, "@prefix acl: <http://www.w3.org/ns/auth/acl#> .")
139        .map_err(|e| e.to_string())?;
140    writeln!(&mut out, "@prefix foaf: <http://xmlns.com/foaf/0.1/> .")
141        .map_err(|e| e.to_string())?;
142    writeln!(
143        &mut out,
144        "@prefix qualia: <https://webizen.org/ld/vocab/> ."
145    )
146    .map_err(|e| e.to_string())?;
147    writeln!(&mut out).map_err(|e| e.to_string())?;
148
149    // Group by subject for valid Turtle blocks.
150    let mut order: Vec<u64> = Vec::new();
151    let mut map: HashMap<u64, Vec<&NQuin>> = HashMap::new();
152    for q in quins {
153        let bucket = map.entry(q.subject).or_default();
154        if bucket.is_empty() {
155            order.push(q.subject);
156        }
157        bucket.push(q);
158    }
159    for subject in order {
160        let rows = map.remove(&subject).unwrap_or_default();
161        write_iri(subject, lex, &mut out).map_err(|e| e.to_string())?;
162        for (i, quin) in rows.iter().enumerate() {
163            if i == 0 {
164                write!(&mut out, " ").map_err(|e| e.to_string())?;
165            } else {
166                write!(&mut out, " ;\n    ").map_err(|e| e.to_string())?;
167            }
168            write_iri(quin.predicate, lex, &mut out).map_err(|e| e.to_string())?;
169            write!(&mut out, " ").map_err(|e| e.to_string())?;
170            write_object(quin.object, lex, &mut out).map_err(|e| e.to_string())?;
171        }
172        writeln!(&mut out, " .").map_err(|e| e.to_string())?;
173    }
174    String::from_utf8(out).map_err(|e| e.to_string())
175}
176
177fn serialize_nquads_lex(
178    quins: &[NQuin],
179    lex: Option<&HashMap<u64, String>>,
180) -> Result<String, String> {
181    // Prefer lexicon-aware lines so named-graph context is preserved for Solid.
182    if lex.is_none() {
183        let mut buf = Vec::new();
184        serialize_to_nquads(&mut buf, quins)?;
185        return String::from_utf8(buf).map_err(|e| e.to_string());
186    }
187    let mut out = Vec::new();
188    for q in quins {
189        write_iri(q.subject, lex, &mut out).map_err(|e| e.to_string())?;
190        write!(&mut out, " ").map_err(|e| e.to_string())?;
191        write_iri(q.predicate, lex, &mut out).map_err(|e| e.to_string())?;
192        write!(&mut out, " ").map_err(|e| e.to_string())?;
193        write_object(q.object, lex, &mut out).map_err(|e| e.to_string())?;
194        write!(&mut out, " ").map_err(|e| e.to_string())?;
195        write_iri(q.context, lex, &mut out).map_err(|e| e.to_string())?;
196        writeln!(&mut out, " .").map_err(|e| e.to_string())?;
197    }
198    String::from_utf8(out).map_err(|e| e.to_string())
199}
200
201fn render_acl(owner_webid: &str, grant_public_read: bool) -> String {
202    let mut s = String::from(
203        "@prefix acl: <http://www.w3.org/ns/auth/acl#> .\n\
204         @prefix foaf: <http://xmlns.com/foaf/0.1/> .\n\n\
205         # Generated by QualiaDB Solid leave/migrate exporter\n\n\
206         <#ownerAccess> a acl:Authorization ;\n",
207    );
208    s.push_str(&format!("    acl:agent <{owner_webid}> ;\n"));
209    s.push_str(
210        "    acl:accessTo <./data.ttl> ;\n\
211            acl:mode acl:Read, acl:Write, acl:Control .\n",
212    );
213    if grant_public_read {
214        s.push_str(
215            "\n<#publicAccess> a acl:Authorization ;\n\
216                acl:agentClass foaf:Agent ;\n\
217                acl:accessTo <./data.ttl> ;\n\
218                acl:mode acl:Read .\n",
219        );
220    }
221    s
222}
223
224fn render_manifest(
225    stats: &EgressStats,
226    opts: &SolidMigrationOptions,
227    turtle: Option<&str>,
228    nquads: Option<&str>,
229) -> String {
230    let resources = {
231        let mut parts = Vec::new();
232        if turtle.is_some() {
233            parts.push(r#"{ "@id": "data.ttl", "dcterms:format": "text/turtle" }"#);
234        }
235        if nquads.is_some() {
236            parts.push(r#"{ "@id": "data.nq", "dcterms:format": "application/n-quads" }"#);
237        }
238        if opts.formats.jsonld {
239            parts.push(r#"{ "@id": "data.jsonld", "dcterms:format": "application/ld+json" }"#);
240        }
241        if opts.formats.acl {
242            parts.push(r#"{ "@id": "data.ttl.acl", "dcterms:format": "text/turtle" }"#);
243        }
244        parts.join(",\n    ")
245    };
246    format!(
247        r#"{{
248  "@context": {{
249    "schema": "https://schema.org/",
250    "dcterms": "http://purl.org/dc/terms/",
251    "qualia": "https://webizen.org/ld/vocab/"
252  }},
253  "@type": "qualia:SolidMigrationBundle",
254  "schema:softwareVersion": "{ENGINE_VERSION}",
255  "qualia:sourceEngine": "QualiaDB",
256  "qualia:target": "Solid LDP (triples/quads; not Quins)",
257  "qualia:sanctuaryChoice": "{}",
258  "qualia:includeRestricted": {},
259  "qualia:grantPublicRead": {},
260  "qualia:stats": {{
261    "scanned": {},
262    "exported": {},
263    "redactedClassified": {},
264    "redactedRestricted": {},
265    "skippedParity": {}
266  }},
267  "schema:hasPart": [
268    {resources}
269  ]
270}}"#,
271        opts.sanctuary_choice.as_str(),
272        opts.sanctuary_choice.includes_restricted(),
273        opts.grant_public_read,
274        stats.scanned,
275        stats.exported,
276        stats.redacted_classified,
277        stats.redacted_restricted,
278        stats.skipped_parity,
279    )
280}
281
282/// Fallback when no custom lex map: use shared Turtle serializer (demo lex).
283#[allow(dead_code)]
284pub fn serialize_turtle_shared(quins: &[NQuin]) -> Result<String, String> {
285    let mut buf = Vec::new();
286    serialize_to_turtle(&mut buf, quins)?;
287    String::from_utf8(buf).map_err(|e| e.to_string())
288}
289
290#[cfg(test)]
291mod tests {
292    use super::*;
293    use crate::q_hash;
294
295    fn alice_knows_bob() -> NQuin {
296        let mut q = NQuin {
297            subject: q_hash("Alice"),
298            predicate: q_hash("knows"),
299            object: q_hash("Bob"),
300            context: q_hash("http://example.org/graph"),
301            metadata: 0,
302            parity: 0,
303        };
304        q.recalculate_parity();
305        q
306    }
307
308    #[test]
309    fn bundle_emits_turtle_and_redacts_classified() {
310        let public = alice_knows_bob();
311        let mut classified = alice_knows_bob();
312        classified.set_sensitivity_byte(NQuin::SENSITIVITY_CLASSIFIED);
313        classified.recalculate_parity();
314
315        let bundle = build_migration_bundle(
316            &[public, classified],
317            None,
318            &SolidMigrationOptions::default(),
319        )
320        .unwrap();
321        assert_eq!(bundle.stats.exported, 1);
322        assert_eq!(bundle.stats.redacted_classified, 1);
323        let ttl = bundle.turtle.as_deref().unwrap();
324        assert!(ttl.contains("schema.org/knows") || ttl.contains("quin:hash/"));
325        assert!(bundle.manifest_jsonld.contains("SolidMigrationBundle"));
326        assert!(!bundle.acl.as_deref().unwrap().contains("foaf:Agent"));
327    }
328
329    #[test]
330    fn public_read_acl_only_when_requested() {
331        let q = alice_knows_bob();
332        let mut opts = SolidMigrationOptions::default();
333        opts.grant_public_read = true;
334        let bundle = build_migration_bundle(&[q], None, &opts).unwrap();
335        assert!(bundle.acl.as_deref().unwrap().contains("foaf:Agent"));
336    }
337}