Skip to main content

native_document/
native_document.rs

1//! Document-driver witness with a synthetic compiled guest, not a JavaScript engine.
2
3use std::cell::{Cell, RefCell};
4use std::collections::BTreeMap;
5use std::rc::Rc;
6use std::sync::Arc;
7use std::sync::atomic::{AtomicUsize, Ordering};
8use std::task::Context;
9
10use blitz_dom::{BaseDocument, Document, DocumentConfig};
11use blitz_script::native_host::{
12    NativeGuest, NativeHost, NativeIntrinsic, RealmScope, RetainedCallback,
13};
14use blitz_script::{
15    BoundScriptDocument, NativeHostDocumentBackend, ScriptDocumentBackend, ScriptKind,
16    TypedNativeGuest,
17};
18use blitz_traits::events::UiEvent;
19use url::Url;
20
21type Trace = Rc<RefCell<Vec<&'static str>>>;
22type Callback = RetainedCallback<u64, u64>;
23
24struct Guest {
25    trace: Trace,
26    storage: BTreeMap<String, i64>,
27    intrinsic: Option<NativeIntrinsic<Self>>,
28    callback: bool,
29    omit_write: bool,
30    intl: bool,
31}
32
33impl NativeGuest for Guest {
34    type Value = i64;
35    type RealmId = u64;
36    type CallbackId = u64;
37    type Error = &'static str;
38
39    fn scope(&self) -> RealmScope<u64> {
40        RealmScope::new(1, 1)
41    }
42    fn retain_callback(&mut self, value: &i64) -> Result<Callback, Self::Error> {
43        if *value != 7 || self.callback {
44            return Err("callback unavailable");
45        }
46        self.callback = true;
47        Ok(RetainedCallback::new(1, 1, 1))
48    }
49    fn release_callback(&mut self, callback: &Callback) -> Result<(), Self::Error> {
50        if !callback.is_current_in(&self.scope()) || !self.callback || *callback.callback() != 1 {
51            return Err("callback unavailable");
52        }
53        self.callback = false;
54        Ok(())
55    }
56    fn register_intrinsic(
57        &mut self,
58        name: &'static str,
59        arity: u8,
60        callback: NativeIntrinsic<Self>,
61    ) -> Result<(), Self::Error> {
62        if name != "paint" || arity != 1 {
63            return Err("unsupported intrinsic");
64        }
65        self.intrinsic = Some(callback);
66        Ok(())
67    }
68    fn invoke_retained_callback(
69        &mut self,
70        callback: &Callback,
71        args: &[i64],
72    ) -> Result<i64, Self::Error> {
73        if !callback.is_current_in(&self.scope()) || !self.callback || *callback.callback() != 1 {
74            return Err("callback unavailable");
75        }
76        self.intrinsic.ok_or("intrinsic unavailable")?(self, args)
77    }
78}
79
80impl NativeHost for Guest {
81    type Guest = Self;
82
83    fn guest(&self) -> &Self {
84        self
85    }
86
87    fn guest_mut(&mut self) -> &mut Self {
88        self
89    }
90}
91
92impl TypedNativeGuest for Guest {
93    fn supports_intl(&self) -> bool {
94        self.intl
95    }
96    fn install_document(&mut self, _: &mut BaseDocument) -> Result<(), Self::Error> {
97        self.trace.borrow_mut().push("install");
98        self.register_intrinsic("paint", 1, |_, args| {
99            args.first().copied().map(|v| v + 1).ok_or("missing value")
100        })
101    }
102    fn execute_source(
103        &mut self,
104        doc: &mut BaseDocument,
105        source: &str,
106        _: Option<&Url>,
107        kind: &ScriptKind,
108    ) -> Result<(), Self::Error> {
109        // This fixture has one precompiled entry. Unknown input is rejected,
110        // never interpreted or reported as successful JavaScript execution.
111        if source != "paint()" || *kind != ScriptKind::Classic {
112            return Err("unknown compiled fixture");
113        }
114        self.trace.borrow_mut().push("execute");
115        let seed = *self.storage.get("seed").ok_or("storage was not seeded")?;
116        let callback = self.retain_callback(&7)?;
117        let result = NativeHost::invoke_retained_callback(self, &callback, &[seed])
118            .map_err(|_| "compiled call failed")?;
119        self.release_callback(&callback)?;
120        if !self.omit_write {
121            let subject = doc
122                .query_selector("#subject")
123                .map_err(|_| "invalid selector")?
124                .ok_or("missing subject")?;
125            let text = *doc
126                .get_node(subject)
127                .ok_or("missing node")?
128                .children
129                .first()
130                .ok_or("missing text")?;
131            doc.mutate().set_node_text(text, &result.to_string());
132        }
133        Ok(())
134    }
135    fn install_import_map(&mut self, _: &str, _: Option<&Url>) -> Result<(), Self::Error> {
136        Err("import maps unsupported")
137    }
138    fn dispatch_ui_event(&mut self, _: &mut BaseDocument, _: UiEvent) -> Result<(), Self::Error> {
139        self.trace.borrow_mut().push("event");
140        Ok(())
141    }
142    fn poll(
143        &mut self,
144        _: &mut BaseDocument,
145        context: Option<Context>,
146    ) -> Result<bool, Self::Error> {
147        self.trace.borrow_mut().push("poll");
148        if let Some(context) = context {
149            context.waker().wake_by_ref();
150        }
151        Ok(true)
152    }
153    fn poll_for_settle(
154        &mut self,
155        _: &mut BaseDocument,
156        _: Option<Context>,
157        timers: bool,
158    ) -> Result<bool, Self::Error> {
159        self.trace
160            .borrow_mut()
161            .push(if timers { "timers" } else { "jobs" });
162        Ok(true)
163    }
164    fn prepare_teardown(&mut self, _: &mut BaseDocument) -> Result<(), Self::Error> {
165        self.trace.borrow_mut().push("teardown");
166        self.callback = false;
167        Ok(())
168    }
169    fn dispose_document(&mut self, _: &mut BaseDocument) -> Result<(), Self::Error> {
170        self.trace.borrow_mut().push("dispose");
171        Ok(())
172    }
173    fn finish_loading(&mut self, _: &mut BaseDocument) -> Result<(), Self::Error> {
174        self.trace.borrow_mut().push("ready");
175        Ok(())
176    }
177    fn set_page_visible(&mut self, _: &mut BaseDocument, _: bool) -> Result<(), Self::Error> {
178        self.trace.borrow_mut().push("visibility");
179        Ok(())
180    }
181    fn freeze(&mut self, _: &mut BaseDocument) -> Result<(), Self::Error> {
182        self.trace.borrow_mut().push("freeze");
183        Ok(())
184    }
185    fn finish_restore(&mut self, _: &mut BaseDocument) -> Result<(), Self::Error> {
186        self.trace.borrow_mut().push("restore");
187        Ok(())
188    }
189    fn resume(&mut self, _: &mut BaseDocument) -> Result<(), Self::Error> {
190        self.trace.borrow_mut().push("resume");
191        Ok(())
192    }
193    fn storage_get(&mut self, key: &str) -> Result<Option<i64>, Self::Error> {
194        Ok(self.storage.get(key).copied())
195    }
196    fn storage_set(&mut self, key: &str, value: i64) -> Result<(), Self::Error> {
197        self.storage.insert(key.to_owned(), value);
198        Ok(())
199    }
200    fn storage_remove(&mut self, key: &str) -> Result<(), Self::Error> {
201        self.storage.remove(key);
202        Ok(())
203    }
204    fn storage_clear(&mut self) -> Result<(), Self::Error> {
205        self.storage.clear();
206        Ok(())
207    }
208}
209
210fn guest(trace: &Trace, intl: bool) -> Guest {
211    Guest {
212        trace: Rc::clone(trace),
213        storage: BTreeMap::new(),
214        intrinsic: None,
215        callback: false,
216        omit_write: std::env::args().any(|arg| arg == "--omit-dom-write"),
217        intl,
218    }
219}
220
221type Page = BoundScriptDocument<Guest, Guest>;
222
223struct WakeCount(AtomicUsize);
224
225impl std::task::Wake for WakeCount {
226    fn wake(self: Arc<Self>) {
227        self.0.fetch_add(1, Ordering::Relaxed);
228    }
229    fn wake_by_ref(self: &Arc<Self>) {
230        self.0.fetch_add(1, Ordering::Relaxed);
231    }
232}
233
234fn main() {
235    let trace = Rc::new(RefCell::new(Vec::new()));
236    let html = Arc::from(
237        "<output id=subject>pending</output><template><script src='inert.js'>inert</script></template><script nomodule src='legacy.js'>inert</script><script type=application/json>inert</script><script>paint()</script><script src='data:text/javascript,paint()'></script>",
238    );
239    let mut page = Page::from_html(html, DocumentConfig::default()).expect("parse fixture");
240    assert_eq!(
241        blitz_script::external_script_urls(&page.inner()),
242        vec![Url::parse("data:text/javascript,paint()").unwrap()]
243    );
244    assert!(
245        page.execute_scripts().is_err(),
246        "unbound execution must fail"
247    );
248    page.attach_native_host(guest(&trace, true))
249        .expect("bind compiled guest");
250    page.storage_set("seed", 8).expect("seed before scripts");
251    page.execute_scripts().expect("execute compiled fixture");
252    page.execute_scripts().expect("bootstrap is idempotent");
253    let subject = page.inner().query_selector("#subject").unwrap().unwrap();
254    assert_eq!(
255        page.inner().get_node(subject).unwrap().text_content(),
256        "9",
257        "rendered-bootstrap"
258    );
259    assert_eq!(
260        &*trace.borrow(),
261        &["install", "execute", "execute", "ready"],
262        "script-order-and-inert-subtrees"
263    );
264    page.handle_ui_event(UiEvent::AppleStandardKeybinding("selectAll:".into()));
265    page.set_page_visible(false);
266    page.freeze();
267    assert!(!page.poll(None), "frozen guest must not run");
268    page.resume();
269    page.finish_restore();
270    let wakes = Arc::new(WakeCount(AtomicUsize::new(0)));
271    let waker = std::task::Waker::from(Arc::clone(&wakes));
272    assert!(page.poll(Some(Context::from_waker(&waker))));
273    assert_eq!(
274        wakes.0.load(Ordering::Relaxed),
275        1,
276        "document-waker-propagation"
277    );
278    assert!(page.poll_for_settle(None, false));
279    assert!(page.poll_for_settle(None, true));
280    assert_eq!(
281        &trace.borrow()[4..],
282        &[
283            "event",
284            "visibility",
285            "freeze",
286            "resume",
287            "restore",
288            "poll",
289            "jobs",
290            "timers"
291        ],
292        "lifecycle-and-timer-policy"
293    );
294    assert_eq!(page.storage_get("seed").unwrap(), Some(8));
295    page.storage_remove("seed").unwrap();
296    assert_eq!(page.storage_get("seed").unwrap(), None);
297    page.storage_set("seed", 3).unwrap();
298    page.storage_clear().unwrap();
299    assert_eq!(page.storage_get("seed").unwrap(), None);
300
301    page.with_guest_mut(|guest, document| {
302        assert!(guest.storage.is_empty());
303        assert_eq!(document.query_selector("#subject").unwrap(), Some(subject));
304    })
305    .unwrap();
306    let hook_order = Rc::new(RefCell::new(Vec::new()));
307    let nested_installed = Rc::new(Cell::new(false));
308    let retire = Rc::new(Cell::new(false));
309    let hook_wakes = Rc::new(Cell::new(0));
310    for index in [1, 2] {
311        let order = Rc::clone(&hook_order);
312        let installed = Rc::clone(&nested_installed);
313        let retire = Rc::clone(&retire);
314        let wakes = Rc::clone(&hook_wakes);
315        page.add_poll_hook(Box::new(move |document, context| {
316            order.borrow_mut().push(index);
317            if context.is_some() {
318                wakes.set(wakes.get() + 1);
319            }
320            if index == 1 && !installed.replace(true) {
321                let nested_order = Rc::clone(&order);
322                (document as &mut dyn std::any::Any)
323                    .downcast_mut::<Page>()
324                    .unwrap()
325                    .add_poll_hook(Box::new(move |_, _| {
326                        nested_order.borrow_mut().push(3);
327                        false
328                    }))
329                    .unwrap();
330            }
331            if index == 1 && retire.get() {
332                document.prepare_teardown();
333            }
334            index == 1
335        }))
336        .unwrap();
337    }
338    assert!(page.poll(None));
339    assert_eq!(&*hook_order.borrow(), &[1, 2]);
340    assert!(page.poll_for_settle(Some(Context::from_waker(&waker)), false));
341    assert_eq!(&*hook_order.borrow(), &[1, 2, 1, 2, 3]);
342    assert_eq!(hook_wakes.get(), 2);
343    retire.set(true);
344    assert!(!page.poll(None));
345    assert_eq!(&*hook_order.borrow(), &[1, 2, 1, 2, 3, 1]);
346    assert!(page.guest().is_none());
347    assert!(page.add_poll_hook(Box::new(|_, _| true)).is_err());
348    page.prepare_teardown();
349    let calls = trace.borrow().len();
350    assert!(!page.poll(None));
351    assert!(page.execute_scripts().is_err());
352    assert!(page.storage_set("seed", 1).is_err());
353    page.handle_ui_event(UiEvent::AppleStandardKeybinding("selectAll:".into()));
354    assert_eq!(trace.borrow().len(), calls, "retired-guest-entry");
355    drop(page);
356    assert_eq!(
357        trace.borrow().iter().filter(|&&v| v == "teardown").count(),
358        1
359    );
360    assert_eq!(trace.borrow().last(), Some(&"dispose"));
361    let drop_trace = Rc::new(RefCell::new(Vec::new()));
362    let page = Page::new_bound(
363        Arc::from("<p>plain</p>"),
364        DocumentConfig::default(),
365        guest(&drop_trace, true),
366    )
367    .unwrap();
368    drop(page);
369    assert_eq!(
370        &*drop_trace.borrow(),
371        &["install", "teardown", "dispose"],
372        "drop-cleanup"
373    );
374    #[cfg(feature = "intl")]
375    {
376        let mut page = Page::new_bound(
377            Arc::from("<script>paint()</script>"),
378            DocumentConfig::default(),
379            guest(&drop_trace, false),
380        )
381        .unwrap();
382        assert!(page.execute_scripts().unwrap_err().contains("Intl"));
383    }
384    println!(
385        "PASS bound document driver: compiled fixture, DOM, storage, lifecycle and teardown; no JavaScript engine claimed"
386    );
387}