Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.2.x (latest)
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Older Enterprise versions (2.1-2.5)
  • Older OSS versions (2.1-2.5)
  • Archive (pre-2.1)
    • Overview of Kong Gateway
      • Version Support Policy
      • Supported Installation Options
      • Supported Linux Distributions
    • Stability
    • Release Notes
      • Services
        • Overview
        • Configure Routes with Expressions
      • Upstreams
      • Plugins
      • Routing Traffic
      • Load Balancing
      • Health Checks and Circuit Breakers
      • Kong Performance Testing
    • Glossary
    • Get Kong
    • Services and Routes
    • Rate Limiting
    • Proxy Caching
    • Key Authentication
    • Load-Balancing
      • Overview
        • Overview
        • Deploy Kong Gateway in Hybrid mode
      • DB-less Deployment
      • Traditional
      • Overview
        • Helm
        • OpenShift with Helm
        • kubectl apply
        • Kubernetes Deployment Options
        • Using docker run
        • Build your own Docker images
        • Amazon Linux
        • Debian
        • Red Hat
        • Ubuntu
      • Running Kong as a non-root user
      • Securing the Admin API
      • Using systemd
      • Start Kong Gateway Securely
      • Programatically Creating Admins
      • Enabling RBAC
      • Overview
      • Download your License
      • Deploy Enterprise License
      • Using the License API
      • Monitor Licenses Usage
      • Default Ports
      • DNS Considerations
      • Network and Firewall
      • CP/DP Communication through a Forward Proxy
    • Kong Configuration File
    • Environment Variables
    • Serving a Website and APIs from Kong
      • Overview
      • Prometheus
      • StatsD
      • Datadog
      • Overview
      • Writing a Custom Trace Exporter
      • Tracing API Reference
    • Resource Sizing Guidelines
    • Security Update Process
    • Blue-Green Deployments
    • Canary Deployments
    • Clustering Reference
      • Log Reference
      • Dynamic log level updates
      • Customize Gateway Logs
      • Upgrade Kong Gateway 3.1.x
      • Migrate from OSS to Enterprise
    • Overview
      • Overview
      • Metrics
      • Analytics with InfluxDB
      • Analytics with Prometheus
      • Estimate Analytics Storage in PostgreSQL
      • Overview
      • Getting Started
      • Advanced Usage
        • Overview
        • Environment Variables
        • AWS Secrets Manager
        • Google Secrets Manager
        • Hashicorp Vault
        • Securing the Database with AWS Secrets Manager
      • Reference Format
      • Overview
      • Get Started with Dynamic Plugin Ordering
      • Overview
      • Enable the Dev Portal
      • Publish an OpenAPI Spec
      • Structure and File Types
      • Themes Files
      • Working with Templates
      • Using the Editor
        • Basic Auth
        • Key Auth
        • OIDC
        • Sessions
        • Adding Custom Registration Fields
        • Manage Developers
        • Developer Roles and Content Permissions
        • Authorization Provider Strategy
        • Enable Application Registration
        • Enable Key Authentication for Application Registration
          • External OAuth2 Support
          • Set up Okta and Kong for External Oauth
          • Set up Azure AD and Kong for External Authentication
        • Manage Applications
        • Theme Editing
        • Migrating Templates Between Workspaces
        • Markdown Rendering Module
        • Customizing Portal Emails
        • Adding and Using JavaScript Assets
        • Single Page App in Dev Portal
        • Alternate OpenAPI Renderer
      • SMTP
      • Workspaces
      • Helpers CLI
      • Portal API Documentation
    • Audit Logging
    • Keyring and Data Encryption
    • Workspaces
    • Consumer Groups
    • Event Hooks
    • FIPS 140-2
    • Overview
    • Enable Kong Manager
      • Services and Routes
      • Rate Limiting
      • Proxy Caching
      • Authentication with Consumers
      • Load Balancing
      • Overview
      • Create a Super Admin
      • Workspaces and Teams
      • Reset Passwords and RBAC Tokens
      • Basic Auth
        • Configure LDAP
        • LDAP Service Directory Mapping
        • Configure OIDC
        • OIDC Authenticated Group Mapping
      • Sessions
        • Overview
        • Enable RBAC
        • Add a Role and Permissions
        • Create a User
        • Create an Admin
    • Networking Configuration
    • Workspaces
    • Create Consumer Groups
    • Sending Email
    • Overview
    • File Structure
    • Implementing Custom Logic
    • Plugin Configuration
    • Accessing the Data Store
    • Storing Custom Entities
    • Caching Custom Entities
    • Extending the Admin API
    • Writing Tests
    • (un)Installing your Plugin
      • Overview
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.jwe
      • kong.log
      • kong.nginx
      • kong.node
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.tracing
      • kong.vault
      • kong.websocket.client
      • kong.websocket.upstream
      • Go
      • Javascript
      • Python
      • Running Plugins in Containers
      • External Plugin Performance
    • Overview
        • Overview
        • OpenID Connect with Curity
        • OpenID Connect with Azure AD
        • OpenID Connect with Google
        • OpenID Connect with Okta
        • OpenID Connect with Auth0
        • OpenID Connect with Cognito
      • Authentication Reference
      • Allow Multiple Authentication Plugins
    • Rate Limiting Plugin
      • Add a Body Value
    • GraphQL
      • gRPC Plugins
      • Configure a gRPC service
    • Overview
    • Information Routes
    • Health Routes
    • Tags
    • Debug Routes
    • Services
    • Routes
    • Consumers
    • Plugins
    • Certificates
    • CA Certificates
    • SNIs
    • Upstreams
    • Targets
    • Vaults
    • Keys
    • Licenses
    • Workspaces
    • RBAC
    • Admins
    • Developers
    • Consumer Groups
    • Event Hooks
    • Keyring and Data Encryption
    • Audit Logs
    • kong.conf
    • Injecting Nginx Directives
    • CLI
    • File Permissions Reference
    • Key Management
    • Performance Testing Framework
    • Router Expressions Language
    • FAQ

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • kong.request.get_scheme()
  • kong.request.get_host()
  • kong.request.get_port()
  • kong.request.get_forwarded_scheme()
  • kong.request.get_forwarded_host()
  • kong.request.get_forwarded_port()
  • kong.request.get_forwarded_path()
  • kong.request.get_forwarded_prefix()
  • kong.request.get_http_version()
  • kong.request.get_method()
  • kong.request.get_path()
  • kong.request.get_raw_path()
  • kong.request.get_path_with_query()
  • kong.request.get_raw_query()
  • kong.request.get_query_arg()
  • kong.request.get_query([max_args])
  • kong.request.get_header(name)
  • kong.request.get_headers([max_headers])
  • kong.request.get_raw_body()
  • kong.request.get_body([mimetype[, max_args]])
  • kong.request.get_start_time()
