Merge pull request #1 from wowica/add-behaviour

Add behaviour

.github/workflows/ci.yml

@@ -0,0 +1,118 @@
+name: CI
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+env:
+  MIX_ENV: test
+
+jobs:
+  setup:
+    name: Setup
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup BEAM
+        uses: erlef/setup-beam@v1
+        with:
+          version-file: .tool-versions
+          version-type: strict
+
+      - name: Cache
+        uses: actions/cache@v3
+        with:
+          path: |
+            _build
+            deps
+          key: |
+            xogmios-versions-${{ hashFiles('.tool-versions') }}-${{ hashFiles('mix.lock') }}-YYYY-MM-DD
+          restore-keys: |
+            xogmios-versions-${{ hashFiles('.tool-versions') }}-${{ hashFiles('mix.lock') }}-YYYY-MM-DD
+
+      - name: Install Elixir dependencies
+        run: mix do deps.get, compile --warnings-as-errors
+
+  test:
+    name: Test
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup BEAM
+        uses: erlef/setup-beam@v1
+        with:
+          version-file: .tool-versions
+          version-type: strict
+
+      - name: Cache
+        uses: actions/cache@v3
+        with:
+          path: |
+            _build
+            deps
+          key: |
+            xogmios-versions-${{ hashFiles('.tool-versions') }}-${{ hashFiles('mix.lock') }}-YYYY-MM-DD
+          restore-keys: |
+            xogmios-versions-${{ hashFiles('.tool-versions') }}-${{ hashFiles('mix.lock') }}-YYYY-MM-DD
+
+      - name: Run tests
+        run: mix test --warnings-as-errors
+
+  analysis:
+    name: Static Analysis
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup BEAM
+        id: beam
+        uses: erlef/setup-beam@v1
+        with:
+          version-file: .tool-versions
+          version-type: strict
+
+      - name: Cache
+        uses: actions/cache@v3
+        with:
+          path: |
+            _build
+            deps
+          key: |
+            xogmios-versions-${{ hashFiles('.tool-versions') }}-${{ hashFiles('mix.lock') }}-YYYY-MM-DD
+          restore-keys: |
+            xogmios-versions-${{ hashFiles('.tool-versions') }}-${{ hashFiles('mix.lock') }}-YYYY-MM-DD
+
+      - name: Mix Audit
+        run: mix deps.audit
+
+      - name: Formatted
+        run: mix format --check-formatted
+
+      - name: Restore PLT cache
+        uses: actions/cache@v3
+        id: plt_cache
+        with:
+          key: plt-${{ runner.os }}-${{ steps.beam.outputs.otp-version }}-${{ steps.beam.outputs.elixir-version }}-${{ hashFiles('**/mix.lock') }}-${{ hashFiles('**/*.ex') }}
+          restore-keys: |
+            plt-${{ runner.os }}-${{ steps.beam.outputs.otp-version }}-${{ steps.beam.outputs.elixir-version }}-${{ hashFiles('**/mix.lock') }}-${{ hashFiles('**/*.ex') }}
+            plt-${{ runner.os }}-${{ steps.beam.outputs.otp-version }}-${{ steps.beam.outputs.elixir-version }}-${{ hashFiles('**/mix.lock') }}-
+            plt-${{ runner.os }}-${{ steps.beam.outputs.otp-version }}-${{ steps.beam.outputs.elixir-version }}-
+            plt-${{ runner.os }}-${{ steps.beam.outputs.otp-version }}-
+          path: priv/plts
+
+      - name: Create PLTs
+        if: steps.plt_cache.outputs.cache-hit != 'true' || github.run_attempt != '1'
+        run: mix dialyzer --plt
+
+      - name: Run Dialyzer
+        run: mix dialyzer --format github

README.md

@@ -1,13 +1,60 @@
 # Xogmios
 
-An Elixir client for [Ogmios](https://github.com/CardanoSolutions/ogmios)
+![CI Status](https://github.com/wowica/xogmios/actions/workflows/ci.yml/badge.svg)
 
-## Running
+An Elixir client for [Ogmios](https://github.com/CardanoSolutions/ogmios). This project is highly experimental. It currently only partially supports the chain sync Ouroboros mini-protocol.
 
-Populate `OGMIOS_URL` and run the following to start following the chain and printing newly minted blocks as they become available:
+## Running as a library
+
+Add the dependency to `mix.exs`:
+
+```elixir
+defp deps do
+  [
+    {:xogmios, git: "https://github.com/wowica/xogmios"}
+  ]
+end
+```
+
+From a new module, call `use Xogmios.ChainSync` and implement the `start_link/1` and `handle_block/2` functions as such:
+
+```elixir
+defmodule MyApp.XogmiosClient do
+
+  use Xogmios.ChainSync
+
+  def start_link(opts),
+    do: start_connection(opts)
+
+  @impl true
+  def handle_block(block, state) do
+    IO.puts("handle_block #{block["height"]}")
+    {:ok, :next_block, state}
+  end
+end
+```
+
+Add the new module to the app's supervision tree in `application.ex`:
+
+```elixir
+def start(_type, _args) do
+  children =[
+    {MyApp.XogmiosClient, url: "ws://url-for-ogmios"},
+  ]
+
+  opts = [strategy: :one_for_one, name: Xogmios.Supervisor]
+  Supervisor.start_link(children, opts)
+end
+```
+
+See more examples in [Xogmios.ClientExampleA](lib/xogmios/client_example_a.ex) and [Xogmios.ClientExampleB](lib/xogmios/client_example_b.ex)
+
+## Running as a standalone client
+
+Clone this repo, populate `OGMIOS_URL` and run the following to start following the chain and printing newly minted blocks as they become available:  
 
 ```shell
-OGMIOS_URL="ws://..." mix run -e "Xogmios.chain_sync" --no-halt
+OGMIOS_URL="ws://..." mix run --no-halt
 connected!
 Finding intersection...
 
@@ -23,6 +70,7 @@ Height: 9739938 ID: eba6cfb41f2e1c777ec282b24ea27cf23d118d4522fd26397d8f4b179ea7
 ...
 ```
 
-## Development
+## Text
+
+Run `mix test`
 
-This library is highly experimental. It currently only partially supports the chain sync Ouroboros mini-protocol.

lib/xogmios.ex

@@ -1,17 +1,2 @@
 defmodule Xogmios do
-  def chain_sync() do
-    pid = GenServer.whereis(Xogmios.Websocket)
-    Xogmios.Websocket.send_frame(pid, message())
-  end
-
-  defp message do
-    # Syncs with tip
-    ~S"""
-    {
-      "jsonrpc": "2.0",
-      "method": "nextBlock",
-      "id": "start"
-    }
-    """
-  end
 end

lib/xogmios/application.ex

@@ -4,9 +4,7 @@ defmodule Xogmios.Application do
   @impl true
   def start(_type, _args) do
     children =
-      [
-        Xogmios.Database
-      ]
+      []
       |> Kernel.++(xogmios_websocket())
 
     opts = [strategy: :one_for_one, name: Xogmios.Supervisor]
@@ -19,7 +17,10 @@ defmodule Xogmios.Application do
     if is_nil(connection_url) do
       []
     else
-      [{Xogmios.Websocket, url: connection_url}]
+      [
+        {Xogmios.ClientExampleA, url: connection_url},
+        {Xogmios.ClientExampleB, url: connection_url}
+      ]
     end
   end
 end