deepslate 0.3.1

//! Type-safe event system for the Deepslate proxy.
//!
//! Inspired by [Velocity's event system](https://docs.papermc.io/velocity/dev/event-system),
//! this module provides a type-safe publish-subscribe event system where:
//!
//! - **Events are plain structs** — no required base trait or common ancestor.
//! - **Result-based outcomes** — events that can be cancelled or modified implement
//!   [`ResultedEvent`] with domain-specific result enums (e.g., `Allow`/`Deny`).
//! - **Priority ordering** — handlers execute in priority order ([`PostOrder`]),
//!   so multiple plugins can cooperate on the same event.
//! - **Immutable observers** — read-only callbacks ([`Phase::Pre`] / [`Phase::Post`])
//!   that receive `&E` instead of `&mut E`, separating "watch" from "influence" at
//!   the type level.
//! - **Compile-time type safety** — the [`EventManager::subscribe`] and
//!   [`EventManager::observe`] APIs are fully generic; internal storage uses
//!   type-erased trait objects keyed by [`TypeId`].
//!
//! # Dispatch Order
//!
//! When an event is fired, the pipeline executes three phases in order:
//!
//! 1. **Pre-observers** — `&E`, registration order. See the event before any
//!    handler runs.
//! 2. **Handlers** — `&mut E`, priority order ([`PostOrder`]). Can modify the
//!    event, set results, etc.
//! 3. **Post-observers** — `&E`, registration order. See the event after all
//!    handlers have finished.
//!
//! # Plugin Model
//!
//! Rather than implementing a monolithic trait with one method per event, plugins
//! implement the [`Plugin`] trait and register individual event handlers and
//! observers during startup:
//!
//! ```rust,no_run
//! use deepslate::event::*;
//! use deepslate::event::events::*;
//!
//! struct MyPlugin;
//!
//! impl Plugin for MyPlugin {
//!     fn register(&self, events: &mut EventManager) {
//!         // Mutable handler — can modify the event
//!         events.subscribe::<LoginEvent>(PostOrder::NORMAL, |event| {
//!             if event.player.profile.name == "griefer" {
//!                 event.set_result(LoginResult::Deny("Not allowed".into()));
//!             }
//!         });
//!
//!         // Pre-observer — read-only, runs before handlers
//!         events.observe::<LoginEvent>(Phase::Pre, |event| {
//!             println!("login attempt: {}", event.player.profile.name);
//!         });
//!
//!         // Post-observer — read-only, runs after handlers
//!         events.observe::<LoginEvent>(Phase::Post, |event| {
//!             println!("login result: {:?}", event.result());
//!         });
//!     }
//! }
//! ```

/// Event types and domain models.
pub mod events;
/// Internal event handler and observer storage.
pub mod handler;
/// Handler execution priority levels and observer phases.
pub mod priority;
/// Event results and cancellation logic.
pub mod result;

use std::any::TypeId;
use std::collections::HashMap;

use deepslate_protocol::types::GameProfile;

pub use events::*;
pub use priority::{Phase, PostOrder};
pub use result::{EventResult, ResultedEvent};

use handler::{
    EventPipeline, HandlerRegistration, ObserverRegistration, TypedHandler, TypedObserver,
    sort_handlers,
};

/// Information about a connected player, passed to event handlers.
#[derive(Debug, Clone)]
pub struct PlayerInfo {
    /// The player's authenticated game profile.
    pub profile: GameProfile,
    /// The player's remote IP address as a string.
    pub remote_addr: String,
    /// The protocol version the player connected with.
    pub protocol_version: i32,
    /// The hostname the player used to connect (from the handshake packet's
    /// `server_address` field).
    ///
    /// This value is normalised: Forge/FML null-byte suffixes are stripped,
    /// trailing dots are removed, and the hostname is lowercased.
    pub virtual_host: String,
}

