quicburn-shared 0.1.0

// crates/quicburn-shared/src/routes.rs

use std::collections::HashMap;

// ============================================================
// Route IDs
// ============================================================

/// Compute a route's wire id from its name.
///
/// Routes are identified by name (a string) everywhere in application code,
/// but the wire protocol needs a single byte per frame, so every route name
/// is hashed down to a `u32` here. This is the ONE place that hashing logic
/// lives — hand-written route registrations, the `#[route(...)]` macro, and
/// this registry all call this same function, so nothing can ever disagree
/// about what a name hashes to.
///
/// This hash is deliberately simple and NOT collision-resistant (XOR of the
/// first 8 bytes of the name). Two different names can hash to the same
/// byte. Collisions are caught at startup — by `RouteTable::register` in
/// quicburn-server, and by `RouteRegistry::register` below — which panic
/// rather than silently letting one route shadow another.
pub const fn route_id(name: &str) -> u32 {
    let bytes = name.as_bytes();
    let mut hash: u32 = 0x811c9dc5; // FNV-1a offset basis
    let mut i = 0;
    while i < bytes.len() && i < 32 {
        hash ^= bytes[i] as u32;
        hash = hash.wrapping_mul(0x01000193); // FNV-1a prime
        i += 1;
    }
    hash
}

// ============================================================
// Route Categories
// ============================================================

/// A route's category, used for grouping in introspection/docs (e.g. a
/// `/routes` debug endpoint, or CLI tooling listing what a server supports).
/// Core categories are named variants for nice `Display`; a third-party
/// crate that doesn't fit an existing category uses `Other`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RouteCategory {
    Basic,
    PubSub,
    Kv,
    File,
    Time,
    Health,
    Query,
    Crypto,
    Auth,
    Terminal,
    /// A category defined by a third-party crate — we can't add a variant
    /// here for every crate that might ever extend this server.
    Other(&'static str),
}

impl RouteCategory {
    pub fn name(self) -> &'static str {
        match self {
            Self::Basic => "Basic",
            Self::PubSub => "PubSub",
            Self::Kv => "KV Store",
            Self::File => "File Operations",
            Self::Time => "Time",
            Self::Health => "Health",
            Self::Query => "Query",
            Self::Crypto => "Crypto",
            Self::Auth => "Auth",
            Self::Terminal => "Terminal",
            Self::Other(name) => name,
        }
    }
}

// ============================================================
// Priority
// ============================================================

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Default)]
pub enum Priority {
    Background,
    Low,
    #[default]
    Normal,
    High,
    Critical,
}

impl Priority {
    pub fn as_i32(self) -> i32 {
        match self {
            Self::Background => -10,
            Self::Low => -5,
            Self::Normal => 0,
            Self::High => 5,
            Self::Critical => 10,
        }
    }
}

// ============================================================
// Route Registry — metadata for introspection, NOT dispatch
// ============================================================
//
// This registry is descriptive only (for a `/routes` debug endpoint, CLI
// docs, etc). It has no connection to actual request handling — that's
// `quicburn_server::route_map::RouteTable`, which holds real handlers. They
// stay separate so this crate doesn't need to know about `AppState`,
// `Frame`, or anything server-specific.
//
// There's deliberately no global/static instance anymore. A `OnceLock`
// singleton can only be populated once, in whatever order crates happen to
// touch it first — which breaks the moment two crates both try to register
// routes into it. Instead, whoever assembles the server builds one
// explicitly, the same way `build_routes()` assembles the `RouteTable`.

#[derive(Debug, Clone)]
pub struct RouteInfo {
    pub id: u32,
    pub name: &'static str,
    pub category: RouteCategory,
    pub priority: Priority,
    pub requires_auth: bool,
    pub description: Option<&'static str>,
}

#[derive(Debug, Default, Clone)]
pub struct RouteRegistry {
    routes: HashMap<u32, RouteInfo>,
}

impl RouteRegistry {
    pub fn new() -> Self {
        Self::default()
    }

    /// Register a route's metadata. Panics on id collision — same
    /// fail-fast-at-startup philosophy as `RouteTable::register` in
    /// quicburn-server: silently shadowing one route's docs with another's
    /// is worse than a loud panic at boot.
    pub fn register(
        &mut self,
        name: &'static str,
        category: RouteCategory,
        priority: Priority,
        requires_auth: bool,
        description: Option<&'static str>,
    ) {
        let id: u32 = route_id(name);
        if let Some(existing) = self.routes.get(&id) {
            panic!(
                "route id collision in registry: \"{}\" and \"{}\" both hash to byte {} \
                 — rename one of them",
                existing.name, name, id
            );
        }
        self.routes.insert(
            id,
            RouteInfo { id, name, category, priority, requires_auth, description },
        );
    }

    pub fn get(&self, id: u32) -> Option<&RouteInfo> {
        self.routes.get(&id)
    }

    pub fn get_by_name(&self, name: &str) -> Option<&RouteInfo> {
        self.routes.get(&route_id(name))
    }

