# `Parrhesia.API.Sync`

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:

```elixir
%{
  "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.

# `server`

```elixir
@type server() :: map()
```

Normalized sync server configuration returned by the sync manager.

# `get_server`

```elixir
@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`

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

Lists all configured sync servers, including their runtime state.

# `put_server`

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

Creates or replaces a sync server definition.

# `remove_server`

```elixir
@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`

```elixir
@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`

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

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

# `stop_server`

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

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

# `sync_health`

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

Returns a health summary for the sync subsystem.

# `sync_now`

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

Triggers an immediate sync run for a server.

# `sync_stats`

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

Returns aggregate counters across all configured sync servers.

---

*Consult [api-reference.md](api-reference.md) for complete listing*