kittycad_modeling_cmds/
websocket.rs

1//! Types for the websocket server.
2
3use std::{borrow::Cow, collections::HashMap};
4
5use parse_display_derive::{Display, FromStr};
6use schemars::JsonSchema;
7use serde::{Deserialize, Serialize};
8#[cfg(feature = "slog")]
9use slog::{Record, Serializer, KV};
10use uuid::Uuid;
11
12use crate::{
13    id::ModelingCmdId,
14    ok_response::OkModelingCmdResponse,
15    shared::{EngineErrorCode, ExportFile},
16    ModelingCmd,
17};
18
19/// The type of error sent by the KittyCAD API.
20#[derive(Display, FromStr, Copy, Eq, PartialEq, Debug, JsonSchema, Deserialize, Serialize, Clone, Ord, PartialOrd)]
21#[serde(rename_all = "snake_case")]
22pub enum ErrorCode {
23    /// Graphics engine failed to complete request, consider retrying
24    InternalEngine,
25    /// API failed to complete request, consider retrying
26    InternalApi,
27    /// User requested something geometrically or graphically impossible.
28    /// Don't retry this request, as it's inherently impossible. Instead, read the error message
29    /// and change your request.
30    BadRequest,
31    /// Auth token is missing from the request
32    AuthTokenMissing,
33    /// Auth token is invalid in some way (expired, incorrect format, etc)
34    AuthTokenInvalid,
35    /// Client sent invalid JSON.
36    InvalidJson,
37    /// Client sent invalid BSON.
38    InvalidBson,
39    /// Client sent a message which is not accepted over this protocol.
40    WrongProtocol,
41    /// Problem sending data between client and KittyCAD API.
42    ConnectionProblem,
43    /// Client sent a Websocket message type which the KittyCAD API does not handle.
44    MessageTypeNotAccepted,
45    /// Client sent a Websocket message intended for WebRTC but it was configured as a WebRTC
46    /// connection.
47    MessageTypeNotAcceptedForWebRTC,
48}
49
50/// Because [`EngineErrorCode`] is a subset of [`ErrorCode`], you can trivially map
51/// each variant of the former to a variant of the latter.
52impl From<EngineErrorCode> for ErrorCode {
53    fn from(value: EngineErrorCode) -> Self {
54        match value {
55            EngineErrorCode::InternalEngine => Self::InternalEngine,
56            EngineErrorCode::BadRequest => Self::BadRequest,
57        }
58    }
59}
60
61/// A graphics command submitted to the KittyCAD engine via the Modeling API.
62#[derive(Debug, Clone, Deserialize, Serialize)]
63#[cfg_attr(feature = "derive-jsonschema-on-enums", derive(schemars::JsonSchema))]
64pub struct ModelingCmdReq {
65    /// Which command to submit to the Kittycad engine.
66    pub cmd: ModelingCmd,
67    /// ID of command being submitted.
68    pub cmd_id: ModelingCmdId,
69}
70
71/// The websocket messages the server receives.
72#[allow(clippy::large_enum_variant)]
73#[derive(Serialize, Deserialize, Debug, Clone)]
74#[cfg_attr(feature = "derive-jsonschema-on-enums", derive(schemars::JsonSchema))]
75#[serde(tag = "type", rename_all = "snake_case")]
76pub enum WebSocketRequest {
77    /// The trickle ICE candidate request.
78    // We box these to avoid a huge size difference between variants.
79    TrickleIce {
80        /// Information about the ICE candidate.
81        candidate: Box<RtcIceCandidateInit>,
82    },
83    /// The SDP offer request.
84    SdpOffer {
85        /// The session description.
86        offer: Box<RtcSessionDescription>,
87    },
88    /// The modeling command request.
89    ModelingCmdReq(ModelingCmdReq),
90    /// A sequence of modeling requests. If any request fails, following requests will not be tried.
91    ModelingCmdBatchReq(ModelingBatch),
92    /// The client-to-server Ping to ensure the WebSocket stays alive.
93    Ping {},
94
95    /// The response to a metrics collection request from the server.
96    MetricsResponse {
97        /// Collected metrics from the Client's end of the engine connection.
98        metrics: Box<ClientMetrics>,
99    },
100
101    /// Return information about the connected instance
102    Debug {},
103
104    /// Authentication header request.
105    Headers {
106        /// The authentication header.
107        headers: HashMap<String, String>,
108    },
109}
110
111/// A sequence of modeling requests. If any request fails, following requests will not be tried.
112#[derive(Serialize, Deserialize, Debug, Clone)]
113#[cfg_attr(feature = "derive-jsonschema-on-enums", derive(schemars::JsonSchema))]
114#[serde(rename_all = "snake_case")]
115pub struct ModelingBatch {
116    /// A sequence of modeling requests. If any request fails, following requests will not be tried.
117    pub requests: Vec<ModelingCmdReq>,
118    /// ID of batch being submitted.
119    /// Each request has their own individual ModelingCmdId, but this is the
120    /// ID of the overall batch.
121    pub batch_id: ModelingCmdId,
122    /// If false or omitted, responses to each batch command will just be Ok(()).
123    /// If true, responses will be the actual response data for that modeling command.
124    #[serde(default)]
125    pub responses: bool,
126}
127
128impl std::default::Default for ModelingBatch {
129    /// Creates a batch with 0 requests and a random ID.
130    fn default() -> Self {
131        Self {
132            requests: Default::default(),
133            batch_id: Uuid::new_v4().into(),
134            responses: false,
135        }
136    }
137}
138
139impl ModelingBatch {
140    /// Add a new modeling command to the end of this batch.
141    pub fn push(&mut self, req: ModelingCmdReq) {
142        self.requests.push(req);
143    }
144
145    /// Are there any requests in the batch?
146    pub fn is_empty(&self) -> bool {
147        self.requests.is_empty()
148    }
149}
150
151/// Representation of an ICE server used for STUN/TURN
152/// Used to initiate WebRTC connections
153/// based on <https://developer.mozilla.org/en-US/docs/Web/API/RTCIceServer>
154#[derive(serde::Serialize, serde::Deserialize, Debug, JsonSchema, Clone)]
155pub struct IceServer {
156    /// URLs for a given STUN/TURN server.
157    /// IceServer urls can either be a string or an array of strings
158    /// But, we choose to always convert to an array of strings for consistency
159    pub urls: Vec<String>,
160    /// Credentials for a given TURN server.
161    pub credential: Option<String>,
162    /// Username for a given TURN server.
163    pub username: Option<String>,
164}
165
166/// The websocket messages this server sends.
167#[derive(Serialize, Deserialize, Debug, Clone)]
168#[cfg_attr(feature = "derive-jsonschema-on-enums", derive(schemars::JsonSchema))]
169#[serde(tag = "type", content = "data", rename_all = "snake_case")]
170pub enum OkWebSocketResponseData {
171    /// Information about the ICE servers.
172    IceServerInfo {
173        /// Information about the ICE servers.
174        ice_servers: Vec<IceServer>,
175    },
176    /// The trickle ICE candidate response.
177    // We box these to avoid a huge size difference between variants.
178    TrickleIce {
179        /// Information about the ICE candidate.
180        candidate: Box<RtcIceCandidateInit>,
181    },
182    /// The SDP answer response.
183    SdpAnswer {
184        /// The session description.
185        answer: Box<RtcSessionDescription>,
186    },
187    /// The modeling command response.
188    Modeling {
189        /// The result of the command.
190        modeling_response: OkModelingCmdResponse,
191    },
192    /// Response to a ModelingBatch.
193    ModelingBatch {
194        /// For each request in the batch,
195        /// maps its ID to the request's outcome.
196        responses: HashMap<ModelingCmdId, BatchResponse>,
197    },
198    /// The exported files.
199    Export {
200        /// The exported files
201        files: Vec<RawFile>,
202    },
203
204    /// Request a collection of metrics, to include WebRTC.
205    MetricsRequest {},
206
207    /// Data about the Modeling Session (application-level).
208    ModelingSessionData {
209        /// Data about the Modeling Session (application-level).
210        session: ModelingSessionData,
211    },
212
213    /// Pong response to a Ping message.
214    Pong {},
215
216    /// Information about the connected instance
217    Debug {
218        /// Instance name. This may or may not mean something.
219        name: String,
220    },
221}
222
223/// Successful Websocket response.
224#[derive(Debug, Serialize, Deserialize, Clone)]
225#[cfg_attr(feature = "derive-jsonschema-on-enums", derive(schemars::JsonSchema))]
226#[serde(rename_all = "snake_case")]
227pub struct SuccessWebSocketResponse {
228    /// Always true
229    pub success: bool,
230    /// Which request this is a response to.
231    /// If the request was a modeling command, this is the modeling command ID.
232    /// If no request ID was sent, this will be null.
233    pub request_id: Option<Uuid>,
234    /// The data sent with a successful response.
235    /// This will be flattened into a 'type' and 'data' field.
236    pub resp: OkWebSocketResponseData,
237}
238
239/// Unsuccessful Websocket response.
240#[derive(JsonSchema, Debug, Serialize, Deserialize, Clone)]
241#[serde(rename_all = "snake_case")]
242pub struct FailureWebSocketResponse {
243    /// Always false
244    pub success: bool,
245    /// Which request this is a response to.
246    /// If the request was a modeling command, this is the modeling command ID.
247    /// If no request ID was sent, this will be null.
248    pub request_id: Option<Uuid>,
249    /// The errors that occurred.
250    pub errors: Vec<ApiError>,
251}
252
253/// Websocket responses can either be successful or unsuccessful.
254/// Slightly different schemas in either case.
255#[derive(Debug, Serialize, Deserialize, Clone)]
256#[cfg_attr(feature = "derive-jsonschema-on-enums", derive(schemars::JsonSchema))]
257#[serde(rename_all = "snake_case", untagged)]
258pub enum WebSocketResponse {
259    /// Response sent when a request succeeded.
260    Success(SuccessWebSocketResponse),
261    /// Response sent when a request did not succeed.
262    Failure(FailureWebSocketResponse),
263}
264
265/// Websocket responses can either be successful or unsuccessful.
266/// Slightly different schemas in either case.
267#[derive(Debug, Serialize, Deserialize, Clone)]
268#[cfg_attr(feature = "derive-jsonschema-on-enums", derive(schemars::JsonSchema))]
269#[serde(rename_all = "snake_case", untagged)]
270pub enum BatchResponse {
271    /// Response sent when a request succeeded.
272    Success {
273        /// Response to the modeling command.
274        response: OkModelingCmdResponse,
275    },
276    /// Response sent when a request did not succeed.
277    Failure {
278        /// Errors that occurred during the modeling command.
279        errors: Vec<ApiError>,
280    },
281}
282
283impl WebSocketResponse {
284    /// Make a new success response.
285    pub fn success(request_id: Option<Uuid>, resp: OkWebSocketResponseData) -> Self {
286        Self::Success(SuccessWebSocketResponse {
287            success: true,
288            request_id,
289            resp,
290        })
291    }
292
293    /// Make a new failure response.
294    pub fn failure(request_id: Option<Uuid>, errors: Vec<ApiError>) -> Self {
295        Self::Failure(FailureWebSocketResponse {
296            success: false,
297            request_id,
298            errors,
299        })
300    }
301
302    /// Did the request succeed?
303    pub fn is_success(&self) -> bool {
304        matches!(self, Self::Success(_))
305    }
306
307    /// Did the request fail?
308    pub fn is_failure(&self) -> bool {
309        matches!(self, Self::Failure(_))
310    }
311
312    /// Get the ID of whichever request this response is for.
313    pub fn request_id(&self) -> Option<Uuid> {
314        match self {
315            WebSocketResponse::Success(x) => x.request_id,
316            WebSocketResponse::Failure(x) => x.request_id,
317        }
318    }
319}
320
321/// A raw file with unencoded contents to be passed over binary websockets.
322/// When raw files come back for exports it is sent as binary/bson, not text/json.
323#[derive(Debug, Serialize, Deserialize, JsonSchema, Clone)]
324#[cfg_attr(feature = "python", pyo3::pyclass, pyo3_stub_gen::derive::gen_stub_pyclass)]
325pub struct RawFile {
326    /// The name of the file.
327    pub name: String,
328    /// The contents of the file.
329    #[serde(
330        serialize_with = "serde_bytes::serialize",
331        deserialize_with = "serde_bytes::deserialize"
332    )]
333    pub contents: Vec<u8>,
334}
335
336#[cfg(feature = "python")]
337#[pyo3_stub_gen::derive::gen_stub_pymethods]
338#[pyo3::pymethods]
339impl RawFile {
340    #[getter]
341    fn contents(&self) -> Vec<u8> {
342        self.contents.clone()
343    }
344
345    #[getter]
346    fn name(&self) -> String {
347        self.name.clone()
348    }
349}
350
351impl From<ExportFile> for RawFile {
352    fn from(f: ExportFile) -> Self {
353        Self {
354            name: f.name,
355            contents: f.contents.0,
356        }
357    }
358}
359
360/// An error with an internal message for logging.
361#[derive(Debug, Serialize, Deserialize, JsonSchema)]
362pub struct LoggableApiError {
363    /// The error shown to users
364    pub error: ApiError,
365    /// The string logged internally
366    pub msg_internal: Option<Cow<'static, str>>,
367}
368
369#[cfg(feature = "slog")]
370impl KV for LoggableApiError {
371    fn serialize(&self, _rec: &Record, serializer: &mut dyn Serializer) -> slog::Result {
372        use slog::Key;
373        if let Some(ref msg_internal) = self.msg_internal {
374            serializer.emit_str(Key::from("msg_internal"), msg_internal)?;
375        }
376        serializer.emit_str(Key::from("msg_external"), &self.error.message)?;
377        serializer.emit_str(Key::from("error_code"), &self.error.error_code.to_string())
378    }
379}
380
381/// An error.
382#[derive(Debug, Serialize, Deserialize, JsonSchema, Eq, PartialEq, Clone)]
383pub struct ApiError {
384    /// The error code.
385    pub error_code: ErrorCode,
386    /// The error message.
387    pub message: String,
388}
389
390impl ApiError {
391    /// Convert to a `LoggableApiError` with no internal message.
392    pub fn no_internal_message(self) -> LoggableApiError {
393        LoggableApiError {
394            error: self,
395            msg_internal: None,
396        }
397    }
398    /// Add an internal log message to this error.
399    pub fn with_message(self, msg_internal: Cow<'static, str>) -> LoggableApiError {
400        LoggableApiError {
401            error: self,
402            msg_internal: Some(msg_internal),
403        }
404    }
405
406    /// Should the internal error message be logged?
407    pub fn should_log_internal_message(&self) -> bool {
408        use ErrorCode as Code;
409        match self.error_code {
410            // Internal errors should always be logged, as they're problems with KittyCAD programming
411            Code::InternalEngine | Code::InternalApi => true,
412            // The user did something wrong, no need to log it, as there's nothing KittyCAD programmers can fix
413            Code::MessageTypeNotAcceptedForWebRTC
414            | Code::MessageTypeNotAccepted
415            | Code::BadRequest
416            | Code::WrongProtocol
417            | Code::AuthTokenMissing
418            | Code::AuthTokenInvalid
419            | Code::InvalidBson
420            | Code::InvalidJson => false,
421            // In debug builds, log connection problems, otherwise don't.
422            Code::ConnectionProblem => cfg!(debug_assertions),
423        }
424    }
425}
426
427/// Serde serializes Result into JSON as "Ok" and "Err", but we want "ok" and "err".
428/// So, create a new enum that serializes as lowercase.
429#[derive(Debug, Serialize, Deserialize, JsonSchema)]
430#[serde(rename_all = "snake_case", rename = "SnakeCaseResult")]
431pub enum SnakeCaseResult<T, E> {
432    /// The result is Ok.
433    Ok(T),
434    /// The result is Err.
435    Err(E),
436}
437
438impl<T, E> From<SnakeCaseResult<T, E>> for Result<T, E> {
439    fn from(value: SnakeCaseResult<T, E>) -> Self {
440        match value {
441            SnakeCaseResult::Ok(x) => Self::Ok(x),
442            SnakeCaseResult::Err(x) => Self::Err(x),
443        }
444    }
445}
446
447impl<T, E> From<Result<T, E>> for SnakeCaseResult<T, E> {
448    fn from(value: Result<T, E>) -> Self {
449        match value {
450            Ok(x) => Self::Ok(x),
451            Err(x) => Self::Err(x),
452        }
453    }
454}
455
456/// ClientMetrics contains information regarding the state of the peer.
457#[derive(Default, Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
458pub struct ClientMetrics {
459    /// Counter of the number of WebRTC frames the client has dropped from the
460    /// inbound video stream.
461    ///
462    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-framesdropped
463    pub rtc_frames_dropped: Option<u32>,
464
465    /// Counter of the number of WebRTC frames that the client has decoded
466    /// from the inbound video stream.
467    ///
468    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-freezecount
469    pub rtc_frames_decoded: Option<u64>,
470
471    /// Counter of the number of WebRTC frames that the client has received
472    /// from the inbound video stream.
473    ///
474    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-freezecount
475    pub rtc_frames_received: Option<u64>,
476
477    /// Current number of frames being rendered in the last second. A good target
478    /// is 60 frames per second, but it can fluctuate depending on network
479    /// conditions.
480    ///
481    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-freezecount
482    pub rtc_frames_per_second: Option<u8>, // no way we're more than 255 fps :)
483
484    /// Number of times the inbound video playback has frozen. This is usually due to
485    /// network conditions.
486    ///
487    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-freezecount
488    pub rtc_freeze_count: Option<u32>,
489
490    /// Amount of "jitter" in the inbound video stream. Network latency is the time
491    /// it takes a packet to traverse the network. The amount that the latency
492    /// varies is the jitter. Video latency is the time it takes to render
493    /// a frame sent by the server (including network latency). A low jitter
494    /// means the video latency can be reduced without impacting smooth
495    /// playback. High jitter means clients will increase video latency to
496    /// ensure smooth playback.
497    ///
498    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcreceivedrtpstreamstats-jitter
499    pub rtc_jitter_sec: Option<f64>,
500
501    /// Number of "key frames" decoded in the inbound h.264 stream. A
502    /// key frame is an expensive (bandwidth-wise) "full image" of the video
503    /// frame. Data after the keyframe become -- effectively -- "diff"
504    /// operations on that key frame. The Engine will only send a keyframe if
505    /// required, which is an indication that some of the "diffs" have been
506    /// lost, usually an indication of poor network conditions. We like this
507    /// metric to understand times when the connection has had to recover.
508    ///
509    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-keyframesdecoded
510    pub rtc_keyframes_decoded: Option<u32>,
511
512    /// Number of seconds of frozen video the user has been subjected to.
513    ///
514    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-totalfreezesduration
515    pub rtc_total_freezes_duration_sec: Option<f32>,
516
517    /// The height of the inbound video stream in pixels.
518    ///
519    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-frameheight
520    pub rtc_frame_height: Option<u32>,
521
522    /// The width of the inbound video stream in pixels.
523    ///
524    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-framewidth
525    pub rtc_frame_width: Option<u32>,
526
527    /// Amount of packets lost in the inbound video stream.
528    ///
529    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcreceivedrtpstreamstats-packetslost
530    pub rtc_packets_lost: Option<u32>,
531
532    ///  Count the total number of Picture Loss Indication (PLI) packets.
533    ///
534    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-plicount
535    pub rtc_pli_count: Option<u32>,
536
537    /// Count of the total number of video pauses experienced by this receiver.
538    ///
539    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-pausecount
540    pub rtc_pause_count: Option<u32>,
541
542    /// Count of the total number of video pauses experienced by this receiver.
543    ///
544    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-totalpausesduration
545    pub rtc_total_pauses_duration_sec: Option<f32>,
546
547    /// Total duration of pauses in seconds.
548    ///
549    /// This is the "ping" between the client and the STUN server. Not to be confused with the
550    /// E2E RTT documented
551    /// [here](https://www.w3.org/TR/webrtc-stats/#dom-rtcremoteinboundrtpstreamstats-roundtriptime)
552    ///
553    /// https://www.w3.org/TR/webrtc-stats/#dom-rtcicecandidatepairstats-currentroundtriptime
554    pub rtc_stun_rtt_sec: Option<f32>,
555}
556
557/// ICECandidate represents a ice candidate
558#[derive(Default, Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
559pub struct RtcIceCandidate {
560    /// The stats ID.
561    pub stats_id: String,
562    /// The foundation for the address.
563    pub foundation: String,
564    /// The priority of the candidate.
565    pub priority: u32,
566    /// The address of the candidate.
567    pub address: String,
568    /// The protocol used for the candidate.
569    pub protocol: RtcIceProtocol,
570    /// The port used for the candidate.
571    pub port: u16,
572    /// The type of the candidate.
573    pub typ: RtcIceCandidateType,
574    /// The component of the candidate.
575    pub component: u16,
576    /// The related address of the candidate.
577    pub related_address: String,
578    /// The related port of the candidate.
579    pub related_port: u16,
580    /// The TCP type of the candidate.
581    pub tcp_type: String,
582}
583
584#[cfg(feature = "webrtc")]
585impl From<webrtc::ice_transport::ice_candidate::RTCIceCandidate> for RtcIceCandidate {
586    fn from(candidate: webrtc::ice_transport::ice_candidate::RTCIceCandidate) -> Self {
587        Self {
588            stats_id: candidate.stats_id,
589            foundation: candidate.foundation,
590            priority: candidate.priority,
591            address: candidate.address,
592            protocol: candidate.protocol.into(),
593            port: candidate.port,
594            typ: candidate.typ.into(),
595            component: candidate.component,
596            related_address: candidate.related_address,
597            related_port: candidate.related_port,
598            tcp_type: candidate.tcp_type,
599        }
600    }
601}
602
603#[cfg(feature = "webrtc")]
604impl From<RtcIceCandidate> for webrtc::ice_transport::ice_candidate::RTCIceCandidate {
605    fn from(candidate: RtcIceCandidate) -> Self {
606        Self {
607            stats_id: candidate.stats_id,
608            foundation: candidate.foundation,
609            priority: candidate.priority,
610            address: candidate.address,
611            protocol: candidate.protocol.into(),
612            port: candidate.port,
613            typ: candidate.typ.into(),
614            component: candidate.component,
615            related_address: candidate.related_address,
616            related_port: candidate.related_port,
617            tcp_type: candidate.tcp_type,
618        }
619    }
620}
621
622/// ICECandidateType represents the type of the ICE candidate used.
623#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
624#[serde(rename_all = "snake_case")]
625pub enum RtcIceCandidateType {
626    /// Unspecified indicates that the candidate type is unspecified.
627    #[default]
628    Unspecified,
629
630    /// ICECandidateTypeHost indicates that the candidate is of Host type as
631    /// described in <https://tools.ietf.org/html/rfc8445#section-5.1.1.1>. A
632    /// candidate obtained by binding to a specific port from an IP address on
633    /// the host. This includes IP addresses on physical interfaces and logical
634    /// ones, such as ones obtained through VPNs.
635    Host,
636
637    /// ICECandidateTypeSrflx indicates the the candidate is of Server
638    /// Reflexive type as described
639    /// <https://tools.ietf.org/html/rfc8445#section-5.1.1.2>. A candidate type
640    /// whose IP address and port are a binding allocated by a NAT for an ICE
641    /// agent after it sends a packet through the NAT to a server, such as a
642    /// STUN server.
643    Srflx,
644
645    /// ICECandidateTypePrflx indicates that the candidate is of Peer
646    /// Reflexive type. A candidate type whose IP address and port are a binding
647    /// allocated by a NAT for an ICE agent after it sends a packet through the
648    /// NAT to its peer.
649    Prflx,
650
651    /// ICECandidateTypeRelay indicates the the candidate is of Relay type as
652    /// described in <https://tools.ietf.org/html/rfc8445#section-5.1.1.2>. A
653    /// candidate type obtained from a relay server, such as a TURN server.
654    Relay,
655}
656
657#[cfg(feature = "webrtc")]
658impl From<webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType> for RtcIceCandidateType {
659    fn from(candidate_type: webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType) -> Self {
660        match candidate_type {
661            webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType::Host => RtcIceCandidateType::Host,
662            webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType::Srflx => RtcIceCandidateType::Srflx,
663            webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType::Prflx => RtcIceCandidateType::Prflx,
664            webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType::Relay => RtcIceCandidateType::Relay,
665            webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType::Unspecified => {
666                RtcIceCandidateType::Unspecified
667            }
668        }
669    }
670}
671
672#[cfg(feature = "webrtc")]
673impl From<RtcIceCandidateType> for webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType {
674    fn from(candidate_type: RtcIceCandidateType) -> Self {
675        match candidate_type {
676            RtcIceCandidateType::Host => webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType::Host,
677            RtcIceCandidateType::Srflx => webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType::Srflx,
678            RtcIceCandidateType::Prflx => webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType::Prflx,
679            RtcIceCandidateType::Relay => webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType::Relay,
680            RtcIceCandidateType::Unspecified => {
681                webrtc::ice_transport::ice_candidate_type::RTCIceCandidateType::Unspecified
682            }
683        }
684    }
685}
686
687/// ICEProtocol indicates the transport protocol type that is used in the
688/// ice.URL structure.
689#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
690#[serde(rename_all = "snake_case")]
691pub enum RtcIceProtocol {
692    /// Unspecified indicates that the protocol is unspecified.
693    #[default]
694    Unspecified,
695
696    /// UDP indicates the URL uses a UDP transport.
697    Udp,
698
699    /// TCP indicates the URL uses a TCP transport.
700    Tcp,
701}
702
703#[cfg(feature = "webrtc")]
704impl From<webrtc::ice_transport::ice_protocol::RTCIceProtocol> for RtcIceProtocol {
705    fn from(protocol: webrtc::ice_transport::ice_protocol::RTCIceProtocol) -> Self {
706        match protocol {
707            webrtc::ice_transport::ice_protocol::RTCIceProtocol::Udp => RtcIceProtocol::Udp,
708            webrtc::ice_transport::ice_protocol::RTCIceProtocol::Tcp => RtcIceProtocol::Tcp,
709            webrtc::ice_transport::ice_protocol::RTCIceProtocol::Unspecified => RtcIceProtocol::Unspecified,
710        }
711    }
712}
713
714#[cfg(feature = "webrtc")]
715impl From<RtcIceProtocol> for webrtc::ice_transport::ice_protocol::RTCIceProtocol {
716    fn from(protocol: RtcIceProtocol) -> Self {
717        match protocol {
718            RtcIceProtocol::Udp => webrtc::ice_transport::ice_protocol::RTCIceProtocol::Udp,
719            RtcIceProtocol::Tcp => webrtc::ice_transport::ice_protocol::RTCIceProtocol::Tcp,
720            RtcIceProtocol::Unspecified => webrtc::ice_transport::ice_protocol::RTCIceProtocol::Unspecified,
721        }
722    }
723}
724
725/// ICECandidateInit is used to serialize ice candidates
726#[derive(Default, Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
727#[serde(rename_all = "camelCase")]
728// These HAVE to be camel case as per the RFC.
729pub struct RtcIceCandidateInit {
730    /// The candidate string associated with the object.
731    pub candidate: String,
732    /// The identifier of the "media stream identification" as defined in
733    /// [RFC 8841](https://tools.ietf.org/html/rfc8841).
734    pub sdp_mid: Option<String>,
735    /// The index (starting at zero) of the m-line in the SDP this candidate is
736    /// associated with.
737    #[serde(rename = "sdpMLineIndex")]
738    pub sdp_mline_index: Option<u16>,
739    /// The username fragment (as defined in
740    /// [RFC 8445](https://tools.ietf.org/html/rfc8445#section-5.2.1)) associated with the object.
741    pub username_fragment: Option<String>,
742}
743
744#[cfg(feature = "webrtc")]
745impl From<webrtc::ice_transport::ice_candidate::RTCIceCandidateInit> for RtcIceCandidateInit {
746    fn from(candidate: webrtc::ice_transport::ice_candidate::RTCIceCandidateInit) -> Self {
747        Self {
748            candidate: candidate.candidate,
749            sdp_mid: candidate.sdp_mid,
750            sdp_mline_index: candidate.sdp_mline_index,
751            username_fragment: candidate.username_fragment,
752        }
753    }
754}
755
756#[cfg(feature = "webrtc")]
757impl From<RtcIceCandidateInit> for webrtc::ice_transport::ice_candidate::RTCIceCandidateInit {
758    fn from(candidate: RtcIceCandidateInit) -> Self {
759        Self {
760            candidate: candidate.candidate,
761            sdp_mid: candidate.sdp_mid,
762            sdp_mline_index: candidate.sdp_mline_index,
763            username_fragment: candidate.username_fragment,
764        }
765    }
766}
767
768/// SessionDescription is used to expose local and remote session descriptions.
769#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema)]
770pub struct RtcSessionDescription {
771    /// SDP type.
772    #[serde(rename = "type")]
773    pub sdp_type: RtcSdpType,
774
775    /// SDP string.
776    pub sdp: String,
777}
778
779#[cfg(feature = "webrtc")]
780impl From<webrtc::peer_connection::sdp::session_description::RTCSessionDescription> for RtcSessionDescription {
781    fn from(desc: webrtc::peer_connection::sdp::session_description::RTCSessionDescription) -> Self {
782        Self {
783            sdp_type: desc.sdp_type.into(),
784            sdp: desc.sdp,
785        }
786    }
787}
788
789#[cfg(feature = "webrtc")]
790impl TryFrom<RtcSessionDescription> for webrtc::peer_connection::sdp::session_description::RTCSessionDescription {
791    type Error = anyhow::Error;
792
793    fn try_from(desc: RtcSessionDescription) -> Result<Self, Self::Error> {
794        let result = match desc.sdp_type {
795            RtcSdpType::Offer => {
796                webrtc::peer_connection::sdp::session_description::RTCSessionDescription::offer(desc.sdp)?
797            }
798            RtcSdpType::Pranswer => {
799                webrtc::peer_connection::sdp::session_description::RTCSessionDescription::pranswer(desc.sdp)?
800            }
801            RtcSdpType::Answer => {
802                webrtc::peer_connection::sdp::session_description::RTCSessionDescription::answer(desc.sdp)?
803            }
804            RtcSdpType::Rollback => anyhow::bail!("Rollback is not supported"),
805            RtcSdpType::Unspecified => anyhow::bail!("Unspecified is not supported"),
806        };
807
808        Ok(result)
809    }
810}
811
812/// SDPType describes the type of an SessionDescription.
813#[derive(Default, Debug, PartialEq, Eq, Copy, Clone, Serialize, Deserialize, JsonSchema)]
814#[serde(rename_all = "snake_case")]
815pub enum RtcSdpType {
816    /// Unspecified indicates that the type is unspecified.
817    #[default]
818    Unspecified = 0,
819
820    /// indicates that a description MUST be treated as an SDP offer.
821    Offer,
822
823    /// indicates that a description MUST be treated as an
824    /// SDP answer, but not a final answer. A description used as an SDP
825    /// pranswer may be applied as a response to an SDP offer, or an update to
826    /// a previously sent SDP pranswer.
827    Pranswer,
828
829    /// indicates that a description MUST be treated as an SDP
830    /// final answer, and the offer-answer exchange MUST be considered complete.
831    /// A description used as an SDP answer may be applied as a response to an
832    /// SDP offer or as an update to a previously sent SDP pranswer.
833    Answer,
834
835    /// indicates that a description MUST be treated as
836    /// canceling the current SDP negotiation and moving the SDP offer and
837    /// answer back to what it was in the previous stable state. Note the
838    /// local or remote SDP descriptions in the previous stable state could be
839    /// null if there has not yet been a successful offer-answer negotiation.
840    Rollback,
841}
842
843#[cfg(feature = "webrtc")]
844impl From<webrtc::peer_connection::sdp::sdp_type::RTCSdpType> for RtcSdpType {
845    fn from(sdp_type: webrtc::peer_connection::sdp::sdp_type::RTCSdpType) -> Self {
846        match sdp_type {
847            webrtc::peer_connection::sdp::sdp_type::RTCSdpType::Offer => Self::Offer,
848            webrtc::peer_connection::sdp::sdp_type::RTCSdpType::Pranswer => Self::Pranswer,
849            webrtc::peer_connection::sdp::sdp_type::RTCSdpType::Answer => Self::Answer,
850            webrtc::peer_connection::sdp::sdp_type::RTCSdpType::Rollback => Self::Rollback,
851            webrtc::peer_connection::sdp::sdp_type::RTCSdpType::Unspecified => Self::Unspecified,
852        }
853    }
854}
855
856#[cfg(feature = "webrtc")]
857impl From<RtcSdpType> for webrtc::peer_connection::sdp::sdp_type::RTCSdpType {
858    fn from(sdp_type: RtcSdpType) -> Self {
859        match sdp_type {
860            RtcSdpType::Offer => Self::Offer,
861            RtcSdpType::Pranswer => Self::Pranswer,
862            RtcSdpType::Answer => Self::Answer,
863            RtcSdpType::Rollback => Self::Rollback,
864            RtcSdpType::Unspecified => Self::Unspecified,
865        }
866    }
867}
868/// Successful Websocket response.
869#[derive(JsonSchema, Debug, Serialize, Deserialize, Clone)]
870#[serde(rename_all = "snake_case")]
871pub struct ModelingSessionData {
872    /// ID of the API call this modeling session is using.
873    /// Useful for tracing and debugging.
874    pub api_call_id: String,
875}
876
877#[cfg(test)]
878mod tests {
879    use super::*;
880    use crate::output;
881
882    const REQ_ID: Uuid = uuid::uuid!("cc30d5e2-482b-4498-b5d2-6131c30a50a4");
883
884    #[test]
885    fn serialize_websocket_modeling_ok() {
886        let actual = WebSocketResponse::Success(SuccessWebSocketResponse {
887            success: true,
888            request_id: Some(REQ_ID),
889            resp: OkWebSocketResponseData::Modeling {
890                modeling_response: OkModelingCmdResponse::CurveGetControlPoints(output::CurveGetControlPoints {
891                    control_points: vec![],
892                }),
893            },
894        });
895        let expected = serde_json::json!({
896            "success": true,
897            "request_id": "cc30d5e2-482b-4498-b5d2-6131c30a50a4",
898            "resp": {
899                "type": "modeling",
900                "data": {
901                    "modeling_response": {
902                        "type": "curve_get_control_points",
903                        "data": { "control_points": [] }
904                    }
905                }
906            }
907        });
908        assert_json_eq(actual, expected);
909    }
910
911    #[test]
912    fn serialize_websocket_webrtc_ok() {
913        let actual = WebSocketResponse::Success(SuccessWebSocketResponse {
914            success: true,
915            request_id: Some(REQ_ID),
916            resp: OkWebSocketResponseData::IceServerInfo { ice_servers: vec![] },
917        });
918        let expected = serde_json::json!({
919            "success": true,
920            "request_id": "cc30d5e2-482b-4498-b5d2-6131c30a50a4",
921            "resp": {
922                "type": "ice_server_info",
923                "data": {
924                    "ice_servers": []
925                }
926            }
927        });
928        assert_json_eq(actual, expected);
929    }
930
931    #[test]
932    fn serialize_websocket_export_ok() {
933        let actual = WebSocketResponse::Success(SuccessWebSocketResponse {
934            success: true,
935            request_id: Some(REQ_ID),
936            resp: OkWebSocketResponseData::Export { files: vec![] },
937        });
938        let expected = serde_json::json!({
939            "success": true,
940            "request_id": "cc30d5e2-482b-4498-b5d2-6131c30a50a4",
941            "resp": {
942                "type": "export",
943                "data": {"files": [] }
944            }
945        });
946        assert_json_eq(actual, expected);
947    }
948
949    #[test]
950    fn serialize_websocket_err() {
951        let actual = WebSocketResponse::Failure(FailureWebSocketResponse {
952            success: false,
953            request_id: Some(REQ_ID),
954            errors: vec![ApiError {
955                error_code: ErrorCode::InternalApi,
956                message: "you fucked up!".to_owned(),
957            }],
958        });
959        let expected = serde_json::json!({
960            "success": false,
961            "request_id": "cc30d5e2-482b-4498-b5d2-6131c30a50a4",
962            "errors": [
963                {
964                    "error_code": "internal_api",
965                    "message": "you fucked up!"
966                }
967            ],
968        });
969        assert_json_eq(actual, expected);
970    }
971
972    #[test]
973    fn serialize_websocket_metrics() {
974        let actual = WebSocketRequest::MetricsResponse {
975            metrics: Box::new(ClientMetrics {
976                rtc_frames_dropped: Some(1),
977                rtc_frames_decoded: Some(2),
978                rtc_frames_per_second: Some(3),
979                rtc_frames_received: Some(4),
980                rtc_freeze_count: Some(5),
981                rtc_jitter_sec: Some(6.7),
982                rtc_keyframes_decoded: Some(8),
983                rtc_total_freezes_duration_sec: Some(9.1),
984                rtc_frame_height: Some(100),
985                rtc_frame_width: Some(100),
986                rtc_packets_lost: Some(0),
987                rtc_pli_count: Some(0),
988                rtc_pause_count: Some(0),
989                rtc_total_pauses_duration_sec: Some(0.0),
990                rtc_stun_rtt_sec: Some(0.005),
991            }),
992        };
993        let expected = serde_json::json!({
994            "type": "metrics_response",
995            "metrics": {
996                "rtc_frames_dropped": 1,
997                "rtc_frames_decoded": 2,
998                "rtc_frames_per_second": 3,
999                "rtc_frames_received": 4,
1000                "rtc_freeze_count": 5,
1001                "rtc_jitter_sec": 6.7,
1002                "rtc_keyframes_decoded": 8,
1003                "rtc_total_freezes_duration_sec": 9.1,
1004                "rtc_frame_height": 100,
1005                "rtc_frame_width": 100,
1006                "rtc_packets_lost": 0,
1007                "rtc_pli_count": 0,
1008                "rtc_pause_count": 0,
1009                "rtc_total_pauses_duration_sec": 0.0,
1010                "rtc_stun_rtt_sec": 0.005,
1011            },
1012        });
1013        assert_json_eq(actual, expected);
1014    }
1015
1016    fn assert_json_eq<T: Serialize>(actual: T, expected: serde_json::Value) {
1017        let json_str = serde_json::to_string(&actual).unwrap();
1018        let actual: serde_json::Value = serde_json::from_str(&json_str).unwrap();
1019        assert_eq!(actual, expected, "got\n{actual:#}\n, expected\n{expected:#}\n");
1020    }
1021}
kittycad_modeling_cmds/websocket.rs

kittycad_modeling_cmds/
websocket.rs
