extism 1.0.0.pre.rc.2 → 1.0.0.pre.rc.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9de040945d856411394ee9e9631aeffdf7b89a6e1269788e823191a26c0e50a8
-  data.tar.gz: 9a588d3b134ee5e1d817d38bb4bd0b8abb92d48148c35d4b538870872dffafd3
+  metadata.gz: ff531578509d2c71f3db9d20e01fdbbba922e342f76dbb84aafa69ce94db3350
+  data.tar.gz: 163c31c8cddeec68fd774af387effcbd13e3a8e9ea40ab26445ab94fa6db75a3
 SHA512:
-  metadata.gz: a675e36bf299fbb2dc2457a35569ef491f0f6be308f7afe7e01603d83971fe6b7f8a23051bb385eb1de5a9be6948d8658128975aa3b183f02b54c9e0312abb58
-  data.tar.gz: '082c612825780d24869dd7a975adf67cf61f5a7e90b3c4b801cad6769ef69eb237e43621a118a95c6d376bc1d88e57fb0ba1f27519ffc31f52850a453c229865'
+  metadata.gz: a5b97afbbeddff3e52a0627832fa92b860ef921cee1b82d0f1a4753b2b9a47ae89810e2f2c8b061f94aff9fa639283a7886d06026e3c98a588693f86369cbdb1
+  data.tar.gz: 5399c2a2d9f0183bad275c212f7009b73ef9234ddc2cc4a90433972a3decb36926c967fd3935f20e58f2cb18966c9e76546e967db4882ecc01936eb0593092ab

data/.yardopts

@@ -1 +1,2 @@
 --readme README.md
+--exclude lib/extism/libextism.rb

data/Gemfile

@@ -1,16 +1,16 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-# Specify your gem's dependencies in extism.gemspec
-gemspec
-
-gem 'ffi', '~> 1.15.5'
-gem 'rake', '~> 13.0'
-
-group :development do
-  gem 'debug'
-  gem 'minitest', '~> 5.20.0'
-  gem 'rufo', '~> 0.13.0'
-  gem 'yard', '~> 0.9.28'
-end
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in extism.gemspec
+gemspec
+
+gem 'ffi', '~> 1.15.5'
+gem 'rake', '~> 13.0'
+
+group :development do
+  gem 'debug'
+  gem 'minitest', '~> 5.20.0'
+  gem 'rufo', '~> 0.13.0'
+  gem 'yard', '~> 0.9.28'
+end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    extism (1.0.0.pre.rc.2)
+    extism (1.0.0.pre.rc.3)
       ffi (>= 1.0.0)
 
 GEM
@@ -29,6 +29,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-22
+  x86_64-linux
 
 DEPENDENCIES
   debug

data/README.md

@@ -1,14 +1,14 @@
 # Extism Ruby Host SDK
 
