workflow

Runs different plugins for different matched requests.

Category TrafficAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin workflowPriority 1006

What it does

workflow holds a list of Rules on a route. Each rule pairs Conditions on the request with an action under Actions. return answers the request with a status of your choice, and limit-count and limit-conn limit it with those plugins' own settings.

The rules are read from the top, and only the first one whose conditions pass acts on a request. A condition on the caller's consumer group needs an authentication plugin on the same route, key-auth for example, which names the consumer first.

How a rule is chosen

Each request is held against the rules in the order they are listed.

• The first rule whose Conditions pass takes the request, and the rules below it are never read.
• A rule with no conditions at all takes every request that reaches it.
• The rule that takes the request runs its action, and only the first pair under Actions is ever run.
• Conditions are read like a route's conditions.

When to use it

• Customers on a blocked plan are refused with 403, while customers on the trial plan get 100 requests a minute, each plan being a consumer group.
• One path of the orders API closed with a status of your choice for some callers, without a route of its own.
• A limit on concurrent connections that applies only to the requests a condition picks out, with limit-conn.

Not for refusing or delaying requests on purpose to see how clients cope — see fault-injection (Injects delays or fixed responses for testing) or one limit on every request of a route — see limit-count (Limits the number of requests in a time window, per key).

Set it up

Refuse requests from a blocked plan and rate-limit the trial plan

Plans are consumer groups; needs an authentication plugin on the same route, which is what tells the gateway which consumer, and so which group, is calling.

Fill Rules as in the JSON below.

workflow · as the console saves it

{
  "rules": [
    {
      "case": [
        [
          "consumer_group_id",
          "==",
          "blocked"
        ]
      ],
      "actions": [
        [
          "return",
          {
            "code": 403
          }
        ]
      ]
    },
    {
      "case": [
        [
          "consumer_group_id",
          "==",
          "trial"
        ]
      ],
      "actions": [
        [
          "limit-count",
          {
            "count": 100,
            "time_window": 60,
            "key": "consumer_name",
            "rejected_code": 429
          }
        ]
      ]
    }
  ]
}

Things to know

• Rules — A condition whose operator is unknown is stored without a word and then passes every request, so the rule's action runs on all of them. A pattern that does not compile is stored too, but then matches nothing.
• Conditions — With key-auth on the same route, a condition on consumer_group_id reads the group of the consumer whose key the request carries: a key of a consumer in blocked is answered 403.
• Actions — With limit-count, the rule counts like that plugin: a key of a consumer in trial is answered 200 carrying X-Ratelimit-Limit with 100.
• Actions — The action is return, limit-count or limit-conn. Any other name is refused when you save.
• Actions — A return without a status code is refused when you save.
• Actions — A rule without an action is refused when you save.
• Rules — A request that no rule takes goes on as if the plugin were absent: a consumer in neither group reaches the backend, which receives its name in X-Consumer-Username.
• AdvicePut a rule with no conditions last, and give each plan a consumer group of its own, so that one condition on consumer_group_id covers every customer of the plan.

Settings

The fields as the console shows them, section by section.

Rulesrulesarray of objectsRequired

The first rule whose conditions pass takes the request and the rules below it are never read.

Each item:

Conditionsrules[].casearray

Read like a route's conditions. A rule with no conditions at all takes every request.

at least 1 item · conditions on request variables: see Conditions on request variables

Actionsrules[].actionsarrayRequired

One pair of a name and its settings, such as ["return", {"code": 403}]; limit-count and limit-conn take their own plugins' settings. Only the first pair of a rule is ever run.

exactly 1 item; each exactly 2 items · example [["return",{"code":403}]]

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.