vstorage 0.6.0

// Copyright 2023-2025 Hugo Osvaldo Barrera
//
// SPDX-License-Identifier: EUPL-1.2

//! Synchronisation operations.
//!
//! The main type is [`Operation`], which represents a single atomic synchronisation action.

use std::sync::Arc;

use crate::Href;
use crate::base::{ItemVersion, Property};
use crate::sync::analysis::{ItemSource, ResolvedMapping, StatusAction};
use crate::sync::conflict::ConflictInfo;
use crate::sync::ordering::CompletionDroppedError;
use crate::sync::status::StatusVersions;

use super::ordering::{CompletionHandle, DeletionCompletionHandle, DeletionWaitHandle, WaitHandle};
use super::status::{MappingUid, Side};

/// Operation to be executed on a pair.
#[derive(Debug, Clone)]
#[allow(clippy::large_enum_variant)]
pub enum Operation {
    /// Flush stale mappings from status database.
    FlushStaleMappings { stale_uids: Vec<MappingUid> },

    /// Collection-level operation
    Collection(CollectionOp),

    /// Item-level operation
    Item(ItemOp),

    /// Property-level operation
    Property(PropertyOp),
}

impl Operation {
    /// Returns true if this operation represents a conflict requiring resolution.
    #[must_use]
    pub fn is_conflict(&self) -> bool {
        matches!(
            self,
            Operation::Item(ItemOp::Conflict { .. })
                | Operation::Property(PropertyOp::PropertyConflict { .. })
        )
    }
}

/// Collection-level synchronisation operation.
#[derive(Debug, Clone)]
pub enum CollectionOp {
    /// Save new collection mapping to status database.
    SaveToStatus {
        mapping: Arc<ResolvedMapping>,
        completion: CompletionHandle,
    },

    /// Create collection on one side.
    CreateInOne {
        mapping: Arc<ResolvedMapping>,
        side: Side,
        completion: CompletionHandle,
    },

    /// Create collection on both sides.
    CreateInBoth {
        mapping: Arc<ResolvedMapping>,
        completion: CompletionHandle,
    },

    /// Delete collection (after items removed).
    ///
    /// Guaranteed to be queued after all item operations for this collection.
    /// Execution waits for all item/property operations to complete via the deletion barrier.
    Delete {
        mapping: Arc<ResolvedMapping>,
        mapping_uid: MappingUid,
        side: Side,
        /// Wait handle for deletion barrier - ensures all items/properties complete before deletion.
        wait_for_items: DeletionWaitHandle,
    },

    /// Collection requires no action (already in sync).
    NoAction { mapping_uid: MappingUid },

    /// Store sync token for a collection side.
    StoreSyncToken {
        mapping_uid: MappingUidSource,
        side: Side,
        token: String,
        wait_for_items: DeletionWaitHandle,
    },
}

/// Source of mapping UID for item operations.
///
/// The mapping UID may be immediately available (for existing collections)
/// or deferred via a wait handle (for collections being created).
#[derive(Debug, Clone)]
pub enum MappingUidSource {
    /// Mapping UID is immediately available.
    Immediate(MappingUid),
    /// Mapping UID will be provided via wait handle when collection operation completes.
    Deferred(WaitHandle),
}

impl MappingUidSource {
    /// Returns the immediate mapping UID if available, otherwise None.
    #[must_use]
    pub fn immediate(&self) -> Option<MappingUid> {
        match self {
            MappingUidSource::Immediate(uid) => Some(*uid),
            MappingUidSource::Deferred(_) => None,
        }
    }

    /// Returns the wait handle if mapping UID is deferred, otherwise None.
    #[must_use]
    pub fn wait_handle(&self) -> Option<&WaitHandle> {
        match self {
            MappingUidSource::Immediate(_) => None,
            MappingUidSource::Deferred(handle) => Some(handle),
        }
    }