-This repo houses the ruby gem for integrating with the [Extism](https://extism.org/) runtime. Install this library into your host ruby applications to run Extism plug-ins.
+This repo contains the ruby gem for integrating with the [Extism](https://extism.org/) runtime. Install this library into your host ruby application to run Extism plug-ins.
 
-> **Note**: This repo is 1.0 alpha version of the Ruby SDK and is a work in progress. We'd love any feedback you have on it, but consider using the supported ruby SDK in [extism/extism](https://github.com/extism/extism/tree/main/ruby) until we hit 1.0.
+> **Note**: This repo is 1.0 alpha version of the Ruby SDK and we may push breaking changes in between versions until we hit 1.0.0 in December, 2023. However, it is ready to use and you should use this if you're building a new integration. We'd love any feedback on it.
 
 ## Installation
 
-### Install the Extism Runtime
+### Install the Extism Runtime Dependency
 
-You first need to install the Extism Runtime which is a native shared object that this library uses to load and run the Wasm code. You can [download the shared library directly from a release](https://github.com/extism/extism/releases) or use the [Extism CLI](https://github.com/extism/cli) to install it:
+For this library, you first need to install the Extism Runtime. You can [download the shared object directly from a release](https://github.com/extism/extism/releases) or use the [Extism CLI](https://github.com/extism/cli) to install it:
 
 ```bash
 sudo extism lib install latest
@@ -18,14 +18,14 @@ sudo extism lib install latest
 #=> Copying extism.h to /usr/local/include/extism.h
 ```
 
-> **Note**: This library has breaking changes and targets 1.0 of the runtime. For the time being, install the runtime from our nightly development builds on git: `sudo extism lib install --version git`
+> **Note**: This library has breaking changes and targets 1.0 of the runtime. For the time being, install the runtime from our nightly development builds on git: `sudo extism lib install --version git`.
 
-### Install the Rubygem
+### Install the Gem
 
 Add this library to your [Gemfile](https://bundler.io/):
 
 ```ruby
-gem 'extism', '1.0.0.pre.rc.2'
+gem 'extism', '1.0.0.pre.rc.3'
 ```
 
 Or if installing on the system level:
@@ -36,41 +36,37 @@ gem install extism --pre
 
 ## Getting Started
 
-> *Note*: You should be able to follow this guide by copy pasting the code into `irb`.
-
-First you should require `"extism"`:
+This guide should walk you through some of the concepts in Extism and this ruby library.
 
-```ruby
-require "extism"
-```
+> *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. You can [learn more about plug-ins here](https://extism.org/concepts/plug-in).
+The primary concept in Extism is the [plug-in](https://extism.org/docs/concepts/plug-in). You can think of a plug-in as a code module stored in a `.wasm` file.
 
-You'll generally load the plug-in from disk, but for simplicity let's load a pre-built demo plug-in from the web:
+Since you may not have an Extism plug-in on hand to test, let's load a demo plug-in from the web:
 
 ```ruby
-manifest = {
-  wasm: [
-    { url: "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm" }
-  ]
-}
+# 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**: The schema for this manifest can be found here: [https://extism.org/docs/concepts/manifest/](https://extism.org/docs/concepts/manifest/)
+> **Note**: See [the Manifest docs](https://extism.github.io/ruby-sdk/Extism/Manifest.html) 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](https://extism.github.io/ruby-sdk/Extism/Plugin.html#call-instance_method):
+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](https://extism.github.io/ruby-sdk/Extism/Plugin.html#call-instance_method):
 
 ```ruby
 plugin.call("count_vowels", "Hello, World!")
 # => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}
 ```
 
-All exports have a simple interface of optional bytes in, and optional bytes out. This plug-in happens to take a string and return a JSON encoded string with a report of results.
+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
 
@@ -101,106 +97,73 @@ plugin.call("count_vowels", "Yellow, World!")
 
 ### Host Functions
 
-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 to and invoked from any language inside the plug-in.
-
-> *Note*: Host functions can be a complicated topic. Please review this [concept doc](https://extism.org/docs/concepts/host-functions) if you are unsure how they work.
-
-### Host Functions Example
+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!
 
-We've created a contrived, but familiar example to illustrate this. Suppose you are a stripe-like payments platform.
-When a [charge.succeeded](https://stripe.com/docs/api/events/types#event_types-charge.succeeded) event occurs, we will call the `on_charge_succeeded` function on our merchant's plug-in and let them decide what to do with it. Here our merchant has some very specific requirements, if the account has spent more than $100, their currency is USD, and they have no credits on their account, it will add $10 credit to their account and then send them an email.
+Wasm can't use our KV store on it's own. This is where [Host Functions](https://extism.org/docs/concepts/host-functions) come in.
 
-> *Note*: The source code for this is [here](https://github.com/extism/plugins/blob/main/store_credit/src/lib.rs) and is written in rust, but it could be written in any of our PDK languages.
+[Host functions](https://extism.org/docs/concepts/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.
 
-First let's create the manifest for our plug-in like usual but load up the `store_credit` plug-in:
+Let's load the manifest like usual but load up this `count_vowels_kvstore` plug-in:
 
 ```ruby
-manifest = {
-  wasm: [
-    { url: "https://github.com/extism/plugins/releases/latest/download/store_credit.wasm" }
-  ]
-}
+url = "https://github.com/extism/plugins/releases/latest/download/count_vowels_kvstore.wasm"
+manifest = Extism::Manifest.from_url(url)
 ```
 
-But, unlike our `count_vowels` plug-in, this plug-in expects you to provide host functions that satisfy our plug-in's imports.
+> *Note*: The source code for this is [here](https://github.com/extism/plugins/blob/main/count_vowels_kvstore/src/lib.rs) and is written in rust, but it could be written in any of our PDK languages.
 
-In the ruby sdk, we have a concept for this called a [Host Environment](https://extism.github.io/ruby-sdk/Extism/HostEnvironment.html). An environment is just an object that responds to `host_functions` and returns an array of `Extism::Function`s. We want to expose two capabilities to our plugin, `add_credit(customer_id, amount)` which adds credit to an account and `send_email(customer_id, email)` which sends them an email.
+Unlike our previous plug-in, this plug-in expects you to provide host functions that satisfy our its import interface for a KV store.
 
-```ruby
+In the ruby sdk, we have a concept for this called a [Host Environment](https://extism.github.io/ruby-sdk/Extism/HostEnvironment.html). An environment is an instance of a class that implements any host functions your plug-in needs.
 
-# This is global is just for demo purposes but would in
-# reality be in a database or something
-CUSTOMER = {
-  full_name: 'John Smith',
-  customer_id: 'abcd1234',
-  total_spend: {
-    currency: 'USD',
-    amount_in_cents: 20_000
-  },
-  credit: {
-    currency: 'USD',
-    amount_in_cents: 0
-  }
-}
-
-class MyEnvironment
-  include Extism::HostEnvironment
+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`.
 
-  # we need to register each import that the plug-in expects and match the Wasm signature
-  # register_import takes the name, the param types, and the return types
-  register_import :add_credit, [Extism::ValType::I64, Extism::ValType::I64], [Extism::ValType::I64]
-  register_import :send_email, [Extism::ValType::I64, Extism::ValType::I64], []
+```ruby
+# pretend this is Redis or something :)
+KV_STORE = {}
 
-  def add_credit(plugin, inputs, outputs, _user_data)
-    # add_credit takes a string `customer_id` as the first parameter
-    customer_id = plugin.input_as_string(inputs.first)
-    # it takes an object `amount` { amount_in_cents: int, currency: string } as the second parameter
-    amount = plugin.input_as_json(inputs[1])
+class KvEnvironment
+  include Extism::HostEnvironment
 
-    # we're just going to print it out and add to the CUSTOMER global
-    puts "Adding Credit #{amount} to customer #{customer_id}"
-    CUSTOMER[:credit][:amount_in_cents] += amount['amount_in_cents']
+  # 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], []
 
-    # add_credit returns a Json object with the new customer details
-    plugin.return_json(outputs.first, CUSTOMER)
+  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 send_email(plugin, inputs, _outputs, _user_data)
-    # send_email takes a string `customer_id` as the first parameter
-    customer_id = plugin.input_as_string(inputs.first)
-    # it takes an object `email` { subject: string, body: string } as the second parameter
-    email = plugin.input_as_json(inputs[1])
-
-    # we'll just print it but you could imagine we'd put something 
-    # in a database or call an internal api to send this email
-    puts "Sending email #{email} to customer #{customer_id}"
-
-    # it doesn't return anything
+  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
 ```
 
-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 merchant specific instance variables in there:
+> *Note*: In order to write host functions you should get familiar with the methods on the [Extism::CurrentPlugin](https://extism.github.io/ruby-sdk/Extism/CurrentPlugin.html) 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:
 
 ```ruby
-env = MyEnvironment.new
+env = KvEnvironment.new
 plugin = Extism::Plugin.new(manifest, environment: env)
 ```
 
 Now we can invoke the event:
 
 ```ruby
-event = {
-  event_type: 'charge.succeeded',
-  customer: CUSTOMER
-}
-result = plugin.call('on_charge_succeeded', JSON.generate(event))
-```
-
-This will print:
-
-```
-Adding Credit {"amount_in_cents"=>1000, "currency"=>"USD"} for customer abcd1234
-Sending email {"subject"=>"A gift for you John Smith", "body"=>"You have received $10 in store credi
-t!"} to customer abcd1234
+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"}
 ```

data/Rakefile

@@ -1,12 +1,12 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
-end
-
-task default: :test
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+task default: :test

data/lib/extism/current_plugin.rb

@@ -16,15 +16,15 @@ module Extism
 
     # Allocates a memory block in the plugin
     #
-    # @example
+    # @example Allocate 1kB
     #   mem = current_plugin.alloc(1_024)
-    #   mem.put_bytes(0, "Hello, World!")
+    #   current_plugin.free(mem)
     #
-    # @param amount [Integer] The amount in bytes to allocate
+    # @param num_bytes [Integer] The amount in bytes to allocate
     # @return [Extism::Memory] The reference to the freshly allocated memory
-    def alloc(amount)
-      offset = LibExtism.extism_current_plugin_memory_alloc(@ptr, amount)
-      Memory.new(offset, amount)
+    def alloc(num_bytes)
+      offset = LibExtism.extism_current_plugin_memory_alloc(@ptr, num_bytes)
+      Memory.new(offset, num_bytes)
     end
 
     # Frees the memory block
@@ -142,7 +142,7 @@ module Extism
     private
 
     # Returns a raw pointer (absolute to the host) to the given memory block
-    # Be careful with this. it's not exposed for a reason.
+    # **Danger**: Be careful with this. it's not exposed for a reason.
     # This is a pointer in host memory so it could read outside of the plugin
     # if manipulated
     def memory_ptr(mem)

data/lib/extism/host_environment.rb

@@ -21,6 +21,12 @@ module Extism
       base.class_variable_set(:@@import_funcs, [])
     end
 
+    # Creates the host functions to pass to the plug-in on intialization.
+    # Used internally by the Plugin initializer
+    #
+    # @see Extism::Plugin::new
+    #
+    # @return [Array<Extism::Function>]
     def host_functions
       import_funcs = self.class.class_variable_get(:@@import_funcs)
       import_funcs.map do |f|
@@ -33,12 +39,21 @@ module Extism
         )
       end
     end
-  end
 
-  module ClassMethods
-    def register_import(func_name, parameters, returns)
-      import_funcs = class_variable_get(:@@import_funcs)
-      import_funcs << [func_name, parameters, returns]
+    module ClassMethods
+      # Register an import by name. You must know the wasm signature
+      # of the function to do this.
+      #
+      # @example
+      #   register_import :my_func, [Extism::ValType::I64], [Extism::ValType::F64]
+      #
+      # @param [Symbol | String] func_name The name of the wasm import function. Assumes `env` namespace.
+      # @param [Array<Extism::ValType>] parameters The Wasm types of the parameters that the import takes
+      # @param [Array<Extism::ValType>] returns The Wasm types of the returns that the import returns. Will usually be just be one of these.
+      def register_import(func_name, parameters, returns)
+        import_funcs = class_variable_get(:@@import_funcs)
+        import_funcs << [func_name, parameters, returns]
+      end
     end
   end
 end

data/lib/extism/manifest.rb

@@ -0,0 +1,68 @@
+module Extism
+  # The manifest represents a recipe to build a plug-in.
+  # It generally consists of a path to one wasm module
+  # but could contain more. It also helps you define some
+  # options and restrictions on the runtime behavior of the plug-in.
+  # See https://extism.org/docs/concepts/manifest for more info.
+  class Manifest
+    attr_reader :manifest_data
+
+    # Create a manifest of a single wasm from url.
+    # Look at {Manifest#initialize} for an interface with more control
+    #
+    # @see Manifest::initialize
+    # @param [String] url The url to the wasm module
+    # @param [String | nil] hash An optional sha256 integrity hash. Defaults to nil
+    # @param [String | nil] name An optional name. Defaults to nil
+    # @return [Extism::Manifest]
+    def self.from_url(url, hash: nil, name: nil)
+      wasm = { url: url }
+      wasm[:hash] = hash unless hash.nil?
+      wasm[:name] = name unless hash.nil?
+
+      Manifest.new({ wasm: [wasm] })
+    end
+
+    # Create a manifest of a single wasm from file path.
+    # Look at {Manifest#initialize} for an interface with more control
+    #
+    # @see Manifest::initialize
+    # @param [String] path The path to the wasm module on disk
+    # @param [String | nil] hash An optional sha256 integrity hash. Defaults to nil
+    # @param [String | nil] name An optional name. Defaults to nil
+    # @return [Extism::Manifest]
+    def self.from_path(path, hash: nil, name: nil)
+      wasm = { path: path }
+      wasm[:hash] = hash unless hash.nil?
+      wasm[:name] = name unless hash.nil?
+
+      Manifest.new({ wasm: [wasm] })
+    end
+
+    # Create a manifest of a single wasm module with raw binary data.
+    # Look at {Manifest#initialize} for an interface with more control
+    # Consider using a file path instead of the raw wasm binary in memory.
+    # The performance is often better letting the runtime load the binary itself.
+    #
+    # @see Manifest::initialize
+    # @param [String] data The binary data of the wasm module
+    # @param [String | nil] hash An optional sha256 integrity hash. Defaults to nil
+    # @param [String | nil] name An optional name. Defaults to nil
+    # @return [Extism::Manifest]
+    def self.from_bytes(data, hash: nil, name: nil)
+      wasm = { data: data }
+      wasm[:hash] = hash unless hash.nil?
+      wasm[:name] = name unless hash.nil?
+
+      Manifest.new({ wasm: [wasm] })
+    end
+
+    # Initialize a manifest
+    # See https://extism.org/docs/concepts/manifest for schema
+    #
+    # @param [Hash] data The Hash data that conforms the Manifest schema
+    def initialize(data)
+      @manifest_data = data
+    end
+  end
+end

data/lib/extism/plugin.rb

@@ -4,19 +4,29 @@ module Extism
   class Plugin
     # Intialize a plugin
     #
-    # @example
-    #   manifest = {
-    #     wasm: [
-    #       { url: "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm" }
-    #     ]
-    #   }
+    # @example Initialize a plugin from a url
+    #   manifest = Extism::Manifest.from_url "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"
     #   plugin = Extism::Plugin.new(manifest)
     #
-    # @param wasm [Hash, String] The manifest as a Hash or WASM binary as a String. See https://extism.org/docs/concepts/manifest/.
+    # @example Pass a config object to configure the plug-in
+    #   plugin = Extism::Plugin.new(manifest, config: { hello: "world" })
+    #
+    # @example Initalize a plug-in that needs WASI
+    #   plugin = Extism::Plugin.new(manifest, wasi: true)
+    #
+    # @param wasm [Hash, String, Manifest] The manifest as a Hash or WASM binary as a String. See https://extism.org/docs/concepts/manifest/.
     # @param wasi [Boolean] Enable WASI support
     # @param config [Hash] The plugin config
     def initialize(wasm, environment: nil, functions: [], wasi: false, config: nil)
-      wasm = JSON.generate(wasm) if wasm.instance_of?(Hash)
+      wasm = case wasm
+             when Hash
+               JSON.generate(wasm)
+             when Manifest
+               JSON.generate(wasm.manifest_data)
+             else
+               wasm
+             end
+
       code = FFI::MemoryPointer.new(:char, wasm.bytesize)
       errmsg = FFI::MemoryPointer.new(:pointer)
       code.put_bytes(0, wasm)

data/lib/extism/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Extism
-  VERSION = '1.0.0-rc.2'
+  VERSION = '1.0.0-rc.3'
 end

data/lib/extism/wasm.rb

@@ -1,7 +1,13 @@
 module Extism
+  # Extism specific values for Wasm types. Useful when you need to describe
+  # something in pure wasm like host function signatures.
+  #
+  # @example
+  #   register_import :hostfunc, [Extism::ValType::I32, Extism::ValType::F64], [Extism::ValType::I64]
   module ValType
     I32 = 0
     I64 = 1
+    PTR = 1
     F32 = 2
     F64 = 3
     V128 = 4
@@ -9,6 +15,7 @@ module Extism
     EXTERN_REF = 6
   end
 
+  # A raw Wasm value. Contains the type and the data
   class Val
     def initialize(ptr)
       @c_val = LibExtism::ExtismVal.new(ptr)
@@ -20,6 +27,8 @@ module Extism
         :i32
       when :I64
         :i64
+      when :PTR
+        :i64
       when :F32
         :f32
       when :F64
@@ -50,7 +59,10 @@ module Extism
     end
   end
 
-  # Represents a host function
+  # Represents a host function. This is mostly for internal use and you should
+  # try to use HostEnvironment instead
+  #
+  # @see Extism::HostEnvironment
   class Function
     # Create a new host function
     #
@@ -81,6 +93,9 @@ module Extism
       returns = LibExtism.from_int_array(@returns)
       @_pointer = LibExtism.extism_function_new(@name, args, @params.length, returns, @returns.length, c_func, free,
                                                 nil)
+      $FUNCTIONS[object_id] = { function: @_pointer}
+      ObjectSpace.define_finalizer(self, $FREE_FUNCTION)
+      return @_pointer
     end
 
     def c_func

data/lib/extism.rb

@@ -1,38 +1,59 @@
-require 'ffi'
-require 'json'
-require_relative './extism/version'
-require_relative './extism/plugin'
-require_relative './extism/current_plugin'
-require_relative './extism/libextism'
-require_relative './extism/wasm'
-require_relative './extism/host_environment'
-
-module Extism
-  class Error < StandardError
-  end
-
-  # Return the version of Extism
-  #
-  # @return [String] The version string of the Extism runtime
-  def self.extism_version
-    LibExtism.extism_version
-  end
-
-  # Set log file and level, this is a global configuration
-  # @param name [String] The path to the logfile
-  # @param level [String] The log level. One of {"debug", "error", "info", "trace" }
-  def self.set_log_file(name, level = nil)
-    LibExtism.extism_log_file(name, level)
-  end
-
-  $PLUGINS = {}
-  $FREE_PLUGIN = proc { |ptr|
-    x = $PLUGINS[ptr]
-    unless x.nil?
-      LibExtism.extism_plugin_free(x[:plugin])
-      $PLUGINS.delete(ptr)
-    end
-  }
-
-  Memory = Struct.new(:offset, :len)
-end
+require 'ffi'
+require 'json'
+require_relative './extism/manifest'
+require_relative './extism/version'
+require_relative './extism/plugin'
+require_relative './extism/current_plugin'
+require_relative './extism/libextism'
+require_relative './extism/wasm'
+require_relative './extism/host_environment'
+
+module Extism
+  class Error < StandardError
+  end
+
+  # Return the version of Extism
+  #
+  # @return [String] The version string of the Extism runtime
+  def self.extism_version
+    LibExtism.extism_version
+  end
+
+  # Set log file and level, this is a global configuration
+  # @param name [String] The path to the logfile
+  # @param level [String] The log level. One of {"debug", "error", "info", "trace" }
+  def self.set_log_file(name, level = nil)
+    LibExtism.extism_log_file(name, level)
+  end
+
+  $PLUGINS = {}
+  $FREE_PLUGIN = proc { |ptr|
+    x = $PLUGINS[ptr]
+    unless x.nil?
+      LibExtism.extism_plugin_free(x[:plugin])
+      $PLUGINS.delete(ptr)
+    end
+  }
+
+  
+  $FUNCTIONS = {}
+  $FREE_FUNCTION = proc { |ptr|
+    x = $FUNCTIONS[ptr]
+    unless x.nil?
+      LibExtism.extism_function_free(x[:function])
+      $FUNCTIONS.delete(ptr)
+    end
+  }
+
+  # Represents a "block" of memory in Extism.
+  # This memory is in the communication buffer b/w the
+  # guest in the host and technically lives in host memory.
+  class Memory
+    attr_reader :offset, :len
+
+    def initialize(offset, len)
+      @offset = offset
+      @len = len
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: extism
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.rc.2
+  version: 1.0.0.pre.rc.3
 platform: ruby
 authors:
 - zach
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-29 00:00:00.000000000 Z
+date: 2023-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -42,11 +42,13 @@ files:
 - lib/extism/current_plugin.rb
 - lib/extism/host_environment.rb
 - lib/extism/libextism.rb
+- lib/extism/manifest.rb
 - lib/extism/plugin.rb
 - lib/extism/version.rb
 - lib/extism/wasm.rb
 - sig/extism.rbs
 - wasm/count_vowels.wasm
+- wasm/count_vowels_kvstore.wasm
 - wasm/reflect.wasm
 - wasm/store_credit.wasm
 homepage: https://github.com/extism/extism