> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-serverless.md).
# Serverless plugins
Plugins in this category execute code on the request path: Lua snippets, AWS Lambda invocations, Azure Function calls, Cloudflare Workers. Use them sparingly; they add latency and operational complexity compared to fixed-policy plugins. The catalogue ships 5 Serverless plugins.
{% hint style="info" %}
**In this category:** [`aws-lambda`](#aws-lambda), [`azure-functions`](#azure-functions), [`lua-callout`](#lua-callout), [`openfunction`](#openfunction), [`openwhisk`](#openwhisk)
{% endhint %}
### `aws-lambda`
The `aws-lambda` Plugin is used for integrating Helix with [AWS Lambda](https://aws.amazon.com/lambda/) and [Amazon API Gateway](https://aws.amazon.com/api-gateway/) as a dynamic upstream to proxy all requests for a particular URI to the AWS Cloud.
{% hint style="info" %}
**Priority** `-1899` · **Category** Serverless · **Required** `function_uri`
{% endhint %}
Configuration and details
When enabled, the Plugin terminates the ongoing request to the configured URI and initiates a new request to the AWS Lambda Gateway URI on behalf of the client with configured authorization details, request headers, body and parameters (all three passed from the original request). It returns the response with headers, status code and the body to the client that initiated the request with Helix.
This Plugin supports authorization via AWS API key and AWS IAM secrets. The Plugin implements [AWS Signature Version 4 signing](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) for IAM secrets.
| Name | Type | Required | Default | Valid values | Description |
| ----------------------------- | ------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| function\_uri | string | True | | | AWS API Gateway endpoint which triggers the lambda serverless function. |
| authorization | object | False | | | Authorization credentials to access the cloud function. |
| authorization.apikey | string | False | | | Generated API Key to authorize requests to the AWS Gateway endpoint. |
| authorization.iam | object | False | | | Used for AWS IAM role based authorization performed via AWS v4 request signing. See [IAM authorization schema](#iam-authorization-schema). |
| authorization.iam.accesskey | string | True | | Generated access key ID from AWS IAM console. | |
| authorization.iam.secretkey | string | True | | Generated access key secret from AWS IAM console. | |
| authorization.iam.aws\_region | string | False | "us-east-1" | AWS region where the request is being sent. | |
| authorization.iam.service | string | False | "execute-api" | The service that is receiving the request. For Amazon API gateway APIs, it should be set to `execute-api`. For Lambda function, it should be set to `lambda`. | |
| timeout | integer | False | 3000 | \[100,...] | Proxy request timeout in milliseconds. |
| ssl\_verify | boolean | False | true | true/false | When set to `true` performs SSL verification. |
| keepalive | boolean | False | true | true/false | When set to `true` keeps the connection alive for reuse. |
| keepalive\_pool | integer | False | 5 | \[1,...] | Maximum number of requests that can be sent on this connection before closing it. |
| keepalive\_timeout | integer | False | 60000 | \[1000,...] | Time is ms for connection to remain idle without closing. |
**Sample configuration**
Minimal, proxy to a Lambda-backed API Gateway endpoint (no authorization set):
```json
{
"aws-lambda": {
"function_uri": "https://ekpu4hnc37.execute-api.us-east-1.amazonaws.com/default/my-function"
}
}
```
API key authorization, pass the generated key to the AWS Gateway endpoint:
```json
{
"aws-lambda": {
"function_uri": "https://ekpu4hnc37.execute-api.us-east-1.amazonaws.com/default/my-function",
"authorization": {
"apikey": "my-aws-api-key"
}
}
}
```
IAM authorization, sign requests with AWS Signature Version 4:
```json
{
"aws-lambda": {
"function_uri": "https://ekpu4hnc37.execute-api.us-east-1.amazonaws.com/default/my-function",
"authorization": {
"iam": {
"accesskey": "AKIAIOSFODNN7EXAMPLE",
"secretkey": "my-iam-secret-key",
"aws_region": "us-west-2",
"service": "execute-api"
}
}
}
}
```
Fuller config, IAM authorization with tuning and connection reuse:
```json
{
"aws-lambda": {
"function_uri": "https://ekpu4hnc37.execute-api.us-east-1.amazonaws.com/default/my-function",
"authorization": {
"iam": {
"accesskey": "AKIAIOSFODNN7EXAMPLE",
"secretkey": "my-iam-secret-key",
"aws_region": "us-east-1",
"service": "lambda"
}
},
"timeout": 5000,
"ssl_verify": true,
"keepalive": true,
"keepalive_pool": 10,
"keepalive_timeout": 60000
}
}
```
### `azure-functions`
The `azure-functions` Plugin is used to integrate Helix with [Azure Serverless Function](https://azure.microsoft.com/en-in/services/functions/) as a dynamic upstream to proxy all requests for a particular URI to the Microsoft Azure Cloud.
{% hint style="info" %}
**Priority** `-1900` · **Category** Serverless · **Required** `function_uri`
{% endhint %}
Configuration and details
When enabled, the Plugin terminates the ongoing request to the configured URI and initiates a new request to Azure Functions on behalf of the client with configured authorization details, request headers, body and parameters (all three passed from the original request). It returns back the response with headers, status code and the body to the client that initiated the request with Helix.
| Name | Type | Required | Default | Valid values | Description |
| ---------------------- | ------- | -------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| function\_uri | string | True | | | Azure FunctionS endpoint which triggers the serverless function. For example, `http://test-helix.azurewebsites.net/api/HttpTrigger`. |
| authorization | object | False | | | Authorization credentials to access Azure Functions. |
| authorization.apikey | string | False | | | Generated API key to authorize requests. |
| authorization.clientid | string | False | | | Azure AD client ID to authorize requests. |
| timeout | integer | False | 3000 | \[100,...] | Proxy request timeout in milliseconds. |
| ssl\_verify | boolean | False | true | true/false | When set to `true` performs SSL verification. |
| keepalive | boolean | False | true | true/false | When set to `true` keeps the connection alive for reuse. |
| keepalive\_pool | integer | False | 5 | \[1,...] | Maximum number of requests that can be sent on this connection before closing it. |
| keepalive\_timeout | integer | False | 60000 | \[1000,...] | Time is ms for connection to remain idle without closing. |
**Sample configuration**
Minimal, proxy to an Azure Functions HTTP trigger:
```json
{
"azure-functions": {
"function_uri": "http://test-helix.azurewebsites.net/api/HttpTrigger"
}
}
```
API key authorization:
```json
{
"azure-functions": {
"function_uri": "http://test-helix.azurewebsites.net/api/HttpTrigger",
"authorization": {
"apikey": "my-azure-function-key"
}
}
}
```
Azure AD client ID authorization:
```json
{
"azure-functions": {
"function_uri": "http://test-helix.azurewebsites.net/api/HttpTrigger",
"authorization": {
"clientid": "00000000-0000-0000-0000-000000000000"
}
}
}
```
Fuller config, API key with tuning and connection reuse:
```json
{
"azure-functions": {
"function_uri": "http://test-helix.azurewebsites.net/api/HttpTrigger",
"authorization": {
"apikey": "my-azure-function-key"
},
"timeout": 5000,
"ssl_verify": true,
"keepalive": true,
"keepalive_pool": 10,
"keepalive_timeout": 60000
}
}
```
### `lua-callout`
The `lua-callout` Plugin executes **user-provided Lua code** on a route or an API. Each entry in `functions` is a string that returns a **function**, which the gateway runs as `func(conf, ctx)` in the configured **phase**. Functions run in order; if any function returns a non-nil **HTTP status code** and/or **body**, the pipeline **short-circuits** and that response is returned to the client.
{% hint style="info" %}
**Priority** `0` · **Category** Serverless · **Required** `functions` · **Enterprise only**
{% endhint %}
{% hint style="danger" %}
**Caution:** This plugin executes Lua code stored in configuration. Restrict who can create or change routes that use `lua-callout`, and audit its use.
{% endhint %}
Configuration and details
Supported phases: `rewrite`, `access`, `header_filter`, `body_filter`, `log`, `before_proxy`. Only the phase named in `phase` runs your functions.
Your functions run as ordinary Lua: the standard library and `require()` are available, and only the specific capabilities listed in **What your functions cannot do** are blocked. Through the scoped `ctx` facade your code reads and mutates the current request and response, and it also reads and writes the gateway **request context** directly (`ctx.var`, `ctx.helix`, and any other `ctx` field; see **Scoped context: gateway fields** below).
**What your functions cannot do**
The following are blocked (rejected when the route or API is saved):
* `load`, `loadstring`, `loadfile`, `dofile`, `getfenv`, `setfenv`, `getmetatable`, `collectgarbage`
* `package`, `debug`, `jit`
* `io`, `ffi`, `posix`, `syscall`, `lfs`, `luv`, `uv`
* `socket`, `cqueues`, `ljsocket`, and the network and service client modules (HTTP, Redis, MySQL, Memcached, Kafka, DNS, WebSocket)
* `os.execute`, `os.getenv`, `os.remove`, `os.rename`, `os.exit`, `os.tmpname`, `os.setlocale` (only `os.time`, `os.date`, `os.clock`, `os.difftime` remain)
* the gateway runtime and its internal modules
`require()` of any of these is rejected. If unsupported logic still runs at runtime (for example a mistyped global), the plugin ignores it, logs internally, and continues. Clients never receive an error for unsupported code.
**What your functions can use**
Anything not listed above: the full standard library (`string`, `table`, `math`, `coroutine`, `bit`, the usual globals, and the read-only `os.time` / `os.date` / `os.clock` / `os.difftime`) and `require()` of any other module. A `callout.*` shortcut is also injected: `callout.json` and `callout.cjson` for JSON, `callout.random` for random bytes.
**Configuration**
| Name | Type | Required | Default | Valid values | Description |
| -------------- | -------------- | -------- | ------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| functions | array\[string] | True | | at least 1 entry | Lua source strings. Each must compile and, when executed, return a function with signature `function(conf, ctx)`. Return `code, body` to stop processing and respond with that status and body (`body` may be a table for JSON). Return nothing to continue. |
| phase | string | False | `access` | \["rewrite","access","header\_filter","body\_filter","log","before\_proxy"] | Phase in which to run the Lua functions. |
| error\_policy | string | False | `open` | \["open","close"] | `open`: if a step raises inside supported user logic, log the error and continue to the next function. `close`: respond with **503** and a JSON body (see plugin metadata below). Runtime details are logged only, never sent to the client. |
| ctx\_namespace | string | False | `lua_callout` | | Reserved for future namespacing and the plugin's own failure-state fields. User Lua reads and writes the gateway context directly (see **Scoped context: gateway fields** below). |
At configuration time each string is validated: forbidden patterns are rejected, the code must compile, and it must return a function when called.
**Plugin metadata**
| Metadata field | Type | Description |
| ---------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_meta.error_response` | string or object | When `error_policy` is `close` and the plugin returns **503**, the response body is this value if set. An object is JSON-encoded; a string is sent as the raw body. If unset, the body defaults to `{"error_msg":"lua-callout error"}`. |
:::note
Do **not** put `error_response` at the top level of the plugin object; the schema rejects it (`additionalProperties: false`). Use `_meta.error_response` only.
:::
**Scoped context: `ctx.request`** (available in `rewrite`, `access`, `before_proxy`)
| Field / method | Type | Description |
| ------------------------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `ctx.request.method` | string | HTTP method (read-only). |
| `ctx.request.uri` | string | Request URI path (read-only). |
| `ctx.request.query` | table | URI query arguments (read-only view). |
| `ctx.request.headers` | table | Incoming request headers, lowercase keys (read-only view). |
| `ctx.request.body` | string | Request body. |
| `ctx.request.form` | table | Parsed `application/x-www-form-urlencoded` body fields. |
| `ctx.request.scheme` | string | `http` or `https` (read-only). |
| `ctx.request.host` | string | Host header / server name (read-only). |
| `ctx.request.set_header(name, value)` | method | Set a request header before upstream. |
| `ctx.request.set_query(name, value)` | method | Set a URI query argument before upstream. |
| `ctx.request.set_body(string)` | method | Replace the request body before upstream. |
| `ctx.request.set_uri(path)` | method | Replace the request path sent upstream. |
| `ctx.request.set_method(name)` | method | Change the HTTP method sent upstream, for example `"POST"`. An unrecognised method is ignored. |
Direct assignment such as `ctx.request.headers["x"] = "y"` updates the read view only. Use `set_header`, `set_query`, and `set_body` to mutate the real request.
**Scoped context: `ctx.response`** (available in `header_filter`, `body_filter`, `log`)
| Field / method | Type | Description |
| -------------------------------------- | ------ | --------------------------------------------------------- |
| `ctx.response.status` | number | Response status code (read-only view). |
| `ctx.response.headers` | table | Response headers (read-only view). |
| `ctx.response.body` | string | Buffered response body in `body_filter`. |
| `ctx.response.set_header(name, value)` | method | Set a response header (`header_filter`, `body_filter`). |
| `ctx.response.set_status(code)` | method | Set the response status (`header_filter`, `body_filter`). |
| `ctx.response.set_body(string)` | method | Replace the response body (`body_filter` only). |
The `log` phase is read-only for the response (no `set_*` methods). Mutations apply when the function returns without short-circuiting; `return code, body` skips pending mutations for that step.
**Scoped context: gateway fields** (available in every phase)
Any `ctx` key other than `request` and `response` reads and writes the live gateway **request context** by reference. Use it to read what other plugins have put on the request and to pass data along the chain:
| Access | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `ctx.var.` | Read or write a gateway variable. |
| `ctx.helix.<...>` | Read (and write) values other Helix plugins place on the request, for example the resolved product or consumer. |
| `ctx.` | Create or replace your own fields, for example `ctx.my_state = { checked = true }`. |
Unlike the `ctx.request` and `ctx.response` mutators, these writes are **not** staged: they take effect on the request immediately and persist for the rest of its lifecycle, so a value set in one function (or phase) is visible to later functions and phases handling the same request. This is the supported way to pass data between functions.
{% hint style="warning" %}
Writing gateway variables can change routing and downstream behaviour. Treat `ctx.var` writes with the same care as the request mutators, and prefer your own `ctx.` for scratch data.
{% endhint %}
**Examples**
Access phase, set a request header before upstream:
```json
{
"lua-callout": {
"phase": "access",
"functions": [
"return function(conf, ctx)\n ctx.request.set_header(\"x-lua-callout\", \"test\")\nend"
]
}
}
```
Header filter phase, set a response header:
```json
{
"lua-callout": {
"phase": "header_filter",
"functions": [
"return function(conf, ctx)\n ctx.response.set_header(\"x-lua-callout\", \"test\")\nend"
]
}
}
```
Access phase, require a header (requests without `X-Allowed: yes` are rejected with 403):
```json
{
"lua-callout": {
"phase": "access",
"functions": [
"return function(conf, ctx)\n local h = ctx.request.headers[\"x-allowed\"]\n if h ~= \"yes\" then\n return 403, { message = \"forbidden\" }\n end\nend"
]
}
}
```
Access phase, read a form field from an `application/x-www-form-urlencoded` body:
```json
{
"lua-callout": {
"phase": "access",
"functions": [
"return function(conf, ctx)\n local name = ctx.request.form.name\n if not name then\n return 400, { error_msg = \"name not found\" }\n end\n return 200, { name = name }\nend"
]
}
}
```
`error_policy: close` with a fixed client-facing error body:
```json
{
"lua-callout": {
"phase": "access",
"error_policy": "close",
"_meta": {
"error_response": { "error_msg": "step failed" }
},
"functions": [
"return function(conf, ctx) error(\"internal\") end"
]
}
}
```
If you omit `_meta.error_response`, the default body is `{"error_msg":"lua-callout error"}`.
Multiple functions run in array order; the first that returns `code` or `body` wins and later functions are not run for that request:
```json
{
"lua-callout": {
"phase": "access",
"functions": [
"return function(c, x) end",
"return function(c, x)\n return 503, { error = \"maintenance\" }\nend"
]
}
}
```
Access phase, rewrite the path and method sent upstream:
```json
{
"lua-callout": {
"phase": "access",
"functions": [
"return function(conf, ctx)\n ctx.request.set_uri(\"/v2/orders\")\n ctx.request.set_method(\"POST\")\nend"
]
}
}
```
Pass data between functions on the same request through a `ctx` field (the first function records state, the second reads it):
```json
{
"lua-callout": {
"phase": "access",
"functions": [
"return function(conf, ctx)\n ctx.my_state = { checked = true }\nend",
"return function(conf, ctx)\n if ctx.my_state and ctx.my_state.checked then\n ctx.request.set_header(\"x-checked\", \"yes\")\n end\nend"
]
}
}
```
### `openfunction`
The `openfunction` Plugin is used to integrate Helix with [CNCF OpenFunction](https://openfunction.dev/) serverless platform.
{% hint style="info" %}
**Priority** `-1902` · **Category** Serverless · **Required** `function_uri`
{% endhint %}
Configuration and details
This Plugin can be configured on a Route and requests will be sent to the configured OpenFunction API endpoint as the upstream.
| Name | Type | Required | Default | Valid values | Description |
| ---------------------------- | ------- | -------- | -------- | -------------- | --------------------------------------------------------------------------------- |
| function\_uri | string | True | | | function uri. For example, `https://localhost:30858/default/function-sample`. |
| ssl\_verify | boolean | False | true | | When set to `true` verifies the SSL certificate. |
| authorization | object | False | | | Authorization credentials to access functions of OpenFunction. |
| authorization.service\_token | string | False | | | The token format is 'xx:xx' which supports basic auth for function entry points. |
| timeout | integer | False | 3000 ms | \[100, ...] ms | OpenFunction action and HTTP call timeout in ms. |
| keepalive | boolean | False | true | | When set to `true` keeps the connection alive for reuse. |
| keepalive\_timeout | integer | False | 60000 ms | \[1000,...] ms | Time is ms for connection to remain idle without closing. |
| keepalive\_pool | integer | False | 5 | \[1,...] | Maximum number of requests that can be sent on this connection before closing it. |
**Sample configuration**
Minimal, proxy to an OpenFunction endpoint:
```json
{
"openfunction": {
"function_uri": "https://localhost:30858/default/function-sample"
}
}
```
With basic auth service token for the function entry point:
```json
{
"openfunction": {
"function_uri": "https://localhost:30858/default/function-sample",
"authorization": {
"service_token": "user:my-service-token"
}
}
}
```
Fuller config, service token with tuning and connection reuse:
```json
{
"openfunction": {
"function_uri": "https://localhost:30858/default/function-sample",
"authorization": {
"service_token": "user:my-service-token"
},
"timeout": 5000,
"ssl_verify": true,
"keepalive": true,
"keepalive_pool": 10,
"keepalive_timeout": 60000
}
}
```
### `openwhisk`
The `openwhisk` Plugin is used to integrate Helix with Apache OpenWhisk serverless platform.
{% hint style="info" %}
**Priority** `-1901` · **Category** Serverless · **Required** `api_host`, `service_token`, `namespace`, `action`
{% endhint %}
Configuration and details
This Plugin can be configured on a Route and requests will be send to the configured OpenWhisk API endpoint as the upstream.
| Name | Type | Required | Default | Valid values | Description |
| ------------------ | ------- | -------- | ------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
| api\_host | string | True | | | OpenWhisk API host address. For example, `https://localhost:3233`. |
| ssl\_verify | boolean | False | true | | When set to `true` verifies the SSL certificate. |
| service\_token | string | True | | | OpenWhisk service token. The format is `xxx:xxx` and it is passed through basic auth when calling the API. |
| namespace | string | True | | | OpenWhisk namespace. For example `guest`. |
| action | string | True | | | OpenWhisk action. For example `hello`. |
| result | boolean | False | true | | When set to `true` gets the action metadata (executes the function and gets response). |
| timeout | integer | False | 60000ms | \[1, 60000]ms | OpenWhisk action and HTTP call timeout in ms. |
| keepalive | boolean | False | true | | When set to `true` keeps the connection alive for reuse. |
| keepalive\_timeout | integer | False | 60000ms | \[1000,...]ms | Time is ms for connection to remain idle without closing. |
| keepalive\_pool | integer | False | 5 | \[1,...] | Maximum number of requests that can be sent on this connection before closing it. |
**Sample configuration**
Minimal, invoke an OpenWhisk action with all required fields:
```json
{
"openwhisk": {
"api_host": "https://localhost:3233",
"service_token": "23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP",
"namespace": "guest",
"action": "hello"
}
}
```
Return only the action result without metadata:
```json
{
"openwhisk": {
"api_host": "https://localhost:3233",
"service_token": "23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP",
"namespace": "guest",
"action": "hello",
"result": false
}
}
```
Fuller config, with timeout tuning and connection reuse:
```json
{
"openwhisk": {
"api_host": "https://localhost:3233",
"service_token": "23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP",
"namespace": "guest",
"action": "hello",
"result": true,
"timeout": 3000,
"ssl_verify": true,
"keepalive": true,
"keepalive_pool": 10,
"keepalive_timeout": 60000
}
}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-serverless.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.