Skip to content

extism/ruby-sdk

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

93 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Extism Ruby Host SDK

This repo contains the ruby gem for integrating with the Extism runtime. Install this library into your host ruby application to run Extism plug-ins.

Installation

Install the Extism Runtime Dependency

For this library, you first need to install the Extism Runtime. You can download the shared object directly from a release or use the Extism CLI to install it:

sudo extism lib install latest

#=> Fetching https://github.com/extism/extism/releases/download/v0.5.2/libextism-aarch64-apple-darwin-v0.5.2.tar.gz
#=> Copying libextism.dylib to /usr/local/lib/libextism.dylib
#=> Copying extism.h to /usr/local/include/extism.h

Install the Gem

Add this library to your Gemfile:

gem 'extism', '~> 1.0.0'

Or if installing on the system level:

gem install extism

Getting Started

This guide should walk you through some of the concepts in Extism and this ruby library.

Note: You should be able to follow this guide by copy pasting the code into irb.

Creating A Plug-in

The primary concept in Extism is the plug-in. You can think of a plug-in as a code module stored in a .wasm file.

Since you may not have an Extism plug-in on hand to test, let's load a demo plug-in from the web:

# First require the library
require "extism"

url = "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"
manifest = Extism::Manifest.from_url url
plugin = Extism::Plugin.new(manifest)

Note: See the Manifest docs as it has a rich schema and a lot of options.

Calling A Plug-in's Exports

This plug-in was written in Rust and it does one thing, it counts vowels in a string. As such, it exposes one "export" function: count_vowels. We can call exports using Extism::Plugin#call:

plugin.call("count_vowels", "Hello, World!")
# => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}

All exports have a simple interface of bytes-in and bytes-out. This plug-in happens to take a string and return a JSON encoded string with a report of results.

Plug-in State

Plug-ins may be stateful or stateless. Plug-ins can maintain state b/w calls by the use of variables. Our count vowels plug-in remembers the total number of vowels it's ever counted in the "total" key in the result. You can see this by making subsequent calls to the export:

plugin.call("count_vowels", "Hello, World!")
# => {"count": 3, "total": 6, "vowels": "aeiouAEIOU"}
plugin.call("count_vowels", "Hello, World!")
# => {"count": 3, "total": 9, "vowels": "aeiouAEIOU"}

These variables will persist until this plug-in is freed or you initialize a new one.

Configuration

Plug-ins may optionally take a configuration object. This is a static way to configure the plug-in. Our count-vowels plugin takes an optional configuration to change out which characters are considered vowels. Example:

plugin = Extism::Plugin.new(manifest)
plugin.call("count_vowels", "Yellow, World!")
# => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}

plugin = Extism::Plugin.new(manifest, config: { vowels: "aeiouyAEIOUY" })
plugin.call("count_vowels", "Yellow, World!")
# => {"count": 4, "total": 4, "vowels": "aeiouAEIOUY"}

Host Functions

Let's extend our count-vowels example a little bit: Instead of storing the total in an ephemeral plug-in var, let's store it in a persistent key-value store!

Wasm can't use our KV store on it's own. This is where Host Functions come in.

Host functions allow us to grant new capabilities to our plug-ins from our application. They are simply some ruby methods you write which can be passed down and invoked from any language inside the plug-in.

Let's load the manifest like usual but load up this count_vowels_kvstore plug-in:

url = "https://github.com/extism/plugins/releases/latest/download/count_vowels_kvstore.wasm"
manifest = Extism::Manifest.from_url(url)

Note: The source code for this is here and is written in rust, but it could be written in any of our PDK languages.

Unlike our previous plug-in, this plug-in expects you to provide host functions that satisfy our its import interface for a KV store.

In the ruby sdk, we have a concept for this called a Host Environment. An environment is an instance of a class that implements any host functions your plug-in needs.

We want to expose two functions to our plugin, kv_write(key: String, value: Bytes) which writes a bytes value to a key and kv_read(key: String) -> Bytes which reads the bytes at the given key.

# pretend this is Redis or something :)
KV_STORE = {}

class KvEnvironment
  include Extism::HostEnvironment

  # We need to describe the wasm function signature of each host function
  # to register them to this environment
  register_import :kv_read, [Extism::ValType::PTR], [Extism::ValType::PTR]
  register_import :kv_write, [Extism::ValType::PTR, Extism::ValType::PTR], []

  def kv_read(plugin, inputs, outputs, _user_data)
    key = plugin.input_as_string(inputs.first)
    val = KV_STORE[key] || [0].pack('V') # get 4 LE bytes for 0 default
    puts "Read from key=#{key}"
    plugin.output_string(outputs.first, val)
  end

  def kv_write(plugin, inputs, _outputs, _user_data)
    key = plugin.input_as_string(inputs.first)
    val = plugin.input_as_string(inputs[1])
    puts "Writing value=#{val.unpack1('V')} from key=#{key}"
    KV_STORE[key] = val
  end
end

Note: In order to write host functions you should get familiar with the methods on the Extism::CurrentPlugin class. The plugin parameter is an instance of this class.

Now we just need to create a new host environment and pass it in when loading the plug-in. Here our environment initializer takes no arguments, but you could imagine putting some customer specific instance variables in there:

env = KvEnvironment.new
plugin = Extism::Plugin.new(manifest, environment: env)

Now we can invoke the event:

plugin.call("count_vowels", "Hello, World!")
# => Read from key=count-vowels"
# => Writing value=3 from key=count-vowels"
# => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}
plugin.call("count_vowels", "Hello, World!")
# => Read from key=count-vowels"
# => Writing value=6 from key=count-vowels"
# => {"count": 3, "total": 6, "vowels": "aeiouAEIOU"}