    pub fn iter(&self) -> impl Iterator<Item = &RouteInfo> {
        self.routes.values()
    }

    pub fn by_category(&self, category: RouteCategory) -> Vec<&RouteInfo> {
        self.routes
            .values()
            .filter(|info| info.category == category)
            .collect()
    }

    pub fn len(&self) -> usize {
        self.routes.len()
    }

    pub fn is_empty(&self) -> bool {
        self.routes.is_empty()
    }
}

// ============================================================
// Core route metadata (optional convenience)
// ============================================================

/// Metadata for the routes this crate ships out of the box. Opt-in — call
/// this yourself if you want built-ins to show up in your registry, same as
/// you call each `register_X_routes` yourself in `build_routes()`.
pub fn register_core_routes(registry: &mut RouteRegistry) {
    registry.register(
        "echo",
        RouteCategory::Basic,
        Priority::Normal,
        false,
        Some("Echo back the request"),
    );
    registry.register(
        "uppercase",
        RouteCategory::Basic,
        Priority::Normal,
        false,
        Some("Convert text to uppercase"),
    );
    registry.register(
        "reverse",
        RouteCategory::Basic,
        Priority::Normal,
        false,
        Some("Reverse the input string"),
    );

    registry.register(
        "publish",
        RouteCategory::PubSub,
        Priority::Normal,
        true,
        Some("Publish a message to a topic"),
    );
    registry.register(
        "subscribe",
        RouteCategory::PubSub,
        Priority::Normal,
        true,
        Some("Subscribe to a topic"),
    );

    registry.register(
        "kv_set",
        RouteCategory::Kv,
        Priority::Normal,
        true,
        Some("Set a key-value pair"),
    );
    registry.register(
        "kv_get",
        RouteCategory::Kv,
        Priority::Normal,
        true,
        Some("Get a value by key"),
    );
    registry.register(
        "kv_delete",
        RouteCategory::Kv,
        Priority::Normal,
        true,
        Some("Delete a key-value pair"),
    );

    registry.register(
        "file_upload",
        RouteCategory::File,
        Priority::Low,
        false,
        Some("Upload a file"),
    );
    registry.register(
        "file_download",
        RouteCategory::File,
        Priority::Low,
        false,
        Some("Download a file"),
    );
    registry.register(
        "file_list",
        RouteCategory::File,
        Priority::Low,
        false,
        Some("List files in directory"),
    );
    registry.register(
        "file_delete",
        RouteCategory::File,
        Priority::Low,
        false,
        Some("Delete a file"),
    );
    registry.register(
        "file_info",
        RouteCategory::File,
        Priority::Low,
        false,
        Some("Get file metadata"),
    );

    registry.register(
        "time",
        RouteCategory::Time,
        Priority::Normal,
        false,
        Some("Get current time"),
    );
    registry.register(
        "timestamp",
        RouteCategory::Time,
        Priority::Normal,
        false,
        Some("Get current timestamp"),
    );

    registry.register(
        "health",
        RouteCategory::Health,
        Priority::High,
        false,
        Some("Health check"),
    );
    registry.register(
        "status",
        RouteCategory::Health,
        Priority::High,
        false,
        Some("Detailed status"),
    );

    registry.register(
        "query_json",
        RouteCategory::Query,
        Priority::Normal,
        true,
        Some("Execute a JSON query"),
    );

    registry.register(
        "query_filtered",
        RouteCategory::Query,
        Priority::Normal,
        true,
        Some("Execute a filtered query"),
    );

    registry.register(
        "query",
        RouteCategory::Query,
        Priority::Normal,
        true,
        Some("Execute a query"),
    );

    registry.register(
        "hash",
        RouteCategory::Crypto,
        Priority::Normal,
        true,
        Some("Hash a value"),
    );
    registry.register(
        "hmac",
        RouteCategory::Crypto,
        Priority::Normal,
        true,
        Some("HMAC a value"),
    );

    registry.register(
        "auth",
        RouteCategory::Auth,
        Priority::Normal,
        false,
        Some("Authenticate a session"),
    );
    registry.register(
        "whoami",
        RouteCategory::Auth,
        Priority::Normal,
        true,
        Some("Get current user info"),
    );
    registry.register(
        "logout",
        RouteCategory::Auth,
        Priority::Normal,
        true,
        Some("Log out and invalidate the current session"),
    );
    registry.register(
        "refresh",
        RouteCategory::Auth,
        Priority::Normal,
        true,
        Some("Refresh the current session's expiry"),
    );

    registry.register(
        "admin_stats",
        RouteCategory::Auth,
        Priority::Normal,
        true,
        Some("Get admin statistics"),
    );

    registry.register(
        "term_attach",
        RouteCategory::Terminal,
        Priority::Normal,
        true,
        Some("Attach to a terminal session"),
    );
    registry.register(
        "term_resize",
        RouteCategory::Terminal,
        Priority::Normal,
        true,
        Some("Resize terminal window"),
    );
}