//! State helper utility

//!

//! All the methods in this module perform appropriate mistrust checks.

//!

//! All the methods arrange to ensure suitably-finegrained exclusive access.

//! "Read-only" or "shared" mode is not supported.

//!

//! ### Differences from `tor_persist::StorageHandle`

//!

//!  * Explicit provision is made for multiple instances of a single facility.

//!    For example, multiple hidden services,

//!    each with their own state, and own lock.

//!

//!  * Locking (via filesystem locks) is mandatory, rather than optional -

//!    there is no "shared" mode.

//!

//!  * Locked state is represented in the Rust type system.

//!

//!  * We don't use traits to support multiple implementations.

//!    Platform support would be done in the future with `#[cfg]`.

//!    Testing is done by temporary directories (as currently with `tor_persist`).

//!

//!  * The serde-based `StorageHandle` requires `&mut` for writing.

//!    This ensures proper serialisation of 1. read-modify-write cycles

//!    and 2. use of the temporary file.

//!    Or to put it another way, we model `StorageHandle`

//!    as *containing* a `T` without interior mutability.

//!

//!  * There's a way to get a raw directory for filesystem operations

//!    (currently, will be used for IPT replay logs).

//!

//! ### Implied filesystem structure

//!

//! ```text

//! STATE_DIR/

//! STATE_DIR/KIND/INSTANCE_ID/

//! STATE_DIR/KIND/INSTANCE_ID/lock

//! STATE_DIR/KIND/INSTANCE_ID/KEY.json

//! STATE_DIR/KIND/INSTANCE_ID/KEY.new

//! STATE_DIR/KIND/INSTANCE_ID/KEY/

//!

//! eg

//!

//! STATE_DIR/hss/allium-cepa.lock

//! STATE_DIR/hss/allium-cepa/ipts.json

//! STATE_DIR/hss/allium-cepa/iptpub.json

//! STATE_DIR/hss/allium-cepa/iptreplay/

//! STATE_DIR/hss/allium-cepa/iptreplay/9aa9517e6901c280a550911d3a3c679630403db1c622eedefbdf1715297f795f.bin

//! ```

//!

// The instance's last modification time (see `purge_instances`) is the mtime of

// the INSTANCE_ID directory.  The lockfile mtime is not meaningful.

//

//! (The lockfile is outside the instance directory to facilitate

//! concurrency-correct deletion.)

//!

// Specifically:

//

// The situation where there is only the lockfile, is an out-of-course but legal one.

// Likewise, a lockfile plus a *partially* deleted instance state, is also legal.

// Having an existing directory without associated lockfile is forbidden,

// but if it should occur we handle it properly.

//

//! ### Comprehensive example

//!

//! ```

//! use std::{collections::HashSet, fmt, time::{Duration, SystemTime}};

//! use tor_error::{into_internal, Bug};

//! use tor_persist::slug::SlugRef;

//! use tor_persist::state_dir;

//! use state_dir::{InstanceIdentity, InstancePurgeHandler};

//! use state_dir::{InstancePurgeInfo, InstanceStateHandle, StateDirectory, StorageHandle};

//! #

//! # // fake up some things; we do this rather than using real ones

//! # // since this example will move, with the module, to a lower level crate.

//! # struct OnionService { }

//! # #[derive(derive_more::Display)] struct HsNickname(String);

//! # type Error = anyhow::Error;

//! # mod ipt_mgr { pub mod persist {

//! #     #[derive(serde::Serialize, serde::Deserialize)] pub struct StateRecord {}

//! # } }

//!

//! impl InstanceIdentity for HsNickname {

//!     fn kind() -> &'static str { "hss" }

//!     fn write_identity(&self, f: &mut fmt::Formatter) -> fmt::Result {

//!         write!(f, "{self}")

//!     }

//! }

//!

//! impl OnionService {

//!     fn new(

//!         nick: HsNickname,

//!         state_dir: &StateDirectory,

//!     ) -> Result<Self, Error> {

//!         let instance_state = state_dir.acquire_instance(&nick)?;

//!         let replay_log_dir = instance_state.raw_subdir("ipt_replay")?;

//!         let ipts_storage: StorageHandle<ipt_mgr::persist::StateRecord> =

//!             instance_state.storage_handle("ipts")?;

//!         // ..

//! #       Ok(OnionService { })

//!     }

//! }

//!

//! struct PurgeHandler<'h>(&'h HashSet<&'h str>, Duration);

//! impl InstancePurgeHandler for PurgeHandler<'_> {

