@temporalio/core-bridge 1.11.8 → 1.12.0

package/src/helpers/abort_controller.rs

@@ -0,0 +1,204 @@
+use std::sync::{
+    Arc, OnceLock,
+    atomic::{AtomicU8, Ordering, fence},
+};
+
+use neon::{
+    handle::{Handle, Root},
+    object::Object,
+    prelude::{Context, JsResult},
+    types::{JsFunction, JsObject, JsValue},
+};
+
+use super::{BridgeResult, JsCallback, TryIntoJs, errors::IntoThrow as _};
+
+pub type JsAbortController = JsObject;
+pub type JsAbortSignal = JsValue;
+
+/// An object that models a JavaScript `AbortController`, and its corresponding `AbortSignal`,
+/// allowing the Rust side to fire that signal if/when needed, e.g. when dropped from the Rust side.
+///
+/// The JS counterpart object is lazily instantiated when the signal gets converted to JS (through
+/// the `TryIntoJs` trait); this ensures that the Rust side can be created without a JS `Context`.
+pub struct AbortController {
+    inner: Arc<AbortControllerInner>,
+    drop_abort_reason: String,
+}
+
+/// An object that models the signal of a JavaScript `AbortController`.
+pub struct AbortSignal {
+    inner: Arc<AbortControllerInner>,
+}
+
+/// The inner state of an `AbortController`, shared between the Rust and JS sides.
+struct AbortControllerInner {
+    // The fact that we require a `Context` to initialize the JS counterpart means that we are running
+    // on the Node's thread, which guarantees that there can't be multiple threads calling into that
+    // function concurrently; that should in theory aleviate the need to use a lock on `js_counterpart`.
+    //
+    // It is however possible for the rust-side controller to get aborted from a non-Node thread
+    // while the JS-side controller is being created on the Node thread, in which case we don't
+    // want the Rust-side thread to get blocked for the JS-side to complete instantiation.
+    //
+    // By modelling the "JS initialization" and "is aborted" states as two distinct independant
+    // structures, we ensure that we're never blocking execution of either thread. This however
+    // means that either step may happen before the other, so we need to be careful not to miss
+    // sending the abort signal. The good news is that nothing bad will happen if we call the JS
+    // abort callback multiple times.
+    js_counterpart: OnceLock<AbortControllerJsCounterpart>,
+    aborted: OnceLock<String>,
+
+    state: AtomicU8,
+}
+
+struct AbortControllerJsCounterpart {
+    controller: Root<JsObject>,
+    abort: JsCallback<(String,), ()>,
+}
+
+const STATE_UNINITIALIZED: u8 = 0;
+const STATE_ARMED: u8 = 1 << 0;
+const STATE_ABORTED: u8 = 1 << 1;
+const STATE_DISARMED: u8 = STATE_ARMED | STATE_ABORTED;
+
+impl AbortController {
+    /// Create a new `AbortController`.
+    ///
+    /// The `drop_abort_reason` string will be used as the reason for the abort
+    /// if the controller is dropped from the Rust side.
+    #[must_use]
+    pub fn new(drop_abort_reason: String) -> Self {
+        let inner = AbortControllerInner {
+            js_counterpart: OnceLock::new(),
+            aborted: OnceLock::new(),
+            state: AtomicU8::new(STATE_UNINITIALIZED),
+        };
+        let inner = Arc::new(inner);
+        Self {
+            inner,
+            drop_abort_reason,
+        }
+    }
+
+    /// Get an associated `AbortSignal` object for this controller. This method can
+    /// be called at any time (i.e. even after the controller has been cancelled),
+    /// any number of times (i.e. to pass a same signal to multiple JS functions),
+    /// and from any thread.
+    #[must_use]
+    pub fn get_signal(&self) -> AbortSignal {
+        AbortSignal {
+            inner: self.inner.clone(),
+        }
+    }
+
+    /// Abort the controller, causing the JS side `signal` to fire.
+    ///
+    /// This method can be called at any time (i.e. even before the controller has been armed,
+    /// or after it has been disarmed), and from any thread.
+    pub fn abort(&self, reason: impl Into<String>) {
+        self.inner.abort(reason);
+    }
+
+    /// Disarm the controller, so that it can no longer be aborted.
+    ///
+    /// Once a controller has been disarmed, it's abort status will not change anymore. It is
+    /// recommended to call this method once it is known that the signal is no longer needed
+    /// on the JS side, e.g. when the called JS function has returned, as this will prevent the
+    /// overhead of implicit abortion when the controller is dropped.
+    pub fn disarm(&self) {
+        self.inner.disarm();
+    }
+}
+
+impl Drop for AbortController {
+    fn drop(&mut self) {
+        self.abort(self.drop_abort_reason.clone());
+    }
+}
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+impl TryIntoJs for AbortSignal {
+    type Output = JsAbortSignal;
+    fn try_into_js<'cx>(self, cx: &mut impl Context<'cx>) -> JsResult<'cx, JsAbortSignal> {
+        let controller = self.inner.get_or_init_controller(cx).into_throw(cx)?;
+        controller.get(cx, "signal")
+    }
+}
+
+impl AbortControllerInner {
+    /// Create the JS `AbortController` if it hasn't been created yet.
+    /// Returns a reference to the signal object that can be passed to JS.
+    fn get_or_init_controller<'cx, C: Context<'cx>>(
+        &self,
+        cx: &mut C,
+    ) -> BridgeResult<Handle<'cx, JsAbortController>> {
+        if let Some(js_counterpart) = self.js_counterpart.get() {
+            // Already initialized, return the controller
+            return Ok(js_counterpart.controller.to_inner(cx).upcast());
+        }
+
+        // Not initialized yet, create the JS AbortController
+        let global = cx.global_object();
+        let abort_controller_class = global.get::<JsFunction, _, _>(cx, "AbortController")?;
+        let js_controller = abort_controller_class.construct(cx, [])?;
+
+        let abort_fn = js_controller.get::<JsFunction, _, _>(cx, "abort")?;
+        let abort_cb = JsCallback::new(cx, abort_fn, Some(js_controller));
+
+        let js_counterpart = AbortControllerJsCounterpart {
+            controller: js_controller.root(cx),
+            abort: abort_cb,
+        };
+
+        let controller = match self.js_counterpart.set(js_counterpart) {
+            Ok(()) => {
+                // Ordering: Write to `state` implies previous write to `js_counterpart` is visible to other threads
+                if self.state.fetch_or(STATE_ARMED, Ordering::Release) == STATE_ABORTED {
+                    // Ordering: Previous concurrent write to `aborted` must be visible at this point
+                    fence(Ordering::Acquire);
+
+                    // The controller was aborted before it was armed; immediately call the abort callback
+
+                    // Fire and forget
+                    let _ = self
+                        .js_counterpart
+                        .get()
+                        .unwrap()
+                        .abort
+                        .call(cx, (self.aborted.get().unwrap().clone(),));
+                }
+                js_controller
+            }
+            Err(js_counterpart) => js_counterpart.controller.to_inner(cx).upcast(),
+        };
+
+        Ok(controller)
+    }
+
+    /// Immediately abort the `AbortController`, causing the JS side `signal` to fire.
+    fn abort(&self, reason: impl Into<String>) {
+        let reason = reason.into();
+        if self.aborted.set(reason.clone()) == Ok(()) {
+            // If we haven't created the JS AbortController yet, there's nothing to abort
+            // Ordering: Write to `state` implies previous write to `aborted` is visible to other threads
+            if self.state.fetch_or(STATE_ABORTED, Ordering::Release) == STATE_ARMED {
+                // Ordering: Previous concurrent write to `js_counterpart` must be visible at this point
+                fence(Ordering::Acquire);
+
+                // Fire and forget
+                let _ = self
+                    .js_counterpart
+                    .get()
+                    .unwrap()
+                    .abort
+                    .call_on_js_thread((reason,));
+            }
+        }
+    }
+
+    fn disarm(&self) {
+        // Ordering: this requires no dependency on any other state
+        self.state.store(STATE_DISARMED, Ordering::Relaxed);
+    }
+}

