lib_efo/epoch/

epoch_config.rs

//! Management of the *current-epoch* configuration.
//!
//! The configuration is stored in a file named `.epoch` and contains only
//! the lightweight information needed for the CLI to switch between epochs
//! quickly:
//! * the numeric ID of the current epoch,
//! * a map of human-friendly tags to epoch IDs,
//! * a map of known epoch IDs to unloaded metadata (`EpochInfo`).
//!
//! The world data and all event logs belong to the individual epoch
//! directories and are **not** part of this file.

use crate::{
    epoch::{
        EpochId, EpochIdentifier, EpochInfo, MAIN_NAME, SUBFOLDER_NAMING, SaveMode, TagList,
        epoch_traits::ConfigWritable,
    },
    stats::{self, Symbols},
};
use colored::*;
use std::{
    collections::HashMap,
    fs::{read_to_string, remove_dir_all},
    path::Path,
};

use log::{info, warn};
use serde::{Deserialize, Serialize};

use crate::error::EpochError;

/// The file written to *.epochconfig* that tells the CLI which
/// epoch folder is the “current” one.
///
/// Only the minimal information needed for fast switches is stored:
/// * the numeric identifier of the selected epoch,
/// * a list of human-readable tags,
/// * the absolute path to the epoch's directory.
///
/// No world or event data lives here - it is purely a lightweight pointer.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EpochConfig {
    /// The epoch ID that the binary should consider “current”.
    pub epoch_id: EpochId,

    /// The version of the file loaded, and hopefully of all the project
    pub version: String,

    /// Optional human-friendly tags (e.g. `"winter-B"`, `"post-war"`).
    pub tags: HashMap<String, EpochId>,
    // TODO(6): Can become important
    // #[serde(skip)]
    // /// Absolute path to `epoch/<epoch_id>/`.
    // pub path: PathBuf,
    /// A hashmap containing the name of all existing epochs, only loaded in memory if used
    #[serde(skip)]
    pub list_existing_epochs: HashMap<EpochId, Option<EpochInfo>>,
}

impl Default for EpochConfig {
    /// Create an empty config, mainly for initialisation
    fn default() -> Self {
        EpochConfig {
            epoch_id: EpochId::new(0),
            tags: HashMap::new(),
            list_existing_epochs: HashMap::new(),
            version: env!("EFO_SHORT_VERSION").to_string(),
        }
    }
}

impl EpochConfig {
    /// Create a new config from an existig path
    pub fn new_from_path(_path: Option<&Path>) -> Result<Self, EpochError> {
        let path = Path::new(MAIN_NAME);

        if path.is_file() {
            // TODO(6): write a trait for this
            let config: EpochConfig = serde_json::from_str(&io_err_with_help!(
                read_to_string(path),
                "Reading config from path {:?}",
                path
            )?)
            .map_err(|e| EpochError::Serde {
                source: e,
                file_name: path.to_string_lossy().to_string(),
                version: format!("Current version: {}", env!("EFO_SHORT_VERSION")),
            })?;
            Ok(config.initialize()?)
        } else {
            Err(EpochError::MainFolderInvalid(
                EpochConfig::default().save_folder(),
            ))
        }
    }

    /// Output the current version vs the filesystem version
    pub fn version(&self) -> String {
        format!(
            "Program version {}.\nFilesystem version: {}.",
            self.version,
            env!("EFO_SHORT_VERSION")
        )
    }

    /// Initialize the epoch structure in depth.
    ///
    /// Scans the default configuration folder for sub-directories that are
    /// interpreted as epoch identifiers, logs each discovered epoch and
    /// registers it in the in-memory cache.
    ///
    /// This function may return an error if the configuration folder cannot
    /// be read or if any directory name cannot be parsed as an `EpochId`.
    pub(crate) fn initialize(mut self) -> Result<Self, EpochError> {
        let path = EpochConfig::default().save_subfolder();
        let path = io_err_with_help!(Path::new(&path).read_dir(), "Reading initial folder {path}")?;
        // let mut valid_folders = HashMap::new();
        for elt in path {
            let elt = io_err_with_help!(elt, "Opening file in main config folder")?;
            if io_err_with_help!(elt.file_type(), "Determining file type of {:?}", elt)?.is_dir() {
                let id = elt.file_name().to_string_lossy().parse::<EpochId>()?;
                info!("Preloaded Epoch {:?}", id);
                self.list_existing_epochs.insert(id, None);
            }
        }
        Ok(self)
    }