//!     fn kind(&self) -> &'static str {

//!         <HsNickname as InstanceIdentity>::kind()

//!     }

//!     fn name_filter(&mut self, id: &SlugRef) -> state_dir::Result<state_dir::Liveness> {

//!         Ok(if self.0.contains(id.as_str()) {

//!             state_dir::Liveness::Live

//!         } else {

//!             state_dir::Liveness::PossiblyUnused

//!         })

//!     }

//!     fn age_filter(&mut self, id: &SlugRef, age: Duration)

//!              -> state_dir::Result<state_dir::Liveness>

//!     {

//!         Ok(if age > self.1 {

//!             state_dir::Liveness::PossiblyUnused

//!         } else {

//!             state_dir::Liveness::Live

//!         })

//!     }

//!     fn dispose(&mut self, _info: &InstancePurgeInfo, handle: InstanceStateHandle)

//!                -> state_dir::Result<()> {

//!         // here might be a good place to delete keys too

//!         handle.purge()

//!     }

//! }

//! pub fn expire_hidden_services(

//!     state_dir: &StateDirectory,

//!     currently_configured_nicks: &HashSet<&str>,

//!     retain_for: Duration,

//! ) -> Result<(), Error> {

//!     state_dir.purge_instances(

//!         SystemTime::now(),

//!         &mut PurgeHandler(currently_configured_nicks, retain_for),

//!     )?;

//!     Ok(())

//! }

//! ```

//!

//! ### Platforms without a filesystem

//!

//! The implementation and (in places) the documentation

//! is in terms of filesystems.

//! But, everything except `InstanceStateHandle::raw_subdir`

//! is abstract enough to implement some other way.

//!

//! If we wish to support such platforms, the approach is:

//!

//!  * Decide on an approach for `StorageHandle`

//!    and for each caller of `raw_subdir`.

//!

//!  * Figure out how the startup code will look.

//!    (Currently everything is in terms of `fs_mistrust` and filesystems.)

//!

//!  * Provide a version of this module with a compatible API

//!    in terms of whatever underlying facilities are available.

//!    Use `#[cfg]` to select it.

//!    Don't implement `raw_subdir`.

//!

//!  * Call sites using `raw_subdir` will no longer compile.

//!    Use `#[cfg]` at call sites to replace the `raw_subdir`

//!    with whatever is appropriate for the platform.

#![forbid(unsafe_code)] // if you remove this, enable (or write) miri tests (git grep miri)

use std::collections::HashSet;

use std::fmt::{self, Display};

use std::fs;

use std::io;

use std::marker::PhantomData;

use std::path::Path;

use std::sync::Arc;

use std::time::{Duration, SystemTime};

use derive_deftly::{Deftly, define_derive_deftly};

use derive_more::{AsRef, Deref};

use itertools::chain;

use serde::{Serialize, de::DeserializeOwned};

use fs_mistrust::{CheckedDir, Mistrust};

use tor_error::ErrorReport as _;

use tor_error::bad_api_usage;

use tracing::trace;

pub use crate::Error;

use crate::err::{Action, ErrorSource, Resource};

use crate::load_store;

use crate::slug::{BadSlug, Slug, SlugRef, TryIntoSlug};

#[allow(unused_imports)] // Simplifies a lot of references in our docs

use crate::slug;

define_derive_deftly! {

    ContainsInstanceStateGuard:

    impl<$tgens> ContainsInstanceStateGuard for $ttype where $twheres {

            self.flock_guard.clone()

        }

    }

}

/// Re-export of the lock guard type, as obtained via [`ContainsInstanceStateGuard`]

pub use fslock_guard::LockFileGuard;

use std::result::Result as StdResult;

use std::path::MAIN_SEPARATOR as PATH_SEPARATOR;

/// [`Result`](StdResult) throwing a [`state_dir::Error`](Error)

pub type Result<T> = StdResult<T, Error>;

/// Extension for lockfiles

const LOCK_EXTN: &str = "lock";

/// Suffix for lockfiles, precisely `"." + LOCK_EXTN`

// There's no way to concatenate constant strings with names!

// We could use the const_format crate maybe?

const DOT_LOCK: &str = ".lock";

/// The whole program's state directory

///

/// Representation of `[storage] state_dir` and `permissions`

/// from the Arti configuration.

///

/// This type does not embody any subpaths relating to

/// any particular facility within Arti.

///

/// Constructing a `StateDirectory` may involve filesystem permissions checks,

