Модуль socket

Модуль socket позволяет обмениваться данными с локальным или удаленным хостом по BSD-сокетам в режиме с установлением соединений (TCP) или на основе датаграмм (UDP). Семантика вызовов в API модуля socket точно соответствует семантике соответствующих вызовов в POSIX.

Функции для настройки и подключения: socket, sysconnect, tcp_connect. Функции для отправки данных: send, sendto, write, syswrite. Функции для получения данных: recv, recvfrom, read. Функции для ожидания отправки/получения данных: wait, readable, writable. Функции для установки флагов: nonblock, setsockopt. Функции для остановки и отключения: shutdown, close. Функции для проверки ошибок: errno, error.

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

Как правило, сессия сокета начинается с функций настройки, определяет один или более флагов, запустит цикл с функциями отправки и получения и закончится функциями завершения – как в примере в конце данного раздела. В течение сессии может быть проверка на ошибки и ожидание синхронизации функции. Чтобы файбер с сокетом не блокировал другие файберы, правила неявной передачи управления заставят его передать управление другим процессам в рамках кооперативной многозадачности.

Для всех примеров в данном разделе имя сокета будет sock, а вызов функции будет выглядеть как sock:имя_функции(...).

Создание нового TCP-сокета или UDP-сокета. Значения аргумента остаются теми же, что и на странице socket(2) руководства по Linux.

Возвращает

неподключенный сокет или nil.

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

userdata

Пример:

 
socket('AF_INET', 'SOCK_STREAM', 'tcp')

Подключение к удаленному хосту с помощью сокета.

Параметры:

• host (string) — URL или IP-адрес
• port (number) — номер порта
• timeout (number) — время ожидания в секундах

Возвращает

(в случае ошибки) {nil, строка с сообщением об ошибке}. (без ошибки) новый объект сокета.

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

объект сокета, который можно рассматривать как таблицу

Пример:

 
sock, e = socket.tcp_connect('127.0.0.1', 3301)if sock == nil then print(e) end

Функция socket.getaddrinfo() используется для поиска информации об удаленном узле, чтобы можно было передать правильные аргументы для sock:sysconnect(). Эта функция может использовать конфигурационный параметр worker_pool_threads.

Параметры:

• host (string) — URL или IP-адрес

• port (number/string) — номер порта в виде числа или строки

• timeout (number) — максимальное время ожидания в секундах

• options (table) —

  • type – предпочтительный тип сокета
  • family – желаемое семейство адресов для возвращаемых адресов
  • protocol
  • flags – дополнительные опции (подробнее см. здесь)

Возвращает

(в случае ошибки) {nil, строка с сообщением об ошибке}. (без ошибки) Таблица, содержащая следующие поля: "host", "family", "type", "protocol", "port".

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

table

Пример:

 
tarantool> socket.getaddrinfo('tarantool.org', 'http')---- - host: 188.93.56.70    family: AF_INET    type: SOCK_STREAM    protocol: tcp    port: 80  - host: 188.93.56.70    family: AF_INET    type: SOCK_DGRAM    protocol: udp    port: 80...

Чтобы найти доступные значения параметров, используйте следующее:

 
tarantool> socket.internal.AI_FLAGS -- или SO_TYPE, или DOMAIN---- AI_ALL: 256  AI_PASSIVE: 1  AI_NUMERICSERV: 4096  AI_NUMERICHOST: 4  AI_V4MAPPED: 2048  AI_ADDRCONFIG: 1024  AI_CANONNAME: 2...

Функция socket.tcp_server() заставляет Tarantool выступать в качестве сервера для принятия подключений. Обычно для этой же цели используется box.cfg{listen=...}.

Параметры:

• host (string) — имя хоста или IP-адрес
• port (number) — порт хоста, может быть 0
• handler-function-or-table (function/table) — что выполнять при установке соединения
• timeout (number) — время ожидания разрешения имени хоста в секундах

Возвращает

(в случае ошибки) {nil, строка_сообщения_об_ошибке}. (если нет ошибки) новый объект сокета.

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

объект сокета, который можно рассматривать как таблицу

