Версия:

Модуль http

Модуль 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) – integer settings which are passed to libcurl.

The two possible options are max_connections and max_total_connections.

max_connections is the maximum number of entries in the cache. It affects libcurl CURLMOPT_MAXCONNECTS. The default is -1.

max_total_connections is the maximum number of active connections. It affects libcurl CURLMOPT_MAX_TOTAL_CONNECTIONS. It is ignored if the curl version is less than 7.30. The default is 0, which allows libcurl to scale according to easy handles count.

The default option values are usually good enough but in rare cases it might be good to set them. In that case here are two tips.

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 - delay, in seconds, that the operating system will wait while the connection is idle before sending keepalive probes. See also CURLOPT_TCP_KEEPIDLE and the note below about keepalive_interval.
    • keepalive_interval - the interval, in seconds, that the operating system will wait between sending keepalive probes. See also CURLOPT_TCP_KEEPINTVL. If both keepalive_idle and keepalive_interval are set, then Tarantool will also set HTTP keepalive headers: Connection:Keep-Alive and Keep-Alive:timeout=<keepalive_idle>. Otherwise Tarantool will send 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 – версия протокола
тип возвращаемого значения:
 

таблица

Для запросов существуют следующие ускоренные методы:

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