/// so ideally it would be created once per process for performance reasons.

///

/// Existence of a `StateDirectory` also does not imply exclusive access.

///

/// This type is passed to each facility's constructor;

/// the facility implements [`InstanceIdentity`]

/// and calls [`acquire_instance`](StateDirectory::acquire_instance).

///

/// ### Use for caches

///

/// In principle this type and the methods and subtypes available

/// would be suitable for cache data as well as state data.

///

/// However the locking scheme does not tolerate random removal of files.

/// And cache directories are sometimes configured to point to locations

/// with OS-supplied automatic file cleaning.

/// That would not be correct,

/// since the automatic file cleaner might remove an in-use lockfile,

/// effectively unlocking the instance state

/// even while a process exists that thinks it still has the lock.

#[derive(Debug, Clone)]

pub struct StateDirectory {

    /// The actual directory, including mistrust config

    dir: CheckedDir,

}

/// An instance of a facility that wants to save persistent state (caller-provided impl)

///

/// Each value of a type implementing `InstanceIdentity`

/// designates a specific instance of a specific facility.

///

/// For example, `HsNickname` implements `state_dir::InstanceIdentity`.

///

/// The kind and identity are [`slug`]s.

pub trait InstanceIdentity {

    /// Return the kind.  For example `hss` for a Tor Hidden Service.

    ///

    /// This must return a fixed string,

    /// since usually all instances represented the same Rust type

    /// are also the same kind.

    ///

    /// The returned value must be valid as a [`slug`].

    //

    // This precludes dynamically chosen instance kind identifiers.

    // If we ever want that, we'd need an InstanceKind trait that is implemented

    // not for actual instances, but for values representing a kind.

    fn kind() -> &'static str;

    /// Obtain identity

    ///

    /// The instance identity distinguishes different instances of the same kind.

    ///

    /// For example, for a Tor Hidden Service the identity is the nickname.

    ///

    /// The generated string must be valid as a [`slug`].

    /// If it is not, the functions in this module will throw `Bug` errors.

    /// (Returning `fmt::Error` will cause a panic, as is usual with the fmt API.)

    fn write_identity(&self, f: &mut fmt::Formatter) -> fmt::Result;

}

/// For a facility to be expired using [`purge_instances`](StateDirectory::purge_instances) (caller-provided impl)

///

/// A filter which decides which instances to delete,

/// and deletes them if appropriate.

///

/// See [`purge_instances`](StateDirectory::purge_instances) for full documentation.

pub trait InstancePurgeHandler {

    /// What kind to iterate over

    fn kind(&self) -> &'static str;

    /// Can we tell by its name that this instance is still live ?

    fn name_filter(&mut self, identity: &SlugRef) -> Result<Liveness>;

    /// Can we tell by recent modification that this instance is still live ?

    ///

    /// Many implementations won't need to use the `identity` parameter.

    ///

    /// ### Concurrency

    ///

    /// The `age` passed to this callback might

    /// sometimes not be the most recent modification time of the instance.

    /// But. before calling `dispose`, `purge_instances` will call this

    /// function at least once with a fully up-to-date modification time.

    fn age_filter(&mut self, identity: &SlugRef, age: Duration) -> Result<Liveness>;

    /// Decide whether to keep this instance

    ///

    /// When it has made its decision, `dispose` should

    /// either call [`delete`](InstanceStateHandle::purge),

    /// or simply drop `handle`.

    ///

    /// Called only after `name_filter` and `age_filter`

    /// both returned [`Liveness::PossiblyUnused`].

    ///

    /// `info` includes the instance name and other useful information

    /// such as the last modification time.

    ///

    /// Note that although the existence of `handle` implies

    /// there can be no other `InstanceStateHandle`s for this instance,

    /// the last modification time of this instance has *not* been updated,

    /// as it would be by [`acquire_instance`](StateDirectory::acquire_instance).

    fn dispose(&mut self, info: &InstancePurgeInfo, handle: InstanceStateHandle) -> Result<()>;

}

/// Information about an instance, passed to [`InstancePurgeHandler::dispose`]

#[derive(Debug, Clone, amplify::Getters, AsRef)]

pub struct InstancePurgeInfo<'i> {

    /// The instance's identity string

    #[as_ref]

    identity: &'i SlugRef,

    /// When the instance state was last updated, according to the filesystem timestamps

    ///

    /// See `[InstanceStateHandle::purge_instances]`

    /// for details of what kinds of events count as modifications.

    last_modified: SystemTime,

}