/// Central event dispatcher.
///
/// Stores type-erased handlers and observers keyed by event [`TypeId`].
/// Handlers are sorted by priority at registration time; observers run in
/// registration order.
///
/// When an event is fired, the pipeline dispatches three phases:
///
/// 1. **Pre-observers** (`&E`, registration order)
/// 2. **Handlers** (`&mut E`, priority order)
/// 3. **Post-observers** (`&E`, registration order)
///
/// The `EventManager` is built during proxy startup (plugins register handlers
/// via [`Plugin::register`]), then wrapped in an `Arc` and shared across async
/// tasks as an immutable reference.
pub struct EventManager {
    pipelines: HashMap<TypeId, EventPipeline>,
}

impl EventManager {
    /// Create a new, empty event manager.
    #[must_use]
    pub fn new() -> Self {
        Self {
            pipelines: HashMap::new(),
        }
    }

    /// Register a handler for a specific event type at the given priority.
    ///
    /// Handlers are called in priority order (highest first). Handlers at the
    /// same priority execute in registration order.
    ///
    /// # Type Safety
    ///
    /// The handler closure receives a `&mut E`, so it can read and modify the
    /// event (including setting results on [`ResultedEvent`] types). The
    /// `EventManager` guarantees that the handler is only called with events of
    /// the correct type.
    pub fn subscribe<E: 'static + Send + Sync>(
        &mut self,
        priority: PostOrder,
        handler: impl Fn(&mut E) + Send + Sync + 'static,
    ) {
        let type_id = TypeId::of::<E>();
        let registration = HandlerRegistration {
            priority,
            handler: Box::new(TypedHandler::new(handler)),
        };

        let pipeline = self.pipelines.entry(type_id).or_default();
        pipeline.handlers.push(registration);
        sort_handlers(&mut pipeline.handlers);
    }

    /// Register an immutable observer for a specific event type.
    ///
    /// Observers receive a shared `&E` reference and cannot modify the event.
    /// They run in registration order within their phase, either before all
    /// handlers ([`Phase::Pre`]) or after all handlers ([`Phase::Post`]).
    ///
    /// Because observers only require `&E`, they are safe to run in parallel
    /// once async event dispatch is added.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use deepslate::event::*;
    /// use deepslate::event::events::*;
    ///
    /// let mut events = EventManager::new();
    ///
    /// // Log every login attempt before handlers run
    /// events.observe::<LoginEvent>(Phase::Pre, |event| {
    ///     println!("login attempt: {}", event.player.profile.name);
    /// });
    ///
    /// // Log the final result after handlers run
    /// events.observe::<LoginEvent>(Phase::Post, |event| {
    ///     println!("login result: {:?}", event.result());
    /// });
    /// ```
    pub fn observe<E: 'static + Send + Sync>(
        &mut self,
        phase: Phase,
        observer: impl Fn(&E) + Send + Sync + 'static,
    ) {
        let type_id = TypeId::of::<E>();
        let registration = ObserverRegistration {
            observer: Box::new(TypedObserver::new(observer)),
        };

        let pipeline = self.pipelines.entry(type_id).or_default();
        match phase {
            Phase::Pre => pipeline.pre_observers.push(registration),
            Phase::Post => pipeline.post_observers.push(registration),
        }
    }

    /// Fire an event through all registered observers and handlers.
    ///
    /// The dispatch pipeline runs three phases in order:
    ///
    /// 1. Pre-observers (`&E`, registration order)
    /// 2. Handlers (`&mut E`, priority order)
    /// 3. Post-observers (`&E`, registration order)
    ///
    /// Returns the (potentially modified) event so callers can inspect the
    /// final result.
    pub fn fire<E: 'static + Send + Sync>(&self, mut event: E) -> E {
        if let Some(pipeline) = self.pipelines.get(&TypeId::of::<E>()) {
            // Phase 1: pre-observers (immutable)
            for observer in &pipeline.pre_observers {
                observer.observer.call(&event);
            }

            // Phase 2: handlers (mutable, priority-ordered)
            for handler in &pipeline.handlers {
                handler.handler.call(&mut event);
            }

            // Phase 3: post-observers (immutable)
            for observer in &pipeline.post_observers {
                observer.observer.call(&event);
            }
        }
        event
    }
}

