1*ec63e07aSXin Li# LibUV Sandbox 2*ec63e07aSXin Li 3*ec63e07aSXin LiThis library is a sandboxed version of [LibUV](https://libuv.org/), implemented 4*ec63e07aSXin Liusing Sandboxed API. 5*ec63e07aSXin Li 6*ec63e07aSXin Li## Setup 7*ec63e07aSXin Li 8*ec63e07aSXin LiThe repository can be cloned using: 9*ec63e07aSXin Li``` 10*ec63e07aSXin Ligit clone --recursive [URL to this repo] 11*ec63e07aSXin Li``` 12*ec63e07aSXin LiThe `--recursive` flag ensures that submodules are also cloned. 13*ec63e07aSXin Li 14*ec63e07aSXin LiAlternatively, if the repository has already been cloned but the submodules have 15*ec63e07aSXin Linot, these can be cloned using: 16*ec63e07aSXin Li``` 17*ec63e07aSXin Ligit submodule update --init --recursive 18*ec63e07aSXin Li``` 19*ec63e07aSXin Li 20*ec63e07aSXin LiThe full list of Sandboxed API dependencies can be found on 21*ec63e07aSXin Li[Sandboxed API Getting Started page](https://developers.google.com/code-sandboxing/sandboxed-api/getting-started). 22*ec63e07aSXin Li 23*ec63e07aSXin LiThe following commands, used from the current `libuv/` directory, build the 24*ec63e07aSXin Lilibrary: 25*ec63e07aSXin Li``` 26*ec63e07aSXin Limkdir -p build 27*ec63e07aSXin Licd build 28*ec63e07aSXin Licmake .. -G Ninja -D SAPI_ROOT=[path to sandboxed-api] 29*ec63e07aSXin Licmake --build . 30*ec63e07aSXin Li``` 31*ec63e07aSXin Li 32*ec63e07aSXin Li## Implementation details 33*ec63e07aSXin Li 34*ec63e07aSXin LiLibUV can't be directly sandboxed by Sandboxed API. Because of the size and 35*ec63e07aSXin Licomplexity of the library, doing so creates some compilation errors and does not 36*ec63e07aSXin Licreate the correct APIs for all methods. The solution for this issue is creating 37*ec63e07aSXin Lia wrapper library, whose methods (which can be sandboxed properly) internally 38*ec63e07aSXin Licall the original LibUV's methods. 39*ec63e07aSXin Li 40*ec63e07aSXin LiUsing these wrapper methods is extremely simple, the only relevant difference is 41*ec63e07aSXin Lithat they have a `sapi_` prefix before their names (e.g. `uv_loop_init` becomes 42*ec63e07aSXin Li`sapi_uv_loop_init`). The only exception is the variadic method 43*ec63e07aSXin Li`uv_loop_configure`. This has two wrappers, `sapi_uv_loop_configure` (with no 44*ec63e07aSXin Liadditional parameters) and `sapi_uv_loop_configure_int` (with an additional 45*ec63e07aSXin Li`int` parameter). Currently, these are the only valid calls to the method in 46*ec63e07aSXin LiLibUV. 47*ec63e07aSXin Li 48*ec63e07aSXin Li#### Wrapper generator 49*ec63e07aSXin Li 50*ec63e07aSXin LiThe wrapper is generated automatically by a Python script that is called by 51*ec63e07aSXin LiCMake at build time. This script can be found in the `generator` folder. 52*ec63e07aSXin Li 53*ec63e07aSXin Li#### Function pointers 54*ec63e07aSXin Li 55*ec63e07aSXin LiThe functions whose pointers will be passed to the library's methods 56*ec63e07aSXin Li(*callbacks*) can't be implemented in the files making use of the library, but 57*ec63e07aSXin Limust be in other files. These files must be compiled together with the library, 58*ec63e07aSXin Liand this is done by adding their absolute path to the CMake variable 59*ec63e07aSXin Li`SAPI_UV_CALLBACKS`. 60*ec63e07aSXin Li 61*ec63e07aSXin LiThe pointers can then be obtained using an `RPCChannel` object, as shown in the 62*ec63e07aSXin Liexample `idle-basic.cc`. 63*ec63e07aSXin Li 64*ec63e07aSXin Li## Examples 65*ec63e07aSXin Li 66*ec63e07aSXin LiThe `examples` directory contains the sandboxed versions of example source codes 67*ec63e07aSXin Litaken from from [LibUV's User Guide](https://docs.libuv.org/en/v1.x/guide.html). 68*ec63e07aSXin LiMore information about each example can be found in the examples' 69*ec63e07aSXin Li[README](examples/README.md). 70*ec63e07aSXin Li 71*ec63e07aSXin LiTo build these examples when building the library, the CMake variable 72*ec63e07aSXin Li`SAPI_UV_ENABLE_EXAMPLES` must be set to `ON`. This enables Sandboxed API 73*ec63e07aSXin Liexamples as well. 74*ec63e07aSXin Li 75*ec63e07aSXin Li## Testing 76*ec63e07aSXin Li 77*ec63e07aSXin LiThe `tests` folder contains some test cases created using Google Test. 78*ec63e07aSXin Li 79*ec63e07aSXin LiTo build these tests when building the library, the CMake variable 80*ec63e07aSXin Li`SAPI_UV_ENABLE_TESTS` must be set to `ON`. This enables Sandboxed API tests as 81*ec63e07aSXin Liwell. 82*ec63e07aSXin Li 83*ec63e07aSXin Li## Policies 84*ec63e07aSXin Li 85*ec63e07aSXin LiEach example and test has an ad-hoc policy implemented on its own file. These 86*ec63e07aSXin Lipolicies can be used as references for pieces of code that perform similar 87*ec63e07aSXin Lioperations. For example, the `helloworld.cc` example has a policy that only 88*ec63e07aSXin Liallows the strictly necessary syscalls for running a loop. 89*ec63e07aSXin Li 90*ec63e07aSXin Li## Callbacks 91*ec63e07aSXin Li 92*ec63e07aSXin LiThe `callbacks.h` and `callbacks.cc` files in the `callbacks` folder implement 93*ec63e07aSXin Liall the callbacks used by examples and tests. 94