/// Is an instance still relevant?

///

/// Returned by [`InstancePurgeHandler::name_filter`].

///

/// See [`StateDirectory::purge_instances`] for details of the semantics.

#[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash)]

#[allow(clippy::exhaustive_enums)] // this is a boolean

pub enum Liveness {

    /// This instance is not known to be interesting

    ///

    /// It could be perhaps expired, if it's been long enough

    PossiblyUnused,

    /// This instance is still wanted

    Live,

}

/// Objects that co-own a lock on an instance

///

/// Each type implementing this trait mutually excludes independently-acquired

/// [`InstanceStateHandle`]s, and anything derived from them

/// (including, therefore, `ContainsInstanceStateGuard` implementors

/// with independent provenance.)

pub trait ContainsInstanceStateGuard {

    /// Obtain a raw clone of the underlying filesystem lock

    ///

    /// This lock (and clones of it) will mutually exclude

    /// re-acquisition of the same instance.

    fn raw_lock_guard(&self) -> Arc<LockFileGuard>;

}

/// Instance identity string formatter, type-erased

type InstanceIdWriter<'i> = &'i dyn Fn(&mut fmt::Formatter) -> fmt::Result;

impl StateDirectory {

    /// Create a new `StateDirectory` from a directory and mistrust configuration

        /// Implementation, taking non-generic path

    /// Acquires (creates and locks) a storage for an instance

    ///

    /// Ensures the existence and suitability of a subdirectory named `kind/identity`,

    /// and locks it for exclusive access.

        /// Implementation, taking non-generic values for identity

                // Obtain (creating if necessary) a subdir for a Checked

