edeliver v1.2.7 Edeliver.Relup.Instructions.CheckRanchConnections

This upgrade instruction checks whether the running ranch connections can be found.

This instruction will cause the upgrade to be canceled if the ranch connections cannot be found and because it is insterted before the “point of no return” it will run twice, once when checking the relup and once when executing the relup.

If Phoenix.PubSub.PG2 is used as pubsub backend for phoenix channels, running websocket processes will be detected and suspended by the

Edeliver.Relup.Instructions.SuspendChannels

instruction during the upgrade and resumed by the

Edeliver.Relup.Instructions.ResumeChannels instruction

after the upgrade / downgrade of the node.

Summary

Types

insert_fun()

instruction()

instructions()

Functions

arguments(instructions, config)

Returns name of the application

call_this(arguments \\ [])

Calls the run/1 function of this module

debug(message)

Logs a debug message using the Logger on the running node which is upgraded

dependencies()

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

ensure_dependencies_loaded_before_instruction_for_upgrade(instructions, call_this_instruction, dependencies \\ dependencies())

Ensures that all Edeliver.Relup.RunnableInstruction modules used / referenced by this instruction and returned by the dependencies/0 callback are loaded before this instruction is executed during the upgrade

ensure_dependencies_unloaded_after_instruction_for_downgrade(instructions, call_this_instruction, dependencies \\ dependencies())

Ensures that all Edeliver.Relup.RunnableInstruction modules used / referenced by this instruction and returned by the dependencies/0 callback are unloaded after this instruction is executed during the downgrade

error(message)

Logs an error using the Logger on the running node which is upgraded

format_in_upgrade_script(format, arguments)

Formats and prints the message on the node

info(message)

Logs an info message using the Logger on the running node which is upgraded

insert_where()

Inserts the instruction before the point of no return

log_in_upgrade_script(type, message)

Logs the message of the given type on the node

modify_relup(instructions, config)

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

ranch_connections(ranch_acceptors_sup)

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

ranch_connections_sup(ranch_listener_sup)

Gets the pid of the supervisor which supervises the ranch connections

run(otp_application_name)

Checks whether the ranch connections can be found

warn(message)

Logs a warning using the Logger on the running node which is upgraded

websocket_channel_connections(otp_application_name, connections)

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

Macros

assume(assertion, error_message)

Assumes that the pattern matches or throws an error with the given error message

Types

insert_fun :: (%Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term} | instructions, new_instructions :: instruction | instructions -> updated_instructions :: %Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term} | instructions)

instruction :: :relup.instruction

instructions :: [instruction]

Functions

arguments(instructions, config)

Specs

arguments(%Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term}, %ReleaseManager.Config{dev: term, env: term, erl: term, name: term, package: term, relx_config: term, upgrade?: term, verbosity: term, version: term}) :: 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

call_this(arguments \\ [])

Specs

call_this(arguments :: [term]) ::
  instruction |
  instructions

Calls the run/1 function of this module

from the relup file during hot code upgrade

debug(message)

Specs

debug(message :: String.t) :: no_return

Logs a debug message using the Logger on the running node which is upgraded.

In addition the same debug message is logged on the node which executes the upgrade and is displayed as output of the $APP/bin/$APP upgarde $RELEASE command.

dependencies()

Specs

dependencies :: [instruction_module :: atom]

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.

ensure_dependencies_loaded_before_instruction_for_upgrade(instructions, call_this_instruction, dependencies \\ dependencies())

Specs

ensure_dependencies_loaded_before_instruction_for_upgrade(instructions :: %Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term}, runnable_instruction :: {:apply, {module :: atom, :run, arguments :: [term]}}, dependencies :: [instruction_module :: atom]) :: %Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term}

ensure_dependencies_unloaded_after_instruction_for_downgrade(instructions, call_this_instruction, dependencies \\ dependencies())

Specs

ensure_dependencies_unloaded_after_instruction_for_downgrade(instructions :: %Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term}, runnable_instruction :: {:apply, {module :: atom, :run, arguments :: [term]}}, dependencies :: [instruction_module :: atom]) :: %Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term}

error(message)

Specs

error(message :: String.t) :: no_return

Logs an error using the Logger on the running node which is upgraded.

In addition the same error message is logged on the node which executes the upgrade and is displayed as output of the $APP/bin/$APP upgarde $RELEASE command.

format_in_upgrade_script(format, arguments)

Specs

format_in_upgrade_script(format :: char_list, arguments :: [term]) :: no_return

Formats and prints the message on the node

running the upgrade script which was started by the $APP/bin/$APP upgrade $RELEASE command.

info(message)

Specs

info(message :: String.t) :: no_return

Logs an info message using the Logger on the running node which is upgraded.

In addition the same info message is logged on the node which executes the upgrade and is displayed as output of the $APP/bin/$APP upgarde $RELEASE command.

insert_where()

Specs

insert_where :: 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.

log_in_upgrade_script(type, message)

Specs

log_in_upgrade_script(type :: :error | :warning | :info | :debug, message :: String.t) :: no_return

Logs the message of the given type on the node

which executes the upgrade and displays it as output of the $APP/bin/$APP upgrade $RELEASE command. The message is prefixed with a string derived from the message type.

modify_relup(instructions, config)

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

ranch_connections(ranch_acceptors_sup)

Specs

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

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

ranch_connections_sup(ranch_listener_sup)

Specs

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.

run(otp_application_name)

Specs

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

warn(message)

Specs

warn(message :: String.t) :: no_return

Logs a warning using the Logger on the running node which is upgraded.

In addition the same warning message is logged on the node which executes the upgrade and is displayed as output of the $APP/bin/$APP upgarde $RELEASE command.

websocket_channel_connections(otp_application_name, connections)

Specs

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. Thats 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`

Macros

assume(assertion, error_message)

Assumes that the pattern matches or throws an error with the given error message.

The error message is logged as error to the logfile using the Logger and displayed as error output by the $APP/bin/$APP upgrade $RELEASE task using the $APP/ebin/install_upgrade.escript script. If the pattern matches the variables from the matching are assigned.