Kong Gateway
3.1.x
  • Home
  • Kong Gateway
  • Plugin Development
  • PDK
  • kong.request
You are browsing documentation for an outdated version. See the latest documentation here.

kong.request

Client request module.

This module provides a set of functions to retrieve information about the incoming requests made by clients.

kong.request.get_scheme()

Returns the scheme component of the request’s URL. The returned value is normalized to lowercase form.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • string: A string like "http" or "https".

Usage

-- Given a request to https://example.com:1234/v1/movies

kong.request.get_scheme() -- "https"

kong.request.get_host()

Returns the host component of the request’s URL, or the value of the “Host” header. The returned value is normalized to lowercase form.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • string: The hostname.

Usage

-- Given a request to https://example.com:1234/v1/movies

kong.request.get_host() -- "example.com"

kong.request.get_port()

Returns the port component of the request’s URL. The value is returned as a Lua number.

Phases

  • certificate, rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • number: The port.

Usage

-- Given a request to https://example.com:1234/v1/movies

kong.request.get_port() -- 1234

kong.request.get_forwarded_scheme()

Returns the scheme component of the request’s URL, but also considers X-Forwarded-Proto if it comes from a trusted source. The returned value is normalized to lowercase.

Whether this function considers X-Forwarded-Proto or not depends on several Kong configuration parameters:

  • trusted_ips
  • real_ip_header
  • real_ip_recursive

