Update jail README (#626)
This commit is contained in:
parent
4cddc362ac
commit
3c83c93039
|
@ -1,5 +1,5 @@
|
|||
# jail [![GoDoc](https://godoc.org/github.com/status-im/status-go/geth/jail?status.png)](https://godoc.org/github.com/status-im/status-go/geth/jail)
|
||||
jail - jailed enviroment for executing JS code.
|
||||
jail - jailed environment for executing JS code.
|
||||
|
||||
Download:
|
||||
```shell
|
||||
|
@ -7,9 +7,9 @@ go get github.com/status-im/status-go/geth/jail
|
|||
```
|
||||
|
||||
* * *
|
||||
jail - jailed enviroment for executing JS code.
|
||||
jail - jailed environment for executing JS code.
|
||||
|
||||
Package jail implements "jailed" enviroment for executing arbitrary
|
||||
Package jail implements "jailed" environment for executing arbitrary
|
||||
JavaScript code using Otto JS interpreter (https://github.com/robertkrimen/otto).
|
||||
|
||||
Jail create multiple Cells, one cell per status client chat. Each cell runs own
|
||||
|
@ -29,29 +29,27 @@ Otto virtual machine and lives forever, but that may change in the future.
|
|||
++-------++ ++-------++ ++-------++ ++-------++
|
||||
```
|
||||
|
||||
##Cells
|
||||
## Cells
|
||||
Each Cell object embeds *VM from 'jail/vm' for concurrency safe wrapper around
|
||||
*otto.VM functions. This is important when dealing with setTimeout and Fetch API
|
||||
functions (see below).
|
||||
|
||||
##Get and Set
|
||||
## Get and Set
|
||||
(*VM).Get/Set functions provide transparent and concurrently safe wrappers for
|
||||
Otto VM Get and Set functions respectively. See Otto documentation for usage examples:
|
||||
https://godoc.org/github.com/robertkrimen/otto
|
||||
|
||||
##Call and Run
|
||||
## Call and Run
|
||||
(*VM).Call/Run functions allows executing arbitrary JS in the cell. They're also
|
||||
wrappers arount Otto VM functions of the same name. Run accepts raw JS strings for execution,
|
||||
Call takes a JS function name (defined in VM) and parameters.
|
||||
wrappers around Otto VM functions of the same name. `Run` accepts raw JS strings for execution while `Call` takes a JS function name (defined in VM) and parameters.
|
||||
|
||||
##Timeouts and intervals support
|
||||
Default Otto VM interpreter doesn't support setTimeout()/setInterval() JS functions,
|
||||
## Timeouts and intervals support
|
||||
Default Otto VM interpreter doesn't support setTimeout() / setInterval() JS functions,
|
||||
because they're not part of ECMA-262 spec, but properties of the window object in browser.
|
||||
We add support for them using own implementation of Event Loop, heavily based on http://github.com/status-im/ottoext package. See loop/fetch/promise packages under `jail/internal/`.
|
||||
|
||||
Each cell starts a new loop in a separate goroutine, registers functions for setTimeout/setInterval
|
||||
calls and associate them with this loop. All JS code executed as callback to setTimeout/setInterval
|
||||
will be handled by this loop.
|
||||
We add support for them using own implementation of Event Loop, heavily based on [ottoext package](https://github.com/deoxxa/ottoext). See loop/fetch/promise packages under [jail/internal/](https://github.com/status-im/status-go/tree/develop/geth/jail/internal).
|
||||
|
||||
Each cell starts a new loop in a separate goroutine, registers functions for setTimeout / setInterval calls and associate them with this loop. All JS code executed as callback to setTimeout/setInterval will be handled by this loop.
|
||||
|
||||
For example, following code:
|
||||
|
||||
|
@ -59,7 +57,7 @@ For example, following code:
|
|||
cell.Run(`setTimeout(function(){ value = "42" }, 2000);`)
|
||||
```
|
||||
|
||||
will execute setTimeout and return immidiately, but callback function will
|
||||
will execute setTimeout and return immediately, but callback function will
|
||||
be executed after 2 seconds in the loop that was started upon current cell.
|
||||
|
||||
In order to capture response one may use following approach:
|
||||
|
@ -72,7 +70,8 @@ err = cell.Set("__captureResponse", func(val string) otto.Value {
|
|||
cell.Run(`setTimeout(function(){ __captureResponse("OK") }, 2000);`)
|
||||
```
|
||||
|
||||
##Fetch support
|
||||
## Fetch support
|
||||
|
||||
Fetch API is implemented in a similar way using the same loop. When Cell is created, corresponding handlers are registered within VM and associated event loop.
|
||||
|
||||
Due to asynchronous nature of Fetch API, the following code will return immediately:
|
||||
|
@ -81,8 +80,7 @@ Due to asynchronous nature of Fetch API, the following code will return immediat
|
|||
cell.Run(`fetch('http://example.com/').then(function(data) { ... })`)
|
||||
```
|
||||
|
||||
and callback function in a promise will be executed in a event loop in the background. Thus,
|
||||
it's user responsibility to register a corresponding callback function before:
|
||||
and callback function in a promise will be executed in a event loop in the background. Thus, it's user responsibility to register a corresponding callback function before:
|
||||
|
||||
```
|
||||
cell.Set("__captureSuccess", func(res otto.Value) { ... })
|
||||
|
@ -98,4 +96,4 @@ cell.Run(`fetch('http://example.com').then(function(r) {
|
|||
|
||||
|
||||
* * *
|
||||
Automatically generated by [autoreadme](https://github.com/jimmyfrasche/autoreadme) on 2017.09.15
|
||||
Automatically generated by [autoreadme](https://github.com/jimmyfrasche/autoreadme) on 2018.02.08
|
||||
|
|
|
@ -1,57 +1,51 @@
|
|||
/*
|
||||
jail - jailed enviroment for executing JS code.
|
||||
jail - jailed environment for executing JS code.
|
||||
|
||||
Package jail implements "jailed" enviroment for executing arbitrary
|
||||
Package jail implements "jailed" environment for executing arbitrary
|
||||
JavaScript code using Otto JS interpreter (https://github.com/robertkrimen/otto).
|
||||
|
||||
Jail create multiple Cells, one cell per status client chat. Each cell runs own
|
||||
Otto virtual machine and lives forever, but that may change in the future.
|
||||
|
||||
+----------------------------------------------+
|
||||
| Jail |
|
||||
+----------------------------------------------+
|
||||
+---------+ +---------+ +---------+ +---------+
|
||||
| Cell | | Cell | | Cell | | Cell |
|
||||
|ChatID 1 | |ChatID 2 | |ChatID 3 | |ChatID N |
|
||||
|+-------+| |+-------+| |+-------+| |+-------+|
|
||||
||Otto VM|| ||Otto VM|| ||Otto VM|| ||Otto VM||
|
||||
|+-------+| |+-------+| |+-------+| |+-------+|
|
||||
|| Loop || || Loop || || Loop || || Loop ||
|
||||
++-------++ ++-------++ ++-------++ ++-------++
|
||||
|
||||
Cells
|
||||
+----------------------------------------------+
|
||||
| Jail |
|
||||
+----------------------------------------------+
|
||||
+---------+ +---------+ +---------+ +---------+
|
||||
| Cell | | Cell | | Cell | | Cell |
|
||||
|ChatID 1 | |ChatID 2 | |ChatID 3 | |ChatID N |
|
||||
|+-------+| |+-------+| |+-------+| |+-------+|
|
||||
||Otto VM|| ||Otto VM|| ||Otto VM|| ||Otto VM||
|
||||
|+-------+| |+-------+| |+-------+| |+-------+|
|
||||
|| Loop || || Loop || || Loop || || Loop ||
|
||||
++-------++ ++-------++ ++-------++ ++-------++
|
||||
|
||||
## Cells
|
||||
Each Cell object embeds *VM from 'jail/vm' for concurrency safe wrapper around
|
||||
*otto.VM functions. This is important when dealing with setTimeout and Fetch API
|
||||
functions (see below).
|
||||
|
||||
Get and Set
|
||||
|
||||
## Get and Set
|
||||
(*VM).Get/Set functions provide transparent and concurrently safe wrappers for
|
||||
Otto VM Get and Set functions respectively. See Otto documentation for usage examples:
|
||||
https://godoc.org/github.com/robertkrimen/otto
|
||||
|
||||
Call and Run
|
||||
|
||||
## Call and Run
|
||||
(*VM).Call/Run functions allows executing arbitrary JS in the cell. They're also
|
||||
wrappers arount Otto VM functions of the same name. Run accepts raw JS strings for execution,
|
||||
Call takes a JS function name (defined in VM) and parameters.
|
||||
wrappers around Otto VM functions of the same name. `Run` accepts raw JS strings for execution while `Call` takes a JS function name (defined in VM) and parameters.
|
||||
|
||||
Timeouts and intervals support
|
||||
|
||||
Default Otto VM interpreter doesn't support setTimeout()/setInterval() JS functions,
|
||||
## Timeouts and intervals support
|
||||
Default Otto VM interpreter doesn't support setTimeout() / setInterval() JS functions,
|
||||
because they're not part of ECMA-262 spec, but properties of the window object in browser.
|
||||
We add support for them using own implementation of Event Loop, heavily based on http://github.com/status-im/ottoext package. See loop/fetch/promise packages under `jail/internal/`.
|
||||
|
||||
Each cell starts a new loop in a separate goroutine, registers functions for setTimeout/setInterval
|
||||
calls and associate them with this loop. All JS code executed as callback to setTimeout/setInterval
|
||||
will be handled by this loop.
|
||||
We add support for them using own implementation of Event Loop, heavily based on [ottoext package](https://github.com/deoxxa/ottoext). See loop/fetch/promise packages under [jail/internal/](https://github.com/status-im/status-go/tree/develop/geth/jail/internal).
|
||||
|
||||
Each cell starts a new loop in a separate goroutine, registers functions for setTimeout / setInterval calls and associate them with this loop. All JS code executed as callback to setTimeout/setInterval will be handled by this loop.
|
||||
|
||||
For example, following code:
|
||||
|
||||
cell.Run(`setTimeout(function(){ value = "42" }, 2000);`)
|
||||
|
||||
will execute setTimeout and return immidiately, but callback function will
|
||||
will execute setTimeout and return immediately, but callback function will
|
||||
be executed after 2 seconds in the loop that was started upon current cell.
|
||||
|
||||
In order to capture response one may use following approach:
|
||||
|
@ -62,7 +56,7 @@ In order to capture response one may use following approach:
|
|||
})
|
||||
cell.Run(`setTimeout(function(){ __captureResponse("OK") }, 2000);`)
|
||||
|
||||
Fetch support
|
||||
## Fetch support
|
||||
|
||||
Fetch API is implemented in a similar way using the same loop. When Cell is created, corresponding handlers are registered within VM and associated event loop.
|
||||
|
||||
|
@ -70,8 +64,7 @@ Due to asynchronous nature of Fetch API, the following code will return immediat
|
|||
|
||||
cell.Run(`fetch('http://example.com/').then(function(data) { ... })`)
|
||||
|
||||
and callback function in a promise will be executed in a event loop in the background. Thus,
|
||||
it's user responsibility to register a corresponding callback function before:
|
||||
and callback function in a promise will be executed in a event loop in the background. Thus, it's user responsibility to register a corresponding callback function before:
|
||||
|
||||
cell.Set("__captureSuccess", func(res otto.Value) { ... })
|
||||
|
||||
|
|
Loading…
Reference in New Issue