Skip to main content

Triggers

MistServer reports certain occurrences as configurable triggers to a URL or executable. Triggers are the preferred way of responding to server events. Each trigger has a name and a payload, and may be blocking or non-blocking as well as stream-specific or global.

Triggers may be handled by a URL or an executable. If the handler contains the string ://, a HTTP(S) URL is assumed. Otherwise, an executable is assumed.

URL Trigger handler​

If handled as an URL, a POST request is sent to the URL with an extra X-Trigger header containing the trigger name and the payload as the POST body.

Executable Trigger handler​

If handled as an executable, the given executable is started with the trigger name as its only argument, and the payload is piped into the executable over standard input.

Responses​

Blocking triggers will wait for a response from the URL (as response body) or executable (standard output), using the response to perform some action. Non-blocking triggers do not wait for a response, and will ignore any response if received later.

A response to a trigger is considered positive if it starts with any of the following: 1, yes, true, cont. It is considered negative in all other cases.

Stream-specific triggers​

Stream-specific triggers can be set to activate for only specific streams, while global triggers always activate, regardless of any related streams.

Enabling triggers​

As mentioned in the API call, triggers are enabled as such:

  "SOME_TRIGGER": [
    ["handler", nonblocking, ["optional", "stream", "list"]],
    //Multiple handlers may be defined
  ]

The "handler" here is the handler URL or executable.

The nonblocking variable is a boolean true or false, where true means non-blocking and false means blocking. Note that non-blocking executable triggers will not have anything connected to standard output, which in the case of bash scripts will mean that they abort as soon as you try to echo anything.

The ["optional", "stream", "list"] is an optional list of streams for which this trigger should activate. If the trigger is global or this variable is left out or empty, it always activates.

Triggers no longer activate if the controller has been shut down cleanly, but keep activating if the controller has been shut down by other means.

A full list of triggers and their properties follows.