extism 0.0.1.rc4 → 0.0.1.rc6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9baa968de02938c07de67d56f468c482392d15c3b0d4856679ffa65ac54bcf8e
-  data.tar.gz: 18577dac8681ec65162505ea3664ec85d39be3c7b97df203a12f89a0eeff1617
+  metadata.gz: da418ff834d018a2db1264a41bb5a1492ee9ed46afd23da98b7f1cd7d063daef
+  data.tar.gz: ff401836b2d1338d0c83941cd697c7045b4c966dabbf180fd912d785289abdb5
 SHA512:
-  metadata.gz: ffc8f845fc8d42e6f55dc90bc56ab6e4b2ad35f1a1af88c4a5caf1c8f0353314be92e2e33157eb9c50c9a7d168d477d78c7af883f7d30f5879f27e53e4b34f0f
-  data.tar.gz: cf4175f208e06380f761ff80dec20ac38a416e7c866cee1ccb3844a37e24369464eeb4a60bcd547b7e348fc00744d06de8cceda5cfcd87dc9675d45bdbb407f4
+  metadata.gz: d5b255ef462bdb062b10c91830de25a95ca0c8178427a5de3ba83d2a47baa18557023ad3782e66c3340e9b5b96fdc0045fe8929387a5ce196d6add8c3ad6594b
+  data.tar.gz: c47fde60afa59d51f85267ef59e6ecb07125a4252b0c9ea4e265f1b23c0a5e2e2aa32bcb19db2f445fe647d3b09d9612a4d740ab67c209bcf73be96276c2e0f6

data/.yardopts

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

data/GETTING_STARTED.md

@@ -0,0 +1,35 @@
+# 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/Gemfile

@@ -6,5 +6,10 @@ source "https://rubygems.org"
 gemspec
 
 gem "rake", "~> 13.0"
-gem "ffi"
+gem "ffi", "~> 1.15.5"
 
+group :development do
+  gem "yard", "~> 0.9.28"
+  gem "rufo", "~> 0.13.0"
+  gem "minitest", "~> 5.16.3"
+end

data/Makefile

@@ -0,0 +1,28 @@
+
+.PHONY: prepare test
+
+prepare:
+	bundle install
+	bundle binstubs --all
+
+test: prepare
+	bundle exec rake test
+
+clean:
+	rm -f extism-*.gem
+
+publish: clean prepare
+	gem build extism.gemspec
+	gem push extism-*.gem -k ${RUBYGEMS_API_KEY}
+
+lint:
+	bundle exec rufo --check .
+
+format:
+	bundle exec rufo .
+
+docs:
+	bundle exec yard
+
+show-docs: docs
+	open doc/index.html

data/Rakefile

@@ -1,3 +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

data/example.rb

@@ -1,16 +1,17 @@
-require './lib/extism'
-require 'json'
+require "./lib/extism"
+require "json"
 
 # a Context provides a scope for plugins to be managed within. creating multiple contexts
 # is expected and groups plugins based on source/tenant/lifetime etc.
-ctx = Extism::Context.new
-Extism::with_context {|ctx| 
+# We recommend you use `Extism.with_context` unless you have a reason to keep your context around.
+# If you do you can create a context with `Extism#new`, example: `ctx = Extism.new`
+Extism.with_context do |ctx|
   manifest = {
-    :wasm => [{:path => "../wasm/code.wasm"}]
+    :wasm => [{ :path => "../wasm/code.wasm" }],
   }
 
   plugin = ctx.plugin(manifest)
   res = JSON.parse(plugin.call("count_vowels", ARGV[0] || "this is a test"))
-  
-  puts res['count']
-}
+
+  puts res["count"]
+end

data/lib/extism/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Extism
-  VERSION = "0.0.1.rc4"
+  VERSION = "0.0.1.rc6"
 end

data/lib/extism.rb

@@ -1,37 +1,23 @@
-require 'ffi'
-require 'json'
+require "ffi"
+require "json"
+require_relative "./extism/version"
 
 module Extism
