diff --git a/crates/canvas-pilot/src/device.rs b/crates/canvas-pilot/src/device.rs index dfb2f41..72af11d 100644 --- a/crates/canvas-pilot/src/device.rs +++ b/crates/canvas-pilot/src/device.rs @@ -221,6 +221,14 @@ pub fn fetch(host: &str) -> Result { pub fn fetch_cancellable( host: &str, cancelled: &std::sync::atomic::AtomicBool, +) -> Result { + fetch_with_awj_port(host, cancelled, 10606) +} + +pub(crate) fn fetch_with_awj_port( + host: &str, + cancelled: &std::sync::atomic::AtomicBool, + awj_port: u16, ) -> Result { if cancelled.load(std::sync::atomic::Ordering::Relaxed) { return Err("Device read cancelled.".into()); @@ -246,8 +254,8 @@ pub fn fetch_cancellable( cancelled, )?, Profile::Aquilon6 => state::fetch( - &client, - &format!("http://{authority}/api/stores/device"), + SocketAddr::new(authority.ip(), awj_port), + &identity, cancelled, )?, }; diff --git a/crates/canvas-pilot/src/device/state.rs b/crates/canvas-pilot/src/device/state.rs index 8b106cf..abed3bf 100644 --- a/crates/canvas-pilot/src/device/state.rs +++ b/crates/canvas-pilot/src/device/state.rs @@ -1,263 +1,785 @@ -//! Bounded streaming projection of Aquilon's large store. Unused trees are skipped, never cloned. -use serde::de::{self, DeserializeSeed, IgnoredAny, MapAccess, Visitor}; -use serde_json::{Map, Value}; +//! Targeted Aquilon reads over AWJ (TCP 10606). No full-store download or retained cache. +use super::*; +use serde_json::json; use std::{ - fmt, - io::{BufReader, Read}, + collections::{BTreeMap, BTreeSet}, + io::{BufRead, BufReader, Write}, + net::TcpStream, + sync::atomic::{AtomicBool, Ordering}, + time::Instant, }; -// Only this adapter's native fields are retained. '*' matches one native identifier. -const FIELDS: &[&str] = &[ - "device/screenList/items/*/status/pp/*", - "device/screenList/items/*/status/size/pp/*", - "device/auxiliaryList/items/*/status/pp/*", - "device/auxiliaryList/items/*/status/size/pp/*", - "device/screenList/items/*/presetList/items/*/layerList/items/*/position/pp/*", - "device/screenList/items/*/presetList/items/*/layerList/items/*/source/pp/*", - "device/screenList/items/*/presetList/items/*/layerList/items/*/cropping/classic/pp/*", - "device/screenList/items/*/presetList/items/*/layerList/items/*/cropping/mask/pp/*", - "device/auxiliaryList/items/*/presetList/items/*/layerList/items/*/position/pp/*", - "device/auxiliaryList/items/*/presetList/items/*/layerList/items/*/source/pp/*", - "device/auxiliaryList/items/*/presetList/items/*/layerList/items/*/cropping/classic/pp/*", - "device/auxiliaryList/items/*/presetList/items/*/layerList/items/*/cropping/mask/pp/*", - "device/screenAuxGroupList/items/*/control/pp/*", - "device/screenAuxGroupList/items/*/status/pp/*", - "device/inputList/items/*/status/pp/*", - "device/inputList/items/*/snapshot/pp/*", - "device/inputList/items/*/plugList/items/*/status/signal/pp/*", - "device/inputList/items/*/plugList/items/*/settings/aspect/pp/*", - "device/inputList/items/*/plugList/items/*/settings/cropping/status/pp/*", -]; -struct Budget { - nodes: usize, - strings: usize, +const MAX_FRAME: usize = 16 * 1024; +const MAX_BYTES: usize = 16 * 1024 * 1024; +const MAX_FIELDS: usize = 65_536; +const BATCH: usize = 64; + +fn awj_path(path: &str) -> String { + path.trim_start_matches('/') + .split('/') + .map(|part| match part { + "device" => "DeviceObject".to_owned(), + "items" => "@items".to_owned(), + "pp" => "@props".to_owned(), + p if p.ends_with("List") => format!("${}", &p[..p.len() - 4]), + p => p.to_owned(), + }) + .collect::>() + .join("/") } -struct Seed<'a> { - path: Vec, - budget: &'a mut Budget, - patterns: &'a [Vec<&'static str>], +trait Reader { + fn get(&mut self, paths: &[String]) -> Result, String>; } -impl<'de> DeserializeSeed<'de> for Seed<'_> { - type Value = Value; - fn deserialize>(self, d: D) -> Result { - if self.budget.nodes == 0 { - return Err(de::Error::custom("Decoded state exceeds one million nodes")); +struct Connection<'a> { + reader: BufReader, + cancelled: &'a AtomicBool, + deadline: Instant, + bytes: usize, +} +impl Connection<'_> { + fn check(&self) -> Result<(), String> { + if self.cancelled.load(Ordering::Relaxed) { + Err("Device read cancelled.".into()) + } else if Instant::now() >= self.deadline { + Err("Aquilon targeted read timed out after 30 seconds.".into()) + } else { + Ok(()) + } + } + fn frame(&mut self) -> Result { + let mut frame = Vec::new(); + loop { + self.check()?; + let chunk = match self.reader.fill_buf() { + Ok([]) => return Err("Aquilon AWJ connection closed during read.".into()), + Ok(chunk) => chunk, + Err(e) + if matches!( + e.kind(), + std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut + ) => + { + continue; + } + Err(e) => return Err(format!("Cannot read Aquilon AWJ response: {e}")), + }; + let end = chunk.iter().position(|b| *b == 4); + let size = end.map_or(chunk.len(), |n| n + 1); + self.bytes += size; + if frame.len() + size > MAX_FRAME || self.bytes > MAX_BYTES { + return Err("Aquilon targeted response exceeds its size budget.".into()); + } + frame.extend_from_slice(&chunk[..size]); + self.reader.consume(size); + if end.is_some() { + frame.pop(); + return serde_json::from_slice(&frame) + .map_err(|e| format!("Invalid Aquilon AWJ response: {e}")); + } } - self.budget.nodes -= 1; - d.deserialize_any(self) } } -impl Seed<'_> { - fn charge(&mut self, text: &str) -> Result<(), E> { - if text.len() > 1024 || text.len() > self.budget.strings { - return Err(E::custom("Decoded state string budget exceeded")); +impl Reader for Connection<'_> { + fn get(&mut self, paths: &[String]) -> Result, String> { + let mut result = Vec::with_capacity(paths.len()); + for batch in paths.chunks(BATCH) { + self.check()?; + let canonical: Vec<_> = batch.iter().map(|p| awj_path(p)).collect(); + let mut pending: BTreeSet<_> = canonical.iter().cloned().collect(); + if pending.len() != batch.len() { + return Err("Duplicate targeted read path.".into()); + } + let mut request = Vec::new(); + for path in &canonical { + serde_json::to_writer(&mut request, &json!({"op":"get","path":path})) + .map_err(|e| e.to_string())?; + request.push(4); + } + self.reader + .get_mut() + .write_all(&request) + .map_err(|e| format!("Cannot request Aquilon fields: {e}"))?; + let mut values = BTreeMap::new(); + while !pending.is_empty() { + let response = self.frame()?; + if let Some(error) = response.get("error") { + return Err(format!("Aquilon rejected targeted read: {error}")); + } + let path = response + .get("path") + .and_then(Value::as_str) + .ok_or("AWJ response has no path")?; + if !pending.remove(path) { + return Err(format!( + "Unexpected or duplicate Aquilon AWJ response: {path}" + )); + } + values.insert( + path.to_owned(), + response + .get("value") + .ok_or("AWJ response has no value")? + .clone(), + ); + } + result.extend(canonical.iter().map(|path| values.remove(path).unwrap())); } - self.budget.strings -= text.len(); + Ok(result) + } +} + +pub(super) fn fetch( + address: SocketAddr, + identity: &Value, + cancelled: &AtomicBool, +) -> Result { + let stream = TcpStream::connect_timeout(&address, Duration::from_secs(3)) + .map_err(|e| format!("Cannot connect to Aquilon AWJ at {address}: {e}. Enable/reach TCP port {} for targeted reads; no full-store fallback is performed.", address.port()))?; + stream + .set_read_timeout(Some(Duration::from_millis(250))) + .map_err(|e| e.to_string())?; + stream + .set_write_timeout(Some(Duration::from_secs(3))) + .map_err(|e| e.to_string())?; + stream.set_nodelay(true).map_err(|e| e.to_string())?; + let mut connection = Connection { + reader: BufReader::new(stream), + cancelled, + deadline: Instant::now() + Duration::from_secs(30), + bytes: 0, + }; + collect(&mut connection, identity) +} +fn set(raw: &mut Value, path: &str, value: Value) { + let mut node = raw; + for key in path.trim_start_matches('/').split('/') { + if !node.is_object() { + *node = json!({}); + } + node = node + .as_object_mut() + .unwrap() + .entry(key) + .or_insert(Value::Null); + } + *node = value; +} +struct State<'a, R> { + reader: &'a mut R, + raw: Value, + paths: Vec, + values: Vec, +} +impl State<'_, R> { + fn read(&mut self, paths: Vec) -> Result<(), String> { + if self.paths.len() + paths.len() > MAX_FIELDS { + return Err("Aquilon targeted read exceeds 65536 fields.".into()); + } + let values = self.reader.get(&paths)?; + if values.len() != paths.len() { + return Err("Incomplete Aquilon targeted read.".into()); + } + for (path, value) in paths.iter().zip(&values) { + set(&mut self.raw, path, value.clone()); + } + self.paths.extend(paths); + self.values.extend(values); Ok(()) } -} -impl<'de> Visitor<'de> for Seed<'_> { - type Value = Value; - fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { - f.write_str("bounded native device fields") - } - fn visit_map>(mut self, mut map: M) -> Result { - if self.path.len() > 20 { - return Err(de::Error::custom("Device nesting limit exceeded")); + fn keys(&self, list: &str, prefix: &str) -> Result, String> { + let keys = value(&self.raw, &format!("/device/{list}/itemKeys"))? + .as_array() + .ok_or("Invalid Aquilon itemKeys")?; + if keys.len() > 256 { + return Err("Aquilon collection exceeds 256 entries.".into()); } - let mut result = Map::new(); - while let Some(key) = map.next_key::()? { - self.charge(&key)?; - let mut path = self.path.clone(); - path.push(key.clone()); - let keep = self.patterns.iter().any(|parts| { - path.len() <= parts.len() - && path.iter().zip(parts).all(|(key, p)| *p == "*" || key == p) - }); - if keep { - if result.len() >= 256 { - return Err(de::Error::custom("Device collection exceeds 256 items")); - } - let v = map.next_value_seed(Seed { - path, - budget: self.budget, - patterns: self.patterns, - })?; - if result.insert(key, v).is_some() { - return Err(de::Error::custom("Duplicate device field")); - } - } else { - map.next_value::()?; + let mut unique = BTreeSet::new(); + for key in keys { + let key = key.as_str().ok_or("Invalid Aquilon identifier")?; + let id = key + .strip_prefix(prefix) + .ok_or("Invalid Aquilon identifier prefix")?; + if id.is_empty() + || id.len() > 16 + || id.starts_with('0') + || !id.bytes().all(|b| b.is_ascii_digit()) + || !unique.insert(key.to_owned()) + { + return Err("Invalid or duplicate Aquilon identifier.".into()); } } - Ok(Value::Object(result)) - } - fn visit_seq>(self, mut seq: A) -> Result { - // Status flags can be arrays. They are not part of the geometry model. - let mut count = 0; - while seq.next_element::()?.is_some() { - count += 1; - if count > 256 { - return Err(de::Error::custom("Device array exceeds 256 entries")); - } - } - Ok(Value::Null) - } - fn visit_bool(self, v: bool) -> Result { - Ok(v.into()) - } - fn visit_u64(self, v: u64) -> Result { - Ok(v.into()) - } - fn visit_i64(self, v: i64) -> Result { - Ok(v.into()) - } - fn visit_f64(self, v: f64) -> Result { - serde_json::Number::from_f64(v) - .map(Value::Number) - .ok_or_else(|| E::custom("Nonfinite device number")) - } - fn visit_str(mut self, v: &str) -> Result { - self.charge(v)?; - Ok(v.into()) - } - fn visit_string(mut self, v: String) -> Result { - self.charge(&v)?; - Ok(v.into()) - } - fn visit_unit(self) -> Result { - Ok(Value::Null) + Ok(unique.into_iter().collect()) } } -pub(super) fn fetch( - client: &reqwest::blocking::Client, - url: &str, - cancelled: &std::sync::atomic::AtomicBool, -) -> Result { - let response = client - .get(url) - .send() - .and_then(|r| r.error_for_status()) - .map_err(|e| format!("Cannot read Aquilon state: {e}"))?; - if !response.status().is_success() { - return Err("Device redirected the state request; check authentication.".into()); - } - const LIMIT: u64 = 160 * 1024 * 1024; - if response.content_length().is_some_and(|size| size > LIMIT) { - return Err("Aquilon state exceeds 160 MiB.".into()); - } - let mut bounded = super::CancelReader { - inner: response, - cancelled, - } - .take(LIMIT + 1); - let projected = project(BufReader::new(&mut bounded))?; - if bounded.limit() == 0 { - return Err("Aquilon state exceeds 160 MiB.".into()); - } - Ok(projected) +fn fields(paths: &mut Vec, base: &str, suffixes: &[&str]) { + paths.extend(suffixes.iter().map(|suffix| format!("{base}/{suffix}"))); } -pub(super) fn project(reader: impl Read) -> Result { - let patterns: Vec> = FIELDS.iter().map(|p| p.split('/').collect()).collect(); - let mut budget = Budget { - nodes: 1_000_000, - strings: 16 * 1024 * 1024, +fn collect(reader: &mut impl Reader, identity: &Value) -> Result { + let mut state = State { + reader, + raw: json!({"device":{"screenList":{"items":{}},"auxiliaryList":{"items":{}},"inputList":{"items":{}}}}), + paths: vec![], + values: vec![], }; - let mut deserializer = serde_json::Deserializer::from_reader(reader); - let mut root = Seed { - path: vec![], - budget: &mut budget, - patterns: &patterns, + state.read(vec![ + "/device/system/deviceList/items/1/pp/dev".into(), + "/device/system/deviceList/items/1/version/pp/updater".into(), + "/device/screenList/itemKeys".into(), + "/device/auxiliaryList/itemKeys".into(), + "/device/inputList/itemKeys".into(), + ])?; + let version = format!( + "{}.{}.{}", + identity["version"]["major"], identity["version"]["minor"], identity["version"]["patch"] + ); + if text(&state.raw, "/device/system/deviceList/items/1/pp/dev")? != "NLC_CMAX" + || text( + &state.raw, + "/device/system/deviceList/items/1/version/pp/updater", + )? != version + { + return Err("Aquilon AWJ model/firmware does not match the HTTP device identity.".into()); } - .deserialize(&mut deserializer) - .map_err(|e| format!("Invalid or oversized Aquilon state: {e}"))?; - deserializer.end().map_err(|e| e.to_string())?; - for list in ["screenList", "auxiliaryList"] { - let screens = root - .pointer_mut(&format!("/device/{list}/items")) - .and_then(Value::as_object_mut) - .ok_or("Missing screen list")?; - screens.retain(|_, s| { - s.pointer("/status/pp/mode").and_then(Value::as_str) != Some("DISABLED") - }); - for screen in screens.values_mut() { - let count = screen - .pointer("/status/pp/layerCount") - .and_then(Value::as_u64) - .filter(|n| *n <= 128) - .ok_or("Invalid allocated layer count")?; - let presets = screen - .pointer_mut("/presetList/items") - .and_then(Value::as_object_mut) - .ok_or("Missing presets")?; - for preset in presets.values_mut() { - let layers = preset - .pointer_mut("/layerList/items") - .and_then(Value::as_object_mut) - .ok_or("Missing layers")?; - layers.retain(|id, _| id.parse::().is_ok_and(|n| n > 0 && n <= count)); + let mut screens = Vec::new(); + for (list, prefix) in [("screenList", "S"), ("auxiliaryList", "A")] { + for id in state.keys(list, prefix)? { + screens.push(format!("/device/{list}/items/{id}")); + } + } + let inputs = state.keys("inputList", "IN_")?; + let mut paths = screens + .iter() + .map(|s| format!("{s}/status/pp/mode")) + .collect::>(); + paths.extend( + inputs + .iter() + .map(|i| format!("/device/inputList/items/{i}/status/pp/isAvailable")), + ); + state.read(paths)?; + let screens: Vec<_> = screens + .into_iter() + .map(|screen| { + let mode = text(&state.raw, &format!("{screen}/status/pp/mode"))?; + Ok((screen, mode != "DISABLED")) + }) + .collect::, String>>()? + .into_iter() + .filter_map(|(screen, enabled)| enabled.then_some(screen)) + .collect(); + let inputs: Vec<_> = inputs + .into_iter() + .map(|input| { + let available = value( + &state.raw, + &format!("/device/inputList/items/{input}/status/pp/isAvailable"), + )? + .as_bool() + .ok_or("Invalid Aquilon input availability")?; + Ok((input, available)) + }) + .collect::, String>>()? + .into_iter() + .filter_map(|(input, available)| available.then_some(input)) + .collect(); + let mut paths = Vec::new(); + for screen in &screens { + fields( + &mut paths, + screen, + &[ + "status/pp/layerCount", + "status/pp/transitionGroup", + "status/size/pp/sizeH", + "status/size/pp/sizeV", + ], + ); + } + for input in &inputs { + fields( + &mut paths, + &format!("/device/inputList/items/{input}"), + &["status/pp/plug", "snapshot/pp/enable"], + ); + } + state.read(paths)?; + let mut groups = BTreeSet::new(); + let mut paths = Vec::new(); + for screen in &screens { + let group = text(&state.raw, &format!("{screen}/status/pp/transitionGroup"))?; + if group.is_empty() || group.len() > 16 || !group.bytes().all(|b| b.is_ascii_alphanumeric()) + { + return Err("Invalid Aquilon transition group identifier.".into()); + } + groups.insert(group); + } + for group in &groups { + fields( + &mut paths, + &format!("/device/screenAuxGroupList/items/{group}"), + &[ + "control/pp/presetUp", + "control/pp/presetDown", + "status/pp/transition", + ], + ); + } + for input in &inputs { + let base = format!("/device/inputList/items/{input}"); + let plug = text(&state.raw, &format!("{base}/status/pp/plug"))?; + if plug.is_empty() || plug.len() > 16 || !plug.bytes().all(|b| b.is_ascii_digit()) { + return Err("Invalid Aquilon plug identifier.".into()); + } + fields( + &mut paths, + &format!("{base}/plugList/items/{plug}"), + &[ + "status/signal/pp/imageWidth", + "status/signal/pp/imageHeight", + "status/signal/pp/isValid", + "settings/aspect/pp/signal", + "settings/aspect/pp/transformTo", + "settings/aspect/pp/layerFill", + "settings/cropping/status/pp/left", + "settings/cropping/status/pp/right", + "settings/cropping/status/pp/top", + "settings/cropping/status/pp/bottom", + ], + ); + } + state.read(paths)?; + let mut paths = Vec::new(); + for screen in &screens { + let count = value(&state.raw, &format!("{screen}/status/pp/layerCount"))? + .as_u64() + .filter(|v| *v <= 128) + .ok_or("Invalid allocated layer count")?; + let group = text(&state.raw, &format!("{screen}/status/pp/transitionGroup"))?; + let base = format!("/device/screenAuxGroupList/items/{group}"); + let up = text(&state.raw, &format!("{base}/control/pp/presetUp"))?; + let down = text(&state.raw, &format!("{base}/control/pp/presetDown"))?; + if up == down + || ![&up, &down] + .iter() + .all(|b| matches!(b.as_str(), "A" | "B" | "C")) + { + return Err("Invalid Aquilon bank mapping.".into()); + } + if !matches!( + text(&state.raw, &format!("{base}/status/pp/transition"))?.as_str(), + "AT_UP" | "AT_DOWN" + ) { + return Err("Aquilon screen is transitioning; refresh when idle.".into()); + } + for bank in [&up, &down] { + for layer in 1..=count { + fields( + &mut paths, + &format!("{screen}/presetList/items/{bank}/layerList/items/{layer}"), + &[ + "position/pp/posH", + "position/pp/posV", + "position/pp/sizeH", + "position/pp/sizeV", + "position/pp/anchor", + "source/pp/inputNum", + "cropping/classic/pp/aspectOverride", + "cropping/classic/pp/left", + "cropping/classic/pp/right", + "cropping/classic/pp/top", + "cropping/classic/pp/bottom", + "cropping/mask/pp/left", + "cropping/mask/pp/right", + "cropping/mask/pp/top", + "cropping/mask/pp/bottom", + ], + ); + if paths.len() > MAX_FIELDS { + return Err("Aquilon targeted read exceeds 65536 fields.".into()); + } } } } - let inputs = root - .pointer_mut("/device/inputList/items") - .and_then(Value::as_object_mut) - .ok_or("Missing inputs")?; - inputs.retain(|_, input| { - input - .pointer("/status/pp/isAvailable") - .and_then(Value::as_bool) - == Some(true) - }); - Ok(root) + state.read(paths)?; + // A second bounded pass catches edits, input changes and bank/allocation changes + // while collecting the first pass. Never use a mixed snapshot to plan writes. + if state.reader.get(&state.paths)? != state.values { + return Err("Aquilon state changed during targeted read. Refresh when idle.".into()); + } + Ok(state.raw) } #[cfg(test)] mod tests { use super::*; - #[test] - fn projection_retains_allocated_geometry_and_skips_unrelated_state() { - let raw = include_str!("../../tests/fixtures/aquilon-6.2.json"); - let projected = project(raw.as_bytes()).unwrap(); - assert_eq!( - projected["device"]["screenList"]["items"] - .as_object() - .unwrap() - .len(), - 1 - ); - assert_eq!(projected["device"]["screenList"]["items"]["S1"]["presetList"]["items"]["A"]["layerList"]["items"].as_object().unwrap().len(),7); - let identity = serde_json::json!({"type":"AQL Cmax","isLinked":false,"version":{"major":6,"minor":2,"patch":79}}); - let snapshot = super::super::Snapshot::parse(&identity, &projected).unwrap(); - assert_eq!(snapshot.screens[0].layers.len(), 7); - let mut raw: Value = serde_json::from_str(raw).unwrap(); - raw["device"]["unrelated"] = serde_json::json!({"very_large_unused_array":vec![0;100_000]}); - assert_eq!(project(raw.to_string().as_bytes()).unwrap(), projected); + fn identity() -> Value { + json!({"type":"AQL Cmax","isLinked":false,"version":{"major":6,"minor":2,"patch":79}}) } - #[test] - fn projection_rejects_invalid_bounds_duplicates_and_trailing_json() { - let patterns: Vec> = FIELDS.iter().map(|p| p.split('/').collect()).collect(); - for (text, nodes, strings) in [ - (r#"{"device":{"inputList":{"items":{}}}}"#, 1, 1000), - (r#"{"device":{},"device":{}}"#, 100, 1000), - (r#"{"device":{}}"#, 100, 1), - ] { - let mut budget = Budget { nodes, strings }; - let mut d = serde_json::Deserializer::from_str(text); - assert!( - Seed { - path: vec![], - budget: &mut budget, - patterns: &patterns - } - .deserialize(&mut d) - .is_err() - ); - } - assert!(project(b"{} {}".as_slice()).is_err()); + fn fixture() -> Value { let mut raw: Value = serde_json::from_str(include_str!("../../tests/fixtures/aquilon-6.2.json")).unwrap(); - raw["device"]["screenList"]["items"]["S1"]["status"]["pp"]["layerCount"] = 999.into(); - assert!(project(raw.to_string().as_bytes()).is_err()); + for list in ["screenList", "auxiliaryList", "inputList"] { + let keys: Vec<_> = raw["device"][list]["items"] + .as_object() + .unwrap() + .keys() + .cloned() + .collect(); + raw["device"][list]["itemKeys"] = json!(keys); + } + set( + &mut raw, + "/device/system/deviceList/items/1/pp/dev", + json!("NLC_CMAX"), + ); + set( + &mut raw, + "/device/system/deviceList/items/1/version/pp/updater", + json!("6.2.79"), + ); + raw["device"]["screenList"]["items"]["S1"]["presetList"]["items"]["A"]["layerList"]["items"] + ["1"]["source"]["pp"]["inputNum"] = json!("LIVE_1"); + raw + } + struct Memory { + raw: Value, + calls: usize, + change: bool, + } + impl Reader for Memory { + fn get(&mut self, paths: &[String]) -> Result, String> { + self.calls += 1; + if self.change && self.calls == 6 { + self.raw["device"]["screenAuxGroupList"]["items"]["S1"]["status"]["pp"]["transition"] = + json!("AT_DOWN"); + } + paths + .iter() + .map(|path| { + self.raw + .pointer(path) + .cloned() + .ok_or_else(|| format!("Missing test field {path}")) + }) + .collect() + } + } + fn memory(raw: Value) -> Memory { + Memory { + raw, + calls: 0, + change: false, + } + } + #[test] + fn targeted_collection_reads_only_allocated_banks_and_detects_changes() { + let mut reader = memory(fixture()); + let raw = collect(&mut reader, &identity()).unwrap(); + let snapshot = Snapshot::parse(&identity(), &raw).unwrap(); + assert_eq!(snapshot.screens.len(), 1); + assert_eq!(snapshot.screens[0].layers.len(), 7); + assert!( + raw.pointer("/device/screenList/items/S1/presetList/items/C") + .is_none() + ); + assert!( + raw.pointer("/device/screenList/items/S1/presetList/items/A/layerList/items/8") + .is_none() + ); + assert!( + raw.pointer("/device/auxiliaryList/items/A1/presetList") + .is_none() + ); + assert!( + crate::device_capture::inputs(&snapshot) + .iter() + .any(|i| i.id == 17) + ); + reader = memory(fixture()); + reader.change = true; + assert!( + collect(&mut reader, &identity()) + .unwrap_err() + .contains("changed during") + ); + } + #[test] + fn malformed_topology_and_mismatched_endpoint_fail() { + for (path, bad) in [ + ("/device/system/deviceList/items/1/pp/dev", json!("OTHER")), + ( + "/device/system/deviceList/items/1/version/pp/updater", + json!("6.2.80"), + ), + ("/device/screenList/itemKeys", json!(["S1", "S1"])), + ("/device/screenList/itemKeys", json!(["S1/other"])), + ("/device/inputList/itemKeys", json!(["IN_01"])), + ( + "/device/screenList/items/S1/status/pp/layerCount", + json!(129), + ), + ( + "/device/screenList/items/S1/status/pp/transitionGroup", + json!("../S1"), + ), + ("/device/inputList/items/IN_1/status/pp/plug", json!("../1")), + ( + "/device/screenAuxGroupList/items/S1/control/pp/presetUp", + json!("D"), + ), + ( + "/device/screenAuxGroupList/items/S1/status/pp/transition", + json!("MOVING"), + ), + ] { + let mut raw = fixture(); + set(&mut raw, path, bad); + assert!(collect(&mut memory(raw), &identity()).is_err(), "{path}"); + } + } + fn connect(address: SocketAddr, cancelled: &AtomicBool) -> Connection<'_> { + let stream = TcpStream::connect(address).unwrap(); + stream + .set_read_timeout(Some(Duration::from_millis(50))) + .unwrap(); + Connection { + reader: BufReader::new(stream), + cancelled, + deadline: Instant::now() + Duration::from_secs(3), + bytes: 0, + } + } + #[test] + fn canonical_paths_pipelining_fragmentation_and_out_of_order_replies() { + assert_eq!( + awj_path( + "/device/screenList/items/S1/presetList/items/A/layerList/items/1/position/pp/sizeH" + ), + "DeviceObject/$screen/@items/S1/$preset/@items/A/$layer/@items/1/position/@props/sizeH" + ); + let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); + let address = listener.local_addr().unwrap(); + let server = std::thread::spawn(move || { + let mut reader = BufReader::new(listener.accept().unwrap().0); + let mut paths = vec![]; + for _ in 0..2 { + let mut bytes = vec![]; + reader.read_until(4, &mut bytes).unwrap(); + bytes.pop(); + let message: Value = serde_json::from_slice(&bytes).unwrap(); + assert_eq!(message["op"], "get"); + paths.push(message["path"].clone()); + } + for (i, path) in paths.into_iter().enumerate().rev() { + let bytes = format!("{}\x04", json!({"path":path,"value":i})); + for part in bytes.as_bytes().chunks(7) { + reader.get_mut().write_all(part).unwrap(); + } + } + }); + let cancel = AtomicBool::new(false); + let mut reader = connect(address, &cancel); + assert_eq!( + reader + .get(&["/device/first".into(), "/device/second".into()]) + .unwrap(), + vec![json!(0), json!(1)] + ); + server.join().unwrap(); + } + #[test] + fn wire_errors_oversized_frames_missing_values_and_cancellation_fail_closed() { + for response in [ + b"not json\x04".to_vec(), + b"{\"error\":{\"code\":\"E12\"}}\x04".to_vec(), + b"{\"path\":\"DeviceObject/wrong\",\"value\":1}\x04".to_vec(), + b"{\"path\":\"DeviceObject/test\"}\x04".to_vec(), + vec![b' '; MAX_FRAME + 1], + vec![], + ] { + let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); + let address = listener.local_addr().unwrap(); + let server = std::thread::spawn(move || { + let mut reader = BufReader::new(listener.accept().unwrap().0); + let mut request = vec![]; + reader.read_until(4, &mut request).unwrap(); + let _ = reader.get_mut().write_all(&response); + }); + let cancel = AtomicBool::new(false); + assert!( + connect(address, &cancel) + .get(&["/device/test".into()]) + .is_err() + ); + server.join().unwrap(); + } + let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); + let cancel = AtomicBool::new(true); + let mut reader = connect(listener.local_addr().unwrap(), &cancel); + assert!( + reader + .get(&["/device/test".into()]) + .unwrap_err() + .contains("cancelled") + ); + cancel.store(false, Ordering::Relaxed); + reader.deadline = Instant::now(); + assert!( + reader + .get(&["/device/test".into()]) + .unwrap_err() + .contains("timed out") + ); + } + + #[test] + fn http_identity_awj_preflight_websocket_writes_and_awj_readback() { + use crate::{ + Geometry, Layout, + device_send::{self, Plan, Sizing, Target}, + }; + use std::sync::{Arc, Mutex}; + let raw = fixture(); + let state = Snapshot::parse( + &identity(), + &collect(&mut memory(raw.clone()), &identity()).unwrap(), + ) + .unwrap(); + let mut layout = Layout::default(); + layout + .apply( + 0, + Geometry { + x: 12.125, + y: 34.375, + width: 301.25, + height: 251.5, + }, + ) + .unwrap(); + let plan = Plan::prepare( + &state, + &layout, + 0, + &[(layout.layer_info(0).id, "1".into())], + Target::Preview, + Sizing::SourceAspect, + ) + .unwrap(); + let changes = plan.changes.len(); + let raw = Arc::new(Mutex::new(raw)); + let awj = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); + let port = awj.local_addr().unwrap().port(); + let awj_raw = raw.clone(); + let awj_server = std::thread::spawn(move || { + let mut count = 0; + for _ in 0..2 { + let mut reader = BufReader::new(awj.accept().unwrap().0); + reader + .get_mut() + .set_read_timeout(Some(Duration::from_secs(5))) + .unwrap(); + loop { + let mut bytes = vec![]; + if reader.read_until(4, &mut bytes).unwrap() == 0 { + break; + } + bytes.pop(); + let message: Value = serde_json::from_slice(&bytes).unwrap(); + assert_eq!(message["op"], "get"); + let path = message["path"].as_str().unwrap(); + let native = path + .split('/') + .map(|p| match p { + "DeviceObject" => "device".to_owned(), + "@items" => "items".to_owned(), + "@props" => "pp".to_owned(), + p if p.starts_with('$') => format!("{}List", &p[1..]), + p => p.to_owned(), + }) + .collect::>() + .join("/"); + let value = awj_raw + .lock() + .unwrap() + .pointer(&format!("/{native}")) + .unwrap() + .clone(); + write!( + reader.get_mut(), + "{}\x04", + json!({"path":path,"value":value}) + ) + .unwrap(); + count += 1; + } + } + count + }); + let http = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); + let host = http.local_addr().unwrap().to_string(); + let server = std::thread::spawn(move || { + fn identity_response(listener: &std::net::TcpListener) { + let mut reader = BufReader::new(listener.accept().unwrap().0); + reader + .get_mut() + .set_read_timeout(Some(Duration::from_secs(5))) + .unwrap(); + let mut line = String::new(); + reader.read_line(&mut line).unwrap(); + assert_eq!( + line, "GET /api/tpp/v1/system HTTP/1.1\r\n", + "Full-store HTTP requests are forbidden" + ); + loop { + line.clear(); + reader.read_line(&mut line).unwrap(); + if line == "\r\n" { + break; + } + } + let body = identity().to_string(); + write!( + reader.get_mut(), + "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", + body.len() + ) + .unwrap(); + } + identity_response(&http); + let stream = http.accept().unwrap().0; + stream + .set_read_timeout(Some(Duration::from_secs(5))) + .unwrap(); + let mut ws = tungstenite::accept(stream).unwrap(); + for i in 0..changes + 2 { + let message = ws.read().unwrap(); + let message: Value = serde_json::from_str(message.to_text().unwrap()).unwrap(); + assert_eq!(message["channel"], "DEVICE"); + let path = message["data"]["path"] + .as_array() + .unwrap() + .iter() + .map(|p| p.as_str().unwrap()) + .collect::>() + .join("/"); + let value = message["data"]["value"].clone(); + if i >= changes { + assert_eq!(path, "device/screenAuxGroupList/control/pp/xUpdate"); + assert_eq!(value, json!(i == changes + 1)); + } + assert!( + !path.contains("source/") + && !path.contains("inputList") + && !path.contains("xTake") + ); + set(&mut raw.lock().unwrap(), &path, value); + } + identity_response(&http); + }); + let result = device_send::send_with_awj_port(&host, &plan, port); + assert!(result.is_ok(), "{result:?}"); + server.join().unwrap(); + assert!(awj_server.join().unwrap() < 2000); } } diff --git a/crates/canvas-pilot/src/device_send.rs b/crates/canvas-pilot/src/device_send.rs index d7e57d1..fdecc07 100644 --- a/crates/canvas-pilot/src/device_send.rs +++ b/crates/canvas-pilot/src/device_send.rs @@ -344,11 +344,16 @@ fn execute(plan: &Plan, transport: &mut impl Transport) -> Result>, } impl Transport for Connection { fn read(&mut self) -> Result { - device::fetch(&self.host) + device::fetch_with_awj_port( + &self.host, + &std::sync::atomic::AtomicBool::new(false), + self.awj_port, + ) } fn write(&mut self, change: &Change) -> Result<(), String> { if self.socket.is_none() { @@ -380,8 +385,16 @@ impl Transport for Connection { /// Explicit send: write fields, pulse preset xUpdate, then verify geometry readback. /// Banks are pinned; another controller's TAKE can change their on-air role. pub fn send(host: &str, plan: &Plan) -> Result { + send_with_awj_port(host, plan, 10606) +} +pub(crate) fn send_with_awj_port( + host: &str, + plan: &Plan, + awj_port: u16, +) -> Result { let mut connection = Connection { host: host.trim().into(), + awj_port, socket: None, }; let fresh = connection.read()?; @@ -442,7 +455,11 @@ mod tests { let message = socket.read().unwrap(); serde_json::from_str::(message.to_text().unwrap()).unwrap() }); - let mut connection = Connection { host, socket: None }; + let mut connection = Connection { + host, + awj_port: 10606, + socket: None, + }; connection .write(&Change { path: vec!["test".into()], diff --git a/crates/canvas-pilot/tests/aquilon.rs b/crates/canvas-pilot/tests/aquilon.rs index 9ddef5b..5cf8b02 100644 --- a/crates/canvas-pilot/tests/aquilon.rs +++ b/crates/canvas-pilot/tests/aquilon.rs @@ -294,115 +294,6 @@ fn cancellation_does_not_contact_device() { ); } -#[test] -fn mock_http_websocket_send_preflights_applies_and_reads_back_without_routing() { - use std::{ - io::{BufRead, BufReader, Write}, - net::{TcpListener, TcpStream}, - time::{Duration, Instant}, - }; - fn accept(listener: &TcpListener) -> TcpStream { - let deadline = Instant::now() + Duration::from_secs(8); - loop { - match listener.accept() { - Ok((s, _)) => { - s.set_read_timeout(Some(Duration::from_secs(5))).unwrap(); - return s; - } - Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => { - assert!(Instant::now() < deadline, "mock server timed out"); - std::thread::sleep(Duration::from_millis(10)); - } - Err(e) => panic!("{e}"), - } - } - } - fn http(listener: &TcpListener, expected: &str, body: &Value) { - let mut stream = accept(listener); - let mut reader = BufReader::new(stream.try_clone().unwrap()); - let mut line = String::new(); - reader.read_line(&mut line).unwrap(); - assert_eq!(line, format!("GET {expected} HTTP/1.1\r\n")); - loop { - line.clear(); - reader.read_line(&mut line).unwrap(); - if line == "\r\n" { - break; - } - } - let body = body.to_string(); - write!( - stream, - "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", - body.len() - ) - .unwrap(); - } - let raw = routed(); - let state = Snapshot::parse(&identity(), &raw).unwrap(); - let mut layout = Layout::default(); - layout - .apply( - 0, - Geometry { - x: 12.125, - y: 34.375, - width: 301.25, - height: 251.5, - }, - ) - .unwrap(); - let plan = Plan::prepare( - &state, - &layout, - 0, - &[(layout.layer_info(0).id, "1".into())], - Target::Preview, - Sizing::SourceAspect, - ) - .unwrap(); - let changes = plan.changes.len(); - let listener = TcpListener::bind("127.0.0.1:0").unwrap(); - listener.set_nonblocking(true).unwrap(); - let host = listener.local_addr().unwrap().to_string(); - let server = std::thread::spawn(move || { - let mut raw = raw; - http(&listener, "/api/tpp/v1/system", &identity()); - http(&listener, "/api/stores/device", &raw); - let mut ws = tungstenite::accept(accept(&listener)).unwrap(); - let mut paths = vec![]; - for i in 0..changes + 2 { - let message = ws.read().unwrap(); - let message: Value = serde_json::from_str(message.to_text().unwrap()).unwrap(); - assert_eq!(message["channel"], "DEVICE"); - let path = message["data"]["path"] - .as_array() - .unwrap() - .iter() - .map(|s| s.as_str().unwrap()) - .collect::>() - .join("/"); - let after = &message["data"]["value"]; - if i >= changes { - assert_eq!(path, "device/screenAuxGroupList/control/pp/xUpdate"); - assert_eq!(after, &json!(i == changes + 1)); - } - assert!( - !path.contains("xTake") && !path.contains("source/") && !path.contains("inputList") - ); - *raw.pointer_mut(&format!("/{path}")).unwrap() = after.clone(); - paths.push(path); - } - http(&listener, "/api/tpp/v1/system", &identity()); - http(&listener, "/api/stores/device", &raw); - paths - }); - let result = canvas_pilot::device_send::send(&host, &plan); - let paths = server.join().unwrap(); - assert!(result.is_ok(), "{result:?}"); - assert_eq!(paths.len(), changes + 2); -} - #[test] fn documented_v13_example_contains_native_aquilon_link() { let p = Project::from_json(include_str!( diff --git a/crates/canvas-pilot/tests/fixtures/aquilon-6.2.README.md b/crates/canvas-pilot/tests/fixtures/aquilon-6.2.README.md index 2a44d94..3e09065 100644 --- a/crates/canvas-pilot/tests/fixtures/aquilon-6.2.README.md +++ b/crates/canvas-pilot/tests/fixtures/aquilon-6.2.README.md @@ -8,6 +8,6 @@ S1 has seven allocated numbered layers; its stored eighth slot tests allocation filtering. S2 and A1 are disabled. Test code creates explicit synthetic variations for active auxiliaries, canvas changes, bank swaps and malformed fields. -The full 118 MiB response remains a private temporary artifact. The runtime -projection and parser both exercise this fixture; live write/restore diagnostics +The full 118 MiB response remains a private temporary artifact. The targeted-read collector and parser exercise this fixture; test helpers +add collection keys and identity fields for the mock AWJ endpoint; live write/restore diagnostics are separate examples, never CI tests. diff --git a/docs/canvas-pilot/aquilon-compatibility.md b/docs/canvas-pilot/aquilon-compatibility.md index 7a23efa..3c12dd0 100644 --- a/docs/canvas-pilot/aquilon-compatibility.md +++ b/docs/canvas-pilot/aquilon-compatibility.md @@ -8,7 +8,7 @@ user-provided custom port. See the [current adapter contract](../interfaces/devi ## Current acceptance -- Identity, bounded full-store streaming projection, screen/layer allocations and +- Identity, bounded targeted AWJ reads, screen/layer allocations and Preview/Program transition-group resolution work on the emulator. - Twelve apply/readback/import cases pass: Preview and Program × Output-sized and Source aspect × three fractional/portrait/asymmetric crop cases (zoom 1, 2 and 4). @@ -28,7 +28,7 @@ user-provided custom port. See the [current adapter contract](../interfaces/devi WebSocket/apply behavior. Auxiliaries are tested with sanitized synthetic state; this emulator's baseline only allocates S1. - Workspace tests, Clippy, formatting and warning-free Rust documentation pass; - all 62 Python checks pass. Full application line coverage is 90.53%. + all 62 Python checks pass. Full application line coverage is 90.69%. - Linked units, older firmware, other models, physical output and advanced shared input correction are not claimed as verified. Masks and non-centered fit modes remain explicit import limitations, not silently approximated geometry. @@ -39,6 +39,24 @@ to LIVE_1 in both banks; production sends never route. A separate `--visual-check-and-restore` mode holds a known Preview layout for 60 seconds for WebRCS inspection, then restores it. These diagnostics are never automated CI tests. +## Targeted read performance follow-up + +The initial full-store reader has been replaced by batched property reads on +AWJ TCP 10606. The configured HTTP port still handles identity, captures and +WebSocket writes. The [adapter contract](../interfaces/device-adapters.md) records +framing, bounds, endpoint requirements and the consistency check. + +Measured on the same emulator: 197180 AWJ response bytes + 124 HTTP identity bytes, +184978 request bytes, and direct reads of 0.314 / 0.302 / 0.297 seconds. The earlier +store was 124077157 bytes, so downloaded payload fell by 99.84%. A counting proxy +confirmed no `/api/stores/device` request. All twelve Preview/Program send cases +passed again with targeted preflight/readback, and the current baseline was restored. + +The current manufacturer AWJ V6.2 and REST v6.0 PDFs were accessible using literal +`+` URL path segments; the percent-encoded links returned 403. AWJ property and +collection reads were verified directly. The historical full-store investigation +below describes the earlier implementation, not the current connection path. + ## Historical protocol investigation The following records the investigation before implementation; its future-tense diff --git a/docs/canvas-pilot/aquilon_support.task.md b/docs/canvas-pilot/aquilon_support.task.md index 5c75ebb..22d5abf 100644 --- a/docs/canvas-pilot/aquilon_support.task.md +++ b/docs/canvas-pilot/aquilon_support.task.md @@ -1,6 +1,7 @@ # Aquilon / LivePremier support — agent handoff -Status: **initial standalone AQL Cmax 6.2 adapter implemented**. See +Status: **initial standalone AQL Cmax 6.2 adapter implemented**, now using +batched targeted AWJ reads instead of full-store downloads. See [acceptance and limitations](aquilon-compatibility.md) and the [adapter contract](../interfaces/device-adapters.md). The checklist below is the original implementation brief, retained for the remaining unverified profiles and diff --git a/docs/canvas-pilot/changelog.md b/docs/canvas-pilot/changelog.md index b0e5f0e..ff892f6 100644 --- a/docs/canvas-pilot/changelog.md +++ b/docs/canvas-pilot/changelog.md @@ -4,6 +4,8 @@ ## Unreleased +- Replace Aquilon full-store downloads with batched AWJ reads on TCP 10606, retaining fresh preflight and verified sends. Emulator reads fell from 124 MB to about 197 KB and took about 0.30 seconds directly. Twelve transfer cases passed with restoration; malformed/incomplete responses and changing snapshots fail explicitly. HTTP/WebSocket custom ports remain supported; AWJ must be reachable on the same IP. + - Replace unsupported arrow glyphs in transfer labels and help text with plain text so they render with the bundled UI font. - Add a separate Aquilon / LivePremier 6.2 adapter around a shared screen/layer model, with bounded cancellable state reads, allocated-slot discovery, explicit bank roles, fractional geometry and centered crop/zoom transfer, and input previews above 16. Sends preflight conversion inputs and bank roles, apply the correct family pulse and verify readback. Twelve emulator Preview/Program geometry/crop cases passed with baseline restoration; device writes round sizes/centers to whole pixels because WebRCS rejects fractional fields despite firmware accepting them. The initial profile targets standalone AQL Cmax; linked systems, other firmware/models and unsupported fit/input-correction modes remain explicit limitations. diff --git a/docs/canvas-pilot/guide/device.md b/docs/canvas-pilot/guide/device.md index 91f06f1..b2a190c 100644 --- a/docs/canvas-pilot/guide/device.md +++ b/docs/canvas-pilot/guide/device.md @@ -7,8 +7,9 @@ Enter an IP address in **Device IP / port**, optionally followed by a TCP port: `192.168.10.146:3000`. Without a port, the app uses port 80. IPv6 addresses with a port use brackets, for example `[::1]:3000`. Omit URL schemes and paths. -The same address is saved in preferences and used for reads, input snapshots, -automatic reconnect and WebSocket sends. +The address is saved in preferences and used for identity, input snapshots, +automatic reconnect and WebSocket sends. Aquilon also requires AWJ TCP port +10606 on the same IP for its targeted geometry reads; Midra reads use the HTTP port. Use **Recent machines…** to switch to one of the last four successful connections. Choosing an entry connects immediately to read its state; it does not send layers. @@ -179,10 +180,12 @@ reported explicitly when their visible bounds cannot be imported. Shared input correction controls remain managed in WebRCS for this adapter. Ordinary sends never route inputs, TAKE, or change shared input processing. -The 118 MiB emulator state is streamed through a bounded projection on a worker. -Connection/read cancellation discards results and stops subsequent reads; a -blocked network read can take until its timeout. Input snapshots retain the same +Aquilon reads only the required properties through AWJ TCP 10606, in batches, +including a consistency check. The tested emulator now downloads about 197 KB +per refresh instead of 124 MB, with direct reads around 0.30 seconds. Preflight +and verification use the same targeted reader. If the AWJ port is disabled or +blocked, the connection reports an error instead of falling back to the full +store. Connect, load and send remain background operations. Input snapshots retain pooled, throttled, opt-in behavior, including inputs above 16. Older firmware, -linked units and other Aquilon models are not enabled without adapter validation. -See the [adapter contract](../../interfaces/device-adapters.md) for tested scope, -limits and protocol details. +linked units and other Aquilon models remain unverified. See the +[adapter contract](../../interfaces/device-adapters.md) for tested scope and limits. diff --git a/docs/canvas-pilot/plan.md b/docs/canvas-pilot/plan.md index 8705ce7..613dea4 100644 --- a/docs/canvas-pilot/plan.md +++ b/docs/canvas-pilot/plan.md @@ -67,7 +67,7 @@ device readback and physical-screen acceptance. ## Remaining feature work -- [x] **Aquilon / LivePremier adapter (standalone AQL Cmax 6.2).** Device-neutral snapshots, family-aware v13 links, bounded state projection, geometry/crop import, mapped Preview/Program sends and pooled input previews. See [adapter contract](../interfaces/device-adapters.md) and [emulator acceptance](aquilon-compatibility.md). Linked units, other models/firmware, shared input corrections and non-centered/masked import remain explicitly unsupported. +- [x] **Aquilon / LivePremier adapter (standalone AQL Cmax 6.2).** Device-neutral snapshots, family-aware v13 links, bounded targeted AWJ reads, geometry/crop import, mapped Preview/Program sends and pooled input previews. See [adapter contract](../interfaces/device-adapters.md) and [emulator acceptance](aquilon-compatibility.md). Linked units, other models/firmware, shared input corrections and non-centered/masked import remain explicitly unsupported. - [ ] **Further export/workflow cleanup.** Shared transfer scopes, mapping review and direct linked send/load are implemented; further changes await specifications. diff --git a/docs/interfaces/device-adapters.md b/docs/interfaces/device-adapters.md index 15bd856..d1abd9f 100644 --- a/docs/interfaces/device-adapters.md +++ b/docs/interfaces/device-adapters.md @@ -15,21 +15,43 @@ profiles do not support linked-unit identity; linked Aquilon devices are refused ## Aquilon profile and reads Initial profile: standalone **AQL Cmax, firmware 6.2.x**, exercised on **6.2.79**. -Other firmware/models are rejected before downloading the state. `/api/tpp/v1/system` -supplies identity; `/api/stores/device` supplies native state. The emulator has -authentication disabled. Authenticated devices currently report their HTTP/auth -failure rather than saving credentials or attempting a login. +Other firmware/models are rejected before reading geometry. `/api/tpp/v1/system` +on the configured HTTP port supplies identity. Aquilon geometry uses **AWJ TCP +10606 on the same IP**, independently of the HTTP/WebSocket port. AWJ model and +firmware are checked against the HTTP identity. A blocked/disabled AWJ port is an +explicit connection error; there is no full-store HTTP fallback. Midra retains +its existing HTTP reader. The emulator has authentication disabled; HTTP auth +failures remain explicit and credentials are not saved. -No smaller supported read route was found in the installed WebRCS client. Tested -`/api/stores/device/device/screenList/items/S1/status` and -`/api/device/screenList/items/S1/status` return 404. The fallback streams the -observed 124,077,157-byte store with a **160 MiB** wire limit, **one million** -decoded nodes, **16 MiB** aggregate retained/key text budget, **1024 bytes** per -string, **256 entries** per retained map/array, and bounded nesting. Unrelated -trees are skipped rather than materialized. Unallocated layers and disabled -screens are removed before the snapshot is retained. Network connection timeout -is 5 seconds; request timeout is 45 seconds. Worker cancellation is checked -between reads; a blocked read retains its timeout. No state enters project files. +The [manufacturer's AWJ guide V6.2](https://dwn01.analogway.com/Site+Internet/Series/Aquilon/Common/AWJ+Protocol/AW_Aquilon_AWJ_ProgrammersGuide_V6.2.pdf) +documents property reads over TCP. Requests are `{"op":"get","path":"..."}`, +terminated by byte `0x04`. Canonical paths start with `DeviceObject`; list, +item and property segments use `$screen`, `@items` and `@props`. Responses are +matched by exact canonical path, including out-of-order replies. Error, missing, +unexpected, duplicate, truncated and oversized responses fail the read. + +Reads discover `itemKeys`, then screen modes and available inputs. Only enabled +screens, their allocated numbered layers in the two current role banks, active +input plugs, framing settings and snapshot availability are requested. No memory +banks, inactive layer slots, hardware inventories or other large subtrees are read. +These targeted values populate the same normalized adapter state as before. +Requests are pipelined in batches of **64**; parent-object reads are avoided because +the emulator returns empty objects for them. A second pass compares all selected +values, including topology and bank roles; a changing snapshot is rejected instead +of being used for a send. No cache, persistent subscription or AWJ writes are used. + +Bounds: **256** entries per discovered collection, **65536** selected fields, +**16 KiB** per response, and **16 MiB** aggregate response bytes across both passes. +TCP connect/write timeout is **3 seconds**, collection deadline **30 seconds**, +and read waits check cancellation at **250 ms** intervals. HTTP identity retains +its 5-second connect / 45-second request limits. All work stays on the worker. + +On the 6.2.79 emulator, a complete two-pass read received **197180 bytes** over +AWJ plus **124 bytes** of HTTP identity, versus the previous **124077157-byte** +store download: **99.84% less downloaded payload**. AWJ requests totalled 184978 +bytes. Three direct debug-build reads took **0.314, 0.302 and 0.297 seconds**; +a counting proxy took 1.601 seconds. These are local emulator measurements, +excluding TCP/HTTP header overhead, not guarantees for every device configuration. Enabled `screenList` and `auxiliaryList` entries supply `status.pp.layerCount` (0–128) and `status.size.pp.sizeH/sizeV`. Canvas dimensions also obey editor