Name type parameters consistently

.vscode/settings.json

@@ -1,8 +1,8 @@
 {
-    "files.insertFinalNewline": true,
+  "files.insertFinalNewline": true,
-    "rust-analyzer.cargo.features": "all",
+  "rust-analyzer.cargo.features": "all",
-    "rust-analyzer.imports.granularity.enforce": true,
+  "rust-analyzer.imports.granularity.enforce": true,
-    "rust-analyzer.imports.granularity.group": "module",
+  "rust-analyzer.imports.granularity.group": "crate",
-    "rust-analyzer.imports.group.enable": true,
+  "rust-analyzer.imports.group.enable": true,
-    "evenBetterToml.formatter.columnWidth": 100,
+  "evenBetterToml.formatter.columnWidth": 100
 }

Cargo.toml

@@ -1,48 +1,33 @@
-[package]
+[workspace]
-name = "euphoxide"
+resolver = "2"
+members = ["euphoxide", "euphoxide-bot", "euphoxide-client"]
+
+[workspace.package]
 version = "0.5.1"
 edition = "2021"
 
-[features]
+[workspace.dependencies]
-bot = ["dep:async-trait", "dep:clap", "dep:cookie"]
+async-trait = "0.1.83"
-
-[dependencies]
-async-trait = { version = "0.1.83", optional = true }
 caseless = "0.2.1"
-cookie = { version = "0.18.1", optional = true }
+clap = { version = "4.5.23", default-features = false, features = ["std"] }
-futures-util = { version = "0.3.31", default-features = false, features = ["sink"] }
+cookie = "0.18.1"
-jiff = { version = "0.1.15", features = ["serde"] }
+futures-util = "0.3.31"
+jiff = { version = "0.1.15", default-features = false, features = ["std"] }
 log = "0.4.22"
 serde = { version = "1.0.215", features = ["derive"] }
 serde_json = "1.0.133"
-tokio = { version = "1.42.0", features = ["time", "sync", "macros", "rt"] }
+tokio = { version = "1.42.0", features = ["macros", "sync", "time"] }
-tokio-stream = "0.1.16"
+tokio-tungstenite = "0.24.0"
-tokio-tungstenite = { version = "0.24.0", features = ["rustls-tls-native-roots"] }
 unicode-normalization = "0.1.24"
-
+# For examples
-[dependencies.clap]
+anyhow = "1.0.94"
-version = "4.5.22"
-optional = true
-default-features = false
-features = ["std", "derive", "deprecated"]
-
-[dev-dependencies] # For example bot
 rustls = "0.23.19"
-tokio = { version = "1.42.0", features = ["rt-multi-thread"] }
+# In this workspace
+euphoxide = { path = "./euphoxide" }
+euphoxide-bot = { path = "./euphoxide-bot" }
+euphoxide-client = { path = "./euphoxide-client" }
 
-[[example]]
+[workspace.lints]
-name = "testbot_instance"
-required-features = ["bot"]
-
-[[example]]
-name = "testbot_instances"
-required-features = ["bot"]
-
-[[example]]
-name = "testbot_commands"
-required-features = ["bot"]
-
-[lints]
 rust.unsafe_code = { level = "forbid", priority = 1 }
 # Lint groups
 rust.deprecated_safe = "warn"

euphoxide-bot/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "euphoxide-bot"
+version = { workspace = true }
+edition = { workspace = true }
+
+[features]
+clap = ["dep:clap"]
+
+[dependencies]
+async-trait = { workspace = true }
+clap = { workspace = true, optional = true, features = ["derive"] }
+cookie = { workspace = true }
+euphoxide = { path = "../euphoxide" }
+jiff = { workspace = true }
+log = { workspace = true }
+tokio = { workspace = true, features = ["rt"] }
+tokio-tungstenite = { workspace = true }
+
+[dev-dependencies]
+anyhow = { workspace = true }
+rustls = { workspace = true }
+tokio = { workspace = true, features = ["full"] }
+tokio-tungstenite = { workspace = true, features = ["rustls-tls-native-roots"] }
+
+[lints]
+workspace = true

euphoxide-bot/examples/examplebot.rs

@@ -0,0 +1,87 @@
+use std::time::Duration;
+
+use async_trait::async_trait;
+use euphoxide::api::Message;
+use euphoxide_bot::{
+    bot::Bot,
+    command::{
+        botrulez::{FullHelp, Ping, ShortHelp},
+        Command, CommandExt, Commands, Context, Info, Propagate,
+    },
+};
+use tokio::sync::mpsc;
+
+struct Pyramid;
+
+#[async_trait]
+impl Command for Pyramid {
+    fn info(&self, _ctx: &Context) -> Info {
+        Info::new().with_description("build a pyramid")
+    }
+
+    async fn execute(
+        &self,
+        _arg: &str,
+        msg: &Message,
+        ctx: &Context,
+        _bot: &Bot,
+    ) -> euphoxide::Result<Propagate> {
+        let mut parent = msg.id;
+
+        for _ in 0..3 {
+            let first = ctx.reply(parent, "brick").await?;
+            ctx.reply_only(parent, "brick").await?;
+            parent = first.await?.0.id;
+            tokio::time::sleep(Duration::from_secs(1)).await;
+        }
+
+        ctx.reply_only(parent, "brick").await?;
+        Ok(Propagate::No)
+    }
+}
+
+async fn run() -> anyhow::Result<()> {
+    let (event_tx, mut event_rx) = mpsc::channel(10);
+
+    let commands = Commands::new()
+        .then(Ping::default().general("ping").hidden())
+        .then(Ping::default().specific("ping").hidden())
+        .then(
+            ShortHelp::new("/me demonstrates how to use euphoxide")
+                .general("help")
+                .hidden(),
+        )
+        .then(
+            FullHelp::new()
+                .with_after("Created using euphoxide.")
+                .specific("help")
+                .hidden(),
+        )
+        .then(Pyramid.general("pyramid"));
+
+    let bot: Bot = Bot::new_simple(commands, event_tx);
+
+    bot.instances
+        .add_instance(
+            bot.server_config
+                .clone()
+                .instance("test")
+                .with_username("examplebot"),
+        )
+        .await;
+
+    while let Some(event) = event_rx.recv().await {
+        bot.handle_event(event);
+    }
+
+    Ok(())
+}
+
+#[tokio::main]
+async fn main() {
+    loop {
+        if let Err(err) = run().await {
+            println!("Error while running: {err}");
+        }
+    }
+}

euphoxide-bot/src/bot.rs

@@ -0,0 +1,76 @@
+use std::{fmt::Debug, sync::Arc};
+
+use jiff::Timestamp;
+use log::error;
+use tokio::sync::mpsc;
+
+use crate::{
+    command::Commands,
+    instance::ServerConfig,
+    instances::{Event, Instances, InstancesConfig},
+};
+
+#[non_exhaustive]
+pub struct Bot<S = (), E = euphoxide::Error> {
+    pub server_config: ServerConfig,
+    pub commands: Arc<Commands<S, E>>,
+    pub state: Arc<S>,
+    pub instances: Instances,
+    pub start_time: Timestamp,
+}
+
+impl Bot {
+    pub fn new_simple(commands: Commands, event_tx: mpsc::Sender<Event>) -> Self {
+        Self::new(
+            ServerConfig::default(),
+            InstancesConfig::default(),
+            commands,
+            (),
+            event_tx,
+        )
+    }
+}
+
+impl<S, E> Bot<S, E> {
+    pub fn new(
+        server_config: ServerConfig,
+        instances_config: InstancesConfig,
+        commands: Commands<S, E>,
+        state: S,
+        event_tx: mpsc::Sender<Event>,
+    ) -> Self {
+        Self {
+            server_config,
+            commands: Arc::new(commands),
+            state: Arc::new(state),
+            instances: Instances::new(instances_config, event_tx),
+            start_time: Timestamp::now(),
+        }
+    }
+}
+impl<S, E> Bot<S, E>
+where
+    S: Send + Sync + 'static,
+    E: Debug + 'static,
+{
+    pub fn handle_event(&self, event: Event) {
+        let bot = self.clone();
+        tokio::task::spawn(async move {
+            if let Err(err) = bot.commands.on_event(event, &bot).await {
+                error!("while handling event: {err:#?}");
+            }
+        });
+    }
+}
+
+impl<S, E> Clone for Bot<S, E> {
+    fn clone(&self) -> Self {
+        Self {
+            server_config: self.server_config.clone(),
+            commands: self.commands.clone(),
+            state: self.state.clone(),
+            instances: self.instances.clone(),
+            start_time: self.start_time,
+        }
+    }
+}

euphoxide-bot/src/command.rs

@@ -0,0 +1,217 @@
+pub mod bang;
+pub mod basic;
+pub mod botrulez;
+#[cfg(feature = "clap")]
+pub mod clap;
+
+use std::future::Future;
+
+use async_trait::async_trait;
+use euphoxide::{
+    api::{self, Data, Message, MessageId, SendEvent, SendReply},
+    client::{
+        conn::ClientConnHandle,
+        state::{Joined, State},
+    },
+};
+
+use crate::{bot::Bot, instance::Instance, instances::Event};
+
+#[non_exhaustive]
+pub struct Context {
+    pub instance: Instance,
+    pub conn: ClientConnHandle,
+    pub joined: Joined,
+}
+
+impl Context {
+    pub async fn send(
+        &self,
+        content: impl ToString,
+    ) -> euphoxide::Result<impl Future<Output = euphoxide::Result<SendReply>>> {
+        self.conn
+            .send(api::Send {
+                content: content.to_string(),
+                parent: None,
+            })
+            .await
+    }
+
+    pub async fn send_only(&self, content: impl ToString) -> euphoxide::Result<()> {
+        let _ignore = self.send(content).await?;
+        Ok(())
+    }
+
+    pub async fn reply(
+        &self,
+        parent: MessageId,
+        content: impl ToString,
+    ) -> euphoxide::Result<impl Future<Output = euphoxide::Result<SendReply>>> {
+        self.conn
+            .send(api::Send {
+                content: content.to_string(),
+                parent: Some(parent),
+            })
+            .await
+    }
+
+    pub async fn reply_only(
+        &self,
+        parent: MessageId,
+        content: impl ToString,
+    ) -> euphoxide::Result<()> {
+        let _ignore = self.reply(parent, content).await?;
+        Ok(())
+    }
+}
+
+#[derive(Default)]
+pub struct Info {
+    pub trigger: Option<String>,
+    pub description: Option<String>,
+}
+
+impl Info {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn with_trigger(mut self, trigger: impl ToString) -> Self {
+        self.trigger = Some(trigger.to_string());
+        self
+    }
+
+    pub fn with_description(mut self, description: impl ToString) -> Self {
+        self.description = Some(description.to_string());
+        self
+    }
+
+    pub fn prepend_trigger(&mut self, trigger: impl ToString) {
+        let cur_trigger = self.trigger.get_or_insert_default();
+        if !cur_trigger.is_empty() {
+            cur_trigger.insert(0, ' ');
+        }
+        cur_trigger.insert_str(0, &trigger.to_string());
+    }
+
+    pub fn with_prepended_trigger(mut self, trigger: impl ToString) -> Self {
+        self.prepend_trigger(trigger);
+        self
+    }
+}
+
+/// Whether a message should propagate to subsequent commands.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Propagate {
+    No,
+    Yes,
+}
+
+#[allow(unused_variables)]
+#[async_trait]
+pub trait Command<S = (), E = euphoxide::Error> {
+    fn info(&self, ctx: &Context) -> Info {
+        Info::default()
+    }
+
+    async fn execute(
+        &self,
+        arg: &str,
+        msg: &Message,
+        ctx: &Context,
+        bot: &Bot<S, E>,
+    ) -> Result<Propagate, E>;
+}
+
+pub trait CommandExt: Sized {
+    fn described(self) -> basic::Described<Self> {
+        basic::Described::new(self)
+    }
+
+    fn hidden(self) -> basic::Described<Self> {
+        basic::Described::hidden(self)
+    }
+
+    fn prefixed(self, prefix: impl ToString) -> basic::Prefixed<Self> {
+        basic::Prefixed::new(prefix, self)
+    }
+
+    fn general(self, name: impl ToString) -> bang::General<Self> {
+        bang::General::new(name, self)
+    }
+
+    fn global(self, name: impl ToString) -> bang::Global<Self> {
+        bang::Global::new(name, self)
+    }
+
+    fn specific(self, name: impl ToString) -> bang::Specific<Self> {
+        bang::Specific::new(name, self)
+    }
+}
+
+impl<C> CommandExt for C {}
+
+pub struct Commands<S = (), E = euphoxide::Error> {
+    commands: Vec<Box<dyn Command<S, E> + Sync + Send>>,
+}
+
+impl<S, E> Commands<S, E> {
+    pub fn new() -> Self {
+        Self { commands: vec![] }
+    }
+
+    pub fn add(&mut self, command: impl Command<S, E> + Sync + Send + 'static) {
+        self.commands.push(Box::new(command));
+    }
+
+    pub fn then(mut self, command: impl Command<S, E> + Sync + Send + 'static) -> Self {
+        self.add(command);
+        self
+    }
+
+    pub fn infos(&self, ctx: &Context) -> Vec<Info> {
+        self.commands.iter().map(|c| c.info(ctx)).collect()
+    }
+
+    pub(crate) async fn on_event(&self, event: Event, bot: &Bot<S, E>) -> Result<Propagate, E> {
+        let Event::Packet {
+            instance,
+            conn,
+            state,
+            packet,
+        } = event
+        else {
+            return Ok(Propagate::Yes);
+        };
+
+        let Ok(Data::SendEvent(SendEvent(msg))) = &packet.content else {
+            return Ok(Propagate::Yes);
+        };
+
+        let State::Joined(joined) = state else {
+            return Ok(Propagate::Yes);
+        };
+
+        let ctx = Context {
+            instance,
+            conn,
+            joined,
+        };
+
+        for command in &self.commands {
+            let propagate = command.execute(&msg.content, msg, &ctx, bot).await?;
+            if propagate == Propagate::No {
+                return Ok(Propagate::No);
+            }
+        }
+
+        Ok(Propagate::Yes)
+    }
+}
+
+// Has fewer restrictions on generic types than #[derive(Default)].
+impl<S, E> Default for Commands<S, E> {
+    fn default() -> Self {
+        Self::new()
+    }
+}

euphoxide-bot/src/command/bang.rs

@@ -1,9 +1,11 @@
+//! Euphoria-style `!foo` and `!foo @bar` command wrappers.
+
 use async_trait::async_trait;
+use euphoxide::{api::Message, nick};
 
-use crate::api::Message;
+use crate::bot::Bot;
-use crate::nick;
 
-use super::{Command, Context};
+use super::{Command, Context, Info, Propagate};
 
 // TODO Don't ignore leading whitespace?
 // I'm not entirely happy with how commands handle whitespace, and on euphoria,
@@ -38,21 +40,22 @@ impl<C> Global<C> {
         }
     }
 
-    pub fn prefix<S: ToString>(mut self, prefix: S) -> Self {
+    pub fn with_prefix<S: ToString>(mut self, prefix: S) -> Self {
         self.prefix = prefix.to_string();
         self
     }
 }
 
 #[async_trait]
-impl<B, E, C> Command<B, E> for Global<C>
+impl<S, E, C> Command<S, E> for Global<C>
 where
