From fffd60d675ee00f28934364e8d75babda3f059b7 Mon Sep 17 00:00:00 2001 From: Ivan Daniluk Date: Fri, 1 Sep 2017 20:18:09 +0200 Subject: [PATCH] Add docs for Jail package (#285) --- geth/jail/README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++ geth/jail/doc.go | 63 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 135 insertions(+) create mode 100644 geth/jail/README.md create mode 100644 geth/jail/doc.go diff --git a/geth/jail/README.md b/geth/jail/README.md new file mode 100644 index 000000000..fdab0e937 --- /dev/null +++ b/geth/jail/README.md @@ -0,0 +1,72 @@ +# Package jail +-- + + import "github.com/status-im/status-go/geth/jail" + +[![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) + +Package jail implements "jailed" enviroment for executing arbitrary JavaScript +code using Otto JS interpreter (https://github.com/robertkrimen/otto). + +Jail create multiple JailCells, 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 || + ++-------++ ++-------++ ++-------++ ++-------++ + + +# Get and Set + +(*JailCell).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 + +(*JailCell).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. + + +# 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 +http://github.com/deoxxa/ottoext/timers and +http://github.com/deoxxa/ottoext/loop packages. + +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 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);`) + + +# Fetch support + +### TBD diff --git a/geth/jail/doc.go b/geth/jail/doc.go new file mode 100644 index 000000000..486e527fd --- /dev/null +++ b/geth/jail/doc.go @@ -0,0 +1,63 @@ +/* +Package jail implements "jailed" enviroment for executing arbitrary +JavaScript code using Otto JS interpreter (https://github.com/robertkrimen/otto). + +Jail create multiple JailCells, 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 || + ++-------++ ++-------++ ++-------++ ++-------++ + + +Get and Set + +(*JailCell).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 + +(*JailCell).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. + +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 http://github.com/deoxxa/ottoext/timers and http://github.com/deoxxa/ottoext/loop +packages. + +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 +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);`) + +Fetch support + +TBD +*/ +package jail