Skip to main content

sk_app/
embed.rs

1//! Skathi as a library: another program runs the whole engine on a thread of its own and gives
2//! the app native modules (`import { … } from "native:<name>"`): typed functions, tasks and
3//! events. On macOS, AppKit owns the process main thread: use `Builder::run_on_main_thread` with
4//! an application cleanup callback instead.
5//!
6//! **One per process, once.** The JS realm cannot be torn down and gpui is one `Application`, so
7//! [`Builder::spawn`] works once; after the app closes its thread sleeps for the rest of the process.
8//!
9//! **A module function runs on the Skathi thread**, inside the JS call, so one that blocks
10//! freezes the UI: slow work is a [`Module::task`], which runs on a worker and returns a promise.
11//!
12//! The exe keeps the host command-line flags, `singleInstance`, protocol handling and ending the
13//! process. F12 opens the inspector only when [`Builder::inspector_exe`] names a sk-app.exe.
14
15use std::collections::{HashMap, VecDeque};
16use std::ffi::c_void;
17use std::path::{Path, PathBuf};
18use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
19use std::sync::{Arc, Condvar, Mutex, OnceLock};
20use std::time::Duration;
21
22use sk_runtime::redjs::api::Value;
23use sk_runtime::{host_fn, JsRuntime};
24
25pub mod bytes;
26mod host_context;
27mod marshal;
28mod module;
29#[cfg(feature = "types")]
30mod types;
31pub use bytes::Bytes;
32pub use host_context::{HostContext, HostCookie, SameSite};
33pub use module::{Declared, Function, IntoModule, Job, Module, Task, Typed};
34pub use serde;
35
36/// What `#[skathi::module]` and `#[skathi::data]` expand to; not an API.
37#[doc(hidden)]
38pub mod __private {
39    pub use super::module::private::*;
40}
41
42/// [`SurfaceInfo::dynamic_range_limit`]'s type.
43pub use sk_css::DynamicRangeLimit;
44pub use sk_tree::surface::{
45    monotonic_ns, surface, D3D11Device, D3D12Device, D3D12Fence, FrameDropReason, FrameEvent,
46    FramePrecision, FramePresent, FrameWatch, MetalDevice, MetalEvent, SharedTexture,
47    SurfaceDisplay, SurfaceError, SurfaceEvent, SurfaceFormat, SurfaceHandle, SurfaceInfo,
48    SurfaceStats, SurfaceWatch,
49};
50#[cfg(feature = "types")]
51pub use specta::{self, Type};
52
53type Setup = Box<dyn FnOnce(&HostContext) -> Result<(), String> + Send + 'static>;
54type PrepareDataDir = Box<dyn FnOnce(&Path) -> Result<(), String> + Send + 'static>;
55
56#[derive(Default)]
57struct SetupHook(Mutex<Option<Setup>>);
58
59impl SetupHook {
60    fn run(&self, context: &HostContext) -> Result<(), String> {
61        let setup = self
62            .0
63            .lock()
64            .map_err(|_| "host setup lock was poisoned".to_string())?
65            .take();
66        let Some(setup) = setup else { return Ok(()) };
67        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| setup(context)))
68            .unwrap_or_else(|_| Err("host setup panicked".into()))
69    }
70}
71
72/// The exe's own stack size (`/STACK` in build.rs), which JSC's recursion limit is sized for.
73#[cfg(not(target_os = "macos"))]
74const STACK: usize = 8 * 1024 * 1024;
75
76const DRAIN_CAP: usize = 16;
77
78pub(crate) const HOST_TYPES_FLAG: &str = "--sk-host-types";
79
80#[cfg(feature = "types")]
81fn host_types(modules: &[Module]) -> Result<String, String> {
82    types::declarations(modules)
83}
84
85#[cfg(not(feature = "types"))]
86fn host_types(modules: &[Module]) -> Result<String, String> {
87    if modules.is_empty() {
88        return Ok(String::new());
89    }
90    Err("this program was built without skathi's types feature: turn it on to type its native modules".into())
91}
92
93/// A host function: called with the [`Call`] on the Skathi thread.
94pub type Handler = Arc<dyn Fn(Call) + Send + Sync + 'static>;
95
96struct Config {
97    data_dir: Option<PathBuf>,
98    #[cfg(feature = "storages")]
99    storage_encrypted: Option<bool>,
100    visible: bool,
101    desktop_launch: bool,
102    setup: SetupHook,
103    functions: HashMap<String, Handler>,
104    modules: Vec<Module>,
105    executor: Option<module::Executor>,
106    activate: bool,
107    #[cfg_attr(not(sk_devtools), allow(dead_code))]
108    inspector_exe: Option<PathBuf>,
109    #[cfg_attr(not(target_os = "linux"), allow(dead_code))]
110    desktop_id: Option<String>,
111}
112
113static CONFIG: OnceLock<Config> = OnceLock::new();
114static STARTED: AtomicBool = AtomicBool::new(false);
115
116pub(crate) fn active() -> bool {
117    CONFIG.get().is_some()
118}
119
120/// `spawn` already prepared the desktop launch policy.
121pub(crate) fn desktop_launch_prepared() -> bool {
122    CONFIG.get().is_some_and(|config| config.desktop_launch)
123}
124
125/// Always, unless embedded with [`Builder::activate`]`(false)`.
126pub(crate) fn activates() -> bool {
127    CONFIG
128        .get()
129        .is_none_or(|c| requests_activation(c.activate, c.visible))
130}
131
132pub(crate) fn visible() -> bool {
133    CONFIG.get().is_none_or(|c| c.visible)
134}
135
136/// Seals a dormant profile's localStorage with the OS provider, no plaintext fallback.
137pub fn encrypt_local_storage_at(directory: &Path) -> Result<bool, String> {
138    #[cfg(feature = "storages")]
139    {
140        sk_storage::encrypt_local_storage_at(directory)
141    }
142    #[cfg(not(feature = "storages"))]
143    {
144        let _ = directory;
145        Err("enable the storages feature to encrypt localStorage".into())
146    }
147}
148
149#[cfg(feature = "storages")]
150pub(crate) fn storage_encrypted() -> Option<bool> {
151    CONFIG.get()?.storage_encrypted
152}
153
154pub(crate) fn data_dir() -> Option<&'static Path> {
155    CONFIG.get()?.data_dir.as_deref()
156}
157
158fn resolve_data_dir(
159    configured: Option<PathBuf>,
160    override_dir: Option<std::ffi::OsString>,
161) -> Result<Option<PathBuf>, Error> {
162    let directory = override_dir
163        .filter(|path| !path.is_empty())
164        .map(PathBuf::from)
165        .or(configured);
166    if let Some(path) = &directory {
167        if !path.is_absolute() {
168            return Err(Error::DataDirectory(format!(
169                "data directory must be absolute: {}",
170                path.display()
171            )));
172        }
173    }
174    Ok(directory)
175}
176
177fn prepare_directory(
178    directory: Option<&Path>,
179    prepare: Option<PrepareDataDir>,
180) -> Result<(), Error> {
181    let Some(directory) = directory else {
182        return if prepare.is_some() {
183            Err(Error::DataDirectory(
184                "prepare_data_dir requires a data directory".into(),
185            ))
186        } else {
187            Ok(())
188        };
189    };
190    if let Some(prepare) = prepare {
191        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| prepare(directory)))
192            .unwrap_or_else(|_| Err("data directory preparation panicked".into()))
193            .map_err(Error::DataDirectory)?;
194    }
195    std::fs::create_dir_all(directory).map_err(|error| {
196        Error::DataDirectory(format!("could not create {}: {error}", directory.display()))
197    })
198}
199
200fn requests_activation(activate: bool, visible: bool) -> bool {
201    activate && visible
202}
203
204#[cfg_attr(not(sk_devtools), allow(dead_code))]
205pub(crate) fn inspector_exe() -> Option<PathBuf> {
206    CONFIG.get()?.inspector_exe.clone()
207}
208
209#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
210pub(crate) fn desktop_id() -> Option<String> {
211    CONFIG.get()?.desktop_id.clone()
212}
213
214// A dev build has no payload loader; it only refuses one.
215#[cfg_attr(not(feature = "prod"), allow(dead_code))]
216enum PayloadSource {
217    File(PathBuf),
218    Bytes(Vec<u8>),
219    Static(&'static [u8]),
220}
221
222#[cfg(any(feature = "prod", test))]
223impl PayloadSource {
224    /// The bytes, a label, and the folder of its asset packs (`None`: the executable's).
225    fn load(self) -> Result<(crate::payload::PayloadBytes, String, Option<PathBuf>), Error> {
226        use crate::payload::PayloadBytes;
227        match self {
228            Self::File(path) => {
229                let file = crate::mapped_file::MappedFile::open(&path)
230                    .map_err(|e| Error::Payload(format!("{}: {e}", path.display())))?;
231                let dir = path.parent().map(Path::to_path_buf);
232                Ok((PayloadBytes::File(file), path.display().to_string(), dir))
233            }
234            Self::Bytes(bytes) => Ok((PayloadBytes::Owned(bytes), "bytes".into(), None)),
235            Self::Static(bytes) => Ok((PayloadBytes::Embedded(bytes), "static bytes".into(), None)),
236        }
237    }
238}
239
240/// Why [`Builder::spawn`] did not start Skathi.
241#[derive(Debug)]
242pub enum Error {
243    /// It runs once per process.
244    AlreadyStarted,
245    /// A `--features prod` build with no payload given, stamped in, or in `SK_PAYLOAD`.
246    NoPayload,
247    /// A dev build boots the dev dist and has no payload loader.
248    PayloadNeedsProd,
249    /// The payload could not be read or parsed.
250    Payload(String),
251    /// Something read this process's arguments before `spawn`.
252    ArgsAlreadyRead,
253    /// Desktop launch policy forwarded this invocation or refused a duplicate: the embedding main
254    /// should return this exit code (0 means forwarded).
255    LaunchExit(i32),
256    /// The configured profile directory could not be prepared.
257    DataDirectory(String),
258    /// A native module is misdeclared: a bad or repeated name.
259    Module(String),
260    Spawn(std::io::Error),
261    /// AppKit needs the process main thread: use `run_on_main_thread`.
262    MainThreadRequired,
263}
264
265impl std::fmt::Display for Error {
266    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
267        match self {
268            Error::AlreadyStarted => write!(f, "Skathi already ran in this process; it runs once"),
269            Error::NoPayload => write!(
270                f,
271                "no app: give the builder a payload (`sk publish --payload-only` writes dist/release/.sk/app.skpk)"
272            ),
273            Error::PayloadNeedsProd => {
274                write!(f, "a payload needs sk-app's `prod` feature; a dev build boots the dev dist instead")
275            }
276            Error::Payload(e) => write!(f, "{e}"),
277            Error::ArgsAlreadyRead => write!(f, "Skathi's arguments were read before spawn"),
278            Error::LaunchExit(code) => write!(f, "desktop launch finished with exit code {code}"),
279            Error::DataDirectory(e) => write!(f, "data directory: {e}"),
280            Error::Module(e) => write!(f, "{e}"),
281            Error::Spawn(e) => write!(f, "the Skathi thread did not start: {e}"),
282            Error::MainThreadRequired => write!(f, "AppKit requires the process main thread; call Builder::run_on_main_thread from main"),
283        }
284    }
285}
286
287impl std::error::Error for Error {}
288
289/// Configures and starts an embedded Skathi.
290///
291/// ```no_run
292/// let ui = sk_app::embed::Builder::new()
293///     .payload_file("apps/hello/dist/release/.sk/app.skpk")
294///     .module("db", |m: &mut sk_app::embed::Module| {
295///         m.task("query", |sql: String| -> Result<Vec<String>, String> { Ok(vec![sql]) });
296///         m.event::<bool>("online");
297///     })
298///     .spawn()?;
299/// ui.emit_to("db", "online", &true)?;
300/// let exit = ui.wait();
301/// # Ok::<(), Box<dyn std::error::Error>>(())
302/// ```
303pub struct Builder {
304    data_dir: Option<PathBuf>,
305    storage_encrypted: Option<bool>,
306    prepare_data_dir: Option<PrepareDataDir>,
307    visible: bool,
308    desktop_launch: bool,
309    setup: Option<Setup>,
310    payload: Option<PayloadSource>,
311    args: Vec<String>,
312    functions: HashMap<String, Handler>,
313    modules: Vec<Module>,
314    executor: Option<module::Executor>,
315    activate: bool,
316    inspector_exe: Option<PathBuf>,
317    desktop_id: Option<String>,
318    exact_frame_feedback: bool,
319}
320
321impl Default for Builder {
322    fn default() -> Self {
323        Self::new()
324    }
325}
326
327impl Builder {
328    pub fn new() -> Self {
329        Builder {
330            data_dir: None,
331            storage_encrypted: None,
332            prepare_data_dir: None,
333            visible: true,
334            desktop_launch: false,
335            setup: None,
336            payload: None,
337            args: Vec::new(),
338            functions: HashMap::new(),
339            modules: Vec::new(),
340            executor: None,
341            activate: true,
342            inspector_exe: None,
343            desktop_id: None,
344            exact_frame_feedback: false,
345        }
346    }
347
348    /// Sets the persistent profile root, before storage and cookies load. HTTP and bytecode caches
349    /// live in its `cache/http` and `cache/jsc`. `SK_DATA_DIR` overrides it. Must be absolute.
350    pub fn data_dir(mut self, directory: impl Into<PathBuf>) -> Self {
351        self.data_dir = Some(directory.into());
352        self
353    }
354
355    /// Sets storage encryption before any cookie, database or app code runs. `true` requires an OS
356    /// provider and seals existing plaintext localStorage before boot.
357    pub fn storage_encrypted(mut self, encrypted: bool) -> Self {
358        self.storage_encrypted = Some(encrypted);
359        self
360    }
361
362    /// Prepares or migrates the profile after single-instance handling, before any storage or VM
363    /// initialization. An error or panic stops startup.
364    pub fn prepare_data_dir<F>(mut self, prepare: F) -> Self
365    where
366        F: FnOnce(&Path) -> Result<(), String> + Send + 'static,
367    {
368        self.prepare_data_dir = Some(Box::new(prepare));
369        self
370    }
371
372    /// Lets this binary own the payload's single-instance and protocol policy, using the real command
373    /// line (a deep link's raw URL included). A forwarded launch returns `Error::LaunchExit(0)`.
374    pub fn desktop_launch(mut self, enabled: bool) -> Self {
375        self.desktop_launch = enabled;
376        self
377    }
378
379    /// Runs once on the Skathi thread after storage install, before any app JS or window. An
380    /// error or panic prevents startup. Keep it short.
381    pub fn setup<F>(mut self, setup: F) -> Self
382    where
383        F: FnOnce(&HostContext) -> Result<(), String> + Send + 'static,
384    {
385        self.setup = Some(Box::new(setup));
386        self
387    }
388
389    /// The `.skpk` file `sk build` writes (`--features prod` only), mapped read-only for the app's
390    /// lifetime: replace it atomically, never modify it in place.
391    pub fn payload_file(mut self, path: impl Into<PathBuf>) -> Self {
392        self.payload = Some(PayloadSource::File(path.into()));
393        self
394    }
395
396    /// Owned `.skpk` bytes. Prefer [`Self::payload_static`] for `include_bytes!`.
397    pub fn payload_bytes(mut self, bytes: impl Into<Vec<u8>>) -> Self {
398        self.payload = Some(PayloadSource::Bytes(bytes.into()));
399        self
400    }
401
402    /// A static `.skpk`, borrowed without copying.
403    pub fn payload_static(mut self, bytes: &'static [u8]) -> Self {
404        self.payload = Some(PayloadSource::Static(bytes));
405        self
406    }
407
408    /// `appLaunch.argv` after the exe; none of it is read as a host flag.
409    pub fn args<I, S>(mut self, args: I) -> Self
410    where
411        I: IntoIterator<Item = S>,
412        S: Into<String>,
413    {
414        self.args = args.into_iter().map(Into::into).collect();
415        self
416    }
417
418    /// A native module the app imports as `native:<name>`: a value of a `#[skathi::module]` type,
419    /// or a closure `|m: &mut Module| …` that registers its functions, tasks and events.
420    pub fn module(mut self, name: impl Into<String>, exports: impl IntoModule) -> Self {
421        let mut module = Module::new(name.into());
422        exports.register(&mut module);
423        self.modules.push(module);
424        self
425    }
426
427    /// Runs module tasks on the embedder's own executor (a tokio or rayon pool) instead of
428    /// Skathi's four worker threads. A job it drops unrun rejects its promise.
429    pub fn task_executor<F>(mut self, executor: F) -> Self
430    where
431        F: Fn(Job) + Send + Sync + 'static,
432    {
433        self.executor = Some(Arc::new(executor));
434        self
435    }
436
437    /// A function the app calls as `appHost.call(name, ...args)`; the handler gets the arguments
438    /// as a JSON array and answers through the [`Call`].
439    #[deprecated(
440        since = "0.4.0",
441        note = "use native modules: `Builder::module` and `import { … } from \"native:<name>\"`"
442    )]
443    pub fn function<F>(mut self, name: impl Into<String>, handler: F) -> Self
444    where
445        F: Fn(Call) + Send + Sync + 'static,
446    {
447        self.functions.insert(name.into(), Arc::new(handler));
448        self
449    }
450
451    /// Whether the primary window is shown at startup (default true). Hidden apps still boot JS and
452    /// pump background work, and do not activate or raise an already running instance.
453    pub fn visible(mut self, visible: bool) -> Self {
454        self.visible = visible;
455        self
456    }
457
458    /// Whether the app's window takes the foreground when it opens (default `true`).
459    pub fn activate(mut self, on: bool) -> Self {
460        self.activate = on;
461        self
462    }
463
464    /// A sk-app.exe of this Skathi version, started as the inspector on F12 and
465    /// `appDevtools.open()`. Without it they say why nothing opened; the devtools protocol works either way.
466    pub fn inspector_exe(mut self, path: impl Into<PathBuf>) -> Self {
467        self.inspector_exe = Some(path.into());
468        self
469    }
470
471    /// The app's desktop entry id on Linux (`gl.example.App`): the Wayland app id and X11 class of
472    /// its windows, which the desktop matches to the entry's icon and dock slot. Ignored elsewhere.
473    pub fn desktop_id(mut self, id: impl Into<String>) -> Self {
474        self.desktop_id = Some(id.into());
475        self
476    }
477
478    /// On Windows, reports frames once the compositor has finished each refresh (default `false`):
479    /// every `FrameEvent::Presented` is `Exact` and no frame misses its refresh to another
480    /// application's update, but every window present reaches the screen one refresh later.
481    pub fn exact_frame_feedback(mut self, on: bool) -> Self {
482        self.exact_frame_feedback = on;
483        self
484    }
485
486    /// Starts Skathi on a thread of its own and returns at once; events emitted before the app
487    /// is ready wait for it. On macOS this returns `Error::MainThreadRequired`: use
488    /// `Self::run_on_main_thread` instead.
489    pub fn spawn(self) -> Result<Handle, Error> {
490        self.answer_host_types();
491        #[cfg(target_os = "macos")]
492        {
493            Err(Error::MainThreadRequired)
494        }
495        #[cfg(not(target_os = "macos"))]
496        {
497            let handle = self.prepare()?;
498            std::thread::Builder::new()
499                .name("skathi".into())
500                .stack_size(STACK)
501                .spawn(run_thread)
502                .map_err(Error::Spawn)?;
503            Ok(handle)
504        }
505    }
506
507    /// Runs AppKit and JSC on the process main thread until the app closes, then owns the rest of the
508    /// process: the cleanup callback runs on a separate lifecycle thread after shutdown hooks (or the
509    /// deadline), should stop workers and flush logs, and returns the exit code. A panic in it exits
510    /// with code 1. Startup validation errors return normally; calls from a background thread fail
511    /// before consuming the one-run state.
512    #[cfg(target_os = "macos")]
513    pub fn run_on_main_thread<F>(self, on_exit: F) -> Result<(), Error>
514    where
515        F: FnOnce(Exit) -> i32 + Send + 'static,
516    {
517        self.answer_host_types();
518        require_main_thread()?;
519        let handle = self.prepare()?;
520        std::thread::Builder::new()
521            .name("skathi-lifecycle".into())
522            .spawn(move || {
523                let exit = handle.wait();
524                let code = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| on_exit(exit)))
525                    .unwrap_or_else(|_| {
526                        eprintln!("[embed] the application shutdown callback panicked");
527                        1
528                    });
529                std::process::exit(code);
530            })
531            .map_err(Error::Spawn)?;
532        run_thread();
533        Ok(())
534    }
535
536    /// `<exe> --sk-host-types` (what `sk types` and `sk dev --exe` run): prints the modules'
537    /// declarations and ends the process before anything starts.
538    fn answer_host_types(&self) {
539        if std::env::args_os()
540            .nth(1)
541            // `sk types` looks for the flag's bytes in the exe before it runs it; without
542            // black_box an optimised build compares immediates and the bytes are gone.
543            .is_none_or(|a| a != std::hint::black_box(HOST_TYPES_FLAG))
544        {
545            return;
546        }
547        let result = self
548            .module_problem()
549            .map_or_else(|| host_types(&self.modules), Err);
550        match result {
551            Ok(text) => {
552                print!("{text}");
553                std::process::exit(0);
554            }
555            Err(e) => {
556                eprintln!("{e}");
557                std::process::exit(1);
558            }
559        }
560    }
561
562    fn module_problem(&self) -> Option<String> {
563        for (i, m) in self.modules.iter().enumerate() {
564            if let Some(problem) = m.problem() {
565                return Some(problem.to_owned());
566            }
567            if self.modules[..i].iter().any(|other| other.name == m.name) {
568                return Some(format!("native:{} is registered twice", m.name));
569            }
570        }
571        None
572    }
573
574    fn prepare(mut self) -> Result<Handle, Error> {
575        if let Some(problem) = self.module_problem() {
576            return Err(Error::Module(problem));
577        }
578        let data_dir = resolve_data_dir(self.data_dir.take(), std::env::var_os("SK_DATA_DIR"))?;
579        #[cfg(not(feature = "storages"))]
580        if self.storage_encrypted.is_some() {
581            return Err(Error::DataDirectory(
582                "storage_encrypted requires the storages feature".into(),
583            ));
584        }
585        if STARTED.swap(true, Ordering::SeqCst) {
586            return Err(Error::AlreadyStarted);
587        }
588        if let Err(e) = self.load_payload() {
589            STARTED.store(false, Ordering::SeqCst);
590            return Err(e);
591        }
592        if self.desktop_launch {
593            // Preserve GetCommandLineW protocol recovery; rejoining Builder.args
594            // would corrupt quotes and repeated spaces inside a deep link.
595            let args = sk_desktop::args::process();
596            let launch = crate::boot_mode::launch_config();
597            if let sk_desktop::launch::Outcome::Exit(code) =
598                sk_desktop::launch::start_with_activation(
599                    args,
600                    launch.as_deref(),
601                    crate::boot_mode::app_name(),
602                    None,
603                    requests_activation(self.activate, self.visible),
604                )
605            {
606                return Err(Error::LaunchExit(code));
607            }
608            sk_desktop::launch::register_declared();
609        } else {
610            let exe = std::env::current_exe()
611                .map(|p| p.to_string_lossy().into_owned())
612                .unwrap_or_default();
613            if !sk_desktop::args::set_embedded(exe, self.args) {
614                return Err(Error::ArgsAlreadyRead);
615            }
616        }
617        prepare_directory(data_dir.as_deref(), self.prepare_data_dir.take())?;
618        gpui::present_feedback::set_feedback_after_composition(self.exact_frame_feedback);
619        let config = Config {
620            data_dir,
621            #[cfg(feature = "storages")]
622            storage_encrypted: self.storage_encrypted,
623            visible: self.visible,
624            desktop_launch: self.desktop_launch,
625            setup: SetupHook(Mutex::new(self.setup)),
626            functions: self.functions,
627            modules: self.modules,
628            executor: self.executor,
629            activate: self.activate,
630            inspector_exe: self.inspector_exe,
631            desktop_id: self.desktop_id,
632        };
633        if CONFIG.set(config).is_err() {
634            return Err(Error::AlreadyStarted);
635        }
636        Ok(Handle { _private: () })
637    }
638
639    #[cfg(feature = "prod")]
640    fn load_payload(&mut self) -> Result<(), Error> {
641        let Some(source) = self.payload.take() else {
642            return if crate::payload::get().is_some() {
643                Ok(())
644            } else {
645                Err(Error::NoPayload)
646            };
647        };
648        let (bytes, label, dir) = source.load()?;
649        crate::payload::set_external(bytes, label, dir.as_deref()).map_err(Error::Payload)
650    }
651
652    #[cfg(not(feature = "prod"))]
653    fn load_payload(&self) -> Result<(), Error> {
654        match self.payload {
655            Some(_) => Err(Error::PayloadNeedsProd),
656            None => Ok(()),
657        }
658    }
659}
660
661#[cfg(target_os = "macos")]
662fn require_main_thread() -> Result<(), Error> {
663    unsafe extern "C" {
664        fn pthread_main_np() -> std::ffi::c_int;
665    }
666    if unsafe { pthread_main_np() } == 0 {
667        Err(Error::MainThreadRequired)
668    } else {
669        Ok(())
670    }
671}
672
673fn run_thread() {
674    // `run_embedded` ends in `shutdown::finish`, which never returns; only a panic out of gpui's
675    // loop gets past it. The thread must not end even then (its thread-locals are the JS realm).
676    if let Err(p) = std::panic::catch_unwind(crate::run_embedded) {
677        let why = p
678            .downcast_ref::<&str>()
679            .map(|s| s.to_string())
680            .or_else(|| p.downcast_ref::<String>().cloned())
681            .unwrap_or_else(|| "a panic".into());
682        eprintln!("[embed] the Skathi thread panicked: {why}");
683        finished(false, format!("panicked: {why}"));
684    }
685    loop {
686        std::thread::park();
687    }
688}
689
690/// How the app ended.
691#[derive(Debug, Clone)]
692pub struct Exit {
693    /// `false` when the teardown ran past its deadline or the Skathi thread panicked.
694    pub clean: bool,
695    /// What closed it and how long each teardown step took (the exe's `[shutdown]` line).
696    pub summary: String,
697}
698
699static EXIT: Mutex<Option<Exit>> = Mutex::new(None);
700static EXIT_CV: Condvar = Condvar::new();
701static CLOSE: AtomicBool = AtomicBool::new(false);
702static SHOW: AtomicBool = AtomicBool::new(false);
703
704/// The first report wins.
705pub(crate) fn finished(clean: bool, summary: String) {
706    let Ok(mut exit) = EXIT.lock() else { return };
707    if exit.is_none() {
708        *exit = Some(Exit { clean, summary });
709        EXIT_CV.notify_all();
710    }
711}
712
713/// Why [`Handle::emit_to`] did not queue an event.
714#[derive(Debug, PartialEq, Eq)]
715pub enum EmitError {
716    /// `data` is not one JSON value.
717    NotJson,
718    /// The app has closed.
719    Closed,
720    /// No module of that name declared that event with `Module::event`.
721    NotDeclared,
722}
723
724impl std::fmt::Display for EmitError {
725    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
726        match self {
727            EmitError::NotJson => write!(f, "the event's data is not JSON"),
728            EmitError::Closed => write!(f, "the app has closed"),
729            EmitError::NotDeclared => write!(
730                f,
731                "no native module declares that event: declare it with Module::event"
732            ),
733        }
734    }
735}
736
737impl std::error::Error for EmitError {}
738
739/// The embedder's side of a running Skathi. Cheap to clone; every method works from any thread.
740#[derive(Clone)]
741pub struct Handle {
742    _private: (),
743}
744
745impl Handle {
746    /// Delivers `data` to the `on(event)` handlers of `native:<module>` in the app's next frame.
747    /// The event must be declared with [`Module::event`].
748    pub fn emit_to<T: serde::Serialize + ?Sized>(
749        &self,
750        module: &str,
751        event: &str,
752        data: &T,
753    ) -> Result<(), EmitError> {
754        if self.is_closed() {
755            return Err(EmitError::Closed);
756        }
757        let Some((module, event)) = CONFIG.get().and_then(|c| {
758            let m = c.modules.iter().find(|m| m.name == module)?;
759            Some((m.name.as_str(), m.declared(event)?))
760        }) else {
761            return Err(EmitError::NotDeclared);
762        };
763        let data = module::event_data(data).ok_or(EmitError::NotJson)?;
764        module::emit(module, event, data);
765        Ok(())
766    }
767
768    /// Delivers `data` (one JSON value) to `appHost.on(event)` handlers in the app's next frame.
769    #[deprecated(
770        since = "0.4.0",
771        note = "declare the event on a native module and send it with `Handle::emit_to`"
772    )]
773    pub fn emit(&self, event: &str, data: &str) -> Result<(), EmitError> {
774        if self.is_closed() {
775            return Err(EmitError::Closed);
776        }
777        if crate::json::parse(data).is_none() {
778            return Err(EmitError::NotJson);
779        }
780        let json = format!(
781            "{{\"event\":{},\"data\":{data}}}",
782            crate::json::quote(event)
783        );
784        push(Item::Event { json });
785        Ok(())
786    }
787
788    /// Queues a show/activation on the UI thread, including the first show of an initially hidden
789    /// window. Returns whether it was accepted.
790    pub fn show(&self) -> bool {
791        if self.is_closed() || crate::shutdown::is_closing() || CLOSE.load(Ordering::Acquire) {
792            return false;
793        }
794        SHOW.store(true, Ordering::Release);
795        wake();
796        true
797    }
798
799    /// Closes the app as `appWindow.close()` does: the windows go at once, the teardown runs behind them.
800    pub fn close(&self) {
801        CLOSE.store(true, Ordering::Release);
802        wake();
803    }
804
805    pub fn is_closed(&self) -> bool {
806        EXIT.lock().is_ok_and(|e| e.is_some())
807    }
808
809    pub fn wait(&self) -> Exit {
810        let mut exit = EXIT.lock().unwrap_or_else(|p| p.into_inner());
811        loop {
812            if let Some(e) = exit.as_ref() {
813                return e.clone();
814            }
815            exit = EXIT_CV.wait(exit).unwrap_or_else(|p| p.into_inner());
816        }
817    }
818
819    /// [`Handle::wait`], for at most `timeout`.
820    pub fn wait_timeout(&self, timeout: Duration) -> Option<Exit> {
821        let exit = EXIT.lock().unwrap_or_else(|p| p.into_inner());
822        let (exit, _) = EXIT_CV
823            .wait_timeout_while(exit, timeout, |e| e.is_none())
824            .unwrap_or_else(|p| p.into_inner());
825        exit.clone()
826    }
827}
828
829/// One `appHost.call(name, ...args)`.
830pub struct Call {
831    name: String,
832    args: String,
833    reply: Reply,
834}
835
836impl Call {
837    pub fn name(&self) -> &str {
838        &self.name
839    }
840
841    /// One JSON array.
842    pub fn args(&self) -> &str {
843        &self.args
844    }
845
846    /// Resolves the call's promise with `json` (one JSON value).
847    pub fn resolve(self, json: impl Into<String>) {
848        self.reply.resolve(json)
849    }
850
851    /// Rejects the call's promise with an `AppHostError` saying `message`.
852    pub fn reject(self, message: impl Into<String>) {
853        self.reply.reject(message)
854    }
855
856    pub fn into_reply(self) -> Reply {
857        self.reply
858    }
859}
860
861/// Settles one call's promise, from any thread. Dropped unanswered, it rejects, so a promise never hangs.
862pub struct Reply {
863    token: u32,
864    settled: bool,
865}
866
867impl Reply {
868    /// Resolves with `json` (one JSON value); text that is not JSON rejects.
869    pub fn resolve(mut self, json: impl Into<String>) {
870        self.settled = true;
871        let json = json.into();
872        if crate::json::parse(&json).is_some() {
873            push(Item::Settle {
874                token: self.token,
875                ok: true,
876                text: json,
877            });
878        } else {
879            push(Item::Settle {
880                token: self.token,
881                ok: false,
882                text: "the host answered with text that is not JSON".into(),
883            });
884        }
885    }
886
887    pub fn reject(mut self, message: impl Into<String>) {
888        self.settled = true;
889        push(Item::Settle {
890            token: self.token,
891            ok: false,
892            text: message.into(),
893        });
894    }
895}
896
897impl Drop for Reply {
898    fn drop(&mut self) {
899        if self.settled {
900            return;
901        }
902        let why = if std::thread::panicking() {
903            "the host function panicked"
904        } else {
905            "the host dropped this call without answering"
906        };
907        push(Item::Settle {
908            token: self.token,
909            ok: false,
910            text: why.into(),
911        });
912    }
913}
914
915enum Item {
916    Settle { token: u32, ok: bool, text: String },
917    Event { json: String },
918}
919
920static QUEUE: Mutex<VecDeque<Item>> = Mutex::new(VecDeque::new());
921static QUEUED: AtomicUsize = AtomicUsize::new(0);
922/// Calls made and not yet settled: the event loop's in-flight work.
923static IN_FLIGHT: AtomicUsize = AtomicUsize::new(0);
924static NEXT_TOKEN: AtomicU32 = AtomicU32::new(1);
925static RT_G: AtomicUsize = AtomicUsize::new(0);
926static RT_ID: AtomicU64 = AtomicU64::new(0);
927
928thread_local! {
929    static DISPATCHER: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
930}
931
932fn push(item: Item) {
933    if let Ok(mut q) = QUEUE.lock() {
934        q.push_back(item);
935        QUEUED.fetch_add(1, Ordering::AcqRel);
936    }
937    wake();
938}
939
940fn wake() {
941    let id = RT_ID.load(Ordering::Acquire);
942    if id != 0 {
943        sk_runtime::redjs::web::wake(sk_runtime::redjs::context::ContextId(id));
944    }
945    sk_runtime::frames::wake();
946    crate::background::prompt();
947}
948
949/// A call's answer, a module task's result or a native event is waiting for JS.
950pub(crate) fn queued() -> bool {
951    QUEUED.load(Ordering::Acquire) != 0 || module::queued()
952}
953
954fn is_ours(g: *mut c_void) -> bool {
955    !g.is_null() && g as usize == RT_G.load(Ordering::Acquire)
956}
957
958unsafe fn src_inflight(g: *mut c_void) -> bool {
959    is_ours(g) && IN_FLIGHT.load(Ordering::Acquire) != 0
960}
961
962unsafe fn src_ready(g: *mut c_void) -> bool {
963    is_ours(g) && QUEUED.load(Ordering::Acquire) != 0 && DISPATCHER.with(|d| d.get()) != 0
964}
965
966unsafe fn src_drain(g: *mut c_void) -> usize {
967    if !unsafe { src_ready(g) } {
968        return 0;
969    }
970    let budget = Duration::from_micros(sk_runtime::redjs::web::pump_budget_us() as u64);
971    let start = std::time::Instant::now();
972    let mut n = 0;
973    while n < DRAIN_CAP {
974        let Some(item) = QUEUE.lock().ok().and_then(|mut q| q.pop_front()) else {
975            break;
976        };
977        QUEUED.fetch_sub(1, Ordering::AcqRel);
978        match item {
979            Item::Settle { token, ok, text } => {
980                IN_FLIGHT.fetch_sub(1, Ordering::AcqRel);
981                deliver(token, ok, &text);
982            }
983            Item::Event { json } => deliver(0, true, &json),
984        }
985        n += 1;
986        if start.elapsed() >= budget {
987            break;
988        }
989    }
990    n
991}
992
993fn deliver(token: u32, ok: bool, text: &str) {
994    let dispatcher = DISPATCHER.with(|d| d.get());
995    if dispatcher == 0 {
996        return;
997    }
998    JsRuntime::with(|rt| {
999        let a = [
1000            Value::number(f64::from(token)),
1001            Value::boolean(ok),
1002            rt.ctx().string(text),
1003        ];
1004        if let Err(sk_runtime::redjs::api::Error::Exception(e)) =
1005            rt.ctx().call(Value(dispatcher), Value::undefined(), &a)
1006        {
1007            let err = rt.describe(e);
1008            eprintln!("[appHost dispatch] {}\n{}", err.header, err.stack);
1009        }
1010    });
1011}
1012
1013pub(crate) fn setup(runtime: &JsRuntime) -> Result<(), String> {
1014    let Some(config) = CONFIG.get() else {
1015        return Ok(());
1016    };
1017    config.setup.run(&HostContext::installed(Some(runtime)))
1018}
1019
1020/// Dock click with no window visible (`applicationShouldHandleReopen:`): as [`Handle::show`].
1021#[cfg(target_os = "macos")]
1022pub(crate) fn reopen() {
1023    let _accepted = Handle { _private: () }.show();
1024}
1025
1026/// Applies a show or close the embedder asked for, from the frame's JS wave.
1027pub(crate) fn pump() {
1028    let show = SHOW.swap(false, Ordering::AcqRel);
1029    if CLOSE.swap(false, Ordering::AcqRel) {
1030        sk_tree::log::record("embed", "[embed] the embedder closed the app");
1031        crate::window::request_close();
1032    } else if show && !crate::shutdown::is_closing() {
1033        crate::window::request_activate();
1034    }
1035}
1036
1037host_fn!(fn sk_host_set_dispatcher(g, args) {
1038    let f = args.arg(0);
1039    unsafe { sk_runtime::redjs::ffi::redjs_protect(g, f.0) };
1040    let old = DISPATCHER.with(|d| d.replace(f.0));
1041    if old != 0 {
1042        unsafe { sk_runtime::redjs::ffi::redjs_unprotect(g, old) };
1043    }
1044    wake();
1045    Value::undefined().0
1046});
1047
1048// Returns a token, 0 for a name the embedder did not register (the shim rejects with the list it did).
1049host_fn!(fn sk_host_call(g, args) {
1050    let name = unsafe { sk_runtime::redjs::webapi::util::read_string(g, args.arg(0).0) }.unwrap_or_default();
1051    let call_args = unsafe { sk_runtime::redjs::webapi::util::read_string(g, args.arg(1).0) }
1052        .filter(|a| crate::json::parse(a).is_some())
1053        .unwrap_or_else(|| "[]".into());
1054    let Some(handler) = CONFIG.get().and_then(|c| c.functions.get(&name)).cloned() else {
1055        return Value::number(0.0).0;
1056    };
1057    let token = loop {
1058        let t = NEXT_TOKEN.fetch_add(1, Ordering::Relaxed);
1059        if t != 0 {
1060            break t;
1061        }
1062    };
1063    IN_FLIGHT.fetch_add(1, Ordering::AcqRel);
1064    let call = Call { name, args: call_args, reply: Reply { token, settled: false } };
1065    // A panic in the embedder's code rejects this call (via Reply's drop) rather than poisoning the runtime.
1066    if std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| handler(call))).is_err() {
1067        eprintln!("[embed] the host function behind appHost.call panicked");
1068    }
1069    Value::number(f64::from(token)).0
1070});
1071
1072host_fn!(fn sk_host_functions(_g, _args) {
1073    let mut names: Vec<&String> = CONFIG.get().map(|c| c.functions.keys().collect()).unwrap_or_default();
1074    names.sort();
1075    let json = crate::json::Json::arr(names.into_iter().map(|n| crate::json::Json::s(n.as_str())).collect()).to_json();
1076    JsRuntime::with(|rt| rt.ctx().string(&json)).0
1077});
1078
1079/// Embedded only: in the exe `__sk_host_*` do not exist and `appHost.available` is `false`.
1080pub(crate) fn install(rt: &JsRuntime) {
1081    if !active() {
1082        return;
1083    }
1084    rt.register(
1085        "__sk_host_set_dispatcher",
1086        1,
1087        sk_host_set_dispatcher as *const _,
1088    );
1089    rt.register("__sk_host_call", 2, sk_host_call as *const _);
1090    rt.register("__sk_host_functions", 0, sk_host_functions as *const _);
1091    let g = rt.raw();
1092    RT_G.store(g as usize, Ordering::Release);
1093    if let Some(id) = sk_runtime::redjs::context::id_of(g) {
1094        RT_ID.store(id.0, Ordering::Release);
1095        let _ = sk_runtime::redjs::web::waker(id);
1096    }
1097    sk_runtime::redjs::web::register_pump_source(sk_runtime::redjs::web::PumpSource {
1098        inflight: src_inflight,
1099        ready: src_ready,
1100        drain: src_drain,
1101    });
1102    if let Some(config) = CONFIG.get() {
1103        if let Err(e) = module::install(rt.ctx(), &config.modules, config.executor.clone()) {
1104            eprintln!("[embed] the native modules could not be installed: {e}");
1105        }
1106    }
1107}
1108
1109#[cfg(test)]
1110mod tests {
1111    use super::*;
1112
1113    fn drain_queue() -> Vec<(u32, bool, String)> {
1114        let mut q = QUEUE.lock().unwrap();
1115        let out = q
1116            .drain(..)
1117            .map(|i| match i {
1118                Item::Settle { token, ok, text } => (token, ok, text),
1119                Item::Event { json } => (0, true, json),
1120            })
1121            .collect();
1122        QUEUED.store(0, Ordering::Release);
1123        out
1124    }
1125
1126    #[test]
1127    fn payload_source_moves_builder_bytes_and_maps_files_without_cloning() {
1128        let bytes = vec![1, 2, 3, 4];
1129        let pointer = bytes.as_ptr();
1130        let mut builder = Builder::new().payload_bytes(bytes);
1131        let (owned, _, _) = builder.payload.take().unwrap().load().unwrap();
1132        let crate::payload::PayloadBytes::Owned(owned) = owned else {
1133            panic!("owned bytes expected")
1134        };
1135        assert_eq!(owned.as_ptr(), pointer);
1136        assert!(builder.payload.is_none());
1137        static STATIC_PAYLOAD: &[u8] = b"static payload bytes";
1138        let mut builder = Builder::new().payload_static(STATIC_PAYLOAD);
1139        let (borrowed, _, _) = builder.payload.take().unwrap().load().unwrap();
1140        let crate::payload::PayloadBytes::Embedded(borrowed) = borrowed else {
1141            panic!("static bytes expected")
1142        };
1143        assert_eq!(borrowed.as_ptr(), STATIC_PAYLOAD.as_ptr());
1144        assert_eq!(borrowed.len(), STATIC_PAYLOAD.len());
1145        let mut files = crate::mapped_file::tests::Files::new();
1146        let path = files.write("app.skpk", b"file bytes");
1147        let mut builder = Builder::new().payload_file(&path);
1148        let (mapped, _, dir) = builder.payload.take().unwrap().load().unwrap();
1149        let crate::payload::PayloadBytes::File(mapped) = mapped else {
1150            panic!("mapped file expected")
1151        };
1152        assert_eq!(mapped.as_bytes(), b"file bytes");
1153        assert_eq!(dir.as_deref(), path.parent());
1154        assert!(builder.payload.is_none());
1155        #[cfg(target_os = "windows")]
1156        assert!(std::fs::OpenOptions::new().write(true).open(&path).is_err());
1157        drop(mapped);
1158        std::fs::write(&path, b"released").unwrap();
1159    }
1160
1161    #[test]
1162    fn data_directory_override_and_preparation_precede_storage() {
1163        let base = std::env::temp_dir().join(format!(
1164            "sk-data-dir-{}-{}",
1165            std::process::id(),
1166            std::time::SystemTime::now()
1167                .duration_since(std::time::UNIX_EPOCH)
1168                .unwrap()
1169                .as_nanos()
1170        ));
1171        let configured = base.join("configured");
1172        let overridden = base.join("override");
1173        assert_eq!(
1174            resolve_data_dir(
1175                Some(configured.clone()),
1176                Some(overridden.clone().into_os_string())
1177            )
1178            .unwrap(),
1179            Some(overridden)
1180        );
1181        assert_eq!(
1182            resolve_data_dir(Some(configured.clone()), Some("".into())).unwrap(),
1183            Some(configured.clone())
1184        );
1185        assert_eq!(resolve_data_dir(None, None).unwrap(), None);
1186        assert!(resolve_data_dir(Some(PathBuf::from("relative")), None).is_err());
1187        assert!(prepare_directory(None, Some(Box::new(|_| Ok(())))).is_err());
1188        let refused = base.join("refused");
1189        assert!(prepare_directory(
1190            Some(&refused),
1191            Some(Box::new(|_| Err("migration refused".into())))
1192        )
1193        .is_err());
1194        assert!(!refused.exists());
1195        prepare_directory(
1196            Some(&configured),
1197            Some(Box::new(|path| {
1198                assert!(!path.exists());
1199                std::fs::create_dir_all(path).map_err(|e| e.to_string())?;
1200                std::fs::write(path.join("prepared"), "profile").map_err(|e| e.to_string())
1201            })),
1202        )
1203        .unwrap();
1204        assert_eq!(
1205            std::fs::read_to_string(configured.join("prepared")).unwrap(),
1206            "profile"
1207        );
1208        std::fs::remove_file(configured.join("prepared")).unwrap();
1209        std::fs::remove_dir(configured).unwrap();
1210        std::fs::remove_dir(base).unwrap();
1211    }
1212
1213    #[cfg(target_os = "macos")]
1214    #[test]
1215    fn appkit_rejects_worker_entry_before_startup_state_changes() {
1216        std::thread::spawn(|| {
1217            assert!(matches!(
1218                require_main_thread(),
1219                Err(Error::MainThreadRequired)
1220            ));
1221            assert!(matches!(
1222                Builder::new().spawn(),
1223                Err(Error::MainThreadRequired)
1224            ));
1225            assert!(matches!(
1226                Builder::new().run_on_main_thread(|_| 0),
1227                Err(Error::MainThreadRequired)
1228            ));
1229        })
1230        .join()
1231        .unwrap();
1232    }
1233
1234    #[test]
1235    fn setup_receives_installed_context_once_and_propagates_failure() {
1236        let called = Arc::new(AtomicUsize::new(0));
1237        let observed = called.clone();
1238        let hook = SetupHook(Mutex::new(Some(Box::new(move |ctx| {
1239            assert_eq!(
1240                ctx.storage_dir().ok(),
1241                HostContext::installed(None).storage_dir().ok()
1242            );
1243            observed.fetch_add(1, Ordering::SeqCst);
1244            Err("bootstrap refused".into())
1245        }))));
1246        assert_eq!(
1247            hook.run(&HostContext::installed(None)),
1248            Err("bootstrap refused".into())
1249        );
1250        assert!(hook.run(&HostContext::installed(None)).is_ok());
1251        assert_eq!(called.load(Ordering::SeqCst), 1);
1252        let panic = SetupHook(Mutex::new(Some(Box::new(|_| panic!("plugin panic")))));
1253        assert!(panic.run(&HostContext::installed(None)).is_err());
1254    }
1255
1256    // One test, because the queue is the process's.
1257    #[test]
1258    #[allow(deprecated)]
1259    fn replies_settle_once_and_a_dropped_one_rejects() {
1260        drain_queue();
1261        Reply {
1262            token: 7,
1263            settled: false,
1264        }
1265        .resolve(r#"{"a":1}"#);
1266        Reply {
1267            token: 8,
1268            settled: false,
1269        }
1270        .resolve("not json");
1271        Reply {
1272            token: 9,
1273            settled: false,
1274        }
1275        .reject("nope");
1276        drop(Reply {
1277            token: 10,
1278            settled: false,
1279        });
1280        let got = drain_queue();
1281        assert_eq!(got[0], (7, true, r#"{"a":1}"#.to_string()));
1282        assert_eq!(got[1].0, 8);
1283        assert!(!got[1].1);
1284        assert_eq!(got[2], (9, false, "nope".to_string()));
1285        assert_eq!(got[3].0, 10);
1286        assert!(!got[3].1);
1287
1288        let h = Handle { _private: () };
1289        assert_eq!(h.emit("x", "{bad"), Err(EmitError::NotJson));
1290        h.emit("status", r#"{"online":true}"#).unwrap();
1291        assert_eq!(
1292            drain_queue()[0].2,
1293            r#"{"event":"status","data":{"online":true}}"#
1294        );
1295    }
1296}