Merge pull request #2 from phanikishoreg/cleanup
chore: clean up and comment build scripts and improve READMEsledge_graph
Sean McBride
5 years ago
committed by
GitHub
commit
81950fcf94
@ -1,80 +1,138 @@
|
||||
# aWsm (awesome)
|
||||
|
||||
This project is a work-in-progress to build an efficient WASM runtime, **aWsm**, using `silverfish` compiler.
|
||||
**aWsm** is an efficient serverless runtime built with the `silverfish` compiler. It combines WebAssembly sandboxing with asynchronous I/O to provide a lightweight serverless solution suitable for edge computing.
|
||||
|
||||
## Setting up the environment
|
||||
## Host Dependencies
|
||||
|
||||
- Docker - [Installation Instructions](https://docs.docker.com/install/)
|
||||
- libuv
|
||||
|
||||
If on Debian, you can install libuv with the following:
|
||||
|
||||
To use a Docker container based environment, that makes your life easy by installing all the required dependencies and builds the toolchain for you.
|
||||
Run
|
||||
```bash
|
||||
./devenv.sh install_libuv
|
||||
```
|
||||
|
||||
## Setting up the environment
|
||||
|
||||
**Note: These steps require Docker. Make sure you've got it installed!**
|
||||
|
||||
We provide a Docker build environment configured with the dependencies and toolchain needed to build the aWsm runtime and serverless functions.
|
||||
|
||||
To setup this environment, run:
|
||||
|
||||
```bash
|
||||
./devenv.sh setup
|
||||
```
|
||||
**make sure you've docker installed.**
|
||||
|
||||
To enter the docker environment,
|
||||
```
|
||||
## Using the Docker container to compile your serverless functions
|
||||
|
||||
To enter the docker environment, run:
|
||||
|
||||
```bash
|
||||
./devenv.sh run
|
||||
```
|
||||
**spawns a shell in the container.**
|
||||
|
||||
To setup toolchain path (within a container, per `run`)
|
||||
The first time you enter this environment, run the following to copy the awsmrt binary to /awsm/runtime/bin.
|
||||
|
||||
```bash
|
||||
cd /awsm/runtime
|
||||
make clean all
|
||||
```
|
||||
source /opt/awsm/bin/devenv_src.sh
|
||||
|
||||
There are a set of benchmarking applications in the `/awsm/runtime/tests` directory. Run the following to compile all benchmarks runtime tests using silverfish and then copy all resulting `<application>_wasm.so` files to /awsm/runtime/bin.
|
||||
|
||||
```bash
|
||||
cd /awsm/runtime/tests/
|
||||
make clean all
|
||||
```
|
||||
|
||||
## To run applications
|
||||
You now have everything that you need to execute your first serverless function on aWsm
|
||||
|
||||
There are a set of benchmarking applications in `code_benches` directory that should be "loadable", WIP!!
|
||||
**All the remaining steps are in a Docker container environment.**
|
||||
To exit the container:
|
||||
|
||||
```bash
|
||||
exit
|
||||
```
|
||||
cd /awsm/tests/
|
||||
|
||||
make clean all
|
||||
```
|
||||
This compiles all benchmarks in silverfish and other runtime tests and copies `<application>_wasm.so` to /awsm/runtime/bin.
|
||||
To stop the Docker container:
|
||||
|
||||
```bash
|
||||
./devenv.sh stop
|
||||
```
|
||||
cd /awsm/runtime
|
||||
make clean all
|
||||
```
|
||||
This will copy the awsmrt binary to /awsm/runtime/bin.
|
||||
|
||||
## Running your first serverless function
|
||||
|
||||
An aWsm serverless function consists of a shared library (*.so) and a JSON configuration file that determines how the runtime should execute the serverless function. As an example, here is the configuration file for our sample fibonacci function:.
|
||||
|
||||
```json
|
||||
{
|
||||
"active": "yes",
|
||||
"name": "fibonacci",
|
||||
"path": "fibonacci_wasm.so",
|
||||
"port": 10000,
|
||||
"argsize": 1,
|
||||
"http-req-headers": [],
|
||||
"http-req-content-type": "text/plain",
|
||||
"http-req-size": 1024,
|
||||
"http-resp-headers": [],
|
||||
"http-resp-size": 1024,
|
||||
"http-resp-content-type": "text/plain"
|
||||
}
|
||||
```
|
||||
cd /awsm/runtime/bin
|
||||
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`pwd`
|
||||
```
|
||||
|
||||
**Create input and test files**
|
||||
Supports module registration using json format now and invocations as well.
|
||||
More importantly, each module runs a udp server and waits for connections.
|
||||
The udpclient tool in `runtime/tools` directory uses a format `<ip:port>$<json_request_string>`,
|
||||
connects to <ip:port> and sends the <json_reqest_string> to the IP address it connects at the start.
|
||||
The `port` and `name` fields are used to determine the path where our serverless function will be served served.
|
||||
|
||||
In our case, we are running the aWsm runtime on localhost, so our function is available at `http://localhost:10000/fibonacci`
|
||||
|
||||
To run `awsm runtime`,
|
||||
Our fibonacci function will parse a single argument from the HTTP POST body that we send. The expected Content-Type is "text/plain" and the buffer is sized to 1024 bytes for both the request and response. This is sufficient for our simple Fibonacci function, but this must be changed and sized for other functions, such as image processing.
|
||||
|
||||
Now that we understand roughly how the aWsm runtime interacts with serverless function, let's run Fibonacci!
|
||||
|
||||
From the root project directory of the host environment (not the Docker container!), navigate to the binary directory
|
||||
|
||||
```bash
|
||||
cd runtime/bin/
|
||||
```
|
||||
./awsmrt ../tests/test_modules.json
|
||||
|
||||
Now run the awsmrt binary, passing the JSON file of the serverless function we want to serve. Because serverless functions are loaded by aWsm as shared libraries, we want to add the `runtime/tests/` directory to LD_LIBRARY_PATH.
|
||||
|
||||
```bash
|
||||
LD_LIBRARY_PATH="$(pwd):$LD_LIBRARY_PATH" ./awsmrt ../tests/test_fibonacci.json
|
||||
```
|
||||
|
||||
To run the udpclient,
|
||||
While you don't see any output to the console, the runtime is running in the foreground.
|
||||
|
||||
Let's now invoke our serverless function to compute the 10th fibonacci number. I'll use [HTTPie](https://httpie.org/) to send a POST request with a body containing the parameter I want to pass to my serverless function. Feel free to use cURL or whatever network client you prefer!
|
||||
|
||||
Open a new terminal session and execute the following
|
||||
|
||||
```bash
|
||||
echo "10" | http :10000
|
||||
```
|
||||
./udpclient ../tests/test_sandboxes.jsondata
|
||||
|
||||
You should receive the following in response. The serverless function says that the 10th fibonacci number is 55, which seems to be correct!
|
||||
|
||||
```bash
|
||||
HTTP/1.1 200 OK
|
||||
Content-length: 3
|
||||
Content-type: text/plain
|
||||
|
||||
55
|
||||
```
|
||||
And follow the prompts in udpclient to send requests to the runtime.
|
||||
|
||||
## WIP (Work In Progress)
|
||||
When done, terminal the aWsm runtime with `Ctrl+c`
|
||||
|
||||
## Removing the aWsm Runtime
|
||||
|
||||
If you are finished working with the aWsm runtime and wish to remove it, run the following command to delete our Docker build and runtime images.
|
||||
|
||||
```bash
|
||||
./devenv.sh rma
|
||||
```
|
||||
|
||||
* ~~Dynamic loading of multiple modules~~
|
||||
* ~~Multiple sandboxes (includes multiple modules, multiple instances of a module)~~
|
||||
* ~~Bookkeeping of multiple modules and multiple sandboxes.~~
|
||||
* ~~Runtime to "poll"?? on requests to instantiate a module~~ and respond with the result.
|
||||
* ~~Runtime to schedule multiple sandboxes.~~
|
||||
* Efficient scheduling and performance optimizations.
|
||||
* ~~Runtime to enable event-based I/O (using `libuv`).~~ (basic I/O works with libuv)
|
||||
* To enable WASI interface, perhaps through the use of WASI-SDK
|
||||
And then simply delete this repository.
|
||||
|
||||
## Silverfish compiler
|
||||
## Problems or Feedback?
|
||||
|
||||
Silverfish compiler uses `llvm` and interposes on loads/stores to enable sandbox isolation necessary in `aWsm` multi-sandboxing runtime.
|
||||
`aWsm` runtime includes the compiler-runtime API required for bounds checking in sandboxes.
|
||||
Most of the sandboxing isolation is copied from the silverfish runtime.
|
||||
If you encountered bugs or have feedback, please let us know in our [issue tracker.](https://github.com/phanikishoreg/awsm-Serverless-Framework/issues)
|
||||
|
||||
Loading…
Reference in new issue