feat(ssip): extract bounded Speech Dispatcher wire helpers (#1500)

Adapted from WordCraft SSIP implementation; preserves contributor framing behavior while rejecting overlong complete lines.

Co-authored-by: Skaywalker <115165402+Skaywalker@users.noreply.github.com>
This commit is contained in:
Dylan M. Taylor
2026-11-16 09:55:17 -05:00
committed by GitHub
co-authored by Skaywalker
parent 9ac3245966
commit eeae2bb7ca
5 changed files with 175 additions and 0 deletions
Generated
+4
View File
@@ -2798,6 +2798,10 @@ dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-ssip"
version = "0.1.0"
[[package]]
name = "craft-stencilcraft-format"
version = "0.1.0"
+1
View File
@@ -15,6 +15,7 @@ craft-shx = { path = "crates/shx" }
craft-http-url = { path = "crates/http-url" }
craft-usd = { path = "crates/usd" }
craft-smime = { path = "crates/smime" }
craft-ssip = { path = "crates/ssip" }
craft-ber = { path = "crates/ber" }
craft-proto = { path = "crates/proto" }
craft-render-parity = { path = "crates/render-parity" }
+11
View File
@@ -0,0 +1,11 @@
[package]
name = "craft-ssip"
description = "Bounded Speech Dispatcher SSIP wire framing and message-data encoding"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
+19
View File
@@ -0,0 +1,19 @@
# craft-ssip
A focused Speech Dispatcher SSIP wire layer: sentence-as-data encoding, final response codes,
and a bounded incremental reply reader. No sockets, process launch, cancellation commands,
voice discovery, retry or playback scheduling: those policies remain with the application.
Derived from Skaywalker's WordCraft SSIP implementation in
`crates/engine/src/speech/ssip.rs` at `e9750c5cb75d577a4669059d7bf6f9874e945839`
(MIT OR Apache-2.0). WordCraft #2937 (`65d7999eddebf120ca9fde523b01156b3e1f5fce`)
adds voice selection on this same core; this extraction does not duplicate those application changes.
Unlike the original reader, a complete line that becomes overlong in the final read is refused.
The 4096-byte limit counts bytes before LF, including an optional CR. Reply buffering holds
at most that limit plus one 512-byte read. Invalid UTF-8 is replaced, preserving WordCraft behavior.
Message input is bounded by the caller; ASCII three-digit response codes are enforced.
Caller-provided `Read` implementations must obey Rust's Read contract; callers remain responsible
for transport timeouts, cancellation and an overall deadline between `next_line` calls.
This is not a complete SSIP client and does not establish WordCraft consumer cutover.
+140
View File
@@ -0,0 +1,140 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
//! Speech Dispatcher SSIP wire helpers extracted from WordCraft's contributor implementation.
//! Socket discovery, deadlines, voice selection, retry and cancellation policy stay in the app.
use std::io::{self, ErrorKind, Read};
/// Maximum reply bytes before LF, including an optional CR.
pub const MAX_LINE: usize = 4096;
/// Encode one sentence as data, never as protocol commands. CR/LF become spaces; a leading
/// dot is doubled and the message terminator is appended. The caller bounds input bytes.
pub fn message_data(text: &str, max_input_bytes: usize) -> io::Result<String> {
if text.len() > max_input_bytes {
return Err(ErrorKind::InvalidInput.into());
}
let size = text.len().checked_add(6).ok_or(ErrorKind::InvalidInput)?;
let mut out = String::new();
out.try_reserve_exact(size).map_err(|_| io::Error::other("SSIP message allocation failed"))?;
if text.starts_with('.') {
out.push('.');
}
out.extend(text.chars().map(|c| if c == '\r' || c == '\n' { ' ' } else { c }));
out.push_str("\r\n.\r\n");
Ok(out)
}
/// The three ASCII digits of a final response; continuation (`225-...`) is not final.
pub fn final_code(line: &str) -> Option<u16> {
let digits = line.as_bytes().get(..3)?;
if !digits.iter().all(u8::is_ascii_digit) || !(line.len() == 3 || line.as_bytes().get(3) == Some(&b' ')) {
return None;
}
line.get(..3)?.parse().ok()
}
/// Incremental replies. At most one read per call lets the app enforce its own deadline.
/// Invalid UTF-8 retains WordCraft's replacement-character behavior. Overlong replies fail,
/// including those whose terminating newline arrives in the same read that exceeds the cap.
pub struct Lines<R> {
reader: R,
pending: Vec<u8>,
}
impl<R: Read> Lines<R> {
pub fn new(reader: R) -> Self {
Self { reader, pending: Vec::new() }
}
/// Complete next line without CR/LF, or None after a partial read or transient timeout.
/// The caller must set transport timeouts and enforce cancellation/deadlines.
pub fn next_line(&mut self) -> io::Result<Option<String>> {
if let Some(line) = self.complete_line()? {
return Ok(Some(line));
}
let mut buf = [0u8; 512];
match self.reader.read(&mut buf) {
Ok(0) => Err(ErrorKind::UnexpectedEof.into()),
Ok(n) => {
let bytes = buf.get(..n).ok_or(ErrorKind::InvalidData)?;
// Invariant: pending <= MAX_LINE before this read, so storage <= MAX_LINE+512.
self.pending.try_reserve(bytes.len()).map_err(|_| io::Error::other("SSIP reply allocation failed"))?;
self.pending.extend_from_slice(bytes);
self.complete_line()
}
Err(e) if matches!(e.kind(), ErrorKind::WouldBlock | ErrorKind::TimedOut | ErrorKind::Interrupted) => Ok(None),
Err(e) => Err(e),
}
}
fn complete_line(&mut self) -> io::Result<Option<String>> {
let end = self.pending.iter().position(|&b| b == b'\n');
if end.unwrap_or(self.pending.len()) > MAX_LINE {
return Err(ErrorKind::InvalidData.into());
}
let Some(end) = end else { return Ok(None) };
let bytes = self.pending.get(..end).ok_or(ErrorKind::InvalidData)?;
let line = String::from_utf8_lossy(bytes).trim_end_matches('\r').to_string();
self.pending.drain(..=end);
Ok(Some(line))
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use std::collections::VecDeque;
struct Chunks(VecDeque<io::Result<Vec<u8>>>);
impl Read for Chunks {
fn read(&mut self, out: &mut [u8]) -> io::Result<usize> {
let bytes = self.0.pop_front().unwrap_or(Ok(Vec::new()))?;
out[..bytes.len()].copy_from_slice(&bytes);
Ok(bytes.len())
}
}
#[test]
fn message_text_cannot_inject_commands() {
assert_eq!(message_data(".\r\nCANCEL ALL\n!-!", 64).unwrap(), ".. CANCEL ALL !-!\r\n.\r\n");
assert_eq!(message_data("你好", 6).unwrap(), "你好\r\n.\r\n");
assert!(message_data("你好", 5).is_err());
}
#[test]
fn final_codes_are_ascii_and_not_continuations() {
assert_eq!(final_code("225 OK"), Some(225));
assert_eq!(final_code("701"), Some(701));
for bad in ["225-12", "+22 OK", "22 OK", "225 OK", "225x", ""] {
assert_eq!(final_code(bad), None);
}
}
#[test]
fn fragmented_utf8_timeout_and_buffered_lines() {
let mut lines = Lines::new(Chunks(VecDeque::from([
Ok(vec![b'2', b'2', b'5', b' ', 0xc3]),
Err(ErrorKind::TimedOut.into()),
Ok(vec![0xa9, b'\r', b'\n', b'7', b'0', b'2', b'\n']),
])));
assert!(lines.next_line().unwrap().is_none());
assert!(lines.next_line().unwrap().is_none());
assert_eq!(lines.next_line().unwrap().as_deref(), Some("225 é"));
assert_eq!(lines.next_line().unwrap().as_deref(), Some("702"));
assert_eq!(lines.next_line().unwrap_err().kind(), ErrorKind::UnexpectedEof);
}
#[test]
fn completed_overlong_line_is_rejected_at_boundary() {
for extra in [0, 1, 511] {
let mut chunks: VecDeque<_> = (0..8).map(|_| Ok(vec![b'x'; 512])).collect();
let mut last = vec![b'x'; extra];
last.push(b'\n');
chunks.push_back(Ok(last));
let mut lines = Lines::new(Chunks(chunks));
for _ in 0..8 {
assert!(lines.next_line().unwrap().is_none());
}
if extra == 0 {
assert_eq!(lines.next_line().unwrap().unwrap().len(), MAX_LINE);
} else {
assert_eq!(lines.next_line().unwrap_err().kind(), ErrorKind::InvalidData);
}
}
}
}