davsclaus commented on code in PR #25778:
URL: https://github.com/apache/camel/pull/25778#discussion_r3873030754
##########
components/camel-quickjs/src/main/docs/quickjs-language.adoc:
##########
@@ -0,0 +1,171 @@
+= QuickJS Language
+:doctitle: QuickJS
+:shortname: quickjs
+:artifactid: camel-quickjs
+:description: Evaluates a JavaScript expression using QuickJS4J
+:since: 4.23
+:supportlevel: Preview
+:tabs-sync-option:
+
+*Since Camel {since}*
+
+The QuickJS language evaluates JavaScript as an
xref:manual::expression.adoc[Expression] or
+xref:manual::predicate.adoc[Predicate] in Camel routes.
+
+`camel-javascript` provides GraalVM JavaScript with Java interoperability,
while `camel-quickjs`
+provides a lightweight pure-Java JavaScript runtime using QuickJS4J and
JSON-based data exchange.
+
+QuickJS4J compiles QuickJS to WebAssembly and runs it as Java bytecode through
Endive (the successor
+to Chicory). There is no JNI and no native library. Native-image compatibility
and
+architecture-specific support have not been validated as part of this module.
+
+Do not treat this language as a drop-in replacement for
xref:js-language.adoc[JavaScript]. The
+scripting APIs and Exchange bindings are different.
+
+For example, you can use QuickJS in a xref:manual::predicate.adoc[Predicate]
with the
+xref:eips:choice-eip.adoc[Content-Based Router] EIP.
+
+== QuickJS Options
+
+// language options: START
+include::partial$language-options.adoc[]
+// language options: END
+
+== Variables
+
+The following variables are bound for each evaluation. Values are JSON
snapshots, not live Java
+objects. This data-only binding is the intended Preview design: there is no
host-object bridge to
+live `Exchange`, `Message`, or `CamelContext` instances.
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Variable |Type |Description
+|body |JSON value |the message body after JSON conversion
+|headers |Object |the message headers after JSON conversion
+|properties |Object |the exchange properties after JSON conversion
+|exchangeId |String |the exchange id
+|=======================================================================
+
+`message`, `exchange`, and `context` are not bound. Scripts that refer to them
raise a JavaScript
+`ReferenceError`.
+
+The following is *not* supported:
+
+[source,javascript]
+----
+exchange.getMessage().setHeader('foo', 'bar')
+----
+
+Assigning to `headers` or `body` inside a script changes only the JavaScript
snapshot. It does not
+mutate the Camel `Exchange`. Use the expression result (for example
`.transform().quickjs(...)`)
+when you need to change the message body.
+
+The generic `ScriptingLanguage.evaluate(script, bindings, resultType)` API
uses caller-supplied
+map keys as JavaScript function parameters. Those keys must be valid
JavaScript identifiers
+(for example `body` or `foo_bar`). Names such as `foo-bar`, `123foo`, or
reserved words such as
+`for` are rejected with a Camel evaluation exception rather than a raw
JavaScript `SyntaxError`.
+Route expressions do not use this map.
+
+== Data types
+
+Values cross the Java/JavaScript boundary as JSON:
+
+* `null`, string, boolean, and number pass through.
+* `Map` becomes a JavaScript object. Header and property names are strings, so
+ `headers.MyHeader` and `headers['MyHeader']` both work.
+* `List` and arrays become JavaScript arrays.
+* `byte[]` becomes a Base64 JSON string. `char[]` becomes a JSON string.
+* Other Java types are serialized with Jackson into a JSON object or array
snapshot.
+ Java methods such as `getAge()` are not callable from JavaScript; use JSON
fields
+ such as `body.age`.
+* `Exchange`, `Message`, `CamelContext`, `Class`, and `ClassLoader` values are
rejected
+ when they appear as the message body, with an evaluation error. They are
never passed
+ into the script.
+* Streaming bodies (`InputStream`, `Reader`, and Camel `StreamCache`) are
rejected with
+ an evaluation error. The stream is not read, closed, or otherwise consumed.
+* Header and property values that cannot be JSON-serialized (including Camel
internals
+ and streaming values) are omitted from the JavaScript snapshot so evaluation
can still
+ use the remaining data.
+
+Serialization failures of the message body raise a Camel evaluation exception
that names
+the unsupported type.
+
+== Expression and predicate
+
+As an expression, the JavaScript value of the script becomes the Camel result
(then converted
+with Camel type converters when a result type is requested).
+
+As a predicate (`.when().quickjs(...)` or `.filter().quickjs(...)`), the
result is converted to
+boolean with Camel's standard `ObjectHelper.evaluateValuePredicate` rules: a
`Boolean` is used
+directly; the strings `true`/`false` are parsed; any other non-empty, non-null
value is true.
+
+== Security
+
+JavaScript runs in the QuickJS4J sandbox. The runtime does not expose Java
classes, reflection,
+class loaders, or live Camel objects. WASI has no filesystem or network
preopens. Stdout from
+scripts is discarded so a reused engine does not accumulate output.
Per-evaluation stderr is
+captured into Camel exceptions (for example `ReferenceError`) and then cleared
so later
+evaluations do not include stale error output.
+
+QuickJS4J host plumbing is not available to user scripts: `java_invoke` throws
a
Review Comment:
Minor precision note: this says host plumbing is "not available to user
scripts," but per
`QuickjsLanguageSecurityTest.javaInvokeHostPlumbingIsNotInScriptScope`, `typeof
java_invoke` still resolves to `"function"` (a stub that throws `TypeError`
when called), rather than being absent from scope. Functionally equivalent and
not a security gap — just slightly imprecise wording if a future reader takes
"not available" to mean the identifier itself is unreachable.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
