dnet-js 0.1.2

JavaScript transport base for dnet
Documentation
#![cfg(target_arch = "wasm32")]
#![warn(missing_docs)]

//! Common features used by WebSocket (WASM), WebWorker and MessagePort transports.

pub mod state;

#[cfg(feature = "logging")]
use dnet_base::Logging;
/// Derive macro  that can be used to automatically implement
/// [IntoTransferable]/[FromTransferable] traits.
///
/// - fields of [transferable objects](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects)
///   need to be marked with `#[transferable]` attribute.
/// - fields holding types implementing [IntoTransferable]/[FromTransferable] need to be marked `#[into_transferable]` attribute,
/// - other fields need to be serializable (with [serde]).
///
/// [IntoTransferable]/[FromTransferable] implementations generated by this macro use [wrapper::Context].
/// Generated [Transferable] implementation is similar to the one used in [Wrapper] -
/// similar, but not exact - [Wrapper] isn't being used, instead a special type-specific wrapper is generated
/// for every type decorated with this derive macro.
///
/// See `transferable` example in `examples` directory for example use.
pub use dnet_macros::IntoTransferable;

pub mod transferable;
pub use transferable::{
    FromTransferable, IntoTransferable, Transferable, TransferableTransport, WithTransferable,
};

use std::{
    pin::Pin,
    rc::Rc,
    task::{self, Poll},
};

use dnet_base::{Decode, Encode};
use dnet_utils::unwrap::Unwrap;
use futures::{stream::FusedStream, Sink, SinkExt, Stream, StreamExt};
use pin_project::pin_project;

pub mod wrapper;
use wrapper::Context;
pub use wrapper::Wrapper;

use serde::Serialize;

use js_sys::Array;
use wasm_bindgen::{JsCast, JsValue};
use web_sys::{DedicatedWorkerGlobalScope, EventTarget, MessagePort, Worker};

type WrapperError<Codec> = wrapper::Error<<Codec as Encode>::Error, <Codec as Decode>::Error>;

/// [Transport] error.
pub type Error<Codec> = transferable::Error<WrapperError<Codec>>;

/// A trait implemented by underlying transports that can be wrapped with [Transport]
/// or [TransferableTransport].
pub trait PostMessage {
    /// Post message.
    fn post_message(&self, message: &JsValue) -> Result<(), JsValue>;

    /// Post message with transfer.
    fn post_message_with_transfer(
        &self,
        message: &JsValue,
        transfer: &Array,
    ) -> Result<(), JsValue>;
}

impl PostMessage for MessagePort {
    fn post_message(&self, message: &JsValue) -> Result<(), JsValue> {
        self.post_message(message)
    }

    fn post_message_with_transfer(
        &self,
        message: &JsValue,
        transfer: &Array,
    ) -> Result<(), JsValue> {
        self.post_message_with_transferable(message, transfer)
    }
}

impl PostMessage for Worker {
    fn post_message(&self, message: &JsValue) -> Result<(), JsValue> {
        self.post_message(message)
    }

    fn post_message_with_transfer(
        &self,
        message: &JsValue,
        transfer: &Array,
    ) -> Result<(), JsValue> {
        self.post_message_with_transfer(message, transfer)
    }
}

impl PostMessage for DedicatedWorkerGlobalScope {
    fn post_message(&self, message: &JsValue) -> Result<(), JsValue> {
        self.post_message(message)
    }

    fn post_message_with_transfer(
        &self,
        message: &JsValue,
        transfer: &Array,
    ) -> Result<(), JsValue> {
        self.post_message_with_transfer(message, transfer)
    }
}

/// Transport of data over underlying transports implementing [PostMessage].
///
/// It wraps message with [Wrapper] an uses [TransferableTransport] internally to
/// transport them.
#[pin_project]
pub struct Transport<T, Codec, Incoming, Outgoing>
where
    T: JsCast + AsRef<EventTarget> + PostMessage,
    Codec: dnet_base::Codec,
    <Codec as Encode>::Error: 'static,
    <Codec as Decode>::Error: 'static,
    Incoming: Serialize,
    Outgoing: Serialize,
    for<'de> Incoming: serde::de::Deserialize<'de>,
    for<'de> Outgoing: serde::de::Deserialize<'de>,
{
    #[allow(clippy::type_complexity)]
    #[pin]
    inner: TransferableTransport<
        T,
        Context<Codec>,
        Wrapper<Codec, Incoming>,
        Wrapper<Codec, Outgoing>,
        WrapperError<Codec>,
    >,

    #[cfg(feature = "logging")]
    logger: dnet_base::Logger,
}