Параметр handler-function-or-table может представлять собой просто имя функции или объявление функции: handler_function. Или же может быть таблицей: {handler = {handler_function} [, prepare = {prepare_function}] [, name = {name}]}. Функция handler_function является обязательной, в ней может быть только один параметр = сокет (используется для непрерывной работы после установки соединения), выполняется один раз за соединение после того, как произойдет accept(). Функция prepare_function необязательна; она выполняется однократно перед установкой соединения (bind()) на слушающем сокете и должна возвращать либо значение бэклога, либо ничего. Например:

 
socket.tcp_server('localhost', 3302, function (s) loop_loop() end)socket.tcp_server('localhost', 3302, {handler=hfunc, name='name'})socket.tcp_server('localhost', 3302, {handler=hfunc, prepare=pfunc})

Более полный пример см. в разделе Использование tcp_server для получения содержимого файла, отправленного по socat и Использование tcp_server с handler и prepare.

Привязка сокета к заданным хосту/порту. Эквивалентно socket_object:bind(), но вызывается для результата require('socket'), а не для объекта сокета.

Параметры:

• host (string) — URL или IP-адрес
• port (number) — номер порта

Возвращает

(в случае ошибки) {nil, строка_сообщения_об_ошибке}. (если нет ошибки) Таблица, которая может содержать информацию о результат привязки.

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

table

Подключение к удаленному хосту с помощью существующего сокета. Значения аргументов будут такие же, как в tcp_connect(). Хост должен представлять собой IP-адрес.

Параметры:

• либо host – строковое представление IPv4- или IPv6-адреса, port – число;
• либо host – строка, содержащая "unix/", port – строка, содержащая путь к unix-сокету;
• либо host – число 0 (ноль), означающее "все локальные интерфейсы", port – число. Если номер порта 0 (ноль), сокет будет привязан к случайному локальному порту.

Возвращает

значение объекта сокета может измениться в случае успешного выполнения sysconnect().

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

boolean

Пример:

 
socket = require('socket')sock = socket('AF_INET', 'SOCK_STREAM', 'tcp')sock:sysconnect(0, 3301)

Отправка данных по подключенному сокету.

Параметры:

• data (string) — данные для отправки

Возвращает

количество отправленных байтов.

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

number

Возможные ошибки: nil в случае ошибки.

Запись максимально возможного количества данных в буфер сокета без блокировки. Используется редко. Для получения подробной информации см. описание.

Чтение количества байтов, определенного в size, из подключенного сокета. Внутренний буфер опережающего считывания используется для уменьшения использования ресурсов на вызов.

Параметры:

• size (integer) — максимальное количество байтов для получения. См. Рекомендуемый размер.

Возвращает

строка запрошенной длины в случае успеха.

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

string

Возможные ошибки: В случае ошибки возвращается пустая строка, после чего статус, errno, errstr. Если передача данных на запись закрыта с другой стороны, возвращаются оставшиеся для чтения данные из сокета (возможно, пустая строка), после чего идет статус "eof" (конец файла).

Чтение данных из подключенного сокета до выполнения какого-либо условия и возврат прочтенных байтов. Производится чтение количества байтов, которое указано в параметре limit, либо до символа-разделителя, либо до истечения времени ожидания. В отличие от socket_object:recv (где используется внутренний буфер опережающего считывания), socket_object:read зависит от буфера сокета.

Параметры:

• limit (integer) — максимальное количество байтов для чтения, например 50 означает "остановиться после 50 байтов"
• delimiter (string) — разделитель, например ? означает "остановиться после вопросительного знака"; этот параметр может принимать таблицу разделителей, например delimiter = {"\n", "\r"}
• timeout (number) — максимальное время ожидания в секундах, например 50 означает "остановиться через 50 секунд"
• options (table) — chunk={limit} и/или delimiter={delimiter}, например {chunk=5,delimiter='x'}.

Возвращает

пустая строка, если больше нечего читать, или значение nil в случае ошибки, или строка длиной до limit байтов, которая может включать байты, соответствующие выражению delimiter.

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

string

Возврат данных из буфера сокета без блокировки. Если сокет с блокировкой, sysread() может блокировать процесс вызова. Используется редко. Для получения подробной информации см. описание.

Параметры:

• size (integer) — максимальное количество байтов для чтения, например 50 означает "остановиться после 50 байтов"

Возвращает

пустая строка, если больше нечего читать, или значение nil в случае ошибки, или строка длиной до size байтов.

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

string

Привязка сокета к данному хосту/порту. UDP-сокет после привязки может использоваться для получения данных (см. socket_object.recvfrom). TCP-сокет может использоваться для принятия новых соединений после перевода в режим прослушивания.

