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](https://51degrees.com/img/logo.png?utm_source=docs.rs&utm_medium=docs&utm_campaign=rust&utm_content=fiftyone-javascript-builder-lib.rs&utm_term=logo "Data rewards the curious")](https://51degrees.com/?utm_source=docs.rs&utm_medium=docs&utm_campaign=rust&utm_content=fiftyone-javascript-builder-lib.rs&utm_term=logo)
24//!
25//! # 51Degrees JavaScript builder
26//!
27//! The JavaScript builder element renders a client-side JavaScript include from
28//! the JSON payload produced by the [`fiftyone_json_builder`] crate. The
29//! generated script creates a global manager object on the client device, runs
30//! any JavaScript-typed properties the JSON carries, and (when a callback URL is
31//! configured) posts the evidence it gathers back to the server for a refreshed
32//! result. It implements the
33//! [javascript-builder specification](https://github.com/51Degrees/specifications/blob/main/pipeline-specification/pipeline-elements/javascript-builder.md).
34//!
35//! ## The template
36//!
37//! The script is rendered from a single Mustache template,
38//! `JavaScriptResource.mustache`, embedded at compile time with `include_str!`.
39//! Rendering uses a small,
40//! pure-safe-Rust Mustache renderer (in this crate's `mustache` module) with
41//! HTML escaping disabled, so the JSON payload, the callback URL and the object
42//! name reach the client verbatim.
43//!
44//! ## Configuration and per-request overrides
45//!
46//! [`JavaScriptBuilderElementBuilder`] sets the host, endpoint, protocol, object
47//! name, cookie behavior and minification. Several of those can be overridden
48//! per request through evidence (`query.fod-js-object-name`,
49//! `query.fod-js-enable-cookies`, `header.host` and `header.protocol`). See
50//! [`JavaScriptBuilderElement`] for the full derivation rules.
51//!
52//! ## Minification
53//!
54//! With the default-on `minify` feature the rendered script is minified by the
55//! oxc toolchain (see the `minify` module). A minification failure falls back to
56//! the unminified script, so valid JavaScript is always served. The `set_minify`
57//! builder flag turns minification off for an element, and building the crate
58//! with `default-features = false` drops the oxc dependency entirely.
59//!
60//! ## A worked pipeline
61//!
62//! ```
63//! use std::sync::Arc;
64//! use fiftyone_pipeline_core::{Evidence, Pipeline};
65//! use fiftyone_json_builder::JsonBuilderElement;
66//! use fiftyone_javascript_builder::{JavaScriptBuilderElement, JAVASCRIPT_BUILDER_DATA_KEY};
67//!
68//! let pipeline = Pipeline::builder()
69//!     .add_element(Arc::new(JsonBuilderElement::new()))
70//!     .add_element(Arc::new(JavaScriptBuilderElement::new()))
71//!     .build()
72//!     .unwrap();
73//!
74//! let mut data = pipeline.create_flow_data_with(
75//!     Evidence::builder().add("header.host", "localhost").build(),
76//! );
77//! data.process().unwrap();
78//!
79//! let js = data.get(JAVASCRIPT_BUILDER_DATA_KEY).unwrap().javascript().to_owned();
80//! assert!(js.contains("fiftyoneDegreesManager"));
81//! ```
82
83#![warn(missing_docs)]
84
85mod builder;
86mod constants;
87mod data;
88mod element;
89mod minify;
90mod mustache;
91mod template_data;
92
93pub use builder::JavaScriptBuilderElementBuilder;
94pub use constants::{
95    BUILDER_DEFAULT_ENABLE_COOKIES, BUILDER_DEFAULT_HOST, BUILDER_DEFAULT_MINIFY,
96    BUILDER_DEFAULT_OBJECT_NAME, BUILDER_DEFAULT_PROTOCOL, EVIDENCE_ENABLE_COOKIES,
97    EVIDENCE_ENABLE_COOKIES_SUFFIX, EVIDENCE_HOST_KEY, EVIDENCE_OBJECT_NAME,
98    EVIDENCE_OBJECT_NAME_SUFFIX, FALLBACK_PROTOCOL, JAVASCRIPT_BUILDER_ELEMENT_DATA_KEY,
99    JAVASCRIPT_PROPERTY_KEY,
100};
101pub use data::{JavaScriptBuilderElementData, JAVASCRIPT_BUILDER_DATA_KEY};
102pub use element::JavaScriptBuilderElement;
103pub use template_data::JavaScriptResource;
fiftyone_javascript_builder/lib.rs

fiftyone_javascript_builder/
lib.rs
