@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} - 停止套接字

仅在使用 WebSockets 时支持控制帧。

options 包含一个 opcode 键，它将是 :ping 或 :pong。

如果控制帧没有有效负载，则有效负载值将为 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 原子和一个消息，该消息可以是任何项。内置的 WebSockets 传输支持 :text 和 :binary opcode，并且消息必须始终是 iodata。长轮询仅支持文本 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 原子和一个消息，该消息可以是任何项。内置的 WebSockets 传输支持 :text 和 :binary opcode，并且消息必须始终是 iodata。长轮询仅支持文本 opcode。

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

初始化套接字状态。

这必须从将有效操作套接字的进程中执行。

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

在终止时调用。

如果 reason 是 :closed，则意味着客户端关闭了套接字。这被认为是 :normal 退出信号，因此链接的进程不会自动退出。有关退出信号的更多详细信息，请参阅 Process.exit/2。