@callback child_spec(keyword()) :: :supervisor.child_spec() | :ignore

傳回套接字管理的子項規格。

此動作僅對每個套接字呼叫一次，與傳輸數量無關，且應該負責設定由套接字獨自使用的任何程序結構，與傳輸無關。

各個套接字連線是由傳輸程式開始運作，而控制套接字的程序很可能會屬於傳輸程式。但是，有些套接字會產生新的程序，例如會產生頻道的 Phoenix.Socket，而且這會賦予開始與套接字相關的督導樹的能力。

它會從端點收到套接字選項，例如

socket "/my_app", MyApp.Socket, shutdown: 5000

表示將會呼叫 child_spec([shutdown: 5000])。

:ignore 表示此套接字不需要子項規格。

@callback connect(transport_info :: map()) :: {:ok, state()} | {:error, term()} | :error

連線到套接字。

傳輸通訊會傳遞一個元資料的映射，而通訊中繼端會傳回 {:ok, state}、{:error, reason} 或 :error。傳輸通訊必須儲存狀態，並在所有後續的操作中傳回。當 {:error, reason} 傳回時，有些傳輸通訊（如 WebSockets）允許透過自訂的 :error_handler 根據 reason 自訂回應。

此函式用於授權目的，且可能在有效執行通訊中繼端的程序外呼叫。

在預設的 Phoenix.Socket 實作中，元資料預期有下列金鑰

• :endpoint - 應用程式終端
• :transport - 傳輸通訊名稱
• :params - 連線參數
• :options - 傳輸通訊選項的關鍵字清單，通常由開發人員在設定傳輸通訊時提供。此選項必須包含一個 :serializer 欄位，其中包含序列化程式清單及其需求

@callback drainer_spec(keyword()) :: :supervisor.child_spec() | :ignore

傳回中止套接字的子項規格。

此程序會較晚在監控樹狀結構中啟動，具體目標是在應用程式關閉時中斷連線。

與 child_spec/1 類似，此程序會從終端接收通訊中繼端選項。

@callback handle_control(
  {message :: term(), opts :: keyword()},
  state()
) ::
  {:ok, state()}
  | {:reply, :ok | :error, {opcode :: atom(), message :: term()}, state()}
  | {:stop, reason :: term(), state()}

處理傳入的控制框架。

訊息表示為 {payload, options}。此訊息必須傳回下列任一項：

• {:ok, state} - 繼續通訊中繼端，不回覆
• {:reply, status, reply, state} - 繼續通訊中繼端，並附上回覆
• {:stop, reason, state} - 停止通訊中繼端

僅在使用 WebSocket 時才支援控制框架。

options 包含一個 opcode 金鑰，此金鑰可能是 :ping 或 :pong。

如果控制框架沒有 payload，則 payload 值會為 nil。

@callback handle_in(
  {message :: term(), opts :: keyword()},
  state()
) ::
  {:ok, state()}
  | {:reply, :ok | :error, {opcode :: atom(), message :: term()}, state()}
  | {:stop, reason :: term(), state()}

處理傳入的套接字訊息。

訊息表示為 {payload, options}。此訊息必須傳回下列任一項：

• {:ok, state} - 繼續通訊中繼端，不回覆
• {:reply, status, reply, state} - 繼續通訊中繼端，並附上回覆
• {:stop, reason, state} - 停止通訊中繼端

reply 為一個包含 opcode 項與可以是任何條件的訊息的樹狀結構。內建 WebSocket 傳輸通訊支援 :text 與 :binary opcode，而訊息必須永遠為 iodata。長輪詢僅支援 text opcode。

@callback handle_info(message :: term(), state()) ::
  {:ok, state()}
  | {:push, {opcode :: atom(), message :: term()}, state()}
  | {:stop, reason :: term(), state()}

處理資訊訊息。

訊息為一個條件。此訊息必須傳回下列任一項：

• {:ok, state} - 繼續通訊中繼端，不回覆
• {:push, reply, state} - 繼續通訊中繼端，並附上回覆
• {:stop, reason, state} - 停止通訊中繼端

reply 為一個包含 opcode 項與可以是任何條件的訊息的樹狀結構。內建 WebSocket 傳輸通訊支援 :text 與 :binary opcode，而訊息必須永遠為 iodata。長輪詢僅支援 text opcode。

@callback init(state()) :: {:ok, state()}

初始化套接字狀態。

此訊息必須在會實際執行通訊中繼端的程序中執行。

@callback terminate(reason :: term(), state()) :: :ok

在終止時呼叫。

如果 reason 為 :closed，則表示客戶端關閉了 socket。這被視為 :normal 的退出訊號，因此連結的程序將不會自動退出。有關退出訊號的更多詳細資訊，請參閱 Process.exit/2。