Note: Kong does not offer support for the Forwarded HTTP Extension (RFC 7239) since it is not supported by ngx_http_realip_module.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • string: The forwarded scheme.

Usage

kong.request.get_forwarded_scheme() -- "https"

kong.request.get_forwarded_host()

Returns the host component of the request’s URL or the value of the “host” header. Unlike kong.request.get_host(), this function also considers X-Forwarded-Host if it comes from a trusted source. The returned value is normalized to lowercase.

Whether this function considers X-Forwarded-Host or not depends on several Kong configuration parameters:

  • trusted_ips
  • real_ip_header
  • real_ip_recursive

Note: Kong does not offer support for the Forwarded HTTP Extension (RFC 7239) since it is not supported by ngx_http_realip_module.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • string: The forwarded host.

Usage

kong.request.get_forwarded_host() -- "example.com"

kong.request.get_forwarded_port()

Returns the port component of the request’s URL, but also considers X-Forwarded-Host if it comes from a trusted source. The value is returned as a Lua number.

Whether this function considers X-Forwarded-Proto or not depends on several Kong configuration parameters:

  • trusted_ips
  • real_ip_header
  • real_ip_recursive

Note: Kong does not offer support for the Forwarded HTTP Extension (RFC 7239) since it is not supported by ngx_http_realip_module.

When running Kong behind the L4 port mapping (or forwarding), you can also configure:

  • port_maps

The port_maps configuration parameter enables this function to return the port to which the port Kong is listening to is mapped to (in case they differ).

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • number: The forwarded port.

Usage

kong.request.get_forwarded_port() -- 1234

kong.request.get_forwarded_path()

Returns the path component of the request’s URL, but also considers X-Forwarded-Path if it comes from a trusted source. The value is returned as a Lua string.

Whether this function considers X-Forwarded-Path or not depends on several Kong configuration parameters:

  • trusted_ips
  • real_ip_header
  • real_ip_recursive

Note: Kong does not do any normalization on the request path.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • string: The forwarded path.

Usage

kong.request.get_forwarded_path() -- /path

kong.request.get_forwarded_prefix()

Returns the prefix path component of the request’s URL that Kong stripped before proxying to upstream. It also checks if X-Forwarded-Prefix comes from a trusted source, and uses it as-is when given. The value is returned as a Lua string.

If a trusted X-Forwarded-Prefix is not passed, this function must be called after Kong has run its router (access phase), as the Kong router may strip the prefix of the request path. That stripped path becomes the return value of this function, unless there is already a trusted X-Forwarded-Prefix header in the request.

Whether this function considers X-Forwarded-Prefix or not depends on several Kong configuration parameters:

  • trusted_ips
  • real_ip_header
  • real_ip_recursive

Note: Kong does not do any normalization on the request path prefix.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • string|nil: The forwarded path prefix or nil if the prefix was not stripped.

Usage

kong.request.get_forwarded_prefix() -- /prefix

kong.request.get_http_version()

Returns the HTTP version used by the client in the request as a Lua number, returning values such as 1, 1.1, 2.0, or nil for unrecognized values.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • number|nil: The HTTP version as a Lua number.

Usage

kong.request.get_http_version() -- 1.1

kong.request.get_method()

Returns the HTTP method of the request. The value is normalized to uppercase.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • string: The request method.

Usage

kong.request.get_method() -- "GET"

kong.request.get_path()

