extism 0.5.0 → 1.0.0.pre.rc.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 844243a86e28c001eceea6a44a3e73b07aea648d608b2c3e989d0c1185e6207c
-  data.tar.gz: 13caf6cf47b8cf7640a194a3a91607392f5f5a963c8dca56ff466c92055ea17a
+  metadata.gz: 9de040945d856411394ee9e9631aeffdf7b89a6e1269788e823191a26c0e50a8
+  data.tar.gz: 9a588d3b134ee5e1d817d38bb4bd0b8abb92d48148c35d4b538870872dffafd3
 SHA512:
-  metadata.gz: c78963cf077ac7d85710554f781b6a4e4dac2352bd89ecbc62852a33b4a1ada70f4728eea80b6b2894d3508ce164f817c70bddc537958514fb0353d63ee02252
-  data.tar.gz: c9270b4c474c816a743fd5ba1efd9c37b765ee177d59bae93a0e17540d91ae95e618292c257e6873b198e508fb79cf051156bf397cefb812554be0cb52c0db2e
+  metadata.gz: a675e36bf299fbb2dc2457a35569ef491f0f6be308f7afe7e01603d83971fe6b7f8a23051bb385eb1de5a9be6948d8658128975aa3b183f02b54c9e0312abb58
+  data.tar.gz: '082c612825780d24869dd7a975adf67cf61f5a7e90b3c4b801cad6769ef69eb237e43621a118a95c6d376bc1d88e57fb0ba1f27519ffc31f52850a453c229865'

data/.yardopts

