edeliver_fork

v1.4.6

edeliver_fork

edeliver_fork v1.4.6 Edeliver.Relup.RunnableInstruction behaviour

This module can be used to provide custom instructions executed during the upgrade.

They can be used in implementations of the Edeliver.Relup.Modification behaviours. A runnable instruction must implement a Edeliver.Relup.RunnableInstruction.run/1 function which will be executed during the upgrade on the nodes.

Example:

defmodule Acme.Relup.PingNodeInstruction do
  use Edeliver.Relup.RunnableInstruction

  def modify_relup(instructions = %Instructions{up_instructions: up_instructions}, _config = %{}) do
    node_name = :"node@host"
    %{instructions|
      up_instructions:   [call_this([node_name]) | instructions.up_instructions],
      down_instructions: [call_this([node_name]) | instructions.down_instructions]
    }
  end

  # executed during hot code upgrade from relup file
  def run(_options = [node_name]) do
    :net_adm.ping(node_name)
  end

  # actually implemented already in this module
  def call_this(arguments) do
    # creates a relup instruction to call `run/1` of this module
    {:apply, {__MODULE__, :run, arguments}}
  end

end

# using the instruction
defmodule Acme.Relup.Modification do
  use Edeliver.Relup.Modification

  def modify_relup(instructions = %Instructions{}, config = %{}) do
    instructions |> Edeliver.Relup.DefaultModification.modify_relup(config) # use default modifications
                 |> Acme.Relup.PingNodeInstruction.modify_relup(config) # apply also custom instructions
  end
end

Link to this section Summary

Functions

assume(assertion, error_message)

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

debug(message)

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

ensure_dependencies_loaded_before_instruction_for_upgrade(instructions, call_this_instruction, dependencies)

Ensures that all Edeliver.Relup.RunnableInstruction modules used / referenced by this instruction and returned by the Edeliver.Relup.RunnableInstruction.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)

Ensures that all Edeliver.Relup.RunnableInstruction modules used / referenced by this instruction and returned by the Edeliver.Relup.RunnableInstruction.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

log_in_upgrade_script(type, message)

Logs the message of the given type on the node

warn(message)

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

Callbacks

arguments(instructions, config)

Returns the arguments which will be passed the Edeliver.Relup.RunnableInstruction.run/1 function during the upgrade

dependencies()

Returns a list of module names which implement the behaviour Edeliver.Relup.RunnableInstruction

insert_where()

Returns a function which inserts the relup instruction

run(options)

The function to run during hot code upgrade on nodes

Link to this section Functions

Link to this macro assume(assertion, error_message) (macro)

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.

Link to this function debug(message) 
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.

Link to this function ensure_dependencies_loaded_before_instruction_for_upgrade(instructions, call_this_instruction, dependencies) 
ensure_dependencies_loaded_before_instruction_for_upgrade(
  instructions :: Edeliver.Relup.Instructions.t(),
  runnable_instruction ::
    {:apply, {module :: atom(), :run, arguments :: [term()]}},
  dependencies :: [instruction_module :: atom()]
) :: Edeliver.Relup.Instructions.t()

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

Link to this function ensure_dependencies_unloaded_after_instruction_for_downgrade(instructions, call_this_instruction, dependencies) 
ensure_dependencies_unloaded_after_instruction_for_downgrade(
  instructions :: Edeliver.Relup.Instructions.t(),
  runnable_instruction ::
    {:apply, {module :: atom(), :run, arguments :: [term()]}},
  dependencies :: [instruction_module :: atom()]
) :: Edeliver.Relup.Instructions.t()

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

Link to this function error(message) 
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.

Link to this function format_in_upgrade_script(format, arguments) 
format_in_upgrade_script(format :: charlist(), 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.

Link to this function info(message) 
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.

Link to this function log_in_upgrade_script(type, message) 
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.

Link to this function warn(message) 
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.

Link to this section Callbacks

Link to this callback arguments(instructions, config) 
arguments(
  instructions :: %Edeliver.Relup.Instructions{
    changed_modules: term(),
    down_instructions: term(),
    down_version: term(),
    up_instructions: term(),
    up_version: term()
  },
  config :: Edeliver.Relup.Config.t()
) :: [term()]

Returns the arguments which will be passed the Edeliver.Relup.RunnableInstruction.run/1 function during the upgrade.

Default is an empty list.

Link to this callback dependencies() 
dependencies() :: [instruction_module :: atom()]

Returns a list of module names which implement the behaviour Edeliver.Relup.RunnableInstruction

and are used / referenced by this runnable instruction. These modules must be loaded before this instruction is executed for upgrades and unloaded after this instruction for downgrades. Default is an empty list.

Link to this callback insert_where() 
insert_where() ::
  (%Edeliver.Relup.Instructions{
     changed_modules: term(),
     down_instructions: term(),
     down_version: term(),
     up_instructions: term(),
     up_version: term()
   },
   Edeliver.Relup.Instruction.instruction() ->
     %Edeliver.Relup.Instructions{
       changed_modules: term(),
       down_instructions: term(),
       down_version: term(),
       up_instructions: term(),
       up_version: term()
     })

Returns a function which inserts the relup instruction

that calls the Edeliver.Relup.RunnableInstruction.run/1 fuction of this module. Default is inserting it at the end of the instructions

Link to this callback run(options) 
run(options :: [term()]) :: :ok

The function to run during hot code upgrade on nodes.

If it throws an error before the point_of_no_return the upgrade is aborted. If it throws an error and was executed after that point, the release is restarted