                // ---- obtain the lock ----

                    }

                    }

                    Ok(None) => {

                    }

                };

                // ---- we have the lock, calculate the directory (creating it if need be) ----

    /// Given a kind and id, obtain pieces of its path and call a "doing work" callback

    ///

    /// This function factors out common functionality needed by

    /// [`StateDirectory::acquire_instance`] and [`StateDirectory::instance_peek_storage`],

    /// particularly relating to instance kind and id, and errors.

    ///

    /// `kind` and `id` are from an `InstanceIdentity`.

        /// Struct that impls `Display` for formatting an instance id

        //

        // This exists because we want implementors of InstanceIdentity to be able to

        // use write! to format their identity string.

        struct InstanceIdDisplay<'i>(InstanceIdWriter<'i>);

        impl Display for InstanceIdDisplay<'_> {

        }

        // Both we and caller use this for our error reporting

    /// List the instances of a particular kind

    ///

    /// Returns the instance identities.

    ///

    /// (The implementation lists subdirectories named `kind_*`.)

    ///

    /// Concurrency:

    /// An instance which is not being removed or created will be

    /// listed (or not) according to whether it's present.

    /// But, in the presence of concurrent calls to `acquire_instance` and `delete`

    /// on different instances,

    /// is not guaranteed to provide a snapshot:

    /// serialisation is not guaranteed across different instances.

    ///

    /// It *is* guaranteed to list each instance only once.

    /// List the instances of a kind, where the kind is supplied as a value

    ///

    /// Used by `list_instances` and `purge_instances`.

    ///

    /// *Includes* instances that exists only as a stale lockfile.

    #[allow(clippy::blocks_in_conditions)] // TODO #1176 this wants to be global

    #[allow(clippy::redundant_closure_call)] // false positive, re handle_err

        // We collect the output into these

        // Error handling

        /// `fn handle_err!()(source: impl Into<ErrorSource>) -> Error`

        //

        // (Generic, so can't be a closure.  Uses local bindings, so can't be a fn.)

        macro_rules! handle_err { { } => {

        } }

        // Obtain an iterator of Result<DirEntry>

        })() {

                            // Actually handle a directory entry!

                                // look for either ID or ID.lock

                            })() else {

                            };

                        }

                    }

                }

            }

        }

    /// Delete instances according to selections made by the caller

    ///

    /// Each instance is considered in three stages.

    ///

    /// Firstly, it is passed to [`name_filter`](InstancePurgeHandler::name_filter).

    /// If `name_filter` returns `Live`,

    /// further consideration is skipped and the instance is retained.

    ///

    /// Secondly, the last time the instance was written to is determined,

    // This must be done with the lock held, for correctness

    // but the lock must be acquired in a way that doesn't itself update the modification time.

    // On Unix this is straightforward because opening for write doesn't update the mtime.

    // If this is hard on another platform, we'll need a separate stamp file updated

    // by an explicit Acquire operation.

    // This is tested by `test_reset_expiry`.

    /// and passed to

    /// [`age_filter`](InstancePurgeHandler::age_filter).

    /// Again, this might mean ensure the instance is retained.

    ///

    /// Thirdly, the resulting `InstanceStateHandle` is passed to

    /// [`dispose`](InstancePurgeHandler::dispose).

    /// `dispose` may choose to call `handle.delete()`,

    /// or simply drop the handle.

    ///

    /// Concurrency:

    /// In the presence of multiple concurrent calls to `acquire_instance` and `delete`:

    /// `filter` may be called for an instance which is being created or deleted

    /// by another task.

    /// `dispose` will be properly serialised with other activities on the same instance,

    /// as implied by it receiving an `InstanceStateHandle`.

    ///

    /// The expiry time is reset by calls to `acquire_instance`,

    /// `StorageHandle::store` and `InstanceStateHandle::raw_subdir`;

    /// it *may* be reset by calls to `StorageHandle::delete`.

    ///

    /// Instances that are currently locked by another task will not be purged,

    /// but the expiry time is *not* reset by *unlocking* an instance

    /// (dropping the last clone of an `InstanceStateHandle`).

    ///

    /// ### Sequencing of `InstancePurgeHandler` callbacks

    ///

    /// Each instance will be processed

    /// (and callbacks made for it) at most once;

    /// and calls for different instances will not be interleaved.

    ///

    /// During the processing of a particular instance

    /// The callbacks will be made in order,

    /// progressing monotonically through the methods in the order listed.

    /// But `name_filter` and `age_filter` might each be called

    /// more than once for the same instance.

    // We don't actually call name_filter more than once.

    ///

    /// Between each stage,

    /// the purge implementation may discover that the instance

    /// ought not to be processed further.

    /// So returning `Liveness::PossiblyUnused` from a filter does not

    /// guarantee that the next callback will be made.

        }

    /// Consider whether to purge an instance

    ///

    /// Performs all the necessary steps, including liveness checks,

    /// passing an InstanceStateHandle to filter.dispose,

    /// and deleting stale lockfiles without associated state.

    #[allow(clippy::cognitive_complexity)] // splitting this would be more, not less, confusing

        /// If `$l` is `Liveness::Live`, returns early with `Ok(())`.

        macro_rules! check_liveness { { $l:expr } => {

            match $l {

                Liveness::Live => return Ok(()),

                Liveness::PossiblyUnused => {},

            }

        } }

        // Checks whether it should be kept due to being recently modified.

        // None::<SystemTime> means the instance directory is ENOENT

        // (which must mean that the instance exists only as a stale lockfile).

            // 1. stat the instance dir

                // If instance dir is ENOENT, treat as old (maybe there was just a lockfile)

                }

            };

            // 2. calculate the age

            // 3. do the age check

        // preliminary check, without locking yet

        // ok we're probably doing to pass it to dispose (for possible deletion)

            }

                // We couldn't open the lockfile due to ENOENT

                // (Presumably) a containing directory is gone, so we don't need to do anything.

            }

            Ok(None) => {

                // Someone else has it locked.  Skip purging it.

            }

                );

            }

        };

        // recheck to see if anyone has updated it

        // We have locked it and the filters say to maybe purge it.

            None => {

                // And it doesn't even exist!  All we have is a leftover lockfile.  Delete it.

            }

                // Construct a state handle.

            }

        }

    /// Tries to peek at something written by [`StorageHandle::store`]

    ///

    /// It is guaranteed that this will return either the `T` that was stored,

    /// or `None` if `store` was never called,

    /// or `StorageHandle::delete` was called

    ///

    /// So the operation is atomic, but there is no further synchronisation.

    //

    // Not sure if we need this, but it's logically permissible

            // This closure is generic over T, so with_instance_path_pieces will be too;

            // this isn't desirable (code bloat) but avoiding it would involves some contortions.

                // Throwing this error here will give a slightly wrong Error for this Bug

                // (because with_instance_path_pieces has its own notion of Action & Resource)

                // but that seems OK.

                    kind_slug, id_slug, key_slug,

                );

                    // This Resource::File isn't consistent with those from StorageHandle:

                    // StorageHandle's `container` is the instance directory;

                    // here `container` is the top-level `state_dir`,

                    // and `file` is `KIND+INSTANCE/STORAGE.json".

                        )

        )

}

