Модуль http

Модуль http, в частности подмодуль http.client, предоставляет функциональность HTTP-клиента с поддержкой HTTPS и keepalive. HTTP-клиент использует библиотеку libcurl и учитывает переменные окружения, обрабатываемые libcurl.

Подмодуль http.client предоставляет экземпляр HTTP-клиента по умолчанию:

 
local http_client = require('http.client')

В этом случае запросы выполняются с использованием точечной нотации, например:

 
local response = http_client.get('https://httpbin.org/get')

Если требуется задать определённые параметры HTTP-клиента, используйте функцию http.client.new() для создания экземпляра клиента:

 
local http_client = require('http.client').new()

В этом случае запросы выполняются с использованием нотации с двоеточием, например:

 
local response = http_client:get('https://httpbin.org/get')

Все примеры в этом разделе используют HTTP-клиент, созданный с помощью http.client.new().

С помощью экземпляра клиента можно выполнять HTTP-запросы.

Основной способ выполнения HTTP-запросов — метод request, который принимает следующие аргументы:

• HTTP-метод, например GET, POST, PUT и так далее.
• URL запроса. Для формирования URL из компонентов можно использовать модуль uri.
• (Необязательно) тело запроса для методов POST, PUT и PATCH.
• (Необязательно) параметры запроса, например заголовки запроса, настройки SSL и так далее.

В примере ниже показано, как выполнить GET-запрос к URL https://httpbin.org/get:

 
local http_client = require('http.client').new()local response = http_client:request('GET', 'https://httpbin.org/get')

Помимо request, HTTP-клиент предоставляет API для отдельных HTTP-методов: get, post, put и так далее. Например, приведенный выше запрос можно заменить вызовом get следующим образом:

 
local http_client = require('http.client').new()local response = http_client:get('https://httpbin.org/get')

Чтобы добавить параметры строки запроса, используйте параметр params, предоставляемый объектом request_options:

 
local http_client = require('http.client').new()local response = http_client:get('https://httpbin.org/get', {    params = { page = 1 },})print('URL: '..response.url)

В примере выше запрашиваемый URL — https://httpbin.org/get?page=1.

Чтобы добавить заголовки к запросу, используйте параметр headers:

 
local http_client = require('http.client').new()local response = http_client:get('https://httpbin.org/headers', {    headers = {        ['User-Agent'] = 'Tarantool HTTP client',        ['Authorization'] = 'Bearer abc123'    }})print('Authorization: '..response:decode()['headers']['Authorization'])

Добавить cookies в запрос можно с помощью параметра headers:

 
local http_client = require('http.client').new()local response = http_client:get('https://httpbin.org/cookies', {    headers = {        ['Cookie'] = 'session_id=abc123; csrftoken=u32t4o;',    }})print(response.body)

Подробнее о том, как получить cookies, передаваемые в заголовке ответа Set-Cookie, см. Cookies ответа.

HTTP-клиент автоматически сериализует содержимое в определенном формате при отправке запроса на основе указанного заголовка Content-Type. По умолчанию клиент использует тип содержимого application/json и отправляет данные, сериализованные как JSON:

 
local http_client = require('http.client').new()local response = http_client:post('https://httpbin.org/anything', {    user_id = 123,    user_name = 'John Smith'})print('Posted data: '..response:decode()['data'])

Тело запроса из примера выше может выглядеть так:

 
{    "user_id": 123,    "user_name": "John Smith"}

Чтобы отправить данные в формате YAML или MsgPack, явно укажите для заголовка Content-Type значение application/yaml или application/msgpack соответственно, например:

 
local http_client = require('http.client').new()local response = http_client:post('https://httpbin.org/anything', {    user_id = 123,    user_name = 'John Smith'}, {    headers = {        ['Content-Type'] = 'application/yaml',    }})print('Posted data:\n'..response:decode()['data'])

В этом случае тело запроса сериализуется в формат YAML:

 
user_id: 123user_name: John Smith