    /// Loads the metadata for an epoch from disk into the in-memory cache.
    ///
    /// The epoch identified by `epoch_id` must exist in `list_existing_epochs`.
    /// The JSON file on disk is read, deserialized into an `EpochInfo`, and
    /// stored in the map.  Any existing value for that epoch is overwritten.
    ///
    /// # Returns
    /// * `Ok(())` when the epoch was successfully read and cached.
    /// * `Err(EpochError::EpochNotFound(..))` if the epoch is not present in the
    ///   internal map.
    /// * `Err(EpochError::Serde { .. })` if the JSON file could not be parsed.
    /// * `Err(EpochError::Io { .. })` if the file could not be read.
    pub fn try_load(&mut self, epoch_id: &EpochId) -> Result<(), EpochError> {
        // Preload the epoch
        let version = self.version();
        let value = self
            .list_existing_epochs
            .get_mut(epoch_id)
            .ok_or(EpochError::EpochNotFound(format!("{epoch_id}")))?;

        // Create a mock epoch
        let path = EpochInfo::with_id(epoch_id).save_path();
        let read_to_string = io_err_with_help!(read_to_string(&path), "Reading {:?}", path);

        // Try to load
        let maybe_epoch: EpochInfo =
            serde_json::from_str(&read_to_string?).map_err(|e| EpochError::Serde {
                source: e,
                file_name: path.to_string(),
                version,
            })?;
        log::info!("Fully loaded Epoch {:?}", epoch_id);

        // Overwrite the value
        *value = Some(maybe_epoch);
        Ok(())
    }

    /// Load the currently active epoch.
    ///
    /// This helper first ensures that the current epoch's metadata is cached
    /// by delegating to `try_load`, then returns a reference to it.
    ///
    /// # Returns
    /// * `Ok(&EpochInfo)` - Reference to the cached epoch.
    /// * Propagates any error from `try_load`.
    pub fn try_load_current(&mut self) -> Result<&EpochInfo, EpochError> {
        self.try_load(&self.epoch_id.clone())?;
        unsafe { self.try_load_id(self.epoch_id) }
    }

    /// Load an epoch by its identifier.
    ///
    /// The caller must guarantee that the epoch has already been loaded into
    /// the cache (e.g. by calling `try_load`).  This function is marked `unsafe`
    /// because it performs a raw reference conversion without performing that
    /// check.
    ///
    /// # Safety
    /// Calling this function when the requested epoch has not yet been
    /// loaded results in undefined behaviour.
    ///
    /// # Arguments
    /// * `epoch_id` - Identifier of the epoch to load.
    ///
    /// # Returns
    /// * `Ok(&EpochInfo)` - Reference to the cached epoch.
    /// * `Err(EpochError::EpochHashingImpossible(..))` - The identifier is
    ///   unknown.
    /// * `Err(EpochError::LoadingEpochId(..))` - The epoch data is not yet
    ///   present in the cache.
    pub unsafe fn try_load_id(&self, epoch_id: EpochId) -> Result<&EpochInfo, EpochError> {
        let current = self
            .list_existing_epochs
            .get(&epoch_id)
            .ok_or(EpochError::EpochHashingImpossible(file!(), line!()))?
            .as_ref()
            .ok_or(EpochError::LoadingEpochId(self.epoch_id))?;
        Ok(current)
    }

    /// Load the currently active epoch mutably.
    ///
    /// This is a convenience wrapper that forwards to `try_load_id_as_mut`
    /// for the current epoch.
    ///
    /// # Returns
    /// * `Ok(&mut EpochInfo)` - Mutable reference to the cached epoch.
    /// * Propagates any error from the underlying load routine.
    pub fn try_load_current_as_mut(&mut self) -> Result<&mut EpochInfo, EpochError> {
        self.try_load_id_as_mut(self.epoch_id)
    }

    /// Load an epoch's metadata mutably.
    ///
    /// The function guarantees that the epoch data is present in the cache
    /// by first invoking `try_load` on the current epoch ID.  It then
    /// retrieves a mutable reference to the requested epoch.
    ///
    /// # Arguments
    /// * `epoch_id` - Identifier of the epoch to load.
    ///
    /// # Returns
    /// * `Ok(&mut EpochInfo)` - Mutable reference to the cached epoch.
    /// * `Err(EpochError::EpochHashingImpossible(..))` - The identifier is
    ///   unknown.
    /// * `Err(EpochError::LoadingEpochId(..))` - The epoch data is not yet
    ///   present in the cache.
    ///
    /// # Notes
    /// The call to `try_load` may incur a small performance penalty because
    /// it ensures that the epoch metadata is read from disk even when the
    /// caller already knows the epoch is cached.  This function is *not* `unsafe`;
    /// it performs all safety checks internally.
    fn try_load_id_as_mut(&mut self, epoch_id: EpochId) -> Result<&mut EpochInfo, EpochError> {
        self.try_load(&self.epoch_id.clone())?;
        let current = self
            .list_existing_epochs
            .get_mut(&epoch_id)
            .ok_or(EpochError::EpochHashingImpossible(file!(), line!()))?
            .as_mut()
            .ok_or(EpochError::LoadingEpochId(self.epoch_id))?;
        Ok(current)
    }

