Update README for jail.

This commit is contained in:
Ivan Danyliuk 2017-09-15 14:16:43 +02:00
parent 8153d935d2
commit 704d271c64
No known key found for this signature in database
GPG Key ID: 97ED33CE024E1DBF
2 changed files with 75 additions and 77 deletions

View File

@ -1,103 +1,101 @@
# Package 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)
go:generate autoreadme -f Package jail implements "jailed" enviroment for executing arbitrary JavaScript code using Otto JS interpreter (https://github.com/robertkrimen/otto).
[![GoDoc](https://godoc.org/github.com/status-im/status-go/geth/jail?status.svg)](https://godoc.org/github.com/status-im/status-go/geth/jail)
Download:
```shell
go get github.com/status-im/status-go/geth/jail
```
--
* * *
go:generate autoreadme -f
import "github.com/status-im/status-go/geth/jail"
Package jail implements "jailed" enviroment for executing arbitrary JavaScript
code using Otto JS interpreter (https://github.com/robertkrimen/otto).
Package jail implements "jailed" enviroment 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
Otto VM Get and Set functions respectively. See Otto documentation for usage examples:
https://godoc.org/github.com/robertkrimen/otto
##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 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.
##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/`.
### 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.
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);`)
```
cell.Run(`setTimeout(function(){ value = "42" }, 2000);`)
```
will execute setTimeout and return immidiately, but callback function will be
executed after 2 seconds in the loop that was started upon current cell.
will execute setTimeout and return immidiately, 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:
err = cell.Set("__captureResponse", func(val string) otto.Value {
fmt.Println("Captured response from callback:", val)
return otto.UndefinedValue()
})
cell.Run(`setTimeout(function(){ __captureResponse("OK") }, 2000);`)
```
err = cell.Set("__captureResponse", func(val string) otto.Value {
fmt.Println("Captured response from callback:", val)
return otto.UndefinedValue()
})
cell.Run(`setTimeout(function(){ __captureResponse("OK") }, 2000);`)
```
##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:
```
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:
```
cell.Set("__captureSuccess", func(res otto.Value) { ... })
cell.Run(`fetch('http://example.com').then(function(r) {
return r.text()
}).then(function(data) {
// user code
__captureSuccess(data)
}))
```
### 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:
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:
cell.Set("__captureSuccess", func(res otto.Value) { ... })
cell.Run(`fetch('http://example.com').then(function(r) {
return r.text()
}).then(function(data) {
// user code
__captureSuccess(data)
}))
### Package documentation
See: [![GoDoc](https://godoc.org/github.com/status-im/status-go/geth/jail?status.svg)](https://godoc.org/github.com/status-im/status-go/geth/jail)
* * *
Automatically generated by [autoreadme](https://github.com/jimmyfrasche/autoreadme) on 2017.09.15

View File

@ -1,4 +1,4 @@
//go:generate godocdown -heading Title -o README.md
//go:generate autoreadme -f
/*
Package jail implements "jailed" enviroment for executing arbitrary
JavaScript code using Otto JS interpreter (https://github.com/robertkrimen/otto).