wiki.rs 94.6%

158 of 167 lines run, 42 of 71 functions · run #507 on main · run missed

//! Wikis (hub spec §6.11, oxygenhub#104): Markdown pages kept as an
//! Oxygen repository of their own beside the code, under
//! `<data>/wikis/<owner>/<name>`, read and written on the web and cloned
//! or pushed as `OWNER/NAME.wiki`. A page `Getting-Started` is the file
//! `Getting-Started.md` on bookmark `main`; `_Sidebar.md` is the sidebar.
//! Web edits are changes authored by the user and signed by the hub as
//! their delegate, exactly as code edits are (§6.9).

use crate::repos::edits::{Committed, Signer};
use crate::repos::view::{self, ChangeView};
use crate::repos::{RepoError, RepoName};
use crate::Shared;
use oxy_core::hash::ChangeHash;
use oxy_core::identity::Domain;
use oxy_core::repo::{FileEdit, Repo};

pub const BOOKMARK: &str = "main";
pub const HOME: &str = "Home";
pub const SIDEBAR: &str = "_Sidebar";
/// The suffix a wiki's clone address carries: `OWNER/NAME.wiki`.
pub const SUFFIX: &str = ".wiki";
/// Pages searched at most.
const MAX_SEARCHED: usize = 500;

/// A page's name in a URL and file name: `Getting-Started`.
pub fn slug_ok(slug: &str) -> bool {
    !slug.is_empty()
        && slug.len() <= 100
        && slug.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.'))
        && !slug.contains("..")
        && !slug.starts_with('.')
        && !slug.ends_with('.')
}

/// `Getting Started` → `Getting-Started`.
pub fn slug_of(title: &str) -> String {
    title.split_whitespace().collect::<Vec<_>>().join("-")
}

/// `Getting-Started` → `Getting Started`.
pub fn title_of(slug: &str) -> String {
    slug.replace('-', " ")
}

pub fn path_of(slug: &str) -> String {
    format!("{slug}.md")
}

/// The page a file at the root is, if it is one.
pub fn slug_from_path(path: &str) -> Option<&str> {
    path.strip_suffix(".md").filter(|s| !s.contains('/') && slug_ok(s))
}

/// `OWNER/NAME.wiki` → the repository it belongs to, and whether it was
/// a wiki address at all.
pub fn parent_of(name: &RepoName) -> (RepoName, bool) {
    match name.name.strip_suffix(SUFFIX).and_then(|n| RepoName::new(&name.owner, n)) {
        Some(parent) => (parent, true),
        None => (name.clone(), false),
    }
}

pub fn exists(app: &Shared, repo: &RepoName) -> bool {
    app.wikis.exists(repo)
}

/// `main`'s heads, empty before the first page.
fn heads(r: &Repo) -> Result<Vec<ChangeHash>, RepoError> {
    Ok(r.bookmarks()?.into_iter().find(|b| b.name == BOOKMARK).map(|b| b.heads).unwrap_or_default())
}

/// A page's Markdown, `None` when there is no such page.
pub async fn page(app: &Shared, repo: &RepoName, slug: &str) -> Result<Option<String>, RepoError> {
    if !exists(app, repo) {
        return Ok(None);
    }
    let path = path_of(slug);
    app.wikis
        .read(repo, move |r, _| {
            let heads = heads(r)?;
            if heads.is_empty() {
                return Ok(None);
            }
            Ok(r.file_at(&path, Some(&heads)).ok().map(|b| String::from_utf8_lossy(&b).into_owned()))
        })
        .await
}

/// Every page, by slug, sorted; the sidebar and other `_` pages left out.
pub async fn pages(app: &Shared, repo: &RepoName) -> Result<Vec<String>, RepoError> {
    if !exists(app, repo) {
        return Ok(vec![]);
    }
    app.wikis
        .read(repo, |r, cache| {
            let heads = heads(r)?;
            if heads.is_empty() {
                return Ok(vec![]);
            }
            let loaded = cache.load(r, &heads)?;
            let mut out: Vec<String> =
                loaded.snapshot.files.keys().filter_map(|p| slug_from_path(p)).filter(|s| !s.starts_with('_')).map(String::from).collect();
            out.sort_by_key(|s| s.to_lowercase());
            Ok(out)
        })
        .await
}