Чтобы отправить параметры формы с использованием типа application/x-www-form-urlencoded, используйте опцию params:

 
local http_client = require('http.client').new()local response = http_client:post('https://httpbin.org/anything', nil, {    params = { user_id = 123, user_name = 'John Smith' },})print('User ID: '..response:decode()['form']['user_id'])

HTTP-клиент поддерживает поблочную запись данных запроса. Это можно реализовать следующим образом:

1. Задайте значение true для параметра chunked. В этом случае метод запроса возвращает io_object вместо response_object.
2. Используйте метод io_object.write() для записи блока данных.
3. Вызовите метод io_object.finish(), чтобы завершить запись данных и выполнить запрос. В примере ниже показано, как загрузить данные в два блока:

 
local http_client = require('http.client').new()local json = require('json')local io = http_client:post('https://httpbin.org/anything', nil, {chunked = true})io:write('Data part 1')io:write('Data part 2')io:finish()response = io:read('\r\n')decoded_data = json.decode(response)print('Posted data: '..decoded_data['data'])

Все методы, используемые для создания HTTP-запроса (request, get, post и т. д.), возвращают response_object. Объект response_object предоставляет API, необходимое для получения тела ответа и его параметров, таких как код состояния, заголовки и т. д.

Чтобы получить код состояния и текст ответа, используйте параметры response_object.status и response_object.reason соответственно:

 
local http_client = require('http.client').new()local response = http_client:get('https://httpbin.org/get')print('Status: '..response.status..' '.. response.reason)

Параметр response_object.headers возвращает набор заголовков ответа. В примере ниже показано, как получить значение заголовка ETag:

 
local http_client = require('http.client').new()local response = http_client:get('https://httpbin.org/etag/7c876b7e')print('ETag header value: '..response.headers['etag'])

Для получения куки ответа используйте параметр response_object.cookies. Этот параметр возвращает Lua-таблицу, в которой ключом выступает имя куки. Значение представляет собой массив из двух элементов, где первый — это значение куки, а второй — массив с параметрами куки.

В примере ниже показано, как получить значение куки session_id:

 
local http_client = require('http.client').new()local response = http_client:get('https://httpbin.org/cookies/set?session_id=abc123&csrftoken=u32t4o&', {follow_location = false})print("'session_id' cookie value: "..response.cookies['session_id'][1])

HTTP-клиент может десериализовать данные ответа в Lua-объект на основе значения заголовка ответа Content-Type. Для десериализации данных вызовите метод response_object.decode(). В примере ниже JSON-ответ десериализуется в Lua-объект:

 
local http_client = require('http.client').new()local response = http_client:get('https://httpbin.org/json')local document = response:decode()print("'title' value: "..document['slideshow']['title'])

Из коробки поддерживаются следующие типы содержимого:

• application/json
• application/msgpack
• application/yaml

Если ответ не содержит заголовка Content-Type, клиент использует application/json.

Для десериализации других типов содержимого необходимо предоставить пользовательский десериализатор через свойство client_object.decoders. В примере ниже ответы application/xml декодируются с помощью библиотеки luarapidxml:

 
local http_client = require('http.client').new()local xml = require("luarapidxml")http_client.decoders = {    ['application/xml'] = function(body, _content_type)        return xml.decode(body)    end,}local response = http_client:get('https://httpbin.org/xml')local document = response:decode()print("'title' value: "..document['attr']['title'])

Результат выполнения приведенного выше примера кода должен выглядеть так:

 
'title' value: Sample Slide Show

HTTP-клиент может автоматически распаковывать тело ответа на основе значения заголовка Content-Encoding. Чтобы включить эту возможность, передайте требуемые форматы с помощью параметра request_options.accept_encoding:

 
local http_client = require('http.client').new()local response = http_client:get('https://httpbin.org/gzip', {accept_encoding = "br, gzip, deflate"})print('Is response gzipped: '..tostring(response:decode()['gzipped']))

HTTP-клиент поддерживает чтение данных запроса по частям. Это можно реализовать следующим образом:

1. Задайте значение true для параметра chunked. В этом случае метод запроса возвращает io_object вместо response_object.
2. Используйте метод io_object.read() для чтения данных частями заданной длины или до определенного разделителя.
3. Вызовите метод io_object.finish() для завершения чтения данных. В примере ниже показано, как получать части JSON-ответа последовательно, не дожидаясь получения всего ответа:

 
local http_client = require('http.client').new()local json = require('json')local io = http_client:get('https://httpbin.org/stream/5', {chunked = true})local chunk_ids = ''while data ~= '' do    local data = io:read('\n')    if data == '' then break end    local decoded_data = json.decode(data)    chunk_ids = chunk_ids..decoded_data['id']..' 'endprint('IDs of received chunks: '..chunk_ids)io:finish()

По умолчанию HTTP-клиент выполняет перенаправление на URL, указанный в заголовке Location ответа 3xx. При необходимости перенаправление можно отключить с помощью параметра follow_location:

 
local http_client = require('http.client').new()local response = http_client:get('https://httpbin.org/cookies/set?session_id=abc123&csrftoken=u32t4o&', {follow_location = false})

Ниже приведен список функций и объектов http.client.

Функции

• http.client.new() — создание экземпляра HTTP-клиента

Объекты

• client_options — параметры конфигурации клиента
• client_object — экземпляр HTTP-клиента
• request_options — параметры, передаваемые в запрос
• response_object — объект ответа
• io_object — объект ввода-вывода, используемый для чтения/записи данных по частям

Создание экземпляра HTTP-клиента.

Параметры:

• options (table) — параметры конфигурации клиента (см. client_options)

Возвращает

новый экземпляр HTTP-клиента (см. client_object)

Тип возвращаемого значения

userdata

Пример:

 
local http_client = require('http.client').new()

Параметры конфигурации клиента. Эти параметры можно передать в функцию http.client.new().

Задает максимальное количество записей в кэше. Этот параметр влияет на libcurl CURLMOPT_MAXCONNECTS. Значение по умолчанию: -1.

Пример:

 
local http_client = require('http.client').new({max_connections = 5})

Задает максимальное количество активных соединений. Этот параметр влияет на libcurl CURLMOPT_MAX_TOTAL_CONNECTIONS.

Экземпляр HTTP-клиента, предоставляющий API для выполнения запросов. Чтобы создать клиент, вызовите http.client.new().

Выполнение HTTP-запроса и получение ответа.

Параметры:

• method (string) — HTTP-метод запроса. Возможные значения: GET, POST, PUT, PATCH, OPTIONS, HEAD, DELETE, TRACE, CONNECT.
• url (string) — URL запроса, например, https://httpbin.org/get
• body (string) — тело запроса (см. Тело запроса)
• opts (table) — параметры запроса (см. request_options)

Возвращает

один из следующих объектов:

• response_object
• io_object, если для параметра request_options.chunked задано значение true

Тип возвращаемого значения

table

Пример:

 
local http_client = require('http.client').new()local response = http_client:request('GET', 'https://httpbin.org/get')

См. также: Выполнение запросов, Получение ответов

Выполнение GET-запроса и получение ответа.

Параметры:

• url (string) — URL запроса, например, https://httpbin.org/get
• opts (table) — параметры запроса (см. request_options)

Возвращает

один из следующих объектов:

• response_object
• io_object, если для параметра request_options.chunked задано значение true

Тип возвращаемого значения

table

Пример:

 
local http_client = require('http.client').new()local response = http_client:get('https://httpbin.org/get')

См. также: Выполнение запросов, Получение ответов

Выполнение POST-запроса и получение ответа.

Параметры:

• url (string) — URL запроса, например, https://httpbin.org/post
• body (string) — тело запроса (см. Тело запроса)
• opts (table) — параметры запроса (см. request_options)

Возвращает

один из следующих объектов:

• response_object
• io_object, если для параметра request_options.chunked задано значение true

Тип возвращаемого значения

table