    /// Retrieves the internal epoch ID for a given identifier.
    ///
    /// The identifier can be either a *tag* string (`EpochIdentifier::Tag`) or an
    /// explicit epoch ID (`EpochIdentifier::Id`).  
    /// * When a tag is supplied the function looks up the corresponding epoch ID in
    ///   the `tags` map.  
    /// * When an ID is supplied it verifies that an epoch with that ID exists in
    ///   `list_existing_epochs` and returns it.
    ///
    /// # Returns
    /// * `Ok(epoch_id)` when the identifier is successfully resolved.  
    /// * `Err(EpochError::AmbiguousTag(tag))` if a supplied tag does not exist.  
    /// * `Err(EpochError::EpochFolderMissing(id, path))` if an ID does not have an
    ///   associated epoch folder.
    pub fn get_epoch_id(&self, id: &EpochIdentifier) -> Result<EpochId, EpochError> {
        match id {
            EpochIdentifier::Tag(s) => self
                .tags
                .get(s)
                .copied()
                .ok_or(EpochError::AmbiguousTag(s.to_string())),
            EpochIdentifier::Id(epoch_id) => self
                .list_existing_epochs
                .contains_key(epoch_id)
                .then_some(epoch_id)
                .ok_or(EpochError::EpochFolderMissing(
                    *epoch_id,
                    EpochConfig::default().save_folder().into(),
                ))
                .copied(),
        }
    }

    /// Return the name of the subfolder used to save this structure
    pub(crate) fn save_subfolder(&self) -> String {
        format!("{}/", SUBFOLDER_NAMING)
    }

    /// Delete an entire epoch folder by its ID.
    ///
    /// The function removes the directory, deletes all references to the
    /// epoch from `list_existing_epochs` and `tags`, and then writes the
    /// updated configuration to disk.
    // TODO(9): Create a delete_ids taking an iterator for added performance on huge deletions
    pub fn delete_id(&mut self, id: EpochId) -> Result<(), EpochError> {
        if !self.list_existing_epochs.contains_key(&id) {
            warn!(
                "The given epoch {} doesn't exists and it's deletion was skipped",
                id
            )
        } else {
            io_err_with_help!(
                remove_dir_all(EpochInfo::with_id(&id).save_folder()),
                "Removing the epoch {}",
                id
            )?;
            self.list_existing_epochs.remove(&id);
            self.tags.retain(|_k, v| *v != id);
            self.save_with_context("Saving after delete_id", &SaveMode::Erase)?;
        }
        Ok(())
    }

    /// Compute the next epoch.
    ///
    /// Currently this function is a placeholder that creates a new epoch
    /// with the ID immediately following the current one.  The actual logic
    /// is deferred to the `EpochInfo -> World` subsystem.
    pub fn compute_next(&mut self) -> Result<EpochInfo, EpochError> {
        // unimplemented!();
        // Iter on events, increment time
        // Iter on character, increment time
        //
        // create a new_towns_values vector, update it with base stats, then all events modifying underlying value
        // create_new_character_base_v vector, do the same
        // calculate the temps values (via function)
        // TODO(1): Implement this
        warn!("DEBUG LINE: COMPUTING NEXT EPOCH");
        // Set base for new epoch
        let mut new_epoch = self.try_load_current()?.clone();
        let _ = self.increment_time(&mut new_epoch);
        new_epoch.epoch_id = self.epoch_id.next();
        new_epoch.summary = String::new();
        new_epoch.tags = TagList::new();

        // Increment time on all events
        Ok(new_epoch)
    }

    /// Increment time, can only be called from inside
    /// Must be called on initialized data
    fn increment_time(&mut self, new_epoch: &mut EpochInfo) -> Result<(), EpochError> {
        new_epoch
            .iter_all_entities_mut()
            .for_each(|f| f.increment_time());

        Ok(())
    }

