extism 1.0.0.pre.rc.1 → 1.0.0.pre.rc.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed731bd8ff622c67eee229b14588ce7e6311337d5b3c888aca2e116f77758b4b
-  data.tar.gz: e0bea72460c008c16dc4747c39ebb09643c48ddecf6c5a5efc0bae754609ebdb
+  metadata.gz: ff531578509d2c71f3db9d20e01fdbbba922e342f76dbb84aafa69ce94db3350
+  data.tar.gz: 163c31c8cddeec68fd774af387effcbd13e3a8e9ea40ab26445ab94fa6db75a3
 SHA512:
-  metadata.gz: 81e70c7e6b7b649733f68b4c284104155ccec044f9604882b99cb54b626a777aa4e7dcfdc51a224b00600c6ee705f4a9b5761c85b5fb73ebff542be94ae5627c
-  data.tar.gz: 39ee1905ea234277c040698eae6098dfcc5d0ffac53185598536ac915dc4999c316bdab88d5ccb716895bf006d2cb25fc6b636640a5402b5b8aaf5b658653fd7
+  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.1)
+    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,191 +1,169 @@
-# Extism Ruby Host SDK
-
-> **Note**: This houses the 1.0 version of the Ruby SDK and is a work in progress. Please use the ruby SDK in extism/extism until we hit 1.0.
-
-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 plugins.
-
-## Installation
-
-You first need to [install the Extism runtime](https://extism.org/docs/install).
-
-Add this library to your [Gemfile](https://bundler.io/):
-
-```ruby
-gem 'extism', '1.0.0-rc.1'
-```
-
-Or if installing on the system level:
-
-```
-gem install extism
-```
-
-## Getting Started
-
-First you should require `"extism"`:
-
-```ruby
-require "extism"
-```
-
-### Creating A Plug-in
-
-The primary concept in Extism is the plug-in. You can think of a plug-in as a code module. It has imports and it has exports. These imports and exports define the interface, or your API. You decide what they are called and typed, and what they do. Then the plug-in developer implements them and you can call them.
-
-The code for a plug-in exist as a binary wasm module. We can load this with the raw bytes or we can use the manifest to tell Extism how to load it from disk or the web.
-
-For simplicity let's load one from the web:
-
-```ruby
-manifest = {
-  wasm: [
-    { url: "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm" }
-  ]
-}
-plugin = Extism::Plugin.new(manifest)
-```
-
-> **Note**: The schema for this manifest can be found here: https://extism.org/docs/concepts/manifest/
-
-### Calling A Plug-in's Exports
-
-This plug-in was written in C 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`:
-
-```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.
-
-
-### 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:
-
-```ruby
-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:
-
-```ruby
-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
-
-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
-
-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.
-
-> *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.
-
-First let's create the manifest for our plug-in like usual but load up the store_credit plug-in:
-
-```ruby
-manifest = {
-  wasm: [
-    { url: "https://github.com/extism/plugins/releases/latest/download/store_credit.wasm" }
-  ]
-}
-```
-
-But, unlike our original plug-in, this plug-in expects you to provide host functions that satisfy our plug-ins imports.
-
-In the ruby sdk, we have a concept for this call an "host environment". 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.
-
-```ruby
-
-# 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 Environment
-  include Extism::HostEnvironment
-
-  register_import :add_credit, [Extism::ValType::I64, Extism::ValType::I64], [Extism::ValType::I64]
-  register_import :send_email, [Extism::ValType::I64, Extism::ValType::I64], []
-
-  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])
-
-    # 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']
-
-    # add_credit returns a Json object with the new customer details
-    plugin.return_json(outputs.first, CUSTOMER)
-  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
-  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:
-
-```ruby
-env = Environment.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
-```
+# Extism Ruby Host SDK
+
+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 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 Dependency
+
+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
+
+#=> 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
+```
+
+> **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 Gem
+
+Add this library to your [Gemfile](https://bundler.io/):
+
+```ruby
+gem 'extism', '1.0.0.pre.rc.3'
+```
+
+Or if installing on the system level:
+
+```
+gem install extism --pre
+```
+
+## 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](https://extism.org/docs/concepts/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:
+
+```ruby
+# 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](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):
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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](https://extism.org/docs/concepts/host-functions) come in.
+
+[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.
+
+Let's load the manifest like usual but load up this `count_vowels_kvstore` plug-in:
+
+```ruby
+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](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.
+
+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](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.
+
+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`.
+
+```ruby
+# 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](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 = KvEnvironment.new
+plugin = Extism::Plugin.new(manifest, environment: env)
+```
+
+Now we can invoke the event:
+
+```ruby
+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,22 +16,34 @@ module Extism
 
     # Allocates a memory block in the plugin
     #
-    # @param amount [Integer] The amount in bytes to allocate
+    # @example Allocate 1kB
+    #   mem = current_plugin.alloc(1_024)
+    #   current_plugin.free(mem)
+    #
+    # @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
     #
+    # @example
+    #   mem = current_plugin.alloc(1_024)
+    #   current_plugin.free(mem)
+    #
     # @param memory [Extism::Memory] The memory object you wish to free
     # @return [Extism::Memory] The reference to the freshly allocated memory
     def free(memory)
       LibExtism.extism_current_plugin_memory_free(@ptr, memory.offset)
     end
 
-    # Gets the memory block at a given offset
+    # Gets the memory block at a given offset. Note: try to use input_* and output_* methods where possible.
+    #
+    # @example
+    #   mem = current_plugin.memory_at_offset(123456789)
+    #   current_plugin.free(mem)
     #
     # @raise [Extism::Error] if memory block could not be found
     #
@@ -48,6 +60,10 @@ module Extism
     #
     # @raise [Extism::Error] if memory block could not be found
     #
+    # @example
+    #   param1 = current_plugin.input_as_string(inputs.first)
+    #   raise "Failed" unless param1 == "First param from plug-in host function call"
+    #
     # @param input [Extism::Val] The input val from the host function
     # @return [String] raw bytes as a string
     def input_as_string(input)
@@ -57,10 +73,14 @@ module Extism
       memory_ptr(mem).read_bytes(mem.len)
     end
 
-    # Gets the input as a string
+    # Gets the input as a JSON parsed Hash
     #
     # @raise [Extism::Error] if memory block could not be found
     #
+    # @example
+    #   param1 = current_plugin.input_as_json(inputs.first)
+    #   raise "Failed" unless param1 == {hello: "world"}
+    #
     # @param input [Extism::Val] The input val from the host function
     # @return [Hash] The Hash object
     def input_as_json(input)
@@ -73,6 +93,10 @@ module Extism
 
     # Sets string to the return of the host function
     #
+    # @example
+    #   msg = "A string returned from the host function"
+    #   current_plugin.output_string(outputs.first, msg)
+    #
     # @raise [Extism::Error] if memory block could not be found
     #
     # @param output [Extism::Val] The output val from the host function
@@ -85,6 +109,10 @@ module Extism
 
     # Sets json to the return of the host function
     #
+    # @example
+    #   msg = {hello: "world"}
+    #   current_plugin.output_json(outputs.first, msg)
+    #
     # @raise [Extism::Error] if memory block could not be found
     #
     # @param output [Extism::Val] The output val from the host function
@@ -114,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

@@ -1,10 +1,32 @@
 module Extism
+  # Represents an "environment" that can be imported to a plug-in
+  #
+  # @example
+  #   class MyEnvironment
+  #     include Extism::HostEnvironment
+  #     # 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 :reflect, [Extism::ValType::I64], [Extism::ValType::I64]
+  #
+  #     # reflect just takes a string from the plug-in and reflects it back in return
+  #     def reflect(plugin, inputs, outputs, _user_data)
+  #       msg = plugin.input_as_string(inputs.first)
+  #       plugin.output_string(outputs.first, msg)
+  #     end
+  #   end
+  #
   module HostEnvironment
     def self.included(base)
       base.extend ClassMethods
       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|
@@ -17,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,11 +4,29 @@ module Extism
   class Plugin
     # Intialize a plugin
     #
-    # @param wasm [Hash, String] The manifest as a Hash or WASM binary as a String. See https://extism.org/docs/concepts/manifest/.
+    # @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)
+    #
+    # @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)
@@ -46,6 +64,11 @@ module Extism
 
     # Call a function by name
     #
+    # @example
+    #   input = JSON.generate({hello: "world"})
+    #   result = plugin.call("my_func", input)
+    #   output = JSON.parse(result)
+    #
     # @param name [String] The function name
     # @param data [String] The input data for the function
     # @return [String] The output from the function in String form

data/lib/extism/version.rb

@@ -1,5 +1,5 @@
-# frozen_string_literal: true
-
-module Extism
-  VERSION = '1.0.0-rc.1'
-end
+# frozen_string_literal: true
+
+module Extism
+  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.1
+  version: 1.0.0.pre.rc.3
 platform: ruby
 authors:
 - zach
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-21 00:00:00.000000000 Z
+date: 2023-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -38,16 +38,17 @@ files:
 - Makefile
 - README.md
 - Rakefile
-- example.rb
 - lib/extism.rb
 - 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

data/example.rb

@@ -1,11 +0,0 @@
-require "./lib/extism"
-require "json"
-
-manifest = {
-  :wasm => [{ :path => "../wasm/code.wasm" }],
-}
-
-plugin = Extism::Plugin.new(manifest)
-res = JSON.parse(plugin.call("count_vowels", ARGV[0] || "this is a test"))
-
-puts res["count"]