Add docs and examples

Author: undr

README.md

@@ -1,11 +1,10 @@
-# JSONRPC2Plug
+# JSON-RPC 2.0 plug
 
-JSON-RPC 2 plug
+`JSONRPC2Plug` is an Elixir library for a JSON-RPC 2.0 server. Can be used as the plug middleware or as a standalone transport-agnostic server handler.
 
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `jsonrpc2_plug` to your list of dependencies in `mix.exs`:
+The package can be installed by adding `jsonrpc2_plug` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
@@ -15,6 +14,88 @@ def deps do
 end
 ```
 
+## Usage
+
+### Defining Services
+
+Services should use `JSONRPC2Plug.Service`, which allows describing methods of service. Each method is a module which use `JSONRPC2Plug.Method`.
+
+Examples:
+
+
+```elixir
+defmodule CalculatorService do
+  use JSONRPC2Plug.Service
+
+  method "add", AddMethod
+  method "subtract", SubtractMethod
+  method "multiply", MultiplyMethod
+  method "divide", DivideMethod
+end
+
+defmodule AddMethod do
+  use JSONRPC2Plug.Method
+end
+# and so on...
+```
+
+### Defining Methods
+
+There are two possible ways to execute a request: `call` and `cast`. The first assumes the response which the service will return, the second does not. The module should implement at least one `handle_call` or `handle_cast` callback function to handle requests.
+
+```elixir
+defmodule AddMethod do
+  use JSONRPC2Plug.Method
+
+  # It handles requests like this:
+  # {"id": "123", "method": "add", "params": {"x": 10, "y": 20}, "jsonrpc": "2.0"}
+  def handle_call(%{"x" = > x, "y" => y}, _conn) do
+    {:ok, x + y}
+  end
+end
+```
+
+The first argument is the `"params"` data comes from request JSON. According to [JSONRPC2 spec](https://www.jsonrpc.org/specification), it must be either object or an array of arguments.
+
+The second argument is the `Plug.Conn` struct. Sometimes it could be useful to access the `Plug` connection.
+
+The module implements behaviour `JSONRPC2Plug.Method` which consists of five callbacks: `handle_call`, `handle_cast`, `validate`, `handle_error` and, `handle_exception`.
+
+#### `handle_call` and `handle_cast`
+
+_TODO: Add description_
+
+#### `validate`
+
+This function is for the validation of the input dataset.
+
+```elixir
+import JSONRPC2Plug.Validator, only: [type: 1, required: 0]
+
+def validate(params) do
+  params
+  |> Validator.validate("x", [type(:integer), required()])
+  |> Validator.validate("y", [type(:integer), required()])
+  |> Validator.unwrap()
+end
+```
+
+The library has its own validator. It has 8 built-in validations: `type`, `required`, `not_empty`, `exclude`, `include`, `len`, `number` and `format`. However, you can write custom validations and extend existing ones.
+
+Moreover, you can use any preferred validator (eg. [`valdi`](https://github.com/bluzky/valdi)), but you should respect the following requirements: the `validate` function should return either `{:ok, params}` or `{:invalid, errors}`. Where `errors` could be any type that can be safely encoded to JSON and `params` is params to pass into `handle_call` or `handle_cast` functions.
+
+#### `handle_error` and `handle_exception`
+
+_TODO: Add description_
+
+### Add as a plug to the router
+
+_TODO: Add description_
+
+### Using as standalone module
+
+_TODO: Add description_
+
 Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
 and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
 be found at [https://hexdocs.pm/jsonrpc2_plug](https://hexdocs.pm/jsonrpc2_plug).

examples/add_method.ex

@@ -0,0 +1,16 @@
+defmodule AddMethod do
+  use JSONRPC2Plug.Method
+
+  alias JSONRPC2Plug.Validator
+  require JSONRPC2Plug.Validator, [type: 1, required: 0]
+
+  def handle_call(%{"x" => x, "y" => y}),
+    do: {:ok, x + y}
+
+  def validate(params) do
+    params
+    |> Validator.validate("x", [type(:integer), required()])
+    |> Validator.validate("y", [type(:integer), required()])
+    |> Validator.unwrap()
+  end
+end

examples/calculator_service.ex

@@ -0,0 +1,8 @@
+defmodule CalculatorService do
+  use JSONRPC2Plug.Service
+
+  method "add", AddMethod
+  method "subtract", SubtractMethod
+  method "multiply", MultiplyMethod
+  method "divide", DivideMethod
+end

examples/divide_method.ex

@@ -0,0 +1,21 @@
+defmodule DivideMethod do
+  use JSONRPC2Plug.Method
+
+  alias JSONRPC2Plug.Validator
+  require JSONRPC2Plug.Validator, [type: 1, required: 0]
+
+  def handle_call(%{"x" => x, "y" => y}),
+    do: {:ok, round(x / y)}
+
+  def validate(params) do
+    params
+    |> Validator.validate("x", [type(:integer), required()])
+    |> Validator.validate("y", [type(:integer), required()])
+    |> Validator.unwrap()
+  end
+
+  def handle_exception(request, %ArithmeticError{message: message} = ex, stacktrace) do
+    log_error(request, {:error, ex}, stacktrace)
+    error(12345, message)
+  end
+end

examples/multiply_method.ex

@@ -0,0 +1,16 @@
+defmodule MultiplyMethod do
+  use JSONRPC2Plug.Method
+
+  alias JSONRPC2Plug.Validator
+  require JSONRPC2Plug.Validator, [type: 1, required: 0]
+
+  def handle_call(%{"x" => x, "y" => y}),
+    do: {:ok, x * y}
+
+  def validate(params) do
+    params
+    |> Validator.validate("x", [type(:integer), required()])
+    |> Validator.validate("y", [type(:integer), required()])
+    |> Validator.unwrap()
+  end
+end

examples/subtract_method.ex

@@ -0,0 +1,16 @@
+defmodule SubtractMethod do
+  use JSONRPC2Plug.Method
+
+  alias JSONRPC2Plug.Validator
+  require JSONRPC2Plug.Validator, [type: 1, required: 0]
+
+  def handle_call(%{"x" => x, "y" => y}),
+    do: {:ok, x - y}
+
+  def validate(params) do
+    params
+    |> Validator.validate("x", [type(:integer), required()])
+    |> Validator.validate("y", [type(:integer), required()])
+    |> Validator.unwrap()
+  end
+end

lib/jsonrpc2_plug.ex

@@ -1,4 +1,6 @@
 defmodule JSONRPC2Plug do
+  @moduledoc "README.md" |> File.read!()
+
   @behaviour Plug
   require Logger
 
@@ -7,6 +9,14 @@ defmodule JSONRPC2Plug do
   def init(handler),
     do: handler
 
+  @doc """
+  HTTP entry point to JSONRPC 2.0 services. It's usual plug and accepts service handler module as a param.
+
+  Example:
+      use Plug.Router
+      
+      forward "/jsonrpc", to: JSONRPC2Plug, init_opts: CalculatorService
+  """
   @impl true
   @spec call(Plug.Conn.t(), Plug.opts()) :: Plug.Conn.t()
   def call(%{method: "POST", body_params: %Plug.Conn.Unfetched{}}, _handler),
@@ -27,6 +37,25 @@ defmodule JSONRPC2Plug do
   def call(conn, _),
     do: Plug.Conn.resp(conn, 404, "")
 
+  @doc """
+  Send an error encoded according to JSONRPC 2.0 spec. It can be useful for global error handler in the router.
+
+  Example:
+      forward "/jsonrpc", to: JSONRPC2Plug, init_opts: CalculatorService
+
+      @impl Plug.ErrorHandler
+      def handle_errors(conn, %{kind: kind, reason: reason, stack: stacktrace}) do
+        Logger.error(Exception.format(kind, reason, stacktrace))
+
+        case conn do
+          %{request_path: "/jsonrpc"} ->
+            JSONRPC2Plug.send_error(conn, kind, reason)
+
+          _ ->
+            send_resp(conn, 500, "Someting went wrong")
+        end
+      end
+  """
   @spec send_error(Plug.Conn.t(), atom(), struct()) :: Plug.Conn.t()
   def send_error(conn, :error, %Plug.Parsers.ParseError{} = ex),
     do: send_error_response(conn, :parse_error, Exception.message(ex))

lib/jsonrpc2_plug/error.ex

@@ -31,14 +31,39 @@ defmodule JSONRPC2Plug.Error do
   def code2error(code),
     do: Keyword.get(@errors, code, {-32603, "Internal error"})
 
+  @doc """
+  Create error struct with predefined errors.
+
+  Example:
+      iex> Error.new("123", :invalid_request)
+      %Error{id: "123", error: %{code: -32600, message: "Invalid request"}, jsonrpc: "2.0"}
+  """
   @spec new(id(), atom()) :: t()
   def new(id, code),
     do: %__MODULE__{id: id, error: error(code)}
 
+  @doc """
+  Create error struct.
+
+  Example:
+      iex> Error.new("123", :invalid_params, %{"x" => ["is not a integer"]})
+      %Error{id: "123", error: %{code: -32602, message: "Invalid params", data: %{"x" => ["is not a integer"]}}, jsonrpc: "2.0"}
+
+      iex> Error.new("123", 500, "Some valuable error")
+      %Error{id: "123", error: %{code: 500, message: "Some valuable error"}, jsonrpc: "2.0"}
+  """
   @spec new(id(), raw_code(), message() | data()) :: t()
   def new(id, code, message_or_data),
     do: %__MODULE__{id: id, error: error(code, message_or_data)}
 
+  @doc """
+  Create error struct with custom errors.
+
+  Example:
+
+      iex> Error.new("123", 500, "Some valuable error", "details")
+      %Error{id: "123", error: %{code: 500, message: "Some valuable error", data: "details"}, jsonrpc: "2.0"}
+  """
   @spec new(id(), raw_code(), message(), data()) :: t()
   def new(id, code, message, data),
     do: %__MODULE__{id: id, error: error(code, message, data)}

lib/jsonrpc2_plug/gettext.ex

@@ -1,3 +1,4 @@
 defmodule JSONRPC2Plug.Gettext do
+  @moduledoc false
   use Gettext, otp_app: :jsonrpc2_plug
 end

lib/jsonrpc2_plug/method.ex

@@ -20,12 +20,40 @@ defmodule JSONRPC2Plug.Method do
 
       alias JSONRPC2Plug.Request
 
+      @doc """
+      Call service method.
+
+      Example:
+
+          iex> DivideMethod.call(%{"x" => 13, "y" => 5})
+          {:ok, 3}
+
+          iex> DivideMethod.call(%{"x" => 13, "y" => "5"})
+          {:jsonrpc2_error, {:invalid_params, %{"y" => ["is not a integer"]}}}
+
+          iex> DivideMethod.call(%{"x" => 13, "y" => 0})
+          {:jsonrpc2_error, {12345, "bad argument in arithmetic expression"}}
+      """
       @spec call(Request.params(), Plug.Conn.t()) :: result()
-      def call(params, conn),
+      def call(params, conn \\ %Plug.Conn{}),
         do: unquote(__MODULE__).handle({__MODULE__, :handle_call}, params, conn)
 
+      @doc """
+      Cast service method.
+
+      Example:
+
+          iex> DivideMethod.call(%{"x" => 13, "y" => 5})
+          {:ok, 3}
+
+          iex> DivideMethod.call(%{"x" => 13, "y" => "5"})
+          {:jsonrpc2_error, {:invalid_params, %{"y" => ["is not a integer"]}}}
+
+          iex> DivideMethod.call(%{"x" => 13, "y" => 0})
+          {:jsonrpc2_error, {12345, "bad argument in arithmetic expression"}}
+      """
       @spec cast(Request.params(), Plug.Conn.t()) :: result()
-      def cast(params, conn),
+      def cast(params, conn \\ %Plug.Conn{}),
         do: unquote(__MODULE__).handle({__MODULE__, :handle_cast}, params, conn)
 
       defp error!(code),
@@ -81,7 +109,7 @@ defmodule JSONRPC2Plug.Method do
       {:ok, result}
     else
       {:invalid, errors} ->
-        {:jsonrpc2_error, {:invalid_params, Enum.into(errors, %{})}}
+        {:jsonrpc2_error, {:invalid_params, errors}}
 
       error ->
         error

lib/jsonrpc2_plug/request.ex

@@ -10,6 +10,23 @@ defmodule JSONRPC2Plug.Request do
 
   defstruct [:id, :method, :params]
 
+  @doc """
+  Build request struct from input data
+
+  Example:
+
+      iex> Request.parse(%{"id" => 123, "method" => "add", "params" => %{"x" => 15, "y" => 51}, "jsonrpc" => "2.0"})
+      {:ok, %Request{id: 123, method: "add", params: %{"x" => 15, "y" => 51}, "jsonrpc" => "2.0"}}
+
+      iex> Request.parse(%{"id" => nil, "method" => "add", "params" => %{"x" => 15, "y" => 51}, "jsonrpc" => "2.0"})
+      {:ok, %Request{id: nil, method: "add", params: %{"x" => 15, "y" => 51}, "jsonrpc" => "2.0"}}
+
+      iex> Request.parse(%{"id" => 123, "method" => "add", "params" => %{"x" => 15, "y" => 51}})
+      {:invalid, 123}
+
+      iex> Request.parse(%{"method" => "add", "params" => %{"x" => 15, "y" => 51}, "jsonrpc" => "2.0"})
+      {:invalid, nil}
+  """
   @spec parse(map()) :: {:ok, t()} | {:invalid, id()}
   def parse(%{"id" => id, "method" => method, "params" => params, "jsonrpc" => "2.0"}),
     do: {:ok, %__MODULE__{id: id, method: method, params: params}}

lib/jsonrpc2_plug/service.ex

@@ -15,6 +15,9 @@ defmodule JSONRPC2Plug.Service do
 
       @before_compile unquote(__MODULE__)
 
+      @doc """
+      Handle service requests.
+      """
       def handle(%{"_json" => body_params}, conn) when is_list(body_params),
         do: Enum.map(body_params, fn(one) -> handle_one(one, conn) end) |> drop_nils()
       def handle(body_params, conn) when is_map(body_params),
@@ -100,6 +103,13 @@ defmodule JSONRPC2Plug.Service do
     end
   end
 
+  @doc """
+  Define method and handler.
+
+  Example:
+      method "add", AddMethod
+      method :subtract, SubtractMethod
+  """
   @spec method(Request.method(), module()) :: term()
   defmacro method(name, handler) when is_binary(name),
     do: build_method(String.to_atom(name), handler)

test/jsonrpc2_plug/service_test.exs

@@ -46,7 +46,7 @@ defmodule JSONRPC2Plug.ServiceTest do
       do: {:ok, "result"}
 
     def validate(%{"invalid" => true}),
-      do: {:invalid, [key: ["error 1", "error 2"]]}
+      do: {:invalid, %{key: ["error 1", "error 2"]}}
     def validate(params),
       do: {:ok, params}
   end