    /// Resolves the mapping UID, waiting if necessary.
    ///
    /// If immediate, returns the UID. If deferred, waits on the handle.
    ///
    /// # Errors
    ///
    /// Returns an error if the completion handle was dropped before signaling.
    pub async fn resolve(self) -> Result<MappingUid, CompletionDroppedError> {
        match self {
            MappingUidSource::Immediate(uid) => Ok(uid),
            MappingUidSource::Deferred(mut handle) => handle.wait().await,
        }
    }
}

/// Specifies how a write operation should interact with storage and status database.
#[derive(Debug, Clone)]
pub enum WriteMode {
    /// Create new item in collection, insert into status database.
    CreateNew { collection: Href },

    /// Create new item in collection, update existing status entry.
    CreateRefresh {
        collection: Href,
        old: StatusVersions,
    },

    /// Update existing item, insert into status database.
    /// Used for first sync, [`OneWaySync`](super::one_way::OneWaySync) or conflict resolution.
    UpdateNew { target: ItemVersion },

    /// Update existing item, update existing status entry.
    UpdateExisting { old: StatusVersions },

    /// Update existing item which does not match the status entry.
    /// Use for conflict resolution or [`OneWaySync`](super::one_way::OneWaySync) sync.
    UpdateForce {
        target: ItemVersion,
        old: StatusVersions,
    },
}

/// Write item to storage A from source in storage B.
#[derive(Debug, Clone)]
pub struct WriteInA {
    pub source_b: ItemSource,
    pub mode: WriteMode,
    pub mapping_uid: MappingUidSource,
    /// Optional handle to signal collection deletion barrier when this operation completes.
    pub on_complete: Option<DeletionCompletionHandle>,
}

impl From<WriteInA> for ItemOp {
    fn from(inner: WriteInA) -> Self {
        ItemOp::WriteInA(inner)
    }
}

/// Write item to storage B from source in storage A.
#[derive(Debug, Clone)]
pub struct WriteInB {
    pub source_a: ItemSource,
    pub mode: WriteMode,
    pub mapping_uid: MappingUidSource,
    /// Optional handle to signal collection deletion barrier when this operation completes.
    pub on_complete: Option<DeletionCompletionHandle>,
}

impl From<WriteInB> for ItemOp {
    fn from(inner: WriteInB) -> Self {
        ItemOp::WriteInB(inner)
    }
}

/// Delete item from storage A.
#[derive(Debug, Clone)]
pub struct DeleteA {
    pub target_a: ItemVersion,
    pub uid: String,
    pub mapping_uid: MappingUidSource,
    /// Optional handle to signal collection deletion barrier when this operation completes.
    pub on_complete: Option<DeletionCompletionHandle>,
}

impl From<DeleteA> for ItemOp {
    fn from(inner: DeleteA) -> Self {
        ItemOp::DeleteA(inner)
    }
}

/// Delete item from storage B.
#[derive(Debug, Clone)]
pub struct DeleteB {
    pub target_b: ItemVersion,
    pub uid: String,
    pub mapping_uid: MappingUidSource,
    /// Optional handle to signal collection deletion barrier when this operation completes.
    pub on_complete: Option<DeletionCompletionHandle>,
}

impl From<DeleteB> for ItemOp {
    fn from(inner: DeleteB) -> Self {
        ItemOp::DeleteB(inner)
    }
}

/// Only update status database (no storage operations).
#[derive(Debug, Clone)]
pub struct StatusOnly {
    pub action: StatusAction,
    pub mapping_uid: MappingUidSource,
    /// Optional handle to signal collection deletion barrier when this operation completes.
    pub on_complete: Option<DeletionCompletionHandle>,
}

impl From<StatusOnly> for ItemOp {
    fn from(inner: StatusOnly) -> Self {
        ItemOp::StatusOnly(inner)
    }
}

/// Item-level synchronisation operation.
#[derive(Debug, Clone)]
#[allow(clippy::large_enum_variant)]
pub enum ItemOp {
    /// Write item to storage A from source in B.
    ///
    /// If collection creation is pending, `wait_for` will receive the mapping UID when it completes.
    WriteInA(WriteInA),

    /// Write item to storage B from source in A.
    ///
    /// If collection creation is pending, `wait_for` will receive the mapping UID when it completes.
    WriteInB(WriteInB),

