requests: Еще одна HTTP библиотека для nginx-module-lua - Для людей!

Установка

Если вы еще не подписались на RPM репозиторий, зарегистрируйтесь. Затем вы можете продолжить с следующими шагами.

CentOS/RHEL 7 или Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-requests

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-requests

Чтобы использовать эту Lua библиотеку с NGINX, убедитесь, что nginx-module-lua установлен.

Этот документ описывает lua-resty-requests v0.7.3, выпущенную 18 июля 2019 года.

Поддержка HTTP/1.0, HTTP/1.1 и HTTP/2 (в разработке).
Поддержка SSL/TLS.
Поддержка фрагментированных данных.
Удобные интерфейсы для поддержки таких функций, как json, авторизация и т.д.
Потоковые интерфейсы для чтения тела.
HTTP/HTTPS прокси.
Метрики задержки.
Поддержка сессий.

Синопсис

local requests = require "resty.requests"

-- пример url
local url = "http://example.com/index.html"

local r, err = requests.get(url)
if not r then
    ngx.log(ngx.ERR, err)
    return
end

-- прочитать все тело
local body = r:body()
ngx.print(body)

-- или вы можете итерировать по телу ответа
-- while true do
--     local chunk, err = r:iter_content(4096)
--     if not chunk then
--         ngx.log(ngx.ERR, err)
--         return
--     end
--
--     if chunk == "" then
--         break
--     end
--
--     ngx.print(chunk)
-- end

-- вы также можете использовать нестриминговый режим
-- local opts = {
--     stream = false
-- }
--
-- local r, err = requests.get(url, opts)
-- if not r then
--     ngx.log(ngx.ERR, err)
-- end
--
-- ngx.print(r.content)

-- или вы можете использовать сокращенный способ, чтобы сделать код чище.
local r, err = requests.get { url = url, stream = false }

Методы

request

синтаксис: local r, err = requests.request(method, url, opts?) синтаксис: local r, err = requests.request { method = method, url = url, ... }

Это основной метод в lua-resty-requests, он вернет объект response object r. В случае ошибки будет возвращено nil и строка Lua, описывающая соответствующую ошибку.

Первый параметр method - это HTTP метод, который вы хотите использовать (такой же, как семантика HTTP), который принимает строку Lua, и значение может быть:

GET
HEAD
POST
PUT
DELETE
OPTIONS
PATCH

Второй параметр url просто принимает буквальное значение (т.е. Uniform Resource Location), например, http://foo.com/blah?a=b, вы можете опустить префикс схемы, и по умолчанию будет выбрана схема http.

Третий параметр - это необязательная таблица Lua, которая содержит ряд опций:

headers содержит пользовательские заголовки запроса.
allow_redirects указывает, следует ли перенаправлять на целевой URL (указанный в заголовке Location) или нет, когда код состояния 301, 302, 303, 307 или 308.
redirect_max_times указывает пределы перенаправления, по умолчанию 10.
body, тело запроса, может быть:
- строкой Lua, или
- функцией Lua, без параметров и возвращающей часть данных (строка) или пустую строку Lua, чтобы представить EOF, или
- таблицей Lua, каждая пара ключ-значение будет конкатенирована с помощью "&", и заголовок Content-Type будет "application/x-www-form-urlencoded"
error_filter содержит функцию Lua, которая принимает два параметра, state и err. Параметр err описывает ошибку, а state всегда является одним из этих значений (представляет текущую стадию):
- requests.CONNECT
- requests.HANDSHAKE
- requests.SEND_HEADER
- requests.SEND_BODY
- requests.RECV_HEADER
- requests.RECV_BODY
- requests.CLOSE

Вы можете использовать метод requests.state, чтобы получить текстовое значение этих значений.

timeouts, таблица, подобная массиву, timeouts[1], timeouts[2] и timeouts[3] представляют connect timeout, send timeout и read timeout соответственно (в миллисекундах).
http10 указывает, следует ли использовать HTTP/1.0, версия по умолчанию - HTTP/1.1.
http20 указывает, следует ли использовать HTTP/2, версия по умолчанию - HTTP/1.1.

Обратите внимание, что это все еще нестабильно, следует проявлять осторожность. Также есть некоторые ограничения, см. lua-resty-http2 для получения подробностей.

ssl содержит таблицу Lua с тремя полями:
verify, управляет тем, следует ли выполнять проверку SSL
server_name, используется для указания имени сервера для нового TLS расширения Server Name Indication (SNI)
proxies указывает прокси-серверы, форма следующая:

{
    http = { host = "127.0.0.1", port = 80 },
    https = { host = "192.168.1.3", port = 443 },
}

При использовании HTTPS прокси будет отправлен предварительный запрос CONNECT на прокси-сервер.

hooks, также таблица Lua, представляет систему хуков, которую вы можете использовать для манипуляции частями процесса запроса. Доступные хуки:
response, будет вызван немедленно после получения заголовков ответа

вы можете назначить функции Lua хукам, эти функции принимают response object в качестве единственного параметра.

local hooks = {
    response = function(r)
        ngx.log(ngx.WARN, "в процессе запросов")
    end
}

Для удобства также есть некоторые "короткие пути":

auth, для выполнения базовой HTTP авторизации, принимает таблицу Lua, содержащую user и pass, например, когда auth:

{
    user = "alex",
    pass = "123456"
}

Заголовок запроса Authorization будет добавлен, и значение будет Basic YWxleDoxMjM0NTY=.

