OneCAD-Draft/crates/ocs_plugin_api/src/ipc/v4/protocol.rs

//! V4 wire frames and envelope types.
//!
//! V4 replaces the simple request/response pipe with a multiplexed frame layer.
//! Every request and response carries a monotonically increasing correlation
//! `id` so a plugin can send/receive out of order. Notifications carry an
//! optional `command_id` so a plugin can associate a host notification with the
//! long-running command that caused it.
//!
//! The two frame enums are:
//!
//! - [`HostToPluginV4`] — host → runner requests, responses to runner requests,
//!   and host notifications.
//! - [`PluginToHostV4`] — runner → host requests, responses to host requests,
//!   and plugin notifications.
//!
//! Notifications are wrapped in [`NotificationEnvelope`] and are best-effort:
//! a process that fails to accept a notification is logged and skipped, but the
//! connection stays alive. Unknown host-notification discriminants deserialize
//! to [`crate::host::HostNotification::Unknown`] so newer host notifications do
//! not break older plugins.

use serde::{Deserialize, Serialize};

use crate::host::{HostNotification, PluginNotification};
use crate::ipc::protocol::{HostRequest, HostResponse, PluginRequest, PluginResponse};

/// Protocol version carried in the V4 handshake.
pub const V4_PROTOCOL_VERSION: u32 = 4;

/// Best-effort notification envelope carrying an optional command correlation
/// ID in addition to the typed payload.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NotificationEnvelope<T> {
    pub command_id: Option<u64>,
    pub payload: T,
}

/// Messages sent from the host to the plugin runner on the V4 socket.
#[derive(Debug, Serialize, Deserialize)]
#[allow(clippy::large_enum_variant)]
pub enum HostToPluginV4 {
    Request { id: u64, payload: HostRequest },
    Response { id: u64, payload: PluginResponse },
    Notification(NotificationEnvelope<HostNotification>),
}

/// Messages sent from the plugin runner to the host on the V4 socket.
#[derive(Debug, Serialize, Deserialize)]
#[allow(clippy::large_enum_variant)]
pub enum PluginToHostV4 {
    Request {
        id: u64,
        tab_id: Option<u64>,
        payload: PluginRequest,
    },
    Response {
        id: u64,
        payload: HostResponse,
    },
    Notification(NotificationEnvelope<PluginNotification>),
}

#[cfg(all(test, feature = "host"))]
mod tests {
    use super::*;
    use crate::host::LogLevel;

    #[test]
    fn v4_frame_roundtrip() {
        let frame = HostToPluginV4::Notification(NotificationEnvelope {
            command_id: Some(7),
            payload: HostNotification::InputLine {
                line: "hello".to_string(),
            },
        });
        let bytes = bincode::serialize(&frame).unwrap();
        let got: HostToPluginV4 = bincode::deserialize(&bytes).unwrap();
        match got {
            HostToPluginV4::Notification(env) => {
                assert_eq!(env.command_id, Some(7));
                assert_eq!(
                    env.payload,
                    HostNotification::InputLine {
                        line: "hello".to_string()
                    }
                );
            }
            other => panic!("unexpected: {other:?}"),
        }
    }

    #[test]
    fn command_state_notification_roundtrips() {
        let notification = HostNotification::CommandStateChanged {
            tab_id: 42,
            command: Some("LINE".to_owned()),
        };
        let bytes = bincode::serialize(&notification).unwrap();
        let decoded: HostNotification = bincode::deserialize(&bytes).unwrap();
        assert_eq!(decoded, notification);
        let stopped = HostNotification::CommandStateChanged {
            tab_id: 42,
            command: None,
        };
        let bytes = bincode::serialize(&stopped).unwrap();
        let decoded: HostNotification = bincode::deserialize(&bytes).unwrap();
        assert_eq!(decoded, stopped);
        let changed = HostNotification::DrawingChanged {
            tab_id: 42,
            epoch: 7,
        };
        let bytes = bincode::serialize(&changed).unwrap();
        let decoded: HostNotification = bincode::deserialize(&bytes).unwrap();
        assert_eq!(decoded, changed);
    }

    #[test]
    fn command_request_and_outcome_roundtrip() {
        use crate::host::{CommandOutcome, CommandRequest};
        for request in [
            CommandRequest::Run {
                line: "LINE 0,0 1,1".into(),
            },
            CommandRequest::Start {
                name: "OFFSET".into(),
            },
            CommandRequest::Point {
                point: [1.0, 2.0, 3.0],
            },
            CommandRequest::Text { text: "2".into() },
            CommandRequest::Token { text: "R".into() },
            CommandRequest::Entity {
                handle: codec::Handle::new(9),
                point: [0.0; 3],
            },
            CommandRequest::Selection,
            CommandRequest::Enter,
            CommandRequest::Cancel,
        ] {
            let bytes = bincode::serialize(&PluginRequest::RunCommand {
                request: request.clone(),
            })
            .unwrap();
            assert!(
                matches!(bincode::deserialize::<PluginRequest>(&bytes).unwrap(),
                PluginRequest::RunCommand { request: decoded } if decoded == request)
            );
        }
        let outcome = CommandOutcome {
            status: "waiting_input".into(),
            blocked_by: Some("command".into()),
            command: "OFFSET".into(),
            prompt: "Select object".into(),
            accepts: vec!["entity".into()],
            options: vec!["M".into()],
            entities: 4,
            added: -1,
            unconsumed: vec!["x".into()],
            error: Some("e".into()),
        };
        for result in [Ok(outcome), Err("refused".to_owned())] {
            let bytes = bincode::serialize(&PluginResponse::CommandResult(result.clone())).unwrap();
            assert!(
                matches!(bincode::deserialize::<PluginResponse>(&bytes).unwrap(),
                PluginResponse::CommandResult(decoded) if decoded == result)
            );
        }
    }