    /// Delete item from storage A.
    DeleteA(DeleteA),

    /// Delete item from storage B.
    DeleteB(DeleteB),

    /// Only update status database (no storage operations).
    StatusOnly(StatusOnly),

    /// Conflict requiring resolution.
    Conflict {
        info: ConflictInfo,
        mapping: Arc<ResolvedMapping>,
        mapping_uid: MappingUidSource,
        /// Signal collection deletion barrier when this operation completes.
        /// Only meaningful if some form of auto-resolution is in use.
        deletion_completion: Option<DeletionCompletionHandle>,
    },
}

impl ItemOp {
    /// Returns the wait handle that must be awaited before executing this operation, if any.
    #[must_use]
    pub fn wait_handle(&self) -> Option<&WaitHandle> {
        match self {
            ItemOp::WriteInA(inner) => inner.mapping_uid.wait_handle(),
            ItemOp::WriteInB(inner) => inner.mapping_uid.wait_handle(),
            ItemOp::StatusOnly(inner) => inner.mapping_uid.wait_handle(),
            _ => None,
        }
    }

    /// Returns the item UID for this operation, if applicable.
    #[must_use]
    pub fn uid(&self) -> Option<&str> {
        match self {
            ItemOp::WriteInA(inner) => Some(&inner.source_b.state.uid),
            ItemOp::WriteInB(inner) => Some(&inner.source_a.state.uid),
            ItemOp::DeleteA(inner) => Some(&inner.uid),
            ItemOp::DeleteB(inner) => Some(&inner.uid),
            ItemOp::StatusOnly(inner) => match &inner.action {
                StatusAction::Insert { uid, .. } | StatusAction::Clear { uid } => Some(uid),
                StatusAction::Update { .. } => None,
            },
            ItemOp::Conflict { info, .. } => Some(&info.a.state.uid),
        }
    }

    /// Returns the mapping UID source for this operation.
    #[must_use]
    pub fn mapping_uid(&self) -> MappingUidSource {
        match self {
            ItemOp::WriteInA(inner) => inner.mapping_uid.clone(),
            ItemOp::WriteInB(inner) => inner.mapping_uid.clone(),
            ItemOp::DeleteA(inner) => inner.mapping_uid.clone(),
            ItemOp::DeleteB(inner) => inner.mapping_uid.clone(),
            ItemOp::StatusOnly(inner) => inner.mapping_uid.clone(),
            ItemOp::Conflict { mapping_uid, .. } => mapping_uid.clone(),
        }
    }
}

/// Property-level synchronisation operation.
#[derive(Debug, Clone)]
pub enum PropertyOp {
    /// Write property to one side.
    Write {
        property: Property,
        value: String,
        side: Side,
        mapping: Arc<ResolvedMapping>,
        mapping_uid: MappingUidSource,
        /// Optional handle to signal collection deletion barrier when this operation completes.
        deletion_completion: Option<DeletionCompletionHandle>,
    },

    /// Delete property from one side.
    Delete {
        property: Property,
        side: Side,
        mapping: Arc<ResolvedMapping>,
        mapping_uid: MappingUidSource,
        /// Optional handle to signal collection deletion barrier when this operation completes.
        deletion_completion: Option<DeletionCompletionHandle>,
    },

    /// Clear property from status database.
    ClearStatus {
        property: Property,
        mapping: Arc<ResolvedMapping>,
        mapping_uid: MappingUidSource,
        /// Optional handle to signal collection deletion barrier when this operation completes.
        deletion_completion: Option<DeletionCompletionHandle>,
    },

    /// Update property in status database.
    UpdateStatus {
        property: Property,
        value: String,
        mapping: Arc<ResolvedMapping>,
        mapping_uid: MappingUidSource,
        /// Optional handle to signal collection deletion barrier when this operation completes.
        deletion_completion: Option<DeletionCompletionHandle>,
    },

