Модуль http
Модуль http
, в частности вложенный модуль http.client
, обеспечивать функциональные возможности HTTP-клиента с поддержкой HTTPS и механизма поддержания в активном состоянии keepalive. Модуль использует процедуры из библиотеки libcurl.
Ниже приведен перечень всех функций модуля http
.
Имя | Назначение |
---|---|
http.client.new() | Создание экземпляра HTTP-клиента |
client_object:request() | Выполнение HTTP-запроса |
client_object:stat() | Получение таблицы со статистикой |
-
http.client.
new
([options]) Создание нового экземпляра HTTP-клиента.
Параметры: - options (table) – настройки целочисленных значений, которые передаются в
libcurl
.
Доступны два параметра:
max_connections
иmax_total_connections
.max_connections
– это максимальное количество записей в кэше, которое влияет на CURLMOPT_MAXCONNECTS вlibcurl
. По умолчанию -1.max_total_connections
– это максимальное число активных соединений, которое влияет на CURLMOPT_MAX_TOTAL_CONNECTIONS вlibcurl
. Значение не учитывается, если версияcurl
ниже 7.30. По умолчанию 0, что позволяетlibcurl
масштабироваться в зависимости от количества обработчиков.Обычно значений параметров по умолчанию будет достаточно, но в редких случаях может понадобиться их настройка. На этот случай два совета.
1. You may want to control the maximum number of sockets that a particular http client uses simultaneously. If a system passes many requests to distinct hosts, then
libcurl
cannot reuse sockets. In this case settingmax_total_connections
may be useful, since it causescurl
to avoid creating too many sockets which would not be used anyway.2. Do not set
max_connections
less thanmax_total_connections
unless you are confident about your actions. Whenmax_connections
is less thenmax_total_connections
, in some caseslibcurl
will not reuse sockets for requests that are going to the same host. If the limit is reached and a new request occurs, thenlibcurl
will first create a new socket, send the request, wait for the first connection to be free, and close it, in order to avoid exceeding themax_connections
cache size. In the worst case,libcurl
will create a new socket for every request, even if all requests are going to the same host. See this Tarantool issue on github for details.возвращает: новый экземпляр HTTP-клиента тип возвращаемого значения: пользовательские данные Пример:
tarantool> http_client = require('http.client').new({max_connections = 5}) --- ...
- options (table) – настройки целочисленных значений, которые передаются в
-
object
client_object
-
client_object:
request
(method, url, body, opts) Если
http_client
– это экземпляр HTTP-клиента,http_client:request()
выполнит HTTP-запрос, и в случае успешного подключения вернет таблицу с информацией о подключении.Параметры: - method (string) – HTTP-метод, например „GET“, „POST“ или „PUT“
- url (string) – расположение, например „https://tarantool.org/doc“
- body (string) – необязательное начальное сообщение, например „My text string!“
- opts (table) – таблица с параметрами подключения, которые могут содержать любые из следующих компонентов: *
timeout
– количество секунд ожидания API-запросаcurl
на чтение до превышения времени ожидания *ca_path
– путь к директории, где хранятся один или более сертификатов для проверки подключенного узла *ca_file
– путь к SSL-сертификату для проверки подключенного узла *verify_host
– включение/отключение проверки имени сертификата (CN) для хоста. См. также CURLOPT_SSL_VERIFYHOST *verify_peer
– включение/отключение проверки SSL-сертификата подключенного узла. См. также CURLOPT_SSL_VERIFYPEER *ssl_key
– путь к файлу закрытого ключа для клиентского TSL-сертификата и SSL-сертификата. См. также CURLOPT_SSLKEY *ssl_cert
– путь к файлу клиентского SSL-сертификата. См. также CURLOPT_SSLCERT *headers
– таблица HTTP-заголовков *keepalive_idle
– время задержки в секундах, в течение которого операционная система находится в режиме ожидания подключения до отправки сообщений для поддержания в активном состоянии keepalive. См. также CURLOPT_TCP_KEEPALIVE *keepalive_interval
– время интервала в секундах, в течение которого операционная система находится в режиме ожидания между отправкой сообщений keepalive. См. также CURLOPT_TCP_KEEPIDLE и примечание ниже к keepalive_interval. *keepalive_interval
– период времени в секундах между отправками сообщений keepalive в операционной системе. См. также CURLOPT_TCP_KEEPINTVL. Если заданы оба параметр keepalive_idle и keepalive_interval, то Tarantool отобразит HTTP-заголовки для keepalive: Connection:Keep-Alive и Keep-Alive:timeout=<keepalive_idle>. В противном случае, Tarantool отправит Connection:close *low_speed_time
– установка «времени работы с низкой скоростью» – времени, в течение которого скорость передачи должна быть ниже «предела низкой скорости», чтобы библиотека посчитала работу слишком медленной и завершила ее. См. также CURLOPT_LOW_SPEED_TIME *low_speed_limit
– установка «предела низкой скорости» – средней скорости передачи в байтах в секунду, ниже которой должна быть скорость передачи, чтобы библиотека посчитала работу слишком медленной и завершила ее. См. также CURLOPT_LOW_SPEED_LIMIT *verbose
– включение/отключение режима отображения подробной информации *unix_socket
– имя сокета, которое используется вместо адреса в сети Интернет, для локального соединения. Сборка сервера Tarantool’а должна осуществляться с помощьюlibcurl
7.40 или более поздней версии. См. второй пример далее в разделе. *max_header_name_len
– максимальная длина имени заголовка. Если имя заголовка больше данного значения, оно усекается до такой длины. По умолчанию, „32“.
возвращает: информация об ответах со всеми следующими компонентами:
status
– статус HTTP-ответаreason
– текст статуса HTTP-ответаheaders
– Lua-таблица с нормализованными HTTP-заголовкамиbody
– тело сообщения-ответаproto
– версия протоколаcookies
– Lua-таблица с файлами cookies и их параметрами
тип возвращаемого значения: таблица
Компонент
cookies
содержит Lua-таблицу, ключом в которой является имя файла cookie. Значением же является массив из двух элементов: первый элемент представляет собой значение данных cookie, а второй – массив с параметрами файла cookie. Возможные параметры: «Expires», «Max-Age», «Domain», «Path», «Secure», «HttpOnly», «SameSite». Обратите внимание, что параметр представляет собой строку, в которой знак „=“ разделяет имя параметра и его значение. Дополнительную информацию можно получить здесь.Пример:
Информацию по файлам cookies можно использовать следующим образом:
tarantool> require('http.client').get('https://www.tarantool.io/en/').cookies --- - csrftoken: - bWJVkBybvX9LdJ8uLPOTVrit5P3VbRjE3potYVOuUnsSjYT5ahghDV06tXRkfnOl - - Max-Age=31449600 - Path=/ ... tarantool> cookies = require('http.client').get('https://www.tarantool.io/en/').cookies --- ... tarantool> options = cookies['csrftoken'][2] --- ... tarantool> for _, option in ipairs(options) do > if option:startswith('csrftoken cookie's Max-Age = ') then > print(option) > end > end csrftoken cookie's Max-Age = 31449600 --- ... tarantool>
Для запросов существуют следующие ускоренные методы:
http_client:get(url, options)
– вспомогательный метод дляhttp_client:request("GET", url, nil, opts)
http_client:post (url, body, options)
– ускоренный метод дляhttp_client:request("POST", url, body, opts)
http_client:put(url, body, options)
– ускоренный метод дляhttp_client:request("PUT", url, body, opts)
http_client:patch(url, body, options)
– ускоренный метод дляhttp_client:request("PATCH", url, body, opts)
http_client:options(url, options)
– ускоренный метод дляhttp_client:request("OPTIONS", url, nil, opts)
http_client:head(url, options)
– ускоренный метод дляhttp_client:request("HEAD", url, nil, opts)
http_client:delete(url, options)
– ускоренный метод дляhttp_client:request("DELETE", url, nil, opts)
http_client:trace(url, options)
– ускоренный метод дляhttp_client:request("TRACE", url, nil, opts)
http_client:connect:(url, options)
– ускоренный метод дляhttp_client:request("CONNECT", url, nil, opts)
На запросы могут влиять переменные окружения, например, пользователи могут задать прокси-сервер с HTTP, указав
HTTP_PROXY=прокси-сервер
перед выполнением каких-либо запросов. См. веб-документ по переменным окружения Environment variables libcurl understands.
-
client_object:
stat
() Функция
http_client:stat()
возвращает таблицу со статистическими данными:active_requests
– количество активно выполняемых запросовsockets_added
– общее количество сокетов, добавленных в событийный циклsockets_deleted
– общее количество сокетов, удаленных из событийного циклаtotal_requests
– общее количество запросовhttp_200_responses
– общее количество запросов, которые вернули код состояния HTTP 200http_other_responses
– общее количество запросов, которые не вернули код состояния HTTP 200failed_requests
– общее количество невыполненных запросов, включая системные ошибки, ошибкиcurl
и HTTP-ошибки
-
Пример 1:
Подключение к HTTP-серверу, просмотр размера ответа на „GET“-запрос и просмотр статистики по сессии.
tarantool> http_client = require('http.client').new()
---
...
tarantool> r = http_client:request('GET','http://tarantool.org')
---
...
tarantool> string.len(r.body)
---
- 21725
...
tarantool> http_client:stat()
---
- total_requests: 1
sockets_deleted: 2
failed_requests: 0
active_requests: 0
http_other_responses: 0
http_200_responses: 1
sockets_added: 2
Пример 2:
Запустите два экземпляра Tarantool’а на одном компьютере.
В первом экземпляре Tarantool’а включите прослушивание Unix-сокета:
box.cfg{listen='/tmp/unix_domain_socket.sock'}
На втором экземпляре Tarantool’а отправьте с помощью http_client
:
box.cfg{}
http_client = require('http.client').new({5})
http_client:put('http://localhost/','body',{unix_socket = '/tmp/unix_domain_socket.sock'})
Терминал №1 покажет сообщение об ошибке: «Invalid MsgPack». Данный пример бесполезен, но наглядно демонстрирует синтаксис и получение отправленного сообщения.