defmodule Wasmex.Module do
  @moduledoc ~S"""
  A compiled WebAssembly module.

  A Wasm Module contains stateless WebAssembly code that has
  already been compiled and can be instantiated multiple times.
  """

  alias Wasmex.Engine

  @type t :: %__MODULE__{
          resource: binary(),
          reference: reference()
        }

  defstruct resource: nil,
            # The actual NIF module resource.
            # Normally the compiler will happily do stuff like inlining the
            # resource in attributes. This will convert the resource into an
            # empty binary with no warning. This will make that harder to
            # accidentally do.
            reference: nil

  defp __wrap_resource__(resource) do
    %__MODULE__{
      resource: resource,
      reference: make_ref()
    }
  end

  @doc ~S"""
  Compiles a Wasm module from it's Wasm (a .wasm file) or WAT (a .wat file) representation.

  Compiled modules can be instantiated using `Wasmex.start_link/1` or `Instance.new/3`.

  Since module compilation takes time and resources but instantiation is
  comparatively cheap, it may be a good idea to compile a module once and
  instantiate it often if you want to run a Wasm binary multiple times.

  ## Example

  Read a Wasm file and compile it into a Wasm module.
  Use the compiled module to start a running `Wasmex.Instance`.

      iex> {:ok, store} = Wasmex.Store.new()
      iex> {:ok, module} = Wasmex.Module.compile(store, File.read!(TestHelper.wasm_test_file_path()))
      iex> {:ok, _pid} = Wasmex.start_link(%{store: store, module: module})

  Modules can be compiled from WAT (WebAssembly Text) format:

      iex> wat = "(module)" # minimal and not very useful
      iex> {:ok, store} = Wasmex.Store.new()
      iex> {:ok, %Wasmex.Module{}} = Wasmex.Module.compile(store, wat)
  """
  @spec compile(Wasmex.StoreOrCaller.t(), binary()) ::
          {:ok, __MODULE__.t()} | {:error, binary()}
  def compile(%Wasmex.StoreOrCaller{resource: store_or_caller_resource}, bytes)
      when is_binary(bytes) do
    case Wasmex.Native.module_compile(store_or_caller_resource, bytes) do
      {:error, err} -> {:error, err}
      resource -> {:ok, __wrap_resource__(resource)}
    end
  end

  @doc ~S"""
  Returns the name of the current module if a name is given.

  This name is normally set in the Wasm bytecode by some compilers.

  ## Example

      iex> {:ok, store} = Wasmex.Store.new()
      iex> wat = "(module $hiFromTheDocs)" # minimal and not very useful Wasm module
      iex> {:ok, module} = Wasmex.Module.compile(store, wat)
      iex> Wasmex.Module.name(module)
      "hiFromTheDocs"
  """
  @spec name(__MODULE__.t()) :: binary() | nil
  def name(%__MODULE__{resource: resource}) do
    case Wasmex.Native.module_name(resource) do
      {:error, _} -> nil
      name -> name
    end
  end

  @doc ~S"""
  Lists all exports of a Wasm module.

  Returns a map which has the exports name (string) as key and export info-tuples as values.
  Info tuples always start with an atom indicating the exports type:

  * `:fn` (function)
  * `:global`
  * `:table`
  * `:memory`

  Further parts of the info tuple vary depending on the type.

  ## Example

  List the exported function "hello_world()" of a Wasm module:

      iex> {:ok, store} = Wasmex.Store.new()
      iex> wat = "(module
      ...>          (func $helloWorld (result i32) (i32.const 42))
      ...>          (export \"hello_world\" (func $helloWorld))
      ...>        )"
      iex> {:ok, module} = Wasmex.Module.compile(store, wat)
      iex> Wasmex.Module.exports(module)
      %{
        "hello_world" => {:fn, [], [:i32]},
      }
  """
  @spec exports(__MODULE__.t()) :: %{String.t() => any()}
  def exports(%__MODULE__{resource: resource}) do
    Wasmex.Native.module_exports(resource)
  end

  @doc ~S"""
  Lists all imports of a WebAssembly module grouped by their module namespace.

  Returns a map of namespace names to namespaces with each namespace being a map again.
  A namespace is a map of imports with the import name as key and and info-tuple as value.

  Info tuples always start with an atom indicating the imports type:

  * `:fn` (function)
  * `:global`
  * `:table`
  * `:memory`

  Further parts of the info tuple vary depending on the type.

  ## Example

  Show that the Wasm module imports a function "inspect" from the "IO" namespace:

      iex> {:ok, store} = Wasmex.Store.new()
      iex> wat = "(module
      ...>          (import \"IO\" \"inspect\" (func $log (param i32)))
      ...>        )"
      iex> {:ok, module} = Wasmex.Module.compile(store, wat)
      iex> Wasmex.Module.imports(module)
      %{
        "IO" => %{
          "inspect" => {:fn, [:i32], []},
        }
      }
  """
  @spec imports(__MODULE__.t()) :: %{String.t() => any()}
  def imports(%__MODULE__{resource: resource}) do
    Wasmex.Native.module_imports(resource)
  end

  @doc ~S"""
  Serializes a compiled Wasm module into a binary.

  The generated binary can be deserialized back into a module using `unsafe_deserialize/1`.
  It is unsafe do alter the binary in any way. See `unsafe_deserialize/1` for safety considerations.

  ## Example

  Serializes a compiled module:

      iex> {:ok, store} = Wasmex.Store.new()
      iex> {:ok, module} = Wasmex.Module.compile(store, File.read!(TestHelper.wasm_test_file_path()))
      iex> {:ok, serialized} = Wasmex.Module.serialize(module)
      iex> is_binary(serialized)
      true
  """
  @spec serialize(__MODULE__.t()) :: {:ok, binary()} | {:error, binary()}
  def serialize(%__MODULE__{resource: resource}) do
    case Wasmex.Native.module_serialize(resource) do
      {:error, err} -> {:error, err}
      binary -> {:ok, binary}
    end
  end

  @doc ~S"""
  Deserializes an in-memory compiled module previously created with
  `Wasmex.Module.serialize/1` or `Wasmex.Engine::precompile_module/2`.

  This function will deserialize the binary blobs emitted by
  `Wasmex.Module.serialize/1` and `Wasmex.Engine::precompile_module/2`
  back into an in-memory `Wasmex.Module` that's ready to be instantiated.

  # Unsafety

  This function is marked as `unsafe` because if fed invalid input or used
  improperly this could lead to memory safety vulnerabilities. This method
  should not, for example, be exposed to arbitrary user input.

  The structure of the binary blob read here is only lightly validated
  internally in `wasmtime`. This is intended to be an efficient
  "rehydration" for a `Wasmex.Module` which has very few runtime checks
  beyond deserialization. Arbitrary input could, for example, replace
  valid compiled code with any other valid compiled code, meaning that
  this can trivially be used to execute arbitrary code otherwise.

  For these reasons this function is `unsafe`. This function is only
  designed to receive the previous input from `Wasmex.Module.serialize/1`
  and `Wasmex.Engine::precompile_module/2`. If the exact output of those
  functions (unmodified) is passed to this function then calls to this
  function can be considered safe. It is the caller's responsibility to
  provide the guarantee that only previously-serialized bytes are being
  passed in here.

  Note that this function is designed to be safe receiving output from
  *any* compiled version of `wasmtime` itself. This means that it is safe
  to feed output from older versions of Wasmtime into this function, in
  addition to newer versions of wasmtime (from the future!). These inputs
  will deterministically and safely produce an error. This function only
  successfully accepts inputs from the same version of `wasmtime`.
  (this means that if you cache blobs across versions of wasmtime you can
  be safely guaranteed that future versions of wasmtime will reject old
  cache entries).

  It is best to deserialize modules using an Engine with the same
  configuration as the one used to serialize/precompile it.

  ## Example

  Serializes a compiled module and deserializes it again:

      iex> {:ok, store} = Wasmex.Store.new()
      iex> {:ok, module} = Wasmex.Module.compile(store, File.read!(TestHelper.wasm_test_file_path()))
      iex> {:ok, serialized} = Wasmex.Module.serialize(module)
      iex> {:ok, %Wasmex.Module{}} = Wasmex.Module.unsafe_deserialize(serialized)
  """
  @spec unsafe_deserialize(binary(), Engine.t() | nil) ::
          {:ok, __MODULE__.t()} | {:error, binary()}
  def unsafe_deserialize(bytes, engine \\ nil) when is_binary(bytes) do
    %Engine{resource: engine_resource} = engine || Engine.default()

    case Wasmex.Native.module_unsafe_deserialize(bytes, engine_resource) do
      {:error, err} -> {:error, err}
      resource -> {:ok, __wrap_resource__(resource)}
    end
  end
end

defimpl Inspect, for: Wasmex.Module do
  import Inspect.Algebra

  def inspect(dict, opts) do
    concat(["#Wasmex.Module<", to_doc(dict.reference, opts), ">"])
  end
end
