Publish v0.1 (#14)

* Updates for hex package
* Add CI and Hex badges

Author: caike

README.md

@@ -1,10 +1,38 @@
 # Xander
 
-Elixir client for Cardano's Ouroboros networking.
+![CI Status](https://github.com/wowica/xander/actions/workflows/ci.yml/badge.svg)
+[![Version](https://img.shields.io/hexpm/v/xander.svg)](https://hex.pm/packages/xander)
+
+Elixir client for Cardano's Ouroboros networking protocol.
 
 ⚠️ This project is under active development. For a more stable solution to connect to a Cardano node using Elixir, see [Xogmios](https://github.com/wowica/xogmios).
 
- There are two ways to run this project:
+## Quickstart
+
+Below is an example of how to connect to a Cardano node and run a query that returns the current tip of the ledger, similar to a `cardano-cli query tip` command.
+
+```elixir
+$ iex
+> Mix.install([{:xander, "~> 0.1.0"}])
+> # Must be a valid Unix socket path
+> # to a fully synced Cardano node
+> socket_path = "/path/to/cardano-node.socket"
+> config = Xander.Config.default_config!(socket_path)
+[
+  network: :mainnet,
+  path: [socket_path: "/tmp/cardano-node.socket"],
+  port: 0,
+  type: :socket
+]
+> {:ok, pid} = Xander.Query.start_link(config)
+{:ok, #PID<0.207.0>}
+> Xander.Query.run(pid, :get_current_tip)
+{:ok,
+ {147911158, "b2a4f78539559866281d6089143fa4c99db90b7efc4cf7787777f927967f0c8a"}}
+```
+
+For a more detailed description of different ways to use this library, read the following sections:
+
 
 1. [Running via Docker](#running-via-docker)
 2. [Running natively with an Elixir local dev environment](#running-natively-with-an-elixir-local-dev-environment)
@@ -31,6 +59,8 @@ docker compose up --build
 
 #### Via local UNIX socket
 
+🚨 **Note:** Socket files mapped via socat/ssh tunnels **DO NOT WORK** when using containers on OS X.
+
 Uncomment the `volumes` section in the `compose.yml` file to mount the local UNIX socket to the container's socket path.
 
 ```yml
@@ -57,7 +87,7 @@ CARDANO_NODE_PATH=/your/cardano/node.socket elixir run.exs
 
 This is useful if you want to run the application on a server different from your Cardano node.
 
-🚨 **Note:** Socket files mapped via socat/ssh tunnels do not work when using containers on OS X.
+🚨 **Note:** Socket files mapped via socat/ssh tunnels **DO NOT WORK** when using containers on OS X.
 
 1. Run socat on the remote server with the following command:
 

lib/xander/handshake/response.ex

@@ -1,8 +1,16 @@
 defmodule Xander.Handshake.Response do
+  @moduledoc """
+  This module is responsible for validating and parsing the
+  handshake response from a Cardano node.
+  """
+
   defstruct [:type, :version_number, :network_magic, :query]
 
   alias Xander.Util
 
+  @doc """
+  Validates the handshake response from a Cardano node.
+  """
   def validate(response) do
     %{payload: payload} = Util.plex(response)
 

lib/xander/handshake_response.ex

@@ -1,7 +1,9 @@
 defmodule Xander.Query do
   @moduledoc """
   Issues ledger queries to a Cardano node using the Node-to-Client (n2c) protocol.
+  This module implements the `gen_statem` behaviour.
   """
+
   @behaviour :gen_statem
 
   alias Xander.Handshake
@@ -19,10 +21,31 @@ defmodule Xander.Query do
   # Public API #
   ##############
 
+  @doc """
+  Sends a query to the connected Cardano node.
+
+  Available queries are:
+
+    * `:get_current_era`
+    * `:get_current_block_height`
+    * `:get_epoch_number`
+    * `:get_current_tip`
+
+  For example:
+
+  ```elixir
+  Xander.Query.run(pid, :get_epoch_number)
+  ```
+  """
+  @spec run(pid() | atom(), atom()) :: {atom(), any()}
   def run(pid \\ __MODULE__, query_name) do
     :gen_statem.call(pid, {:request, query_name})
   end
 
+  @doc """
+  Starts a new query process.
+  """
+  @spec start_link(Keyword.t()) :: GenServer.on_start()
   def start_link(network: network, path: path, port: port, type: type) do
     data = %__MODULE__{
       client: tcp_lib(type),
@@ -39,6 +62,10 @@ defmodule Xander.Query do
   # Callbacks #
   #############
 
+  @doc """
+  Returns a child specification for the process. This determines the
+  configuration of the OTP process when it is started by its parent.
+  """
   def child_spec(opts) do
     %{
       id: __MODULE__,
@@ -58,6 +85,11 @@ defmodule Xander.Query do
     {:ok, :disconnected, data, actions}
   end
 
+  @doc """
+  Emits events when in the `disconnected` state.
+  """
+  def disconnected(_event_type, _event_content, _data)
+
   def disconnected(
         :internal,
         :connect,
@@ -84,6 +116,12 @@ defmodule Xander.Query do
     {:keep_state, data, actions}
   end
 
+  @doc """
+  Emits events when in the `connected` state. Must transition to the
+  `established_has_agency` state prior to sending queries to the node.
+  """
+  def connected(_event_type, _event_content, _data)
+
   def connected(
         :internal,
         :establish,
@@ -108,6 +146,11 @@ defmodule Xander.Query do
     end
   end
 
+  @doc """
+  Emits events when in the `established_no_agency` state.
+  """
+  def established_no_agency(_event_type, _event_content, _data)
+
   def established_no_agency(
         :internal,
         :acquire_agency,
@@ -123,6 +166,12 @@ defmodule Xander.Query do
     {:next_state, :disconnected, data}
   end
 
+  @doc """
+  Emits events when in the `established_has_agency` state. Can send queries
+  to the node when in this state.
+  """
+  def established_has_agency(_event_type, _event_content, _data)
+
   def established_has_agency(
         {:call, from},
         {:request, request},

lib/xander/query.ex

@@ -4,10 +4,16 @@ defmodule Xander.Query.Response do
   @message_response 4
   @slot_timeline 1
 
-  def parse_response(full_response) do
-    %{payload: response_payload} = Xander.Util.plex(full_response)
+  @type cbor :: binary()
 
-    case CBOR.decode(response_payload) do
+  @doc """
+  Parses the response from a query. Accepts CBOR encoded responses.
+  """
+  @spec parse_response(cbor()) :: {:ok, any()} | {:error, atom()}
+  def parse_response(cbor_response) do
+    %{payload: cbor_response_payload} = Xander.Util.plex(cbor_response)
+
+    case CBOR.decode(cbor_response_payload) do
       {:ok, decoded, ""} -> parse_cbor(decoded)
       {:error, _reason} -> {:error, :error_decoding_cbor}
     end

lib/xander/query/response.ex

@@ -1,21 +1,23 @@
 defmodule Xander.MixProject do
   use Mix.Project
 
+  @description "An Elixir library for communicating with a Cardano node"
+  @source_url "https://github.com/wowica/xander"
+  @version "0.1.0"
+
   def project do
     [
       app: :xander,
-      version: "0.1.0",
+      version: @version,
       elixir: "~> 1.16",
       start_permanent: Mix.env() == :prod,
       deps: deps(),
       description: description(),
       package: package(),
       name: "Xander",
-      source_url: "https://github.com/wowica/xander",
-      docs: [
-        main: "Xander",
-        extras: ["README.md"]
-      ]
+      source_url: @source_url,
+      description: @description,
+      docs: docs()
     ]
   end
 
@@ -41,9 +43,17 @@ defmodule Xander.MixProject do
   defp package do
     [
       name: "xander",
+      maintainers: ["Carlos Souza", "Dave Miner"],
       files: ~w(lib .formatter.exs mix.exs README* LICENSE*),
       licenses: ["Apache-2.0"],
       links: %{"GitHub" => "https://github.com/wowica/xander"}
     ]
   end
+
+  defp docs do
+    [
+      main: "readme",
+      extras: ["README.md"]
+    ]
+  end
 end

mix.exs

@@ -3,7 +3,6 @@ Mix.install([
   {:xander, path: Path.expand(".")}
 ])
 
-
 socket_path = System.get_env("CARDANO_NODE_SOCKET_PATH")
 
 if socket_path == nil do
@@ -26,20 +25,19 @@ queries = [
 
 case Query.start_link(config) do
   {:ok, pid} ->
-    IO.puts("Successfully connected to Cardano node")
+    IO.puts("Successfully connected to Cardano node 🎉\n")
 
     for query <- queries do
       case Query.run(pid, query) do
-      {:ok, result} ->
-        IO.puts("Query #{query} result: #{inspect(result)}")
+        {:ok, result} ->
+          IO.puts("Query #{query} result: #{inspect(result)}")
 
-      {:error, reason} ->
+        {:error, reason} ->
           IO.puts("Error querying #{inspect(query)}: #{inspect(reason)}")
           System.halt(1)
       end
     end
 
-
   {:error, reason} ->
     IO.puts("Failed to connect to Cardano node: #{inspect(reason)}")
     System.halt(1)

run.exs

@@ -29,14 +29,14 @@ queries = [
 
 case Query.start_link(config) do
   {:ok, pid} ->
-    IO.puts("Successfully connected to Demeter node")
+    IO.puts("Successfully connected to Demeter node 🎉\n")
 
     for query <- queries do
       case Query.run(pid, query) do
-      {:ok, result} ->
-        IO.puts("Query #{query} result: #{inspect(result)}")
+        {:ok, result} ->
+          IO.puts("Query #{query} result: #{inspect(result)}")
 
-      {:error, reason} ->
+        {:error, reason} ->
           IO.puts("Error querying #{inspect(query)}: #{inspect(reason)}")
           System.halt(1)
       end