/// Pages whose text holds `q`, with a line that does: (slug, snippet).
pub async fn search(app: &Shared, repo: &RepoName, q: &str) -> Result<Vec<(String, String)>, RepoError> {
    let q = q.trim().to_lowercase();
    if q.is_empty() || !exists(app, repo) {
        return Ok(vec![]);
    }
    app.wikis
        .read(repo, move |r, cache| {
            let heads = heads(r)?;
            if heads.is_empty() {
                return Ok(vec![]);
            }
            let loaded = cache.load(r, &heads)?;
            let mut out = vec![];
            for path in loaded.snapshot.files.keys().take(MAX_SEARCHED) {
                let Some(slug) = slug_from_path(path) else { continue };
                let Ok(bytes) = r.file_at(path, Some(&heads)) else { continue };
                let text = String::from_utf8_lossy(&bytes);
                let hit = slug.to_lowercase().contains(&q) || text.to_lowercase().contains(&q);
                if hit {
                    let line = text.lines().find(|l| l.to_lowercase().contains(&q)).unwrap_or("").trim();
                    out.push((slug.to_string(), line.chars().take(160).collect()));
                }
            }
            Ok(out)
        })
        .await
}

/// The changes that touched a page, newest first.
pub async fn history(app: &Shared, repo: &RepoName, slug: &str, limit: usize) -> Result<Vec<ChangeView>, RepoError> {
    if !exists(app, repo) {
        return Ok(vec![]);
    }
    let path = path_of(slug);
    app.wikis
        .read(repo, move |r, cache| {
            if heads(r)?.is_empty() {
                return Ok(vec![]);
            }
            let target = view::resolve(r, cache, BOOKMARK)?;
            Ok(view::history(r, cache, target, Some(&path), 0, limit)?.entries)
        })
        .await
}

/// Record `edits` as a change on the wiki's `main`, authored by the user
/// and signed by the hub as their delegate; the wiki is made on the first.
pub async fn commit(app: &Shared, repo: &RepoName, edits: Vec<FileEdit>, message: String, signer: Signer) -> Result<Committed, RepoError> {
    if !exists(app, repo) {
        // Bound to an id from the start, so it clones before any push.
        app.wikis.create(repo, Some(rand::random::<[u8; 16]>()))?;
    }
    app.wikis
        .write(repo, move |r, _| {
            let base_heads = heads(r)?;
            let author = signer.author.hash();
            let change = r.build_change(&base_heads, &edits, &message, author)?;
            let hash = change.hash();
            let sig = signer.hub_secret.sign(Domain::Change, &signer.hub_key, &hash);
            let mut state = r.load_state(&base_heads)?;
            state.add(change.clone()).map_err(|e| RepoError::Oxy(oxy_core::repo::RepoError::Msg(e.to_string())))?;
            let mut candidates = base_heads.clone();
            candidates.push(hash);
            let heads = state.maximal(&candidates);
            let update = r.host_ref_update(BOOKMARK, &heads, Some((&signer.hub_key, &signer.hub_secret)))?;
            let (old_state, new_state) = (update.old_state.to_hex(), update.new_state.to_hex());
            let report = r.apply_hosted(Some((change, vec![sig])), &[signer.hub_identity.clone(), signer.author.clone()], update)?;
            if let Some(refused) = report.results.iter().find(|x| !x.ok) {
                return Err(RepoError::Oxy(oxy_core::repo::RepoError::Msg(format!("the wiki refused the change: {}", refused.reason))));
            }
            Ok(Committed { change: hash, bookmark: BOOKMARK.into(), old_state, new_state, heads, report })
        })
        .await
}