/// State or cache directory for an instance of a facility

///

/// Implies exclusive access:

/// there is only one `InstanceStateHandle` at a time,

/// across any number of processes, tasks, and threads,

/// for the same instance.

///

/// # Key uniqueness and syntactic restrictions

///

/// Methods on `InstanceStateHandle` typically take a [`TryIntoSlug`].

///

/// **It is important that keys are distinct within an instance.**

///

/// Specifically:

/// each key provided to a method on the same [`InstanceStateHandle`]

/// (or a clone of it)

/// must be different.

/// Violating this rule does not result in memory-unsafety,

/// but might result in incorrect operation due to concurrent filesystem access,

/// including possible data loss and corruption.

/// (Typically, the key is fixed, and the [`StorageHandle`]s are usually

/// obtained during instance construction, so ensuring this is straightforward.)

///

/// There are also syntactic restrictions on keys.  See [slug].

// We could implement a runtime check for this by retaining a table of in-use keys,

// possibly only with `cfg(debug_assertions)`.  However I think this isn't worth the code:

// it would involve an Arc<Mutex<SlugsInUseTable>> in InstanceStateHnndle and StorageHandle,

// and Drop impls to remove unused entries (and `raw_subdir` would have imprecise checking

// unless it returned a Drop newtype around CheckedDir).

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(ContainsInstanceStateGuard)]

pub struct InstanceStateHandle {

    /// The directory

    dir: CheckedDir,

    /// Lock guard

    flock_guard: Arc<LockFileGuard>,

}

impl InstanceStateHandle {

    /// Obtain a [`StorageHandle`], usable for storing/retrieving a `T`

    ///

    /// [`key` has syntactic and uniqueness restrictions.](InstanceStateHandle#key-uniqueness-and-syntactic-restrictions)

        /// Implementation, not generic over `slug` and `T`

    /// Obtain a raw filesystem subdirectory, within the directory for this instance

    ///

    /// This API is unsuitable platforms without a filesystem accessible via `std::fs`.

    /// May therefore only be used within Arti for features

    /// where we're happy to not to support such platforms (eg WASM without WASI)

    /// without substantial further work.

    ///

    /// [`key` has syntactic and uniqueness restrictions.](InstanceStateHandle#key-uniqueness-and-syntactic-restrictions)

        /// Implementation, not generic over `slug`

            })()

                )

    /// Unconditionally delete this instance directory

    ///

    /// For expiry, use `StateDirectory::purge_instances`,

    /// and then call this in the `dispose` method.

    ///

    /// Will return a `BadAPIUsage` if other clones of this `InstanceStateHandle` exist.

    ///

    /// ### Deletion is *not* atomic

    ///

    /// If a deletion operation doesn't complete for any reason

    /// (maybe it was interrupted, or there was a filesystem access problem),

    /// *part* of the instance contents may remain.

    ///

    /// After such an interrupted deletion,

    /// storage items ([`StorageHandle`]) are might each independently

    /// be deleted ([`load`](StorageHandle::load) returns `None`)

    /// or retained (`Some`).

    ///

    /// Deletion of the contents of raw subdirectories

    /// ([`InstanceStateHandle::raw_subdir`])

    /// is done with `std::fs::remove_dir_all`.

    /// If deletion is interrupted, the raw subdirectory may contain partial contents.

    //

    // In principle we could provide atomic deletion, but it would lead to instances

    // that were in "limbo": they exist, but wouldn't appear in list_instances,

    // and the deletion would need to be completed next time they were acquired

    // (or during a purge_instances run).

    //

    // In practice we expect that callers will not try to use a partially-deleted instance,

    // and that if they do they will fail with a "state corrupted" error, which would be fine.

            // use Arc::into_inner on the lock object,

            // to make sure we're actually the only surviving InstanceStateHandle

                )

                // dir.with_extension is right because the last component of dir

                // is KIND+ID which doesn't contain `.` so no extension will be stripped

        })()

            )

}

/// Touch an instance the state directory, `dir`, for expiry purposes

/// A place in the state or cache directory, where we can load/store a serialisable type

///

/// Implies exclusive access.

///

/// Rust mutability-xor-sharing rules enforce proper synchronisation,

/// unless multiple `StorageHandle`s are created

/// using the same [`InstanceStateHandle`] and key.

#[derive(Deftly, Debug)] // not Clone, to enforce mutability rules (see above)

#[derive_deftly(ContainsInstanceStateGuard)]

pub struct StorageHandle<T> {

