1//! Notebooks a document provider keeps, as Android's Storage Access Framework reaches them:
2//! documents named by opaque ids, listed by folder and opened as descriptors, with no locks,
3//! no rename over another document and, on many providers, no seeking. A picked folder is a
4//! notebook root (`session::Notebook::open_provider`), a picked document a lone section
5//! (`session::Section::open_provider`); replicas and the catalog's listing stay in the cache.
6
7use crate::{
8 Error, Result, discover,
9 published::{Published, Written, whole},
10 session::Storage,
11};
12use onestore::{CommitError, CommitIo, CommitState, Stamp, Store, Transaction};
13use std::{
14 collections::BTreeMap,
15 fs::File,
16 io::{self, Read, Seek, SeekFrom, Write},
17 path::{Path, PathBuf},
18 sync::{Arc, Mutex, MutexGuard, PoisonError},
19};
20
21/// A document as its provider describes it.
22#[derive(Clone, Debug)]
23pub struct Document {
24 pub id: String,
25 pub name: String,
26 pub directory: bool,
27 /// What the provider lists, where it lists anything.
28 pub size: Option<u64>,
29 pub modified: Option<u64>,
30 /// The grant allows writing and the provider supports it.
31 pub writable: bool,
32}
33
34/// The host's document provider. Failures take the shapes a provider gives them: unreachable
35/// as `NotConnected`, a revoked grant as `PermissionDenied`, and a document gone (or renamed,
36/// which changes its id) as `NotFound`.
37pub trait Provider: Send + Sync {
38 fn document(&self, id: &str) -> io::Result<Document>;
39 fn children(&self, id: &str) -> io::Result<Vec<Document>>;
40 /// Opens a document in a `ContentResolver` mode: `r`, `rw`, `wt` or `w`.
41 fn open(&self, id: &str, mode: &str) -> io::Result<File>;
42 /// Closes a file `open` gave, with the provider's verdict on what was written to it.
43 fn close(&self, file: File) -> io::Result<()>;
44 /// Renames a document, returning its new id.
45 fn rename(&self, id: &str, name: &str) -> io::Result<String>;
46}
47
48/// The documents under one root a provider keeps: a notebook's folder or a lone section.
49/// Paths are catalog paths, `/`-separated below the root.
50pub struct Documents {
51 provider: Box<dyn Provider>,
52 pub(crate) root: String,
53 /// The app's cache, holding the replicas and the notebook's listing.
54 pub(crate) cache: PathBuf,
55 /// This device as the conflict pages its merged-back publications make name it.
56 device: String,
57 /// Each path's document as last listed; a stale one is listed again.
58 ids: Mutex<BTreeMap<String, String>>,
59}
60
61impl Documents {
62 pub fn new(
63 provider: impl Provider + 'static,
64 root: impl Into<String>,
65 cache: impl Into<PathBuf>,
66 device: impl Into<String>,
67 ) -> Self {
68 Self {
69 provider: Box::new(provider),
70 root: root.into(),
71 cache: cache.into(),
72 device: device.into(),
73 ids: Mutex::default(),
74 }
75 }
76
77 pub(crate) fn location(&self) -> String {
78 format!("provider:{}", self.root)
79 }
80
81 fn id(&self, path: &str) -> io::Result<String> {
82 if path.is_empty() {
83 return Ok(self.root.clone());
84 }
85 if let Some(id) = lock(&self.ids).get(path) {
86 return Ok(id.clone());
87 }
88 self.listing(path.rsplit_once('/').map_or("", |(folder, _)| folder))?;
89 lock(&self.ids)
90 .get(path)
91 .cloned()
92 .ok_or_else(|| io::ErrorKind::NotFound.into())
93 }
94
95 /// Reads through the document at `path`, listing its folders again once if the id they
96 /// last gave is gone.
97 fn with_id<T>(&self, path: &str, read: impl Fn(&str) -> io::Result<T>) -> io::Result<T> {
98 match read(&self.id(path)?) {
99 Err(error) if error.kind() == io::ErrorKind::NotFound && !path.is_empty() => {
100 lock(&self.ids).clear();
101 read(&self.id(path)?)
102 }
103 result => result,
104 }
105 }
106
107 /// A folder's entries, and the documents sharing a name with one listed before them by id.
108 fn listing(&self, folder: &str) -> io::Result<(Vec<discover::Entry>, Vec<Document>)> {
109 let mut children = self.with_id(folder, |id| self.provider.children(id))?;
110 children.sort_by(|a, b| (&a.name, &a.id).cmp(&(&b.name, &b.id)));
111 let (mut entries, mut duplicates) = (Vec::<discover::Entry>::new(), Vec::new());
112 let mut ids = lock(&self.ids);
113 for child in children {
114 if entries.last().is_some_and(|last| last.name == child.name) {
115 duplicates.push(child);
116 continue;
117 }
118 ids.insert(discover::join(folder, &child.name), child.id.clone());
119 entries.push(discover::Entry {
120 name: child.name,
121 kind: if child.directory {
122 discover::EntryKind::Directory
123 } else {
124 discover::EntryKind::File
125 },
126 listed: discover::Listed {
127 size: child.size.unwrap_or_default(),
128 // Unknown, it never matches an earlier listing, so the file is read again.
129 modified: child
130 .modified
131 .filter(|_| child.size.is_some())
132 .unwrap_or_else(crate::now),
133 },
134 });
135 }
136 Ok((entries, duplicates))
137 }
138
139 pub(crate) fn entries(&self, folder: &str) -> io::Result<Vec<discover::Entry>> {
140 Ok(self.listing(folder)?.0)
141 }
142
143 /// Opens the document `id`, hands it to `operation` and closes it, failing if either fails.
144 fn opened<T>(
145 &self,
146 id: &str,
147 mode: &str,
148 operation: impl FnOnce(&mut File) -> io::Result<T>,
149 ) -> io::Result<T> {
150 let mut file = self.provider.open(id, mode)?;
151 let result = operation(&mut file);
152 let closed = self.provider.close(file);
153 let value = result?;
154 closed?;
155 Ok(value)
156 }
157
158 fn read(&self, path: &str, limit: usize) -> io::Result<Vec<u8>> {
159 self.with_id(path, |id| self.opened(id, "r", |file| whole(file, limit)))
160 }
161
162 /// The document's stamp, with its image where a stream had to be read whole for it.
163 fn stamp(&self, path: &str) -> io::Result<(Stamp, Option<Vec<u8>>)> {
164 self.with_id(path, |id| {
165 self.opened(id, "r", |file| {
166 if file.stream_position().is_err() {
167 let image = whole(file, crate::MAX_FILE_BYTES)?;
168 // A torn image shorter than a header still stamps, as it stands.
169 let mut header = [0; 1024];
170 let start = &image[..image.len().min(1024)];
171 header[..start.len()].copy_from_slice(start);
172 let length = image.len() as u64;
173 return Ok((Stamp { header, length }, Some(image)));
174 }
175 let mut header = [0; 1024];
176 file.read_exact(&mut header)?;
177 let length = file.seek(SeekFrom::End(0))?;
178 Ok((Stamp { header, length }, None))
179 })
180 })
181 }
182
183 /// Writes the document at `path` through `operation`, provided its grant allows writing:
184 /// in place where its `r` descriptor seeks, else on the image read whole, which then
185 /// replaces it. `keep` takes what was written: the descriptor, once the commit landed, or
186 /// the image, once a write to the document opened. The id is the one the last listing gave,
187 /// never listed again, so that a document taking the name meanwhile is not the one written.
188 fn write(
189 &self,
190 path: &str,
191 operation: impl FnOnce(&mut Io) -> std::result::Result<(), CommitError>,
192 keep: impl FnOnce(Written<'_>) -> io::Result<()>,
193 ) -> std::result::Result<(), CommitError> {
194 let id = self.id(path).map_err(refused)?;
195 self.writable(&id).map_err(refused)?;
196 let seekable = self
197 .opened(&id, "r", |file| Ok(file.stream_position().is_ok()))
198 .map_err(refused)?;
199 let mut io = if seekable {
200 Io::File(self.provider.open(&id, "rw").map_err(refused)?)
201 } else {
202 let image = self.opened(&id, "r", |file| whole(file, crate::MAX_FILE_BYTES));
203 Io::Image(image.map_err(refused)?)
204 };
205 let result = operation(&mut io);
206 match io {
207 Io::File(mut file) => {
208 // A copy it could not keep only leaves the publication unprotected.
209 if result.is_ok() {
210 let _ = keep(Written::InPlace(&mut file));
211 }
212 let closed = self.provider.close(file);
213 result?;
214 closed.map_err(uncertain)
215 }
216 Io::Image(image) => {
217 result?;
218 self.upload(&id, &image, keep)
219 }
220 }
221 }
222
223 /// Fails unless the grant allows writing the document `id`.
224 fn writable(&self, id: &str) -> io::Result<()> {
225 if self.provider.document(id)?.writable {
226 return Ok(());
227 }
228 Err(io::Error::new(
229 io::ErrorKind::ReadOnlyFilesystem,
230 "The app keeping this section lets Snowbound only read it",
231 ))
232 }
233
234 /// Writes `image` whole as the document `id`, with `wt`, or `w` where that is refused
235 /// (images only grow), having `keep` take it once a write opened.
236 fn upload(
237 &self,
238 id: &str,
239 image: &[u8],
240 keep: impl FnOnce(Written<'_>) -> io::Result<()>,
241 ) -> std::result::Result<(), CommitError> {
242 // A provider refusing `wt` may say so as any failure but a revoked grant.
243 let mut file = match self.provider.open(id, "wt") {
244 Err(error) if error.kind() != io::ErrorKind::PermissionDenied => {
245 self.provider.open(id, "w")
246 }
247 opened => opened,
248 }
249 .map_err(refused)?;
250 if let Err(error) = keep(Written::Image(image)) {
251 let _ = self.provider.close(file);
252 return Err(refused(error));
253 }
254 let written = file.write_all(image);
255 let closed = self.provider.close(file);
256 written.and(closed).map_err(uncertain)
257 }
258
259 /// Renames the document at `path` within its folder.
260 fn rename(&self, path: &str, name: &str) -> io::Result<()> {
261 self.provider.rename(&self.id(path)?, name)?;
262 lock(&self.ids).clear();
263 Ok(())
264 }
265}
266
267fn refused(error: io::Error) -> CommitError {
268 CommitError {
269 state: CommitState::NotCommitted,
270 error,
271 }
272}
273
274fn uncertain(error: io::Error) -> CommitError {
275 CommitError {
276 state: CommitState::Unknown,
277 error,
278 }
279}
280
281fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
282 mutex.lock().unwrap_or_else(PoisonError::into_inner)
283}
284
285/// A document as a commit writes it: its seekable descriptor, or its image to write whole.
286enum Io {
287 File(File),
288 Image(Vec<u8>),
289}
290
291impl CommitIo for Io {
292 fn read_at(&mut self, offset: u64, bytes: &mut [u8]) -> io::Result<usize> {
293 match self {
294 Io::File(file) => {
295 file.seek(SeekFrom::Start(offset))?;
296 file.read(bytes)
297 }
298 Io::Image(image) => {
299 let rest = usize::try_from(offset)
300 .ok()
301 .and_then(|offset| image.get(offset..))
302 .unwrap_or_default();
303 let count = rest.len().min(bytes.len());
304 bytes[..count].copy_from_slice(&rest[..count]);
305 Ok(count)
306 }
307 }
308 }
309
310 fn write_at(&mut self, offset: u64, bytes: &[u8]) -> io::Result<usize> {
311 match self {
312 Io::File(file) => {
313 file.seek(SeekFrom::Start(offset))?;
314 file.write(bytes)
315 }
316 Io::Image(image) => {
317 let offset = usize::try_from(offset).map_err(|_| io::ErrorKind::FileTooLarge)?;
318 let end = offset + bytes.len();
319 if image.len() < end {
320 image.resize(end, 0);
321 }
322 image[offset..end].copy_from_slice(bytes);
323 Ok(bytes.len())
324 }
325 }
326 }
327
328 fn flush(&mut self) -> io::Result<()> {
329 match self {
330 Io::File(file) => file.sync_all(),
331 Io::Image(_) => Ok(()),
332 }
333 }
334}
335
336/// A section a document provider keeps, as its replica publishes to it, each image it
337/// publishes kept beside the replica until the document holds it (`published.rs`).
338pub(crate) struct ProviderRemote {
339 documents: Arc<Documents>,
340 path: String,
341 /// None for a section with no replica yet, which publishes nothing.
342 published: Option<Published>,
343 /// The image the step read whole for a stamp, which its read takes.
344 read: Option<Vec<u8>>,
345}
346
347impl ProviderRemote {
348 pub(crate) fn new(documents: &Arc<Documents>, path: &str, replica: Option<&Path>) -> Self {
349 Self {
350 documents: Arc::clone(documents),
351 path: path.to_owned(),
352 published: replica.map(|replica| Published::of(replica, &documents.device)),
353 read: None,
354 }
355 }
356
357 /// This device's own upload cut off, as a provider that writes non-atomically leaves it,
358 /// put back and read again: the newest image kept that the torn bytes begin. Any other
359 /// document that does not parse is left as it is.
360 fn repair(&self, torn: &[u8]) -> io::Result<Vec<u8>> {
361 let published = self.published.as_ref().ok_or(io::ErrorKind::WouldBlock)?;
362 let image = published.torn(torn)?.ok_or(io::ErrorKind::WouldBlock)?;
363 let id = self.documents.id(&self.path)?;
364 self.documents.writable(&id)?;
365 self.documents
366 .upload(&id, &image, |_| Ok(()))
367 .map_err(|error| error.error)?;
368 self.documents.read(&self.path, crate::MAX_FILE_BYTES)
369 }
370}
371
372fn parses(image: &[u8]) -> bool {
373 Store::parse(image).is_ok_and(|store| store.checksum_mismatches.is_empty())
374}
375
376impl crate::Remote for ProviderRemote {
377 /// A torn or damaged image, as a stream mid-upload reads, is never a base to rebase on.
378 fn read(&mut self) -> io::Result<Vec<u8>> {
379 let image = match self.read.take() {
380 Some(image) => image,
381 None => self.documents.read(&self.path, crate::MAX_FILE_BYTES)?,
382 };
383 if !parses(&image) {
384 return Err(io::Error::new(
385 io::ErrorKind::WouldBlock,
386 "The section was read mid-write",
387 ));
388 }
389 Ok(image)
390 }
391
392 fn stamp(&mut self) -> io::Result<Stamp> {
393 if let Some(image) = &self.read {
394 return Stamp::of(image)
395 .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error));
396 }
397 let (stamp, image) = self.documents.stamp(&self.path)?;
398 self.read = image;
399 Ok(stamp)
400 }
401
402 fn publish(&mut self, transaction: &Transaction) -> std::result::Result<(), CommitError> {
403 self.read = None;
404 self.documents.write(
405 &self.path,
406 |io| transaction.commit(io),
407 |written| match &self.published {
408 Some(published) => published.keep(written, transaction),
409 None => Ok(()),
410 },
411 )
412 }
413
414 fn confirm(&mut self, base: &Stamp) -> std::result::Result<(), CommitError> {
415 self.read = None;
416 self.documents.write(
417 &self.path,
418 |io| onestore::confirm(io, base),
419 |written| match &self.published {
420 Some(published) => published.confirmed(written, base),
421 None => Ok(()),
422 },
423 )
424 }
425
426 /// The images kept of this document other than the one it stands as
427 /// (`Published::versions`). A document read torn is repaired first, once a step.
428 fn versions(&mut self) -> io::Result<Vec<crate::Version>> {
429 let (mut stamp, mut image) = self.documents.stamp(&self.path)?;
430 if let Some(torn) = image.as_ref().filter(|image| !parses(image))
431 && let Ok(repaired) = self.repair(torn)
432 && let Ok(repaired_stamp) = Stamp::of(&repaired)
433 {
434 (stamp, image) = (repaired_stamp, Some(repaired));
435 }
436 self.read = image;
437 match &self.published {
438 Some(published) => published.versions(|| Ok(stamp), &[]),
439 None => Ok(Vec::new()),
440 }
441 }
442
443 fn version(&mut self, id: &str) -> io::Result<Vec<u8>> {
444 crate::fs::read(id)
445 }
446
447 /// One that cannot merge, of another section under the document's name, is set aside
448 /// whole, where `versions` lists it no more: no provider here takes a new document beside it.
449 fn retire(&mut self, id: &str, keep: bool) -> io::Result<()> {
450 let path = PathBuf::from(id);
451 if keep {
452 crate::fs::rename(&path, path.with_extension("unmerged"))
453 } else {
454 crate::fs::remove_file(path)
455 }
456 }
457}
458
459/// A notebook folder a document provider keeps, its folders as last listed kept at `listed`.
460pub(crate) struct Tree {
461 pub(crate) documents: Arc<Documents>,
462 pub(crate) listed: PathBuf,
463}
464
465/// The provider's folders, or as they were last listed while it can't be reached.
466struct Source<'a> {
467 documents: &'a Documents,
468 kept: BTreeMap<String, Vec<discover::Entry>>,
469 listed: BTreeMap<String, Vec<discover::Entry>>,
470 /// Documents sharing a name with one listed, by folder.
471 duplicates: BTreeMap<String, Vec<Document>>,
472}
473
474impl discover::Source for Source<'_> {
475 fn entries(&mut self, path: &str, limit: usize) -> io::Result<Vec<discover::Entry>> {
476 let entries = match self.documents.listing(path) {
477 Ok((entries, duplicates)) => {
478 self.duplicates.insert(path.to_owned(), duplicates);
479 entries
480 }
481 Err(error) if error.kind() == io::ErrorKind::NotConnected => {
482 self.kept.get(path).cloned().ok_or(error)?
483 }
484 Err(error) => return Err(error),
485 };
486 if entries.len() > limit {
487 return Err(io::ErrorKind::FileTooLarge.into());
488 }
489 self.listed.insert(path.to_owned(), entries.clone());
490 Ok(entries)
491 }
492
493 fn read(&mut self, path: &str, limit: usize) -> io::Result<Vec<u8>> {
494 self.documents.read(path, limit)
495 }
496}
497
498fn unsupported() -> Error {
499 io::Error::new(
500 io::ErrorKind::Unsupported,
501 "Snowbound can't change this notebook's folders in another app yet",
502 )
503 .into()
504}
505
506impl Storage for Tree {
507 /// Of several documents with one name, the first by id stands for it and the rest are
508 /// unavailable, named with their ids.
509 fn discover(
510 &self,
511 cache: &mut discover::Cache,
512 limits: discover::Limits,
513 ) -> Result<discover::Folder> {
514 let kept = crate::fs::read(&self.listed)
515 .ok()
516 .and_then(|bytes| serde_json::from_slice(&bytes).ok())
517 .unwrap_or_default();
518 let mut source = Source {
519 documents: &self.documents,
520 kept,
521 listed: BTreeMap::new(),
522 duplicates: BTreeMap::new(),
523 };
524 let mut catalog = cache.discover(&mut source, limits)?;
525 if let Ok(json) = serde_json::to_vec(&source.listed) {
526 let _ = crate::fs::write(&self.listed, json);
527 }
528 for (path, duplicates) in source.duplicates {
529 let Some(folder) = folder(&mut catalog, &path) else {
530 continue;
531 };
532 for duplicate in duplicates {
533 folder.unavailable.push(discover::Unavailable {
534 path: discover::join(&path, &format!("{} ({})", duplicate.name, duplicate.id)),
535 group: duplicate.directory,
536 error: "Another document here has the same name".into(),
537 reason: discover::Reason::Denied,
538 });
539 }
540 }
541 Ok(catalog)
542 }
543
544 fn location(&self) -> String {
545 self.documents.location()
546 }
547
548 fn entries(&self, folder: &str) -> io::Result<Vec<discover::Entry>> {
549 self.documents.entries(folder)
550 }
551
552 fn exists(&self, path: &str) -> bool {
553 let (folder, name) = path.rsplit_once('/').unwrap_or(("", path));
554 self.documents
555 .entries(folder)
556 .is_ok_and(|entries| entries.iter().any(|entry| entry.name == name))
557 }
558
559 fn stamp(&self, path: &str) -> io::Result<Stamp> {
560 Ok(self.documents.stamp(path)?.0)
561 }
562
563 fn read(&self, path: &str) -> Result<Vec<u8>> {
564 Ok(self.documents.read(path, crate::MAX_FILE_BYTES)?)
565 }
566
567 fn read_file(&self, path: &str, limit: usize) -> Result<Vec<u8>> {
568 Ok(self.documents.read(path, limit)?)
569 }
570
571 fn create(&self, _: &str, _: &[u8]) -> Result<()> {
572 Err(unsupported())
573 }
574
575 fn create_directory(&self, _: &str) -> Result<()> {
576 Err(unsupported())
577 }
578
579 fn hide(&self, _: &str) -> Result<()> {
580 Err(unsupported())
581 }
582
583 fn rename(&self, from: &str, to: &str) -> Result<()> {
584 let folder = |path: &str| path.rsplit_once('/').map(|(folder, _)| folder.to_owned());
585 if folder(from) != folder(to) {
586 return Err(unsupported());
587 }
588 let name = to.rsplit('/').next().unwrap_or(to);
589 Ok(self.documents.rename(from, name)?)
590 }
591
592 fn rename_root(&self, _: &str, _: &[String]) -> Result<String> {
593 Err(unsupported())
594 }
595
596 fn replace(&self, _: &str, _: &str) -> Result<()> {
597 Err(unsupported())
598 }
599
600 fn delete(&self, _: &str) -> Result<()> {
601 Err(unsupported())
602 }
603
604 fn place(&self, path: &str, ancestor: [u8; 16], name: &str) -> Result<()> {
605 let place = |io: &mut Io| {
606 onestore::place(io, ancestor, name).map_err(|error| CommitError {
607 state: CommitState::Unknown,
608 error,
609 })
610 };
611 Ok(self.documents.write(path, place, |_| Ok(()))?)
612 }
613
614 fn commit(&self, path: &str, transaction: &Transaction) -> Result<()> {
615 Ok(self
616 .documents
617 .write(path, |io| transaction.commit(io), |_| Ok(()))?)
618 }
619
620 fn confirm(&self, path: &str, base: &Stamp) -> std::result::Result<(), CommitError> {
621 self.documents
622 .write(path, |io| onestore::confirm(io, base), |_| Ok(()))
623 }
624
625 fn supersede(&self, _: &str, _: &Stamp, _: &str) -> Result<()> {
626 Err(unsupported())
627 }
628}
629
630fn folder<'a>(folder: &'a mut discover::Folder, path: &str) -> Option<&'a mut discover::Folder> {
631 if folder.path == path {
632 return Some(folder);
633 }
634 folder
635 .groups
636 .iter_mut()
637 .find_map(|group| self::folder(group, path))
638}
639
640#[cfg(all(test, unix))]
641mod tests;