-    B: Send,
+    S: Send + Sync,
-    C: Command<B, E> + Send + Sync,
+    C: Command<S, E> + Sync,
 {
-    fn description(&self, ctx: &Context) -> Option<String> {
+    fn info(&self, ctx: &Context) -> Info {
-        let inner = self.inner.description(ctx)?;
+        self.inner
-        Some(format!("{}{} - {inner}", self.prefix, self.name))
+            .info(ctx)
+            .with_prepended_trigger(format!("{}{}", self.prefix, self.name))
     }
 
     async fn execute(
@@ -60,16 +63,14 @@ where
         arg: &str,
         msg: &Message,
         ctx: &Context,
-        bot: &mut B,
+        bot: &Bot<S, E>,
-    ) -> Result<bool, E> {
+    ) -> Result<Propagate, E> {
-        // TODO Replace with let-else
+        let Some((name, rest)) = parse_prefix_initiated(arg, &self.prefix) else {
-        let (name, rest) = match parse_prefix_initiated(arg, &self.prefix) {
+            return Ok(Propagate::Yes);
-            Some(parsed) => parsed,
-            None => return Ok(false),
         };
 
         if name != self.name {
-            return Ok(false);
+            return Ok(Propagate::Yes);
         }
 
         self.inner.execute(rest, msg, ctx, bot).await
@@ -91,21 +92,22 @@ impl<C> General<C> {
         }
     }
 
-    pub fn prefix<S: ToString>(mut self, prefix: S) -> Self {
+    pub fn with_prefix<S: ToString>(mut self, prefix: S) -> Self {
         self.prefix = prefix.to_string();
         self
     }
 }
 
 #[async_trait]
-impl<B, E, C> Command<B, E> for General<C>
+impl<S, E, C> Command<S, E> for General<C>
 where
-    B: Send,
+    S: Send + Sync,
-    C: Command<B, E> + Send + Sync,
+    C: Command<S, E> + Sync,
 {
-    fn description(&self, ctx: &Context) -> Option<String> {
+    fn info(&self, ctx: &Context) -> Info {
-        let inner = self.inner.description(ctx)?;
+        self.inner
-        Some(format!("{}{} - {inner}", self.prefix, self.name))
+            .info(ctx)
+            .with_prepended_trigger(format!("{}{}", self.prefix, self.name))
     }
 
     async fn execute(
@@ -113,23 +115,21 @@ where
         arg: &str,
         msg: &Message,
         ctx: &Context,
-        bot: &mut B,
+        bot: &Bot<S, E>,
-    ) -> Result<bool, E> {
+    ) -> Result<Propagate, E> {
-        // TODO Replace with let-else
+        let Some((name, rest)) = parse_prefix_initiated(arg, &self.prefix) else {
-        let (name, rest) = match parse_prefix_initiated(arg, &self.prefix) {
+            return Ok(Propagate::Yes);
-            Some(parsed) => parsed,
-            None => return Ok(false),
         };
 
         if name != self.name {
-            return Ok(false);
+            return Ok(Propagate::Yes);
         }
 
         if parse_prefix_initiated(rest, "@").is_some() {
             // The command looks like a specific command. If we treated it like
             // a general command match, we would interpret other bots' specific
             // commands as general commands.
-            return Ok(false);
+            return Ok(Propagate::Yes);
         }
 
         self.inner.execute(rest, msg, ctx, bot).await
@@ -151,22 +151,23 @@ impl<C> Specific<C> {
         }
     }
 
-    pub fn prefix<S: ToString>(mut self, prefix: S) -> Self {
+    pub fn with_prefix<S: ToString>(mut self, prefix: S) -> Self {
         self.prefix = prefix.to_string();
         self
     }
 }
 
 #[async_trait]
-impl<B, E, C> Command<B, E> for Specific<C>
+impl<S, E, C> Command<S, E> for Specific<C>
 where
-    B: Send,
+    S: Send + Sync,
-    C: Command<B, E> + Send + Sync,
+    C: Command<S, E> + Sync,
 {
-    fn description(&self, ctx: &Context) -> Option<String> {
+    fn info(&self, ctx: &Context) -> Info {
-        let inner = self.inner.description(ctx)?;
         let nick = nick::mention(&ctx.joined.session.name);
-        Some(format!("{}{} @{nick} - {inner}", self.prefix, self.name))
+        self.inner
+            .info(ctx)
+            .with_prepended_trigger(format!("{}{} @{nick}", self.prefix, self.name))
     }
 
     async fn execute(
@@ -174,26 +175,22 @@ where
         arg: &str,
         msg: &Message,
         ctx: &Context,
-        bot: &mut B,
+        bot: &Bot<S, E>,
-    ) -> Result<bool, E> {
+    ) -> Result<Propagate, E> {
-        // TODO Replace with let-else
+        let Some((name, rest)) = parse_prefix_initiated(arg, &self.prefix) else {
-        let (name, rest) = match parse_prefix_initiated(arg, &self.prefix) {
+            return Ok(Propagate::Yes);
-            Some(parsed) => parsed,
-            None => return Ok(false),
         };
 
         if name != self.name {
-            return Ok(false);
+            return Ok(Propagate::Yes);
         }
 
-        // TODO Replace with let-else
+        let Some((nick, rest)) = parse_prefix_initiated(rest, "@") else {
-        let (nick, rest) = match parse_prefix_initiated(rest, "@") {
+            return Ok(Propagate::Yes);
-            Some(parsed) => parsed,
-            None => return Ok(false),
         };
 
         if nick::normalize(nick) != nick::normalize(&ctx.joined.session.name) {
-            return Ok(false);
+            return Ok(Propagate::Yes);
         }
 
         self.inner.execute(rest, msg, ctx, bot).await

euphoxide-bot/src/command/basic.rs

@@ -0,0 +1,115 @@
+//! Basic command wrappers.
+
+use async_trait::async_trait;
+use euphoxide::api::Message;
+
+use crate::bot::Bot;
+
+use super::{Command, Context, Info, Propagate};
+
+/// Rewrite or hide command info.
+pub struct Described<C> {
+    pub inner: C,
+    pub trigger: Option<Option<String>>,
+    pub description: Option<Option<String>>,
+}
+
+impl<C> Described<C> {
+    pub fn new(inner: C) -> Self {
+        Self {
+            inner,
+            trigger: None,
+            description: None,
+        }
+    }
+
+    pub fn hidden(inner: C) -> Self {
+        Self::new(inner)
+            .with_trigger_hidden()
+            .with_description_hidden()
+    }
+
+    pub fn with_trigger(mut self, trigger: impl ToString) -> Self {
+        self.trigger = Some(Some(trigger.to_string()));
+        self
+    }
+
+    pub fn with_trigger_hidden(mut self) -> Self {
+        self.trigger = Some(None);
+        self
+    }
+
+    pub fn with_description(mut self, description: impl ToString) -> Self {
+        self.description = Some(Some(description.to_string()));
+        self
+    }
+
+    pub fn with_description_hidden(mut self) -> Self {
+        self.description = Some(None);
+        self
+    }
+}
+
+#[async_trait]
+impl<S, E, C> Command<S, E> for Described<C>
+where
+    S: Send + Sync,
+    C: Command<S, E> + Sync,
+{
+    fn info(&self, ctx: &Context) -> Info {
+        let info = self.inner.info(ctx);
+        Info {
+            trigger: self.trigger.clone().unwrap_or(info.trigger),
+            description: self.description.clone().unwrap_or(info.description),
+        }
+    }
+
+    async fn execute(
+        &self,
+        arg: &str,
+        msg: &Message,
+        ctx: &Context,
+        bot: &Bot<S, E>,
+    ) -> Result<Propagate, E> {
+        self.inner.execute(arg, msg, ctx, bot).await
+    }
+}
+
+pub struct Prefixed<C> {
+    prefix: String,
+    inner: C,
+}
+
+impl<C> Prefixed<C> {
+    pub fn new<S: ToString>(prefix: S, inner: C) -> Self {
+        Self {
+            prefix: prefix.to_string(),
+            inner,
+        }
+    }
+}
+
+#[async_trait]
+impl<S, E, C> Command<S, E> for Prefixed<C>
+where
+    S: Send + Sync,
+    C: Command<S, E> + Sync,
+{
+    fn info(&self, ctx: &Context) -> Info {
+        self.inner.info(ctx).with_prepended_trigger(&self.prefix)
+    }
+
+    async fn execute(
+        &self,
+        arg: &str,
+        msg: &Message,
+        ctx: &Context,
+        bot: &Bot<S, E>,
+    ) -> Result<Propagate, E> {
+        if let Some(rest) = arg.trim_start().strip_prefix(&self.prefix) {
+            self.inner.execute(rest, msg, ctx, bot).await
+        } else {
+            Ok(Propagate::Yes)
+        }
+    }
+}

euphoxide-bot/src/command/botrulez.rs

@@ -0,0 +1,8 @@
+//! The main [botrulez](https://github.com/jedevc/botrulez) commands.
+
+mod full_help;
+mod ping;
+mod short_help;
+mod uptime;
+
+pub use self::{full_help::*, ping::*, short_help::*, uptime::*};

euphoxide-bot/src/command/botrulez/full_help.rs

@@ -0,0 +1,110 @@
+use async_trait::async_trait;
+#[cfg(feature = "clap")]
+use clap::Parser;
+use euphoxide::api::Message;
+
+#[cfg(feature = "clap")]
+use crate::command::clap::ClapCommand;
+use crate::{
+    bot::Bot,
+    command::{Command, Context, Propagate},
+};
+
+#[derive(Default)]
+pub struct FullHelp {
+    pub before: String,
+    pub after: String,
+}
+
+impl FullHelp {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn with_before(mut self, before: impl ToString) -> Self {
+        self.before = before.to_string();
+        self
+    }
+
+    pub fn with_after(mut self, after: impl ToString) -> Self {
+        self.after = after.to_string();
+        self
+    }
+
+    fn formulate_reply<S, E>(&self, ctx: &Context, bot: &Bot<S, E>) -> String {
+        let mut result = String::new();
+
+        if !self.before.is_empty() {
+            result.push_str(&self.before);
+            result.push('\n');
+        }
+
+        for info in bot.commands.infos(ctx) {
+            if let Some(trigger) = &info.trigger {
+                result.push_str(trigger);
+                if let Some(description) = &info.description {
+                    result.push_str(" - ");
+                    result.push_str(description);
+                }
+                result.push('\n');
+            }
+        }
+
+        if !self.after.is_empty() {
+            result.push_str(&self.after);
+            result.push('\n');
+        }
+
+        result
+    }
+}
+
+#[async_trait]
+impl<S, E> Command<S, E> for FullHelp
+where
+    S: Send + Sync,
+    E: From<euphoxide::Error>,
+{
+    async fn execute(
+        &self,
+        arg: &str,
+        msg: &Message,
+        ctx: &Context,
+        bot: &Bot<S, E>,
+    ) -> Result<Propagate, E> {
+        if arg.trim().is_empty() {
+            let reply = self.formulate_reply(ctx, bot);
+            ctx.reply_only(msg.id, reply).await?;
+            Ok(Propagate::No)
+        } else {
+            Ok(Propagate::Yes)
+        }
+    }
+}
+
+/// Show full bot help.
+#[cfg(feature = "clap")]
+#[derive(Parser)]
+pub struct FullHelpArgs {}
+
+#[cfg(feature = "clap")]
+#[async_trait]
+impl<S, E> ClapCommand<S, E> for FullHelp
+where
+    S: Send + Sync,
+    E: From<euphoxide::Error>,
+{
+    type Args = FullHelpArgs;
+
+    async fn execute(
+        &self,
+        _args: Self::Args,
+        msg: &Message,
+        ctx: &Context,
+        bot: &Bot<S, E>,
+    ) -> Result<Propagate, E> {
+        let reply = self.formulate_reply(ctx, bot);
+        ctx.reply_only(msg.id, reply).await?;
+        Ok(Propagate::No)
+    }
+}

euphoxide-bot/src/command/botrulez/ping.rs

@@ -0,0 +1,71 @@
+use async_trait::async_trait;
+#[cfg(feature = "clap")]
+use clap::Parser;
+use euphoxide::api::Message;
+
+#[cfg(feature = "clap")]
+use crate::command::clap::ClapCommand;
+use crate::{
+    bot::Bot,
+    command::{Command, Context, Propagate},
+};
+
+pub struct Ping(pub String);
+
+impl Ping {
+    pub fn new<S: ToString>(reply: S) -> Self {
+        Self(reply.to_string())
+    }
+}
+
+impl Default for Ping {
+    fn default() -> Self {
+        Self::new("Pong!")
+    }
+}
+
+#[async_trait]
+impl<S, E> Command<S, E> for Ping
+where
+    E: From<euphoxide::Error>,
+{
+    async fn execute(
+        &self,
+        arg: &str,
+        msg: &Message,
+        ctx: &Context,
+        _bot: &Bot<S, E>,
+    ) -> Result<Propagate, E> {
+        if arg.trim().is_empty() {
+            ctx.reply_only(msg.id, &self.0).await?;
+            Ok(Propagate::No)
+        } else {
+            Ok(Propagate::Yes)
+        }
+    }
+}
+
+/// Trigger a short reply.
+#[cfg(feature = "clap")]
+#[derive(Parser)]
+pub struct PingArgs {}
+
+#[cfg(feature = "clap")]
+#[async_trait]
+impl<S, E> ClapCommand<S, E> for Ping
+where
+    E: From<euphoxide::Error>,
+{
+    type Args = PingArgs;
+
+    async fn execute(
+        &self,
+        _args: Self::Args,
+        msg: &Message,
+        ctx: &Context,
+        _bot: &Bot<S, E>,
+    ) -> Result<Propagate, E> {
+        ctx.reply_only(msg.id, &self.0).await?;
+        Ok(Propagate::No)
+    }
+}

euphoxide-bot/src/command/botrulez/short_help.rs

@@ -0,0 +1,65 @@
+use async_trait::async_trait;
+#[cfg(feature = "clap")]
+use clap::Parser;
+use euphoxide::api::Message;
+
+#[cfg(feature = "clap")]
+use crate::command::clap::ClapCommand;
+use crate::{
+    bot::Bot,
+    command::{Command, Context, Propagate},
+};
+
+pub struct ShortHelp(pub String);
+
+impl ShortHelp {
+    pub fn new<S: ToString>(text: S) -> Self {
+        Self(text.to_string())
+    }
+}
+
+#[async_trait]
+impl<S, E> Command<S, E> for ShortHelp
+where
+    E: From<euphoxide::Error>,
+{
+    async fn execute(
+        &self,
+        arg: &str,
+        msg: &Message,
+        ctx: &Context,
+        _bot: &Bot<S, E>,
+    ) -> Result<Propagate, E> {
+        if arg.trim().is_empty() {
+            ctx.reply_only(msg.id, &self.0).await?;
+            Ok(Propagate::No)
+        } else {
+            Ok(Propagate::Yes)
+        }
+    }
+}
+
+/// Show short bot help.
+#[cfg(feature = "clap")]
+#[derive(Parser)]
+pub struct ShortHelpArgs {}
+
+#[cfg(feature = "clap")]
+#[async_trait]
+impl<S, E> ClapCommand<S, E> for ShortHelp
+where
+    E: From<euphoxide::Error>,
+{
+    type Args = ShortHelpArgs;
+
+    async fn execute(
+        &self,
+        _args: Self::Args,
+        msg: &Message,
+        ctx: &Context,
+        _bot: &Bot<S, E>,
+    ) -> Result<Propagate, E> {
+        ctx.reply_only(msg.id, &self.0).await?;
+        Ok(Propagate::No)
+    }
+}

euphoxide-bot/src/command/botrulez/uptime.rs

@@ -1,10 +1,15 @@
 use async_trait::async_trait;
+#[cfg(feature = "clap")]
 use clap::Parser;
+use euphoxide::api::Message;
 use jiff::{Span, Timestamp, Unit};
 
-use crate::api::Message;
+#[cfg(feature = "clap")]
-use crate::bot::command::{ClapCommand, Command, Context};
+use crate::command::clap::ClapCommand;
-use crate::conn;
+use crate::{
+    bot::Bot,
+    command::{Command, Context, Propagate},
+};
 
 pub fn format_time(t: Timestamp) -> String {
     t.strftime("%Y-%m-%d %H:%M:%S UTC").to_string()
@@ -57,8 +62,8 @@ pub trait HasStartTime {
 }
 
 impl Uptime {
-    fn formulate_reply<B: HasStartTime>(&self, ctx: &Context, bot: &B, connected: bool) -> String {
+    fn formulate_reply<S, E>(&self, ctx: &Context, bot: &Bot<S, E>, connected: bool) -> String {
-        let start = bot.start_time();
+        let start = bot.start_time;
         let now = Timestamp::now();
 
         let mut reply = format!(
@@ -81,53 +86,55 @@ impl Uptime {
 }
 
 #[async_trait]
-impl<B, E> Command<B, E> for Uptime
+impl<S, E> Command<S, E> for Uptime
 where
-    B: HasStartTime + Send,
+    S: Send + Sync,
-    E: From<conn::Error>,
+    E: From<euphoxide::Error>,
 {
     async fn execute(
         &self,
         arg: &str,
         msg: &Message,
         ctx: &Context,
-        bot: &mut B,
+        bot: &Bot<S, E>,
-    ) -> Result<bool, E> {
+    ) -> Result<Propagate, E> {
         if arg.trim().is_empty() {
             let reply = self.formulate_reply(ctx, bot, false);
-            ctx.reply(msg.id, reply).await?;
+            ctx.reply_only(msg.id, reply).await?;
-            Ok(true)
+            Ok(Propagate::No)
         } else {
-            Ok(false)
+            Ok(Propagate::Yes)
         }
     }
 }
 
 /// Show how long the bot has been online.
+#[cfg(feature = "clap")]
 #[derive(Parser)]
-pub struct Args {
+pub struct UptimeArgs {
     /// Show how long the bot has been connected without interruption.
     #[arg(long, short)]
     pub connected: bool,
 }
 
+#[cfg(feature = "clap")]
 #[async_trait]
-impl<B, E> ClapCommand<B, E> for Uptime
+impl<S, E> ClapCommand<S, E> for Uptime
 where
-    B: HasStartTime + Send,
+    S: Send + Sync,
-    E: From<conn::Error>,
+    E: From<euphoxide::Error>,
 {
-    type Args = Args;
+    type Args = UptimeArgs;
 
     async fn execute(
         &self,
         args: Self::Args,
         msg: &Message,
         ctx: &Context,
-        bot: &mut B,
+        bot: &Bot<S, E>,
-    ) -> Result<bool, E> {
+    ) -> Result<Propagate, E> {
         let reply = self.formulate_reply(ctx, bot, args.connected);
-        ctx.reply(msg.id, reply).await?;
+        ctx.reply_only(msg.id, reply).await?;
-        Ok(true)
+        Ok(Propagate::No)
     }
 }

euphoxide-bot/src/command/clap.rs

@@ -1,13 +1,15 @@
+//! [`clap`]-based commands.
+
 use async_trait::async_trait;
 use clap::{CommandFactory, Parser};
+use euphoxide::api::Message;
 
-use crate::api::Message;
+use crate::bot::Bot;
-use crate::conn;
 
-use super::{Command, Context};
+use super::{Command, Context, Info, Propagate};
 
 #[async_trait]
-pub trait ClapCommand<B, E> {
+pub trait ClapCommand<S, E> {
     type Args;
 
     async fn execute(
@@ -15,8 +17,8 @@ pub trait ClapCommand<B, E> {
         args: Self::Args,
         msg: &Message,
         ctx: &Context,
-        bot: &mut B,
+        bot: &Bot<S, E>,
-    ) -> Result<bool, E>;
+    ) -> Result<Propagate, E>;
 }
 
 /// Parse bash-like quoted arguments separated by whitespace.
@@ -99,15 +101,18 @@ fn parse_quoted_args(text: &str) -> Result<Vec<String>, &'static str> {
 pub struct Clap<C>(pub C);
 
 #[async_trait]
-impl<B, E, C> Command<B, E> for Clap<C>
+impl<S, E, C> Command<S, E> for Clap<C>
 where
-    B: Send,
+    S: Send + Sync,
-    E: From<conn::Error>,
+    E: From<euphoxide::Error>,
-    C: ClapCommand<B, E> + Send + Sync,
+    C: ClapCommand<S, E> + Sync,
     C::Args: Parser + Send,
 {
-    fn description(&self, _ctx: &Context) -> Option<String> {
+    fn info(&self, _ctx: &Context) -> Info {
-        C::Args::command().get_about().map(|s| format!("{s}"))
+        Info {
+            description: C::Args::command().get_about().map(|s| s.to_string()),
+            ..Info::default()
+        }
     }
 
     async fn execute(
@@ -115,13 +120,13 @@ where
         arg: &str,
         msg: &Message,
         ctx: &Context,
-        bot: &mut B,
+        bot: &Bot<S, E>,
-    ) -> Result<bool, E> {
+    ) -> Result<Propagate, E> {
         let mut args = match parse_quoted_args(arg) {
             Ok(args) => args,
             Err(err) => {
-                ctx.reply(msg.id, err).await?;
+                ctx.reply_only(msg.id, err).await?;
-                return Ok(true);
+                return Ok(Propagate::No);
             }
         };
 
@@ -132,8 +137,8 @@ where
         let args = match C::Args::try_parse_from(args) {
             Ok(args) => args,
             Err(err) => {
-                ctx.reply(msg.id, format!("{}", err.render())).await?;
+                ctx.reply_only(msg.id, format!("{}", err.render())).await?;
-                return Ok(true);
+                return Ok(Propagate::No);
             }
         };
 

euphoxide-bot/src/instance.rs

@@ -0,0 +1,447 @@
+use std::{
+    fmt, result,
+    str::FromStr,
+    sync::{Arc, Mutex},
+    time::Duration,
+};
+
+use cookie::{Cookie, CookieJar};
+use euphoxide::{
+    api::{Auth, AuthOption, BounceEvent, Data, Nick, ParsedPacket},
+    client::{
+        conn::{ClientConn, ClientConnConfig, ClientConnHandle},
+        state::State,
+    },
+};
+use log::warn;
+use tokio::{
+    select,
+    sync::{mpsc, oneshot},
+};
+use tokio_tungstenite::tungstenite::{
+    self,
+    http::{HeaderValue, StatusCode},
+};
+
+enum Error {
+    Stopped,
+    NoReferences,
+    AuthRequired,
+    InvalidPassword,
+    OutOfJoinAttempts,
+    Euphoxide(euphoxide::Error),
+}
+
+impl Error {
+    fn is_fatal(&self) -> bool {
+        match self {
+            Self::Stopped => true,
+            Self::NoReferences => true,
+            Self::AuthRequired => true,
+            Self::InvalidPassword => true,
+            Self::OutOfJoinAttempts => true,
+            Self::Euphoxide(euphoxide::Error::Tungstenite(tungstenite::Error::Http(response))) => {
+                response.status() == StatusCode::NOT_FOUND
+            }
+            _ => false,
+        }
+    }
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Stopped => write!(f, "the instance was stopped manually"),
+            Self::NoReferences => write!(f, "all references to the instance were dropped"),
+            Self::AuthRequired => write!(f, "authentication required but no credentials found"),
+            Self::InvalidPassword => write!(f, "authentication required but password is invalid"),
+            Self::OutOfJoinAttempts => write!(f, "failed to join within attempt limit"),
+            Self::Euphoxide(error) => write!(f, "{error}"),
+        }
+    }
+}
+
+impl From<euphoxide::Error> for Error {
+    fn from(value: euphoxide::Error) -> Self {
+        Self::Euphoxide(value)
+    }
+}
+
+type Result<T> = result::Result<T, Error>;
+
+enum Command {
+    GetConn(oneshot::Sender<ClientConnHandle>),
+    Stop,
+}
+
+#[derive(Debug)]
+pub enum Event {
+    Started {
+        id: usize,
+    },
+    Connecting {
+        id: usize,
+    },
+    Connected {
+        id: usize,
+        conn: ClientConnHandle,
+        state: State,
+    },
+    Joined {
+        id: usize,
+        conn: ClientConnHandle,
+        state: State,
+    },
+    Packet {
+        id: usize,
+        conn: ClientConnHandle,
+        state: State,
+        packet: ParsedPacket,
+    },
+    Disconnected {
+        id: usize,
+    },
+    Stopped {
+        id: usize,
+    },
+}
+
+impl Event {
+    pub fn id(&self) -> usize {
+        match self {
+            Self::Started { id } => *id,
+            Self::Connecting { id } => *id,
+            Self::Connected { id, .. } => *id,
+            Self::Joined { id, .. } => *id,
+            Self::Packet { id, .. } => *id,
+            Self::Disconnected { id } => *id,
+            Self::Stopped { id } => *id,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct ServerConfig {
+    pub client: ClientConnConfig,
+    pub cookies: Arc<Mutex<CookieJar>>,
+    pub join_attempts: usize,
+    pub reconnect_delay: Duration,
+    pub cmd_channel_bufsize: usize,
+}
+
+impl ServerConfig {
+    pub fn instance(self, room: impl ToString) -> InstanceConfig {
+        InstanceConfig {
+            server: self,
+            room: room.to_string(),
+            human: false,
+            username: None,
+            force_username: false,
+            password: None,
+        }
+    }
+}
+
+impl Default for ServerConfig {
+    fn default() -> Self {
+        Self {
+            client: ClientConnConfig::default(),
+            cookies: Arc::new(Mutex::new(CookieJar::new())),
+            join_attempts: 5,
+            reconnect_delay: Duration::from_secs(30),
+            cmd_channel_bufsize: 1,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct InstanceConfig {
+    pub server: ServerConfig,
+    pub room: String,
+    pub human: bool,
+    pub username: Option<String>,
+    pub force_username: bool,
+    pub password: Option<String>,
+}
+
+impl InstanceConfig {
+    pub fn with_human(mut self, human: bool) -> Self {
+        self.human = human;
+        self
+    }
+
+    pub fn with_username(mut self, username: impl ToString) -> Self {
+        self.username = Some(username.to_string());
+        self
+    }
+
+    pub fn with_force_username(mut self, enabled: bool) -> Self {
+        self.force_username = enabled;
+        self
+    }
+
+    pub fn with_password(mut self, password: impl ToString) -> Self {
+        self.password = Some(password.to_string());
+        self
+    }
+}
+
+struct InstanceTask {
+    id: usize,
+    config: InstanceConfig,
+
+    cmd_rx: mpsc::Receiver<Command>,
+    event_tx: mpsc::Sender<Event>,
+
+    attempts: usize,
+    never_joined: bool,
+}
+
+impl InstanceTask {
+    fn get_cookies(&self) -> Option<HeaderValue> {
+        self.config
+            .server
+            .cookies
+            .lock()
+            .unwrap()
+            .iter()
+            .map(|c| c.stripped().to_string())
+            .collect::<Vec<_>>()
+            .join("; ")
+            .try_into()
+            .ok()
+    }
+
+    fn set_cookies(&mut self, cookies: &[HeaderValue]) {
+        let mut guard = self.config.server.cookies.lock().unwrap();
+        for cookie in cookies {
+            if let Ok(cookie) = cookie.to_str() {
+                if let Ok(cookie) = Cookie::from_str(cookie) {
+                    guard.add(cookie);
+                }
+            }
+        }
+    }
+
+    async fn connect(&mut self) -> Result<ClientConn> {
+        let (conn, cookies) = ClientConn::connect_with_config(
+            &self.config.room,
+            self.get_cookies(),
+            &self.config.server.client,
+        )
+        .await?;
+
+        self.set_cookies(&cookies);
+
+        Ok(conn)
+    }
+
+    async fn on_joined(&mut self, conn: &ClientConn) {
+        self.never_joined = false;
+
+        let _ = self
+            .event_tx
+            .send(Event::Joined {
+                id: self.id,
+                conn: conn.handle(),
+                state: conn.state().clone(),
+            })
+            .await;
+    }
+
+    async fn on_packet(&mut self, conn: &mut ClientConn, packet: ParsedPacket) -> Result<()> {
+        let _ = self
+            .event_tx
+            .send(Event::Packet {
+                id: self.id,
+                conn: conn.handle(),
+                state: conn.state().clone(),
+                packet: packet.clone(),
+            })
+            .await;
+
+        match packet.into_data()? {
+            // Attempting to authenticate
+            Data::BounceEvent(BounceEvent {
+                auth_options: Some(auth_options),
+                ..
+            }) if auth_options.contains(&AuthOption::Passcode) => {
+                if let Some(password) = &self.config.password {
+                    conn.send(Auth {
+                        r#type: AuthOption::Passcode,
+                        passcode: Some(password.clone()),
+                    })
+                    .await?;
+                } else {
+                    return Err(Error::AuthRequired);
+                }
+            }
+
+            // Auth attempt failed :(
+            Data::AuthReply(ev) if !ev.success => return Err(Error::InvalidPassword),
+
+            // Just joined
+            Data::SnapshotEvent(ev) => {
+                if let Some(username) = &self.config.username {
+                    if ev.nick.is_none() || self.config.force_username {
+                        conn.send(Nick {
+                            name: username.clone(),
+                        })
+                        .await?;
+                    }
+                }
+
+                // Maybe we should only count this as joining if we successfully
+                // updated the nick instead of just sending a Nick command? And
+                // maybe we should ensure that we're in the State::Joined state?
+                // Both of these would probably complicate the code a lot. On
+                // the other hand, InstanceEvent::Joined::state would contain
+                // the actual nick after joining, which feels like the right
+                // thing to do™. Probably not worth the increase in code
+                // complexity though.
+
+                self.on_joined(conn).await;
+            }
+
+            _ => {}
+        }
+
+        Ok(())
+    }
+
+    async fn on_cmd(&mut self, conn: &ClientConn, cmd: Command) -> Result<()> {
+        match cmd {
+            Command::GetConn(sender) => {
+                let _ = sender.send(conn.handle());
+                Ok(())
+            }
+            Command::Stop => Err(Error::Stopped),
+        }
+    }
+
+    async fn run_once(&mut self) -> Result<()> {
+        // If we try to connect too many times without managing to join at least
+        // once, the room is probably not accessible for one reason or another
+        // and the instance should stop.
+        self.attempts += 1;
+        if self.never_joined && self.attempts > self.config.server.join_attempts {
+            return Err(Error::OutOfJoinAttempts);
+        }
+
+        let _ = self.event_tx.send(Event::Connecting { id: self.id }).await;
+
+        let mut conn = match self.connect().await {
+            Ok(conn) => conn,
+            Err(err) => {
+                // When we fail to connect, we want to wait a bit before
+                // reconnecting in order not to spam the server. However, when
+                // we are connected successfully and then disconnect for
+                // whatever reason, we want to try to reconnect immediately. We
+                // might, for example, be disconnected from the server because
+                // we just logged in.
+                tokio::time::sleep(self.config.server.reconnect_delay).await;
+                Err(err)?
+            }
+        };
+
+        let _ = self
+            .event_tx
+            .send(Event::Connected {
+                id: self.id,
+                conn: conn.handle(),
+                state: conn.state().clone(),
+            })
+            .await;
+
+        let result = loop {
+            let received = select! {
+                r = conn.recv() => Ok(r?),
+                r = self.cmd_rx.recv() => Err(r),
+            };
+
+            match received {
+                // We received a packet
+                Ok(None) => break Ok(()), // Connection closed
+                Ok(Some(packet)) => self.on_packet(&mut conn, packet).await?,
+                // We received a command
+                Err(None) => break Err(Error::NoReferences),
+                Err(Some(cmd)) => self.on_cmd(&conn, cmd).await?,
+            };
+        };
+
+        let _ = self
+            .event_tx
+            .send(Event::Disconnected { id: self.id })
+            .await;
+
+        result
+    }
+
+    async fn run(mut self) {
+        let _ = self.event_tx.send(Event::Started { id: self.id }).await;
+
+        loop {
+            if let Err(err) = self.run_once().await {
+                warn!("instance {:?}: {err}", self.id);
+                if err.is_fatal() {
+                    break;
+                }
+            }
+        }
+
+        let _ = self.event_tx.send(Event::Stopped { id: self.id }).await;
+    }
+}
+
+#[derive(Clone)]
+pub struct Instance {
+    id: usize,
+    cmd_tx: mpsc::Sender<Command>,
+}
+
+impl fmt::Debug for Instance {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Instance")
+            .field("id", &self.id)
+            .finish_non_exhaustive()
+    }
+}
+
+impl Instance {
+    pub fn new(id: usize, config: InstanceConfig, event_tx: mpsc::Sender<Event>) -> Self {
+        let (cmd_tx, cmd_rx) = mpsc::channel(config.server.cmd_channel_bufsize);
+
+        let task = InstanceTask {
+            id,
+            config,
+            attempts: 0,
+            never_joined: false,
+            cmd_rx,
+            event_tx,
+        };
+
+        tokio::task::spawn(task.run());
+
+        Self { id, cmd_tx }
+    }
+
+    pub fn id(&self) -> usize {
+        self.id
+    }
+
+    pub fn stopped(&self) -> bool {
+        self.cmd_tx.is_closed()
+    }
+
+    pub async fn stop(&self) {
+        let _ = self.cmd_tx.send(Command::Stop).await;
+    }
+
+    pub async fn handle(&self) -> Option<ClientConnHandle> {
+        let (tx, rx) = oneshot::channel();
+        let _ = self.cmd_tx.send(Command::GetConn(tx)).await;
+        rx.await.ok()
+    }
+}

euphoxide-bot/src/instances.rs

@@ -0,0 +1,210 @@
+use std::collections::HashMap;
+
+use euphoxide::{
+    api::ParsedPacket,
+    client::{conn::ClientConnHandle, state::State},
+};
+use tokio::{
+    select,
+    sync::{mpsc, oneshot},
+};
+
+use crate::instance::{Event as IEvent, Instance, InstanceConfig};
+
+#[derive(Debug)]
+pub enum Event {
+    Started {
+        instance: Instance,
+    },
+    Connecting {
+        instance: Instance,
+    },
+    Connected {
+        instance: Instance,
+        conn: ClientConnHandle,
+        state: State,
+    },
+    Joined {
+        instance: Instance,
+        conn: ClientConnHandle,
+        state: State,
+    },
+    Packet {
+        instance: Instance,
+        conn: ClientConnHandle,
+        state: State,
+        packet: ParsedPacket,
+    },
+    Disconnected {
+        instance: Instance,
+    },
+    Stopped {
+        instance: Instance,
+    },
+}
+
+impl Event {
+    fn from_instance_event(instance: Instance, event: IEvent) -> Self {
+        match event {
+            IEvent::Started { id: _ } => Self::Started { instance },
+            IEvent::Connecting { id: _ } => Self::Connecting { instance },
+            IEvent::Connected { id: _, conn, state } => Self::Connected {
+                instance,
+                conn,
+                state,
+            },
+            IEvent::Joined { id: _, conn, state } => Self::Joined {
+                instance,
+                conn,
+                state,
+            },
+            IEvent::Packet {
+                id: _,
+                conn,
+                state,
+                packet,
+            } => Self::Packet {
+                instance,
+                conn,
+                state,
+                packet,
+            },
+            IEvent::Disconnected { id: _ } => Self::Disconnected { instance },
+            IEvent::Stopped { id: _ } => Self::Stopped { instance },
+        }
+    }
+
+    pub fn instance(&self) -> &Instance {
+        match self {
+            Self::Started { instance } => instance,
+            Self::Connecting { instance, .. } => instance,
+            Self::Connected { instance, .. } => instance,
+            Self::Joined { instance, .. } => instance,
+            Self::Packet { instance, .. } => instance,
+            Self::Disconnected { instance } => instance,
+            Self::Stopped { instance } => instance,
+        }
+    }
+}
+
+#[allow(clippy::large_enum_variant)]
+enum Command {
+    GetInstances(oneshot::Sender<Vec<Instance>>),
+    AddInstance(InstanceConfig, oneshot::Sender<Instance>),
+}
+
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct InstancesConfig {
+    pub cmd_channel_bufsize: usize,
+    pub event_channel_bufsize: usize,
+}
+
+impl Default for InstancesConfig {
+    fn default() -> Self {
+        Self {
+            cmd_channel_bufsize: 1,
+            event_channel_bufsize: 10,
+        }
+    }
+}
+
+struct InstancesTask {
+    next_id: usize,
+    instances: HashMap<usize, Instance>,
+
+    cmd_rx: mpsc::Receiver<Command>,
+    event_rx: mpsc::Receiver<IEvent>,
+    event_tx: mpsc::Sender<IEvent>,
+    out_tx: mpsc::Sender<Event>,
+}
+
+impl InstancesTask {
+    fn purge_instances(&mut self) {
+        self.instances.retain(|_, v| !v.stopped());
+    }
+
+    async fn on_event(&self, event: IEvent) {
+        if let Some(instance) = self.instances.get(&event.id()) {
+            let event = Event::from_instance_event(instance.clone(), event);
+            let _ = self.out_tx.send(event).await;
+        }
+    }
+
+    async fn on_cmd(&mut self, cmd: Command) {
+        match cmd {
+            Command::GetInstances(tx) => {
+                self.purge_instances(); // Not necessary for correctness
+                let _ = tx.send(self.instances.values().cloned().collect());
+            }
+            Command::AddInstance(config, tx) => {
+                let id = self.next_id;
+                assert!(!self.instances.contains_key(&id));
+                self.next_id += 1;
+
+                let instance = Instance::new(id, config, self.event_tx.clone());
+                self.instances.insert(id, instance.clone());
+
+                let _ = tx.send(instance);
+            }
+        }
+    }
+
+    async fn run(mut self) {
+        loop {
+            // Prevent potential memory leak
+            self.purge_instances();
+
+            let received = select! {
+                r = self.event_rx.recv() => Ok(r),
+                r = self.cmd_rx.recv() => Err(r),
+            };
+
+            match received {
+                Ok(None) => break,
+                Ok(Some(event)) => self.on_event(event).await,
+                Err(None) => break,
+                Err(Some(cmd)) => self.on_cmd(cmd).await,
+            }
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct Instances {
+    cmd_tx: mpsc::Sender<Command>,
+}
+
+impl Instances {
+    pub fn new(config: InstancesConfig, event_tx: mpsc::Sender<Event>) -> Self {
+        let out_tx = event_tx;
+
+        let (cmd_tx, cmd_rx) = mpsc::channel(config.cmd_channel_bufsize);
+        let (event_tx, event_rx) = mpsc::channel(config.event_channel_bufsize);
+
+        let task = InstancesTask {
+            next_id: 0,
+            instances: HashMap::new(),
+            cmd_rx,
+            event_rx,
+            event_tx,
+            out_tx,
+        };
+
+        tokio::task::spawn(task.run());
+
+        Self { cmd_tx }
+    }
+
+    pub async fn get_instances(&self) -> Vec<Instance> {
+        let (tx, rx) = oneshot::channel();
+        let _ = self.cmd_tx.send(Command::GetInstances(tx)).await;
+        rx.await.expect("task should still be running")
+    }
+
+    pub async fn add_instance(&self, config: InstanceConfig) -> Instance {
+        let (tx, rx) = oneshot::channel();
+        let _ = self.cmd_tx.send(Command::AddInstance(config, tx)).await;
+        rx.await.expect("task should still be running")
+    }
+}

euphoxide-bot/src/lib.rs

@@ -0,0 +1,4 @@
+pub mod bot;
+pub mod command;
+pub mod instance;
+pub mod instances;

euphoxide-client/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "euphoxide-client"
+version = { workspace = true }
+edition = { workspace = true }
+
+[dependencies]
+cookie = { workspace = true }
+euphoxide = { workspace = true }
+log = { workspace = true }
+tokio = { workspace = true }
+tokio-tungstenite = { workspace = true }
+
+[dev-dependencies]
+anyhow = { workspace = true }
+rustls = { workspace = true }
+tokio = { workspace = true, features = ["full"] }
+tokio-tungstenite = { workspace = true, features = ["rustls-tls-native-roots"] }
+
+[lints]
+workspace = true

euphoxide-client/examples/examplebot_multi.rs

@@ -0,0 +1,103 @@
+use std::time::Duration;
+
+use euphoxide::{
+    api::{Data, Message, Nick, Send},
+    client::conn::ClientConnHandle,
+};
+use euphoxide_client::{Client, ClientEvent, MultiClient, MultiClientEvent};
+use tokio::sync::mpsc;
+
+async fn set_nick(conn: &ClientConnHandle) -> anyhow::Result<()> {
+    conn.send_only(Nick {
+        name: "examplebot".to_string(),
+    })
+    .await?;
+
+    Ok(())
+}
+
+async fn send_pong(conn: &ClientConnHandle, msg: Message) -> anyhow::Result<()> {
+    conn.send_only(Send {
+        content: "Pong!".to_string(),
+        parent: Some(msg.id),
+    })
+    .await?;
+
+    Ok(())
+}
+
+async fn send_pyramid(conn: &ClientConnHandle, msg: Message) -> anyhow::Result<()> {
+    let mut parent = msg.id;
+
+    for _ in 0..3 {
+        let first = conn
+            .send(Send {
+                content: "brick".to_string(),
+                parent: Some(parent),
+            })
+            .await?;
+
+        conn.send_only(Send {
+            content: "brick".to_string(),
+            parent: Some(parent),
+        })
+        .await?;
+
+        parent = first.await?.0.id;
+        tokio::time::sleep(Duration::from_secs(1)).await;
+    }
+
+    conn.send_only(Send {
+        content: "brick".to_string(),
+        parent: Some(parent),
+    })
+    .await?;
+
+    Ok(())
+}
+
+async fn on_data(conn: ClientConnHandle, data: Data) {
+    let result = match data {
+        Data::SnapshotEvent(_) => set_nick(&conn).await,
+        Data::SendEvent(event) if event.0.content == "!ping" => send_pong(&conn, event.0).await,
+        Data::SendEvent(event) if event.0.content == "!pyramid" => {
+            send_pyramid(&conn, event.0).await
+        }
+        _ => Ok(()),
+    };
+
+    if let Err(err) = result {
+        println!("Error while responding: {err}");
+    }
+}
+
+async fn run() -> anyhow::Result<()> {
+    let (event_tx, mut event_rx) = mpsc::channel(10);
+
+    // Don't drop the client or it will stop running.
+    let clients = MultiClient::new(event_tx);
+
+    clients
+        .client_builder("test")
+        .with_username("examplebot")
+        .build_and_add()
+        .await;
+
+    while let Some(event) = event_rx.recv().await {
+        if let MultiClientEvent::Packet { conn, packet, .. } = event {
+            let data = packet.into_data()?;
+            tokio::task::spawn(on_data(conn, data));
+        }
+    }
+
+    Ok(())
+}
+
+#[tokio::main]
+async fn main() {
+    loop {
+        if let Err(err) = run().await {
+            println!("Error while running: {err}");
+        }
+    }
+}

euphoxide-client/examples/examplebot_single.rs

@@ -0,0 +1,99 @@
+use std::time::Duration;
+
+use euphoxide::{
+    api::{Data, Message, Nick, Send},
+    client::conn::ClientConnHandle,
+};
+use euphoxide_client::{Client, ClientEvent};
+use tokio::sync::mpsc;
+
+async fn set_nick(conn: &ClientConnHandle) -> anyhow::Result<()> {
+    conn.send_only(Nick {
+        name: "examplebot".to_string(),
+    })
+    .await?;
+
+    Ok(())
+}
+
+async fn send_pong(conn: &ClientConnHandle, msg: Message) -> anyhow::Result<()> {
+    conn.send_only(Send {
+        content: "Pong!".to_string(),
+        parent: Some(msg.id),
+    })
+    .await?;
+
+    Ok(())
+}
+
+async fn send_pyramid(conn: &ClientConnHandle, msg: Message) -> anyhow::Result<()> {
+    let mut parent = msg.id;
+
+    for _ in 0..3 {
+        let first = conn
+            .send(Send {
+                content: "brick".to_string(),
+                parent: Some(parent),
+            })
+            .await?;
+
+        conn.send_only(Send {
+            content: "brick".to_string(),
+            parent: Some(parent),
+        })
+        .await?;
+
+        parent = first.await?.0.id;
+        tokio::time::sleep(Duration::from_secs(1)).await;
+    }
+
+    conn.send_only(Send {
+        content: "brick".to_string(),
+        parent: Some(parent),
+    })
+    .await?;
+
+    Ok(())
+}
+
+async fn on_data(conn: ClientConnHandle, data: Data) {
+    let result = match data {
+        Data::SnapshotEvent(_) => set_nick(&conn).await,
+        Data::SendEvent(event) if event.0.content == "!ping" => send_pong(&conn, event.0).await,
+        Data::SendEvent(event) if event.0.content == "!pyramid" => {
+            send_pyramid(&conn, event.0).await
+        }
+        _ => Ok(()),
+    };
+
+    if let Err(err) = result {
+        println!("Error while responding: {err}");
+    }
+}
+
+async fn run() -> anyhow::Result<()> {
+    let (event_tx, mut event_rx) = mpsc::channel(10);
+
+    // Don't drop the client or it will stop running.
+    let _client = Client::builder("test")
+        .with_username("examplebot")
+        .build(0, event_tx);
+
+    while let Some(event) = event_rx.recv().await {
+        if let ClientEvent::Packet { conn, packet, .. } = event {
+            let data = packet.into_data()?;
+            tokio::task::spawn(on_data(conn, data));
+        }
+    }
+
+    Ok(())
+}
+
+#[tokio::main]
+async fn main() {
+    loop {
+        if let Err(err) = run().await {
+            println!("Error while running: {err}");
+        }
+    }
+}

euphoxide-client/src/builder.rs

@@ -0,0 +1,40 @@
+use crate::ClientConfig;
+
+pub trait ClientBuilderBase<'a> {
+    type Base;
+}
+
+pub struct ClientBuilder<'a, B: ClientBuilderBase<'a>> {
+    pub(crate) base: B::Base,
+    pub(crate) config: ClientConfig,
+}
+
+impl<'a, B: ClientBuilderBase<'a>> ClientBuilder<'a, B> {
+    pub fn config(&self) -> &ClientConfig {
+        &self.config
+    }
+
+    pub fn config_mut(&mut self) -> &mut ClientConfig {
+        &mut self.config
+    }
+
+    pub fn with_human(mut self, human: bool) -> Self {
+        self.config.human = human;
+        self
+    }
+
+    pub fn with_username(mut self, username: impl ToString) -> Self {
+        self.config.username = Some(username.to_string());
+        self
+    }
+
+    pub fn with_force_username(mut self, force_username: bool) -> Self {
+        self.config.force_username = force_username;
+        self
+    }
+
+    pub fn with_password(mut self, password: impl ToString) -> Self {
+        self.config.password = Some(password.to_string());
+        self
+    }
+}

euphoxide-client/src/config.rs

@@ -0,0 +1,71 @@
+use std::{
+    sync::{Arc, Mutex},
+    time::Duration,
+};
+
+use cookie::CookieJar;
+use euphoxide::client::conn::ClientConnConfig;
+
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct ServerConfig {
+    pub client: ClientConnConfig,
+    pub cookies: Arc<Mutex<CookieJar>>,
+    pub join_attempts: usize,
+    pub reconnect_delay: Duration,
+    pub cmd_channel_bufsize: usize,
+}
+
+impl Default for ServerConfig {
+    fn default() -> Self {
+        Self {
+            client: ClientConnConfig::default(),
+            cookies: Arc::new(Mutex::new(CookieJar::new())),
+            join_attempts: 5,
+            reconnect_delay: Duration::from_secs(30),
+            cmd_channel_bufsize: 1,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct ClientConfig {
+    pub server: ServerConfig,
+    pub room: String,
+    pub human: bool,
+    pub username: Option<String>,
+    pub force_username: bool,
+    pub password: Option<String>,
+}
+
+impl ClientConfig {
+    pub fn new(server: ServerConfig, room: String) -> Self {
+        Self {
+            server,
+            room,
+            human: false,
+            username: None,
+            force_username: false,
+            password: None,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct MultiClientConfig {
+    pub server: ServerConfig,
+    pub cmd_channel_bufsize: usize,
+    pub event_channel_bufsize: usize,
+}
+
+impl Default for MultiClientConfig {
+    fn default() -> Self {
+        Self {
+            server: ServerConfig::default(),
+            cmd_channel_bufsize: 1,
+            event_channel_bufsize: 10,
+        }
+    }
+}

euphoxide-client/src/lib.rs

@@ -0,0 +1,6 @@
+mod builder;
+mod config;
+mod multi;
+mod single;
+
+pub use self::{builder::*, config::*, multi::*, single::*};

euphoxide-client/src/multi.rs

@@ -0,0 +1,228 @@
+use std::{collections::HashMap, sync::Arc};
+
+use euphoxide::{
+    api::ParsedPacket,
+    client::{conn::ClientConnHandle, state::State},
+};
+use tokio::{
+    select,
+    sync::{mpsc, oneshot},
+};
+
+use crate::{
+    Client, ClientBuilder, ClientBuilderBase, ClientConfig, ClientEvent, MultiClientConfig,
+};
+
+#[derive(Debug)]
+pub enum MultiClientEvent {
+    Started {
+        client: Client,
+    },
+    Connecting {
+        client: Client,
+    },
+    Connected {
+        client: Client,
+        conn: ClientConnHandle,
+        state: State,
+    },
+    Joined {
+        client: Client,
+        conn: ClientConnHandle,
+        state: State,
+    },
+    Packet {
+        client: Client,
+        conn: ClientConnHandle,
+        state: State,
+        packet: ParsedPacket,
+    },
+    Disconnected {
+        client: Client,
+    },
+    Stopped {
+        client: Client,
+    },
+}
+
+impl MultiClientEvent {
+    fn from_client_event(client: Client, event: ClientEvent) -> Self {
+        match event {
+            ClientEvent::Started { id: _ } => Self::Started { client },
+            ClientEvent::Connecting { id: _ } => Self::Connecting { client },
+            ClientEvent::Connected { id: _, conn, state } => Self::Connected {
+                client,
+                conn,
+                state,
+            },
+            ClientEvent::Joined { id: _, conn, state } => Self::Joined {
+                client,
+                conn,
+                state,
+            },
+            ClientEvent::Packet {
+                id: _,
+                conn,
+                state,
+                packet,
+            } => Self::Packet {
+                client,
+                conn,
+                state,
+                packet,
+            },
+            ClientEvent::Disconnected { id: _ } => Self::Disconnected { client },
+            ClientEvent::Stopped { id: _ } => Self::Stopped { client },
+        }
+    }
+
+    pub fn client(&self) -> &Client {
+        match self {
+            Self::Started { client } => client,
+            Self::Connecting { client, .. } => client,
+            Self::Connected { client, .. } => client,
+            Self::Joined { client, .. } => client,
+            Self::Packet { client, .. } => client,
+            Self::Disconnected { client } => client,
+            Self::Stopped { client } => client,
+        }
+    }
+}
+
+#[allow(clippy::large_enum_variant)]
+enum Command {
+    GetClients(oneshot::Sender<Vec<Client>>),
+    AddClient(ClientConfig, oneshot::Sender<Client>),
+}
+
+struct MultiClientTask {
+    next_id: usize,
+    clients: HashMap<usize, Client>,
+
+    cmd_rx: mpsc::Receiver<Command>,
+    event_rx: mpsc::Receiver<ClientEvent>,
+    event_tx: mpsc::Sender<ClientEvent>,
+    out_tx: mpsc::Sender<MultiClientEvent>,
+}
+
+impl MultiClientTask {
+    fn purge_clients(&mut self) {
+        self.clients.retain(|_, v| !v.stopped());
+    }
+
+    async fn on_event(&self, event: ClientEvent) {
+        if let Some(client) = self.clients.get(&event.id()) {
+            let event = MultiClientEvent::from_client_event(client.clone(), event);
+            let _ = self.out_tx.send(event).await;
+        }
+    }
+
+    async fn on_cmd(&mut self, cmd: Command) {
+        match cmd {
+            Command::GetClients(tx) => {
+                self.purge_clients(); // Not necessary for correctness
+                let _ = tx.send(self.clients.values().cloned().collect());
+            }
+            Command::AddClient(config, tx) => {
+                let id = self.next_id;
+                assert!(!self.clients.contains_key(&id));
+                self.next_id += 1;
+
+                let client = Client::new(id, config, self.event_tx.clone());
+                self.clients.insert(id, client.clone());
+
+                let _ = tx.send(client);
+            }
+        }
+    }
+
+    async fn run(mut self) {
+        loop {
+            // Prevent potential memory leak
+            self.purge_clients();
+
+            let received = select! {
+                r = self.event_rx.recv() => Ok(r),
+                r = self.cmd_rx.recv() => Err(r),
+            };
+
+            match received {
+                Ok(None) => break,
+                Ok(Some(event)) => self.on_event(event).await,
+                Err(None) => break,
+                Err(Some(cmd)) => self.on_cmd(cmd).await,
+            }
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct MultiClient {
+    config: Arc<MultiClientConfig>,
+    cmd_tx: mpsc::Sender<Command>,
+}
+
+impl MultiClient {
+    pub fn new(event_tx: mpsc::Sender<MultiClientEvent>) -> Self {
+        Self::new_with_config(MultiClientConfig::default(), event_tx)
+    }
+
+    pub fn new_with_config(
+        config: MultiClientConfig,
+        event_tx: mpsc::Sender<MultiClientEvent>,
+    ) -> Self {
+        let config = Arc::new(config);
+        let out_tx = event_tx;
+
+        let (cmd_tx, cmd_rx) = mpsc::channel(config.cmd_channel_bufsize);
+        let (event_tx, event_rx) = mpsc::channel(config.event_channel_bufsize);
+
+        let task = MultiClientTask {
+            next_id: 0,
+            clients: HashMap::new(),
+            cmd_rx,
+            event_rx,
+            event_tx,
+            out_tx,
+        };
+
+        tokio::task::spawn(task.run());
+
+        Self { config, cmd_tx }
+    }
+
+    pub async fn get_clients(&self) -> Vec<Client> {
+        let (tx, rx) = oneshot::channel();
+        let _ = self.cmd_tx.send(Command::GetClients(tx)).await;
+        rx.await.expect("task should still be running")
+    }
+
+    pub async fn add_client(&self, config: ClientConfig) -> Client {
+        let (tx, rx) = oneshot::channel();
+        let _ = self.cmd_tx.send(Command::AddClient(config, tx)).await;
+        rx.await.expect("task should still be running")
+    }
+}
+
+/////////////
+// Builder //
+/////////////
+
+impl<'a> ClientBuilderBase<'a> for MultiClient {
+    type Base = &'a Self;
+}
+
+impl MultiClient {
+    pub fn client_builder(&self, room: impl ToString) -> ClientBuilder<'_, Self> {
+        ClientBuilder {
+            base: self,
+            config: ClientConfig::new(self.config.server.clone(), room.to_string()),
+        }
+    }
+}
+
+impl ClientBuilder<'_, MultiClient> {
+    pub async fn build_and_add(self) -> Client {
+        self.base.add_client(self.config).await
+    }
+}

euphoxide-client/src/single.rs

@@ -0,0 +1,415 @@
+use std::{fmt, result, str::FromStr};
+
+use cookie::Cookie;
+use euphoxide::{
+    api::{Auth, AuthOption, BounceEvent, Data, Nick, ParsedPacket},
+    client::{
+        conn::{ClientConn, ClientConnHandle},
+        state::State,
+    },
+};
+use log::warn;
+use tokio::{
+    select,
+    sync::{mpsc, oneshot},
+};
+use tokio_tungstenite::tungstenite::{
+    self,
+    http::{HeaderValue, StatusCode},
+};
+
+use crate::{ClientBuilder, ClientBuilderBase, ClientConfig, ServerConfig};
+
+enum Error {
+    Stopped,
+    NoReferences,
+    AuthRequired,
+    InvalidPassword,
+    OutOfJoinAttempts,
+    Euphoxide(euphoxide::Error),
+}
+
+impl Error {
+    fn is_fatal(&self) -> bool {
+        match self {
+            Self::Stopped => true,
+            Self::NoReferences => true,
+            Self::AuthRequired => true,
+            Self::InvalidPassword => true,
+            Self::OutOfJoinAttempts => true,
+            Self::Euphoxide(euphoxide::Error::Tungstenite(tungstenite::Error::Http(response))) => {
+                response.status() == StatusCode::NOT_FOUND
+            }
+            _ => false,
+        }
+    }
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Stopped => write!(f, "the instance was stopped manually"),
+            Self::NoReferences => write!(f, "all references to the instance were dropped"),
+            Self::AuthRequired => write!(f, "authentication required but no credentials found"),
+            Self::InvalidPassword => write!(f, "authentication required but password is invalid"),
+            Self::OutOfJoinAttempts => write!(f, "failed to join within attempt limit"),
+            Self::Euphoxide(error) => write!(f, "{error}"),
+        }
+    }
+}
+
+impl From<euphoxide::Error> for Error {
+    fn from(value: euphoxide::Error) -> Self {
+        Self::Euphoxide(value)
+    }
+}
+
+type Result<T> = result::Result<T, Error>;
+
+enum Command {
+    GetConn(oneshot::Sender<ClientConnHandle>),
+    Stop,
+}
+
+#[derive(Debug)]
+pub enum ClientEvent {
+    Started {
+        id: usize,
+    },
+    Connecting {
+        id: usize,
+    },
+    Connected {
+        id: usize,
+        conn: ClientConnHandle,
+        state: State,
+    },
+    Joined {
+        id: usize,
+        conn: ClientConnHandle,
+        state: State,
+    },
+    Packet {
+        id: usize,
+        conn: ClientConnHandle,
+        state: State,
+        packet: ParsedPacket,
+    },
+    Disconnected {
+        id: usize,
+    },
+    Stopped {
+        id: usize,
+    },
+}
+
+impl ClientEvent {
+    pub fn id(&self) -> usize {
+        match self {
+            Self::Started { id } => *id,
+            Self::Connecting { id } => *id,
+            Self::Connected { id, .. } => *id,
+            Self::Joined { id, .. } => *id,
+            Self::Packet { id, .. } => *id,
+            Self::Disconnected { id } => *id,
+            Self::Stopped { id } => *id,
+        }
+    }
+}
+
+struct ClientTask {
+    id: usize,
+    config: ClientConfig,
+
+    cmd_rx: mpsc::Receiver<Command>,
+    event_tx: mpsc::Sender<ClientEvent>,
+
+    attempts: usize,
+    never_joined: bool,
+}
+
+impl ClientTask {
+    fn get_cookies(&self) -> Option<HeaderValue> {
+        self.config
+            .server
+            .cookies
+            .lock()
+            .unwrap()
+            .iter()
+            .map(|c| c.stripped().to_string())
+            .collect::<Vec<_>>()
+            .join("; ")
+            .try_into()
+            .ok()
+    }
+
+    fn set_cookies(&mut self, cookies: &[HeaderValue]) {
+        let mut guard = self.config.server.cookies.lock().unwrap();
+        for cookie in cookies {
+            if let Ok(cookie) = cookie.to_str() {
+                if let Ok(cookie) = Cookie::from_str(cookie) {
+                    guard.add(cookie);
+                }
+            }
+        }
+    }
+
+    async fn connect(&mut self) -> Result<ClientConn> {
+        let (conn, cookies) = ClientConn::connect_with_config(
+            &self.config.room,
+            self.get_cookies(),
+            &self.config.server.client,
+        )
+        .await?;
+
+        self.set_cookies(&cookies);
+
+        Ok(conn)
+    }
+
+    async fn on_joined(&mut self, conn: &ClientConn) {
+        self.never_joined = false;
+
+        let _ = self
+            .event_tx
+            .send(ClientEvent::Joined {
+                id: self.id,
+                conn: conn.handle(),
+                state: conn.state().clone(),
+            })
+            .await;
+    }
+
+    async fn on_packet(&mut self, conn: &mut ClientConn, packet: ParsedPacket) -> Result<()> {
+        let _ = self
+            .event_tx
+            .send(ClientEvent::Packet {
+                id: self.id,
+                conn: conn.handle(),
+                state: conn.state().clone(),
+                packet: packet.clone(),
+            })
+            .await;
+
+        match packet.into_data()? {
+            // Attempting to authenticate
+            Data::BounceEvent(BounceEvent {
+                auth_options: Some(auth_options),
+                ..
+            }) if auth_options.contains(&AuthOption::Passcode) => {
+                if let Some(password) = &self.config.password {
+                    conn.send(Auth {
+                        r#type: AuthOption::Passcode,
+                        passcode: Some(password.clone()),
+                    })
+                    .await?;
+                } else {
+                    return Err(Error::AuthRequired);
+                }
+            }
+
+            // Auth attempt failed :(
+            Data::AuthReply(ev) if !ev.success => return Err(Error::InvalidPassword),
+
+            // Just joined
+            Data::SnapshotEvent(ev) => {
+                if let Some(username) = &self.config.username {
+                    if ev.nick.is_none() || self.config.force_username {
+                        conn.send(Nick {
+                            name: username.clone(),
+                        })
+                        .await?;
+                    }
+                }
+
+                // Maybe we should only count this as joining if we successfully
+                // updated the nick instead of just sending a Nick command? And
+                // maybe we should ensure that we're in the State::Joined state?
+                // Both of these would probably complicate the code a lot. On
+                // the other hand, InstanceEvent::Joined::state would contain
+                // the actual nick after joining, which feels like the right
+                // thing to do™. Probably not worth the increase in code
+                // complexity though.
+
+                self.on_joined(conn).await;
+            }
+
+            _ => {}
+        }
+
+        Ok(())
+    }
+
+    async fn on_cmd(&mut self, conn: &ClientConn, cmd: Command) -> Result<()> {
+        match cmd {
+            Command::GetConn(sender) => {
+                let _ = sender.send(conn.handle());
+                Ok(())
+            }
+            Command::Stop => Err(Error::Stopped),
+        }
+    }
+
+    async fn run_once(&mut self) -> Result<()> {
+        // If we try to connect too many times without managing to join at least
+        // once, the room is probably not accessible for one reason or another
+        // and the instance should stop.
+        self.attempts += 1;
+        if self.never_joined && self.attempts > self.config.server.join_attempts {
+            return Err(Error::OutOfJoinAttempts);
+        }
+
+        let _ = self
+            .event_tx
+            .send(ClientEvent::Connecting { id: self.id })
+            .await;
+
+        let mut conn = match self.connect().await {
+            Ok(conn) => conn,
+            Err(err) => {
+                // When we fail to connect, we want to wait a bit before
+                // reconnecting in order not to spam the server. However, when
+                // we are connected successfully and then disconnect for
+                // whatever reason, we want to try to reconnect immediately. We
+                // might, for example, be disconnected from the server because
+                // we just logged in.
+                tokio::time::sleep(self.config.server.reconnect_delay).await;
+                Err(err)?
+            }
+        };
+
+        let _ = self
+            .event_tx
+            .send(ClientEvent::Connected {
+                id: self.id,
+                conn: conn.handle(),
+                state: conn.state().clone(),
+            })
+            .await;
+
+        let result = loop {
+            let received = select! {
+                r = conn.recv() => Ok(r?),
+                r = self.cmd_rx.recv() => Err(r),
+            };
+
+            match received {
+                // We received a packet
+                Ok(None) => break Ok(()), // Connection closed
+                Ok(Some(packet)) => self.on_packet(&mut conn, packet).await?,
+                // We received a command
+                Err(None) => break Err(Error::NoReferences),
+                Err(Some(cmd)) => self.on_cmd(&conn, cmd).await?,
+            };
+        };
+
+        let _ = self
+            .event_tx
+            .send(ClientEvent::Disconnected { id: self.id })
+            .await;
+
+        result
+    }
+
+    async fn run(mut self) {
+        let _ = self
+            .event_tx
+            .send(ClientEvent::Started { id: self.id })
+            .await;
+
+        loop {
+            if let Err(err) = self.run_once().await {
+                warn!("instance {:?}: {err}", self.id);
+                if err.is_fatal() {
+                    break;
+                }
+            }
+        }
+
+        let _ = self
+            .event_tx
+            .send(ClientEvent::Stopped { id: self.id })
+            .await;
+    }
+}
+
+#[derive(Clone)]
+pub struct Client {
+    id: usize,
+    cmd_tx: mpsc::Sender<Command>,
+}
+
+impl fmt::Debug for Client {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Instance")
+            .field("id", &self.id)
+            .finish_non_exhaustive()
+    }
+}
+
+impl Client {
+    pub fn new(id: usize, config: ClientConfig, event_tx: mpsc::Sender<ClientEvent>) -> Self {
+        let (cmd_tx, cmd_rx) = mpsc::channel(config.server.cmd_channel_bufsize);
+
+        let task = ClientTask {
+            id,
+            config,
+            attempts: 0,
+            never_joined: false,
+            cmd_rx,
+            event_tx,
+        };
+
+        tokio::task::spawn(task.run());
+
+        Self { id, cmd_tx }
+    }
+
+    pub fn id(&self) -> usize {
+        self.id
+    }
+
+    pub fn stopped(&self) -> bool {
+        self.cmd_tx.is_closed()
+    }
+
+    pub async fn stop(&self) {
+        let _ = self.cmd_tx.send(Command::Stop).await;
+    }
+
+    pub async fn handle(&self) -> Option<ClientConnHandle> {
+        let (tx, rx) = oneshot::channel();
+        let _ = self.cmd_tx.send(Command::GetConn(tx)).await;
+        rx.await.ok()
+    }
+}
+
+/////////////
+// Builder //
+/////////////
+
+impl ClientBuilderBase<'static> for Client {
+    type Base = ();
+}
+
+impl Client {
+    pub fn builder(room: impl ToString) -> ClientBuilder<'static, Self> {
+        Self::builder_for_server(ServerConfig::default(), room)
+    }
+
+    pub fn builder_for_server(
+        server: ServerConfig,
+        room: impl ToString,
+    ) -> ClientBuilder<'static, Self> {
+        ClientBuilder {
+            base: (),
+            config: ClientConfig::new(server, room.to_string()),
+        }
+    }
+}
+
+impl ClientBuilder<'static, Client> {
+    pub fn build(self, id: usize, event_tx: mpsc::Sender<ClientEvent>) -> Client {
+        Client::new(id, self.config, event_tx)
+    }
+}

euphoxide/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "euphoxide"
+edition = { workspace = true }
+version = { workspace = true }
+
+[dependencies]
+caseless = { workspace = true }
+futures-util = { workspace = true }
+jiff = { workspace = true }
+log = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+tokio = { workspace = true }
+tokio-tungstenite = { workspace = true }
+unicode-normalization = { workspace = true }
+
+[dev-dependencies]
+anyhow = { workspace = true }
+rustls = { workspace = true }
+tokio = { workspace = true, features = ["full"] }
+tokio-tungstenite = { workspace = true, features = ["rustls-tls-native-roots"] }
+
+[lints]
+workspace = true

euphoxide/examples/examplebot.rs

@@ -0,0 +1,90 @@
+use std::time::Duration;
+
+use euphoxide::{
+    api::{Data, Message, Nick, Send},
+    client::conn::{ClientConn, ClientConnHandle},
+};
+
+async fn set_nick(conn: &ClientConnHandle) -> anyhow::Result<()> {
+    conn.send_only(Nick {
+        name: "examplebot".to_string(),
+    })
+    .await?;
+
+    Ok(())
+}
+
+async fn send_pong(conn: &ClientConnHandle, msg: Message) -> anyhow::Result<()> {
+    conn.send_only(Send {
+        content: "Pong!".to_string(),
+        parent: Some(msg.id),
+    })
+    .await?;
+
+    Ok(())
+}
+
+async fn send_pyramid(conn: &ClientConnHandle, msg: Message) -> anyhow::Result<()> {
+    let mut parent = msg.id;
+
+    for _ in 0..3 {
+        let first = conn
+            .send(Send {
+                content: "brick".to_string(),
+                parent: Some(parent),
+            })
+            .await?;
+
+        conn.send_only(Send {
+            content: "brick".to_string(),
+            parent: Some(parent),
+        })
+        .await?;
+
+        parent = first.await?.0.id;
+        tokio::time::sleep(Duration::from_secs(1)).await;
+    }
+
+    conn.send_only(Send {
+        content: "brick".to_string(),
+        parent: Some(parent),
+    })
+    .await?;
+
+    Ok(())
+}
+
+async fn on_data(conn: ClientConnHandle, data: Data) {
+    let result = match data {
+        Data::SnapshotEvent(_) => set_nick(&conn).await,
+        Data::SendEvent(event) if event.0.content == "!ping" => send_pong(&conn, event.0).await,
+        Data::SendEvent(event) if event.0.content == "!pyramid" => {
+            send_pyramid(&conn, event.0).await
+        }
+        _ => Ok(()),
+    };
+
+    if let Err(err) = result {
+        println!("Error while responding: {err}");
+    }
+}
+
+async fn run() -> anyhow::Result<()> {
+    let (mut conn, _) = ClientConn::connect("test", None).await?;
+
+    while let Some(packet) = conn.recv().await? {
+        let data = packet.into_data()?;
+        tokio::task::spawn(on_data(conn.handle(), data));
+    }
+
+    Ok(())
+}
+
+#[tokio::main]
+async fn main() {
+    loop {
+        if let Err(err) = run().await {
+            println!("Error while running: {err}");
+        }
+    }
+}

euphoxide/src/api.rs

@@ -0,0 +1,12 @@
+//! Models the [euphoria.leet.nu API][0].
+//!
+//! [0]: https://euphoria.leet.nu/heim/api
+
+pub mod account_cmds;
+pub mod events;
+pub mod packets;
+pub mod room_cmds;
+pub mod session_cmds;
+pub mod types;
+
+pub use self::{account_cmds::*, events::*, packets::*, room_cmds::*, session_cmds::*, types::*};

euphoxide/src/api/account_cmds.rs

@@ -1,8 +1,10 @@
-//! Account commands.
+//! Models [account commands][0] and their replies.
 //!
 //! These commands enable a client to register, associate, and dissociate with
 //! an account. An account allows an identity to be shared across browsers and
 //! devices, and is a prerequisite for room management
+//!
+//! [0]: https://euphoria.leet.nu/heim/api#account-commands
 
 use serde::{Deserialize, Serialize};
 
@@ -11,6 +13,8 @@ use super::AccountId;
 /// Change the primary email address associated with the signed in account.
 ///
 /// The email address may need to be verified before the change is fully applied.
+///
+/// <https://euphoria.leet.nu/heim/api#change-email>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ChangeEmail {
     /// The new primary email address for the account.
@@ -32,6 +36,8 @@ pub struct ChangeEmailReply {
 }
 
 /// Change the name associated with the signed in account.
+///
+/// <https://euphoria.leet.nu/heim/api#change-name>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ChangeName {
     /// The name to associate with the account.
@@ -46,6 +52,8 @@ pub struct ChangeNameReply {
 }
 
 /// Change the password of the signed in account.
+///
+/// <https://euphoria.leet.nu/heim/api#change-password>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ChangePassword {
     /// The current (and soon-to-be former) password.
@@ -65,6 +73,8 @@ pub struct ChangePasswordReply {}
 /// If the login succeeds, the client should expect to receive a
 /// [`DisconnectEvent`](super::DisconnectEvent) shortly after. The next
 /// connection the client makes will be a logged in session.
+///
+/// <https://euphoria.leet.nu/heim/api#login>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Login {
     /// The namespace of a personal identifier.
@@ -98,6 +108,8 @@ pub struct LoginReply {
 /// If the logout is successful, the client should expect to receive a
 /// [`DisconnectEvent`](super::DisconnectEvent) shortly after. The next
 /// connection the client makes will be a logged out session.
+///
+/// <https://euphoria.leet.nu/heim/api#logout>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Logout {}
 
@@ -113,6 +125,8 @@ pub struct LogoutReply {}
 /// [`DisconnectEvent`](super::DisconnectEvent) shortly after. The next
 /// connection the client makes will be a logged in session using the new
 /// account.
+///
+/// <https://euphoria.leet.nu/heim/api#register-account>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct RegisterAccount {
     /// The namespace of a personal identifier.
@@ -145,6 +159,8 @@ pub struct RegisterAccountReply {
 ///
 /// An error will be returned if the account has no unverified email addresses
 /// associated with it.
+///
+/// <https://euphoria.leet.nu/heim/api#resend-verification-email>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ResendVerificationEmail {}
 
@@ -156,6 +172,8 @@ pub struct ResendVerificationEmailReply {}
 ///
 /// An email will be sent to the owner of the given personal identifier, with
 /// instructions and a confirmation code for resetting the password.
+///
+/// <https://euphoria.leet.nu/heim/api#reset-password>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ResetPassword {
     pub namespace: String,

euphoxide/src/api/events.rs

@@ -1,4 +1,6 @@
-//! Asynchronous events.
+//! Models [asynchronous events][0].
+//!
+//! [0]: https://euphoria.leet.nu/heim/api#asynchronous-events
 
 use serde::{Deserialize, Serialize};
 
@@ -8,6 +10,8 @@ use super::{
 };
 
 /// Indicates that access to a room is denied.
+///
+/// <https://euphoria.leet.nu/heim/api#bounce-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct BounceEvent {
     /// The reason why access was denied.
@@ -25,16 +29,37 @@ pub struct BounceEvent {
 ///
 /// If the disconnect reason is `authentication changed`, the client should
 /// immediately reconnect.
+///
+/// <https://euphoria.leet.nu/heim/api#disconnect-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct DisconnectEvent {
     /// The reason for disconnection.
     pub reason: String,
 }
 
+/// Indicates that a message in the room has been modified or deleted.
+///
+/// If the client offers a user interface and the indicated message is currently
+/// displayed, it should update its display accordingly.
+///
+/// The event packet includes a snapshot of the message post-edit.
+///
+/// <https://euphoria.leet.nu/heim/api#edit-message-event>
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EditMessageEvent {
+    /// The id of the edit.
+    pub edit_id: Snowflake,
+    /// The snapshot of the message post-edit.
+    #[serde(flatten)]
+    pub message: Message,
+}
+
 /// Sent by the server to the client when a session is started.
 ///
 /// It includes information about the client's authentication and associated
 /// identity.
+///
+/// <https://euphoria.leet.nu/heim/api#hello-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct HelloEvent {
     /// The id of the agent or account logged into this session.
@@ -55,11 +80,15 @@ pub struct HelloEvent {
 }
 
 /// Indicates a session just joined the room.
+///
+/// <https://euphoria.leet.nu/heim/api#join-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct JoinEvent(pub SessionView);
 
 /// Sent to all sessions of an agent when that agent is logged in (except for
 /// the session that issued the login command).
+///
+/// <https://euphoria.leet.nu/heim/api#login-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct LoginEvent {
     pub account_id: AccountId,
@@ -67,6 +96,8 @@ pub struct LoginEvent {
 
 /// Sent to all sessions of an agent when that agent is logged out (except for
 /// the session that issued the logout command).
+///
+/// <https://euphoria.leet.nu/heim/api#logout-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct LogoutEvent {}
 
@@ -75,6 +106,8 @@ pub struct LogoutEvent {}
 ///
 /// If the network event type is `partition`, then this should be treated as a
 /// [`PartEvent`] for all sessions connected to the same server id/era combo.
+///
+/// <https://euphoria.leet.nu/heim/api#network-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct NetworkEvent {
     /// The type of network event; for now, always `partition`.
@@ -86,6 +119,8 @@ pub struct NetworkEvent {
 }
 
 /// Announces a nick change by another session in the room.
+///
+/// <https://euphoria.leet.nu/heim/api#nick-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct NickEvent {
     /// The id of the session this name applies to.
@@ -98,22 +133,9 @@ pub struct NickEvent {
     pub to: String,
 }
 
-/// Indicates that a message in the room has been modified or deleted.
-///
-/// If the client offers a user interface and the indicated message is currently
-/// displayed, it should update its display accordingly.
-///
-/// The event packet includes a snapshot of the message post-edit.
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct EditMessageEvent {
-    /// The id of the edit.
-    pub edit_id: Snowflake,
-    /// The snapshot of the message post-edit.
-    #[serde(flatten)]
-    pub message: Message,
-}
-
 /// Indicates a session just disconnected from the room.
+///
+/// <https://euphoria.leet.nu/heim/api#part-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PartEvent(pub SessionView);
 
@@ -121,6 +143,8 @@ pub struct PartEvent(pub SessionView);
 ///
 /// The client should send back a ping-reply with the same value for the time
 /// field as soon as possible (or risk disconnection).
+///
+/// <https://euphoria.leet.nu/heim/api#ping-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PingEvent {
     /// A unix timestamp according to the server's clock.
@@ -131,6 +155,8 @@ pub struct PingEvent {
 }
 
 /// Informs the client that another user wants to chat with them privately.
+///
+/// <https://euphoria.leet.nu/heim/api#pm-initiate-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PmInitiateEvent {
     /// The id of the user inviting the client to chat privately.
@@ -144,12 +170,16 @@ pub struct PmInitiateEvent {
 }
 
 /// Indicates a message received by the room from another session.
+///
+/// <https://euphoria.leet.nu/heim/api#send-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SendEvent(pub Message);
 
 /// Indicates that a session has successfully joined a room.
 ///
 /// It also offers a snapshot of the room’s state and recent history.
+///
+/// <https://euphoria.leet.nu/heim/api#snapshot-event>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SnapshotEvent {
     /// The id of the agent or account logged into this session.
@@ -158,7 +188,7 @@ pub struct SnapshotEvent {
     pub session_id: SessionId,
     /// The server’s version identifier.
     pub version: String,
-    /// The list of all other sessions joined to the room (excluding this
+    /// The list of all other sessions joined to the room (excluding our
     /// session).
     pub listing: Vec<SessionView>,
     /// The most recent messages posted to the room (currently up to 100).

euphoxide/src/api/packets.rs

@@ -0,0 +1,319 @@
+//! Models the [packets][0] sent between the server and client.
+//!
+//! [0]: https://euphoria.leet.nu/heim/api#packets
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use crate::Error;
+
+use super::PacketType;
+
+/// A "raw" packet.
+///
+/// This packet closely matches the [packet representation defined in the
+/// API][0]. It can contain arbitrary data in the form of a JSON [`Value`]. It
+/// can also contain both data and an error at the same time.
+///
+/// In order to interpret this packet, you probably want to convert it to a
+/// [`ParsedPacket`] using [`ParsedPacket::from_packet`].
+///
+/// [0]: https://euphoria.leet.nu/heim/api#packets
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Packet {
+    /// Client-generated id for associating replies with commands.
+    pub id: Option<String>,
+    /// The type of the command, reply, or event.
+    pub r#type: PacketType,
+    /// The payload of the command, reply, or event.
+    pub data: Option<Value>,
+    /// This field appears in replies if a command fails.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error: Option<String>,
+    /// This field appears in replies to warn the client that it may be
+    /// flooding.
+    ///
+    /// The client should slow down its command rate.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub throttled: bool,
+    /// If throttled is true, this field describes why.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub throttled_reason: Option<String>,
+}
+
+/// Models the relationship between command and reply types.
+///
+/// This trait is useful for type-safe command-reply APIs.
+pub trait Command {
+    /// The type of reply one can expect from the server when sending this
+    /// command.
+    type Reply;
+}
+
+macro_rules! packets {
+    ( $( $mod:ident::$name:ident, )*) => {
+        /// A big enum containing most types of packet data.
+        #[derive(Debug, Clone)]
+        #[non_exhaustive]
+        pub enum Data {
+            $( $name(super::$mod::$name), )*
+            /// A valid type of packet data that this library does not model as
+            /// a struct.
+            Unimplemented(PacketType, Value),
+        }
+
+        impl Data {
+            /// Interpret a JSON [`Value`] as packet data of a specific [`PacketType`].
+            ///
+            /// This method may fail if the data is invalid.
+            pub fn from_value(ptype: PacketType, value: Value) -> serde_json::Result<Self> {
+                Ok(match ptype {
+                    $( PacketType::$name => Self::$name(serde_json::from_value(value)?), )*
+                    _ => Self::Unimplemented(ptype, value),
+                })
+            }
+
+            /// Convert the packet data into a JSON [`Value`].
+            ///
+            /// This method may fail if the data fails to serialize.
+            pub fn into_value(self) -> serde_json::Result<Value> {
+                Ok(match self {
+                    $( Self::$name(p) => serde_json::to_value(p)?, )*
+                    Self::Unimplemented(_, value) => value,
+                })
+            }
+
+            /// The [`PacketType`] of this packet data.
+            pub fn packet_type(&self) -> PacketType {
+                match self {
+                    $( Self::$name(_) => PacketType::$name, )*
+                    Self::Unimplemented(ptype, _) => *ptype,
+                }
+            }
+        }
+
+        $(
+            impl From<super::$mod::$name> for Data {
+                fn from(p: super::$mod::$name) -> Self {
+                    Self::$name(p)
+                }
+            }
+
+            impl TryFrom<Data> for super::$mod::$name{
+                type Error = ();
+
+                fn try_from(value: Data) -> Result<Self, Self::Error> {
+                    match value {
+                        Data::$name(p) => Ok(p),
+                        _ => Err(())
+                    }
+                }
+            }
+        )*
+    };
+}
+
+macro_rules! commands {
+    ( $( $cmd:ident => $rpl:ident, )* ) => {
+        $(
+            impl Command for super::$cmd {
+                type Reply = super::$rpl;
+            }
+        )*
+    };
+}
+
+packets! {
+    // Events
+    events::BounceEvent,
+    events::DisconnectEvent,
+    events::EditMessageEvent,
+    events::HelloEvent,
+    events::JoinEvent,
+    events::LoginEvent,
+    events::LogoutEvent,
+    events::NetworkEvent,
+    events::NickEvent,
+    events::PartEvent,
+    events::PingEvent,
+    events::PmInitiateEvent,
+    events::SendEvent,
+    events::SnapshotEvent,
+    // Session commands
+    session_cmds::Auth,
+    session_cmds::AuthReply,
+    session_cmds::Ping,
+    session_cmds::PingReply,
+    // Chat room commands
+    room_cmds::GetMessage,
+    room_cmds::GetMessageReply,
+    room_cmds::Log,
+    room_cmds::LogReply,
+    room_cmds::Nick,
+    room_cmds::NickReply,
+    room_cmds::PmInitiate,
+    room_cmds::PmInitiateReply,
+    room_cmds::Send,
+    room_cmds::SendReply,
+    room_cmds::Who,
+    room_cmds::WhoReply,
+    // Account commands
+    account_cmds::ChangeEmail,
+    account_cmds::ChangeEmailReply,
+    account_cmds::ChangeName,
+    account_cmds::ChangeNameReply,
+    account_cmds::ChangePassword,
+    account_cmds::ChangePasswordReply,
+    account_cmds::Login,
+    account_cmds::LoginReply,
+    account_cmds::Logout,
+    account_cmds::LogoutReply,
+    account_cmds::RegisterAccount,
+    account_cmds::RegisterAccountReply,
+    account_cmds::ResendVerificationEmail,
+    account_cmds::ResendVerificationEmailReply,
+    account_cmds::ResetPassword,
+    account_cmds::ResetPasswordReply,
+}
+
+commands! {
+    // Session commands
+    Auth => AuthReply,
+    Ping => PingReply,
+    // Chat room commands
+    GetMessage => GetMessageReply,
+    Log => LogReply,
+    Nick => NickReply,
+    PmInitiate => PmInitiateReply,
+    Send => SendReply,
+    Who => WhoReply,
+    // Account commands
+    ChangeEmail => ChangeEmailReply,
+    ChangeName => ChangeNameReply,
+    ChangePassword => ChangePasswordReply,
+    Login => LoginReply,
+    Logout => LogoutReply,
+    RegisterAccount => RegisterAccountReply,
+    ResendVerificationEmail => ResendVerificationEmailReply,
+    ResetPassword => ResetPasswordReply,
+}
+
+/// A fully parsed and interpreted packet.
+///
+/// Compared to [`Packet`], this packet's representation more closely matches
+/// the actual use of packets.
+#[derive(Debug, Clone)]
+pub struct ParsedPacket {
+    /// Client-generated id for associating replies with commands.
+    pub id: Option<String>,
+    /// The type of the command, reply, or event.
+    pub r#type: PacketType,
+    /// The payload of the command, reply, or event, or an error message if the
+    /// command failed.
+    pub content: Result<Data, String>,
+    /// A warning to the client that it may be flooding.
+    ///
+    /// The client should slow down its command rate.
+    pub throttled: Option<String>,
+}
+
+impl ParsedPacket {
+    /// Convert a [`Data`]-compatible value into a [`ParsedPacket`].
+    pub fn from_data(id: Option<String>, data: impl Into<Data>) -> Self {
+        let data = data.into();
+        Self {
+            id,
+            r#type: data.packet_type(),
+            content: Ok(data),
+            throttled: None,
+        }
+    }
+
+    pub fn into_data(self) -> crate::Result<Data> {
+        self.content.map_err(Error::Euph)
+    }
+
+    /// Convert a [`Packet`] into a [`ParsedPacket`].
+    ///
+    /// This method may fail if the packet data is invalid.
+    pub fn from_packet(packet: Packet) -> serde_json::Result<Self> {
+        let id = packet.id;
+        let r#type = packet.r#type;
+
+        let content = if let Some(error) = packet.error {
+            Err(error)
+        } else {
+            let data = packet.data.unwrap_or_default();
+            Ok(Data::from_value(r#type, data)?)
+        };
+
+        let throttled = if packet.throttled {
+            let reason = packet
+                .throttled_reason
+                .unwrap_or_else(|| "no reason given".to_string());
+            Some(reason)
+        } else {
+            None
+        };
+
+        Ok(Self {
+            id,
+            r#type,
+            content,
+            throttled,
+        })
+    }
+
+    /// Convert a [`ParsedPacket`] into a [`Packet`].
+    ///
+    /// This method may fail if the packet data fails to serialize.
+    pub fn into_packet(self) -> serde_json::Result<Packet> {
+        let id = self.id;
+        let r#type = self.r#type;
+        let throttled = self.throttled.is_some();
+        let throttled_reason = self.throttled;
+
+        Ok(match self.content {
+            Ok(data) => Packet {
+                id,
+                r#type,
+                data: Some(data.into_value()?),
+                error: None,
+                throttled,
+                throttled_reason,
+            },
+            Err(error) => Packet {
+                id,
+                r#type,
+                data: None,
+                error: Some(error),
+                throttled,
+                throttled_reason,
+            },
+        })
+    }
+}
+
+impl TryFrom<Packet> for ParsedPacket {
+    type Error = serde_json::Error;
+
+    fn try_from(value: Packet) -> Result<Self, Self::Error> {
+        Self::from_packet(value)
+    }
+}
+
+impl TryFrom<ParsedPacket> for Packet {
+    type Error = serde_json::Error;
+
+    fn try_from(value: ParsedPacket) -> Result<Self, Self::Error> {
+        value.into_packet()
+    }
+}
+
+impl TryFrom<ParsedPacket> for Data {
+    type Error = Error;
+
+    fn try_from(value: ParsedPacket) -> Result<Self, Self::Error> {
+        value.into_data()
+    }
+}

euphoxide/src/api/room_cmds.rs

@@ -1,13 +1,17 @@
-//! Chat room commands.
+//! Models [chat room commands][0] and their replies.
 //!
 //! These commands are available to the client once a session successfully joins
 //! a room.
+//!
+//! [0]: https://euphoria.leet.nu/heim/api#chat-room-commands
 
 use serde::{Deserialize, Serialize};
 
 use super::{Message, MessageId, PmId, SessionId, SessionView, UserId};
 
 /// Retrieve the full content of a single message in the room.
+///
+/// <https://euphoria.leet.nu/heim/api#get-message>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct GetMessage {
     /// The id of the message to retrieve.
@@ -23,6 +27,8 @@ pub struct GetMessageReply(pub Message);
 /// This can be used to supplement the log provided by
 /// [`SnapshotEvent`](super::SnapshotEvent) (for example, when scrolling back
 /// further in history).
+///
+/// <https://euphoria.leet.nu/heim/api#log>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Log {
     /// Maximum number of messages to return (up to 1000).
@@ -44,6 +50,8 @@ pub struct LogReply {
 ///
 /// This name applies to all messages sent during this session, until the nick
 /// command is called again.
+///
+/// <https://euphoria.leet.nu/heim/api#nick>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Nick {
     /// The requested name (maximum length 36 bytes).
@@ -68,6 +76,8 @@ pub struct NickReply {
 
 /// Constructs a virtual room for private messaging between the client and the
 /// given [`UserId`].
+///
+/// <https://euphoria.leet.nu/heim/api#pm-initiate>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PmInitiate {
     /// The id of the user to invite to chat privately.
@@ -94,6 +104,8 @@ pub struct PmInitiateReply {
 /// The caller of this command will not receive the corresponding
 /// [`SendEvent`](super::SendEvent), but will receive the same information in
 /// the [`SendReply`].
+///
+/// <https://euphoria.leet.nu/heim/api#send>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Send {
     /// The content of the message (client-defined).
@@ -109,12 +121,14 @@ pub struct Send {
 pub struct SendReply(pub Message);
 
 /// Request a list of sessions currently joined in the room.
+///
+/// <https://euphoria.leet.nu/heim/api#who>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Who {}
 
 /// Lists the sessions currently joined in the room.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct WhoReply {
-    /// A list of session views.
+    /// A list of session views (including our session).
     pub listing: Vec<SessionView>,
 }

euphoxide/src/api/session_cmds.rs

@@ -1,7 +1,9 @@
-//! Session commands.
+//! Models [session commands][0] and their replies.
 //!
 //! Session management commands are involved in the initial handshake and
 //! maintenance of a session.
+//!
+//! [0]: https://euphoria.leet.nu/heim/api#session-commands
 
 use serde::{Deserialize, Serialize};
 
@@ -11,6 +13,8 @@ use super::{AuthOption, Time};
 ///
 /// This should be sent in response to a [`BounceEvent`](super::BounceEvent) at
 /// the beginning of a session.
+///
+/// <https://euphoria.leet.nu/heim/api#auth>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Auth {
     /// The method of authentication.
@@ -32,6 +36,8 @@ pub struct AuthReply {
 ///
 /// The server will send back a [`PingReply`] with the same timestamp as soon as
 /// possible.
+///
+/// <https://euphoria.leet.nu/heim/api#ping>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Ping {
     /// An arbitrary value, intended to be a unix timestamp.

euphoxide/src/api/types.rs

@@ -1,20 +1,16 @@
-//! Field types.
+//! Models the [field types][0].
+//!
+//! [0]: https://euphoria.leet.nu/heim/api#field-types
 
-// TODO Add newtype wrappers for different kinds of IDs?
+use std::{error, fmt, num::ParseIntError, str::FromStr};
-
-// Serde's derive macros generate this warning and I can't turn it off locally,
-// so I'm turning it off for the entire module.
-#![allow(clippy::use_self)]
-
-use std::num::ParseIntError;
-use std::str::FromStr;
-use std::{error, fmt};
 
 use jiff::Timestamp;
 use serde::{de, ser, Deserialize, Serialize};
 use serde_json::Value;
 
 /// Describes an account and its preferred name.
+///
+/// <https://euphoria.leet.nu/heim/api#accountview>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AccountView {
     /// The id of the account.
@@ -24,7 +20,9 @@ pub struct AccountView {
 }
 
 /// Mode of authentication.
-#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+///
+/// <https://euphoria.leet.nu/heim/api#authoption>
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case")]
 pub enum AuthOption {
     /// Authentication with a passcode, where a key is derived from the passcode
@@ -36,6 +34,8 @@ pub enum AuthOption {
 ///
 /// It corresponds to a chat message, or a post, or any broadcasted event in a
 /// room that should appear in the log.
+///
+/// <https://euphoria.leet.nu/heim/api#message>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Message {
     /// The id of the message (unique within a room).
@@ -72,6 +72,8 @@ pub struct Message {
 /// The type of a packet.
 ///
 /// Not all of these types have their corresponding data modeled as a struct.
+///
+/// <https://euphoria.leet.nu/heim/api#packettype>
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case")]
 pub enum PacketType {
@@ -250,6 +252,8 @@ impl fmt::Display for PacketType {
 }
 
 /// Describes an account to its owner.
+///
+/// <https://euphoria.leet.nu/heim/api#personalaccountview>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PersonalAccountView {
     /// The id of the account.
@@ -261,6 +265,8 @@ pub struct PersonalAccountView {
 }
 
 /// Describes a session and its identity.
+///
+/// <https://euphoria.leet.nu/heim/api#sessionview>
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SessionView {
     /// The id of an agent or account (or bot).
@@ -290,6 +296,8 @@ pub struct SessionView {
 /// A 13-character string, usually used as aunique identifier for some type of object.
 ///
 /// It is the base-36 encoding of an unsigned, 64-bit integer.
+///
+/// <https://euphoria.leet.nu/heim/api#snowflake>
 #[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
 pub struct Snowflake(pub u64);
 
@@ -307,7 +315,7 @@ impl Snowflake {
     /// representation of message ids to suddenly use the upper parts of the
     /// range, and since message ids mostly consist of a timestamp, this
     /// approach should last until at least 2075.
-    pub const MAX: Self = Snowflake(i64::MAX as u64);
+    pub const MAX: Self = Self(i64::MAX as u64);
 }
 
 impl fmt::Display for Snowflake {
@@ -324,6 +332,7 @@ impl fmt::Display for Snowflake {
     }
 }
 
+/// An error that occurred while parsing a [`Snowflake`].
 #[derive(Debug)]
 pub enum ParseSnowflakeError {
     InvalidLength(usize),
@@ -365,7 +374,7 @@ impl FromStr for Snowflake {
             return Err(ParseSnowflakeError::InvalidLength(s.len()));
         }
         let n = u64::from_str_radix(s, 36)?;
-        Ok(Snowflake(n))
+        Ok(Self(n))
     }
 }
 
@@ -402,6 +411,8 @@ impl<'de> Deserialize<'de> for Snowflake {
 
 /// Time is specified as a signed 64-bit integer, giving the number of seconds
 /// since the Unix Epoch.
+///
+/// <https://euphoria.leet.nu/heim/api#time>
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 pub struct Time(pub i64);
 
@@ -426,6 +437,8 @@ impl Time {
 ///
 /// It is possible for this value to have no prefix and colon, and there is no
 /// fixed format for the unique value.
+///
+/// <https://euphoria.leet.nu/heim/api#userid>
 #[derive(Debug, Clone, Hash, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
 pub struct UserId(pub String);
 
@@ -435,21 +448,27 @@ impl fmt::Display for UserId {
     }
 }
 
+/// What kind of user a [`UserId`] is.
 #[derive(Debug, PartialEq, Eq)]
-pub enum SessionType {
+pub enum UserType {
     Agent,
     Account,
     Bot,
 }
 
 impl UserId {
-    pub fn session_type(&self) -> Option<SessionType> {
+    /// Retrieve the [`UserType`] of this user.
+    ///
+    /// This method can return [`None`] because user IDs used to have no
+    /// associated type. Such user IDs can still occur in old room logs, so
+    /// euphoxide supports them.
+    pub fn user_type(&self) -> Option<UserType> {
         if self.0.starts_with("agent:") {
-            Some(SessionType::Agent)
+            Some(UserType::Agent)
         } else if self.0.starts_with("account:") {
-            Some(SessionType::Account)
+            Some(UserType::Account)
         } else if self.0.starts_with("bot:") {
-            Some(SessionType::Bot)
+            Some(UserType::Bot)
         } else {
             None
         }

euphoxide/src/client.rs

@@ -0,0 +1,4 @@
+//! A connection from a client's perspective.
+
+pub mod conn;
+pub mod state;

euphoxide/src/client/conn.rs

@@ -0,0 +1,343 @@
+//! Client-specific connection with a more expressive API.
+
+use std::{future::Future, time::Duration};
+
+use log::debug;
+use tokio::{
+    select,
+    sync::{mpsc, oneshot},
+};
+use tokio_tungstenite::tungstenite::{
+    client::IntoClientRequest,
+    http::{header, HeaderValue},
+};
+
+use crate::{
+    api::{Command, Data, LoginReply, ParsedPacket},
+    conn::{Conn, ConnConfig, Side},
+    replies::{self, PendingReply, Replies},
+    Error, Result,
+};
+
+use super::state::State;
+
+enum ConnCommand {
+    SendCmd(Data, oneshot::Sender<Result<PendingReply<ParsedPacket>>>),
+    GetState(oneshot::Sender<State>),
+}
+
+/// Configuration options for a [`ClientConn`].
+#[derive(Debug, Clone)]
+pub struct ClientConnConfig {
+    /// The domain where the server is hosted.
+    pub domain: String,
+    /// Whether the client should present itself as a human to the server.
+    ///
+    /// This should only be set if the client is directly acting on behalf of a
+    /// human, similar to the web client.
+    pub human: bool,
+    /// The size of the [`mpsc::channel`] for communication between
+    /// [`ClientConn`] and [`ClientConnHandle`].
+    pub channel_bufsize: usize,
+    /// Timeout for opening a websocket connection.
+    pub connect_timeout: Duration,
+    /// Timeout for server replies when sending euphoria commands, i.e. packets
+    /// implementing [`Command`].
+    pub command_timeout: Duration,
+    /// How long to wait in-between sending pings.
+    ///
+    /// See also [`ConnConfig::ping_interval`].
+    pub ping_interval: Duration,
+}
+
+impl Default for ClientConnConfig {
+    fn default() -> Self {
+        Self {
+            domain: "euphoria.leet.nu".to_string(),
+            human: false,
+            channel_bufsize: 10,
+            connect_timeout: Duration::from_secs(10),
+            command_timeout: Duration::from_secs(30),
+            ping_interval: Duration::from_secs(30),
+        }
+    }
+}
+
+/// A client connection to an euphoria server.
+///
+/// This struct is a wrapper around [`Conn`] with a more client-centric API. It
+/// tracks the connection state, including room information sent by the server.
+/// It also provides [`ClientConnHandle`], which can be used to asynchronously
+/// send commands and await their replies.
+pub struct ClientConn {
+    rx: mpsc::Receiver<ConnCommand>,
+    tx: mpsc::Sender<ConnCommand>,
+
+    conn: Conn,
+    state: State,
+
+    last_id: usize,
+    replies: Replies<String, ParsedPacket>,
+}
+
+impl ClientConn {
+    /// Retrieve the current [`State`] of the connection.
+    pub fn state(&self) -> &State {
+        &self.state
+    }
+
+    /// Create a new handle for this connection.
+    pub fn handle(&self) -> ClientConnHandle {
+        ClientConnHandle {
+            tx: self.tx.clone(),
+        }
+    }
+
+    /// Start closing the connection.
+    ///
+    /// To finish closing the connection gracefully, continue calling
+    /// [`Self::recv`] until it returns [`None`].
+    pub async fn close(&mut self) -> Result<()> {
+        self.conn.close().await
+    }
+
+    /// Receive a [`ParsedPacket`] over the connection.
+    ///
+    /// This method also maintains the connection by listening and responding to
+    /// pings as well as managing [`ClientConnHandle`]s. Thus, it must be called
+    /// regularly.
+    ///
+    /// Returns [`None`] if the connection is closed.
+    pub async fn recv(&mut self) -> Result<Option<ParsedPacket>> {
+        loop {
+            self.replies.purge();
+
+            // There's always at least one tx end (self.tx), so self.rx.recv()
+            // should never return None.
+            let packet = select! {
+                packet = self.conn.recv() => packet?,
+                Some(cmd) = self.rx.recv() => {
+                    self.on_cmd(cmd).await;
+                    continue;
+                },
+            };
+
+            if let Some(packet) = &packet {
+                self.on_packet(packet).await?;
+            }
+
+            break Ok(packet);
+        }
+    }
+
+    /// Send a packet over the connection.
+    ///
+    /// A packet id is automatically generated and returned. When the server
+    /// replies to the packet, it will use this id as its [`ParsedPacket::id`].
+    pub async fn send(&mut self, data: impl Into<Data>) -> Result<String> {
+        // Overkill of universe-heat-death-like proportions
+        self.last_id = self.last_id.wrapping_add(1);
+        let id = self.last_id.to_string();
+
+        self.conn
+            .send(ParsedPacket::from_data(Some(id.clone()), data.into()))
+            .await?;
+
+        Ok(id)
+    }
+
+    async fn on_packet(&mut self, packet: &ParsedPacket) -> Result<()> {
+        if let Ok(data) = &packet.content {
+            self.state.on_data(data);
+
+            // The euphoria server doesn't always disconnect the client when it
+            // would make sense to do so or when the API specifies it should.
+            // This ensures we always disconnect when it makes sense to do so.
+            if matches!(
+                data,
+                Data::DisconnectEvent(_)
+                    | Data::LoginEvent(_)
+                    | Data::LogoutEvent(_)
+                    | Data::LoginReply(LoginReply { success: true, .. })
+                    | Data::LogoutReply(_)
+            ) {
+                self.close().await?;
+            }
+        }
+
+        if let Some(id) = &packet.id {
+            let id = id.clone();
+            self.replies.complete(&id, packet.clone());
+        }
+
+        Ok(())
+    }
+
+    async fn on_cmd(&mut self, cmd: ConnCommand) {
+        match cmd {
+            ConnCommand::SendCmd(data, sender) => {
+                let result = self.send(data).await.map(|id| self.replies.wait_for(id));
+                let _ = sender.send(result);
+            }
+            ConnCommand::GetState(sender) => {
+                let _ = sender.send(self.state.clone());
+            }
+        }
+    }
+
+    /// Connect to a room.
+    ///
+    /// See [`Self::connect_with_config`] for more details.
+    pub async fn connect(
+        room: &str,
+        cookies: Option<HeaderValue>,
+    ) -> Result<(Self, Vec<HeaderValue>)> {
+        Self::connect_with_config(room, cookies, &ClientConnConfig::default()).await
+    }
+
+    /// Connect to a room with a specific configuration.
+    ///
+    /// Cookies to be sent to the server can be specified as a [`HeaderValue`]
+    /// in the format of a [`Cookie` request header][0]. If the connection
+    /// attempt was successful, cookies set by the server will be returned
+    /// alongside the connection itself as one [`HeaderValue`] per [`Set-Cookie`
+    /// response header][1].
+    ///
+    /// The tasks of cookie parsing and storage are not handled by this library.
+    ///
+    /// [0]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cookie
+    /// [1]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie
+    pub async fn connect_with_config(
+        room: &str,
+        cookies: Option<HeaderValue>,
+        config: &ClientConnConfig,
+    ) -> Result<(Self, Vec<HeaderValue>)> {
+        // Prepare URL
+        let human = if config.human { "?h=1" } else { "" };
+        let uri = format!("wss://{}/room/{room}/ws{human}", config.domain);
+        debug!("Connecting to {uri} with cookies: {cookies:?}");
+
+        // Prepare request
+        let mut request = uri.into_client_request().expect("valid request");
+        if let Some(cookies) = cookies {
+            request.headers_mut().append(header::COOKIE, cookies);
+        }
+
+        // Connect to server
+        let (ws, response) = tokio::time::timeout(
+            config.connect_timeout,
+            tokio_tungstenite::connect_async(request),
+        )
+        .await
+        .map_err(|_| Error::ConnectionTimeout)??;
+
+        // Extract response cookies
+        let (mut parts, _) = response.into_parts();
+        let cookies_set = match parts.headers.entry(header::SET_COOKIE) {
+            header::Entry::Occupied(entry) => entry.remove_entry_mult().1.collect(),
+            header::Entry::Vacant(_) => vec![],
+        };
+        debug!("Received cookies {cookies_set:?}");
+
+        // Prepare EuphConn
+        let conn_config = ConnConfig {
+            ping_interval: config.ping_interval,
+        };
+        let conn = Conn::wrap_with_config(ws, Side::Client, conn_config);
+
+        // Prepare client
+        let (tx, rx) = mpsc::channel(config.channel_bufsize);
+        let client = Self {
+            rx,
+            tx,
+            conn,
+            state: State::new(),
+            last_id: 0,
+            replies: Replies::new(config.command_timeout),
+        };
+
+        Ok((client, cookies_set))
+    }
+}
+
+/// Asynchronous access to a [`ClientConn`].
+///
+/// Handle methods are only processed while [`ClientConn::recv`] is being
+/// called. They may return before they were processed by the associated
+/// [`ClientConn`], or they may block until processed. Methods are processed in
+/// the order they are called.
+///
+/// The handle is cheap to clone.
+#[derive(Debug, Clone)]
+pub struct ClientConnHandle {
+    tx: mpsc::Sender<ConnCommand>,
+}
+
+impl ClientConnHandle {
+    /// Send a command to the server.
+    ///
+    /// When awaited, returns either an error if something went wrong while
+    /// sending the command, or a second future with the server's reply (the
+    /// *reply future*).
+    ///
+    /// When awaited, the *reply future* returns either an error if something
+    /// was wrong with the reply, or the data returned by the server. The *reply
+    /// future* can be safely ignored and doesn't have to be awaited.
+    pub async fn send<C>(&self, cmd: C) -> Result<impl Future<Output = Result<C::Reply>>>
+    where
+        C: Command + Into<Data>,
+        C::Reply: TryFrom<Data>,
+    {
+        let (tx, rx) = oneshot::channel();
+
+        self.tx
+            .send(ConnCommand::SendCmd(cmd.into(), tx))
+            .await
+            .map_err(|_| Error::ConnectionClosed)?;
+
+        Ok(async {
+            let data = rx
+                .await
+                .map_err(|_| Error::ConnectionClosed)??
+                .get()
+                .await
+                .map_err(|err| match err {
+                    replies::Error::TimedOut => Error::CommandTimeout,
+                    replies::Error::Canceled => Error::ConnectionClosed,
+                })?
+                .content
+                .map_err(Error::Euph)?;
+
+            let ptype = data.packet_type();
+            data.try_into()
+                .map_err(|_| Error::ReceivedUnexpectedPacket(ptype))
+        })
+    }
+
+    /// Send a command to the server without waiting for a reply.
+    ///
+    /// This method is equivalent to calling and awaiting [`Self::send`] but
+    /// ignoring the *reply future*. The reason it exists is that clippy gets
+    /// really annoying when you try to ignore a future (which is usually the
+    /// right call).
+    pub async fn send_only<C>(&self, cmd: C) -> Result<()>
+    where
+        C: Command + Into<Data>,
+        C::Reply: TryFrom<Data>,
+    {
+        let _ignore = self.send(cmd).await?;
+        Ok(())
+    }
+
+    /// Retrieve the current connection [`State`].
+    pub async fn state(&self) -> Result<State> {
+        let (tx, rx) = oneshot::channel();
+
+        self.tx
+            .send(ConnCommand::GetState(tx))
+            .await
+            .map_err(|_| Error::ConnectionClosed)?;
+
+        rx.await.map_err(|_| Error::ConnectionClosed)
+    }
+}

euphoxide/src/client/state.rs

@@ -0,0 +1,307 @@
+//! Models the client's connection state.
+
+use std::collections::HashMap;
+
+use jiff::Timestamp;
+use log::debug;
+
+use crate::api::{
+    BounceEvent, Data, HelloEvent, NickEvent, PersonalAccountView, SessionId, SessionView,
+    SnapshotEvent, UserId,
+};
+
+/// Information about a session in the room.
+///
+/// For quite a while before finally going down altogether, the euphoria.io
+/// instance had an unreliable nick list: Listings returned by the server were
+/// usually incomplete. Because of this, the bot library uses any observable
+/// action by a session (including nick changes) to update the listing. Since
+/// nick events don't include full session info though, the [`SessionInfo`] enum
+/// can contain partial information.
+///
+/// This level of paranioa probably isn't required any more now that the only
+/// euphoria instance is working correctly. However, the code already works and
+/// users who don't want to worry about it can just ignore partial session
+/// infos.
+#[derive(Debug, Clone)]
+pub enum SessionInfo {
+    Full(SessionView),
+    Partial(NickEvent),
+}
+
+impl SessionInfo {
+    /// Retrieve the user id of the session.
+    pub fn id(&self) -> &UserId {
+        match self {
+            Self::Full(sess) => &sess.id,
+            Self::Partial(nick) => &nick.id,
+        }
+    }
+
+    /// Retrieve the session id of the session.
+    pub fn session_id(&self) -> &SessionId {
+        match self {
+            Self::Full(sess) => &sess.session_id,
+            Self::Partial(nick) => &nick.session_id,
+        }
+    }
+
+    /// Retrieve the user name of the session.
+    pub fn name(&self) -> &str {
+        match self {
+            Self::Full(sess) => &sess.name,
+            Self::Partial(nick) => &nick.to,
+        }
+    }
+}
+
+impl From<SessionView> for SessionInfo {
+    fn from(value: SessionView) -> Self {
+        Self::Full(value)
+    }
+}
+
+impl From<NickEvent> for SessionInfo {
+    fn from(value: NickEvent) -> Self {
+        Self::Partial(value)
+    }
+}
+
+/// The state of the connection before the client has joined the room.
+///
+/// Depending on the room, the client may need to authenticate or log in in
+/// order to join.
+#[derive(Debug, Clone)]
+pub struct Joining {
+    /// Since when the connection has been in this state.
+    pub since: Timestamp,
+    /// A [`HelloEvent`], if one has been received.
+    ///
+    /// Contains information about the client's own session.
+    pub hello: Option<HelloEvent>,
+    /// A [`SnapshotEvent`], if one has been received.
+    pub snapshot: Option<SnapshotEvent>,
+    /// A [`BounceEvent`], if one has been received.
+    pub bounce: Option<BounceEvent>,
+}
+
+impl Joining {
+    fn new() -> Self {
+        Self {
+            since: Timestamp::now(),
+            hello: None,
+            snapshot: None,
+            bounce: None,
+        }
+    }
+
+    fn on_data(&mut self, data: &Data) {
+        match data {
+            Data::BounceEvent(p) => self.bounce = Some(p.clone()),
+            Data::HelloEvent(p) => self.hello = Some(p.clone()),
+            Data::SnapshotEvent(p) => self.snapshot = Some(p.clone()),
+            _ => {}
+        }
+    }
+
+    fn to_joined(&self) -> Option<Joined> {
+        let hello = self.hello.as_ref()?;
+        let snapshot = self.snapshot.as_ref()?;
+
+        let mut session = hello.session.clone();
+
+        if let Some(nick) = &snapshot.nick {
+            session.name = nick.clone();
+        }
+
+        let listing = snapshot
+            .listing
+            .iter()
+            .cloned()
+            .map(|s| (s.session_id.clone(), SessionInfo::Full(s)))
+            .collect::<HashMap<_, _>>();
+
+        Some(Joined {
+            since: Timestamp::now(),
+            session,
+            account: hello.account.clone(),
+            listing,
+        })
+    }
+}
+
+/// The state of the connection after the client has successfully joined the
+/// room.
+///
+/// The client may need to set a nick in order to be able to send messages.
+/// However, it can access the room history without nick.
+#[derive(Debug, Clone)]
+pub struct Joined {
+    /// Since when the connection has been in this state.
+    pub since: Timestamp,
+    /// The client's own session.
+    pub session: SessionView,
+    /// Account information, if the client is logged in.
+    pub account: Option<PersonalAccountView>,
+    /// All sessions currently connected to the room (except the client's own
+    /// session).
+    pub listing: HashMap<SessionId, SessionInfo>,
+}
+
+impl Joined {
+    fn on_data(&mut self, data: &Data) {
+        match data {
+            Data::JoinEvent(p) => {
+                debug!("Updating listing after join-event");
+                self.listing
+                    .insert(p.0.session_id.clone(), SessionInfo::Full(p.0.clone()));
+            }
+            Data::PartEvent(p) => {
+                debug!("Updating listing after part-event");
+                self.listing.remove(&p.0.session_id);
+            }
+            Data::NetworkEvent(p) => {
+                if p.r#type == "partition" {
+                    debug!("Updating listing after network-event with type partition");
+                    self.listing.retain(|_, s| match s {
+                        SessionInfo::Full(s) => {
+                            s.server_id != p.server_id && s.server_era != p.server_era
+                        }
+                        // We can't know if the session was disconnected by the
+                        // partition or not, so we're erring on the side of
+                        // caution and assuming they were kicked. If we're
+                        // wrong, we'll re-add the session as soon as it
+                        // performs another visible action.
+                        //
+                        // If we always kept such sessions, we might keep
+                        // disconnected ones indefinitely, thereby keeping them
+                        // from moving on, instead forever tethering them to the
+                        // digital realm.
+                        SessionInfo::Partial(_) => false,
+                    });
+                }
+            }
+            Data::SendEvent(p) => {
+                debug!("Updating listing after send-event");
+                self.listing.insert(
+                    p.0.sender.session_id.clone(),
+                    SessionInfo::Full(p.0.sender.clone()),
+                );
+            }
+            Data::NickEvent(p) => {
+                debug!("Updating listing after nick-event");
+                self.listing
+                    .entry(p.session_id.clone())
+                    .and_modify(|s| match s {
+                        SessionInfo::Full(session) => session.name = p.to.clone(),
+                        SessionInfo::Partial(_) => *s = SessionInfo::Partial(p.clone()),
+                    })
+                    .or_insert_with(|| SessionInfo::Partial(p.clone()));
+            }
+            Data::NickReply(p) => {
+                debug!("Updating own session after nick-reply");
+                assert_eq!(self.session.id, p.id);
+                self.session.name = p.to.clone();
+            }
+            Data::WhoReply(p) => {
+                debug!("Updating listing after who-reply");
+                self.listing.clear();
+                for session in p.listing.clone() {
+                    if session.session_id == self.session.session_id {
+                        self.session = session;
+                    } else {
+                        self.listing
+                            .insert(session.session_id.clone(), session.into());
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+}
+
+/// The state of a connection to the server, from a client's perspective.
+#[derive(Debug, Clone)]
+#[allow(clippy::large_enum_variant)]
+pub enum State {
+    /// The client has not joined the room yet.
+    Joining(Joining),
+    /// The client has successfully joined the room.
+    Joined(Joined),
+}
+
+impl State {
+    /// Create a new state for a fresh connection.
+    ///
+    /// Assumes that no packets have been received yet. See also
+    /// [`Self::on_data`].
+    pub fn new() -> Self {
+        Joining::new().into()
+    }
+
+    /// If the state consists of a [`Joining`], return a reference to it.
+    pub fn as_joining(&self) -> Option<&Joining> {
+        match self {
+            Self::Joining(joining) => Some(joining),
+            Self::Joined(_) => None,
+        }
+    }
+
+    /// If the state consists of a [`Joined`], return a reference to it.
+    pub fn as_joined(&self) -> Option<&Joined> {
+        match self {
+            Self::Joining(_) => None,
+            Self::Joined(joined) => Some(joined),
+        }
+    }
+
+    /// If the state consists of a [`Joining`], return it.
+    pub fn into_joining(self) -> Option<Joining> {
+        match self {
+            Self::Joining(joining) => Some(joining),
+            Self::Joined(_) => None,
+        }
+    }
+
+    /// If the state consists of a [`Joined`], return it.
+    pub fn into_joined(self) -> Option<Joined> {
+        match self {
+            Self::Joining(_) => None,
+            Self::Joined(joined) => Some(joined),
+        }
+    }
+
+    /// Update the state with a packet received from the server.
+    ///
+    /// This method should be called whenever any packet is received from the
+    /// server. Skipping packets may cause the state to become inconsistent.
+    pub fn on_data(&mut self, data: &Data) {
+        match self {
+            Self::Joining(joining) => {
+                joining.on_data(data);
+                if let Some(joined) = joining.to_joined() {
+                    *self = joined.into();
+                }
+            }
+            Self::Joined(joined) => joined.on_data(data),
+        }
+    }
+}
+
+impl Default for State {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl From<Joining> for State {
+    fn from(value: Joining) -> Self {
+        Self::Joining(value)
+    }
+}
+
+impl From<Joined> for State {
+    fn from(value: Joined) -> Self {
+        Self::Joined(value)
+    }
+}

euphoxide/src/conn.rs

@@ -0,0 +1,312 @@
+//! Basic connection between client and server.
+
+use std::{fmt, time::Duration};
+
+use futures_util::{SinkExt, StreamExt};
+use jiff::Timestamp;
+use log::debug;
+use tokio::{
+    net::TcpStream,
+    select,
+    time::{self, Instant},
+};
+use tokio_tungstenite::{
+    tungstenite::{client::IntoClientRequest, handshake::client::Response, Message},
+    MaybeTlsStream, WebSocketStream,
+};
+
+use crate::{
+    api::{Data, Packet, PacketType, ParsedPacket, Ping, PingEvent, PingReply, Time},
+    Error, Result,
+};
+
+/// Which side of the connection we're on.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Side {
+    /// We're the client and are talking to a server.
+    Client,
+    /// We're the server and are talking to a client.
+    Server,
+}
+
+/// Configuration options for a [`Conn`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ConnConfig {
+    /// How long to wait in-between sending pings.
+    ///
+    /// This includes both websocket and euphoria pings ([`Ping`] or
+    /// [`PingEvent`]).
+    pub ping_interval: Duration,
+}
+
+impl Default for ConnConfig {
+    fn default() -> Self {
+        Self {
+            ping_interval: Duration::from_secs(30),
+        }
+    }
+}
+
+/// A basic connection between a client and a server.
+///
+/// The connection can be used both from a server's and from a client's
+/// perspective. In both cases, it performs regular websocket *and* euphoria
+/// pings and terminates the connection if the other side does not reply before
+/// the next ping is sent.
+pub struct Conn {
+    ws: WebSocketStream<MaybeTlsStream<TcpStream>>,
+    side: Side,
+    config: ConnConfig,
+
+    // The websocket server may send a pong frame with arbitrary payload
+    // unprompted at any time (see RFC 6455 5.5.3). Because of this, we can't
+    // just remember the last pong payload.
+    last_ping: Instant,
+    last_ws_ping_payload: Option<Vec<u8>>,
+    last_ws_ping_replied_to: bool,
+    last_euph_ping_payload: Option<Time>,
+    last_euph_ping_replied_to: bool,
+}
+
+impl Conn {
+    /// The connection's side.
+    pub fn side(&self) -> Side {
+        self.side
+    }
+
+    /// The connection's config.
+    pub fn config(&self) -> &ConnConfig {
+        &self.config
+    }
+
+    /// Connect to a given URL.
+    pub async fn connect<R>(request: R) -> Result<(Self, Response)>
+    where
+        R: IntoClientRequest + Unpin,
+    {
+        Self::connect_with_config(request, ConnConfig::default()).await
+    }
+
+    /// Connect to a given URL with a specific configuration.
+    pub async fn connect_with_config<R>(request: R, config: ConnConfig) -> Result<(Self, Response)>
+    where
+        R: IntoClientRequest + Unpin,
+    {
+        let (ws, response) = tokio_tungstenite::connect_async(request).await?;
+        let conn = Self::wrap_with_config(ws, Side::Client, config);
+        Ok((conn, response))
+    }
+
+    /// Wrap an existing websocket stream.
+    pub fn wrap(ws: WebSocketStream<MaybeTlsStream<TcpStream>>, side: Side) -> Self {
+        Self::wrap_with_config(ws, side, ConnConfig::default())
+    }
+
+    /// Wrap an existing websocket stream with a specific configuration.
+    pub fn wrap_with_config(
+        ws: WebSocketStream<MaybeTlsStream<TcpStream>>,
+        side: Side,
+        config: ConnConfig,
+    ) -> Self {
+        Self {
+            ws,
+            side,
+            config,
+            last_ping: Instant::now(),
+            last_ws_ping_payload: None,
+            last_ws_ping_replied_to: false,
+            last_euph_ping_payload: None,
+            last_euph_ping_replied_to: false,
+        }
+    }
+
+    /// Start closing the connection.
+    ///
+    /// To finish closing the connection gracefully, continue calling
+    /// [`Self::recv_raw`] or [`Self::recv`] until they return [`None`].
+    pub async fn close(&mut self) -> Result<()> {
+        self.ws.close(None).await?;
+        Ok(())
+    }
+
+    /// Send a [`Packet`] over the connection.
+    pub async fn send_raw(&mut self, packet: &Packet) -> Result<()> {
+        debug!(target: "euphoxide::conn::full", "Sending {packet:?}");
+        let text = serde_json::to_string(&packet).map_err(Error::MalformedPacket)?;
+        self.ws.send(Message::Text(text)).await?;
+        Ok(())
+    }
+
+    /// Send a [`ParsedPacket`] over the connection.
+    pub async fn send(&mut self, packet: ParsedPacket) -> Result<()> {
+        let packet = packet.into_packet().map_err(Error::MalformedPacket)?;
+        self.send_raw(&packet).await
+    }
+
+    /// Receive a [`Packet`] over the connection.
+    ///
+    /// This method also listens for and sends pings in regular intervals as
+    /// specified by [`ConnConfig::ping_interval`]. Thus, this method must be
+    /// called regularly.
+    ///
+    /// Returns [`None`] if the connection is closed.
+    pub async fn recv_raw(&mut self) -> Result<Option<Packet>> {
+        loop {
+            let next_ping = self.last_ping + self.config.ping_interval;
+
+            let result = select! {
+                _ = time::sleep_until(next_ping) => None,
+                r = self.ws.next() => Some(r),
+            };
+
+            match result {
+                None => self.check_and_send_pings().await?,
+                Some(None) => break Ok(None),
+                Some(Some(result)) => {
+                    if let Some(packet) = self.on_message(result?).await? {
+                        debug!(target: "euphoxide::conn::full", "Received {packet:?}");
+                        break Ok(Some(packet));
+                    }
+                }
+            }
+        }
+    }
+
+    /// Receive a [`ParsedPacket`] over the connection.
+    ///
+    /// For more details, see [`Self::recv_raw`].
+    pub async fn recv(&mut self) -> Result<Option<ParsedPacket>> {
+        let Some(packet) = self.recv_raw().await? else {
+            return Ok(None);
+        };
+
+        let packet = ParsedPacket::from_packet(packet).map_err(Error::ReceivedMalformedPacket)?;
+        Ok(Some(packet))
+    }
+
+    async fn check_and_send_pings(&mut self) -> Result<()> {
+        debug!("Checking ping replies and sending new pings");
+
+        // Check previous ws ping
+        if self.last_ws_ping_payload.is_some() && !self.last_ws_ping_replied_to {
+            debug!("No response to websocket ping, disconnecting");
+            self.close().await?;
+            return Err(Error::PingTimeout);
+        }
+
+        // Check previous euph ping
+        if self.last_euph_ping_payload.is_some() && !self.last_euph_ping_replied_to {
+            debug!("No response to euph ping, disconnecting");
+            self.close().await?;
+            return Err(Error::PingTimeout);
+        }
+
+        let now = Timestamp::now();
+
+        // Send new ws ping
+        let ws_payload = now.as_millisecond().to_be_bytes().to_vec();
+        self.last_ws_ping_payload = Some(ws_payload.clone());
+        self.last_ws_ping_replied_to = false;
+        self.ws.send(Message::Ping(ws_payload)).await?;
+
+        // Send new euph ping
+        let euph_payload = Time::from_timestamp(now);
+        self.last_euph_ping_payload = Some(euph_payload);
+        self.last_euph_ping_replied_to = false;
+        let data: Data = match self.side {
+            Side::Client => Ping { time: euph_payload }.into(),
+            Side::Server => PingEvent {
+                time: euph_payload,
+                next: Time::from_timestamp(now + self.config.ping_interval),
+            }
+            .into(),
+        };
+        self.send(ParsedPacket::from_data(None, data)).await?;
+
+        self.last_ping = Instant::now();
+
+        Ok(())
+    }
+
+    async fn on_message(&mut self, message: Message) -> Result<Option<Packet>> {
+        match message {
+            Message::Pong(payload) => {
+                if self.last_ws_ping_payload == Some(payload) {
+                    debug!("Received valid ws pong");
+                    self.last_ws_ping_replied_to = true
+                }
+                Ok(None)
+            }
+
+            Message::Text(text) => {
+                let packet = serde_json::from_str(&text).map_err(Error::ReceivedMalformedPacket)?;
+                self.on_packet(&packet).await?;
+                Ok(Some(packet))
+            }
+
+            Message::Binary(_) => {
+                self.close().await?;
+                Err(Error::ReceivedBinaryMessage)
+            }
+
+            Message::Close(_) => Err(Error::ConnectionClosed),
+
+            // We don't have to manually respond to pings.
+            _ => Ok(None),
+        }
+    }
+
+    async fn on_packet(&mut self, packet: &Packet) -> Result<()> {
+        match packet.r#type {
+            PacketType::PingEvent => self.on_ping_event(packet).await,
+            PacketType::Ping => self.on_ping(packet).await,
+            PacketType::PingReply => self.on_ping_reply(packet),
+            _ => Ok(()),
+        }
+    }
+
+    async fn on_ping_event(&mut self, packet: &Packet) -> Result<()> {
+        debug!("Responding to ping-event");
+        let data = packet.data.clone().unwrap_or_default();
+        let data =
+            serde_json::from_value::<PingEvent>(data).map_err(Error::ReceivedMalformedPacket)?;
+        let time = Some(data.time);
+        let reply = ParsedPacket::from_data(packet.id.clone(), PingReply { time });
+        self.send(reply).await?;
+        Ok(())
+    }
+
+    async fn on_ping(&mut self, packet: &Packet) -> Result<()> {
+        debug!("Responding to ping");
+        let data = packet.data.clone().unwrap_or_default();
+        let data = serde_json::from_value::<Ping>(data).map_err(Error::ReceivedMalformedPacket)?;
+        let time = Some(data.time);
+        let reply = ParsedPacket::from_data(packet.id.clone(), PingReply { time });
+        self.send(reply).await?;
+        Ok(())
+    }
+
+    fn on_ping_reply(&mut self, packet: &Packet) -> Result<()> {
+        let data = packet.data.clone().unwrap_or_default();
+        let data =
+            serde_json::from_value::<PingReply>(data).map_err(Error::ReceivedMalformedPacket)?;
+
+        let Some(time) = data.time else { return Ok(()) };
+
+        if self.last_euph_ping_payload == Some(time) {
+            debug!("Received valid euph pong");
+            self.last_euph_ping_replied_to = true;
+        }
+
+        Ok(())
+    }
+}
+
+impl fmt::Debug for Conn {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Conn")
+            .field("side", &self.side)
+            .field("config", &self.config)
+            .finish_non_exhaustive()
+    }
+}

euphoxide/src/emoji.rs

@@ -0,0 +1,312 @@
+use std::{borrow::Cow, collections::HashMap, ops::Range};
+
+/// Emoji list from euphoria.leet.nu, obtainable via shell command:
+///
+/// ```bash
+/// curl 'https://euphoria.leet.nu/static/emoji.json' \
+///   | jq 'to_entries | sort_by(.key) | from_entries' \
+///   > emoji.json
+/// ```
+const EMOJI_JSON: &str = include_str!("emoji.json");
+
+/// A database of emoji names and their unicode representation.
+///
+/// Some emoji are rendered with custom icons in the web client and don't
+/// correspond to an emoji in the unicode standard. These emoji don't have an
+/// unicode representation.
+pub struct Emoji(HashMap<String, Option<String>>);
+
+fn parse_hex_to_char(hex: &str) -> Option<char> {
+    u32::from_str_radix(hex, 16).ok()?.try_into().ok()
+}
+
+fn parse_code_points(code_points: &str) -> Option<String> {
+    code_points
+        .split('-')
+        .map(parse_hex_to_char)
+        .collect::<Option<String>>()
+}
+
+impl Emoji {
+    /// Load the list of emoji compiled into the library.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use euphoxide::Emoji;
+    /// let emoji = Emoji::load();
+    ///
+    /// assert_eq!(emoji.get("robot"), Some(Some("🤖")));
+    /// ```
+    pub fn load() -> Self {
+        Self::load_from_json(EMOJI_JSON).unwrap()
+    }
+
+    /// Load a list of emoji from a string containing a JSON object.
+    ///
+    /// The object keys are the emoji names (without colons `:`). The object
+    /// values are the emoji code points encoded as hexadecimal numbers and
+    /// separated by a dash `-` (e.g. `"34-fe0f-20e3"`). Emoji whose values
+    /// don't match this schema are interpreted as emoji without unicode
+    /// representation.
+    ///
+    /// This is the format used by the [euphoria.leet.nu emoji listing][0].
+    ///
+    /// [0]: https://euphoria.leet.nu/static/emoji.json
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use euphoxide::Emoji;
+    ///
+    /// const EMOJI: &str = r#" {"Roboter": "1f916", "foo": "~bar"} "#;
+    /// let emoji = Emoji::load_from_json(EMOJI).unwrap();
+    ///
+    /// assert_eq!(emoji.get("Roboter"), Some(Some("🤖")));
+    /// assert_eq!(emoji.get("foo"), Some(None));
+    /// assert_eq!(emoji.get("robot"), None);
+    /// ```
+    pub fn load_from_json(json: &str) -> Option<Self> {
+        let map = serde_json::from_str::<HashMap<String, String>>(json)
+            .ok()?
+            .into_iter()
+            .map(|(k, v)| (k, parse_code_points(&v)))
+            .collect::<HashMap<_, _>>();
+
+        Some(Self(map))
+    }
+
+    /// Retrieve an emoji's unicode representation by name.
+    ///
+    /// Returns `None` if the emoji could not be found. Returns `Some(None)` if
+    /// the emoji could be found but does not have a unicode representation.
+    ///
+    /// The name is not colon-delimited.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use euphoxide::Emoji;
+    /// let emoji = Emoji::load();
+    ///
+    /// assert_eq!(emoji.get("robot"), Some(Some("🤖")));
+    /// assert_eq!(emoji.get("+1"), Some(None));
+    /// assert_eq!(emoji.get("foobar"), None);
+    ///
+    /// assert_eq!(emoji.get(":robot:"), None);
+    /// ```
+    pub fn get(&self, name: &str) -> Option<Option<&str>> {
+        match self.0.get(name) {
+            Some(Some(replace)) => Some(Some(replace)),
+            Some(None) => Some(None),
+            None => None,
+        }
+    }
+
+    /// All known emoji and their unicode representation.
+    ///
+    /// The emoji are not in any particular order.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use euphoxide::Emoji;
+    /// let emoji = Emoji::load();
+    ///
+    /// // List all emoji that don't have a unicode representation
+    /// let custom_emoji = emoji
+    ///     .all()
+    ///     .filter(|(_, unicode)| unicode.is_none())
+    ///     .map(|(name, _)| name)
+    ///     .collect::<Vec<_>>();
+    ///
+    /// assert!(!custom_emoji.is_empty());
+    /// ```
+    pub fn all(&self) -> impl Iterator<Item = (&str, Option<&str>)> {
+        self.0
+            .iter()
+            .map(|(k, v)| (k as &str, v.as_ref().map(|v| v as &str)))
+    }
+
+    /// Find all colon-delimited emoji in a string.
+    ///
+    /// Returns a list of emoji locations (colons are included in the range) and
+    /// corresponding unicode representations.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use euphoxide::Emoji;
+    /// let emoji = Emoji::load();
+    ///
+    /// let found = emoji.find("Hello :globe_with_meridians:!");
+    /// assert_eq!(found, vec![(6..28, Some("🌐"))]);
+    ///
+    /// // Ignores nonexistent emoji
+    /// let found = emoji.find("Hello :sparkly_wizard:!");
+    /// assert!(found.is_empty());
+    /// ```
+    pub fn find(&self, text: &str) -> Vec<(Range<usize>, Option<&str>)> {
+        let mut result = vec![];
+
+        let mut prev_colon_idx = None;
+        for (colon_idx, _) in text.match_indices(':') {
+            if let Some(prev_idx) = prev_colon_idx {
+                let name = &text[prev_idx + 1..colon_idx];
+                if let Some(replace) = self.get(name) {
+                    let range = prev_idx..colon_idx + 1;
+                    result.push((range, replace));
+                    prev_colon_idx = None;
+                    continue;
+                }
+            }
+            prev_colon_idx = Some(colon_idx);
+        }
+
+        result
+    }
+
+    /// Replace all colon-delimited emoji in a string.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use euphoxide::Emoji;
+    /// let emoji = Emoji::load();
+    ///
+    /// let replaced = emoji.replace("Hello :globe_with_meridians:!");
+    /// assert_eq!(replaced, "Hello 🌐!");
+    ///
+    /// // Ignores nonexistent emoji
+    /// let replaced = emoji.replace("Hello :sparkly_wizard:!");
+    /// assert_eq!(replaced, "Hello :sparkly_wizard:!");
+    /// ```
+    pub fn replace<'a>(&self, text: &'a str) -> Cow<'a, str> {
+        let emoji = self.find(text);
+        if emoji.is_empty() {
+            return Cow::Borrowed(text);
+        }
+
+        let mut result = String::new();
+
+        let mut after_last_emoji = 0;
+        for (range, replace) in emoji {
+            // Only replace emoji with a replacement
+            if let Some(replace) = replace {
+                if range.start > after_last_emoji {
+                    // There were non-emoji characters between the last and the
+                    // current emoji.
+                    result.push_str(&text[after_last_emoji..range.start]);
+                }
+                result.push_str(replace);
+                after_last_emoji = range.end;
+            }
+        }
+
+        if after_last_emoji < text.len() {
+            result.push_str(&text[after_last_emoji..]);
+        }
+
+        Cow::Owned(result)
+    }
+
+    /// Remove all colon-delimited emoji in a string.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use euphoxide::Emoji;
+    /// let emoji = Emoji::load();
+    ///
+    /// let removed = emoji.remove("Hello :globe_with_meridians:!");
+    /// assert_eq!(removed, "Hello !");
+    ///
+    /// // Ignores nonexistent emoji
+    /// let removed = emoji.replace("Hello :sparkly_wizard:!");
+    /// assert_eq!(removed, "Hello :sparkly_wizard:!");
+    /// ```
+    pub fn remove<'a>(&self, text: &'a str) -> Cow<'a, str> {
+        let emoji = self.find(text);
+        if emoji.is_empty() {
+            return Cow::Borrowed(text);
+        }
+
+        let mut result = String::new();
+
+        let mut after_last_emoji = 0;
+        for (range, _) in emoji {
+            if range.start > after_last_emoji {
+                // There were non-emoji characters between the last and the
+                // current emoji.
+                result.push_str(&text[after_last_emoji..range.start]);
+            }
+            after_last_emoji = range.end;
+        }
+
+        if after_last_emoji < text.len() {
+            result.push_str(&text[after_last_emoji..]);
+        }
+
+        Cow::Owned(result)
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::Emoji;
+
+    #[test]
+    fn load_without_panic() {
+        Emoji::load();
+    }
+
+    #[test]
+    fn find() {
+        let emoji = Emoji::load();
+
+        // :bad: does not exist, while :x: and :o: do.
+
+        assert_eq!(emoji.find(":bad:x:o:"), vec![(4..7, Some("❌"))]);
+        assert_eq!(
+            emoji.find(":x:bad:o:"),
+            vec![(0..3, Some("❌")), (6..9, Some("⭕"))]
+        );
+        assert_eq!(emoji.find("ab:bad:x:o:cd"), vec![(6..9, Some("❌"))]);
+        assert_eq!(
+            emoji.find("ab:x:bad:o:cd"),
+            vec![(2..5, Some("❌")), (8..11, Some("⭕"))]
+        );
+    }
+
+    #[test]
+    fn replace() {
+        let emoji = Emoji::load();
+        assert_eq!(emoji.replace("no:emo:ji:here"), "no:emo:ji:here");
+        assert_eq!(emoji.replace(":bad:x:o:"), ":bad❌o:");
+        assert_eq!(emoji.replace(":x:bad:o:"), "❌bad⭕");
+        assert_eq!(emoji.replace("ab:bad:x:o:cd"), "ab:bad❌o:cd");
+        assert_eq!(emoji.replace("ab:x:bad:o:cd"), "ab❌bad⭕cd");
+        assert_eq!(emoji.replace("chᴜm:crown::ant:"), "chᴜm👑🐜");
+        assert_eq!(
+            emoji.replace(":waning_crescent_moon: (2% full)"),
+            "🌘 (2% full)"
+        );
+        assert_eq!(emoji.replace("Jan-20 17:58 Z"), "Jan-20 17:58 Z");
+    }
+
+    #[test]
+    fn remove() {
+        let emoji = Emoji::load();
+        assert_eq!(emoji.remove("no:emo:ji:here"), "no:emo:ji:here");
+        assert_eq!(emoji.remove(":bad:x:o:"), ":bado:");
+        assert_eq!(emoji.remove(":x:bad:o:"), "bad");
+        assert_eq!(emoji.remove("ab:bad:x:o:cd"), "ab:bado:cd");
+        assert_eq!(emoji.remove("ab:x:bad:o:cd"), "abbadcd");
+        assert_eq!(emoji.remove("chᴜm:crown::ant:"), "chᴜm");
+        assert_eq!(
+            emoji.remove(":waning_crescent_moon: (2% full)"),
+            " (2% full)"
+        );
+        assert_eq!(emoji.remove("Jan-20 17:58 Z"), "Jan-20 17:58 Z");
+    }
+}

euphoxide/src/error.rs

@@ -0,0 +1,82 @@
+//! Error handling.
+
+use std::fmt;
+
+use tokio_tungstenite::tungstenite;
+
+use crate::api::PacketType;
+
+/// Possible euphoria communication errors.
+#[derive(Debug)]
+pub enum Error {
+    /// The connection is closed.
+    ConnectionClosed,
+
+    /// A ping was not replied to in time.
+    PingTimeout,
+
+    /// A packet was not sent because it was malformed.
+    MalformedPacket(serde_json::Error),
+
+    /// A binary message was received.
+    ReceivedBinaryMessage,
+
+    /// A malformed packet was received.
+    ReceivedMalformedPacket(serde_json::Error),
+
+    /// An unexpected packet was received.
+    ReceivedUnexpectedPacket(PacketType),
+
+    /// A tungstenite error.
+    Tungstenite(tungstenite::Error),
+
+    /// A timeout occurred while opening a connection.
+    ///
+    /// This is a higher-level error that only occurs in the
+    /// [`ClientConn`](crate::client::conn::ClientConn).
+    ConnectionTimeout,
+
+    /// The server did not reply to a command in time.
+    ///
+    /// This is a higher-level error that only occurs with
+    /// [`Command`](crate::api::Command)-based APIs in
+    /// [`ClientConn`](crate::client::conn::ClientConn).
+    CommandTimeout,
+
+    /// The server replied with an error string.
+    ///
+    /// This is a higher-level error that only occurs with
+    /// [`Command`](crate::api::Command)-based APIs in
+    /// [`ClientConn`](crate::client::conn::ClientConn).
+    Euph(String),
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::ConnectionClosed => write!(f, "connection closed"),
+            Self::PingTimeout => write!(f, "ping timed out"),
+            Self::MalformedPacket(err) => write!(f, "malformed packet: {err}"),
+            Self::ReceivedBinaryMessage => write!(f, "received binary message"),
+            Self::ReceivedMalformedPacket(err) => write!(f, "received malformed packet: {err}"),
+            Self::ReceivedUnexpectedPacket(ptype) => {
+                write!(f, "received packet of unexpected type: {ptype}")
+            }
+            Self::Tungstenite(err) => write!(f, "{err}"),
+            Self::ConnectionTimeout => write!(f, "connection timed out while connecting"),
+            Self::CommandTimeout => write!(f, "command timed out"),
+            Self::Euph(msg) => write!(f, "{msg}"),
+        }
+    }
+}
+
+impl std::error::Error for Error {}
+
+impl From<tungstenite::Error> for Error {
+    fn from(err: tungstenite::Error) -> Self {
+        Self::Tungstenite(err)
+    }
+}
+
+/// An alias of [`Result`](std::result::Result) for [`Error`].
+pub type Result<T> = std::result::Result<T, Error>;

euphoxide/src/lib.rs

@@ -1,9 +1,9 @@
 pub mod api;
-#[cfg(feature = "bot")]
+pub mod client;
-pub mod bot;
 pub mod conn;
 mod emoji;
+mod error;
 pub mod nick;
 mod replies;
 
-pub use emoji::Emoji;
+pub use crate::{emoji::*, error::*};

euphoxide/src/nick.rs

@@ -69,17 +69,18 @@ pub fn hue(emoji: &Emoji, nick: &str) -> u8 {
 /// 1. Apply [`mention`]
 /// 2. Convert to NFKC
 /// 3. Case fold
+/// 4. Convert to NFC
 ///
-/// Steps 2 and 3 are meant to be an alternative to the NKFC_Casefold derived
+/// Steps 2 to 4 are meant to emulate NKFC_Casefold, but may differ in some edge
-/// property that's easier to implement, even though it may be incorrect in some
+/// cases. Most notably, they don't ignore default ignorable code points. Maybe
-/// edge cases.
+/// there are also other edge cases I don't know about.
-///
-/// [0]: https://github.com/CylonicRaider/heim/blob/978c921063e6b06012fc8d16d9fbf1b3a0be1191/client/lib/stores/chat.js#L14
 pub fn normalize(nick: &str) -> String {
     mention(nick) // Step 1
         .nfkc() // Step 2
         .default_case_fold() // Step 3
-        .collect()
+        .collect::<String>()
+        .nfc() // Step 4
+        .collect::<String>()
 }
 
 fn is_non_whitespace_delimiter(c: char) -> bool {
@@ -96,12 +97,14 @@ fn is_non_whitespace_delimiter(c: char) -> bool {
 /// highlight as a mention in the official euphoria client. It should ping any
 /// people using the original nick. It might also ping other people.
 ///
-/// In the official euphoria client, mentions are non-whitespace characters
+/// [In the official euphoria client][0], mentions are non-whitespace characters
 /// delimited by whitespace and any of the following characters:
 ///
 /// `,`, `.`, `!`, `?`, `;`, `&`, `<`, `>`, `'`, `"`.
 ///
 /// The first character of a mention may be a delimiting character.
+///
+/// [0]: https://github.com/CylonicRaider/heim/blob/978c921063e6b06012fc8d16d9fbf1b3a0be1191/client/lib/stores/chat.js#L14
 pub fn mention(nick: &str) -> String {
     let mut nick = nick.chars().filter(|c| !c.is_whitespace());
     let mut result = String::new();

euphoxide/src/replies.rs

@@ -1,10 +1,6 @@
-use std::collections::HashMap;
+use std::{collections::HashMap, error, fmt, hash::Hash, result, time::Duration};
-use std::fmt;
-use std::hash::Hash;
-use std::time::Duration;
-use std::{error, result};
 
-use tokio::sync::oneshot::{self, Receiver, Sender};
+use tokio::sync::oneshot;
 
 #[derive(Debug)]
 pub enum Error {
@@ -28,7 +24,7 @@ pub type Result<T> = result::Result<T, Error>;
 #[derive(Debug)]
 pub struct PendingReply<R> {
     timeout: Duration,
-    result: Receiver<R>,
+    result: oneshot::Receiver<R>,
 }
 
 impl<R> PendingReply<R> {
@@ -44,7 +40,7 @@ impl<R> PendingReply<R> {
 #[derive(Debug)]
 pub struct Replies<I, R> {
     timeout: Duration,
-    pending: HashMap<I, Sender<R>>,
+    pending: HashMap<I, oneshot::Sender<R>>,
 }
 
 impl<I, R> Replies<I, R> {
@@ -55,10 +51,6 @@ impl<I, R> Replies<I, R> {
         }
     }
 
-    pub fn timeout(&self) -> Duration {
-        self.timeout
-    }
-
     pub fn wait_for(&mut self, id: I) -> PendingReply<R>
     where
         I: Eq + Hash,

examples/testbot_commands.rs

@@ -1,150 +0,0 @@
-// TODO Add description
-// TODO Clean up and unify test bots
-
-use std::sync::Arc;
-
-use async_trait::async_trait;
-use clap::Parser;
-use euphoxide::api::Message;
-use euphoxide::bot::botrulez::{FullHelp, HasDescriptions, HasStartTime, Ping, ShortHelp, Uptime};
-use euphoxide::bot::command::{Clap, ClapCommand, Context, General, Global, Hidden, Specific};
-use euphoxide::bot::commands::Commands;
-use euphoxide::bot::instance::{Event, ServerConfig};
-use euphoxide::bot::instances::Instances;
-use euphoxide::conn;
-use jiff::Timestamp;
-use log::error;
-use tokio::sync::mpsc;
-
-const HELP: &str = "I'm an example bot for https://github.com/Garmelon/euphoxide";
-
-/// Kill this bot.
-#[derive(Parser)]
-struct KillArgs;
-
-struct Kill;
-
-#[async_trait]
-impl ClapCommand<Bot, conn::Error> for Kill {
-    type Args = KillArgs;
-
-    async fn execute(
-        &self,
-        _args: Self::Args,
-        msg: &Message,
-        ctx: &Context,
-        bot: &mut Bot,
-    ) -> Result<bool, conn::Error> {
-        bot.stop = true;
-        ctx.reply(msg.id, "/me dies").await?;
-        Ok(true)
-    }
-}
-
-/// Do some testing.
-#[derive(Parser)]
-struct TestArgs {
-    /// How much testing to do.
-    #[arg(default_value_t = 1)]
-    amount: u64,
-}
-
-struct Test;
-
-#[async_trait]
-impl ClapCommand<Bot, conn::Error> for Test {
-    type Args = TestArgs;
-
-    async fn execute(
-        &self,
-        args: Self::Args,
-        msg: &Message,
-        ctx: &Context,
-        _bot: &mut Bot,
-    ) -> Result<bool, conn::Error> {
-        let content = if args.amount == 1 {
-            format!("/me did {} test", args.amount)
-        } else {
-            format!("/me did {} tests", args.amount)
-        };
-        ctx.reply(msg.id, content).await?;
-        Ok(true)
-    }
-}
-
-struct Bot {
-    commands: Arc<Commands<Self, conn::Error>>,
-    start_time: Timestamp,
-    stop: bool,
-}
-
-impl HasDescriptions for Bot {
-    fn descriptions(&self, ctx: &Context) -> Vec<String> {
-        self.commands.descriptions(ctx)
-    }
-}
-
-impl HasStartTime for Bot {
-    fn start_time(&self) -> Timestamp {
-        self.start_time
-    }
-}
-
-#[tokio::main]
-async fn main() {
-    // https://github.com/snapview/tokio-tungstenite/issues/353#issuecomment-2455247837
-    rustls::crypto::aws_lc_rs::default_provider()
-        .install_default()
-        .unwrap();
-
-    let (tx, mut rx) = mpsc::unbounded_channel();
-    let mut instances = Instances::new(ServerConfig::default());
-
-    let mut cmds = Commands::new();
-    cmds.add(Hidden(General::new("ping", Clap(Ping::default()))));
-    cmds.add(Specific::new("ping", Clap(Ping::default())));
-    cmds.add(Hidden(General::new("help", Clap(ShortHelp::new(HELP)))));
-    cmds.add(Specific::new("help", Clap(FullHelp::new(HELP, ""))));
-    cmds.add(Specific::new("uptime", Clap(Uptime)));
-    cmds.add(Specific::new("kill", Clap(Kill)));
-    cmds.add(Global::new("test", Clap(Test)));
-    let cmds = Arc::new(cmds);
-
-    let mut bot = Bot {
-        commands: cmds.clone(),
-        start_time: Timestamp::now(),
-        stop: false,
-    };
-
-    for room in ["test", "test2", "testing"] {
-        let tx_clone = tx.clone();
-        let instance = instances
-            .server_config()
-            .clone()
-            .room(room)
-            .username(Some("TestBot"))
-            .build(move |e| {
-                let _ = tx_clone.send(e);
-            });
-        instances.add(instance);
-    }
-
-    while let Some(event) = rx.recv().await {
-        instances.purge();
-        if instances.is_empty() {
-            break;
-        }
-
-        if let Event::Packet(config, packet, snapshot) = event {
-            let result = cmds
-                .handle_packet(&config, &packet, &snapshot, &mut bot)
-                .await;
-            if let Err(err) = result {
-                error!("{err}");
-            }
-            if bot.stop {
-                break;
-            }
-        }
-    }
-}

examples/testbot_instance.rs

@@ -1,146 +0,0 @@
-//! Similar to the `testbot_manual` example, but using [`Instance`] to connect
-//! to the room (and to reconnect).
-
-use euphoxide::api::packet::ParsedPacket;
-use euphoxide::api::{Data, Nick, Send};
-use euphoxide::bot::botrulez;
-use euphoxide::bot::instance::{ConnSnapshot, Event, ServerConfig};
-use jiff::Timestamp;
-use tokio::sync::mpsc;
-
-const NICK: &str = "TestBot";
-const HELP: &str = "I'm an example bot for https://github.com/Garmelon/euphoxide";
-
-async fn on_packet(packet: ParsedPacket, snapshot: ConnSnapshot) -> Result<(), ()> {
-    let data = match packet.content {
-        Ok(data) => data,
-        Err(err) => {
-            println!("Error for {}: {err}", packet.r#type);
-            return Err(());
-        }
-    };
-
-    match data {
-        Data::HelloEvent(ev) => println!("Connected with id {}", ev.session.id),
-        Data::SnapshotEvent(ev) => {
-            for session in ev.listing {
-                println!("{:?} ({}) is already here", session.name, session.id);
-            }
-
-            // Here, a new task is spawned so the main event loop can
-            // continue running immediately instead of waiting for a reply
-            // from the server.
-            //
-            // We only need to do this because we want to log the result of
-            // the nick command. Otherwise, we could've just called
-            // tx.send() synchronously and ignored the returned Future.
-            let conn_tx_clone = snapshot.conn_tx.clone();
-            tokio::spawn(async move {
-                // Awaiting the future returned by the send command lets you
-                // (type-safely) access the server's reply.
-                let reply = conn_tx_clone
-                    .send(Nick {
-                        name: NICK.to_string(),
-                    })
-                    .await;
-                match reply {
-                    Ok(reply) => println!("Set nick to {:?}", reply.to),
-                    Err(err) => println!("Failed to set nick: {err}"),
-                };
-            });
-        }
-        Data::BounceEvent(_) => {
-            println!("Received bounce event, stopping");
-            return Err(());
-        }
-        Data::DisconnectEvent(_) => {
-            println!("Received disconnect event, stopping");
-            return Err(());
-        }
-        Data::JoinEvent(event) => println!("{:?} ({}) joined", event.0.name, event.0.id),
-        Data::PartEvent(event) => println!("{:?} ({}) left", event.0.name, event.0.id),
-        Data::NickEvent(event) => println!(
-            "{:?} ({}) is now known as {:?}",
-            event.from, event.id, event.to
-        ),
-        Data::SendEvent(event) => {
-            println!("Message {} was just sent", event.0.id.0);
-
-            let content = event.0.content.trim();
-            let mut reply = None;
-
-            if content == "!ping" || content == format!("!ping @{NICK}") {
-                reply = Some("Pong!".to_string());
-            } else if content == format!("!help @{NICK}") {
-                reply = Some(HELP.to_string());
-            } else if content == format!("!uptime @{NICK}") {
-                if let Some(joined) = snapshot.state.joined() {
-                    let delta = Timestamp::now() - joined.since;
-                    reply = Some(format!(
-                        "/me has been up for {}",
-                        botrulez::format_duration(delta)
-                    ));
-                }
-            } else if content == "!test" {
-                reply = Some("Test successful!".to_string());
-            } else if content == format!("!kill @{NICK}") {
-                println!(
-                    "I was killed by {:?} ({})",
-                    event.0.sender.name, event.0.sender.id
-                );
-                // Awaiting the server reply in the main loop to ensure the
-                // message is sent before we exit the loop. Otherwise, there
-                // would be a race between sending the message and closing
-                // the connection as the send function can return before the
-                // message has actually been sent.
-                let _ = snapshot
-                    .conn_tx
-                    .send(Send {
-                        content: "/me dies".to_string(),
-                        parent: Some(event.0.id),
-                    })
-                    .await;
-                return Err(());
-            }
-
-            if let Some(reply) = reply {
-                // If you are not interested in the result, you can just
-                // throw away the future returned by the send function.
-                println!("Sending reply...");
-                snapshot.conn_tx.send_only(Send {
-                    content: reply,
-                    parent: Some(event.0.id),
-                });
-                println!("Reply sent!");
-            }
-        }
-        _ => {}
-    }
-
-    Ok(())
-}
-
-#[tokio::main]
-async fn main() {
-    // https://github.com/snapview/tokio-tungstenite/issues/353#issuecomment-2455247837
-    rustls::crypto::aws_lc_rs::default_provider()
-        .install_default()
-        .unwrap();
-
-    let (tx, mut rx) = mpsc::unbounded_channel();
-
-    let _instance = ServerConfig::default()
-        .room("test")
-        .username(Some("TestBot"))
-        .build(move |e| {
-            let _ = tx.send(e);
-        });
-
-    while let Some(event) = rx.recv().await {
-        if let Event::Packet(_config, packet, snapshot) = event {
-            if on_packet(packet, snapshot).await.is_err() {
-                break;
-            }
-        }
-    }
-}

examples/testbot_instances.rs

@@ -1,159 +0,0 @@
-//! Similar to the `testbot_manual` example, but using [`Instance`] to connect
-//! to the room (and to reconnect).
-
-use euphoxide::api::packet::ParsedPacket;
-use euphoxide::api::{Data, Nick, Send};
-use euphoxide::bot::botrulez;
-use euphoxide::bot::instance::{ConnSnapshot, Event, ServerConfig};
-use euphoxide::bot::instances::Instances;
-use jiff::Timestamp;
-use tokio::sync::mpsc;
-
-const NICK: &str = "TestBot";
-const HELP: &str = "I'm an example bot for https://github.com/Garmelon/euphoxide";
-
-async fn on_packet(packet: ParsedPacket, snapshot: ConnSnapshot) -> Result<(), ()> {
-    let data = match packet.content {
-        Ok(data) => data,
-        Err(err) => {
-            println!("Error for {}: {err}", packet.r#type);
-            return Err(());
-        }
-    };
-
-    match data {
-        Data::HelloEvent(ev) => println!("Connected with id {}", ev.session.id),
-        Data::SnapshotEvent(ev) => {
-            for session in ev.listing {
-                println!("{:?} ({}) is already here", session.name, session.id);
-            }
-
-            // Here, a new task is spawned so the main event loop can
-            // continue running immediately instead of waiting for a reply
-            // from the server.
-            //
-            // We only need to do this because we want to log the result of
-            // the nick command. Otherwise, we could've just called
-            // tx.send() synchronously and ignored the returned Future.
-            let conn_tx_clone = snapshot.conn_tx.clone();
-            tokio::spawn(async move {
-                // Awaiting the future returned by the send command lets you
-                // (type-safely) access the server's reply.
-                let reply = conn_tx_clone
-                    .send(Nick {
-                        name: NICK.to_string(),
-                    })
-                    .await;
-                match reply {
-                    Ok(reply) => println!("Set nick to {:?}", reply.to),
-                    Err(err) => println!("Failed to set nick: {err}"),
-                };
-            });
-        }
-        Data::BounceEvent(_) => {
-            println!("Received bounce event, stopping");
-            return Err(());
-        }
-        Data::DisconnectEvent(_) => {
-            println!("Received disconnect event, stopping");
-            return Err(());
-        }
-        Data::JoinEvent(event) => println!("{:?} ({}) joined", event.0.name, event.0.id),
-        Data::PartEvent(event) => println!("{:?} ({}) left", event.0.name, event.0.id),
-        Data::NickEvent(event) => println!(
-            "{:?} ({}) is now known as {:?}",
-            event.from, event.id, event.to
-        ),
-        Data::SendEvent(event) => {
-            println!("Message {} was just sent", event.0.id.0);
-
-            let content = event.0.content.trim();
-            let mut reply = None;
-
-            if content == "!ping" || content == format!("!ping @{NICK}") {
-                reply = Some("Pong!".to_string());
-            } else if content == format!("!help @{NICK}") {
-                reply = Some(HELP.to_string());
-            } else if content == format!("!uptime @{NICK}") {
-                if let Some(joined) = snapshot.state.joined() {
-                    let delta = Timestamp::now() - joined.since;
-                    reply = Some(format!(
-                        "/me has been up for {}",
-                        botrulez::format_duration(delta)
-                    ));
-                }
-            } else if content == "!test" {
-                reply = Some("Test successful!".to_string());
-            } else if content == format!("!kill @{NICK}") {
-                println!(
-                    "I was killed by {:?} ({})",
-                    event.0.sender.name, event.0.sender.id
-                );
-                // Awaiting the server reply in the main loop to ensure the
-                // message is sent before we exit the loop. Otherwise, there
-                // would be a race between sending the message and closing
-                // the connection as the send function can return before the
-                // message has actually been sent.
-                let _ = snapshot
-                    .conn_tx
-                    .send(Send {
-                        content: "/me dies".to_string(),
-                        parent: Some(event.0.id),
-                    })
-                    .await;
-                return Err(());
-            }
-
-            if let Some(reply) = reply {
-                // If you are not interested in the result, you can just
-                // throw away the future returned by the send function.
-                println!("Sending reply...");
-                snapshot.conn_tx.send_only(Send {
-                    content: reply,
-                    parent: Some(event.0.id),
-                });
-                println!("Reply sent!");
-            }
-        }
-        _ => {}
-    }
-
-    Ok(())
-}
-
-#[tokio::main]
-async fn main() {
-    // https://github.com/snapview/tokio-tungstenite/issues/353#issuecomment-2455247837
-    rustls::crypto::aws_lc_rs::default_provider()
-        .install_default()
-        .unwrap();
-
-    let (tx, mut rx) = mpsc::unbounded_channel();
-    let mut instances = Instances::new(ServerConfig::default());
-
-    for room in ["test", "test2", "testing"] {
-        let tx_clone = tx.clone();
-        let instance = instances
-            .server_config()
-            .clone()
-            .room(room)
-            .username(Some("TestBot"))
-            .build(move |e| {
-                let _ = tx_clone.send(e);
-            });
-        instances.add(instance);
-    }
-
-    while let Some(event) = rx.recv().await {
-        instances.purge();
-        if instances.is_empty() {
-            break;
-        }
-
-        if let Event::Packet(_config, packet, snapshot) = event {
-            if on_packet(packet, snapshot).await.is_err() {
-                break;
-            }
-        }
-    }
-}

examples/testbot_manual.rs

@@ -1,142 +0,0 @@
-//! A small bot that doesn't use the `bot` submodule. Meant to show how the main
-//! parts of the API fit together.
-
-use std::error::Error;
-use std::time::Duration;
-
-use euphoxide::api::packet::ParsedPacket;
-use euphoxide::api::{Data, Nick, Send};
-use euphoxide::bot::botrulez;
-use euphoxide::conn::{Conn, ConnTx, State};
-use jiff::Timestamp;
-
-const TIMEOUT: Duration = Duration::from_secs(10);
-const DOMAIN: &str = "euphoria.leet.nu";
-const ROOM: &str = "test";
-const NICK: &str = "TestBot";
-const HELP: &str = "I'm an example bot for https://github.com/Garmelon/euphoxide";
-
-async fn on_packet(packet: ParsedPacket, conn_tx: &ConnTx, state: &State) -> Result<(), ()> {
-    let data = match packet.content {
-        Ok(data) => data,
-        Err(err) => {
-            println!("Error for {}: {err}", packet.r#type);
-            return Err(());
-        }
-    };
-
-    match data {
-        Data::HelloEvent(event) => println!("Connected with id {}", event.session.id),
-        Data::SnapshotEvent(event) => {
-            for session in event.listing {
-                println!("{:?} ({}) is already here", session.name, session.id);
-            }
-
-            // Here, a new task is spawned so the main event loop can
-            // continue running immediately instead of waiting for a reply
-            // from the server.
-            //
-            // We only need to do this because we want to log the result of
-            // the nick command. Otherwise, we could've just called
-            // tx.send() synchronously and ignored the returned Future.
-            let conn_tx_clone = conn_tx.clone();
-            tokio::spawn(async move {
-                // Awaiting the future returned by the send command lets you
-                // (type-safely) access the server's reply.
-                let reply = conn_tx_clone
-                    .send(Nick {
-                        name: NICK.to_string(),
-                    })
-                    .await;
-                match reply {
-                    Ok(reply) => println!("Set nick to {:?}", reply.to),
-                    Err(err) => println!("Failed to set nick: {err}"),
-                };
-            });
-        }
-        Data::BounceEvent(_) => {
-            println!("Received bounce event, stopping");
-            return Err(());
-        }
-        Data::DisconnectEvent(_) => {
-            println!("Received disconnect event, stopping");
-            return Err(());
-        }
-        Data::JoinEvent(event) => println!("{:?} ({}) joined", event.0.name, event.0.id),
-        Data::PartEvent(event) => println!("{:?} ({}) left", event.0.name, event.0.id),
-        Data::NickEvent(event) => println!(
-            "{:?} ({}) is now known as {:?}",
-            event.from, event.id, event.to
-        ),
-        Data::SendEvent(event) => {
-            println!("Message {} was just sent", event.0.id.0);
-
-            let content = event.0.content.trim();
-            let mut reply = None;
-
-            if content == "!ping" || content == format!("!ping @{NICK}") {
-                reply = Some("Pong!".to_string());
-            } else if content == format!("!help @{NICK}") {
-                reply = Some(HELP.to_string());
-            } else if content == format!("!uptime @{NICK}") {
-                if let Some(joined) = state.joined() {
-                    let delta = Timestamp::now() - joined.since;
-                    reply = Some(format!(
-                        "/me has been up for {}",
-                        botrulez::format_duration(delta)
-                    ));
-                }
-            } else if content == "!test" {
-                reply = Some("Test successful!".to_string());
-            } else if content == format!("!kill @{NICK}") {
-                println!(
-                    "I was killed by {:?} ({})",
-                    event.0.sender.name, event.0.sender.id
-                );
-                // Awaiting the server reply in the main loop to ensure the
-                // message is sent before we exit the loop. Otherwise, there
-                // would be a race between sending the message and closing
-                // the connection as the send function can return before the
-                // message has actually been sent.
-                let _ = conn_tx
-                    .send(Send {
-                        content: "/me dies".to_string(),
-                        parent: Some(event.0.id),
-                    })
-                    .await;
-                return Err(());
-            }
-
-            if let Some(reply) = reply {
-                // If you are not interested in the result, you can just
-                // throw away the future returned by the send function.
-                println!("Sending reply...");
-                conn_tx.send_only(Send {
-                    content: reply,
-                    parent: Some(event.0.id),
-                });
-                println!("Reply sent!");
-            }
-        }
-        _ => {}
-    }
-
-    Ok(())
-}
-
-#[tokio::main]
-async fn main() -> Result<(), Box<dyn Error>> {
-    // https://github.com/snapview/tokio-tungstenite/issues/353#issuecomment-2455247837
-    rustls::crypto::aws_lc_rs::default_provider()
-        .install_default()
-        .unwrap();
-
-    let (mut conn, _) = Conn::connect(DOMAIN, ROOM, false, None, TIMEOUT).await?;
-
-    while let Ok(packet) = conn.recv().await {
-        if on_packet(packet, conn.tx(), conn.state()).await.is_err() {
-            break;
-        }
-    }
-    Ok(())
-}

src/api.rs

@@ -1,17 +0,0 @@
-//! Models the [euphoria API][0].
-//!
-//! [0]: https://euphoria.leet.nu/heim/api
-
-mod account_cmds;
-mod events;
-pub mod packet;
-mod room_cmds;
-mod session_cmds;
-mod types;
-
-pub use account_cmds::*;
-pub use events::*;
-pub use packet::Data;
-pub use room_cmds::*;
-pub use session_cmds::*;
-pub use types::*;

src/api/packet.rs

@@ -1,223 +0,0 @@
-use serde::{Deserialize, Serialize};
-use serde_json::Value;
-
-use super::PacketType;
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct Packet {
-    pub id: Option<String>,
-    pub r#type: PacketType,
-    pub data: Option<Value>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub error: Option<String>,
-    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
-    pub throttled: bool,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub throttled_reason: Option<String>,
-}
-
-pub trait Command {
-    type Reply;
-}
-
-macro_rules! packets {
-    ( $( $name:ident, )*) => {
-        #[derive(Debug, Clone)]
-        #[non_exhaustive]
-        pub enum Data {
-            $( $name(super::$name), )*
-            Unimplemented,
-        }
-
-        impl Data {
-            pub fn from_value(ptype: PacketType, value: Value) -> serde_json::Result<Self> {
-                Ok(match ptype {
-                    $( PacketType::$name => Self::$name(serde_json::from_value(value)?), )*
-                    _ => Self::Unimplemented,
-                })
-            }
-
-            pub fn into_value(self) -> serde_json::Result<Value> {
-                Ok(match self{
-                    $( Self::$name(p) => serde_json::to_value(p)?, )*
-                    Self::Unimplemented => panic!("using unimplemented data"),
-                })
-            }
-
-            pub fn packet_type(&self) -> PacketType {
-                match self {
-                    $( Self::$name(_) => PacketType::$name, )*
-                    Self::Unimplemented => panic!("using unimplemented data"),
-                }
-            }
-        }
-
-        $(
-            impl From<super::$name> for Data {
-                fn from(p: super::$name) -> Self {
-                    Self::$name(p)
-                }
-            }
-
-            impl TryFrom<Data> for super::$name{
-                type Error = ();
-
-                fn try_from(value: Data) -> Result<Self, Self::Error> {
-                    match value {
-                        Data::$name(p) => Ok(p),
-                        _ => Err(())
-                    }
-                }
-            }
-        )*
-    };
-}
-
-macro_rules! commands {
-    ( $( $cmd:ident => $rpl:ident, )* ) => {
-        $(
-            impl Command for super::$cmd {
-                type Reply = super::$rpl;
-            }
-        )*
-    };
-}
-
-packets! {
-    // Events
-    BounceEvent,
-    DisconnectEvent,
-    HelloEvent,
-    JoinEvent,
-    LoginEvent,
-    LogoutEvent,
-    NetworkEvent,
-    NickEvent,
-    EditMessageEvent,
-    PartEvent,
-    PingEvent,
-    PmInitiateEvent,
-    SendEvent,
-    SnapshotEvent,
-    // Session commands
-    Auth,
-    AuthReply,
-    Ping,
-    PingReply,
-    // Chat room commands
-    GetMessage,
-    GetMessageReply,
-    Log,
-    LogReply,
-    Nick,
-    NickReply,
-    PmInitiate,
-    PmInitiateReply,
-    Send,
-    SendReply,
-    Who,
-    WhoReply,
-    // Account commands
-    ChangeEmail,
-    ChangeEmailReply,
-    ChangeName,
-    ChangeNameReply,
-    ChangePassword,
-    ChangePasswordReply,
-    Login,
-    LoginReply,
-    Logout,
-    LogoutReply,
-    RegisterAccount,
-    RegisterAccountReply,
-    ResendVerificationEmail,
-    ResendVerificationEmailReply,
-    ResetPassword,
-    ResetPasswordReply,
-}
-
-commands! {
-    // Session commands
-    Auth => AuthReply,
-    Ping => PingReply,
-    // Chat room commands
-    GetMessage => GetMessageReply,
-    Log => LogReply,
-    Nick => NickReply,
-    PmInitiate => PmInitiateReply,
-    Send => SendReply,
-    Who => WhoReply,
-    // Account commands
-    ChangeEmail => ChangeEmailReply,
-    ChangeName => ChangeNameReply,
-    ChangePassword => ChangePasswordReply,
-    Login => LoginReply,
-    Logout => LogoutReply,
-    RegisterAccount => RegisterAccountReply,
-    ResendVerificationEmail => ResendVerificationEmailReply,
-    ResetPassword => ResetPasswordReply,
-}
-
-#[derive(Debug, Clone)]
-pub struct ParsedPacket {
-    pub id: Option<String>,
-    pub r#type: PacketType,
-    pub content: Result<Data, String>,
-    pub throttled: Option<String>,
-}
-
-impl ParsedPacket {
-    pub fn from_packet(packet: Packet) -> serde_json::Result<Self> {
-        let id = packet.id;
-        let r#type = packet.r#type;
-
-        let content = if let Some(error) = packet.error {
-            Err(error)
-        } else {
-            let data = packet.data.unwrap_or_default();
-            Ok(Data::from_value(r#type, data)?)
-        };
-
-        let throttled = if packet.throttled {
-            let reason = packet
-                .throttled_reason
-                .unwrap_or_else(|| "no reason given".to_string());
-            Some(reason)
-        } else {
-            None
-        };
-
-        Ok(Self {
-            id,
-            r#type,
-            content,
-            throttled,
-        })
-    }
-
-    pub fn into_packet(self) -> serde_json::Result<Packet> {
-        let id = self.id;
-        let r#type = self.r#type;
-        let throttled = self.throttled.is_some();
-        let throttled_reason = self.throttled;
-
-        Ok(match self.content {
-            Ok(data) => Packet {
-                id,
-                r#type,
-                data: Some(data.into_value()?),
-                error: None,
-                throttled,
-                throttled_reason,
-            },
-            Err(error) => Packet {
-                id,
-                r#type,
-                data: None,
-                error: Some(error),
-                throttled,
-                throttled_reason,
-            },
-        })
-    }
-}

src/bot.rs

@@ -1,7 +0,0 @@
-//! Building blocks for bots.
-
-pub mod botrulez;
-pub mod command;
-pub mod commands;
-pub mod instance;
-pub mod instances;

src/bot/botrulez.rs

@@ -1,10 +0,0 @@
-//! The main [botrulez](https://github.com/jedevc/botrulez) commands.
-pub mod full_help;
-pub mod ping;
-pub mod short_help;
-pub mod uptime;
-
-pub use self::full_help::{FullHelp, HasDescriptions};
-pub use self::ping::Ping;
-pub use self::short_help::ShortHelp;
-pub use self::uptime::{format_duration, format_relative_time, format_time, HasStartTime, Uptime};

src/bot/botrulez/full_help.rs

@@ -1,93 +0,0 @@
-use async_trait::async_trait;
-use clap::Parser;
-
-use crate::api::Message;
-use crate::bot::command::{ClapCommand, Command, Context};
-use crate::conn;
-
-pub struct FullHelp {
-    pub before: String,
-    pub after: String,
-}
-
-pub trait HasDescriptions {
-    fn descriptions(&self, ctx: &Context) -> Vec<String>;
-}
-
-impl FullHelp {
-    pub fn new<S1: ToString, S2: ToString>(before: S1, after: S2) -> Self {
-        Self {
-            before: before.to_string(),
-            after: after.to_string(),
-        }
-    }
-
-    fn formulate_reply<B: HasDescriptions>(&self, ctx: &Context, bot: &B) -> String {
-        let mut result = String::new();
-
-        if !self.before.is_empty() {
-            result.push_str(&self.before);
-            result.push('\n');
-        }
-
-        for description in bot.descriptions(ctx) {
-            result.push_str(&description);
-            result.push('\n');
-        }
-
-        if !self.after.is_empty() {
-            result.push_str(&self.after);
-            result.push('\n');
-        }
-
-        result
-    }
-}
-
-#[async_trait]
-impl<B, E> Command<B, E> for FullHelp
-where
-    B: HasDescriptions + Send,
-    E: From<conn::Error>,
-{
-    async fn execute(
-        &self,
-        arg: &str,
-        msg: &Message,
-        ctx: &Context,
-        bot: &mut B,
-    ) -> Result<bool, E> {
-        if arg.trim().is_empty() {
-            let reply = self.formulate_reply(ctx, bot);
-            ctx.reply(msg.id, reply).await?;
-            Ok(true)
-        } else {
-            Ok(false)
-        }
-    }
-}
-
-/// Show full bot help.
-#[derive(Parser)]
-pub struct Args {}
-
-#[async_trait]
-impl<B, E> ClapCommand<B, E> for FullHelp
-where
-    B: HasDescriptions + Send,
-    E: From<conn::Error>,
-{
-    type Args = Args;
-
-    async fn execute(
-        &self,
-        _args: Self::Args,
-        msg: &Message,
-        ctx: &Context,
-        bot: &mut B,
-    ) -> Result<bool, E> {
-        let reply = self.formulate_reply(ctx, bot);
-        ctx.reply(msg.id, reply).await?;
-        Ok(true)
-    }
-}

src/bot/botrulez/ping.rs

@@ -1,64 +0,0 @@
-use async_trait::async_trait;
-use clap::Parser;
-
-use crate::api::Message;
-use crate::bot::command::{ClapCommand, Command, Context};
-use crate::conn;
-
-pub struct Ping(pub String);
-
-impl Ping {
-    pub fn new<S: ToString>(reply: S) -> Self {
-        Self(reply.to_string())
-    }
-}
-
-impl Default for Ping {
-    fn default() -> Self {
-        Self::new("Pong!")
-    }
-}
-
-#[async_trait]
-impl<B, E> Command<B, E> for Ping
-where
-    E: From<conn::Error>,
-{
-    async fn execute(
-        &self,
-        arg: &str,
-        msg: &Message,
-        ctx: &Context,
-        _bot: &mut B,
-    ) -> Result<bool, E> {
-        if arg.trim().is_empty() {
-            ctx.reply(msg.id, &self.0).await?;
-            Ok(true)
-        } else {
-            Ok(false)
-        }
-    }
-}
-
-/// Trigger a short reply.
-#[derive(Parser)]
-pub struct Args {}
-
-#[async_trait]
-impl<B, E> ClapCommand<B, E> for Ping
-where
-    E: From<conn::Error>,
-{
-    type Args = Args;
-
-    async fn execute(
-        &self,
-        _args: Self::Args,
-        msg: &Message,
-        ctx: &Context,
-        _bot: &mut B,
-    ) -> Result<bool, E> {
-        ctx.reply(msg.id, &self.0).await?;
-        Ok(true)
-    }
-}

src/bot/botrulez/short_help.rs

@@ -1,58 +0,0 @@
-use async_trait::async_trait;
-use clap::Parser;
-
-use crate::api::Message;
-use crate::bot::command::{ClapCommand, Command, Context};
-use crate::conn;
-
-pub struct ShortHelp(pub String);
-
-impl ShortHelp {
-    pub fn new<S: ToString>(text: S) -> Self {
-        Self(text.to_string())
-    }
-}
-
-#[async_trait]
-impl<B, E> Command<B, E> for ShortHelp
-where
-    E: From<conn::Error>,
-{
-    async fn execute(
-        &self,
-        arg: &str,
-        msg: &Message,
-        ctx: &Context,
-        _bot: &mut B,
-    ) -> Result<bool, E> {
-        if arg.trim().is_empty() {
-            ctx.reply(msg.id, &self.0).await?;
-            Ok(true)
-        } else {
-            Ok(false)
-        }
-    }
-}
-
-/// Show short bot help.
-#[derive(Parser)]
-pub struct Args {}
-
-#[async_trait]
-impl<B, E> ClapCommand<B, E> for ShortHelp
-where
-    E: From<conn::Error>,
-{
-    type Args = Args;
-
-    async fn execute(
-        &self,
-        _args: Self::Args,
-        msg: &Message,
-        ctx: &Context,
-        _bot: &mut B,
-    ) -> Result<bool, E> {
-        ctx.reply(msg.id, &self.0).await?;
-        Ok(true)
-    }
-}

src/bot/command.rs

@@ -1,64 +0,0 @@
-mod bang;
-mod clap;
-mod hidden;
-mod prefixed;
-
-use std::future::Future;
-
-use async_trait::async_trait;
-
-use crate::api::{self, Message, MessageId};
-use crate::conn::{self, ConnTx, Joined};
-
-pub use self::bang::*;
-pub use self::clap::*;
-pub use self::hidden::*;
-pub use self::prefixed::*;
-
-use super::instance::InstanceConfig;
-
-pub struct Context {
-    pub config: InstanceConfig,
-    pub conn_tx: ConnTx,
-    pub joined: Joined,
-}
-
-impl Context {
-    pub fn send<S: ToString>(&self, content: S) -> impl Future<Output = conn::Result<Message>> {
-        let cmd = api::Send {
-            content: content.to_string(),
-            parent: None,
-        };
-        let reply = self.conn_tx.send(cmd);
-        async move { reply.await.map(|r| r.0) }
-    }
-
-    pub fn reply<S: ToString>(
-        &self,
-        parent: MessageId,
-        content: S,
-    ) -> impl Future<Output = conn::Result<Message>> {
-        let cmd = api::Send {
-            content: content.to_string(),
-            parent: Some(parent),
-        };
-        let reply = self.conn_tx.send(cmd);
-        async move { reply.await.map(|r| r.0) }
-    }
-}
-
-#[allow(unused_variables)]
-#[async_trait]
-pub trait Command<B, E> {
-    fn description(&self, ctx: &Context) -> Option<String> {
-        None
-    }
-
-    async fn execute(
-        &self,
-        arg: &str,
-        msg: &Message,
-        ctx: &Context,
-        bot: &mut B,
-    ) -> Result<bool, E>;
-}

src/bot/command/hidden.rs

@@ -1,29 +0,0 @@
-use async_trait::async_trait;
-
-use crate::api::Message;
-
-use super::{Command, Context};
-
-pub struct Hidden<C>(pub C);
-
-#[async_trait]
-impl<B, E, C> Command<B, E> for Hidden<C>
-where
-    B: Send,
-    C: Command<B, E> + Send + Sync,
-{
-    fn description(&self, _ctx: &Context) -> Option<String> {
-        // Default implementation, repeated here for emphasis.
-        None
-    }
-
-    async fn execute(
-        &self,
-        arg: &str,
-        msg: &Message,
-        ctx: &Context,
-        bot: &mut B,
-    ) -> Result<bool, E> {
-        self.0.execute(arg, msg, ctx, bot).await
-    }
-}

src/bot/command/prefixed.rs

@@ -1,45 +0,0 @@
-use async_trait::async_trait;
-
-use crate::api::Message;
-
-use super::{Command, Context};
-
-pub struct Prefixed<C> {
-    prefix: String,
-    inner: C,
-}
-
-impl<C> Prefixed<C> {
-    pub fn new<S: ToString>(prefix: S, inner: C) -> Self {
-        Self {
-            prefix: prefix.to_string(),
-            inner,
-        }
-    }
-}
-
-#[async_trait]
-impl<B, E, C> Command<B, E> for Prefixed<C>
-where
-    B: Send,
-    C: Command<B, E> + Send + Sync,
-{
-    fn description(&self, ctx: &Context) -> Option<String> {
-        let inner = self.inner.description(ctx)?;
-        Some(format!("{} - {inner}", self.prefix))
-    }
-
-    async fn execute(
-        &self,
-        arg: &str,
-        msg: &Message,
-        ctx: &Context,
-        bot: &mut B,
-    ) -> Result<bool, E> {
-        if let Some(rest) = arg.trim_start().strip_prefix(&self.prefix) {
-            self.inner.execute(rest, msg, ctx, bot).await
-        } else {
-            Ok(false)
-        }
-    }
-}

src/bot/commands.rs

@@ -1,93 +0,0 @@
-use crate::api::packet::ParsedPacket;
-use crate::api::{Data, SendEvent};
-use crate::conn;
-
-use super::command::{Command, Context};
-use super::instance::{ConnSnapshot, InstanceConfig};
-
-pub struct Commands<B, E> {
-    commands: Vec<Box<dyn Command<B, E> + Send + Sync>>,
-    fallthrough: bool,
-}
-
-impl<B, E> Commands<B, E> {
-    pub fn new() -> Self {
-        Self {
-            commands: vec![],
-            fallthrough: false,
-        }
-    }
-
-    /// Whether further commands should be executed after a command returns
-    /// `true`.
-    ///
-    /// If disabled, commands are run until the first command that returns
-    /// `true`. If enabled, all commands are run irrespective of their return
-    /// values.
-    pub fn fallthrough(&self) -> bool {
-        self.fallthrough
-    }
-
-    /// Set whether fallthrough is active.
-    ///
-    /// See [`Self::fallthrough`] for more details.
-    pub fn set_fallthrough(&mut self, active: bool) {
-        self.fallthrough = active;
-    }
-
-    pub fn add<C>(&mut self, command: C)
-    where
-        C: Command<B, E> + Send + Sync + 'static,
-    {
-        self.commands.push(Box::new(command));
-    }
-
-    pub fn descriptions(&self, ctx: &Context) -> Vec<String> {
-        self.commands
-            .iter()
-            .filter_map(|c| c.description(ctx))
-            .collect::<Vec<_>>()
-    }
-
-    /// Returns `true` if one or more commands returned `true`, `false`
-    /// otherwise.
-    pub async fn handle_packet(
-        &self,
-        config: &InstanceConfig,
-        packet: &ParsedPacket,
-        snapshot: &ConnSnapshot,
-        bot: &mut B,
-    ) -> Result<bool, E> {
-        let msg = match &packet.content {
-            Ok(Data::SendEvent(SendEvent(msg))) => msg,
-            _ => return Ok(false),
-        };
-
-        let joined = match &snapshot.state {
-            conn::State::Joining(_) => return Ok(false),
-            conn::State::Joined(joined) => joined.clone(),
-        };
-
-        let ctx = Context {
-            config: config.clone(),
-            conn_tx: snapshot.conn_tx.clone(),
-            joined,
-        };
-
-        let mut handled = false;
-        for command in &self.commands {
-            handled = handled || command.execute(&msg.content, msg, &ctx, bot).await?;
-            if !self.fallthrough && handled {
-                break;
-            }
-        }
-
-        Ok(handled)
-    }
-}
-
-impl<B, E> Default for Commands<B, E> {
-    fn default() -> Self {
-        Self::new()
-    }
-}

src/bot/instance.rs

@@ -1,534 +0,0 @@
-//! A single instance of a bot in a single room.
-//!
-//! See [`Instance`] for more details.
-
-use std::convert::Infallible;
-use std::fmt;
-use std::str::FromStr;
-use std::sync::{Arc, Mutex};
-use std::time::Duration;
-
-use cookie::{Cookie, CookieJar};
-use tokio::select;
-use tokio::sync::{mpsc, oneshot};
-use tokio_tungstenite::tungstenite;
-use tokio_tungstenite::tungstenite::http::{HeaderValue, StatusCode};
-
-use crate::api::packet::ParsedPacket;
-use crate::api::{Auth, AuthOption, Data, Nick};
-use crate::conn::{self, Conn, ConnTx, State};
-
-macro_rules! ilog {
-    ( $conf:expr, $target:expr, $($arg:tt)+ ) => {
-        ::log::log!(
-            target: &format!("euphoxide::live::{}", $conf.name),
-            $target,
-            $($arg)+
-        );
-    };
-}
-
-macro_rules! idebug {
-    ( $conf:expr, $($arg:tt)+ ) => {
-        ilog!($conf, ::log::Level::Debug, $($arg)+);
-    };
-}
-
-macro_rules! iinfo {
-    ( $conf:expr, $($arg:tt)+ ) => {
-        ilog!($conf, ::log::Level::Info, $($arg)+);
-    };
-}
-
-macro_rules! iwarn {
-    ( $conf:expr, $($arg:tt)+ ) => {
-        ilog!($conf, ::log::Level::Warn, $($arg)+);
-    };
-}
-
-/// Settings that are usually shared between all instances connecting to a
-/// specific server.
-#[derive(Clone)]
-pub struct ServerConfig {
-    /// How long to wait for the server until an operation is considered timed
-    /// out.
-    ///
-    /// This timeout applies to waiting for reply packets to command packets
-    /// sent by the client, as well as operations like connecting or closing a
-    /// connection.
-    pub timeout: Duration,
-    /// How long to wait until reconnecting after an unsuccessful attempt to
-    /// connect.
-    pub reconnect_delay: Duration,
-    /// Domain name, to be used with [`Conn::connect`].
-    pub domain: String,
-    /// Cookies to use when connecting. They are updated with the server's reply
-    /// after successful connection attempts.
-    pub cookies: Arc<Mutex<CookieJar>>,
-}
-
-impl ServerConfig {
-    pub fn timeout(mut self, timeout: Duration) -> Self {
-        self.timeout = timeout;
-        self
-    }
-
-    pub fn reconnect_delay(mut self, reconnect_delay: Duration) -> Self {
-        self.reconnect_delay = reconnect_delay;
-        self
-    }
-
-    pub fn domain<S: ToString>(mut self, domain: S) -> Self {
-        self.domain = domain.to_string();
-        self
-    }
-
-    pub fn cookies(mut self, cookies: Arc<Mutex<CookieJar>>) -> Self {
-        self.cookies = cookies;
-        self
-    }
-
-    pub fn room<S: ToString>(self, room: S) -> InstanceConfig {
-        InstanceConfig::new(self, room)
-    }
-}
-
-impl Default for ServerConfig {
-    fn default() -> Self {
-        Self {
-            timeout: Duration::from_secs(30),
-            reconnect_delay: Duration::from_secs(30),
-            domain: "euphoria.leet.nu".to_string(),
-            cookies: Arc::new(Mutex::new(CookieJar::new())),
-        }
-    }
-}
-
-struct Hidden;
-
-impl fmt::Debug for Hidden {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "<hidden>")
-    }
-}
-
-impl fmt::Debug for ServerConfig {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.debug_struct("ServerConfig")
-            .field("timeout", &self.timeout)
-            .field("reconnect_delay", &self.reconnect_delay)
-            .field("domain", &self.domain)
-            .field("cookies", &Hidden)
-            .finish()
-    }
-}
-
-/// Settings that are usually specific to a single instance.
-#[derive(Debug, Clone)]
-pub struct InstanceConfig {
-    pub server: ServerConfig,
-    /// Unique name of this instance.
-    pub name: String,
-    /// Room name, to be used with [`Conn::connect`].
-    pub room: String,
-    /// Whether the instance should connect as human or bot.
-    pub human: bool,
-    /// Username to set upon connecting.
-    pub username: Option<String>,
-    /// Whether to set the username even if the server reports that the session
-    /// already has a username set.
-    pub force_username: bool,
-    /// Password to use if room requires authentication.
-    pub password: Option<String>,
-}
-
-impl InstanceConfig {
-    pub fn new<S: ToString>(server: ServerConfig, room: S) -> Self {
-        Self {
-            server,
-            name: room.to_string(),
-            room: room.to_string(),
-            human: false,
-            username: None,
-            force_username: false,
-            password: None,
-        }
-    }
-
-    pub fn name<S: ToString>(mut self, name: S) -> Self {
-        self.name = name.to_string();
-        self
-    }
-
-    pub fn human(mut self, human: bool) -> Self {
-        self.human = human;
-        self
-    }
-
-    pub fn username<S: ToString>(mut self, username: Option<S>) -> Self {
-        self.username = username.map(|s| s.to_string());
-        self
-    }
-
-    pub fn force_username(mut self, force_username: bool) -> Self {
-        self.force_username = force_username;
-        self
-    }
-
-    pub fn password<S: ToString>(mut self, password: Option<S>) -> Self {
-        self.password = password.map(|s| s.to_string());
-        self
-    }
-
-    /// Create a new instance using this config.
-    ///
-    /// See [`Instance::new`] for more details.
-    pub fn build<F>(self, on_event: F) -> Instance
-    where
-        F: Fn(Event) + Send + Sync + 'static,
-    {
-        Instance::new(self, on_event)
-    }
-}
-
-/// Snapshot of a [`Conn`]'s state immediately after receiving a packet.
-#[derive(Debug, Clone)]
-pub struct ConnSnapshot {
-    pub conn_tx: ConnTx,
-    pub state: State,
-}
-
-impl ConnSnapshot {
-    fn from_conn(conn: &Conn) -> Self {
-        Self {
-            conn_tx: conn.tx().clone(),
-            state: conn.state().clone(),
-        }
-    }
-}
-
-// Most of the time, the largest variant (`Packet`) is sent. The size of this
-// enum is not critical anyways since it's not constructed that often.
-#[allow(clippy::large_enum_variant)]
-/// An event emitted by an [`Instance`].
-///
-/// Events are emitted by a single instance following this schema, written in
-/// pseudo-regex syntax:
-/// ```text
-/// (Connecting (Connected Packet*)? Disconnected)* Stopped
-/// ```
-///
-/// In particular, this means that every [`Self::Connecting`] is always followed
-/// by exactly one [`Self::Disconnected`], and that [`Self::Stopped`] is always
-/// the last event and is always sent exactly once per instance.
-#[derive(Debug)]
-pub enum Event {
-    Connecting(InstanceConfig),
-    Connected(InstanceConfig, ConnSnapshot),
-    Packet(InstanceConfig, ParsedPacket, ConnSnapshot),
-    Disconnected(InstanceConfig),
-    Stopped(InstanceConfig),
-}
-
-impl Event {
-    pub fn config(&self) -> &InstanceConfig {
-        match self {
-            Self::Connecting(config) => config,
-            Self::Connected(config, _) => config,
-            Self::Packet(config, _, _) => config,
-            Self::Disconnected(config) => config,
-            Self::Stopped(config) => config,
-        }
-    }
-}
-
-enum Request {
-    GetConnTx(oneshot::Sender<ConnTx>),
-    Stop,
-}
-
-/// An error that occurred inside an [`Instance`] while it was running.
-enum RunError {
-    StoppedManually,
-    InstanceDropped,
-    CouldNotConnect(conn::Error),
-    Conn(conn::Error),
-}
-
-/// A single instance of a bot in a single room.
-///
-/// The instance automatically connects to its room once it is created, and it
-/// reconnects when it loses connection. If the room requires authentication and
-/// a password is given, the instance automatically authenticates. If a nick is
-/// given, the instance sets its nick upon joining the room.
-///
-/// An instance has a unique name used for logging and identifying the instance.
-/// The room name can be used as the instance name if there is never more than
-/// one instance per room.
-///
-/// An instance can be created using [`Instance::new`] or using
-/// [`InstanceConfig::build`].
-///
-/// An instance can be stopped using [`Instance::stop`] or by dropping it. In
-/// either case, the last event the instance sends will be an
-/// [`Event::Stopped`]. If it is not stopped using one of these two ways, it
-/// will continue to run and reconnect indefinitely.
-#[derive(Debug, Clone)]
-pub struct Instance {
-    config: InstanceConfig,
-    request_tx: mpsc::UnboundedSender<Request>,
-    // In theory, request_tx should be sufficient as canary, but I'm not sure
-    // exactly how to check it during the reconnect timeout.
-    _canary_tx: mpsc::UnboundedSender<Infallible>,
-}
-
-impl Instance {
-    // Previously, the event callback was asynchronous and would return a result. It
-    // was called in-line to calling Conn::recv. The idea was that the instance
-    // would stop if the event handler returned Err. This was, however, not even
-    // implemented correctly and the instance would just reconnect.
-    //
-    // The new event handler is synchronous. This way, it becomes harder to
-    // accidentally block Conn::recv, for example by waiting for a channel with
-    // limited capacity. If async code must be executed upon receiving a command,
-    // the user can start a task from inside the handler.
-    //
-    // The new event handler does not return anything. This makes the code nicer. In
-    // the use cases I'm thinking of, it should not be a problem: If the event
-    // handler encounters errors, there's usually other ways to tell the same. Make
-    // the event handler ignore the errors and stop the instance in that other way.
-
-    /// Create a new instance based on an [`InstanceConfig`].
-    ///
-    /// The `on_event` parameter is called whenever the instance wants to emit
-    /// an [`Event`]. It must not block for long. See [`Event`] for more details
-    /// on the events and the order in which they are emitted.
-    ///
-    /// [`InstanceConfig::build`] can be used in place of this function.
-    pub fn new<F>(config: InstanceConfig, on_event: F) -> Self
-    where
-        F: Fn(Event) + Send + Sync + 'static,
-    {
-        idebug!(config, "Created with config {config:?}");
-
-        let (request_tx, request_rx) = mpsc::unbounded_channel();
-        let (canary_tx, canary_rx) = mpsc::unbounded_channel();
-
-        tokio::spawn(Self::run::<F>(
-            config.clone(),
-            on_event,
-            request_rx,
-            canary_rx,
-        ));
-
-        Self {
-            config,
-            request_tx,
-            _canary_tx: canary_tx,
-        }
-    }
-
-    pub fn config(&self) -> &InstanceConfig {
-        &self.config
-    }
-
-    /// Retrieve the instance's current connection.
-    ///
-    /// Returns `None` if the instance is currently not connected, or has
-    /// stopped running.
-    pub async fn conn_tx(&self) -> Option<ConnTx> {
-        let (tx, rx) = oneshot::channel();
-        let _ = self.request_tx.send(Request::GetConnTx(tx));
-        rx.await.ok()
-    }
-
-    /// Stop the instance.
-    ///
-    /// For more info on stopping instances, see [`Instance`].
-    pub fn stop(&self) {
-        let _ = self.request_tx.send(Request::Stop);
-    }
-
-    /// Whether this instance is stopped.
-    ///
-    /// For more info on stopping instances, see [`Instance`].
-    pub fn stopped(&self) -> bool {
-        self.request_tx.is_closed()
-    }
-
-    async fn run<F: Fn(Event)>(
-        config: InstanceConfig,
-        on_event: F,
-        request_rx: mpsc::UnboundedReceiver<Request>,
-        mut canary_rx: mpsc::UnboundedReceiver<Infallible>,
-    ) {
-        select! {
-            _ = Self::stay_connected(&config, &on_event, request_rx) => (),
-            _ = canary_rx.recv() => { idebug!(config, "Instance dropped"); },
-        }
-        on_event(Event::Stopped(config))
-    }
-
-    async fn stay_connected<F: Fn(Event)>(
-        config: &InstanceConfig,
-        on_event: &F,
-        mut request_rx: mpsc::UnboundedReceiver<Request>,
-    ) {
-        loop {
-            idebug!(config, "Connecting...");
-
-            on_event(Event::Connecting(config.clone()));
-            let result = Self::run_once::<F>(config, on_event, &mut request_rx).await;
-            on_event(Event::Disconnected(config.clone()));
-
-            let connected = match result {
-                Ok(()) => {
-                    idebug!(config, "Connection closed normally");
-                    true
-                }
-                Err(RunError::StoppedManually) => {
-                    idebug!(config, "Instance stopped manually");
-                    break;
-                }
-                Err(RunError::InstanceDropped) => {
-                    idebug!(config, "Instance dropped");
-                    break;
-                }
-                Err(RunError::CouldNotConnect(conn::Error::Tungstenite(
-                    tungstenite::Error::Http(response),
-                ))) if response.status() == StatusCode::NOT_FOUND => {
-                    iwarn!(config, "Failed to connect: room does not exist");
-                    break;
-                }
-                Err(RunError::CouldNotConnect(err)) => {
-                    iwarn!(config, "Failed to connect: {err}");
-                    false
-                }
-                Err(RunError::Conn(err)) => {
-                    iwarn!(config, "An error occurred: {err}");
-                    true
-                }
-            };
-
-            if !connected {
-                let s = config.server.reconnect_delay.as_secs();
-                idebug!(config, "Waiting {s} seconds before reconnecting");
-                tokio::time::sleep(config.server.reconnect_delay).await;
-            }
-        }
-    }
-
-    fn get_cookies(config: &InstanceConfig) -> HeaderValue {
-        let guard = config.server.cookies.lock().unwrap();
-        let cookies = guard
-            .iter()
-            .map(|c| format!("{}", c.stripped()))
-            .collect::<Vec<_>>()
-            .join("; ");
-        drop(guard);
-        cookies.try_into().unwrap()
-    }
-
-    fn set_cookies(config: &InstanceConfig, cookies: Vec<HeaderValue>) {
-        idebug!(config, "Updating cookies");
-        let mut guard = config.server.cookies.lock().unwrap();
-
-        for cookie in cookies {
-            if let Ok(cookie) = cookie.to_str() {
-                if let Ok(cookie) = Cookie::from_str(cookie) {
-                    guard.add(cookie);
-                }
-            }
-        }
-    }
-
-    async fn run_once<F: Fn(Event)>(
-        config: &InstanceConfig,
-        on_event: &F,
-        request_rx: &mut mpsc::UnboundedReceiver<Request>,
-    ) -> Result<(), RunError> {
-        let (mut conn, cookies) = Conn::connect(
-            &config.server.domain,
-            &config.room,
-            config.human,
-            Some(Self::get_cookies(config)),
-            config.server.timeout,
-        )
-        .await
-        .map_err(RunError::CouldNotConnect)?;
-
-        Self::set_cookies(config, cookies);
-        on_event(Event::Connected(
-            config.clone(),
-            ConnSnapshot::from_conn(&conn),
-        ));
-
-        let conn_tx = conn.tx().clone();
-        select! {
-            r = Self::receive::<F>(config, &mut conn, on_event) => r,
-            r = Self::handle_requests(request_rx, &conn_tx) => Err(r),
-        }
-    }
-
-    async fn receive<F: Fn(Event)>(
-        config: &InstanceConfig,
-        conn: &mut Conn,
-        on_event: &F,
-    ) -> Result<(), RunError> {
-        loop {
-            let packet = conn.recv().await.map_err(RunError::Conn)?;
-            let snapshot = ConnSnapshot::from_conn(conn);
-
-            match &packet.content {
-                Ok(Data::SnapshotEvent(snapshot)) => {
-                    if let Some(username) = &config.username {
-                        if config.force_username || snapshot.nick.is_none() {
-                            idebug!(config, "Setting nick to username {username}");
-                            let name = username.to_string();
-                            conn.tx().send_only(Nick { name });
-                        } else if let Some(nick) = &snapshot.nick {
-                            idebug!(config, "Not setting nick, already set to {nick}");
-                        }
-                    }
-                }
-                Ok(Data::BounceEvent(_)) => {
-                    if let Some(password) = &config.password {
-                        idebug!(config, "Authenticating with password");
-                        let cmd = Auth {
-                            r#type: AuthOption::Passcode,
-                            passcode: Some(password.to_string()),
-                        };
-                        conn.tx().send_only(cmd);
-                    } else {
-                        iwarn!(config, "Auth required but no password configured");
-                    }
-                }
-                Ok(Data::DisconnectEvent(ev)) => {
-                    if ev.reason == "authentication changed" {
-                        iinfo!(config, "Disconnected because {}", ev.reason);
-                    } else {
-                        iwarn!(config, "Disconnected because {}", ev.reason);
-                    }
-                }
-                _ => {}
-            }
-
-            on_event(Event::Packet(config.clone(), packet, snapshot));
-        }
-    }
-
-    async fn handle_requests(
-        request_rx: &mut mpsc::UnboundedReceiver<Request>,
-        conn_tx: &ConnTx,
-    ) -> RunError {
-        while let Some(request) = request_rx.recv().await {
-            match request {
-                Request::GetConnTx(tx) => {
-                    let _ = tx.send(conn_tx.clone());
-                }
-                Request::Stop => return RunError::StoppedManually,
-            }
-        }
-        RunError::InstanceDropped
-    }
-}

src/bot/instances.rs

@@ -1,70 +0,0 @@
-//! A convenient way to keep a [`ServerConfig`] and some [`Instance`]s.
-
-use std::collections::HashMap;
-
-use super::instance::{self, Instance, ServerConfig};
-
-/// A convenient way to keep a [`ServerConfig`] and some [`Instance`]s.
-pub struct Instances {
-    server_config: ServerConfig,
-    instances: HashMap<String, Instance>,
-}
-
-impl Instances {
-    pub fn new(server_config: ServerConfig) -> Self {
-        Self {
-            server_config,
-            instances: HashMap::new(),
-        }
-    }
-
-    pub fn server_config(&self) -> &ServerConfig {
-        &self.server_config
-    }
-
-    pub fn instances(&self) -> impl Iterator<Item = &Instance> {
-        self.instances.values()
-    }
-
-    /// Check if an event comes from an instance whose name is known.
-    ///
-    /// Assuming every instance has a unique name, events from unknown instances
-    /// should be discarded. This helps prevent "ghost instances" that were
-    /// stopped but haven't yet disconnected properly from influencing your
-    /// bot's state.
-    ///
-    /// The user is responsible for ensuring that instances' names are unique.
-    pub fn is_from_known_instance(&self, event: &instance::Event) -> bool {
-        self.instances.contains_key(&event.config().name)
-    }
-
-    pub fn is_empty(&self) -> bool {
-        self.instances.is_empty()
-    }
-
-    /// Get an instance by its name.
-    pub fn get(&self, name: &str) -> Option<&Instance> {
-        self.instances.get(name)
-    }
-
-    /// Add a new instance.
-    ///
-    /// If an instance with the same name exists already, it will be replaced by
-    /// the new instance.
-    pub fn add(&mut self, instance: Instance) {
-        self.instances
-            .insert(instance.config().name.clone(), instance);
-    }
-
-    /// Remove an instance by its name.
-    pub fn remove(&mut self, name: &str) -> Option<Instance> {
-        self.instances.remove(name)
-    }
-
-    /// Remove all stopped instances.
-    ///
-    /// This function should be called regularly.
-    pub fn purge(&mut self) {
-        self.instances.retain(|_, i| !i.stopped());
-    }
-}

src/conn.rs

@@ -1,642 +0,0 @@
-//! Connection state modeling.
-
-use std::collections::HashMap;
-use std::convert::Infallible;
-use std::future::Future;
-use std::time::{Duration, Instant};
-use std::{error, fmt, result};
-
-use futures_util::SinkExt;
-use jiff::Timestamp;
-use log::debug;
-use tokio::net::TcpStream;
-use tokio::select;
-use tokio::sync::{mpsc, oneshot};
-use tokio_stream::StreamExt;
-use tokio_tungstenite::tungstenite::client::IntoClientRequest;
-use tokio_tungstenite::tungstenite::http::{header, HeaderValue};
-use tokio_tungstenite::{tungstenite, MaybeTlsStream, WebSocketStream};
-
-use crate::api::packet::{Command, ParsedPacket};
-use crate::api::{
-    BounceEvent, Data, HelloEvent, LoginReply, NickEvent, PersonalAccountView, Ping, PingReply,
-    SessionId, SessionView, SnapshotEvent, Time, UserId,
-};
-use crate::replies::{self, PendingReply, Replies};
-
-pub type WsStream = WebSocketStream<MaybeTlsStream<TcpStream>>;
-
-#[derive(Debug)]
-pub enum Error {
-    /// The connection is now closed.
-    ConnectionClosed,
-    /// The connection was not opened in time.
-    ConnectionTimedOut,
-    /// The server didn't reply to one of our commands in time.
-    CommandTimedOut,
-    /// The server did something that violated the api specification.
-    ProtocolViolation(&'static str),
-    /// An error returned by the euphoria server.
-    Euph(String),
-
-    Tungstenite(tungstenite::Error),
-    SerdeJson(serde_json::Error),
-}
-
-impl fmt::Display for Error {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        match self {
-            Self::ConnectionClosed => write!(f, "connection closed"),
-            Self::ConnectionTimedOut => write!(f, "connection did not open in time"),
-            Self::CommandTimedOut => write!(f, "server did not reply to command in time"),
-            Self::ProtocolViolation(msg) => write!(f, "{msg}"),
-            Self::Euph(msg) => write!(f, "{msg}"),
-            Self::Tungstenite(err) => write!(f, "{err}"),
-            Self::SerdeJson(err) => write!(f, "{err}"),
-        }
-    }
-}
-
-impl From<tungstenite::Error> for Error {
-    fn from(err: tungstenite::Error) -> Self {
-        Self::Tungstenite(err)
-    }
-}
-
-impl From<serde_json::Error> for Error {
-    fn from(err: serde_json::Error) -> Self {
-        Self::SerdeJson(err)
-    }
-}
-
-impl error::Error for Error {}
-
-pub type Result<T> = result::Result<T, Error>;
-
-#[derive(Debug, Clone)]
-pub struct Joining {
-    pub since: Timestamp,
-    pub hello: Option<HelloEvent>,
-    pub snapshot: Option<SnapshotEvent>,
-    pub bounce: Option<BounceEvent>,
-}
-
-impl Joining {
-    fn new() -> Self {
-        Self {
-            since: Timestamp::now(),
-            hello: None,
-            snapshot: None,
-            bounce: None,
-        }
-    }
-
-    fn on_data(&mut self, data: &Data) -> Result<()> {
-        match data {
-            Data::BounceEvent(p) => self.bounce = Some(p.clone()),
-            Data::HelloEvent(p) => self.hello = Some(p.clone()),
-            Data::SnapshotEvent(p) => self.snapshot = Some(p.clone()),
-            // TODO Check and maybe expand list of unexpected packet types
-            Data::JoinEvent(_)
-            | Data::NetworkEvent(_)
-            | Data::NickEvent(_)
-            | Data::EditMessageEvent(_)
-            | Data::PartEvent(_)
-            | Data::PmInitiateEvent(_)
-            | Data::SendEvent(_) => return Err(Error::ProtocolViolation("unexpected packet type")),
-            _ => {}
-        }
-        Ok(())
-    }
-
-    fn joined(&self) -> Option<Joined> {
-        if let (Some(hello), Some(snapshot)) = (&self.hello, &self.snapshot) {
-            let mut session = hello.session.clone();
-            if let Some(nick) = &snapshot.nick {
-                session.name = nick.clone();
-            }
-            let listing = snapshot
-                .listing
-                .iter()
-                .cloned()
-                .map(|s| (s.session_id.clone(), SessionInfo::Full(s)))
-                .collect::<HashMap<_, _>>();
-            Some(Joined {
-                since: Timestamp::now(),
-                session,
-                account: hello.account.clone(),
-                listing,
-            })
-        } else {
-            None
-        }
-    }
-}
-
-#[derive(Debug, Clone)]
-pub enum SessionInfo {
-    Full(SessionView),
-    Partial(NickEvent),
-}
-
-impl SessionInfo {
-    pub fn id(&self) -> &UserId {
-        match self {
-            Self::Full(sess) => &sess.id,
-            Self::Partial(nick) => &nick.id,
-        }
-    }
-
-    pub fn session_id(&self) -> &SessionId {
-        match self {
-            Self::Full(sess) => &sess.session_id,
-            Self::Partial(nick) => &nick.session_id,
-        }
-    }
-
-    pub fn name(&self) -> &str {
-        match self {
-            Self::Full(sess) => &sess.name,
-            Self::Partial(nick) => &nick.to,
-        }
-    }
-}
-
-#[derive(Debug, Clone)]
-pub struct Joined {
-    pub since: Timestamp,
-    pub session: SessionView,
-    pub account: Option<PersonalAccountView>,
-    pub listing: HashMap<SessionId, SessionInfo>,
-}
-
-impl Joined {
-    fn on_data(&mut self, data: &Data) {
-        match data {
-            Data::JoinEvent(p) => {
-                debug!("Updating listing after join-event");
-                self.listing
-                    .insert(p.0.session_id.clone(), SessionInfo::Full(p.0.clone()));
-            }
-            Data::SendEvent(p) => {
-                debug!("Updating listing after send-event");
-                self.listing.insert(
-                    p.0.sender.session_id.clone(),
-                    SessionInfo::Full(p.0.sender.clone()),
-                );
-            }
-            Data::PartEvent(p) => {
-                debug!("Updating listing after part-event");
-                self.listing.remove(&p.0.session_id);
-            }
-            Data::NetworkEvent(p) => {
-                if p.r#type == "partition" {
-                    debug!("Updating listing after network-event with type partition");
-                    self.listing.retain(|_, s| match s {
-                        SessionInfo::Full(s) => {
-                            s.server_id != p.server_id && s.server_era != p.server_era
-                        }
-                        // We can't know if the session was disconnected by the
-                        // partition or not, so we're erring on the side of
-                        // caution and assuming they were kicked. If we're
-                        // wrong, we'll re-add the session as soon as it
-                        // performs another visible action.
-                        //
-                        // If we always kept such sessions, we might keep
-                        // disconnected ones indefinitely, thereby keeping them
-                        // from moving on, instead forever tethering them to the
-                        // digital realm.
-                        SessionInfo::Partial(_) => false,
-                    });
-                }
-            }
-            Data::NickEvent(p) => {
-                debug!("Updating listing after nick-event");
-                self.listing
-                    .entry(p.session_id.clone())
-                    .and_modify(|s| match s {
-                        SessionInfo::Full(session) => session.name = p.to.clone(),
-                        SessionInfo::Partial(_) => *s = SessionInfo::Partial(p.clone()),
-                    })
-                    .or_insert_with(|| SessionInfo::Partial(p.clone()));
-            }
-            Data::NickReply(p) => {
-                debug!("Updating own session after nick-reply");
-                assert_eq!(self.session.id, p.id);
-                self.session.name = p.to.clone();
-            }
-            // The who reply is broken and can't be trusted right now, so we'll
-            // not even look at it.
-            _ => {}
-        }
-    }
-}
-
-#[derive(Debug, Clone)]
-#[allow(clippy::large_enum_variant)]
-pub enum State {
-    Joining(Joining),
-    Joined(Joined),
-}
-
-impl State {
-    pub fn into_joining(self) -> Option<Joining> {
-        match self {
-            Self::Joining(joining) => Some(joining),
-            Self::Joined(_) => None,
-        }
-    }
-
-    pub fn into_joined(self) -> Option<Joined> {
-        match self {
-            Self::Joining(_) => None,
-            Self::Joined(joined) => Some(joined),
-        }
-    }
-
-    pub fn joining(&self) -> Option<&Joining> {
-        match self {
-            Self::Joining(joining) => Some(joining),
-            Self::Joined(_) => None,
-        }
-    }
-
-    pub fn joined(&self) -> Option<&Joined> {
-        match self {
-            Self::Joining(_) => None,
-            Self::Joined(joined) => Some(joined),
-        }
-    }
-}
-
-#[allow(clippy::large_enum_variant)]
-enum ConnCommand {
-    SendCmd(Data, oneshot::Sender<PendingReply<ParsedPacket>>),
-    GetState(oneshot::Sender<State>),
-}
-
-#[derive(Debug, Clone)]
-pub struct ConnTx {
-    cmd_tx: mpsc::UnboundedSender<ConnCommand>,
-}
-
-impl ConnTx {
-    /// The async part of sending a command.
-    ///
-    /// This is split into a separate function so that [`Self::send`] can be
-    /// fully synchronous (you can safely throw away the returned future) while
-    /// still guaranteeing that the packet was sent.
-    async fn finish_send<C>(rx: oneshot::Receiver<PendingReply<ParsedPacket>>) -> Result<C::Reply>
-    where
-        C: Command,
-        C::Reply: TryFrom<Data>,
-    {
-        let pending_reply = rx
-            .await
-            // This should only happen if something goes wrong during encoding
-            // of the packet or while sending it through the websocket. Assuming
-            // the first doesn't happen, the connection is probably closed.
-            .map_err(|_| Error::ConnectionClosed)?;
-
-        let data = pending_reply
-            .get()
-            .await
-            .map_err(|e| match e {
-                replies::Error::TimedOut => Error::CommandTimedOut,
-                replies::Error::Canceled => Error::ConnectionClosed,
-            })?
-            .content
-            .map_err(Error::Euph)?;
-
-        data.try_into()
-            .map_err(|_| Error::ProtocolViolation("incorrect command reply type"))
-    }
-
-    /// Send a command to the server.
-    ///
-    /// Returns a future containing the server's reply. This future does not
-    /// have to be awaited and can be safely ignored if you are not interested
-    /// in the reply.
-    ///
-    /// This function may return before the command was sent. To ensure that it
-    /// was sent before doing something else, await the returned future first.
-    ///
-    /// When called multiple times, this function guarantees that the commands
-    /// are sent in the order that the function is called.
-    pub fn send<C>(&self, cmd: C) -> impl Future<Output = Result<C::Reply>>
-    where
-        C: Command + Into<Data>,
-        C::Reply: TryFrom<Data>,
-    {
-        let (tx, rx) = oneshot::channel();
-        let _ = self.cmd_tx.send(ConnCommand::SendCmd(cmd.into(), tx));
-        Self::finish_send::<C>(rx)
-    }
-
-    /// Like [`Self::send`] but ignoring the server's reply.
-    pub fn send_only<C: Into<Data>>(&self, cmd: C) {
-        let (tx, _) = oneshot::channel();
-        let _ = self.cmd_tx.send(ConnCommand::SendCmd(cmd.into(), tx));
-    }
-
-    pub async fn state(&self) -> Result<State> {
-        let (tx, rx) = oneshot::channel();
-        self.cmd_tx
-            .send(ConnCommand::GetState(tx))
-            .map_err(|_| Error::ConnectionClosed)?;
-        rx.await.map_err(|_| Error::ConnectionClosed)
-    }
-}
-
-#[derive(Debug)]
-pub struct Conn {
-    ws: WsStream,
-    last_id: usize,
-    replies: Replies<String, ParsedPacket>,
-
-    conn_tx: ConnTx,
-    cmd_rx: mpsc::UnboundedReceiver<ConnCommand>,
-
-    // The websocket server may send a pong frame with arbitrary payload
-    // unprompted at any time (see RFC 6455 5.5.3). Because of this, we can't
-    // just remember the last pong payload.
-    last_ping: Instant,
-    last_ws_ping_payload: Option<Vec<u8>>,
-    last_ws_ping_replied_to: bool,
-    last_euph_ping_payload: Option<Time>,
-    last_euph_ping_replied_to: bool,
-
-    state: State,
-}
-
-enum ConnEvent {
-    Ws(Option<tungstenite::Result<tungstenite::Message>>),
-    Cmd(Option<ConnCommand>),
-    Ping,
-}
-
-impl Conn {
-    pub fn tx(&self) -> &ConnTx {
-        &self.conn_tx
-    }
-
-    pub fn state(&self) -> &State {
-        &self.state
-    }
-
-    pub async fn recv(&mut self) -> Result<ParsedPacket> {
-        loop {
-            self.replies.purge();
-            let timeout = self.replies.timeout();
-
-            // All of these functions are cancel-safe.
-            let event = select! {
-                msg = self.ws.next() => ConnEvent::Ws(msg),
-                cmd = self.cmd_rx.recv() => ConnEvent::Cmd(cmd),
-                _ = Self::await_next_ping(self.last_ping, timeout) => ConnEvent::Ping,
-            };
-
-            match event {
-                ConnEvent::Ws(msg) => {
-                    if let Some(packet) = self.on_ws(msg).await? {
-                        break Ok(packet);
-                    }
-                }
-                ConnEvent::Cmd(Some(cmd)) => self.on_cmd(cmd).await?,
-                ConnEvent::Cmd(None) => unreachable!("self contains a ConnTx"),
-                ConnEvent::Ping => self.on_ping().await?,
-            }
-        }
-    }
-
-    async fn on_ws(
-        &mut self,
-        msg: Option<tungstenite::Result<tungstenite::Message>>,
-    ) -> Result<Option<ParsedPacket>> {
-        let msg = msg.ok_or(Error::ConnectionClosed)??;
-        match msg {
-            tungstenite::Message::Text(text) => {
-                let packet = serde_json::from_str(&text)?;
-                debug!(target: "euphoxide::conn::full", "Received {packet:?}");
-                let packet = ParsedPacket::from_packet(packet)?;
-                self.on_packet(&packet).await?;
-                return Ok(Some(packet));
-            }
-            tungstenite::Message::Binary(_) => {
-                return Err(Error::ProtocolViolation("unexpected binary ws message"));
-            }
-            tungstenite::Message::Ping(_) => {}
-            tungstenite::Message::Pong(payload) => {
-                if self.last_ws_ping_payload == Some(payload) {
-                    self.last_ws_ping_replied_to = true;
-                }
-            }
-            tungstenite::Message::Close(_) => {}
-            tungstenite::Message::Frame(_) => {}
-        }
-        Ok(None)
-    }
-
-    async fn on_packet(&mut self, packet: &ParsedPacket) -> Result<()> {
-        // Complete pending replies if the packet has an id
-        if let Some(id) = &packet.id {
-            debug!("Resolving pending reply for id {id}");
-            self.replies.complete(id, packet.clone());
-        }
-
-        if let Ok(data) = &packet.content {
-            self.on_data(&packet.id, data).await?;
-        }
-
-        Ok(())
-    }
-
-    async fn on_data(&mut self, id: &Option<String>, data: &Data) -> Result<()> {
-        // Play a game of table tennis
-        match data {
-            Data::PingReply(p) => {
-                if self.last_euph_ping_payload.is_some() && self.last_euph_ping_payload == p.time {
-                    self.last_euph_ping_replied_to = true;
-                }
-            }
-            Data::PingEvent(p) => {
-                let reply = PingReply { time: Some(p.time) };
-                self.send_rpl(id.clone(), reply.into()).await?;
-            }
-            _ => {}
-        }
-
-        // Update internal state
-        match &mut self.state {
-            State::Joining(joining) => {
-                joining.on_data(data)?;
-                if let Some(joined) = joining.joined() {
-                    self.state = State::Joined(joined);
-                }
-            }
-            State::Joined(joined) => joined.on_data(data),
-        }
-
-        // The euphoria server doesn't always disconnect the client when it
-        // would make sense to do so or when the API specifies it should. This
-        // ensures we always disconnect when it makes sense to do so.
-        if matches!(
-            data,
-            Data::DisconnectEvent(_)
-                | Data::LoginEvent(_)
-                | Data::LogoutEvent(_)
-                | Data::LoginReply(LoginReply { success: true, .. })
-                | Data::LogoutReply(_)
-        ) {
-            self.disconnect().await?;
-        }
-
-        Ok(())
-    }
-
-    async fn on_cmd(&mut self, cmd: ConnCommand) -> Result<()> {
-        match cmd {
-            ConnCommand::SendCmd(data, reply_tx) => self.send_cmd(data, reply_tx).await?,
-            ConnCommand::GetState(reply_tx) => {
-                let _ = reply_tx.send(self.state.clone());
-            }
-        }
-        Ok(())
-    }
-
-    async fn await_next_ping(last_ping: Instant, timeout: Duration) {
-        let next_ping = last_ping + timeout;
-        tokio::time::sleep_until(next_ping.into()).await;
-    }
-
-    async fn on_ping(&mut self) -> Result<()> {
-        debug!("Checking ping replies and sending new pings");
-
-        // Check previous pings
-        if self.last_ws_ping_payload.is_some() && !self.last_ws_ping_replied_to {
-            debug!("Server did not respond to websocket ping, disconnecting");
-            self.disconnect().await?;
-        }
-        if self.last_euph_ping_payload.is_some() && !self.last_euph_ping_replied_to {
-            debug!("Server did not respond to euph ping, disconnecting");
-            self.disconnect().await?;
-        }
-
-        let now = Timestamp::now();
-
-        // Send new ws ping
-        let ws_payload = now.as_millisecond().to_be_bytes().to_vec();
-        self.last_ws_ping_payload = Some(ws_payload.clone());
-        self.last_ws_ping_replied_to = false;
-        self.ws.send(tungstenite::Message::Ping(ws_payload)).await?;
-
-        // Send new euph ping
-        let euph_payload = Time::from_timestamp(now);
-        self.last_euph_ping_payload = Some(euph_payload);
-        self.last_euph_ping_replied_to = false;
-        let (tx, _) = oneshot::channel();
-        self.send_cmd(Ping { time: euph_payload }.into(), tx)
-            .await?;
-
-        self.last_ping = Instant::now();
-
-        Ok(())
-    }
-
-    async fn send_cmd(
-        &mut self,
-        data: Data,
-        reply_tx: oneshot::Sender<PendingReply<ParsedPacket>>,
-    ) -> Result<()> {
-        // Overkill of universe-heat-death-like proportions
-        self.last_id = self.last_id.wrapping_add(1);
-        let id = format!("{}", self.last_id);
-
-        let packet = ParsedPacket {
-            id: Some(id.clone()),
-            r#type: data.packet_type(),
-            content: Ok(data),
-            throttled: None,
-        }
-        .into_packet()?;
-        debug!(target: "euphoxide::conn::full", "Sending {packet:?}");
-
-        let msg = tungstenite::Message::Text(serde_json::to_string(&packet)?);
-        self.ws.send(msg).await?;
-
-        let _ = reply_tx.send(self.replies.wait_for(id));
-
-        Ok(())
-    }
-
-    async fn send_rpl(&mut self, id: Option<String>, data: Data) -> Result<()> {
-        let packet = ParsedPacket {
-            id,
-            r#type: data.packet_type(),
-            content: Ok(data),
-            throttled: None,
-        }
-        .into_packet()?;
-        debug!(target: "euphoxide::conn::full", "Sending {packet:?}");
-
-        let msg = tungstenite::Message::Text(serde_json::to_string(&packet)?);
-        self.ws.send(msg).await?;
-
-        Ok(())
-    }
-
-    async fn disconnect(&mut self) -> Result<Infallible> {
-        let _ = tokio::time::timeout(self.replies.timeout(), self.ws.close(None)).await;
-        debug!("Closed connection");
-        Err(Error::ConnectionClosed)
-    }
-
-    pub fn wrap(ws: WsStream, timeout: Duration) -> Self {
-        let (cmd_tx, cmd_rx) = mpsc::unbounded_channel();
-        Self {
-            ws,
-            last_id: 0,
-            replies: Replies::new(timeout),
-
-            conn_tx: ConnTx { cmd_tx },
-            cmd_rx,
-
-            last_ping: Instant::now(), // Wait a bit before first pings
-            last_ws_ping_payload: None,
-            last_ws_ping_replied_to: false,
-            last_euph_ping_payload: None,
-            last_euph_ping_replied_to: false,
-
-            state: State::Joining(Joining::new()),
-        }
-    }
-
-    pub async fn connect(
-        domain: &str,
-        room: &str,
-        human: bool,
-        cookies: Option<HeaderValue>,
-        timeout: Duration,
-    ) -> Result<(Self, Vec<HeaderValue>)> {
-        let human = if human { "?h=1" } else { "" };
-        let uri = format!("wss://{domain}/room/{room}/ws{human}");
-        debug!("Connecting to {uri} with cookies: {cookies:?}");
-        let mut request = uri.into_client_request().expect("valid request");
-        if let Some(cookies) = cookies {
-            request.headers_mut().append(header::COOKIE, cookies);
-        }
-
-        let (ws, response) =
-            tokio::time::timeout(timeout, tokio_tungstenite::connect_async(request))
-                .await
-                .map_err(|_| Error::ConnectionTimedOut)??;
-        let (mut parts, _) = response.into_parts();
-        let cookies_set = match parts.headers.entry(header::SET_COOKIE) {
-            header::Entry::Occupied(entry) => entry.remove_entry_mult().1.collect(),
-            header::Entry::Vacant(_) => vec![],
-        };
-        debug!("Received cookies {cookies_set:?}");
-        let rx = Self::wrap(ws, timeout);
-        Ok((rx, cookies_set))
-    }
-}

src/emoji.rs

@@ -1,195 +0,0 @@
-//! All emoji the euphoria.leet.nu client knows.
-
-use std::borrow::Cow;
-use std::collections::HashMap;
-use std::ops::RangeInclusive;
-
-/// Euphoria.leet.nu emoji list, obtainable via shell command:
-///
-/// ```bash
-/// curl 'https://euphoria.leet.nu/static/emoji.json' \
-///   | jq 'to_entries | sort_by(.key) | from_entries' \
-///   > emoji.json
-/// ```
-const EMOJI_JSON: &str = include_str!("emoji.json");
-
-/// A map from emoji names to their unicode representation. Not all emojis have
-/// such a representation.
-pub struct Emoji(pub HashMap<String, Option<String>>);
-
-fn parse_hex_to_char(hex: &str) -> Option<char> {
-    u32::from_str_radix(hex, 16).ok()?.try_into().ok()
-}
-
-fn parse_code_points(code_points: &str) -> Option<String> {
-    code_points
-        .split('-')
-        .map(parse_hex_to_char)
-        .collect::<Option<String>>()
-}
-
-impl Emoji {
-    /// Load a list of emoji compiled into the library.
-    pub fn load() -> Self {
-        Self::load_from_json(EMOJI_JSON).unwrap()
-    }
-
-    /// Load a list of emoji from a string containing a JSON object.
-    ///
-    /// The object keys are the emoji names (without colons `:`). The object
-    /// values are the emoji code points encoded as hexadecimal numbers and
-    /// separated by a dash `-` (e.g. `"34-fe0f-20e3"`). Emojis whose values
-    /// don't match this schema are interpreted as emojis without unicode
-    /// representation.
-    pub fn load_from_json(json: &str) -> Option<Self> {
-        let map = serde_json::from_str::<HashMap<String, String>>(json)
-            .ok()?
-            .into_iter()
-            .map(|(k, v)| (k, parse_code_points(&v)))
-            .collect::<HashMap<_, _>>();
-
-        Some(Self(map))
-    }
-
-    pub fn get(&self, name: &str) -> Option<Option<&str>> {
-        match self.0.get(name) {
-            Some(Some(replace)) => Some(Some(replace)),
-            Some(None) => Some(None),
-            None => None,
-        }
-    }
-
-    pub fn find(&self, text: &str) -> Vec<(RangeInclusive<usize>, Option<&str>)> {
-        let mut result = vec![];
-
-        let mut prev_colon_idx = None;
-        for (colon_idx, _) in text.match_indices(':') {
-            if let Some(prev_idx) = prev_colon_idx {
-                let name = &text[prev_idx + 1..colon_idx];
-                if let Some(replace) = self.get(name) {
-                    let range = prev_idx..=colon_idx;
-                    result.push((range, replace));
-                    prev_colon_idx = None;
-                    continue;
-                }
-            }
-            prev_colon_idx = Some(colon_idx);
-        }
-
-        result
-    }
-
-    pub fn replace<'a>(&self, text: &'a str) -> Cow<'a, str> {
-        let emoji = self.find(text);
-        if emoji.is_empty() {
-            return Cow::Borrowed(text);
-        }
-
-        let mut result = String::new();
-
-        let mut after_last_emoji = 0;
-        for (range, replace) in emoji {
-            // Only replace emoji with a replacement
-            if let Some(replace) = replace {
-                if *range.start() > after_last_emoji {
-                    // There were non-emoji characters between the last and the
-                    // current emoji.
-                    result.push_str(&text[after_last_emoji..*range.start()]);
-                }
-                result.push_str(replace);
-                after_last_emoji = range.end() + 1;
-            }
-        }
-
-        if after_last_emoji < text.len() {
-            result.push_str(&text[after_last_emoji..]);
-        }
-
-        Cow::Owned(result)
-    }
-
-    pub fn remove<'a>(&self, text: &'a str) -> Cow<'a, str> {
-        let emoji = self.find(text);
-        if emoji.is_empty() {
-            return Cow::Borrowed(text);
-        }
-
-        let mut result = String::new();
-
-        let mut after_last_emoji = 0;
-        for (range, _) in emoji {
-            if *range.start() > after_last_emoji {
-                // There were non-emoji characters between the last and the
-                // current emoji.
-                result.push_str(&text[after_last_emoji..*range.start()]);
-            }
-            after_last_emoji = range.end() + 1;
-        }
-
-        if after_last_emoji < text.len() {
-            result.push_str(&text[after_last_emoji..]);
-        }
-
-        Cow::Owned(result)
-    }
-}
-
-#[cfg(test)]
-mod test {
-    use super::Emoji;
-
-    #[test]
-    fn load_without_panic() {
-        Emoji::load();
-    }
-
-    #[test]
-    fn find() {
-        let emoji = Emoji::load();
-
-        // :bad: does not exist, while :x: and :o: do.
-
-        assert_eq!(emoji.find(":bad:x:o:"), vec![(4..=6, Some("❌"))]);
-        assert_eq!(
-            emoji.find(":x:bad:o:"),
-            vec![(0..=2, Some("❌")), (6..=8, Some("⭕"))]
-        );
-        assert_eq!(emoji.find("ab:bad:x:o:cd"), vec![(6..=8, Some("❌"))]);
-        assert_eq!(
-            emoji.find("ab:x:bad:o:cd"),
-            vec![(2..=4, Some("❌")), (8..=10, Some("⭕"))]
-        );
-    }
-
-    #[test]
-    fn replace() {
-        let emoji = Emoji::load();
-        assert_eq!(emoji.replace("no:emo:ji:here"), "no:emo:ji:here");
-        assert_eq!(emoji.replace(":bad:x:o:"), ":bad❌o:");
-        assert_eq!(emoji.replace(":x:bad:o:"), "❌bad⭕");
-        assert_eq!(emoji.replace("ab:bad:x:o:cd"), "ab:bad❌o:cd");
-        assert_eq!(emoji.replace("ab:x:bad:o:cd"), "ab❌bad⭕cd");
-        assert_eq!(emoji.replace("chᴜm:crown::ant:"), "chᴜm👑🐜");
-        assert_eq!(
-            emoji.replace(":waning_crescent_moon: (2% full)"),
-            "🌘 (2% full)"
-        );
-        assert_eq!(emoji.replace("Jan-20 17:58 Z"), "Jan-20 17:58 Z");
-    }
-
-    #[test]
-    fn remove() {
-        let emoji = Emoji::load();
-        assert_eq!(emoji.remove("no:emo:ji:here"), "no:emo:ji:here");
-        assert_eq!(emoji.remove(":bad:x:o:"), ":bado:");
-        assert_eq!(emoji.remove(":x:bad:o:"), "bad");
-        assert_eq!(emoji.remove("ab:bad:x:o:cd"), "ab:bado:cd");
-        assert_eq!(emoji.remove("ab:x:bad:o:cd"), "abbadcd");
-        assert_eq!(emoji.remove("chᴜm:crown::ant:"), "chᴜm");
-        assert_eq!(
-            emoji.remove(":waning_crescent_moon: (2% full)"),
-            " (2% full)"
-        );
-        assert_eq!(emoji.remove("Jan-20 17:58 Z"), "Jan-20 17:58 Z");
-    }
-}