View Source GenNostr behaviour (GenNostr v0.1.0)

A low level websocket client that implements the Nostr protocol.

It works like a GenServer.

architecture
Architecture

The GenNostr process spawn a PrimarySupervisor with a ConnectionRegistry and a ConnectionSupervisor (DynamicSupervisor) that supervises connections. The ConnectionRegistry store the url as key to avoid connections to same relay.

The GenNostr process is the client and the websocket processes are then connections. The client send commands to connections. The connections emit events that can to be generated by the commands or by websocket messages and sends back the response to client through handlers.

Link to this section Summary

Callbacks

handle_auth(auth_msg, relay, state)

Invoked when a gen_nostr connection receives a AUTH message (NIP-42).

handle_call(request, from, state)

Invoked when a GenNostr process receives a GenServer call.

handle_cast(request, state)

Invoked when a GenNostr process receives a GenServer cast.

handle_connect(relay, state)

Invoked when a connection has been established to a relay.

handle_continue(continue_arg, state)

Invoked when a GenNostr process receives a message.

handle_disconnect(reason, relay, state)

Invoked when a gen_nostr connection is disconected from relay.

handle_eose(eose_msg, relay, state)

Invoked when a gen_nostr connection receives a EOSE message (NIP-15).

handle_error(reason, relay, state)

Invoked when a gen_nostr connection has a error and can trigger a handle_disconnect/3 if the error close the connection.

handle_event(event_msg, relay, state)

Invoked when a gen_nostr connection receives a EVENT message (NIP-01).

handle_info(msg, state)

Invoked when a GenNostr process receives a message.

handle_notice(notice_msg, relay, state)

Invoked when a gen_nostr connection receives a NOTICE message (NIP-01).

handle_ok(ok_msg, relay, state)

Invoked when a gen_nostr connection receives a OK message (NIP-20).

init(init_arg)

Invoked when the gen_nostr process starts.

terminate(reason, state)

Invoked when a GenNostr process is terminated.

Functions

add_relay(relay)

Crate a new connection to relay.

add_relay(url, options \\ [])

broadcast_message(message)

Send a broadcast message to connected relays.

list_relays()

Relay url list of all current connections.

reconnect(relay)

Tries to reconnect after a disconnection.

remove_relay(relay)

Finishes the connection and removes the relay.

send_message(message, relay)

Send a message to the specified url or relay.

start_link(module, args, options \\ [])

Starts a GenNostr client process.

Link to this section Callbacks

handle_auth(auth_msg, relay, state)

(optional)

@callback handle_auth(auth_msg :: term(), relay :: GenNostr.Relay.t(), state :: term()) ::
  {:ok, new_state} | {:stop, new_state} | {:stop, reason :: term(), new_state}
when new_state: term()

Invoked when a gen_nostr connection receives a AUTH message (NIP-42).

handle_call(request, from, state)

(optional)

@callback handle_call(
  request :: term(),
  from :: GenServer.from(),
  state :: term()
) ::
  {:reply, reply, new_state}
  | {:reply, reply, new_state, timeout() | :hibernate | {:continue, term()}}
  | {:noreply, new_state}
  | {:noreply, new_state, timeout() | :hibernate | {:continue, term()}}
  | {:stop, reason, new_state}
  | {:stop, reason, reply, new_state}
when new_state: term(), reply: term(), reason: term()

Invoked when a GenNostr process receives a GenServer call.

Behaves the same as GenServer.handle_call/3

handle_cast(request, state)

(optional)

@callback handle_cast(request :: term(), state :: term()) ::
  {:noreply, new_state}
  | {:noreply, new_state, timeout() | :hibernate | {:continue, term()}}
  | {:stop, reason :: term(), new_state}
when new_state: term()

Invoked when a GenNostr process receives a GenServer cast.

Behaves the same as GenServer.handle_cast/2

handle_connect(relay, state)

(optional)

@callback handle_connect(relay :: GenNostr.Relay.t(), state :: term()) ::
  {:ok, new_state} | {:stop, reason :: term(), new_state}
when new_state: term()

Invoked when a connection has been established to a relay.

handle_continue(continue_arg, state)

(optional)

@callback handle_continue(continue_arg, state :: term()) ::
  {:noreply, new_state}
  | {:noreply, new_state, timeout() | :hibernate | {:continue, continue_arg}}
  | {:stop, reason :: term(), new_state}
when new_state: term(), continue_arg: term()

Invoked when a GenNostr process receives a message.

Behaves the same as GenServer.handle_continue/2

handle_disconnect(reason, relay, state)

(optional)

@callback handle_disconnect(
  reason :: term(),
  relay :: GenNostr.Relay.t(),
  state :: term()
) ::
  {:ok, new_state} | {:stop, stop_reason :: term(), new_state}
when new_state: term()

Invoked when a gen_nostr connection is disconected from relay.

handle_eose(eose_msg, relay, state)

(optional)

@callback handle_eose(eose_msg :: term(), relay :: GenNostr.Relay.t(), state :: term()) ::
  {:ok, new_state} | {:stop, new_state} | {:stop, reason :: term(), new_state}
when new_state: term()

Invoked when a gen_nostr connection receives a EOSE message (NIP-15).

handle_error(reason, relay, state)

(optional)

@callback handle_error(reason :: term(), relay :: GenNostr.Relay.t(), state :: term()) ::
  {:ok, new_state} | {:stop, stop_reason :: term(), new_state}
when new_state: term()

Invoked when a gen_nostr connection has a error and can trigger a handle_disconnect/3 if the error close the connection.

handle_event(event_msg, relay, state)

(optional)

@callback handle_event(event_msg :: term(), relay :: GenNostr.Relay.t(), state :: term()) ::
  {:ok, new_state} | {:stop, new_state} | {:stop, reason :: term(), new_state}
