6ef13b2cc8a6
ssip.rs
//! Speech Dispatcher through its own protocol (SSIP) on the user's socket, for systems that have
//! Speech Dispatcher but not the `espeak-ng` command.
//!
//! Talking SSIP directly, instead of starting `spd-say`, keeps two promises `spd-say` can't: the
//! sentence is always data (pipe mode runs a line starting with `!-!` as an SSIP command, and a
//! document must never send commands), and stopping cancels only WordCraft's own speech
//! (`CANCEL self`), where `spd-say -C` would silence every client, a screen reader included.
//!
//! One connection speaks one sentence: it names the client, asks for the begin, end, cancel and
//! pause events, sets the rate and language, sends the text, and waits for the sentence's end
//! event. A sentence another client's message cancels (a screen reader's announcement) is sent
//! again after a pause, twice at most; a sentence cancelled once more or paused by another
//! client halts reading on it ([`Outcome::Halted`]), and so does one that never began
//! ([`Outcome::NotStarted`]).
use craft_ssip::{Lines, final_code, message_data};
use std::io::{ErrorKind, Read, Write};
use std::net::{TcpStream, ToSocketAddrs};
use std::os::unix::net::UnixStream;
use std::path::PathBuf;
use std::time::{Duration, Instant};
/// How often a wait for the end event looks at whether reading moved on.
const POLL: Duration = Duration::from_millis(30);
/// Longest wait for a reply to a command (the server answers at once; this only bounds a stuck one).
const REPLY_TIMEOUT: Duration = if cfg!(test) { Duration::from_secs(1) } else { Duration::from_secs(5) };
/// Most bytes of one sentence sent as message data: [`super::MAX_UTTERANCE`] chars of up to 4 bytes each.
const MAX_MESSAGE_BYTES: usize = 4 * super::MAX_UTTERANCE;
/// Speech Dispatcher's TCP port when `SPEECHD_ADDRESS` names none.
const DEFAULT_PORT: u16 = 6560;
/// How long a freshly started server gets to open its socket (it loads its speech modules first).
const START_WAIT: Duration = Duration::from_secs(5);
/// Longest wait for a TCP connection to one address.
const CONNECT_TIMEOUT: Duration = Duration::from_secs(1);
/// The end of a sentence is awaited this long after it began, plus [`SENTENCE_PER_CHAR`] for each
/// character: far more than the slowest reading takes, so only a stuck server reaches it.
const SENTENCE_BASE: Duration = if cfg!(test) { Duration::from_secs(1) } else { Duration::from_secs(30) };
const SENTENCE_PER_CHAR: Duration = Duration::from_millis(400);
/// Longest wait for a queued sentence to begin (behind other clients' speech, or paused before it
/// began, which sends no pause event).
const QUEUE_WAIT: Duration = if cfg!(test) { Duration::from_secs(1) } else { Duration::from_secs(120) };
/// The pauses before a sentence another client cancelled is sent again: the other client's
/// message gets time to end, and the server holds ours back while a higher-priority one speaks.
const RESEND_AFTER: [Duration; 2] =
if cfg!(test) { [Duration::from_millis(50), Duration::from_millis(50)] } else { [Duration::from_secs(1), Duration::from_secs(3)] };
/// What to say and how.
pub(super) struct Request<'a> {
pub text: &'a str,
/// Speech Dispatcher's rate, -100 to 100.
pub rate: i32,
/// A plain language tag (`hu`, `pt-BR`); anything else is left out.
pub lang: Option<&'a str>,
}
/// How a sentence ended.
#[derive(Debug, PartialEq, Eq)]
pub(super) enum Outcome {
/// Spoken to the end.
Done,
/// Reading moved on: the sentence was cancelled.
Interrupted,
/// Another client stopped it: cancelled it again after it was sent again, or paused it.
/// Reading halts on it instead of fighting the other client.
Halted,
/// The sentence never began: queued too long, behind other clients' speech, paused before it
/// began (which sends no event), or with a speech module that doesn't start. Reading halts on it.
NotStarted,
}
/// Where Speech Dispatcher listens.
#[derive(Debug, PartialEq, Eq)]
pub(super) enum Address {
Unix(PathBuf),
/// Host and port.
Inet(String, u16),
}
/// The server's address, found the way Speech Dispatcher's own client library finds it:
/// `SPEECHD_ADDRESS` when set (`unix_socket[:path]`, `inet_socket[:host[:port]]`), else the socket
/// `speech-dispatcher/speechd.sock` in the runtime folder, else in the cache folder
/// (`XDG_CACHE_HOME`, else `~/.cache`). `None` for an address method it doesn't know, a port that
/// isn't a number, or no folder to look in.
pub(super) fn address(spec: Option<&str>, runtime_dir: Option<PathBuf>, cache_home: Option<PathBuf>, home: Option<PathBuf>) -> Option<Address> {
let default_socket = || {
let set = |p: Option<PathBuf>| p.filter(|p| !p.as_os_str().is_empty());
set(runtime_dir)
.or_else(|| set(cache_home))
.or_else(|| set(home).map(|h| h.join(".cache")))
.map(|d| d.join("speech-dispatcher").join("speechd.sock"))
};
let Some(spec) = spec.map(str::trim).filter(|a| !a.is_empty()) else { return default_socket().map(Address::Unix) };
let (method, rest) = spec.split_once(':').unwrap_or((spec, ""));
match method {
"unix_socket" => Some(Address::Unix(if rest.is_empty() { default_socket()? } else { PathBuf::from(rest) })),
"inet_socket" => {
let mut p = rest.split(':');
let host = p.next().filter(|h| !h.is_empty()).unwrap_or("127.0.0.1");
let port = p.next().filter(|p| !p.is_empty()).map_or(Some(DEFAULT_PORT), |p| p.parse().ok())?;
Some(Address::Inet(host.to_string(), port))
}
_ => None,
}
}
/// Is `host` this machine (the only place a server may be started)?
fn is_local(host: &str) -> bool {
host.eq_ignore_ascii_case("localhost") || host.parse::<std::net::IpAddr>().is_ok_and(|ip| ip.is_loopback())
}
/// A connection to Speech Dispatcher.
pub(super) enum Stream {
Unix(UnixStream),
Tcp(TcpStream),
}
impl Stream {
fn try_clone(&self) -> std::io::Result<Stream> {
Ok(match self {
Stream::Unix(s) => Stream::Unix(s.try_clone()?),
Stream::Tcp(s) => Stream::Tcp(s.try_clone()?),
})
}
/// Reads give up after [`POLL`] (so a wait can look at whether reading moved on), writes after
/// [`REPLY_TIMEOUT`].
fn set_timeouts(&self) -> std::io::Result<()> {
match self {
Stream::Unix(s) => {
s.set_read_timeout(Some(POLL))?;
s.set_write_timeout(Some(REPLY_TIMEOUT))
}
Stream::Tcp(s) => {
s.set_read_timeout(Some(POLL))?;
s.set_write_timeout(Some(REPLY_TIMEOUT))
}
}
}
}
impl Read for Stream {
fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
match self {
Stream::Unix(s) => s.read(buf),
Stream::Tcp(s) => s.read(buf),
}
}
}
impl Write for Stream {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
match self {
Stream::Unix(s) => s.write(buf),
Stream::Tcp(s) => s.write(buf),
}
}
fn flush(&mut self) -> std::io::Result<()> {
match self {
Stream::Unix(s) => s.flush(),
Stream::Tcp(s) => s.flush(),
}
}
}
/// Connect to `address`; between the addresses a host name resolves to, give up once `changed()`.
fn open(address: &Address, changed: &dyn Fn() -> bool) -> std::io::Result<Stream> {
match address {
Address::Unix(path) => UnixStream::connect(path).map(Stream::Unix),
Address::Inet(host, port) => {
let mut last = std::io::Error::from(ErrorKind::NotFound);
for a in (host.as_str(), *port).to_socket_addrs()? {
if changed() {
return Err(moved_on());
}
match TcpStream::connect_timeout(&a, CONNECT_TIMEOUT) {
Ok(s) => return Ok(Stream::Tcp(s)),
Err(e) => last = e,
}
}
Err(last)
}
}
}
/// How [`connect`] went.
pub(super) enum Connection {
Open(Stream),
/// Speech Dispatcher isn't installed.
Missing,
/// It is installed but can't be reached: why.
Unreachable(String),
/// Reading moved on while the server was starting.
Interrupted,
}
/// Connect to the user's Speech Dispatcher, starting it once if it isn't running (as `spd-say`
/// does), unless the address is another machine's.
pub(super) fn connect(changed: &dyn Fn() -> bool) -> Connection {
let env = |k: &str| std::env::var_os(k).map(PathBuf::from);
let spec = std::env::var("SPEECHD_ADDRESS").ok().filter(|s| !s.trim().is_empty());
let Some(address) = address(spec.as_deref(), env("XDG_RUNTIME_DIR"), env("XDG_CACHE_HOME"), env("HOME")) else {
return if spec.is_some() { Connection::Unreachable("SPEECHD_ADDRESS isn't an address it understands".into()) } else { Connection::Missing };
};
match open(&address, changed) {
Ok(s) => return Connection::Open(s),
Err(e) if e.kind() == ErrorKind::Interrupted => return Connection::Interrupted,
Err(_) => {}
}
let mut start = std::process::Command::new("speech-dispatcher");
start.arg("--spawn");
// A server started for an address of its own must open it there.
match (&address, spec.is_some()) {
(_, false) => {}
(Address::Unix(path), true) => {
start.args(["--communication-method", "unix_socket", "--socket-path"]).arg(path);
}
(Address::Inet(host, port), true) if is_local(host) => {
start.args(["--communication-method", "inet_socket", "--port", &port.to_string()]);
}
(Address::Inet(..), true) => return Connection::Unreachable("nothing answers at SPEECHD_ADDRESS".into()),
}
// `--spawn` exits once it has forked the server; the wait for it is still bounded and gives way
// to Stop, so a start that hangs can't keep the reading thread (and Read Aloud with it) busy.
let until = Instant::now() + START_WAIT;
match start_server(&mut start, until, changed) {
Started::Exited(true) => {}
Started::Exited(false) => {
return Connection::Unreachable("it isn't running and didn't start (its configuration may turn starting on demand off)".into());
}
Started::Missing => return Connection::Missing,
Started::Failed(e) => return Connection::Unreachable(format!("it couldn't be started: {e}")),
Started::Interrupted => return Connection::Interrupted,
Started::TimedOut => {
return open(&address, changed).map_or_else(|_| Connection::Unreachable("starting it didn't finish in time".into()), Connection::Open);
}
}
// The server opens its socket a moment after it starts.
loop {
if changed() {
return Connection::Interrupted;
}
if let Ok(s) = open(&address, changed) {
return Connection::Open(s);
}
if Instant::now() >= until {
return Connection::Unreachable("it started but doesn't answer".into());
}
std::thread::sleep(Duration::from_millis(50));
}
}
/// How running the server's start command went.
#[derive(Debug)]
enum Started {
/// It exited, successfully or not.
Exited(bool),
/// The command isn't installed.
Missing,
/// It couldn't be run or waited for.
Failed(std::io::Error),
/// Reading moved on before it exited; it was stopped.
Interrupted,
/// It was still running at the deadline; it was stopped.
TimedOut,
}
/// Run `command` (output discarded) and wait for it to exit, at most until `until` and only while
/// reading stays put; a command still running then is stopped and reaped.
fn start_server(command: &mut std::process::Command, until: Instant, changed: &dyn Fn() -> bool) -> Started {
use std::process::Stdio;
let mut child = match command.stdin(Stdio::null()).stdout(Stdio::null()).stderr(Stdio::null()).spawn() {
Ok(child) => child,
Err(e) if e.kind() == ErrorKind::NotFound => return Started::Missing,
Err(e) => return Started::Failed(e),
};
let stopped = loop {
match child.try_wait() {
Ok(Some(status)) => return Started::Exited(status.success()),
Ok(None) if changed() => break Started::Interrupted,
Ok(None) if Instant::now() >= until => break Started::TimedOut,
Ok(None) => std::thread::sleep(Duration::from_millis(20)),
Err(e) => break Started::Failed(e),
}
};
let _ = child.kill();
let _ = child.wait();
stopped
}
/// A `2xx` reply, or an error naming the code.
fn ok(code: u16) -> std::io::Result<()> {
if (200..300).contains(&code) { Ok(()) } else { Err(std::io::Error::other(format!("Speech Dispatcher refused a command ({code})"))) }
}
/// The error a conversation stops with when reading moved on.
fn moved_on() -> std::io::Error {
std::io::Error::new(ErrorKind::Interrupted, "reading moved on")
}
/// The begin (701), end (702), cancel (703) and pause (704) events.
const BEGIN: u16 = 701;
const END: u16 = 702;
const CANCEL: u16 = 703;
const PAUSE: u16 = 704;
/// One conversation with the server.
struct Conversation<'a, W, R> {
w: W,
lines: Lines<R>,
/// The last end, cancel or pause event, until it's taken.
event: Option<u16>,
/// The message just queued began.
begun: bool,
/// Whether reading moved on (checked between lines and at every read timeout).
changed: &'a dyn Fn() -> bool,
}
impl<W: Write, R: Read> Conversation<'_, W, R> {
/// The reply to the command just sent: its final code. An end, cancel or pause event that arrives
/// meanwhile is kept. Gives up after [`REPLY_TIMEOUT`], also when the server keeps sending
/// other lines, and as soon as reading moves on.
fn reply(&mut self) -> std::io::Result<u16> {
let start = Instant::now();
loop {
if let Some(line) = self.lines.next_line()? {
match final_code(&line) {
Some(BEGIN) => self.begun = true,
Some(code @ (END | CANCEL | PAUSE)) => self.event = Some(code),
Some(code) if (700..800).contains(&code) => {}
Some(code) => return Ok(code),
None => {}
}
}
if start.elapsed() > REPLY_TIMEOUT {
return Err(ErrorKind::TimedOut.into());
}
if (self.changed)() {
return Err(moved_on());
}
}
}
/// Send one command line and read its reply code.
fn command(&mut self, cmd: &str) -> std::io::Result<u16> {
self.w.write_all(cmd.as_bytes())?;
self.w.write_all(b"\r\n")?;
self.reply()
}
/// What became of the message just queued: its end, cancel or pause event, or
/// [`Fate::NotStarted`] when it didn't begin within [`QUEUE_WAIT`]. Once it began, its end is
/// waited for until `limit` has passed (a stuck server: an error). An error as soon as reading
/// moves on.
fn fate(&mut self, limit: Duration) -> std::io::Result<Fate> {
let queued = Instant::now();
let mut began = self.begun.then(Instant::now);
loop {
match self.event.take() {
Some(END) => return Ok(Fate::End),
Some(CANCEL) => return Ok(Fate::Cancelled),
Some(_) => return Ok(Fate::Paused),
None => {}
}
if (self.changed)() {
return Err(moved_on());
}
match began {
None if queued.elapsed() > QUEUE_WAIT => return Ok(Fate::NotStarted),
Some(t) if t.elapsed() > limit => return Err(std::io::Error::new(ErrorKind::TimedOut, "the sentence didn't end")),
_ => {}
}
if let Some(line) = self.lines.next_line()? {
match final_code(&line) {
Some(BEGIN) => {
began.get_or_insert_with(Instant::now);
}
Some(code @ (END | CANCEL | PAUSE)) => self.event = Some(code),
_ => {}
}
}
}
}
/// Wait `pause`, reading what the server sends meanwhile; an error as soon as reading moves on.
fn wait(&mut self, pause: Duration) -> std::io::Result<()> {
let start = Instant::now();
while start.elapsed() < pause {
if (self.changed)() {
return Err(moved_on());
}
self.lines.next_line()?;
}
Ok(())
}
/// Set up the client, say the sentence, and wait for it to end. Only [`converse`] cancels our
/// own speech, and it stops waiting first, so a cancel or pause event comes from another
/// client. A cancel is most often another client's message, a screen reader's announcement:
/// the sentence is sent again after a pause ([`RESEND_AFTER`]), when the announcement has
/// ended or the server holds ours back until it has. Cancelled again after that, paused, or
/// never begun, the sentence halts reading.
fn speak(&mut self, req: &Request<'_>) -> std::io::Result<Outcome> {
ok(self.command("SET SELF CLIENT_NAME user:wordcraft:read-aloud")?)?;
ok(self.command("SET SELF NOTIFICATION BEGIN on")?)?;
ok(self.command("SET SELF NOTIFICATION END on")?)?;
ok(self.command("SET SELF NOTIFICATION CANCEL on")?)?;
ok(self.command("SET SELF NOTIFICATION PAUSE on")?)?;
ok(self.command(&format!("SET SELF RATE {}", req.rate))?)?;
// A language the server doesn't know leaves its default: no error. The tag is checked
// again here, at the edge of the protocol: it goes on a command line.
if let Some(lang) = req.lang.and_then(super::plain_tag) {
self.command(&format!("SET SELF LANGUAGE {lang}"))?;
}
let chars = u32::try_from(req.text.chars().count()).unwrap_or(u32::MAX);
let limit = SENTENCE_BASE.saturating_add(SENTENCE_PER_CHAR.saturating_mul(chars));
let mut resends = RESEND_AFTER.iter();
loop {
self.event = None;
self.begun = false;
ok(self.command("SPEAK")?)?;
self.w.write_all(message_data(req.text, MAX_MESSAGE_BYTES)?.as_bytes())?;
ok(self.reply()?)?;
match self.fate(limit)? {
Fate::End => return Ok(Outcome::Done),
Fate::Cancelled => match resends.next() {
Some(pause) => self.wait(*pause)?,
None => return Ok(Outcome::Halted),
},
Fate::Paused => return Ok(Outcome::Halted),
Fate::NotStarted => return Ok(Outcome::NotStarted),
}
}
}
}
/// What became of a queued message.
enum Fate {
End,
Cancelled,
Paused,
NotStarted,
}
/// The last words after a sentence that didn't finish.
const CLOSE: &[u8] = b"\r\n.\r\nCANCEL self\r\nQUIT\r\n";
/// Speak `req` over `stream`, cancelling it when `changed()`.
pub(super) fn converse(stream: &Stream, req: &Request<'_>, changed: &dyn Fn() -> bool) -> std::io::Result<Outcome> {
stream.set_timeouts()?;
let mut c = Conversation { w: stream.try_clone()?, lines: Lines::new(stream.try_clone()?), event: None, begun: false, changed };
let result = c.speak(req);
// The last words wait for no answer: a server that stopped answering mustn't hold up Stop.
// After anything but a finished sentence our message may still be queued, or the server may
// be reading message data: an empty line and `.` end a message being sent (outside one they
// are two refused commands), and `CANCEL self` drops ours.
let done = matches!(result, Ok(Outcome::Done));
let _ = c.w.write_all(if done { b"QUIT\r\n" } else { CLOSE });
match result {
Err(e) if e.kind() == ErrorKind::Interrupted => Ok(Outcome::Interrupted),
r => r,
}
}
#[cfg(test)]
mod tests {
use super::*;
use craft_ssip::MAX_LINE;
use std::io::{BufRead, BufReader};
#[test]
fn the_address_follows_the_environment() {
let unix = |p: &str| Some(Address::Unix(PathBuf::from(p)));
let run = || Some(PathBuf::from("/run/user/1"));
assert_eq!(address(Some("unix_socket:/tmp/s.sock"), None, None, None), unix("/tmp/s.sock"));
assert_eq!(address(None, run(), None, None), unix("/run/user/1/speech-dispatcher/speechd.sock"));
// `unix_socket` alone is the default socket, as in Speech Dispatcher's client library.
assert_eq!(address(Some("unix_socket"), run(), None, None), unix("/run/user/1/speech-dispatcher/speechd.sock"));
assert_eq!(address(Some("unix_socket:"), None, None, Some("/home/u".into())), unix("/home/u/.cache/speech-dispatcher/speechd.sock"));
// Without a runtime folder: the cache folder, `XDG_CACHE_HOME` first.
assert_eq!(address(Some(" "), None, None, Some("/home/u".into())), unix("/home/u/.cache/speech-dispatcher/speechd.sock"));
assert_eq!(address(None, Some("".into()), Some("/c".into()), Some("/home/u".into())), unix("/c/speech-dispatcher/speechd.sock"));
// A TCP address, with the default host and port filled in.
assert_eq!(address(Some("inet_socket:localhost:6561"), run(), None, None), Some(Address::Inet("localhost".into(), 6561)));
assert_eq!(address(Some("inet_socket"), None, None, None), Some(Address::Inet("127.0.0.1".into(), DEFAULT_PORT)));
assert_eq!(address(Some("inet_socket:host"), None, None, None), Some(Address::Inet("host".into(), DEFAULT_PORT)));
assert_eq!(address(Some("inet_socket:host:port"), None, None, None), None);
assert_eq!(address(Some("inet_socket:host:99999"), None, None, None), None);
assert_eq!(address(Some("carrier_pigeon:x"), run(), None, None), None);
assert_eq!(address(None, None, None, None), None);
assert!(is_local("localhost") && is_local("127.0.0.1") && is_local("::1"));
assert!(!is_local("example.org") && !is_local("192.0.2.1"));
}
#[test]
fn document_text_is_always_message_data() {
// `spd-say -e` would run this line as an SSIP command; here it's spoken text.
assert_eq!(message_data("!-!SET SELF RATE 50", 64).unwrap(), "!-!SET SELF RATE 50\r\n.\r\n");
// A line of a single `.` would end the message early, and a line break would start a
// new line that could be one.
assert_eq!(message_data(".\r\nQUIT", 64).unwrap(), ".. QUIT\r\n.\r\n");
assert_eq!(message_data("a\n.\nb", 64).unwrap(), "a . b\r\n.\r\n");
assert_eq!(final_code("225 OK MESSAGE QUEUED"), Some(225));
assert_eq!(final_code("225-17"), None);
assert_eq!(final_code("x"), None);
}
/// Hands out the given reads one by one, then reports a timeout.
struct Reads(std::collections::VecDeque<Vec<u8>>);
impl Read for Reads {
fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
match self.0.pop_front() {
Some(chunk) if !chunk.is_empty() => {
let n = chunk.len().min(buf.len());
buf[..n].copy_from_slice(&chunk[..n]);
if n < chunk.len() {
self.0.push_front(chunk[n..].to_vec());
}
Ok(n)
}
_ => Err(ErrorKind::WouldBlock.into()),
}
}
}
#[test]
fn a_character_split_by_a_read_timeout_stays_whole() {
// `é` is C3 A9; the read times out (the empty read) between its two bytes.
let mut lines = Lines::new(Reads(vec![b"249-Caf\xC3".to_vec(), Vec::new(), b"\xA9\tfr\tnone\r\n702 END\r\n".to_vec()].into()));
assert_eq!(lines.next_line().unwrap(), None, "half a line");
assert_eq!(lines.next_line().unwrap(), None, "the timeout");
assert_eq!(lines.next_line().unwrap().as_deref(), Some("249-Café\tfr\tnone"));
assert_eq!(lines.next_line().unwrap().as_deref(), Some("702 END"));
assert_eq!(lines.next_line().unwrap(), None);
}
#[test]
fn a_line_without_an_end_is_an_error_not_a_growing_buffer() {
// A peer that never stops sending and never ends the line.
let mut lines = Lines::new(std::io::repeat(b'x'));
let mut calls = 0;
let err = loop {
calls += 1;
assert!(calls < 100, "never gave up");
match lines.next_line() {
Ok(None) => {}
Ok(Some(l)) => panic!("{l}"),
Err(e) => break e,
}
};
assert_eq!(err.kind(), ErrorKind::InvalidData);
}
#[test]
fn a_trickle_of_bytes_hands_control_back_after_each_read() {
// One byte per read and never a line end: every call returns, so the caller can look at
// its deadline and at whether reading moved on.
let mut lines = Lines::new(Reads(vec![b"2".to_vec(), b"0".to_vec(), b"0".to_vec(), b" OK\r\n".to_vec()].into()));
assert_eq!(lines.next_line().unwrap(), None);
assert_eq!(lines.next_line().unwrap(), None);
assert_eq!(lines.next_line().unwrap(), None);
assert_eq!(lines.next_line().unwrap().as_deref(), Some("200 OK"));
}
/// The sentence encoder this module had before it moved to `craft-ssip`, kept as the oracle.
fn old_message_data(text: &str) -> String {
let line: String = text.chars().map(|c| if c == '\r' || c == '\n' { ' ' } else { c }).collect();
let dot = if line.starts_with('.') { "." } else { "" };
format!("{dot}{line}\r\n.\r\n")
}
#[test]
fn shared_message_data_matches_the_old_encoder() {
let near_cap = "é".repeat(super::super::MAX_UTTERANCE);
let at_cap = "𝄞".repeat(super::super::MAX_UTTERANCE);
assert_eq!(at_cap.len(), MAX_MESSAGE_BYTES, "the cap fits the worst case");
for text in ["", ".", "..x", "a\r\nb", "\n.", "!-!SET SELF RATE 50", "\r\n.\r\n", near_cap.as_str(), at_cap.as_str()] {
assert_eq!(message_data(text, MAX_MESSAGE_BYTES).unwrap(), old_message_data(text), "{text:?}");
}
}
/// A server that answers the first command with `reply` instead of a code.
fn bad_server(mut s: UnixStream, reply: Vec<u8>) -> std::thread::JoinHandle<()> {
std::thread::spawn(move || {
let mut line = String::new();
let _ = BufReader::new(s.try_clone().unwrap()).read_line(&mut line);
let _ = s.write_all(&reply);
// Hold the socket open so the client sees the reply, not a hang-up.
std::thread::sleep(Duration::from_millis(1500));
})
}
#[test]
fn a_reply_code_with_a_sign_is_not_a_code() {
// `+22` parsed as a number before; now it's no reply at all, so the wait ends in a timeout.
let (client, srv) = UnixStream::pair().unwrap();
let h = bad_server(srv, b"+22 OK\r\n".to_vec());
let req = Request { text: "Hello.", rate: 0, lang: None };
let err = converse(&Stream::Unix(client), &req, &|| false).unwrap_err();
assert_eq!(err.kind(), ErrorKind::TimedOut);
h.join().unwrap();
}
#[test]
fn an_overlong_reply_line_is_an_error() {
let (client, srv) = UnixStream::pair().unwrap();
let mut junk = vec![b'x'; MAX_LINE + 100];
junk.extend_from_slice(b"\r\n");
let h = bad_server(srv, junk);
let req = Request { text: "Hello.", rate: 0, lang: None };
let err = converse(&Stream::Unix(client), &req, &|| false).unwrap_err();
assert_eq!(err.kind(), ErrorKind::InvalidData);
h.join().unwrap();
}
/// How the stand-in server ends a message.
#[derive(Clone, Copy)]
enum Ending {
/// The end event.
End,
/// Nothing until `CANCEL self`.
Hold,
/// Cancelled by another client every time.
CancelledByOther,
/// Cancelled by another client the first time only.
CancelledOnce,
/// Queued and never begun (paused before it began: no event at all).
NeverBegins,
/// Paused by another client (`PAUSE all`).
PausedByOther,
}
/// A Speech Dispatcher stand-in: answers every command with `2xx` and ends each message as
/// `ending` says. Returns the lines it received.
fn server(mut s: UnixStream, ending: Ending) -> std::thread::JoinHandle<Vec<String>> {
std::thread::spawn(move || {
let mut got = Vec::new();
let mut r = BufReader::new(s.try_clone().unwrap());
let mut in_data = false;
let mut messages = 0;
loop {
let mut line = String::new();
if r.read_line(&mut line).unwrap_or(0) == 0 {
return got;
}
let line = line.trim_end_matches(['\r', '\n']).to_string();
got.push(line.clone());
let reply: &[u8] = if in_data {
if line != "." {
continue;
}
in_data = false;
messages += 1;
match ending {
Ending::CancelledOnce if messages == 1 => {
b"225-1\r\n225 OK MESSAGE QUEUED\r\n701 BEGIN\r\n703-1\r\n703-7\r\n703 CANCELED\r\n"
}
Ending::CancelledOnce => b"225-1\r\n225 OK MESSAGE QUEUED\r\n701 BEGIN\r\n702-1\r\n702-7\r\n702 END\r\n",
Ending::NeverBegins => b"225-1\r\n225 OK MESSAGE QUEUED\r\n",
Ending::CancelledByOther => b"225-1\r\n225 OK MESSAGE QUEUED\r\n701 BEGIN\r\n703-1\r\n703-7\r\n703 CANCELED\r\n",
Ending::PausedByOther => b"225-1\r\n225 OK MESSAGE QUEUED\r\n701 BEGIN\r\n704-1\r\n704-7\r\n704 PAUSED\r\n",
Ending::End => b"225-1\r\n225 OK MESSAGE QUEUED\r\n702-1\r\n702-7\r\n702 END\r\n",
Ending::Hold => b"225-1\r\n225 OK MESSAGE QUEUED\r\n701 BEGIN\r\n",
}
} else if line == "SPEAK" {
in_data = true;
b"230 OK RECEIVING DATA\r\n"
} else if line == "CANCEL self" {
b"703-1\r\n703-7\r\n703 CANCELED\r\n210 OK CANCELLED\r\n"
} else if line == "QUIT" {
let _ = s.write_all(b"231 HAPPY HACKING\r\n");
return got;
} else {
b"200 OK\r\n"
};
// The client doesn't wait for the answers to its last words.
let _ = s.write_all(reply);
}
})
}
fn speaks(got: &[String]) -> usize {
got.iter().filter(|l| *l == "SPEAK").count()
}
#[test]
fn a_sentence_is_spoken_to_its_end() {
let (client, srv) = UnixStream::pair().unwrap();
let h = server(srv, Ending::End);
let req = Request { text: "!-!QUIT", rate: 50, lang: Some("pt-BR") };
assert_eq!(converse(&Stream::Unix(client), &req, &|| false).unwrap(), Outcome::Done);
let got = h.join().unwrap();
assert!(got.contains(&"SET SELF RATE 50".to_string()), "{got:?}");
// The region stays: Speech Dispatcher's voices are per region (`en-GB`, `pt-BR`).
assert!(got.contains(&"SET SELF LANGUAGE pt-BR".to_string()), "{got:?}");
let at = got.iter().position(|l| l == "SPEAK").unwrap();
assert_eq!(got[at + 1..at + 3], ["!-!QUIT".to_string(), ".".to_string()], "the text went as data");
assert_eq!(speaks(&got), 1);
assert!(!got.iter().any(|l| l.starts_with("CANCEL")), "nothing cancelled");
assert_eq!(got.last().map(String::as_str), Some("QUIT"));
}
#[test]
fn a_sentence_a_screen_reader_cuts_off_is_said_again_after_a_pause() {
// One announcement: the sentence is said again once it has had time to end.
let (client, srv) = UnixStream::pair().unwrap();
let h = server(srv, Ending::CancelledOnce);
let req = Request { text: "Interrupted by a screen reader.", rate: 0, lang: None };
let start = Instant::now();
assert_eq!(converse(&Stream::Unix(client), &req, &|| false).unwrap(), Outcome::Done);
assert!(start.elapsed() >= RESEND_AFTER[0], "it waited before saying it again");
let got = h.join().unwrap();
assert_eq!(speaks(&got), 2, "{got:?}");
assert!(got.contains(&"SET SELF NOTIFICATION BEGIN on".to_string()), "{got:?}");
assert!(!got.iter().any(|l| l.starts_with("CANCEL")), "{got:?}");
}
#[test]
fn a_sentence_another_client_keeps_stopping_halts_reading() {
// Cancelled every time (another client stopping everything, a failing module): two
// tries more, then reading halts, never moving on silently. A pause halts at once.
for (ending, sent) in [(Ending::CancelledByOther, 1 + RESEND_AFTER.len()), (Ending::PausedByOther, 1)] {
let (client, srv) = UnixStream::pair().unwrap();
let h = server(srv, ending);
let req = Request { text: "Interrupted by a screen reader.", rate: 0, lang: None };
assert_eq!(converse(&Stream::Unix(client), &req, &|| false).unwrap(), Outcome::Halted);
let got = h.join().unwrap();
assert_eq!(speaks(&got), sent, "{got:?}");
assert!(got.contains(&"SET SELF NOTIFICATION PAUSE on".to_string()), "{got:?}");
// Only our own message is dropped.
assert!(got.contains(&"CANCEL self".to_string()) && !got.iter().any(|l| l.eq_ignore_ascii_case("CANCEL all")), "{got:?}");
}
}
#[test]
fn a_withheld_end_times_out_and_the_next_sentence_plays() {
// The server accepts the sentence, begins it, stays connected and never reports its end:
// the wait gives up with an error, drops the message (`CANCEL self`), and closes.
let (client, srv) = UnixStream::pair().unwrap();
let h = server(srv, Ending::Hold);
let req = Request { text: "Withheld.", rate: 0, lang: None };
let start = Instant::now();
let err = converse(&Stream::Unix(client), &req, &|| false).unwrap_err();
assert_eq!(err.kind(), ErrorKind::TimedOut, "{err}");
assert!(start.elapsed() < SENTENCE_BASE + SENTENCE_PER_CHAR * 9 + REPLY_TIMEOUT * 2, "{:?}", start.elapsed());
let got = h.join().unwrap();
assert_eq!(speaks(&got), 1);
assert!(got.contains(&"CANCEL self".to_string()) && got.last().map(String::as_str) == Some("QUIT"), "{got:?}");
// Playback recovers: the next sentence, on a new connection as every sentence gets,
// is spoken to its end.
let (client, srv) = UnixStream::pair().unwrap();
let h = server(srv, Ending::End);
assert_eq!(converse(&Stream::Unix(client), &Request { text: "Next.", rate: 0, lang: None }, &|| false).unwrap(), Outcome::Done);
assert_eq!(speaks(&h.join().unwrap()), 1);
}
#[test]
fn a_sentence_that_never_begins_halts_reading_instead_of_failing() {
// `PAUSE all` before our message began sends no event: the time queued has its own
// bound, and reaching it halts reading (Play carries on) rather than stopping with an error.
let (client, srv) = UnixStream::pair().unwrap();
let h = server(srv, Ending::NeverBegins);
let req = Request { text: "Queued behind another client.", rate: 0, lang: None };
let start = Instant::now();
assert_eq!(converse(&Stream::Unix(client), &req, &|| false).unwrap(), Outcome::NotStarted);
assert!(start.elapsed() >= QUEUE_WAIT && start.elapsed() < QUEUE_WAIT + REPLY_TIMEOUT * 2, "{:?}", start.elapsed());
assert!(h.join().unwrap().contains(&"CANCEL self".to_string()));
}
#[test]
fn a_sentence_that_never_ends_times_out() {
// A stuck speech module: no end event ever. The wait is bounded by the sentence's length.
let (client, srv) = UnixStream::pair().unwrap();
let h = server(srv, Ending::Hold);
let req = Request { text: "x", rate: 0, lang: None };
let start = Instant::now();
assert_eq!(converse(&Stream::Unix(client), &req, &|| false).unwrap_err().kind(), ErrorKind::TimedOut);
assert!(start.elapsed() < SENTENCE_BASE + SENTENCE_PER_CHAR + REPLY_TIMEOUT * 2, "{:?}", start.elapsed());
assert!(h.join().unwrap().contains(&"CANCEL self".to_string()), "the stuck message is dropped");
}
#[test]
fn moving_on_cancels_only_our_own_speech() {
let (client, srv) = UnixStream::pair().unwrap();
let h = server(srv, Ending::Hold);
let req = Request { text: "Long sentence.", rate: 0, lang: None };
let start = Instant::now();
let changed = || start.elapsed() > Duration::from_millis(300);
assert_eq!(converse(&Stream::Unix(client), &req, &changed).unwrap(), Outcome::Interrupted);
let got = h.join().unwrap();
assert_eq!(speaks(&got), 1, "{got:?}");
assert!(got.contains(&"CANCEL self".to_string()), "{got:?}");
assert!(!got.iter().any(|l| l.eq_ignore_ascii_case("CANCEL all")));
assert!(!got.iter().any(|l| l.starts_with("SET SELF LANGUAGE")), "no language, no command");
}
#[test]
fn moving_on_stops_waiting_for_a_slow_server() {
// A server that reads but never answers: Stop acts at once, not after the reply timeout.
let (client, mut srv) = UnixStream::pair().unwrap();
let h = std::thread::spawn(move || {
let mut all = String::new();
let _ = srv.read_to_string(&mut all);
all
});
let req = Request { text: "x", rate: 0, lang: None };
let start = Instant::now();
assert_eq!(converse(&Stream::Unix(client), &req, &|| true).unwrap(), Outcome::Interrupted);
assert!(start.elapsed() < REPLY_TIMEOUT, "{:?}", start.elapsed());
// Stopped while the server may be about to read message data: the empty line and `.` end
// any message first, so `CANCEL self` is never taken for text.
let all = h.join().unwrap();
assert!(all.ends_with("\r\n\r\n.\r\nCANCEL self\r\nQUIT\r\n"), "{all:?}");
}
#[test]
fn a_server_that_only_sends_events_times_out() {
// Events and continuation lines are no reply: they can't keep a command waiting forever.
let (client, mut srv) = UnixStream::pair().unwrap();
let h = std::thread::spawn(move || while srv.write_all(b"701 BEGIN\r\n225-1\r\n").is_ok() {});
let req = Request { text: "x", rate: 0, lang: None };
let start = Instant::now();
let client = Stream::Unix(client);
assert_eq!(converse(&client, &req, &|| false).unwrap_err().kind(), ErrorKind::TimedOut);
assert!(start.elapsed() < REPLY_TIMEOUT * 3, "{:?}", start.elapsed());
drop(client);
h.join().unwrap();
}
#[test]
fn a_hostile_language_tag_is_never_sent() {
let (client, srv) = UnixStream::pair().unwrap();
let h = server(srv, Ending::End);
let req = Request { text: "x", rate: 0, lang: Some("hu\r\nCANCEL all") };
assert_eq!(converse(&Stream::Unix(client), &req, &|| false).unwrap(), Outcome::Done);
let got = h.join().unwrap();
assert!(!got.iter().any(|l| l.starts_with("SET SELF LANGUAGE") || l.starts_with("CANCEL")), "{got:?}");
}
#[test]
fn a_server_that_hangs_up_is_an_error_not_a_hang() {
let (client, mut srv) = UnixStream::pair().unwrap();
let h = std::thread::spawn(move || {
let mut buf = [0u8; 64];
let _ = srv.read(&mut buf);
});
let req = Request { text: "x", rate: 0, lang: None };
assert!(converse(&Stream::Unix(client), &req, &|| false).is_err());
h.join().unwrap();
}
#[test]
fn a_start_command_that_exits_reports_how() {
let far = Instant::now() + Duration::from_secs(30);
let run = |script: &str| start_server(std::process::Command::new("sh").args(["-c", script]), far, &|| false);
assert!(matches!(run("exit 0"), Started::Exited(true)));
assert!(matches!(run("exit 1"), Started::Exited(false)));
let missing = start_server(&mut std::process::Command::new("no-such-program-for-wordcraft"), far, &|| false);
assert!(matches!(missing, Started::Missing), "{missing:?}");
}
/// A start command that never exits, writing its process id to `pid` first (whole, by renaming).
fn hanging_start(pid: &std::path::Path) -> std::process::Command {
let mut c = std::process::Command::new("sh");
c.args(["-c", "echo $$ > \"$1.part\" && mv \"$1.part\" \"$1\" && exec sleep 30", "sh"]).arg(pid);
c
}
/// A fresh path for a start command's process id.
fn pid_file(name: &str) -> std::path::PathBuf {
let p = std::env::temp_dir().join(format!("wordcraft-ssip-{}-{name}.pid", std::process::id()));
let _ = std::fs::remove_file(&p);
let _ = std::fs::remove_file(p.with_extension("pid.part"));
p
}
/// The process id the start command wrote (whole, or still in its `.part` file when it was
/// stopped before renaming it); `None` when it was stopped before writing any.
fn written_pid(pid: &std::path::Path) -> Option<String> {
let part = pid.with_extension("pid.part");
let id = std::fs::read_to_string(pid).or_else(|_| std::fs::read_to_string(&part)).ok();
let _ = std::fs::remove_file(pid);
let _ = std::fs::remove_file(part);
id.map(|id| id.trim().to_string()).filter(|id| !id.is_empty())
}
/// Is process `id` gone: reaped, not merely killed and left a zombie (which `kill -0` still
/// finds)?
fn gone(id: &str) -> bool {
let probe = std::process::Command::new("sh").args(["-c", "kill -0 \"$1\" 2>/dev/null", "sh", id]).status().unwrap();
!probe.success()
}
#[test]
fn a_start_command_that_hangs_is_stopped_at_the_deadline() {
// A start stopped before the stand-in wrote its id is tried again with a longer deadline
// (a loaded machine may not run it at once); one that never wrote it left nothing to reap.
for deadline in [Duration::from_secs(1), Duration::from_secs(3), Duration::from_secs(10)] {
let pid = pid_file("deadline");
let begun = Instant::now();
let got = start_server(&mut hanging_start(&pid), begun + deadline, &|| false);
assert!(matches!(got, Started::TimedOut), "{got:?}");
assert!(begun.elapsed() < deadline + Duration::from_secs(4), "{:?}", begun.elapsed());
if let Some(id) = written_pid(&pid) {
assert!(gone(&id), "the start command was reaped");
return;
}
}
}
#[test]
fn stop_ends_the_wait_for_a_start_command_at_once() {
let pid = pid_file("stop");
let begun = Instant::now();
// Stop once the command is surely running.
let got = start_server(&mut hanging_start(&pid), begun + Duration::from_secs(30), &|| pid.exists());
assert!(matches!(got, Started::Interrupted), "{got:?}");
assert!(begun.elapsed() < Duration::from_secs(5), "{:?}", begun.elapsed());
let id = written_pid(&pid).expect("stopped only once the id was written");
assert!(gone(&id), "the start command was reaped");
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.