package/src/helpers/callbacks.rs

@@ -0,0 +1,299 @@
+use std::{marker::PhantomData, sync::Arc};
+
+use neon::{
+    event::Channel,
+    handle::{Handle, Root},
+    object::Object,
+    prelude::Context,
+    types::{JsFunction, JsFuture, JsObject, JsPromise, JsValue, Value as _},
+};
+use tracing::error;
+
+use super::{BridgeError, BridgeResult, TryFromJs, TryIntoJs, errors::IntoThrow as _};
+
+/// A callback is a JS function that is meant to be called by the Rust side.
+/// A `JsCallback` is a callback that returns a value synchronously.
+#[derive(Debug)]
+pub struct JsCallback<Args, Ret>
+where
+    Args: TryIntoJsArgs + Send + Sync,
+    Ret: TryFromJs + Send + Sync,
+{
+    inner: Arc<CallbackInner<Args, Ret>>,
+}
+
+impl<Args, Ret> Clone for JsCallback<Args, Ret>
+where
+    Args: TryIntoJsArgs + Send + Sync,
+    Ret: TryFromJs + Send + Sync,
+{
+    fn clone(&self) -> Self {
+        Self {
+            inner: self.inner.clone(),
+        }
+    }
+}
+
+impl<Args, Ret> JsCallback<Args, Ret>
+where
+    Args: TryIntoJsArgs + Send + Sync + 'static,
+    Ret: TryFromJs + Send + Sync + 'static,
+{
+    pub fn new<'cx, C: Context<'cx>>(
+        cx: &mut C,
+        func: Handle<JsFunction>,
+        this: Option<Handle<JsObject>>,
+    ) -> Self {
+        Self {
+            inner: Arc::new(CallbackInner {
+                this: this.map(|t| t.root(cx)),
+                func: func.root(cx),
+                func_name: func
+                    .to_string(cx)
+                    .map_or_else(|_| "anonymous func".to_owned(), |s| s.value(cx)),
+                chan: cx.channel(),
+                _marker: PhantomData,
+            }),
+        }
+    }
+
+    /// Synchronously call the callback from the current JS thread.
+    pub fn call<'cx, C: Context<'cx>>(&self, cx: &mut C, args: Args) -> BridgeResult<Ret> {
+        let inner = self.inner.clone();
+        inner.call(cx, args)
+    }
+
+    /// Call the callback on the JS thread and return a handle to the result.
+    pub fn call_on_js_thread(&self, args: Args) -> BridgeResult<neon::event::JoinHandle<Ret>> {
+        let inner = self.inner.clone();
+
+        let ret = inner
+            .chan
+            .clone()
+            .try_send(move |mut cx| inner.call(&mut cx, args).into_throw(&mut cx))
+            .map_err(|e| BridgeError::Other(e.into()))?;
+
+        Ok(ret)
+    }
+
+    pub fn call_and_block(&self, args: Args) -> BridgeResult<Ret> {
+        let join_handle = self.call_on_js_thread(args)?;
+
+        // This is... unfortunate but since this method is called from an async context way up
+        // the stack, but is not async itself AND we need some way to get the result from the JS
+        // callback, we must use this roundabout way of blocking. Simply calling `join` on the
+        // channel send won't work - it'll panic because it calls block_on internally.
+        let callback_res = futures::executor::block_on(join_handle);
+
+        match callback_res {
+            Ok(x) => Ok(x),
+            Err(e) => Err(BridgeError::Other(e.into())),
+        }
+    }
+}
+
+/// Unfortunately, the `TryFromJS` trait doesn't have access to the containing object, and therefore
+/// can't preserve the `this` context. If the JS side API presents the callback as a method on some
+/// object, then the function should be `bind(this)`'d on the JS side before passing it to Rust.
+impl<Args, Ret> TryFromJs for JsCallback<Args, Ret>
+where
+    Args: TryIntoJsArgs + Send + Sync + 'static,
+    Ret: TryFromJs + Send + Sync + 'static,
+{
+    fn try_from_js<'cx, 'b>(
+        cx: &mut impl Context<'cx>,
+        js_value: Handle<'b, JsValue>,
+    ) -> BridgeResult<Self> {
+        let func = js_value.downcast::<JsFunction, _>(cx)?;
+        Ok(Self::new(cx, func, None))
+    }
+}
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+pub struct JsAsyncCallback<Args, Ret>
+where
+    Args: TryIntoJsArgs + Send + Sync,
+    Ret: TryFromJs + Send + Sync + 'static,
+{
+    inner: Arc<CallbackInner<Args, JsFuture<BridgeResult<Ret>>>>,
+}
+
+impl<Args, Ret> JsAsyncCallback<Args, Ret>
+where
+    Args: TryIntoJsArgs + Send + Sync + 'static,
+    Ret: TryFromJs + Send + Sync + 'static,
+{
+    pub fn new<'cx, C: Context<'cx>>(
+        cx: &mut C,
+        func: Handle<JsFunction>,
+        this: Option<Handle<JsObject>>,
+    ) -> Self {
+        Self {
+            inner: Arc::new(CallbackInner {
+                this: this.map(|t| t.root(cx)),
+                func: func.root(cx),
+                func_name: func
+                    .to_string(cx)
+                    .map_or_else(|_| "anonymous func".to_owned(), |s| s.value(cx)),
+                chan: cx.channel(),
+                _marker: PhantomData,
+            }),
+        }
+    }
+
+    pub async fn call(&self, args: Args) -> BridgeResult<Ret> {
+        let inner = self.inner.clone();
+
+        let join_handle = inner
+            .chan
+            .clone()
+            .try_send(move |mut cx| inner.call(&mut cx, args).into_throw(&mut cx))
+            .map_err(|e| BridgeError::Other(e.into()))?;
+
+        // Wait for the JS function to return a Promise...
+        let res = join_handle.await;
+        let future = res.map_err(|e| BridgeError::Other(e.into()))?;
+
+        // ... and then wait for the Promise to resolve
+        let res = future.await;
+        let res = res.map_err(|e| BridgeError::Other(e.into()))??;
+        Ok(res)
+    }
+}
+
+/// Unfortunately, the `TryFromJS` trait doesn't have access to the containing object, and therefore
+/// can't preserve the `this` context. If the JS side API presents the callback as a method on some
+/// object, then the function should be `bind(this)`'d on the JS side before passing it to Rust.
+impl<Args, Ret> TryFromJs for JsAsyncCallback<Args, Ret>
+where
+    Args: TryIntoJsArgs + Send + Sync + 'static,
+    Ret: TryFromJs + Send + Sync + 'static,
+{
+    fn try_from_js<'cx, 'b>(
+        cx: &mut impl Context<'cx>,
+        js_value: Handle<'b, JsValue>,
+    ) -> BridgeResult<Self> {
+        let func = js_value.downcast::<JsFunction, _>(cx)?;
+        Ok(Self::new(cx, func, None))
+    }
+}
+
+impl<R: TryFromJs + Send + Sync + 'static> TryFromJs for JsFuture<BridgeResult<R>> {
+    fn try_from_js<'cx, 'b>(
+        cx: &mut impl Context<'cx>,
+        js_value: Handle<'b, JsValue>,
+    ) -> BridgeResult<Self> {
+        let promise = js_value.downcast::<JsPromise, _>(cx)?;
+        let future = promise.to_future(cx, |mut cx, result| match result {
+            Ok(value) => {
+                // Promise resolved, but there might still be an error trying to
+                // convert the promise's returned value to the desired type.
+                let val = R::try_from_js(&mut cx, value);
+                match val {
+                    Ok(val) => Ok(Ok(val)),
+                    Err(e) => Ok(Err(e)),
+                }
+            }
+            Err(e) => {
+                // Promise failed to resolve
+                let err_str = e.to_string(&mut cx)?.value(&mut cx);
+                Ok(Err(BridgeError::UnexpectedError(err_str)))
+            }
+        })?;
+
+        Ok(future)
+    }
+}
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+#[derive(Debug)]
+struct CallbackInner<Args, Ret>
+where
+    Args: TryIntoJsArgs + Send + Sync,
+    Ret: TryFromJs + Send + Sync,
+{
+    this: Option<Root<JsObject>>,
+    func: Root<JsFunction>,
+    func_name: String,
+    chan: Channel,
+    _marker: PhantomData<(Args, Ret)>,
+}
+
+impl<Args: TryIntoJsArgs + Send + Sync, Ret: TryFromJs + Send + Sync> CallbackInner<Args, Ret> {
+    fn call<'a, C: Context<'a>>(&self, cx: &mut C, args: Args) -> BridgeResult<Ret> {
+        let this: Handle<'a, JsValue> = self
+            .this
+            .as_ref()
+            .map_or(cx.undefined().upcast(), |t| t.to_inner(cx).upcast());
+
+        // Convert the arguments to a JS array using the new trait
+        let js_args = args.try_into_js_args(cx)?;
+
+        // Call the function with the JS arguments directly
+        let ret = cx
+            .try_catch(|cx| self.func.to_inner(cx).call(cx, this, js_args))
+            .map_err(|e| {
+                let err_str = format!(
+                    "Error calling JS callback '{}' on JS thread, {:?}",
+                    self.func_name, e
+                );
+                error!(err_str);
+                BridgeError::UnexpectedError(err_str)
+            })?;
+
+        <Ret>::try_from_js(cx, ret)
+    }
+}
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+/// A trait to build an arguments array for a JS function call from a tuple.
+pub trait TryIntoJsArgs {
+    fn try_into_js_args<'cx, 'a>(
+        self,
+        cx: &mut impl Context<'cx>,
+    ) -> BridgeResult<Vec<Handle<'a, JsValue>>>
+    where
+        'cx: 'a;
+}
+
+impl TryIntoJsArgs for () {
+    fn try_into_js_args<'cx, 'a>(
+        self,
+        _cx: &mut impl Context<'cx>,
+    ) -> BridgeResult<Vec<Handle<'a, JsValue>>>
+    where
+        'cx: 'a,
+    {
+        Ok(Vec::new())
+    }
+}
+
+impl<T0: TryIntoJs> TryIntoJsArgs for (T0,) {
+    fn try_into_js_args<'cx, 'a>(
+        self,
+        cx: &mut impl Context<'cx>,
+    ) -> BridgeResult<Vec<Handle<'a, JsValue>>>
+    where
+        'cx: 'a,
+    {
+        let js_value = self.0.try_into_js(cx)?;
+        Ok(vec![js_value.upcast()])
+    }
+}
+
+impl<T0: TryIntoJs, T1: TryIntoJs> TryIntoJsArgs for (T0, T1) {
+    fn try_into_js_args<'cx, 'a>(
+        self,
+        cx: &mut impl Context<'cx>,
+    ) -> BridgeResult<Vec<Handle<'a, JsValue>>>
+    where
+        'cx: 'a,
+    {
+        let v0 = self.0.try_into_js(cx)?;
+        let v1 = self.1.try_into_js(cx)?;
+        Ok(vec![v0.upcast(), v1.upcast()])
+    }
+}