    /// Property has conflicting values.
    PropertyConflict {
        property: Property,
        value_a: String,
        value_b: String,
        mapping: Arc<ResolvedMapping>,
        mapping_uid: MappingUidSource,
        /// Optional handle to signal collection deletion barrier when this operation completes.
        deletion_completion: Option<DeletionCompletionHandle>,
    },
}

impl std::fmt::Display for CollectionOp {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            CollectionOp::SaveToStatus { mapping, .. } => {
                write!(f, "save collection '{}' to status", mapping.alias())
            }
            CollectionOp::CreateInOne { mapping, side, .. } => {
                let alias = mapping.alias();
                write!(f, "create collection '{alias}' in storage {side}",)
            }
            CollectionOp::CreateInBoth { mapping, .. } => {
                let alias = mapping.alias();
                write!(f, "create collection '{alias}' in both storages",)
            }
            CollectionOp::Delete { mapping, side, .. } => {
                let alias = mapping.alias();
                write!(f, "delete collection '{alias}' from storage {side}",)
            }
            CollectionOp::NoAction { mapping_uid } => {
                write!(f, "no action for collection (uid: {mapping_uid:?})")
            }
            CollectionOp::StoreSyncToken {
                mapping_uid, side, ..
            } => {
                write!(
                    f,
                    "store sync token for collection (uid: {mapping_uid:?}) side {side}"
                )
            }
        }
    }
}

impl std::fmt::Display for ItemOp {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ItemOp::WriteInA(inner) => {
                let uid = &inner.source_b.state.uid;
                match &inner.mode {
                    WriteMode::CreateNew { .. } | WriteMode::CreateRefresh { .. } => {
                        write!(f, "create in storage A (uid: {uid})")
                    }
                    WriteMode::UpdateNew { .. }
                    | WriteMode::UpdateExisting { .. }
                    | WriteMode::UpdateForce { .. } => {
                        write!(f, "update in storage A (uid: {uid})")
                    }
                }
            }
            ItemOp::WriteInB(inner) => {
                let uid = &inner.source_a.state.uid;
                match &inner.mode {
                    WriteMode::CreateNew { .. } | WriteMode::CreateRefresh { .. } => {
                        write!(f, "create in storage B (uid: {uid})")
                    }
                    WriteMode::UpdateNew { .. }
                    | WriteMode::UpdateExisting { .. }
                    | WriteMode::UpdateForce { .. } => {
                        write!(f, "update in storage B (uid: {uid})")
                    }
                }
            }
            ItemOp::DeleteA(inner) => {
                write!(f, "delete from storage A (uid: {})", inner.uid)
            }
            ItemOp::DeleteB(inner) => {
                write!(f, "delete from storage B (uid: {})", inner.uid)
            }
            ItemOp::StatusOnly(inner) => {
                write!(f, "status only: {}", inner.action)
            }
            ItemOp::Conflict { info, .. } => {
                write!(f, "conflict (uid: {})", info.a.state.uid)
            }
        }
    }
}

impl std::fmt::Display for PropertyOp {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            PropertyOp::Write {
                property,
                value,
                side,
                mapping,
                ..
            } => {
                let alias = mapping.alias();
                write!(
                    f,
                    "write property {property:?} to storage {side} on collection '{alias}': {value}",
                )
            }
            PropertyOp::Delete {
                property,
                side,
                mapping,
                ..
            } => {
                let alias = mapping.alias();
                write!(
                    f,
                    "delete property {property:?} from storage {side} on collection '{alias}'",
                )
            }
            PropertyOp::ClearStatus {
                property, mapping, ..
            } => {
                let alias = mapping.alias();
                write!(
                    f,
                    "clear property {property:?} from status for collection '{alias}'",
                )
            }
            PropertyOp::UpdateStatus {
                property, mapping, ..
            } => {
                let alias = mapping.alias();
                write!(
                    f,
                    "update property {property:?} in status for collection '{alias}'",
                )
            }
            PropertyOp::PropertyConflict {
                property, mapping, ..
            } => {
                let alias = mapping.alias();
                write!(f, "property {property:?} conflict on collection '{alias}'")
            }
        }
    }
}