impl<T, Codec, Incoming, Outgoing> Transport<T, Codec, Incoming, Outgoing>
where
    T: JsCast + AsRef<EventTarget> + PostMessage,
    Codec: dnet_base::Codec,
    <Codec as Encode>::Error: 'static,
    <Codec as Decode>::Error: 'static,
    Incoming: Serialize,
    Outgoing: Serialize,
    for<'de> Incoming: serde::de::Deserialize<'de>,
    for<'de> Outgoing: serde::de::Deserialize<'de>,
{
    /// Create new [Transport] wrapping provided target implementing [PostMessage].
    pub async fn new(
        target: &Rc<T>,
        name: Option<String>,
        codec: Codec,
        wait_for_open: bool,
    ) -> Result<Self, Error<Codec>> {
        #[cfg(feature = "logging")]
        let logger = if let Some(name) = name.as_ref() {
            dnet_base::Logger::new_for_already_named::<Self>(&name)
        } else {
            dnet_base::Logger::new::<Self>()
        };

        let mut inner =
            TransferableTransport::new(target, name, Context::new(codec), false).await?;

        #[cfg(feature = "logging")]
        inner.with_logger_mut(|logger| logger.override_kind::<Self>());

        if wait_for_open {
            inner.wait_for_open().await;
        }

        Ok(Transport {
            inner,

            #[cfg(feature = "logging")]
            logger,
        })
    }

    /// Name of the transport.
    pub fn name(&self) -> Option<&str> {
        self.inner.name()
    }

    /// Wait for transport open.
    pub async fn wait_for_open(&mut self) {
        self.inner.wait_for_open().await;
    }
}

impl<T, Codec, Incoming, Outgoing> Sink<Outgoing> for Transport<T, Codec, Incoming, Outgoing>
where
    T: JsCast + AsRef<EventTarget> + PostMessage,
    Codec: dnet_base::Codec,
    <Codec as Encode>::Error: 'static,
    <Codec as Decode>::Error: 'static,
    Incoming: Serialize,
    Outgoing: Serialize,
    for<'de> Incoming: serde::de::Deserialize<'de>,
    for<'de> Outgoing: serde::de::Deserialize<'de>,
{
    type Error = dnet_base::Error<Error<Codec>>;

    fn poll_ready(
        self: Pin<&mut Self>,
        cx: &mut task::Context<'_>,
    ) -> Poll<Result<(), Self::Error>> {
        let mut me = self.project();
        let result = me.inner.poll_ready_unpin(cx);

        #[cfg(feature = "logging")]
        me.logger.log_ready(&result);

        result
    }

    fn start_send(self: Pin<&mut Self>, item: Outgoing) -> Result<(), Self::Error> {
        let mut me = self.project();
        let result = me.inner.start_send_unpin(Wrapper::new(item));

        #[cfg(feature = "logging")]
        me.logger.log_sending::<Outgoing, _>(&result, None);

        result
    }

    fn poll_flush(
        self: Pin<&mut Self>,
        cx: &mut task::Context<'_>,
    ) -> Poll<Result<(), Self::Error>> {
        let mut me = self.project();
        let result = me.inner.poll_flush_unpin(cx);

        #[cfg(feature = "logging")]
        me.logger.log_flush(&result);

        result
    }

    fn poll_close(
        self: Pin<&mut Self>,
        cx: &mut task::Context<'_>,
    ) -> Poll<Result<(), Self::Error>> {
        let mut me = self.project();
        let result = me.inner.poll_close_unpin(cx);

        #[cfg(feature = "logging")]
        me.logger.log_close(&result);

        result
    }
}

impl<T, Codec, Incoming, Outgoing> Stream for Transport<T, Codec, Incoming, Outgoing>
where
    T: JsCast + AsRef<EventTarget> + PostMessage,
    Codec: dnet_base::Codec,
    <Codec as Encode>::Error: 'static,
    <Codec as Decode>::Error: 'static,
    Incoming: Serialize,
    Outgoing: Serialize,
    for<'de> Incoming: serde::de::Deserialize<'de>,
    for<'de> Outgoing: serde::de::Deserialize<'de>,
{
    type Item = Result<Incoming, Error<Codec>>;

    fn poll_next(self: Pin<&mut Self>, cx: &mut task::Context<'_>) -> Poll<Option<Self::Item>> {
        let mut me = self.project();
        let result = me.inner.poll_next_unpin(cx).map_ok(Wrapper::unwrap);

        #[cfg(feature = "logging")]
        me.logger.log_receiving(&result, None);

        result
    }
}

impl<T, Codec, Incoming, Outgoing> FusedStream for Transport<T, Codec, Incoming, Outgoing>
where
    T: JsCast + AsRef<EventTarget> + PostMessage,
    Codec: dnet_base::Codec,
    <Codec as Encode>::Error: 'static,
    <Codec as Decode>::Error: 'static,
    Incoming: Serialize,
    Outgoing: Serialize,
    for<'de> Incoming: serde::de::Deserialize<'de>,
    for<'de> Outgoing: serde::de::Deserialize<'de>,
{
    fn is_terminated(&self) -> bool {
        self.inner.is_terminated()
    }
}

#[cfg(feature = "logging")]
impl<T, Codec, Incoming, Outgoing> dnet_base::Logging for Transport<T, Codec, Incoming, Outgoing>
where
    T: JsCast + AsRef<EventTarget> + PostMessage,
    Codec: dnet_base::Codec,
    <Codec as Encode>::Error: 'static,
    <Codec as Decode>::Error: 'static,
    Incoming: Serialize,
    Outgoing: Serialize,
    for<'de> Incoming: serde::de::Deserialize<'de>,
    for<'de> Outgoing: serde::de::Deserialize<'de>,
{
    const KIND: &'static str = "JS";

    fn with_logger<F, R>(&self, f: F) -> R
    where
        F: FnOnce(&dnet_base::Logger) -> R,
    {
        f(&self.logger)
    }

    fn with_logger_mut<F, R>(&mut self, f: F) -> R
    where
        F: FnOnce(&mut dnet_base::Logger) -> R,
    {
        f(&mut self.logger)
    }
}