Merge pull request #15 from esl/typed-server

Sketch the TypedServer module and import the example

Author: erszcz

examples/typed_gen_server/.formatter.exs

@@ -0,0 +1,4 @@
+# Used by "mix format"
+[
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+]

examples/typed_gen_server/.gitignore

@@ -0,0 +1,27 @@
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
+
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
+
+# If the VM crashes, it generates a dump, let's ignore it too.
+erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
+*.ez
+
+# Ignore package tarball (built via "mix hex.build").
+typed_gen_server-*.tar
+
+
+# Temporary files for e.g. tests
+/tmp

examples/typed_gen_server/README.md

@@ -0,0 +1,21 @@
+# TypedGenServer
+
+This is an experiment which abuses Gradualizer's exhaustiveness checking
+to type message passing contracts.
+
+This does not automatically determine the types of messages passed around - it's
+the programmer who's responsbile for providing this information in form of a type
+defining the message.
+
+However, given that type in place, the techniques used here make it easier
+to catch bugs if:
+
+- some messages are not handled (completely forgotten or added to the
+  contract, but not to the implementation)
+- some messages get malformed (think typos, pattern match mistakes, etc)
+- some responses are not handled (i.e. response handlers are incomplete,
+  for example if new response types were introduced after the handler was
+  in place)
+
+I hope you're interested ;)
+If so, please check out [`lib/typed_gen_server/multi_server.ex`](/lib/typed_gen_server/multi_server.ex).

examples/typed_gen_server/lib/contract/echo.ex

@@ -0,0 +1,4 @@
+defmodule Contract.Echo do
+  @type req :: {:echo_req, String.t()}
+  @type res :: {:echo_res, String.t()}
+end

examples/typed_gen_server/lib/contract/hello.ex

@@ -0,0 +1,4 @@
+defmodule Contract.Hello do
+  @type req :: {:hello, String.t()}
+  @type res :: :ok
+end

examples/typed_gen_server/lib/typed_gen_server.ex

@@ -0,0 +1,18 @@
+defmodule TypedGenServer do
+  @moduledoc """
+  Documentation for `TypedGenServer`.
+  """
+
+  @doc """
+  Hello world.
+
+  ## Examples
+
+      iex> TypedGenServer.hello()
+      :world
+
+  """
+  def hello do
+    :world
+  end
+end

examples/typed_gen_server/lib/typed_gen_server/application.ex

@@ -0,0 +1,20 @@
+defmodule TypedGenServer.Application do
+  # See https://hexdocs.pm/elixir/Application.html
+  # for more information on OTP Applications
+  @moduledoc false
+
+  use Application
+
+  @impl true
+  def start(_type, _args) do
+    children = [
+      # Starts a worker by calling: TypedGenServer.Worker.start_link(arg)
+      # {TypedGenServer.Worker, arg}
+    ]
+
+    # See https://hexdocs.pm/elixir/Supervisor.html
+    # for other strategies and supported options
+    opts = [strategy: :one_for_one, name: TypedGenServer.Supervisor]
+    Supervisor.start_link(children, opts)
+  end
+end

examples/typed_gen_server/lib/typed_gen_server/stage1.ex

@@ -0,0 +1,67 @@
+defmodule TypedGenServer.Stage1.Server do
+  use GenServer
+  use GradualizerEx.TypeAnnotation
+
+  ## Start IEx with:
+  ##   iex -S mix run --no-start
+  ##
+  ## Then use the following to recheck the file on any change:
+  ##   recompile(); GradualizerEx.type_check_file(:code.which( TypedGenServer.Stage1.Server ), [:infer])
+
+  ## Try switching between the definitions and see what happens
+  @type message :: Contract.Echo.req() | Contract.Hello.req()
+  #@type message :: Contract.Echo.req()
+  #@type message :: {:echo_req, String.t()} | {:hello, String.t()}
+
+  @type state :: map()
+
+  def start_link() do
+    GenServer.start_link(__MODULE__, %{})
+  end
+
+  @spec echo(pid(), String.t()) :: String.t()
+  # @spec echo(pid(), String.t()) :: {:echo_req, String.t()}
+  def echo(pid, message) do
+    case annotate_type( GenServer.call(pid, {:echo_req, message}), Contract.Echo.res() ) do
+    #case call_echo(pid, message) do
+      ## Try changing the pattern or the returned response
+      {:echo_res, response} -> response
+    end
+  end
+
+  #@spec call_echo(pid(), String.t()) :: Contract.Echo.res()
+  #defp call_echo(pid, message) do
+  #  GenServer.call(pid, {:echo_req, message})
+  #end
+
+  @spec hello(pid(), String.t()) :: :ok
+  def hello(pid, name) do
+    case GenServer.call(pid, {:hello, name}) |> annotate_type(Contract.Hello.res()) do
+      :ok -> :ok
+    end
+  end
+
+  @impl true
+  def init(state) do
+    {:ok, state}
+  end
+
+  @impl true
+  def handle_call(m, from, state) do
+    {:noreply, handle(m, from, state)}
+  end
+
+  @spec handle(message(), any, any) :: state()
+  ## Try breaking the pattern match, e.g. by changing 'echo_req'
+  def handle({:echo_req, payload}, from, state) do
+    GenServer.reply(from, {:echo_res, payload})
+    state
+  end
+
+  ## Try commenting out the following clause
+  def handle({:hello, name}, from, state) do
+    IO.puts("Hello, #{name}!")
+    GenServer.reply(from, :ok)
+    state
+  end
+end

