# AUTO GENERATED BASED ON Kong 3.8.x, DO NOT EDIT
# Original source path: kong/pdk/service/request.lua
from typing import TypeVar, Any, Union, List, Mapping, Tuple, Optional
number = TypeVar('number', int, float)
table = TypeVar('table', List[Any], Mapping[str, Any])
array = table
# XXX
cdata = Any
err = str
[docs]
class request():
[docs]
@staticmethod
def disable_tls() -> Tuple[bool, str]:
"""
Disables the TLS handshake to upstream for [ngx\_stream\_proxy\_module](https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html).
This overrides the [proxy\_ssl](https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_ssl) directive, effectively setting it to `off`
for the current stream session.
Once this function has been called, it is not possible to re-enable TLS handshake for the current session.
Phases:
preread, balancer
Example:
ok, err = kong.service.request.disable_tls()
if not ok:
# do something with error
:return: `true` if the operation succeeded, `nil` if an error occurred.
:rtype: bool
:return: An error message describing the error if there was one.
:rtype: str
"""
pass
[docs]
@staticmethod
def enable_buffering() -> None:
"""
Enables buffered proxying, which allows plugins to access Service body and
response headers at the same time.
Phases:
rewrite, access, balancer
Example:
kong.service.request.enable_buffering()
:return:
:rtype: None
"""
pass
[docs]
@staticmethod
def set_body(args: table, mimetype: Optional[str]) -> Tuple[bool, str]:
"""
Sets the body of the request to the Service. Unlike
`kong.service.request.set_raw_body()`, the `args` argument must be a table, and
is encoded with a MIME type. The encoding MIME type can be specified in
the optional `mimetype` argument, or if left unspecified, is chosen based
on the `Content-Type` header of the client's request.
Behavior based on MIME type in the `Content-Type` header:
* `application/x-www-form-urlencoded`: Encodes the arguments as
form-encoded. Keys are produced in lexicographical
order. The order of entries within the same key (when values are
given as an array) is retained. Any string values given are URL-encoded.
* `multipart/form-data`: Encodes the arguments as multipart form data.
* `application/json`: Encodes the arguments as JSON (same as
`kong.service.request.set_raw_body(json.encode(args))`). Lua types are
converted to matching JSON types.
If the MIME type is none of the above, this function returns `nil` and
an error message indicating the body could not be encoded.
If the `mimetype` argument is specified, the `Content-Type` header is
set accordingly in the request to the Service.
If further control of the body generation is needed, a raw body can be given as
a string with `kong.service.request.set_raw_body()`.
Phases:
rewrite, access, balancer
Example:
kong.service.set_header("application/json")
ok, err = kong.service.request.set_body({
name = "John Doe",
age = 42,
numbers = {1, 2, 3}
})
# Produces the following JSON body:
# { "name": "John Doe", "age": 42, "numbers":[1, 2, 3] }
ok, err = kong.service.request.set_body({
foo = "hello world",
bar = {"baz", "bla", true},
zzz = true,
blo = ""
}, "application/x-www-form-urlencoded")
# Produces the following body:
# bar=baz&bar=bla&bar&blo=&foo=hello%20world&zzz
:parameter args: A table with data to be converted to the appropriate format
and stored in the body.
:type args: table
:parameter mimetype: can be one of:
:type mimetype: str
:return: `true` on success, `nil` otherwise.
:rtype: bool
:return: `nil` on success, an error message in case of error.
Throws an error on invalid inputs.
:rtype: str
"""
pass
[docs]
@staticmethod
def set_method(method: str) -> None:
"""
Sets the HTTP method for the request to the service.
Phases:
rewrite, access
Example:
kong.service.request.set_method("DELETE")
:parameter method: The method string, which must be in all
uppercase. Supported values are: `"GET"`, `"HEAD"`, `"PUT"`, `"POST"`,
`"DELETE"`, `"OPTIONS"`, `"MKCOL"`, `"COPY"`, `"MOVE"`, `"PROPFIND"`,
`"PROPPATCH"`, `"LOCK"`, `"UNLOCK"`, `"PATCH"`, or `"TRACE"`.
:type method: str
:return: throws an error on invalid inputs.
:rtype: None
"""
pass
[docs]
@staticmethod
def set_path(path: str) -> None:
"""
Sets the path component for the request to the service.
The input accepts any valid *normalized* URI (including UTF-8 characters)
and this API will perform necessary escaping according to the RFC
to make the request valid.
Input should **not** include the query string.
Phases:
access, rewrite, balancer
Example:
kong.service.request.set_path("/v2/movies")
:parameter path: The path string. Special characters and UTF-8
characters are allowed, for example: `"/v2/movies"` or `"/foo/😀"`.
:type path: str
:return: throws an error on invalid inputs.
:rtype: None
"""
pass
[docs]
@staticmethod
def set_query(args: table) -> None:
"""
Set the query string of the request to the Service.
Unlike `kong.service.request.set_raw_query()`, the `query` argument must be a
table in which each key is a string (corresponding to an argument's name), and
each value is either a boolean, a string, or an array of strings or booleans.
Additionally, all string values will be URL-encoded.
The resulting query string contains keys in their lexicographical order. The
order of entries within the same key (when values are given as an array) is
retained.
If further control of the query string generation is needed, a raw query
string can be given as a string with `kong.service.request.set_raw_query()`.
Phases:
rewrite, access
Example:
kong.service.request.set_query({
foo = "hello world",
bar = {"baz", "bla", true},
zzz = true,
blo = ""
})
# Produces the following query string:
# bar=baz&bar=bla&bar&blo=&foo=hello%20world&zzz
:parameter args: A table where each key is a string (corresponding to an
argument name), and each value is either a boolean, a string, or an array of
strings or booleans. Any string values given are URL-encoded.
:type args: table
:return: throws an error on invalid inputs.
:rtype: None
"""
pass
[docs]
@staticmethod
def set_raw_body(body: str) -> None:
"""
Sets the body of the request to the Service.
The `body` argument must be a string and will not be processed in any way.
This function also sets the `Content-Length` header appropriately. To set an
empty body, you can provide an empty string (`""`) to this function.
For a higher-level function to set the body based on the request content type,
see `kong.service.request.set_body()`.
Phases:
rewrite, access, balancer
Example:
kong.service.request.set_raw_body("Hello, world!")
:parameter body: The raw body.
:type body: str
:return: throws an error on invalid inputs.
:rtype: None
"""
pass
[docs]
@staticmethod
def set_raw_query(query: str) -> None:
"""
Sets the query string of the request to the Service. The `query` argument is a
string (without the leading `?` character), and is not processed in any
way.
For a higher-level function to set the query string from a Lua table of
arguments, see `kong.service.request.set_query()`.
Phases:
rewrite, access
Example:
kong.service.request.set_raw_query("zzz&bar=baz&bar=bla&bar&blo=&foo=hello%20world")
:parameter query: The raw querystring. Example:
`"foo=bar&bla&baz=hello%20world"`.
:type query: str
:return: throws an error on invalid inputs.
:rtype: None
"""
pass
[docs]
@staticmethod
def set_scheme(scheme: str) -> None:
"""
Sets the protocol to use when proxying the request to the Service.
Phases:
access, rewrite, balancer
Example:
kong.service.request.set_scheme("https")
:parameter scheme: The scheme to be used. Supported values are `"http"` or `"https"`.
:type scheme: str
:return: throws an error on invalid inputs.
:rtype: None
"""
pass
pass