Модуль http

Общие сведения

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

Указатель

Ниже приведен перечень всех функций модуля http.

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 setting max_total_connections may be useful, since it causes curl to avoid creating too many sockets which would not be used anyway.

2. Do not set max_connections less than max_total_connections unless you are confident about your actions. When max_connections is less then max_total_connections, in some cases libcurl will not reuse sockets for requests that are going to the same host. If the limit is reached and a new request occurs, then libcurl 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 the max_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})
---
...

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 200
• http_other_responses – общее количество запросов, которые не вернули код состояния HTTP 200
• failed_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». Данный пример бесполезен, но наглядно демонстрирует синтаксис и получение отправленного сообщения.