Skip to main content

sk_app/embed/
module.rs

1//! Native modules: typed functions, tasks and events an embedder gives the app as `native:<name>`.
2//!
3//! Arguments are read from the engine's values straight into serde types and results built
4//! straight into engine values, with the meaning a JSON round trip gives them (`marshal`). A
5//! function runs inside the JS call; a task reads its arguments in the call, runs on a worker
6//! and settles a promise in a later frame.
7
8use std::cell::RefCell;
9use std::collections::{HashMap, VecDeque};
10use std::ffi::c_void;
11use std::sync::atomic::{AtomicU32, AtomicUsize, Ordering};
12use std::sync::{mpsc, Arc, Mutex, OnceLock};
13use std::time::Duration;
14
15use serde::de::DeserializeOwned;
16use serde::Serialize;
17use serde_json::Value as Json;
18use sk_runtime::JsRuntime;
19
20use super::marshal;
21use crate::js::{self, Context, HostArgs, Value};
22
23#[cfg(feature = "types")]
24use specta::{datatype::DataType, Types};
25
26/// What every argument, result and event type implements: `serde` plus, with the `types` feature,
27/// [`specta::Type`] (`#[derive(skathi::Type)]`).
28#[cfg(feature = "types")]
29pub trait Typed: specta::Type {}
30#[cfg(feature = "types")]
31impl<T: specta::Type + ?Sized> Typed for T {}
32#[cfg(not(feature = "types"))]
33pub trait Typed {}
34#[cfg(not(feature = "types"))]
35impl<T: ?Sized> Typed for T {}
36
37/// Why a call failed, as the app sees it.
38#[doc(hidden)]
39#[derive(Debug, Clone, PartialEq)]
40pub struct Failure {
41    message: String,
42    data: Option<String>,
43    kind: u32,
44}
45
46impl Failure {
47    fn new(message: impl Into<String>) -> Self {
48        Self {
49            message: message.into(),
50            data: None,
51            kind: 0,
52        }
53    }
54
55    fn type_error(message: impl Into<String>) -> Self {
56        Self {
57            kind: 1,
58            ..Self::new(message)
59        }
60    }
61
62    /// An `Err` value: a string is the message; anything else rides along as `error.data`.
63    fn from_err(json: String) -> Self {
64        let message = match serde_json::from_str::<Json>(&json) {
65            Ok(Json::String(text)) => return Self::new(text),
66            Ok(Json::Object(fields)) => match fields.get("message") {
67                Some(Json::String(text)) => text.clone(),
68                _ => json.clone(),
69            },
70            _ => json.clone(),
71        };
72        Self {
73            data: Some(json),
74            ..Self::new(message)
75        }
76    }
77}
78
79impl From<Failure> for Fail {
80    fn from(failure: Failure) -> Self {
81        Fail::Failure(failure)
82    }
83}
84
85/// Why a call failed: a JS exception thrown while reading the arguments, or a [`Failure`].
86#[doc(hidden)]
87#[derive(Debug)]
88pub enum Fail {
89    Thrown(Value),
90    Failure(Failure),
91}
92
93/// A task's work, made in the call from its arguments and run on a worker.
94#[doc(hidden)]
95pub type Work = Box<dyn FnOnce() -> Result<marshal::Owned, Failure> + Send + 'static>;
96
97/// A Rust closure the app can call: `Fn(A1, ..., An) -> R` for up to eight arguments, each
98/// `Deserialize`, with `R: Serialize`. An `Err(e)` result throws with `e`.
99pub trait Function<Args>: Send + Sync + 'static {
100    #[doc(hidden)]
101    const ARITY: usize;
102    #[doc(hidden)]
103    fn invoke(&self, context: &Context, args: &HostArgs) -> Result<Value, Fail>;
104    #[cfg(feature = "types")]
105    #[doc(hidden)]
106    fn signature(types: &mut Types) -> (Vec<DataType>, DataType);
107}
108
109/// A [`Function`] run on a worker: its arguments are read in the call, so they are also `Send`.
110/// An `Err(e)` result rejects with `e`.
111pub trait Task<Args>: Send + Sync + 'static {
112    #[doc(hidden)]
113    const ARITY: usize;
114    #[doc(hidden)]
115    fn prepare(self: Arc<Self>, context: &Context, args: &HostArgs) -> Result<Work, Fail>;
116    #[cfg(feature = "types")]
117    #[doc(hidden)]
118    fn signature(types: &mut Types) -> (Vec<DataType>, DataType);
119}
120
121macro_rules! function {
122    ($n:expr; $($A:ident $a:ident $i:expr),*) => {
123        impl<F, R, $($A,)*> Function<($($A,)*)> for F
124        where
125            F: Fn($($A),*) -> R + Send + Sync + 'static,
126            R: Serialize + Typed,
127            $($A: DeserializeOwned + Typed,)*
128        {
129            const ARITY: usize = $n;
130
131            #[allow(unused_variables)]
132            #[inline]
133            fn invoke(&self, context: &Context, args: &HostArgs) -> Result<Value, Fail> {
134                $(let $a = argument::<$A>(context, args, $i)?;)*
135                answer(context, &(self)($($a),*))
136            }
137
138            #[cfg(feature = "types")]
139            #[allow(unused_variables)]
140            fn signature(types: &mut Types) -> (Vec<DataType>, DataType) {
141                (vec![$(types.define::<$A>()),*], types.define::<R>())
142            }
143        }
144
145        impl<F, R, $($A,)*> Task<($($A,)*)> for F
146        where
147            F: Fn($($A),*) -> R + Send + Sync + 'static,
148            R: Serialize + Typed,
149            $($A: DeserializeOwned + Typed + Send + 'static,)*
150        {
151            const ARITY: usize = $n;
152
153            #[allow(unused_variables)]
154            fn prepare(self: Arc<Self>, context: &Context, args: &HostArgs) -> Result<Work, Fail> {
155                $(let $a = argument::<$A>(context, args, $i)?;)*
156                Ok(Box::new(move || answer_owned(&(self)($($a),*))))
157            }
158
159            #[cfg(feature = "types")]
160            #[allow(unused_variables)]
161            fn signature(types: &mut Types) -> (Vec<DataType>, DataType) {
162                (vec![$(types.define::<$A>()),*], types.define::<R>())
163            }
164        }
165    };
166}
167
168function!(0;);
169function!(1; A1 a1 1);
170function!(2; A1 a1 1, A2 a2 2);
171function!(3; A1 a1 1, A2 a2 2, A3 a3 3);
172function!(4; A1 a1 1, A2 a2 2, A3 a3 3, A4 a4 4);
173function!(5; A1 a1 1, A2 a2 2, A3 a3 3, A4 a4 4, A5 a5 5);
174function!(6; A1 a1 1, A2 a2 2, A3 a3 3, A4 a4 4, A5 a5 5, A6 a6 6);
175function!(7; A1 a1 1, A2 a2 2, A3 a3 3, A4 a4 4, A5 a5 5, A6 a6 6, A7 a7 7);
176function!(8; A1 a1 1, A2 a2 2, A3 a3 3, A4 a4 4, A5 a5 5, A6 a6 6, A7 a7 7, A8 a8 8);
177
178#[inline]
179fn argument<A: DeserializeOwned>(
180    context: &Context,
181    args: &HostArgs,
182    position: u32,
183) -> Result<A, Fail> {
184    private::argument(context, args, position, |js| A::deserialize(js))
185}
186
187fn outcome<V>(result: Result<V, marshal::OutError>) -> Result<V, Fail> {
188    result.map_err(private::fail)
189}
190
191#[inline]
192fn answer<R: Serialize + ?Sized>(context: &Context, value: &R) -> Result<Value, Fail> {
193    outcome(marshal::to_js(context, value, true))
194}
195
196/// A task's result, made on its worker.
197fn answer_owned<R: Serialize + ?Sized>(value: &R) -> Result<marshal::Owned, Failure> {
198    worker_outcome(marshal::owned(value, true))
199}
200
201fn worker_outcome(
202    result: Result<marshal::Owned, marshal::OutError>,
203) -> Result<marshal::Owned, Failure> {
204    outcome(result).map_err(|e| match e {
205        Fail::Failure(failure) => failure,
206        Fail::Thrown(_) => Failure::new("the result cannot be serialized"),
207    })
208}
209
210/// What `#[skathi::module]` expands to; not an API.
211pub mod private {
212    pub use super::super::marshal::{
213        answer_compound, encode_bytes, encode_serde, missing, owned_compound, read_struct,
214        unit_variant, Element, Error, Fields, FromJs, IntoJs, Js, Keys, Open, OutError, Owned,
215        Pick, ReadDirect, ReadSerde, Slice, Str, Tree, WriteDirect, WriteSerde,
216    };
217    pub use super::{Fail, Work};
218    pub use crate::js::{Context, HostArgs, Value};
219
220    use super::{marshal, Failure};
221
222    /// Argument `position` (from 1), read by `read`; a wrong one is a TypeError that names it.
223    #[inline]
224    pub fn argument<T>(
225        context: &Context,
226        args: &HostArgs,
227        position: u32,
228        read: impl FnOnce(Js<'_, '_>) -> Result<T, Error>,
229    ) -> Result<T, Fail> {
230        let walk = marshal::Walk::new(context);
231        read(walk.arg(position - 1, args.arg(position - 1))).map_err(|e| match e {
232            Error::Thrown(v) => Fail::Thrown(v),
233            Error::NotJson(m) => Fail::Thrown(context.error(1, &m)),
234            e => Fail::Failure(Failure::type_error(format!("argument {position}: {e}"))),
235        })
236    }
237
238    pub fn fail(e: OutError) -> Fail {
239        match e {
240            OutError::Err(json) => Fail::Failure(Failure::from_err(json)),
241            OutError::Thrown(v) => Fail::Thrown(v),
242            e => Fail::Failure(Failure::new(format!(
243                "the result cannot be serialized: {e}"
244            ))),
245        }
246    }
247
248    /// A task's work: the call on a worker, its result encoded there.
249    pub fn work(run: impl FnOnce() -> Result<Owned, OutError> + Send + 'static) -> Work {
250        Box::new(move || super::worker_outcome(run()))
251    }
252}
253
254/// An event's data, made on the thread that emits it.
255pub(crate) fn event_data<T: Serialize + ?Sized>(data: &T) -> Option<marshal::Owned> {
256    marshal::owned(data, false).ok()
257}
258
259enum Invoke {
260    Function(Box<dyn Fn(&Context, &HostArgs) -> Result<Value, Fail> + Send + Sync>),
261    Task(Box<dyn Fn(&Context, &HostArgs) -> Result<Work, Fail> + Send + Sync>),
262}
263
264pub(crate) struct Entry {
265    pub(crate) name: String,
266    #[cfg(feature = "types")]
267    pub(crate) task: bool,
268    pub(crate) arity: usize,
269    pub(crate) params: Vec<String>,
270    invoke: Invoke,
271    #[cfg(feature = "types")]
272    pub(crate) signature: Signature,
273}
274
275#[cfg(feature = "types")]
276type Signature = fn(&mut Types) -> (Vec<DataType>, DataType);
277#[cfg(not(feature = "types"))]
278type Signature = ();
279
280pub(crate) struct Event {
281    pub(crate) name: String,
282    #[cfg(feature = "types")]
283    pub(crate) ty: fn(&mut Types) -> DataType,
284}
285
286/// What `Builder::module` takes: a type with `#[skathi::module]`, or a closure that fills the
287/// [`Module`] (`|m: &mut Module| …`).
288pub trait IntoModule {
289    fn register(self, module: &mut Module);
290}
291
292impl<F: FnOnce(&mut Module)> IntoModule for F {
293    fn register(self, module: &mut Module) {
294        self(module)
295    }
296}
297
298/// One `native:<name>` module, filled in by `Builder::module`.
299pub struct Module {
300    pub(crate) name: String,
301    pub(crate) functions: Vec<Entry>,
302    pub(crate) events: Vec<Event>,
303    problem: Option<String>,
304}
305
306const RESERVED: &[&str] = &["available", "on", "off", "default", "then", "__esModule"];
307
308/// Cannot be imported by name or declared as a function.
309const KEYWORDS: &str = "await break case catch class const continue debugger delete do else enum \
310    export extends false finally for function if implements import in instanceof interface let new \
311    null package private protected public return static super switch this throw true try typeof var \
312    void while with yield";
313
314fn is_identifier(name: &str) -> bool {
315    let mut chars = name.chars();
316    chars
317        .next()
318        .is_some_and(|c| c.is_ascii_alphabetic() || c == '_' || c == '$')
319        && chars.all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '$')
320}
321
322pub(crate) fn valid_module_name(name: &str) -> bool {
323    !name.is_empty()
324        && name
325            .bytes()
326            .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b'-' | b'.' | b'/'))
327}
328
329#[cfg(feature = "types")]
330fn event_type<T: Typed>(types: &mut Types) -> DataType {
331    types.define::<T>()
332}
333
334impl Module {
335    pub(crate) fn new(name: String) -> Self {
336        let problem = (!valid_module_name(&name)).then(|| {
337            format!("native module name {name:?}: use letters, digits, '_', '-', '.' or '/'")
338        });
339        Self {
340            name,
341            functions: Vec::new(),
342            events: Vec::new(),
343            problem,
344        }
345    }
346
347    pub(crate) fn problem(&self) -> Option<&str> {
348        self.problem.as_deref()
349    }
350
351    fn claim(&mut self, name: &str) -> bool {
352        if self.problem.is_some() {
353            return false;
354        }
355        let taken = self.functions.iter().any(|f| f.name == name);
356        if !is_identifier(name)
357            || RESERVED.contains(&name)
358            || KEYWORDS.split_whitespace().any(|k| k == name)
359            || taken
360        {
361            self.problem = Some(format!(
362                "native:{}: {name:?} is {}",
363                self.name,
364                if taken {
365                    "registered twice"
366                } else {
367                    "not a usable export name: use a JS identifier that is not a keyword, available, on, off, default or then"
368                }
369            ));
370            return false;
371        }
372        true
373    }
374
375    #[cfg_attr(not(feature = "types"), allow(unused_variables))]
376    fn add(
377        &mut self,
378        name: &str,
379        arity: usize,
380        invoke: Invoke,
381        signature: Signature,
382    ) -> Declared<'_> {
383        if !self.claim(name) {
384            return Declared { entry: None };
385        }
386        self.functions.push(Entry {
387            name: name.to_owned(),
388            #[cfg(feature = "types")]
389            task: matches!(invoke, Invoke::Task(_)),
390            arity,
391            params: Vec::new(),
392            invoke,
393            #[cfg(feature = "types")]
394            signature,
395        });
396        Declared {
397            entry: self.functions.last_mut(),
398        }
399    }
400
401    /// A synchronous export: runs on the UI thread inside the call and returns its value. Keep it
402    /// short; anything slow is a [`Self::task`].
403    pub fn function<Args, H: Function<Args>>(&mut self, name: &str, handler: H) -> Declared<'_> {
404        let signature: Signature;
405        #[cfg(feature = "types")]
406        {
407            signature = H::signature;
408        }
409        #[cfg(not(feature = "types"))]
410        {
411            signature = ();
412        }
413        self.add(
414            name,
415            H::ARITY,
416            Invoke::Function(Box::new(move |context, args| handler.invoke(context, args))),
417            signature,
418        )
419    }
420
421    /// An export that runs on a worker thread and returns a `Promise` in the app.
422    pub fn task<Args, H: Task<Args>>(&mut self, name: &str, handler: H) -> Declared<'_> {
423        let signature: Signature;
424        #[cfg(feature = "types")]
425        {
426            signature = H::signature;
427        }
428        #[cfg(not(feature = "types"))]
429        {
430            signature = ();
431        }
432        let handler = Arc::new(handler);
433        self.add(
434            name,
435            H::ARITY,
436            Invoke::Task(Box::new(move |context, args| {
437                handler.clone().prepare(context, args)
438            })),
439            signature,
440        )
441    }
442
443    /// A function `#[skathi::module]` generated: `types` gives the signature, `invoke` runs it.
444    #[doc(hidden)]
445    pub fn __function<Args, H: Function<Args>>(
446        &mut self,
447        name: &str,
448        types: H,
449        invoke: impl Fn(&Context, &HostArgs) -> Result<Value, Fail> + Send + Sync + 'static,
450    ) -> Declared<'_> {
451        drop(types);
452        let signature: Signature;
453        #[cfg(feature = "types")]
454        {
455            signature = H::signature;
456        }
457        #[cfg(not(feature = "types"))]
458        {
459            signature = ();
460        }
461        self.add(
462            name,
463            H::ARITY,
464            Invoke::Function(Box::new(invoke)),
465            signature,
466        )
467    }
468
469    /// A task `#[skathi::module]` generated: `types` gives the signature, `prepare` reads the
470    /// arguments and returns the work.
471    #[doc(hidden)]
472    pub fn __task<Args, H: Task<Args>>(
473        &mut self,
474        name: &str,
475        types: H,
476        prepare: impl Fn(&Context, &HostArgs) -> Result<Work, Fail> + Send + Sync + 'static,
477    ) -> Declared<'_> {
478        drop(types);
479        let signature: Signature;
480        #[cfg(feature = "types")]
481        {
482            signature = H::signature;
483        }
484        #[cfg(not(feature = "types"))]
485        {
486            signature = ();
487        }
488        self.add(name, H::ARITY, Invoke::Task(Box::new(prepare)), signature)
489    }
490
491    /// Declares an event `Handle::emit_to` may send with a `T` payload; the app subscribes with `on`.
492    pub fn event<T: Serialize + Typed + 'static>(&mut self, name: &str) -> &mut Self {
493        if self.problem.is_none() && self.events.iter().any(|e| e.name == name) {
494            self.problem = Some(format!(
495                "native:{}: event {name:?} is declared twice",
496                self.name
497            ));
498        }
499        if name.is_empty() {
500            self.problem = Some(format!("native:{}: an event needs a name", self.name));
501        }
502        self.events.push(Event {
503            name: name.to_owned(),
504            #[cfg(feature = "types")]
505            ty: event_type::<T>,
506        });
507        self
508    }
509
510    /// The declared event called `event`, as the module keeps it.
511    pub(crate) fn declared(&'static self, event: &str) -> Option<&'static str> {
512        self.events
513            .iter()
514            .find(|e| e.name == event)
515            .map(|e| e.name.as_str())
516    }
517}
518
519/// A registered function or task; name its parameters for the generated declarations.
520pub struct Declared<'a> {
521    entry: Option<&'a mut Entry>,
522}
523
524impl Declared<'_> {
525    /// Parameter names for the `.d.ts` (`arg1`, `arg2`, … otherwise).
526    pub fn params<I, S>(self, names: I)
527    where
528        I: IntoIterator<Item = S>,
529        S: Into<String>,
530    {
531        if let Some(entry) = self.entry {
532            entry.params = names.into_iter().map(Into::into).collect();
533        }
534    }
535}
536
537fn panic_message(payload: &(dyn std::any::Any + Send)) -> String {
538    payload
539        .downcast_ref::<&str>()
540        .map(|s| (*s).to_owned())
541        .or_else(|| payload.downcast_ref::<String>().cloned())
542        .unwrap_or_else(|| "a panic".into())
543}
544
545fn labeled(module: &Module, entry: &Entry, failure: Failure) -> Failure {
546    if failure.kind == 1 {
547        Failure {
548            message: format!("native:{}.{}: {}", module.name, entry.name, failure.message),
549            ..failure
550        }
551    } else {
552        failure
553    }
554}
555
556fn panicked(module: &Module, entry: &Entry, payload: &(dyn std::any::Any + Send)) -> Failure {
557    Failure::new(format!(
558        "native:{}.{} panicked: {}",
559        module.name,
560        entry.name,
561        panic_message(payload)
562    ))
563}
564
565/// Runs a call's part on the JS thread: a panic becomes a [`Failure`], a type error is labeled.
566fn guarded<T>(
567    module: &Module,
568    entry: &Entry,
569    run: impl FnOnce() -> Result<T, Fail>,
570) -> Result<T, Fail> {
571    match std::panic::catch_unwind(std::panic::AssertUnwindSafe(run)) {
572        Ok(Ok(value)) => Ok(value),
573        Ok(Err(Fail::Failure(failure))) => Err(Fail::Failure(labeled(module, entry, failure))),
574        Ok(Err(thrown)) => Err(thrown),
575        Err(payload) => Err(Fail::Failure(panicked(module, entry, payload.as_ref()))),
576    }
577}
578
579fn thrown(context: &Context, fail: Fail) -> js::Error {
580    js::Error::Exception(match fail {
581        Fail::Thrown(value) => value,
582        Fail::Failure(failure) => error_value(context, &failure),
583    })
584}
585
586/// Runs one task's work; see `Builder::task_executor`.
587pub type Job = Box<dyn FnOnce() + Send + 'static>;
588pub(crate) type Executor = Arc<dyn Fn(Job) + Send + Sync + 'static>;
589
590const POOL_THREADS: usize = 4;
591static POOL: OnceLock<Mutex<mpsc::Sender<Job>>> = OnceLock::new();
592
593fn pool_run(job: Job) {
594    let sender = POOL.get_or_init(|| {
595        let (tx, rx) = mpsc::channel::<Job>();
596        let rx = Arc::new(Mutex::new(rx));
597        for i in 0..POOL_THREADS {
598            let rx = rx.clone();
599            let _ = std::thread::Builder::new()
600                .name(format!("skathi-task-{i}"))
601                .spawn(move || loop {
602                    let job = match rx.lock() {
603                        Ok(rx) => rx.recv(),
604                        Err(_) => return,
605                    };
606                    match job {
607                        Ok(job) => job(),
608                        Err(_) => return,
609                    }
610                });
611        }
612        Mutex::new(tx)
613    });
614    if let Ok(sender) = sender.lock() {
615        // A send fails only with every worker gone; the job's drop rejects its promise.
616        let _ = sender.send(job);
617    }
618}
619
620enum Item {
621    Task {
622        token: u32,
623        result: Result<marshal::Owned, Failure>,
624    },
625    Event {
626        module: &'static str,
627        event: &'static str,
628        data: marshal::Owned,
629    },
630}
631
632static QUEUE: Mutex<VecDeque<Item>> = Mutex::new(VecDeque::new());
633static QUEUED: AtomicUsize = AtomicUsize::new(0);
634static TASKS: AtomicUsize = AtomicUsize::new(0);
635static NEXT_TOKEN: AtomicU32 = AtomicU32::new(1);
636
637pub(super) fn queued() -> bool {
638    QUEUED.load(Ordering::Acquire) != 0
639}
640
641// Only the first item wakes the JS thread: it drains until the queue is empty, and wakes itself
642// again when it stops early.
643fn push(item: Item) {
644    let first = match QUEUE.lock() {
645        Ok(mut queue) => {
646            queue.push_back(item);
647            QUEUED.fetch_add(1, Ordering::AcqRel) == 0
648        }
649        Err(_) => false,
650    };
651    if first {
652        super::wake();
653    }
654}
655
656/// Settles one task's promise; dropped without settling (an executor that discards the job), it rejects.
657struct TaskReply {
658    token: u32,
659    settled: bool,
660}
661
662impl TaskReply {
663    fn settle(mut self, result: Result<marshal::Owned, Failure>) {
664        self.settled = true;
665        push(Item::Task {
666            token: self.token,
667            result,
668        });
669    }
670}
671
672impl Drop for TaskReply {
673    fn drop(&mut self) {
674        if !self.settled {
675            push(Item::Task {
676                token: self.token,
677                result: Err(Failure::new("the task was dropped before it ran")),
678            });
679        }
680    }
681}
682
683pub(crate) fn emit(module: &'static str, event: &'static str, data: marshal::Owned) {
684    push(Item::Event {
685        module,
686        event,
687        data,
688    });
689}
690
691struct Pending {
692    resolve: Value,
693    reject: Value,
694}
695
696#[derive(Default)]
697struct State {
698    executor: Option<Executor>,
699    modules: HashMap<String, Value>,
700    listeners: HashMap<(&'static str, &'static str), Vec<Value>>,
701    pending: HashMap<u32, Pending>,
702}
703
704thread_local! {
705    static STATE: RefCell<State> = RefCell::new(State::default());
706}
707
708fn type_error(context: &Context, message: &str) -> js::Error {
709    js::Error::Exception(context.error(1, message))
710}
711
712fn parse(context: &Context, json: &str) -> js::Result<Value> {
713    marshal::parse(context, json).map_err(|e| match e {
714        marshal::Error::Thrown(v) => js::Error::Exception(v),
715        _ => js::Error::BadArg,
716    })
717}
718
719fn error_value(context: &Context, failure: &Failure) -> Value {
720    let error = context.error(failure.kind, &failure.message);
721    if let Some(data) = failure.data.as_deref() {
722        if let Ok(value) = parse(context, data) {
723            let _ = context.set(error, &context.atom("data"), value);
724        }
725    }
726    error
727}
728
729fn sync_function(
730    context: &Context,
731    module: &'static Module,
732    entry: &'static Entry,
733    invoke: &'static (dyn Fn(&Context, &HostArgs) -> Result<Value, Fail> + Send + Sync),
734) -> js::Result<Value> {
735    js::function(
736        context,
737        &entry.name,
738        entry.arity as u32,
739        move |context, args| {
740            guarded(module, entry, || invoke(context, &args)).map_err(|f| thrown(context, f))
741        },
742    )
743}
744
745fn task_function(
746    context: &Context,
747    module: &'static Module,
748    entry: &'static Entry,
749    prepare: &'static (dyn Fn(&Context, &HostArgs) -> Result<Work, Fail> + Send + Sync),
750) -> js::Result<Value> {
751    js::function(
752        context,
753        &entry.name,
754        entry.arity as u32,
755        move |context, args| {
756            let work = match guarded(module, entry, || prepare(context, &args)) {
757                Err(Fail::Thrown(e)) => return Err(js::Error::Exception(e)),
758                work => work,
759            };
760            let (promise, resolve, reject) = context.promise()?;
761            let work = match work {
762                Ok(work) => work,
763                Err(Fail::Thrown(e)) => return Err(js::Error::Exception(e)),
764                // Arguments of the wrong type reject, as when they were read on the worker.
765                Err(Fail::Failure(failure)) => {
766                    context.call(
767                        reject,
768                        Value::undefined(),
769                        &[error_value(context, &failure)],
770                    )?;
771                    return Ok(promise);
772                }
773            };
774            context.protect(resolve);
775            context.protect(reject);
776            let token = loop {
777                let t = NEXT_TOKEN.fetch_add(1, Ordering::Relaxed);
778                if t != 0 {
779                    break t;
780                }
781            };
782            let executor = STATE.with(|s| {
783                let mut s = s.borrow_mut();
784                s.pending.insert(token, Pending { resolve, reject });
785                s.executor.clone()
786            });
787            TASKS.fetch_add(1, Ordering::AcqRel);
788            let reply = TaskReply {
789                token,
790                settled: false,
791            };
792            let job: Job = Box::new(move || {
793                let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(work))
794                    .unwrap_or_else(|payload| Err(panicked(module, entry, payload.as_ref())));
795                reply.settle(result)
796            });
797            match executor {
798                Some(executor) => {
799                    if std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| executor(job)))
800                        .is_err()
801                    {
802                        eprintln!("[embed] the task executor panicked");
803                    }
804                }
805                None => pool_run(job),
806            }
807            Ok(promise)
808        },
809    )
810}
811
812fn event_name(
813    context: &Context,
814    module: &'static Module,
815    value: Value,
816) -> js::Result<&'static str> {
817    let name = (context.kind(value) == 5)
818        .then(|| context.read_string(value).ok())
819        .flatten();
820    match name.and_then(|name| module.declared(&name)) {
821        Some(name) => Ok(name),
822        _ => {
823            let declared: Vec<String> = module
824                .events
825                .iter()
826                .map(|e| format!("{:?}", e.name))
827                .collect();
828            Err(type_error(
829                context,
830                &format!(
831                    "native:{} has no such event (it has {})",
832                    module.name,
833                    if declared.is_empty() {
834                        "none".into()
835                    } else {
836                        declared.join(", ")
837                    }
838                ),
839            ))
840        }
841    }
842}
843
844fn subscribe(
845    context: &Context,
846    module: &'static Module,
847    off: Value,
848    args: HostArgs,
849) -> js::Result<Value> {
850    let event = event_name(context, module, args.arg(0))?;
851    let callback = args.arg(1);
852    if context.kind(callback) != 9 {
853        return Err(type_error(
854            context,
855            &format!("native:{}.on({event:?}, …) needs a function", module.name),
856        ));
857    }
858    STATE.with(|s| {
859        let mut s = s.borrow_mut();
860        let list = s.listeners.entry((&module.name, event)).or_default();
861        if !list.contains(&callback) {
862            context.protect(callback);
863            list.push(callback);
864        }
865    });
866    let bind = context.get(off, &context.atom("bind"))?;
867    context.call(bind, off, &[Value::undefined(), args.arg(0), callback])
868}
869
870fn unsubscribe(context: &Context, module: &'static Module, args: HostArgs) -> js::Result<Value> {
871    let event = event_name(context, module, args.arg(0))?;
872    let callback = args.arg(1);
873    let removed = STATE.with(|s| {
874        let mut s = s.borrow_mut();
875        let list = s.listeners.get_mut(&(module.name.as_str(), event))?;
876        let at = list.iter().position(|c| *c == callback)?;
877        Some(list.remove(at))
878    });
879    if let Some(callback) = removed {
880        context.unprotect(callback);
881    }
882    Ok(Value::undefined())
883}
884
885fn build(context: &Context, module: &'static Module) -> js::Result<Value> {
886    let object = context.object();
887    context.set(object, &context.atom("available"), Value::boolean(true))?;
888    for entry in &module.functions {
889        let f = match &entry.invoke {
890            Invoke::Task(prepare) => task_function(context, module, entry, &**prepare)?,
891            Invoke::Function(invoke) => sync_function(context, module, entry, &**invoke)?,
892        };
893        context.set(object, &context.atom(&entry.name), f)?;
894    }
895    let off = js::function(context, "off", 2, move |context, args| {
896        unsubscribe(context, module, args)
897    })?;
898    context.protect(off);
899    let on = js::function(context, "on", 2, move |context, args| {
900        subscribe(context, module, off, args)
901    })?;
902    context.set(object, &context.atom("on"), on)?;
903    context.set(object, &context.atom("off"), off)?;
904    Ok(object)
905}
906
907fn deliver_event(context: &Context, module: &str, event: &'static str, data: marshal::Owned) {
908    // The listeners are copied, since one may unsubscribe itself or another while it runs, and
909    // kept alive: on this stack, which the collector scans, or protected when there are more.
910    let mut few = [Value::undefined(); 4];
911    let mut more = Vec::new();
912    let count = STATE.with(|s| {
913        let s = s.borrow();
914        let list = s
915            .listeners
916            .get(&(module, event))
917            .map_or(&[][..], |l| &l[..]);
918        match list.len() {
919            n @ ..=4 => few[..n].copy_from_slice(list),
920            _ => more.extend_from_slice(list),
921        }
922        list.len()
923    });
924    if count == 0 {
925        return;
926    }
927    let Ok(data) = data.to_js(context) else {
928        return;
929    };
930    let listeners = if more.is_empty() {
931        &few[..count]
932    } else {
933        more.iter().for_each(|&c| context.protect(c));
934        &more[..]
935    };
936    for &callback in listeners {
937        if let Err(js::Error::Exception(e)) = context.call(callback, Value::undefined(), &[data]) {
938            JsRuntime::with(|rt| {
939                let err = rt.describe(e);
940                eprintln!(
941                    "[native:{module}] a handler for {event:?} threw: {}\n{}",
942                    err.header, err.stack
943                );
944            });
945        }
946    }
947    more.iter().for_each(|&c| context.unprotect(c));
948}
949
950fn settle_task(context: &Context, token: u32, result: Result<marshal::Owned, Failure>) {
951    TASKS.fetch_sub(1, Ordering::AcqRel);
952    let Some(pending) = STATE.with(|s| s.borrow_mut().pending.remove(&token)) else {
953        return;
954    };
955    let (callback, value) = match result.map(|data| data.to_js(context)) {
956        Ok(Ok(value)) => (pending.resolve, value),
957        Ok(Err(marshal::Error::Thrown(e))) => (pending.reject, e),
958        Ok(Err(other)) => (pending.reject, context.error(0, &other.to_string())),
959        Err(failure) => (pending.reject, error_value(context, &failure)),
960    };
961    let _ = context.call(callback, Value::undefined(), &[value]);
962    context.unprotect(pending.resolve);
963    context.unprotect(pending.reject);
964}
965
966// Queued items count as in flight: the pump keeps draining them within its budget instead of
967// leaving the rest for a wake that already came.
968unsafe fn src_inflight(g: *mut c_void) -> bool {
969    super::is_ours(g) && (TASKS.load(Ordering::Acquire) != 0 || QUEUED.load(Ordering::Acquire) != 0)
970}
971
972unsafe fn src_ready(g: *mut c_void) -> bool {
973    super::is_ours(g) && QUEUED.load(Ordering::Acquire) != 0
974}
975
976const DRAIN_CAP: usize = 16;
977
978unsafe fn src_drain(g: *mut c_void) -> usize {
979    if !unsafe { src_ready(g) } {
980        return 0;
981    }
982    drain()
983}
984
985fn drain() -> usize {
986    let budget = Duration::from_micros(sk_runtime::redjs::web::pump_budget_us() as u64);
987    let start = std::time::Instant::now();
988    let mut n = 0;
989    let mut batch = Vec::with_capacity(DRAIN_CAP);
990    while n < DRAIN_CAP {
991        if let Ok(mut queue) = QUEUE.lock() {
992            let take = queue.len().min(DRAIN_CAP - n);
993            batch.extend(queue.drain(..take));
994        }
995        if batch.is_empty() {
996            break;
997        }
998        QUEUED.fetch_sub(batch.len(), Ordering::AcqRel);
999        n += batch.len();
1000        JsRuntime::with(|rt| {
1001            let context = rt.ctx();
1002            for item in batch.drain(..) {
1003                match item {
1004                    Item::Task { token, result } => settle_task(context, token, result),
1005                    Item::Event {
1006                        module,
1007                        event,
1008                        data,
1009                    } => deliver_event(context, module, event, data),
1010                }
1011            }
1012        });
1013        if start.elapsed() >= budget {
1014            break;
1015        }
1016    }
1017    if QUEUED.load(Ordering::Acquire) != 0 {
1018        super::wake();
1019    }
1020    n
1021}
1022
1023/// Page reload: the old page's subscriptions, unsettled promises and undelivered events are dropped.
1024fn reset(context: &Context) {
1025    if let Ok(mut queue) = QUEUE.lock() {
1026        let before = queue.len();
1027        queue.retain(|item| matches!(item, Item::Task { .. }));
1028        QUEUED.fetch_sub(before - queue.len(), Ordering::AcqRel);
1029    }
1030    let (listeners, pending) = STATE.with(|s| {
1031        let mut s = s.borrow_mut();
1032        (
1033            std::mem::take(&mut s.listeners),
1034            std::mem::take(&mut s.pending),
1035        )
1036    });
1037    for callback in listeners.into_values().flatten() {
1038        context.unprotect(callback);
1039    }
1040    for p in pending.into_values() {
1041        context.unprotect(p.resolve);
1042        context.unprotect(p.reject);
1043    }
1044}
1045
1046/// Builds every module's object before app code and installs `__sk_native_module(name)`, which
1047/// the module loader asks for `native:<name>`.
1048pub(crate) fn install(
1049    context: &Context,
1050    modules: &'static [Module],
1051    executor: Option<Executor>,
1052) -> js::Result<()> {
1053    marshal::install(context)?;
1054    STATE.with(|s| s.borrow_mut().executor = executor);
1055    for module in modules {
1056        let object = build(context, module)?;
1057        context.protect(object);
1058        STATE.with(|s| s.borrow_mut().modules.insert(module.name.clone(), object));
1059    }
1060    let lookup = js::function(context, "__sk_native_module", 1, |context, args| {
1061        let value = args.arg(0);
1062        let name = (context.kind(value) == 5)
1063            .then(|| context.read_string(value).ok())
1064            .flatten()
1065            .unwrap_or_default();
1066        Ok(STATE
1067            .with(|s| s.borrow().modules.get(&name).copied())
1068            .unwrap_or_else(Value::undefined))
1069    })?;
1070    context.global_set("__sk_native_module", lookup)?;
1071    js::on_reload(reset);
1072    sk_runtime::redjs::web::register_pump_source(sk_runtime::redjs::web::PumpSource {
1073        inflight: src_inflight,
1074        ready: src_ready,
1075        drain: src_drain,
1076    });
1077    Ok(())
1078}
1079
1080#[cfg(test)]
1081mod tests {
1082    use super::*;
1083
1084    #[derive(serde::Serialize, serde::Deserialize)]
1085    #[cfg_attr(feature = "types", derive(specta::Type))]
1086    struct Point {
1087        x: i32,
1088        y: i32,
1089    }
1090
1091    #[test]
1092    fn module_names_and_exports_are_checked() {
1093        let mut m = Module::new("notes".into());
1094        m.function("get", |id: u32| id);
1095        assert!(m.problem().is_none());
1096        m.function("get", |id: u32| id);
1097        assert!(m.problem().is_some());
1098        let mut m = Module::new("notes".into());
1099        m.task("on", || 1);
1100        assert!(m.problem().is_some());
1101        let mut m = Module::new("notes".into());
1102        m.function("delete", |id: u32| id);
1103        assert!(m.problem().is_some());
1104        assert!(Module::new("bad name".into()).problem().is_some());
1105    }
1106
1107    #[test]
1108    fn functions_tasks_and_events_reach_js_as_values_errors_and_promises() {
1109        sk_runtime::testing::on_js_thread(|| {
1110            JsRuntime::with(|runtime| {
1111                let context = runtime.ctx();
1112                let mut m = Module::new("demo".into());
1113                m.function("flip", |p: Point| Point { x: p.y, y: p.x });
1114                m.function("fail", || -> Result<u8, String> { Err("refused".into()) });
1115                m.function("boom", || -> u8 { panic!("kaboom") });
1116                m.task("slow", |n: u32| -> Result<u32, String> {
1117                    if n == 0 {
1118                        Err("zero".into())
1119                    } else {
1120                        Ok(n * 2)
1121                    }
1122                });
1123                m.task("crash", || -> u8 { panic!("worker kaboom") });
1124                m.task("halve", |p: Point| p.x / 2);
1125                m.function("add", |a: i32, b: Option<i32>| a + b.unwrap_or(10));
1126                m.function("found", |id: u32| -> Result<Point, String> {
1127                    if id == 1 {
1128                        Ok(Point { x: 1, y: 1 })
1129                    } else {
1130                        Err(format!("no point {id}"))
1131                    }
1132                });
1133                m.function("structured", || -> Result<(), Point> {
1134                    Err(Point { x: 0, y: 7 })
1135                });
1136                #[derive(serde::Serialize)]
1137                #[cfg_attr(feature = "types", derive(specta::Type))]
1138                enum Status {
1139                    Ok(u8),
1140                }
1141                m.function("status", || Status::Ok(1));
1142                m.function("shout", |s: marshal::Str, n: u8| {
1143                    // SAFETY: used inside the call.
1144                    unsafe { s.get() }.to_uppercase().repeat(n as usize)
1145                });
1146                m.function("sum", |b: marshal::Slice<u8>| {
1147                    // SAFETY: used inside the call.
1148                    unsafe { b.get() }.iter().map(|&b| b as u32).sum::<u32>()
1149                });
1150                m.function("reversed", |mut b: crate::embed::Bytes| {
1151                    b.reverse();
1152                    b
1153                });
1154                m.task("doubled", |b: crate::embed::Bytes| {
1155                    crate::embed::Bytes(b.iter().map(|b| b * 2).collect())
1156                });
1157                m.event::<Point>("moved");
1158                let modules: &'static [Module] = Box::leak(vec![m].into_boxed_slice());
1159                install(context, modules, None).unwrap();
1160                let eval = |src: &str| -> String {
1161                    let v = context.eval(src).unwrap();
1162                    context.read_string(v).unwrap()
1163                };
1164                eval(
1165                    "globalThis.__nm = __sk_native_module('demo');
1166                     globalThis.__seen = [];
1167                     globalThis.__off = __nm.on('moved', (p) => __seen.push(p.x + p.y));
1168                     ''",
1169                );
1170                let settle = || {
1171                    let deadline = std::time::Instant::now() + Duration::from_secs(10);
1172                    while TASKS.load(Ordering::Acquire) != 0 || QUEUED.load(Ordering::Acquire) != 0
1173                    {
1174                        assert!(std::time::Instant::now() < deadline, "tasks did not settle");
1175                        drain();
1176                        context.drain_microtasks();
1177                        std::thread::sleep(Duration::from_millis(5));
1178                    }
1179                    context.drain_microtasks();
1180                };
1181                assert_eq!(
1182                    eval("JSON.stringify(__nm.flip({ x: 1, y: 2 }))"),
1183                    r#"{"x":2,"y":1}"#
1184                );
1185                assert_eq!(
1186                    eval("try { __nm.fail(); 'no' } catch (e) { e instanceof Error ? e.message : 'not an Error' }"),
1187                    "refused"
1188                );
1189                assert_eq!(
1190                    eval("try { __nm.boom(); 'no' } catch (e) { String(e.message.includes('kaboom')) }"),
1191                    "true"
1192                );
1193                assert_eq!(
1194                    eval("try { __nm.flip('x'); 'no' } catch (e) { e.name }"),
1195                    "TypeError"
1196                );
1197                assert_eq!(
1198                    eval("try { __nm.on('nope', () => {}); 'no' } catch (e) { e.name }"),
1199                    "TypeError"
1200                );
1201                assert_eq!(eval("typeof __sk_native_module('missing')"), "undefined");
1202                assert_eq!(
1203                    eval("[__nm.add(2, 3), __nm.add(2), __nm.add(2, 3, 99)].join()"),
1204                    "5,12,5"
1205                );
1206                assert_eq!(
1207                    eval("JSON.stringify([__nm.found(1), __nm.status()])"),
1208                    r#"[{"x":1,"y":1},{"Ok":1}]"#
1209                );
1210                assert_eq!(
1211                    eval("[__nm.shout('ab', 2), __nm.shout('éß中', 1)].join()"),
1212                    "ABAB,ÉSS中"
1213                );
1214                assert_eq!(
1215                    eval("try { __nm.shout(1, 1); 'no' } catch (e) { e.message }"),
1216                    "native:demo.shout: argument 1: invalid type: integer `1`, expected a string"
1217                );
1218                assert_eq!(
1219                    eval("try { __nm.found(2); 'no' } catch (e) { e.message + '|' + e.name }"),
1220                    "no point 2|Error"
1221                );
1222                assert_eq!(
1223                    eval("try { __nm.structured(); 'no' } catch (e) { JSON.stringify(e.data) }"),
1224                    r#"{"x":0,"y":7}"#
1225                );
1226                assert_eq!(
1227                    eval("[__nm.sum(new Uint8Array([1, 2, 3])), __nm.sum([4, 5]), __nm.sum(new Uint8Array([9, 9]).buffer)].join()"),
1228                    "6,9,18"
1229                );
1230                assert_eq!(
1231                    eval("const r = __nm.reversed(new Uint8Array([1, 2, 3])); r.constructor.name + ':' + r.join()"),
1232                    "Uint8Array:3,2,1"
1233                );
1234                eval(
1235                    "globalThis.__settled = {};
1236                     __nm.doubled(new Uint8Array([1, 2])).then((v) => __settled.bytes = v.constructor.name + ':' + v.join());
1237                     __nm.slow(21).then((v) => __settled.ok = v);
1238                     __nm.slow(0).catch((e) => __settled.err = e.message);
1239                     __nm.crash().catch((e) => __settled.crash = e.message.includes('worker kaboom'));
1240                     __nm.halve('x').catch((e) => __settled.bad = e.name + ': ' + e.message);
1241                     ''",
1242                );
1243                emit("demo", "moved", event_data(&Point { x: 3, y: 4 }).unwrap());
1244                settle();
1245                assert_eq!(
1246                    eval("[__settled.ok, __settled.err, __settled.crash, __settled.bytes].join()"),
1247                    "42,zero,true,Uint8Array:2,4"
1248                );
1249                assert_eq!(
1250                    eval("__settled.bad"),
1251                    "TypeError: native:demo.halve: argument 1: invalid type: string \"x\", expected struct Point"
1252                );
1253                assert_eq!(eval("JSON.stringify(__seen)"), "[7]");
1254                eval("__off(); ''");
1255                emit("demo", "moved", event_data(&Point { x: 1, y: 1 }).unwrap());
1256                settle();
1257                assert_eq!(eval("JSON.stringify(__seen)"), "[7]");
1258                emit("demo", "moved", event_data(&Point { x: 2, y: 2 }).unwrap());
1259                reset(context);
1260                eval("__nm.on('moved', (p) => __seen.push(p.x + p.y)); ''");
1261                emit("demo", "moved", event_data(&Point { x: 5, y: 5 }).unwrap());
1262                settle();
1263                assert_eq!(eval("JSON.stringify(__seen)"), "[7,10]");
1264            })
1265        });
1266    }
1267}