    /// Update **all** temporary values of every entity in the current epoch.
    ///
    /// # Safety
    /// * The caller must guarantee that the current epoch is **loaded** and
    ///   its storage is still valid for the duration of the call.
    /// * The function performs raw pointer arithmetic / `unsafe` reads/writes
    ///   on the internal data structures.  No other thread may be mutably
    ///   borrowing the same data at the same time.
    pub unsafe fn update_all_temporary_values(&mut self) {}

    /// Reset **all** temporary values to the current live values.
    ///
    /// # Safety
    /// * The caller must ensure that the current epoch is loaded and that
    ///   no other mutable references to the same data exist.  
    /// * This method writes directly into the entity structs; any concurrent
    ///   access will lead to undefined behaviour.
    pub unsafe fn reset_temporary_stats(&mut self) -> Result<(), EpochError> {
        let current_epoch = self.try_load_current_as_mut()?;
        current_epoch
            .vec_entities_mut(&stats::EntityType::Town)
            .iter_mut()
            .for_each(|entity| entity.reset_temporary_stats_to(Some(entity.get_stats().clone())));

        Ok(())
    }

    /// Update temporary values for every entity assuming the current epoch
    /// is loaded.
    ///
    /// # Safety
    /// * Same as `update_all_temporary_values`: the current epoch must be
    ///   loaded and no other mutable references may exist.
    pub unsafe fn update_temps(&mut self) {}

    /// Insert a new epoch into the configuration and persist it.
    ///
    /// The function creates the epoch's directory, writes its metadata,
    /// updates the internal maps, and finally writes the updated
    /// configuration to disk.
    ///
    /// # Returns
    /// * `Ok(())` - the epoch was added and the configuration was saved.
    /// * `Err(EpochError::EpochAlreadyExists(..))` if an epoch with the same ID already exists.
    pub fn insert_and_save(
        &mut self,
        new_epoch: EpochInfo,
        save_mode: &SaveMode,
    ) -> Result<(), EpochError> {
        if self.list_existing_epochs.contains_key(&new_epoch.epoch_id) {
            return Err(EpochError::EpochAlreadyExists(new_epoch.epoch_id));
        }

        new_epoch.create_subfolders()?;
        new_epoch.save_with_context("Saving new epoch", save_mode)?;

        // Add the epoch to the list of epochs, not doing so will still have it added
        // at the next iteration since the command always parse the files to determine it's state rater that the list
        // not doing so would likely create errors if insert is used before another command
        let new_id = new_epoch.epoch_id;
        self.list_existing_epochs.insert(new_id, Some(new_epoch));
        self.epoch_id = new_id;
        self.save_with_context("Saving after insert_and_save", &SaveMode::Erase)?;
        Ok(())
    }

    /// Load and display the metadata for a list of epoch IDs.
    ///
    /// The function first ensures that each requested epoch's metadata is
    /// loaded into memory, then displays a formatted log for each one.
    pub fn log_elements(&mut self, list_ids: &[EpochId]) -> Result<(), EpochError> {
        let mut items_to_log = Vec::with_capacity(list_ids.len());
        // Tries to load all ids into memory
        for id in list_ids {
            self.try_load(id)?;
        }
        // Makes a vector with all elements from the list of ids
        for id in list_ids {
            if let Some(info) = self
                .list_existing_epochs
                .get(id)
                .ok_or(EpochError::EpochNotFound(id.to_string()))?
            {
                items_to_log.push(info);
            }
        }

        // TODO: Have this in a message and return a string
        println!(
            "{}",
            "List of epoch, most recent shown first".bright_green()
        );
        // TODO: Make a method for this
        for elt in items_to_log.iter().rev() {
            let star = if elt.epoch_id == self.epoch_id {
                " "
            } else {
                "  "
            };
            println!(
                "{} {:>4} - {}{}{:10} {:50}",
                star.green(),
                elt.epoch_id.to_symbol().blue(),
                "󰬌 ".yellow(),
                (elt.events.len()
                    + elt.characters.len()
                    + elt.towns.len()
                    + elt.calamities.len()
                    + elt.blockers.len())
                .to_string()
                .yellow(),
                elt.tags.join(","),
                elt.summary
            )
        }
        // println!("{}", EpochInfo::as_table(items_to_log)?);
        Ok(())
    }
}

impl ConfigWritable for EpochConfig {
    fn save_path(&self) -> String {
        MAIN_NAME.to_string()
    }

    fn save_folder(&self) -> String {
        ".".to_string()
    }
}