Extism (extism.Extism)

Introduction

Extism is a framework for executing WebAssembly plugins. The OCaml bindings require libextism, installation information is available on the Extism website

The Plugin and Manifest modules are the main modules to look at.
Type provides different types that can be encoded as input/output to Plugin.call
Function is used to define host functions and Host_function is used from inside host functions to access the plugin memory

Basic example

The following loads a Plugin from a file on disk using Manifest then calls a function with a string and prints the string output:

open Extism

let () =
  let plugin =
    Plugin.of_manifest_exn
    @@ Manifest.create [ Manifest.Wasm.file "test/code.wasm" ]
  in
  let res =
    Plugin.call_string_exn plugin ~name:"count_vowels" "input data"
  in
  print_endline res

Using the typed plugin interface you can pre-define plug-in functions:

open Extism

module Example = struct
  include Plugin.Typed.Init ()

  let count_vowels = exn @@ fn "count_vowels" Type.string Type.string
end

let () =
  let plugin =
    Example.of_plugin_exn
    @@ Plugin.of_manifest_exn
    @@ Manifest.create [ Manifest.Wasm.file "test/code.wasm" ]
  in
  let res =
    Example.count_vowels plugin "input data"
  in
  print_endline res

API

module Manifest = Extism_manifest

The Manifest module is a reference to the Extism_manifest package, it allows you to programatically construct Extism manifests.

module Val_type : sig ... end

Val_type enumerates the available Wasm types, this should only be used when implementing host functions

module Val : sig ... end

Val represents low-level WebAssembly values

module Type : sig ... end

Type defines conversions from OCaml values in and out of Extism memory

module Host_function : sig ... end

Host_function represents the plugin that is currently running from inside a host function definition

module Function : sig ... end

Function is used to create new a new function, which can be called from a WebAssembly plugin

module Plugin : sig ... end

Plugins contain functions that can be called

val set_log_file : 
  ?level:[ `Error | `Warn | `Info | `Debug | `Trace | `Filter of string ] ->
  string ->
  bool

Set the log file and level for all Extism plugins, the names stdout or stderr can be used to write to the terminal

type drain_logs = unit -> unit

val set_log_custom : 
  ?level:[ `Error | `Warn | `Info | `Debug | `Trace | `Filter of string ] ->
  (string -> unit) ->
  drain_logs

Set the log level and enable buffered logging. Returns a function that can be used to drain the logs

module Error : sig ... end

Extism error type

val with_plugin : (Plugin.t -> 'a) -> Plugin.t -> 'a

with_plugin f plugin uses Fun.protect to ensure that a plugin is freed when f finished executing

val extism_version : unit -> string

Returns the libextism version, not the version of the OCaml library