mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-16 20:25:02 +00:00
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:
co-authored by
Skaywalker
parent
9ac3245966
commit
eeae2bb7ca
Generated
+4
@@ -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"
|
||||
|
||||
@@ -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" }
|
||||
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user