Document updated on Oct 21, 2022
Lua scripting
Scripting with Lua allows you to extend your business logic and make transformations on requests and responses. The Lua module is compatible with the rest of components such as CEL, Martian, or other Go plugins and middlewares.
The introduction of Lua scripts in your Gateway does not require recompiling KrakenD, but unlike Go, Lua scripts are interpreted in real-time. If you are new to Lua, see Lua Documentation.
Configuration
You can add your Lua scripts under the extra_config
at the service level, the endpoint
level or the backend
level. You can choose three different namespaces (explained below):
"modifier/lua-endpoint"
(endpoint and service level)"modifier/lua-proxy"
(endpoint level)"modifier/lua-backend"
(backend level)
The configuration options are:
{
"extra_config": {
"modifier/lua-proxy": {
"sources": [
"file1.lua",
"./relative/path/file2.lua",
"/etc/krakend/absolute/path.lua"
],
"md5": {
"file1.lua": "49ae50f58e35f4821ad4550e1a4d1de0"
},
"pre": "print('Hi from pre!'); my_file1_function()",
"post": "print('Hi from post!'); my_file1_function()",
"live": false,
"allow_open_libs": false,
"skip_next": false
}
}
}
Fields of Lua modifier
allow_open_libs
boolean- As an efficiency point the Lua component does not load the standard libraries by default. If you need to import Lua libraries (e.g, the I/O, String, etc.), then you must set this flag to true.Defaults to
false
live
boolean- For security and efficiency, the Lua script is loaded once into memory and not reloaded even if the file contents change. Set this flag to
true
if you want to modify the Lua script while KrakenD is running and apply the changes live (mostly during development to avoid the snippet being cached).Defaults tofalse
md5
object- The md5sum is an extra security feature to make sure that once you have coded the Lua script, the MD5 of what is loaded into memory matches what you expect and has not been tampered by a malicious 3rd party.Example:
{"file1.lua":"49ae50f58e35f4821ad4550e1a4d1de0"}
post
string- The Lua code that is executed after performing the request. Available when used in the
backend
section. You can write all the Lua code inline (e.g.,print('Hi'); print('there!')
but you can also call functions that live inside one of the files undersources
(e.g.,my_function()
).Example:"local r = response.load(); r:headers('Set-Cookie', 'key1='.. r:data('response'));"
pre
string- The Lua code that is executed before performing the request. Unlike
post
, it’s available in all sections. You can write all the Lua code inline (e.g.,print('Hi'); print('there!')
but you can also call functions that live inside one of the files undersources
(e.g.,my_function()
).Example:"print('Backend response, pre-logic:'); local r = request.load(); print(r:body());"
skip_next
boolean- Available on the
backend
section only. Instead of connecting to next backend in the pipe, returns an empty response and executes thepost
lua function.Defaults tofalse
sources
array- An array with all the Lua files that will be processed. If no path is provided (e.g.,
myfile.lua
) the file loads from the working directory (same place you loaded the configuration, usually/etc/krakend
)
Configuration placement and sequence of execution
When running Lua scripts, you can place them at the proxy
level, or the router
level:
These two places have the following considerations:
- Router (at
endpoint
’sextra_config
or service level): Communication between the end-user and KrakenD. You can inspect and modify the request of the user.- With
"modifier/lua-endpoint"
you can modify the HTTP request context early in the transport layer. However, KrakenD has not converted the request into an internal request just yet. - With
"modifier/lua-proxy"
you can modify the internal KrakenD request before reaching all backends in the endpoint and modify the response AFTER the merge of all backends.
- With
- Proxy (at
backend
’sextra_config
): Communication between KrakenD and your services. For both the request and the response.- With
"modifier/lua-backend"
you can modify the internal KrakenD request before reaching a particular backend and change its response BEFORE is passed for the merge of backends at the endpoint level.
- With
In a request/response execution, this is how the different namespaces for Lua placement work:
Functions for Proxy
You can use the following Lua functions to access and manipulate requests and responses in "modifier/lua-proxy"
and "modifier/lua-backend"
namespaces.
Request functions (request
)
If you have a script that needs access to the request, use the request
object in Lua. The request is set when KrakenD is about to do a call to the backend services.
input_headers
or input_query_strings
accordingly.The request
functions are:
load()
(Static): The constructor to view and manipulate requests. E.g.:local r = request.load()
. Notice that the rest of the functions rely on this one.method()
(Dynamic): Getter that retrieves the method of the request. E.g.:r:method()
could return a stringGET
.method(value)
(Dynamic): Setter that changes the method of the request. E.g.:r:method('POST')
.path()
(Dynamic): Getter that retrieves the path of the request. E.g.:r:path()
could return a string/foo/var
.path(value)
(Dynamic): Setter that changes the path of the request. E.g.:r:path('/foo/var')
. It does not have any effect when you usemodifier/lua-backend
.query()
(Dynamic): Getter that retrieves the query string of the request, URL encoded. E.g.:r:query()
could return a string?foo=var&vaz=42
.query(value)
(Dynamic): Setter that changes the query of the request. E.g.:r:query('?foo=var&vaz=42')
.url()
(Dynamic): Getter that retrieves the full URL string of the request, including the host and path. E.g.:r:url()
could return a stringhttp://domain.com/api/test
. The URL might be empty depending on the step where this information is requested, as the URL is a calculated field just before performing the request to the backend.url(value)
(Dynamic): Setter that changes the URL of the request. E.g.:r:url('http://domain.com/api/test')
. Changing the value before theurl
is calculated will result in KrakenD overwriting its value. Although available, it does not have any effect when you use itmodifier/lua-proxy
.params(param)
(Dynamic): Getter that retrieves the{params}
of the request as defined in the endpoint. E.g.: For an endpoint/users/{user}
the functionr:params('User')
could return a stringalice
. The parameters must have the first letter capitalized.params(param,value)
(Dynamic): Setter that changes the params of the request. E.g.:r:params('User','bob')
. The parameters must have the first letter capitalized.headers(header)
(Dynamic): Getter that retrieves the headers of the request as allowed to pass (byinput_headers
) in the endpoint. E.g.:r:headers('Accept')
could return a string*/*
.headers(header,value)
(Dynamic): Setter that changes the headers of the request. E.g.:r:headers('Accept','*/*')
.body()
(Dynamic): Getter that retrieves the body of the request sent by the user. E.g.:r:body()
could return a string{"foo": "bar"}
.body(value)
(Dynamic): Setter that changes the body of the request. E.g.:r:body('{"foo": "bar"}')
.
Response functions (response
)
Scripts that need to modify a request that KrakenD that just got from the backend service.
load()
(Static): The constructor to view and manipulate responses. E.g.:local r = response.load()
. Notice that the rest of the functions rely on this one.isComplete()
(Dynamic): Getter that returns a boolean if the response from the backend (or a merge of backends) succeeded with a20x
code, and completed successfully before the timeout. E.g.:r:isComplete()
returnstrue
orfalse
.isComplete(bool)
(Dynamic): Setter that allows you to mark a response as completed. It will change the internalX-KrakenD-Complete: true
header. E.g.:r:isComplete(true)
tells KrakenD everything went OK (even not true).statusCode()
(Dynamic): Getter that retrieves the response status code when you useno-op
encoding. You will always get a0
in the other cases. E.g.:r:statusCode()
returns an integer200
.statusCode(integer)
(Dynamic): Setter that allows you to set a new status for the response. E.g.:r:statusCode(301)
.data()
(Dynamic): Getter that returns a Lua table with all the parsed data from the response. It only works if you don’t useno-op
encoding.data(table)
(Dynamic): Setter that lets you assign the whole Lua table with all the parsed data from the response. It will make more sense to do alocal responseData = r:data()
first, and then set individual items withresponseData:set("key", value)
instead. It only works if you don’t useno-op
encoding.headers(header)
(Dynamic): Getter that retrieves one header from the response when you useno-op
encoding. In the rest of the responses, you will always get an empty string''
. E.g.:r:headers('Content-Type')
returns an integerapplication/json
.headers(header,value)
(Dynamic): Setter that allows you to replace or set a new header for the response when you useno-op
encoding. E.g.:r:headers('Content-Type', 'application/json')
.body()
(Dynamic): Getter that retrieves the body of the response when you use encodingno-op
. E.g.:r:body()
could return a string{"foo": "bar"}
.body(value)
(Dynamic): Setter that changes the body of the response when you use encodingno-op
. E.g.:r:body('{"foo": "bar"}')
.
Functions for Router
Use this type when you need to script the router layer, traffic between end-users, and KrakenD with the "modifier/lua-endpoint"
namespace.
Context functions (ctx
)
load()
(Static): The constructor to view and manipulate requests. E.g.:local c = ctx.load()
. Notice that the rest of the functions rely on this one.method()
(Dynamic): Getter that retrieves the method of the request. E.g.:c:method()
could return a stringGET
.method(value)
(Dynamic): Setter that changes the method of the request. E.g.:c:method('POST')
.query(key)
(Dynamic): Getter that retrieves the query string of the request, URL encoded. E.g.:c:query('foo')
could return a stringvar
for?foo=var&vaz=42
.query(key,value)
(Dynamic): Setter that changes the query of the request. E.g.:c:query('foo','var')
.url()
(Dynamic): Getter that retrieves the URL string of the request (path and parameters). E.g.:c:url()
could return a string/api/test?foo=bar
. The URL might be empty depending on the step where this information is requested, as the URL is a calculated field just before performing the request to the backend.url(value)
(Dynamic): Setter that changes the url of the request. E.g.:c:url('/api/test?foo=bar')
. Changing the value before theurl
is calculated will result in KrakenD overwriting its value.params(param)
(Dynamic): Getter that retrieves the{params}
of the request as defined in the endpoint. E.g.: For an endpoint/users/{user}
the functionc:params('User')
could return a stringalice
. The parameters must have the first letter capitalized.params(param,value)
(Dynamic): Setter that changes the params of the request. E.g.:c:params('User','bob')
. The parameters must have the first letter capitalized.headers(header)
(Dynamic): Getter that retrieves the headers of the request as allowed to pass (byinput_headers
) in the endpoint. E.g.:c:headers('Accept')
could return a string*/*
.headers(header,value)
(Dynamic): Setter that changes the headers of the request. E.g.:c:headers('Accept','*/*')
.body()
(Dynamic): Getter that retrieves the body of the request sent by the user. E.g.:c:body()
could return a string{"foo": "bar"}
.body(value)
(Dynamic): Setter that changes the body of the request. E.g.:c:body('{"foo": "bar"}')
.host()
(Dynamic): Getter that retrieves theHost
header of the request sent by the user. E.g.:c:host()
could return a stringapi.domain.com
.host(value)
(Dynamic): Setter that changes the host header of the request. E.g.:c:host('api.domain.com')
.
Lua helpers
Now you know where to put the Lua code according to what you want to do, and how to access and modify the requests and responses. In addition, the following helper functions are brought by KrakenD to extend the possibilities of your scripts without using third parties:
Tables helper (table
)
To work with associative arrays on Lua you have the following functions:
get(key)
(Dynamic): Retrieves the value of a key inside the table. E.g.:local r = response.load(); local responseData = r:data(); responseData:get('key')
set(key,value)
(Dynamic): Adds or replaces a key in the table. E.g.:local r = response.load(); local responseData = r:data(); responseData:set('key',value)
len()
(Dynamic): Returns the length of the whole table so you can iterate over it. E.g.:local r = response.load(); local responseData = r:data(); local length = responseData:len()
del(key)
(Dynamic): Deletes a key from a table. E.g.:local r = response.load(); local responseData = r:data(); responseData:del('key')
An example of Lua script that gets a field source_result
from a table and sets a new key result
accordingly by reading the response text (decorator pattern):
function post_proxy_decorator( resp )
local responseData = resp:data()
local responseContent = responseData:get("source_result")
local message = responseContent:get("message")
local c = string.match(message, "Successfully")
if not not c
then
responseData:set("result", "success")
else
responseData:set("result", "failed")
end
end
Collections helper (list
)
get(key)
(Dynamic): Retrieves the value of a key inside the list. E.g.:local r = response.load(); local responseData = r:data(); local l = responseData:get('collection'); l:get(1)
gets the item at position 1 from the list.set(key,value)
(Dynamic): Adds or replaces a key in the list. E.g.:local r = response.load(); local responseData = r:data(); local l = responseData:get('collection'); l:set(1,value)
sets the value of position1
.len()
(Dynamic): Returns the length of the whole list so you can iterate over it. E.g.:local r = response.load(); local responseData = r:data(); local l = responseData:get('collection'); l:len()
del(key)
(Dynamic): Deletes an offset from a list. E.g.:local r = response.load(); local responseData = r:data(); local l = responseData:get('collection'); l:del(1)
Example of Lua code that iterates the items under the array collection
and also uses sets and deletes tables:
-- A function that receives a response object through response.load()
function post_proxy( resp )
local data = {}
local responseData = resp:data()
local col = responseData:get("collection")
local size = col:len()
-- Sets a new attribute "total" in the response with the number of elements in the array
responseData:set("total", size)
local paths = {}
for i=0,size-1 do
local element = col:get(i)
local t = element:get("path")
table.insert(paths, t)
end
responseData:set("paths", paths)
responseData:del("collection")
end
Making additional requests (http_response
)
The http_response
helper allows you to make an additional HTTP request and access its response. Is is available on:
"modifier/lua-proxy"
(endpoint level)"modifier/lua-backend"
(backend level)
Notice that you cannot use it in modifier/lua-endpoint
.
new(url)
(Static): Constructor. Sets the URL you want to call and makes the request. E.g.:local r = http_response.new('http://api.domain.com/test')
. Notice that the rest of the functions rely on this one. The constructor accepts 1, 3, or 4 arguments, respectively. See examples below.statusCode()
(Dynamic): Getter for the status code of the response. E.g.:r:statusCode()
could return200
headers(header)
(Dynamic): : Getter for a specific header of the response. E.g.:r:headers('Content-Type')
could returnapplication/json
body()
(Dynamic): Getter for the full response body.close()
(Dynamic): Closes the HTTP connection to free resources. Although it will be done automatically later by KrakenD, a better approach is to close the resource as soon as you don’t need it anymore.
local url = 'http://api.domain.com/test'
-- Constructor with 1 parameter
local r = http_response.new(url)
print(r:statusCode())
print(r:headers('Content-Type'))
print(r:body())
r:close()
-- Constructor with 3 parameters
local r = http_response.new(url, "POST", '{"foo":"bar"}')
print(r:statusCode())
print(r:headers('Content-Type'))
print(r:body())
r:close()
-- Constructor with 4 parameters
local r = http_response.new(url, "POST", '{"foo":"bar"}', {["foo"] = "bar", ["123"] = "456"})
print(r:statusCode())
print(r:headers('Content-Type'))
print(r:body())
r:close()
Set custom HTTP status codes (custom_error
)
A generic helper in pre and post-scripts that allows you to set custom HTTP status codes. For instance, when you want to send an immediate response to the client from within a Lua script without further querying the backend, or after evaluating the response of the backend.
It stops the script and the pipe execution.
Example of throwing a generic error (500
status code ) with a message:
custom_error("Something weird happened")
Or even changing the HTTP status code (418 I'm a teapot
)
custom_error("I refuse to make any coffee, I'm a teapot!", 418)
Lua examples in different pipes
The following snippets show how to add Lua code in different sections.
Lua in the service for all endpoints
An example setting a common header in the request to all endpoints.
{
"version": 3,
"extra_config": {
"modifier/lua-endpoint": {
"pre": "print('Lua service!'); local c = ctx.load(); c:headers('X-from-lua', '1234');"
}
}
}
Lua in the endpoint
An example of setting lua scripts in three different stages that modify headers.
{
"endpoint": "/set-a-header",
"extra_config": {
"modifier/lua-endpoint": {
"pre": "print('Modifies the HTTP request'); local c = ctx.load(); c:headers('X-from-lua-endpoint', '1234');"
},
"modifier/lua-proxy": {
"@comment-pre": "Modifies the internal proxy request before the split to all backends",
"pre": "print('Lua proxy pre modifier'); local r = request.load(); r:headers('X-from-lua-proxy', '1234');",
"@comment-post": "Modifies the response after merging all backends",
"post": "print('Lua proxy post modifier'); local r = response.load(); r:headers('X-from-lua-proxy', '1234');",
}
}
}
- The
modifier/lua-endpoint
hits first as it modifies the HTTP request directly. Can’t modify the response (post
). - The
pre
inmodifier/lua-proxy
modifies the internal request before it’s sent to each of the backends you have configured in the endpoint. Backends see an extra header. - The
post
inmodifier/lua-proxy
modifies the response after having merged all the contents from all backends.
Lua in the backend
An example showing how to print the backend response in the console.
{
"extra_config": {
"modifier/lua-backend": {
"pre": "print('Backend response, pre-logic:'); local r = request.load(); print(r:body());"
}
}
}
Another example setting a cookie from Lua:
{
"extra_config": {
"modifier/lua-proxy": {
"post": "local r = response.load(); r:headers('Set-Cookie', 'key1='.. r:data('response'));",
"allow_open_libs": true
}
}
}