Skip to main content

dnet_js/
lib.rs

1#![cfg(target_arch = "wasm32")]
2#![warn(missing_docs)]
3
4//! Common features used by WebSocket (WASM), WebWorker and MessagePort transports.
5
6pub mod state;
7
8#[cfg(feature = "logging")]
9use dnet_base::Logging;
10/// Derive macro  that can be used to automatically implement
11/// [IntoTransferable]/[FromTransferable] traits.
12///
13/// - fields of [transferable objects](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects)
14///   need to be marked with `#[transferable]` attribute.
15/// - fields holding types implementing [IntoTransferable]/[FromTransferable] need to be marked `#[into_transferable]` attribute,
16/// - other fields need to be serializable (with [serde]).
17///
18/// [IntoTransferable]/[FromTransferable] implementations generated by this macro use [wrapper::Context].
19/// Generated [Transferable] implementation is similar to the one used in [Wrapper] -
20/// similar, but not exact - [Wrapper] isn't being used, instead a special type-specific wrapper is generated
21/// for every type decorated with this derive macro.
22///
23/// See `transferable` example in `examples` directory for example use.
24pub use dnet_macros::IntoTransferable;
25
26pub mod transferable;
27pub use transferable::{
28    FromTransferable, IntoTransferable, Transferable, TransferableTransport, WithTransferable,
29};
30
31use std::{
32    pin::Pin,
33    rc::Rc,
34    task::{self, Poll},
35};
36
37use dnet_base::{Decode, Encode};
38use dnet_utils::unwrap::Unwrap;
39use futures::{stream::FusedStream, Sink, SinkExt, Stream, StreamExt};
40use pin_project::pin_project;
41
42pub mod wrapper;
43use wrapper::Context;
44pub use wrapper::Wrapper;
45
46use serde::Serialize;
47
48use js_sys::Array;
49use wasm_bindgen::{JsCast, JsValue};
50use web_sys::{DedicatedWorkerGlobalScope, EventTarget, MessagePort, Worker};
51
52type WrapperError<Codec> = wrapper::Error<<Codec as Encode>::Error, <Codec as Decode>::Error>;
53
54/// [Transport] error.
55pub type Error<Codec> = transferable::Error<WrapperError<Codec>>;
56
57/// A trait implemented by underlying transports that can be wrapped with [Transport]
58/// or [TransferableTransport].
59pub trait PostMessage {
60    /// Post message.
61    fn post_message(&self, message: &JsValue) -> Result<(), JsValue>;
62
63    /// Post message with transfer.
64    fn post_message_with_transfer(
65        &self,
66        message: &JsValue,
67        transfer: &Array,
68    ) -> Result<(), JsValue>;
69}
70
71impl PostMessage for MessagePort {
72    fn post_message(&self, message: &JsValue) -> Result<(), JsValue> {
73        self.post_message(message)
74    }
75
76    fn post_message_with_transfer(
77        &self,
78        message: &JsValue,
79        transfer: &Array,
80    ) -> Result<(), JsValue> {
81        self.post_message_with_transferable(message, transfer)
82    }
83}
84
85impl PostMessage for Worker {
86    fn post_message(&self, message: &JsValue) -> Result<(), JsValue> {
87        self.post_message(message)
88    }
89
90    fn post_message_with_transfer(
91        &self,
92        message: &JsValue,
93        transfer: &Array,
94    ) -> Result<(), JsValue> {
95        self.post_message_with_transfer(message, transfer)
96    }
97}
98
99impl PostMessage for DedicatedWorkerGlobalScope {
100    fn post_message(&self, message: &JsValue) -> Result<(), JsValue> {
101        self.post_message(message)
102    }
103
104    fn post_message_with_transfer(
105        &self,
106        message: &JsValue,
107        transfer: &Array,
108    ) -> Result<(), JsValue> {
109        self.post_message_with_transfer(message, transfer)
110    }
111}
112
113/// Transport of data over underlying transports implementing [PostMessage].
114///
115/// It wraps message with [Wrapper] an uses [TransferableTransport] internally to
116/// transport them.
117#[pin_project]
118pub struct Transport<T, Codec, Incoming, Outgoing>
119where
120    T: JsCast + AsRef<EventTarget> + PostMessage,
121    Codec: dnet_base::Codec,
122    <Codec as Encode>::Error: 'static,
123    <Codec as Decode>::Error: 'static,
124    Incoming: Serialize,
125    Outgoing: Serialize,
126    for<'de> Incoming: serde::de::Deserialize<'de>,
127    for<'de> Outgoing: serde::de::Deserialize<'de>,
128{
129    #[allow(clippy::type_complexity)]
130    #[pin]
131    inner: TransferableTransport<
132        T,
133        Context<Codec>,
134        Wrapper<Codec, Incoming>,
135        Wrapper<Codec, Outgoing>,
136        WrapperError<Codec>,
137    >,
138
139    #[cfg(feature = "logging")]
140    logger: dnet_base::Logger,
141}
142
143impl<T, Codec, Incoming, Outgoing> Transport<T, Codec, Incoming, Outgoing>
144where
145    T: JsCast + AsRef<EventTarget> + PostMessage,
146    Codec: dnet_base::Codec,
147    <Codec as Encode>::Error: 'static,
148    <Codec as Decode>::Error: 'static,
149    Incoming: Serialize,
150    Outgoing: Serialize,
151    for<'de> Incoming: serde::de::Deserialize<'de>,
152    for<'de> Outgoing: serde::de::Deserialize<'de>,
153{
154    /// Create new [Transport] wrapping provided target implementing [PostMessage].
155    pub async fn new(
156        target: &Rc<T>,
157        name: Option<String>,
158        codec: Codec,
159        wait_for_open: bool,
160    ) -> Result<Self, Error<Codec>> {
161        #[cfg(feature = "logging")]
162        let logger = if let Some(name) = name.as_ref() {
163            dnet_base::Logger::new_for_already_named::<Self>(&name)
164        } else {
165            dnet_base::Logger::new::<Self>()
166        };
167
168        let mut inner =
169            TransferableTransport::new(target, name, Context::new(codec), false).await?;
170
171        #[cfg(feature = "logging")]
172        inner.with_logger_mut(|logger| logger.override_kind::<Self>());
173
174        if wait_for_open {
175            inner.wait_for_open().await;
176        }
177
178        Ok(Transport {
179            inner,
180
181            #[cfg(feature = "logging")]
182            logger,
183        })
184    }
185
186    /// Name of the transport.
187    pub fn name(&self) -> Option<&str> {
188        self.inner.name()
189    }
190
191    /// Wait for transport open.
192    pub async fn wait_for_open(&mut self) {
193        self.inner.wait_for_open().await;
194    }
195}
196
197impl<T, Codec, Incoming, Outgoing> Sink<Outgoing> for Transport<T, Codec, Incoming, Outgoing>
198where
199    T: JsCast + AsRef<EventTarget> + PostMessage,
200    Codec: dnet_base::Codec,
201    <Codec as Encode>::Error: 'static,
202    <Codec as Decode>::Error: 'static,
203    Incoming: Serialize,
204    Outgoing: Serialize,
205    for<'de> Incoming: serde::de::Deserialize<'de>,
206    for<'de> Outgoing: serde::de::Deserialize<'de>,
207{
208    type Error = dnet_base::Error<Error<Codec>>;
209
210    fn poll_ready(
211        self: Pin<&mut Self>,
212        cx: &mut task::Context<'_>,
213    ) -> Poll<Result<(), Self::Error>> {
214        let mut me = self.project();
215        let result = me.inner.poll_ready_unpin(cx);
216
217        #[cfg(feature = "logging")]
218        me.logger.log_ready(&result);
219
220        result
221    }
222
223    fn start_send(self: Pin<&mut Self>, item: Outgoing) -> Result<(), Self::Error> {
224        let mut me = self.project();
225        let result = me.inner.start_send_unpin(Wrapper::new(item));
226
227        #[cfg(feature = "logging")]
228        me.logger.log_sending::<Outgoing, _>(&result, None);
229
230        result
231    }
232
233    fn poll_flush(
234        self: Pin<&mut Self>,
235        cx: &mut task::Context<'_>,
236    ) -> Poll<Result<(), Self::Error>> {
237        let mut me = self.project();
238        let result = me.inner.poll_flush_unpin(cx);
239
240        #[cfg(feature = "logging")]
241        me.logger.log_flush(&result);
242
243        result
244    }
245
246    fn poll_close(
247        self: Pin<&mut Self>,
248        cx: &mut task::Context<'_>,
249    ) -> Poll<Result<(), Self::Error>> {
250        let mut me = self.project();
251        let result = me.inner.poll_close_unpin(cx);
252
253        #[cfg(feature = "logging")]
254        me.logger.log_close(&result);
255
256        result
257    }
258}
259
260impl<T, Codec, Incoming, Outgoing> Stream for Transport<T, Codec, Incoming, Outgoing>
261where
262    T: JsCast + AsRef<EventTarget> + PostMessage,
263    Codec: dnet_base::Codec,
264    <Codec as Encode>::Error: 'static,
265    <Codec as Decode>::Error: 'static,
266    Incoming: Serialize,
267    Outgoing: Serialize,
268    for<'de> Incoming: serde::de::Deserialize<'de>,
269    for<'de> Outgoing: serde::de::Deserialize<'de>,
270{
271    type Item = Result<Incoming, Error<Codec>>;
272
273    fn poll_next(self: Pin<&mut Self>, cx: &mut task::Context<'_>) -> Poll<Option<Self::Item>> {
274        let mut me = self.project();
275        let result = me.inner.poll_next_unpin(cx).map_ok(Wrapper::unwrap);
276
277        #[cfg(feature = "logging")]
278        me.logger.log_receiving(&result, None);
279
280        result
281    }
282}
283
284impl<T, Codec, Incoming, Outgoing> FusedStream for Transport<T, Codec, Incoming, Outgoing>
285where
286    T: JsCast + AsRef<EventTarget> + PostMessage,
287    Codec: dnet_base::Codec,
288    <Codec as Encode>::Error: 'static,
289    <Codec as Decode>::Error: 'static,
290    Incoming: Serialize,
291    Outgoing: Serialize,
292    for<'de> Incoming: serde::de::Deserialize<'de>,
293    for<'de> Outgoing: serde::de::Deserialize<'de>,
294{
295    fn is_terminated(&self) -> bool {
296        self.inner.is_terminated()
297    }
298}
299
300#[cfg(feature = "logging")]
301impl<T, Codec, Incoming, Outgoing> dnet_base::Logging for Transport<T, Codec, Incoming, Outgoing>
302where
303    T: JsCast + AsRef<EventTarget> + PostMessage,
304    Codec: dnet_base::Codec,
305    <Codec as Encode>::Error: 'static,
306    <Codec as Decode>::Error: 'static,
307    Incoming: Serialize,
308    Outgoing: Serialize,
309    for<'de> Incoming: serde::de::Deserialize<'de>,
310    for<'de> Outgoing: serde::de::Deserialize<'de>,
311{
312    const KIND: &'static str = "JS";
313
314    fn with_logger<F, R>(&self, f: F) -> R
315    where
316        F: FnOnce(&dnet_base::Logger) -> R,
317    {
318        f(&self.logger)
319    }
320
321    fn with_logger_mut<F, R>(&mut self, f: F) -> R
322    where
323        F: FnOnce(&mut dnet_base::Logger) -> R,
324    {
325        f(&mut self.logger)
326    }
327}