    /// The directory and leafname

    instance_dir: CheckedDir,

    /// `KEY.json`

    leafname: String,

    /// We can load and store a `T`.

    ///

    /// Invariant in `T`.  But we're `Sync` and `Send` regardless of `T`.

    /// (From the Table of PhantomData patterns in the Nomicon.)

    marker: PhantomData<fn(T) -> T>,

    /// Clone of the InstanceStateHandle's lock

    flock_guard: Arc<LockFileGuard>,

}

// Like tor_persist, but writing needs `&mut`

impl<T: Serialize + DeserializeOwned> StorageHandle<T> {

    /// Load this persistent state

    ///

    /// `None` means the state was most recently [`delete`](StorageHandle::delete)ed

    /// Store this persistent state

        // The renames will cause a directory mtime update

    /// Delete this persistent state

        // Only counts as a recent modification if this state *did* exist

    /// Operate using a `load_store::Target`

    {

    /// Helper to convert an `ErrorSource` to an `Error`, if we were performing `action`

    /// Return the proper `Resource` for reporting errors

}

/// Subdirectory within an instance's state, for raw filesystem operations

///

/// Dereferences to `fs_mistrust::CheckedDir` and can be used mostly like one.

/// Obtained from [`InstanceStateHandle::raw_subdir`].

///

/// Existence of this value implies exclusive access to the instance.

///

/// If you need to manage the lock, and the directory path, separately,

/// [`raw_lock_guard`](ContainsInstanceStateGuard::raw_lock_guard)

///  will help.

#[derive(Deref, Clone, Debug, Deftly)]

#[derive_deftly(ContainsInstanceStateGuard)]

pub struct InstanceRawSubdir {

    /// The actual directory, as a [`fs_mistrust::CheckedDir`]

    #[deref]

    dir: CheckedDir,

    /// Clone of the InstanceStateHandle's lock

    flock_guard: Arc<LockFileGuard>,

}

#[cfg(all(test, not(miri) /* filesystem access */))]

mod test {

    // @@ begin test lint list maintained by maint/add_warning @@

    #![allow(clippy::bool_assert_comparison)]

    #![allow(clippy::clone_on_copy)]

    #![allow(clippy::dbg_macro)]

    #![allow(clippy::mixed_attributes_style)]

    #![allow(clippy::print_stderr)]

    #![allow(clippy::print_stdout)]

    #![allow(clippy::single_char_pattern)]

    #![allow(clippy::unwrap_used)]

    #![allow(clippy::unchecked_duration_subtraction)]

    #![allow(clippy::useless_vec)]

    #![allow(clippy::needless_pass_by_value)]

    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->

    use super::*;

    use derive_deftly::{Deftly, derive_deftly_adhoc};

    use itertools::{Itertools, iproduct};

    use serde::{Deserialize, Serialize};

    use std::collections::BTreeSet;

    use std::fmt::Display;

    use std::fs::File;

    use std::io;

    use std::str::FromStr;

    use test_temp_dir::test_temp_dir;

    use tor_basic_utils::PathExt as _;

    use tor_error::HasKind as _;

    use tracing_test::traced_test;

    use tor_error::ErrorKind as TEK;

    type AgeDays = i8;

    fn days(days: AgeDays) -> Duration {

        Duration::from_secs(86400 * u64::try_from(days).unwrap())

    }

    fn now() -> SystemTime {

        SystemTime::now()

    }

    struct Garlic(Slug);

    impl InstanceIdentity for Garlic {

        fn kind() -> &'static str {

            "garlic"

        }

        fn write_identity(&self, f: &mut fmt::Formatter) -> fmt::Result {

            Display::fmt(&self.0, f)

        }

    }

    #[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq)]

    struct StoredData {

        some_value: i32,

    }

    fn mk_state_dir(dir: &Path) -> StateDirectory {

        StateDirectory::new(

            dir,

            &fs_mistrust::Mistrust::new_dangerously_trust_everyone(),

        )

        .unwrap()

    }

    #[test]

    #[traced_test]