Пример:

 
local http_client = require('http.client').new()local response = http_client:post('https://httpbin.org/anything', {    user_id = 123,    user_name = 'John Smith'})print('Posted data: '..response:decode()['data'])

См. также: Выполнение запросов, Получение ответов

Выполнение PUT-запроса и получение ответа.

Параметры:

• url (string) — URL запроса, например, https://httpbin.org/put
• body (string) — тело запроса (см. Тело запроса)
• opts (table) — параметры запроса (см. request_options)

Возвращает

один из следующих объектов:

• response_object
• io_object, если для параметра request_options.chunked задано значение true

Тип возвращаемого значения

table

См. также: Выполнение запросов, Получение ответов

Выполнение PATCH-запроса и получение ответа.

Параметры:

• url (string) — URL запроса, например, https://httpbin.org/patch
• body (string) — тело запроса (см. Тело запроса)
• opts (table) — параметры запроса (см. request_options)

Возвращает

один из следующих объектов:

• response_object
• io_object, если для параметра request_options.chunked задано значение true

Тип возвращаемого значения

table

См. также: Выполнение запросов, Получение ответов

Выполнение DELETE-запроса и получение ответа.

Параметры:

• url (string) — URL запроса, например, https://httpbin.org/delete
• opts (table) — параметры запроса (см. request_options)

Возвращает

один из следующих объектов:

• response_object
• io_object, если для параметра request_options.chunked задано значение true

Тип возвращаемого значения

table

См. также: Выполнение запросов, Получение ответов

Выполнение HEAD-запроса и получение ответа.

Параметры:

• url (string) — URL запроса, например, https://httpbin.org/get
• opts (table) — параметры запроса (см. request_options)

Возвращает

один из следующих объектов:

• response_object
• io_object, если для параметра request_options.chunked задано значение true

Тип возвращаемого значения

table

См. также: Выполнение запросов, Получение ответов

Выполнение OPTIONS-запроса и получение ответа.

Параметры:

• url (string) — URL запроса, например, https://httpbin.org/get
• opts (table) — параметры запроса (см. request_options)

Возвращает

один из следующих объектов:

• response_object
• io_object, если для параметра request_options.chunked задано значение true

Тип возвращаемого значения

table

См. также: Выполнение запросов, Получение ответов

Выполнение TRACE-запроса и получение ответа.

Параметры:

• url (string) — URL запроса, например, https://httpbin.org/get
• opts (table) — параметры запроса (см. request_options)

Возвращает

один из следующих объектов:

• response_object
• io_object, если для параметра request_options.chunked задано значение true

Тип возвращаемого значения

table

См. также: Выполнение запросов, Получение ответов

Выполнение CONNECT-запроса и получение ответа.

Параметры:

• url (string) — URL запроса, например, server.example.com:80
• opts (table) — параметры запроса (см. request_options)

Возвращает

один из следующих объектов:

• response_object
• io_object, если для параметра request_options.chunked задано значение true

Тип возвращаемого значения

table

См. также: Выполнение запросов, Получение ответов

Получение таблицы со статистикой HTTP-клиента:

• active_requests – количество выполняемых в данный момент запросов
• sockets_added – общее количество сокетов, добавленных в цикл обработки событий
• sockets_deleted – общее количество сокетов, удаленных из цикла обработки событий
• total_requests – общее количество запросов
• http_200_responses – общее количество запросов, вернувших ответы HTTP 200 OK
• http_other_responses – общее количество запросов, вернувших ответы, отличные от 200 OK
• failed_requests – общее количество неудачных запросов, включая системные ошибки, ошибки curl и HTTP

Начиная с: 2.11.0

Декодеры, используемые для десериализации данных ответа на основе значения заголовка Content-Type. Подробнее см. Десериализация.

Параметры, передаваемые в метод запроса (request, get, post и так далее).

См. также: Выполнение запросов

Путь к файлу SSL-сертификата для проверки узла.

Тип возвращаемого значения

string

Путь к каталогу, содержащему один или несколько сертификатов для проверки узла.

