JavaScriptSandbox
@ThreadSafe
class JavaScriptSandbox : AutoCloseable
Sandbox that provides APIs for JavaScript evaluation in a restricted environment.
JavaScriptSandbox represents a connection to an isolated process. The isolated process is exclusive to the calling app (i.e. it doesn't share anything with, and can't be compromised by another app's isolated process).
Code that is run in a sandbox does not have any access to data belonging to the original app unless explicitly passed into it by using the methods of this class. This provides a security boundary between the calling app and the Javascript execution environment.
The calling app can have only one isolated process at a time, so only one instance of this class can be open at any given time.
It's safe to share a single JavaScriptSandbox object with multiple threads and use it from multiple threads at once. For example, JavaScriptSandbox can be stored at a global location and multiple threads can create their own JavaScriptIsolate objects from it but the JavaScriptIsolate object cannot be shared.
Summary
Constants |
|
|---|---|
const String! |
JS_FEATURE_CONSOLE_MESSAGING = "JS_FEATURE_CONSOLE_MESSAGING"Feature for |
const String! |
JS_FEATURE_EVALUATE_FROM_FD = "JS_FEATURE_EVALUATE_FROM_FD"Feature for |
const String! |
JS_FEATURE_EVALUATE_WITHOUT_TRANSACTION_LIMIT = "JS_FEATURE_EVALUATE_WITHOUT_TRANSACTION_LIMIT"Feature for |
const String! |
JS_FEATURE_ISOLATE_MAX_HEAP_SIZE = "JS_FEATURE_ISOLATE_MAX_HEAP_SIZE"Feature for |
const String! |
JS_FEATURE_ISOLATE_TERMINATION = "JS_FEATURE_ISOLATE_TERMINATION"Feature for |
const String! |
JS_FEATURE_PROMISE_RETURN = "JS_FEATURE_PROMISE_RETURN"Feature for |
const String! |
JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER = "JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER"Feature for |
const String! |
JS_FEATURE_WASM_COMPILATION = "JS_FEATURE_WASM_COMPILATION"Feature for |
Public functions |
|
|---|---|
Unit |
close()Closes the |
java-static ListenableFuture<JavaScriptSandbox!> |
createConnectedInstanceAsync(context: Context)Asynchronously create and connect to the sandbox process. |
JavaScriptIsolate |
Creates and returns a |
JavaScriptIsolate |
createIsolate(settings: IsolateStartupParameters)Creates and returns a |
Boolean |
isFeatureSupported(feature: String)Checks whether a given feature is supported by the JS Sandbox implementation. |
java-static Boolean |
Check if JavaScriptSandbox is supported on the system. |
Constants
JS_FEATURE_CONSOLE_MESSAGING
const val JS_FEATURE_CONSOLE_MESSAGING = "JS_FEATURE_CONSOLE_MESSAGING": String!
Feature for isFeatureSupported.
When this feature is present, setConsoleCallback can be used to set a JavaScriptConsoleCallback for processing console messages.
JS_FEATURE_EVALUATE_FROM_FD
const val JS_FEATURE_EVALUATE_FROM_FD = "JS_FEATURE_EVALUATE_FROM_FD": String!
Feature for isFeatureSupported.
When this feature is present, evaluateJavaScriptAsync and evaluateJavaScriptAsync can be used to evaluate JavaScript code of known and unknown length from file descriptors.
JS_FEATURE_EVALUATE_WITHOUT_TRANSACTION_LIMIT
const val JS_FEATURE_EVALUATE_WITHOUT_TRANSACTION_LIMIT = "JS_FEATURE_EVALUATE_WITHOUT_TRANSACTION_LIMIT": String!
Feature for isFeatureSupported.
When this feature is present, the script passed into evaluateJavaScriptAsync as well as the result/error is not limited by the Binder transaction buffer size.
JS_FEATURE_ISOLATE_MAX_HEAP_SIZE
const val JS_FEATURE_ISOLATE_MAX_HEAP_SIZE = "JS_FEATURE_ISOLATE_MAX_HEAP_SIZE": String!
Feature for isFeatureSupported.
When this feature is present, createIsolate can be used.
JS_FEATURE_ISOLATE_TERMINATION
const val JS_FEATURE_ISOLATE_TERMINATION = "JS_FEATURE_ISOLATE_TERMINATION": String!
Feature for isFeatureSupported.
When this feature is present, close terminates the currently running JS evaluation and close the isolate. If it is absent, close cannot terminate any running or queued evaluations in the background, so the isolate continues to consume resources until they complete.
Irrespective of this feature, calling close terminates all JavaScriptIsolate objects (and the isolated process) immediately and all pending evaluateJavaScriptAsync futures resolve with IsolateTerminatedException.
JS_FEATURE_PROMISE_RETURN
const val JS_FEATURE_PROMISE_RETURN = "JS_FEATURE_PROMISE_RETURN": String!
Feature for isFeatureSupported.
When this feature is present, JS expressions may return promises. The Future returned by evaluateJavaScriptAsync resolves to the promise's result, once the promise resolves.
JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER
const val JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER = "JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER": String!
Feature for isFeatureSupported. When this feature is present, provideNamedData can be used.
This also covers the JS API android.consumeNamedDataAsArrayBuffer(string).
JS_FEATURE_WASM_COMPILATION
const val JS_FEATURE_WASM_COMPILATION = "JS_FEATURE_WASM_COMPILATION": String!
Feature for isFeatureSupported.
This features provides additional behavior to evaluateJavaScriptAsync ()}. When this feature is present, the JS API WebAssembly.compile(ArrayBuffer) can be used.
Public functions
close
fun close(): Unit
Closes the JavaScriptSandbox object and renders it unusable.
The client is expected to call this method explicitly to terminate the isolated process.
Once closed, no more JavaScriptSandbox and JavaScriptIsolate method calls can be made. Closing terminates the isolated process immediately. All pending evaluations are immediately terminated. Once closed, the client may call createConnectedInstanceAsync to create another JavaScriptSandbox. You should still call close even if the sandbox has died, otherwise you will not be able to create a new one.
createConnectedInstanceAsync
java-static fun createConnectedInstanceAsync(context: Context): ListenableFuture<JavaScriptSandbox!>
Asynchronously create and connect to the sandbox process.
Only one sandbox process can exist at a time. Attempting to create a new instance before the previous instance has been closed fails with an IllegalStateException.
Sandbox support should be checked using isSupported before attempting to create a sandbox via this method.
| Parameters | |
|---|---|
context: Context |
the Context for the sandbox. Use an application context if the connection is expected to outlive a single activity or service. |
| Returns | |
|---|---|
ListenableFuture<JavaScriptSandbox!> |
a Future that evaluates to a connected |
createIsolate
fun createIsolate(): JavaScriptIsolate
Creates and returns a JavaScriptIsolate within which JS can be executed with default settings.
| Returns | |
|---|---|
JavaScriptIsolate |
a new JavaScriptIsolate |
createIsolate
fun createIsolate(settings: IsolateStartupParameters): JavaScriptIsolate
Creates and returns a JavaScriptIsolate within which JS can be executed with the specified settings.
If the sandbox is dead, this will still return an isolate, but evaluations will fail with SandboxDeadException.
| Parameters | |
|---|---|
settings: IsolateStartupParameters |
the configuration for the isolate |
| Returns | |
|---|---|
JavaScriptIsolate |
a new JavaScriptIsolate |
isFeatureSupported
fun isFeatureSupported(feature: String): Boolean
Checks whether a given feature is supported by the JS Sandbox implementation.
The sandbox implementation is provided by the version of WebView installed on the device. The app must use this method to check which library features are supported by the device's implementation before using them.
A feature check should be made prior to depending on certain features.
| Parameters | |
|---|---|
feature: String |
the feature to be checked |
| Returns | |
|---|---|
Boolean |
|
isSupported
java-static fun isSupported(): Boolean
Check if JavaScriptSandbox is supported on the system.
This method should be used to check for sandbox support before calling createConnectedInstanceAsync.
| Returns | |
|---|---|
Boolean |
true if JavaScriptSandbox is supported and false otherwise |