hoy-core

Shared domain logic and persistent storage abstractions for the hoy app.

Index

• Lib modules
• store module
  • RoomName
  • RoomRecord
  • StoredMessage
  • ServerStore trait
• memory module
  • InMemoryStore
• dbstore module
  • DbStore
• cli module
  • Hoy
• error module
  • StoreError
  • HoyError

Lib modules

• error: StoreError, HoyError
• store: RoomName, RoomRecord, StoredMessage, ServerStore
• memory: InMemoryStore — in-memory ServerStore implementation (always available)
• dbstore: DbStore — SQLite-backed ServerStore implementation
• cli: Hoy — CLI argument parsing and application entry-point helpers

store module

RoomName

A validated, owned room name. Enforces:

• Allowed characters: lowercase ASCII letters (a–z), ASCII digits (0–9), -, _
• Length: 1–64 characters (inclusive)

let name = RoomName::new("my-room_01")?;  // Ok
let _    = RoomName::new("");             // Err — empty
let _    = RoomName::new("Bad Room!");    // Err — uppercase, space, '!'

RoomName derives Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord.

RoomRecord

A persisted room entry returned by ServerStore::load_rooms:

StoredMessage

A single persisted chat message:

ServerStore trait

The persistence interface for durable server data — room definitions and message history. Live connection state (connected clients, active memberships, writer channels) is not managed here; that belongs to the network layer.

All methods except storage_slug are async, expressed as RPIT (fn method() -> impl Future<Output = …> + Send) for Send-safe use across tokio tasks.

pub trait ServerStore: Send + 'static {
    fn ensure_room(&mut self, name: &RoomName)
        -> impl Future<Output = Result<(), StoreError>> + Send;
    fn load_rooms(&self)
        -> impl Future<Output = Result<Vec<RoomRecord>, StoreError>> + Send;
    fn append_message(&mut self, msg: StoredMessage)
        -> impl Future<Output = Result<(), StoreError>> + Send;
    fn load_recent_messages(&self, room: &RoomName, limit: usize)
        -> impl Future<Output = Result<Vec<StoredMessage>, StoreError>> + Send;
    fn storage_slug(&self) -> String;
}

memory module

InMemoryStore

A HashMap-backed ServerStore for use in tests and lightweight scenarios. All data is held in process memory and is not persisted across restarts.

use hoy_core::memory::InMemoryStore;
use hoy_core::store::{RoomName, ServerStore};

let mut store = InMemoryStore::new();
let general = RoomName::new("general")?;

store.ensure_room(&general).await?;

let rooms = store.load_rooms().await?;
assert_eq!(rooms.len(), 1);

load_rooms returns rooms sorted alphabetically by name. load_recent_messages returns the last limit messages (tail of the chronological history), oldest first.

dbstore module

DbStore

A SQLite-backed ServerStore that persists room definitions and message history across server restarts. Uses sqlx with a connection pool and applies schema migrations automatically on construction.

use hoy_core::dbstore::DbStore;
use hoy_core::store::{RoomName, ServerStore};

// Pass None to use the platform data directory (e.g. ~/.local/share/hoy/hoy.db on Linux)
let store = DbStore::new(None).await?;

// Or supply an explicit path to the database file
let store = DbStore::new(Some("/var/lib/hoy/hoy.db".into())).await?;

let general = RoomName::new("general")?;
let messages = store.load_recent_messages(&general, 50).await?;

Storage location (when path is None):

DbStore derives Debug and Clone (the underlying SqlitePool is reference-counted).

cli module

Provides CLI argument parsing and application bootstrap helpers, so the binary entry point stays thin.

Hoy

The top-level application handle. Constructed by parsing CLI arguments with clap via Hoy::default().

use hoy_core::cli::Hoy;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let hoy = Hoy::default(); // parses std::env::args()

    let addr = hoy.resolve_address();

    if hoy.run_server() {
        let store = hoy.construct_store().await?;
        // run_server(addr, store).await?;
    } else {
        let username = hoy.resolve_username()?;
        // run_test_client(addr, username).await?;
    }

    Ok(())
}

CLI flags:

error module

StoreError

HoyError