serverless-pre-function

Runs Lua functions before the other plugins of a phase.

Category ServerlessAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin serverless-pre-functionPriority 10000

What it does

serverless-pre-function runs Lua code written on the route itself. Each box under Functions holds a chunk that returns a function, and Phase says in which phase the gateway calls it, access unless you choose another. Within that phase it runs before the route's other plugins.

The phase decides what the code acts on. In rewrite, access and before_proxy it runs before the backend is called, in header_filter and body_filter on the answer, and in log once the answer is sent. How G8 handles a request explains phases and priority.

When to use it

• The backend of the orders API needs a header no plugin writes, for example the moment the gateway received the request.
• A check of your own that answers a request with a status before the route's other plugins see it.
• A small piece of logic tried out on one route before anyone writes a plugin for it.

Not for changing the path, Host or headers the backend receives without code — see proxy-rewrite (Rewrites the request URI, method, host and headers before proxying), code that runs after the other plugins of a phase — see serverless-post-function (Runs Lua functions after the other plugins of a phase) or answering with a made-up response and no backend at all — see mocking (Answers requests with a mocked response instead of an upstream).

Set it up

Tell the backend when the gateway received the request with a few lines of Lua

Fill Functions as in the JSON below and set Phase to rewrite.

serverless-pre-function · as the console saves it

{
  "functions": [
    "return function(conf, ctx)\n  ngx.req.set_header(\"X-Received-At\", ngx.now())\nend"
  ],
  "phase": "rewrite"
}

Things to know

• Functions — Compiled and run when the object is checked: a chunk that fails to compile, fails when called or returns no function is refused, as is a $secret:// or $env:// reference. A refused chunk has still run once on the gateway.
• Functions — A function in the rewrite phase can set a request header, and the backend receives it: the example adds X-Received-At and the request is answered 200 by the backend.
• Phase — In rewrite, access and before_proxy a function that returns a status answers the request itself, with or without a body. In header_filter, body_filter and log what it returns is thrown away.
• AdviceTry a new chunk on a route of its own before you add it to a route your clients call.

Settings

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

Functionsfunctionsarray of stringsRequired

Each box is a Lua chunk returning function(conf, ctx), such as return function(conf, ctx) ngx.log(ngx.INFO, "hi") end. In rewrite, access and before_proxy a function that returns a status answers the request itself, with or without a body. In header_filter, body_filter and log what it returns is thrown away.

at least 1 item · example ["return function(conf, ctx)\n ngx.log(ngx.INFO, \"hello from the gateway\")\nend"]

Phasephasestringdefault access

When the functions run: rewrite, access or before_proxy before the upstream is called, header_filter or body_filter on the answer, log after it is sent.

one of access, before_proxy, body_filter, header_filter, log, rewrite

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