1use std::path::PathBuf;
4use std::sync::Arc;
5
6#[cfg(unix)]
7use crate::files::flush_batch::BatchFolder;
8use crate::files::protection::Protection;
9use crate::files::{
10 lock, settings, AtomicFile, CacheWriteLock, ClosedStoreLock, FileError, FileWriter, FlushBatch,
11 SettingsError, StoreDeletionLock, StoreLock, StoreLockError, StoreReadLock, StoreSettings,
12 WriterFolder,
13};
14use crate::id_source::StoreId;
15use crate::task::BugSinkRef;
16
17pub(super) const DATABASE: &str = "store.db";
19
20#[derive(Clone, Copy, Debug)]
23pub enum StoreFile {
24 StorageSettings,
26 StoreKeys,
28 MemberKeys,
30 Bootstrap,
32}
33
34impl StoreFile {
35 pub(super) const fn name(self) -> &'static str {
37 match self {
38 Self::StorageSettings => "storage.json",
39 Self::StoreKeys => "store-keys.sealed",
40 Self::MemberKeys => "member-keys.sealed",
41 Self::Bootstrap => "bootstrap.sealed",
42 }
43 }
44}
45
46#[derive(Clone, Copy, Debug)]
48pub enum FileArea {
49 AppProvided,
52 Cache,
54}
55
56impl FileArea {
57 const ALL: [Self; 2] = [Self::AppProvided, Self::Cache];
58
59 const fn name(self) -> &'static str {
61 match self {
62 Self::AppProvided => "files",
63 Self::Cache => "cache",
64 }
65 }
66}
67
68#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
71pub struct FileName(String);
72
73#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
75pub enum FileNameError {
76 #[error("file name must contain 1 to 255 bytes")]
78 Length,
79 #[error("file name requires ASCII letters, digits, hyphens, underscores or interior dots")]
81 Character,
82 #[error("file name is reserved for a Windows device")]
84 Reserved,
85}
86
87impl FileName {
88 pub fn as_str(&self) -> &str {
90 &self.0
91 }
92
93 pub fn new(name: impl Into<String>) -> Result<Self, FileNameError> {
95 let name = name.into();
96 if name.is_empty() || name.len() > super::relative_path::NAME_LIMIT {
97 return Err(FileNameError::Length);
98 }
99 if name.starts_with('.')
100 || name.ends_with('.')
101 || !name.bytes().all(|b| b.is_ascii_alphanumeric() || b"-_.".contains(&b))
102 {
103 return Err(FileNameError::Character);
104 }
105 let stem = name.split('.').next().expect("a nonempty name has a stem");
106 if windows_reserved_names::windows_device(stem) {
107 return Err(FileNameError::Reserved);
108 }
109 Ok(Self(name))
110 }
111}
112
113#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
117pub struct StagedName(String);
118
119impl StagedName {
120 pub fn new(folder: &FileName, name: &FileName) -> Self {
122 Self(format!("{}/{}", folder.0, name.0))
123 }
124
125 pub fn parse(recorded: &str) -> Option<Self> {
128 let (folder, name) = recorded.split_once('/')?;
129 Some(Self::new(&FileName::new(folder).ok()?, &FileName::new(name).ok()?))
130 }
131
132 pub fn as_str(&self) -> &str {
134 &self.0
135 }
136
137 pub fn folder(&self) -> FileName {
139 FileName(self.parts().0.to_owned())
140 }
141
142 pub fn copy(&self) -> FileName {
144 FileName(self.parts().1.to_owned())
145 }
146
147 fn parts(&self) -> (&str, &str) {
149 self.0.split_once('/').expect("a staged name holds its folder")
150 }
151}
152
153#[derive(Debug, thiserror::Error)]
155pub enum StagingFolderError {
156 #[error("staging folder {} is already there", .0.as_str())]
159 Taken(FileName),
160 #[error(transparent)]
162 Writer(#[from] WriterError),
163}
164
165#[derive(Clone)]
168pub struct StoreDir {
169 path: PathBuf,
170 id: StoreId,
171 bootstrap: Option<lock::LockInstance>,
174 protection: Protection,
176 bugs: BugSinkRef,
178}
179
180impl std::fmt::Debug for StoreDir {
181 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
182 f.debug_struct("StoreDir")
183 .field("path", &self.path)
184 .field("id", &self.id)
185 .field("bootstrap", &self.bootstrap)
186 .field("protection", &self.protection)
187 .finish_non_exhaustive()
188 }
189}
190
191impl StoreDir {
192 pub(crate) fn new(
193 path: PathBuf,
194 id: StoreId,
195 protection: Protection,
196 bugs: BugSinkRef,
197 ) -> Self {
198 Self { path, id, bootstrap: None, protection, bugs }
199 }
200
201 pub(super) fn bootstrapping(
202 path: PathBuf,
203 id: StoreId,
204 bootstrap: lock::LockInstance,
205 protection: Protection,
206 bugs: BugSinkRef,
207 ) -> Self {
208 Self { path, id, bootstrap: Some(bootstrap), protection, bugs }
209 }
210
211 pub fn is_unpublished(&self) -> Result<bool, FileError> {
214 super::bootstrap::is_pending(&self.path)
215 }
216
217 fn is_bootstrapping(&self) -> bool {
218 self.bootstrap
219 .is_some_and(|instance| lock::bootstrap_running(&self.path, self.id, instance))
220 }
221
222 fn check_published(&self) -> Result<(), StoreLockError> {
226 if self.is_bootstrapping() {
227 return Ok(());
228 }
229 let unfinished =
230 super::device_reset::unfinished(&self.path, self.id).map_err(|error| match error {
231 SettingsError::File(error) => StoreLockError::from(error),
232 SettingsError::Bug(bug) => StoreLockError::Bug(bug),
233 error => FileError::at(
234 "read the store's settings beside its replacement record",
235 &self.path,
236 std::io::Error::other(error),
237 )
238 .into(),
239 })?;
240 if let Some(record) = unfinished {
241 return Err(StoreLockError::ReplacementUnfinished { store: self.id, by: record.by });
242 }
243 if super::bootstrap::is_pending(&self.path)? {
244 return Err(StoreLockError::BootstrapPending(self.id));
245 }
246 Ok(())
247 }
248
249 pub fn id(&self) -> StoreId {
251 self.id
252 }
253
254 #[cfg(any(test, feature = "test-utils"))]
257 pub fn area_path(&self, area: FileArea) -> std::path::PathBuf {
258 self.path.join(area.name())
259 }
260
261 #[cfg(any(test, feature = "test-utils"))]
265 pub fn files_exist(&self) -> bool {
266 self.path.exists() || lock::deletion_path(&self.path, self.id).exists()
267 }
268
269 #[cfg(any(test, feature = "test-utils"))]
274 pub fn copy_files(&self, to: &std::path::Path) {
275 crate::files::copy_tree(&self.path, to);
276 }
277
278 #[cfg(any(test, feature = "test-utils"))]
282 pub fn damage_settings(&self) {
283 std::fs::write(self.path.join(settings::SETTINGS_FILE), b"{").unwrap();
284 }
285
286 #[cfg(any(test, feature = "test-utils"))]
289 pub fn damage_storage_settings(&self) {
290 std::fs::write(self.path.join(StoreFile::StorageSettings.name()), b"{not settings")
291 .unwrap();
292 }
293
294 #[cfg(any(test, feature = "test-utils"))]
298 pub fn restore_files(&self, from: &std::path::Path) {
299 std::fs::remove_dir_all(&self.path).unwrap();
300 crate::files::copy_tree(from, &self.path);
301 }
302}
303
304const REBUILD: &str = "rebuild";
306const REMOVING_REBUILD: &str = "removing-rebuild";
308
309pub(crate) fn initialize(
310 path: &std::path::Path,
311 settings: &StoreSettings,
312) -> Result<(), SettingsError> {
313 for area in FileArea::ALL {
314 let directory = path.join(area.name());
315 std::fs::create_dir(&directory).map_err(|source| {
316 crate::files::FileError::at("create store files directory", &directory, source)
317 })?;
318 #[cfg(unix)]
319 crate::files::atomic_file::sync_directory(&directory).map_err(|source| {
320 crate::files::FileError::at("sync store files directory", &directory, source)
321 })?;
322 }
323 settings::write(path, settings)
324}
325
326#[derive(Debug, thiserror::Error)]
329pub enum WriterError {
330 #[error(transparent)]
332 Lock(#[from] StoreLockError),
333 #[error(transparent)]
335 File(#[from] FileError),
336}
337
338#[cfg(any(test, feature = "test-utils"))]
341pub trait StoreLockProbe {
342 fn lock_exclusive(&self) -> Result<StoreLock, StoreLockError>;
344}
345
346#[cfg(any(test, feature = "test-utils"))]
347impl StoreLockProbe for StoreDir {
348 fn lock_exclusive(&self) -> Result<StoreLock, StoreLockError> {
349 let guard = lock::acquire(&self.path, self.id)?;
350 self.check_published()?;
351 Ok(guard)
352 }
353}
354
355pub trait StoreDirAccess: Sized {
357 fn database_path(&self) -> PathBuf;
360 fn input_database_path(&self) -> PathBuf;
363 fn audience_database_path(&self) -> PathBuf;
366 fn remove_audience_database(&self) -> Result<(), FileError>;
369 fn rebuild_directory(
376 &self,
377 ) -> impl std::future::Future<Output = Result<Self, SettingsError>> + Send;
378 fn remove_rebuild_directory(&self) -> Result<(), FileError>;
380 fn retire_rebuild_directory(&self) -> Result<bool, FileError>;
384 fn return_rebuild_directory(&self) -> Result<(), FileError>;
386 fn remove_retired_rebuild(&self) -> Result<(), FileError>;
391 fn unfinished_replacement(&self) -> Result<Option<super::ReplacementRecord>, SettingsError>;
396 fn unfinished_deletion(&self) -> Result<Option<super::IfUnsent>, FileError>;
400 fn record_deletion(&self, unsent: super::IfUnsent) -> Result<(), FileError>;
404 fn forget_deletion(&self) -> Result<(), FileError>;
407 fn discarded_devices(&self) -> Result<Vec<String>, FileError>;
410 fn discarded_device_size(&self, name: &str) -> Result<u64, FileError>;
413 fn retire_discarded_device(&self, name: &str) -> Result<bool, FileError>;
417 fn return_discarded_device(&self, name: &str) -> Result<(), FileError>;
419 fn remove_retired_devices(&self) -> Result<(), FileError>;
424 fn settings(&self) -> Result<StoreSettings, SettingsError>;
427 fn bugs(&self) -> &BugSinkRef;
430 fn lock_for_open(
433 &self,
434 ) -> impl std::future::Future<Output = Result<StoreLock, StoreLockError>> + Send;
435 fn lock_closed(
440 &self,
441 ) -> impl std::future::Future<Output = Result<ClosedStoreLock, StoreLockError>> + Send;
442 fn lock_read_only(&self) -> Result<StoreReadLock, StoreLockError>;
445 fn lock_cache_write(&self) -> Result<CacheWriteLock, FileError>;
449 fn exclude_cache_writes(&self) -> Result<CacheWriteLock, FileError>;
453 fn lock_for_deletion(&self) -> Result<Option<StoreDeletionLock>, StoreLockError>;
462 fn closed(&self) -> impl std::future::Future<Output = Result<(), FileError>> + Send;
468 fn owned_file(&self, file: StoreFile) -> AtomicFile;
471 fn file(&self, area: FileArea, name: &FileName) -> AtomicFile;
474 fn create_writer(&self, area: FileArea, name: &FileName) -> Result<FileWriter, WriterError>;
480 fn writer_folder(&self, area: FileArea) -> Result<WriterFolder, WriterError>;
484 fn staged_file(&self, name: &StagedName) -> AtomicFile;
486 fn staging_folder(
492 &self,
493 folder: &FileName,
494 batch: &mut FlushBatch,
495 ) -> Result<WriterFolder, StagingFolderError>;
496 fn remove_staged(&self, name: &StagedName) -> Result<(), FileError>;
500 fn resume_writer(
506 &self,
507 area: FileArea,
508 name: &FileName,
509 length: u64,
510 ) -> Result<FileWriter, WriterError>;
511}
512
513pub fn verify_lock(directory: &StoreDir, lock: &StoreLock) -> Result<(), StoreLockError> {
515 lock.verify(&directory.path, directory.id)
516}
517
518pub fn settle_files(directory: &StoreDir, lock: &StoreLock) -> Result<(), FileError> {
526 super::atomic_file::remove_temporaries(lock.directory())?;
527 if !super::bootstrap::is_pending(lock.directory())?
529 && super::atomic_file::exists(
530 "inspect the joining keys",
531 &lock.directory().join(StoreFile::Bootstrap.name()),
532 )?
533 {
534 directory.owned_file(StoreFile::Bootstrap).remove_with_temporaries()?;
535 }
536 directory.protection.apply(lock.directory())
537}
538
539impl StoreDirAccess for StoreDir {
540 fn database_path(&self) -> PathBuf {
541 self.path.join(DATABASE)
542 }
543 fn input_database_path(&self) -> PathBuf {
544 self.path.join("inputs.db")
545 }
546 fn audience_database_path(&self) -> PathBuf {
547 self.path.join("audiences.db")
548 }
549 fn remove_audience_database(&self) -> Result<(), FileError> {
550 let path = self.audience_database_path();
551 for suffix in ["", "-wal", "-shm", "-journal"] {
552 let mut file = path.as_os_str().to_owned();
553 file.push(suffix);
554 match std::fs::remove_file(PathBuf::from(&file)) {
555 Err(source) if source.kind() != std::io::ErrorKind::NotFound => {
556 return Err(FileError::at(
557 "remove the audience database",
558 &PathBuf::from(file),
559 source,
560 ));
561 }
562 _ => (),
563 }
564 }
565 Ok(())
566 }
567 async fn rebuild_directory(&self) -> Result<StoreDir, SettingsError> {
568 let settings = self.settings()?;
569 let scratch = self.path.join(REBUILD).join(self.id.to_string());
570 lock::closed(&scratch, self.id).await?;
571 self.remove_rebuild_directory()?;
572 let root = self.path.join(REBUILD);
573 for folder in [&root, &scratch] {
574 std::fs::create_dir(folder).map_err(|source| {
575 FileError::at("create the rebuild store's folder", folder, source)
576 })?;
577 self.protection.begin(folder)?;
578 }
579 initialize(&scratch, &settings)?;
580 Ok(StoreDir::new(scratch, self.id, self.protection, self.bugs.clone()))
581 }
582 fn remove_rebuild_directory(&self) -> Result<(), FileError> {
583 let root = self.path.join(REBUILD);
584 match std::fs::remove_dir_all(&root) {
585 Err(source) if source.kind() != std::io::ErrorKind::NotFound => {
586 Err(FileError::at("remove the rebuild store's folder", &root, source))
587 }
588 _ => Ok(()),
589 }
590 }
591 fn retire_rebuild_directory(&self) -> Result<bool, FileError> {
592 self.remove_retired_rebuild()?;
593 super::set_aside::move_aside(&self.path.join(REBUILD), &self.path.join(REMOVING_REBUILD))
594 }
595 fn return_rebuild_directory(&self) -> Result<(), FileError> {
596 super::set_aside::move_back(&self.path.join(REBUILD), &self.path.join(REMOVING_REBUILD))
597 }
598 fn remove_retired_rebuild(&self) -> Result<(), FileError> {
599 super::set_aside::delete(&self.path.join(REMOVING_REBUILD))
600 }
601 fn unfinished_replacement(&self) -> Result<Option<super::ReplacementRecord>, SettingsError> {
602 super::device_reset::unfinished(&self.path, self.id)
603 }
604 fn unfinished_deletion(&self) -> Result<Option<super::IfUnsent>, FileError> {
605 super::deletion::read(&self.path)
606 }
607 fn record_deletion(&self, unsent: super::IfUnsent) -> Result<(), FileError> {
608 super::deletion::record(&self.path, unsent)
609 }
610 fn forget_deletion(&self) -> Result<(), FileError> {
611 super::deletion::forget(&self.path)
612 }
613 fn discarded_devices(&self) -> Result<Vec<String>, FileError> {
614 super::device_reset::discarded_devices(&self.path)
615 }
616 fn discarded_device_size(&self, name: &str) -> Result<u64, FileError> {
617 super::device_reset::discarded_device_size(&self.path, name)
618 }
619 fn retire_discarded_device(&self, name: &str) -> Result<bool, FileError> {
620 super::device_reset::retire(&self.path, name)
621 }
622 fn return_discarded_device(&self, name: &str) -> Result<(), FileError> {
623 super::device_reset::unretire(&self.path, name)
624 }
625 fn remove_retired_devices(&self) -> Result<(), FileError> {
626 super::device_reset::remove_retired(&self.path)
627 }
628 fn settings(&self) -> Result<StoreSettings, SettingsError> {
629 settings::read(&self.path, self.id)
630 }
631 fn bugs(&self) -> &BugSinkRef {
632 &self.bugs
633 }
634 async fn lock_for_open(&self) -> Result<StoreLock, StoreLockError> {
635 let guard = lock::acquire_for_open(&self.path, self.id, &self.bugs).await?;
636 self.check_published()?;
637 Ok(guard)
638 }
639 async fn lock_closed(&self) -> Result<ClosedStoreLock, StoreLockError> {
640 let guard = lock::acquire_closed(&self.path, self.id, &self.bugs).await?;
641 self.check_published()?;
642 Ok(guard)
643 }
644 fn lock_read_only(&self) -> Result<StoreReadLock, StoreLockError> {
645 let guard = lock::acquire_reader(&self.path, self.id)?;
646 self.check_published()?;
647 Ok(guard)
648 }
649 fn lock_cache_write(&self) -> Result<CacheWriteLock, FileError> {
650 lock::cache_writes(&self.path, true)
651 }
652 fn exclude_cache_writes(&self) -> Result<CacheWriteLock, FileError> {
653 lock::cache_writes(&self.path, false)
654 }
655 fn lock_for_deletion(&self) -> Result<Option<StoreDeletionLock>, StoreLockError> {
656 let bootstrapping = self.is_bootstrapping();
657 let locked = lock::for_deletion(&self.path, self.id, None);
658 if !bootstrapping
664 && matches!(locked, Ok(Some(_)) | Err(StoreLockError::AlreadyOpen(_)))
665 && super::device_reset::read(&self.path)?.is_none()
666 && super::bootstrap::is_pending(&self.path)?
667 {
668 return Err(StoreLockError::BootstrapPending(self.id));
669 }
670 locked
671 }
672 async fn closed(&self) -> Result<(), FileError> {
673 lock::closed(&self.path, self.id).await?;
674 lock::closed(&super::device_reset::loading(&self.path, self.id), self.id).await
680 }
681 fn owned_file(&self, file: StoreFile) -> AtomicFile {
682 AtomicFile::new(self.path.join(file.name()))
683 }
684 fn file(&self, area: FileArea, name: &FileName) -> AtomicFile {
685 AtomicFile::new(self.path.join(area.name()).join(&name.0))
686 }
687 fn create_writer(&self, area: FileArea, name: &FileName) -> Result<FileWriter, WriterError> {
688 Ok(self.writer_folder(area)?.create(name)?)
689 }
690 fn writer_folder(&self, area: FileArea) -> Result<WriterFolder, WriterError> {
691 let lock = self.lock_read_only()?;
692 Ok(WriterFolder::open(&self.path.join(area.name()), Arc::new(lock), self.bugs.clone())?)
693 }
694 fn resume_writer(
695 &self,
696 area: FileArea,
697 name: &FileName,
698 length: u64,
699 ) -> Result<FileWriter, WriterError> {
700 let lock = self.lock_read_only()?;
701 Ok(FileWriter::resume(&self.file(area, name), lock, self.bugs.clone(), length)?)
702 }
703 fn staged_file(&self, name: &StagedName) -> AtomicFile {
704 let (folder, copy) = name.parts();
705 AtomicFile::new(self.path.join(FileArea::AppProvided.name()).join(folder).join(copy))
706 }
707 fn staging_folder(
708 &self,
709 folder: &FileName,
710 #[cfg_attr(
711 not(unix),
712 expect(unused_variables, reason = "Windows writes a folder's entries through")
713 )]
714 batch: &mut FlushBatch,
715 ) -> Result<WriterFolder, StagingFolderError> {
716 let lock = Arc::new(self.lock_read_only().map_err(WriterError::from)?);
717 let files = self.path.join(FileArea::AppProvided.name());
718 let path = files.join(&folder.0);
719 match std::fs::create_dir(&path) {
720 Ok(()) => {}
721 Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
722 return Err(StagingFolderError::Taken(folder.clone()));
723 }
724 Err(source) => {
725 let error = FileError::at("create staging folder", &path, source);
726 return Err(WriterError::from(error).into());
727 }
728 }
729 #[cfg(unix)]
730 batch.add_folder(
731 BatchFolder::open(files.clone(), Some(lock.clone())).map_err(|source| {
732 WriterError::from(FileError::at("open folder", &files, source))
733 })?,
734 );
735 Ok(WriterFolder::open(&path, lock, self.bugs.clone()).map_err(WriterError::from)?)
736 }
737 fn remove_staged(&self, name: &StagedName) -> Result<(), FileError> {
738 let copy = self.staged_file(name);
739 copy.remove()?;
740 let (folder, _) = name.parts();
741 super::atomic_file::remove_empty_folder(
742 &self.path.join(FileArea::AppProvided.name()).join(folder),
743 )
744 }
745}
746
747#[cfg(test)]
748#[path = "directory_tests.rs"]
749mod tests;