wavecraft_protocol/
ipc.rs

1//! IPC message contracts for WebView ↔ Rust communication
2//!
3//! This module defines JSON-RPC 2.0 style messages used for bidirectional
4//! communication between the React UI (running in WebView) and the Rust
5//! application logic.
6//!
7//! # Architecture
8//!
9//! - **Request/Response**: UI initiates, Rust responds (e.g., setParameter, getParameter)
10//! - **Notifications**: Rust pushes updates to UI (e.g., parameter changes from host)
11//!
12//! # JSON-RPC 2.0 Compatibility
13//!
14//! Messages follow JSON-RPC 2.0 conventions:
15//! - Requests have `id`, `method`, and `params`
16//! - Responses have `id` and either `result` or `error`
17//! - Notifications have `method` and `params` but no `id`
18
19use serde::{Deserialize, Serialize};
20
21/// Request message sent from UI to Rust
22#[derive(Debug, Clone, Serialize, Deserialize)]
23pub struct IpcRequest {
24    /// JSON-RPC version (always "2.0")
25    pub jsonrpc: String,
26    /// Unique request identifier for matching responses
27    pub id: RequestId,
28    /// Method name to invoke
29    pub method: String,
30    /// Method parameters (method-specific)
31    #[serde(skip_serializing_if = "Option::is_none")]
32    pub params: Option<serde_json::Value>,
33}
34
35/// Response message sent from Rust to UI
36#[derive(Debug, Clone, Serialize, Deserialize)]
37pub struct IpcResponse {
38    /// JSON-RPC version (always "2.0")
39    pub jsonrpc: String,
40    /// Request ID this response corresponds to
41    pub id: RequestId,
42    /// Success result (mutually exclusive with error)
43    #[serde(skip_serializing_if = "Option::is_none")]
44    pub result: Option<serde_json::Value>,
45    /// Error result (mutually exclusive with result)
46    #[serde(skip_serializing_if = "Option::is_none")]
47    pub error: Option<IpcError>,
48}
49
50/// Notification message sent from Rust to UI (no response expected)
51#[derive(Debug, Clone, Serialize, Deserialize)]
52pub struct IpcNotification {
53    /// JSON-RPC version (always "2.0")
54    pub jsonrpc: String,
55    /// Event type
56    pub method: String,
57    /// Event data
58    #[serde(skip_serializing_if = "Option::is_none")]
59    pub params: Option<serde_json::Value>,
60}
61
62/// Request ID can be string or number
63#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
64#[serde(untagged)]
65pub enum RequestId {
66    String(String),
67    Number(i64),
68}
69
70/// Error returned in IpcResponse
71#[derive(Debug, Clone, Serialize, Deserialize)]
72pub struct IpcError {
73    /// Error code (see error code constants)
74    pub code: i32,
75    /// Human-readable error message
76    pub message: String,
77    /// Additional error data (optional)
78    #[serde(skip_serializing_if = "Option::is_none")]
79    pub data: Option<serde_json::Value>,
80}
81
82// ============================================================================
83// Error Codes (JSON-RPC 2.0 standard codes + custom extensions)
84// ============================================================================
85
86/// JSON-RPC parse error (invalid JSON)
87pub const ERROR_PARSE: i32 = -32700;
88/// JSON-RPC invalid request (malformed structure)
89pub const ERROR_INVALID_REQUEST: i32 = -32600;
90/// JSON-RPC method not found
91pub const ERROR_METHOD_NOT_FOUND: i32 = -32601;
92/// JSON-RPC invalid method parameters
93pub const ERROR_INVALID_PARAMS: i32 = -32602;
94/// JSON-RPC internal error
95pub const ERROR_INTERNAL: i32 = -32603;
96
97// Custom application error codes (start at -32000)
98/// Parameter not found
99pub const ERROR_PARAM_NOT_FOUND: i32 = -32000;
100/// Parameter value out of valid range
101pub const ERROR_PARAM_OUT_OF_RANGE: i32 = -32001;
102
103// ============================================================================
104// Method-Specific Types
105// ============================================================================
106
107// ----------------------------------------------------------------------------
108// getParameter
109// ----------------------------------------------------------------------------
110
111/// Parameters for getParameter request
112#[derive(Debug, Clone, Serialize, Deserialize)]
113pub struct GetParameterParams {
114    /// Parameter ID to retrieve
115    pub id: String,
116}
117
118/// Result of getParameter request
119#[derive(Debug, Clone, Serialize, Deserialize)]
120pub struct GetParameterResult {
121    /// Parameter ID
122    pub id: String,
123    /// Current parameter value in the parameter's declared range.
124    pub value: f32,
125}
126
127// ----------------------------------------------------------------------------
128// setParameter
129// ----------------------------------------------------------------------------
130
131/// Parameters for setParameter request
132#[derive(Debug, Clone, Serialize, Deserialize)]
133pub struct SetParameterParams {
134    /// Parameter ID to update
135    pub id: String,
136    /// New parameter value in the parameter's declared range.
137    pub value: f32,
138}
139
140/// Result of setParameter request (empty success)
141#[derive(Debug, Clone, Serialize, Deserialize)]
142pub struct SetParameterResult {}
143
144// ----------------------------------------------------------------------------
145// getAllParameters
146// ----------------------------------------------------------------------------
147
148/// Result of getAllParameters request
149#[derive(Debug, Clone, Serialize, Deserialize)]
150pub struct GetAllParametersResult {
151    /// List of all parameters with their metadata and current values
152    pub parameters: Vec<ParameterInfo>,
153}
154
155/// Information about a single parameter
156#[derive(Debug, Clone, Serialize, Deserialize)]
157pub struct ParameterInfo {
158    /// Parameter ID (unique identifier)
159    pub id: String,
160    /// Human-readable name
161    pub name: String,
162    /// Parameter type (float, bool, enum, etc.)
163    #[serde(rename = "type")]
164    pub param_type: ParameterType,
165    /// Current parameter value in the parameter's declared range.
166    pub value: f32,
167    /// Default parameter value in the parameter's declared range.
168    pub default: f32,
169    /// Minimum value for this parameter.
170    pub min: f32,
171    /// Maximum value for this parameter.
172    pub max: f32,
173    /// Unit suffix for display (e.g., "dB", "%", "Hz")
174    #[serde(skip_serializing_if = "Option::is_none")]
175    pub unit: Option<String>,
176    /// Group name for UI organization (e.g., "Input", "Processing", "Output")
177    #[serde(skip_serializing_if = "Option::is_none")]
178    pub group: Option<String>,
179}
180
181/// Parameter type discriminator
182#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
183#[serde(rename_all = "lowercase")]
184pub enum ParameterType {
185    Float,
186    Bool,
187    Enum,
188}
189
190// ----------------------------------------------------------------------------
191// Notification: parameterChanged
192// ----------------------------------------------------------------------------
193
194/// Notification sent when a parameter changes (e.g., from host automation)
195#[derive(Debug, Clone, Serialize, Deserialize)]
196pub struct ParameterChangedNotification {
197    /// Parameter ID that changed
198    pub id: String,
199    /// New parameter value in the parameter's declared range.
200    pub value: f32,
201}
202
203// ============================================================================
204// Method Name Constants
205// ============================================================================
206
207/// Method: Get single parameter value
208pub const METHOD_GET_PARAMETER: &str = "getParameter";
209/// Method: Set single parameter value
210pub const METHOD_SET_PARAMETER: &str = "setParameter";
211/// Method: Get all parameters with metadata
212pub const METHOD_GET_ALL_PARAMETERS: &str = "getAllParameters";
213/// Method: Get current meter frame (peak/RMS levels)
214pub const METHOD_GET_METER_FRAME: &str = "getMeterFrame";
215/// Method: Get current audio runtime status
216pub const METHOD_GET_AUDIO_STATUS: &str = "getAudioStatus";
217/// Method: Request resize of editor window
218pub const METHOD_REQUEST_RESIZE: &str = "requestResize";
219/// Method: Register audio client with dev server
220pub const METHOD_REGISTER_AUDIO: &str = "registerAudio";
221/// Notification: Parameter changed (push from Rust to UI)
222pub const NOTIFICATION_PARAMETER_CHANGED: &str = "parameterChanged";
223/// Notification: Meter update from audio binary (push to browser)
224pub const NOTIFICATION_METER_UPDATE: &str = "meterUpdate";
225/// Notification: Audio runtime status changed
226pub const NOTIFICATION_AUDIO_STATUS_CHANGED: &str = "audioStatusChanged";
227
228// ============================================================================
229// Helper Constructors
230// ============================================================================
231
232impl IpcRequest {
233    /// Create a new request
234    pub fn new(
235        id: RequestId,
236        method: impl Into<String>,
237        params: Option<serde_json::Value>,
238    ) -> Self {
239        Self {
240            jsonrpc: "2.0".to_string(),
241            id,
242            method: method.into(),
243            params,
244        }
245    }
246}
247
248impl IpcResponse {
249    /// Create a success response
250    pub fn success(id: RequestId, result: impl Serialize) -> Self {
251        Self {
252            jsonrpc: "2.0".to_string(),
253            id,
254            result: Some(serde_json::to_value(result).unwrap()),
255            error: None,
256        }
257    }
258
259    /// Create an error response
260    pub fn error(id: RequestId, error: IpcError) -> Self {
261        Self {
262            jsonrpc: "2.0".to_string(),
263            id,
264            result: None,
265            error: Some(error),
266        }
267    }
268}
269
270impl IpcNotification {
271    /// Create a new notification
272    pub fn new(method: impl Into<String>, params: impl Serialize) -> Self {
273        Self {
274            jsonrpc: "2.0".to_string(),
275            method: method.into(),
276            params: Some(serde_json::to_value(params).unwrap()),
277        }
278    }
279}
280
281impl IpcError {
282    /// Create a new error
283    pub fn new(code: i32, message: impl Into<String>) -> Self {
284        Self {
285            code,
286            message: message.into(),
287            data: None,
288        }
289    }
290
291    /// Create an error with additional data
292    pub fn with_data(code: i32, message: impl Into<String>, data: impl Serialize) -> Self {
293        Self {
294            code,
295            message: message.into(),
296            data: Some(serde_json::to_value(data).unwrap()),
297        }
298    }
299
300    /// Parse error
301    pub fn parse_error() -> Self {
302        Self::new(ERROR_PARSE, "Parse error")
303    }
304
305    /// Invalid request error
306    pub fn invalid_request(reason: impl Into<String>) -> Self {
307        Self::new(
308            ERROR_INVALID_REQUEST,
309            format!("Invalid request: {}", reason.into()),
310        )
311    }
312
313    /// Method not found error
314    pub fn method_not_found(method: impl AsRef<str>) -> Self {
315        Self::new(
316            ERROR_METHOD_NOT_FOUND,
317            format!("Method not found: {}", method.as_ref()),
318        )
319    }
320
321    /// Invalid params error
322    pub fn invalid_params(reason: impl Into<String>) -> Self {
323        Self::new(
324            ERROR_INVALID_PARAMS,
325            format!("Invalid params: {}", reason.into()),
326        )
327    }
328
329    /// Internal error
330    pub fn internal_error(reason: impl Into<String>) -> Self {
331        Self::new(ERROR_INTERNAL, format!("Internal error: {}", reason.into()))
332    }
333
334    /// Parameter not found error
335    pub fn param_not_found(id: impl AsRef<str>) -> Self {
336        Self::new(
337            ERROR_PARAM_NOT_FOUND,
338            format!("Parameter not found: {}", id.as_ref()),
339        )
340    }
341
342    /// Parameter out of range error
343    pub fn param_out_of_range(id: impl AsRef<str>, value: f32) -> Self {
344        Self::new(
345            ERROR_PARAM_OUT_OF_RANGE,
346            format!("Parameter '{}' value {} out of range", id.as_ref(), value),
347        )
348    }
349}
350
351#[cfg(test)]
352mod tests {
353    use super::*;
354
355    #[test]
356    fn test_request_serialization() {
357        let req = IpcRequest::new(
358            RequestId::Number(1),
359            METHOD_GET_PARAMETER,
360            Some(serde_json::json!({"id": "gain"})),
361        );
362
363        let json = serde_json::to_string(&req).unwrap();
364        assert!(json.contains("\"jsonrpc\":\"2.0\""));
365        assert!(json.contains("\"method\":\"getParameter\""));
366    }
367
368    #[test]
369    fn test_response_serialization() {
370        let resp = IpcResponse::success(
371            RequestId::Number(1),
372            GetParameterResult {
373                id: "gain".to_string(),
374                value: 0.5,
375            },
376        );
377
378        let json = serde_json::to_string(&resp).unwrap();
379        assert!(json.contains("\"jsonrpc\":\"2.0\""));
380        assert!(json.contains("\"result\""));
381        assert!(!json.contains("\"error\""));
382    }
383
384    #[test]
385    fn test_error_response() {
386        let resp = IpcResponse::error(
387            RequestId::String("test".to_string()),
388            IpcError::method_not_found("unknownMethod"),
389        );
390
391        let json = serde_json::to_string(&resp).unwrap();
392        assert!(json.contains("\"error\""));
393        assert!(!json.contains("\"result\""));
394    }
395
396    #[test]
397    fn test_notification_serialization() {
398        let notif = IpcNotification::new(
399            NOTIFICATION_PARAMETER_CHANGED,
400            ParameterChangedNotification {
401                id: "gain".to_string(),
402                value: 0.8,
403            },
404        );
405
406        let json = serde_json::to_string(&notif).unwrap();
407        println!("Notification JSON: {}", json);
408        assert!(json.contains("\"jsonrpc\":\"2.0\""));
409        assert!(json.contains("\"method\":\"parameterChanged\""));
410        // The ParameterChangedNotification has an "id" field, which is OK
411        // We're checking that the notification itself doesn't have a request id
412    }
413
414    #[test]
415    fn test_register_audio_serialization() {
416        let req = IpcRequest::new(
417            RequestId::String("audio-1".to_string()),
418            METHOD_REGISTER_AUDIO,
419            Some(serde_json::json!({
420                "client_id": "dev-audio",
421                "sample_rate": 44100.0,
422                "buffer_size": 512
423            })),
424        );
425
426        let json = serde_json::to_string(&req).unwrap();
427        assert!(json.contains("\"method\":\"registerAudio\""));
428        assert!(json.contains("\"sample_rate\":44100"));
429    }
430
431    #[test]
432    fn test_meter_update_notification() {
433        let notif = IpcNotification::new(
434            NOTIFICATION_METER_UPDATE,
435            MeterUpdateNotification {
436                timestamp_us: 1000,
437                left_peak: 0.5,
438                left_rms: 0.3,
439                right_peak: 0.6,
440                right_rms: 0.4,
441            },
442        );
443
444        let json = serde_json::to_string(&notif).unwrap();
445        assert!(json.contains("\"method\":\"meterUpdate\""));
446        assert!(json.contains("\"left_peak\":0.5"));
447    }
448
449    #[test]
450    fn test_audio_status_serialization() {
451        let result = GetAudioStatusResult {
452            status: Some(AudioRuntimeStatus {
453                phase: AudioRuntimePhase::RunningFullDuplex,
454                diagnostic: None,
455                sample_rate: Some(44100.0),
456                buffer_size: Some(512),
457                updated_at_ms: 123,
458            }),
459        };
460
461        let json = serde_json::to_string(&result).expect("status result should serialize");
462        assert!(json.contains("\"phase\":\"runningFullDuplex\""));
463        assert!(json.contains("\"sample_rate\":44100"));
464    }
465}
466
467// ============================================================================
468// Metering Types
469// ============================================================================
470
471/// Meter frame data for UI visualization.
472///
473/// All values are in linear scale (not dB).
474#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
475pub struct MeterFrame {
476    /// Left channel peak (linear, 0.0 to 1.0+)
477    pub peak_l: f32,
478    /// Right channel peak (linear, 0.0 to 1.0+)
479    pub peak_r: f32,
480    /// Left channel RMS (linear, 0.0 to 1.0+)
481    pub rms_l: f32,
482    /// Right channel RMS (linear, 0.0 to 1.0+)
483    pub rms_r: f32,
484    /// Sample timestamp (monotonic)
485    pub timestamp: u64,
486}
487
488/// Result for getMeterFrame method
489#[derive(Debug, Clone, Serialize, Deserialize)]
490pub struct GetMeterFrameResult {
491    /// Latest meter frame, or null if no data available
492    pub frame: Option<MeterFrame>,
493}
494
495// ----------------------------------------------------------------------------
496// getAudioStatus
497// ----------------------------------------------------------------------------
498
499/// Audio runtime phase as observed by browser dev mode.
500#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
501#[serde(rename_all = "camelCase")]
502pub enum AudioRuntimePhase {
503    Disabled,
504    Initializing,
505    RunningFullDuplex,
506    RunningInputOnly,
507    Degraded,
508    Failed,
509}
510
511/// Structured diagnostic code for audio startup/runtime issues.
512#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
513#[serde(rename_all = "camelCase")]
514pub enum AudioDiagnosticCode {
515    LoaderUnavailable,
516    VtableMissing,
517    ProcessorCreateFailed,
518    NoInputDevice,
519    InputPermissionDenied,
520    NoOutputDevice,
521    StreamStartFailed,
522    Unknown,
523}
524
525/// Optional diagnostic details for the current runtime status.
526#[derive(Debug, Clone, Serialize, Deserialize)]
527pub struct AudioDiagnostic {
528    /// Machine-readable diagnostic code.
529    pub code: AudioDiagnosticCode,
530    /// Human-readable error/diagnostic message.
531    pub message: String,
532    /// Optional actionable hint for the user.
533    #[serde(skip_serializing_if = "Option::is_none")]
534    pub hint: Option<String>,
535}
536
537/// Current audio runtime status for browser dev mode.
538#[derive(Debug, Clone, Serialize, Deserialize)]
539pub struct AudioRuntimeStatus {
540    /// Current runtime phase.
541    pub phase: AudioRuntimePhase,
542    /// Optional startup/runtime diagnostic details.
543    #[serde(skip_serializing_if = "Option::is_none")]
544    pub diagnostic: Option<AudioDiagnostic>,
545    /// Active sample rate when available.
546    #[serde(skip_serializing_if = "Option::is_none")]
547    pub sample_rate: Option<f32>,
548    /// Active audio buffer size when available.
549    #[serde(skip_serializing_if = "Option::is_none")]
550    pub buffer_size: Option<u32>,
551    /// Last update timestamp (milliseconds since UNIX epoch).
552    pub updated_at_ms: u64,
553}
554
555/// Result for getAudioStatus method.
556#[derive(Debug, Clone, Serialize, Deserialize)]
557pub struct GetAudioStatusResult {
558    /// Current status if available on this host.
559    pub status: Option<AudioRuntimeStatus>,
560}
561
562// ----------------------------------------------------------------------------
563// requestResize
564// ----------------------------------------------------------------------------
565
566/// Parameters for requestResize request
567#[derive(Debug, Clone, Serialize, Deserialize)]
568pub struct RequestResizeParams {
569    /// Desired width in logical pixels
570    pub width: u32,
571    /// Desired height in logical pixels
572    pub height: u32,
573}
574
575/// Result of requestResize request
576#[derive(Debug, Clone, Serialize, Deserialize)]
577pub struct RequestResizeResult {
578    /// Whether the host approved the resize
579    pub accepted: bool,
580}
581
582// ----------------------------------------------------------------------------
583// registerAudio
584// ----------------------------------------------------------------------------
585
586/// Parameters for registerAudio request (audio binary → dev server)
587#[derive(Debug, Clone, Serialize, Deserialize)]
588pub struct RegisterAudioParams {
589    /// Unique client identifier
590    pub client_id: String,
591    /// Audio sample rate (e.g., 44100.0)
592    pub sample_rate: f32,
593    /// Buffer size in samples
594    pub buffer_size: u32,
595}
596
597/// Result of registerAudio request
598#[derive(Debug, Clone, Serialize, Deserialize)]
599pub struct RegisterAudioResult {
600    /// Acknowledgment message
601    pub status: String,
602}
603
604// ----------------------------------------------------------------------------
605// Notification: meterUpdate
606// ----------------------------------------------------------------------------
607
608/// Notification sent from audio binary to browser via dev server
609#[derive(Debug, Clone, Serialize, Deserialize)]
610pub struct MeterUpdateNotification {
611    /// Timestamp in microseconds
612    pub timestamp_us: u64,
613    /// Left channel peak (linear scale)
614    pub left_peak: f32,
615    /// Left channel RMS (linear scale)
616    pub left_rms: f32,
617    /// Right channel peak (linear scale)
618    pub right_peak: f32,
619    /// Right channel RMS (linear scale)
620    pub right_rms: f32,
621}
wavecraft_protocol/ipc.rs

wavecraft_protocol/
ipc.rs
