plugins

Google Cloud Service Extension Plugins Samples

Code samples and tools for developing Google Cloud Service Extensions WebAssembly (wasm) plugins.

Each sample/recipe has an example plugin written in Rust and C++, and an accompanying unit test that verifies both.

Getting started

We recommend the following process:

1. Write a wasm plugin using the samples and SDKs as a starting point: C++, Rust. See also the best practices.
2. Build the plugin.
3. Test and benchmark the plugin.

Building

All sample plugins can be built using Bazel. If you prefer to use language-native toolchains, see the SDK-specific instructions:

• C++ supports Make
• Rust supports Cargo

All languages also support Bazel; we recommend the Bazelisk wrapper which provides support for multiple Bazel versions:

# A target is defined using BUILD files. Dependencies are in WORKSPACE.
$ bazelisk build <target>

# For example, to build a sample in C++ and Rust, from the plugins/ directory:
$ bazelisk build //samples/add_header:plugin_cpp.wasm
$ bazelisk build //samples/add_header:plugin_rust.wasm

C++ builds may require a specific toolchain: --config=clang or --config=gcc.

Testing and benchmarking

1. Write a plugin test file (text proto) to specify the plugin's functional expectations (example). Consult the plugin tester proto API as needed.
2. Add benchmark: true to tests that exemplify common wasm operations (example).
3. Run + Test + Benchmark your wasm plugin as follows!

docker run -it -v $(pwd):/mnt \
    us-docker.pkg.dev/service-extensions-samples/plugins/wasm-tester:main \
    --proto /mnt/local/path/to/tests.textpb \
    --plugin /mnt/local/path/to/plugin.wasm

Tips:

• When benchmarking and publishing, compile a release (optimized) wasm build.
• Try sending empty or invalid input. Verify your plugin doesn't crash.
• To see plugin-emitted logs on the console, add --logfile=/dev/stdout.
• To see a trace of logs and wasm ABI calls, add --loglevel=TRACE.
• To disable benchmarking for faster iteration, add --nobench.
• To optionally specify plugin config data, add --config=<path>.

You can also run tests using Bazel. This is much slower the first time, because this builds both the tester and the V8 runtime from scratch. Use the Docker command above for a better experience.

bazelisk test --config=bench --test_output=all //samples/...

Samples & Recipes

The samples folder contains Samples & Recipes to use as a reference for your own plugin. Extend them to fit your particular use case.

• Testing examples: A demonstration of our test framework capabilities (sending inputs and checking results).
• Log each Wasm call: Don't change anything about the traffic (noop plugin). Log each wasm invocation, including lifecycle callbacks.
• Add HTTP request & response headers: Add a header on both the client request and server response paths. Also check for existing headers.
• Plugin config with a list of tokens to deny: Deny a request whenever it contains a known bad token. Bad tokens are loaded at plugin initialization time from plugin configuration.
• Log the value of a query parameter: Emit a custom variable to Cloud Logging. Demonstrate a standard way to parse query string values from the request.
• Set or update query parameter: Change the path, and specifically query string values.
• Rewrite the path using regex: Remove a piece of the URI using regex replacement. Demonstrate a standard way to use regular expressions, compiling them at plugin initialization.
• Overwrite HTTP request & response headers: Overwrite a header on both the client request and server response paths.
• Normalize a HTTP header on request: Creates a new HTTP header (client-device-type) to shard requests based on device according to the existence of HTTP Client Hints or User-Agent header values.
• Block request with particular header: Check whether the client's Referer header matches an expected domain. If not, generate a 403 Forbidden response.
• Overwrite origin response error code: Overwrites error code served from origin from 5xx error to 4xx error class.
• Perform a HTTP redirect: Redirect a given URL to another URL.
• Set a cookie for a given client request: Set cookie on HTTP response for a particular client request.
• A/B decisioning based on query param: Showcase A/B testing in action, 50% chance a user is served file A and 50% chance they are served file B.
• Custom error page For a certain class of origin errors, redirect to a custom error page hosted on GCS.
• Validate client JWT for authorization: Ensures user authentication by verifying an RS256-signed JWT token in the query string and subsequently removing it.
• Check for PII on response: Checks the response HTTP headers and body for the presence of credit card numbers. If found, the initial numbers will be masked.

Feature set / ABI

Service Extension plugins are compiled against the ProxyWasm ABI, described here: https://github.com/proxy-wasm/spec/tree/master

Service Extension plugins currently support a subset of the ProxyWasm spec. Support will grow over time. The current feature set includes:

• Root context lifecycle callbacks (host -> wasm)
  • on_context_create
  • on_vm_start
  • on_configure
  • on_done
  • on_delete
• Stream context lifecycle callbacks (host -> wasm)
  • on_context_create
  • on_done
  • on_delete
• Stream context HTTP callbacks (host -> wasm)
  • on_request_headers
  • on_response_headers
• Stream context HTTP hostcalls (wasm -> host)
  • send_local_response
  • get_header_map_value, add_header_map_value, replace_header_map_value, remove_header_map_value
  • get_header_map_pairs, set_header_map_pairs
  • get_header_map_size
• Other hostcalls (wasm -> host)
  • log
  • get_current_time_nanoseconds (frozen per stream)
  • get_property ("plugin_root_id" only)
  • get_buffer_status, get_buffer_bytes, set_buffer_bytes (PluginConfiguration, HttpRequestBody, HttpResponseBody)

Implementation details

Fixture

In support of unit testing, this repo contains an HttpTest fixture with a TestWasm host implementation and TestHttpContext stream handler. These minimal implementations loosely match GCP Service Extension execution environment. The contexts implement the ABI / feature set described above (mainly HTTP headers and logging), but often in a simple way (behaviors may not match GCP exactly).

Rust and Cargo

This project leverages crate_universe to integrate Cargo with Bazel. In order to add new Rust library dependencies:

• Edit dependencies in Cargo.toml
• Regenerate Bazel targets: $ CARGO_BAZEL_REPIN=1 bazelisk sync --only=crate_index
• Reference libraries as @crate_index//:<target>