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.
Three packages
Section titled “Three packages”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 itThe 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)}The extension
Section titled “The extension”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:
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:
[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
Section titled “The host”The host loads the extension, provides what it requires, starts it, then
calls its services through a handle, Service<any Greeter>:
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.
Reloading
Section titled “Reloading”wv build # bin/host and bin/polite.wvx./bin/host bin/polite.wvxThe 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 AdaHello, Ada!reloadAda log: greeting AdaGood morning, Ada.The handle greeter was taken once: it does not hold the service, and
calls the new version after the reload.
What crosses
Section titled “What crosses”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.