    fn test_api() {

        test_temp_dir!().used_by(|dir| {

            let sd = mk_state_dir(dir);

            let garlic = Garlic("wild".try_into_slug().unwrap());

            let acquire_instance = || sd.acquire_instance(&garlic);

            let ih = acquire_instance().unwrap();

            let inst_path = dir.join("garlic/wild");

            assert!(fs::metadata(&inst_path).unwrap().is_dir());

            assert_eq!(

                acquire_instance().unwrap_err().kind(),

                TEK::LocalResourceAlreadyInUse,

            );

            let irsd = ih.raw_subdir("raw").unwrap();

            assert!(fs::metadata(irsd.as_path()).unwrap().is_dir());

            assert_eq!(irsd.as_path(), dir.join("garlic").join("wild").join("raw"));

            let mut sh = ih.storage_handle::<StoredData>("stored_data").unwrap();

            let storage_path = dir.join("garlic/wild/stored_data.json");

            let peek = || sd.instance_peek_storage(&garlic, "stored_data");

            let expect_load = |sh: &StorageHandle<_>, expect| {

                let check_loaded = |what, loaded: Result<Option<StoredData>>| {

                    assert_eq!(loaded.unwrap().as_ref(), expect, "{what}");

                };

                check_loaded("load", sh.load());

                check_loaded("peek", peek());

            };

            expect_load(&sh, None);

            let to_store = StoredData { some_value: 42 };

            sh.store(&to_store).unwrap();

            assert!(fs::metadata(storage_path).unwrap().is_file());

            expect_load(&sh, Some(&to_store));

            sh.delete().unwrap();

            expect_load(&sh, None);

            drop(sh);

            drop(irsd);

            ih.purge().unwrap();

            assert_eq!(peek().unwrap(), None);

            assert_eq!(

                fs::metadata(&inst_path).unwrap_err().kind(),

                io::ErrorKind::NotFound

            );

        });

    }

    #[test]

    #[traced_test]

    #[allow(clippy::comparison_chain)]

    #[allow(clippy::expect_fun_call)]

    fn test_iter() {

        // Tests list_instances and purge_instances.

        //

        //  1. Set up a single state directory containing a number of instances,

        //    enumerating all the possible situations that purge_instance might find.

        //    The instance is identified by a `Which` which specifies its properties,

        //    and which is representable as the instance id slug.

        //  1b. Put some junk in the state directory too, that we expect to be ignored.

        //

        //  2. Call list_instances and check that we see what we expect.

        //

        //  3. Call purge_instances and check that all the callbacks happen as we expect.

        //

        //  4. Call list_instances again and check that we see what we now expect.

        //

        //  5. Check that the junk is still present.

        let temp_dir = test_temp_dir!();

        let state_dir = temp_dir.used_by(mk_state_dir);

        /// Reified test case spec for expiry

        //

        // For non-`bool` fields, `#[deftly(test = )]` gives the set of values to test.

        #[derive(Deftly, Eq, PartialEq, Debug)]

        #[derive_deftly_adhoc]

        struct Which {

            /// Does `name_filter` return `Live`?

            namefilter_live: bool,

            /// What is the oldest does `age_filter` will return `Live` for?

            #[deftly(test = "0, 2")]

            max_age: AgeDays,

            /// How long ago was the instance dir actually modified?

            #[deftly(test = "-1, 1, 3")]

            age: AgeDays,

            /// Does the instance dir exist?

            dir: bool,

            /// Does the instance !lockfile exist?

            lockfile: bool,

        }

        /// Ad-hoc (de)serialisation scheme of `Which` as an instance id (a `Slug`)

        ///

        /// The serialisation is `n<namefilter_live>_m<max_age>_...`,

        /// ie, for each field, the initial letter of its name, followed by the value.

        /// (We don't bother suppressing the trailiong `_`).

        impl Display for Which {

            fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {

                derive_deftly_adhoc! {

                    Which:

                    $(

                        write!(

                            f, "{}{}_",

                            stringify!($fname).chars().next().unwrap(),

                            self.$fname,

                        )?;

                    )

                }

                Ok(())

            }

        }

        impl FromStr for Which {

            type Err = Error;

            fn from_str(s: &str) -> Result<Self> {

                let mut fields = s.split('_');

                derive_deftly_adhoc! {

                    Which:

                    Ok(Which { $(

                        $fname: fields.next().unwrap()

                            .split_at(1).1

                            .parse().unwrap(),

                    )})

                }

            }

        }

        impl InstanceIdentity for Which {

            fn kind() -> &'static str {

                "which"

            }

            fn write_identity(&self, f: &mut fmt::Formatter) -> fmt::Result {

                Display::fmt(self, f)

            }

        }

        // 0. Calculate all possible whiches

        let whiches = {

            derive_deftly_adhoc!(

                Which:

                iproduct!(

                    $(

                        ${if fmeta(test) { [ ${fmeta(test) as token_stream} ] }