PhoenixKit.Modules.Sync.Web.ApiController (phoenix_kit v1.7.38)

Copy Markdown View Source

API controller for Sync cross-site operations.

Handles incoming connection registration requests from remote PhoenixKit sites. When a remote site creates a sender connection pointing to this site, they call this API to automatically register the connection here.

Security

  • Incoming connection mode controls how requests are handled
  • Optional password protection for incoming connections
  • All connections are logged with remote site information

Endpoints

  • POST /{prefix}/sync/api/register-connection - Register incoming connection

Summary

Functions

delete_connection(conn, params)

Deletes a connection when requested by the remote site.

get_connection_status(conn, params)

Returns the current status of a connection.

list_tables(conn, params)

Lists available tables for sync.

pull_data(conn, params)

Pulls data for a specific table.

register_connection(conn, params)

Registers an incoming connection from a remote site.

status(conn, params)

Health check endpoint for DB Sync API.

table_records(conn, params)

Returns records from a specific table for preview.

table_schema(conn, params)

Returns schema for a specific table.

update_status(conn, params)

Updates the status of a connection when notified by the sender.

verify_connection(conn, params)

Verifies a connection still exists.

Functions

delete_connection(conn, params)

Deletes a connection when requested by the remote site.

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

Expected JSON body:

  • sender_url (required) - URL of the site sending this request
  • auth_token_hash (required) - The auth token hash to identify the connection

Responses

  • 200 OK - Connection deleted successfully
  • 404 Not Found - Connection not found
  • 503 Service Unavailable - DB Sync module is disabled

get_connection_status(conn, params)

Returns the current status of a connection.

Called by receiver to get the sender's current connection status. This allows receivers to sync their status with the sender.

Expected JSON body:

  • receiver_url (required) - URL of the receiver site requesting status
  • auth_token_hash (required) - The auth token hash to identify the connection

Responses

  • 200 OK - Returns connection status
  • 404 Not Found - Connection not found
  • 503 Service Unavailable - DB Sync module is disabled

list_tables(conn, params)

Lists available tables for sync.

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

Expected JSON body:

  • auth_token_hash (required) - The auth token hash to identify the connection

Responses

  • 200 OK - Returns list of tables with row counts and sizes
  • 401 Unauthorized - Invalid auth token
  • 503 Service Unavailable - DB Sync module is disabled

pull_data(conn, params)

Pulls data for a specific table.

Called by receiver to fetch table data during sync.

Expected JSON body:

  • auth_token_hash (required) - The auth token hash to identify the connection
  • table_name (required) - Name of the table to pull
  • conflict_strategy (optional) - How to handle conflicts (skip, overwrite, merge)

Responses

  • 200 OK - Returns table data
  • 401 Unauthorized - Invalid auth token
  • 404 Not Found - Table not found
  • 503 Service Unavailable - DB Sync module is disabled

register_connection(conn, params)

Registers an incoming connection from a remote site.

Expected JSON body:

  • sender_url (required) - URL of the site sending this request
  • connection_name (required) - Name for the connection
  • auth_token (required) - The auth token for the connection
  • password (optional) - Password if this site requires one

Responses

  • 200 OK - Connection registered successfully
  • 400 Bad Request - Missing required fields
  • 401 Unauthorized - Invalid password
  • 403 Forbidden - Incoming connections are denied
  • 409 Conflict - Connection already exists for this site
  • 503 Service Unavailable - DB Sync module is disabled

status(conn, params)

Health check endpoint for DB Sync API.

Returns whether the module is enabled and accepting connections.

table_records(conn, params)

Returns records from a specific table for preview.

Expected JSON body:

  • auth_token_hash - Hash of the auth token
  • table_name - Name of the table
  • limit - Maximum number of records (default: 10)
  • offset - Offset for pagination (default: 0)
  • ids (optional) - List of specific IDs to fetch
  • id_start, id_end (optional) - ID range filter

Returns:

  • 200 OK with records
  • 401 Unauthorized
  • 404 Not Found

table_schema(conn, params)

Returns schema for a specific table.

Expected JSON body:

  • auth_token_hash - Hash of the auth token
  • table_name - Name of the table

Returns:

  • 200 OK with schema data
  • 401 Unauthorized
  • 404 Not Found

update_status(conn, params)

Updates the status of a connection when notified by the sender.

Called when the sender suspends, reactivates, or revokes their connection. The receiver should mirror the status change.

Expected JSON body:

  • sender_url (required) - URL of the site sending this request
  • auth_token_hash (required) - The auth token hash to identify the connection
  • status (required) - The new status ("active", "suspended", "revoked")

Responses

  • 200 OK - Status updated successfully
  • 404 Not Found - Connection not found
  • 503 Service Unavailable - DB Sync module is disabled

verify_connection(conn, params)

Verifies a connection still exists.

Called by sender to check if receiver still has the connection. Used for self-healing when the receiver was offline during delete.

Expected JSON body:

  • sender_url (required) - URL of the site sending this request
  • auth_token_hash (required) - The auth token hash to identify the connection

Responses

  • 200 OK - Connection exists
  • 404 Not Found - Connection not found (deleted)
  • 503 Service Unavailable - DB Sync module is disabled