feat: validate function return values (#75)

Author: davydog187

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v0.2.0] - 2025-05-14
+
+### Changed
+- Any data returned from a `deflua` function, or a function set by `Lua.set!/3` is now validated. If the data is not an identity value, or an encoded value, it will raise an exception. In the past, `Lua` and Luerl would happily accept bad values, causing downstream problem is the program. This led to unexpected behavior, where depending on if the data passed was decoded or not, the program would succeed or fail
+
 
 ## [v0.1.1] - 2025-05-13
 
@@ -26,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Tables must now be explicitly decoded when receiving as arguments `deflua` and other Elixir callbacks
 
 
-[unreleased]: https://github.com/tv-labs/lua/compare/v0.1.1...HEAD
+[unreleased]: https://github.com/tv-labs/lua/compare/v0.2.0...HEAD
+[0.1.1]: https://github.com/tv-labs/lua/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/tv-labs/lua/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/tv-labs/lua/compare/v0.0.22...v0.1.0

README.md

@@ -160,6 +160,46 @@ lua = Lua.new() |> Lua.put_private(:user, user) |> Lua.load_api(UserAPI)
 
 This allows you to have simple, expressive APIs that access context that is unavailable to the Lua code.
 
+## Encoding and Decoding data
+
+When working with `Lua`, you may want inject data of various types into the runtime. Some values, such as integers, have the same representation inside of the runtime as they do in Elixir, they do not require encoding. Other values, such as maps, are represented inside of `Lua` as tables, and must be encoded first. Values not listed are not valid and cannot be encoded by `Lua` and Luerl, however, they can be passed using a `{:userdata, any()}` tuple and encoding them.
+
+Values may be encoded with `Lua.encode!/2`
+
+  Elixir type                 | Luerl type                | Requires encoding?
+  :-------------------------- | :------------------------ | :---------------------
+  `nil`                       | `nil`                     | no
+  `boolean()`                 | `boolean()`               | no
+  `number()`                  | `number()`                | no
+  `binary()`                  | `binary()`                | no
+  `atom()`                    | `binary()`                | yes
+  `map()`                     | `:luerl.tref()`           | yes
+  `{:userdata, any()}`        | `:luerl.usdref()`         | yes
+  `(any()) -> any()`          | `:luerl.erl_func()`       | yes
+  `(any(), Lua.t()) -> any()` | `:luerl.erl_func()`       | yes
+  `{module(), atom(), list()` | `:luerl.erl_mfa()`        | yes
+  `list(any())`               | `list(luerl type)`        | maybe (if any of its values require encoding)
+  
+
+## Userdata
+
+There are situations where you want to pass around a reference to some Elixir datastructure, such as a struct. In these situations, you can use a `{:userdata, any()}` tuple.
+
+``` elixir
+defmodule Thing do
+  defstruct [:value]
+end
+
+{encoded, lua} = Lua.encode!(Lua.new(), {:userdata, %Thing{value: "1234"}})
+
+lua = Lua.set!(lua, [:foo], encoded)
+
+{[{:userdata, %Thing{value: "1234"}}], _} = Lua.eval!(lua, "return foo")
+```
+
+Trying to deference userdata inside a Lua program will result in an exception.
+  
+  
 ## Credits
 
 `Lua` piggy-backs off of Robert Virding's [Luerl](https://github.com/rvirding/luerl) project, which implements a Lua lexer, parser, and full-blown Lua virtual machine that runs inside the BEAM.

guides/working-with-lua.livemd

@@ -4,7 +4,7 @@
 
 ```elixir
 Mix.install([
-  {:lua, "~> 0.1.1"}
+  {:lua, "~> 0.2.0"}
 ])
 ```
 
@@ -39,9 +39,7 @@ code = ~LUA"""
 ## Getting and Setting values
 
 ```elixir
-lua =
-  Lua.new()
-  |> Lua.set!([:dave], "Lucia")
+lua = Lua.set!(Lua.new(), [:dave], "Lucia")
 
 {["Grohl", "Lucia"], %Lua{} = lua} =
   Lua.eval!(lua, ~LUA"""
