Skip to content
Weaverv0.5.0

Extensions

An extension is Weaver code compiled apart from a program, which the program, its host, loads while it runs. The host can stop it, and reload it from its file once it has been recompiled, without stopping itself: a server reloaded as you edit it in development, or an application that loads only the features a session needs.

The host and its extensions exchange services: values of a contract that both sides compile. An extension compiled against another version of the contract does not find its services, rather than call them wrongly.

The usual layout is a workspace of three packages: the contracts, the extension, and the host.

greeter/
├── weaver-workspace.toml members = ["api", "polite", "host"]
├── api/ acme/greeter: the contracts both sides share
├── polite/ acme/polite: the extension
└── host/ acme/host: the program that loads it

The API package holds the contracts, and nothing else needs to be shared:

// api/greeter.wft, in the package acme/greeter, version 1.0.0
/// What greets: the service the extension provides.
pub contract Greeter {
/// The greeting of name.
fn greet(self, name: String): String
}
/// What writes a line: the service the host provides.
pub contract Log {
/// Writes text.
fn line(self, text: String)
}

An extension has no main: its start function is called when the host starts it. It takes there what the host provides, with require, and provides its own services, with provide:

polite/polite.wft
import weaver.extension.{Context, ExtensionError}
import acme.greeter.{Greeter, Log}
type Polite = { log: any Log }
impl Greeter for Polite {
fn greet(self, name: String): String {
self.log.line("greeting ${name}")
return "Hello, ${name}!"
}
}
/// Called by the host when it starts the extension.
fn start(ctx: Context) ! ExtensionError {
val log = ctx.require<any Log>()!
ctx.provide<any Greeter>(Polite{log})
}

Its manifest builds it as an extension:

polite/weaver.toml
[package]
name = "acme/polite"
[dependencies]
"acme/greeter" = { workspace = true }
[build.polite]
main = "."
kind = "extension"

wv build polite writes bin/polite.wvx, a shared object. It does not carry the runtime: it uses its host’s, and states the version of the ABI it was built for, which the host checks when it loads it.

The host loads the extension, provides what it requires, starts it, then calls its services through a handle, Service<any Greeter>:

host/main.wft
import weaver.io.{print, Stdin}
import weaver.extension.{Extension, ExtensionError}
import acme.greeter.{Greeter, Log}
type Console = { prefix: String }
impl Log for Console {
fn line(self, text: String) = print("${self.prefix}${text}")
}
fn main(args: String[]) ! ExtensionError {
val ext = Extension.load(args[0])!
ext.provide<any Log>(Console{prefix: " log: "})
ext.start()!
val greeter = ext.service<any Greeter>()
val input = mut Stdin.lock()
loop {
val line = input.readLine(b'\n') catch _ => None
val Some(bytes) = line else { break }
match (bytes.utf8() ?? "").trimEnd() {
"reload" => ext.reload() catch e => print("reload failed: ${e}")
name => print(greeter.greet(name) catch e => "error: ${e}")
}
}
}

A call through the handle can fail where a direct call cannot: each method also returns ExtensionError, Stopped if the extension was stopped, Failed if it panicked. A panic in the extension does not stop the host: the extension goes into a failed state, and reload puts it back in service.

Terminal window
wv build # bin/host and bin/polite.wvx
./bin/host bin/polite.wvx

The host greets each name it reads. While it runs, change the greeting in polite.wft to "Good morning, ${name}.", rebuild the extension alone, wv build polite, and type reload:

Ada
log: greeting Ada
Hello, Ada!
reload
Ada
log: greeting Ada
Good morning, Ada.

The handle greeter was taken once: it does not hold the service, and calls the new version after the reload.

What the two sides exchange is data: numbers, strings, arrays, records, enums, options and results. A function, a resource or a pointer would point into code that a reload removes, and the compiler refuses them in a service’s contract. What must stay on one side is lent by a handle, ctx.lend<any Cursor>(rows), which the other side calls like a service.

The lifecycle has more steps than this chapter shows: stop waits for the calls in progress and cancels the extension’s tasks, unload removes its code. A Registry holds several extensions that exchange services with each other, and services can be named, ranked and watched as they come and go. The Extensions part of the reference has the whole of it, and the repository’s examples/plugins is a complete host and extension.