PhoenixKit.Modules.Sync.ConnectionNotifier (phoenix_kit v1.7.42)

Copy Markdown View Source

Handles cross-site notification when creating sender connections.

When a sender connection is created, this module notifies the remote site so they can automatically register the incoming connection on their end.

How It Works

  1. When you create a sender connection pointing to a remote site (e.g., "https://remote.com")
  2. This module calls POST https://remote.com/{prefix}/db-sync/api/register-connection
  3. The remote site creates a receiver connection automatically
  4. The result is recorded in the connection's metadata

Remote Site Responses

  • 200 OK - Connection registered successfully
  • 401 Unauthorized - Password required or invalid
  • 403 Forbidden - Incoming connections denied
  • 409 Conflict - Connection already exists
  • 503 Service Unavailable - DB Sync module disabled

Usage

Usually called automatically when creating connections via the LiveView UI. Can also be called manually:

{:ok, result} = ConnectionNotifier.notify_remote_site(connection, token, password: "optional")

Summary

Types

notify_result()

Functions

check_remote_status(site_url)

Checks the status of a remote site's DB Sync API.

fetch_sender_tables(connection, opts \\ [])

Fetches the list of available tables from the sender.

fetch_table_records(connection, table_name, opts \\ [])

Fetch table records from a sender site via HTTP API for preview.

fetch_table_schema(connection, table_name, opts \\ [])

Fetch table schema from a sender site via HTTP API.

notify_delete(connection, opts \\ [])

Notifies a remote site to delete a connection.

notify_remote_site(connection, raw_token, opts \\ [])

Notifies a remote site about a new sender connection.

notify_status_change(connection, new_status, opts \\ [])

Notifies a remote site of a status change (suspend, reactivate, revoke).

pull_table_data(connection, table_name, opts \\ [])

Pulls data for a specific table from the sender.

query_sender_status(connection, opts \\ [])

Queries the sender for the current connection status.

verify_connection(connection, opts \\ [])

Verifies a connection still exists on the remote site.

Types

notify_result()

@type notify_result() :: %{
  success: boolean(),
  status: :registered | :pending | :failed | :skipped,
  message: String.t(),
  remote_connection_id: integer() | nil,
  http_status: integer() | nil,
  error: String.t() | nil
}

Functions

check_remote_status(site_url)

@spec check_remote_status(String.t()) :: {:ok, map()} | {:error, any()}

Checks the status of a remote site's DB Sync API.

Parameters

  • site_url - The remote site's base URL

Returns

  • {:ok, status} - Remote site status
  • {:error, reason} - Failed to contact site

fetch_sender_tables(connection, opts \\ [])

Fetches the list of available tables from the sender.

Called by receiver to get a list of tables that can be synced.

Parameters

  • connection - The receiver connection (must have site_url and auth_token/auth_token_hash)
  • opts - Options:
    • :timeout - HTTP request timeout (default: 30_000ms)

Returns

  • {:ok, tables} - List of table info maps with :name, :row_count, :size_bytes
  • {:error, :offline} - Sender is offline
  • {:error, reason} - Failed to fetch

fetch_table_records(connection, table_name, opts \\ [])

Fetch table records from a sender site via HTTP API for preview.

Options:

  • :limit - Maximum number of records to fetch (default: 10)
  • :offset - Offset for pagination (default: 0)
  • :ids - List of specific IDs to fetch
  • :id_range - Tuple of {start_id, end_id}

Returns:

  • {:ok, records} - List of record maps
  • {:error, :offline} - Sender is offline
  • {:error, reason} - Failed to fetch records

fetch_table_schema(connection, table_name, opts \\ [])

Fetch table schema from a sender site via HTTP API.

Returns:

  • {:ok, schema} - Map with :columns list
  • {:error, :offline} - Sender is offline
  • {:error, reason} - Failed to fetch schema

notify_delete(connection, opts \\ [])

Notifies a remote site to delete a connection.

Called when a receiver deletes their connection - notifies the sender to also delete.

Parameters

  • connection - The connection being deleted (must have site_url and auth_token_hash)
  • opts - Options:
    • :timeout - HTTP request timeout (default: 30_000ms)

Returns

  • {:ok, :deleted} - Remote site deleted the connection
  • {:ok, :not_found} - Connection didn't exist on remote (already deleted)
  • {:ok, :offline} - Remote site is offline (will self-heal later)
  • {:error, reason} - Failed to notify

notify_remote_site(connection, raw_token, opts \\ [])

@spec notify_remote_site(map(), String.t(), keyword()) ::
  {:ok, notify_result()} | {:error, any()}

Notifies a remote site about a new sender connection.

Parameters

  • connection - The sender connection that was just created
  • raw_token - The raw auth token (only available at creation time)
  • opts - Options:
    • :password - Password to provide to remote site (if required)
    • :timeout - HTTP request timeout (default: 30_000ms)

Returns

  • {:ok, result} - Notification sent, result contains details
  • {:error, reason} - Failed to send notification

notify_status_change(connection, new_status, opts \\ [])

Notifies a remote site of a status change (suspend, reactivate, revoke).

Called when a sender changes their connection status - the receiver should mirror it.

Parameters

  • connection - The connection with updated status
  • new_status - The new status ("active", "suspended", "revoked")
  • opts - Options:
    • :timeout - HTTP request timeout (default: 30_000ms)

Returns

  • {:ok, :updated} - Remote site updated the status
  • {:ok, :not_found} - Connection not found on remote
  • {:ok, :offline} - Remote site is offline
  • {:error, reason} - Failed to notify

pull_table_data(connection, table_name, opts \\ [])

Pulls data for a specific table from the sender.

Called by receiver to fetch table data during sync.

Parameters

  • connection - The receiver connection
  • table_name - Name of the table to pull
  • opts - Options:
    • :timeout - HTTP request timeout (default: 60_000ms for large data)
    • :conflict_strategy - How to handle existing records ("skip", "overwrite", "merge")

Returns

  • {:ok, result} - Map with :records_imported, :records_skipped, etc.
  • {:error, :offline} - Sender is offline
  • {:error, reason} - Failed to pull

query_sender_status(connection, opts \\ [])

Queries the sender for the current connection status.

Called by receiver to sync their status with the sender's status.

Parameters

  • connection - The receiver connection (must have site_url and auth_token_hash)
  • opts - Options:
    • :timeout - HTTP request timeout (default: 30_000ms)

Returns

  • {:ok, status} - Current status from sender ("active", "suspended", "revoked")
  • {:ok, :offline} - Sender is offline
  • {:ok, :not_found} - Connection not found on sender
  • {:error, reason} - Failed to query

verify_connection(connection, opts \\ [])

Verifies a connection still exists on the remote site.

Called by sender to check if receiver still has the connection. If not, the sender should delete their own connection.

Returns

  • {:ok, :exists} - Connection exists on remote
  • {:ok, :not_found} - Connection was deleted on remote
  • {:ok, :offline} - Remote site is offline
  • {:error, reason} - Failed to verify