Parrhesia.API.Sync (parrhesia v0.12.0)

Copy Markdown

Sync server control-plane API.

This module manages outbound relay sync definitions and exposes runtime status for each configured sync worker.

The main entrypoint is put_server/2. Accepted server maps are normalized into a stable internal shape and persisted by the sync manager. The expected input shape is:

%{
  "id" => "tribes-primary",
  "url" => "wss://relay-a.example/relay",
  "enabled?" => true,
  "auth_pubkey" => "...64 hex chars...",
  "filters" => [%{"kinds" => [5000]}],
  "mode" => "req_stream",
  "overlap_window_seconds" => 300,
  "relay_info_mode" => "required",
  "auth" => %{"type" => "nip42", "mode" => "on_challenge"},
  "tls" => %{
    "mode" => "required",
    "hostname" => "relay-a.example",
    "ca_certfile" => "/etc/tribes/cluster-ca.pem",
    "client_certfile" => "/etc/tribes/node.crt",
    "client_keyfile" => "/etc/tribes/node.key",
    "pins" => [%{"type" => "spki_sha256", "value" => "..."}]
  },
  "metadata" => %{}
}

Most functions accept :manager or :name in opts to target a non-default manager.

Summary

Types

server()

Normalized sync server configuration returned by the sync manager.

Functions

get_server(server_id, opts \\ [])

Fetches a single normalized sync server definition.

list_servers(opts \\ [])

Lists all configured sync servers, including their runtime state.

put_server(server, opts \\ [])

Creates or replaces a sync server definition.

remove_server(server_id, opts \\ [])

Removes a stored sync server definition and stops its worker if it is running.

server_stats(server_id, opts \\ [])

Returns runtime counters and timestamps for a single sync server.

start_server(server_id, opts \\ [])

Marks a sync server as running and reconciles its worker state.

stop_server(server_id, opts \\ [])

Stops a sync server and records a disconnect timestamp in runtime state.

sync_health(opts \\ [])

Returns a health summary for the sync subsystem.

sync_now(server_id, opts \\ [])

Triggers an immediate sync run for a server.

sync_stats(opts \\ [])

Returns aggregate counters across all configured sync servers.

Types

server()

@type server() :: map()

Normalized sync server configuration returned by the sync manager.

Functions

get_server(server_id, opts \\ [])

@spec get_server(
  String.t(),
  keyword()
) :: {:ok, server()} | :error | {:error, term()}

Fetches a single normalized sync server definition.

Returns :error when the server id is unknown.

list_servers(opts \\ [])

@spec list_servers(keyword()) :: {:ok, [server()]} | {:error, term()}

Lists all configured sync servers, including their runtime state.

put_server(server, opts \\ [])

@spec put_server(
  map(),
  keyword()
) :: {:ok, server()} | {:error, term()}

Creates or replaces a sync server definition.

remove_server(server_id, opts \\ [])

@spec remove_server(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Removes a stored sync server definition and stops its worker if it is running.

server_stats(server_id, opts \\ [])

@spec server_stats(
  String.t(),
  keyword()
) :: {:ok, map()} | :error | {:error, term()}

Returns runtime counters and timestamps for a single sync server.

Returns :error when the server id is unknown.

start_server(server_id, opts \\ [])

@spec start_server(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Marks a sync server as running and reconciles its worker state.

stop_server(server_id, opts \\ [])

@spec stop_server(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Stops a sync server and records a disconnect timestamp in runtime state.

sync_health(opts \\ [])

@spec sync_health(keyword()) :: {:ok, map()} | {:error, term()}

Returns a health summary for the sync subsystem.

sync_now(server_id, opts \\ [])

@spec sync_now(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Triggers an immediate sync run for a server.

sync_stats(opts \\ [])

@spec sync_stats(keyword()) :: {:ok, map()} | {:error, term()}

Returns aggregate counters across all configured sync servers.