Параметры:

• host (string) — URL или IP-адрес
• port (number) — номер порта

Возвращает

true в случае успеха, false в случае ошибки. Если возвращается false, используйте socket_object:errno() или socket_object:error() для получения подробностей.

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

boolean

Начало прослушивания входящих соединений.

Параметры:

• backlog — в Linux значение backlog для listen может быть из /proc/sys/net/core/somaxconn, в BSD значение backlog может быть SOMAXCONN.

Возвращает

true в случае успеха, false в случае ошибки.

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

boolean

Принятие нового клиентского соединения и создание нового подключенного сокета. Установка блокирующего режима на сокете явным образом после принятия соединения приведет к эффективной работе.

Возвращает

новый сокет в случае успеха.

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

userdata

Возможные ошибки: nil.

Отправка сообщения по UDP-сокету на указанный хост.

Параметры:

• host (string) — URL или IP-адрес
• port (number) — номер порта
• data (string) — данные для отправки

Возвращает

количество отправленных байтов.

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

number

Возможные ошибки: в случае ошибки возвращает nil, а также может вернуть статус, errno, errstr.

Получение сообщения по UDP-сокету.

Параметры:

• size (integer) — максимальное количество байтов для получения. См. Рекомендуемый размер.

Возвращает

сообщение, таблица, содержащая поля "host", "family" и "port".

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

string, table

Возможные ошибки: в случае ошибки возвращает nil, статус, errno, errstr.

Пример:

После message_content, message_sender = recvfrom(1) значением message_content может быть строка, которая содержит 'X', а значением message_sender может быть таблица, которая содержит

 
message_sender.host = '18.44.0.1'message_sender.family = 'AF_INET'message_sender.port = 43065

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

Параметры:

• how — socket.SHUT_RD, socket.SHUT_WR или socket.SHUT_RDWR.

Возвращает

true или false.

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

boolean

Закрытие (удаление) сокета. Закрытый сокет больше не должен использоваться. Сокет будет закрыт автоматически, когда сборщик мусора Lua удалит данные.

Возвращает

true в случае успеха, false в случае ошибки. Например, если сокет уже закрыт, sock:close() вернет false.

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

boolean

Получение информации о последней ошибке на сокете, если таковая была. Ошибки не выдают исключения, поэтому данные функции необходимы.

Возвращает

результат для sock:errno(), результат для sock:error(). Если ошибки нет, sock:errno() вернет 0, а sock:error() – nil.

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

number, string

Определение флагов сокета. Значения аргумента будут такими же, что и на странице getsockopt(2) руководства по Linux. Tarantool принимает следующие:

• SO_ACCEPTCONN
• SO_BINDTODEVICE
• SO_BROADCAST
• SO_DEBUG
• SO_DOMAIN
• SO_ERROR
• SO_DONTROUTE
• SO_KEEPALIVE
• SO_MARK
• SO_OOBINLINE
• SO_PASSCRED
• SO_PEERCRED
• SO_PRIORITY
• SO_PROTOCOL
• SO_RCVBUF
• SO_RCVBUFFORCE
• SO_RCVLOWAT
• SO_SNDLOWAT
• SO_RCVTIMEO
• SO_SNDTIMEO
• SO_REUSEADDR
• SO_SNDBUF
• SO_SNDBUFFORCE
• SO_TIMESTAMP
• SO_TYPE

Получение флагов сокета. Список возможных флагов см. с помощью sock:setsockopt().

Установить или убрать флаг SO_LINGER. Описание флага см. в руководстве по Linux. Установка флага SO_LINGER осуществляется с помощью sock:linger(active).

Параметры:

• active (boolean)

Возвращает

новые значения active и timeout.

• sock:nonblock() возвращает текущее значение флага.
• sock:nonblock(false) устанавливает флаг в false и возвращает false.
• sock:nonblock(true) устанавливает флаг в true и возвращает true.

Эту функцию можно использовать до вызова функции, которая в противном случае будет блокировать бесконечно.

Ожидание доступности чего-либо для чтения или до истечения времени ожидания.

Возвращает

true, если сокет доступен для чтения, false, если время ожидания истекло;

Ожидание доступности чего-либо для записи или до истечения времени ожидания.

Возвращает

true, если сокет доступен для записи, false, если время ожидания истекло;

