Skip to main content

modelith_plugin_protocol/
message.rs

1//! v1(`browser`)のプラグインとホストのメッセージ(ADR-0018 §3・§6)。
2//!
3//! プラグインはサンドボックス化した iframe の中の Worker で動き、ホストと `postMessage` で
4//! やり取りする。どのメッセージも `type` で種類を区別する JSON で、バイト列は base64 の文字列にする。
5//!
6//! `apiVersion` が `"0"` の間は互換性を約束しない(ModelSnapshot には属性値・接続などを足す予定)。
7//! 受け手は知らないフィールドを無視する。版の違うホストとプラグインが、任意フィールドの追加で壊れないようにするため
8//! (マニフェストやルールのファイルのような、人が書くものとは扱いを変えている)。
9
10use serde::{Deserialize, Serialize};
11use serde_json::Value;
12
13use crate::{Diagnostic, PluginId, Range, TextEdit};
14
15/// ホストからプラグインへのメッセージ。
16#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
17#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
18#[serde(
19    tag = "type",
20    rename_all = "camelCase",
21    rename_all_fields = "camelCase"
22)]
23#[cfg_attr(feature = "codegen", schemars(title = "Modelith host message"))]
24pub enum HostMessage {
25    /// プラグインを起動する。プラグインは `ready` を返す。
26    Activate {
27        api_version: String,
28        plugin_id: PluginId,
29        /// プロジェクトの設定(`modelith.json` の `plugins.<id>.settings`)。形はプラグインが決める。無ければ省く。
30        #[serde(default, skip_serializing_if = "Option::is_none")]
31        #[cfg_attr(feature = "codegen", ts(optional, type = "unknown"))]
32        settings: Option<Value>,
33    },
34    /// モデルのテキストが変わった。
35    DidChange {
36        /// テキストの版。診断や変更案は、どの版に対するものかをこの値で示す。
37        version: u32,
38        text: String,
39        /// 解析結果。マニフェストで `model:read` を宣言したときだけ送る。
40        #[serde(default, skip_serializing_if = "Option::is_none")]
41        #[cfg_attr(feature = "codegen", ts(optional))]
42        model: Option<ModelSnapshot>,
43    },
44    /// マニフェストの `contributes.commands` のコマンドを実行する。
45    RunCommand { request_id: u32, command: String },
46    /// `contributes.importers` の取り込みを実行する。
47    Import {
48        request_id: u32,
49        importer: String,
50        file_name: String,
51        /// ファイルの中身(base64)。
52        base64: String,
53    },
54    /// `contributes.exporters` の書き出しを実行する。
55    Export {
56        request_id: u32,
57        exporter: String,
58        /// 表示中の図の名前。無ければモデル全体。
59        #[serde(default, skip_serializing_if = "Option::is_none")]
60        #[cfg_attr(feature = "codegen", ts(optional))]
61        view: Option<String>,
62    },
63    /// `storageGet` / `storageSet` への応答。
64    StorageResult {
65        request_id: u32,
66        /// `storageGet` で読んだ値。無ければ省く。
67        #[serde(default, skip_serializing_if = "Option::is_none")]
68        #[cfg_attr(feature = "codegen", ts(optional, type = "unknown"))]
69        value: Option<Value>,
70    },
71}
72
73/// プラグインからホストへのメッセージ。
74#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
75#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
76#[serde(
77    tag = "type",
78    rename_all = "camelCase",
79    rename_all_fields = "camelCase"
80)]
81#[cfg_attr(feature = "codegen", schemars(title = "Modelith plugin message"))]
82pub enum PluginMessage {
83    /// `activate` を受けて準備ができた。
84    Ready,
85    /// テキストの版 `version` に対する診断。前に送った診断を置き換える。
86    Diagnostics {
87        version: u32,
88        items: Vec<Diagnostic>,
89    },
90    /// テキストの版 `version` に対する変更案。ホストが検証してから適用する。
91    ProposeEdits {
92        version: u32,
93        edits: Vec<TextEdit>,
94        /// 「元に戻す」に出す名前。
95        #[serde(default, skip_serializing_if = "Option::is_none")]
96        #[cfg_attr(feature = "codegen", ts(optional))]
97        label: Option<String>,
98    },
99    /// `runCommand` が終わった。
100    CommandDone { request_id: u32 },
101    /// `import` の結果(SysML v2 のテキスト)。
102    Imported {
103        request_id: u32,
104        file_name: String,
105        text: String,
106    },
107    /// `export` の結果。
108    Exported {
109        request_id: u32,
110        file_name: String,
111        media_type: String,
112        /// ファイルの中身(base64)。
113        base64: String,
114    },
115    /// 依頼(`request_id`)に応えられなかった。
116    Failed { request_id: u32, message: String },
117    /// プラグイン専用のストレージから読む(`storage` 権限が要る)。
118    StorageGet { request_id: u32, key: String },
119    /// プラグイン専用のストレージに書く(`storage` 権限が要る)。
120    StorageSet {
121        request_id: u32,
122        key: String,
123        #[cfg_attr(feature = "codegen", ts(type = "unknown"))]
124        value: Value,
125    },
126    /// 利用者への通知。
127    Notify { level: NotifyLevel, message: String },
128}
129
130#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
131#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
132#[serde(rename_all = "lowercase")]
133pub enum NotifyLevel {
134    Info,
135    Warning,
136    Error,
137}
138
139/// `didChange` で送る解析結果。
140///
141/// `apiVersion` が `"0"` の間は互換性を約束しない(0.2.0 で属性値・接続を足す予定)。
142#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
143#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
144#[serde(rename_all = "camelCase")]
145pub struct ModelSnapshot {
146    pub elements: Vec<ModelElement>,
147    pub relations: Vec<ModelRelation>,
148}
149
150#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
151#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
152#[serde(rename_all = "camelCase")]
153pub struct ModelElement {
154    /// 要素を指す鍵。`ModelRelation` の `from` / `to` はこの値を使う。
155    pub key: String,
156    pub name: String,
157    /// 要素の種類(例: `part def`)。検査ルールの `match.kind` と同じ言葉。
158    pub kind: String,
159    /// 工程(`@Phase`)の名前。
160    #[serde(default, skip_serializing_if = "Option::is_none")]
161    #[cfg_attr(feature = "codegen", ts(optional))]
162    pub phase: Option<String>,
163    #[serde(default)]
164    pub ports: Vec<ModelPort>,
165    /// テキスト上の位置。
166    pub range: Range,
167}
168
169#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
170#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
171#[serde(rename_all = "camelCase")]
172pub struct ModelPort {
173    pub name: String,
174    /// ポートの型の名前。型を書いていなければ省く。
175    #[serde(rename = "type", default, skip_serializing_if = "Option::is_none")]
176    #[cfg_attr(feature = "codegen", ts(optional))]
177    pub port_type: Option<String>,
178    /// 向き。書いていなければ省く。
179    #[serde(default, skip_serializing_if = "Option::is_none")]
180    #[cfg_attr(feature = "codegen", ts(optional))]
181    pub direction: Option<PortDirection>,
182}
183
184#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
185#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
186#[serde(rename_all = "lowercase")]
187pub enum PortDirection {
188    In,
189    Out,
190    Inout,
191}
192
193#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
194#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
195#[serde(rename_all = "camelCase")]
196pub struct ModelRelation {
197    pub id: String,
198    pub kind: RelationKind,
199    /// 出る側の要素の `key`。
200    pub from: String,
201    /// 受ける側の要素の `key`。
202    pub to: String,
203}
204
205/// 関係の種類。検査ルールの `incoming` / `outgoing` と同じ言葉。
206#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
207#[cfg_attr(feature = "codegen", derive(schemars::JsonSchema, ts_rs::TS))]
208#[serde(rename_all = "lowercase")]
209pub enum RelationKind {
210    Satisfy,
211    Verify,
212    Frame,
213    Derivation,
214    Flow,
215}
216
217#[cfg(test)]
218mod tests {
219    use serde_json::json;
220
221    use super::*;
222
223    // --- 正常系 ---
224
225    #[test]
226    fn host_message_uses_type_tag_and_camel_case_fields() {
227        // Arrange
228        let message = HostMessage::RunCommand {
229            request_id: 7,
230            command: "fmea.open".to_owned(),
231        };
232        // Act
233        let value = serde_json::to_value(&message).unwrap();
234        // Assert
235        assert_eq!(
236            value,
237            json!({ "type": "runCommand", "requestId": 7, "command": "fmea.open" })
238        );
239    }
240
241    #[test]
242    fn unit_variant_is_just_the_tag() {
243        // Arrange(境界値: フィールドの無いメッセージ)
244        let message = PluginMessage::Ready;
245        // Act
246        let value = serde_json::to_value(&message).unwrap();
247        // Assert
248        assert_eq!(value, json!({ "type": "ready" }));
249    }
250
251    #[test]
252    fn omitted_optional_fields_are_none() {
253        // Arrange(境界値: 任意フィールドをすべて省く)
254        let json = r#"{"type":"didChange","version":0,"text":""}"#;
255        // Act
256        let message: HostMessage = serde_json::from_str(json).unwrap();
257        // Assert
258        assert_eq!(
259            message,
260            HostMessage::DidChange {
261                version: 0,
262                text: String::new(),
263                model: None
264            }
265        );
266    }
267
268    #[test]
269    fn activate_without_settings() {
270        // Arrange(設定の無いプロジェクト)
271        let json = r#"{"type":"activate","apiVersion":"0","pluginId":"a.b"}"#;
272        // Act
273        let message: HostMessage = serde_json::from_str(json).unwrap();
274        // Assert
275        assert!(matches!(
276            message,
277            HostMessage::Activate { settings: None, .. }
278        ));
279    }
280
281    #[test]
282    fn rejects_invalid_plugin_id_in_activate() {
283        // Arrange
284        let json = r#"{"type":"activate","apiVersion":"0","pluginId":"Bad"}"#;
285        // Act
286        let result = serde_json::from_str::<HostMessage>(json);
287        // Assert
288        assert!(result.is_err());
289    }
290
291    #[test]
292    fn ignores_unknown_fields() {
293        // Arrange(新しい版の相手が任意フィールドを足した場合)
294        let json = r#"{"type":"commandDone","requestId":1,"durationMs":3}"#;
295        // Act
296        let message: PluginMessage = serde_json::from_str(json).unwrap();
297        // Assert
298        assert_eq!(message, PluginMessage::CommandDone { request_id: 1 });
299    }
300
301    #[test]
302    fn port_type_is_named_type_in_json() {
303        // Arrange
304        let port = ModelPort {
305            name: "p".to_owned(),
306            port_type: Some("Power".to_owned()),
307            direction: Some(PortDirection::Inout),
308        };
309        // Act
310        let value = serde_json::to_value(&port).unwrap();
311        // Assert
312        assert_eq!(
313            value,
314            json!({ "name": "p", "type": "Power", "direction": "inout" })
315        );
316    }
317
318    // --- 異常系 ---
319
320    #[test]
321    fn rejects_unknown_type() {
322        // Arrange
323        let json = r#"{"type":"shutdown"}"#;
324        // Act
325        let result = serde_json::from_str::<HostMessage>(json);
326        // Assert
327        assert!(result.is_err());
328    }
329
330    #[test]
331    fn rejects_missing_type() {
332        // Arrange
333        let json = r#"{"requestId":1}"#;
334        // Act
335        let result = serde_json::from_str::<PluginMessage>(json);
336        // Assert
337        assert!(result.is_err());
338    }
339
340    #[test]
341    fn rejects_missing_required_field() {
342        // Arrange(`failed` に `message` が無い)
343        let json = r#"{"type":"failed","requestId":1}"#;
344        // Act
345        let result = serde_json::from_str::<PluginMessage>(json);
346        // Assert
347        assert!(result.is_err());
348    }
349
350    #[test]
351    fn rejects_negative_request_id() {
352        // Arrange(境界値: -1)
353        let json = r#"{"type":"commandDone","requestId":-1}"#;
354        // Act
355        let result = serde_json::from_str::<PluginMessage>(json);
356        // Assert
357        assert!(result.is_err());
358    }
359
360    #[test]
361    fn rejects_unknown_relation_kind() {
362        // Arrange(modelith にまだ無い関係)
363        let json = r#"{"id":"r1","kind":"refinement","from":"a","to":"b"}"#;
364        // Act
365        let result = serde_json::from_str::<ModelRelation>(json);
366        // Assert
367        assert!(result.is_err());
368    }
369
370    #[test]
371    fn rejects_unknown_notify_level() {
372        // Arrange
373        let json = r#"{"type":"notify","level":"debug","message":"m"}"#;
374        // Act
375        let result = serde_json::from_str::<PluginMessage>(json);
376        // Assert
377        assert!(result.is_err());
378    }
379}