json, принимает таблицу Lua, она будет сериализована с помощью cjson, сериализованные данные будут отправлены в качестве тела запроса, и она имеет приоритет, когда указаны как json, так и body.
cookie, принимает таблицу Lua, пары ключ-значение будут организованы в соответствии с правилами заголовка Cookie, например, cookie:

{
    ["PHPSESSID"] = "298zf09hf012fh2",
    ["csrftoken"] = "u32t4o3tb3gg43"
}

Заголовок Cookie будет PHPSESSID=298zf09hf012fh2; csrftoken=u32t4o3tb3gg43.

stream, принимает логическое значение, указывает, следует ли читать тело в потоковом режиме, и по умолчанию будет true.

state

синтаксис: local state_name = requests.state(state)

Метод используется для получения текстового значения этих значений:

requests.CONNECT
requests.HANDSHAKE
requests.SEND_HEADER
requests.SEND_BODY
requests.RECV_HEADER
requests.RECV_BODY
requests.CLOSE

Будет возвращена строка Lua "unknown", если state не является одним из вышеуказанных значений.

get

синтаксис: local r, err = requests.get(url, opts?) синтаксис: local r, err = requests.get { url = url, ... }

Отправляет HTTP GET запрос. Это идентично:

requests.request("GET", url, opts)

head

синтаксис: local r, err = requests.head(url, opts?) синтаксис: local r, err = requests.head { url = url, ... }

Отправляет HTTP HEAD запрос. Это идентично:

requests.request("HEAD", url, opts)

post

синтаксис: local r, err = requests.post(url, opts?) синтаксис: local r, err = requests.post { url = url, ... }

Отправляет HTTP POST запрос. Это идентично:

requests.request("POST", url, opts)

put

синтаксис: local r, err = requests.put(url, opts?) синтаксис: local r, err = requests.put { url = url, ... }

Отправляет HTTP PUT запрос. Это идентично:

requests.request("PUT", url, opts)

delete

синтаксис: local r, err = requests.delete(url, opts?) синтаксис: local r, err = requests.delete { url = url, ... }

Отправляет HTTP DELETE запрос. Это идентично:

requests.request("DELETE", url, opts)

options

синтаксис: local r, err = requests.options(url, opts?) синтаксис: local r, err = requests.options { url = url, ... }

Отправляет HTTP OPTIONS запрос. Это идентично:

requests.request("OPTIONS", url, opts)

patch

синтаксис: local r, err = requests.patch(url, opts?) синтаксис: local r, err = requests.patch { url = url, ... }

Отправляет HTTP PATCH запрос. Это идентично:

requests.request("PATCH", url, opts)

Response Object

Методы, такие как requests.get и другие, вернут объект ответа r, который можно манипулировать с помощью следующих методов и переменных:

url, URL, переданный вызывающим
method, метод запроса, например, POST
status_line, сырой статусный ряд (полученный от удаленного сервера)
status_code, HTTP статус код
http_version, версия HTTP ответа, например, HTTP/1.1
headers, таблица Lua, представляющая HTTP заголовки ответа (регистр не имеет значения)
close, содержит функцию Lua, используемую для закрытия (поддержания) базового TCP соединения
drop, это функция Lua, используемая для сброса непрочитанного тела HTTP ответа, будет вызвана автоматически при закрытии (если остались непрочитанные данные)
iter_content, которая также является функцией Lua, выдает часть тела ответа (декодированного из фрагментированного формата) каждый раз, когда вызывается.

Эта функция принимает необязательный параметр size, чтобы указать размер тела, который вызывает хочет, при отсутствии iter_content возвращает 8192 байт, когда тело ответа обычное, или возвращает часть фрагментированных данных, если тело ответа фрагментировано.

В случае ошибки будет возвращено nil и строка Lua, описывающая ошибку.

body, также содержит функцию Lua, которая возвращает все тело ответа.

В случае ошибки будет возвращено nil и строка Lua, описывающая ошибку.

json, содержит функцию Lua, сериализует тело в таблицу Lua, обратите внимание, что Content-Type должен быть application/json. В случае ошибки будет возвращено nil и строка ошибки.
content, тело ответа, действительно только в нестриминговом режиме.
elapsed, таблица Lua, подобная хешу, которая представляет время затраченного на каждую стадию (в секундах).
elapsed.connect, время затраченное на TCP 3-Way Handshake;
elapsed.handshake, время затраченное на SSL/TLS handshake (если есть);
elapsed.send_header, время затраченное на отправку заголовков HTTP запроса;
elapsed.send_body, время затраченное на отправку тела HTTP запроса (если есть);
elapsed.read_header, время затраченное на получение заголовков HTTP ответа;
elapsed.ttfb, время до первого байта.

Обратите внимание, что когда применяется протокол HTTP/2, elapsed.send_body (если есть) будет таким же, как elapsed.send_header.

Сессия

Сессия сохраняет некоторые данные между несколькими запросами, такие как данные куки, данные авторизации и т.д.

Этот механизм все еще является экспериментальным.

Простой пример:

s = requests.session()
local r, err = s:get("https://www.example.com")
ngx.say(r:body())

Объект сессии имеет те же интерфейсы, что и requests, т.е. те же HTTP методы.

См. также

upyun-resty: https://github.com/upyun/upyun-resty
httpipe: https://github.com/timebug/lua-resty-httpipe

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-requests.