@@ -1,2 +1 @@
---readme GETTING_STARTED.md
-- GETTING_STARTED.md
+--readme README.md

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,43 @@
+PATH
+  remote: .
+  specs:
+    extism (1.0.0.pre.rc.2)
+      ffi (>= 1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    debug (1.8.0)
+      irb (>= 1.5.0)
+      reline (>= 0.3.1)
+    ffi (1.15.5)
+    io-console (0.6.0)
+    irb (1.8.1)
+      rdoc
+      reline (>= 0.3.8)
+    minitest (5.20.0)
+    psych (5.1.0)
+      stringio
+    rake (13.0.6)
+    rdoc (6.5.0)
+      psych (>= 4.0.0)
+    reline (0.3.8)
+      io-console (~> 0.5)
+    rufo (0.13.0)
+    stringio (3.0.8)
+    yard (0.9.34)
+
+PLATFORMS
+  arm64-darwin-22
+
+DEPENDENCIES
+  debug
+  extism!
+  ffi (~> 1.15.5)
+  minitest (~> 5.20.0)
+  rake (~> 13.0)
+  rufo (~> 0.13.0)
+  yard (~> 0.9.28)
+
+BUNDLED WITH
+   2.4.10

data/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2022 Dylibso, Inc.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Makefile

@@ -1,33 +1,39 @@
-RUBYGEMS_API_KEY ?=
-
-.PHONY: prepare test
-
-prepare:
-	bundle install
-	bundle binstubs --all
-
-test: prepare
-	bundle exec rake test
-
-clean:
-	rm -f extism-*.gem
-
-publish-local: clean prepare
-	gem build extism.gemspec
-	gem push extism-*.gem
-
-publish: clean prepare
-	gem build extism.gemspec
-	GEM_HOST_API_KEY=$(RUBYGEMS_API_KEY) gem push extism-*.gem
-
-lint:
-	bundle exec rufo --check .
-
-format:
-	bundle exec rufo .
-
-docs:
-	bundle exec yard
-
-show-docs: docs
-	open doc/index.html
+RUBYGEMS_API_KEY ?=
+
+.PHONY: prepare test
+
+prepare:
+	bundle install
+	bundle binstubs --all
+
+test: prepare
+	bundle exec rake test
+
+clean:
+	rm -f extism-*.gem
+
+publish-local: clean prepare
+	gem build extism.gemspec
+	gem push extism-*.gem
+
+publish: clean prepare
+	gem build extism.gemspec
+	GEM_HOST_API_KEY=$(RUBYGEMS_API_KEY) gem push extism-*.gem
+
+lint:
+	bundle exec rufo --check .
+
+format:
+	bundle exec rufo .
+
+docs:
+	bundle exec yard
+
+show-docs: docs
+	open doc/index.html
+
+seed:
+	curl -L https://github.com/extism/plugins/releases/latest/download/count_vowels.debug.wasm > wasm/count_vowels.wasm
+	curl -L https://github.com/extism/plugins/releases/latest/download/reflect.debug.wasm > wasm/reflect.wasm
+	curl -L https://github.com/extism/plugins/releases/latest/download/store_credit.debug.wasm > wasm/store_credit.wasm
+

data/README.md

@@ -0,0 +1,206 @@
+# 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.
+
+> **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.
+
+## Installation
+
+### Install the Extism Runtime
+
+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:
+
+```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 Rubygem
+
+Add this library to your [Gemfile](https://bundler.io/):
+
+```ruby
+gem 'extism', '1.0.0.pre.rc.2'
+```
+
+Or if installing on the system level:
+
+```
+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"`:
+
+```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 stored in a `.wasm` file. You can [learn more about plug-ins here](https://extism.org/concepts/plug-in).
+
+You'll generally load the plug-in from disk, but for simplicity let's load a pre-built demo plug-in 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/](https://extism.org/docs/concepts/manifest/)
+
+### 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 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 `count_vowels` plug-in, this plug-in expects you to provide host functions that satisfy our plug-in's imports.
+
+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.
+
+```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 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 :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 = MyEnvironment.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
+```

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

@@ -0,0 +1,153 @@
+module Extism
+  # Represents a reference to a plugin in a host function
+  # Use this class to read and write to the memory of the plugin
+  # These methods allow you to get data in and out of the plugin
+  # in a host function
+  class CurrentPlugin
+    # let's not let people construct these since it comes from a pointer
+    private_class_method :new
+
+    # Initialize a CurrentPlugin given an pointer
+    #
+    # @param ptr [FFI::Pointer] the raw pointer to the plugin
+    def initialize(ptr)
+      @ptr = ptr
+    end
+
+    # Allocates a memory block in the plugin
+    #
+    # @example
+    #   mem = current_plugin.alloc(1_024)
+    #   mem.put_bytes(0, "Hello, World!")
+    #
+    # @param amount [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)
+    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. 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
+    #
+    # @param offset [Integer] The offset pointer to the memory. This is relative to the plugin not the host.
+    # @return [Extism::Memory] The reference to the memory block if found
+    def memory_at_offset(offset)
+      len = LibExtism.extism_current_plugin_memory_length(@ptr, offset)
+      raise Extism::Error, "Could not find memory block at offset #{offset}" if len.zero?
+
+      Memory.new(offset, len)
+    end
+
+    # Gets the input as a string
+    #
+    # @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)
+      raise ArgumentError, 'input is not an Extism::Val' unless input.instance_of? Extism::Val
+
+      mem = memory_at_offset(input.value)
+      memory_ptr(mem).read_bytes(mem.len)
+    end
+
+    # 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)
+      raise ArgumentError, 'input is not an Extism::Val' unless input.instance_of? Extism::Val
+
+      mem = memory_at_offset(input.value)
+      str = memory_ptr(mem).read_bytes(mem.len)
+      JSON.parse(str)
+    end
+
+    # 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
+    # @param bytes [String] The bytes to set
+    def output_string(output, bytes)
+      mem = alloc(bytes.length)
+      memory_ptr(mem).put_bytes(0, bytes)
+      set_return(output, mem.offset)
+    end
+
+    # 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
+    # @param obj [Hash] The hash object to turn to JSON
+    def output_json(output, obj)
+      bytes = JSON.generate(obj)
+      mem = alloc(bytes.length)
+      memory_ptr(mem).put_bytes(0, bytes)
+      set_return(output, mem.offset)
+    end
+
+    # Sets the return value parameter
+    #
+    # @raise [Extism::Error] if memory block could not be found
+    #
+    # @param output [Extism::Val] The output val from the host function
+    # @param value [Integer | Float] The i32 value
+    def set_return(output, value)
+      case output.type
+      when :i32, :i64, :f32, :f64
+        output.value = value
+      else
+        raise ArgumentError, "Don't know how to set output type #{output.type}"
+      end
+    end
+
+    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.
+    # This is a pointer in host memory so it could read outside of the plugin
+    # if manipulated
+    def memory_ptr(mem)
+      plugin_ptr = LibExtism.extism_current_plugin_memory(@ptr)
+      FFI::Pointer.new(plugin_ptr.address + mem.offset)
+    end
+  end
+end

data/lib/extism/host_environment.rb

@@ -0,0 +1,44 @@
+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
+
+    def host_functions
+      import_funcs = self.class.class_variable_get(:@@import_funcs)
+      import_funcs.map do |f|
+        name, params, returns = f
+        Extism::Function.new(
+          name.to_s,
+          params,
+          returns,
+          method(name).to_proc
+        )
+      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]
+    end
+  end
+end

data/lib/extism/libextism.rb

@@ -0,0 +1,77 @@
+module Extism
+  # Private module used to interface with the Extism runtime.
+  # *Warning*: Do not use or rely on this directly
+  # improperly using this interface may enable exploits and the interface
+  # might change over time.
+  module LibExtism
+    extend FFI::Library
+    ffi_lib 'extism'
+
+    def self.from_int_array(ruby_array)
+      ptr = FFI::MemoryPointer.new(:int, ruby_array.length)
+      ptr.write_array_of_int(ruby_array)
+      ptr
+    end
+
+    typedef :uint64, :ExtismMemoryHandle
+    typedef :uint64, :ExtismSize
+
+    enum :ExtismValType, %i[I32 I64 F32 F64 V128 FuncRef ExternRef]
+
+    class ExtismValUnion < FFI::Union
+      layout :i32, :int32,
+             :i64, :int64,
+             :f32, :float,
+             :f64, :double
+    end
+
+    class ExtismVal < FFI::Struct
+      layout :t, :ExtismValType,
+             :v, ExtismValUnion
+    end
+
+    class ExtismFunction < FFI::Struct
+      layout :name, :string,
+             :inputs, :pointer,
+             :n_inputs, :uint64,
+             :outputs, :pointer,
+             :n_outputs, :uint64,
+             :data, :pointer
+    end
+
+    callback :ExtismFunctionType, [
+      :pointer, # plugin
+      :pointer, # inputs
+      :ExtismSize, # n_inputs
+      :pointer, # outputs
+      :ExtismSize, # n_outputs
+      :pointer # user_data
+    ], :void
+
+    callback :ExtismFreeFunctionType, [], :void
+
+    attach_function :extism_plugin_id, [:pointer], :pointer
+    attach_function :extism_current_plugin_memory, [:pointer], :pointer
+    attach_function :extism_current_plugin_memory_alloc, %i[pointer ExtismSize], :ExtismMemoryHandle
+    attach_function :extism_current_plugin_memory_length, %i[pointer ExtismMemoryHandle], :ExtismSize
+    attach_function :extism_current_plugin_memory_free, %i[pointer ExtismMemoryHandle], :void
+    attach_function :extism_function_new,
+                    %i[string pointer ExtismSize pointer ExtismSize ExtismFunctionType ExtismFreeFunctionType pointer], :pointer
+    attach_function :extism_function_free, [:pointer], :void
+    attach_function :extism_function_set_namespace, %i[pointer string], :void
+    attach_function :extism_plugin_new, %i[pointer ExtismSize pointer ExtismSize bool pointer], :pointer
+    attach_function :extism_plugin_new_error_free, [:pointer], :void
+    attach_function :extism_plugin_free, [:pointer], :void
+    attach_function :extism_plugin_cancel_handle, [:pointer], :pointer
+    attach_function :extism_plugin_cancel, [:pointer], :bool
+    attach_function :extism_plugin_config, %i[pointer pointer ExtismSize], :bool
+    attach_function :extism_plugin_function_exists, %i[pointer string], :bool
+    attach_function :extism_plugin_call, %i[pointer string pointer ExtismSize], :int32
+    attach_function :extism_error, [:pointer], :string
+    attach_function :extism_plugin_error, [:pointer], :string
+    attach_function :extism_plugin_output_length, [:pointer], :ExtismSize
+    attach_function :extism_plugin_output_data, [:pointer], :pointer
+    attach_function :extism_log_file, %i[string string], :bool
+    attach_function :extism_version, [], :string
+  end
+end

data/lib/extism/plugin.rb

@@ -0,0 +1,99 @@
+module Extism
+  # A Plugin represents an instance of your WASM program
+  # created from the given manifest.
+  class Plugin
+    # Intialize a plugin
+    #
+    # @example
+    #   manifest = {
+    #     wasm: [
+    #       { 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/.
+    # @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)
+      code = FFI::MemoryPointer.new(:char, wasm.bytesize)
+      errmsg = FFI::MemoryPointer.new(:pointer)
+      code.put_bytes(0, wasm)
+      if functions.empty? && environment
+        unless environment.respond_to?(:host_functions)
+          raise ArgumentError 'environment should implement host_functions method'
+        end
+
+        functions = environment.host_functions
+      end
+      funcs_ptr = FFI::MemoryPointer.new(LibExtism::ExtismFunction)
+      funcs_ptr.write_array_of_pointer(functions.map { |f| f.send(:pointer) })
+      @plugin = LibExtism.extism_plugin_new(code, wasm.bytesize, funcs_ptr, functions.length, wasi, errmsg)
+      if @plugin.null?
+        err = errmsg.read_pointer.read_string
+        LibExtism.extism_plugin_new_error_free errmsg.read_pointer
+        raise Error, err
+      end
+      $PLUGINS[object_id] = { plugin: @plugin }
+      ObjectSpace.define_finalizer(self, $FREE_PLUGIN)
+      return unless !config.nil? and @plugin.null?
+
+      s = JSON.generate(config)
+      ptr = FFI::MemoryPointer.from_string(s)
+      LibExtism.extism_plugin_config(@plugin, ptr, s.bytesize)
+    end
+
+    # Check if a function exists
+    #
+    # @param name [String] The name of the function
+    # @return [Boolean] Returns true if function exists
+    def has_function?(name)
+      LibExtism.extism_plugin_function_exists(@plugin, name)
+    end
+
+    # 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
+    def call(name, data, &block)
+      # If no block was passed then use Pointer::read_string
+      block ||= ->(buf, len) { buf.read_string(len) }
+      input = FFI::MemoryPointer.from_string(data)
+      rc = LibExtism.extism_plugin_call(@plugin, name, input, data.bytesize)
+      if rc != 0
+        err = LibExtism.extism_plugin_error(@plugin)
+        raise Error, 'extism_call failed' if err&.empty?
+
+        raise Error, err
+
+      end
+
+      out_len = LibExtism.extism_plugin_output_length(@plugin)
+      buf = LibExtism.extism_plugin_output_data(@plugin)
+      block.call(buf, out_len)
+    end
+
+    # Free a plugin, this should be called when the plugin is no longer needed
+    #
+    # @return [void]
+    def free
+      return if @plugin.null?
+
+      $PLUGINS.delete(object_id)
+      LibExtism.extism_plugin_free(@plugin)
+      @plugin = nil
+    end
+
+    # Get a CancelHandle for a plugin
+    def cancel_handle
+      CancelHandle.new(LibExtism.extism_plugin_cancel_handle(@plugin))
+    end
+  end
+end

data/lib/extism/version.rb

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

data/lib/extism/wasm.rb

@@ -0,0 +1,102 @@
+module Extism
+  module ValType
+    I32 = 0
+    I64 = 1
+    F32 = 2
+    F64 = 3
+    V128 = 4
+    FUNC_REF = 5
+    EXTERN_REF = 6
+  end
+
+  class Val
+    def initialize(ptr)
+      @c_val = LibExtism::ExtismVal.new(ptr)
+    end
+
+    def type
+      case @c_val[:t]
+      when :I32
+        :i32
+      when :I64
+        :i64
+      when :F32
+        :f32
+      when :F64
+        :f64
+      else
+        raise "Unsupported wasm value type #{type}"
+      end
+    end
+
+    def value
+      @c_val[:v][type]
+    end
+
+    def value=(val)
+      @c_val[:v][type] = val
+    end
+  end
+
+  # A CancelHandle can be used to cancel a running plugin from another thread
+  class CancelHandle
+    def initialize(handle)
+      @handle = handle
+    end
+
+    # Cancel the plugin used to generate the handle
+    def cancel
+      LibExtism.extism_plugin_cancel(@handle)
+    end
+  end
+
+  # Represents a host function
+  class Function
+    # Create a new host function
+    #
+    # @param name [String] Must match the import name in Wasm. Doesn't include namespace. All extism host functions are in the env name space
+    # @param params [Array[Extism::ValType]] An array of val types matching the import's params
+    # @param returns [Array[Extism::ValType]] An array of val types matching the import returns
+    # @param func_proc [Proc] A proc that will be executed when the host function is executed
+    # @param user_data [Object] Any reference to object you want to be passed back to you when the func is invoked
+    # @param on_free [Proc] A proc triggered when this function is freed by the runtime. Not guaranteed to trigger.
+    def initialize(name, params, returns, func_proc, user_data: nil, on_free: nil)
+      @name = name
+      @params = params
+      @returns = returns
+      @func = func_proc
+      @user_data = user_data
+      @on_free = on_free
+    end
+
+    private
+
+    # Gets the pointer to this function.
+    # Warning: This should not be used
+    def pointer
+      return @_pointer if @_pointer
+
+      free = @on_free || proc {}
+      args = LibExtism.from_int_array(@params)
+      returns = LibExtism.from_int_array(@returns)
+      @_pointer = LibExtism.extism_function_new(@name, args, @params.length, returns, @returns.length, c_func, free,
+                                                nil)
+    end
+
+    def c_func
+      @c_func ||= proc do |plugin_ptr, inputs_ptr, inputs_size, outputs_ptr, outputs_size, _data_ptr|
+        current_plugin = Extism::CurrentPlugin.send(:new, plugin_ptr)
+        val_struct_size = LibExtism::ExtismVal.size
+
+        inputs = (0...inputs_size).map do |i|
+          Val.new(inputs_ptr + i * val_struct_size)
+        end
+        outputs = (0...outputs_size).map do |i|
+          Val.new(outputs_ptr + i * val_struct_size)
+        end
+
+        @func.call(current_plugin, inputs, outputs, @user_data)
+      end
+    end
+  end
+end

data/lib/extism.rb

@@ -1,6 +1,11 @@
-require "ffi"
-require "json"
-require_relative "./extism/version"
+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
@@ -10,258 +15,24 @@ module Extism
   #
   # @return [String] The version string of the Extism runtime
   def self.extism_version
-    C.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)
-    if level
-      level = FFI::MemoryPointer::from_string(level)
-    end
-    C.extism_log_file(name, level)
+    LibExtism.extism_log_file(name, level)
   end
 
   $PLUGINS = {}
-  $FREE_PLUGIN = proc { |id|
-    x = $PLUGINS[id]
-    if !x.nil?
-      C.extism_plugin_free(x[:context].pointer, x[:plugin])
-      $PLUGINS.delete(id)
-    end
-  }
-
-  $CONTEXTS = {}
-  $FREE_CONTEXT = proc { |id|
-    x = $CONTEXTS[id]
-    if !x.nil?
-      C.extism_context_free($CONTEXTS[id])
-      $CONTEXTS.delete(id)
+  $FREE_PLUGIN = proc { |ptr|
+    x = $PLUGINS[ptr]
+    unless x.nil?
+      LibExtism.extism_plugin_free(x[:plugin])
+      $PLUGINS.delete(ptr)
     end
   }
 
-  # A Context is needed to create plugins. The Context
-  # is where your plugins live. Freeing the context
-  # frees all of the plugins in its scope.
-  #
-  # @example Create and free a context
-  #  ctx = Extism::Context.new
-  #  plugin = ctx.plugin(my_manifest)
-  #  puts plugin.call("my_func", "my-input")
-  #  ctx.free # frees any plugins
-  #
-  # @example Use with_context to auto-free
-  #  Extism.with_context do |ctx|
-  #    plugin = ctx.plugin(my_manifest)
-  #    puts plugin.call("my_func", "my-input")
-  #  end # frees context after exiting this block
-  #
-  # @attr_reader pointer [FFI::Pointer] Pointer to the Extism context. *Used internally*.
-  class Context
-    attr_reader :pointer
-
-    # Initialize a new context
-    def initialize
-      @pointer = C.extism_context_new()
-      $CONTEXTS[self.object_id] = @pointer
-      ObjectSpace.define_finalizer(self, $FREE_CONTEXT)
-    end
-
-    # Remove all registered plugins in this context
-    # @return [void]
-    def reset
-      C.extism_context_reset(@pointer)
-    end
-
-    # Free the context, this should be called when it is no longer needed
-    # @return [void]
-    def free
-      return if @pointer.nil?
-
-      $CONTEXTS.delete(self.object_id)
-      C.extism_context_free(@pointer)
-      @pointer = nil
-    end
-
-    # Create a new plugin from a WASM module or JSON encoded manifest
-    #
-    # @see Plugin#new
-    # @param wasm [Hash, String] The manifest for the plugin. See https://extism.org/docs/concepts/manifest/.
-    # @param wasi [Boolean] Enable WASI support
-    # @param config [Hash] The plugin config
-    # @return [Plugin]
-    def plugin(wasm, wasi = false, config = nil)
-      Plugin.new(wasm, wasi, config, self)
-    end
-  end
-
-  # A context manager to create contexts and ensure that they get freed.
-  #
-  # @example Use with_context to auto-free
-  #  Extism.with_context do |ctx|
-  #    plugin = ctx.plugin(my_manifest)
-  #    puts plugin.call("my_func", "my-input")
-  #  end # frees context after exiting this block
-  #
-  # @yield [ctx] Yields the created Context
-  # @return [Object] returns whatever your block returns
-  def self.with_context(&block)
-    ctx = Context.new
-    begin
-      x = block.call(ctx)
-      return x
-    ensure
-      ctx.free
-    end
-  end
-
-  # A CancelHandle can be used to cancel a running plugin from another thread
-  class CancelHandle
-    def initialize(handle)
-      @handle = handle
-    end
-
-    # Cancel the plugin used to generate the handle
-    def cancel
-      return C.extism_plugin_cancel(@handle)
-    end
-  end
-
-  # A Plugin represents an instance of your WASM program from the given manifest.
-  class Plugin
-    # Intialize a plugin
-    #
-    # @param wasm [Hash, String] The manifest or WASM binary. See https://extism.org/docs/concepts/manifest/.
-    # @param wasi [Boolean] Enable WASI support
-    # @param config [Hash] The plugin config
-    # @param context [Context] The context to manager this plugin
-    def initialize(wasm, wasi = false, config = nil, context = nil)
-      if context.nil? then
-        context = Context.new
-      end
-      @context = context
-      if wasm.class == Hash
-        wasm = JSON.generate(wasm)
-      end
-      code = FFI::MemoryPointer.new(:char, wasm.bytesize)
-      code.put_bytes(0, wasm)
-      @plugin = C.extism_plugin_new(context.pointer, code, wasm.bytesize, nil, 0, wasi)
-      if @plugin < 0
-        err = C.extism_error(@context.pointer, -1)
-        if err&.empty?
-          raise Error.new "extism_plugin_new failed"
-        else
-          raise Error.new err
-        end
-      end
-      $PLUGINS[self.object_id] = { :plugin => @plugin, :context => context }
-      ObjectSpace.define_finalizer(self, $FREE_PLUGIN)
-      if config != nil and @plugin >= 0
-        s = JSON.generate(config)
-        ptr = FFI::MemoryPointer::from_string(s)
-        C.extism_plugin_config(@context.pointer, @plugin, ptr, s.bytesize)
-      end
-    end
-
-    # Update a plugin with new WASM module or manifest
-    #
-    # @param wasm [Hash, String] The manifest or WASM binary. See https://extism.org/docs/concepts/manifest/.
-    # @param wasi [Boolean] Enable WASI support
-    # @param config [Hash] The plugin config
-    # @return [void]
-    def update(wasm, wasi = false, config = nil)
-      if wasm.class == Hash
-        wasm = JSON.generate(wasm)
-      end
-      code = FFI::MemoryPointer.new(:char, wasm.bytesize)
-      code.put_bytes(0, wasm)
-      ok = C.extism_plugin_update(@context.pointer, @plugin, code, wasm.bytesize, nil, 0, wasi)
-      if !ok
-        err = C.extism_error(@context.pointer, @plugin)
-        if err&.empty?
-          raise Error.new "extism_plugin_update failed"
-        else
-          raise Error.new err
-        end
-      end
-
-      if config != nil
-        s = JSON.generate(config)
-        ptr = FFI::MemoryPointer::from_string(s)
-        C.extism_plugin_config(@context.pointer, @plugin, ptr, s.bytesize)
-      end
-    end
-
-    # Check if a function exists
-    #
-    # @param name [String] The name of the function
-    # @return [Boolean] Returns true if function exists
-    def has_function?(name)
-      C.extism_plugin_function_exists(@context.pointer, @plugin, name)
-    end
-
-    # Call a function by name
-    #
-    # @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
-    def call(name, data, &block)
-      # If no block was passed then use Pointer::read_string
-      block ||= ->(buf, len) { buf.read_string(len) }
-      input = FFI::MemoryPointer::from_string(data)
-      rc = C.extism_plugin_call(@context.pointer, @plugin, name, input, data.bytesize)
-      if rc != 0
-        err = C.extism_error(@context.pointer, @plugin)
-        if err&.empty?
-          raise Error.new "extism_call failed"
-        else
-          raise Error.new err
-        end
-      end
-      out_len = C.extism_plugin_output_length(@context.pointer, @plugin)
-      buf = C.extism_plugin_output_data(@context.pointer, @plugin)
-      block.call(buf, out_len)
-    end
-
-    # Free a plugin, this should be called when the plugin is no longer needed
-    #
-    # @return [void]
-    def free
-      return if @context.pointer.nil?
-
-      $PLUGINS.delete(self.object_id)
-      C.extism_plugin_free(@context.pointer, @plugin)
-      @plugin = -1
-    end
-
-    # Get a CancelHandle for a plugin
-    def cancel_handle
-      return CancelHandle.new(C.extism_plugin_cancel_handle(@context.pointer, @plugin))
-    end
-  end
-
-  private
-
-  # Private module used to interface with the Extism runtime.
-  # *Warning*: Do not use or rely on this directly.
-  module C
-    extend FFI::Library
-    ffi_lib "extism"
-    attach_function :extism_context_new, [], :pointer
-    attach_function :extism_context_free, [:pointer], :void
-    attach_function :extism_plugin_new, [:pointer, :pointer, :uint64, :pointer, :uint64, :bool], :int32
-    attach_function :extism_plugin_update, [:pointer, :int32, :pointer, :uint64, :pointer, :uint64, :bool], :bool
-    attach_function :extism_error, [:pointer, :int32], :string
-    attach_function :extism_plugin_call, [:pointer, :int32, :string, :pointer, :uint64], :int32
-    attach_function :extism_plugin_function_exists, [:pointer, :int32, :string], :bool
-    attach_function :extism_plugin_output_length, [:pointer, :int32], :uint64
-    attach_function :extism_plugin_output_data, [:pointer, :int32], :pointer
-    attach_function :extism_log_file, [:string, :pointer], :void
-    attach_function :extism_plugin_free, [:pointer, :int32], :void
-    attach_function :extism_context_reset, [:pointer], :void
-    attach_function :extism_version, [], :string
-    attach_function :extism_plugin_cancel_handle, [:pointer, :int32], :pointer
-    attach_function :extism_plugin_cancel, [:pointer], :bool
-  end
+  Memory = Struct.new(:offset, :len)
 end

data/sig/extism.rbs

@@ -1,4 +1,4 @@
-module Extism
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end
+module Extism
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: extism
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0.pre.rc.2
 platform: ruby
 authors:
 - zach
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-24 00:00:00.000000000 Z
+date: 2023-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -32,15 +32,23 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".yardopts"
-- GETTING_STARTED.md
 - Gemfile
+- Gemfile.lock
+- LICENSE
 - 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/plugin.rb
 - lib/extism/version.rb
+- lib/extism/wasm.rb
 - sig/extism.rbs
-- user_code.wasm
+- wasm/count_vowels.wasm
+- wasm/reflect.wasm
+- wasm/store_credit.wasm
 homepage: https://github.com/extism/extism
 licenses:
 - MIT
@@ -59,9 +67,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.4.10
 signing_key:

data/GETTING_STARTED.md

@@ -1,35 +0,0 @@
-# Extism
-
-## Getting Started
-
-### Example
-
-```ruby
-require "extism"
-require "json"
-
-Extism.with_context do |ctx|
-  manifest = {
-    :wasm => [{ :path => "../wasm/code.wasm" }],
-  }
-  plugin = ctx.plugin(manifest)
-  res = JSON.parse(plugin.call("count_vowels", "this is a test"))
-  puts res["count"] # => 4
-end
-```
-
-### API
-
-There are two primary classes you need to understand:
-
-* [Context](Extism/Context.html)
-* [Plugin](Extism/Plugin.html)
-
-#### Context
-
-The [Context](Extism/Context.html) can be thought of as a session. You need a context to interact with the Extism runtime. The context holds your plugins and when you free the context, it frees your plugins. We recommend using the [Extism.with_context](Extism.html#with_context-class_method) method to ensure that your plugins are cleaned up. But if you need a long lived context for any reason, you can use the constructor [Extism::Context.new](Extism/Context.html#initialize-instance_method).
-
-#### Plugin
-
-The [Plugin](Extism/Plugin.html) represents an instance of your WASM program from the given manifest.
-The key method to know here is [Extism::Plugin#call](Extism/Plugin.html#call-instance_method) which takes a function name to invoke and some input data, and returns the results from the plugin.

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"]