-  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, :bool], :int32
-    attach_function :extism_plugin_update, [:pointer, :int32, :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
-  end
-
-
   class Error < StandardError
   end
 
   # Return the version of Extism
+  #
+  # @return [String] The version string of the Extism runtime
   def self.extism_version
     C.extism_version
   end
 
   # Set log file and level, this is a global configuration
-  def self.set_log_file(name, level=nil)
-    if level then
+  # @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)
@@ -40,7 +26,7 @@ module Extism
   $PLUGINS = {}
   $FREE_PLUGIN = proc { |id|
     x = $PLUGINS[id]
-    if !x.nil? then
+    if !x.nil?
       C.extism_plugin_free(x[:context].pointer, x[:plugin])
       $PLUGINS.delete(id)
     end
@@ -49,44 +35,76 @@ module Extism
   $CONTEXTS = {}
   $FREE_CONTEXT = proc { |id|
     x = $CONTEXTS[id]
-    if !x.nil? then
+    if !x.nil?
       C.extism_context_free($CONTEXTS[id])
       $CONTEXTS.delete(id)
     end
   }
 
-  # Context is used to manage plugins
+  # 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_accessor :pointer
+    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)
+      ObjectSpace.define_finalizer(self, $FREE_CONTEXT)
     end
 
-    # Remove all registered plugins
+    # 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
-      if @pointer.nil? then
-        return
-      end
+      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
-    def plugin(wasm, wasi=false, config=nil)
-      return Plugin.new(self, wasm, wasi, config)
+    #
+    # @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(self, wasm, wasi, config)
     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
@@ -97,25 +115,34 @@ module Extism
     end
   end
 
+  # A Plugin represents an instance of your WASM program from the given manifest.
   class Plugin
-    def initialize(context, wasm, wasi=false, config=nil)
-      if wasm.class == Hash then
+    # Intialize a plugin
+    #
+    # @see Extism::Context#plugin
+    # @param context [Context] The context to manager this 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
+    def initialize(context, wasm, wasi = false, config = nil)
+      @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, wasi)
-      if @plugin < 0 then
-        err = C.extism_error(-1)
-        if err&.empty? then
+      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
+        else
+          raise Error.new err
         end
       end
-      @context = context
-      $PLUGINS[self.object_id] = {:plugin => @plugin, :context => context}
-      ObjectSpace.define_finalizer(self,  $FREE_PLUGIN)
-      if config != nil and @plugin >= 0 then
+      $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)
@@ -123,22 +150,28 @@ module Extism
     end
 
     # Update a plugin with new WASM module or manifest
-    def update(wasm, wasi=false, config=nil)
-      if wasm.class == Hash then
+    #
+    # @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, wasi)
-      if !ok then
-        err = C.extism_error(-1)
-        if err&.empty? then
+      if !ok
+        err = C.extism_error(@context.pointer, @plugin)
+        if err&.empty?
           raise Error.new "extism_plugin_update failed"
-        else raise Error.new err
+        else
+          raise Error.new err
         end
       end
 
-      if config != nil then
+      if config != nil
         s = JSON.generate(config)
         ptr = FFI::MemoryPointer::from_string(s)
         C.extism_plugin_config(@context.pointer, @plugin, ptr, s.bytesize)
@@ -146,38 +179,67 @@ module Extism
     end
 
     # Check if a function exists
-    def function_exists(name)
-      return C.extism_function_exists(@context.pointer, @plugin, name)
+    #
+    # @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) }
+      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 then
+      if rc != 0
         err = C.extism_error(@context.pointer, @plugin)
-        if err&.empty? then
+        if err&.empty?
           raise Error.new "extism_call failed"
-        else raise Error.new err
+        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)
-      return block.call(buf, out_len)
+      block.call(buf, out_len)
     end
 
     # Free a plugin, this should be called when the plugin is no longer needed
+    #
+    # @return [void]
     def free
-      if @context.pointer.nil? then
-        return
-      end
+      return if @context.pointer.nil?
 
       $PLUGINS.delete(self.object_id)
       C.extism_plugin_free(@context.pointer, @plugin)
       @plugin = -1
     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, :bool], :int32
+    attach_function :extism_plugin_update, [:pointer, :int32, :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
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: extism
 version: !ruby/object:Gem::Version
-  version: 0.0.1.rc4
+  version: 0.0.1.rc6
 platform: ruby
 authors:
 - zach
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-10-20 00:00:00.000000000 Z
+date: 2022-11-04 00:00:00.000000000 Z
 dependencies: []
 description: A library for loading and executing WASM plugins
 email:
@@ -17,7 +17,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
+- GETTING_STARTED.md
 - Gemfile
+- Makefile
 - Rakefile
 - example.rb
 - lib/extism.rb