fiftyone_javascript_builder/
lib.rs

1/* *********************************************************************
2 * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
3 * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
4 * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
5 *
6 * This Original Work is licensed under the European Union Public Licence
7 * (EUPL) v.1.2 and is subject to its terms as set out below.
8 *
9 * If a copy of the EUPL was not distributed with this file, You can obtain
10 * one at https://opensource.org/licenses/EUPL-1.2.
11 *
12 * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
13 * amended by the European Commission) shall be deemed incompatible for
14 * the purposes of the Work and the provisions of the compatibility
15 * clause in Article 5 of the EUPL shall not apply.
16 *
17 * If using the Work as, or as part of, a network application, by
18 * including the attribution notice(s) required under Article 5 of the EUPL
19 * in the end user terms of the application under an appropriate heading,
20 * such notice(s) shall fulfill the requirements of that article.
21 * ********************************************************************* */
22
23//! # 51Degrees JavaScript builder
24//!
25//! The JavaScript builder element renders a client-side JavaScript include from
26//! the JSON payload produced by the [`fiftyone_json_builder`] crate. The
27//! generated script creates a global manager object on the client device, runs
28//! any JavaScript-typed properties the JSON carries, and (when a callback URL is
29//! configured) posts the evidence it gathers back to the server for a refreshed
30//! result. It implements the
31//! [javascript-builder specification](https://github.com/51Degrees/specifications/blob/main/pipeline-specification/pipeline-elements/javascript-builder.md).
32//!
33//! ## The template
34//!
35//! The script is rendered from a single Mustache template,
36//! `JavaScriptResource.mustache`, embedded at compile time with `include_str!`.
37//! Rendering uses a small,
38//! pure-safe-Rust Mustache renderer (in this crate's `mustache` module) with
39//! HTML escaping disabled, so the JSON payload, the callback URL and the object
40//! name reach the client verbatim.
41//!
42//! ## Configuration and per-request overrides
43//!
44//! [`JavaScriptBuilderElementBuilder`] sets the host, endpoint, protocol, object
45//! name, cookie behavior and minification. Several of those can be overridden
46//! per request through evidence (`query.fod-js-object-name`,
47//! `query.fod-js-enable-cookies`, `header.host` and `header.protocol`). See
48//! [`JavaScriptBuilderElement`] for the full derivation rules.
49//!
50//! ## Minification
51//!
52//! With the default-on `minify` feature the rendered script is minified by the
53//! oxc toolchain (see the `minify` module). A minification failure falls back to
54//! the unminified script, so valid JavaScript is always served. The `set_minify`
55//! builder flag turns minification off for an element, and building the crate
56//! with `default-features = false` drops the oxc dependency entirely.
57//!
58//! ## A worked pipeline
59//!
60//! ```
61//! use std::sync::Arc;
62//! use fiftyone_pipeline_core::{Evidence, Pipeline};
63//! use fiftyone_json_builder::JsonBuilderElement;
64//! use fiftyone_javascript_builder::{JavaScriptBuilderElement, JAVASCRIPT_BUILDER_DATA_KEY};
65//!
66//! let pipeline = Pipeline::builder()
67//!     .add_element(Arc::new(JsonBuilderElement::new()))
68//!     .add_element(Arc::new(JavaScriptBuilderElement::new()))
69//!     .build()
70//!     .unwrap();
71//!
72//! let mut data = pipeline.create_flow_data_with(
73//!     Evidence::builder().add("header.host", "localhost").build(),
74//! );
75//! data.process().unwrap();
76//!
77//! let js = data.get(JAVASCRIPT_BUILDER_DATA_KEY).unwrap().javascript().to_owned();
78//! assert!(js.contains("fiftyoneDegreesManager"));
79//! ```
80
81#![warn(missing_docs)]
82
83mod builder;
84mod constants;
85mod data;
86mod element;
87mod minify;
88mod mustache;
89mod template_data;
90
91pub use builder::JavaScriptBuilderElementBuilder;
92pub use constants::{
93    BUILDER_DEFAULT_ENABLE_COOKIES, BUILDER_DEFAULT_HOST, BUILDER_DEFAULT_MINIFY,
94    BUILDER_DEFAULT_OBJECT_NAME, BUILDER_DEFAULT_PROTOCOL, EVIDENCE_ENABLE_COOKIES,
95    EVIDENCE_ENABLE_COOKIES_SUFFIX, EVIDENCE_HOST_KEY, EVIDENCE_OBJECT_NAME,
96    EVIDENCE_OBJECT_NAME_SUFFIX, FALLBACK_PROTOCOL, JAVASCRIPT_BUILDER_ELEMENT_DATA_KEY,
97    JAVASCRIPT_PROPERTY_KEY,
98};
99pub use data::{JavaScriptBuilderElementData, JAVASCRIPT_BUILDER_DATA_KEY};
100pub use element::JavaScriptBuilderElement;
101pub use template_data::JavaScriptResource;
fiftyone_javascript_builder/lib.rs

fiftyone_javascript_builder/
lib.rs