examples/typed_gen_server/lib/typed_gen_server/stage2.ex

@@ -0,0 +1,92 @@
+defmodule TypedGenServer.Stage2.Server do
+  use GenServer
+  use GradualizerEx.TypeAnnotation
+  alias Stage2.TypedServer
+
+  ## Start IEx with:
+  ##   iex -S mix run --no-start
+  ##
+  ## Then use the following to recheck the file on any change:
+  ##   recompile(); GradualizerEx.type_check_file(:code.which( TypedGenServer.Stage2.Server ), [:infer])
+
+  @opaque t :: pid()
+
+  ## Try switching between the definitions and see what happens
+  @type message :: Contract.Echo.req() | Contract.Hello.req()
+  #@type message :: Contract.Echo.req()
+  #@type message :: {:echo_req, String.t()} | {:hello, String.t()}
+
+  @type state :: map()
+
+  @spec start_link() :: {:ok, t()} | :ignore | {:error, {:already_started, t()} | any()}
+  def start_link() do
+    GenServer.start_link(__MODULE__, %{})
+  end
+
+  @spec echo(t(), String.t()) :: String.t()
+  # @spec echo(t(), String.t()) :: {:echo_req, String.t()}
+  def echo(pid, message) do
+    case annotate_type( GenServer.call(pid, {:echo_req, message}), Contract.Echo.res() ) do
+    #case call_echo(pid, message) do
+      ## Try changing the pattern or the returned response
+      {:echo_res, response} -> response
+    end
+  end
+
+  ## This could be generated based on present handle clauses - thanks, Robert!
+  @spec call_echo(t(), String.t()) :: Contract.Echo.res()
+  defp call_echo(pid, message) do
+    GenServer.call(pid, {:echo_req, message})
+  end
+
+  @spec hello(t(), String.t()) :: :ok
+  def hello(pid, name) do
+    case GenServer.call(pid, {:hello, name}) |> annotate_type(Contract.Hello.res()) do
+      :ok -> :ok
+    end
+  end
+
+  @impl true
+  def init(state) do
+    {:ok, state}
+  end
+
+  @impl true
+  def handle_call(m, from, state) do
+    {:noreply, handle(m, from, state)}
+  end
+
+  @spec handle(message(), any, any) :: state()
+  ## Try breaking the pattern match, e.g. by changing 'echo_req'
+  def handle({:echo_req, payload}, from, state) do
+    ## This could register {:echo_req, payload} <-> {:echo_res, payload} mapping
+    ## and response type at compile time to generate call_echo() automatically.
+    ## Thanks Robert!
+    #TypedServer.reply( from, {:echo_res, payload}, Contract.Echo.res() )
+    GenServer.reply( from, {:echo_res, payload} )
+    state
+  end
+
+  ## Try commenting out the following clause
+  def handle({:hello, name}, from, state) do
+    IO.puts("Hello, #{name}!")
+    GenServer.reply(from, :ok)
+    state
+  end
+end
+
+defmodule Test.TypedGenServer.Stage2.Server do
+  alias TypedGenServer.Stage2.Server
+
+  ## Typecheck with:
+  ##   recompile(); GradualizerEx.type_check_file(:code.which( Test.TypedGenServer.Stage2.Server ), [:infer])
+
+  @spec test :: any()
+  def test do
+    {:ok, srv} = Server.start_link()
+    pid = self()
+    "payload" = Server.echo(srv, "payload")
+    ## This won't typecheck, since Server.echo only accepts Server.t(), that is our Server pids
+    #"payload" = Server.echo(pid, "payload")
+  end
+end