/// Remove the wiki (to the trash), when the repository goes or an admin
/// asks under Settings › Advanced.
pub fn trash(app: &Shared, repo: &RepoName) -> Result<(), RepoError> {
    if exists(app, repo) {
        app.wikis.trash(repo)?;
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn slugs_titles_and_paths() {
        assert_eq!(slug_of("  Getting   Started "), "Getting-Started");
        assert_eq!(title_of("Getting-Started"), "Getting Started");
        assert_eq!(path_of("Home"), "Home.md");
        assert_eq!(slug_from_path("Home.md"), Some("Home"));
        assert_eq!(slug_from_path("docs/Home.md"), None);
        assert_eq!(slug_from_path("notes.txt"), None);
        assert!(slug_ok("_Sidebar") && slug_ok("v1.2-notes") && !slug_ok("") && !slug_ok("a/b") && !slug_ok("..") && !slug_ok("a b"));
    }
}

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

1		//! Wikis (hub spec §6.11, oxygenhub#104): Markdown pages kept as an
2		//! Oxygen repository of their own beside the code, under
3		//! `<data>/wikis/<owner>/<name>`, read and written on the web and cloned
4		//! or pushed as `OWNER/NAME.wiki`. A page `Getting-Started` is the file
5		//! `Getting-Started.md` on bookmark `main`; `_Sidebar.md` is the sidebar.
6		//! Web edits are changes authored by the user and signed by the hub as
7		//! their delegate, exactly as code edits are (§6.9).
8
9		use crate::repos::edits::{Committed, Signer};
10		use crate::repos::view::{self, ChangeView};
11		use crate::repos::{RepoError, RepoName};
12		use crate::Shared;
13		use oxy_core::hash::ChangeHash;
14		use oxy_core::identity::Domain;
15		use oxy_core::repo::{FileEdit, Repo};
16
17		pub const BOOKMARK: &str = "main";
18		pub const HOME: &str = "Home";
19		pub const SIDEBAR: &str = "_Sidebar";
20		/// The suffix a wiki's clone address carries: `OWNER/NAME.wiki`.
21		pub const SUFFIX: &str = ".wiki";
22		/// Pages searched at most.
23		const MAX_SEARCHED: usize = 500;
24
25		/// A page's name in a URL and file name: `Getting-Started`.
26	37×	pub fn slug_ok(slug: &str) -> bool {
27	37×	!slug.is_empty()
28	36×	&& slug.len() <= 100
29	213×	&& slug.chars().all(\|c\| c.is_ascii_alphanumeric() \|\| matches!(c, '-' \| '_' \| '.'))
30	34×	&& !slug.contains("..")
31	33×	&& !slug.starts_with('.')
32	33×	&& !slug.ends_with('.')
33	37×	}
34
35		/// `Getting Started` → `Getting-Started`.
36	4×	pub fn slug_of(title: &str) -> String {
37	4×	title.split_whitespace().collect::<Vec<_>>().join("-")
38	4×	}
39
40		/// `Getting-Started` → `Getting Started`.
41	29×	pub fn title_of(slug: &str) -> String {
42	29×	slug.replace('-', " ")
43	29×	}
44
45	31×	pub fn path_of(slug: &str) -> String {
46	31×	format!("{slug}.md")
47	31×	}
48
49		/// The page a file at the root is, if it is one.
50	16×	pub fn slug_from_path(path: &str) -> Option<&str> {
51	16×	path.strip_suffix(".md").filter(\|s\| !s.contains('/') && slug_ok(s))
52	16×	}
53
54		/// `OWNER/NAME.wiki` → the repository it belongs to, and whether it was
55		/// a wiki address at all.
56	4895×	pub fn parent_of(name: &RepoName) -> (RepoName, bool) {
57	4895×	match name.name.strip_suffix(SUFFIX).and_then(\|n\| RepoName::new(&name.owner, n)) {
58	55×	Some(parent) => (parent, true),
59	4840×	None => (name.clone(), false),
60		}
61	4895×	}
62
63	49×	pub fn exists(app: &Shared, repo: &RepoName) -> bool {
64	49×	app.wikis.exists(repo)
65	49×	}
66
67		/// `main`'s heads, empty before the first page.
68	39×	fn heads(r: &Repo) -> Result<Vec<ChangeHash>, RepoError> {
69	39×	Ok(r.bookmarks()?.into_iter().find(\|b\| b.name == BOOKMARK).map(\|b\| b.heads).unwrap_or_default())
70	39×	}
71
72		/// A page's Markdown, `None` when there is no such page.
73	24×	pub async fn page(app: &Shared, repo: &RepoName, slug: &str) -> Result<Option<String>, RepoError> {
74	24×	if !exists(app, repo) {
75	5×	return Ok(None);
76	19×	}
77	19×	let path = path_of(slug);
78	19×	app.wikis
79	19×	.read(repo, move \|r, _\| {
80	19×	let heads = heads(r)?;
81	19×	if heads.is_empty() {
82	0×	return Ok(None);
83	19×	}
84	19×	Ok(r.file_at(&path, Some(&heads)).ok().map(\|b\| String::from_utf8_lossy(&b).into_owned()))
85	19×	})
86	19×	.await
87	24×	}
88
89		/// Every page, by slug, sorted; the sidebar and other `_` pages left out.
90	11×	pub async fn pages(app: &Shared, repo: &RepoName) -> Result<Vec<String>, RepoError> {
91	11×	if !exists(app, repo) {
92	2×	return Ok(vec![]);
93	9×	}
94	9×	app.wikis
95	9×	.read(repo, \|r, cache\| {
96	9×	let heads = heads(r)?;
97	9×	if heads.is_empty() {
98	0×	return Ok(vec![]);
99	9×	}
100	9×	let loaded = cache.load(r, &heads)?;
101	9×	let mut out: Vec<String> =
102	12×	loaded.snapshot.files.keys().filter_map(\|p\| slug_from_path(p)).filter(\|s\| !s.starts_with('_')).map(String::from).collect();
103	9×	out.sort_by_key(\|s\| s.to_lowercase());
104	9×	Ok(out)
105	9×	})
106	9×	.await
107	11×	}
108
109		/// Pages whose text holds `q`, with a line that does: (slug, snippet).
110	1×	pub async fn search(app: &Shared, repo: &RepoName, q: &str) -> Result<Vec<(String, String)>, RepoError> {
111	1×	let q = q.trim().to_lowercase();
112	1×	if q.is_empty() \|\| !exists(app, repo) {
113	0×	return Ok(vec![]);
114	1×	}
115	1×	app.wikis
116	1×	.read(repo, move \|r, cache\| {
117	1×	let heads = heads(r)?;
118	1×	if heads.is_empty() {
119	0×	return Ok(vec![]);
120	1×	}
121	1×	let loaded = cache.load(r, &heads)?;
122	1×	let mut out = vec![];
123	1×	for path in loaded.snapshot.files.keys().take(MAX_SEARCHED) {
124	1×	let Some(slug) = slug_from_path(path) else { continue };
125	1×	let Ok(bytes) = r.file_at(path, Some(&heads)) else { continue };
126	1×	let text = String::from_utf8_lossy(&bytes);
127	1×	let hit = slug.to_lowercase().contains(&q) \|\| text.to_lowercase().contains(&q);
128	1×	if hit {
129	1×	let line = text.lines().find(\|l\| l.to_lowercase().contains(&q)).unwrap_or("").trim();
130	1×	out.push((slug.to_string(), line.chars().take(160).collect()));
131	0×	}
132		}
133	1×	Ok(out)
134	1×	})
135	1×	.await
136	1×	}
137
138		/// The changes that touched a page, newest first.
139	6×	pub async fn history(app: &Shared, repo: &RepoName, slug: &str, limit: usize) -> Result<Vec<ChangeView>, RepoError> {
140	6×	if !exists(app, repo) {
141	0×	return Ok(vec![]);
142	6×	}
143	6×	let path = path_of(slug);
144	6×	app.wikis
145	6×	.read(repo, move \|r, cache\| {
146	6×	if heads(r)?.is_empty() {
147	0×	return Ok(vec![]);
148	6×	}
149	6×	let target = view::resolve(r, cache, BOOKMARK)?;
150	6×	Ok(view::history(r, cache, target, Some(&path), 0, limit)?.entries)
151	6×	})
152	6×	.await
153	6×	}
154
155		/// Record `edits` as a change on the wiki's `main`, authored by the user
156		/// and signed by the hub as their delegate; the wiki is made on the first.
157	4×	pub async fn commit(app: &Shared, repo: &RepoName, edits: Vec<FileEdit>, message: String, signer: Signer) -> Result<Committed, RepoError> {
158	4×	if !exists(app, repo) {
159		// Bound to an id from the start, so it clones before any push.
160	1×	app.wikis.create(repo, Some(rand::random::<[u8; 16]>()))?;
161	3×	}
162	4×	app.wikis
163	4×	.write(repo, move \|r, _\| {
164	4×	let base_heads = heads(r)?;
165	4×	let author = signer.author.hash();
166	4×	let change = r.build_change(&base_heads, &edits, &message, author)?;
167	4×	let hash = change.hash();
168	4×	let sig = signer.hub_secret.sign(Domain::Change, &signer.hub_key, &hash);
169	4×	let mut state = r.load_state(&base_heads)?;
170	4×	state.add(change.clone()).map_err(\|e\| RepoError::Oxy(oxy_core::repo::RepoError::Msg(e.to_string())))?;
171	4×	let mut candidates = base_heads.clone();
172	4×	candidates.push(hash);
173	4×	let heads = state.maximal(&candidates);
174	4×	let update = r.host_ref_update(BOOKMARK, &heads, Some((&signer.hub_key, &signer.hub_secret)))?;
175	4×	let (old_state, new_state) = (update.old_state.to_hex(), update.new_state.to_hex());
176	4×	let report = r.apply_hosted(Some((change, vec![sig])), &[signer.hub_identity.clone(), signer.author.clone()], update)?;
177	4×	if let Some(refused) = report.results.iter().find(\|x\| !x.ok) {
178	0×	return Err(RepoError::Oxy(oxy_core::repo::RepoError::Msg(format!("the wiki refused the change: {}", refused.reason))));
179	4×	}
180	4×	Ok(Committed { change: hash, bookmark: BOOKMARK.into(), old_state, new_state, heads, report })
181	4×	})
182	4×	.await
183	4×	}
184
185		/// Remove the wiki (to the trash), when the repository goes or an admin
186		/// asks under Settings › Advanced.
187	2×	pub fn trash(app: &Shared, repo: &RepoName) -> Result<(), RepoError> {
188	2×	if exists(app, repo) {
189	1×	app.wikis.trash(repo)?;
190	1×	}
191	2×	Ok(())
192	2×	}
193
194		#[cfg(test)]
195		mod tests {
196		use super::*;
197
198		#[test]
199	1×	fn slugs_titles_and_paths() {
200	1×	assert_eq!(slug_of(" Getting Started "), "Getting-Started");
201	1×	assert_eq!(title_of("Getting-Started"), "Getting Started");
202	1×	assert_eq!(path_of("Home"), "Home.md");
203	1×	assert_eq!(slug_from_path("Home.md"), Some("Home"));
204	1×	assert_eq!(slug_from_path("docs/Home.md"), None);
205	1×	assert_eq!(slug_from_path("notes.txt"), None);
206	1×	assert!(slug_ok("_Sidebar") && slug_ok("v1.2-notes") && !slug_ok("") && !slug_ok("a/b") && !slug_ok("..") && !slug_ok("a b"));
207	1×	}
208		}

Coverage / crates/hub/src/wiki.rs 94.6%

Keyboard