@spec arguments(
  %Edeliver.Relup.Instructions{
    changed_modules: term(),
    down_instructions: term(),
    down_version: term(),
    up_instructions: term(),
    up_version: term()
  },
  Edeliver.Relup.Config.t()
) :: term()

Returns name of the application.

This name is taken as argument for the run/1 function and is required to access the acceptor processes through the supervision tree

@spec call_this(arguments :: [term()]) ::
  Instruction.instruction() | Instruction.instructions()

Calls the run/1 function of this module

from the relup file during hot code upgrade

@spec dependencies() :: [instruction_module :: atom()]

@spec dependencies() :: [Edeliver.Relup.Instructions.CheckRanchAcceptors]

This module requires the Edeliver.Relup.Instructions.CheckRanchAcceptors module

which must be loaded before this instruction for upgrades and unload after this instruction for downgrades.

@spec insert_where() :: Instruction.insert_fun()

Inserts the instruction before the point of no return.

This causes the release handler to abort the upgrade already when running :release_handler.check_install_release/1 if this instruction fails.

Callback implementation for Edeliver.Relup.Instruction.modify_relup/2.

@spec ranch_connections(ranch_acceptors_sup :: pid()) :: [:supervisor.child_id()]

Gets the process ids of the ranch socket connections if there are any.

@spec ranch_connections_sup(ranch_listener_sup :: pid()) :: pid()

Gets the pid of the supervisor which supervises the ranch connections.

If it cannot be found as child of the given ranch listener supervisor it throws and logs an error.

@spec run(otp_application_name :: atom()) :: :ok

Checks whether the ranch connections can be found.

If not the upgrade will be canceled. This function runs twice because it is executed before the "point of no return", once when checking the relup and once when executing the relup. It also tries to detect the websocket processes if the Phoenix.PubSub.PG2 pubsub backend is used for phoenix websocket channels. It will not fail if that detection is not possible, but a warning is printed

@spec websocket_channel_connections(
  otp_application_name :: atom(),
  connections :: [pid()]
) :: [] | [pid()] | :not_detected

Returns the pids of the connections which are websocket connections for channels.

This detection works only if Phoenix.PubSub.PG2 is used as pubsub backend. If detection fails, it returns :not_detected. Knowing which processes of the known connections are websockets is useful because they should be suspended during the hot code upgrade and resumed again afterwards. If detection fails, websocket connections must be treated as "normal" http request connections. Detection of websocket connections is not possible either by the phoenix api nor by the cowboy / ranch api. That's why this function takes the processes that are monitored by the Phoenix.PubSub.Local process and are a subset of the detected connections as websocket connections for channels. The lookup for Phoenix.PubSub.Local process is dones by searching the supervision tree of the application for:

    `Phoenix.Endpoint` -> `Phoenix.PubSub.PG2` -> `Phoenix.PubSub.LocalSupervisor` -> `Supervisor` -> `Phoenix.PubSub.Local`