impl Default for EventManager {
    fn default() -> Self {
        Self::new()
    }
}

/// Trait that plugins implement to hook into the proxy lifecycle.
///
/// Instead of overriding hardcoded event methods, plugins register individual
/// event handlers and observers with the [`EventManager`] during the
/// [`register`](Plugin::register) call. This allows multiple plugins to
/// subscribe to the same events with independent priority ordering, and
/// attach read-only observers for logging or metrics.
///
/// The trait requires `Send + Sync + 'static` because plugin references are
/// shared during the registration phase.
///
/// # Example
///
/// ```rust,no_run
/// use deepslate::event::*;
/// use deepslate::event::events::*;
/// use deepslate::ServerId;
///
/// const LOBBY: ServerId = ServerId::new("lobby", "127.0.0.1:25566");
///
/// struct LobbyPlugin;
///
/// impl Plugin for LobbyPlugin {
///     fn register(&self, events: &mut EventManager) {
///         events.subscribe::<ChooseServerEvent>(PostOrder::NORMAL, |event| {
///             event.set_server(&LOBBY);
///         });
///
///         events.observe::<ChooseServerEvent>(Phase::Post, |event| {
///             println!("server chosen: {:?}", event.result());
///         });
///     }
/// }
/// ```
pub trait Plugin: Send + Sync + 'static {
    /// Called once during proxy startup to register event handlers and
    /// observers.
    ///
    /// Implementations should call [`EventManager::subscribe`] to register
    /// handlers for the events they care about, and [`EventManager::observe`]
    /// for read-only observers.
    fn register(&self, events: &mut EventManager);
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;
    use std::sync::atomic::{AtomicU32, Ordering};

    use super::*;

    /// Minimal event type for testing.
    #[derive(Debug, PartialEq, Eq)]
    struct TestEvent {
        value: i32,
    }

    #[test]
    fn pre_observer_runs_before_handlers() {
        let order = Arc::new(AtomicU32::new(0));
        let mut em = EventManager::new();

        let o = Arc::clone(&order);
        em.observe::<TestEvent>(Phase::Pre, move |_| {
            // Pre-observer should be the first callback.
            assert_eq!(o.fetch_add(1, Ordering::SeqCst), 0);
        });

        let o = Arc::clone(&order);
        em.subscribe::<TestEvent>(PostOrder::NORMAL, move |_| {
            // Handler should run second.
            assert_eq!(o.fetch_add(1, Ordering::SeqCst), 1);
        });

        em.fire(TestEvent { value: 0 });
        assert_eq!(order.load(Ordering::SeqCst), 2);
    }

    #[test]
    fn post_observer_runs_after_handlers() {
        let order = Arc::new(AtomicU32::new(0));
        let mut em = EventManager::new();

        let o = Arc::clone(&order);
        em.subscribe::<TestEvent>(PostOrder::NORMAL, move |_| {
            assert_eq!(o.fetch_add(1, Ordering::SeqCst), 0);
        });

        let o = Arc::clone(&order);
        em.observe::<TestEvent>(Phase::Post, move |_| {
            assert_eq!(o.fetch_add(1, Ordering::SeqCst), 1);
        });

        em.fire(TestEvent { value: 0 });
        assert_eq!(order.load(Ordering::SeqCst), 2);
    }

    #[test]
    fn full_pipeline_dispatches_in_order() {
        let order = Arc::new(AtomicU32::new(0));
        let mut em = EventManager::new();

        // Register in arbitrary order — dispatch order is determined by phase,
        // not registration order across phases.
        let o = Arc::clone(&order);
        em.observe::<TestEvent>(Phase::Post, move |_| {
            assert_eq!(o.fetch_add(1, Ordering::SeqCst), 3);
        });

        let o = Arc::clone(&order);
        em.subscribe::<TestEvent>(PostOrder::NORMAL, move |_| {
            assert_eq!(o.fetch_add(1, Ordering::SeqCst), 2);
        });

        let o = Arc::clone(&order);
        em.observe::<TestEvent>(Phase::Pre, move |_| {
            assert_eq!(o.fetch_add(1, Ordering::SeqCst), 0);
        });

        let o = Arc::clone(&order);
        em.subscribe::<TestEvent>(PostOrder::FIRST, move |_| {
            // FIRST priority handler runs before NORMAL.
            assert_eq!(o.fetch_add(1, Ordering::SeqCst), 1);
        });

        em.fire(TestEvent { value: 0 });
        assert_eq!(order.load(Ordering::SeqCst), 4);
    }

    #[test]
    fn observers_see_handler_mutations() {
        let mut em = EventManager::new();

        em.subscribe::<TestEvent>(PostOrder::NORMAL, |event| {
            event.value = 42;
        });

        let saw_value = Arc::new(AtomicU32::new(0));
        let v = Arc::clone(&saw_value);
        em.observe::<TestEvent>(Phase::Post, move |event| {
            v.store(u32::try_from(event.value).unwrap(), Ordering::SeqCst);
        });

        em.fire(TestEvent { value: 0 });
        assert_eq!(saw_value.load(Ordering::SeqCst), 42);
    }

    #[test]
    fn pre_observers_see_initial_state() {
        let mut em = EventManager::new();

        let saw_value = Arc::new(AtomicU32::new(0));
        let v = Arc::clone(&saw_value);
        em.observe::<TestEvent>(Phase::Pre, move |event| {
            v.store(u32::try_from(event.value).unwrap(), Ordering::SeqCst);
        });

        em.subscribe::<TestEvent>(PostOrder::NORMAL, |event| {
            event.value = 99;
        });

        em.fire(TestEvent { value: 7 });
        assert_eq!(saw_value.load(Ordering::SeqCst), 7);
    }

    #[test]
    fn multiple_observers_run_in_registration_order() {
        let order = Arc::new(AtomicU32::new(0));
        let mut em = EventManager::new();

        let o = Arc::clone(&order);
        em.observe::<TestEvent>(Phase::Pre, move |_| {
            assert_eq!(o.fetch_add(1, Ordering::SeqCst), 0);
        });

        let o = Arc::clone(&order);
        em.observe::<TestEvent>(Phase::Pre, move |_| {
            assert_eq!(o.fetch_add(1, Ordering::SeqCst), 1);
        });

        let o = Arc::clone(&order);
        em.observe::<TestEvent>(Phase::Pre, move |_| {
            assert_eq!(o.fetch_add(1, Ordering::SeqCst), 2);
        });

        em.fire(TestEvent { value: 0 });
        assert_eq!(order.load(Ordering::SeqCst), 3);
    }

    #[test]
    fn fire_with_no_registrations() {
        let em = EventManager::new();
        let event = em.fire(TestEvent { value: 5 });
        assert_eq!(event.value, 5);
    }

    #[test]
    fn fire_with_only_observers() {
        let mut em = EventManager::new();

        let called = Arc::new(AtomicU32::new(0));

        let c = Arc::clone(&called);
        em.observe::<TestEvent>(Phase::Pre, move |_| {
            c.fetch_add(1, Ordering::SeqCst);
        });

        let c = Arc::clone(&called);
        em.observe::<TestEvent>(Phase::Post, move |_| {
            c.fetch_add(1, Ordering::SeqCst);
        });

        let event = em.fire(TestEvent { value: 10 });
        // Event should be unmodified (no handlers).
        assert_eq!(event.value, 10);
        // Both observers should have been called.
        assert_eq!(called.load(Ordering::SeqCst), 2);
    }

    #[test]
    fn handlers_still_work_without_observers() {
        let mut em = EventManager::new();

        em.subscribe::<TestEvent>(PostOrder::NORMAL, |event| {
            event.value += 1;
        });

        let event = em.fire(TestEvent { value: 0 });
        assert_eq!(event.value, 1);
    }
}