Модуль membership

Этот модуль представляет собой библиотеку membership для Tarantool на основе протокола gossip.

Эта библиотека создает сеть из нескольких экземпляров Tarantool. Сеть сама контролирует себя, помогает участникам обнаружить всех остальных в группе и получать уведомления об изменениях своего статуса с низкой задержкой. Модуль основан на концепциях из Consul или, точнее, алгоритма SWIM.

Модуль membership работает по протоколу UDP и может производить операции даже до инициализации box.cfg.

Члены-данные представлены в виде таблиц со следующими полями:

• uri (string) — унифицированный идентификатор ресурса (URI).

• status (string) — строка, принимающая одно из значений ниже:

  • alive — член группы, отвечающий на ping-сообщения, имеет статус alive и работает корректно.

  • suspect — если любой член группы не получает ответа от другого члена, он просит трёх других членов со статусом alive отправить ping-сообщение этому члену. Если ответа нет, член получает статус suspect.

  • dead — член со статусом suspect получает статус dead по истечении времени ожидания.

  • left — член получает статус left после выполнения функции leave().

• incarnation (number) — значение, увеличивающееся каждый раз, когда экземпляр получает статус suspect, dead или обновляет свои полезные данные (payload).

• payload (table) — вспомогательные данные, которые могут использоваться различными модулями.

• timestamp (number) — значение fiber.time64(), которое:

  • соответствует последнему обновлению status или incarnation;
  • всегда является локальным;
  • не зависит от настроек часов других членов группы.

Ниже приведен пример таблицы:

 
tarantool> membership.myself()---uri: localhost:33001status: aliveincarnation: 1payload:    uuid: 2d00c500-2570-4019-bfcc-ab25e5096b73timestamp: 1522427330993752...

Ниже приведен список простых функций, функций шифрования, подписки и параметры модуля membership.

Простые функции:

Инициализация модуля membership. Привязывает UDP-сокет к 0.0.0.0:<port>, задает значение параметра advertise_uri = <advertise_host>:<port> (передаваемый хост, порт) и значение параметра incarnation = 1.

Функцию init() можно вызвать несколько раз, старый сокет будет закрыт, откроется новый сокет.

Если значение параметра advertise_uri изменится во время очередного выполнения init(), старый URI считается недоступным со статусом DEAD. Чтобы корректно исключить члена из группы, используйте функцию leave().

Параметры:

• advertise_host (string) — имя хоста или IP-адрес для передачи другим членам группы
• port (number) — UDP-порт для привязки

Возвращает

true

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

boolean

Ошибка

ошибка привязки сокета

Возвращает

структуру данных члена группы текущего экземпляра.

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

table

Параметры:

• uri (string) — advertise_uri заданного члена группы

Возвращает

структуру данных члена группы экземпляра с заданным URI.

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

table

Получение всех членов группы, известных текущему экземпляру.

Редактирование этой таблицы ни на что не вляет.

Возвращает

таблицу, где ключами являются URI, а значениями — соответствующие структуры данных членов группы.

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

table

Сокращение для pairs(membership.members()).

Возвращает

итератор Lua

Можно использовать следующим образом:

 
for uri, member in membership.pairs()  -- что-то сделатьend

Добавление в группу члена с указанным URI и передача информации об этом событии другим членам группы. Достаточно добавить члена группы в один экземпляр, так как все остальные экземпляры в группе со временем получат информацию об этом. Не имеет значения, кто кого добавляет.

Параметры:

• uri (string) — advertise_uri добавляемого члена группы

Возвращает

true или nil в случае ошибки

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

boolean

Ошибка

ошибка разбора, если URI не удалось разобрать

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

Параметры:

• uri (string) — advertise_uri члена группы для проверки связи

Возвращает

true, если член отвечает в течение 0,2 секунды, иначе no response

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

boolean

Ошибка

ping was not sent, если не удалось разрешить имя хоста

Обнаружение членов группы в локальной сети путем отправки широковещательного сообщения UDP во все сети, обнаруженные с помощью вызова getifaddrs() на языке C.

Возвращает

true, если широковещательное сообщение отправлено, false, если getaddrinfo() завершилась ошибкой.

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

boolean

Обновление myself().payload и распространение соответствующей информации вместе со статусом члена группы.

Увеличивает значение параметра incarnation.

Параметры:

• key (string) — ключ для установки в таблице payload
• value — вспомогательные данные

Возвращает

true

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

boolean

Корректное исключение из группы membership. Узел получает статус выбывшего left, другие члены группы не будут пытаться снова подключить его.

Возвращает

true

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

boolean

Возвращает

true, если шифрование включено, иначе false.

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

boolean

Функции шифрования:

Установка ключа, который используется для низкоуровневого шифрования сообщений. Ключ автоматически обрезается или дополняется до 32 байтов. Если значения ключа key нулевое nil, шифрование будет отключено.

Модуль Tarantool crypto.cipher.aes256.cbc занимается шифрованием.

Чтобы обеспечить правильную связь, все члены группы должны быть настроены на использование одного и того же ключа шифрования. В противном случае члены группы получат статус либо dead, либо non-decryptable (невозможно расшифровать).

Параметры:

• key (string) — ключ шифрования

Возвращает

nil.

Получение используемого ключа шифрования.

Возвращает

ключ шифрования или nil, если шифрование отключено.

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

string

Функции подписки:

Подписка на обновления членов таблицы.

Возвращает

объект fiber.cond, который получает сигнал при каждом изменении таблицы членов группы.

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

object

Удаление подписки на cond, получаемый с помощью функции subscribe().

Достоверность cond не проверяется.

Параметры:

• cond — объект fiber.cond, полученный из subscribe()

Возвращает

nil.

Ниже приведен перечень параметров membership. Их можно задать следующим образом:

 
options = require('membership.options')options.<параметр> = <значение>

Период отправки сообщение проверки связи напрямую. Обозначается как T' в протоколе SWIM.

Время ожидания сообщения подтверждения после отправки сообщения проверки связи. Если ответ запаздывает, вызывается алгоритм косвенной проверки связи.

Период выполнения алгоритма синхронизации во избежание энтропии из протокола SWIM.

Время ожидания, чтобы перевести члена группы из статуса suspect в dead.

Число членов группы, которые пытаются отправить сообщения проверки связи члену группы в статусе suspect. Обозначается как k в протоколе SWIM.