Тип возвращаемого значения

string

Начиная с: 2.11.0

Определяет, должен ли HTTP-клиент возвращать полный ответ (response_object) или объект ввода-вывода (io_object), используемый для потоковой загрузки/выгрузки.

Тип возвращаемого значения

boolean

См. также: Потоковая загрузка, Потоковая выгрузка

Таблица HTTP-заголовков, передаваемых в запросе.

Тип возвращаемого значения

table

Начиная с: 2.11.0

Таблица параметров, передаваемых в запрос. Поведение этого параметра зависит от типа запроса, например:

• Для запроса GET этот параметр задает параметры строки запроса.
• Для запроса POST этот параметр задает параметры формы, отправляемые с использованием типа application/x-www-form-urlencoded.

Тип возвращаемого значения

table

Время ожидания (в секундах), в течение которого операционная система ждет при простое соединения перед отправкой keepalive-проб.

Тип возвращаемого значения

integer

См. также: CURLOPT_TCP_KEEPIDLE, keepalive_interval

Интервал (в секундах), в течение которого операционная система ждет между отправками keepalive-проб. Если заданы оба параметра keepalive_idle и keepalive_interval, то Tarantool также задает HTTP-заголовки keepalive: Connection:Keep-Alive и Keep-Alive:timeout=<keepalive_idle>. В противном случае Tarantool отправляет Connection:close.

Тип возвращаемого значения

integer

См. также: CURLOPT_TCP_KEEPINTVL

Средняя скорость передачи в байтах в секунду, ниже которой скорость передачи должна оставаться в течение времени "low speed time", чтобы библиотека сочла ее слишком низкой и прервала передачу.

Тип возвращаемого значения

integer

См. также: CURLOPT_LOW_SPEED_LIMIT

Время, в течение которого скорость передачи должна оставаться ниже "low speed limit", чтобы библиотека сочла ее слишком низкой и прервала передачу.

Тип возвращаемого значения

integer

См. также: CURLOPT_LOW_SPEED_TIME

Максимальная длина имени заголовка. Если длина имени заголовка превышает это значение, оно усекается до этой длины. Значение по умолчанию: 32.

Тип возвращаемого значения

integer

Определяет, переходит ли HTTP-клиент по URL-адресам перенаправления, указанным в заголовке Location для ответов 3xx. При получении ответа, отличного от 3xx, клиент возвращает его в качестве результата. Если задать для этого параметра значение false, клиент вернет первый ответ 3xx.

Тип возвращаемого значения

boolean

См. также: Перенаправления

Разделенный запятыми список хостов, не требующих прокси-сервера, либо *, либо ''.

• Задайте no_proxy = {host} [, {host} ...], чтобы указать хосты, доступные без прокси-сервера, даже если для параметра proxy задано непустое значение и/или установлена переменная окружения, связанная с прокси.
• Задайте no_proxy = '*', чтобы указать, что все хосты доступны без прокси-сервера, что эквивалентно заданию proxy=''.
• Задайте no_proxy = '', чтобы указать, что ни один хост недоступен без прокси-сервера, даже если используется переменная окружения, связанная с прокси (HTTP_PROXY).

Если параметр no_proxy не задан, может использоваться переменная окружения, связанная с прокси (HTTP_PROXY).

Тип возвращаемого значения

string

См. также: CURLOPT_NOPROXY

Хост или IP-адрес прокси-сервера, либо ''.

• Если proxy — это хост или IP-адрес, то он может начинаться со схемы, например, https:// для HTTPS-прокси или http:// для HTTP-прокси.
• Если для параметра proxy задано пустое значение '', использование прокси отключается, и переменные окружения, связанные с прокси, не применяются.
• Если параметр proxy не задан, может использоваться переменная окружения, связанная с прокси, например, HTTP_PROXY, HTTPS_PROXY, FTP_PROXY или ALL_PROXY, если протокол может быть любым.

Тип возвращаемого значения

string

См. также: CURLOPT_PROXY