Ожидание доступности чего-либо для чтения или записи, или до истечения времени ожидания.

Возвращает

'R', если сокет доступен для чтения, 'W', если сокет доступен для записи, 'RW', если сокет доступен и для чтения, и для записи, '' (пустая строка), если время ожидания истекло;

Функция sock:name() используется для получения информации о ближней стороне соединения. Если сокет привязан к xyz.com:45, то sock:name вернет информацию о [host:xyz.com, port:45]. Аналогичная функция в POSIX – getsockname().

Возвращает

Таблица, содержащая следующие поля: "host", "family", "type", "protocol", "port".

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

table

Функция sock:peer() используется для получения информации о дальней стороне соединения. Если TCP-соединение установлено с удаленным хостом tarantool.org:80, то sock:peer() вернет информацию о [host:tarantool.org, port:80]. Аналогичная функция в POSIX – getpeername().

Возвращает

Таблица, содержащая следующие поля: "host", "family", "type", "protocol", "port".

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

table

Функция socket.iowait() используется для ожидания, пока дескриптор файла не будет активен для чтения или записи.

Параметры:

• fd — файловый дескриптор
• read-or-write-flags — 'R' или 1 = чтение, 'W' или 2 = запись, 'RW' или 3 = чтение|запись
• timeout — время ожидания в секундах

Если значение параметра fd – nil, то будет режим ожидания до истечения времени, указанного в параметре timeout. Если timeout – nil или не указан, время ожидания считается бесконечным.

Как правило, возвращается значение совершенного действия ('R' или 'W', или 'RW', или 1, или 2, или 3). Если время ожидания в timeout проходит без действий чтения или записи, возвращается ошибка = ETIMEDOUT.

Пример: socket.iowait(sock:fd(), 'r', 1.11)

В API LuaSocket есть функции, эквивалентные описанным выше, но с другими именами и параметрами, например connect() вместо tcp_connect(). Tarantool поддерживает эти функции, чтобы сторонние пакеты, зависящие от них, могли работать.

Проект LuaSocket находится на github. Описание API находится в руководстве по LuaSocket (нажмите на ссылки "введение" и "ссылка" внизу главной страницы руководства).

Пример для Tarantool - Использование сокета с функциями обертки LuaSocket.

Для recv и recvfrom: используйте необязательный параметр size, чтобы ограничить количество получаемых байтов. Часто используется заданный размер, такой как 512; но во многих случаях лучше использовать предварительно рассчитанный размер, который зависит от контекста – как формат сообщения или состояние сети. Что касается recvfrom, следует помнить, что размер больше максимального размера полезного блока данных одного пакета (Maximum Transmission Unit) может вызвать низкоэффективную передачу данных. Что касается Mac OS X, следует отметить, что размер можно настроить с помощью sysctl net.inet.udp.maxdgram.

Если размер size не задан: Tarantool сделает дополнительный вызов для расчет необходимого количества байтов. Такой дополнительный вызов занимает время, поэтому во избежание низкой эффективности лучше указать size.

Если размер size задан: в UDP-сокете лишние байты отбрасываются; в TCP-сокете лишние байты не отбрасываются, их можно получить при следующем вызове.

В данном примере устанавливается соединение по интернету между экземпляром Tarantool и tarantool.org, затем отправляется HTTP-сообщение заголовка "head" и возвращается ответ: "HTTP/1.1 200 OK" или что-то другое, если сайт перемещен. Так не слишком удобно взаимодействовать с определенным сайтом, но пример показывает работу системы.

 
tarantool> socket = require('socket')---tarantool> sock = socket.tcp_connect('tarantool.org', 80)---tarantool> type(sock)---- tabletarantool> sock:error()---- nulltarantool> sock:send("HEAD / HTTP/1.0\r\nHost: tarantool.org\r\n\r\n")---- 40tarantool> sock:read(17)---- HTTP/1.1 302 Movetarantool> sock:close()---- true

Это вариант более раннего примера "Использование TCP-подключения через Интернет". В нем используются функции обертки LuaSocket, с слишком коротким временем ожидания, так что, скорее всего, произойдет ошибка "Connection timed out" (истекло время ожидания соединения). Более распространенным способом обнаружения истечения времени ожидания является использование функции tcp_connect().

 
tarantool> socket = require('socket')---tarantool> sock = socket.connect('tarantool.org', 80)---tarantool> sock:settimeout(0.001)---- 1tarantool> sock:send("HEAD / HTTP/1.0\r\nHost: tarantool.org\r\n\r\n")---- 40tarantool> sock:receive(17)---- null- Connection timed outtarantool> sock:close()---- 1