Returns the normalized path component of the request’s URL. The return value is the same as kong.request.get_raw_path() but normalized according to RFC 3986 section 6:

  • Percent-encoded values of unreserved characters are decoded (%20 becomes ` `).
  • Percent-encoded values of reserved characters have their hexidecimal value uppercased (%2f becomes %2F).
  • Relative path elements (/. and /..) are dereferenced.
  • Duplicate slashes are consolidated (// becomes /).

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • string: the path

Usage

-- Given a request to https://example.com/t/Abc%20123%C3%B8%2f/parent/..//test/./

kong.request.get_path() -- "/t/Abc 123ø%2F/test/"

kong.request.get_raw_path()

Returns the path component of the request’s URL. It is not normalized in any way and does not include the query string.

NOTE: Using the raw path to perform string comparision during request handling (such as in routing, ACL/authorization checks, setting rate-limit keys, etc) is widely regarded as insecure, as it can leave plugin code vulnerable to path traversal attacks. Prefer kong.request.get_path() for such use cases.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • string: The path.

Usage

-- Given a request to https://example.com/t/Abc%20123%C3%B8%2f/parent/..//test/./?movie=foo

kong.request.get_raw_path() -- "/t/Abc%20123%C3%B8%2f/parent/..//test/./"

kong.request.get_path_with_query()

Returns the path, including the query string if any. No transformations or normalizations are done.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • string: The path with the query string.

Usage

-- Given a request to https://example.com:1234/v1/movies?movie=foo

kong.request.get_path_with_query() -- "/v1/movies?movie=foo"

kong.request.get_raw_query()

Returns the query component of the request’s URL. It is not normalized in any way (not even URL-decoding of special characters) and does not include the leading ? character.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • string: The query component of the request’s URL.

Usage

-- Given a request to https://example.com/foo?msg=hello%20world&bla=&bar

kong.request.get_raw_query() -- "msg=hello%20world&bla=&bar"

kong.request.get_query_arg()

Returns the value of the specified argument, obtained from the query arguments of the current request.

The returned value is either a string, a boolean true if an argument was not given a value, or nil if no argument with name was found.

If an argument with the same name is present multiple times in the query string, this function returns the value of the first occurrence.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • string|boolean|nil: The value of the argument.

Usage

-- Given a request GET /test?foo=hello%20world&bar=baz&zzz&blo=&bar=bla&bar

kong.request.get_query_arg("foo") -- "hello world"
kong.request.get_query_arg("bar") -- "baz"
kong.request.get_query_arg("zzz") -- true
kong.request.get_query_arg("blo") -- ""

kong.request.get_query([max_args])

Returns the table of query arguments obtained from the query string. Keys are query argument names. Values are either a string with the argument value, a boolean true if an argument was not given a value, or an array if an argument was given in the query string multiple times. Keys and values are unescaped according to URL-encoded escaping rules.

Note that a query string ?foo&bar translates to two boolean true arguments, and ?foo=&bar= translates to two string arguments containing empty strings.

By default, this function returns up to 100 arguments. The optional max_args argument can be specified to customize this limit, but must be greater than 1 and not greater than 1000.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Parameters

  • max_args (number, optional): Sets a limit on the maximum number of parsed arguments.

Returns

  • table: A table representation of the query string.

Usage

-- Given a request GET /test?foo=hello%20world&bar=baz&zzz&blo=&bar=bla&bar

for k, v in pairs(kong.request.get_query()) do
  kong.log.inspect(k, v)
end

-- Will print
-- "foo" "hello world"
-- "bar" {"baz", "bla", true}
-- "zzz" true
-- "blo" ""

kong.request.get_header(name)

Returns the value of the specified request header.

The returned value is either a string, or can be nil if a header with name was not found in the request. If a header with the same name is present multiple times in the request, this function returns the value of the first occurrence of this header.

Header names in are case-insensitive and are normalized to lowercase, and dashes (-) can be written as underscores (_); that is, the header X-Custom-Header can also be retrieved as x_custom_header.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Parameters

  • name (string): the name of the header to be returned

Returns

  • string|nil: the value of the header or nil if not present

Usage

-- Given a request with the following headers:

-- Host: foo.com
-- X-Custom-Header: bla
-- X-Another: foo bar
-- X-Another: baz

kong.request.get_header("Host")            -- "foo.com"
kong.request.get_header("x-custom-header") -- "bla"
kong.request.get_header("X-Another")       -- "foo bar"

kong.request.get_headers([max_headers])

Returns a Lua table holding the request headers. Keys are header names. Values are either a string with the header value, or an array of strings if a header was sent multiple times. Header names in this table are case-insensitive and are normalized to lowercase, and dashes (-) can be written as underscores (_); that is, the header X-Custom-Header can also be retrieved as x_custom_header.

By default, this function returns up to 100 headers. The optional max_headers argument can be specified to customize this limit, but must be greater than 1 and not greater than 1000.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Parameters

  • max_headers (number, optional): Sets a limit on the maximum number of parsed headers.

Returns

  • table: The request headers in table form.

Usage

-- Given a request with the following headers:

-- Host: foo.com
-- X-Custom-Header: bla
-- X-Another: foo bar
-- X-Another: baz
local headers = kong.request.get_headers()

headers.host            -- "foo.com"
headers.x_custom_header -- "bla"
headers.x_another[1]    -- "foo bar"
headers["X-Another"][2] -- "baz"

kong.request.get_raw_body()

Returns the plain request body.

If the body has no size (empty), this function returns an empty string.

If the size of the body is greater than the Nginx buffer size (set by client_body_buffer_size), this function fails and returns an error message explaining this limitation.

Phases

  • rewrite, access, response, admin_api

Returns

  • string: The plain request body.

Usage

-- Given a body with payload "Hello, Earth!":

kong.request.get_raw_body():gsub("Earth", "Mars") -- "Hello, Mars!"

kong.request.get_body([mimetype[, max_args]])

Returns the request data as a key/value table. A high-level convenience function.

The body is parsed with the most appropriate format:

  • If mimetype is specified, it decodes the body with the requested content type (if supported). This takes precedence over any content type present in the request.

    The optional argument mimetype can be one of the following strings:

    • application/x-www-form-urlencoded
    • application/json
    • multipart/form-data

Whether mimetype is specified or a request content type is otherwise present in the request, each content type behaves as follows:

  • If the request content type is application/x-www-form-urlencoded:
    • Returns the body as form-encoded.
  • If the request content type is multipart/form-data:
    • Decodes the body as multipart form data (same as multipart(kong.request.get_raw_body(), kong.request.get_header("Content-Type")):get_all() ).
  • If the request content type is application/json:
    • Decodes the body as JSON (same as json.decode(kong.request.get_raw_body())).
    • JSON types are converted to matching Lua types.
  • If the request contains none of the above and the mimetype argument is not set, returns nil and an error message indicating the body could not be parsed.

The optional argument max_args can be used to set a limit on the number of form arguments parsed for application/x-www-form-urlencoded payloads.

The third return value is string containing the mimetype used to parsed the body (as per the mimetype argument), allowing the caller to identify what MIME type the body was parsed as.

Phases

  • rewrite, access, response, admin_api

Parameters

  • mimetype (string, optional): The MIME type.
  • max_args (number, optional): Sets a limit on the maximum number of parsed arguments.

Returns

  1. table|nil: A table representation of the body.

  2. string|nil: An error message.

  3. string|nil: mimetype The MIME type used.

Usage

local body, err, mimetype = kong.request.get_body()
body.name -- "John Doe"
body.age  -- "42"

kong.request.get_start_time()

Returns the request start time, in Unix epoch milliseconds.

Phases

  • rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

  • number: The timestamp

Usage

kong.request.get_start_time() -- 1649960273000
Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023