Модуль 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 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 accordingly to easily handles count.

Обычно значений параметров по умолчанию будет достаточно, но в редких случаях может понадобиться их настройка. На этот случай два совета.

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) – таблица с параметрами подключения, которые могут содержать любые из следующих компонентов: ca_file – путь к SSL-сертификату для проверки подключенного узла ca_path – путь к директории, где хранятся один или более сертификатов для проверки подключенного узла headers – таблица HTTP-заголовков keepalive_idle – время задержки в секундах, в течение которого операционная система находится в режиме ожидания подключения до отправки сообщений для поддержания в активном состоянии keepalive. См. также CURLOPT_TCP_KEEPIDLE и примечание ниже к 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_limit – установка «предела низкой скорости» – средней скорости передачи в байтах в секунду, ниже которой должна быть скорость передачи, чтобы библиотека посчитала работу слишком медленной и завершила ее. См. также CURLOPT_LOW_SPEED_LIMIT low_speed_time – установка «времени работы с низкой скоростью» – времени, в течение которого скорость передачи должна быть ниже «предела низкой скорости», чтобы библиотека посчитала работу слишком медленной и завершила ее. См. также CURLOPT_LOW_SPEED_TIME max_header_name_len – максимальная длина имени заголовка. Если имя заголовка больше данного значения, оно усекается до такой длины. По умолчанию, „32“. follow_location - when the option is set to true (default) and the response has a 3xx code, the HTTP client will automatically issue another request to a location that a server sends in the Location header. If the new response is 3xx again, the HTTP client will issue still another request and so on in a loop until a non-3xx response will be received. This last response will be returned as a result. Setting this option to false allows to disable this behavior. In this case, the HTTP client will return a 3xx response itself. no_proxy - a comma-separated list of hosts that do not require proxies, or „*“, or „“. Set no_proxy = host [, host ...] to specify hosts that can be reached without requiring a proxy, even if proxy has been set to a non-blank value and/or if a proxy-related environment variable has been set. Set no__proxy = '*' to specify that all hosts can be reached without requiring a proxy, which is equivalent to setting proxy=''. Set no_proxy = '' to specify that no hosts can be reached without requiring a proxy, even if a proxy-related environment variable (HTTP_PROXY) is used. If no_proxy is not set, then a proxy-related environment variable (HTTP_PROXY) may be used. See also CURLOPT_NOPROXY proxy - a proxy server host or IP address, or „“. If proxy is a host or IP address, then it may begin with a scheme, for example „https://“ for an https proxy or „http:// for an http proxy. If proxy is set to „“ an empty string, then proxy use is disabled, and no proxy-related environment variable will be used. If proxy is not set, then a proxy-related environment variable may be used, such as HTTP_PROXY or HTTPS_PROXY or FTP_PROXY, or ALL_PROXY if the protocol can be any protocol. See also CURLOPT_PROXY proxy_port – a proxy server port. The default is 443 for an https proxy and 1080 for a non-https proxy. See also CURLOPT_PROXYPORT proxy_user_pwd – a proxy server user name and/or password. Format: proxy_user_pwd = user_name: or proxy_user_pwd = :password or proxy_user_pwd = user_name:password. See also CURLOPT_USERPWD ssl_cert – путь к файлу клиентского SSL-сертификата. См. также CURLOPT_SSLCERT ssl_key – путь к файлу закрытого ключа для клиентского TSL-сертификата и SSL-сертификата. См. также CURLOPT_SSLKEY timeout – количество секунд ожидания API-запроса curl на чтение до превышения времени ожидания unix_socket – имя сокета, которое используется вместо адреса в сети Интернет, для локального соединения. Сборка сервера Tarantool’а должна осуществляться с помощью libcurl 7.40 или более поздней версии. См. второй пример далее в разделе. verbose – включение/отключение режима отображения подробной информации verify_host – включение/отключение проверки имени сертификата (CN) для хоста. См. также CURLOPT_SSL_VERIFYHOST verify_peer – включение/отключение проверки SSL-сертификата подключенного узла. См. также CURLOPT_SSL_VERIFYPEER accept_encoding - enables automatic decompression of HTTP responses by setting the contents of the Accept-Encoding: header sent in an HTTP request and enabling decoding of a response when the Content-Encoding: header is received. This option specifies what encoding to use. It can be an empty string which means the Accept-Encoding: header will contain all supported built-in encodings. Four encodings are supported: identity, meaning non-compressed, deflate which requests the server to compress its response using the zlib algorithm, gzip which requests the gzip algorithm and br which is brotli. Provide them in the string as a comma-separated list of accepted encodings, like: "br, gzip, deflate". For details of the option, refer to CURLOPT_ACCEPT_ENCODING
возвращает:	информация о подключении со всеми следующими компонентами: status – статус HTTP-ответа reason – текст статуса HTTP-ответа headers – Lua-таблица с нормализованными HTTP-заголовками body – тело сообщения-ответа proto – версия протокола
тип возвращаемого значения:
	таблица

The cookies component contains a Lua table where the key is a cookie name. The value is an array of two elements where the first one is the cookie value and the second one is an array with the cookie’s options. Possible options are: «Expires», «Max-Age», «Domain», «Path», «Secure», «HttpOnly», «SameSite». Note that an option is a string with „=“ splitting the option’s name and its value. Here you can find more info.

Example

You can use cookies information like this:

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)

Requests may be influenced by environment variables, for example users can set up an http proxy by setting HTTP_PROXY=proxy before initiating any requests, unless a proxy connection option has priority. See the web page document 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». Данный пример бесполезен, но наглядно демонстрирует синтаксис и получение отправленного сообщения.