when new_state: term()

Invoked when a gen_nostr connection receives a EVENT message (NIP-01).

handle_info(msg, state)

(optional)

@callback handle_info(msg :: :timeout | term(), state :: term()) ::
  {:noreply, new_state}
  | {:noreply, new_state, timeout() | :hibernate | {:continue, term()}}
  | {:stop, reason :: term(), new_state}
when new_state: term()

Invoked when a GenNostr process receives a message.

Behaves the same as GenServer.handle_info/2

handle_notice(notice_msg, relay, state)

(optional)

@callback handle_notice(
  notice_msg :: term(),
  relay :: GenNostr.Relay.t(),
  state :: term()
) ::
  {:ok, new_state} | {:stop, new_state} | {:stop, reason :: term(), new_state}
when new_state: GenNostr.Relay.t()

Invoked when a gen_nostr connection receives a NOTICE message (NIP-01).

handle_ok(ok_msg, relay, state)

(optional)

@callback handle_ok(ok_msg :: term(), relay :: GenNostr.Relay.t(), state :: term()) ::
  {:ok, new_state} | {:stop, new_state} | {:stop, reason :: term(), new_state}
when new_state: term()

Invoked when a gen_nostr connection receives a OK message (NIP-20).

init(init_arg)

(optional)

@callback init(init_arg :: term()) ::
  {:ok, state}
  | {:ok, state, timeout() | :hibernate | {:continue, continue_arg :: term()}}
  | :ignore
  | {:stop, reason :: any()}
when state: term()

Invoked when the gen_nostr process starts.

Behaves the same as GenServer.init/1

@impl GenNostr
def init(args) do
  relays = Keyword.get(args, :relays, [])
  options = Keyword.get(args, :options, [])

  Enum.each(relays, &GenNostr.add_relay(&1, options))

  {:ok, %{}}
end

terminate(reason, state)

(optional)

@callback terminate(reason, state :: term()) :: term()
when reason: :normal | :shutdown | {:shutdown, term()} | term()

Invoked when a GenNostr process is terminated.

Note that this callback is not always invoked as the process shuts down. See GenServer.terminate/2 for more information.

Link to this section Functions

add_relay(relay)

Crate a new connection to relay.

options
Options

:mint - keyword list of specific options of elixir mint, default to [protocols: [:http1]]
:reconnect - timeouts list in msec used by reconnect/1, default to [500, 1_000, 5_000, 10_000, 30_000]
:tasks - keyword list of recurring timeout tasks in msec, default to [garbage_collector: 60 * 60 * 1000]

examples
Examples

# using a url and default options
GenNostr.add_relay("wss://relay.com/")

# using the Relay struct and default options
GenNostr.Relay.new(url: "wss://relay.com/")
|> GenNostr.add_relay()

add_relay(url, options \\ [])

@spec add_relay(
  String.t() | GenNostr.Relay.t(),
  keyword()
) :: term()

broadcast_message(message)

@spec broadcast_message(String.t()) :: any()

Send a broadcast message to connected relays.

list_relays()

@spec list_relays() :: [String.t()]

Relay url list of all current connections.

reconnect(relay)

@spec reconnect(GenNostr.Relay.t()) :: term()

Tries to reconnect after a disconnection.

This function must be used within handle_disconnect/3.

examples
Examples

@impl GenNostr
def handle_disconnect(reason, relay, state) do
  Logger.info("Disconnected from relay")

  # don't reconnect if the :remove_relay is the reason
  case reason do
    :remove_relay -> Logger.info("Don't reconnect")
    _ -> GenNostr.reconnect(relay)
  end

  {:ok, state}
end

remove_relay(relay)

@spec remove_relay(String.t() | GenNostr.Relay.t()) :: term()

Finishes the connection and removes the relay.

This function invokes handle_disconnect/3 and receive a reason of :remove_relay

examples
Examples

# using a url and default options
GenNostr.remove_relay("wss://relay.com/")

# using the Relay struct and default options
GenNostr.Relay.new(url: "wss://relay.com/")
|> GenNostr.remove_relay()

send_message(message, relay)

@spec send_message(String.t(), String.t() | GenNostr.Relay.t()) :: any()

Send a message to the specified url or relay.

start_link(module, args, options \\ [])

@spec start_link(module(), term(), GenServer.options()) :: GenServer.on_start()

Starts a GenNostr client process.

This function return a GenServer.start_link/3

examples
Examples

defmodule NostrClient do
  use GenNostr

  def start_link(args) do
    GenNostr.start_link(__MODULE__, args, name: __MODULE__)
  end
end

Settings View Source GenNostr behaviour (GenNostr v0.1.0)

architecture Architecture

Link to this section Summary

Callbacks

Functions

Link to this section Callbacks

handle_auth(auth_msg, relay, state)

handle_call(request, from, state)

handle_cast(request, state)

handle_connect(relay, state)

handle_continue(continue_arg, state)

handle_disconnect(reason, relay, state)

handle_eose(eose_msg, relay, state)

handle_error(reason, relay, state)

handle_event(event_msg, relay, state)

handle_info(msg, state)

handle_notice(notice_msg, relay, state)

handle_ok(ok_msg, relay, state)

init(init_arg)

terminate(reason, state)

Link to this section Functions

add_relay(relay)

options Options

examples Examples

add_relay(url, options \\ [])

broadcast_message(message)

list_relays()

reconnect(relay)

examples Examples

remove_relay(relay)

examples Examples

send_message(message, relay)

start_link(module, args, options \\ [])

examples Examples

View Source GenNostr behaviour (GenNostr v0.1.0)

architecture
Architecture

options
Options

examples
Examples

examples
Examples

examples
Examples

examples
Examples