Ниже приведен пример с датаграммами. Устанавливается два соединения с 127.0.0.1 (localhost): sock_1 и sock_2. С помощью sock_2 отправляется сообщение на sock_1. С помощью sock_1 получается сообщение. Отображается полученное сообщение. Оба соединения закрываются. Компьютеру так не слишком удобно взаимодействовать с самим собой, но пример показывает работу системы.

 
tarantool> socket = require('socket')---tarantool> sock_1 = socket('AF_INET', 'SOCK_DGRAM', 'udp')---tarantool> sock_1:bind('127.0.0.1')---- truetarantool> sock_2 = socket('AF_INET', 'SOCK_DGRAM', 'udp')---tarantool> sock_2:sendto('127.0.0.1', sock_1:name().port,'X')---- 1tarantool> message = sock_1:recvfrom(512)---tarantool> message---- Xtarantool> sock_1:close()---- truetarantool> sock_2:close()---- true

Ниже приведен пример функции tcp_server, которая читает строки с клиента и выводит результат. На клиентской стороне утилита socat в Linux будет использоваться для отправки целого файла на чтение функции tcp_server.

Запустите две оболочки. Первая оболочка будет экземпляром сервера. Вторая оболочка будет клиентом.

В первой оболочке запустите Tarantool и выполните:

 
box.cfg{}socket = require('socket')socket.tcp_server('0.0.0.0', 3302,{  handler = function(s)    while true do      local request      request = s:read("\n");      if request == "" or request == nil then        break      end      print(request)    end  end,  prepare = function()    print('Initialized')  end})

Вышеуказанный код означает:

1. Используйте tcp_server() для ожидания подключения с любого хоста на порту 3302.
2. При подключении запустите цикл, который читает данные из сокета и выводит прочитанное. «Разделителем» для функции чтения является "\n", поэтому каждый вызов read() будет считывать строку до следующего символа перевода строки, включая его.

Во второй оболочке создайте файл, который содержит несколько строк. Содержимое не имеет значения. Предположим, что первая строка содержит A, вторая строка содержит B, третья строка содержит C. Назовите этот файл "tmp.txt".

Во второй оболочке используйте утилиту socat для отправки файла tmp.txt на экземпляр сервера по хосту и порту:

 
$ socat TCP:localhost:3302 ./tmp.txt

Теперь смотрите, что происходит в первой оболочке. Выводятся строки "A", "B", "C".

Ниже приведен пример функции tcp_server с использованием handler и prepare.

Запустите две оболочки. Первая оболочка будет экземпляром сервера. Вторая оболочка будет клиентом.

В первой оболочке запустите Tarantool и выполните:

 
box.cfg{}socket = require('socket')sock = socket.tcp_server(  '0.0.0.0',  3302,  {prepare =     function(sock)       print('listening on socket ' .. sock:fd())       sock:setsockopt('SOL_SOCKET','SO_REUSEADDR',true)       return 5     end,   handler =    function(sock, from)      print('accepted connection from: ')      print('  host: ' .. from.host)      print('  family: ' .. from.family)      print('  port: ' .. from.port)    end  })

Этот код означает следующее:

1. Используйте tcp_server() для ожидания подключения с любого хоста на порту 3302.
2. Укажите, что будет выполнен начальный вызов prepare, который выводит информацию о сервере, затем вызывает setsockopt(...'SO_REUSEADDR'...) (это тот же параметр, который Tarantool установил бы при отсутствии prepare), а затем возвращает 5 (это довольно небольшой размер очереди невыполненных подключений).
3. Укажите, что для каждого подключения будет вызываться handler, который выводит информацию о клиенте.

Теперь смотрите, что происходит в первой оболочке. Выведется что-то вроде 'listening on socket 12'.

Во второй оболочке запустите Tarantool и выполните:

 
box.cfg{}require('socket').tcp_connect('127.0.0.1', 3302)

Теперь смотрите, что происходит на первой оболочке. На дисплее появится что-то вроде 'accepted connection from host: 127.0.0.1 family: AF_INET port: 37186'.