dictserv: opt-in DICT (RFC 2229) lookup service — bots and /msg answer dict/define/thes/acronym/law/etc via dict.org off-reactor

src/config.rs

@@ -45,6 +45,10 @@ pub struct Config {
     // credentials (`kc_…` over SASL) are not honoured.
     #[serde(default)]
     pub keycard: Option<Keycard>,
+    // DictServ dictionary lookups (dict.org / RFC 2229). Absent = the service does
+    // not load and echo makes no outbound lookup requests. Opt-in on purpose.
+    #[serde(default)]
+    pub dictserv: Option<Dict>,
     // Which InspIRCd matching-extbans AKICK may use. Absent = every extban echo
     // knows (full compatibility). List `enabled` to restrict it — e.g. drop the
     // ones your ircd doesn't provide.
@@ -69,6 +73,18 @@ pub struct Keycard {
     pub api_key: String,
 }
 
+// DictServ. `server` is a DICT-protocol endpoint (RFC 2229); dict.org hosts the
+// standard databases (WordNet, GCIDE, thesaurus, …).
+#[derive(Debug, Deserialize, Clone)]
+pub struct Dict {
+    #[serde(default = "default_dict_server")]
+    pub server: String,
+}
+
+fn default_dict_server() -> String {
+    "dict.org:2628".to_string()
+}
+
 // Account-authority configuration.
 #[derive(Debug, Deserialize, Clone)]
 pub struct Auth {

src/dict.rs

@@ -0,0 +1,143 @@
+//! A tiny DICT-protocol (RFC 2229) client used by DictServ. Runs off the reactor
+//! (spawned from the link layer), connects to a DICT server, asks for one
+//! definition, and returns a single truncated line to speak into the channel. The
+//! response parser is split out so it can be tested without a network.
+
+use std::time::Duration;
+use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
+use tokio::net::TcpStream;
+
+const TIMEOUT: Duration = Duration::from_secs(6);
+const MAX_LEN: usize = 400; // keep a spoken reply to about one IRC line
+
+// Look `word` up in `database` on `server`. Never errors out to the caller: on a
+// timeout, connection failure, or no match it returns a short human message, so
+// the bot always has something safe to say.
+pub async fn lookup(server: &str, database: &str, word: &str) -> String {
+    let word = sanitize(word);
+    if word.is_empty() {
+        return "nothing to look up.".to_string();
+    }
+    match tokio::time::timeout(TIMEOUT, exchange(server, database, &word)).await {
+        Ok(Ok(Some(def))) => def,
+        Ok(Ok(None)) => format!("no definition found for \x02{word}\x02."),
+        Ok(Err(_)) | Err(_) => "the dictionary is unavailable right now.".to_string(),
+    }
+}
+
+// One request/response round trip. Returns the first definition's text, or None
+// for a clean "no match".
+async fn exchange(server: &str, database: &str, word: &str) -> std::io::Result<Option<String>> {
+    let stream = TcpStream::connect(server).await?;
+    stream.set_nodelay(true).ok();
+    let (rd, mut wr) = stream.into_split();
+    let mut lines = BufReader::new(rd).lines();
+    // Banner (220 …).
+    lines.next_line().await?;
+    wr.write_all(format!("DEFINE {database} \"{word}\"\r\n").as_bytes()).await?;
+    let mut raw = String::new();
+    while let Some(line) = lines.next_line().await? {
+        // 250 ends the whole response; stop reading once we've seen it.
+        if line.starts_with("250 ") {
+            break;
+        }
+        raw.push_str(&line);
+        raw.push('\n');
+        if raw.len() > MAX_LEN * 8 {
+            break; // guard against a runaway server
+        }
+    }
+    let _ = wr.write_all(b"QUIT\r\n").await;
+    Ok(parse_definition(&raw))
+}
+
+// Extract the first definition's body from a DICT DEFINE response. `raw` is the
+// lines after the `DEFINE` command (excluding the final 250). Returns None for a
+// no-match (552) or an empty body.
+fn parse_definition(raw: &str) -> Option<String> {
+    let mut body = String::new();
+    let mut in_def = false;
+    for line in raw.lines() {
+        if !in_def {
+            match line.get(..3) {
+                Some("552") | Some("550") | Some("551") => return None, // no match / bad db
+                Some("151") => in_def = true, // start of the first definition block
+                _ => {}                       // 220 banner, 150 count, …
+            }
+            continue;
+        }
+        // Body runs until a lone "." — take just the first definition.
+        if line == "." {
+            break;
+        }
+        let text = line.strip_prefix("..").unwrap_or(line).trim(); // undo dot-stuffing
+        if !text.is_empty() {
+            if !body.is_empty() {
+                body.push(' ');
+            }
+            body.push_str(text);
+        }
+        if body.len() >= MAX_LEN {
+            break;
+        }
+    }
+    let body: String = body.split_whitespace().collect::<Vec<_>>().join(" ");
+    if body.is_empty() {
+        return None;
+    }
+    Some(truncate(&body, MAX_LEN))
+}
+
+// A user-supplied term: drop control chars and quotes (which would break the DICT
+// quoting), and cap the length so a giant term can't be smuggled to the server.
+fn sanitize(word: &str) -> String {
+    word.chars().filter(|c| !c.is_control() && *c != '"').take(128).collect::<String>().trim().to_string()
+}
+
+fn truncate(s: &str, max: usize) -> String {
+    if s.chars().count() <= max {
+        return s.to_string();
+    }
+    let mut out: String = s.chars().take(max).collect();
+    out.push('…');
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_the_first_definition() {
+        let raw = "150 2 definitions retrieved\n\
+                   151 \"cat\" wn \"WordNet (r) 3.0\"\n\
+                   cat\n    n 1: feline mammal usually having thick soft fur\n    n 2: an informal term for a youth or man\n\
+                   .\n\
+                   151 \"cat\" gcide \"GCIDE\"\n\
+                   Cat \\Cat\\ another definition\n\
+                   .\n";
+        let def = parse_definition(raw).expect("a definition");
+        assert!(def.contains("feline mammal"), "got: {def}");
+        assert!(!def.contains("GCIDE"), "should stop at the first block: {def}");
+    }
+
+    #[test]
+    fn no_match_returns_none() {
+        assert!(parse_definition("552 no match\n").is_none());
+        assert!(parse_definition("150 0 definitions retrieved\n").is_none());
+    }
+
+    #[test]
+    fn truncates_long_bodies() {
+        let long = format!("151 \"x\" wn \"d\"\n{}\n.\n", "word ".repeat(300));
+        let def = parse_definition(&long).unwrap();
+        assert!(def.chars().count() <= MAX_LEN + 1, "len {}", def.chars().count());
+        assert!(def.ends_with('…'));
+    }
+
+    #[test]
+    fn sanitize_strips_quotes_and_controls() {
+        assert_eq!(sanitize("he\"llo\u{1}"), "hello");
+        assert_eq!(sanitize("  spaced  "), "spaced");
+    }
+}

src/engine/dispatch.rs

@@ -101,10 +101,20 @@ impl Engine {
         out.extend(self.reconcile_bots());
         // Announce whatever this command changed to the staff audit channel.
         out.extend(self.audit_feed(audit_mark, &nick, account.as_deref()));
+        self.apply_dict_limit(&mut out);
         self.apply_msg_style(&mut out);
         out
     }
 
+    // Drop DICT lookups that exceed the global rate budget, so a burst of !dict
+    // can't hammer the dictionary server. Non-lookup actions pass untouched, and
+    // the limiter is only consulted when a lookup is actually present.
+    fn apply_dict_limit(&mut self, out: &mut Vec<NetAction>) {
+        if out.iter().any(|a| matches!(a, NetAction::DictLookup { .. })) {
+            out.retain(|a| !matches!(a, NetAction::DictLookup { .. }) || self.dict_limiter.allow());
+        }
+    }
+
     // Rewrite each service→user NOTICE to a server-notice (sourced from our
     // server) for users who opted into SET SNOTICE; everyone else keeps a normal
     // notice from the pseudoclient. A multi-line reply names the service once, on
@@ -157,6 +167,19 @@ impl Engine {
             return;
         }
 
+        // A dictionary command (!dict/!define/…) becomes a deferred DICT lookup the
+        // assigned bot speaks — only when DictServ is loaded. The rate limiter in
+        // dispatch() drops excess lookups so nobody can hammer the DICT server.
+        if let Some(l) = echo_dictserv::lookup_for(cmd) {
+            if self.service_uid("DictServ").is_some() {
+                let query = words.collect::<Vec<_>>().join(" ");
+                if !query.trim().is_empty() {
+                    ctx.dict_lookup(botuid.as_str(), chan, l.database, l.label, query);
+                }
+            }
+            return;
+        }
+
         let Some(csuid) = self.service_uid("ChanServ") else { return };
         // Rewrite `!cmd args…` into `CMD #channel args…` for ChanServ.
         let mark = ctx.actions.len();

src/engine/mod.rs

@@ -95,6 +95,7 @@ pub struct Engine {
     sasl_source: HashMap<String, (Instant, String)>, // client uid -> real host/IP from the SASL H message
     reg_limiter: RegLimiter,
     cmd_limiter: CmdLimiter, // per-host flood control for service commands
+    dict_limiter: DictLimiter, // global rate cap on outbound DICT lookups
     chan_service: Option<String>, // uid to source channel modes from (ChanServ)
     nick_service: Option<String>, // uid of the account service (NickServ), for its notices
     irc_out: Option<mpsc::UnboundedSender<NetAction>>, // services-initiated actions -> the uplink
@@ -236,6 +237,7 @@ impl Engine {
             sasl_source: HashMap::new(),
             reg_limiter: RegLimiter::new(),
             cmd_limiter: CmdLimiter::default(),
+            dict_limiter: DictLimiter::new(),
             chan_service,
             nick_service,
             irc_out: None,
@@ -2046,6 +2048,36 @@ impl RegLimiter {
     }
 }
 
+// A global token bucket bounding how fast echo hits the DICT server, so a channel
+// of users spamming !dict can't hammer dict.org (and get echo throttled). Bursts
+// of DICT_BURST, then DICT_REFILL_PER_SEC sustained; an over-budget lookup is
+// dropped — the bot simply doesn't answer that one.
+struct DictLimiter {
+    tokens: f64,
+    last: Instant,
+}
+
+const DICT_BURST: f64 = 6.0;
+const DICT_REFILL_PER_SEC: f64 = 1.0;
+
+impl DictLimiter {
+    fn new() -> Self {
+        Self { tokens: DICT_BURST, last: Instant::now() }
+    }
+
+    fn allow(&mut self) -> bool {
+        let now = Instant::now();
+        self.tokens = (self.tokens + now.duration_since(self.last).as_secs_f64() * DICT_REFILL_PER_SEC).min(DICT_BURST);
+        self.last = now;
+        if self.tokens >= 1.0 {
+            self.tokens -= 1.0;
+            true
+        } else {
+            false
+        }
+    }
+}
+
 // Per-host flood control for anonymous service commands. A bot that connects and
 // spams `/msg NickServ HELP` in a loop is warned, then silently dropped until it
 // slows down — never answered per line, which would just double the flood on

src/engine/tests.rs

@@ -5487,6 +5487,47 @@ fn cmd_limiter_bursts_then_throttles_per_host() {
     assert!(matches!(lim.check_at("1.2.3.4", next_window), CmdVerdict::Warn), "one fresh warning in a new window");
 }
 
+// A dict fantasy (!dict) in a bot channel emits a DictLookup carried by the
+// assigned bot — the actual dict.org round trip happens off-reactor in the link
+// layer, so this just checks the routing.
+#[test]
+fn fantasy_dict_emits_a_lookup_via_the_bot() {
+    use echo_botserv::BotServ;
+    use echo_dictserv::DictServ;
+    use echo_nickserv::NickServ;
+    let path = std::env::temp_dir().join("echo-fdict.jsonl");
+    let _ = std::fs::remove_file(&path);
+    let mut db = Db::open(&path, "42S");
+    db.scram_iterations = 4096;
+    db.register("boss", "password1", None).unwrap();
+    db.register_channel("#c", "boss").unwrap();
+    let mut e = Engine::new(
+        vec![
+            Box::new(NickServ { uid: "42SAAAAAA".into(), guest_nick: "Guest".into(), guest_seq: 0 }),
+            Box::new(BotServ { uid: "42SAAAAAD".into() }),
+            Box::new(DictServ { uid: "42SAAAAAQ".into() }),
+        ],
+        db,
+    );
+    e.set_sid("42S".into());
+    let mut opers = std::collections::HashMap::new();
+    opers.insert("boss".to_string(), Privs::default().with(echo_api::Priv::Admin));
+    e.set_opers(opers);
+    e.handle(NetEvent::UserConnect { uid: "000AAAAAB".into(), nick: "boss".into(), host: "h".into(), ip: "0.0.0.0".into() });
+    e.handle(NetEvent::UserConnect { uid: "000AAAAAR".into(), nick: "rando".into(), host: "h".into(), ip: "0.0.0.0".into() });
+    e.handle(NetEvent::Privmsg { from: "000AAAAAB".into(), to: "42SAAAAAA".into(), text: "IDENTIFY password1".into() });
+    e.handle(NetEvent::Privmsg { from: "000AAAAAB".into(), to: "42SAAAAAD".into(), text: "BOT ADD Bendy bot serv.host Helper".into() });
+    e.handle(NetEvent::Privmsg { from: "000AAAAAB".into(), to: "42SAAAAAD".into(), text: "ASSIGN #c Bendy".into() });
+    e.handle(NetEvent::Join { uid: "000AAAAAR".into(), channel: "#c".into(), op: false });
+
+    let out = e.handle(NetEvent::Privmsg { from: "000AAAAAR".into(), to: "#c".into(), text: "!dict cat".into() });
+    assert!(
+        out.iter().any(|a| matches!(a, NetAction::DictLookup { target, database, query, speak_as, .. }
+            if target == "#c" && database == "wn" && query == "cat" && speak_as.starts_with("42SB"))),
+        "expected a bot-carried DictLookup, got {out:?}"
+    );
+}
+
 // Perf harness — not part of the normal suite. Run:
 //   cargo test --release -p echo -- --ignored --nocapture bench_engine
 // Measures the two costs that actually bound the single-threaded engine: the

src/link.rs

@@ -71,7 +71,8 @@ fn redact(line: &str) -> Cow<'_, str> {
 // One uplink session: connect, handshake + burst, then translate lines forever.
 // The engine is shared with the gossip layer, so it is locked per operation and
 // never held across the registration key-stretching await.
-pub async fn run(mut proto: Box<dyn Protocol>, engine: Arc<Mutex<Engine>>, addr: &str, mut irc_rx: mpsc::UnboundedReceiver<NetAction>, email: Option<crate::config::Email>, keycard: Option<crate::config::Keycard>) -> Result<()> {
+#[allow(clippy::too_many_arguments)] // the link driver legitimately wires up many collaborators
+pub async fn run(mut proto: Box<dyn Protocol>, engine: Arc<Mutex<Engine>>, addr: &str, mut irc_rx: mpsc::UnboundedReceiver<NetAction>, irc_tx: mpsc::UnboundedSender<NetAction>, email: Option<crate::config::Email>, keycard: Option<crate::config::Keycard>, dict_server: Option<String>) -> Result<()> {
     let stream = TcpStream::connect(addr).await?;
     // Disable Nagle: service replies are small multi-line bursts, and without this
     // the last segment of a reply is held ~40ms waiting on a delayed ACK, so a
@@ -159,6 +160,10 @@ pub async fn run(mut proto: Box<dyn Protocol>, engine: Arc<Mutex<Engine>>, addr:
                                 dispatch_email(&email, to, subject, text, html);
                                 continue;
                             }
+                            if let NetAction::DictLookup { speak_as, target, database, label, query } = act {
+                                dispatch_dict(&dict_server, &irc_tx, speak_as, target, database, label, query);
+                                continue;
+                            }
                             if let NetAction::Shutdown { restart, reason } = act {
                                 engine.lock().await.persist_stats();
                                 let _ = write.flush().await;
@@ -193,6 +198,27 @@ pub async fn run(mut proto: Box<dyn Protocol>, engine: Arc<Mutex<Engine>>, addr:
     Ok(())
 }
 
+// Run a DictServ lookup off the reactor and speak the result back. The DICT round
+// trip (up to a few seconds) must never touch the engine lock; the reply is pushed
+// through irc_tx so the link loop writes it like any services-initiated action. A
+// #channel target is spoken by the assigned bot (privmsg), a user gets a notice.
+fn dispatch_dict(server: &Option<String>, irc_tx: &mpsc::UnboundedSender<NetAction>, speak_as: String, target: String, database: String, label: String, query: String) {
+    let Some(server) = server.clone() else {
+        return tracing::warn!("dict lookup requested but no server configured");
+    };
+    let tx = irc_tx.clone();
+    tokio::spawn(async move {
+        let result = crate::dict::lookup(&server, &database, &query).await;
+        let text = format!("\x02{query}\x02 ({label}): {result}");
+        let action = if target.starts_with('#') || target.starts_with('&') {
+            NetAction::Privmsg { from: speak_as, to: target, text }
+        } else {
+            NetAction::Notice { from: speak_as, to: target, text }
+        };
+        let _ = tx.send(action);
+    });
+}
+
 // Fire off an email if email is configured: pipe an RFC822 message to the mail
 // command on a spawned task, so a slow MTA never stalls the link. With an HTML
 // body it's sent as multipart/alternative (HTML + plaintext fallback).

src/main.rs

@@ -2,6 +2,7 @@
 // crates (echo-nickserv, echo-chanserv, echo-inspircd), each depending
 // only on the echo-api SDK.
 mod config;
+mod dict;
 mod engine;
 mod gossip;
 mod grpc;
@@ -24,6 +25,7 @@ use echo_statserv::StatServ;
 use echo_hostserv::HostServ;
 use echo_operserv::OperServ;
 use echo_diceserv::DiceServ;
+use echo_dictserv::DictServ;
 use echo_gameserv::GameServ;
 use echo_infoserv::InfoServ;
 use echo_reportserv::ReportServ;
@@ -133,6 +135,13 @@ async fn main() -> Result<()> {
             uid: format!("{}AAAAAI", cfg.server.sid),
         }));
     }
+    // DictServ is gated on its own [dictserv] config, not the module list — it's an
+    // opt-in that makes outbound lookup requests, so it never loads by default.
+    if cfg.dictserv.is_some() {
+        services.push(Box::new(DictServ {
+            uid: format!("{}AAAAAQ", cfg.server.sid),
+        }));
+    }
     if enabled("gameserv") {
         services.push(Box::new(GameServ::new(format!("{}AAAAAP", cfg.server.sid))));
     }
@@ -199,7 +208,7 @@ async fn main() -> Result<()> {
 
     // Channel for services-initiated actions to reach the uplink (drained by the link loop).
     let (irc_tx, irc_rx) = tokio::sync::mpsc::unbounded_channel();
-    engine.lock().await.set_irc_out(irc_tx);
+    engine.lock().await.set_irc_out(irc_tx.clone());
     for (account, name) in cfg.oper_priv_warnings() {
         tracing::warn!(%account, privilege = %name, valid = %echo_api::Priv::valid_names(), "unknown privilege in [[oper]] — ignored (typo?)");
     }
@@ -288,7 +297,7 @@ async fn main() -> Result<()> {
     // just lets systemd stop us without waiting out the kill timeout.
     let shutdown_engine = engine.clone();
     tokio::select! {
-        res = link::run(proto, engine, &addr, irc_rx, cfg.email.clone(), cfg.keycard.clone()) => res,
+        res = link::run(proto, engine, &addr, irc_rx, irc_tx, cfg.email.clone(), cfg.keycard.clone(), cfg.dictserv.as_ref().map(|d| d.server.clone())) => res,
         _ = shutdown_signal() => {
             // Flush stat counters so a clean stop/restart keeps StatServ history.
             shutdown_engine.lock().await.persist_stats();