examples/typed_gen_server/lib/typed_gen_server/stage3.ex

@@ -0,0 +1,105 @@
+defmodule Stage3.TypedServer do
+
+  ## This doesn't play well with:
+  ##   {:ok, srv} = MultiServer.start_link()
+  ## Due to:
+  ##   The pattern {ok, _srv@1} on line 90 doesn't have the type 'Elixir.TypedServer':on_start(t())
+  ## A bug/limitation in Gradualizer pattern match typing?
+  @type on_start(t) :: {:ok, t} | :ignore | {:error, {:already_started, t} | any()}
+
+  def wrap(on_start, module) do
+    case on_start do
+      {:ok, pid} -> {:ok, {module, pid}}
+      {:error, {:already_started, pid}} -> {:error, {:already_started, {module, pid}}}
+      other -> other
+    end
+  end
+end
+
+defmodule TypedGenServer.Stage3.Server do
+  use GenServer
+  use GradualizerEx.TypeAnnotation
+  alias Stage3.TypedServer
+
+  ## Start IEx with:
+  ##   iex -S mix run --no-start
+  ##
+  ## Then use the following to recheck the file on any change:
+  ##   recompile(); GradualizerEx.type_check_file(:code.which( TypedGenServer.Stage3.Server ), [:infer])
+
+  @opaque t :: {__MODULE__, pid()}
+
+  ## Try switching between the definitions and see what happens
+  @type message :: Contract.Echo.req() | Contract.Hello.req()
+  #@type message :: Contract.Echo.req()
+  #@type message :: {:echo_req, String.t()} | {:hello, String.t()}
+
+  @type state :: map()
+
+  @spec start_link() :: TypedServer.on_start(t())
+  def start_link() do
+    GenServer.start_link(__MODULE__, %{}) |> TypedServer.wrap(__MODULE__)
+  end
+
+  @spec echo(t(), String.t()) :: String.t()
+  # @spec echo(t(), String.t()) :: {:echo_req, String.t()}
+  def echo(_server = {__MODULE__, _pid}, message) do
+    case annotate_type( GenServer.call(_pid, {:echo_req, message}), Contract.Echo.res() ) do
+    #case call_echo(_server, message) do
+      ## Try changing the pattern or the returned response
+      {:echo_res, response} -> response
+    end
+  end
+
+  #@spec call_echo(t(), String.t()) :: Contract.Echo.res()
+  #defp call_echo({__MODULE__, pid}, message) do
+  #  GenServer.call(pid, {:echo_req, message})
+  #end
+
+  @spec hello(t(), String.t()) :: :ok
+  def hello({__MODULE__, pid}, name) do
+    case GenServer.call(pid, {:hello, name}) |> annotate_type(Contract.Hello.res()) do
+      :ok -> :ok
+    end
+  end
+
+  @impl true
+  def init(state) do
+    {:ok, state}
+  end
+
+  @impl true
+  def handle_call(m, from, state) do
+    {:noreply, handle(m, from, state)}
+  end
+
+  @spec handle(message(), any, any) :: state()
+  ## Try breaking the pattern match, e.g. by changing 'echo_req'
+  def handle({:echo_req, payload}, from, state) do
+    GenServer.reply(from, {:echo_res, payload})
+    state
+  end
+
+  ## Try commenting out the following clause
+  def handle({:hello, name}, from, state) do
+    IO.puts("Hello, #{name}!")
+    GenServer.reply(from, :ok)
+    state
+  end
+end
+
+defmodule Test.TypedGenServer.Stage3.Server do
+  alias TypedGenServer.Stage3.Server
+
+  ## Typecheck with:
+  ##   recompile(); GradualizerEx.type_check_file(:code.which( Test.TypedGenServer.Stage3.Server ), [:infer])
+
+  @spec test :: any()
+  def test do
+    {:ok, srv} = Server.start_link()
+    pid = self()
+    "payload" = Server.echo(srv, "payload")
+    ## This won't typecheck, since Server.echo only accepts Server.t(), that is Server pids
+    #"payload" = Server.echo(pid, "payload")
+  end
+end