    #[test]
    fn table_operation_request_and_response_roundtrip() {
        use crate::host::{LayerConfig, TableOperation};
        for operation in [
            TableOperation::LayerCreate {
                config: LayerConfig {
                    name: "Walls".into(),
                    color: Some(codec::types::Color::Index(5)),
                    frozen: Some(true),
                    description: Some("d".into()),
                    ..Default::default()
                },
            },
            TableOperation::LayerModify {
                config: LayerConfig {
                    name: "Walls".into(),
                    off: Some(true),
                    ..Default::default()
                },
            },
            TableOperation::LayerRename {
                from: "A".into(),
                to: "B".into(),
            },
            TableOperation::LayerDelete {
                name: "A".into(),
                erase_objects: true,
            },
            TableOperation::LayerSetCurrent { name: "A".into() },
            TableOperation::TextStyleCreate {
                config: crate::host::TextStyleConfig {
                    name: "T".into(),
                    height: Some(2.5),
                    oblique_angle: Some(0.2),
                    backward: Some(true),
                    ..Default::default()
                },
            },
            TableOperation::TextStyleModify {
                config: crate::host::TextStyleConfig {
                    name: "T".into(),
                    font_file: Some("romans".into()),
                    ..Default::default()
                },
            },
            TableOperation::DimStyleCreate {
                name: "D".into(),
                copy_from: Some("Standard".into()),
                properties: "{\"dimscale\":2}".into(),
            },
            TableOperation::DimStyleModify {
                name: "D".into(),
                properties: "{}".into(),
            },
            TableOperation::StyleRename {
                kind: crate::host::TableStyleKind::Text,
                from: "A".into(),
                to: "B".into(),
            },
            TableOperation::StyleDelete {
                kind: crate::host::TableStyleKind::Dim,
                name: "A".into(),
            },
            TableOperation::StyleSetCurrent {
                kind: crate::host::TableStyleKind::Dim,
                name: "A".into(),
            },
            TableOperation::BlockCreate {
                name: "B".into(),
                entities: vec![codec::Handle::new(4), codec::Handle::new(5)],
                base_point: [1.0, 2.0, 3.0],
                erase_originals: true,
                description: Some("d".into()),
            },
            TableOperation::BlockModify {
                name: "B".into(),
                description: None,
                explodable: Some(false),
                scale_uniformly: Some(true),
            },
            TableOperation::BlockRename {
                from: "B".into(),
                to: "C".into(),
            },
            TableOperation::BlockDelete { name: "C".into() },
            TableOperation::BlockEntityAdd {
                block: "C".into(),
                entity: codec::EntityType::Line(codec::entities::Line::new()),
            },
            TableOperation::LinetypeCreate {
                name: "L".into(),
                description: "d".into(),
                pattern: vec![1.0, -1.0],
            },
            TableOperation::LinetypeModify {
                name: "L".into(),
                description: None,
                pattern: Some(vec![2.0, -2.0]),
            },
            TableOperation::LinetypeRename {
                from: "L".into(),
                to: "M".into(),
            },
            TableOperation::LinetypeDelete { name: "M".into() },
            TableOperation::LayoutCreate { name: "S".into() },
            TableOperation::LayoutRename {
                from: "S".into(),
                to: "T".into(),
            },
            TableOperation::LayoutDelete { name: "T".into() },
            TableOperation::LayoutSetCurrent {
                name: "Model".into(),
            },
            TableOperation::LayoutSetPage {
                name: "S".into(),
                paper_size: Some([420.0, 297.0]),
                rotation: Some(90),
                scale: Some([1.0, 50.0]),
            },
        ] {
            let bytes = bincode::serialize(&PluginRequest::TableOperation {
                operation: operation.clone(),
            })
            .unwrap();
            assert!(
                matches!(bincode::deserialize::<PluginRequest>(&bytes).unwrap(),
                PluginRequest::TableOperation { operation: decoded } if decoded == operation)
            );
        }
        for result in [Ok(codec::Handle::new(9)), Err("refused".to_owned())] {
            let bytes = bincode::serialize(&PluginResponse::TableResult(result.clone())).unwrap();
            assert!(
                matches!(bincode::deserialize::<PluginResponse>(&bytes).unwrap(),
                PluginResponse::TableResult(decoded) if decoded == result)
            );
        }
    }