@@ -74,6 +72,9 @@ defmodule Global do
   @variadic true
   deflua my_print(args) do
     IO.puts(Enum.join(args, " "))
+
+    # Return nothing
+    []
   end
 end
 

lib/lua.ex

@@ -175,30 +175,62 @@ defmodule Lua do
       iex> {[3], _} = Lua.eval!(lua, "set_count(1, 2, 3); return count")
 
   """
-  def set!(%__MODULE__{} = lua, keys, value) do
-    value =
-      case value do
+  def set!(%__MODULE__{}, [], _) do
+    raise Lua.RuntimeException, "Lua.set!/3 cannot have empty keys"
+  end
+
+  def set!(%__MODULE__{} = lua, keys, func) when is_function(func, 1) or is_function(func, 2) do
+    {function_name, scope} = List.pop_at(keys, -1)
+
+    func =
+      case func do
         func when is_function(func, 1) ->
-          func
+          fn data ->
+            return = func.(data)
+
+            if not Lua.Util.encoded?(return) do
+              raise Lua.RuntimeException,
+                function: function_name,
+                scope: scope,
+                message: "deflua functions must return encoded data, got #{inspect(return)}"
+            end
+
+            return
+          end
 
         func when is_function(func, 2) ->
           fn args, state ->
             case func.(args, wrap(state)) do
-              {value, %__MODULE__{} = lua} ->
-                {List.wrap(value), lua.state}
-
               {:error, reason, %__MODULE__{} = lua} ->
                 :luerl_lib.lua_error(reason, lua.state)
 
+              {value, %__MODULE__{} = lua} ->
+                if not Lua.Util.encoded?(value) do
+                  raise Lua.RuntimeException,
+                    function: function_name,
+                    scope: scope,
+                    message: "deflua functions must return encoded data, got #{inspect(value)}"
+                end
+
+                {List.wrap(value), lua.state}
+
               value ->
+                if not Lua.Util.encoded?(value) do
+                  raise Lua.RuntimeException,
+                    function: function_name,
+                    scope: scope,
+                    message: "deflua functions must return encoded data, got #{inspect(value)}"
+                end
+
                 {List.wrap(value), state}
             end
           end
-
-        value ->
-          value
       end
 
+    do_set(lua.state, keys, func)
+  end
+
+  def set!(%__MODULE__{} = lua, keys, value) do
     do_set(lua.state, keys, value)
   end
 
@@ -221,7 +253,14 @@ defmodule Lua do
         end
       end)
 
-    case :luerl.set_table_keys_dec(keys, value, state) do
+    set_keys =
+      if Lua.Util.encoded?(value) do
+        &:luerl.set_table_keys/3
+      else
+        &:luerl.set_table_keys_dec/3
+      end
+
+    case set_keys.(keys, value, state) do
       {:ok, state} ->
         wrap(state)
 
@@ -607,7 +646,7 @@ defmodule Lua do
   @doc """
   Puts a private value in storage for use in Elixir functions
 
