handlers

steps that run after a change

A handler is a list of steps that runs once, after a step that notifies it changes something.

Declaring a handler

handlers is a map in a recipe or in a stage. Each key is a handler name, and its value is a list of steps. A handler name has lowercase letters, digits, and _.

Notifying a handler

notify on a step names a handler of the current recipe or stage, or <recipe>.<handler> of another recipe. That recipe must run in the same pipeline, on at least one host where the step runs. On a host where it does not run, winch drops the notification.

# winch.yaml
name: demo
hosts:
  web1.example.com: {}
steps:
  - recipe: nginx
  - file:
      path: /etc/nginx/conf.d/gzip.conf
      content: "gzip on;\n"
    notify: nginx.reload
recipes:
  nginx:
    steps:
      - pkg:
          name: nginx
    handlers:
      reload:
        - service:
            name: nginx
            reloaded: true

# A change of gzip.conf reloads nginx once, at the end of the stage.

When a handler runs

A handler runs at most once per recipe run on a host. A handler of a stage runs at most once per stage run.
A handler runs after the last step of its recipe. When its recipe already ran on that host, it runs at the end of the current stage.
A handler of a stage runs after the last step of the stage and after the recipe handlers at the end of the stage. It runs before the health gate.
Handlers run in the order that the recipe or the stage declares them.

Handler steps

A handler step can have when. It cannot use notify or run a recipe. Only a handler step and winch run can use restarted and reloaded of service.

Pending handlers

When a step notifies a handler, winch marks the handler as pending on the host before the step changes anything. The mark goes when the handler succeeds. When a run stops first, or --stages leaves out the stage of its recipe, the handler stays pending. It runs the next time its recipe or stage runs on that host. The plan shows a handler that will run with "!". For a handler that the run does not reach, the plan shows a note, such as "a pending handler ssh.reload waits until its recipe runs on this host". The note is not a change.