    #[test]
    fn solid_operation_request_and_response_roundtrip() {
        use crate::host::{SolidOperation, SolidPrimitive};
        for operation in [
            SolidOperation::Create {
                primitive: SolidPrimitive::Pyramid {
                    center: [1.0, 2.0, 3.0],
                    radius: 4.0,
                    height: 5.0,
                    sides: 6,
                },
                layer: Some("SOLIDS".into()),
            },
            SolidOperation::Transform {
                handle: codec::Handle::new(7),
                matrix: [1.0; 16],
            },
            SolidOperation::RegionFromProfile {
                source: codec::Handle::new(3),
                layer: None,
                delete_source: true,
            },
            SolidOperation::EmbedPicture {
                path: "p.png".into(),
                origin: [0.0; 3],
                width: 5.0,
                layer: None,
            },
            SolidOperation::Boolean {
                first: codec::Handle::new(1),
                second: codec::Handle::new(2),
                operation: crate::host::SolidBoolean::Subtract,
                layer: None,
                keep_operands: false,
            },
            SolidOperation::SurfaceFromProfile {
                source: codec::Handle::new(4),
                layer: Some("S".into()),
                delete_source: false,
            },
            SolidOperation::Extrude {
                source: codec::Handle::new(5),
                direction: [0.0, 0.0, 2.0],
                layer: None,
                delete_source: true,
            },
        ] {
            let bytes = bincode::serialize(&PluginRequest::SolidOperation {
                operation: operation.clone(),
            })
            .unwrap();
            assert!(
                matches!(bincode::deserialize::<PluginRequest>(&bytes).unwrap(),
                PluginRequest::SolidOperation { operation: decoded } if decoded == operation)
            );
        }
        for result in [Ok(codec::Handle::new(9)), Err("refused".to_owned())] {
            let bytes = bincode::serialize(&PluginResponse::SolidResult(result.clone())).unwrap();
            assert!(
                matches!(bincode::deserialize::<PluginResponse>(&bytes).unwrap(),
                PluginResponse::SolidResult(decoded) if decoded == result)
            );
        }
    }

    #[test]
    fn selection_request_and_response_roundtrip() {
        let request = PluginRequest::SetSelection {
            handles: vec![codec::Handle::new(9)],
        };
        let bytes = bincode::serialize(&request).unwrap();
        assert!(
            matches!(bincode::deserialize::<PluginRequest>(&bytes).unwrap(),
            PluginRequest::SetSelection { handles } if handles == vec![codec::Handle::new(9)])
        );
        let response = PluginResponse::Selection(vec![codec::Handle::new(9)]);
        let bytes = bincode::serialize(&response).unwrap();
        assert!(
            matches!(bincode::deserialize::<PluginResponse>(&bytes).unwrap(),
            PluginResponse::Selection(handles) if handles == vec![codec::Handle::new(9)])
        );
    }

    #[test]
    fn plugin_notification_roundtrip() {
        let frame = PluginToHostV4::Notification(NotificationEnvelope {
            command_id: None,
            payload: PluginNotification::Log {
                level: LogLevel::Info,
                text: "hi".to_string(),
            },
        });
        let bytes = bincode::serialize(&frame).unwrap();
        let got: PluginToHostV4 = bincode::deserialize(&bytes).unwrap();
        match got {
            PluginToHostV4::Notification(env) => {
                assert_eq!(env.command_id, None);
                assert_eq!(
                    env.payload,
                    PluginNotification::Log {
                        level: LogLevel::Info,
                        text: "hi".to_string()
                    }
                );
            }
            other => panic!("unexpected: {other:?}"),
        }
    }

    #[test]
    fn unknown_notification_deserializes_as_unknown() {
        // Build a payload with an unknown discriminant (99) followed by some
        // bytes. The custom deserializer should return Unknown(raw_bytes).
        let mut payload = vec![99u8];
        bincode::serialize_into(&mut payload, &"future".to_string()).unwrap();
        let envelope = NotificationEnvelope {
            command_id: Some(1),
            payload: HostNotification::Unknown(payload.clone()),
        };
        let frame = HostToPluginV4::Notification(envelope);
        let bytes = bincode::serialize(&frame).unwrap();
        let got: HostToPluginV4 = bincode::deserialize(&bytes).unwrap();
        match got {
            HostToPluginV4::Notification(env) => match env.payload {
                HostNotification::Unknown(raw) => {
                    assert_eq!(raw[0], 99);
                }
                other => panic!("expected Unknown, got {other:?}"),
            },
            other => panic!("unexpected: {other:?}"),
        }
    }

    #[test]
    fn v3_runner_handshake_token_roundtrips_after_tokenv4() {
        use crate::ipc::protocol::RunnerHandshake;
        let original = RunnerHandshake::Token("abc".to_string());
        let bytes = bincode::serialize(&original).unwrap();
        let got: RunnerHandshake = bincode::deserialize(&bytes).unwrap();
        match got {
            RunnerHandshake::Token(s) => assert_eq!(s, "abc"),
            other => panic!("unexpected: {other:?}"),
        }
    }
}