-      iex> lua = Lua.new() |> Lua.put_private(:api_key, "1234")
+      iex> Lua.new() |> Lua.put_private(:api_key, "1234")
   """
   def put_private(%__MODULE__{} = lua, key, value) do
     update_in(lua.state, fn state -> :luerl.put_private(key, value, state) end)
@@ -657,11 +696,11 @@ defmodule Lua do
 
     if with_state? do
       fn args, state ->
-        execute_function_with_state(module, function_name, [args, wrap(state)], wrap(state))
+        execute_function(module, function_name, [args, wrap(state)], wrap(state))
       end
     else
       fn args, state ->
-        execute_function(module, function_name, [args], state)
+        execute_function(module, function_name, [args], wrap(state))
       end
     end
   end
@@ -673,7 +712,7 @@ defmodule Lua do
     if with_state? do
       fn args, state ->
         if (length(args) + 1) in arities do
-          execute_function_with_state(module, function_name, args ++ [wrap(state)], wrap(state))
+          execute_function(module, function_name, args ++ [wrap(state)], wrap(state))
         else
           arities = Enum.map(arities, &(&1 - 1))
 
@@ -686,7 +725,7 @@ defmodule Lua do
     else
       fn args, state ->
         if length(args) in arities do
-          execute_function(module, function_name, args, state)
+          execute_function(module, function_name, args, wrap(state))
         else
           raise Lua.RuntimeException,
             function: function_name,
@@ -697,7 +736,7 @@ defmodule Lua do
     end
   end
 
-  defp execute_function(module, function_name, args, state) do
+  defp execute_function(module, function_name, args, lua) do
     # Luerl mandates lists as return values; this function ensures all results conform.
     case apply(module, function_name, args) do
       # Table-like keyword list
@@ -715,42 +754,30 @@ defmodule Lua do
           message: "maps must be explicitly encoded to tables using Lua.encode!/2"
 
       {:error, reason} ->
-        :luerl_lib.lua_error(reason, state)
-
-      other ->
-        {List.wrap(other), state}
-    end
-  catch
-    thrown_value ->
-      {:error,
-       "Value thrown during function '#{function_name}' execution: #{inspect(thrown_value)}"}
-  end
+        :luerl_lib.lua_error(reason, lua.state)
 
-  defp execute_function_with_state(module, function_name, args, lua) do
-    # Luerl mandates lists as return values; this function ensures all results conform.
-    case apply(module, function_name, args) do
-      {ret, %Lua{state: state}} ->
-        {ret, state}
+      {:error, reason, %Lua{} = lua} ->
+        :luerl_lib.lua_error(reason, lua.state)
 
-      # Table-like keyword list
-      [{_, _} | _rest] ->
-        raise Lua.RuntimeException,
-          function: function_name,
-          scope: module.scope(),
-          message: "keyword lists must be explicitly encoded to tables using Lua.encode!/2"
+      {data, %Lua{} = lua} ->
+        if not Lua.Util.encoded?(data) do
+          raise Lua.RuntimeException,
+            function: function_name,
+            scope: module.scope(),
+            message: "deflua functions must return encoded data, got #{inspect(data)}"
+        end
 
-      # Map
-      map when is_map(map) ->
-        raise Lua.RuntimeException,
-          function: function_name,
-          scope: module.scope(),
-          message: "maps must be explicitly encoded to tables using Lua.encode!/2"
+        {List.wrap(data), lua.state}
 
-      {:error, reason, %Lua{} = lua} ->
-        :luerl_lib.lua_error(reason, lua.state)
+      data ->
+        if not Lua.Util.encoded?(data) do
+          raise Lua.RuntimeException,
+            function: function_name,
+            scope: module.scope(),
+            message: "deflua functions must return encoded data, got #{inspect(data)}"
+        end
 
-      other ->
-        {List.wrap(other), lua.state}
+        {List.wrap(data), lua.state}
     end
   catch
     thrown_value ->

lib/lua/util.ex

@@ -10,6 +10,28 @@ defmodule Lua.Util do
     Record.defrecord(name, fields)
   end
 
+  # Returns true for identity values
+  # or values that hold internal Luerl representations like tref
+  def encoded?(nil), do: true
+  def encoded?(false), do: true
+  def encoded?(true), do: true
+  def encoded?(binary) when is_binary(binary), do: true
+  # TODO Remove since this shouldn't be decoded
+  # take out when https://github.com/rvirding/luerl/pull/213
+  # is released
+  def encoded?(number) when is_number(number), do: true
+  def encoded?(table_ref) when Record.is_record(table_ref, :tref), do: true
+  def encoded?(record) when Record.is_record(record, :usdref), do: true
+  def encoded?(record) when Record.is_record(record, :funref), do: true
+  def encoded?(record) when Record.is_record(record, :erl_func), do: true
+  def encoded?(record) when Record.is_record(record, :erl_mfa), do: true
+
+  def encoded?(list) when is_list(list) do
+    Enum.all?(list, &encoded?/1)
+  end
+
+  def encoded?(_), do: false
+
   def format_error(error) do
     case error do
       {line, type, {:illegal, value}} ->

mix.exs

@@ -2,7 +2,7 @@ defmodule Lua.MixProject do
   use Mix.Project
 
   @url "https://github.com/tv-labs/lua"
-  @version "0.1.1"
+  @version "0.2.0"
 
   def project do
     [