Порт прокси-сервера. Значение по умолчанию: 443 для HTTPS-прокси и 1080 для прокси, отличного от HTTPS.

Тип возвращаемого значения

integer

См. также: CURLOPT_PROXYPORT

Имя пользователя и пароль прокси-сервера. Этот параметр может иметь один из следующих форматов:

• proxy_user_pwd = {user_name}:
• proxy_user_pwd = :{password}
• proxy_user_pwd = {user_name}:{password}

Тип возвращаемого значения

string

См. также: CURLOPT_USERPWD

Путь к файлу SSL-сертификата клиента.

Тип возвращаемого значения

string

См. также: CURLOPT_SSLCERT

Путь к файлу закрытого ключа для TLS- и SSL-сертификата клиента.

Тип возвращаемого значения

string

См. также: CURLOPT_SSLKEY

Время ожидания в секундах при выполнении запроса на чтение через API curl. По умолчанию время ожидания установлено на бесконечность (36586400100 секунд).

Тип возвращаемого значения

integer

Имя сокета, используемое вместо интернет-адреса для локального подключения.

Тип возвращаемого значения

string

Пример: /tmp/unix_domain_socket.sock

Включение/выключение режима подробного вывода.

Тип возвращаемого значения

boolean

Включение проверки имени сертификата (CN) на соответствие указанному хосту.

Тип возвращаемого значения

integer

См. также: CURLOPT_SSL_VERIFYHOST

Включение/выключение проверки SSL-сертификата узла.

Тип возвращаемого значения

integer

См. также: CURLOPT_SSL_VERIFYPEER

Включение декомпрессии данных HTTP-ответа на основе указанного заголовка запроса Accept-Encoding. Этому параметру можно передать следующие значения:

• '' – если передана пустая строка, Accept-Encoding содержит все поддерживаемые кодировки (identity, deflate, gzip и br).
• br, gzip, deflate – разделенный запятыми список кодировок, передаваемый в Accept-Encoding.

Тип возвращаемого значения

string

См. также: CURLOPT_ACCEPT_ENCODING

Объект ответа, возвращаемый методом запроса (request, get, post и так далее).

См. также: io_object

Код статуса ответа.

Тип возвращаемого значения

integer

См. также: Код статуса

Текст статуса ответа.

Тип возвращаемого значения

string

См. также: Код статуса

Заголовки ответа.

Тип возвращаемого значения

table

См. также: Заголовки

Cookies ответа. Значение представляет собой массив из двух элементов, где первый — значение cookie, а второй — массив с параметрами cookie.

Тип возвращаемого значения

table

См. также: Cookies

Тело ответа. Для декодирования тела ответа используйте decode.

Тип возвращаемого значения

table

См. также: Тело ответа

Версия HTTP-протокола.

Тип возвращаемого значения

string

Начиная с: 2.11.0

Декодирование тела ответа в объект Lua на основе типа содержимого.

Возвращает

декодированное тело

Тип возвращаемого значения

table

См. также: Десериализация

Начиная с: 2.11.0

Объект ввода-вывода, используемый для чтения или записи данных по частям. Чтобы получить объект ввода-вывода вместо полного ответа (response_object), необходимо задать для параметра запроса chunked значение true.

Чтение данных запроса частями заданной длины или до определенного разделителя.

Параметры:

• chunk (integer) — максимальное количество байт для чтения
• delimiter (string) — разделитель, используемый для остановки чтения данных
• timeout (integer) — время ожидания в секундах. Значение по умолчанию: 10.

Возвращает

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

Тип возвращаемого значения

string

См. также: Потоковая загрузка

Запись указанной части данных.

Параметры:

• data (table) — данные для записи
• timeout (integer) — время ожидания в секундах. Значение по умолчанию: 10.

См. также: Потоковая выгрузка

Завершение чтения или записи данных.

Параметры:

• timeout (integer) — время ожидания в секундах. Значение по умолчанию: 10.

См. также: Потоковая загрузка, Потоковая выгрузка