Skip to content

Commit 8e9f4f8

Browse files
mpwarresmpwarres
authored
Expand C++ SDK documentation (proxy-wasm#158)
Add docs/api_overview.md page, move current README.md to docs/building.md, and add a short top-level README.md that links to both pages. Add inline comments to header files to document individual classes and methods. Signed-off-by: Michael Warres <[email protected]>
1 parent dc4f37e commit 8e9f4f8

8 files changed

+1416
-1498
lines changed

‎README.md

+25-219
Original file line numberDiff line numberDiff line change
@@ -3,225 +3,31 @@
33
[![Build Status][build-badge]][build-link]
44
[![Apache 2.0 License][license-badge]][license-link]
55

6-
The SDK has dependencies on specific versions of the C++ WebAssembly toolchain Emscripten (https://emscripten.org) and the protobuf library, therefor use of a Docker image is recommended.
7-
8-
## Docker
9-
10-
A Dockerfile for the C++ SDK is provided in Dockerfile-sdk.
11-
12-
It can built in this directory by:
13-
14-
```bash
15-
docker build -t wasmsdk:v2 -f Dockerfile-sdk .
16-
```
17-
18-
The docker image can be used for compiling wasm files.
19-
20-
### Creating a project for use with the Docker build image
21-
22-
Create a directory with your source files and a Makefile:
23-
24-
```makefile
25-
PROXY_WASM_CPP_SDK=/sdk
26-
27-
all: myproject.wasm
28-
29-
include ${PROXY_WASM_CPP_SDK}/Makefile.base_lite
30-
```
31-
32-
Source file (myproject.cc):
33-
34-
```c++
35-
#include <string>
36-
#include <unordered_map>
37-
38-
#include "proxy_wasm_intrinsics.h"
39-
40-
class ExampleContext : public Context {
41-
public:
42-
explicit ExampleContext(uint32_t id, RootContext* root) : Context(id, root) {}
43-
44-
FilterHeadersStatus onRequestHeaders(uint32_t headers, bool end_of_stream) override;
45-
void onDone() override;
46-
};
47-
static RegisterContextFactory register_ExampleContext(CONTEXT_FACTORY(ExampleContext));
48-
49-
FilterHeadersStatus ExampleContext::onRequestHeaders(uint32_t headers, bool end_of_stream) {
50-
logInfo(std::string("onRequestHeaders ") + std::to_string(id()));
51-
auto path = getRequestHeader(":path");
52-
logInfo(std::string("header path ") + std::string(path->view()));
53-
return FilterHeadersStatus::Continue;
54-
}
55-
56-
void ExampleContext::onDone() { logInfo("onDone " + std::to_string(id())); }
57-
```
58-
59-
### Compiling with the Docker build image
60-
61-
Run docker:
62-
63-
```bash
64-
docker run -v $PWD:/work -w /work wasmsdk:v2 /build_wasm.sh
65-
```
66-
67-
### Caching the standard libraries
68-
69-
The first time that emscripten runs it will generate the standard libraries. To cache these in the docker image,
70-
after the first successful compilation (e.g myproject.cc above), commit the image with the standard libraries:
71-
72-
```bash
73-
docker commit `docker ps -l | grep wasmsdk:v2 | awk '{print $1}'` wasmsdk:v2
74-
```
75-
76-
This will save time on subsequent compiles.
77-
78-
### Using the SDK from a newer/specific version of Envoy
79-
80-
To use a newer/specific version of the SDK (e.g. from the version of Enovy you are going to deploy the WebAssembly module to) bind that volume and use it in the Makefile.
81-
82-
Here is an example Makefile referencing the SDK at ../envoy/api/wasm/cpp and mounted as 'sdk' in the /work directory:
83-
84-
```makefile
85-
PROXY_WASM_CPP_SDK=/work/sdk
86-
87-
all: myproject.wasm
88-
89-
include ${PROXY_WASM_CPP_SDK}/Makefile.base_lite
90-
```
91-
92-
Run docker pointing to Envoy sources in a directory parallel (at the same level) as your project directory:
93-
94-
```bash
95-
docker run -v $PWD:/work -v $PWD/../envoy/api/wasm/cpp:/work/sdk -w /work wasmsdk:v2 bash /build_wasm.sh
96-
```
97-
98-
### Using abseil form the image
99-
100-
Abseil (optionally) is built in /root/abseil and can be used. Note that the abseil containers (e.g. absl::flat\_hash\_set) exercise many syscalls which are not supported. Consequantally individual files should be pulled in which are relatively self contained (e.g. strings). Example customized Makefile:
101-
102-
```makefile
103-
PROXY_WASM_CPP_SDK=/sdk
104-
CPP_API:=${PROXY_WASM_CPP_SDK}
105-
CPP_CONTEXT_LIB = ${CPP_API}/proxy_wasm_intrinsics.cc
106-
ABSL = /root/abseil-cpp
107-
ABSL_CPP = ${ABSL}/absl/strings/str_cat.cc ${ABSL}/absl/strings/str_split.cc ${ABSL}/absl/strings/numbers.cc ${ABSL}/absl/strings/ascii.cc
108-
109-
all: plugin.wasm
110-
111-
%.wasm %.wat: %.cc ${CPP_API}/proxy_wasm_intrinsics.h ${CPP_API}/proxy_wasm_enums.h ${CPP_API}/proxy_wasm_externs.h ${CPP_API}/proxy_wasm_api.h ${CPP_API}/proxy_wasm_intrinsics.js ${CPP_CONTEXT_LIB}
112-
ls /root
113-
em++ --no-entry -s EXPORTED_FUNCTIONS=['_malloc'] --std=c++17 -O3 -flto -I${CPP_API} -I${CPP_API}/google/protobuf -I/usr/local/include -I${ABSL} --js-library ${CPP_API}/proxy_wasm_intrinsics.js ${ABSL_CPP} $*.cc ${CPP_API}/proxy_wasm_intrinsics.pb.cc ${CPP_CONTEXT_LIB} ${CPP_API}/libprotobuf.a -o $*.wasm
114-
```
115-
116-
Precompiled abseil libraries are also available, so the above can also be done as:
117-
118-
```makefile
119-
PROXY_WASM_CPP_SDK=/sdk
120-
CPP_API:=${PROXY_WASM_CPP_SDK}
121-
CPP_CONTEXT_LIB = ${CPP_API}/proxy_wasm_intrinsics.cc
122-
ABSL = /root/abseil-cpp
123-
ABSL_LIBS = ${ABSL}/absl/strings/libabsl_strings.a ${ABSL}/absl/strings/libabsl_strings_internal.a ${ABSL}/absl/strings/libabsl_str_format_internal.a
124-
125-
all: plugin.wasm
126-
127-
%.wasm %.wat: %.cc ${CPP_API}/proxy_wasm_intrinsics.h ${CPP_API}/proxy_wasm_enums.h ${CPP_API}/proxy_wasm_externs.h ${CPP_API}/proxy_wasm_api.h ${CPP_API}/proxy_wasm_intrinsics.js ${CPP_CONTEXT_LIB}
128-
ls /root
129-
em++ --no-entry -s EXPORTED_FUNCTIONS=['_malloc'] --std=c++17 -O3 -flto -I${CPP_API} -I${CPP_API}/google/protobuf -I/usr/local/include -I${ABSL} --js-library ${CPP_API}/proxy_wasm_intrinsics.js $*.cc ${CPP_API}/proxy_wasm_intrinsics.pb.cc ${CPP_CONTEXT_LIB} ${CPP_API}/libprotobuf.a ${ABSL_LIBS} -o $*.wasm
130-
```
131-
132-
### Ownership of the resulting .wasm files
133-
134-
The compiled files may be owned by root. To chown them add the follow lines to the Makefile and docker invocation:
135-
136-
```makefile
137-
PROXY_WASM_CPP_SDK=/sdk
138-
139-
all: myproject.wasm
140-
chown ${uid}.${gid} $^
141-
142-
include ${PROXY_WASM_CPP_SDK}/Makefile.base_lite
143-
```
144-
145-
Invocation file (e.g. build.sh):
146-
147-
```bash
148-
#!/bin/bash
149-
docker run -e uid="$(id -u)" -e gid="$(id -g)" -v $PWD:/work -w /work wasmsdk:v2 /build_wasm.sh
150-
```
151-
152-
## Dependencies for building WASM modules:
153-
154-
If you do not wish to use the Docker file, the dependencies can be installed by script (sdk\_container.sh), or by hand.
155-
156-
### protobuf v3.9.1
157-
158-
You must install the version of protobuf on your build system that matches the libprotobuf.a files (without any patches) so that the generated code matches the .a library. Currently this is based on tag v3.9.1 of https://github.com/protocolbuffers/protobuf.
159-
160-
```bash
161-
git clone https://github.com/protocolbuffers/protobuf
162-
cd protobuf
163-
git checkout v3.9.1
164-
git submodule update --init --recursive
165-
./autogen.sh
166-
./configure
167-
make
168-
make check
169-
sudo make install
170-
```
171-
172-
### emscripten
173-
174-
```bash
175-
git clone https://github.com/emscripten-core/emsdk.git
176-
cd emsdk
177-
./emsdk update-tags
178-
./emsdk install 3.1.7
179-
./emsdk activate 3.1.7
180-
181-
source ./emsdk\_env.sh
182-
```
183-
184-
It is possible later versions will work, e.g.
185-
186-
```bash
187-
./emsdk update-tags
188-
./emsdk install latest
189-
./emsdk activate latest
190-
```
191-
192-
However 3.1.7 is known to work.
193-
194-
### Rebuilding the libprotobuf.a files
195-
196-
If want to rebuild the libprotobuf.a files or use a different version see the instructions at https://github.com/kwonoj/protobuf-wasm. Commit 4bba8b2f38b5004f87489642b6ca4525ae72fe7f works for protobuf v3.9.x.
197-
198-
```bash
199-
git clone https://github.com/protocolbuffers/protobuf protobuf-wasm
200-
cd protobuf-wasm
201-
git checkout v3.9.1
202-
git clone https://github.com/kwonoj/protobuf-wasm wasm-patches
203-
cd wasm-patches && git checkout 4bba8b2f38b5004f87489642b6ca4525ae72fe7f && cd ..
204-
git apply wasm-patches/*.patch
205-
./autogen.sh
206-
emconfigure ./configure --disable-shared CXXFLAGS="-O3 -flto"
207-
emmake make
208-
cd ..
209-
cp protobuf-wasm/src/.libs/libprotobuf-lite.a ${CPP_API}/libprotobuf-lite.a
210-
cp protobuf-wasm/src/.libs/libprotobuf.a ${CPP_API}/libprotobuf.a
211-
```
212-
213-
### WAVM binaries
214-
215-
```bash
216-
git clone [email protected]:WAVM/WAVM.git
217-
cd WAVM
218-
cmake "."
219-
make
220-
sudo make install
221-
```
222-
223-
Note: ensure /usr/local/bin is in your path
224-
6+
Proxy-Wasm is a specification and supporting framework for using
7+
[WebAssembly](https://webassembly.org) (Wasm) to extend the functionality of
8+
network proxies. It enables developers to write custom logic (plugins) that are
9+
compiled to Wasm modules and then loaded and executed by the proxy.
10+
11+
Proxy-Wasm consists of multiple parts:
12+
13+
* An [ABI](https://github.com/proxy-wasm/spec) that specifies the low-level
14+
interface between network proxies and Wasm virtual machines that run the
15+
plugins.
16+
* [Host implementations](https://github.com/proxy-wasm/spec#host-environments)
17+
of the ABI, provided by network proxies.
18+
* [Language-specific SDKs](https://github.com/proxy-wasm/spec#sdks) that layer
19+
on top of the ABI, providing a more natural and programmer-friendly API for
20+
invoking and implementing Proxy-Wasm functions and callbacks.
21+
22+
This repository provides the C++ SDK.
23+
24+
## Getting started
25+
26+
* Read the [API overview](docs/api_overview.md) to learn about [Proxy-Wasm
27+
concepts] and how they are represented in the C++ SDK.
28+
* View an [example plugin](example/http_wasm_example.cc).
29+
* Refer to [API documentation](docs/api_overview.md#codemap).
30+
* [Build](docs/building.md) plugin code.
22531

22632
[build-badge]: https://github.com/proxy-wasm/proxy-wasm-cpp-sdk/workflows/C++/badge.svg?branch=master
22733
[build-link]: https://github.com/proxy-wasm/proxy-wasm-cpp-sdk/actions?query=workflow%3AC%2B%2B+branch%3Amaster

0 commit comments

Comments
 (0)