status-im/status-go
2
0
Fork 0
mirror of https://github.com/status-im/status-go.git synced 2025-02-19 18:28:18 +00:00
Code Issues Projects Releases Wiki Activity

Update jail README (#626)

Browse Source
This commit is contained in:
Adrià Cidre 2018-02-09 01:25:17 +01:00 committed by Ivan Daniluk
parent 4cddc362ac
commit 3c83c93039
2 changed files with 42 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
geth/jail/README.md
View File

@ -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 [![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: Download:
```shell ```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). 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 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 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 *otto.VM functions. This is important when dealing with setTimeout and Fetch API
functions (see below). functions (see below).
##Get and Set ## Get and Set
(*VM).Get/Set functions provide transparent and concurrently safe wrappers for (*VM).Get/Set functions provide transparent and concurrently safe wrappers for
Otto VM Get and Set functions respectively. See Otto documentation for usage examples: Otto VM Get and Set functions respectively. See Otto documentation for usage examples:
https://godoc.org/github.com/robertkrimen/otto 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 (*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, 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.
Call takes a JS function name (defined in VM) and parameters.
##Timeouts and intervals support ## Timeouts and intervals support
Default Otto VM interpreter doesn't support setTimeout()/setInterval() JS functions, 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. 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 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).
calls and associate them with this loop. All JS code executed as callback to setTimeout/setInterval
will be handled by this loop. 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: For example, following code:
@ -59,7 +57,7 @@ For example, following code:
cell.Run(`setTimeout(function(){ value = "42" }, 2000);`) 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. be executed after 2 seconds in the loop that was started upon current cell.
In order to capture response one may use following approach: 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);`) 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. 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: 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) { ... })`) 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, 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:
it's user responsibility to register a corresponding callback function before:
``` ```
cell.Set("__captureSuccess", func(res otto.Value) { ... }) 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

35
geth/jail/doc.go
View File

@ -1,7 +1,7 @@
/* /*
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). 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 Jail create multiple Cells, one cell per status client chat. Each cell runs own
@ -19,39 +19,33 @@ Otto virtual machine and lives forever, but that may change in the future.
|| Loop || || Loop || || Loop || || Loop || || Loop || || Loop || || Loop || || Loop ||
++-------++ ++-------++ ++-------++ ++-------++ ++-------++ ++-------++ ++-------++ ++-------++
Cells ## Cells
Each Cell object embeds *VM from 'jail/vm' for concurrency safe wrapper around 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 *otto.VM functions. This is important when dealing with setTimeout and Fetch API
functions (see below). functions (see below).
Get and Set ## Get and Set
(*VM).Get/Set functions provide transparent and concurrently safe wrappers for (*VM).Get/Set functions provide transparent and concurrently safe wrappers for
Otto VM Get and Set functions respectively. See Otto documentation for usage examples: Otto VM Get and Set functions respectively. See Otto documentation for usage examples:
https://godoc.org/github.com/robertkrimen/otto 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 (*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, 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.
Call takes a JS function name (defined in VM) and parameters.
Timeouts and intervals support ## Timeouts and intervals support
Default Otto VM interpreter doesn't support setTimeout() / setInterval() JS functions,
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. 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 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).
calls and associate them with this loop. All JS code executed as callback to setTimeout/setInterval
will be handled by this loop. 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: For example, following code:
cell.Run(`setTimeout(function(){ value = "42" }, 2000);`) 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. be executed after 2 seconds in the loop that was started upon current cell.
In order to capture response one may use following approach: 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);`) 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. 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) { ... })`) 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, 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:
it's user responsibility to register a corresponding callback function before:
cell.Set("__captureSuccess", func(res otto.Value) { ... }) cell.Set("__captureSuccess", func(res otto.Value) { ... })