custom-template

Custom Capability Provider

This capability provider is a template for creating providers with custom capabilities. It uses the provider-sdk-go and implements the auto-generated Provider interface with an example handler that will persist the links that target the provider (target links) and links where the provider is the source and targets a component (source links).

The purpose of this example is to provide comprehensive comments on the usage of our wasmCloud provider SDK, from serving RPC exports to invoking component imports. The code is informative to read through and provides a base for extending wasmCloud with custom capabilities.

Building

Prerequisites:

1. Go toolchain
2. wit-bindgen-wrpc cargo install wit-bindgen-wrpc-cli
3. wash

go generate ./...
go build .

Alternatively, you can generate, build and package this provider in one step:

wash build

You can build the included test component with wash build -p ./component.

Running to test

Prerequisites:

1. Go toolchain
2. nats-server
3. nats-cli

You can run this capability provider as a binary by passing a simple base64 encoded HostData struct, in order to do basic testing. For example:

nats-server -js &
echo '{"lattice_rpc_url": "0.0.0.0:4222", "lattice_rpc_prefix": "default", "provider_key": "custom-template", "link_name": "default"}' | base64 | go run .

And in another terminal, you can request the health of the provider using the NATS CLI

nats req "wasmbus.rpc.default.custom-template.health" '{}'

Additionally, you can invoke the provider directly which will send test data to each linked component

wash call custom-template wasmcloud:example/system-info.call

Running as an application

You can deploy this provider, along with a component for testing, by deploying the wadm.yaml application. Make sure to build the component with wash build.

# Build the component
cd component
wash build

# Return to the provider directory
cd ..

# Launch wasmCloud in the background
wash up -d
# Deploy the application
wash app deploy ./wadm.yaml

Customizing

Customizing this provider to meet your needs of a custom capability takes just a few steps.

1. Update the wit/world.wit to include the data types and functions that model your custom capability. You can use the example as a base and the component model WIT reference as a guide for types and keywords.
2. Implement any provider exports in provider.go as methods of your Handler.
3. Use any provider imports in provider.go to invoke linked components. Check out the Call() function for an example for how to invoke a component using RPC.

Have any questions? Please feel free to file an issue and/or join us on the wasmCloud slack!